@cboxdk/id-js 0.15.1 → 0.17.0

package/dist/server.d.ts

@@ -0,0 +1,105 @@
+import { O as OrganizationRole } from './types-BYZldock.js';
+
+/**
+ * A customer API key Cbox ID vouches for: live, bound to YOUR app, and held by an active
+ * member of `org`.
+ *
+ * The field names are the endpoint's own, so the claim helpers read it like a token —
+ * `hasPermission(answer, 'invoices:create')`, `organization(answer)?.role`. (A type
+ * alias rather than an interface for that reason: only an alias is assignable to the
+ * helpers' record type.)
+ */
+type ActiveApiKey = {
+    active: true;
+    /** The key's id — log this, never the key. */
+    key_id: string;
+    /** The person who holds the key (their subject id). */
+    sub: string;
+    /** The organization the key acts in. */
+    org: string;
+    /** The holder's membership tier in `org`; null for a tier this SDK does not know. */
+    org_role: OrganizationRole | null;
+    /**
+     * What the key may do, already re-capped by Cbox ID: the key's own list intersected
+     * with what the holder holds for your app right now. A demoted holder's key loses the
+     * permission on the next verification, not at the next reissue.
+     */
+    permissions: string[];
+    /** Your app's client id — always, or the answer is refused. */
+    client_id: string;
+    /** ISO 8601 UTC expiry, or null for a key that does not expire. */
+    expires_at: string | null;
+};
+/**
+ * Every refusal: unknown, malformed, revoked, expired, another app's key, a holder who
+ * left. Cbox ID never says which, so the endpoint cannot be used to probe keys — and
+ * neither does this.
+ */
+interface InactiveApiKey {
+    active: false;
+}
+/** What {@link ApiKeyVerifier.verifyApiKey} returns. Narrow on `active`. */
+type ApiKeyVerification = ActiveApiKey | InactiveApiKey;
+/** Configuration for an {@link ApiKeyVerifier}. */
+interface ApiKeyVerifierConfig {
+    /** Base URL (issuer) of the Cbox ID instance. */
+    issuer: string;
+    /** Your app's OAuth client id — the app the keys were issued for. */
+    clientId: string;
+    /** Your app's client secret. Verification is a confidential-client call. */
+    clientSecret: string;
+    /** Timeout (ms) for the verification request. Defaults to `10000`. */
+    timeoutMs?: number;
+    /**
+     * Cache an ACTIVE answer for this long (ms), so a burst of requests with one key costs
+     * one round-trip. Off (`0`) by default and at most {@link MAX_API_KEY_CACHE_TTL_MS}:
+     * while an answer is cached, a revoked key keeps working, and a demoted holder keeps
+     * the permissions they lost. Never cached past the key's `expires_at`. Refusals are
+     * never cached, so a key issued a moment ago works on its first request.
+     */
+    cacheTtlMs?: number;
+}
+/** The longest {@link ApiKeyVerifierConfig.cacheTtlMs} allowed: one minute. */
+declare const MAX_API_KEY_CACHE_TTL_MS = 60000;
+/**
+ * Verifies customer API keys presented to your API: `POST {issuer}/oauth/api-keys/verify`,
+ * authenticated with your app's own client credentials.
+ *
+ * SERVER-SIDE ONLY. It holds your client secret, so it lives in the
+ * `@cboxdk/id-js/server` entry and the Next.js adapter, never in the main entry that a
+ * browser bundle pulls in — and it refuses to be constructed in a browser at all.
+ *
+ * ```ts
+ * import { ApiKeyVerifier } from '@cboxdk/id-js/server';
+ * import { hasPermission } from '@cboxdk/id-js';
+ *
+ * const keys = new ApiKeyVerifier({ issuer, clientId, clientSecret, cacheTtlMs: 10_000 });
+ *
+ * const answer = await keys.verifyApiKey(request.headers.get('x-api-key') ?? '');
+ * if (!answer.active) return unauthorized();
+ * if (!hasPermission(answer, 'invoices:create')) return forbidden();
+ * ```
+ */
+declare class ApiKeyVerifier {
+    private readonly config;
+    private readonly endpoint;
+    private readonly timeoutMs;
+    private readonly cacheTtlMs;
+    private readonly cache;
+    constructor(config: ApiKeyVerifierConfig);
+    /**
+     * Ask Cbox ID whether `key` is good for this app, and what it may do.
+     *
+     * Resolves `{ active: false }` for every kind of bad key, without a request for an empty
+     * one. Throws `AuthenticationError` when the call itself fails (wrong client
+     * credentials, an unreachable instance) or when the answer cannot be trusted — one that
+     * names another app's `client_id`, or does not have the promised shape. Both mean "do
+     * not let this request in"; the difference is that a throw is something to look at.
+     */
+    verifyApiKey(key: string): Promise<ApiKeyVerification>;
+    private request;
+    private parse;
+    private remember;
+}
+
+export { type ActiveApiKey, type ApiKeyVerification, ApiKeyVerifier, type ApiKeyVerifierConfig, type InactiveApiKey, MAX_API_KEY_CACHE_TTL_MS };

package/dist/server.js

