@rakomi/node 0.0.0 → 0.1.0

package/dist/client.js

@@ -0,0 +1,202 @@
+import { AgentsClient } from './agents.js';
+import { anonymousSignin, } from './anonymous.js';
+import { awaitCibaDecision as awaitCibaDecisionImpl, initiateCiba as initiateCibaImpl, pollCiba as pollCibaImpl, } from './ciba.js';
+import { CredentialsClient } from './credentials.js';
+import { CONFIG_INVALID_BASE_URL, CONFIG_MISSING_API_KEY, CONFIG_MISSING_WEBHOOK_SECRET, OAUTH_MISSING_CLIENT_ID, RakomiError, } from './errors.js';
+import { FlagsClient } from './flags.js';
+import { JwksCache } from './jwks-cache.js';
+import { LinkClient } from './link.js';
+import { createMiddleware } from './middleware.js';
+import { buildAuthorizeUrl as buildAuthorizeUrlImpl, exchangeCode as exchangeCodeImpl, generatePKCE as generatePKCEImpl, generateState as generateStateImpl, refreshToken as refreshTokenImpl, } from './oauth.js';
+import { exchangeTokenOrThrow as exchangeTokenOrThrowImpl, exchangeTokenViaApi as exchangeTokenViaApiImpl, } from './token-exchange.js';
+import { verifyToken } from './verify-token.js';
+import { verifyWebhook as verifyWebhookImpl } from './verify-webhook.js';
+const DEFAULT_BASE_URL = 'https://api.rakomi.com';
+const DEFAULT_CLOCK_TOLERANCE = 30;
+const MAX_CLOCK_TOLERANCE = 120;
+const DEFAULT_WEBHOOK_TOLERANCE = 300;
+const MAX_WEBHOOK_TOLERANCE = 600;
+const API_KEY_PREFIXES = ['ca_live_', 'ca_test_', 'akm_live_', 'akm_test_'];
+export class RakomiClient {
+    apiKey;
+    baseUrl;
+    clockTolerance;
+    environment;
+    webhookSecret;
+    webhookTolerance;
+    clientId;
+    clientSecret;
+    jwksCache = null;
+    flags;
+    /** Verifiable Credentials issuance (tenant server-to-server). */
+    credentials;
+    /** c: user-scoped account-linking resource. Requires end-user JWT per call. */
+    link;
+    /** end-user agent management (`users.me.agents.list/.revoke`). Requires end-user JWT per call. */
+    users;
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new RakomiError(CONFIG_MISSING_API_KEY());
+        }
+        if (!API_KEY_PREFIXES.some((prefix) => config.apiKey.startsWith(prefix))) {
+            throw new RakomiError(CONFIG_MISSING_API_KEY());
+        }
+        this.apiKey = config.apiKey;
+        if (config.baseUrl !== undefined) {
+            let url;
+            try {
+                url = new URL(config.baseUrl);
+            }
+            catch {
+                throw new RakomiError(CONFIG_INVALID_BASE_URL());
+            }
+            const isLocalhost = url.hostname === '127.0.0.1' || url.hostname === 'localhost';
+            if (url.protocol !== 'https:' && !isLocalhost) {
+                throw new RakomiError(CONFIG_INVALID_BASE_URL());
+            }
+            let end = config.baseUrl.length;
+            while (end > 0 && config.baseUrl.charCodeAt(end - 1) === 47)
+                end--;
+            this.baseUrl = config.baseUrl.slice(0, end);
+        }
+        else {
+            this.baseUrl = DEFAULT_BASE_URL;
+        }
+        const tolerance = config.clockTolerance ?? DEFAULT_CLOCK_TOLERANCE;
+        this.clockTolerance = Math.min(Math.max(0, tolerance), MAX_CLOCK_TOLERANCE);
+        this.environment = config.environment;
+        this.webhookSecret = config.webhookSecret;
+        const whTolerance = config.webhookTolerance ?? DEFAULT_WEBHOOK_TOLERANCE;
+        this.webhookTolerance = Math.min(Math.max(0, whTolerance), MAX_WEBHOOK_TOLERANCE);
+        this.clientId = config.clientId;
+        this.clientSecret = config.clientSecret;
+        this.flags = new FlagsClient(this.baseUrl, this.apiKey);
+        this.credentials = new CredentialsClient(this.baseUrl, this.apiKey);
+        this.link = new LinkClient({ baseUrl: this.baseUrl });
+        this.users = { me: { agents: new AgentsClient({ baseUrl: this.baseUrl }) } };
+    }
+    async verifyToken(token) {
+        if (!this.jwksCache) {
+            this.jwksCache = new JwksCache(this.baseUrl);
+        }
+        const sdkEnv = this.apiKey.startsWith('akm_test_') ? 'test' : 'live';
+        return verifyToken(token, this.jwksCache, this.clockTolerance, sdkEnv);
+    }
+    async verifyWebhook(body, headers, options) {
+        if (!this.webhookSecret) {
+            return { ok: false, error: CONFIG_MISSING_WEBHOOK_SECRET() };
+        }
+        const rawTolerance = options?.tolerance ?? this.webhookTolerance;
+        const tolerance = Math.min(Math.max(0, rawTolerance), MAX_WEBHOOK_TOLERANCE);
+        return verifyWebhookImpl(body, headers, this.webhookSecret, tolerance);
+    }
+    middleware(options) {
+        return createMiddleware((token) => this.verifyToken(token), options, this.environment);
+    }
+    generatePKCE() {
+        return generatePKCEImpl();
+    }
+    generateState() {
+        return generateStateImpl();
+    }
+    buildAuthorizeUrl(options) {
+        const clientId = options.clientId ?? this.clientId;
+        if (!clientId) {
+            throw new RakomiError(OAUTH_MISSING_CLIENT_ID());
+        }
+        return buildAuthorizeUrlImpl({
+            ...options,
+            clientId,
+            baseUrl: options.baseUrl ?? this.baseUrl,
+        });
+    }
+    async exchangeCode(options) {
+        return exchangeCodeImpl({
+            ...options,
+            clientId: options.clientId ?? this.clientId,
+            clientSecret: options.clientSecret ?? this.clientSecret,
+            baseUrl: options.baseUrl ?? this.baseUrl,
+        });
+    }
+    async refreshToken(options) {
+        return refreshTokenImpl({
+            ...options,
+            clientId: options.clientId ?? this.clientId,
+            clientSecret: options.clientSecret ?? this.clientSecret,
+            baseUrl: options.baseUrl ?? this.baseUrl,
+        });
+    }
+    /**
+   * 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.
+   */
+    tokens = {
+        exchange: async (options) => {
+            if (!this.clientId || !this.clientSecret) {
+                throw new RakomiError(OAUTH_MISSING_CLIENT_ID());
+            }
+            return exchangeTokenOrThrowImpl({ baseUrl: this.baseUrl, clientId: this.clientId, clientSecret: this.clientSecret }, options);
+        },
+        exchangeViaApi: async (options) => {
+            if (!this.clientId || !this.clientSecret) {
+                return { ok: false, error: OAUTH_MISSING_CLIENT_ID() };
+            }
+            return exchangeTokenViaApiImpl({ baseUrl: this.baseUrl, clientId: this.clientId, clientSecret: this.clientSecret }, options);
+        },
+    };
+    /**
+   * 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`.
+   */
+    ciba = {
+        initiate: async (options) => {
+            if (!this.clientId || !this.clientSecret) {
+                return { ok: false, error: OAUTH_MISSING_CLIENT_ID() };
+            }
+            return initiateCibaImpl({ baseUrl: this.baseUrl, clientId: this.clientId, clientSecret: this.clientSecret }, options);
+        },
+        poll: async (authReqId) => {
+            if (!this.clientId || !this.clientSecret) {
+                return { ok: false, error: OAUTH_MISSING_CLIENT_ID() };
+            }
+            return pollCibaImpl({ baseUrl: this.baseUrl, clientId: this.clientId, clientSecret: this.clientSecret }, authReqId);
+        },
+        awaitDecision: async (options) => {
+            if (!this.clientId || !this.clientSecret) {
+                throw new RakomiError(OAUTH_MISSING_CLIENT_ID());
+            }
+            return awaitCibaDecisionImpl({ baseUrl: this.baseUrl, clientId: this.clientId, clientSecret: this.clientSecret }, options);
+        },
+    };
+    /**
+   * 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.
+   */
+    async anonymous(options = {}) {
+        return anonymousSignin({
+            baseUrl: this.baseUrl,
+            apiKey: this.apiKey,
+        }, options);
+    }
+}

