@rakomi/node 0.0.0 → 0.1.0

package/dist/anonymous.js

@@ -0,0 +1,105 @@
+/**
+ * Node SDK surface for anonymous sign-ins.
+ *
+ * Pure server-side: no browser globals (window/document/navigator/localStorage).
+ * Browser apps should use the React hook `useAnonymousSignin` from `@rakomi/react`
+ * which calls this under the hood via the user's backend, OR hit `/v1/auth/anonymous`
+ * directly from the browser with the tenant's public API key.
+ *
+ * Returns a Result shape consistent with the rest of the SDK: NEVER throws on
+ * expected API errors (403/429/402/401), throws ONLY on programmer errors.
+ */
+import { RakomiError } from './errors.js';
+import { ANONYMOUS_DISABLED, ANONYMOUS_MAU_EXHAUSTED, ANONYMOUS_NETWORK_ERROR, ANONYMOUS_RATE_LIMITED, AnonymousSessionExpiredError, } from './errors.js';
+/**
+ * POST /v1/auth/anonymous. Returns Result — never throws on 4xx.
+ */
+export async function anonymousSignin(ctx, options = {}) {
+    const fetchImpl = ctx.fetchImpl ?? fetch;
+    const url = `${ctx.baseUrl}/v1/auth/anonymous`;
+    let res;
+    try {
+        res = await fetchImpl(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-API-Key': ctx.apiKey,
+            },
+            body: JSON.stringify(options.publicMetadata ? { public_metadata: options.publicMetadata } : {}),
+        });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: ANONYMOUS_NETWORK_ERROR(err instanceof Error ? err.message : undefined),
+        };
+    }
+    if (res.status === 201) {
+        const body = (await res.json());
+        return {
+            ok: true,
+            data: {
+                accessToken: body.access_token,
+                refreshToken: body.refresh_token,
+                expiresIn: body.expires_in,
+                user: {
+                    id: body.user.id,
+                    isAnonymous: true,
+                    createdAt: body.user.created_at,
+                },
+            },
+        };
+    }
+    let retryAfterSeconds;
+    const retryAfter = res.headers.get('retry-after');
+    if (retryAfter) {
+        const n = Number(retryAfter);
+        if (Number.isFinite(n) && n > 0)
+            retryAfterSeconds = Math.round(n);
+    }
+    let sdkError;
+    switch (res.status) {
+        case 403:
+            sdkError = ANONYMOUS_DISABLED();
+            break;
+        case 402:
+            sdkError = ANONYMOUS_MAU_EXHAUSTED();
+            break;
+        case 429:
+            sdkError = ANONYMOUS_RATE_LIMITED(retryAfterSeconds);
+            break;
+        default: {
+            const body = await res.text().catch(() => '');
+            sdkError = ANONYMOUS_NETWORK_ERROR(body.slice(0, 200));
+        }
+    }
+    return { ok: false, error: sdkError };
+}
+/**
+ * Decode an access token's `is_anonymous` claim WITHOUT verifying the signature.
+ * Used only to gate the `AnonymousSessionExpiredError` path — callers should still
+ * verify any trust-sensitive claim via `client.verifyToken()`.
+ */
+export function isAnonymousTokenHeuristic(accessToken) {
+    try {
+        const parts = accessToken.split('.');
+        if (parts.length !== 3)
+            return false;
+        const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf-8'));
+        return payload.is_anonymous === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Classify a refresh failure: if the prior token was anonymous and the refresh
+ * returned 401, throw `AnonymousSessionExpiredError`. Otherwise the caller
+ * decides its own UX routing.
+ */
+export function maybeThrowAnonymousExpired(priorAccessToken, refreshStatus) {
+    if (refreshStatus === 401 && priorAccessToken && isAnonymousTokenHeuristic(priorAccessToken)) {
+        throw new AnonymousSessionExpiredError();
+    }
+}
+export { AnonymousSessionExpiredError, RakomiError };

package/dist/ciba.d.ts

@@ -0,0 +1,97 @@
+import type { VerifyResult } from './types.js';
+export interface CibaInitiateOptions {
+    /** Space-delimited or array-of-strings scopes. MUST include `openid`. */
+    scope: string | string[];
+    /** Email or user UUID identifying the human approver. */
+    loginHint: string;
+    /** Human-readable description of the action being authorized. ≤256 chars. */
+    bindingMessage: string;
+    /** Optional bound expiry (60–600s). Server default 120s. */
+    requestedExpiry?: number;
+    /** Optional IETF BCP 47 locale tag (e.g. `pl-PL`). */
+    locale?: string;
+}
+export interface CibaInitiateResponse {
+    authReqId: string;
+    expiresIn: number;
+    interval: number;
+}
+export interface CibaPollResponse {
+    accessToken: string;
+    tokenType: 'Bearer';
+    expiresIn: number;
+    scope: string;
+    idToken?: string;
+}
+export declare class CibaError extends Error {
+    readonly code: string;
+    readonly description: string;
+    constructor(code: string, description: string);
+}
+export declare class CibaAuthorizationPendingError extends CibaError {
+    constructor(d?: string);
+}
+export declare class CibaSlowDownError extends CibaError {
+    constructor(d?: string);
+}
+export declare class CibaAccessDeniedError extends CibaError {
+    constructor(d?: string);
+}
+export declare class CibaExpiredTokenError extends CibaError {
+    constructor(d?: string);
+}
+export declare class CibaReplayError extends CibaError {
+    constructor(d: string);
+}
+export declare class CibaInvalidClientError extends CibaError {
+    constructor(d: string);
+}
+export declare class CibaInvalidScopeError extends CibaError {
+    constructor(d: string);
+}
+export declare class CibaUnauthorizedClientError extends CibaError {
+    constructor(d: string);
+}
+export declare class CibaUnknownUserError extends CibaError {
+    constructor(d: string);
+}
+export declare class CibaUserCapReachedError extends CibaError {
+    constructor(d: string);
+}
+export declare class CibaInvalidRequestError extends CibaError {
+    constructor(d: string);
+}
+interface CibaContext {
+    baseUrl: string;
+    clientId: string;
+    clientSecret: string;
+}
+/**
+ * Initiate a CIBA authentication request via POST /oauth/bc-authorize.
+ *
+ * SSRF hardening: `redirect: 'error'` on fetch.
+ */
+export declare function initiateCiba(ctx: CibaContext, options: CibaInitiateOptions): Promise<VerifyResult<CibaInitiateResponse>>;
+/**
+ * Poll for CIBA approval via POST /oauth/token grant=urn:openid:params:grant-type:ciba.
+ *
+ * Returns Result so the SDK never throws on known API failures. Caller can
+ * branch on `result.error.code` (`ciba/authorization_pending` etc.) — the
+ * canonical mapping mirrors OIDC CIBA Core §11.
+ */
+export declare function pollCiba(ctx: CibaContext, authReqId: string): Promise<VerifyResult<CibaPollResponse>>;
+export interface CibaAwaitDecisionOptions {
+    authReqId: string;
+    /** Initial polling interval (ms). Server default = 5000. */
+    intervalMs?: number;
+    /** Optional AbortSignal — used to cancel the poll loop early. */
+    signal?: AbortSignal;
+}
+/**
+ * Poll loop. Resolves on token issuance; rejects on terminal status
+ * (denied / expired / replay / abort). On `slow_down`, doubles the interval
+ * up to 60s. SDK-managed in-flight guard — never issues two
+ * concurrent polls for the same `authReqId`.
+ */
+export declare function awaitCibaDecision(ctx: CibaContext, options: CibaAwaitDecisionOptions): Promise<CibaPollResponse>;
+export {};

package/dist/ciba.js

@@ -0,0 +1,282 @@
+/**
+ * OIDC CIBA Core 1.0 (asynchronous user consent) helper.
+ *
+ * Three-step API for AI agents that need user approval out-of-band:
+ * - `initiate(options)` → POST /oauth/bc-authorize. Returns `auth_req_id`.
+ * - `poll(authReqId)` → POST /oauth/token grant=urn:openid:params:grant-type:ciba.
+ * - `awaitDecision(options)`→ poll-loop with adaptive interval; resolves on
+ * approve / deny / expiry / AbortSignal.
+ *
+ * Confidential-only: the SDK requires a non-empty `clientSecret` on the
+ * RakomiClient config. Browser/edge runtimes that cannot keep a secret MUST
+ * use the device-grant flow instead.
+ */
+import { CIBA_GRANT_TYPE } from './internal/shared-constants.js';
+export class CibaError extends Error {
+    code;
+    description;
+    constructor(code, description) {
+        super(`${code}: ${description}`);
+        this.code = code;
+        this.description = description;
+    }
+}
+export class CibaAuthorizationPendingError extends CibaError {
+    constructor(d = 'authorization_pending') { super('authorization_pending', d); }
+}
+export class CibaSlowDownError extends CibaError {
+    constructor(d = 'slow_down') { super('slow_down', d); }
+}
+export class CibaAccessDeniedError extends CibaError {
+    constructor(d = 'access_denied') { super('access_denied', d); }
+}
+export class CibaExpiredTokenError extends CibaError {
+    constructor(d = 'expired_token') { super('expired_token', d); }
+}
+export class CibaReplayError extends CibaError {
+    constructor(d) { super('invalid_grant', d); }
+}
+export class CibaInvalidClientError extends CibaError {
+    constructor(d) { super('invalid_client', d); }
+}
+export class CibaInvalidScopeError extends CibaError {
+    constructor(d) { super('invalid_scope', d); }
+}
+export class CibaUnauthorizedClientError extends CibaError {
+    constructor(d) { super('unauthorized_client', d); }
+}
+export class CibaUnknownUserError extends CibaError {
+    constructor(d) { super('unknown_user_id', d); }
+}
+export class CibaUserCapReachedError extends CibaError {
+    constructor(d) { super('user_cap_reached', d); }
+}
+export class CibaInvalidRequestError extends CibaError {
+    constructor(d) { super('invalid_request', d); }
+}
+function basicAuth(clientId, secret) {
+    const raw = `${clientId}:${secret}`;
+    if (typeof Buffer !== 'undefined')
+        return `Basic ${Buffer.from(raw).toString('base64')}`;
+    return `Basic ${btoa(raw)}`;
+}
+function makeError(code, description) {
+    return {
+        code: `ciba/${code}`,
+        message: description,
+        suggestion: code === 'unknown_user_id'
+            ? 'Verify the login_hint matches a real user in this tenant.'
+            : code === 'authorization_pending'
+                ? 'Continue polling at the interval the server returned.'
+                : code === 'slow_down'
+                    ? 'Server-mandated back-off — increase polling interval by 5s.'
+                    : code === 'invalid_scope'
+                        ? 'Requested scope is empty after intersection. Reduce the scope set or extend the client allowlist.'
+                        : 'See description; consult Starlight docs for CIBA grant.',
+        docs_url: 'https://docs.rakomi.dev/oauth/ciba',
+    };
+}
+/**
+ * Initiate a CIBA authentication request via POST /oauth/bc-authorize.
+ *
+ * SSRF hardening: `redirect: 'error'` on fetch.
+ */
+export async function initiateCiba(ctx, options) {
+    const params = new URLSearchParams();
+    params.set('client_id', ctx.clientId);
+    const scopeStr = Array.isArray(options.scope) ? options.scope.join(' ') : options.scope;
+    params.set('scope', scopeStr);
+    params.set('login_hint', options.loginHint);
+    params.set('binding_message', options.bindingMessage);
+    if (options.requestedExpiry !== undefined) {
+        params.set('requested_expiry', String(options.requestedExpiry));
+    }
+    if (options.locale !== undefined) {
+        params.set('binding_message_locale', options.locale);
+    }
+    let res;
+    try {
+        res = await fetch(`${ctx.baseUrl}/oauth/bc-authorize`, {
+            method: 'POST',
+            redirect: 'error',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+                Authorization: basicAuth(ctx.clientId, ctx.clientSecret),
+            },
+            body: params.toString(),
+        });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: {
+                code: 'ciba/network_error',
+                message: err?.message ?? 'Network error',
+                suggestion: 'Verify Rakomi base URL is reachable and that DNS / TLS is healthy.',
+                docs_url: 'https://docs.rakomi.dev/oauth/ciba',
+            },
+        };
+    }
+    let body = {};
+    try {
+        body = (await res.json());
+    }
+    catch {
+    }
+    if (res.ok) {
+        const authReqId = body.auth_req_id;
+        const expiresIn = body.expires_in;
+        const interval = body.interval;
+        if (typeof authReqId !== 'string' ||
+            typeof expiresIn !== 'number' ||
+            typeof interval !== 'number') {
+            return {
+                ok: false,
+                error: {
+                    code: 'ciba/malformed_response',
+                    message: 'Server returned 200 with a body that does not match OIDC CIBA Core §7.3 shape',
+                    suggestion: 'Server-side bug — file an issue.',
+                    docs_url: 'https://docs.rakomi.dev/oauth/ciba',
+                },
+            };
+        }
+        return { ok: true, data: { authReqId, expiresIn, interval } };
+    }
+    const code = body.error ?? `http_${res.status}`;
+    const description = body.error_description ?? `HTTP ${res.status}`;
+    return { ok: false, error: makeError(code, description) };
+}
+/**
+ * Poll for CIBA approval via POST /oauth/token grant=urn:openid:params:grant-type:ciba.
+ *
+ * Returns Result so the SDK never throws on known API failures. Caller can
+ * branch on `result.error.code` (`ciba/authorization_pending` etc.) — the
+ * canonical mapping mirrors OIDC CIBA Core §11.
+ */
+export async function pollCiba(ctx, authReqId) {
+    const params = new URLSearchParams();
+    params.set('grant_type', CIBA_GRANT_TYPE);
+    params.set('auth_req_id', authReqId);
+    let res;
+    try {
+        res = await fetch(`${ctx.baseUrl}/oauth/token`, {
+            method: 'POST',
+            redirect: 'error',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+                Authorization: basicAuth(ctx.clientId, ctx.clientSecret),
+            },
+            body: params.toString(),
+        });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: {
+                code: 'ciba/network_error',
+                message: err?.message ?? 'Network error',
+                suggestion: 'Verify Rakomi base URL is reachable.',
+                docs_url: 'https://docs.rakomi.dev/oauth/ciba',
+            },
+        };
+    }
+    let body = {};
+    try {
+        body = (await res.json());
+    }
+    catch {
+    }
+    if (res.ok) {
+        const accessToken = body.access_token;
+        const tokenType = body.token_type;
+        const expiresIn = body.expires_in;
+        const scope = body.scope;
+        const idToken = body.id_token;
+        if (typeof accessToken !== 'string' ||
+            tokenType !== 'Bearer' ||
+            typeof expiresIn !== 'number' ||
+            typeof scope !== 'string') {
+            return {
+                ok: false,
+                error: {
+                    code: 'ciba/malformed_response',
+                    message: 'Server returned 200 with body that does not match the OAuth token-response shape',
+                    suggestion: 'Server-side bug — file an issue.',
+                    docs_url: 'https://docs.rakomi.dev/oauth/ciba',
+                },
+            };
+        }
+        const out = {
+            accessToken,
+            tokenType: 'Bearer',
+            expiresIn,
+            scope,
+            ...(idToken ? { idToken } : {}),
+        };
+        return { ok: true, data: out };
+    }
+    const code = body.error ?? `http_${res.status}`;
+    const description = body.error_description ?? `HTTP ${res.status}`;
+    return { ok: false, error: makeError(code, description) };
+}
+/**
+ * Poll loop. Resolves on token issuance; rejects on terminal status
+ * (denied / expired / replay / abort). On `slow_down`, doubles the interval
+ * up to 60s. SDK-managed in-flight guard — never issues two
+ * concurrent polls for the same `authReqId`.
+ */
+export async function awaitCibaDecision(ctx, options) {
+    let interval = Math.max(options.intervalMs ?? 5000, 1000);
+    const maxInterval = 60_000;
+    while (true) {
+        if (options.signal?.aborted) {
+            throw new CibaError('aborted', 'CIBA poll aborted');
+        }
+        const result = await pollCiba(ctx, options.authReqId);
+        if (result.ok)
+            return result.data;
+        const code = result.error.code.replace(/^ciba\//, '');
+        switch (code) {
+            case 'authorization_pending':
+                await sleep(interval, options.signal);
+                continue;
+            case 'slow_down':
+                interval = Math.min(interval + 5000, maxInterval);
+                await sleep(interval, options.signal);
+                continue;
+            case 'access_denied':
+                throw new CibaAccessDeniedError(result.error.message);
+            case 'expired_token':
+                throw new CibaExpiredTokenError(result.error.message);
+            case 'invalid_grant':
+                throw new CibaReplayError(result.error.message);
+            case 'invalid_scope':
+                throw new CibaInvalidScopeError(result.error.message);
+            case 'unauthorized_client':
+                throw new CibaUnauthorizedClientError(result.error.message);
+            case 'invalid_client':
+                throw new CibaInvalidClientError(result.error.message);
+            case 'invalid_request':
+                throw new CibaInvalidRequestError(result.error.message);
+            default:
+                throw new CibaError(code, result.error.message);
+        }
+    }
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new CibaError('aborted', 'CIBA poll aborted'));
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new CibaError('aborted', 'CIBA poll aborted'));
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}

