@cboxdk/id-js 0.15.1 → 0.17.0

package/dist/{client-CecDIu_N.d.cts → client-CEXddiCR.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 {
@@ -219,6 +93,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 +140,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 +168,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 +222,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 +310,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 CallbackParams as a, type StoredAuthState as b, type VaultLease as c, type VaultSecretRef as d, type VerifyWebhookOptions as e, verifyWebhook as v };

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

@@ -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.js';
 
 /** A stored vault secret's metadata (never its plaintext). */
 interface VaultSecretRef {
@@ -219,6 +93,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 +140,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 +168,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 +222,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 +310,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 CallbackParams as a, type StoredAuthState as b, type VaultLease as c, type VaultSecretRef as d, type VerifyWebhookOptions as e, verifyWebhook as v };