authjs-corepass-provider 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,427 @@
+export { default as CorePass, default } from './provider.js';
+import { Adapter } from '@auth/core/adapters';
+import '@auth/core/providers/webauthn';
+
+type CorePassChallengeStore = {
+    put(key: string, value: string, ttlSeconds: number): Promise<void>;
+    get(key: string): Promise<string | null>;
+    delete(key: string): Promise<void>;
+};
+type CorePassPendingRegistration = {
+    token: string;
+    credentialId: string;
+    credentialPublicKey: string;
+    counter: number;
+    credentialDeviceType: string;
+    credentialBackedUp: boolean;
+    transports: string | null;
+    email: string | null;
+    refId: string | null;
+    aaguid: string | null;
+    createdAt: number;
+    expiresAt: number;
+};
+type CorePassUserIdentity = {
+    coreId: string;
+    userId: string;
+    refId: string | null;
+};
+type CorePassProfile = {
+    userId: string;
+    coreId: string;
+    o18y: boolean | null;
+    o21y: boolean | null;
+    kyc: boolean | null;
+    kycDoc: string | null;
+    providedTill: number | null;
+};
+type CorePassStore = {
+    createPendingRegistration(reg: CorePassPendingRegistration): Promise<void>;
+    getPendingRegistrationByCredentialId(credentialId: string): Promise<CorePassPendingRegistration | null>;
+    deletePendingRegistrationByToken(token: string): Promise<void>;
+    getIdentityByCoreId(coreId: string): Promise<CorePassUserIdentity | null>;
+    getIdentityByUserId?(userId: string): Promise<CorePassUserIdentity | null>;
+    upsertIdentity(identity: CorePassUserIdentity): Promise<void>;
+    upsertProfile(profile: CorePassProfile): Promise<void>;
+};
+type CreateCorePassServerOptions = {
+    /**
+     * Auth.js adapter.
+     * Used to create users, link the WebAuthn account, and create authenticators.
+     */
+    adapter: Required<Pick<Adapter, "createUser" | "getUser" | "updateUser" | "linkAccount" | "getUserByAccount" | "getAuthenticator" | "createAuthenticator">>;
+    /**
+     * CorePass extension store (pending registrations + CoreID mapping + profile).
+     */
+    store: CorePassStore;
+    /**
+     * Store for short-lived WebAuthn challenges (KV/Redis/DB/etc).
+     */
+    challengeStore: CorePassChallengeStore;
+    rpID: string;
+    rpName: string;
+    expectedOrigin: string;
+    /**
+     * Enrichment signature must be calculated over this path.
+     * Defaults to `/passkey/data`.
+     */
+    signaturePath?: string;
+    /**
+     * AAGUID allowlist.
+     *
+     * - Default: CorePass AAGUID (`636f7265-7061-7373-6964-656e74696679`)
+     * - Set to `false` to disable AAGUID checks (allow any authenticator).
+     */
+    allowedAaguids?: string | false;
+    /**
+     * WebAuthn algorithm preferences (COSE `alg` ids).
+     *
+     * Default: `[-257, -7, -8]` (RS256, ES256, Ed25519) like the injector.
+     */
+    pubKeyCredAlgs?: number[];
+    /**
+     * If true, finalization fails if the resulting email is missing.
+     * Defaults to false.
+     */
+    emailRequired?: boolean;
+    /**
+     * Policy flags enforced during the enrich (pending) finalization path only.
+     * Not enforced for immediate-finalize.
+     *
+     * Defaults: false
+     */
+    requireO18y?: boolean;
+    requireO21y?: boolean;
+    requireKyc?: boolean;
+    /**
+     * TTL for pending registrations (seconds). Defaults to 600 (10 minutes).
+     */
+    pendingTtlSeconds?: number;
+    /**
+     * Enable `refId` support (capture it in start/finish/enrich and store it).
+     *
+     * Defaults to `false`.
+     */
+    enableRefId?: boolean;
+    /**
+     * Registration webhook URL to POST after successful finalization.
+     *
+     * Payload: `{ coreId, refId? }`
+     */
+    registrationWebhookUrl?: string;
+    /**
+     * Registration webhook secret for HMAC signing. If set, webhook requests will include:
+     * - `X-Webhook-Timestamp` (unix seconds)
+     * - `X-Webhook-Signature` (`sha256=<hex>`)
+     *
+     * Signature input:
+     * `timestamp + "\\n" + requestBody`
+     *
+     * If unset, webhooks are not signed.
+     */
+    registrationWebhookSecret?: string;
+    /**
+     * Number of registration webhook delivery attempts for a single finalization.
+     *
+     * Retries happen when:
+     * - fetch throws (network error), or
+     * - response is non-2xx
+     *
+     * Allowed range: 1-10
+     * Default: 3
+    */
+    registrationWebhookRetries?: number;
+    /**
+     * If enabled, POST a registration webhook after finalization:
+     * - always sends `coreId`
+     * - includes `refId` only if present
+     *
+     * Defaults to `false`.
+    */
+    postRegistrationWebhooks?: boolean;
+    /**
+     * Login webhook URL to POST after successful login.
+     *
+     * Payload: `{ coreId, refId? }`
+     */
+    loginWebhookUrl?: string;
+    /**
+     * Login webhook secret for HMAC signing (same header/signature format as registration).
+     */
+    loginWebhookSecret?: string;
+    /**
+     * Number of login webhook delivery attempts. Allowed range: 1-10. Default: 3.
+     */
+    loginWebhookRetries?: number;
+    /**
+     * If enabled, POST a login webhook after successful login.
+     *
+     * Defaults to `false`.
+     */
+    postLoginWebhooks?: boolean;
+    /**
+     * Logout webhook URL to POST after logout.
+     *
+     * Payload: `{ coreId, refId? }`
+     */
+    logoutWebhookUrl?: string;
+    /**
+     * Logout webhook secret for HMAC signing (same header/signature format as registration).
+     */
+    logoutWebhookSecret?: string;
+    /**
+     * Number of logout webhook delivery attempts. Allowed range: 1-10. Default: 3.
+     */
+    logoutWebhookRetries?: number;
+    /**
+     * If enabled, POST a logout webhook after logout.
+     *
+     * Defaults to `false`.
+     */
+    postLogoutWebhooks?: boolean;
+    /**
+     * If enabled, `finishRegistration` may finalize immediately when `coreId` is provided.
+     * Defaults to false.
+     *
+     * Security note: immediate finalization shifts trust to whatever provides `coreId` to the server.
+     * The default flow requires an Ed448-signed enrichment request to prove CoreID ownership.
+     */
+    allowImmediateFinalize?: boolean;
+    /**
+     * The provider id to use when linking accounts. Defaults to `corepass`.
+     */
+    providerId?: string;
+    /**
+     * Acceptable timestamp window for enrichment requests.
+     */
+    timestampWindowMs?: number;
+    /**
+     * Allowed future skew for enrichment requests.
+     */
+    timestampFutureSkewMs?: number;
+};
+
+declare function createCorePassServer(options: CreateCorePassServerOptions): {
+    startRegistration: (req: Request) => Promise<Response>;
+    finishRegistration: (req: Request) => Promise<Response>;
+    enrichRegistration: (req: Request) => Promise<Response>;
+    postLoginWebhook: (args: {
+        userId: string;
+    }) => Promise<void>;
+    postLogoutWebhook: (args: {
+        userId: string;
+    }) => Promise<void>;
+};
+
+declare function validateCoreIdMainnet(coreId: string): boolean;
+/**
+ * Default CorePass derivation:
+ * - Validate CoreID as mainnet ICAN
+ * - Treat BBAN as hex encoding of the raw 57-byte Ed448 public key (114 hex chars)
+ */
+declare function deriveEd448PublicKeyFromCoreId(coreId: string): Uint8Array | null;
+
+declare function memoryChallengeStore(): CorePassChallengeStore;
+type RedisLike = {
+    set: (key: string, value: string, opts: {
+        ex: number;
+    }) => Promise<unknown>;
+    get: (key: string) => Promise<string | null>;
+    del: (key: string) => Promise<unknown>;
+};
+declare function redisChallengeStore(redis: RedisLike): CorePassChallengeStore;
+type KvLike = {
+    put: (key: string, value: string, opts: {
+        expirationTtl: number;
+    }) => Promise<unknown>;
+    get: (key: string) => Promise<string | null>;
+    delete: (key: string) => Promise<unknown>;
+};
+declare function kvChallengeStore(kv: KvLike): CorePassChallengeStore;
+/**
+ * Vercel KV client shape (based on `@vercel/kv`).
+ * We intentionally don't import `@vercel/kv` to avoid a hard dependency.
+ */
+type VercelKvLike = {
+    set: (key: string, value: string, opts: {
+        ex: number;
+    }) => Promise<unknown>;
+    get: <T = string>(key: string) => Promise<T | null>;
+    del: (key: string) => Promise<unknown>;
+};
+declare function vercelKvChallengeStore(kv: VercelKvLike): CorePassChallengeStore;
+/**
+ * Upstash Redis REST client shape (based on `@upstash/redis`).
+ * We intentionally don't import `@upstash/redis` to avoid a hard dependency.
+ */
+type UpstashRedisLike = {
+    set: (key: string, value: string, opts: {
+        ex: number;
+    }) => Promise<unknown>;
+    get: <T = string>(key: string) => Promise<T | null>;
+    del: (key: string) => Promise<unknown>;
+};
+declare function upstashRedisChallengeStore(redis: UpstashRedisLike): CorePassChallengeStore;
+/**
+ * Durable Object stub shape (Cloudflare).
+ * Your Durable Object must implement these routes:
+ * - POST /challenge/put { key, value, ttlSeconds }
+ * - GET  /challenge/get?key=...
+ * - POST /challenge/delete { key }
+ */
+type DurableObjectStubLike = {
+    fetch: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+};
+declare function durableObjectChallengeStore(stub: DurableObjectStubLike): CorePassChallengeStore;
+/**
+ * DynamoDB-style store (pluggable).
+ * This avoids hard-depending on AWS SDK packages while still making wiring easy.
+ */
+type DynamoLike = {
+    put: (args: {
+        key: string;
+        value: string;
+        expiresAt: number;
+    }) => Promise<unknown>;
+    get: (key: string) => Promise<{
+        value: string;
+        expiresAt: number;
+    } | null>;
+    delete: (key: string) => Promise<unknown>;
+};
+declare function dynamoChallengeStore(dynamo: DynamoLike): CorePassChallengeStore;
+
+type D1Like = {
+    prepare: (sql: string) => {
+        bind: (...params: unknown[]) => {
+            run: () => Promise<unknown>;
+            first: <T = unknown>() => Promise<T | null>;
+            all?: <T = unknown>() => Promise<{
+                results: T[];
+            }>;
+        };
+    };
+};
+declare function d1CorePassStore(db: D1Like): CorePassStore;
+type PgLike = {
+    query: (text: string, params?: unknown[]) => Promise<{
+        rows: any[];
+    }>;
+};
+declare function postgresCorePassStore(pg: PgLike): CorePassStore;
+type SupabaseLike = {
+    from: (table: string) => any;
+};
+declare function supabaseCorePassStore(supabase: SupabaseLike): CorePassStore;
+
+type WithoutStore<T> = Omit<T, "store">;
+type WithoutStoreAndChallengeStore<T> = Omit<T, "store" | "challengeStore">;
+declare function createCorePassServerD1(options: WithoutStore<CreateCorePassServerOptions> & {
+    db: D1Like;
+}): {
+    startRegistration: (req: Request) => Promise<Response>;
+    finishRegistration: (req: Request) => Promise<Response>;
+    enrichRegistration: (req: Request) => Promise<Response>;
+    postLoginWebhook: (args: {
+        userId: string;
+    }) => Promise<void>;
+    postLogoutWebhook: (args: {
+        userId: string;
+    }) => Promise<void>;
+};
+declare function createCorePassServerPostgres(options: WithoutStore<CreateCorePassServerOptions> & {
+    pg: PgLike;
+}): {
+    startRegistration: (req: Request) => Promise<Response>;
+    finishRegistration: (req: Request) => Promise<Response>;
+    enrichRegistration: (req: Request) => Promise<Response>;
+    postLoginWebhook: (args: {
+        userId: string;
+    }) => Promise<void>;
+    postLogoutWebhook: (args: {
+        userId: string;
+    }) => Promise<void>;
+};
+declare function createCorePassServerSupabase(options: WithoutStore<CreateCorePassServerOptions> & {
+    supabase: SupabaseLike;
+}): {
+    startRegistration: (req: Request) => Promise<Response>;
+    finishRegistration: (req: Request) => Promise<Response>;
+    enrichRegistration: (req: Request) => Promise<Response>;
+    postLoginWebhook: (args: {
+        userId: string;
+    }) => Promise<void>;
+    postLogoutWebhook: (args: {
+        userId: string;
+    }) => Promise<void>;
+};
+/**
+ * Popular stack factory: Cloudflare Workers (D1 + KV)
+ */
+declare function createCorePassServerCloudflareD1Kv(options: WithoutStoreAndChallengeStore<CreateCorePassServerOptions> & {
+    db: D1Like;
+    kv: KvLike;
+}): {
+    startRegistration: (req: Request) => Promise<Response>;
+    finishRegistration: (req: Request) => Promise<Response>;
+    enrichRegistration: (req: Request) => Promise<Response>;
+    postLoginWebhook: (args: {
+        userId: string;
+    }) => Promise<void>;
+    postLogoutWebhook: (args: {
+        userId: string;
+    }) => Promise<void>;
+};
+/**
+ * Popular stack factory: Postgres + Redis
+ */
+declare function createCorePassServerPostgresRedis(options: WithoutStoreAndChallengeStore<CreateCorePassServerOptions> & {
+    pg: PgLike;
+    redis: RedisLike;
+}): {
+    startRegistration: (req: Request) => Promise<Response>;
+    finishRegistration: (req: Request) => Promise<Response>;
+    enrichRegistration: (req: Request) => Promise<Response>;
+    postLoginWebhook: (args: {
+        userId: string;
+    }) => Promise<void>;
+    postLogoutWebhook: (args: {
+        userId: string;
+    }) => Promise<void>;
+};
+/**
+ * Popular stack factory: Supabase (Postgres) + Upstash Redis REST
+ */
+declare function createCorePassServerSupabaseUpstash(options: WithoutStoreAndChallengeStore<CreateCorePassServerOptions> & {
+    supabase: SupabaseLike;
+    redis: UpstashRedisLike;
+}): {
+    startRegistration: (req: Request) => Promise<Response>;
+    finishRegistration: (req: Request) => Promise<Response>;
+    enrichRegistration: (req: Request) => Promise<Response>;
+    postLoginWebhook: (args: {
+        userId: string;
+    }) => Promise<void>;
+    postLogoutWebhook: (args: {
+        userId: string;
+    }) => Promise<void>;
+};
+/**
+ * Popular stack factory: Supabase (Postgres) + Vercel KV
+ */
+declare function createCorePassServerSupabaseVercelKv(options: WithoutStoreAndChallengeStore<CreateCorePassServerOptions> & {
+    supabase: SupabaseLike;
+    kv: VercelKvLike;
+}): {
+    startRegistration: (req: Request) => Promise<Response>;
+    finishRegistration: (req: Request) => Promise<Response>;
+    enrichRegistration: (req: Request) => Promise<Response>;
+    postLoginWebhook: (args: {
+        userId: string;
+    }) => Promise<void>;
+    postLogoutWebhook: (args: {
+        userId: string;
+    }) => Promise<void>;
+};
+
+export { type CorePassChallengeStore, type CorePassPendingRegistration, type CorePassProfile, type CorePassStore, type CorePassUserIdentity, type CreateCorePassServerOptions, type D1Like, type DurableObjectStubLike, type DynamoLike, type KvLike, type PgLike, type RedisLike, type SupabaseLike, type UpstashRedisLike, type VercelKvLike, createCorePassServer, createCorePassServerCloudflareD1Kv, createCorePassServerD1, createCorePassServerPostgres, createCorePassServerPostgresRedis, createCorePassServerSupabase, createCorePassServerSupabaseUpstash, createCorePassServerSupabaseVercelKv, d1CorePassStore, deriveEd448PublicKeyFromCoreId, durableObjectChallengeStore, dynamoChallengeStore, kvChallengeStore, memoryChallengeStore, postgresCorePassStore, redisChallengeStore, supabaseCorePassStore, upstashRedisChallengeStore, validateCoreIdMainnet, vercelKvChallengeStore };