@pafi-dev/issuer 0.36.0 → 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 };

package/dist/auth-client/index.js

@@ -0,0 +1,183 @@
+import "../chunk-BRKEJJFQ.js";
+
+// src/auth-client/pafi-auth-client.ts
+import { randomUUID as randomUUID2 } from "crypto";
+
+// src/auth-client/sign-client-assertion.ts
+import { importJWK, SignJWT } from "jose";
+import { randomUUID } from "crypto";
+async function signClientAssertion(args) {
+  const alg = args.alg ?? args.privateJwk.alg ?? "ES256";
+  const key = await importJWK(args.privateJwk, alg);
+  const now = Math.floor(Date.now() / 1e3);
+  return new 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(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-${randomUUID2()}`;
+    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 } : {}
+  };
+}
+export {
+  PafiAuthClient,
+  PafiAuthError,
+  signClientAssertion
+};
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/auth-client/pafi-auth-client.ts","../../src/auth-client/sign-client-assertion.ts","../../src/auth-client/types.ts"],"sourcesContent":["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":["randomUUID","randomUUID"]}

package/dist/index.cjs

@@ -5421,7 +5421,7 @@ var MemoryRedemptionHistoryStore = class {
 };
 
 // src/index.ts
-var PAFI_ISSUER_SDK_VERSION = true ? "0.35.1" : "dev";
+var PAFI_ISSUER_SDK_VERSION = true ? "0.38.0" : "dev";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AdapterMisconfiguredError,

package/dist/index.js

@@ -5237,7 +5237,7 @@ var MemoryRedemptionHistoryStore = class {
 };
 
 // src/index.ts
-var PAFI_ISSUER_SDK_VERSION = true ? "0.35.1" : "dev";
+var PAFI_ISSUER_SDK_VERSION = true ? "0.38.0" : "dev";
 export {
   AdapterMisconfiguredError,
   AuthError,

package/dist/nestjs/index.d.cts

@@ -1,6 +1,6 @@
 import { ExceptionFilter, ArgumentsHost, DynamicModule, FactoryProvider } from '@nestjs/common';
 import { PafiErrorEnvelope } from '../http/index.cjs';
-import { a as IssuerPublicJwk } from '../types-CxVXRHLy.cjs';
+import { b as IssuerPublicJwk } from '../types-DPqLTJk-.cjs';
 import '@pafi-dev/core';
 import 'jose';
 

package/dist/nestjs/index.d.ts

@@ -1,6 +1,6 @@
 import { ExceptionFilter, ArgumentsHost, DynamicModule, FactoryProvider } from '@nestjs/common';
 import { PafiErrorEnvelope } from '../http/index.js';
-import { a as IssuerPublicJwk } from '../types-CxVXRHLy.js';
+import { b as IssuerPublicJwk } from '../types-DPqLTJk-.js';
 import '@pafi-dev/core';
 import 'jose';
 

package/dist/{types-CxVXRHLy.d.cts → types-DPqLTJk-.d.cts}

@@ -23,6 +23,31 @@ interface IssuerPrivateJwk extends JWK {
     kid: string;
     alg?: string;
 }
+/**
+ * Strong identifier the issuer has verified the user owns at the moment
+ * of this login. Drives cross-issuer wallet unification in the gateway:
+ * `canonical_pafi_user_id = HMAC(pepper, type + ":" + normalized_value)`,
+ * so the same email or wallet address used at two different issuers
+ * resolves to the same Privy embedded wallet.
+ *
+ * Issuers MUST only attach an attribute they have actually verified
+ * (email OTP confirmed, SIWE signature accepted, OAuth provider returned
+ * `email_verified=true`, etc.). The gateway trusts the issuer's claim —
+ * attaching unverified values lets users hijack wallets.
+ *
+ * Normalization rules (gateway enforces, but issuers should mirror to
+ * avoid surprising hash mismatches):
+ *   - `email`:      lowercase + trim. No Gmail dot-strip, no plus-tag strip.
+ *   - `eth_wallet`: lowercase 0x-prefixed 20-byte hex.
+ *
+ * Omit entirely on logins where no strong attribute is verifiable —
+ * gateway falls back to legacy isolated-per-issuer canonical_id.
+ */
+type AuthAttributeType = "email" | "eth_wallet";
+interface AuthAttribute {
+    type: AuthAttributeType;
+    value: string;
+}
 /**
  * Parameters for minting an issuer JWT to send to the PAFI gateway.
  */
@@ -54,11 +79,20 @@ interface SignIssuerJwtParams {
      * uses this for replay protection — must be unique per request.
      */
     jti?: string;
+    /**
+     * Optional strong identifier the user proved ownership of during this
+     * login. Same attribute across issuers = same wallet. See
+     * {@link AuthAttribute}. Omit for SIWE-pure issuers, OAuth providers
+     * that don't expose verified contacts, etc. — gateway then falls back
+     * to legacy per-issuer canonical_id isolation for this login.
+     */
+    authAttribute?: AuthAttribute;
     /**
      * Optional additional claims merged into the payload. Use sparingly —
-     * PAFI gateway only reads `iss`, `sub`, `aud`, `iat`, `exp`, `jti`.
+     * PAFI gateway only reads `iss`, `sub`, `aud`, `iat`, `exp`, `jti`,
+     * and `auth_attribute`.
      */
     extra?: Record<string, unknown>;
 }
 
-export type { IssuerPrivateJwk as I, SignIssuerJwtParams as S, IssuerPublicJwk as a };
+export type { AuthAttribute as A, IssuerPrivateJwk as I, SignIssuerJwtParams as S, AuthAttributeType as a, IssuerPublicJwk as b };

package/dist/{types-CxVXRHLy.d.ts → types-DPqLTJk-.d.ts}

@@ -23,6 +23,31 @@ interface IssuerPrivateJwk extends JWK {
     kid: string;
     alg?: string;
 }
+/**
+ * Strong identifier the issuer has verified the user owns at the moment
+ * of this login. Drives cross-issuer wallet unification in the gateway:
+ * `canonical_pafi_user_id = HMAC(pepper, type + ":" + normalized_value)`,
+ * so the same email or wallet address used at two different issuers
+ * resolves to the same Privy embedded wallet.
+ *
+ * Issuers MUST only attach an attribute they have actually verified
+ * (email OTP confirmed, SIWE signature accepted, OAuth provider returned
+ * `email_verified=true`, etc.). The gateway trusts the issuer's claim —
+ * attaching unverified values lets users hijack wallets.
+ *
+ * Normalization rules (gateway enforces, but issuers should mirror to
+ * avoid surprising hash mismatches):
+ *   - `email`:      lowercase + trim. No Gmail dot-strip, no plus-tag strip.
+ *   - `eth_wallet`: lowercase 0x-prefixed 20-byte hex.
+ *
+ * Omit entirely on logins where no strong attribute is verifiable —
+ * gateway falls back to legacy isolated-per-issuer canonical_id.
+ */
+type AuthAttributeType = "email" | "eth_wallet";
+interface AuthAttribute {
+    type: AuthAttributeType;
+    value: string;
+}
 /**
  * Parameters for minting an issuer JWT to send to the PAFI gateway.
  */
@@ -54,11 +79,20 @@ interface SignIssuerJwtParams {
      * uses this for replay protection — must be unique per request.
      */
     jti?: string;
+    /**
+     * Optional strong identifier the user proved ownership of during this
+     * login. Same attribute across issuers = same wallet. See
+     * {@link AuthAttribute}. Omit for SIWE-pure issuers, OAuth providers
+     * that don't expose verified contacts, etc. — gateway then falls back
+     * to legacy per-issuer canonical_id isolation for this login.
+     */
+    authAttribute?: AuthAttribute;
     /**
      * Optional additional claims merged into the payload. Use sparingly —
-     * PAFI gateway only reads `iss`, `sub`, `aud`, `iat`, `exp`, `jti`.
+     * PAFI gateway only reads `iss`, `sub`, `aud`, `iat`, `exp`, `jti`,
+     * and `auth_attribute`.
      */
     extra?: Record<string, unknown>;
 }
 
-export type { IssuerPrivateJwk as I, SignIssuerJwtParams as S, IssuerPublicJwk as a };
+export type { AuthAttribute as A, IssuerPrivateJwk as I, SignIssuerJwtParams as S, AuthAttributeType as a, IssuerPublicJwk as b };

package/dist/wallet-auth/index.cjs

@@ -38,7 +38,14 @@ async function signIssuerJwt(params) {
   const key = await (0, import_jose.importJWK)(params.privateJwk, alg);
   const now = Math.floor(Date.now() / 1e3);
   const lifetime = params.expiresInSec ?? 60;
-  const builder = new import_jose.SignJWT({ ...params.extra ?? {} }).setProtectedHeader({ alg, typ: "JWT", kid }).setIssuer(params.iss).setSubject(params.sub).setAudience(params.aud).setIssuedAt(now).setExpirationTime(now + lifetime).setJti(params.jti ?? (0, import_node_crypto.randomUUID)());
+  const payload = { ...params.extra ?? {} };
+  if (params.authAttribute) {
+    payload.auth_attribute = {
+      type: params.authAttribute.type,
+      value: params.authAttribute.value
+    };
+  }
+  const builder = new import_jose.SignJWT(payload).setProtectedHeader({ alg, typ: "JWT", kid }).setIssuer(params.iss).setSubject(params.sub).setAudience(params.aud).setIssuedAt(now).setExpirationTime(now + lifetime).setJti(params.jti ?? (0, import_node_crypto.randomUUID)());
   return builder.sign(key);
 }
 // Annotate the CommonJS export names for ESM import in node:

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

@@ -1 +1 @@
-{"version":3,"sources":["../../src/wallet-auth/index.ts","../../src/wallet-auth/signIssuerJwt.ts"],"sourcesContent":["/**\n * Wallet-auth helpers — for issuer backends that integrate with the\n * PAFI Wallet Auth Gateway.\n *\n * Sub-modules:\n *   - signIssuerJwt   : mint an issuer JWT to send to the gateway\n *   - types           : IssuerPublicJwk, IssuerPrivateJwk, SignIssuerJwtParams\n *\n * NestJS-specific helpers (drop-in JWKS publishing controller) live\n * under `@pafi-dev/issuer/nestjs`.\n */\n\nexport { signIssuerJwt } from \"./signIssuerJwt\";\nexport type {\n  IssuerPublicJwk,\n  IssuerPrivateJwk,\n  SignIssuerJwtParams,\n} from \"./types\";\n","import { importJWK, SignJWT } from \"jose\";\nimport { randomUUID } from \"node:crypto\";\nimport type { SignIssuerJwtParams } from \"./types\";\n\n/**\n * Mint an issuer JWT for the PAFI Wallet Auth Gateway.\n *\n * Returns a compact JWT (header.payload.signature) ready to send as\n * the `issuer_jwt` body field in `POST /v1/token-exchange`.\n *\n * The matching public key must be reachable at the issuer's\n * `/.well-known/jwks.json` (see `WalletAuthJwksModule`) so the\n * gateway can verify the signature.\n *\n * @example\n *   import { signIssuerJwt } from '@pafi-dev/issuer/wallet-auth';\n *\n *   const jwt = await signIssuerJwt({\n *     privateJwk: JSON.parse(process.env.ISSUER_PRIVATE_JWK_JSON!),\n *     iss: 'https://gg56.com',\n *     sub: 'gg56_user_99',\n *     aud: 'pafi-gateway-prod',\n *   });\n *\n *   // POST { issuer_id: 'GG56', issuer_jwt: jwt } to gateway\n */\nexport async function signIssuerJwt(\n  params: SignIssuerJwtParams,\n): Promise<string> {\n  const alg = params.alg ?? params.privateJwk.alg ?? \"ES256\";\n  const kid = params.privateJwk.kid;\n\n  if (!kid) {\n    throw new Error(\n      \"signIssuerJwt: privateJwk.kid is required (gateway uses kid to look up the verification key)\",\n    );\n  }\n\n  const key = await importJWK(params.privateJwk, alg);\n  const now = Math.floor(Date.now() / 1000);\n  const lifetime = params.expiresInSec ?? 60;\n\n  const builder = new SignJWT({ ...(params.extra ?? {}) })\n    .setProtectedHeader({ alg, typ: \"JWT\", kid })\n    .setIssuer(params.iss)\n    .setSubject(params.sub)\n    .setAudience(params.aud)\n    .setIssuedAt(now)\n    .setExpirationTime(now + lifetime)\n    .setJti(params.jti ?? randomUUID());\n\n  return builder.sign(key);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,kBAAmC;AACnC,yBAA2B;AAyB3B,eAAsB,cACpB,QACiB;AACjB,QAAM,MAAM,OAAO,OAAO,OAAO,WAAW,OAAO;AACnD,QAAM,MAAM,OAAO,WAAW;AAE9B,MAAI,CAAC,KAAK;AACR,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AAEA,QAAM,MAAM,UAAM,uBAAU,OAAO,YAAY,GAAG;AAClD,QAAM,MAAM,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;AACxC,QAAM,WAAW,OAAO,gBAAgB;AAExC,QAAM,UAAU,IAAI,oBAAQ,EAAE,GAAI,OAAO,SAAS,CAAC,EAAG,CAAC,EACpD,mBAAmB,EAAE,KAAK,KAAK,OAAO,IAAI,CAAC,EAC3C,UAAU,OAAO,GAAG,EACpB,WAAW,OAAO,GAAG,EACrB,YAAY,OAAO,GAAG,EACtB,YAAY,GAAG,EACf,kBAAkB,MAAM,QAAQ,EAChC,OAAO,OAAO,WAAO,+BAAW,CAAC;AAEpC,SAAO,QAAQ,KAAK,GAAG;AACzB;","names":[]}
+{"version":3,"sources":["../../src/wallet-auth/index.ts","../../src/wallet-auth/signIssuerJwt.ts"],"sourcesContent":["/**\n * Wallet-auth helpers — for issuer backends that integrate with the\n * PAFI Wallet Auth Gateway.\n *\n * Sub-modules:\n *   - signIssuerJwt   : mint an issuer JWT to send to the gateway\n *   - types           : IssuerPublicJwk, IssuerPrivateJwk, SignIssuerJwtParams\n *\n * NestJS-specific helpers (drop-in JWKS publishing controller) live\n * under `@pafi-dev/issuer/nestjs`.\n */\n\nexport { signIssuerJwt } from \"./signIssuerJwt\";\nexport type {\n  AuthAttribute,\n  AuthAttributeType,\n  IssuerPublicJwk,\n  IssuerPrivateJwk,\n  SignIssuerJwtParams,\n} from \"./types\";\n","import { importJWK, SignJWT } from \"jose\";\nimport { randomUUID } from \"node:crypto\";\nimport type { SignIssuerJwtParams } from \"./types\";\n\n/**\n * Mint an issuer JWT for the PAFI Wallet Auth Gateway.\n *\n * Returns a compact JWT (header.payload.signature) ready to send as\n * the `issuer_jwt` body field in `POST /v1/token-exchange`.\n *\n * The matching public key must be reachable at the issuer's\n * `/.well-known/jwks.json` (see `WalletAuthJwksModule`) so the\n * gateway can verify the signature.\n *\n * @example\n *   import { signIssuerJwt } from '@pafi-dev/issuer/wallet-auth';\n *\n *   const jwt = await signIssuerJwt({\n *     privateJwk: JSON.parse(process.env.ISSUER_PRIVATE_JWK_JSON!),\n *     iss: 'https://gg56.com',\n *     sub: 'gg56_user_99',\n *     aud: 'pafi-gateway-prod',\n *   });\n *\n *   // POST { issuer_id: 'GG56', issuer_jwt: jwt } to gateway\n */\nexport async function signIssuerJwt(\n  params: SignIssuerJwtParams,\n): Promise<string> {\n  const alg = params.alg ?? params.privateJwk.alg ?? \"ES256\";\n  const kid = params.privateJwk.kid;\n\n  if (!kid) {\n    throw new Error(\n      \"signIssuerJwt: privateJwk.kid is required (gateway uses kid to look up the verification key)\",\n    );\n  }\n\n  const key = await importJWK(params.privateJwk, alg);\n  const now = Math.floor(Date.now() / 1000);\n  const lifetime = params.expiresInSec ?? 60;\n\n  const payload: Record<string, unknown> = { ...(params.extra ?? {}) };\n  if (params.authAttribute) {\n    payload.auth_attribute = {\n      type: params.authAttribute.type,\n      value: params.authAttribute.value,\n    };\n  }\n\n  const builder = new SignJWT(payload)\n    .setProtectedHeader({ alg, typ: \"JWT\", kid })\n    .setIssuer(params.iss)\n    .setSubject(params.sub)\n    .setAudience(params.aud)\n    .setIssuedAt(now)\n    .setExpirationTime(now + lifetime)\n    .setJti(params.jti ?? randomUUID());\n\n  return builder.sign(key);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,kBAAmC;AACnC,yBAA2B;AAyB3B,eAAsB,cACpB,QACiB;AACjB,QAAM,MAAM,OAAO,OAAO,OAAO,WAAW,OAAO;AACnD,QAAM,MAAM,OAAO,WAAW;AAE9B,MAAI,CAAC,KAAK;AACR,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AAEA,QAAM,MAAM,UAAM,uBAAU,OAAO,YAAY,GAAG;AAClD,QAAM,MAAM,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;AACxC,QAAM,WAAW,OAAO,gBAAgB;AAExC,QAAM,UAAmC,EAAE,GAAI,OAAO,SAAS,CAAC,EAAG;AACnE,MAAI,OAAO,eAAe;AACxB,YAAQ,iBAAiB;AAAA,MACvB,MAAM,OAAO,cAAc;AAAA,MAC3B,OAAO,OAAO,cAAc;AAAA,IAC9B;AAAA,EACF;AAEA,QAAM,UAAU,IAAI,oBAAQ,OAAO,EAChC,mBAAmB,EAAE,KAAK,KAAK,OAAO,IAAI,CAAC,EAC3C,UAAU,OAAO,GAAG,EACpB,WAAW,OAAO,GAAG,EACrB,YAAY,OAAO,GAAG,EACtB,YAAY,GAAG,EACf,kBAAkB,MAAM,QAAQ,EAChC,OAAO,OAAO,WAAO,+BAAW,CAAC;AAEpC,SAAO,QAAQ,KAAK,GAAG;AACzB;","names":[]}

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

@@ -1,5 +1,5 @@
-import { S as SignIssuerJwtParams } from '../types-CxVXRHLy.cjs';
-export { I as IssuerPrivateJwk, a as IssuerPublicJwk } from '../types-CxVXRHLy.cjs';
+import { S as SignIssuerJwtParams } from '../types-DPqLTJk-.cjs';
+export { A as AuthAttribute, a as AuthAttributeType, I as IssuerPrivateJwk, b as IssuerPublicJwk } from '../types-DPqLTJk-.cjs';
 import 'jose';
 
 /**

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

@@ -1,5 +1,5 @@
-import { S as SignIssuerJwtParams } from '../types-CxVXRHLy.js';
-export { I as IssuerPrivateJwk, a as IssuerPublicJwk } from '../types-CxVXRHLy.js';
+import { S as SignIssuerJwtParams } from '../types-DPqLTJk-.js';
+export { A as AuthAttribute, a as AuthAttributeType, I as IssuerPrivateJwk, b as IssuerPublicJwk } from '../types-DPqLTJk-.js';
 import 'jose';
 
 /**

package/dist/wallet-auth/index.js

@@ -14,7 +14,14 @@ async function signIssuerJwt(params) {
   const key = await importJWK(params.privateJwk, alg);
   const now = Math.floor(Date.now() / 1e3);
   const lifetime = params.expiresInSec ?? 60;
-  const builder = new SignJWT({ ...params.extra ?? {} }).setProtectedHeader({ alg, typ: "JWT", kid }).setIssuer(params.iss).setSubject(params.sub).setAudience(params.aud).setIssuedAt(now).setExpirationTime(now + lifetime).setJti(params.jti ?? randomUUID());
+  const payload = { ...params.extra ?? {} };
+  if (params.authAttribute) {
+    payload.auth_attribute = {
+      type: params.authAttribute.type,
+      value: params.authAttribute.value
+    };
+  }
+  const builder = new SignJWT(payload).setProtectedHeader({ alg, typ: "JWT", kid }).setIssuer(params.iss).setSubject(params.sub).setAudience(params.aud).setIssuedAt(now).setExpirationTime(now + lifetime).setJti(params.jti ?? randomUUID());
   return builder.sign(key);
 }
 export {

package/dist/wallet-auth/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/wallet-auth/signIssuerJwt.ts"],"sourcesContent":["import { importJWK, SignJWT } from \"jose\";\nimport { randomUUID } from \"node:crypto\";\nimport type { SignIssuerJwtParams } from \"./types\";\n\n/**\n * Mint an issuer JWT for the PAFI Wallet Auth Gateway.\n *\n * Returns a compact JWT (header.payload.signature) ready to send as\n * the `issuer_jwt` body field in `POST /v1/token-exchange`.\n *\n * The matching public key must be reachable at the issuer's\n * `/.well-known/jwks.json` (see `WalletAuthJwksModule`) so the\n * gateway can verify the signature.\n *\n * @example\n *   import { signIssuerJwt } from '@pafi-dev/issuer/wallet-auth';\n *\n *   const jwt = await signIssuerJwt({\n *     privateJwk: JSON.parse(process.env.ISSUER_PRIVATE_JWK_JSON!),\n *     iss: 'https://gg56.com',\n *     sub: 'gg56_user_99',\n *     aud: 'pafi-gateway-prod',\n *   });\n *\n *   // POST { issuer_id: 'GG56', issuer_jwt: jwt } to gateway\n */\nexport async function signIssuerJwt(\n  params: SignIssuerJwtParams,\n): Promise<string> {\n  const alg = params.alg ?? params.privateJwk.alg ?? \"ES256\";\n  const kid = params.privateJwk.kid;\n\n  if (!kid) {\n    throw new Error(\n      \"signIssuerJwt: privateJwk.kid is required (gateway uses kid to look up the verification key)\",\n    );\n  }\n\n  const key = await importJWK(params.privateJwk, alg);\n  const now = Math.floor(Date.now() / 1000);\n  const lifetime = params.expiresInSec ?? 60;\n\n  const builder = new SignJWT({ ...(params.extra ?? {}) })\n    .setProtectedHeader({ alg, typ: \"JWT\", kid })\n    .setIssuer(params.iss)\n    .setSubject(params.sub)\n    .setAudience(params.aud)\n    .setIssuedAt(now)\n    .setExpirationTime(now + lifetime)\n    .setJti(params.jti ?? randomUUID());\n\n  return builder.sign(key);\n}\n"],"mappings":";;;AAAA,SAAS,WAAW,eAAe;AACnC,SAAS,kBAAkB;AAyB3B,eAAsB,cACpB,QACiB;AACjB,QAAM,MAAM,OAAO,OAAO,OAAO,WAAW,OAAO;AACnD,QAAM,MAAM,OAAO,WAAW;AAE9B,MAAI,CAAC,KAAK;AACR,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AAEA,QAAM,MAAM,MAAM,UAAU,OAAO,YAAY,GAAG;AAClD,QAAM,MAAM,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;AACxC,QAAM,WAAW,OAAO,gBAAgB;AAExC,QAAM,UAAU,IAAI,QAAQ,EAAE,GAAI,OAAO,SAAS,CAAC,EAAG,CAAC,EACpD,mBAAmB,EAAE,KAAK,KAAK,OAAO,IAAI,CAAC,EAC3C,UAAU,OAAO,GAAG,EACpB,WAAW,OAAO,GAAG,EACrB,YAAY,OAAO,GAAG,EACtB,YAAY,GAAG,EACf,kBAAkB,MAAM,QAAQ,EAChC,OAAO,OAAO,OAAO,WAAW,CAAC;AAEpC,SAAO,QAAQ,KAAK,GAAG;AACzB;","names":[]}
+{"version":3,"sources":["../../src/wallet-auth/signIssuerJwt.ts"],"sourcesContent":["import { importJWK, SignJWT } from \"jose\";\nimport { randomUUID } from \"node:crypto\";\nimport type { SignIssuerJwtParams } from \"./types\";\n\n/**\n * Mint an issuer JWT for the PAFI Wallet Auth Gateway.\n *\n * Returns a compact JWT (header.payload.signature) ready to send as\n * the `issuer_jwt` body field in `POST /v1/token-exchange`.\n *\n * The matching public key must be reachable at the issuer's\n * `/.well-known/jwks.json` (see `WalletAuthJwksModule`) so the\n * gateway can verify the signature.\n *\n * @example\n *   import { signIssuerJwt } from '@pafi-dev/issuer/wallet-auth';\n *\n *   const jwt = await signIssuerJwt({\n *     privateJwk: JSON.parse(process.env.ISSUER_PRIVATE_JWK_JSON!),\n *     iss: 'https://gg56.com',\n *     sub: 'gg56_user_99',\n *     aud: 'pafi-gateway-prod',\n *   });\n *\n *   // POST { issuer_id: 'GG56', issuer_jwt: jwt } to gateway\n */\nexport async function signIssuerJwt(\n  params: SignIssuerJwtParams,\n): Promise<string> {\n  const alg = params.alg ?? params.privateJwk.alg ?? \"ES256\";\n  const kid = params.privateJwk.kid;\n\n  if (!kid) {\n    throw new Error(\n      \"signIssuerJwt: privateJwk.kid is required (gateway uses kid to look up the verification key)\",\n    );\n  }\n\n  const key = await importJWK(params.privateJwk, alg);\n  const now = Math.floor(Date.now() / 1000);\n  const lifetime = params.expiresInSec ?? 60;\n\n  const payload: Record<string, unknown> = { ...(params.extra ?? {}) };\n  if (params.authAttribute) {\n    payload.auth_attribute = {\n      type: params.authAttribute.type,\n      value: params.authAttribute.value,\n    };\n  }\n\n  const builder = new SignJWT(payload)\n    .setProtectedHeader({ alg, typ: \"JWT\", kid })\n    .setIssuer(params.iss)\n    .setSubject(params.sub)\n    .setAudience(params.aud)\n    .setIssuedAt(now)\n    .setExpirationTime(now + lifetime)\n    .setJti(params.jti ?? randomUUID());\n\n  return builder.sign(key);\n}\n"],"mappings":";;;AAAA,SAAS,WAAW,eAAe;AACnC,SAAS,kBAAkB;AAyB3B,eAAsB,cACpB,QACiB;AACjB,QAAM,MAAM,OAAO,OAAO,OAAO,WAAW,OAAO;AACnD,QAAM,MAAM,OAAO,WAAW;AAE9B,MAAI,CAAC,KAAK;AACR,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AAEA,QAAM,MAAM,MAAM,UAAU,OAAO,YAAY,GAAG;AAClD,QAAM,MAAM,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;AACxC,QAAM,WAAW,OAAO,gBAAgB;AAExC,QAAM,UAAmC,EAAE,GAAI,OAAO,SAAS,CAAC,EAAG;AACnE,MAAI,OAAO,eAAe;AACxB,YAAQ,iBAAiB;AAAA,MACvB,MAAM,OAAO,cAAc;AAAA,MAC3B,OAAO,OAAO,cAAc;AAAA,IAC9B;AAAA,EACF;AAEA,QAAM,UAAU,IAAI,QAAQ,OAAO,EAChC,mBAAmB,EAAE,KAAK,KAAK,OAAO,IAAI,CAAC,EAC3C,UAAU,OAAO,GAAG,EACpB,WAAW,OAAO,GAAG,EACrB,YAAY,OAAO,GAAG,EACtB,YAAY,GAAG,EACf,kBAAkB,MAAM,QAAQ,EAChC,OAAO,OAAO,OAAO,WAAW,CAAC;AAEpC,SAAO,QAAQ,KAAK,GAAG;AACzB;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pafi-dev/issuer",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "description": "Issuer backend API and services for the PAFI point token system",
   "repository": {
     "type": "git",
@@ -55,6 +55,16 @@
         "types": "./dist/wallet-auth/index.d.cts",
         "default": "./dist/wallet-auth/index.cjs"
       }
+    },
+    "./auth-client": {
+      "import": {
+        "types": "./dist/auth-client/index.d.ts",
+        "default": "./dist/auth-client/index.js"
+      },
+      "require": {
+        "types": "./dist/auth-client/index.d.cts",
+        "default": "./dist/auth-client/index.cjs"
+      }
     }
   },
   "typesVersions": {
@@ -67,15 +77,25 @@
       ],
       "wallet-auth": [
         "./dist/wallet-auth/index.d.ts"
+      ],
+      "auth-client": [
+        "./dist/auth-client/index.d.ts"
       ]
     }
   },
   "files": [
     "dist"
   ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "test:cov": "vitest run --coverage --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  },
   "dependencies": {
-    "jose": "^5.9.0",
-    "@pafi-dev/core": "0.24.0"
+    "@pafi-dev/core": "workspace:*",
+    "jose": "^5.9.0"
   },
   "peerDependencies": {
     "@nestjs/common": "^10.0.0",
@@ -94,12 +114,5 @@
     "viem": "^2.21.0",
     "vitest": "^2.0.0"
   },
-  "license": "Apache-2.0",
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run --passWithNoTests",
-    "test:watch": "vitest",
-    "test:cov": "vitest run --coverage --passWithNoTests",
-    "typecheck": "tsc --noEmit"
-  }
-}
+  "license": "Apache-2.0"
+}