@rakomi/node 0.0.0 → 0.1.0

package/dist/link.js

@@ -0,0 +1,262 @@
+/**
+ * Node SDK surface for user-scoped account linking.
+ *
+ * Wraps the three `/v1/users/me/link*` endpoints.
+ * These endpoints require an end-user JWT (NOT an API key), so each helper
+ * takes a `{ userToken }` option. The SDK client (constructed with an API key)
+ * only carries the `baseUrl`; the user token flows per-call.
+ *
+ * Returns the shared `VerifyResult` shape — NEVER throws on expected 4xx.
+ * Typed error classes (AccountLinkingDisabledError, IdentityOwnedByOtherUserError,
+ * CannotUnlinkLastMethodError) are also exported for callers that prefer
+ * pattern-matching via `instanceof` over inspecting `error.code`.
+ */
+import { ACCOUNT_LINKING_IDENTITY_NOT_FOUND, ACCOUNT_LINKING_NETWORK_ERROR, ACCOUNT_LINKING_RATE_LIMITED, AccountLinkingDisabledError, CannotUnlinkLastMethodError, CooldownActiveError, IdentityOwnedByOtherUserError, LinkStateExpiredError, MfaStepUpRequiredError, MfaStepUpUnavailableError, } from './errors.js';
+function parseRetryAfter(res) {
+    const retryAfter = res.headers.get('retry-after');
+    if (!retryAfter)
+        return undefined;
+    const n = Number(retryAfter);
+    if (Number.isFinite(n) && n > 0)
+        return Math.round(n);
+    const ts = Date.parse(retryAfter);
+    if (!Number.isFinite(ts))
+        return undefined;
+    const delta = Math.round((ts - Date.now()) / 1000);
+    return delta > 0 ? delta : undefined;
+}
+async function safeJson(res) {
+    try {
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+}
+async function parseErrorBody(res) {
+    try {
+        return (await res.json());
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * User-scoped account-linking resource. Attached to `RakomiClient#link`.
+ *
+ * All methods require an end-user JWT passed via `{ userToken }`. The underlying
+ * `RakomiClient` API key is NOT sent on these calls — the API rejects API-key
+ * auth on user-scoped routes.
+ */
+export class LinkClient {
+    baseUrl;
+    fetchImpl;
+    constructor(ctx) {
+        this.baseUrl = ctx.baseUrl;
+        this.fetchImpl = ctx.fetchImpl ?? fetch;
+    }
+    /** GET /v1/users/me/link — list linked methods for the authenticated user. */
+    async list(options) {
+        let res;
+        try {
+            res = await this.fetchImpl(`${this.baseUrl}/v1/users/me/link`, {
+                method: 'GET',
+                headers: {
+                    Authorization: `Bearer ${options.userToken}`,
+                    Accept: 'application/json',
+                },
+                redirect: 'error',
+            });
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: ACCOUNT_LINKING_NETWORK_ERROR(err instanceof Error ? err.message : undefined),
+            };
+        }
+        if (res.status === 200) {
+            const body = await safeJson(res);
+            if (!body || !Array.isArray(body.methods)) {
+                return { ok: false, error: ACCOUNT_LINKING_NETWORK_ERROR('malformed response body') };
+            }
+            return { ok: true, data: body };
+        }
+        return { ok: false, error: await this.mapError(res, 'list') };
+    }
+    /** POST /v1/users/me/link/{provider} — initiate OAuth link flow. */
+    async initiate(provider, options) {
+        const body = { redirect_uri: options.redirectUri };
+        if (options.mfaVerificationToken) {
+            body.mfa_verification_token = options.mfaVerificationToken;
+        }
+        let res;
+        try {
+            res = await this.fetchImpl(`${this.baseUrl}/v1/users/me/link/${encodeURIComponent(provider)}`, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${options.userToken}`,
+                    'Content-Type': 'application/json',
+                    Accept: 'application/json',
+                },
+                body: JSON.stringify(body),
+                redirect: 'error',
+            });
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: ACCOUNT_LINKING_NETWORK_ERROR(err instanceof Error ? err.message : undefined),
+            };
+        }
+        if (res.status === 200) {
+            const body = await safeJson(res);
+            if (!body || typeof body.authorization_url !== 'string') {
+                return { ok: false, error: ACCOUNT_LINKING_NETWORK_ERROR('malformed response body') };
+            }
+            if (!/^https?:\/\//i.test(body.authorization_url)) {
+                return { ok: false, error: ACCOUNT_LINKING_NETWORK_ERROR('invalid authorization_url scheme') };
+            }
+            return { ok: true, data: body };
+        }
+        return { ok: false, error: await this.mapError(res, 'initiate') };
+    }
+    /** DELETE /v1/users/me/link/{provider} — unlink a social identity. */
+    async remove(provider, options) {
+        let res;
+        try {
+            res = await this.fetchImpl(`${this.baseUrl}/v1/users/me/link/${encodeURIComponent(provider)}`, {
+                method: 'DELETE',
+                headers: {
+                    Authorization: `Bearer ${options.userToken}`,
+                    Accept: 'application/json',
+                },
+                redirect: 'error',
+            });
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: ACCOUNT_LINKING_NETWORK_ERROR(err instanceof Error ? err.message : undefined),
+            };
+        }
+        if (res.status === 200) {
+            const body = await safeJson(res);
+            if (!body || typeof body.unlinked !== 'boolean') {
+                return { ok: false, error: ACCOUNT_LINKING_NETWORK_ERROR('malformed response body') };
+            }
+            return { ok: true, data: body };
+        }
+        return { ok: false, error: await this.mapError(res, 'remove') };
+    }
+    async mapError(res, op) {
+        const body = await parseErrorBody(res);
+        const code = body.code ?? '';
+        switch (res.status) {
+            case 400:
+                if (code === 'account_linking/link_state_expired_or_missing') {
+                    const err = new LinkStateExpiredError(body.message);
+                    return sdkErrorFromClass(err);
+                }
+                break;
+            case 401:
+                if (code === 'account_linking/mfa_step_up_unavailable') {
+                    const err = new MfaStepUpUnavailableError('passwordless_user_no_step_up_route', body.message);
+                    return sdkErrorFromClass(err, { reason: err.reason });
+                }
+                if (code === 'account_linking/mfa_required') {
+                    const challenge = typeof body.mfa_challenge_token === 'string'
+                        ? body.mfa_challenge_token
+                        : typeof body.details?.mfa_challenge_token === 'string'
+                            ? body.details.mfa_challenge_token
+                            : 'mfa_step_up_required';
+                    const availableRaw = Array.isArray(body.available_methods)
+                        ? body.available_methods
+                        : Array.isArray(body.details?.available_methods)
+                            ? body.details.available_methods
+                            : undefined;
+                    const availableMethods = availableRaw && availableRaw.length > 0
+                        ? availableRaw.filter((m) => typeof m === 'string')
+                        : undefined;
+                    const err = new MfaStepUpRequiredError(challenge, body.message, availableMethods);
+                    return sdkErrorFromClass(err, {
+                        next_action: err.next_action,
+                        ...(availableMethods ? { available_methods: [...availableMethods] } : {}),
+                    });
+                }
+                return {
+                    code: 'account_linking/unauthorized',
+                    message: body.message || 'User token is missing, expired, or invalid.',
+                    suggestion: 'Re-authenticate the end user and retry with a fresh access token.',
+                    docs_url: 'https://docs.rakomi.dev/sdk/errors#account_linking-unauthorized',
+                };
+            case 403:
+                if (code === 'account_linking/disabled_for_tenant') {
+                    const err = new AccountLinkingDisabledError(body.message);
+                    return sdkErrorFromClass(err);
+                }
+                return {
+                    code: code || 'account_linking/forbidden',
+                    message: body.message || 'Forbidden',
+                    suggestion: 'The end user is not permitted to perform this account-linking operation.',
+                    docs_url: 'https://docs.rakomi.dev/sdk/errors#account_linking-forbidden',
+                };
+            case 404:
+                if (code === 'account_linking/identity_not_found' || (op === 'remove' && !code)) {
+                    return ACCOUNT_LINKING_IDENTITY_NOT_FOUND();
+                }
+                return {
+                    code: code || 'account_linking/not_found',
+                    message: body.message || `HTTP 404`,
+                    suggestion: 'The requested resource was not found.',
+                    docs_url: 'https://docs.rakomi.dev/sdk/errors#account_linking-not_found',
+                };
+            case 409:
+                if (code === 'account_linking/cannot_unlink_last_method') {
+                    const err = new CannotUnlinkLastMethodError(body.details?.remaining_methods ?? [], body.message);
+                    return sdkErrorFromClass(err, { remaining_methods: err.remaining_methods });
+                }
+                if (code === 'account_linking/identity_owned_by_other_user') {
+                    const err = new IdentityOwnedByOtherUserError(body.message);
+                    return sdkErrorFromClass(err);
+                }
+                break;
+            case 429:
+                if (code === 'account_linking/cooldown_active') {
+                    const unlockAt = typeof body.details?.unlock_at === 'string'
+                        ? body.details.unlock_at
+                        : new Date(Date.now() + 60 * 60 * 1000).toISOString();
+                    const reason = body.details?.reason === 'account_recently_linked'
+                        ? 'account_recently_linked'
+                        : 'unknown';
+                    const err = new CooldownActiveError(unlockAt, reason, body.message);
+                    return sdkErrorFromClass(err, {
+                        unlock_at: err.unlockAtIso,
+                        reason: err.reason,
+                    });
+                }
+                return ACCOUNT_LINKING_RATE_LIMITED(parseRetryAfter(res));
+        }
+        const truncated = (body.message ?? '').slice(0, 200);
+        return ACCOUNT_LINKING_NETWORK_ERROR(truncated || `HTTP ${res.status}`);
+    }
+}
+const DOCS_BASE = 'https://docs.rakomi.dev/sdk/errors';
+/**
+ * Convert a typed Error class instance into the SDK's SdkError object shape.
+ * Callers who want the typed class can still `instanceof` the exported classes;
+ * this bridge lets the Result-returning APIs emit structured errors without
+ * throwing.
+ */
+function sdkErrorFromClass(err, extra) {
+    const base = {
+        code: err.code,
+        message: err.message,
+        suggestion: err.suggestion,
+        docs_url: err.docs_url ?? `${DOCS_BASE}#${err.code.replace('/', '-')}`,
+    };
+    if (extra) {
+        for (const [k, v] of Object.entries(extra))
+            base[k] = v;
+    }
+    return base;
+}

package/dist/middleware.d.ts

@@ -0,0 +1,21 @@
+import type { MiddlewareOptions, SdkEnvironment, TokenPayload, VerifyResult } from './types.js';
+export interface MiddlewareRequest {
+    headers: Record<string, string | string[] | undefined>;
+}
+export interface MiddlewareResponse {
+    status(code: number): MiddlewareResponse;
+    json(body: unknown): void;
+    setHeader(name: string, value: string): void;
+}
+export type NextFunction = (error?: unknown) => void;
+type VerifyTokenFn = (token: string) => Promise<VerifyResult<TokenPayload>>;
+/**
+ * Resolve whether to include verbose error details (suggestions, fix commands).
+ * SECURITY: NEVER trust the Host header — a spoofed
+ * `Host: localhost` in production would leak permission/role names.
+ * Uses ONLY the `environmentOverride` config parameter set at SDK init time.
+ * Safe default: production (non-verbose).
+ */
+export declare function resolveVerbose(_req: MiddlewareRequest, environmentOverride?: SdkEnvironment): boolean;
+export declare function createMiddleware(verifyTokenFn: VerifyTokenFn, options?: MiddlewareOptions, environmentOverride?: SdkEnvironment): (req: MiddlewareRequest, res: MiddlewareResponse, next: NextFunction) => void;
+export {};

package/dist/middleware.js

@@ -0,0 +1,84 @@
+const BEARER_PREFIX = 'bearer ';
+function formatWireError(sdkError, verbose) {
+    if (verbose) {
+        return {
+            error: {
+                code: sdkError.code,
+                message: sdkError.message,
+                docs_url: sdkError.docs_url,
+                suggestion: sdkError.suggestion,
+                fix_command: sdkError.fix_command,
+            },
+        };
+    }
+    return {
+        error: {
+            code: sdkError.code,
+            message: sdkError.message,
+            docs_url: sdkError.docs_url,
+        },
+    };
+}
+/**
+ * Resolve whether to include verbose error details (suggestions, fix commands).
+ * SECURITY: NEVER trust the Host header — a spoofed
+ * `Host: localhost` in production would leak permission/role names.
+ * Uses ONLY the `environmentOverride` config parameter set at SDK init time.
+ * Safe default: production (non-verbose).
+ */
+export function resolveVerbose(_req, environmentOverride) {
+    if (environmentOverride) {
+        return environmentOverride === 'development';
+    }
+    return false;
+}
+export function createMiddleware(verifyTokenFn, options, environmentOverride) {
+    return (req, res, next) => {
+        const verbose = resolveVerbose(req, environmentOverride);
+        void (async () => {
+            try {
+                const authorization = req.headers['authorization'] ?? req.headers['Authorization'];
+                const authHeader = typeof authorization === 'string' ? authorization : undefined;
+                if (!authHeader || !authHeader.toLowerCase().startsWith(BEARER_PREFIX)) {
+                    const error = {
+                        code: 'token/missing',
+                        message: 'Authorization header with Bearer token is required',
+                        suggestion: 'Include an Authorization header: Bearer <token>',
+                        docs_url: 'https://docs.rakomi.dev/sdk/errors#token-missing',
+                    };
+                    if (options?.onError) {
+                        options.onError(error, req, res);
+                        return;
+                    }
+                    res.status(401).json(formatWireError(error, verbose));
+                    return;
+                }
+                const token = authHeader.slice(BEARER_PREFIX.length);
+                const result = await verifyTokenFn(token);
+                if (!result.ok) {
+                    if (options?.onError) {
+                        options.onError(result.error, req, res);
+                        return;
+                    }
+                    res.status(401).json(formatWireError(result.error, verbose));
+                    return;
+                }
+                req.auth = result.data;
+                next();
+            }
+            catch {
+                const error = {
+                    code: 'token/internal_error',
+                    message: 'An internal error occurred during token verification',
+                    suggestion: 'This is unexpected. Please retry or contact support',
+                    docs_url: 'https://docs.rakomi.dev/sdk/errors#token-internal_error',
+                };
+                if (options?.onError) {
+                    options.onError(error, req, res);
+                    return;
+                }
+                res.status(401).json(formatWireError(error, verbose));
+            }
+        })();
+    };
+}

package/dist/oauth.d.ts

@@ -0,0 +1,46 @@
+import type { AuthorizeUrlOptions, OAuthExchangeOptions, OAuthRefreshOptions, OAuthRotateOptions, OAuthTokenResponse, PkceChallenge, RotationTokenResponse, VerifyResult } from './types.js';
+/**
+ * Generate a PKCE code verifier and challenge pair.
+ * Uses node:crypto for secure random generation.
+ */
+export declare function generatePKCE(): PkceChallenge;
+/**
+ * Generate a random state parameter for CSRF protection.
+ * Returns 32 random bytes, hex-encoded.
+ */
+export declare function generateState(): string;
+/**
+ * Build a full /oauth/authorize URL with all required parameters.
+ * Pure function — no config dependency, usable without RakomiClient instance.
+ */
+export declare function buildAuthorizeUrl(options: AuthorizeUrlOptions): string;
+/**
+ * Exchange an authorization code for tokens via POST /oauth/token.
+ * Never throws — returns VerifyResult<OAuthTokenResponse>.
+ */
+export declare function exchangeCode(options: OAuthExchangeOptions): Promise<VerifyResult<OAuthTokenResponse>>;
+/**
+ * Refresh an OAuth token via POST /oauth/token.
+ * Serializes concurrent calls with the same refresh token to prevent nuclear revocation.
+ * Never throws — returns VerifyResult<OAuthTokenResponse>.
+ */
+export declare function refreshToken(options: OAuthRefreshOptions): Promise<VerifyResult<OAuthTokenResponse>>;
+/**
+ * Perform an in-band DPoP refresh-key ROTATION via POST /oauth/token
+ * Co-presents the OLD-key proof (the
+ * session's current key, on the primary `DPoP` header — backward-safe) and a
+ * fresh NEW-key proof (on the `DPoP-Rotate` header) on ONE refresh request, then
+ * atomically swaps the session's active prover to the new key ONLY after the
+ * server confirms a 200 whose access-token `cnf.jkt` EQUALS the new key's `jkt`
+ * (the master invariant). Any other outcome keeps the OLD key bound (fail-SAFE,
+ * never a half-swap) and surfaces a distinct non-success signal.
+ *
+ * This is a DEDICATED ceremony, not a flag on {@link refreshToken}: the second
+ * key is created only inside this call frame, so a `DPoP-Rotate` header is
+ * structurally impossible to attach to an ordinary refresh. Single-flight
+ * per session — a concurrent rotation coalesces. Never throws; always resolves to
+ * a `VerifyResult`.
+ *
+ * @public — additive-only after the first public release.
+ */
+export declare function rotateRefreshKey(options: OAuthRotateOptions): Promise<VerifyResult<RotationTokenResponse>>;