@foir/sdk 0.28.0 → 0.30.0

package/dist/auth/code-flow.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Sign a person in through the OpenID Connect code flow, from a server app
+ * that has no OpenID Connect library of its own.
+ *
+ * `beginSignIn` finds the issuer's endpoints from its discovery document and
+ * builds the authorization URL, with a PKCE S256 challenge, a state and a
+ * nonce. It returns the URL to send the browser to and what the app keeps
+ * until the person comes back: keep it on the server, or in an http-only
+ * cookie scoped to the callback. `completeSignIn` checks the callback against
+ * it, redeems the code at the token endpoint and returns the tokens.
+ *
+ * These are the same endpoints any OpenID Connect library uses
+ * (`/oauth/authorize` and `/oauth/token`), so an app can move to a library
+ * later without changing anything in Foir. Only `fetch` and Web Crypto are
+ * used, so the helper runs in Workers, Oxygen and Node 18 or later.
+ *
+ * The ID token is checked for its issuer, audience, nonce and expiry. Its
+ * signature is not checked: it came straight from the issuer's token
+ * endpoint over TLS, which OpenID Connect accepts in place of the signature
+ * (Core 1.0, section 3.1.3.7).
+ */
+/** Where the app signs people in. */
+export interface CodeFlowConfig {
+    /**
+     * The issuer: Foir's own (`https://api.foir.dev`) or a project's login
+     * domain (`https://login.example.com`), which is the issuer of the people
+     * who sign in through it.
+     */
+    issuer: string;
+    /** The auth client's id. */
+    clientId: string;
+    /** The callback, exactly as the auth client lists it. */
+    redirectUri: string;
+    /** A fetch to use in place of the global one. */
+    fetch?: typeof fetch;
+}
+/** What one sign-in asks for. */
+export interface BeginSignInOptions {
+    /**
+     * What the sign-in asks to carry. Default `openid profile email`. Add the
+     * permission names the app's list holds to ask for fewer than all of them.
+     */
+    scope?: string | string[];
+    /** The organization the person signs in to, when the app serves several. */
+    org?: string;
+    /** `login` asks the person to sign in again, `consent` to agree again. */
+    prompt?: string;
+    /** The address to start the sign-in with. */
+    loginHint?: string;
+}
+/** A sign-in begun: where to send the browser, and what to keep for the callback. */
+export interface PendingSignIn {
+    /** The authorization URL. */
+    url: string;
+    /** Kept to check the callback's `state`. */
+    state: string;
+    /** Kept, and sent with the code. Never put it in a URL. */
+    codeVerifier: string;
+    /** Kept to check the ID token's `nonce`. */
+    nonce: string;
+}
+/** What a completed sign-in hands back. */
+export interface CodeFlowTokens {
+    accessToken: string;
+    tokenType: string;
+    expiresIn?: number;
+    refreshToken?: string;
+    idToken?: string;
+    scope?: string;
+    /** The ID token's claims, checked as described above. */
+    claims?: Record<string, unknown>;
+}
+/**
+ * A sign-in that did not complete. `code` is the OAuth error the issuer
+ * answered (`access_denied`, `invalid_grant`, ...), or one of the checks the
+ * helper makes: `state_mismatch`, `issuer_mismatch`, `nonce_mismatch`,
+ * `audience_mismatch`, `id_token_expired`, `discovery_failed` (the issuer
+ * could not be reached or answered no discovery document),
+ * `token_request_failed` (the token endpoint could not be reached or answered
+ * no access token), `invalid_request` (the callback carries no code).
+ */
+export declare class CodeFlowError extends Error {
+    readonly code: string;
+    readonly description?: string;
+    constructor(code: string, description?: string);
+}
+/**
+ * Begin a sign-in: the URL to send the browser to, and what to keep until
+ * the person comes back to the callback.
+ */
+export declare function beginSignIn(config: CodeFlowConfig, options?: BeginSignInOptions): Promise<PendingSignIn>;
+/**
+ * Complete a sign-in from its callback: check it against what `beginSignIn`
+ * returned, redeem the code at the token endpoint, and return the tokens.
+ * `callback` is the URL the browser came back to, or its query.
+ */
+export declare function completeSignIn(config: CodeFlowConfig, callback: string | URL | URLSearchParams, pending: Pick<PendingSignIn, 'state' | 'codeVerifier' | 'nonce'>): Promise<CodeFlowTokens>;