package/dist/credentials.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Verifiable Credentials Issuer SDK accessors (`@rakomi/node`).
+ *
+ * Server-to-server methods for tenant backends to issue, list, get, and revoke VCs via
+ * the Rakomi issuer (OpenID4VCI).
+ *
+ * Error contract (closed set): `invalid_claims`, `tenant_disabled`, `rate_limited`, `no_pepper`,
+ * `user_not_found`, `schema_violation`, `dpia_not_acknowledged`, `minor_blocked`,
+ * `pid_attribute_forbidden`.
+ */
+/**
+ * VC issuer SDK errors are thrown as `VcSdkError` (extending Error). Code semantics align
+ * with the Rakomi API error codes (e.g. `vc/tenant_disabled`, `vc/invalid_claims`).
+ */
+export declare class VcSdkError extends Error {
+    readonly code: string;
+    readonly httpStatus: number;
+    constructor(code: string, message: string, httpStatus: number);
+}
+export type VcBuiltinType = 'MembershipCredential' | 'SubscriptionCredential' | 'VerifiedEmailCredential' | 'AgeVerificationCredential' | 'CustomCredential';
+export type VcRevocationReason = 'key_compromise' | 'service_terminated' | 'attribute_change' | 'user_request' | 'other';
+export type VcCredentialStatus = 'active' | 'revoked' | 'expired';
+export interface VcCredentialResponse {
+    jti: string;
+    vct: string;
+    credential_type: VcBuiltinType;
+    custom_type_name: string | null;
+    user_id: string;
+    subject_type: 'user' | 'agent' | 'org';
+    issued_at: string;
+    valid_from: string | null;
+    valid_until: string | null;
+    revoked_at: string | null;
+    revocation_reason: VcRevocationReason | null;
+    status: VcCredentialStatus;
+    signing_kid: string;
+    holder_jkt: string | null;
+}
+export interface VcOfferResponse {
+    jti: string;
+    vct: string;
+    status: {
+        idx: number;
+        uri: string;
+    };
+    credential_offer_uri: string;
+    download_url: string;
+    expires_at: string;
+}
+export interface VcIssueParams {
+    userId: string;
+    credentialType: VcBuiltinType;
+    customTypeName?: string;
+    claims: Record<string, unknown>;
+    validFrom?: string;
+    validUntil?: string;
+    subjectType?: 'user' | 'agent' | 'org';
+}
+export interface VcListParams {
+    userId?: string;
+    credentialType?: VcBuiltinType;
+    limit?: number;
+    offset?: number;
+}
+export interface VcRevokeParams {
+    reason: VcRevocationReason;
+}
+export declare class CredentialsClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    issue(params: VcIssueParams): Promise<VcOfferResponse>;
+    list(params?: VcListParams): Promise<{
+        data: VcCredentialResponse[];
+    }>;
+    get(jti: string): Promise<VcCredentialResponse>;
+    revoke(jti: string, reason?: VcRevocationReason): Promise<{
+        jti: string;
+        revoked_at: string;
+        status: {
+            idx: number;
+            uri: string;
+            list_version: number;
+        };
+    }>;
+    private parse;
+}

