@rakomi/node 0.0.0 → 0.1.0

package/dist/env-detect.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Per-request environment detection based on hostname.
+ * Safe default: production (never accidentally expose verbose errors).
+ */
+import type { SdkEnvironment } from './types.js';
+/**
+ * Detect environment from request hostname.
+ * Returns 'development' for localhost, 127.0.0.1, ::1, *.local.
+ * Returns 'production' for everything else (safe default).
+ */
+export declare function detectEnvironment(hostname: string): SdkEnvironment;

package/dist/env-detect.js

@@ -0,0 +1,26 @@
+/**
+ * Per-request environment detection based on hostname.
+ * Safe default: production (never accidentally expose verbose errors).
+ */
+const DEV_HOSTNAMES = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+/**
+ * Detect environment from request hostname.
+ * Returns 'development' for localhost, 127.0.0.1, ::1, *.local.
+ * Returns 'production' for everything else (safe default).
+ */
+export function detectEnvironment(hostname) {
+    if (!hostname)
+        return 'production';
+    if (DEV_HOSTNAMES.has(hostname))
+        return 'development';
+    const host = hostname.includes(']:')
+        ? hostname.slice(1, hostname.indexOf(']'))
+        : hostname.lastIndexOf(':') > hostname.indexOf(':')
+            ? hostname
+            : hostname.split(':')[0];
+    if (DEV_HOSTNAMES.has(host))
+        return 'development';
+    if (host.endsWith('.local'))
+        return 'development';
+    return 'production';
+}

package/dist/errors.d.ts

