@cboxdk/id-js 0.7.0 → 0.9.0

package/dist/index.d.cts

@@ -1,5 +1,242 @@
 export { A as AuthorizationRequest, C as CallbackParams, a as CboxIdClient, b as CboxIdConfig, c as CboxUser, D as DiscoveryDocument, R as RefreshedTokens, S as StoreSecretInput, d as StoredAuthState, T as TokenResponse, e as TokenTypeHint, V as VaultClient, f as VaultLease, g as VaultSecretRef, h as VerifyWebhookOptions, v as verifyWebhook } from './client-DkZSRmnO.cjs';
 
+/**
+ * The handler on YOUR side of a legacy migration.
+ *
+ * Cbox ID offers it an email and a password it has never seen, and your code answers with
+ * the person or with nothing. On a yes they are created in Cbox ID as a result of the
+ * login that just succeeded, and from their next sign-in the old system is never asked
+ * again.
+ *
+ * WHY THIS IS A FACTORY AND NOT A DOCUMENT. The wire format is simple enough to describe
+ * in a paragraph — a signed POST, JSON in, JSON out — and describing it would mean every
+ * customer writes the signature check themselves. That check is exactly the part people
+ * get wrong: `===` instead of a constant-time compare, no freshness window, no thought
+ * about replay. So the factory owns all of it and you write the one function that knows
+ * your own database.
+ *
+ * It is deliberately framework-agnostic: it takes a `Request` and returns a `Response`,
+ * which is what Next.js route handlers, Remix, Hono, Bun and Deno all speak natively.
+ */
+/** What your handler answers with. Returning `null` means "no", and is not an error. */
+interface LegacyUser {
+    email: string;
+    name?: string | null;
+    emailVerified?: boolean;
+    /**
+     * Your stored hash, when you can expose it.
+     *
+     * Passing it lets the person keep their password in Cbox ID verbatim — it is stored as
+     * is and upgraded to the platform hasher on their next login, exactly like a
+     * bulk-imported user. Omit it and Cbox ID hashes the password they just proved they
+     * know, which is the honest option when your store cannot hand a hash over.
+     */
+    passwordHash?: string;
+}
+interface LegacyVerifierOptions {
+    /** The same secret you declared in your manifest, or configured in the console. */
+    secret: string;
+    /**
+     * Decide whether these credentials are good, and say who they belong to.
+     *
+     * Return `null` for no. THROWING IS NOT THE SAME as returning null: a throw means your
+     * store could not decide, and is answered with a 503 so Cbox ID refuses the sign-in
+     * rather than treating an outage as a wrong password.
+     */
+    verify: (email: string, password: string) => Promise<LegacyUser | null>;
+    /**
+     * How far out of date a request may be, in seconds. Defaults to 300.
+     *
+     * A window is what makes a captured request stop working. Too wide and a recording is
+     * useful for hours; too narrow and ordinary clock skew starts refusing real traffic.
+     */
+    toleranceSeconds?: number;
+}
+/**
+ * Build the request handler.
+ *
+ * ```ts
+ * // app/api/cbox-legacy/route.ts
+ * export const POST = createLegacyVerifier({
+ *   secret: process.env.CBOX_LEGACY_SECRET!,
+ *   async verify(email, password) {
+ *     const row = await db.users.findByEmail(email)
+ *     if (!row || !(await argon2.verify(row.password, password))) return null
+ *     return { email: row.email, name: row.name, emailVerified: !!row.confirmedAt }
+ *   },
+ * })
+ * ```
+ */
+declare function createLegacyVerifier(options: LegacyVerifierOptions): (request: Request) => Promise<Response>;
+
+/**
+ * The browser-safe half of the SDK.
+ *
+ * Everything else in this package assumes a server: it holds a client secret, it exchanges
+ * codes, it verifies webhooks. None of that may run in a page, which is why the UI
+ * components have always been redirect shells — a page that cannot authenticate itself to
+ * the identity provider cannot ask it anything, so it sends the person away and waits.
+ *
+ * A publishable key changes that. It is public on purpose: it ships in your bundle, it is
+ * visible in devtools, and it is safe there because it only works from the origins you
+ * registered. What it buys is that a page can read its OWN sign-in configuration — the
+ * endpoints, the social buttons, your theme — and render a form itself.
+ *
+ * This client deliberately has no secret, no token storage and no crypto. It reads two
+ * documents. Anything that mints or holds a credential still belongs on your server.
+ */
+/** How a page identifies itself. Public — put it in your bundle. */
+interface FrontendClientOptions {
+    /** Your identity provider's origin, e.g. `https://id.acme.com`. */
+    issuer: string;
+    /** `pk_live_…` or `pk_test_…`. Safe to publish. */
+    publishableKey: string;
+    /** Abort after this long. Defaults to 10s. */
+    timeoutMs?: number;
+    /**
+     * How many times to retry a transient failure. Defaults to 2 (so three attempts).
+     *
+     * Only the network and 5xx are retried. A refusal is a configuration problem and
+     * retrying it just delays the developer finding out; a 429 is honoured rather than
+     * hammered.
+     */
+    retries?: number;
+    /** Injectable for tests and for runtimes with a non-global fetch. */
+    fetch?: typeof globalThis.fetch;
+}
+/** A social button to draw. Name and provider only — never an internal id. */
+interface SocialProvider {
+    provider: string;
+    name: string;
+}
+/** The customer's theme, when they have set one. Absent means "use your own defaults". */
+interface Appearance {
+    preset: string;
+    radius: string;
+    font: string;
+    light: Record<string, string>;
+    dark: Record<string, string>;
+}
+/** Everything needed to draw a sign-in box, and nothing that identifies anybody. */
+interface FrontendConfig {
+    mode: 'test' | 'live' | null;
+    issuer: string;
+    endpoints: {
+        authorization: string;
+        token: string;
+        userinfo: string;
+        end_session: string;
+        jwks: string;
+    };
+    social: SocialProvider[];
+    appearance?: Appearance;
+}
+/** What a sign-in attempt produced. */
+type SignInResult = {
+    status: 'ok';
+    loginTicket: string;
+    expiresIn: number;
+} | {
+    status: 'mfa_required';
+} | {
+    status: 'otp_required';
+} | {
+    status: 'sso_required';
+} | {
+    status: 'invalid';
+} | {
+    status: 'rate_limited';
+    retryAfter: number | undefined;
+};
+/** Who the browser is signed in as, or nobody. */
+interface FrontendSession {
+    user: {
+        id: string;
+        email: string;
+        name: string | null;
+    } | null;
+}
+/**
+ * Reads the public configuration and the current session from a browser.
+ *
+ * ```ts
+ * const frontend = new CboxIdFrontend({
+ *   issuer: 'https://id.acme.com',
+ *   publishableKey: 'pk_live_…',
+ * })
+ *
+ * const config = await frontend.config()   // cached for you; safe to call per component
+ * const { user } = await frontend.session(accessToken)
+ * ```
+ */
+declare class CboxIdFrontend {
+    private readonly issuer;
+    private readonly publishableKey;
+    private readonly timeoutMs;
+    private readonly retries;
+    private readonly fetchImpl;
+    /**
+     * The config document, and the in-flight promise for it.
+     *
+     * Deduplicated rather than merely cached: a page with a sign-in form, a user button and
+     * an organization switcher mounts three components in the same tick, and three parallel
+     * fetches of the same immutable document is a waste the SDK should absorb rather than
+     * ask every consumer to.
+     */
+    private configPromise;
+    constructor(options: FrontendClientOptions);
+    /** Whether this key drives real sign-ins. Handy for a "test mode" badge in your own UI. */
+    get isLive(): boolean;
+    /**
+     * The public sign-in configuration.
+     *
+     * Fetched once per client instance. The document is small and changes when somebody
+     * edits it in the console, so a long-lived page picks changes up on its next full load
+     * rather than mid-session — which is the right trade for something that decides layout.
+     */
+    config(): Promise<FrontendConfig>;
+    /**
+     * Who is signed in, given an access token your app already holds.
+     *
+     * Returns `{ user: null }` rather than throwing when nobody is signed in. That is a
+     * state, not an error: a user button renders on pages nobody has signed in on, and
+     * making callers treat a rejection as a state is how flash-of-signed-out bugs happen.
+     *
+     * The publishable key grants nothing here — the token is the entire authority.
+     */
+    session(accessToken?: string): Promise<FrontendSession>;
+    /**
+     * Sign in with a password, from a form your page drew.
+     *
+     * WHAT COMES BACK IS A TICKET, NEVER A TOKEN. Handing tokens to a page that proved a
+     * password is the implicit grant, which OAuth 2.1 removes: tokens in a URL, in history,
+     * in `Referer`, with no client authentication and no PKCE binding. Spend the ticket by
+     * sending the browser to `/oauth/authorize` with your own PKCE challenge and
+     * `login_ticket` in the query — the ordinary flow, which then issues an ordinary code.
+     *
+     * It expires in sixty seconds. It is for one redirect, not for storing.
+     *
+     * ```ts
+     * const result = await frontend.signIn(email, password)
+     *
+     * if (result.status === 'ok') {
+     *   window.location.href = `${config.endpoints.authorization}?${new URLSearchParams({
+     *     client_id, redirect_uri, response_type: 'code', code_challenge, code_challenge_method: 'S256',
+     *     login_ticket: result.loginTicket,
+     *   })}`
+     * }
+     * ```
+     *
+     * EVERY REFUSAL IS THE SAME REFUSAL. `invalid` covers a wrong password, an unknown
+     * address and a locked account, because distinguishing them is the enumeration oracle
+     * the server refuses to build — do not present them differently in your UI either.
+     */
+    signIn(email: string, password: string): Promise<SignInResult>;
+    private post;
+    private get;
+    private attempt;
+}
+
 /**
  * Base class for every error this SDK throws, so callers can `catch (e) { if (e
  * instanceof CboxIdError) ... }` in one branch.
@@ -22,6 +259,27 @@ declare class InvalidStateError extends CboxIdError {
  */
 declare class AuthenticationError extends CboxIdError {
 }