package/dist/credentials.js

@@ -0,0 +1,104 @@
+/**
+ * Verifiable Credentials Issuer SDK accessors (`@rakomi/node`).
+ *
+ * Server-to-server methods for tenant backends to issue, list, get, and revoke VCs via
+ * the Rakomi issuer (OpenID4VCI).
+ *
+ * Error contract (closed set): `invalid_claims`, `tenant_disabled`, `rate_limited`, `no_pepper`,
+ * `user_not_found`, `schema_violation`, `dpia_not_acknowledged`, `minor_blocked`,
+ * `pid_attribute_forbidden`.
+ */
+/**
+ * VC issuer SDK errors are thrown as `VcSdkError` (extending Error). Code semantics align
+ * with the Rakomi API error codes (e.g. `vc/tenant_disabled`, `vc/invalid_claims`).
+ */
+export class VcSdkError extends Error {
+    code;
+    httpStatus;
+    constructor(code, message, httpStatus) {
+        super(message);
+        this.code = code;
+        this.httpStatus = httpStatus;
+        this.name = 'VcSdkError';
+    }
+}
+export class CredentialsClient {
+    baseUrl;
+    apiKey;
+    constructor(baseUrl, apiKey) {
+        this.baseUrl = baseUrl;
+        this.apiKey = apiKey;
+    }
+    async issue(params) {
+        const res = await fetch(`${this.baseUrl}/v1/credentials/issue`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-API-Key': this.apiKey,
+            },
+            redirect: 'error',
+            body: JSON.stringify({
+                user_id: params.userId,
+                credential_type: params.credentialType,
+                custom_type_name: params.customTypeName,
+                claims: params.claims,
+                valid_from: params.validFrom,
+                valid_until: params.validUntil,
+                subject_type: params.subjectType,
+            }),
+        });
+        return this.parse(res, 'issue');
+    }
+    async list(params = {}) {
+        const url = new URL(`${this.baseUrl}/v1/credentials`);
+        if (params.userId)
+            url.searchParams.set('user_id', params.userId);
+        if (params.credentialType)
+            url.searchParams.set('credential_type', params.credentialType);
+        if (params.limit !== undefined)
+            url.searchParams.set('limit', String(params.limit));
+        if (params.offset !== undefined)
+            url.searchParams.set('offset', String(params.offset));
+        const res = await fetch(url, {
+            headers: { 'X-API-Key': this.apiKey },
+            redirect: 'error',
+        });
+        return this.parse(res, 'list');
+    }
+    async get(jti) {
+        const res = await fetch(`${this.baseUrl}/v1/credentials/${encodeURIComponent(jti)}`, {
+            headers: { 'X-API-Key': this.apiKey },
+            redirect: 'error',
+        });
+        return this.parse(res, 'get');
+    }
+    async revoke(jti, reason = 'user_request') {
+        const res = await fetch(`${this.baseUrl}/v1/credentials/${encodeURIComponent(jti)}/revoke`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-API-Key': this.apiKey,
+            },
+            redirect: 'error',
+            body: JSON.stringify({ reason }),
+        });
+        return this.parse(res, 'revoke');
+    }
+    async parse(res, op) {
+        if (!res.ok) {
+            let code = `vc/${op}_failed`;
+            let message = `VC ${op} failed with HTTP ${res.status}`;
+            try {
+                const body = (await res.json());
+                if (body.code)
+                    code = body.code;
+                if (body.message)
+                    message = body.message;
+            }
+            catch {
+            }
+            throw new VcSdkError(code, message, res.status);
+        }
+        return (await res.json());
+    }
+}

