@iqauth/sdk 2.6.4 → 2.8.1

package/dist/server/handlers.mjs

@@ -1,15 +1,26 @@
 import {
+  __resetSignoutMarkersForTests,
+  __resetSignoutRegistryWarningForTests,
+  buildUserinfoResponse,
+  createInMemorySignoutRegistry,
   handleCallback,
   handleRefresh,
   handleSignout,
+  handleUserinfo,
   serializeCookie
-} from "../chunk-6TDJJER7.mjs";
-import "../chunk-WQWBJSSS.mjs";
-import "../chunk-6I6RM4MN.mjs";
+} from "../chunk-WSH4SW7F.mjs";
+import "../chunk-HVHNYPDC.mjs";
+import "../chunk-NUO2I65G.mjs";
+import "../chunk-6PJRLRB4.mjs";
 import "../chunk-Y6FXYEAI.mjs";
 export {
+  __resetSignoutMarkersForTests,
+  __resetSignoutRegistryWarningForTests,
+  buildUserinfoResponse,
+  createInMemorySignoutRegistry,
   handleCallback,
   handleRefresh,
   handleSignout,
+  handleUserinfo,
   serializeCookie
 };

package/dist/server.d.mts

@@ -1,10 +1,173 @@
-import { b as IQAuthTokenClientConfig, N as ExpressMiddlewareOptions, Q as IQAuthRequestLike, R as IQAuthResponseLike, V as IQAuthNextFunction } from './types-DZAflmmq.mjs';
-import { I as IQAuthClient } from './client-kYlJFgPv.mjs';
-export { E as ErrorCodes, I as IQAuthError } from './errors-CDdl24MP.mjs';
-export { C as CookieAwareMiddlewareOptions, D as DEFAULT_ACCESS_COOKIE, a as DEFAULT_REFRESH_COOKIE, i as iqAuthMiddleware } from './express-B6_1vBYZ.mjs';
-export { HandlerResponse, IQAuthHelperConfig, SetCookieDirective, handleCallback, handleRefresh, handleSignout, serializeCookie } from './server/handlers.mjs';
-export { P as ProvisioningBridge, a as ProvisioningBridgeOptions, d as ProvisioningContext, b as ProvisioningStorage, c as createProvisioningBridge } from './provisioningBridge-88xjOS2n.mjs';
-import './tokens-DCyzzn8L.mjs';
+import { J as JwtClaims, f as IQAuthTokenClientConfig, X as ExpressMiddlewareOptions, a as IQAuthRequestLike, b as IQAuthResponseLike, c as IQAuthNextFunction } from './types-Bn8O-OEd.mjs';
+import { I as IQAuthClient } from './client-D8L-PaWr.mjs';
+export { E as ErrorCodes, I as IQAuthError } from './errors-Jl1Jtm-6.mjs';
+export { C as CookieAwareMiddlewareOptions, D as DEFAULT_ACCESS_COOKIE, a as DEFAULT_REFRESH_COOKIE, i as iqAuthMiddleware } from './express-DDTA3qV1.mjs';
+export { HandlerResponse, IQAuthHelperConfig, SetCookieDirective, UserinfoResponse, buildUserinfoResponse, handleCallback, handleRefresh, handleSignout, handleUserinfo, serializeCookie } from './server/handlers.mjs';
+export { P as ProvisioningBridge, a as ProvisioningBridgeOptions, d as ProvisioningContext, e as ProvisioningError, b as ProvisioningStorage, c as createProvisioningBridge } from './provisioningBridge-IEycmsgb.mjs';
+import './tokens-B06VtvUi.mjs';
+
+/**
+ * linkLocalUserToIqAuthSub — first-time-migration helper.
+ *
+ * Use case: an app already had local users before adopting IQAuth. After a
+ * user signs in via IQAuth, the JWT's `sub` won't match any local row. The
+ * conventional self-heal is "look up by email, write the sub onto the matching
+ * row". Doing this safely requires:
+ *
+ *   1. An atomic transaction (find + write) so two concurrent first-time
+ *      sign-ins for the same user can't both succeed.
+ *   2. Email matching that's case-insensitive by default (since email
+ *      providers fold case in delivery).
+ *   3. A refusal to link when the candidate row already has a different
+ *      non-null `iqauthSub` (i.e. that local row belongs to someone else).
+ *   4. A refusal to link when more than one local row matches the email
+ *      (duplicate-email collision in the legacy table).
+ *
+ * The helper is ORM-agnostic. Pass any adapter that implements
+ * `LinkAdapter`. A reference Drizzle adapter is exported as
+ * `createDrizzleLinkAdapter`.
+ *
+ * Result codes:
+ *   - 'linked'         — wrote claims.sub onto the matched local row.
+ *   - 'already_linked' — a row was already keyed by claims.sub. No write.
+ *   - 'conflict'       — matched row already has a different non-null sub,
+ *                        OR more than one local row matches the email,
+ *                        OR the email is unverified and adoption is gated
+ *                        (reason 'unverified_email' — see H-4 below).
+ *   - 'not_found'      — no local row matched any of the provided lookupBy
+ *                        keys. Caller should provision a new row separately.
+ *
+ * Security (H-4): writing the IQAuth `sub` onto a pre-existing local row matched
+ * by email is a takeover of that account. It is only performed when the claims
+ * assert a verified email (`claims.email_verified === true`). When the email is
+ * unverified and `allowUnverifiedEmail` is not set, the helper fails closed with
+ * `{ status: 'conflict', reason: 'unverified_email' }` instead of linking.
+ */
+
+type LinkLookupBy = "email";
+type LinkResult = {
+    status: "linked";
+    userId: string;
+} | {
+    status: "already_linked";
+    userId: string;
+} | {
+    status: "conflict";
+    userId?: string;
+    reason: "different_sub" | "duplicate_email" | "unverified_email";
+} | {
+    status: "not_found";
+};
+interface LinkCandidate {
+    id: string;
+    email: string | null;
+    iqauthSub: string | null;
+}
+interface LinkAdapterTx {
+    findByIqAuthSub(sub: string): Promise<LinkCandidate | null>;
+    findByEmail(email: string, opts: {
+        caseInsensitive: boolean;
+    }): Promise<LinkCandidate[]>;
+    /**
+     * Write the IQAuth `sub` onto the matched row. Implementations SHOULD make
+     * this a conditional update (`WHERE id=? AND iqauth_sub IS NULL OR iqauth_sub=?`)
+     * and return `false` if no row was updated — that signals a concurrent
+     * writer claimed the row first and the helper will surface a `conflict`.
+     * For backward-compatibility, returning `void` is treated as "succeeded".
+     */
+    setIqAuthSub(userId: string, sub: string): Promise<void | boolean>;
+}
+interface LinkAdapter {
+    /**
+     * Run `fn` inside a serialized transaction. Implementations MUST guarantee
+     * that candidate rows surfaced by `findByIqAuthSub` / `findByEmail` are
+     * held under a row-level lock (or equivalent isolation) for the duration
+     * of the transaction so the read+write pair is atomic against other
+     * concurrent first-time logins for the same user. Concretely:
+     *   - Postgres / MySQL: implement the read with `SELECT … FOR UPDATE`.
+     *   - SQLite: relies on the file-level write lock — no extra clause needed.
+     *   - Otherwise: run the transaction at SERIALIZABLE isolation.
+     * The reference `createDrizzleLinkAdapter` does this for you.
+     */
+    withTransaction<T>(fn: (tx: LinkAdapterTx) => Promise<T>): Promise<T>;
+}
+interface LinkLocalUserOptions {
+    adapter: LinkAdapter;
+    claims: Pick<JwtClaims, "sub" | "email" | "email_verified">;
+    /**
+     * Lookup keys to try, in order. Currently only `'email'` is supported.
+     * Defaults to `['email']`.
+     */
+    lookupBy?: LinkLookupBy[];
+    /**
+     * Email matching. Default true — most legacy stores fold case in delivery
+     * but preserve the cased original at registration time.
+     */
+    caseInsensitiveEmail?: boolean;
+    /**
+     * Security gate (H-4): by default the email→sub link only proceeds when the
+     * claims assert a verified email (`claims.email_verified === true`). When the
+     * email is unverified and this flag is left `false`, the helper fails closed
+     * with `{ status: 'conflict', reason: 'unverified_email' }` rather than
+     * letting an unverified email take over a pre-existing local account.
+     *
+     * Set `true` ONLY when your issuer is trusted to never emit an unverified
+     * email for linking (or you have a compensating control). Defaults to
+     * `false` (secure).
+     */
+    allowUnverifiedEmail?: boolean;
+}
+declare function linkLocalUserToIqAuthSub(options: LinkLocalUserOptions): Promise<LinkResult>;
+interface DrizzleLikeDb {
+    transaction<T>(fn: (tx: unknown) => Promise<T>): Promise<T>;
+}
+interface DrizzleLinkAdapterDeps {
+    /** Drizzle DB instance with `.transaction()`. */
+    db: DrizzleLikeDb;
+    /** Drizzle table object (e.g. `users`). */
+    table: unknown;
+    /** Column refs on the table — `id`, `email`, and the iqauth sub column. */
+    columns: {
+        id: unknown;
+        email: unknown;
+        iqauthSub: unknown;
+    };
+    /**
+     * Optional override for the schema property keys used by `.set(...)` on
+     * UPDATE. Drizzle's `.set()` is keyed by the table's TypeScript property
+     * names (the keys of your schema object), which need not match the
+     * underlying column name. Defaults to `{ iqauthSub: 'iqauthSub' }`.
+     */
+    columnNames?: {
+        iqauthSub?: string;
+    };
+    /** Drizzle `eq` operator import (`drizzle-orm`). */
+    eq: (a: unknown, b: unknown) => unknown;
+    /**
+     * Drizzle `sql` template tag (`drizzle-orm`). Used for case-insensitive
+     * email comparison via `lower(email) = lower($1)`.
+     */
+    sql: (strings: TemplateStringsArray, ...values: unknown[]) => unknown;
+}
+/**
+ * Reference adapter for Drizzle ORM (Postgres / SQLite / MySQL). The host
+ * app passes its own `db`, `table`, column refs, and `eq` / `sql` imports
+ * so this SDK has no hard dependency on `drizzle-orm`.
+ *
+ * Example:
+ *
+ *   import { eq, sql } from 'drizzle-orm';
+ *   import { db } from './db';
+ *   import { users } from './schema';
+ *   import { createDrizzleLinkAdapter, linkLocalUserToIqAuthSub } from '@iqauth/sdk/server';
+ *
+ *   const adapter = createDrizzleLinkAdapter({
+ *     db, table: users, eq, sql,
+ *     columns: { id: users.id, email: users.email, iqauthSub: users.iqauthSub },
+ *   });
+ *   const result = await linkLocalUserToIqAuthSub({ adapter, claims: req.auth });
+ */
+declare function createDrizzleLinkAdapter(deps: DrizzleLinkAdapterDeps): LinkAdapter;
 
 declare class ServerIQAuthClient extends IQAuthClient {
     constructor(config: IQAuthTokenClientConfig);
@@ -12,4 +175,4 @@ declare class ServerIQAuthClient extends IQAuthClient {
 }
 declare function createServerClient(config: IQAuthTokenClientConfig): ServerIQAuthClient;
 
-export { ExpressMiddlewareOptions, IQAuthClient, IQAuthTokenClientConfig, ServerIQAuthClient, createServerClient };
+export { type DrizzleLinkAdapterDeps, ExpressMiddlewareOptions, IQAuthClient, IQAuthTokenClientConfig, type LinkAdapter, type LinkAdapterTx, type LinkCandidate, type LinkLocalUserOptions, type LinkLookupBy, type LinkResult, ServerIQAuthClient, createDrizzleLinkAdapter, createServerClient, linkLocalUserToIqAuthSub };

package/dist/server.d.ts

@@ -1,10 +1,173 @@
-import { b as IQAuthTokenClientConfig, N as ExpressMiddlewareOptions, Q as IQAuthRequestLike, R as IQAuthResponseLike, V as IQAuthNextFunction } from './types-DZAflmmq.js';
-import { I as IQAuthClient } from './client-BNQe3AgF.js';
-export { E as ErrorCodes, I as IQAuthError } from './errors-CDdl24MP.js';
-export { C as CookieAwareMiddlewareOptions, D as DEFAULT_ACCESS_COOKIE, a as DEFAULT_REFRESH_COOKIE, i as iqAuthMiddleware } from './express-CHpfa7D_.js';
-export { HandlerResponse, IQAuthHelperConfig, SetCookieDirective, handleCallback, handleRefresh, handleSignout, serializeCookie } from './server/handlers.js';
-export { P as ProvisioningBridge, a as ProvisioningBridgeOptions, d as ProvisioningContext, b as ProvisioningStorage, c as createProvisioningBridge } from './provisioningBridge-DnTfzdZK.js';
-import './tokens-aHiGFr_E.js';
+import { J as JwtClaims, f as IQAuthTokenClientConfig, X as ExpressMiddlewareOptions, a as IQAuthRequestLike, b as IQAuthResponseLike, c as IQAuthNextFunction } from './types-Bn8O-OEd.js';
+import { I as IQAuthClient } from './client-DkPL0EPZ.js';
+export { E as ErrorCodes, I as IQAuthError } from './errors-Jl1Jtm-6.js';
+export { C as CookieAwareMiddlewareOptions, D as DEFAULT_ACCESS_COOKIE, a as DEFAULT_REFRESH_COOKIE, i as iqAuthMiddleware } from './express-Budysq4h.js';
+export { HandlerResponse, IQAuthHelperConfig, SetCookieDirective, UserinfoResponse, buildUserinfoResponse, handleCallback, handleRefresh, handleSignout, handleUserinfo, serializeCookie } from './server/handlers.js';
+export { P as ProvisioningBridge, a as ProvisioningBridgeOptions, d as ProvisioningContext, e as ProvisioningError, b as ProvisioningStorage, c as createProvisioningBridge } from './provisioningBridge-BXPMZCLe.js';
+import './tokens-9F6ETrzk.js';
+
+/**
+ * linkLocalUserToIqAuthSub — first-time-migration helper.
+ *
+ * Use case: an app already had local users before adopting IQAuth. After a
+ * user signs in via IQAuth, the JWT's `sub` won't match any local row. The
+ * conventional self-heal is "look up by email, write the sub onto the matching
+ * row". Doing this safely requires:
+ *
+ *   1. An atomic transaction (find + write) so two concurrent first-time
+ *      sign-ins for the same user can't both succeed.
+ *   2. Email matching that's case-insensitive by default (since email
+ *      providers fold case in delivery).
+ *   3. A refusal to link when the candidate row already has a different
+ *      non-null `iqauthSub` (i.e. that local row belongs to someone else).
+ *   4. A refusal to link when more than one local row matches the email
+ *      (duplicate-email collision in the legacy table).
+ *
+ * The helper is ORM-agnostic. Pass any adapter that implements
+ * `LinkAdapter`. A reference Drizzle adapter is exported as
+ * `createDrizzleLinkAdapter`.
+ *
+ * Result codes:
+ *   - 'linked'         — wrote claims.sub onto the matched local row.
+ *   - 'already_linked' — a row was already keyed by claims.sub. No write.
+ *   - 'conflict'       — matched row already has a different non-null sub,
+ *                        OR more than one local row matches the email,
+ *                        OR the email is unverified and adoption is gated
+ *                        (reason 'unverified_email' — see H-4 below).
+ *   - 'not_found'      — no local row matched any of the provided lookupBy
+ *                        keys. Caller should provision a new row separately.
+ *
+ * Security (H-4): writing the IQAuth `sub` onto a pre-existing local row matched
+ * by email is a takeover of that account. It is only performed when the claims
+ * assert a verified email (`claims.email_verified === true`). When the email is
+ * unverified and `allowUnverifiedEmail` is not set, the helper fails closed with
+ * `{ status: 'conflict', reason: 'unverified_email' }` instead of linking.
+ */
+
+type LinkLookupBy = "email";
+type LinkResult = {
+    status: "linked";
+    userId: string;
+} | {
+    status: "already_linked";
+    userId: string;
+} | {
+    status: "conflict";
+    userId?: string;
+    reason: "different_sub" | "duplicate_email" | "unverified_email";
+} | {
+    status: "not_found";
+};
+interface LinkCandidate {
+    id: string;
+    email: string | null;
+    iqauthSub: string | null;
+}
+interface LinkAdapterTx {
+    findByIqAuthSub(sub: string): Promise<LinkCandidate | null>;
+    findByEmail(email: string, opts: {
+        caseInsensitive: boolean;
+    }): Promise<LinkCandidate[]>;
+    /**
+     * Write the IQAuth `sub` onto the matched row. Implementations SHOULD make
+     * this a conditional update (`WHERE id=? AND iqauth_sub IS NULL OR iqauth_sub=?`)
+     * and return `false` if no row was updated — that signals a concurrent
+     * writer claimed the row first and the helper will surface a `conflict`.
+     * For backward-compatibility, returning `void` is treated as "succeeded".
+     */
+    setIqAuthSub(userId: string, sub: string): Promise<void | boolean>;
+}
+interface LinkAdapter {
+    /**
+     * Run `fn` inside a serialized transaction. Implementations MUST guarantee
+     * that candidate rows surfaced by `findByIqAuthSub` / `findByEmail` are
+     * held under a row-level lock (or equivalent isolation) for the duration
+     * of the transaction so the read+write pair is atomic against other
+     * concurrent first-time logins for the same user. Concretely:
+     *   - Postgres / MySQL: implement the read with `SELECT … FOR UPDATE`.
+     *   - SQLite: relies on the file-level write lock — no extra clause needed.
+     *   - Otherwise: run the transaction at SERIALIZABLE isolation.
+     * The reference `createDrizzleLinkAdapter` does this for you.
+     */
+    withTransaction<T>(fn: (tx: LinkAdapterTx) => Promise<T>): Promise<T>;
+}
+interface LinkLocalUserOptions {
+    adapter: LinkAdapter;
+    claims: Pick<JwtClaims, "sub" | "email" | "email_verified">;
+    /**
+     * Lookup keys to try, in order. Currently only `'email'` is supported.
+     * Defaults to `['email']`.
+     */
+    lookupBy?: LinkLookupBy[];
+    /**
+     * Email matching. Default true — most legacy stores fold case in delivery
+     * but preserve the cased original at registration time.
+     */
+    caseInsensitiveEmail?: boolean;
+    /**
+     * Security gate (H-4): by default the email→sub link only proceeds when the
+     * claims assert a verified email (`claims.email_verified === true`). When the
+     * email is unverified and this flag is left `false`, the helper fails closed
+     * with `{ status: 'conflict', reason: 'unverified_email' }` rather than
+     * letting an unverified email take over a pre-existing local account.
+     *
+     * Set `true` ONLY when your issuer is trusted to never emit an unverified
+     * email for linking (or you have a compensating control). Defaults to
+     * `false` (secure).
+     */
+    allowUnverifiedEmail?: boolean;
+}
+declare function linkLocalUserToIqAuthSub(options: LinkLocalUserOptions): Promise<LinkResult>;
+interface DrizzleLikeDb {
+    transaction<T>(fn: (tx: unknown) => Promise<T>): Promise<T>;
+}
+interface DrizzleLinkAdapterDeps {
+    /** Drizzle DB instance with `.transaction()`. */
+    db: DrizzleLikeDb;
+    /** Drizzle table object (e.g. `users`). */
+    table: unknown;
+    /** Column refs on the table — `id`, `email`, and the iqauth sub column. */
+    columns: {
+        id: unknown;
+        email: unknown;
+        iqauthSub: unknown;
+    };
+    /**
+     * Optional override for the schema property keys used by `.set(...)` on
+     * UPDATE. Drizzle's `.set()` is keyed by the table's TypeScript property
+     * names (the keys of your schema object), which need not match the
+     * underlying column name. Defaults to `{ iqauthSub: 'iqauthSub' }`.
+     */
+    columnNames?: {
+        iqauthSub?: string;
+    };
+    /** Drizzle `eq` operator import (`drizzle-orm`). */
+    eq: (a: unknown, b: unknown) => unknown;
+    /**
+     * Drizzle `sql` template tag (`drizzle-orm`). Used for case-insensitive
+     * email comparison via `lower(email) = lower($1)`.
+     */
+    sql: (strings: TemplateStringsArray, ...values: unknown[]) => unknown;
+}
+/**
+ * Reference adapter for Drizzle ORM (Postgres / SQLite / MySQL). The host
+ * app passes its own `db`, `table`, column refs, and `eq` / `sql` imports
+ * so this SDK has no hard dependency on `drizzle-orm`.
+ *
+ * Example:
+ *
+ *   import { eq, sql } from 'drizzle-orm';
+ *   import { db } from './db';
+ *   import { users } from './schema';
+ *   import { createDrizzleLinkAdapter, linkLocalUserToIqAuthSub } from '@iqauth/sdk/server';
+ *
+ *   const adapter = createDrizzleLinkAdapter({
+ *     db, table: users, eq, sql,
+ *     columns: { id: users.id, email: users.email, iqauthSub: users.iqauthSub },
+ *   });
+ *   const result = await linkLocalUserToIqAuthSub({ adapter, claims: req.auth });
+ */
+declare function createDrizzleLinkAdapter(deps: DrizzleLinkAdapterDeps): LinkAdapter;
 
 declare class ServerIQAuthClient extends IQAuthClient {
     constructor(config: IQAuthTokenClientConfig);
@@ -12,4 +175,4 @@ declare class ServerIQAuthClient extends IQAuthClient {
 }
 declare function createServerClient(config: IQAuthTokenClientConfig): ServerIQAuthClient;
 
-export { ExpressMiddlewareOptions, IQAuthClient, IQAuthTokenClientConfig, ServerIQAuthClient, createServerClient };
+export { type DrizzleLinkAdapterDeps, ExpressMiddlewareOptions, IQAuthClient, IQAuthTokenClientConfig, type LinkAdapter, type LinkAdapterTx, type LinkCandidate, type LinkLocalUserOptions, type LinkLookupBy, type LinkResult, ServerIQAuthClient, createDrizzleLinkAdapter, createServerClient, linkLocalUserToIqAuthSub };