@@ -0,0 +1,307 @@
+import type { SdkError } from './types.js';
+/**
+ * Error class thrown by Rakomi constructor for configuration errors.
+ * Extends Error so `instanceof Error` works and stack traces are available.
+ */
+export declare class RakomiError extends Error {
+    readonly code: string;
+    readonly suggestion: string;
+    readonly docs_url: string;
+    readonly fix_command?: string;
+    constructor(sdkError: SdkError);
+}
+export declare const ERROR_CODES: {
+    readonly TOKEN_REVOKED: "token/revoked";
+    readonly TOKEN_EXPIRED: "token/expired";
+    readonly TOKEN_INVALID_SIGNATURE: "token/invalid_signature";
+    readonly TOKEN_MALFORMED: "token/malformed";
+    readonly TOKEN_INVALID_ALGORITHM: "token/invalid_algorithm";
+    readonly TOKEN_MISSING_CLAIMS: "token/missing_claims";
+    readonly TOKEN_INVALID_ISSUER: "token/invalid_issuer";
+    readonly TOKEN_INVALID_AUDIENCE: "token/invalid_audience";
+    readonly TOKEN_NOT_YET_VALID: "token/not_yet_valid";
+    readonly AUTH_ENVIRONMENT_MISMATCH: "auth/environment_mismatch";
+    readonly AUTH_DPOP_PROVER_UNAVAILABLE: "auth/dpop_prover_unavailable";
+    readonly AUTH_INVALID_DPOP_PROOF: "auth/invalid_dpop_proof";
+    readonly AUTH_INVALID_REFRESH_TOKEN: "auth/invalid_refresh_token";
+    readonly AUTH_DPOP_ROTATION_NOOP: "auth/dpop_rotation_noop";
+    readonly AUTH_DPOP_ROTATION_DID_NOT_TAKE: "auth/dpop_rotation_did_not_take";
+    readonly AUTH_REFRESH_SUPERSEDED_BY_ROTATION: "auth/refresh_superseded_by_rotation";
+    readonly JWKS_FETCH_FAILED: "jwks/fetch_failed";
+    readonly JWKS_NO_MATCHING_KEY: "jwks/no_matching_key";
+    readonly JWKS_INVALID_RESPONSE: "jwks/invalid_response";
+    readonly WEBHOOK_TIMESTAMP_TOO_OLD: "webhook/timestamp_too_old";
+    readonly WEBHOOK_TIMESTAMP_TOO_NEW: "webhook/timestamp_too_new";
+    readonly WEBHOOK_INVALID_SIGNATURE: "webhook/invalid_signature";
+    readonly WEBHOOK_INVALID_SECRET: "webhook/invalid_secret";
+    readonly WEBHOOK_MISSING_HEADER: "webhook/missing_header";
+    readonly WEBHOOK_INVALID_BODY: "webhook/invalid_body";
+};
+export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+export declare const TOKEN_REVOKED: () => SdkError;
+export declare const TOKEN_EXPIRED: () => SdkError;
+export declare const TOKEN_INVALID_SIGNATURE: () => SdkError;
+export declare const TOKEN_MALFORMED: () => SdkError;
+export declare const TOKEN_INVALID_ALGORITHM: () => SdkError;
+export declare const TOKEN_MISSING_CLAIMS: () => SdkError;
+export declare const TOKEN_INVALID_ISSUER: () => SdkError;
+export declare const TOKEN_INVALID_AUDIENCE: () => SdkError;
+export declare const TOKEN_NOT_YET_VALID: () => SdkError;
+export declare const AUTH_ENVIRONMENT_MISMATCH: () => SdkError;
+/**
+ * Client-side: this SDK/platform could not produce a DPoP proof here (no native
+ * prover, or the signer threw / returned falsy). NOT a security event — the SDK
+ * deliberately refused to send an empty/malformed `DPoP` header rather than
+ * silently downgrade to Bearer. App action: report a bug / re-login.
+ */
+export declare const AUTH_DPOP_PROVER_UNAVAILABLE: (detail?: string) => SdkError;
+/**
+ * Server rejected the DPoP proof on the refresh request (signature / `htu` /
+ * `htm` / replayed `jti` / cold-start key mismatch). App action: re-attach a
+ * fresh proof, check device clock skew, or re-authenticate to re-bind the key.
+ */
+export declare const AUTH_INVALID_DPOP_PROOF: (detail?: string) => SdkError;
+/**
+ * The refresh token itself is invalid, expired, or has been revoked (the
+ * genuine end-of-session class — RFC 6749 `invalid_grant` on the refresh
+ * operation). App action: start a full re-authentication (login) flow.
+ */
+export declare const AUTH_INVALID_REFRESH_TOKEN: (detail?: string) => SdkError;
+/**
+ * Client-side rotation bug: the SDK attempted to rotate to a key the server
+ * already has bound (server `400 invalid_request` reason `rotation_noop`). NOT a
+ * security event and NO re-login — the session is unchanged. A fresh keypair
+ * makes this practically unreachable from the SDK; it surfaces only if a caller
+ * forces the new key to equal the old. App action: drop the rotation, keep using
+ * the current session.
+ */
+export declare const AUTH_DPOP_ROTATION_NOOP: (detail?: string) => SdkError;
+/**
+ * The rotation did not take AND no usable refreshed token was obtained. This is the
+ * FAILURE arm — distinct from the common rotation-unaware-server case where the
+ * refresh itself succeeds (that returns `{ ok: true, data: { ...tokens, rotated: false } }` — a
+ * {@link RotationTokenResponse} the caller MUST persist). This error fires
+ * only when there is nothing to persist:
+ *   - a rotation that lost the token-keyed gate to a concurrent ordinary refresh of
+ *     the same one-time-use token (fail-SAFE, NO network call, OLD key still bound);
+ *   - the unreachable-by-construction local pre-swap invariant refusing a swap the
+ *     server DID confirm (a new-key-bound token the SDK has no prover for).
+ * The OLD key is STILL bound (never a half-swap). App action: retry the rotation, or
+ * re-authenticate if it keeps not taking.
+ */
+export declare const AUTH_DPOP_ROTATION_DID_NOT_TAKE: (detail?: string) => SdkError;
+/**
+ * A refresh and a key-rotation were attempted concurrently on the SAME
+ * refresh_token. The server one-time-uses + rotates the refresh token on
+ * every success, so the two operations can never both spend the same token value
+ * without tripping server refresh-reuse detection (which revokes ALL session
+ * tokens). The SDK serializes every refresh_token-consuming operation through one
+ * token-keyed choke point: a key rotation already owns this token, so THIS
+ * ordinary refresh was NOT sent (fail-SAFE — no network call, no double-spend).
+ * The session/binding are unchanged. App action: use the rotation's result (it
+ * also delivers fresh tokens), or retry the refresh with the rotated
+ * refresh_token once the rotation settles.
+ */
+export declare const AUTH_REFRESH_SUPERSEDED_BY_ROTATION: (detail?: string) => SdkError;
+export declare const JWKS_FETCH_FAILED: (detail?: string) => SdkError;
+export declare const JWKS_NO_MATCHING_KEY: () => SdkError;
+export declare const JWKS_INVALID_RESPONSE: () => SdkError;
+export declare const WEBHOOK_TIMESTAMP_TOO_OLD: (tolerance: number) => SdkError;
+export declare const WEBHOOK_TIMESTAMP_TOO_NEW: (tolerance: number) => SdkError;
+/** @deprecated Use WEBHOOK_TIMESTAMP_TOO_OLD or WEBHOOK_TIMESTAMP_TOO_NEW */
+export declare const WEBHOOK_TIMESTAMP_EXPIRED: () => SdkError;
+export declare const WEBHOOK_INVALID_SIGNATURE: () => SdkError;
+export declare const WEBHOOK_INVALID_SECRET: () => SdkError;
+export declare const WEBHOOK_MISSING_HEADER: () => SdkError;
+export declare const WEBHOOK_INVALID_BODY: () => SdkError;
+export declare const CONFIG_MISSING_API_KEY: () => SdkError;
+export declare const CONFIG_INVALID_BASE_URL: () => SdkError;
+export declare const CONFIG_MISSING_WEBHOOK_SECRET: () => SdkError;
+export declare const OAUTH_INVALID_GRANT: (detail?: string) => SdkError;
+export declare const OAUTH_INVALID_CLIENT: (detail?: string) => SdkError;
+export declare const OAUTH_INVALID_REQUEST: (detail?: string) => SdkError;
+export declare const OAUTH_UNSUPPORTED_GRANT_TYPE: (detail?: string) => SdkError;
+export declare const OAUTH_NETWORK_ERROR: (detail?: string) => SdkError;
+export declare const OAUTH_MISSING_CLIENT_ID: () => SdkError;
+export declare const OAUTH_MISSING_CLIENT_SECRET: () => SdkError;
+export declare const DEVICE_AUTHORIZATION_PENDING: (detail?: string) => SdkError;
+export declare const DEVICE_AUTHORIZATION_SLOW_DOWN: (detail?: string) => SdkError;
+export declare const DEVICE_AUTHORIZATION_DENIED: (detail?: string) => SdkError;
+export declare const DEVICE_AUTHORIZATION_EXPIRED: (detail?: string) => SdkError;
+export declare const DEVICE_AUTHORIZATION_TIMEOUT: (detail?: string) => SdkError;
+export declare const DEVICE_AUTHORIZATION_RATE_LIMITED: (detail?: string) => SdkError;
+export declare const ANONYMOUS_DISABLED: () => SdkError;
+export declare const ANONYMOUS_RATE_LIMITED: (retryAfterSeconds?: number) => SdkError;
+export declare const ANONYMOUS_MAU_EXHAUSTED: () => SdkError;
+export declare const ANONYMOUS_NETWORK_ERROR: (detail?: string) => SdkError;
+/**
+ * Thrown by the auto-refresh path when a refresh returns 401 AND the prior
+ * access token was marked `is_anonymous: true`. Distinguishes "the tenant
+ * purged your anon user" from generic auth failures so apps can prompt a
+ * fresh `client.anonymous` rather than sending the user to a login screen.
+ *
+ * Carries `suggestedAction: 'call_anonymous'` as a stable hint for DX-level
+ * UX routing (DX thread).
+ */
+export declare class AnonymousSessionExpiredError extends Error {
+    readonly code = "anonymous/session_expired";
+    readonly suggestedAction: "call_anonymous()";
+    readonly suggestion: string;
+    readonly docs_url: string;
+    constructor(message?: string);
+}
+export declare const ACCOUNT_LINKING_NETWORK_ERROR: (detail?: string) => SdkError;
+export declare const ACCOUNT_LINKING_RATE_LIMITED: (retryAfterSeconds?: number) => SdkError;
+export declare const ACCOUNT_LINKING_IDENTITY_NOT_FOUND: () => SdkError;
+/**
+ * Thrown when POST /v1/users/me/link/{provider} returns 403 —
+ * tenant has disabled explicit self-service linking.
+ */
+export declare class AccountLinkingDisabledError extends Error {
+    readonly code = "account_linking/disabled_for_tenant";
+    readonly suggestion: string;
+    readonly docs_url: string;
+    readonly retryAfterSeconds?: number;
+    constructor(message?: string);
+}
+/**
+ * Thrown when a link attempt finds the identity already owned by a different user.
+ * Never include details about the other user — anti-enumeration invariant.
+ */
+export declare class IdentityOwnedByOtherUserError extends Error {
+    readonly code = "account_linking/identity_owned_by_other_user";
+    readonly suggestion: string;
+    readonly docs_url: string;
+    constructor(message?: string);
+}
+/**
+ * Thrown when DELETE /v1/users/me/link/{provider} would remove the user's last
+ * sign-in method. Includes the remaining method kinds to inform UX.
+ */
+export declare class CannotUnlinkLastMethodError extends Error {
+    readonly code = "account_linking/cannot_unlink_last_method";
+    readonly suggestion: string;
+    readonly docs_url: string;
+    readonly remaining_methods: readonly string[];
+    constructor(remainingMethods?: readonly string[], message?: string);
+}
+/**
+ * Thrown when a high-risk operation is attempted within the 1-hour post-link
+ * cooldown window. Semantically distinct from rate-limit
+ * 429s: clients should surface a localized "try again at {time}" hint rather
+ * than "too many requests".
+ *
+ * Exposes both `unlockAt: Date` and `unlockAtIso: string` so consumers can
+ * format the timestamp without re-parsing.
+ */
+export declare class CooldownActiveError extends Error {
+    readonly code = "account_linking/cooldown_active";
+    readonly suggestion: string;
+    readonly docs_url: string;
+    readonly unlockAt: Date;
+    readonly unlockAtIso: string;
+    /**
+     * User-facing discriminator so consumer UX can render a distinct copy path
+     * ("you recently linked an account") vs. the generic rate-limit message.
+     * Populated from the server-side `details.reason` when present.
+     */
+    readonly reason: 'account_recently_linked' | 'unknown';
+    constructor(unlockAtIso: string, reason?: 'account_recently_linked' | 'unknown', message?: string);
+}
+/**
+ * Thrown when POST /v1/users/me/link/{provider} returns 401 with
+ * `code: 'account_linking/mfa_required'`.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc9470 (Step-Up Authentication
+ * Challenge Protocol — conceptual reference; the JSON-body discriminator here
+ * mirrors RFC 9470's Bearer `WWW-Authenticate` step-up signal for cookie-session
+ * APIs.)
+ *
+ * In SDK 0.11.0 the canonical post-401 discriminator is `next_action: 'verify_mfa'`
+ * (mirrors Stripe `payment_intent.next_action` / AWS Cognito `ChallengeName`).
+ * The `mfa_challenge_token` getter is RETAINED for backward compatibility with
+ * 0.10.x consumers but will be removed in 0.12.0 — switch to `next_action`.
+ *
+ * Calling code: guide the user through `POST /v1/auth/step-up/password`, then
+ * retry the link initiate with the resulting `X-Step-Up-Token` header.
+ *
+ * Note: this error is ONLY thrown for users who CAN satisfy step-up (i.e. have
+ * a password set). Passwordless users (magic-link / OTP / passkey-only) get the
+ * complementary {@link MfaStepUpUnavailableError} instead.
+ */
+export declare class MfaStepUpRequiredError extends Error {
+    readonly code = "account_linking/mfa_required";
+    readonly suggestion: string;
+    readonly docs_url: string;
+    /**
+     * Canonical post-401 discriminator. Always equals the literal `'verify_mfa'`
+     * in SDK 0.11.x. Reserved future literals: `'verify_passkey'`,
+     * `'verify_magic_link'`, `'verify_otp'`, `'verify_eudi_wallet'`.
+     */
+    readonly next_action: "verify_mfa";
+    /**
+   * The set of step-up issuance routes the current user can satisfy. The
+   * client SHOULD pick one and call the corresponding `/v1/auth/step-up/*`
+   * route. Order is a HINT, not a guarantee — the server may personalize
+   * ordering by recent success rate or admin policy.
+   *
+   * Open union: backend-additive values (e.g. `ciba_push`, `eudi_wallet`)
+   * MUST NOT trigger a SemVer-major bump for SDK consumers — the
+   * `(string & {})` escape hatch keeps the literal-aware autocomplete
+   * experience while accepting unknown strings at runtime.
+   *
+   * Optional: older API responses (servers older than 2026-04-26)
+   * lack this field; consumers MUST handle `undefined` by falling through to
+   * the legacy `next_action === 'verify_mfa'` flow.
+   */
+    readonly availableMethods?: ReadonlyArray<'password' | 'passkey' | 'magic_link' | 'email_otp' | (string & {})>;
+    private readonly _mfaChallengeToken;
+    /**
+     * @deprecated Will be removed in 0.12.0+ once the dual-emit window expires
+     * (2026-07-24). Switch to `next_action === 'verify_mfa'`. In 0.10.x this field carried the
+     * literal string `'mfa_step_up_required'` (a routing marker, never a nonce);
+     * the value is preserved here so existing consumers continue working through
+     * the dual-emit window.
+     */
+    get mfa_challenge_token(): string;
+    constructor(mfaChallengeToken?: string, message?: string, availableMethods?: ReadonlyArray<'password' | 'passkey' | 'magic_link' | 'email_otp' | (string & {})>);
+}
+/**
+ * Thrown when POST /v1/users/me/link/{provider} returns 401 with
+ * `code: 'account_linking/mfa_step_up_unavailable'` — a passwordless user
+ * (magic-link / email-OTP / passkey-only) has MFA enabled but no step-up
+ * issuance route exists for their authenticator class today (only
+ * `POST /v1/auth/step-up/password` ships in 0.11.x).
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc9470
+ *
+ * The complement of {@link MfaStepUpRequiredError}: together the two classes
+ * partition the 401-with-MFA-enabled space. UX should surface a "complete
+ * account setup (set a password)" affordance — NOT a promise of a passwordless
+ * step-up flow (none exists in 0.11.x).
+ */
+export declare class MfaStepUpUnavailableError extends Error {
+    readonly code = "account_linking/mfa_step_up_unavailable";
+    readonly suggestion: string;
+    readonly docs_url: string;
+    /**
+     * Extensible enum — additional reasons reserved for future passwordless
+     * step-up flows. The recognised reasons include
+     * `'no_step_up_authenticator_available'`, emitted when the server finds
+     * zero satisfiable methods (defensive tripwire).
+     */
+    readonly reason: string;
+    constructor(reason?: string, message?: string);
+}
+/**
+ * Thrown when an OAuth callback rejects a state row that expired or was
+ * already used. The SDK typically surfaces this via the
+ * link-list read (consumers infer the failure from a `?error=link_state_expired`
+ * query string). Direct API consumers get the typed class.
+ */
+export declare class LinkStateExpiredError extends Error {
+    readonly code = "account_linking/link_state_expired_or_missing";
+    readonly suggestion: string;
+    readonly docs_url: string;
+    constructor(message?: string);
+}