package/dist/device.d.ts

@@ -0,0 +1,76 @@
+import type { OAuthTokenResponse, VerifyResult } from './types.js';
+export interface StartDeviceAuthorizationOptions {
+    clientId: string;
+    /** Optional confidential-client secret. Public clients omit. */
+    clientSecret?: string;
+    /** Space-separated scopes or array. Defaults to client's registered scopes. */
+    scope?: string | string[];
+    /** OIDC nonce — propagated into id_token at success-poll time. */
+    nonce?: string;
+    baseUrl?: string;
+}
+export interface DeviceAuthorizationIssued {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    expires_in: number;
+    interval: number;
+    message?: string;
+}
+export interface PollForDeviceTokenOptions {
+    deviceCode: string;
+    clientId: string;
+    clientSecret?: string;
+    baseUrl?: string;
+    /** Honored by the underlying fetch — aborting cancels the in-flight request. */
+    signal?: AbortSignal;
+}
+export interface AwaitDeviceTokensOptions extends PollForDeviceTokenOptions {
+    /** Server-suggested initial interval in seconds. */
+    intervalSeconds: number;
+    /** Hard client-side timeout in milliseconds (defaults to 30 min). */
+    timeoutMs?: number;
+    /** AbortSignal for caller-driven cancellation. */
+    signal?: AbortSignal;
+}
+export interface RunDeviceFlowOptions {
+    clientId: string;
+    clientSecret?: string;
+    scope?: string | string[];
+    nonce?: string;
+    baseUrl?: string;
+    /** Called once with the issued user_code + verification URLs so the caller can display them. */
+    onCode: (issued: DeviceAuthorizationIssued) => void | Promise<void>;
+    signal?: AbortSignal;
+    /** Override the timeout from issued.expires_in. */
+    timeoutMs?: number;
+}
+/**
+ * POST /oauth/device/code — initiate a device authorization request.
+ */
+export declare function startDeviceAuthorization(options: StartDeviceAuthorizationOptions): Promise<VerifyResult<DeviceAuthorizationIssued>>;
+/**
+ * POST /oauth/token — single poll for a device authorization grant.
+ *
+ * Returns:
+ *   - ok: true → access_token + refresh_token (+ id_token if openid was requested)
+ *   - ok: false, error.code === 'device/authorization_pending' → keep polling
+ *   - ok: false, error.code === 'device/slow_down' → increment interval +5s, keep polling
+ *   - ok: false, error.code === 'device/access_denied' | 'device/expired_token' → stop
+ *   - ok: false, OAuth/network error → stop
+ */
+export declare function pollForDeviceToken(options: PollForDeviceTokenOptions): Promise<VerifyResult<OAuthTokenResponse>>;
+/**
+ * High-level helper: poll the token endpoint at the server-suggested interval
+ * until success, terminal error, timeout, or abort. Honors RFC 8628 §3.5
+ * `slow_down` by incrementing the interval by 5s before the next poll.
+ */
+export declare function awaitDeviceTokens(options: AwaitDeviceTokensOptions): Promise<VerifyResult<OAuthTokenResponse>>;
+/**
+ * One-shot device flow: initiate, surface the code via `onCode`, poll until
+ * tokens are issued. Returns the same VerifyResult as awaitDeviceTokens.
+ *
+ * Copy-paste recipe for CLIs and AI agents.
+ */
+export declare function run(options: RunDeviceFlowOptions): Promise<VerifyResult<OAuthTokenResponse>>;