@rakomi/node 0.0.0 → 0.1.0

package/dist/flags.js

@@ -0,0 +1,173 @@
+const MAX_CACHE_ENTRIES = 1000;
+const ETAG_REGEX = /^"[^"]*"$/;
+class CircuitBreaker {
+    state = 'closed';
+    failures = 0;
+    threshold = 3;
+    resetMs = 60_000;
+    resetTimer = null;
+    get status() {
+        return this.state;
+    }
+    recordFailure() {
+        if (this.state === 'half-open') {
+            this.state = 'open';
+            this.failures = 0;
+            this.resetTimer = setTimeout(() => {
+                this.state = 'half-open';
+                this.failures = 0;
+                this.resetTimer = null;
+            }, this.resetMs);
+            return;
+        }
+        this.failures++;
+        if (this.failures >= this.threshold && this.state === 'closed') {
+            this.state = 'open';
+            this.resetTimer = setTimeout(() => {
+                this.state = 'half-open';
+                this.failures = 0;
+                this.resetTimer = null;
+            }, this.resetMs);
+        }
+    }
+    recordSuccess() {
+        if (this.state === 'half-open') {
+            this.state = 'closed';
+            this.failures = 0;
+            if (this.resetTimer !== null) {
+                clearTimeout(this.resetTimer);
+                this.resetTimer = null;
+            }
+        }
+    }
+    isOpen() {
+        return this.state === 'open';
+    }
+}
+export class FlagsClient {
+    baseUrl;
+    apiKey;
+    cache = new Map();
+    circuit = new CircuitBreaker();
+    constructor(baseUrl, apiKey) {
+        this.baseUrl = baseUrl;
+        this.apiKey = apiKey;
+    }
+    get circuitStatus() {
+        return this.circuit.status;
+    }
+    buildCacheKey(ctx) {
+        const userId = ctx?.userId ?? '__anon__';
+        const sortedKeys = ctx?.keys ? [...ctx.keys].sort().join(',') : '__all__';
+        return `${this.apiKey}:${userId}:${sortedKeys}`;
+    }
+    isCacheValid(entry) {
+        return Date.now() - entry.fetchedAt < entry.ttl * 1000;
+    }
+    setCacheEntry(key, entry) {
+        if (this.cache.size >= MAX_CACHE_ENTRIES && !this.cache.has(key)) {
+            const oldest = this.cache.keys().next().value;
+            if (oldest !== undefined) {
+                this.cache.delete(oldest);
+            }
+        }
+        this.cache.set(key, entry);
+    }
+    async fetchFlags(ctx, _opts) {
+        const body = {
+            ...(ctx?.userId ? { user_id: ctx.userId } : {}),
+            ...(ctx?.userMetadata ? { user_metadata: ctx.userMetadata } : {}),
+            ...(ctx?.keys?.length ? { keys: ctx.keys } : {}),
+        };
+        const cacheKey = this.buildCacheKey(ctx);
+        const cached = this.cache.get(cacheKey);
+        const etag = cached?.etag ?? null;
+        const headers = {
+            'Authorization': `Bearer ${this.apiKey}`,
+            'Content-Type': 'application/json',
+        };
+        if (etag) {
+            headers['If-None-Match'] = etag;
+        }
+        const response = await fetch(`${this.baseUrl}/v1/flags/evaluate`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+            redirect: 'error',
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (response.status === 304 && cached) {
+            return { flags: cached.flags, etag: cached.etag };
+        }
+        if (!response.ok) {
+            const err = new (class extends Error {
+            })(`HTTP ${response.status}`);
+            throw err;
+        }
+        const data = (await response.json());
+        const newEtag = response.headers.get('etag');
+        const validEtag = newEtag && ETAG_REGEX.test(newEtag) ? newEtag : null;
+        return { flags: data.flags ?? {}, etag: validEtag };
+    }
+    async get(key, ctx, opts) {
+        try {
+            if (this.circuit.isOpen()) {
+                return { ok: false, error: { code: 'CIRCUIT_OPEN', message: 'Circuit breaker open — evaluate endpoint unavailable' } };
+            }
+            const effectiveTtl = Math.max(opts?.ttl ?? 60, 10);
+            const cacheKey = this.buildCacheKey(ctx);
+            const cached = this.cache.get(cacheKey);
+            if (!opts?.skipCache && cached && this.isCacheValid(cached)) {
+                const value = cached.flags[key];
+                return { ok: true, value: value };
+            }
+            const { flags, etag } = await this.fetchFlags(ctx, opts);
+            this.setCacheEntry(cacheKey, { flags, etag, fetchedAt: Date.now(), ttl: effectiveTtl });
+            this.circuit.recordSuccess();
+            const value = flags[key];
+            return { ok: true, value: value };
+        }
+        catch (err) {
+            this.circuit.recordFailure();
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            return { ok: false, error: { code: 'FETCH_FAILED', message } };
+        }
+    }
+    async getAll(ctx, opts) {
+        try {
+            if (this.circuit.isOpen()) {
+                return { ok: false, error: { code: 'CIRCUIT_OPEN', message: 'Circuit breaker open — evaluate endpoint unavailable' } };
+            }
+            const effectiveTtl = Math.max(opts?.ttl ?? 60, 10);
+            const cacheKey = this.buildCacheKey(ctx);
+            const cached = this.cache.get(cacheKey);
+            if (!opts?.skipCache && cached && this.isCacheValid(cached)) {
+                return { ok: true, flags: cached.flags };
+            }
+            const { flags, etag } = await this.fetchFlags(ctx, opts);
+            this.setCacheEntry(cacheKey, { flags, etag, fetchedAt: Date.now(), ttl: effectiveTtl });
+            this.circuit.recordSuccess();
+            return { ok: true, flags };
+        }
+        catch (err) {
+            this.circuit.recordFailure();
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            return { ok: false, error: { code: 'FETCH_FAILED', message } };
+        }
+    }
+    startPolling(ctx, opts) {
+        const effectiveTtl = Math.max(opts?.ttl ?? 60, 10);
+        const intervalId = setInterval(() => {
+            void this.getAll(ctx, { ...opts, ttl: effectiveTtl, skipCache: true });
+        }, effectiveTtl * 1000);
+        return { stop: () => clearInterval(intervalId) };
+    }
+    flush(cacheKey) {
+        if (cacheKey !== undefined) {
+            this.cache.delete(cacheKey);
+        }
+        else {
+            this.cache.clear();
+        }
+    }
+}

package/dist/guards.d.ts

@@ -0,0 +1,16 @@
+import type { MiddlewareRequest, MiddlewareResponse, NextFunction } from './middleware.js';
+import type { SdkEnvironment, TokenPayload } from './types.js';
+type AuthenticatedRequest = MiddlewareRequest & {
+    auth?: TokenPayload;
+};
+/**
+ * Express-compatible middleware guard. For Hono/Fastify, use hasPermission() directly.
+ * Checks JWT claims (offline verification) — NOT a live API call.
+ */
+export declare function requirePermission(permission: string, environmentOverride?: SdkEnvironment): (req: AuthenticatedRequest, res: MiddlewareResponse, next: NextFunction) => void;
+/**
+ * Express-compatible middleware guard. For Hono/Fastify, use hasRole() directly.
+ * Checks JWT claims (offline verification) — NOT a live API call.
+ */
+export declare function requireRole(roleKey: string, environmentOverride?: SdkEnvironment): (req: AuthenticatedRequest, res: MiddlewareResponse, next: NextFunction) => void;
+export {};

package/dist/guards.js

@@ -0,0 +1,104 @@
+import { resolveVerbose } from './middleware.js';
+import { hasPermission, hasRole } from './rbac.js';
+/**
+ * Express-compatible middleware guard. For Hono/Fastify, use hasPermission() directly.
+ * Checks JWT claims (offline verification) — NOT a live API call.
+ */
+export function requirePermission(permission, environmentOverride) {
+    return (req, res, next) => {
+        try {
+            const verbose = resolveVerbose(req, environmentOverride);
+            if (!req.auth) {
+                res.setHeader('WWW-Authenticate', 'Bearer realm="rakomi"');
+                res.status(401).json({
+                    error: {
+                        code: 'auth/not_authenticated',
+                        message: 'Authentication required',
+                        ...(verbose && { suggestion: 'Ensure rakomi.middleware() is applied before requirePermission()' }),
+                        docs_url: 'https://docs.rakomi.dev/sdk/errors#not-authenticated',
+                    },
+                });
+                return;
+            }
+            const payload = {
+                ...req.auth,
+                permissions: req.auth.permissions ?? [],
+                roles: req.auth.roles ?? [],
+            };
+            if (!hasPermission(payload, permission)) {
+                res.setHeader('WWW-Authenticate', verbose
+                    ? `Bearer realm="rakomi", error="insufficient_scope", scope="${permission}"`
+                    : 'Bearer realm="rakomi", error="insufficient_scope"');
+                res.status(403).json({
+                    error: {
+                        code: 'auth/insufficient_permissions',
+                        message: verbose ? `Missing permission: ${permission}` : 'Insufficient permissions',
+                        docs_url: 'https://docs.rakomi.dev/sdk/errors#insufficient-permissions',
+                    },
+                });
+                return;
+            }
+            next();
+        }
+        catch {
+            res.setHeader('WWW-Authenticate', 'Bearer realm="rakomi", error="invalid_token"');
+            res.status(401).json({
+                error: {
+                    code: 'auth/guard_error',
+                    message: 'Authorization check failed',
+                    docs_url: 'https://docs.rakomi.dev/sdk/errors#guard-error',
+                },
+            });
+        }
+    };
+}
+/**
+ * Express-compatible middleware guard. For Hono/Fastify, use hasRole() directly.
+ * Checks JWT claims (offline verification) — NOT a live API call.
+ */
+export function requireRole(roleKey, environmentOverride) {
+    return (req, res, next) => {
+        try {
+            const verbose = resolveVerbose(req, environmentOverride);
+            if (!req.auth) {
+                res.setHeader('WWW-Authenticate', 'Bearer realm="rakomi"');
+                res.status(401).json({
+                    error: {
+                        code: 'auth/not_authenticated',
+                        message: 'Authentication required',
+                        ...(verbose && { suggestion: 'Ensure rakomi.middleware() is applied before requireRole()' }),
+                        docs_url: 'https://docs.rakomi.dev/sdk/errors#not-authenticated',
+                    },
+                });
+                return;
+            }
+            const payload = {
+                ...req.auth,
+                permissions: req.auth.permissions ?? [],
+                roles: req.auth.roles ?? [],
+            };
+            if (!hasRole(payload, roleKey)) {
+                res.setHeader('WWW-Authenticate', 'Bearer realm="rakomi", error="insufficient_scope"');
+                res.status(403).json({
+                    error: {
+                        code: 'auth/insufficient_role',
+                        message: verbose ? `Missing role: ${roleKey}` : 'Insufficient role',
+                        docs_url: 'https://docs.rakomi.dev/sdk/errors#insufficient-role',
+                    },
+                });
+                return;
+            }
+            next();
+        }
+        catch {
+            res.setHeader('WWW-Authenticate', 'Bearer realm="rakomi", error="invalid_token"');
+            res.status(401).json({
+                error: {
+                    code: 'auth/guard_error',
+                    message: 'Authorization check failed',
+                    docs_url: 'https://docs.rakomi.dev/sdk/errors#guard-error',
+                },
+            });
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+export type { AnonymousSigninOptions, AnonymousSigninResult } from './anonymous.js';
+export { AnonymousSessionExpiredError, anonymousSignin, isAnonymousTokenHeuristic, maybeThrowAnonymousExpired, } from './anonymous.js';
+export { RakomiClient } from './client.js';
+export type { CreateDpopProverOptions, DpopProver } from './dpop.js';
+export { createDpopProver } from './dpop.js';
+export type { CreateDpopSessionOptions, DpopDowngradeInfo } from './dpop-session.js';
+export { createDpopSession, DpopSession } from './dpop-session.js';
+export type { AwaitDeviceTokensOptions, DeviceAuthorizationIssued, PollForDeviceTokenOptions, RunDeviceFlowOptions, StartDeviceAuthorizationOptions, } from './device.js';
+export { awaitDeviceTokens, pollForDeviceToken, run as runDeviceFlow, startDeviceAuthorization, } from './device.js';
+export { detectEnvironment } from './env-detect.js';
+export type { ErrorCode } from './errors.js';
+export { ACCOUNT_LINKING_IDENTITY_NOT_FOUND, ACCOUNT_LINKING_NETWORK_ERROR, ACCOUNT_LINKING_RATE_LIMITED, AccountLinkingDisabledError, ANONYMOUS_DISABLED, ANONYMOUS_MAU_EXHAUSTED, ANONYMOUS_NETWORK_ERROR, ANONYMOUS_RATE_LIMITED, AUTH_DPOP_PROVER_UNAVAILABLE, AUTH_DPOP_ROTATION_DID_NOT_TAKE, AUTH_DPOP_ROTATION_NOOP, AUTH_INVALID_DPOP_PROOF, AUTH_INVALID_REFRESH_TOKEN, AUTH_REFRESH_SUPERSEDED_BY_ROTATION, CannotUnlinkLastMethodError, CONFIG_INVALID_BASE_URL, CONFIG_MISSING_API_KEY, CONFIG_MISSING_WEBHOOK_SECRET, CooldownActiveError, ERROR_CODES, IdentityOwnedByOtherUserError, JWKS_FETCH_FAILED, JWKS_INVALID_RESPONSE, JWKS_NO_MATCHING_KEY, LinkStateExpiredError, MfaStepUpRequiredError, MfaStepUpUnavailableError, OAUTH_INVALID_CLIENT, OAUTH_INVALID_GRANT, OAUTH_INVALID_REQUEST, OAUTH_MISSING_CLIENT_ID, OAUTH_MISSING_CLIENT_SECRET, OAUTH_NETWORK_ERROR, OAUTH_UNSUPPORTED_GRANT_TYPE, RakomiError, TOKEN_EXPIRED, TOKEN_INVALID_ALGORITHM, TOKEN_INVALID_AUDIENCE, TOKEN_INVALID_ISSUER, TOKEN_INVALID_SIGNATURE, TOKEN_MALFORMED, TOKEN_MISSING_CLAIMS, TOKEN_NOT_YET_VALID, TOKEN_REVOKED, WEBHOOK_INVALID_BODY, WEBHOOK_INVALID_SECRET, WEBHOOK_INVALID_SIGNATURE, WEBHOOK_MISSING_HEADER, WEBHOOK_TIMESTAMP_EXPIRED, WEBHOOK_TIMESTAMP_TOO_NEW, WEBHOOK_TIMESTAMP_TOO_OLD, } from './errors.js';
+export type { EidasLevel } from './eudi.js';
+export { eidasLevel, isEudiVerified } from './eudi.js';
+export type { CircuitState, FlagResult, FlagsAllResult, FlagsOptions, UserContext } from './flags.js';
+export { FlagsClient } from './flags.js';
+export { requirePermission, requireRole } from './guards.js';
+export type { AccountLinkingProvider, LinkCallOptions, LinkedMethod, LinkedMethodsResponse, LinkedVia, LinkInitiateOptions, LinkInitiateResponse, UnlinkResponse, } from './link.js';
+export { LinkClient } from './link.js';
+export type { AgentsCallOptions, AgentsClientContext, ListUserAgentsResponse, RevokeUserAgentOptions, RevokeUserAgentResponse, UserAgentResponse, } from './agents.js';
+export { AgentNotFoundError, AgentsClient, AgentsNetworkError, AgentsRateLimitedError, AgentsUnauthorizedError, } from './agents.js';
+export { buildAuthorizeUrl, exchangeCode, generatePKCE, generateState, refreshToken, rotateRefreshKey, } from './oauth.js';
+export { hasPermission, hasRole } from './rbac.js';
+export type { TokenExchangeOptions, TokenExchangeResponse, } from './token-exchange.js';
+export { exchangeTokenOrThrow, exchangeTokenViaApi, TokenExchangeError, TokenExchangeInvalidClientError, TokenExchangeInvalidGrantError, TokenExchangeInvalidScopeError, TokenExchangeRateLimitedError, TokenExchangeUnauthorizedClientError, } from './token-exchange.js';
+export type { CibaAwaitDecisionOptions, CibaInitiateOptions, CibaInitiateResponse, CibaPollResponse, } from './ciba.js';
+export { awaitCibaDecision, CibaAccessDeniedError, CibaAuthorizationPendingError, CibaError, CibaExpiredTokenError, CibaInvalidClientError, CibaInvalidRequestError, CibaInvalidScopeError, CibaReplayError, CibaSlowDownError, CibaUnauthorizedClientError, CibaUnknownUserError, CibaUserCapReachedError, initiateCiba, pollCiba, } from './ciba.js';
+export type { AuthorizeUrlOptions, MiddlewareOptions, OAuthExchangeOptions, OAuthRefreshOptions, OAuthRotateOptions, OAuthTokenResponse, OrgMembership, PkceChallenge, PublisherEventType, PublisherWebhookEvent, PublisherWebhookEventType, PublisherWebhookVerifyData, RakomiConfig, RotationTokenResponse, SdkEnvironment, SdkError, TokenPayload, VerifyResult, WebhookEvent, WebhookHeaders, WebhookVerifyData, } from './types.js';
+export { verifyPublisherWebhook } from './verify-publisher-webhook.js';
+export { verifyWebhook } from './verify-webhook.js';

package/dist/index.js

@@ -0,0 +1,18 @@
+export { AnonymousSessionExpiredError, anonymousSignin, isAnonymousTokenHeuristic, maybeThrowAnonymousExpired, } from './anonymous.js';
+export { RakomiClient } from './client.js';
+export { createDpopProver } from './dpop.js';
+export { createDpopSession, DpopSession } from './dpop-session.js';
+export { awaitDeviceTokens, pollForDeviceToken, run as runDeviceFlow, startDeviceAuthorization, } from './device.js';
+export { detectEnvironment } from './env-detect.js';
+export { ACCOUNT_LINKING_IDENTITY_NOT_FOUND, ACCOUNT_LINKING_NETWORK_ERROR, ACCOUNT_LINKING_RATE_LIMITED, AccountLinkingDisabledError, ANONYMOUS_DISABLED, ANONYMOUS_MAU_EXHAUSTED, ANONYMOUS_NETWORK_ERROR, ANONYMOUS_RATE_LIMITED, AUTH_DPOP_PROVER_UNAVAILABLE, AUTH_DPOP_ROTATION_DID_NOT_TAKE, AUTH_DPOP_ROTATION_NOOP, AUTH_INVALID_DPOP_PROOF, AUTH_INVALID_REFRESH_TOKEN, AUTH_REFRESH_SUPERSEDED_BY_ROTATION, CannotUnlinkLastMethodError, CONFIG_INVALID_BASE_URL, CONFIG_MISSING_API_KEY, CONFIG_MISSING_WEBHOOK_SECRET, CooldownActiveError, ERROR_CODES, IdentityOwnedByOtherUserError, JWKS_FETCH_FAILED, JWKS_INVALID_RESPONSE, JWKS_NO_MATCHING_KEY, LinkStateExpiredError, MfaStepUpRequiredError, MfaStepUpUnavailableError, OAUTH_INVALID_CLIENT, OAUTH_INVALID_GRANT, OAUTH_INVALID_REQUEST, OAUTH_MISSING_CLIENT_ID, OAUTH_MISSING_CLIENT_SECRET, OAUTH_NETWORK_ERROR, OAUTH_UNSUPPORTED_GRANT_TYPE, RakomiError, TOKEN_EXPIRED, TOKEN_INVALID_ALGORITHM, TOKEN_INVALID_AUDIENCE, TOKEN_INVALID_ISSUER, TOKEN_INVALID_SIGNATURE, TOKEN_MALFORMED, TOKEN_MISSING_CLAIMS, TOKEN_NOT_YET_VALID, TOKEN_REVOKED, WEBHOOK_INVALID_BODY, WEBHOOK_INVALID_SECRET, WEBHOOK_INVALID_SIGNATURE, WEBHOOK_MISSING_HEADER, WEBHOOK_TIMESTAMP_EXPIRED, WEBHOOK_TIMESTAMP_TOO_NEW, WEBHOOK_TIMESTAMP_TOO_OLD, } from './errors.js';
+export { eidasLevel, isEudiVerified } from './eudi.js';
+export { FlagsClient } from './flags.js';
+export { requirePermission, requireRole } from './guards.js';
+export { LinkClient } from './link.js';
+export { AgentNotFoundError, AgentsClient, AgentsNetworkError, AgentsRateLimitedError, AgentsUnauthorizedError, } from './agents.js';
+export { buildAuthorizeUrl, exchangeCode, generatePKCE, generateState, refreshToken, rotateRefreshKey, } from './oauth.js';
+export { hasPermission, hasRole } from './rbac.js';
+export { exchangeTokenOrThrow, exchangeTokenViaApi, TokenExchangeError, TokenExchangeInvalidClientError, TokenExchangeInvalidGrantError, TokenExchangeInvalidScopeError, TokenExchangeRateLimitedError, TokenExchangeUnauthorizedClientError, } from './token-exchange.js';
+export { awaitCibaDecision, CibaAccessDeniedError, CibaAuthorizationPendingError, CibaError, CibaExpiredTokenError, CibaInvalidClientError, CibaInvalidRequestError, CibaInvalidScopeError, CibaReplayError, CibaSlowDownError, CibaUnauthorizedClientError, CibaUnknownUserError, CibaUserCapReachedError, initiateCiba, pollCiba, } from './ciba.js';
+export { verifyPublisherWebhook } from './verify-publisher-webhook.js';
+export { verifyWebhook } from './verify-webhook.js';

package/dist/internal/canonical-url.d.ts

@@ -0,0 +1,13 @@
+export type CanonicalUrlVersion = 'rfc9449-2023';
+export interface CanonicalizeUrlOptions {
+    version?: CanonicalUrlVersion;
+    /** Trusted-proxy hint: scheme override from `X-Forwarded-Proto`. */
+    forwardedProto?: string | null | undefined;
+    /** Trusted-proxy hint: host override from `X-Forwarded-Host`. */
+    forwardedHost?: string | null | undefined;
+}
+export declare class CanonicalizeUrlError extends Error {
+    readonly code: 'invalid_url' | 'unsupported_version';
+    constructor(code: 'invalid_url' | 'unsupported_version', message: string);
+}
+export declare function canonicalizeUrl(input: string, options?: CanonicalizeUrlOptions): string;

package/dist/internal/canonical-url.js

@@ -0,0 +1,52 @@
+export class CanonicalizeUrlError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'CanonicalizeUrlError';
+    }
+}
+function collapsePath(path) {
+    const collapsed = path.replace(/\/{2,}/g, '/');
+    if (collapsed.length > 1 && collapsed.endsWith('/')) {
+        return collapsed.slice(0, -1);
+    }
+    return collapsed;
+}
+function lowercasePercentHex(s) {
+    return s.replace(/%([0-9A-Fa-f]{2})/g, (_m, h) => `%${h.toLowerCase()}`);
+}
+export function canonicalizeUrl(input, options = {}) {
+    const version = options.version ?? 'rfc9449-2023';
+    if (version !== 'rfc9449-2023') {
+        throw new CanonicalizeUrlError('unsupported_version', `unsupported canonicalize-url version: ${version}`);
+    }
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        throw new CanonicalizeUrlError('invalid_url', 'invalid url');
+    }
+    if (options.forwardedProto) {
+        const proto = options.forwardedProto.toLowerCase().trim();
+        if (proto === 'http' || proto === 'https') {
+            url.protocol = `${proto}:`;
+        }
+    }
+    if (options.forwardedHost) {
+        const first = options.forwardedHost.split(',')[0].trim();
+        if (first.length > 0) {
+            url.host = first;
+        }
+    }
+    if ((url.protocol === 'https:' && url.port === '443') ||
+        (url.protocol === 'http:' && url.port === '80')) {
+        url.port = '';
+    }
+    url.search = '';
+    url.hash = '';
+    const normalizedPath = collapsePath(lowercasePercentHex(url.pathname));
+    const host = url.host;
+    return `${url.protocol}//${host}${normalizedPath}`;
+}

package/dist/internal/shared-constants.d.ts

@@ -0,0 +1,3 @@
+export declare const TOKEN_EXCHANGE_GRANT_TYPE: "urn:ietf:params:oauth:grant-type:token-exchange";
+export declare const TOKEN_EXCHANGE_ACCESS_TOKEN_TYPE: "urn:ietf:params:oauth:token-type:access_token";
+export declare const CIBA_GRANT_TYPE: "urn:openid:params:grant-type:ciba";

package/dist/internal/shared-constants.js

@@ -0,0 +1,3 @@
+export const TOKEN_EXCHANGE_GRANT_TYPE = 'urn:ietf:params:oauth:grant-type:token-exchange';
+export const TOKEN_EXCHANGE_ACCESS_TOKEN_TYPE = 'urn:ietf:params:oauth:token-type:access_token';
+export const CIBA_GRANT_TYPE = 'urn:openid:params:grant-type:ciba';

package/dist/jwks-cache.d.ts

@@ -0,0 +1,31 @@
+import type { CryptoKey as JoseCryptoKey } from 'jose';
+import type { SdkError } from './types.js';
+type CacheResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: SdkError;
+};
+export declare class JwksCache {
+    private cache;
+    private refreshPromise;
+    private readonly jwksUrl;
+    private readonly baseUrl;
+    constructor(baseUrl: string);
+    /**
+     * Get the base URL of this Rakomi deployment.
+     * Used to derive the expected JWT audience claim value.
+     */
+    getBaseUrl(): string;
+    /**
+     * Get the revocation epoch from the last JWKS response.
+     * Returns null if no revocation has occurred or JWKS hasn't been fetched yet.
+     */
+    getRevocationEpoch(): number | null;
+    getKey(kid: string): Promise<CacheResult<JoseCryptoKey>>;
+    refresh(): Promise<CacheResult<void>>;
+    private isExpired;
+    private doRefresh;
+}
+export {};