+/**
+ * The Frontend API refused, or could not be reached.
+ *
+ * Carries a `code` because the four ways this goes wrong need four different responses
+ * from the caller, and telling them apart from a message string is the kind of thing
+ * that works until somebody rewords the message:
+ *
+ *  - `origin_not_allowed` — the overwhelmingly likely cause of a refusal, and a
+ *    configuration problem the developer fixes once in the console.
+ *  - `rate_limited` — back off; `retryAfter` says for how long, when the server said.
+ *  - `unavailable` — the network, or a 5xx. Transient by assumption; already retried.
+ *  - `malformed` — a 200 whose body is not the document we expect, which means something
+ *    between the page and us is rewriting responses (a proxy, an extension, a captive
+ *    portal). Worth distinguishing, because retrying it never helps.
+ */
+declare class FrontendApiError extends CboxIdError {
+    readonly code: 'origin_not_allowed' | 'rate_limited' | 'unavailable' | 'malformed';
+    readonly status?: number | undefined;
+    readonly retryAfter?: number | undefined;
+    constructor(message: string, code: 'origin_not_allowed' | 'rate_limited' | 'unavailable' | 'malformed', status?: number | undefined, retryAfter?: number | undefined);
+}
 
 /**
  * PKCE (RFC 7636) and the random values the login flow needs, built on Web Crypto
@@ -60,6 +318,27 @@ interface RoleDefinition {
 interface AuthzDeclaration {
     permissions?: PermissionDefinition[];
     roles?: RoleDefinition[];
+    /**
+     * Where this app's OLD login lives, while you are migrating off it.
+     *
+     * Declared here for the same reason roles are: it is a fact about the app, it belongs
+     * with the deploy, and the alternative is a URL pasted into a console and a secret
+     * pasted into an env file that quietly disagree six weeks later.
+     *
+     * IT DOES NOT TAKE EFFECT ON ITS OWN. Unlike a role — which affects only the app that
+     * declared it — this names a URL that every unknown email and the password typed with
+     * it will be offered to, on the environment's whole sign-in path. So it arrives as a
+     * proposal and an operator has to approve it in the console. Changing the url later
+     * drops that approval, on purpose.
+     */
+    legacyLogin?: LegacyLoginDeclaration;
+}
+/** Where an app's old login lives. See {@link AuthzDeclaration.legacyLogin}. */
+interface LegacyLoginDeclaration {
+    /** Must be https — a password in the clear is readable by everything on the path. */
+    url: string;
+    /** At least 32 characters. It is the only thing proving a request came from Cbox ID. */
+    secret: string;
 }
 /**
  * The manifest as it is sent to Cbox ID: the declared permissions + roles plus a
@@ -69,6 +348,7 @@ interface AuthzManifest {
     version: string;
     permissions: PermissionDefinition[];
     roles: RoleDefinition[];
+    legacy_login?: LegacyLoginDeclaration;
 }
 /** What {@link publishManifest} needs to authenticate the push. */
 interface ManifestPublisherConfig {
@@ -101,7 +381,10 @@ interface ManifestSyncSummary {
  * @throws ConfigurationError on a missing key/name, a duplicate, or a role that
  *   references a permission that was never declared.
  */
-declare function defineAuthz(declaration: AuthzDeclaration): Required<AuthzDeclaration>;
+declare function defineAuthz(declaration: AuthzDeclaration): AuthzDeclaration & {
+    permissions: PermissionDefinition[];
+    roles: RoleDefinition[];
+};
 /**
  * Build the manifest — the declared catalog plus a stable content hash `version`
  * (first 16 hex chars of the sha256 of the canonicalized catalog). The catalog is
@@ -123,4 +406,4 @@ declare function buildManifest(declaration: AuthzDeclaration): Promise<AuthzMani
  */
 declare function publishManifest(config: ManifestPublisherConfig, declaration: AuthzDeclaration): Promise<ManifestSyncSummary>;
 
-export { AuthenticationError, type AuthzDeclaration, type AuthzManifest, CboxIdError, ConfigurationError, InvalidStateError, type ManifestPublisherConfig, type ManifestSyncSummary, type PermissionDefinition, type RoleDefinition, buildManifest, challenge, createVerifier, defineAuthz, publishManifest, randomToken };
+export { type Appearance, AuthenticationError, type AuthzDeclaration, type AuthzManifest, CboxIdError, CboxIdFrontend, ConfigurationError, FrontendApiError, type FrontendClientOptions, type FrontendConfig, type FrontendSession, InvalidStateError, type LegacyUser, type LegacyVerifierOptions, type ManifestPublisherConfig, type ManifestSyncSummary, type PermissionDefinition, type RoleDefinition, type SignInResult, type SocialProvider, buildManifest, challenge, createLegacyVerifier, createVerifier, defineAuthz, publishManifest, randomToken };

package/dist/index.d.ts

@@ -1,5 +1,242 @@
 export { A as AuthorizationRequest, C as CallbackParams, a as CboxIdClient, b as CboxIdConfig, c as CboxUser, D as DiscoveryDocument, R as RefreshedTokens, S as StoreSecretInput, d as StoredAuthState, T as TokenResponse, e as TokenTypeHint, V as VaultClient, f as VaultLease, g as VaultSecretRef, h as VerifyWebhookOptions, v as verifyWebhook } from './client-DkZSRmnO.js';
 
+/**
+ * The handler on YOUR side of a legacy migration.
+ *
+ * Cbox ID offers it an email and a password it has never seen, and your code answers with
+ * the person or with nothing. On a yes they are created in Cbox ID as a result of the
+ * login that just succeeded, and from their next sign-in the old system is never asked
+ * again.
+ *
+ * WHY THIS IS A FACTORY AND NOT A DOCUMENT. The wire format is simple enough to describe
+ * in a paragraph — a signed POST, JSON in, JSON out — and describing it would mean every
+ * customer writes the signature check themselves. That check is exactly the part people
+ * get wrong: `===` instead of a constant-time compare, no freshness window, no thought
+ * about replay. So the factory owns all of it and you write the one function that knows
+ * your own database.
+ *
+ * It is deliberately framework-agnostic: it takes a `Request` and returns a `Response`,
+ * which is what Next.js route handlers, Remix, Hono, Bun and Deno all speak natively.
+ */
+/** What your handler answers with. Returning `null` means "no", and is not an error. */
+interface LegacyUser {
+    email: string;
+    name?: string | null;
+    emailVerified?: boolean;
+    /**
+     * Your stored hash, when you can expose it.
+     *
+     * Passing it lets the person keep their password in Cbox ID verbatim — it is stored as
+     * is and upgraded to the platform hasher on their next login, exactly like a
+     * bulk-imported user. Omit it and Cbox ID hashes the password they just proved they
+     * know, which is the honest option when your store cannot hand a hash over.
+     */
+    passwordHash?: string;
+}
+interface LegacyVerifierOptions {
+    /** The same secret you declared in your manifest, or configured in the console. */
+    secret: string;
+    /**
+     * Decide whether these credentials are good, and say who they belong to.
+     *
+     * Return `null` for no. THROWING IS NOT THE SAME as returning null: a throw means your
+     * store could not decide, and is answered with a 503 so Cbox ID refuses the sign-in
+     * rather than treating an outage as a wrong password.
+     */
+    verify: (email: string, password: string) => Promise<LegacyUser | null>;
+    /**
+     * How far out of date a request may be, in seconds. Defaults to 300.
+     *
+     * A window is what makes a captured request stop working. Too wide and a recording is
+     * useful for hours; too narrow and ordinary clock skew starts refusing real traffic.
+     */
+    toleranceSeconds?: number;
+}
+/**
+ * Build the request handler.
+ *
+ * ```ts
+ * // app/api/cbox-legacy/route.ts
+ * export const POST = createLegacyVerifier({
+ *   secret: process.env.CBOX_LEGACY_SECRET!,
+ *   async verify(email, password) {
+ *     const row = await db.users.findByEmail(email)
+ *     if (!row || !(await argon2.verify(row.password, password))) return null
+ *     return { email: row.email, name: row.name, emailVerified: !!row.confirmedAt }
+ *   },
+ * })
+ * ```
+ */
+declare function createLegacyVerifier(options: LegacyVerifierOptions): (request: Request) => Promise<Response>;
+
+/**
+ * The browser-safe half of the SDK.
+ *
+ * Everything else in this package assumes a server: it holds a client secret, it exchanges
+ * codes, it verifies webhooks. None of that may run in a page, which is why the UI
+ * components have always been redirect shells — a page that cannot authenticate itself to
+ * the identity provider cannot ask it anything, so it sends the person away and waits.
+ *
+ * A publishable key changes that. It is public on purpose: it ships in your bundle, it is
+ * visible in devtools, and it is safe there because it only works from the origins you
+ * registered. What it buys is that a page can read its OWN sign-in configuration — the
+ * endpoints, the social buttons, your theme — and render a form itself.
+ *
+ * This client deliberately has no secret, no token storage and no crypto. It reads two
+ * documents. Anything that mints or holds a credential still belongs on your server.
+ */
+/** How a page identifies itself. Public — put it in your bundle. */
+interface FrontendClientOptions {
+    /** Your identity provider's origin, e.g. `https://id.acme.com`. */
+    issuer: string;
+    /** `pk_live_…` or `pk_test_…`. Safe to publish. */
+    publishableKey: string;
+    /** Abort after this long. Defaults to 10s. */
+    timeoutMs?: number;
+    /**
+     * How many times to retry a transient failure. Defaults to 2 (so three attempts).
+     *
+     * Only the network and 5xx are retried. A refusal is a configuration problem and
+     * retrying it just delays the developer finding out; a 429 is honoured rather than
+     * hammered.
+     */
+    retries?: number;
+    /** Injectable for tests and for runtimes with a non-global fetch. */
+    fetch?: typeof globalThis.fetch;
+}
+/** A social button to draw. Name and provider only — never an internal id. */
+interface SocialProvider {
+    provider: string;
+    name: string;
+}
+/** The customer's theme, when they have set one. Absent means "use your own defaults". */
+interface Appearance {
+    preset: string;
+    radius: string;
+    font: string;
+    light: Record<string, string>;
+    dark: Record<string, string>;
+}
+/** Everything needed to draw a sign-in box, and nothing that identifies anybody. */
+interface FrontendConfig {
+    mode: 'test' | 'live' | null;
+    issuer: string;
+    endpoints: {
+        authorization: string;
+        token: string;
+        userinfo: string;
+        end_session: string;
+        jwks: string;
+    };
+    social: SocialProvider[];
+    appearance?: Appearance;
+}
+/** What a sign-in attempt produced. */
+type SignInResult = {
+    status: 'ok';
+    loginTicket: string;
+    expiresIn: number;
+} | {
+    status: 'mfa_required';
+} | {
+    status: 'otp_required';
+} | {
+    status: 'sso_required';
+} | {
+    status: 'invalid';
+} | {
+    status: 'rate_limited';
+    retryAfter: number | undefined;
+};
+/** Who the browser is signed in as, or nobody. */
+interface FrontendSession {
+    user: {
+        id: string;
+        email: string;
+        name: string | null;
+    } | null;
+}
+/**
+ * Reads the public configuration and the current session from a browser.
+ *
+ * ```ts
+ * const frontend = new CboxIdFrontend({
+ *   issuer: 'https://id.acme.com',
+ *   publishableKey: 'pk_live_…',
+ * })
+ *
+ * const config = await frontend.config()   // cached for you; safe to call per component
+ * const { user } = await frontend.session(accessToken)
+ * ```
+ */
+declare class CboxIdFrontend {
+    private readonly issuer;
+    private readonly publishableKey;
+    private readonly timeoutMs;
+    private readonly retries;
+    private readonly fetchImpl;
+    /**
+     * The config document, and the in-flight promise for it.
+     *
+     * Deduplicated rather than merely cached: a page with a sign-in form, a user button and
+     * an organization switcher mounts three components in the same tick, and three parallel
+     * fetches of the same immutable document is a waste the SDK should absorb rather than
+     * ask every consumer to.
+     */
+    private configPromise;
+    constructor(options: FrontendClientOptions);
+    /** Whether this key drives real sign-ins. Handy for a "test mode" badge in your own UI. */
+    get isLive(): boolean;
+    /**
+     * The public sign-in configuration.
+     *
+     * Fetched once per client instance. The document is small and changes when somebody
+     * edits it in the console, so a long-lived page picks changes up on its next full load
+     * rather than mid-session — which is the right trade for something that decides layout.
+     */
+    config(): Promise<FrontendConfig>;
+    /**
+     * Who is signed in, given an access token your app already holds.
+     *
+     * Returns `{ user: null }` rather than throwing when nobody is signed in. That is a
+     * state, not an error: a user button renders on pages nobody has signed in on, and
+     * making callers treat a rejection as a state is how flash-of-signed-out bugs happen.
+     *
+     * The publishable key grants nothing here — the token is the entire authority.
+     */
+    session(accessToken?: string): Promise<FrontendSession>;
+    /**
+     * Sign in with a password, from a form your page drew.
+     *
+     * WHAT COMES BACK IS A TICKET, NEVER A TOKEN. Handing tokens to a page that proved a
+     * password is the implicit grant, which OAuth 2.1 removes: tokens in a URL, in history,
+     * in `Referer`, with no client authentication and no PKCE binding. Spend the ticket by
+     * sending the browser to `/oauth/authorize` with your own PKCE challenge and
+     * `login_ticket` in the query — the ordinary flow, which then issues an ordinary code.
+     *
+     * It expires in sixty seconds. It is for one redirect, not for storing.
+     *
+     * ```ts
+     * const result = await frontend.signIn(email, password)
+     *
+     * if (result.status === 'ok') {
+     *   window.location.href = `${config.endpoints.authorization}?${new URLSearchParams({
+     *     client_id, redirect_uri, response_type: 'code', code_challenge, code_challenge_method: 'S256',
+     *     login_ticket: result.loginTicket,
+     *   })}`
+     * }
+     * ```
+     *
+     * EVERY REFUSAL IS THE SAME REFUSAL. `invalid` covers a wrong password, an unknown
+     * address and a locked account, because distinguishing them is the enumeration oracle
+     * the server refuses to build — do not present them differently in your UI either.
+     */
+    signIn(email: string, password: string): Promise<SignInResult>;
+    private post;
+    private get;
+    private attempt;
+}
+
 /**
  * Base class for every error this SDK throws, so callers can `catch (e) { if (e
  * instanceof CboxIdError) ... }` in one branch.
@@ -22,6 +259,27 @@ declare class InvalidStateError extends CboxIdError {
  */
 declare class AuthenticationError extends CboxIdError {
 }
+/**
+ * The Frontend API refused, or could not be reached.
+ *
+ * Carries a `code` because the four ways this goes wrong need four different responses
+ * from the caller, and telling them apart from a message string is the kind of thing
+ * that works until somebody rewords the message:
+ *
+ *  - `origin_not_allowed` — the overwhelmingly likely cause of a refusal, and a
+ *    configuration problem the developer fixes once in the console.
+ *  - `rate_limited` — back off; `retryAfter` says for how long, when the server said.
+ *  - `unavailable` — the network, or a 5xx. Transient by assumption; already retried.
+ *  - `malformed` — a 200 whose body is not the document we expect, which means something
+ *    between the page and us is rewriting responses (a proxy, an extension, a captive
+ *    portal). Worth distinguishing, because retrying it never helps.
+ */
+declare class FrontendApiError extends CboxIdError {
+    readonly code: 'origin_not_allowed' | 'rate_limited' | 'unavailable' | 'malformed';
+    readonly status?: number | undefined;
+    readonly retryAfter?: number | undefined;
+    constructor(message: string, code: 'origin_not_allowed' | 'rate_limited' | 'unavailable' | 'malformed', status?: number | undefined, retryAfter?: number | undefined);
+}
 
 /**
  * PKCE (RFC 7636) and the random values the login flow needs, built on Web Crypto
@@ -60,6 +318,27 @@ interface RoleDefinition {
 interface AuthzDeclaration {
     permissions?: PermissionDefinition[];
     roles?: RoleDefinition[];
+    /**
+     * Where this app's OLD login lives, while you are migrating off it.
+     *
+     * Declared here for the same reason roles are: it is a fact about the app, it belongs
+     * with the deploy, and the alternative is a URL pasted into a console and a secret
+     * pasted into an env file that quietly disagree six weeks later.
+     *
+     * IT DOES NOT TAKE EFFECT ON ITS OWN. Unlike a role — which affects only the app that
+     * declared it — this names a URL that every unknown email and the password typed with
+     * it will be offered to, on the environment's whole sign-in path. So it arrives as a
+     * proposal and an operator has to approve it in the console. Changing the url later
+     * drops that approval, on purpose.
+     */
+    legacyLogin?: LegacyLoginDeclaration;
+}
+/** Where an app's old login lives. See {@link AuthzDeclaration.legacyLogin}. */
+interface LegacyLoginDeclaration {
+    /** Must be https — a password in the clear is readable by everything on the path. */
+    url: string;
+    /** At least 32 characters. It is the only thing proving a request came from Cbox ID. */
+    secret: string;
 }
 /**
  * The manifest as it is sent to Cbox ID: the declared permissions + roles plus a
@@ -69,6 +348,7 @@ interface AuthzManifest {
     version: string;
     permissions: PermissionDefinition[];
     roles: RoleDefinition[];
+    legacy_login?: LegacyLoginDeclaration;
 }
 /** What {@link publishManifest} needs to authenticate the push. */
 interface ManifestPublisherConfig {
@@ -101,7 +381,10 @@ interface ManifestSyncSummary {
  * @throws ConfigurationError on a missing key/name, a duplicate, or a role that
  *   references a permission that was never declared.
  */
-declare function defineAuthz(declaration: AuthzDeclaration): Required<AuthzDeclaration>;
+declare function defineAuthz(declaration: AuthzDeclaration): AuthzDeclaration & {
+    permissions: PermissionDefinition[];
+    roles: RoleDefinition[];
+};
 /**
  * Build the manifest — the declared catalog plus a stable content hash `version`
  * (first 16 hex chars of the sha256 of the canonicalized catalog). The catalog is
@@ -123,4 +406,4 @@ declare function buildManifest(declaration: AuthzDeclaration): Promise<AuthzMani
  */
 declare function publishManifest(config: ManifestPublisherConfig, declaration: AuthzDeclaration): Promise<ManifestSyncSummary>;
 
-export { AuthenticationError, type AuthzDeclaration, type AuthzManifest, CboxIdError, ConfigurationError, InvalidStateError, type ManifestPublisherConfig, type ManifestSyncSummary, type PermissionDefinition, type RoleDefinition, buildManifest, challenge, createVerifier, defineAuthz, publishManifest, randomToken };
+export { type Appearance, AuthenticationError, type AuthzDeclaration, type AuthzManifest, CboxIdError, CboxIdFrontend, ConfigurationError, FrontendApiError, type FrontendClientOptions, type FrontendConfig, type FrontendSession, InvalidStateError, type LegacyUser, type LegacyVerifierOptions, type ManifestPublisherConfig, type ManifestSyncSummary, type PermissionDefinition, type RoleDefinition, type SignInResult, type SocialProvider, buildManifest, challenge, createLegacyVerifier, createVerifier, defineAuthz, publishManifest, randomToken };