@cboxdk/id-js 0.15.1 → 0.18.0

package/dist/{client-CecDIu_N.d.ts → client-BxUHm5hX.d.cts}

@@ -1,130 +1,4 @@
-/** Configuration for a {@link CboxIdClient}. */
-interface CboxIdConfig {
-    /**
-     * Base URL (issuer) of the Cbox ID instance, e.g. `https://id.acme.com`. Every
-     * endpoint is discovered from `{issuer}/.well-known/openid-configuration`, so this
-     * is usually the only endpoint you configure.
-     */
-    issuer: string;
-    /** Your registered OAuth client id. */
-    clientId: string;
-    /**
-     * Your client secret. Required for confidential (server-side) apps, machine
-     * tokens and introspection. Omit for public clients (SPA/native) that only do
-     * PKCE login.
-     */
-    clientSecret?: string;
-    /** Your callback URL — must exactly match one registered on the client. */
-    redirectUri: string;
-    /** Scopes requested at login. Defaults to `['openid', 'profile', 'email']`. */
-    scopes?: string[];
-    /**
-     * Path of the instance's hosted account page that {@link CboxIdClient.profileUrl}
-     * points at. Defaults to `/settings`.
-     */
-    accountPath?: string;
-    /** Timeout (ms) for back-channel HTTP calls. Defaults to `10000`. */
-    timeoutMs?: number;
-    /** How long (ms) the discovery document is cached. Defaults to `3600000` (1h). */
-    cacheTtlMs?: number;
-    /**
-     * Leeway (seconds) when checking the id_token's `auth_time` against the `maxAge` you
-     * requested at login. Defaults to `60`.
-     *
-     * Some slack is required, not optional: `maxAge` bounds the age of the
-     * AUTHENTICATION, but `auth_time` is read after a browser redirect and a token
-     * exchange, so even a just-completed re-authentication is already several seconds
-     * old — and the RP's clock and the instance's need not agree. Sixty seconds absorbs
-     * that while still catching what this check exists for: a session hours or days old
-     * being passed off as fresh.
-     */
-    authTimeToleranceSeconds?: number;
-}
-/** The OIDC discovery document fields this SDK uses. */
-interface DiscoveryDocument {
-    issuer: string;
-    authorization_endpoint: string;
-    token_endpoint: string;
-    jwks_uri: string;
-    userinfo_endpoint?: string;
-    introspection_endpoint?: string;
-    revocation_endpoint?: string;
-    end_session_endpoint?: string;
-}
-/**
- * RFC 7009 `token_type_hint`: which token store the server should search first.
- * Only a hint — the server must still find the token if the hint is wrong.
- */
-type TokenTypeHint = 'access_token' | 'refresh_token';
-/**
- * The values {@link CboxIdClient.createAuthorizationRequest} returns. Persist
- * `state`, `codeVerifier` and `nonce` (e.g. in signed, httpOnly cookies) and hand
- * them back to {@link CboxIdClient.authenticate} on the callback.
- */
-interface AuthorizationRequest {
-    /** The URL to redirect the user to. */
-    url: string;
-    state: string;
-    codeVerifier: string;
-    nonce: string;
-    /**
-     * Echoed back when you passed `maxAge`. Persist it with the rest and hand it to
-     * {@link CboxIdClient.authenticate}, which then verifies the id_token's `auth_time`
-     * against it — a step-up nobody checks is not a step-up.
-     */
-    maxAge?: number;
-}
-/** The raw token-endpoint response. */
-interface TokenResponse {
-    access_token: string;
-    token_type?: string;
-    id_token?: string;
-    refresh_token?: string;
-    expires_in?: number;
-    scope?: string;
-}
-/**
- * The tokens returned by {@link CboxIdClient.refresh}. Cbox ID ROTATES refresh
- * tokens and detects reuse, so `refreshToken` is a NEW value — store it and discard
- * the one you presented; replaying a rotated token revokes the whole family.
- */
-interface RefreshedTokens {
-    accessToken: string;
-    refreshToken: string;
-    idToken: string | null;
-    expiresIn: number;
-    scope: string | null;
-}
-/** One organization a user belongs to, from the `organizations` claim when present. */
-interface CboxOrganization {
-    id: string;
-    name: string;
-    /** The member's role in this organization, when the claim carries it. */
-    role?: string | null;
-}
-/**
- * The authenticated Cbox ID user. `id` is the stable opaque subject (`sub`) you key
- * your local account on. `claims` is the full verified id_token + userinfo claim
- * set; the named fields are conveniences over it.
- */
-interface CboxUser {
-    id: string;
-    email: string | null;
-    name: string | null;
-    /** The active organization's id (`org` claim). */
-    organizationId: string | null;
-    /**
-     * The organizations this user belongs to, when the instance emits an
-     * `organizations` claim. Undefined when the claim is absent (single-org apps, or
-     * an instance that doesn't include it). Pass straight to `<OrganizationSwitcher>`.
-     */
-    organizations?: CboxOrganization[];
-    claims: Record<string, unknown>;
-    accessToken: string;
-    refreshToken: string | null;
-    idToken: string | null;
-    expiresIn: number;
-}
+import { a as CboxIdConfig, A as AuthorizationRequestOptions, b as AuthorizationRequest, C as CboxUser, D as DeviceAuthorization, R as RefreshedTokens, T as TokenTypeHint } from './types-BYZldock.cjs';
 
 /** A stored vault secret's metadata (never its plaintext). */
 interface VaultSecretRef {
@@ -204,6 +78,34 @@ interface VerifyWebhookOptions {
 }
 /** Returns `true` only when the signature is present, fresh and valid. Never throws. */
 declare function verifyWebhook(options: VerifyWebhookOptions): Promise<boolean>;
+/** Headers as a `Headers` object or a plain record (Node's `IncomingHttpHeaders`, a framework's map). */
+type WebhookHeaders = Headers | Record<string, string | readonly string[] | undefined>;
+interface VerifyStandardWebhookOptions {
+    /** The RAW request body — the exact bytes received, not a re-encoded copy. */
+    payload: string;
+    /** The request headers; `webhook-id`, `webhook-timestamp` and `webhook-signature` are read. */
+    headers: WebhookHeaders;
+    /**
+     * The endpoint's secret: a `whsec_…` secret, or the 64-hex secret of an endpoint that
+     * moved from the `cbox` scheme (Cbox ID uses it as `whsec_` + base64 of the hex string,
+     * which keys the HMAC with the same bytes).
+     */
+    secret: string;
+    /** Freshness window in seconds. Defaults to 300 (5 minutes). */
+    toleranceSeconds?: number;
+    /** Injectable clock (unix seconds), for tests. Defaults to `Date.now()`. */
+    now?: number;
+}
+/**
+ * Verify a delivery from an endpoint on the `standard_webhooks` signature scheme
+ * ([Standard Webhooks](https://www.standardwebhooks.com/)): `webhook-signature` carries one or
+ * more space-separated `v1,<base64 HMAC-SHA256 of "{webhook-id}.{webhook-timestamp}.{body}">`,
+ * and the timestamp must be within the freshness window. Use {@link verifyWebhook} for the
+ * default `cbox` scheme (`X-Cbox-Signature`).
+ *
+ * Returns `true` only when a signature is present, fresh and valid. Never throws.
+ */
+declare function verifyStandardWebhook(options: VerifyStandardWebhookOptions): Promise<boolean>;
 
 /** Query parameters as they arrive on your callback route. */
 interface CallbackParams {
@@ -219,6 +121,16 @@ interface StoredAuthState {
     nonce: string;
     /** The `maxAge` this login demanded, if any. See {@link AuthorizationRequest.maxAge}. */
     maxAge?: number;
+    /**
+     * The organization this sign-in was bound to, if any. See
+     * {@link AuthorizationRequest.organization}.
+     *
+     * Checked, not trusted: a binding nobody verifies is a binding in name only. An
+     * instance that predates the `organization` parameter ignores it and returns tokens for
+     * whichever organization the session already had — and an app that switched to "Globex"
+     * would then show Globex's name over Acme's data.
+     */
+    organization?: string;
     /**
      * The scopes THIS authorization asked for, when you overrode the configured set.
      *
@@ -256,14 +168,22 @@ declare class CboxIdClient {
      * `nonce` — persist those (signed, httpOnly cookies are ideal) and hand them back
      * to {@link authenticate} on the callback.
      */
-    createAuthorizationRequest(options?: {
-        scopes?: string[];
-        redirectUri?: string;
-        state?: string;
-        prompt?: string;
-        loginHint?: string;
-        maxAge?: number;
-    }): Promise<AuthorizationRequest>;
+    createAuthorizationRequest(options?: AuthorizationRequestOptions): Promise<AuthorizationRequest>;
+    /**
+     * Switch the signed-in person to another organization: a new authorization bound to
+     * `organizationId`. Persist and redirect exactly as for
+     * {@link createAuthorizationRequest} — it is one, with `organization` set.
+     *
+     * Cbox ID already holds the person's session, so this is normally a redirect there and
+     * straight back with no sign-in form. The tokens that come back carry the new `org`,
+     * `org_role`, `roles` and `permissions`; replace your session with them rather than
+     * patching the old one, because every one of those can differ between organizations.
+     *
+     * A person who is not (or is no longer) an active member of that organization comes
+     * back with `error=access_denied`, which {@link authenticate} throws as an
+     * `AuthenticationError` with `error === 'access_denied'`.
+     */
+    switchOrganization(organizationId: string, options?: Omit<AuthorizationRequestOptions, 'organization' | 'organizationHint'>): Promise<AuthorizationRequest>;
     /**
      * Complete login on your callback route: verify state, exchange the code with the
      * PKCE verifier, verify the id_token, and return the authenticated user.
@@ -276,6 +196,45 @@ declare class CboxIdClient {
         stored: StoredAuthState;
         redirectUri?: string;
     }): Promise<CboxUser>;
+    /**
+     * Turn a token response into the verified {@link CboxUser} every flow returns.
+     *
+     * Shared by the browser flow and the device flow rather than written twice: the checks
+     * in here — the UserInfo subject matching the id_token's, the merge that lets UserInfo
+     * enrich but never overwrite signed claims — are the ones that decide whether an
+     * identity is trustworthy. A second copy is a second place for one of them to be
+     * quietly missing, and the flow it was missing from would look exactly as correct.
+     */
+    private identityFrom;
+    /**
+     * Start the device authorization grant (RFC 8628) — the flow for a program with no
+     * browser of its own: a CLI, a CI job, a container, a TV.
+     *
+     * Print `userCode` and `verificationUri`, then call
+     * {@link CboxIdClient.pollDeviceToken}. If the machine has a desktop you may also open
+     * `verificationUriComplete`, which fills the code in — but print the code anyway: the
+     * machine running your program is often not the one the person is looking at.
+     *
+     * The scopes are bounded by what the app is REGISTERED for. A device request naming one
+     * outside that ceiling is refused with `invalid_scope` rather than quietly reduced,
+     * because no browser is in front of it to notice a smaller grant.
+     *
+     * @throws ConfigurationError when the instance advertises no device endpoint.
+     */
+    requestDeviceAuthorization(scopes?: string[]): Promise<DeviceAuthorization>;
+    /**
+     * Poll until the person approves, and return them.
+     *
+     * Blocks. It honours the server's `interval`, backs off permanently by five seconds on
+     * `slow_down` (RFC 8628 §3.5), and stops on the three answers that are final: they
+     * declined, the code expired, or tokens arrived. Pass an `AbortSignal` to give up
+     * early — a CLI should let Ctrl-C work.
+     *
+     * @throws AuthenticationError when the person declines or the code expires.
+     */
+    pollDeviceToken(authorization: DeviceAuthorization, options?: {
+        signal?: AbortSignal;
+    }): Promise<CboxUser>;
     /**
      * Exchange a refresh token for a fresh access token (OAuth 2.0 `refresh_token`
      * grant). Cbox ID rotates refresh tokens and detects reuse, so ALWAYS persist the
@@ -291,6 +250,20 @@ declare class CboxIdClient {
      * ID session; `returnTo` is passed so the page can link back to your app.
      */
     profileUrl(returnTo?: string): string;
+    /**
+     * The hosted page where a person creates and revokes API keys for your API — Cbox ID's
+     * `/account/api-keys`, preselected to this app (or `clientId`). Keys made there are
+     * checked with `ApiKeyVerifier` from `@cboxdk/id-js/server`.
+     *
+     * `returnTo` becomes a link back to your app, honoured only for an origin the app
+     * registered. `organization` picks which of the person's organizations the keys act in;
+     * omitted, the page uses the one they are in.
+     */
+    apiKeysUrl(options?: {
+        clientId?: string;
+        returnTo?: string;
+        organization?: string;
+    }): string;
     /**
      * The RP-initiated logout URL, or null when the instance advertises none.
      *
@@ -365,4 +338,4 @@ declare class CboxIdClient {
     private fetchWithTimeout;
 }
 
-export { type AuthorizationRequest as A, type CallbackParams as C, type DiscoveryDocument as D, type RefreshedTokens as R, type StoreSecretInput as S, type TokenResponse as T, VaultClient as V, CboxIdClient as a, type CboxIdConfig as b, type CboxUser as c, type StoredAuthState as d, type TokenTypeHint as e, type VaultLease as f, type VaultSecretRef as g, type VerifyWebhookOptions as h, verifyWebhook as v };
+export { CboxIdClient as C, type StoreSecretInput as S, VaultClient as V, type WebhookHeaders as W, type CallbackParams as a, type StoredAuthState as b, type VaultLease as c, type VaultSecretRef as d, type VerifyStandardWebhookOptions as e, type VerifyWebhookOptions as f, verifyWebhook as g, verifyStandardWebhook as v };

package/dist/errors-D61xljZE.d.cts

@@ -0,0 +1,87 @@
+/**
+ * Base class for every error this SDK throws, so callers can `catch (e) { if (e
+ * instanceof CboxIdError) ... }` in one branch.
+ */
+declare class CboxIdError extends Error {
+    constructor(message: string);
+}
+/** The client is misconfigured (a required option is missing or empty). */
+declare class ConfigurationError extends CboxIdError {
+}
+/**
+ * The login `state` did not match what was stored — the callback is forged or
+ * stale. Treat as a fresh start, not an error to surface to the user.
+ */
+declare class InvalidStateError extends CboxIdError {
+}
+/**
+ * Login could not be completed: the provider returned an error, the callback was
+ * missing a code, or a token / id_token failed verification.
+ *
+ * `error` carries the RFC 6749 §5.2 code the authorization server sent, when it sent one.
+ * It used to be discarded at every back-channel boundary, leaving a single message string
+ * for outcomes that need opposite responses: `invalid_grant` on a refresh means the
+ * session is over and the person has to sign in again, while `temporarily_unavailable`
+ * means try the same token in a moment. A caller reduced to matching on prose either
+ * retries what can never succeed, or signs out somebody who did not need to be.
+ */
+declare class AuthenticationError extends CboxIdError {
+    /** RFC 6749 §5.2 error code, when the server sent a parseable one. */
+    readonly error?: string | undefined;
+    /** The server's `error_description`, verbatim. Not end-user copy. */
+    readonly errorDescription?: string | undefined;
+    /** HTTP status, for the cases where the body says nothing useful. */
+    readonly status?: number | undefined;
+    /**
+     * Seconds to wait, off the `Retry-After` header — set only on a 429.
+     *
+     * The distinction it carries is the one a caller most needs and could least infer:
+     * a 429 is the ONLY back-channel failure where the same request will succeed
+     * unchanged if you simply wait. Every other one needs a different request, or a new
+     * sign-in. Without this the SDK reported "token refresh failed" and a caller with a
+     * retry loop hammered a limiter that was already telling it exactly how long to stop.
+     */
+    readonly retryAfter?: number | undefined;
+    constructor(message: string, 
+    /** RFC 6749 §5.2 error code, when the server sent a parseable one. */
+    error?: string | undefined, 
+    /** The server's `error_description`, verbatim. Not end-user copy. */
+    errorDescription?: string | undefined, 
+    /** HTTP status, for the cases where the body says nothing useful. */
+    status?: number | undefined, 
+    /**
+     * Seconds to wait, off the `Retry-After` header — set only on a 429.
+     *
+     * The distinction it carries is the one a caller most needs and could least infer:
+     * a 429 is the ONLY back-channel failure where the same request will succeed
+     * unchanged if you simply wait. Every other one needs a different request, or a new
+     * sign-in. Without this the SDK reported "token refresh failed" and a caller with a
+     * retry loop hammered a limiter that was already telling it exactly how long to stop.
+     */
+    retryAfter?: number | undefined);
+    /** Whether waiting `retryAfter` seconds and repeating the same request is worth it. */
+    get isRateLimited(): boolean;
+}
+/**
+ * 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);
+}
+
+export { AuthenticationError as A, CboxIdError as C, FrontendApiError as F, InvalidStateError as I, ConfigurationError as a };

package/dist/errors-D61xljZE.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Base class for every error this SDK throws, so callers can `catch (e) { if (e
+ * instanceof CboxIdError) ... }` in one branch.
+ */
+declare class CboxIdError extends Error {
+    constructor(message: string);
+}
+/** The client is misconfigured (a required option is missing or empty). */
+declare class ConfigurationError extends CboxIdError {
+}
+/**
+ * The login `state` did not match what was stored — the callback is forged or
+ * stale. Treat as a fresh start, not an error to surface to the user.
+ */
+declare class InvalidStateError extends CboxIdError {
+}
+/**
+ * Login could not be completed: the provider returned an error, the callback was
+ * missing a code, or a token / id_token failed verification.
+ *
+ * `error` carries the RFC 6749 §5.2 code the authorization server sent, when it sent one.
+ * It used to be discarded at every back-channel boundary, leaving a single message string
+ * for outcomes that need opposite responses: `invalid_grant` on a refresh means the
+ * session is over and the person has to sign in again, while `temporarily_unavailable`
+ * means try the same token in a moment. A caller reduced to matching on prose either
+ * retries what can never succeed, or signs out somebody who did not need to be.
+ */
+declare class AuthenticationError extends CboxIdError {
+    /** RFC 6749 §5.2 error code, when the server sent a parseable one. */
+    readonly error?: string | undefined;
+    /** The server's `error_description`, verbatim. Not end-user copy. */
+    readonly errorDescription?: string | undefined;
+    /** HTTP status, for the cases where the body says nothing useful. */
+    readonly status?: number | undefined;
+    /**
+     * Seconds to wait, off the `Retry-After` header — set only on a 429.
+     *
+     * The distinction it carries is the one a caller most needs and could least infer:
+     * a 429 is the ONLY back-channel failure where the same request will succeed
+     * unchanged if you simply wait. Every other one needs a different request, or a new
+     * sign-in. Without this the SDK reported "token refresh failed" and a caller with a
+     * retry loop hammered a limiter that was already telling it exactly how long to stop.
+     */
+    readonly retryAfter?: number | undefined;
+    constructor(message: string, 
+    /** RFC 6749 §5.2 error code, when the server sent a parseable one. */
+    error?: string | undefined, 
+    /** The server's `error_description`, verbatim. Not end-user copy. */
+    errorDescription?: string | undefined, 
+    /** HTTP status, for the cases where the body says nothing useful. */
+    status?: number | undefined, 
+    /**
+     * Seconds to wait, off the `Retry-After` header — set only on a 429.
+     *
+     * The distinction it carries is the one a caller most needs and could least infer:
+     * a 429 is the ONLY back-channel failure where the same request will succeed
+     * unchanged if you simply wait. Every other one needs a different request, or a new
+     * sign-in. Without this the SDK reported "token refresh failed" and a caller with a
+     * retry loop hammered a limiter that was already telling it exactly how long to stop.
+     */
+    retryAfter?: number | undefined);
+    /** Whether waiting `retryAfter` seconds and repeating the same request is worth it. */
+    get isRateLimited(): boolean;
+}
+/**
+ * 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);
+}
+
+export { AuthenticationError as A, CboxIdError as C, FrontendApiError as F, InvalidStateError as I, ConfigurationError as a };