package/dist/auth/grant-table.generated.d.ts

@@ -1,5 +1,5 @@
 export type GrantReach = 'own' | 'named' | 'all';
-export type GrantTarget = 'none' | 'model' | 'operation';
+export type GrantTarget = 'none' | 'model' | 'operation' | 'agent' | 'agent_tool';
 /**
  * One permission: its name, what a grant of it may name, the reaches it may be
  * granted at (none: only its bare form exists), and the grants a holder of it

package/dist/auth/grants.d.ts

@@ -3,7 +3,8 @@
  *
  * A grant is written `<resource>:<verb>[.<reach>][:<target>]`. The reach is
  * `named` or `all`, and an unwritten reach means the holder's own rows. The
- * target narrows it to one model or one operation.
+ * target narrows it to one model, one operation, one agent, or one tool of a
+ * remote server registered on an agent (`<agent>.<server>.<tool>`).
  *
  * This is the platform's rule, answered from the platform's own declarations
  * (the table is written from the contract when this package is built) and held

package/dist/auth/hosted.d.ts

@@ -1,7 +1,7 @@
 /**
- * Hosted-login bridge — for storefronts that delegate sign-in to a Foir
- * white-label front door (the `loginWithFoir` flow) instead of
- * rendering their own login UI.
+ * The hosted session: for an app on the same registrable domain as its login
+ * domain, which trades the login domain's session cookie for a token instead
+ * of running the code flow itself (see code-flow.ts for that).
  *
  * The front door sets a first-party session cookie on the registrable domain;
  * because that domain is shared, the cookie reaches the storefront, which
@@ -37,6 +37,14 @@ export interface HostedLoginOptions {
      * of another project, and one that is not active.
      */
     org?: string;
+    /**
+     * Somebody new is expected: the page opens on the project's way in rather
+     * than the sign-in form, for a "Sign up" or "Join the waitlist" button. The
+     * project's sign-up still decides what that is: joining where it is public,
+     * the waitlist, or the invitation-only or closed notice. The URL is the
+     * login domain's `/signup`.
+     */
+    signUp?: boolean;
 }
 /**
  * Build the redirect URL to the hosted front door, forwarding an absolute
@@ -144,7 +152,7 @@ export type HostedSessionResult =
  */
 export declare function fetchHostedSession(request: Request, config: HostedLoginConfig): Promise<HostedSessionResult>;
 /**
- * What the hosted login said beside the code when it sent someone back to your
+ * What hosted sign-in said beside the code when it sent someone back to your
  * app. A sign-in it refused carries a stable code (`foir_error`); one that
  * connected a provider to the person's account on the way in names the
  * provider (`foir_connected`). Each comes with a sentence your app can show as
@@ -161,9 +169,9 @@ export type HostedSignInNotice = {
     message: string;
 };
 /**
- * Reads the notice off the address the hosted login sent the browser back to:
+ * Reads the notice off the address hosted sign-in sent the browser back to:
  * your callback URL, its search string, or its parameters. `names` maps a
  * provider's key to the name to show (from `getAuthProviders`); without it the
- * key is shown. Null when the hosted login said nothing.
+ * key is shown. Null when hosted sign-in said nothing.
  */
 export declare function hostedSignInNoticeOf(location: string | URL | URLSearchParams, names?: Record<string, string>): HostedSignInNotice | null;

package/dist/auth/index.d.ts

@@ -10,7 +10,7 @@
  * the caller's own manifest advertises, through the same op transport
  * `@foir/sdk/data` uses, so `graphql` is not on this module's path at all.
  */