package/dist/client.d.ts

@@ -0,0 +1,93 @@
+import { AgentsClient } from './agents.js';
+import { type AnonymousSigninOptions, type AnonymousSigninResult } from './anonymous.js';
+import { type CibaAwaitDecisionOptions, type CibaInitiateOptions, type CibaInitiateResponse, type CibaPollResponse } from './ciba.js';
+import { CredentialsClient } from './credentials.js';
+import { FlagsClient } from './flags.js';
+import { LinkClient } from './link.js';
+import type { MiddlewareRequest, MiddlewareResponse, NextFunction } from './middleware.js';
+import { type TokenExchangeOptions, type TokenExchangeResponse } from './token-exchange.js';
+import type { AuthorizeUrlOptions, MiddlewareOptions, OAuthExchangeOptions, OAuthRefreshOptions, OAuthTokenResponse, PkceChallenge, RakomiConfig, TokenPayload, VerifyResult, WebhookEvent, WebhookVerifyData } from './types.js';
+export declare class RakomiClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly clockTolerance;
+    private readonly environment?;
+    private readonly webhookSecret?;
+    private readonly webhookTolerance;
+    private readonly clientId?;
+    private readonly clientSecret?;
+    private jwksCache;
+    readonly flags: FlagsClient;
+    /** Verifiable Credentials issuance (tenant server-to-server). */
+    readonly credentials: CredentialsClient;
+    /** c: user-scoped account-linking resource. Requires end-user JWT per call. */
+    readonly link: LinkClient;
+    /** end-user agent management (`users.me.agents.list/.revoke`). Requires end-user JWT per call. */
+    readonly users: {
+        readonly me: {
+            readonly agents: AgentsClient;
+        };
+    };
+    constructor(config: RakomiConfig);
+    verifyToken<T extends TokenPayload = TokenPayload>(token: string): Promise<VerifyResult<T>>;
+    verifyWebhook<T = WebhookEvent>(body: string | Buffer, headers: Record<string, string | string[] | undefined>, options?: {
+        tolerance?: number;
+    }): Promise<VerifyResult<WebhookVerifyData<T>>>;
+    middleware(options?: MiddlewareOptions): (req: MiddlewareRequest, res: MiddlewareResponse, next: NextFunction) => void;
+    generatePKCE(): PkceChallenge;
+    generateState(): string;
+    buildAuthorizeUrl(options: Omit<AuthorizeUrlOptions, 'clientId'> & {
+        clientId?: string;
+    }): string;
+    exchangeCode(options: Omit<OAuthExchangeOptions, 'clientId' | 'clientSecret'> & {
+        clientId?: string;
+        clientSecret?: string;
+    }): Promise<VerifyResult<OAuthTokenResponse>>;
+    refreshToken(options: Omit<OAuthRefreshOptions, 'clientId' | 'clientSecret'> & {
+        clientId?: string;
+        clientSecret?: string;
+    }): Promise<VerifyResult<OAuthTokenResponse>>;
+    /**
+   * RFC 8693 token-exchange resource.
+   *
+   * Exchange a user's currently-valid access token for a scoped-down agent
+   * token. Returns RFC 8693 §2.2.1 response. Throwing variant for ergonomic
+   * try/catch flows (typed errors per RFC 6749 §5.2 codes); the underlying
+   * Result-based variant is exposed as `tokens.exchangeViaApi(...)`.
+   *
+   * The SDK client MUST be constructed with `clientId` + `clientSecret`
+   * referencing an agent-type OAuth client (server-side only — never embed
+   * `clientSecret` in browser/mobile code). Invocations without those credentials
+   * throw `TokenExchangeInvalidClientError` synchronously.
+   */
+    readonly tokens: {
+        exchange: (options: TokenExchangeOptions) => Promise<TokenExchangeResponse>;
+        exchangeViaApi: (options: TokenExchangeOptions) => Promise<VerifyResult<TokenExchangeResponse>>;
+    };
+    /**
+   * OIDC CIBA Core 1.0 (asynchronous user consent) resource.
+   *
+   * Three operations:
+   * - `initiate(options)` → POST /oauth/bc-authorize.
+   * - `poll(authReqId)` → POST /oauth/token grant=ciba.
+   * - `awaitDecision(opts)` → poll-loop until decision / abort.
+   *
+   * The SDK client MUST be constructed with `clientId` + `clientSecret`
+   * referencing a confidential or agent-type OAuth client registered with
+   * `grantTypes` including `urn:openid:params:grant-type:ciba` and the
+   * Pro+ tier flag. Invocations without those credentials reject the
+   * Result with `OAUTH_MISSING_CLIENT_ID`.
+   */
+    readonly ciba: {
+        initiate: (options: CibaInitiateOptions) => Promise<VerifyResult<CibaInitiateResponse>>;
+        poll: (authReqId: string) => Promise<VerifyResult<CibaPollResponse>>;
+        awaitDecision: (options: CibaAwaitDecisionOptions) => Promise<CibaPollResponse>;
+    };
+    /**
+   * Create an anonymous user and return its token pair.
+   *
+   * Call from a trusted backend. Returns a Result (never throws on known API
+   * errors); on 403/402/429 the error is mapped to a stable SDK error code.
+   */
+    anonymous(options?: AnonymousSigninOptions): Promise<VerifyResult<AnonymousSigninResult>>;
+}