@payez/next-mvp 4.4.8 → 4.5.0

package/dist/routes/auth/viability.d.ts

@@ -14,6 +14,7 @@
  * @since auth-ready-v2
  */
 import { NextRequest, NextResponse } from 'next/server';
+import { type RevocationStatus } from '../../vibe/sessions';
 /**
  * GET /api/session/viability - Check if session is viable
  *
@@ -34,6 +35,9 @@ export declare function GET(req: NextRequest): Promise<NextResponse<{
     hasRefreshToken: boolean;
     authenticated: boolean;
     sessionTokenId: string | null;
+    revocationStatus: RevocationStatus;
+    forceInvalid: boolean;
+    revoked: boolean;
     tenantRequiresTwoFactor: boolean;
     userHasCompletedTenantTwoFactorRequirements: boolean;
     userStillNeedsTwoFactor: boolean;
@@ -49,6 +53,7 @@ export declare function GET(req: NextRequest): Promise<NextResponse<{
     viable: boolean;
     needsRefresh: boolean;
     authenticated: boolean;
+    revocationStatus: RevocationStatus;
     error: string;
     code: string;
     correlationId: string;

package/dist/routes/auth/viability.js

@@ -22,6 +22,7 @@ const session_store_1 = require("../../lib/session-store");
 const idp_client_config_1 = require("../../lib/idp-client-config");
 const safe_error_response_1 = require("../../lib/safe-error-response");
 const token_log_id_1 = require("../../lib/token-log-id");
+const sessions_1 = require("../../vibe/sessions");
 /**
  * Get tenant-wide 2FA requirement from cached client config (from broker handshake)
  */
