@cboxdk/id-js 0.19.0 → 0.21.0

package/dist/agent.d.ts

@@ -0,0 +1,400 @@
+import { JWK } from 'jose';
+import { A as AuthenticationError, C as CboxIdError } from './errors-D61xljZE.js';
+export { a as ConfigurationError } from './errors-D61xljZE.js';
+
+/**
+ * RFC 8414 authorization server metadata, as Cbox ID publishes it at
+ * `{issuer}/.well-known/oauth-authorization-server`. Only the members this module reads are
+ * typed; the rest pass through.
+ */
+interface AuthorizationServerMetadata {
+    issuer: string;
+    token_endpoint: string;
+    registration_endpoint?: string;
+    backchannel_authentication_endpoint?: string;
+    device_authorization_endpoint?: string;
+    backchannel_token_delivery_modes_supported?: string[];
+    backchannel_user_code_parameter_supported?: boolean;
+    grant_types_supported?: string[];
+    token_endpoint_auth_methods_supported?: string[];
+    token_endpoint_auth_signing_alg_values_supported?: string[];
+    [member: string]: unknown;
+}
+/** Transport options every call in this module takes. */
+interface AgentRequestOptions {
+    /** A `fetch` to use instead of the global one (tests, proxies, instrumentation). */
+    fetch?: typeof fetch;
+    /** Per-request timeout in milliseconds. Default 10 000. */
+    timeoutMs?: number;
+    /** Abort the call (and, for the wait helpers, the whole wait). */
+    signal?: AbortSignal;
+}
+/** Where to find the server: its issuer, and optionally metadata you already discovered. */
+interface AgentServerOptions extends AgentRequestOptions {
+    /** The Cbox ID issuer, e.g. `https://acme.cboxid.com`. Must be https (loopback excepted). */
+    issuer: string;
+    /**
+     * Metadata from {@link discoverAuthorizationServer}. Pass it to skip a discovery round
+     * trip per call; omitted, each call discovers it (the wait helpers discover once).
+     */
+    metadata?: AuthorizationServerMetadata;
+}
+/**
+ * Fetch and check the authorization server metadata (RFC 8414).
+ *
+ * The document's `issuer` must equal the one asked for (§3.3) — otherwise a host answering
+ * with another tenant's metadata would receive this client's assertions and codes.
+ */
+declare function discoverAuthorizationServer(issuer: string, options?: AgentRequestOptions): Promise<AuthorizationServerMetadata>;
+
+/** The client-assertion algorithms this module signs with. Cbox ID accepts both. */
+type ClientKeyAlgorithm = 'ES256' | 'RS256';
+/** A signing key pair for `private_key_jwt`, from {@link generateClientKeyPair}. */
+interface ClientKeyPair {
+    alg: ClientKeyAlgorithm;
+    /** The RFC 7638 thumbprint of the public key, used as `kid`. */
+    kid: string;
+    /** The public JWK (with `kid`, `alg`, `use: 'sig'`) — what registration sends in `jwks`. */
+    publicJwk: JWK;
+    /**
+     * The private JWK. PERSIST THIS, and only this, somewhere the user alone can read
+     * (mode 0600, the OS keychain). It is the client's credential: whoever holds it is the
+     * client. Never log it, never commit it.
+     */
+    privateJwk: JWK;
+    /** The private key as a WebCrypto `CryptoKey`, ready to sign with. */
+    privateKey: CryptoKey;
+}
+/**
+ * How the client authenticates at the backchannel, device and token endpoints.
+ *
+ * - `private_key_jwt` (RFC 7523): a short-lived assertion signed with your private key.
+ *   The right choice for a self-registered agent or CLI: nothing secret ever crosses the
+ *   wire, and the server stores only the public key.
+ * - `client_secret_basic` / `client_secret_post`: a console-issued secret.
+ * - `none`: a public client names itself by `client_id` only. Fine for the device grant.
+ *   For CIBA, Cbox ID accepts a keyless self-registered client only when the resource
+ *   allows it (`dynamic_public_backchannel`); otherwise the answer is `invalid_target`.
+ *   Prefer `private_key_jwt` for CIBA: a public `client_id` proves nothing, and CIBA has no front
+ *   channel to bind the flow to.
+ */
+type ClientAuth = {
+    method: 'private_key_jwt';
+    clientId: string;
+    /** A `CryptoKey`, or the private JWK you persisted from {@link generateClientKeyPair}. */
+    privateKey: CryptoKey | JWK;
+    /** Inferred from the key when omitted. */
+    alg?: ClientKeyAlgorithm;
+    /** Sent as the assertion's `kid`. Taken from a JWK's own `kid` when omitted. */
+    kid?: string;
+} | {
+    method: 'client_secret_basic' | 'client_secret_post';
+    clientId: string;
+    clientSecret: string;
+} | {
+    method: 'none';
+    clientId: string;
+};
+/**
+ * A fresh signing key pair for `private_key_jwt`, generated with WebCrypto (via `jose`), so
+ * it runs on Node, Deno, Bun and edge runtimes. ES256 by default — small keys, small
+ * signatures. The private key is extractable on purpose: the caller must persist it.
+ */
+declare function generateClientKeyPair(alg?: ClientKeyAlgorithm): Promise<ClientKeyPair>;
+/**
+ * A signed RFC 7523 client assertion: `iss` = `sub` = client id, `aud` = the token
+ * endpoint, a random `jti` (the server remembers it, so each assertion is single-use),
+ * `iat` now and `exp` at most 60 seconds later.
+ */
+declare function createClientAssertion(auth: Extract<ClientAuth, {
+    method: 'private_key_jwt';
+}>, audience: string, options?: {
+    now?: () => number;
+    lifetimeSeconds?: number;
+}): Promise<string>;
+
+/** The CIBA grant type (OpenID CIBA Core). */
+declare const CIBA_GRANT_TYPE = "urn:openid:params:grant-type:ciba";
+/** The device authorization grant type (RFC 8628). */
+declare const DEVICE_CODE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+interface RegisterAgentClientOptions extends AgentServerOptions {
+    /** Shown to the person approving, so make it recognisable: "Cbox Brain CLI on ada-mbp". */
+    clientName: string;
+    /** e.g. `[CIBA_GRANT_TYPE, 'refresh_token']` or `[DEVICE_CODE_GRANT_TYPE, 'refresh_token']`. */
+    grantTypes: string[];
+    /** The scope ceiling to register. A space-separated string or a list. */
+    scope?: string | string[];
+    /**
+     * `private_key_jwt` (default): a key pair is generated (or `keyPair` used) and the
+     * public half registered inline as `jwks`. `none`: a public client — the device grant,
+     * or CIBA where the resource allows keyless clients. `private_key_jwt` is recommended for CIBA.
+     */
+    tokenEndpointAuthMethod?: 'private_key_jwt' | 'none';
+    /** Algorithm for the generated key pair. Default ES256. */
+    alg?: ClientKeyAlgorithm;
+    /** Register an existing key pair instead of generating one. */
+    keyPair?: ClientKeyPair;
+    /** RFC 7591 §3 initial access token, when the instance requires one to register. */
+    initialAccessToken?: string;
+    /** Further RFC 7591 client metadata, sent as-is (e.g. `software_id`, `client_uri`). */
+    extraMetadata?: Record<string, unknown>;
+}
+interface RegisteredAgentClient {
+    clientId: string;
+    /** Present only if the server issued one; a `private_key_jwt` or `none` client has none. */
+    clientSecret: string | null;
+    /** RFC 7592 credential for reading/updating/deleting the registration. Persist it if you need that. */
+    registrationAccessToken: string | null;
+    registrationClientUri: string | null;
+    tokenEndpointAuthMethod: string;
+    grantTypes: string[];
+    scope: string | null;
+    /** The key pair registered, for `private_key_jwt`. Persist `keyPair.privateJwk`. */
+    keyPair: ClientKeyPair | null;
+    /** Ready to hand to {@link startBackchannel} / {@link startDeviceAuthorization}. */
+    auth: ClientAuth;
+    /** The full registration response. */
+    raw: Record<string, unknown>;
+}
+/**
+ * Register this agent or CLI as an OAuth client (RFC 7591 dynamic client registration).
+ *
+ * Do it once per installation and persist the result: `clientId` and, for
+ * `private_key_jwt`, `keyPair.privateJwk`. Re-registering on every run fills the
+ * environment's app list with copies.
+ *
+ * @throws ConfigurationError when the instance has dynamic registration switched off.
+ * @throws AgentGrantError (e.g. `invalid_client_metadata`) when the server refuses.
+ */
+declare function registerAgentClient(options: RegisterAgentClientOptions): Promise<RegisteredAgentClient>;
+
+/** Tokens from a completed CIBA or device grant. */
+interface AgentTokens {
+    accessToken: string;
+    tokenType: string;
+    /** Seconds, when the server said. */
+    expiresIn: number | null;
+    refreshToken: string | null;
+    /**
+     * The id_token, when `openid` was granted — returned as-is, NOT verified here. Verify it
+     * with `CboxIdClient` (or `jose` against the JWKS) before trusting anything in it.
+     */
+    idToken: string | null;
+    scope: string | null;
+    /** The full token response. */
+    raw: Record<string, unknown>;
+}
+/** One poll's outcome. Final failures are thrown, not returned. */
+type PollResult = {
+    status: 'complete';
+    tokens: AgentTokens;
+} | {
+    status: 'pending';
+}
+/** Slow down: add 5 s to the interval, and wait at least `retryAfter` seconds if given. */
+ | {
+    status: 'slow_down';
+    retryAfter: number | null;
+};
+/** Options shared by the wait helpers. */
+interface WaitOptions {
+    /** Replace the timer — tests pass a fake that records the waits. Must honour `signal`. */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Clock in epoch milliseconds. Default `Date.now`. */
+    now?: () => number;
+}
+interface ClientOptions extends AgentServerOptions {
+    /** How the client authenticates. See {@link ClientAuth}. */
+    client: ClientAuth;
+}
+interface StartBackchannelOptions extends ClientOptions {
+    /** Who should approve: a Cbox ID user id, or a confirmed email address. */
+    loginHint: string;
+    /** Space-separated string or list. Bounded by the client's registered scopes. */
+    scope: string | string[];
+    /**
+     * Shown beside Approve. Put a {@link createBindingCode} code in it and print the same
+     * code locally. Required by Cbox ID for self-registered clients; at most 255 characters.
+     */
+    bindingMessage: string;
+    /**
+     * RFC 8707 resource indicator(s) — the API the token is for. Optional in the type, but
+     * REQUIRED by Cbox ID for self-registered clients.
+     * Its settings also decide whether a keyless (`none`) client may use CIBA at all.
+     */
+    resource?: string | string[];
+    /** Seconds the request may wait for approval (the server may shorten it). */
+    requestedExpiry?: number;
+    /** Echoed into the id_token, so you can bind it to this request. */
+    nonce?: string;
+}
+/** A started CIBA request. Persistable as JSON. */
+interface BackchannelAuthorization {
+    authReqId: string;
+    expiresIn: number;
+    /** Seconds between polls. */
+    interval: number;
+    /** Epoch ms after which polling is pointless. */
+    expiresAt: number;
+    /** The resource(s) the request named, re-sent on every poll (the server checks they match). */
+    resource: string[];
+}
+/**
+ * Start a CIBA request (OpenID CIBA Core §7, poll mode): Cbox ID shows `bindingMessage` to
+ * the person named by `loginHint` and waits for Approve.
+ *
+ * `backchannel_user_code_parameter` is not supported by Cbox ID, so no user code is sent.
+ *
+ * @throws InvalidClientError, UnknownUserIdError, InvalidBindingMessageError,
+ *   InvalidTargetError, SlowDownError, AgentGrantError.
+ */
+declare function startBackchannel(options: StartBackchannelOptions): Promise<BackchannelAuthorization>;
+interface PollBackchannelOptions extends ClientOptions {
+    authorization: Pick<BackchannelAuthorization, 'authReqId' | 'resource'>;
+}
+/**
+ * Poll the token endpoint once for a CIBA request.
+ *
+ * @throws AccessDeniedError, ExpiredTokenError, InvalidGrantError, InvalidTargetError,
+ *   InvalidClientError, AgentGrantError.
+ */
+declare function pollBackchannel(options: PollBackchannelOptions): Promise<PollResult>;
+/**
+ * Poll until the person approves, and return the tokens.
+ *
+ * Waits `interval` seconds before each poll; on `slow_down` (or a 429) adds five seconds
+ * for good and waits at least `Retry-After`; keeps going on `authorization_pending`; stops
+ * on anything final. Throws {@link ExpiredTokenError} once `expiresAt` passes and
+ * {@link GrantCancelledError} when `signal` fires — wire it to Ctrl-C.
+ */
+declare function waitForBackchannelToken(options: PollBackchannelOptions & WaitOptions & {
+    authorization: BackchannelAuthorization;
+}): Promise<AgentTokens>;
+interface StartDeviceAuthorizationOptions extends ClientOptions {
+    scope?: string | string[];
+    /** RFC 8707 resource indicator(s). */
+    resource?: string | string[];
+}
+/** A started device authorization. Persistable as JSON. */
+interface DeviceGrantAuthorization {
+    deviceCode: string;
+    /** Show this to the person. */
+    userCode: string;
+    /** Where they enter it. */
+    verificationUri: string;
+    /** The same page with the code filled in — good for a QR code or `open`. */
+    verificationUriComplete: string | null;
+    expiresIn: number;
+    interval: number;
+    expiresAt: number;
+    resource: string[];
+}
+/**
+ * Start the device authorization grant: you get a `userCode` to show and a
+ * `verificationUri` for the person to open on any device.
+ *
+ * @throws InvalidClientError, InvalidTargetError, SlowDownError, AgentGrantError.
+ */
+declare function startDeviceAuthorization(options: StartDeviceAuthorizationOptions): Promise<DeviceGrantAuthorization>;
+interface PollDeviceAuthorizationOptions extends ClientOptions {
+    authorization: Pick<DeviceGrantAuthorization, 'deviceCode' | 'resource'>;
+}
+/** Poll the token endpoint once for a device authorization. */
+declare function pollDeviceAuthorization(options: PollDeviceAuthorizationOptions): Promise<PollResult>;
+/** Poll until the person approves the device code. Same rules as {@link waitForBackchannelToken}. */
+declare function waitForDeviceToken(options: PollDeviceAuthorizationOptions & WaitOptions & {
+    authorization: DeviceGrantAuthorization;
+}): Promise<AgentTokens>;
+interface RefreshAgentTokensOptions extends ClientOptions {
+    refreshToken: string;
+    /** Narrow the scope (never widen it). */
+    scope?: string | string[];
+    /** RFC 8707 resource indicator(s) for the new access token. */
+    resource?: string | string[];
+}
+/**
+ * Exchange a refresh token, authenticating the same way the grant did (including
+ * `private_key_jwt`). Cbox ID rotates refresh tokens and revokes the family on reuse, so
+ * ALWAYS persist the returned `refreshToken` and discard the old one.
+ *
+ * @throws InvalidGrantError when the refresh token is no longer valid — sign in again.
+ */
+declare function refreshAgentTokens(options: RefreshAgentTokensOptions): Promise<AgentTokens>;
+
+/**
+ * Uppercase letters and digits a person cannot confuse when reading them off one screen
+ * and matching them on another: no 0/O, 1/I/L, 5/S, 2/Z, 8/B.
+ */
+declare const BINDING_CODE_ALPHABET = "ACDEFGHJKMNPQRTUVWXY34679";
+/**
+ * A short random code for a CIBA `binding_message`, e.g. `K7QM`.
+ *
+ * Show it in your terminal and put it in the binding message; Cbox ID shows the message
+ * beside Approve, and the person approves only when the two match. That is what stops a
+ * prompt somebody else triggered from being approved by reflex. Cbox ID requires a
+ * binding message from self-registered clients.
+ *
+ * Uniform over the alphabet (rejection sampling, WebCrypto randomness).
+ */
+declare function createBindingCode(length?: number): string;
+
+/**
+ * A CIBA, device-grant or registration request was refused with an OAuth error.
+ *
+ * Extends {@link AuthenticationError}, so `error`, `errorDescription`, `status` and
+ * `retryAfter` read the same as on every other back-channel failure in this SDK, and a
+ * caller already catching `AuthenticationError` keeps working. Branch on the subclass (or
+ * on `error`), never on the message.
+ *
+ * The REQUEST is never part of the error: these calls carry client assertions, secrets and
+ * device codes, and production CLIs log what they throw.
+ */
+declare class AgentGrantError extends AuthenticationError {
+}
+/** The person declined (`access_denied`). Final — do not poll again. */
+declare class AccessDeniedError extends AgentGrantError {
+}
+/**
+ * The `auth_req_id` or `device_code` expired before anyone approved it (`expired_token`).
+ * Also thrown locally when the wait outlives the request's `expires_in`. Start again.
+ */
+declare class ExpiredTokenError extends AgentGrantError {
+}
+/** The `auth_req_id`, `device_code` or refresh token is not valid (`invalid_grant`). */
+declare class InvalidGrantError extends AgentGrantError {
+}
+/**
+ * The `resource` (RFC 8707) is not one this client may ask for, the poll named a
+ * different resource than the request that started it, or the resource lets
+ * self-registered clients use CIBA only with `private_key_jwt` and this one is keyless
+ * (`invalid_target`).
+ */
+declare class InvalidTargetError extends AgentGrantError {
+}
+/**
+ * Client authentication failed (`invalid_client`): an unknown `client_id`, a bad secret, an
+ * assertion signed by a key the server does not hold, or a replayed `jti`.
+ */
+declare class InvalidClientError extends AgentGrantError {
+}
+/** The `login_hint` names nobody the server can reach (`unknown_user_id`). */
+declare class UnknownUserIdError extends AgentGrantError {
+}
+/**
+ * The `binding_message` is missing where the server requires one (self-registered clients),
+ * or too long to show beside Approve (`invalid_binding_message`).
+ */
+declare class InvalidBindingMessageError extends AgentGrantError {
+}
+/**
+ * The server asked us to slow down (`slow_down`, or HTTP 429). `retryAfter` carries the
+ * `Retry-After` seconds when the server sent them. The wait helpers absorb this themselves;
+ * it is thrown only from a call that does not loop (registration, starting a flow).
+ */
+declare class SlowDownError extends AgentGrantError {
+}
+/** The caller aborted the wait (its `AbortSignal` fired). */
+declare class GrantCancelledError extends CboxIdError {
+}
+
+export { AccessDeniedError, AgentGrantError, type AgentRequestOptions, type AgentServerOptions, type AgentTokens, AuthenticationError, type AuthorizationServerMetadata, BINDING_CODE_ALPHABET, type BackchannelAuthorization, CIBA_GRANT_TYPE, CboxIdError, type ClientAuth, type ClientKeyAlgorithm, type ClientKeyPair, DEVICE_CODE_GRANT_TYPE, type DeviceGrantAuthorization, ExpiredTokenError, GrantCancelledError, InvalidBindingMessageError, InvalidClientError, InvalidGrantError, InvalidTargetError, type PollBackchannelOptions, type PollDeviceAuthorizationOptions, type PollResult, type RefreshAgentTokensOptions, type RegisterAgentClientOptions, type RegisteredAgentClient, SlowDownError, type StartBackchannelOptions, type StartDeviceAuthorizationOptions, UnknownUserIdError, type WaitOptions, createBindingCode, createClientAssertion, discoverAuthorizationServer, generateClientKeyPair, pollBackchannel, pollDeviceAuthorization, refreshAgentTokens, registerAgentClient, startBackchannel, startDeviceAuthorization, waitForBackchannelToken, waitForDeviceToken };