@pafi-dev/issuer 0.38.1 → 0.39.1

package/dist/pafi-auth-client-DzHd_Ts_.d.cts

@@ -0,0 +1,142 @@
+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;
+}
+
+export { type AuthSuccess as A, type EmailChallenge as E, PafiAuthClient as P, type PafiAuthClientOptions as a, PafiAuthError as b };

package/dist/pafi-auth-client-DzHd_Ts_.d.ts

@@ -0,0 +1,142 @@
+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;
+}
+
+export { type AuthSuccess as A, type EmailChallenge as E, PafiAuthClient as P, type PafiAuthClientOptions as a, PafiAuthError as b };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pafi-dev/issuer",
-  "version": "0.38.1",
+  "version": "0.39.1",
   "description": "Issuer backend API and services for the PAFI point token system",
   "repository": {
     "type": "git",
@@ -65,6 +65,16 @@
         "types": "./dist/auth-client/index.d.cts",
         "default": "./dist/auth-client/index.cjs"
       }
+    },
+    "./direct-auth": {
+      "import": {
+        "types": "./dist/direct-auth/index.d.ts",
+        "default": "./dist/direct-auth/index.js"
+      },
+      "require": {
+        "types": "./dist/direct-auth/index.d.cts",
+        "default": "./dist/direct-auth/index.cjs"
+      }
     }
   },
   "typesVersions": {
@@ -80,6 +90,9 @@
       ],
       "auth-client": [
         "./dist/auth-client/index.d.ts"
+      ],
+      "direct-auth": [
+        "./dist/direct-auth/index.d.ts"
       ]
     }
   },
@@ -92,16 +105,35 @@
   },
   "peerDependencies": {
     "@nestjs/common": "^10.0.0",
+    "@nestjs/swagger": "^7.0.0 || ^8.0.0",
+    "class-validator": "^0.14.0",
+    "class-transformer": "^0.5.0",
+    "reflect-metadata": "^0.1.13 || ^0.2.0",
     "viem": "^2.0.0"
   },
   "peerDependenciesMeta": {
     "@nestjs/common": {
       "optional": true
+    },
+    "@nestjs/swagger": {
+      "optional": true
+    },
+    "class-validator": {
+      "optional": true
+    },
+    "class-transformer": {
+      "optional": true
+    },
+    "reflect-metadata": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@nestjs/common": "^10.0.0",
+    "@nestjs/swagger": "^7.0.0",
     "@vitest/coverage-v8": "^2.1.0",
+    "class-validator": "^0.14.0",
+    "reflect-metadata": "^0.2.0",
     "tsup": "^8.0.0",
     "typescript": "^5.5.0",
     "viem": "^2.21.0",