package/dist/jwks-cache.js

@@ -0,0 +1,135 @@
+import { importJWK } from 'jose';
+import { JWKS_FETCH_FAILED, JWKS_INVALID_RESPONSE, JWKS_NO_MATCHING_KEY } from './errors.js';
+const DEFAULT_MAX_AGE = 3600;
+export class JwksCache {
+    cache = null;
+    refreshPromise = null;
+    jwksUrl;
+    baseUrl;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl.replace(/\/+$/, '');
+        this.jwksUrl = `${this.baseUrl}/.well-known/jwks.json`;
+    }
+    /**
+     * Get the base URL of this Rakomi deployment.
+     * Used to derive the expected JWT audience claim value.
+     */
+    getBaseUrl() {
+        return this.baseUrl;
+    }
+    /**
+     * Get the revocation epoch from the last JWKS response.
+     * Returns null if no revocation has occurred or JWKS hasn't been fetched yet.
+     */
+    getRevocationEpoch() {
+        return this.cache?.revocationEpoch ?? null;
+    }
+    async getKey(kid) {
+        if (this.cache && !this.isExpired()) {
+            const entry = this.cache.keys.find((k) => k.kid === kid);
+            if (entry) {
+                return { ok: true, data: entry.key };
+            }
+        }
+        const refreshResult = await this.refresh();
+        if (!refreshResult.ok) {
+            return refreshResult;
+        }
+        const entry = this.cache?.keys.find((k) => k.kid === kid);
+        if (!entry) {
+            return { ok: false, error: JWKS_NO_MATCHING_KEY() };
+        }
+        return { ok: true, data: entry.key };
+    }
+    async refresh() {
+        if (this.refreshPromise) {
+            return this.refreshPromise;
+        }
+        this.refreshPromise = this.doRefresh();
+        try {
+            return await this.refreshPromise;
+        }
+        finally {
+            this.refreshPromise = null;
+        }
+    }
+    isExpired() {
+        if (!this.cache)
+            return true;
+        const elapsed = (Date.now() - this.cache.fetchedAt) / 1000;
+        return elapsed >= this.cache.maxAge;
+    }
+    async doRefresh() {
+        let response;
+        try {
+            response = await fetch(this.jwksUrl, {
+                redirect: 'error',
+                signal: AbortSignal.timeout(5000),
+            });
+        }
+        catch (err) {
+            if (this.cache) {
+                return { ok: true, data: undefined };
+            }
+            const detail = err instanceof Error
+                ? (err.name === 'TimeoutError' ? 'Request timeout' : err.message)
+                : 'Network error';
+            return { ok: false, error: JWKS_FETCH_FAILED(detail) };
+        }
+        if (!response.ok) {
+            if (this.cache) {
+                return { ok: true, data: undefined };
+            }
+            return { ok: false, error: JWKS_FETCH_FAILED(`HTTP ${response.status}`) };
+        }
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch {
+            return { ok: false, error: JWKS_INVALID_RESPONSE() };
+        }
+        if (!body ||
+            typeof body !== 'object' ||
+            !('keys' in body) ||
+            !Array.isArray(body.keys)) {
+            return { ok: false, error: JWKS_INVALID_RESPONSE() };
+        }
+        const bodyObj = body;
+        const jwks = bodyObj.keys;
+        let revocationEpoch = null;
+        if (typeof bodyObj.revocation_epoch === 'number' && Number.isInteger(bodyObj.revocation_epoch) && bodyObj.revocation_epoch > 0) {
+            revocationEpoch = bodyObj.revocation_epoch;
+        }
+        const entries = [];
+        for (const jwk of jwks) {
+            if (jwk.alg === 'RS256' && jwk.use === 'sig' && typeof jwk.kid === 'string') {
+                try {
+                    const key = await importJWK(jwk, 'RS256');
+                    if (!(key instanceof Uint8Array)) {
+                        entries.push({ kid: jwk.kid, key });
+                    }
+                }
+                catch {
+                }
+            }
+        }
+        const maxAge = parseCacheControlMaxAge(response.headers.get('Cache-Control'));
+        this.cache = {
+            keys: entries,
+            revocationEpoch,
+            fetchedAt: Date.now(),
+            maxAge,
+        };
+        return { ok: true, data: undefined };
+    }
+}
+function parseCacheControlMaxAge(header) {
+    if (!header)
+        return DEFAULT_MAX_AGE;
+    const match = header.match(/max-age=(\d+)/);
+    if (!match?.[1])
+        return DEFAULT_MAX_AGE;
+    const value = parseInt(match[1], 10);
+    return Number.isFinite(value) && value > 0 ? value : DEFAULT_MAX_AGE;
+}