-export { login, register, requestOTP, loginWithOTP, refreshTokens, loginWithProvider, providerCallback, providerVerifyOTP, providerSignInRefusalOf, signInRefusalOf, confirmProviderLink, resendProviderLinkCode, getAuthProviders, getAuthConfig, getDefaultAuthProvider, signupContext, joinWaitlist, requestPasswordReset, resetPassword, updatePassword, currentUser, myProviderToken, logout, deleteMyAccount, leaveMembership, updateMyProfile, myAuthorizedApps, revokeAuthorizedApp, mySessions, endMySession, myAddresses, addMyAddress, proveMyAddress, makeMyAddressPrimary, removeMyAddress, exportMyData, signOutEverywhere, createPersonalAccessToken, mySignInMethods, connectSignInMethod, disconnectSignInMethod, myFactors, beginStepUp, completeStepUp, beginFactorEnrollment, completeFactorEnrollment, removeFactor, renameFactor, makeRecoveryCodes, myOrganizations, myOrganizationChoices, registerOrganization, saveSession, clearSession, getSessionToken, getSessionUser, signInWithPassword, signUpWithPassword, signInWithOTP, resetPasswordAndSignIn, refreshSession, refreshSessionOnce, signOut, authedRequest, authedOp, requireAuth, } from './auth';
+export { login, register, requestOTP, loginWithOTP, refreshTokens, loginWithProvider, providerCallback, providerVerifyOTP, providerSignInRefusalOf, signInRefusalOf, confirmProviderLink, resendProviderLinkCode, getAuthProviders, getAuthConfig, getDefaultAuthProvider, signupContext, joinWaitlist, requestPasswordReset, resetPassword, updatePassword, currentUser, myProviderToken, logout, deleteMyAccount, deleteMyAccountAndSignOut, leaveMembership, updateMyProfile, myAuthorizedApps, revokeAuthorizedApp, mySessions, endMySession, myAddresses, addMyAddress, proveMyAddress, makeMyAddressPrimary, removeMyAddress, exportMyData, signOutEverywhere, createPersonalAccessToken, mySignInMethods, connectSignInMethod, disconnectSignInMethod, myFactors, beginStepUp, completeStepUp, beginFactorEnrollment, completeFactorEnrollment, removeFactor, renameFactor, makeRecoveryCodes, myOrganizations, myOrganizationChoices, registerOrganization, saveSession, clearSession, getSessionToken, getSessionUser, signInWithPassword, signUpWithPassword, signInWithOTP, resetPasswordAndSignIn, refreshSession, refreshSessionOnce, signOut, authedRequest, authedOp, requireAuth, } from './auth';
 export type { FoirAuthTokens, FoirUser, SessionAdapter, RequireAuthOptions, } from './auth';
 export { userAccess, getSessionAccess, hasRole, hasScope, requireRole, requireScope, FoirAccessDeniedError, } from './access';
 export type { FoirAccess, FoirAccessDenial } from './access';
@@ -18,6 +18,8 @@ export { FoirAuthDowngradedError, FoirSessionExpiredError } from '../graphql/foi
 export { AUTH_OPS } from './ops';
 export type { AuthOpName, AuthOpOptions } from './ops';
 export { hostedLoginUrl, hostedLogoutUrl, fetchHostedSession, hostedSignInNoticeOf } from './hosted';
+export { beginSignIn, completeSignIn, CodeFlowError } from './code-flow';
+export type { CodeFlowConfig, BeginSignInOptions, PendingSignIn, CodeFlowTokens } from './code-flow';
 export type { HostedLoginConfig, HostedLoginOptions, HostedSession, HostedSessionResult, HostedSignInNotice } from './hosted';
 export { createFoirSessionClient } from './session-client';
 export type { FoirSessionClient, FoirSessionConfig, FoirSessionUser, } from './session-client';

package/dist/auth/operations.d.ts

