@pafi-dev/issuer 0.35.1 → 0.38.0

package/dist/auth-client/index.cjs

@@ -0,0 +1,210 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/auth-client/index.ts
+var auth_client_exports = {};
+__export(auth_client_exports, {
+  PafiAuthClient: () => PafiAuthClient,
+  PafiAuthError: () => PafiAuthError,
+  signClientAssertion: () => signClientAssertion
+});
+module.exports = __toCommonJS(auth_client_exports);
+
+// src/auth-client/pafi-auth-client.ts
+var import_node_crypto2 = require("crypto");
+
+// src/auth-client/sign-client-assertion.ts
+var import_jose = require("jose");
+var import_node_crypto = require("crypto");
+async function signClientAssertion(args) {
+  const alg = args.alg ?? args.privateJwk.alg ?? "ES256";
+  const key = await (0, import_jose.importJWK)(args.privateJwk, alg);
+  const now = Math.floor(Date.now() / 1e3);
+  return new import_jose.SignJWT({}).setProtectedHeader({ alg, typ: "JWT", kid: args.privateJwk.kid }).setIssuer(args.clientId).setSubject(args.clientId).setAudience(`${args.gatewayUrl}/v1/token-exchange`).setIssuedAt(now).setExpirationTime(now + 60).setJti((0, import_node_crypto.randomUUID)()).sign(key);
+}
+
+// src/auth-client/types.ts
+var PafiAuthError = class extends Error {
+  constructor(message, status, code, correlationId) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.correlationId = correlationId;
+    this.name = "PafiAuthError";
+  }
+  status;
+  code;
+  correlationId;
+};
+
+// src/auth-client/pafi-auth-client.ts
+var PafiAuthClient = class {
+  constructor(opts) {
+    this.opts = opts;
+    if (!opts.clientPrivateJwk.kid) {
+      throw new Error(
+        "PafiAuthClient: clientPrivateJwk.kid is required (gateway uses kid to look up the verification key)"
+      );
+    }
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+    this.tokenExchangeAud = `${opts.gatewayUrl}/v1/token-exchange`;
+  }
+  opts;
+  fetchImpl;
+  tokenExchangeAud;
+  // ───────────────────────────────────────────────────────────────
+  // EMAIL OTP — 2-step
+  // ───────────────────────────────────────────────────────────────
+  /**
+   * Step 1: ask the gateway to send the user an OTP. Returns the
+   * `challengeId` to echo back on {@link verifyEmail}.
+   */
+  async startEmail(args) {
+    const res = await this.post(
+      "/v1/auth/email/start",
+      {
+        issuer_id: this.opts.issuerId,
+        email: args.email
+      },
+      args.correlationId
+    );
+    return {
+      challengeId: res.challenge_id,
+      expiresInSec: res.expires_in
+    };
+  }
+  /**
+   * Step 2: submit the OTP the user received. On success returns
+   * {@link AuthSuccess} containing BOTH the long-lived
+   * pafi_session_token (issuer verifies via gateway JWKS) AND the
+   * short-lived pafi_jwt (issuer FE feeds to Privy).
+   */
+  async verifyEmail(args) {
+    const res = await this.post(
+      "/v1/auth/email/verify",
+      {
+        challenge_id: args.challengeId,
+        otp_code: args.otpCode
+      },
+      args.correlationId
+    );
+    return mapAuthSuccess(res);
+  }
+  // ───────────────────────────────────────────────────────────────
+  // GOOGLE — 1-step exchange
+  // ───────────────────────────────────────────────────────────────
+  /**
+   * Hand the gateway an id_token the issuer FE obtained from Google
+   * Identity Services (using PAFI's shared client_id). Gateway verifies
+   * signature + audience + `email_verified` before resolving identity.
+   */
+  async exchangeGoogle(args) {
+    const res = await this.post(
+      "/v1/auth/google/exchange",
+      {
+        issuer_id: this.opts.issuerId,
+        id_token: args.idToken
+      },
+      args.correlationId
+    );
+    return mapAuthSuccess(res);
+  }
+  // ───────────────────────────────────────────────────────────────
+  // KAKAO — 1-step exchange (authorization code)
+  // ───────────────────────────────────────────────────────────────
+  /**
+   * Hand the gateway the authorization code returned by Kakao's
+   * redirect. Gateway exchanges with Kakao (server-to-server using
+   * PAFI's client_secret), verifies id_token, resolves identity.
+   *
+   * `redirectUri` must match the URL the FE used when starting the
+   * Kakao flow. Falls back to the gateway's KAKAO_REDIRECT_URI when
+   * omitted — pass an explicit value for multi-environment FEs.
+   */
+  async exchangeKakao(args) {
+    const res = await this.post(
+      "/v1/auth/kakao/exchange",
+      {
+        issuer_id: this.opts.issuerId,
+        code: args.code,
+        ...args.redirectUri ? { redirect_uri: args.redirectUri } : {}
+      },
+      args.correlationId
+    );
+    return mapAuthSuccess(res);
+  }
+  // ───────────────────────────────────────────────────────────────
+  async post(path, body, correlationId) {
+    const assertion = await signClientAssertion({
+      gatewayUrl: this.opts.gatewayUrl,
+      clientId: this.opts.clientId,
+      privateJwk: this.opts.clientPrivateJwk,
+      alg: this.opts.alg
+    });
+    const finalCorrelationId = correlationId ?? `iss-${(0, import_node_crypto2.randomUUID)()}`;
+    const res = await this.fetchImpl(`${this.opts.gatewayUrl}${path}`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${assertion}`,
+        "Content-Type": "application/json",
+        "X-Correlation-Id": finalCorrelationId
+      },
+      body: JSON.stringify(body)
+    });
+    const text = await res.text();
+    let parsed;
+    try {
+      parsed = text ? JSON.parse(text) : {};
+    } catch {
+      throw new PafiAuthError(
+        `Non-JSON response from gateway (${path}): ${text.slice(0, 120)}`,
+        res.status,
+        "non_json_response",
+        finalCorrelationId
+      );
+    }
+    if (!res.ok) {
+      const err = parsed;
+      throw new PafiAuthError(
+        err.error_description ?? err.error ?? `Gateway returned HTTP ${res.status}`,
+        res.status,
+        err.error ?? "unknown_error",
+        err.correlation_id ?? finalCorrelationId
+      );
+    }
+    return parsed;
+  }
+};
+function mapAuthSuccess(res) {
+  return {
+    pafiSessionToken: res.pafi_session_token,
+    pafiJwt: res.pafi_jwt,
+    canonicalId: res.canonical_id,
+    expiresAt: res.expires_at,
+    isFirstLogin: res.is_first_login,
+    ...res.verified_email ? { verifiedEmail: res.verified_email } : {}
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PafiAuthClient,
+  PafiAuthError,
+  signClientAssertion
+});
+//# sourceMappingURL=index.cjs.map

package/dist/auth-client/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/auth-client/index.ts","../../src/auth-client/pafi-auth-client.ts","../../src/auth-client/sign-client-assertion.ts","../../src/auth-client/types.ts"],"sourcesContent":["export { PafiAuthClient } from \"./pafi-auth-client\";\nexport { PafiAuthError } from \"./types\";\nexport type {\n  AuthSuccess,\n  EmailChallenge,\n  PafiAuthClientOptions,\n} from \"./types\";\nexport { signClientAssertion } from \"./sign-client-assertion\";\n","import { randomUUID } from \"node:crypto\";\nimport { signClientAssertion } from \"./sign-client-assertion\";\nimport {\n  PafiAuthError,\n  type AuthSuccess,\n  type EmailChallenge,\n  type PafiAuthClientOptions,\n} from \"./types\";\n\ninterface GatewayErrorResponse {\n  error?: string;\n  error_description?: string;\n  correlation_id?: string;\n}\n\ninterface GatewayAuthSuccessResponse {\n  pafi_session_token: string;\n  pafi_jwt: string;\n  canonical_id: string;\n  expires_at: number;\n  is_first_login: boolean;\n  verified_email?: string;\n}\n\ninterface GatewayChallengeResponse {\n  challenge_id: string;\n  expires_in: number;\n}\n\n/**\n * Issuer-side client for the PAFI gateway's direct-auth endpoints. Use\n * one instance per issuer backend — the constructor binds gateway URL +\n * issuer id + signing credentials, methods just route to specific\n * endpoints.\n *\n * Each method signs a fresh client_assertion (RFC 7523, 60s TTL) so\n * a leaked one is useless beyond the window + replay-protected by jti.\n *\n * The gateway endpoints invoked here are owned by PAFI — the issuer\n * never sees OTP codes, never holds OAuth client_secrets, never\n * verifies signatures itself. Gateway is the sole authority; this\n * client is purely a transport.\n *\n * Usage in a NestJS issuer backend:\n *\n *   @Injectable()\n *   export class PafiAuthClientProvider {\n *     readonly client: PafiAuthClient;\n *     constructor(config: ConfigService) {\n *       this.client = new PafiAuthClient({\n *         gatewayUrl: config.getOrThrow('PAFI_GATEWAY_URL'),\n *         issuerId:   config.getOrThrow('PAFI_GATEWAY_ISSUER_ID'),\n *         clientId:   config.getOrThrow('PAFI_GATEWAY_CLIENT_ID'),\n *         clientPrivateJwk: JSON.parse(\n *           config.getOrThrow('PAFI_GATEWAY_CLIENT_PRIVATE_JWK_JSON'),\n *         ),\n *       });\n *     }\n *   }\n */\nexport class PafiAuthClient {\n  private readonly fetchImpl: typeof fetch;\n  private readonly tokenExchangeAud: string;\n\n  constructor(private readonly opts: PafiAuthClientOptions) {\n    if (!opts.clientPrivateJwk.kid) {\n      throw new Error(\n        \"PafiAuthClient: clientPrivateJwk.kid is required (gateway uses kid to look up the verification key)\",\n      );\n    }\n    this.fetchImpl = opts.fetchImpl ?? fetch;\n    this.tokenExchangeAud = `${opts.gatewayUrl}/v1/token-exchange`;\n  }\n\n  // ───────────────────────────────────────────────────────────────\n  // EMAIL OTP — 2-step\n  // ───────────────────────────────────────────────────────────────\n\n  /**\n   * Step 1: ask the gateway to send the user an OTP. Returns the\n   * `challengeId` to echo back on {@link verifyEmail}.\n   */\n  async startEmail(args: {\n    email: string;\n    correlationId?: string;\n  }): Promise<EmailChallenge> {\n    const res = await this.post<GatewayChallengeResponse>(\n      \"/v1/auth/email/start\",\n      {\n        issuer_id: this.opts.issuerId,\n        email: args.email,\n      },\n      args.correlationId,\n    );\n    return {\n      challengeId: res.challenge_id,\n      expiresInSec: res.expires_in,\n    };\n  }\n\n  /**\n   * Step 2: submit the OTP the user received. On success returns\n   * {@link AuthSuccess} containing BOTH the long-lived\n   * pafi_session_token (issuer verifies via gateway JWKS) AND the\n   * short-lived pafi_jwt (issuer FE feeds to Privy).\n   */\n  async verifyEmail(args: {\n    challengeId: string;\n    otpCode: string;\n    correlationId?: string;\n  }): Promise<AuthSuccess> {\n    const res = await this.post<GatewayAuthSuccessResponse>(\n      \"/v1/auth/email/verify\",\n      {\n        challenge_id: args.challengeId,\n        otp_code: args.otpCode,\n      },\n      args.correlationId,\n    );\n    return mapAuthSuccess(res);\n  }\n\n  // ───────────────────────────────────────────────────────────────\n  // GOOGLE — 1-step exchange\n  // ───────────────────────────────────────────────────────────────\n\n  /**\n   * Hand the gateway an id_token the issuer FE obtained from Google\n   * Identity Services (using PAFI's shared client_id). Gateway verifies\n   * signature + audience + `email_verified` before resolving identity.\n   */\n  async exchangeGoogle(args: {\n    idToken: string;\n    correlationId?: string;\n  }): Promise<AuthSuccess> {\n    const res = await this.post<GatewayAuthSuccessResponse>(\n      \"/v1/auth/google/exchange\",\n      {\n        issuer_id: this.opts.issuerId,\n        id_token: args.idToken,\n      },\n      args.correlationId,\n    );\n    return mapAuthSuccess(res);\n  }\n\n  // ───────────────────────────────────────────────────────────────\n  // KAKAO — 1-step exchange (authorization code)\n  // ───────────────────────────────────────────────────────────────\n\n  /**\n   * Hand the gateway the authorization code returned by Kakao's\n   * redirect. Gateway exchanges with Kakao (server-to-server using\n   * PAFI's client_secret), verifies id_token, resolves identity.\n   *\n   * `redirectUri` must match the URL the FE used when starting the\n   * Kakao flow. Falls back to the gateway's KAKAO_REDIRECT_URI when\n   * omitted — pass an explicit value for multi-environment FEs.\n   */\n  async exchangeKakao(args: {\n    code: string;\n    redirectUri?: string;\n    correlationId?: string;\n  }): Promise<AuthSuccess> {\n    const res = await this.post<GatewayAuthSuccessResponse>(\n      \"/v1/auth/kakao/exchange\",\n      {\n        issuer_id: this.opts.issuerId,\n        code: args.code,\n        ...(args.redirectUri ? { redirect_uri: args.redirectUri } : {}),\n      },\n      args.correlationId,\n    );\n    return mapAuthSuccess(res);\n  }\n\n  // ───────────────────────────────────────────────────────────────\n\n  private async post<T>(\n    path: string,\n    body: unknown,\n    correlationId: string | undefined,\n  ): Promise<T> {\n    const assertion = await signClientAssertion({\n      gatewayUrl: this.opts.gatewayUrl,\n      clientId: this.opts.clientId,\n      privateJwk: this.opts.clientPrivateJwk,\n      alg: this.opts.alg,\n    });\n    const finalCorrelationId = correlationId ?? `iss-${randomUUID()}`;\n    const res = await this.fetchImpl(`${this.opts.gatewayUrl}${path}`, {\n      method: \"POST\",\n      headers: {\n        Authorization: `Bearer ${assertion}`,\n        \"Content-Type\": \"application/json\",\n        \"X-Correlation-Id\": finalCorrelationId,\n      },\n      body: JSON.stringify(body),\n    });\n    const text = await res.text();\n    let parsed: unknown;\n    try {\n      parsed = text ? JSON.parse(text) : {};\n    } catch {\n      throw new PafiAuthError(\n        `Non-JSON response from gateway (${path}): ${text.slice(0, 120)}`,\n        res.status,\n        \"non_json_response\",\n        finalCorrelationId,\n      );\n    }\n    if (!res.ok) {\n      const err = parsed as GatewayErrorResponse;\n      throw new PafiAuthError(\n        err.error_description ??\n          err.error ??\n          `Gateway returned HTTP ${res.status}`,\n        res.status,\n        err.error ?? \"unknown_error\",\n        err.correlation_id ?? finalCorrelationId,\n      );\n    }\n    return parsed as T;\n  }\n}\n\nfunction mapAuthSuccess(res: GatewayAuthSuccessResponse): AuthSuccess {\n  return {\n    pafiSessionToken: res.pafi_session_token,\n    pafiJwt: res.pafi_jwt,\n    canonicalId: res.canonical_id,\n    expiresAt: res.expires_at,\n    isFirstLogin: res.is_first_login,\n    ...(res.verified_email ? { verifiedEmail: res.verified_email } : {}),\n  };\n}\n","import { importJWK, SignJWT, type JWK } from \"jose\";\nimport { randomUUID } from \"node:crypto\";\n\n/**\n * Mint the RFC 7523 client_assertion JWT the gateway expects in the\n * `Authorization: Bearer …` header of every direct-auth call.\n *\n * Claims:\n *   - iss / sub  = clientId (RFC 7523 §3: same value for client auth)\n *   - aud        = `${gatewayUrl}/v1/token-exchange` (exact endpoint URL)\n *                  — NOTE the gateway also accepts this same audience\n *                  for the direct-auth endpoints because they live on\n *                  the same client-auth boundary. Single audience keeps\n *                  one client_assertion reusable across all gateway\n *                  endpoints for the duration of its short lifetime.\n *   - iat / exp  = 60-second window (replay-protected by jti)\n *   - jti        = random UUID\n *\n * 60-second lifetime is a deliberate trade-off: long enough to absorb\n * clock skew + slow networks, short enough that a stolen assertion is\n * usable only briefly. The gateway's per-jti replay cache means even\n * within that window an assertion is single-use.\n */\nexport async function signClientAssertion(args: {\n  gatewayUrl: string;\n  clientId: string;\n  privateJwk: JWK & { kid: string };\n  alg?: string;\n}): Promise<string> {\n  const alg = args.alg ?? args.privateJwk.alg ?? \"ES256\";\n  const key = await importJWK(args.privateJwk, alg);\n  const now = Math.floor(Date.now() / 1000);\n  return new SignJWT({})\n    .setProtectedHeader({ alg, typ: \"JWT\", kid: args.privateJwk.kid })\n    .setIssuer(args.clientId)\n    .setSubject(args.clientId)\n    .setAudience(`${args.gatewayUrl}/v1/token-exchange`)\n    .setIssuedAt(now)\n    .setExpirationTime(now + 60)\n    .setJti(randomUUID())\n    .sign(key);\n}\n","import type { JWK } from \"jose\";\n\n/**\n * Constructor params for {@link PafiAuthClient}. One instance per\n * issuer backend — wraps the issuer's gateway credentials (client_id +\n * private JWK) plus the static config (gateway URL, audience).\n */\nexport interface PafiAuthClientOptions {\n  /** Base URL of the PAFI gateway (e.g. `https://id-dev.pacificfinance.org`). */\n  gatewayUrl: string;\n  /** Issuer identifier registered with the gateway (e.g. `gg56`). */\n  issuerId: string;\n  /**\n   * Gateway client_id assigned at issuer onboarding. Also acts as the\n   * `iss`/`sub` of the client_assertion JWT (RFC 7523 §3).\n   */\n  clientId: string;\n  /**\n   * Private JWK the issuer uses to sign client_assertion. MUST include\n   * `kid` — gateway looks up the matching public JWK by kid.\n   */\n  clientPrivateJwk: JWK & { kid: string };\n  /**\n   * Optional fetch override — useful for tests / Node env without\n   * global fetch (Node ≥ 18 has it built-in).\n   */\n  fetchImpl?: typeof fetch;\n  /**\n   * Optional algorithm override for the client assertion JWT. Default\n   * `ES256`. Must match what the gateway expects for this client.\n   */\n  alg?: \"ES256\" | \"ES384\" | \"RS256\" | \"RS384\" | \"RS512\" | \"EdDSA\";\n}\n\nexport interface AuthSuccess {\n  pafiSessionToken: string;\n  pafiJwt: string;\n  canonicalId: string;\n  expiresAt: number;\n  isFirstLogin: boolean;\n  verifiedEmail?: string;\n}\n\nexport interface EmailChallenge {\n  challengeId: string;\n  expiresInSec: number;\n}\n\n/**\n * Thrown when the gateway rejects the call. `code` is the gateway's\n * structured `error` field (e.g. `invalid_otp`, `too_many_attempts`,\n * `expired`, `email_not_verified`) — issuers can branch on it to drive\n * UX (e.g. show \"Resend code\" button on `expired`).\n */\nexport class PafiAuthError extends Error {\n  constructor(\n    message: string,\n    public readonly status: number,\n    public readonly code: string,\n    public readonly correlationId?: string,\n  ) {\n    super(message);\n    this.name = \"PafiAuthError\";\n  }\n}\n"],"mappings":"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","names":["import_node_crypto"]}

package/dist/auth-client/index.d.cts

@@ -0,0 +1,171 @@
+import { JWK } from 'jose';
+
+/**
+ * Constructor params for {@link PafiAuthClient}. One instance per
+ * issuer backend — wraps the issuer's gateway credentials (client_id +
+ * private JWK) plus the static config (gateway URL, audience).
+ */
+interface PafiAuthClientOptions {
+    /** Base URL of the PAFI gateway (e.g. `https://id-dev.pacificfinance.org`). */
+    gatewayUrl: string;
+    /** Issuer identifier registered with the gateway (e.g. `gg56`). */
+    issuerId: string;
+    /**
+     * Gateway client_id assigned at issuer onboarding. Also acts as the
+     * `iss`/`sub` of the client_assertion JWT (RFC 7523 §3).
+     */
+    clientId: string;
+    /**
+     * Private JWK the issuer uses to sign client_assertion. MUST include
+     * `kid` — gateway looks up the matching public JWK by kid.
+     */
+    clientPrivateJwk: JWK & {
+        kid: string;
+    };
+    /**
+     * Optional fetch override — useful for tests / Node env without
+     * global fetch (Node ≥ 18 has it built-in).
+     */
+    fetchImpl?: typeof fetch;
+    /**
+     * Optional algorithm override for the client assertion JWT. Default
+     * `ES256`. Must match what the gateway expects for this client.
+     */
+    alg?: "ES256" | "ES384" | "RS256" | "RS384" | "RS512" | "EdDSA";
+}
+interface AuthSuccess {
+    pafiSessionToken: string;
+    pafiJwt: string;
+    canonicalId: string;
+    expiresAt: number;
+    isFirstLogin: boolean;
+    verifiedEmail?: string;
+}
+interface EmailChallenge {
+    challengeId: string;
+    expiresInSec: number;
+}
+/**
+ * Thrown when the gateway rejects the call. `code` is the gateway's
+ * structured `error` field (e.g. `invalid_otp`, `too_many_attempts`,
+ * `expired`, `email_not_verified`) — issuers can branch on it to drive
+ * UX (e.g. show "Resend code" button on `expired`).
+ */
+declare class PafiAuthError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly correlationId?: string | undefined;
+    constructor(message: string, status: number, code: string, correlationId?: string | undefined);
+}
+
+/**
+ * Issuer-side client for the PAFI gateway's direct-auth endpoints. Use
+ * one instance per issuer backend — the constructor binds gateway URL +
+ * issuer id + signing credentials, methods just route to specific
+ * endpoints.
+ *
+ * Each method signs a fresh client_assertion (RFC 7523, 60s TTL) so
+ * a leaked one is useless beyond the window + replay-protected by jti.
+ *
+ * The gateway endpoints invoked here are owned by PAFI — the issuer
+ * never sees OTP codes, never holds OAuth client_secrets, never
+ * verifies signatures itself. Gateway is the sole authority; this
+ * client is purely a transport.
+ *
+ * Usage in a NestJS issuer backend:
+ *
+ *   @Injectable()
+ *   export class PafiAuthClientProvider {
+ *     readonly client: PafiAuthClient;
+ *     constructor(config: ConfigService) {
+ *       this.client = new PafiAuthClient({
+ *         gatewayUrl: config.getOrThrow('PAFI_GATEWAY_URL'),
+ *         issuerId:   config.getOrThrow('PAFI_GATEWAY_ISSUER_ID'),
+ *         clientId:   config.getOrThrow('PAFI_GATEWAY_CLIENT_ID'),
+ *         clientPrivateJwk: JSON.parse(
+ *           config.getOrThrow('PAFI_GATEWAY_CLIENT_PRIVATE_JWK_JSON'),
+ *         ),
+ *       });
+ *     }
+ *   }
+ */
+declare class PafiAuthClient {
+    private readonly opts;
+    private readonly fetchImpl;
+    private readonly tokenExchangeAud;
+    constructor(opts: PafiAuthClientOptions);
+    /**
+     * Step 1: ask the gateway to send the user an OTP. Returns the
+     * `challengeId` to echo back on {@link verifyEmail}.
+     */
+    startEmail(args: {
+        email: string;
+        correlationId?: string;
+    }): Promise<EmailChallenge>;
+    /**
+     * Step 2: submit the OTP the user received. On success returns
+     * {@link AuthSuccess} containing BOTH the long-lived
+     * pafi_session_token (issuer verifies via gateway JWKS) AND the
+     * short-lived pafi_jwt (issuer FE feeds to Privy).
+     */
+    verifyEmail(args: {
+        challengeId: string;
+        otpCode: string;
+        correlationId?: string;
+    }): Promise<AuthSuccess>;
+    /**
+     * Hand the gateway an id_token the issuer FE obtained from Google
+     * Identity Services (using PAFI's shared client_id). Gateway verifies
+     * signature + audience + `email_verified` before resolving identity.
+     */
+    exchangeGoogle(args: {
+        idToken: string;
+        correlationId?: string;
+    }): Promise<AuthSuccess>;
+    /**
+     * Hand the gateway the authorization code returned by Kakao's
+     * redirect. Gateway exchanges with Kakao (server-to-server using
+     * PAFI's client_secret), verifies id_token, resolves identity.
+     *
+     * `redirectUri` must match the URL the FE used when starting the
+     * Kakao flow. Falls back to the gateway's KAKAO_REDIRECT_URI when
+     * omitted — pass an explicit value for multi-environment FEs.
+     */
+    exchangeKakao(args: {
+        code: string;
+        redirectUri?: string;
+        correlationId?: string;
+    }): Promise<AuthSuccess>;
+    private post;
+}
+
+/**
+ * Mint the RFC 7523 client_assertion JWT the gateway expects in the
+ * `Authorization: Bearer …` header of every direct-auth call.
+ *
+ * Claims:
+ *   - iss / sub  = clientId (RFC 7523 §3: same value for client auth)
+ *   - aud        = `${gatewayUrl}/v1/token-exchange` (exact endpoint URL)
+ *                  — NOTE the gateway also accepts this same audience
+ *                  for the direct-auth endpoints because they live on
+ *                  the same client-auth boundary. Single audience keeps
+ *                  one client_assertion reusable across all gateway
+ *                  endpoints for the duration of its short lifetime.
+ *   - iat / exp  = 60-second window (replay-protected by jti)
+ *   - jti        = random UUID
+ *
+ * 60-second lifetime is a deliberate trade-off: long enough to absorb
+ * clock skew + slow networks, short enough that a stolen assertion is
+ * usable only briefly. The gateway's per-jti replay cache means even
+ * within that window an assertion is single-use.
+ */
+declare function signClientAssertion(args: {
+    gatewayUrl: string;
+    clientId: string;
+    privateJwk: JWK & {
+        kid: string;
+    };
+    alg?: string;
+}): Promise<string>;
+
+export { type AuthSuccess, type EmailChallenge, PafiAuthClient, type PafiAuthClientOptions, PafiAuthError, signClientAssertion };

package/dist/auth-client/index.d.ts

@@ -0,0 +1,171 @@
+import { JWK } from 'jose';
+
+/**
+ * Constructor params for {@link PafiAuthClient}. One instance per
+ * issuer backend — wraps the issuer's gateway credentials (client_id +
+ * private JWK) plus the static config (gateway URL, audience).
+ */
+interface PafiAuthClientOptions {
+    /** Base URL of the PAFI gateway (e.g. `https://id-dev.pacificfinance.org`). */
+    gatewayUrl: string;
+    /** Issuer identifier registered with the gateway (e.g. `gg56`). */
+    issuerId: string;
+    /**
+     * Gateway client_id assigned at issuer onboarding. Also acts as the
+     * `iss`/`sub` of the client_assertion JWT (RFC 7523 §3).
+     */
+    clientId: string;
+    /**
+     * Private JWK the issuer uses to sign client_assertion. MUST include
+     * `kid` — gateway looks up the matching public JWK by kid.
+     */
+    clientPrivateJwk: JWK & {
+        kid: string;
+    };
+    /**
+     * Optional fetch override — useful for tests / Node env without
+     * global fetch (Node ≥ 18 has it built-in).
+     */
+    fetchImpl?: typeof fetch;
+    /**
+     * Optional algorithm override for the client assertion JWT. Default
+     * `ES256`. Must match what the gateway expects for this client.
+     */
+    alg?: "ES256" | "ES384" | "RS256" | "RS384" | "RS512" | "EdDSA";
+}
+interface AuthSuccess {
+    pafiSessionToken: string;
+    pafiJwt: string;
+    canonicalId: string;
+    expiresAt: number;
+    isFirstLogin: boolean;
+    verifiedEmail?: string;
+}
+interface EmailChallenge {
+    challengeId: string;
+    expiresInSec: number;
+}
+/**
+ * Thrown when the gateway rejects the call. `code` is the gateway's
+ * structured `error` field (e.g. `invalid_otp`, `too_many_attempts`,
+ * `expired`, `email_not_verified`) — issuers can branch on it to drive
+ * UX (e.g. show "Resend code" button on `expired`).
+ */
+declare class PafiAuthError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly correlationId?: string | undefined;
+    constructor(message: string, status: number, code: string, correlationId?: string | undefined);
+}
+
+/**
+ * Issuer-side client for the PAFI gateway's direct-auth endpoints. Use
+ * one instance per issuer backend — the constructor binds gateway URL +
+ * issuer id + signing credentials, methods just route to specific
+ * endpoints.
+ *
+ * Each method signs a fresh client_assertion (RFC 7523, 60s TTL) so
+ * a leaked one is useless beyond the window + replay-protected by jti.
+ *
+ * The gateway endpoints invoked here are owned by PAFI — the issuer
+ * never sees OTP codes, never holds OAuth client_secrets, never
+ * verifies signatures itself. Gateway is the sole authority; this
+ * client is purely a transport.
+ *
+ * Usage in a NestJS issuer backend:
+ *
+ *   @Injectable()
+ *   export class PafiAuthClientProvider {
+ *     readonly client: PafiAuthClient;
+ *     constructor(config: ConfigService) {
+ *       this.client = new PafiAuthClient({
+ *         gatewayUrl: config.getOrThrow('PAFI_GATEWAY_URL'),
+ *         issuerId:   config.getOrThrow('PAFI_GATEWAY_ISSUER_ID'),
+ *         clientId:   config.getOrThrow('PAFI_GATEWAY_CLIENT_ID'),
+ *         clientPrivateJwk: JSON.parse(
+ *           config.getOrThrow('PAFI_GATEWAY_CLIENT_PRIVATE_JWK_JSON'),
+ *         ),
+ *       });
+ *     }
+ *   }
+ */
+declare class PafiAuthClient {
+    private readonly opts;
+    private readonly fetchImpl;
+    private readonly tokenExchangeAud;
+    constructor(opts: PafiAuthClientOptions);
+    /**
+     * Step 1: ask the gateway to send the user an OTP. Returns the
+     * `challengeId` to echo back on {@link verifyEmail}.
+     */
+    startEmail(args: {
+        email: string;
+        correlationId?: string;
+    }): Promise<EmailChallenge>;
+    /**
+     * Step 2: submit the OTP the user received. On success returns
+     * {@link AuthSuccess} containing BOTH the long-lived
+     * pafi_session_token (issuer verifies via gateway JWKS) AND the
+     * short-lived pafi_jwt (issuer FE feeds to Privy).
+     */
+    verifyEmail(args: {
+        challengeId: string;
+        otpCode: string;
+        correlationId?: string;
+    }): Promise<AuthSuccess>;
+    /**
+     * Hand the gateway an id_token the issuer FE obtained from Google
+     * Identity Services (using PAFI's shared client_id). Gateway verifies
+     * signature + audience + `email_verified` before resolving identity.
+     */
+    exchangeGoogle(args: {
+        idToken: string;
+        correlationId?: string;
+    }): Promise<AuthSuccess>;
+    /**
+     * Hand the gateway the authorization code returned by Kakao's
+     * redirect. Gateway exchanges with Kakao (server-to-server using
+     * PAFI's client_secret), verifies id_token, resolves identity.
+     *
+     * `redirectUri` must match the URL the FE used when starting the
+     * Kakao flow. Falls back to the gateway's KAKAO_REDIRECT_URI when
+     * omitted — pass an explicit value for multi-environment FEs.
+     */
+    exchangeKakao(args: {
+        code: string;
+        redirectUri?: string;
+        correlationId?: string;
+    }): Promise<AuthSuccess>;
+    private post;
+}
+
+/**
+ * Mint the RFC 7523 client_assertion JWT the gateway expects in the
+ * `Authorization: Bearer …` header of every direct-auth call.
+ *
+ * Claims:
+ *   - iss / sub  = clientId (RFC 7523 §3: same value for client auth)
+ *   - aud        = `${gatewayUrl}/v1/token-exchange` (exact endpoint URL)
+ *                  — NOTE the gateway also accepts this same audience
+ *                  for the direct-auth endpoints because they live on
+ *                  the same client-auth boundary. Single audience keeps
+ *                  one client_assertion reusable across all gateway
+ *                  endpoints for the duration of its short lifetime.
+ *   - iat / exp  = 60-second window (replay-protected by jti)
+ *   - jti        = random UUID
+ *
+ * 60-second lifetime is a deliberate trade-off: long enough to absorb
+ * clock skew + slow networks, short enough that a stolen assertion is
+ * usable only briefly. The gateway's per-jti replay cache means even
+ * within that window an assertion is single-use.
+ */
+declare function signClientAssertion(args: {
+    gatewayUrl: string;
+    clientId: string;
+    privateJwk: JWK & {
+        kid: string;
+    };
+    alg?: string;
+}): Promise<string>;
+
+export { type AuthSuccess, type EmailChallenge, PafiAuthClient, type PafiAuthClientOptions, PafiAuthError, signClientAssertion };