@@ -248,6 +249,41 @@ async function GET(req) {
         const oauthSessionNeedsTwoFactor = session?.mfaSignalPresent === true &&
             session?.mfaVerified === false &&
             !(session.idpRefreshToken || session?.refreshToken);
+        // --- Session revocation status (PAY-1882 step 4 producer half) ---
+        /*
+         * Resolve the four-state revocation status for this user (BAPert 66320).
+         * Read it HERE, above every authenticated return, so all three responses
+         * carry the SAME value - the same discipline as nextStep above.
+         *
+         * The middleware fails CLOSED by default on 'unknown' (a failed Vibe read)
+         * and always on 'revoked'; 'active' and 'not_configured' stay viable. A
+         * consumer that does NOT read revocationStatus is unaffected - absent is not
+         * revoked - so shipping this changes nothing for them until they opt in.
+         */
+        let revocationStatus = 'not_configured';
+        if (session) {
+            // BAPert 66480 condition 2 / ruling (ii) 66700: the numeric IdP id comes from
+            // the token's own `sub` claim FIRST (session.userId can be an email).
+            const revocationUserId = (0, sessions_1.resolveNumericIdpUserId)(session, session.idpAccessToken);
+            if (revocationUserId > 0) {
+                try {
+                    revocationStatus = await (0, sessions_1.getRevocationStatus)(revocationUserId, sessionToken);
+                }
+                catch {
+                    // getRevocationStatus does not throw by contract, but never let a
+                    // revocation probe take down the viability answer: fail closed.
+                    revocationStatus = 'unknown';
+                }
+            }
+            else {
+                // N1 (NightHawk 66392): a session exists but carries no usable numeric
+                // IdP id, so the check could not run -> 'unknown' (could not determine),
+                // NOT 'not_configured' (no revocation source).
+                // BAPert 66480 condition 1: emit ONE WARN (shape only) so a non-numeric
+                // id surfaces as a log line, not an unexplained sign-out.
+                revocationStatus = (0, sessions_1.warnNonNumericUserId)(sessionToken, session.userId);
+            }
+        }
         // Check access token expiry
         const now = Math.floor(Date.now() / 1000);
         // 240654 addendum 2: fall back to the Redis session's own expiry.
@@ -292,6 +328,11 @@ async function GET(req) {
                 needsRefresh: true,
                 authenticated: true,
                 sessionTokenId: sessionToken ? (0, token_log_id_1.tokenLogId)(sessionToken) : null,
+                // Session revocation (PAY-1882 step 4): the four-state status, plus the
+                // boolean the middleware's existing force-invalid branch already reads.
+                revocationStatus,
+                forceInvalid: revocationStatus === 'revoked' || revocationStatus === 'unknown',
+                revoked: revocationStatus === 'revoked',
                 // Clear names for middleware decision-making
                 tenantRequiresTwoFactor,
                 userHasCompletedTenantTwoFactorRequirements,
@@ -363,6 +404,10 @@ async function GET(req) {
                 twoFactorComplete: userHasCompletedTenantTwoFactorRequirements,
                 accessTokenExpired: true,
                 reason: 'Token expired',
+                // Session revocation (PAY-1882 step 4) - same value on every return.
+                revocationStatus,
+                forceInvalid: revocationStatus === 'revoked' || revocationStatus === 'unknown',
+                revoked: revocationStatus === 'revoked',
                 // RBAC fields
                 roles: session?.roles || [],
                 clientId: resolveClientId(session?.idpClientId),
@@ -375,6 +420,10 @@ async function GET(req) {
             hasRefreshToken,
             authenticated: true,
             sessionTokenId: sessionToken ? (0, token_log_id_1.tokenLogId)(sessionToken) : null,
+            // Session revocation (PAY-1882 step 4) - same value on every return.
+            revocationStatus,
+            forceInvalid: revocationStatus === 'revoked' || revocationStatus === 'unknown',
+            revoked: revocationStatus === 'revoked',
             // Clear names
             tenantRequiresTwoFactor,
             userHasCompletedTenantTwoFactorRequirements,
@@ -398,6 +447,10 @@ async function GET(req) {
             viable: false,
             needsRefresh: false,
             authenticated: false,
+            // PAY-1882 step 4: an exception here means the status could not be read.
+            // Report 'unknown' (not a bare 500 with no revocation signal) so the
+            // middleware's fail-closed default applies rather than reading it as viable.
+            revocationStatus: 'unknown',
             error: 'Failed to check session',
             code: 'INTERNAL_ERROR',
             correlationId

package/dist/routes/onboarding/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Ready-to-use onboarding route handlers (PAY-2121).
+ *
+ * Import directly into your app's API routes with zero configuration:
+ *
+ * @example
+ * ```typescript
+ * // app/api/onboarding/verify-code/route.ts
+ * export { POST } from '@payez/next-mvp/routes/onboarding/verify-code';
+ * ```
+ */
+export { POST as verifyCodePOST } from '../../api-handlers/onboarding/verify-code';
+export { POST as sendEmailCodePOST } from '../../api-handlers/onboarding/send-email-code';
+export { POST as verifyWelcomeEmailPOST } from '../../api-handlers/onboarding/verify-welcome-email';
+export { POST as setPasswordPOST } from '../../api-handlers/onboarding/set-password';

package/dist/routes/onboarding/index.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setPasswordPOST = exports.verifyWelcomeEmailPOST = exports.sendEmailCodePOST = exports.verifyCodePOST = void 0;
+/**
+ * Ready-to-use onboarding route handlers (PAY-2121).
+ *
+ * Import directly into your app's API routes with zero configuration:
+ *
+ * @example
+ * ```typescript
+ * // app/api/onboarding/verify-code/route.ts
+ * export { POST } from '@payez/next-mvp/routes/onboarding/verify-code';
+ * ```
+ */
+var verify_code_1 = require("../../api-handlers/onboarding/verify-code");
+Object.defineProperty(exports, "verifyCodePOST", { enumerable: true, get: function () { return verify_code_1.POST; } });
+var send_email_code_1 = require("../../api-handlers/onboarding/send-email-code");
+Object.defineProperty(exports, "sendEmailCodePOST", { enumerable: true, get: function () { return send_email_code_1.POST; } });
+var verify_welcome_email_1 = require("../../api-handlers/onboarding/verify-welcome-email");
+Object.defineProperty(exports, "verifyWelcomeEmailPOST", { enumerable: true, get: function () { return verify_welcome_email_1.POST; } });
+var set_password_1 = require("../../api-handlers/onboarding/set-password");
+Object.defineProperty(exports, "setPasswordPOST", { enumerable: true, get: function () { return set_password_1.POST; } });

package/dist/routes/onboarding/send-email-code.d.ts

@@ -0,0 +1,2 @@
+/** POST /api/onboarding/send-email-code -> IdP (PAY-2121). */
+export { POST } from '../../api-handlers/onboarding/send-email-code';

package/dist/routes/onboarding/send-email-code.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = void 0;
+/** POST /api/onboarding/send-email-code -> IdP (PAY-2121). */
+var send_email_code_1 = require("../../api-handlers/onboarding/send-email-code");
+Object.defineProperty(exports, "POST", { enumerable: true, get: function () { return send_email_code_1.POST; } });

package/dist/routes/onboarding/set-password.d.ts

@@ -0,0 +1,2 @@
+/** POST /api/onboarding/set-password -> IdP (PAY-2121). */
+export { POST } from '../../api-handlers/onboarding/set-password';

package/dist/routes/onboarding/set-password.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = void 0;
+/** POST /api/onboarding/set-password -> IdP (PAY-2121). */
+var set_password_1 = require("../../api-handlers/onboarding/set-password");
+Object.defineProperty(exports, "POST", { enumerable: true, get: function () { return set_password_1.POST; } });

package/dist/routes/onboarding/verify-code.d.ts

@@ -0,0 +1,2 @@
+/** POST /api/onboarding/verify-code -> IdP (PAY-2121). */
+export { POST } from '../../api-handlers/onboarding/verify-code';

package/dist/routes/onboarding/verify-code.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = void 0;
+/** POST /api/onboarding/verify-code -> IdP (PAY-2121). */
+var verify_code_1 = require("../../api-handlers/onboarding/verify-code");
+Object.defineProperty(exports, "POST", { enumerable: true, get: function () { return verify_code_1.POST; } });

package/dist/routes/onboarding/verify-welcome-email.d.ts

@@ -0,0 +1,2 @@
+/** POST /api/onboarding/verify-welcome-email -> IdP (PAY-2121). */
+export { POST } from '../../api-handlers/onboarding/verify-welcome-email';

package/dist/routes/onboarding/verify-welcome-email.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = void 0;
+/** POST /api/onboarding/verify-welcome-email -> IdP (PAY-2121). */
+var verify_welcome_email_1 = require("../../api-handlers/onboarding/verify-welcome-email");
+Object.defineProperty(exports, "POST", { enumerable: true, get: function () { return verify_welcome_email_1.POST; } });

package/dist/utils/api.d.ts

@@ -33,6 +33,12 @@ export declare function apiFetch<T>(url: string, options?: ApiOptions): Promise<
  */
 export declare const RECOVERY_EXPIRED_TEXT = "This reset link has expired or was already used. Start password recovery again.";
 export declare const RESET_NEUTRAL_TEXT = "We couldn't set that password. Check it meets the requirements shown and try again.";
+/**
+ * PAY-2103 (AUTH-009): the IdP refuses a password found in a breach corpus; the route projects a
+ * `password_breached: true` boolean, and the user reads this. Distinct from the policy sentence,
+ * which would wrongly tell them to re-read the requirements.
+ */
+export declare const RESET_BREACHED_TEXT = "This password appears in a known data breach. Choose a different one.";
 /**
  * Three tiers for a 400/422 from reset (rigpert 60822, QAPert 60820), decided ONLY on codes the IdP actually sends:
  *   policy        details.code password_policy (projected by the handler as password_policy) -> the rule sentences

package/dist/utils/api.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.accountApi = exports.AccountApi = exports.RESET_NEUTRAL_TEXT = exports.RECOVERY_EXPIRED_TEXT = exports.ApiError = void 0;
+exports.accountApi = exports.AccountApi = exports.RESET_BREACHED_TEXT = exports.RESET_NEUTRAL_TEXT = exports.RECOVERY_EXPIRED_TEXT = exports.ApiError = void 0;
 exports.apiFetch = apiFetch;
 exports.resetFailureText = resetFailureText;
 const standardized_client_api_1 = require("../lib/standardized-client-api");
@@ -84,6 +84,12 @@ async function apiFetch(url, options = {}) {
  */
 exports.RECOVERY_EXPIRED_TEXT = 'This reset link has expired or was already used. Start password recovery again.';
 exports.RESET_NEUTRAL_TEXT = "We couldn't set that password. Check it meets the requirements shown and try again.";
+/**
+ * PAY-2103 (AUTH-009): the IdP refuses a password found in a breach corpus; the route projects a
+ * `password_breached: true` boolean, and the user reads this. Distinct from the policy sentence,
+ * which would wrongly tell them to re-read the requirements.
+ */
+exports.RESET_BREACHED_TEXT = 'This password appears in a known data breach. Choose a different one.';
 /**
  * Three tiers for a 400/422 from reset (rigpert 60822, QAPert 60820), decided ONLY on codes the IdP actually sends:
  *   policy        details.code password_policy (projected by the handler as password_policy) -> the rule sentences
@@ -196,7 +202,9 @@ class AccountApi {
             const policy = !!body?.password_policy;
             const rules = (0, password_rules_1.knownPasswordRules)(body?.password_policy?.rules);
             const tokenInvalid = body?.reset_token_invalid === true;
-            const err = new Error(resetFailureText(res.status, rules, policy, tokenInvalid));
+            // PAY-2103: a breached password is its own outcome, not a policy refusal.
+            const breached = body?.password_breached === true;
+            const err = new Error(breached ? exports.RESET_BREACHED_TEXT : resetFailureText(res.status, rules, policy, tokenInvalid));
             if (rules.length)
                 err.rules = rules;
             if ((res.status === 400 || res.status === 422) && tokenInvalid && !policy)

package/dist/vibe/sessions.d.ts

@@ -144,8 +144,95 @@ export declare function isSessionValid(sessionId: number, accessToken: string):
  * @param accessToken - Access token for auth
  * @param sessionTokenHash - Optional token hash to check specific session
  * @returns Revoked session info if enforcement needed, null otherwise
+ *
+ * @deprecated PAY-2037 step 1 (BAPert 69153): kept so no consumer breaks. It is a thin call into the
+ * same hash-first decision as getRevocationStatus; prefer getRevocationStatus, which distinguishes
+ * a failed read ('unknown') from 'active' instead of throwing.
+ */
+export declare function checkSessionRevocation(idpUserId: number, _accessToken: string, sessionTokenHash?: string): Promise<IVibeLoginSession | null>;
+/** The four states a viability producer can report (BAPert 66320). */
+export type RevocationStatus = 'active' | 'revoked' | 'unknown' | 'not_configured';
+/**
+ * Hash a session token the same way record-login stores it.
+ * SHA256 hex, 64 chars. This must stay byte-identical to
+ * `hashSessionToken` in the consumers (idealresume.online/lib/session-token-hash.ts)
+ * or per-session matching silently falls back to the user-wide path.
+ */
+export declare function hashSessionToken(token: string): string;
+/**
+ * BAPert 66480 condition 2 (ruling (ii), 66700; corrected per QAPert 66729):
+ * resolve the NUMERIC IdP user id the Vibe query filters on.
+ *
+ * *** DO NOT READ `sub` FOR THE USER ID. *** In the IdP's bearer token `sub` is the
+ * USERNAME, not the id: AESGCM_Encryption.cs:815 writes `{ "sub", payload.Username }`
+ * and :822 writes `{ "user_id", payload.UserId.ToString() }`. A username is commonly
+ * an email, so reading `sub` yields 0 for the common case - and for a username that
+ * happens to be all digits it yields the WRONG id, which getRevocationStatus answers
+ * 'active' for a user with no rows: a fail-OPEN.
+ *
+ * Resolution order:
+ *   1. the token's `user_id` claim, when it is all digits;
+ *   2. a digits-only session.userId / session.user.id;
+ *   3. otherwise 0 (unresolvable), which the caller reports as 'unknown' (fail closed).
+ *
+ * session.userId is not a safe source on its own either: session-store.ts:143 falls
+ * back to user.email, and better-auth.ts stringifies whichever id it finds.
+ */
+export declare function resolveNumericIdpUserId(session: unknown, accessToken?: string): number;
+/**
+ * Public entry point for the twins: call this when a session exists but its
+ * userId is not a usable numeric IdP id. Returns 'unknown' (fail closed) and
+ * emits the once-per-session WARN. Shape only, never the value.
+ */
+export declare function warnNonNumericUserId(sessionToken: string | undefined, rawUserId: unknown): 'unknown';
+/**
+ * HMAC-ONLY session read for the revocation check (PAY-1882 step 4).
+ *
+ * *** DO NOT "SIMPLIFY" THIS ONTO vibeProxyRequest/getUserSessions. ***
+ * It is deliberately separate and deliberately sends NO Authorization header.
+ *
+ * WHY: the twin this must match is idealresume.online's checkSessionRevocation
+ * read. That repo's vibe-client adds `Authorization: Bearer` ONLY for member
+ * paths (`path.startsWith('/v1/my/')`) - see idealresume.online/lib/vibe-client.ts
+ * :207-210 - so its /v1/collections/.../query for this check goes out HMAC-only.
+ * The comment at vibe-client.ts:188-206 there records why: a bearer on the
+ * collections path caused USER_REQUIRED and broke signups. getUserSessions()
+ * here ALWAYS sends the bearer, so it cannot stand in for this read without
+ * changing the credential the two twins are supposed to share.
+ *
+ * BAPert 66344 (option a): match the twin, HMAC-only.
+ *
+ * Also distinguishes a FAILED read from an EMPTY one - getUserSessions()
+ * collapses a proxy outage and "user has no sessions" to `[]`, which is
+ * fail-OPEN for a revocation decision. Returns `ok:false` on an outage so the
+ * caller fails closed, and `ok:true, sessions:[]` only for a healthy empty.
+ */
+export declare function readSessionRevocationHmac(idpUserId: number): Promise<{
+    ok: boolean;
+    sessions: IVibeLoginSession[];
+}>;
+/**
+ * Determine whether a session is revoked, with an explicit UNKNOWN state
+ * (PAY-1882 step 4 producer half).
+ *
+ * States:
+ *   'not_configured' - this deployment has no revocation source (IDP_URL /
+ *                      VIBE_CLIENT_ID / VIBE_HMAC_KEY absent). Viable; today's
+ *                      behaviour. Logged once, not per request.
+ *   'unknown'        - revocation IS configured but the read FAILED (non-OK,
+ *                      timeout, throw). Enforcing middleware fails this CLOSED
+ *                      by default (revocationFailMode 'closed'); a Vibe-less
+ *                      consumer is 'not_configured', not 'unknown', so it is not
+ *                      signed out.
+ *   'revoked'        - the session's own token hash matches a revoked row, or
+ *                      the user has no active session at all.
+ *   'active'         - read OK and the session is not revoked.
+ *
+ * @param idpUserId - The user's IDP ID
+ * @param sessionToken - The live session token; hashed to match the stored row.
+ *                       When absent, the user-wide check applies (legacy path).
  */
-export declare function checkSessionRevocation(idpUserId: number, accessToken: string, sessionTokenHash?: string): Promise<IVibeLoginSession | null>;
+export declare function getRevocationStatus(idpUserId: number, sessionToken?: string): Promise<RevocationStatus>;
 /**
  * Get session statistics for admin dashboard.
  *