package/dist/link.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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 type { VerifyResult } from './types.js';
+export type AccountLinkingProvider = 'google' | 'github' | 'microsoft' | 'apple' | 'discord' | 'facebook' | 'slack' | 'twitter' | 'gitlab' | 'linkedin';
+export type LinkedVia = 'signup' | 'explicit_link' | 'automatic_link';
+export type LinkedMethod = {
+    kind: 'password';
+    active: boolean;
+} | {
+    kind: 'social';
+    provider: AccountLinkingProvider;
+    provider_email_hash: string;
+    linked_at: string;
+    linked_via: LinkedVia;
+} | {
+    kind: 'passkey';
+    count: number;
+};
+export interface LinkedMethodsResponse {
+    methods: LinkedMethod[];
+    cooldown_until: string | null;
+}
+export interface LinkInitiateResponse {
+    authorization_url: string;
+}
+export interface UnlinkResponse {
+    unlinked: boolean;
+    provider: AccountLinkingProvider;
+    warnings: Array<'only_password_remains'>;
+}
+export interface LinkCallOptions {
+    /** End-user JWT (Bearer). REQUIRED — these endpoints do NOT accept API keys. */
+    userToken: string;
+}
+export interface LinkInitiateOptions extends LinkCallOptions {
+    redirectUri: string;
+    /** Optional MFA step-up token (forward path — server-side gate lives in). */
+    mfaVerificationToken?: string;
+}
+export interface LinkClientContext {
+    baseUrl: string;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * 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 declare class LinkClient {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(ctx: LinkClientContext);
+    /** GET /v1/users/me/link — list linked methods for the authenticated user. */
+    list(options: LinkCallOptions): Promise<VerifyResult<LinkedMethodsResponse>>;
+    /** POST /v1/users/me/link/{provider} — initiate OAuth link flow. */
+    initiate(provider: AccountLinkingProvider, options: LinkInitiateOptions): Promise<VerifyResult<LinkInitiateResponse>>;
+    /** DELETE /v1/users/me/link/{provider} — unlink a social identity. */
+    remove(provider: AccountLinkingProvider, options: LinkCallOptions): Promise<VerifyResult<UnlinkResponse>>;
+    private mapError;
+}