@pafi-dev/issuer 0.38.1 → 0.39.0

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

@@ -0,0 +1,405 @@
+import { Type, DynamicModule, OnModuleInit } from '@nestjs/common';
+import { JWK, JWTPayload } from 'jose';
+import { P as PafiAuthClient } from '../pafi-auth-client-DzHd_Ts_.js';
+
+/**
+ * Issuer-side abstraction for "make sure the local user row exists,
+ * keyed by the canonical_pafi_user_id the gateway just resolved."
+ *
+ * The SDK can't own this because each issuer has a different
+ * `users` table schema (gg56 has `wallet_address`, lotteria doesn't,
+ * future issuers might add `phone_number` / `kyc_status` / etc.).
+ * Each consuming issuer backend implements `IUserStore` once and
+ * passes the class to `PafiDirectAuthModule.forRoot({ userStore })`.
+ *
+ * Idempotency contract: callers invoke this on every successful
+ * direct-auth flow (email OTP / Google / Kakao). Implementation MUST
+ * be idempotent — re-calling with the same args is a no-op, NOT an
+ * error.
+ *
+ * Lookup precedence (recommended): canonical_id first, fall back to
+ * email. Same canonical across issuers = cross-issuer wallet merge.
+ *
+ * Race-safety: parallel requests for the same brand-new canonical
+ * should be tolerated. The SDK assumes the underlying DB enforces a
+ * unique constraint on canonical_id; on conflict, treat as "row
+ * already exists" rather than re-throwing.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * class Gg56UserStore implements IUserStore {
+ *   constructor(
+ *     @InjectRepository(UserEntity)
+ *     private readonly users: Repository<UserEntity>,
+ *   ) {}
+ *
+ *   async upsertByCanonicalAndEmail(args: {
+ *     canonicalId: string;
+ *     verifiedEmail?: string;
+ *   }): Promise<void> {
+ *     const byCanonical = await this.users.findOne({
+ *       where: { canonicalId: args.canonicalId },
+ *     });
+ *     if (byCanonical) return;
+ *     // ... fall back to email, create row, race-handle, etc.
+ *   }
+ * }
+ * ```
+ */
+interface IUserStore {
+    upsertByCanonicalAndEmail(args: {
+        /** canonical_pafi_user_id the gateway just minted. Always present. */
+        canonicalId: string;
+        /**
+         * Verified email when the auth method exposed one (email OTP +
+         * Google always; Kakao only if user shared email at consent).
+         * Issuer may use to display profile, NOT for primary user lookup
+         * (canonicalId is the stable id).
+         */
+        verifiedEmail?: string;
+    }): Promise<void>;
+}
+/** DI token for IUserStore. Use with `@Inject(USER_STORE)`. */
+declare const USER_STORE: unique symbol;
+
+/**
+ * Issuer-side abstraction for "mint an issuer-native session token
+ * the FE will Bearer-auth with for all subsequent /api calls."
+ *
+ * The SDK can't own this because:
+ *  - Each issuer signs with their own `JWT_SECRET` (HS256) OR with
+ *    their own RSA/ECDSA key — SDK shouldn't see secrets
+ *  - Token shape may differ (sub format, scope claims, extra claims
+ *    like role/tier specific to the issuer's app)
+ *  - Lifetime may differ (24h default, but some issuers want shorter)
+ *  - Existing JwtGuard / SessionTokenGuard in the issuer backend
+ *    expects a specific shape — SDK can't predict it
+ *
+ * The SDK orchestrator calls `mint()` once per successful direct-auth
+ * flow, BEFORE returning the bundled response to the issuer's HTTP
+ * controller. The minter is responsible for:
+ *  1. Producing a token the issuer's existing guards accept
+ *  2. Embedding `authAttribute: {type, value}` if the issuer's
+ *     /wallet/exchange-pafi-jwt refresh path needs it (most do — see
+ *     ISSUER_INTEGRATION_GUIDE.md §9 refresh path)
+ *  3. Computing absolute expiry timestamp the FE can show
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * class Gg56SessionMinter implements ISessionTokenMinter {
+ *   private readonly secret: Uint8Array;
+ *   constructor(config: ConfigService) {
+ *     this.secret = new TextEncoder().encode(
+ *       config.getOrThrow('JWT_SECRET'),
+ *     );
+ *   }
+ *
+ *   async mint(args: {
+ *     canonicalId: string;
+ *     verifiedEmail?: string;
+ *   }): Promise<{ token: string; expiresAt: string }> {
+ *     const now = Math.floor(Date.now() / 1000);
+ *     const exp = now + 86400;
+ *     const token = await new SignJWT({
+ *       userKey: args.canonicalId,
+ *       loginType: 'pafi-direct',
+ *       scope: 'pafi-session',
+ *       ...(args.verifiedEmail
+ *         ? { authAttribute: { type: 'email', value: args.verifiedEmail } }
+ *         : {}),
+ *     })
+ *       .setProtectedHeader({ alg: 'HS256', typ: 'JWT' })
+ *       .setSubject(args.canonicalId)
+ *       .setIssuedAt(now)
+ *       .setExpirationTime(exp)
+ *       .sign(this.secret);
+ *     return { token, expiresAt: new Date(exp * 1000).toISOString() };
+ *   }
+ * }
+ * ```
+ */
+interface ISessionTokenMinter {
+    mint(args: {
+        /** canonical_pafi_user_id, use as `sub` so downstream identifies user uniformly. */
+        canonicalId: string;
+        /**
+         * Verified email when available. Implementations SHOULD embed this
+         * as `authAttribute: { type: 'email', value }` in the JWT body so
+         * the legacy /wallet/exchange-pafi-jwt refresh path keeps deriving
+         * the same canonical_id from the same attribute across refreshes.
+         */
+        verifiedEmail?: string;
+    }): Promise<{
+        /** The signed session token (any JWT shape — issuer guards must accept). */
+        token: string;
+        /** ISO 8601 absolute expiry timestamp. Returned to FE so it can show "expires at X". */
+        expiresAt: string;
+    }>;
+}
+/** DI token for ISessionTokenMinter. Use with `@Inject(SESSION_TOKEN_MINTER)`. */
+declare const SESSION_TOKEN_MINTER: unique symbol;
+
+/**
+ * Options consumed by `PafiDirectAuthModule.forRoot(options)`. The
+ * host (issuer backend) supplies:
+ *
+ *  - Gateway credentials (URL, issuer_id, client_id, private JWK)
+ *  - Issuer-specific implementations of IUserStore + ISessionTokenMinter
+ *
+ * Typically read from `ConfigService` in the issuer backend. Use
+ * `forRootAsync()` (planned) when config needs `inject: [ConfigService]`.
+ */
+interface PafiDirectAuthModuleOptions {
+    /** 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;
+    };
+    /**
+     * Issuer-implemented user-row upsert. SDK calls this on every
+     * successful direct-auth flow to ensure the local users row exists
+     * keyed by canonical_id. See `IUserStore` for contract details.
+     */
+    userStore: Type<IUserStore>;
+    /**
+     * Issuer-implemented session-token minter. SDK calls this once per
+     * successful direct-auth flow to wrap the gateway-returned canonical
+     * + verified email into the issuer's own session JWT. See
+     * `ISessionTokenMinter` for contract details.
+     */
+    sessionTokenMinter: Type<ISessionTokenMinter>;
+}
+/** DI token for the resolved options. Use with `@Inject(PAFI_DIRECT_AUTH_MODULE_OPTIONS)`. */
+declare const PAFI_DIRECT_AUTH_MODULE_OPTIONS: unique symbol;
+
+/**
+ * NestJS module wiring the direct-auth surface (`/auth/v2/*`
+ * controller, orchestrator service, gateway client, session
+ * verifier).
+ *
+ * Issuer backends mount this once at the root module with their
+ * gateway credentials + their `IUserStore` and `ISessionTokenMinter`
+ * implementations:
+ *
+ * ```ts
+ * @Module({
+ *   imports: [
+ *     ConfigModule.forRoot(),
+ *     TypeOrmModule.forFeature([UserEntity]),
+ *     PafiDirectAuthModule.forRoot({
+ *       gatewayUrl: process.env.PAFI_GATEWAY_URL!,
+ *       issuerId: process.env.PAFI_GATEWAY_ISSUER_ID!,
+ *       clientId: process.env.PAFI_GATEWAY_CLIENT_ID!,
+ *       clientPrivateJwk: JSON.parse(
+ *         process.env.PAFI_GATEWAY_CLIENT_PRIVATE_JWK_JSON!,
+ *       ) as JWK & { kid: string },
+ *       userStore: Gg56UserStore,
+ *       sessionTokenMinter: Gg56SessionMinter,
+ *     }),
+ *   ],
+ *   providers: [Gg56UserStore, Gg56SessionMinter],
+ * })
+ * export class AuthModule {}
+ * ```
+ *
+ * The `IUserStore` + `ISessionTokenMinter` classes MUST be provided
+ * separately in the host module's `providers:` array (NestJS needs to
+ * see them to instantiate via DI). This module wires them to the
+ * orchestrator via the `USER_STORE` + `SESSION_TOKEN_MINTER` injection
+ * tokens.
+ *
+ * For ConfigService-based async setup, use `forRootAsync()` (TODO).
+ */
+declare class PafiDirectAuthModule {
+    static forRoot(options: PafiDirectAuthModuleOptions): DynamicModule;
+}
+
+/**
+ * Thin DI wrapper around {@link PafiAuthClient}. Constructs a single
+ * client at boot using the issuer's gateway credentials and exposes it
+ * to services that need to call the direct-auth endpoints.
+ *
+ * One instance per process — the SDK client is stateless and the
+ * client_assertion is signed on every call (no warm-up needed).
+ *
+ * Config comes from `PafiDirectAuthModule.forRoot(options)` (see
+ * `pafi-direct-auth.module.ts`). The host app supplies `gatewayUrl`,
+ * `issuerId`, `clientId`, and `clientPrivateJwk` either as literal
+ * values OR as a factory that resolves them from NestJS ConfigService
+ * (`forRootAsync` variant).
+ */
+declare class PafiAuthClientProvider implements OnModuleInit {
+    private readonly options;
+    private _client;
+    constructor(options: PafiDirectAuthModuleOptions);
+    onModuleInit(): void;
+    get client(): PafiAuthClient;
+}
+
+interface PafiSessionClaims {
+    sub: string;
+    scope: "pafi-session";
+    /** Verified attribute the gateway used to derive canonical_id. */
+    verifiedAttribute?: {
+        type: string;
+        valueHash?: string;
+    };
+    /** Issuer that originated the auth (must equal our PAFI_GATEWAY_ISSUER_ID). */
+    issuerId?: string;
+    exp: number;
+    iat: number;
+    raw: JWTPayload;
+}
+/**
+ * Verifies the long-lived `pafi_session_token` returned by the
+ * gateway's direct-auth endpoints. Defense-in-depth: the gateway just
+ * minted this token, so the chance of forgery is near zero — BUT
+ * verifying it locally guarantees we never trust an attacker-supplied
+ * "fake gateway response" that bypassed the network call (e.g. a
+ * compromised inbound proxy injecting an arbitrary JSON body). One
+ * audit line for a millisecond of crypto work.
+ *
+ * Uses the gateway's published JWKS (`/.well-known/jwks.json`) — same
+ * key set Privy uses when verifying the short-lived `pafi_jwt`. The
+ * remote JWKS is cached + auto-refreshed by jose.
+ */
+declare class PafiSessionVerifierService {
+    private readonly jwks;
+    private readonly expectedIssuer;
+    constructor(options: PafiDirectAuthModuleOptions);
+    verify(token: string): Promise<PafiSessionClaims>;
+}
+
+interface DirectAuthResult {
+    sessionToken: string;
+    sessionExpiresAt: string;
+    pafiJwt: string;
+    pafiSessionToken: string;
+    canonicalId: string;
+    isFirstLogin: boolean;
+    verifiedEmail?: string;
+}
+/**
+ * Orchestrates the gateway-owned auth flows for an issuer backend. The
+ * gateway is the sole verifier (it ran the OTP check / verified the
+ * Google id_token / exchanged the Kakao code); this service is a thin
+ * adapter that:
+ *
+ *  1. Forwards the call via {@link PafiAuthClient} (RFC 7523
+ *     client_assertion signed by the issuer's private JWK)
+ *  2. Verifies the returned `pafi_session_token` against the gateway's
+ *     JWKS (defense in depth — see {@link PafiSessionVerifierService})
+ *  3. Upserts the local user row via {@link IUserStore} (issuer
+ *     implements; SDK doesn't know the DB schema)
+ *  4. Mints an issuer-native session token via
+ *     {@link ISessionTokenMinter} (issuer implements; SDK doesn't see
+ *     the issuer's JWT_SECRET)
+ *
+ * The returned `sessionToken.sub` is the canonical_id — the same value
+ * the gateway uses for the PAFI JWT's `sub`. This means downstream
+ * services that need a stable user id can use it without caring which
+ * auth method produced it.
+ *
+ * Extracted from per-issuer boilerplate code in 2026-06-30 SDK refactor.
+ * Previously copy-pasted (~260 lines per issuer); now ~60 lines per
+ * issuer (UserStore + SessionMinter + module wiring).
+ */
+declare class PafiDirectAuthService {
+    private readonly clientProvider;
+    private readonly sessionVerifier;
+    private readonly userStore;
+    private readonly sessionTokenMinter;
+    private readonly logger;
+    constructor(clientProvider: PafiAuthClientProvider, sessionVerifier: PafiSessionVerifierService, userStore: IUserStore, sessionTokenMinter: ISessionTokenMinter);
+    startEmail(args: {
+        email: string;
+        correlationId?: string;
+    }): Promise<{
+        challengeId: string;
+        expiresInSec: number;
+    }>;
+    verifyEmail(args: {
+        challengeId: string;
+        otpCode: string;
+        correlationId?: string;
+    }): Promise<DirectAuthResult>;
+    exchangeGoogle(args: {
+        idToken: string;
+        correlationId?: string;
+    }): Promise<DirectAuthResult>;
+    exchangeKakao(args: {
+        code: string;
+        redirectUri?: string;
+        correlationId?: string;
+    }): Promise<DirectAuthResult>;
+    private finalize;
+}
+
+declare class EmailStartRequestDto {
+    email: string;
+}
+declare class EmailVerifyRequestDto {
+    challengeId: string;
+    otpCode: string;
+}
+declare class GoogleExchangeRequestDto {
+    idToken: string;
+}
+declare class KakaoExchangeRequestDto {
+    code: string;
+    redirectUri?: string;
+}
+declare class EmailStartResponseDto {
+    challengeId: string;
+    expiresInSec: number;
+}
+declare class PafiAuthSuccessDto {
+    sessionToken: string;
+    sessionExpiresAt: string;
+    pafiJwt: string;
+    pafiSessionToken: string;
+    canonicalId: string;
+    isFirstLogin: boolean;
+    verifiedEmail?: string;
+}
+
+/**
+ * `/auth/v2/*` — gateway-owned auth endpoints (2026-06-30 direct-auth
+ * surface, shipped by `@pafi-dev/issuer/direct-auth`).
+ *
+ * Issuer backend no longer verifies OTP codes, OAuth id_tokens, or
+ * holds OAuth client_secrets. All of that lives at the PAFI gateway.
+ * These endpoints are thin proxies that forward user input via
+ * {@link PafiDirectAuthService}, then upsert the local user row (via
+ * the issuer-provided {@link IUserStore}) + mint an issuer-native
+ * session token (via the issuer-provided {@link ISessionTokenMinter})
+ * wrapping the gateway-assigned canonical_id.
+ *
+ * Mounted automatically by `PafiDirectAuthModule.forRoot(options)`.
+ * Issuer apps that want to layer extra auth-error handling (e.g. a
+ * custom `AuthErrorFilter`) can wrap the controller's routes via a
+ * NestJS global filter — no per-route `@UseFilters` needed here.
+ */
+declare class PafiDirectAuthController {
+    private readonly directAuth;
+    constructor(directAuth: PafiDirectAuthService);
+    startEmail(body: EmailStartRequestDto): Promise<EmailStartResponseDto>;
+    verifyEmail(body: EmailVerifyRequestDto): Promise<PafiAuthSuccessDto>;
+    exchangeGoogle(body: GoogleExchangeRequestDto): Promise<PafiAuthSuccessDto>;
+    exchangeKakao(body: KakaoExchangeRequestDto): Promise<PafiAuthSuccessDto>;
+}
+
+export { type DirectAuthResult, EmailStartRequestDto, EmailStartResponseDto, EmailVerifyRequestDto, GoogleExchangeRequestDto, type ISessionTokenMinter, type IUserStore, KakaoExchangeRequestDto, PAFI_DIRECT_AUTH_MODULE_OPTIONS, PafiAuthClientProvider, PafiAuthSuccessDto, PafiDirectAuthController, PafiDirectAuthModule, type PafiDirectAuthModuleOptions, PafiDirectAuthService, type PafiSessionClaims, PafiSessionVerifierService, SESSION_TOKEN_MINTER, USER_STORE };