@@ -0,0 +1,4 @@
+export { ApiKeyVerifier, MAX_API_KEY_CACHE_TTL_MS } from './chunk-WYTGLCMF.js';
+import './chunk-ASOQN47M.js';
+//# sourceMappingURL=server.js.map
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"server.js"}

package/dist/types-BYZldock.d.cts

@@ -0,0 +1,316 @@
+/**
+ * The membership tier a person holds in the organization a token is bound to — the
+ * `org_role` claim. Coarse on purpose: it says who may administer the organization
+ * itself (invite, bill, delete). What they may do inside YOUR app is `roles` /
+ * `permissions`, which your app declares and Cbox ID assigns.
+ */
+type OrganizationRole = 'owner' | 'admin' | 'developer' | 'member' | 'viewer';
+/** The organization a token is bound to: the `org`, `org_name` and `org_role` claims. */
+interface CboxActiveOrganization {
+    /** The stable organization id (`org`). */
+    id: string;
+    /** Its display name (`org_name`), when the instance sent one. */
+    name: string | null;
+    /**
+     * The person's membership tier in it (`org_role`). Null when the claim is absent, or
+     * carries a tier this SDK version does not know — an unrecognised tier is never
+     * guessed upward into one that grants something.
+     */
+    role: OrganizationRole | null;
+}
+/**
+ * Who is actually driving a delegated session — the RFC 8693 §4.1 `act` claim. Cbox ID
+ * sets it on the tokens of a SUPPORT SESSION: a staff member acting as one of your users,
+ * with a stated reason, for at most an hour, with no refresh token.
+ *
+ * `sub` is the actor's subject id. It is null when an `act` claim is present but not in
+ * the shape RFC 8693 describes — the token is still acted, and saying so matters more
+ * than knowing by whom (see {@link isSupportSession}).
+ */
+interface CboxActor {
+    sub: string | null;
+    /** The prior actor, when delegation was chained (RFC 8693 §4.1 nested `act`). */
+    actor: CboxActor | null;
+}
+/**
+ * Anything the helpers below can read claims from: a {@link CboxUser} from sign-in, or a
+ * claim set you verified yourself — an access token's payload on a resource server, say.
+ */
+type ClaimSource = CboxUser | Readonly<Record<string, unknown>>;
+/**
+ * The organization this session is bound to, or null when it is bound to none.
+ *
+ * ```ts
+ * const org = organization(user);
+ * if (org?.role === 'owner') showBilling();
+ * ```
+ */
+declare function organization(source: ClaimSource): CboxActiveOrganization | null;
+/**
+ * The actor behind a support session (`act`), or null for an ordinary session in which
+ * the person is acting as themselves.
+ */
+declare function actor(source: ClaimSource): CboxActor | null;
+/**
+ * Whether somebody other than the signed-in person is driving this session — a staff
+ * member in a support session (the token carries `act`).
+ *
+ * FAIL-CLOSED. Any `act` claim at all counts, including one whose shape this SDK cannot
+ * read: the check exists so an app can show a banner and refuse the things a helper
+ * should never do on somebody's behalf (change their password, move their money), and a
+ * malformed claim is not evidence that nobody else is at the keyboard.
+ */
+declare function isSupportSession(source: ClaimSource): boolean;
+/**
+ * The Cbox ID sign-in session this token came from — the ID Token's `sid` claim — or null
+ * when the instance sent none.
+ *
+ * Store it with your own session: an OIDC Back-Channel Logout token names the session it
+ * ends by this value, and matching on it is how you end the right one (rather than every
+ * session the person has) when they sign out of Cbox ID elsewhere.
+ */
+declare function sessionId(source: ClaimSource): string | null;
+/** The app roles this session holds — the `roles` claim; empty when there are none. */
+declare function roles(source: ClaimSource): string[];
+/**
+ * The permissions this session holds — the `permissions` claim, already expanded from
+ * `roles` by Cbox ID; empty when there are none.
+ */
+declare function permissions(source: ClaimSource): string[];
+/** Whether the session holds `role`. Exact match; no wildcards. */
+declare function hasRole(source: ClaimSource, role: string): boolean;
+/**
+ * Whether the session holds `permission` (`feature:action`). Exact match; no wildcards
+ * — a claim of `invoices:*` does not grant `invoices:delete`, because nothing on the
+ * issuing side ever mints one.
+ */
+declare function hasPermission(source: ClaimSource, permission: string): boolean;
+
+/** 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.
+     *
+     * OPTIONAL, because not every flow has one. The device grant (RFC 8628) exists
+     * precisely for programs with no browser to be returned to, so a CLI has none to give;
+     * requiring it here made every CLI invent `'http://localhost'` and note that it is
+     * unused. It is required by {@link CboxIdClient.createAuthorizationRequest} and
+     * {@link CboxIdClient.authenticate}, which is where its absence actually breaks
+     * something.
+     */
+    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 `/account`, the person's own account area. (`/settings` is
+     * the organization's settings page, for its administrators.)
+     */
+    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;
+    device_authorization_endpoint?: string;
+}
+/**
+ * A pending device authorization (RFC 8628) — what a CLI shows the person while it waits.
+ */
+interface DeviceAuthorization {
+    /** The secret this program polls with. Never show it to the person. */
+    deviceCode: string;
+    /** The short code the person types on the verification page. */
+    userCode: string;
+    /** Where the person goes to approve. Print this. */
+    verificationUri: string;
+    /** The same page with the code filled in — for a clickable link or a QR code. */
+    verificationUriComplete: string | null;
+    /** Seconds until the code stops being valid. */
+    expiresIn: number;
+    /** The minimum seconds between polls. Never poll faster; the server will say so. */
+    interval: number;
+}
+/**
+ * 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';
+/**
+ * An OIDC `prompt` value Cbox ID understands. The first four are OIDC Core §3.1.2.1; the
+ * last two are Cbox ID's organization steps:
+ *
+ * - `select_organization` — always show the hosted organization picker, even to someone
+ *   in a single organization.
+ * - `create_organization` — the hosted "create a team" step: the person creates an
+ *   organization, becomes its owner, and the sign-in continues bound to it.
+ */
+type AuthorizationPrompt = 'none' | 'login' | 'consent' | 'select_account' | 'select_organization' | 'create_organization';
+/** Options for {@link CboxIdClient.createAuthorizationRequest}. */
+interface AuthorizationRequestOptions {
+    /** Scopes for this sign-in; defaults to the configured set. */
+    scopes?: string[];
+    /** Overrides the configured callback for this sign-in. */
+    redirectUri?: string;
+    /** Your own `state`; a random one is generated when omitted. */
+    state?: string;
+    /**
+     * One prompt, or several (sent space-separated). `none` cannot be combined with
+     * anything else — OIDC Core §3.1.2.1 makes that an error at the server, so it is
+     * refused here, where the stack trace still points at your code.
+     */
+    prompt?: AuthorizationPrompt | readonly AuthorizationPrompt[];
+    /** Prefills the email on the sign-in page (`login_hint`). */
+    loginHint?: string;
+    /** Demand an authentication no older than this many seconds (`max_age`). */
+    maxAge?: number;
+    /**
+     * Bind this sign-in to one organization (`organization`). The person must hold an
+     * active membership in it; if they do not, the callback carries
+     * `error=access_denied` and {@link CboxIdClient.authenticate} throws an
+     * `AuthenticationError` whose `error` is `'access_denied'`.
+     *
+     * This is how an app switches organization: a new authorization bound to the other
+     * one. See {@link CboxIdClient.switchOrganization}.
+     */
+    organization?: string;
+    /**
+     * Preselect an organization in the hosted picker (`organization_hint`) without binding
+     * to it — the person can still choose another. Pair it with
+     * `prompt: 'select_organization'` to always show the picker with your guess on top.
+     */
+    organizationHint?: string;
+}
+/**
+ * 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;
+    /**
+     * Echoed back when you passed `organization`. Persist it and hand it to
+     * {@link CboxIdClient.authenticate}, which then refuses tokens bound to any other
+     * organization — see {@link StoredAuthState.organization}.
+     */
+    organization?: string;
+}
+/** 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). Same as `organization?.id`. */
+    organizationId: string | null;
+    /**
+     * The organization this session is bound to — id, name and the person's membership
+     * tier in it (`org`, `org_name`, `org_role`) — or null when it is bound to none.
+     */
+    organization: CboxActiveOrganization | null;
+    /** App roles held in this session (`roles` claim); empty when there are none. */
+    roles: string[];
+    /** Permissions held in this session (`permissions` claim); empty when there are none. */
+    permissions: string[];
+    /**
+     * Set when this is a SUPPORT SESSION — a staff member acting as this person (the RFC
+     * 8693 `act` claim). Null for an ordinary sign-in. Show it: see `isSupportSession()`.
+     */
+    actor: CboxActor | null;
+    /**
+     * The Cbox ID sign-in session (the ID Token's `sid`), or null when none was sent. Keep
+     * it with your session to match a back-channel logout to it. See `sessionId()`.
+     */
+    sessionId: string | null;
+    /**
+     * The organizations this user belongs to — the UserInfo `organizations` claim, which
+     * Cbox ID only sends when you requested the `organizations` scope (it lists every
+     * organization the person is in, so a plain `profile` sign-in does not get it).
+     * Undefined when the claim is absent. Pass straight to `<OrganizationSwitcher>`.
+     */
+    organizations?: CboxOrganization[];
+    claims: Record<string, unknown>;
+    accessToken: string;
+    refreshToken: string | null;
+    idToken: string | null;
+    expiresIn: number;
+}
+
+export { type AuthorizationRequestOptions as A, type CboxUser as C, type DeviceAuthorization as D, type OrganizationRole as O, type RefreshedTokens as R, type TokenTypeHint as T, type CboxIdConfig as a, type AuthorizationRequest as b, type AuthorizationPrompt as c, type CboxActiveOrganization as d, type CboxActor as e, type CboxOrganization as f, type ClaimSource as g, type DiscoveryDocument as h, type TokenResponse as i, actor as j, hasPermission as k, hasRole as l, isSupportSession as m, organization as o, permissions as p, roles as r, sessionId as s };