@@ -317,6 +317,11 @@ export interface AuthorizedApp {
     id: string;
     clientId: string;
     clientName: string;
+    /** The app's logo, where it has one, and what it shows. */
+    clientLogoUrl?: string | null;
+    clientLogoAlt?: string | null;
+    /** The app's homepage, where it has one. */
+    clientHomepageUrl?: string | null;
     /** What the app may carry for them, in the permission catalogue's names. */
     grants: string[];
     /** ISO-8601. */

package/dist/auth/session-client.d.ts

@@ -11,7 +11,7 @@
  * How the pieces divide:
  *
  *   cookie  — long-lived (30d), HttpOnly, first-party on your registrable
- *             domain, set by Foir when hosted login finalizes. JS cannot read
+ *             domain, set by Foir when hosted sign-in finalizes. JS cannot read
  *             it, so XSS cannot exfiltrate it.
  *   bearer  — 15 minutes, held in a closure here. Never written to
  *             localStorage/sessionStorage/IndexedDB, never in a cookie of ours.

package/dist/auth.js

@@ -1408,8 +1408,8 @@ async function getSessionUser(adapter) {
 async function signInWithPassword(adapter, env, vars) {
   return saveSession(adapter, await login(env, vars));
 }
-async function signUpWithPassword(adapter, env, vars) {
-  return saveSession(adapter, await register(env, vars));
+async function signUpWithPassword(env, vars) {
+  await register(env, vars);
 }
 async function signInWithOTP(adapter, env, vars) {
   return saveSession(adapter, await loginWithOTP(env, vars));
@@ -1417,6 +1417,11 @@ async function signInWithOTP(adapter, env, vars) {
 async function resetPasswordAndSignIn(adapter, env, vars) {
   return saveSession(adapter, await resetPassword(env, vars));
 }
+async function deleteMyAccountAndSignOut(adapter, env, vars) {
+  const result = await authedOp(adapter, env, AUTH_OPS.deleteMyAccount, vars);
+  await clearSession(adapter);
+  return result;
+}
 async function signOut(adapter, env) {
   const token = await getSessionToken(adapter);
   if (token) {
@@ -1564,6 +1569,12 @@ var GRANT_TABLE = [
   ["operations:write", "none", [], []],
   ["operations:complete", "none", [], []],
   ["status:write", "none", [], []],
+  ["agents:read", "none", [], []],
+  ["agents:execute", "agent", [], []],
+  ["agents:write", "none", [], []],
+  ["agenttools:execute", "agent_tool", [], []],
+  ["brief:read", "none", [], []],
+  ["brief:write", "none", [], []],
   ["appconfig:read", "none", [], []],
   ["schedules:read", "none", [], []],
   ["schedules:write", "none", [], []],
@@ -1602,6 +1613,7 @@ var GRANT_TABLE = [
   ["apikeys:write", "none", [], []],
   ["organizations:read", "none", [], []],
   ["organizations:write", "none", [], []],
+  ["orgsettings:write", "none", [], []],
   ["organizations:create", "none", [], []],
   ["organizations:delete", "none", [], []],
   ["organizations:reach", "none", [], []],
@@ -1612,7 +1624,7 @@ var GRANT_TABLE = [
   ["projects:read", "none", [], []],
   ["projects:write", "none", [], []],
   ["project:stand", "none", [], []],
-  ["project:manage", "none", [], ["project:stand", "records:read.all", "records:create", "records:write.all", "records:delete.all", "records:publish.all", "records:attribute", "search:read", "embeddings:read", "embeddings:write", "schemas:read", "drafts:read", "files:read.all", "files:write.all", "files:delete.all", "users:read.all", "identities:read", "users:create", "identities:delete", "users:write.all", "users:setup", "users:delete.all", "notifications:read.all", "notifications:write.all", "notifications:consent", "pushcredentials:read", "pushcredentials:write", "notes:read.all", "notes:write.all", "notes:create", "approvals:read", "approvals:write", "rooms:read", "rooms:write", "presence:read", "operations:read", "operations:execute", "operations:write", "appconfig:read", "schedules:read", "schedules:write", "hooks:read", "hooks:write", "auth:login_with_foir", "authclients:read", "authclients:write", "domains:read", "domains:write", "loginpages:read", "loginpages:write", "secrets:read", "secrets:list", "secrets:put", "secrets:delete", "appsecrets:read", "appsecrets:list", "appsecrets:put", "appsecrets:delete", "usersecrets:read", "usersecrets:list", "usersecrets:put", "usersecrets:delete", "opsecrets:read", "opsecrets:write", "settings:read", "settings:write", "designtokens:read", "designtokens:write", "models:read", "models:write", "configs:read", "configs:write", "signinproviders:read", "signinproviders:write", "apps:read", "apps:write", "events:read", "targeting:debug", "visitors:forward", "apikeys:read", "apikeys:write", "organizations:read", "organizations:create", "organizations:delete", "organizations:write", "organizations:reach", "members:read", "members:write", "roles:read", "roles:write", "projects:read", "projects:write", "audit:read"]],
+  ["project:manage", "none", [], ["project:stand", "records:read.all", "records:create", "records:write.all", "records:delete.all", "records:publish.all", "records:attribute", "search:read", "embeddings:read", "embeddings:write", "schemas:read", "drafts:read", "files:read.all", "files:write.all", "files:delete.all", "users:read.all", "identities:read", "users:create", "identities:delete", "users:write.all", "users:setup", "users:delete.all", "notifications:read.all", "notifications:write.all", "notifications:consent", "pushcredentials:read", "pushcredentials:write", "notes:read.all", "notes:write.all", "notes:create", "approvals:read", "approvals:write", "rooms:read", "rooms:write", "presence:read", "operations:read", "operations:execute", "operations:write", "agents:read", "agents:execute", "agents:write", "agenttools:execute", "brief:read", "brief:write", "appconfig:read", "schedules:read", "schedules:write", "hooks:read", "hooks:write", "authclients:read", "authclients:write", "domains:read", "domains:write", "loginpages:read", "loginpages:write", "secrets:read", "secrets:list", "secrets:put", "secrets:delete", "appsecrets:read", "appsecrets:list", "appsecrets:put", "appsecrets:delete", "usersecrets:read", "usersecrets:list", "usersecrets:put", "usersecrets:delete", "opsecrets:read", "opsecrets:write", "settings:read", "settings:write", "designtokens:read", "designtokens:write", "models:read", "models:write", "configs:read", "configs:write", "signinproviders:read", "signinproviders:write", "apps:read", "apps:write", "events:read", "targeting:debug", "visitors:forward", "apikeys:read", "apikeys:write", "organizations:read", "organizations:create", "organizations:delete", "organizations:write", "orgsettings:write", "organizations:reach", "members:read", "members:write", "roles:read", "roles:write", "projects:read", "projects:write", "audit:read"]],
   ["projects:create", "none", [], []],
   ["projects:delete", "none", [], []],
   ["tenants:read", "none", [], []],
@@ -1643,7 +1655,6 @@ var GRANT_TABLE = [
   ["usersecrets:list", "none", [], []],
   ["usersecrets:put", "none", [], []],
   ["usersecrets:delete", "none", [], []],
-  ["auth:login_with_foir", "none", [], []],
   ["signinproviders:read", "none", [], []],
   ["signinproviders:write", "none", [], []]
 ];
@@ -1807,6 +1818,9 @@ var DEFAULT_SESSION_PATH = "/session/token";
 var DEFAULT_END_SESSION_PATH = "/session/end-session";
 function hostedLoginUrl(config, returnTo, options = {}) {
   const dest = new URL(config.loginOrigin);
+  if (options.signUp) {
+    dest.pathname = `${dest.pathname.replace(/\/+$/, "")}/signup`;
+  }
   if (returnTo && returnTo !== "/") {
     dest.searchParams.set("returnTo", returnTo);
   }
@@ -1913,6 +1927,169 @@ function forApp(clientId) {
   return clientId ? `?client_id=${encodeURIComponent(clientId)}` : "";
 }
 
+// src/auth/code-flow.ts
+var CodeFlowError = class extends Error {
+  code;
+  description;
+  constructor(code, description) {
+    super(description ? `${code}: ${description}` : code);
+    this.name = "CodeFlowError";
+    this.code = code;
+    this.description = description;
+  }
+};
+var discoveries = /* @__PURE__ */ new Map();
+function trimSlash(url) {
+  return url.replace(/\/+$/, "");
+}
+async function discover(config) {
+  const issuer = trimSlash(config.issuer);
+  let found = discoveries.get(issuer);
+  if (!found) {
+    found = (async () => {
+      let res;
+      try {
+        res = await (config.fetch ?? fetch)(`${issuer}/.well-known/openid-configuration`, {
+          headers: { accept: "application/json" }
+        });
+      } catch (e) {
+        throw new CodeFlowError("discovery_failed", `${issuer} could not be reached for its discovery document: ${String(e)}`);
+      }
+      if (!res.ok) {
+        throw new CodeFlowError("discovery_failed", `${issuer} answered ${res.status} for its discovery document`);
+      }
+      const doc = await res.json().catch(() => null);
+      if (!doc) {
+        throw new CodeFlowError("discovery_failed", `${issuer} answered no JSON for its discovery document`);
+      }
+      if (!doc.issuer || trimSlash(doc.issuer) !== issuer) {
+        throw new CodeFlowError("issuer_mismatch", `the discovery document at ${issuer} names ${doc.issuer ?? "no issuer"}`);
+      }
+      if (!doc.authorization_endpoint || !doc.token_endpoint) {
+        throw new CodeFlowError("discovery_failed", `the discovery document at ${issuer} names no authorization or token endpoint`);
+      }
+      return doc;
+    })();
+    discoveries.set(issuer, found);
+    found.catch(() => discoveries.delete(issuer));
+  }
+  return found;
+}
+function base64url(bytes) {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function randomString(byteLength) {
+  const bytes = new Uint8Array(byteLength);
+  crypto.getRandomValues(bytes);
+  return base64url(bytes);
+}
+async function s256(verifier) {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  return base64url(new Uint8Array(digest));
+}
+async function beginSignIn(config, options = {}) {
+  const endpoints = await discover(config);
+  const state = randomString(24);
+  const nonce = randomString(24);
+  const codeVerifier = randomString(48);
+  const url = new URL(endpoints.authorization_endpoint);
+  const scope = Array.isArray(options.scope) ? options.scope.join(" ") : options.scope ?? "openid profile email";
+  url.searchParams.set("client_id", config.clientId);
+  url.searchParams.set("redirect_uri", config.redirectUri);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("scope", scope);
+  url.searchParams.set("state", state);
+  url.searchParams.set("nonce", nonce);
+  url.searchParams.set("code_challenge", await s256(codeVerifier));
+  url.searchParams.set("code_challenge_method", "S256");
+  if (options.org) url.searchParams.set("org", options.org);
+  if (options.prompt) url.searchParams.set("prompt", options.prompt);
+  if (options.loginHint) url.searchParams.set("login_hint", options.loginHint);
+  return { url: url.toString(), state, codeVerifier, nonce };
+}
+function callbackParams(callback) {
+  if (callback instanceof URLSearchParams) return callback;
+  if (callback instanceof URL) return callback.searchParams;
+  const query = callback.indexOf("?");
+  return new URLSearchParams(query >= 0 ? callback.slice(query + 1).split("#")[0] : callback);
+}
+function claimsOf(idToken) {
+  const payload = idToken.split(".")[1];
+  if (!payload) throw new CodeFlowError("invalid_id_token", "the ID token is not a JWT");
+  const json = atob(payload.replace(/-/g, "+").replace(/_/g, "/"));
+  const bytes = Uint8Array.from(json, (c) => c.charCodeAt(0));
+  return JSON.parse(new TextDecoder().decode(bytes));
+}
+async function completeSignIn(config, callback, pending) {
+  const endpoints = await discover(config);
+  const params = callbackParams(callback);
+  if (params.get("state") !== pending.state) {
+    throw new CodeFlowError("state_mismatch", "the callback is not for the sign-in this app began");
+  }
+  const refused = params.get("error");
+  if (refused) {
+    throw new CodeFlowError(refused, params.get("error_description") ?? void 0);
+  }
+  const code = params.get("code");
+  if (!code) {
+    throw new CodeFlowError("invalid_request", "the callback carries no code");
+  }
+  let res;
+  try {
+    res = await (config.fetch ?? fetch)(endpoints.token_endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+      body: new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: config.redirectUri,
+        client_id: config.clientId,
+        code_verifier: pending.codeVerifier
+      }).toString()
+    });
+  } catch (e) {
+    throw new CodeFlowError("token_request_failed", `the token endpoint could not be reached: ${String(e)}`);
+  }
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    throw new CodeFlowError(
+      typeof body.error === "string" ? body.error : "token_request_failed",
+      typeof body.error_description === "string" ? body.error_description : `the token endpoint answered ${res.status}`
+    );
+  }
+  const tokens = {
+    accessToken: String(body.access_token ?? ""),
+    tokenType: String(body.token_type ?? "Bearer"),
+    expiresIn: typeof body.expires_in === "number" ? body.expires_in : void 0,
+    refreshToken: typeof body.refresh_token === "string" ? body.refresh_token : void 0,
+    idToken: typeof body.id_token === "string" ? body.id_token : void 0,
+    scope: typeof body.scope === "string" ? body.scope : void 0
+  };
+  if (!tokens.accessToken) {
+    throw new CodeFlowError("token_request_failed", "the token endpoint answered no access token");
+  }
+  if (tokens.idToken) {
+    const claims = claimsOf(tokens.idToken);
+    if (typeof claims.iss !== "string" || trimSlash(claims.iss) !== trimSlash(endpoints.issuer)) {
+      throw new CodeFlowError("issuer_mismatch", `the ID token's issuer is ${String(claims.iss)}`);
+    }
+    const audience = Array.isArray(claims.aud) ? claims.aud : [claims.aud];
+    if (!audience.includes(config.clientId)) {
+      throw new CodeFlowError("audience_mismatch", "the ID token is not for this app");
+    }
+    if (claims.nonce !== pending.nonce) {
+      throw new CodeFlowError("nonce_mismatch", "the ID token is not for the sign-in this app began");
+    }
+    if (typeof claims.exp === "number" && claims.exp * 1e3 < Date.now()) {
+      throw new CodeFlowError("id_token_expired", "the ID token has expired");
+    }
+    tokens.claims = claims;
+  }
+  return tokens;
+}
+
 // src/auth/session-client.ts
 var DEFAULT_SESSION_PATH2 = "/session/token";
 var DEFAULT_LOGOUT_PATH = "/session/logout";
@@ -1921,8 +2098,8 @@ var MIN_REFRESH_DELAY_MS = 5e3;
 var CSRF_HEADER = { "X-Foir-Session": "1" };
 function createFoirSessionClient(config) {
   const forApp2 = config.clientId ? `?client_id=${encodeURIComponent(config.clientId)}` : "";
-  const sessionUrl = `${trimSlash(config.loginOrigin)}${config.sessionPath ?? DEFAULT_SESSION_PATH2}${forApp2}`;
-  const logoutUrl = `${trimSlash(config.loginOrigin)}${config.logoutPath ?? DEFAULT_LOGOUT_PATH}${forApp2}`;
+  const sessionUrl = `${trimSlash2(config.loginOrigin)}${config.sessionPath ?? DEFAULT_SESSION_PATH2}${forApp2}`;
+  const logoutUrl = `${trimSlash2(config.loginOrigin)}${config.logoutPath ?? DEFAULT_LOGOUT_PATH}${forApp2}`;
   const skewMs = (config.refreshSkewSeconds ?? DEFAULT_REFRESH_SKEW_SECONDS) * 1e3;
   let cached = null;
   let inflight = null;
@@ -2029,7 +2206,7 @@ function createFoirSessionClient(config) {
       config.onSignOut?.();
     },
     signInUrl(returnTo, options = {}) {
-      const dest = new URL(trimSlash(config.loginOrigin));
+      const dest = new URL(trimSlash2(config.loginOrigin));
       const target = returnTo ?? (typeof window !== "undefined" ? window.location.href : void 0);
       if (target && target !== "/") dest.searchParams.set("returnTo", target);
       if (options.org) dest.searchParams.set("org", options.org);
@@ -2046,11 +2223,12 @@ function createFoirSessionClient(config) {
     }
   };
 }
-function trimSlash(s) {
+function trimSlash2(s) {
   return s.replace(/\/+$/, "");
 }
 export {
   AUTH_OPS,
+  CodeFlowError,
   FoirAccessDeniedError,
   FoirAuthDowngradedError,
   FoirSessionExpiredError,
@@ -2058,9 +2236,11 @@ export {
   authedOp,
   authedRequest,
   beginFactorEnrollment,
+  beginSignIn,
   beginStepUp,
   clearSession,
   completeFactorEnrollment,
+  completeSignIn,
   completeStepUp,
   confirmProviderLink,
   connectSignInMethod,
@@ -2068,6 +2248,7 @@ export {
   createPersonalAccessToken,
   currentUser,
   deleteMyAccount,
+  deleteMyAccountAndSignOut,
   disconnectSignInMethod,
   endMySession,
   exportMyData,

package/dist/client/platform-client.d.ts

@@ -21,7 +21,7 @@ export declare class PlatformClientError extends Error {
  * });
  *
  * const { data } = await client.query(
- *   `query GetProduct($id: ID!) { product(id: $id) { title } }`,
+ *   `query GetProduct($id: String!) { product(id: $id) { title } }`,
  *   { id: '123' }
  * );
  * ```

package/dist/data/agents.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Talking to a project's agents from a site: send a message, follow the run as
+ * it answers, and keep a visitor's conversation theirs.
+ *
+ * ```ts
+ * const reply = await askAgent(foir, {
+ *   agent: 'ask_about_foir',
+ *   message: 'How do releases work?',
+ *   visitorToken: visitorToken(),
+ *   onText: (delta) => render(delta),
+ * });
+ * // reply.threadId continues the conversation
+ * ```
+ *
+ * The run is the platform's: it charges `agents:execute` for the agent to the
+ * caller, signed in or a visitor through a key that gives it, and a refusal
+ * (a message too long, a limit reached, the safety check) comes back as the
+ * run's answer, not as an error. Only a call the platform could not take at
+ * all throws.
+ */
+import type { FoirAgentAttachment, FoirAgentAttachmentUpload, FoirAgentRun, FoirAgentRunStatus, FoirCreateAgentAttachmentArgs, FoirStartAgentRunArgs } from './builtins';
+import type { FoirAgentRunEvent, FoirAgentRunSubscribeOptions } from './subscriptions';
+import type { FoirSubscription } from './ws-transport';
+/** What `askAgent` needs of a client: the agents namespace a key that runs an agent is given. */
+export interface FoirAgentsClient {
+    ns: {
+        agents: {
+            startAgentRun(args: FoirStartAgentRunArgs): Promise<FoirAgentRun>;
+            onRun(options: FoirAgentRunSubscribeOptions): FoirSubscription;
+        };
+    };
+}
+/** What `uploadAgentFile` needs of a client. */
+export interface FoirAgentFilesClient {
+    ns: {
+        agents: {
+            createAgentAttachment(args: FoirCreateAgentAttachmentArgs): Promise<FoirAgentAttachmentUpload>;
+        };
+    };
+}
+/**
+ * A file to send an agent: a `File` from an input or a paste, or bytes with
+ * their type. An image (PNG, JPEG, GIF or WebP) of at most 5 MB, or a PDF of
+ * at most 10 MB; a visitor may send images only.
+ */
+export type FoirAgentFile = Blob | {
+    data: Blob | ArrayBuffer | Uint8Array;
+    mediaType: string;
+    filename?: string;
+};
+/**
+ * Upload a file to send an agent, and answer with the attachment to pass as
+ * one of `attachmentIds`. The bytes go straight to the project's storage; the
+ * attachment is read only through the conversation it is sent in.
+ */
+export declare function uploadAgentFile(foir: FoirAgentFilesClient | {
+    readonly ns: object;
+}, options: {
+    agent: string;
+    file: FoirAgentFile;
+    visitorToken?: string;
+    fetch?: typeof fetch;
+}): Promise<FoirAgentAttachment>;
+export interface AskAgentOptions extends FoirStartAgentRunArgs {
+    /** Files sent with the message: each is uploaded first, then sent by its id. At most 5. */
+    files?: FoirAgentFile[];
+    /** Each piece of the answer as it is written. */
+    onText?: (delta: string) => void;
+    /** Every event of the run, for a caller that renders its steps. */
+    onEvent?: (event: FoirAgentRunEvent) => void;
+    /** Stop following the run; the run itself goes on. */
+    signal?: AbortSignal;
+}
+export interface AgentReply {
+    runId: string;
+    /** Pass as `threadId` to go on with the conversation. */
+    threadId: string | null;
+    status: FoirAgentRunStatus;
+    /** The answer, or the reason the run was refused. */
+    answer: string;
+    error: string | null;
+    /** An agent with an output schema: its typed answer, a value that fits the schema. */
+    output?: unknown;
+}
+/**
+ * Send an agent a message and follow its run until it has answered, or holds
+ * an act for someone's decision.
+ *
+ * It takes any client `createFoirClient` makes, generated or not: the agents
+ * are offered by the key the client was made with, and a client whose key runs
+ * no agent is refused here, by name.
+ */
+export declare function askAgent(foir: FoirAgentsClient | {
+    readonly ns: object;
+}, options: AskAgentOptions): Promise<AgentReply>;
+/**
+ * The secret a visitor's browser keeps for their runs and threads: made once
+ * and kept, so the conversation they start is theirs when they come back. The
+ * platform keeps only its hash.
+ *
+ * Where nothing can be kept (a private window, a server render), a fresh one
+ * is made for the page, and the conversation lasts as long as it does.
+ */
+export declare function visitorToken(storage?: Pick<Storage, 'getItem' | 'setItem'> | null, key?: string): string;