@payez/next-mvp 4.4.8 → 4.5.0

package/README.md

@@ -256,6 +256,59 @@ export default function VerifyCodePageWrapper() {
 }
 ```
 
+#### What your app must serve (PAY-2121)
+
+The IdP emails links that land on paths your app must host. Two of them are
+conventions the kit mounts for you; wire them or the link 404s at your site:
+
+**Invitation / onboarding** - `app/account-auth/onboarding/page.tsx`:
+
+```typescript
+// The IdP's welcome email links to
+//   {your site}/account-auth/onboarding?client_id=&onboard_token=
+export { default } from '@payez/next-mvp/pages/onboarding';
+```
+
+and the API it posts to (token-driven, no session) - one mount file each:
+
+```typescript
+// app/api/onboarding/verify-code/route.ts
+export { POST } from '@payez/next-mvp/routes/onboarding/verify-code';
+// app/api/onboarding/send-email-code/route.ts
+export { POST } from '@payez/next-mvp/routes/onboarding/send-email-code';
+// app/api/onboarding/verify-welcome-email/route.ts
+export { POST } from '@payez/next-mvp/routes/onboarding/verify-welcome-email';
+// app/api/onboarding/set-password/route.ts
+export { POST } from '@payez/next-mvp/routes/onboarding/set-password';
+```
+
+**Post-verify reset fragment on `/`** - mount the bridge on your home page:
+
+```typescript
+// app/page.tsx
+import { PasswordResetBridge } from '@payez/next-mvp/components/auth/PasswordResetBridge';
+
+export default function Home() {
+  return (<><PasswordResetBridge />{/* your home page */}</>);
+}
+```
+
+When the IdP's verification redirect lands on `/#password_reset_required=true&reset_token=…&email=…`
+(a fragment, for a passwordless account), the bridge performs one replace to
+`/account-auth/recovery?token=…&email=…` and clears the hash. With any other
+fragment it renders nothing. `npx @payez/create-next-app` writes all of the above.
+
+**Registration** has two doors, and the kit ships neither as a page:
+
+- **Owner-initiated invite** (shipped here): an existing owner invites a user; the invite
+  email lands on `/account-auth/onboarding` (above), which the kit now serves.
+- **Self-serve sign-up**: the kit exposes the IdP's ProgressiveAuth flow as API endpoints
+  (`/api/ProgressiveAuth/step1`..`step5`, then `/api/ProgressiveAuth/verify-email`;
+  `API_ENDPOINTS.progressiveAuth` in `config/env.ts`). The kit ships **no** registration
+  page, so a developer who wants self-serve sign-up authors a page that drives that flow,
+  respecting the tenant's `allow_public_registration` / waitlist state. The login page no
+  longer links a register page, because the kit does not ship one.
+
 ### 6. Protect Routes with Authentication
 
 **Server-side protection:**

package/dist/api-handlers/account/reset-password.js

@@ -72,7 +72,9 @@ async function POST(req) {
         if (!upstream.ok) {
             // PAY-1591: a password-policy refusal also carries the KNOWN rule codes so the page can say which rules failed.
             const rules = (0, safe_error_response_1.projectPasswordPolicyRules)(data);
-            return server_1.NextResponse.json({ ...(0, safe_error_response_1.idpErrorEnvelope)(data, 'Failed to reset password'), ...(rules !== undefined ? { password_policy: { rules } } : {}), ...((0, safe_error_response_1.projectResetTokenInvalid)(data) ? { reset_token_invalid: true } : {}) }, { status: upstream.status });
+            // PAY-2103: a breached-password refusal is a distinct 400; project a BOOLEAN so the anonymous
+            // route carries no code text and the page picks its own sentence.
+            return server_1.NextResponse.json({ ...(0, safe_error_response_1.idpErrorEnvelope)(data, 'Failed to reset password'), ...(rules !== undefined ? { password_policy: { rules } } : {}), ...((0, safe_error_response_1.projectResetTokenInvalid)(data) ? { reset_token_invalid: true } : {}), ...((0, safe_error_response_1.projectPasswordBreached)(data) ? { password_breached: true } : {}) }, { status: upstream.status });
         }
         return server_1.NextResponse.json(data, { status: upstream.status });
     }

package/dist/api-handlers/onboarding/send-email-code.d.ts

@@ -0,0 +1,11 @@
+/**
+ * POST /api/onboarding/send-email-code (PAY-2121).
+ *
+ * Body: { onboard_token } - token-driven, no session. Thin proxy to the IdP's
+ * POST /api/Onboarding/send-email-code. The IdP derives the recipient from the
+ * token's BOUND email only, never from client input, so a tampered link cannot
+ * redirect the code. Also the resend leg the verify card's cooldown fires
+ * against.
+ */
+import { NextRequest } from 'next/server';
+export declare function POST(req: NextRequest): Promise<import("next/server").NextResponse<unknown>>;

package/dist/api-handlers/onboarding/send-email-code.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = POST;
+const onboarding_proxy_1 = require("../../lib/onboarding-proxy");
+async function POST(req) {
+    const body = await req.json().catch(() => ({}));
+    const onboardToken = body?.onboard_token;
+    if (!onboardToken)
+        return (0, onboarding_proxy_1.onboardingBadRequest)('MISSING_TOKEN', 'onboard_token is required');
+    return (0, onboarding_proxy_1.onboardingProxy)(req, '/api/Onboarding/send-email-code');
+}

package/dist/api-handlers/onboarding/set-password.d.ts

@@ -0,0 +1,12 @@
+/**
+ * POST /api/onboarding/set-password (PAY-2121).
+ *
+ * Body: { onboard_token, email, reset_token, new_password } - the locked
+ * contract (IdP OnboardingDtos.cs SetPasswordRequest, all four snake_case).
+ * email + reset_token come from the verify-code response; the IdP re-checks
+ * email against the token's bound user before consuming the single-use token.
+ * On success the IdP sets the password AND completes onboarding (issues tokens).
+ * Thin proxy - status and body pass through verbatim.
+ */
+import { NextRequest } from 'next/server';
+export declare function POST(req: NextRequest): Promise<import("next/server").NextResponse<unknown>>;

package/dist/api-handlers/onboarding/set-password.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = POST;
+const onboarding_proxy_1 = require("../../lib/onboarding-proxy");
+async function POST(req) {
+    const body = await req.json().catch(() => ({}));
+    const b = body;
+    if (!b?.onboard_token)
+        return (0, onboarding_proxy_1.onboardingBadRequest)('MISSING_TOKEN', 'onboard_token is required');
+    if (!b?.email || !b?.reset_token)
+        return (0, onboarding_proxy_1.onboardingBadRequest)('MISSING_RESET_CONTEXT', 'email and reset_token (from verify-code) are required');
+    if (!b?.new_password)
+        return (0, onboarding_proxy_1.onboardingBadRequest)('MISSING_PASSWORD', 'new_password is required');
+    return (0, onboarding_proxy_1.onboardingProxy)(req, '/api/Onboarding/set-password');
+}

package/dist/api-handlers/onboarding/verify-code.d.ts

@@ -0,0 +1,11 @@
+/**
+ * POST /api/onboarding/verify-code (PAY-2121).
+ *
+ * Body: { onboard_token, code } - token-driven, no session. Thin proxy to the
+ * IdP's POST /api/Onboarding/verify-code, which answers
+ * { success, reset_token, email, client_key } on success (OnboardingDtos.cs
+ * VerifyCodeResponse). reset_token + email are what the set-password step needs
+ * next. The onboard_token IS the auth; there is no session to attach.
+ */
+import { NextRequest } from 'next/server';
+export declare function POST(req: NextRequest): Promise<import("next/server").NextResponse<unknown>>;

package/dist/api-handlers/onboarding/verify-code.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = POST;
+const onboarding_proxy_1 = require("../../lib/onboarding-proxy");
+async function POST(req) {
+    const body = await req.json().catch(() => ({}));
+    const onboardToken = body?.onboard_token;
+    const code = body?.code;
+    if (!onboardToken)
+        return (0, onboarding_proxy_1.onboardingBadRequest)('MISSING_TOKEN', 'onboard_token is required');
+    if (!code)
+        return (0, onboarding_proxy_1.onboardingBadRequest)('MISSING_CODE', 'code is required');
+    return (0, onboarding_proxy_1.onboardingProxy)(req, '/api/Onboarding/verify-code');
+}

package/dist/api-handlers/onboarding/verify-welcome-email.d.ts

@@ -0,0 +1,10 @@
+/**
+ * POST /api/onboarding/verify-welcome-email (PAY-2121).
+ *
+ * Body: { onboard_token } - token-driven, no session. Thin proxy to the IdP's
+ * POST /api/Onboarding/verify-welcome-email, which answers the masked contact
+ * info + expiry the verify card displays. The onboarding page calls this to
+ * render its "check your email / here is what we know" state.
+ */
+import { NextRequest } from 'next/server';
+export declare function POST(req: NextRequest): Promise<import("next/server").NextResponse<unknown>>;

package/dist/api-handlers/onboarding/verify-welcome-email.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = POST;
+const onboarding_proxy_1 = require("../../lib/onboarding-proxy");
+async function POST(req) {
+    const body = await req.json().catch(() => ({}));
+    const onboardToken = body?.onboard_token;
+    if (!onboardToken)
+        return (0, onboarding_proxy_1.onboardingBadRequest)('MISSING_TOKEN', 'onboard_token is required');
+    return (0, onboarding_proxy_1.onboardingProxy)(req, '/api/Onboarding/verify-welcome-email');
+}

package/dist/api-handlers/session/viability.js

@@ -12,6 +12,7 @@ const auth_1 = require("../../server/auth");
 const startup_init_1 = require("../../lib/startup-init");
 const idp_client_config_1 = require("../../lib/idp-client-config");
 const token_log_id_1 = require("../../lib/token-log-id");
+const sessions_1 = require("../../vibe/sessions");
 async function GET(req) {
     try {
         // Ensure initialization is complete (auth signing secret resolved from IDP)
@@ -124,12 +125,43 @@ async function GET(req) {
                         hoursExpiredAgo: ((Date.now() - mfaExpiresAt) / (1000 * 60 * 60)).toFixed(1)
                     });
                 }
+                // --- Session revocation status (PAY-1882 step 4 producer half) ---
+                // The four-state status (BAPert 66320). 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.
+                let revocationStatus = 'not_configured';
+                // 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)(sessionData, sessionData.idpAccessToken);
+                if (revocationUserId > 0) {
+                    try {
+                        revocationStatus = await (0, sessions_1.getRevocationStatus)(revocationUserId, sessionToken);
+                    }
+                    catch {
+                        // getRevocationStatus does not throw by contract; fail closed if it ever does.
+                        revocationStatus = 'unknown';
+                    }
+                }
+                else {
+                    // N1 (NightHawk 66392): a session EXISTS but its userId is not a usable
+                    // numeric IdP id, so the check could not be run. That is 'unknown'
+                    // (could not determine), NOT 'not_configured' (no revocation source) -
+                    // the two must not be conflated.
+                    // BAPert 66480 condition 1: emit ONE WARN (shape only) per session.
+                    revocationStatus = (0, sessions_1.warnNonNumericUserId)(sessionToken, sessionData.userId);
+                }
                 const response = {
                     authenticated: true,
                     sessionTokenId: (0, token_log_id_1.tokenLogId)(sessionToken), // PAY-1481: correlation id for middleware tracking, never the token
                     // 2FA fields - critical for middleware redirect logic
                     requires2FA, // From cached client config (client-wide setting)
                     twoFactorComplete: effectiveTwoFactorComplete, // From session, BUT respects MFA TTL
+                    // 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',
                     // Cards 141688/141741 — the IDP's routing decision, relayed verbatim.
                     //
                     // THIS IS THE SECOND IMPLEMENTATION OF VIABILITY. The other is

package/dist/auth/password-reset-bridge.d.ts

@@ -0,0 +1,70 @@
+/**
+ * PAY-2121: the fragment bridge on `/`.
+ *
+ * The IdP's post-verify redirect for a passwordless account lands on
+ *   ORIGIN/#password_reset_required=true&reset_token=<token>&email=<addr>
+ * - a FRAGMENT, never a query (ProgressiveAuthController.cs:1204-1222). A fresh
+ * @payez/next-mvp app has no fragment handling at all, so the user lands on `/`
+ * and nothing happens; their reset is lost.
+ *
+ * This is the PURE half (data in, data out) so a test can execute it without a
+ * DOM. The client component (PasswordResetBridge) calls it on mount with
+ * `window.location.hash`. The kit's reset surface is the existing
+ * `/account-auth/recovery` page, which reads `?email=` and a reset token - so the
+ * bridge rewrites the fragment into that surface's OWN query shape and navigates
+ * once. It invents no new reset flow.
+ *
+ * CONTRACT:
+ *   '#password_reset_required=true&reset_token=T&email=a%40b.co' -> '/account-auth/recovery?token=T&email=a%40b.co'
+ *   any other fragment (no flag, flag != true, no token) -> null (leave `/` alone)
+ */
+/** The reset surface the bridge hands off to, by its existing path. */
+export declare const RECOVERY_PATH = "/account-auth/recovery";
+/**
+ * PAY-2121 (BAPert 70576): the recovery page's ENTRY decision, as a pure function.
+ *
+ * The bridge now sends a VERIFIED passwordless user to
+ *   /account-auth/recovery?token=<reset_token>&email=<addr>
+ * with a REAL reset token in hand. If the page then showed its request-a-code
+ * step, it would throw that token away and the flow would still dead-end - just
+ * one page later. So when a token is present the page must start at the
+ * set-password step and submit straight through resetPasswordWithToken.
+ *
+ *   token present      -> { step: 'set-password', resetToken: <token> }
+ *   no token           -> { step: 'initiate',    resetToken: null }   (today's behaviour)
+ */
+export declare function recoveryEntry(token: string | null | undefined, email: string | null | undefined): {
+    step: 'set-password' | 'initiate';
+    resetToken: string | null;
+    email: string;
+};
+/**
+ * PAY-2121 (BAPert 70582): the set-password SUBMIT precondition, as a pure
+ * function. The old guard was `if (!passwordResetToken || !recoverySession) return;`.
+ * Removing the session half (so a deep-linked reset can submit) must NOT let a
+ * submit with NO token reach the API carrying an empty token - which is exactly
+ * what a guard-less submit would do. This decides it, in one testable place:
+ *
+ *   resetSubmitTarget(resetToken, sessionEmail, queryEmail):
+ *     - no token (after trim)          -> null   (REFUSE: never call the API with an empty token)
+ *     - token, session email present   -> { token, email: sessionEmail }
+ *     - token, only a query email      -> { token, email: queryEmail }  (the deep-link case)
+ *     - token, but NO email anywhere    -> null   (REFUSE: nothing to reset)
+ *
+ * Returns the exact { token, email } the caller must pass to
+ * accountApi.resetPasswordWithToken, or null to refuse BEFORE any request.
+ */
+export declare function resetSubmitTarget(resetToken: string | null | undefined, sessionEmail: string | null | undefined, queryEmail: string | null | undefined): {
+    token: string;
+    email: string;
+} | null;
+/**
+ * The redirect the fragment asks for, or null when the fragment is not a reset
+ * request. `hash` is `window.location.hash` (leading '#' optional).
+ *
+ * Returns null - leaves `/` untouched - when:
+ *   - the fragment is empty;
+ *   - `password_reset_required` is absent or not exactly 'true';
+ *   - no `reset_token` is present (nothing to reset with; not a real link).
+ */
+export declare function passwordResetRedirect(hash: string | null | undefined): string | null;

package/dist/auth/password-reset-bridge.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * PAY-2121: the fragment bridge on `/`.
+ *
+ * The IdP's post-verify redirect for a passwordless account lands on
+ *   ORIGIN/#password_reset_required=true&reset_token=<token>&email=<addr>
+ * - a FRAGMENT, never a query (ProgressiveAuthController.cs:1204-1222). A fresh
+ * @payez/next-mvp app has no fragment handling at all, so the user lands on `/`
+ * and nothing happens; their reset is lost.
+ *
+ * This is the PURE half (data in, data out) so a test can execute it without a
+ * DOM. The client component (PasswordResetBridge) calls it on mount with
+ * `window.location.hash`. The kit's reset surface is the existing
+ * `/account-auth/recovery` page, which reads `?email=` and a reset token - so the
+ * bridge rewrites the fragment into that surface's OWN query shape and navigates
+ * once. It invents no new reset flow.
+ *
+ * CONTRACT:
+ *   '#password_reset_required=true&reset_token=T&email=a%40b.co' -> '/account-auth/recovery?token=T&email=a%40b.co'
+ *   any other fragment (no flag, flag != true, no token) -> null (leave `/` alone)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RECOVERY_PATH = void 0;
+exports.recoveryEntry = recoveryEntry;
+exports.resetSubmitTarget = resetSubmitTarget;
+exports.passwordResetRedirect = passwordResetRedirect;
+/** The reset surface the bridge hands off to, by its existing path. */
+exports.RECOVERY_PATH = '/account-auth/recovery';
+/**
+ * PAY-2121 (BAPert 70576): the recovery page's ENTRY decision, as a pure function.
+ *
+ * The bridge now sends a VERIFIED passwordless user to
+ *   /account-auth/recovery?token=<reset_token>&email=<addr>
+ * with a REAL reset token in hand. If the page then showed its request-a-code
+ * step, it would throw that token away and the flow would still dead-end - just
+ * one page later. So when a token is present the page must start at the
+ * set-password step and submit straight through resetPasswordWithToken.
+ *
+ *   token present      -> { step: 'set-password', resetToken: <token> }
+ *   no token           -> { step: 'initiate',    resetToken: null }   (today's behaviour)
+ */
+function recoveryEntry(token, email) {
+    const tok = (token ?? '').trim();
+    return {
+        step: tok ? 'set-password' : 'initiate',
+        resetToken: tok || null,
+        email: (email ?? '').trim(),
+    };
+}
+/**
+ * PAY-2121 (BAPert 70582): the set-password SUBMIT precondition, as a pure
+ * function. The old guard was `if (!passwordResetToken || !recoverySession) return;`.
+ * Removing the session half (so a deep-linked reset can submit) must NOT let a
+ * submit with NO token reach the API carrying an empty token - which is exactly
+ * what a guard-less submit would do. This decides it, in one testable place:
+ *
+ *   resetSubmitTarget(resetToken, sessionEmail, queryEmail):
+ *     - no token (after trim)          -> null   (REFUSE: never call the API with an empty token)
+ *     - token, session email present   -> { token, email: sessionEmail }
+ *     - token, only a query email      -> { token, email: queryEmail }  (the deep-link case)
+ *     - token, but NO email anywhere    -> null   (REFUSE: nothing to reset)
+ *
+ * Returns the exact { token, email } the caller must pass to
+ * accountApi.resetPasswordWithToken, or null to refuse BEFORE any request.
+ */
+function resetSubmitTarget(resetToken, sessionEmail, queryEmail) {
+    const tok = (resetToken ?? '').trim();
+    if (!tok)
+        return null;
+    const email = ((sessionEmail ?? '').trim() || (queryEmail ?? '').trim());
+    if (!email)
+        return null;
+    return { token: tok, email };
+}
+/**
+ * The redirect the fragment asks for, or null when the fragment is not a reset
+ * request. `hash` is `window.location.hash` (leading '#' optional).
+ *
+ * Returns null - leaves `/` untouched - when:
+ *   - the fragment is empty;
+ *   - `password_reset_required` is absent or not exactly 'true';
+ *   - no `reset_token` is present (nothing to reset with; not a real link).
+ */
+function passwordResetRedirect(hash) {
+    const raw = (hash ?? '').replace(/^#/, '');
+    if (!raw)
+        return null;
+    const params = new URLSearchParams(raw);
+    if (params.get('password_reset_required') !== 'true')
+        return null;
+    const token = params.get('reset_token') ?? '';
+    if (!token)
+        return null;
+    const email = params.get('email') ?? '';
+    const qs = new URLSearchParams({ token });
+    if (email)
+        qs.set('email', email);
+    return `${exports.RECOVERY_PATH}?${qs.toString()}`;
+}

package/dist/auth/route-config.js

@@ -46,6 +46,23 @@ const defaultUnauthenticatedRoutes = [
         allowDuringCircuitBreakerOpen: true,
         requiresRateLimit: false
     },
+    // PAY-2121: the IdP emails an invite link to /account-auth/onboarding and a
+    // post-verify reset FRAGMENT on '/'. Both must be reachable unauthenticated -
+    // the invitee has no session (the onboard_token IS the credential), and the
+    // fragment lands on the already-public root. Listed explicitly, not left to
+    // the /account-auth/* wildcard, so the two conventional paths are visible here.
+    {
+        pattern: '/account-auth/onboarding',
+        description: 'IdP invite/onboarding landing page (token-driven, no session)',
+        allowDuringCircuitBreakerOpen: true,
+        requiresRateLimit: false
+    },
+    {
+        pattern: '/api/onboarding/*',
+        description: 'Onboarding API (token-driven, no session)',
+        allowDuringCircuitBreakerOpen: true,
+        requiresRateLimit: true
+    },
     {
         pattern: '/api/auth/*',
         description: 'Authentication API endpoints',

package/dist/components/auth/FederatedAuthSection.js

@@ -3,31 +3,54 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FederatedAuthSection = FederatedAuthSection;
 const jsx_runtime_1 = require("react/jsx-runtime");
+/**
+ * PAY-2104 — PER-PROVIDER BRAND TREATMENT, NOT ONE GENERIC BUTTON.
+ *
+ * Apple and Facebook both publish binding rules for their sign-in buttons and
+ * neither is satisfied by the generic "Continue with X" control this section
+ * used to render for every provider:
+ *   - APPLE (App Store Review Guidelines 4.8 / "Sign in with Apple" HIG): the
+ *     button MUST carry the Apple logo and one of Apple's own wordings. The
+ *     approved primary wording is "Sign in with Apple" ("Continue with Apple"
+ *     is the permitted alternative). "Continue with Apple" with no logo, which
+ *     is what the generic path produced, is non-compliant and is what App Store
+ *     review rejects. Black or white only.
+ *   - FACEBOOK (Meta Platform Terms / brand guidelines): "Continue with
+ *     Facebook", the Facebook "f" mark, and the brand blue (#1877F2) or white
+ *     are the sanctioned treatments.
+ * Google/Microsoft/GitHub keep the neutral control — they impose no such rule,
+ * and inventing brand colours for them would be a change nobody asked for.
+ *
+ * The mark inherits `currentColor` so it is legible on both the white neutral
+ * buttons and the black/blue branded ones without a second SVG per provider.
+ */
+const PROVIDER_BRAND = {
+    google: { label: 'Continue with Google', background: 'var(--bg-default, #ffffff)', color: 'var(--text-primary, #111827)', border: 'var(--border-default, #e5e7eb)' },
+    microsoft: { label: 'Continue with Microsoft', background: 'var(--bg-default, #ffffff)', color: 'var(--text-primary, #111827)', border: 'var(--border-default, #e5e7eb)' },
+    github: { label: 'Continue with GitHub', background: 'var(--bg-default, #ffffff)', color: 'var(--text-primary, #111827)', border: 'var(--border-default, #e5e7eb)' },
+    // Meta brand blue; white mark on blue, per the brand guidelines.
+    facebook: { label: 'Continue with Facebook', background: '#1877F2', color: '#ffffff', border: '#1877F2' },
+    // Apple HIG: black (or white) field, "Sign in with Apple", Apple logo.
+    apple: { label: 'Sign in with Apple', background: '#000000', color: '#ffffff', border: '#000000' },
+};
 const providerIcons = {
     google: {
-        label: 'Google',
-        color: '#4285F4',
-        svg: ((0, jsx_runtime_1.jsxs)("svg", { className: "w-5 h-5", viewBox: "0 0 24 24", fill: "currentColor", children: [(0, jsx_runtime_1.jsx)("path", { d: "M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z", fill: "#4285F4" }), (0, jsx_runtime_1.jsx)("path", { d: "M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z", fill: "#34A853" }), (0, jsx_runtime_1.jsx)("path", { d: "M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z", fill: "#FBBC05" }), (0, jsx_runtime_1.jsx)("path", { d: "M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z", fill: "#EA4335" })] })),
+        svg: ((0, jsx_runtime_1.jsxs)("svg", { className: "w-5 h-5", viewBox: "0 0 24 24", fill: "currentColor", "aria-hidden": "true", children: [(0, jsx_runtime_1.jsx)("path", { d: "M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z", fill: "#4285F4" }), (0, jsx_runtime_1.jsx)("path", { d: "M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z", fill: "#34A853" }), (0, jsx_runtime_1.jsx)("path", { d: "M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z", fill: "#FBBC05" }), (0, jsx_runtime_1.jsx)("path", { d: "M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z", fill: "#EA4335" })] })),
     },
     microsoft: {
-        label: 'Microsoft',
-        color: '#0078D4',
-        svg: ((0, jsx_runtime_1.jsxs)("svg", { className: "w-5 h-5", viewBox: "0 0 24 24", fill: "currentColor", children: [(0, jsx_runtime_1.jsx)("rect", { x: "1", y: "1", width: "9", height: "9", fill: "#F25022" }), (0, jsx_runtime_1.jsx)("rect", { x: "12", y: "1", width: "9", height: "9", fill: "#7FBA00" }), (0, jsx_runtime_1.jsx)("rect", { x: "1", y: "12", width: "9", height: "9", fill: "#00A4EF" }), (0, jsx_runtime_1.jsx)("rect", { x: "12", y: "12", width: "9", height: "9", fill: "#FFB900" })] })),
+        svg: ((0, jsx_runtime_1.jsxs)("svg", { className: "w-5 h-5", viewBox: "0 0 24 24", fill: "currentColor", "aria-hidden": "true", children: [(0, jsx_runtime_1.jsx)("rect", { x: "1", y: "1", width: "9", height: "9", fill: "#F25022" }), (0, jsx_runtime_1.jsx)("rect", { x: "12", y: "1", width: "9", height: "9", fill: "#7FBA00" }), (0, jsx_runtime_1.jsx)("rect", { x: "1", y: "12", width: "9", height: "9", fill: "#00A4EF" }), (0, jsx_runtime_1.jsx)("rect", { x: "12", y: "12", width: "9", height: "9", fill: "#FFB900" })] })),
     },
     facebook: {
-        label: 'Facebook',
-        color: '#1877F2',
-        svg: ((0, jsx_runtime_1.jsx)("svg", { className: "w-5 h-5", viewBox: "0 0 24 24", fill: "#1877F2", children: (0, jsx_runtime_1.jsx)("path", { d: "M24 12.073c0-6.627-5.373-12-12-12s-12 5.373-12 12c0 5.99 4.388 10.954 10.125 11.854v-8.385H7.078v-3.47h3.047V9.43c0-3.007 1.792-4.669 4.533-4.669 1.312 0 2.686.235 2.686.235v2.953H15.83c-1.491 0-1.956.925-1.956 1.874v2.25h3.328l-.532 3.47h-2.796v8.385C19.612 23.027 24 18.062 24 12.073z" }) })),
+        // currentColor: white on the Meta-blue button. A hardcoded #1877F2 fill on a
+        // #1877F2 field is an invisible mark — the exact way a branded button ships
+        // looking like a blank one.
+        svg: ((0, jsx_runtime_1.jsx)("svg", { className: "w-5 h-5", viewBox: "0 0 24 24", fill: "currentColor", "aria-hidden": "true", children: (0, jsx_runtime_1.jsx)("path", { d: "M24 12.073c0-6.627-5.373-12-12-12s-12 5.373-12 12c0 5.99 4.388 10.954 10.125 11.854v-8.385H7.078v-3.47h3.047V9.43c0-3.007 1.792-4.669 4.533-4.669 1.312 0 2.686.235 2.686.235v2.953H15.83c-1.491 0-1.956.925-1.956 1.874v2.25h3.328l-.532 3.47h-2.796v8.385C19.612 23.027 24 18.062 24 12.073z" }) })),
     },
     github: {
-        label: 'GitHub',
-        color: '#000000',
-        svg: ((0, jsx_runtime_1.jsx)("svg", { className: "w-5 h-5", viewBox: "0 0 24 24", fill: "currentColor", children: (0, jsx_runtime_1.jsx)("path", { d: "M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z" }) })),
+        svg: ((0, jsx_runtime_1.jsx)("svg", { className: "w-5 h-5", viewBox: "0 0 24 24", fill: "currentColor", "aria-hidden": "true", children: (0, jsx_runtime_1.jsx)("path", { d: "M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z" }) })),
     },
     apple: {
-        label: 'Apple',
-        color: '#000000',
-        svg: ((0, jsx_runtime_1.jsx)("svg", { className: "w-5 h-5", viewBox: "0 0 24 24", fill: "currentColor", children: (0, jsx_runtime_1.jsx)("path", { d: "M17.05 20.28c-.98.95-2.05.8-3.08.35-1.09-.46-2.09-.48-3.24 0-1.44.62-2.2.44-3.06-.35C2.79 15.25 3.51 7.59 9.05 7.31c1.35.07 2.29.74 3.08.8 1.18-.24 2.31-.93 3.57-.84 1.51.12 2.65.72 3.4 1.8-3.12 1.87-2.38 5.98.48 7.13-.57 1.5-1.31 2.99-2.54 4.09l.01-.01zM12.03 7.25c-.15-2.23 1.66-4.07 3.74-4.25.29 2.58-2.34 4.5-3.74 4.25z" }) })),
+        svg: ((0, jsx_runtime_1.jsx)("svg", { className: "w-5 h-5", viewBox: "0 0 24 24", fill: "currentColor", "aria-hidden": "true", children: (0, jsx_runtime_1.jsx)("path", { d: "M17.05 20.28c-.98.95-2.05.8-3.08.35-1.09-.46-2.09-.48-3.24 0-1.44.62-2.2.44-3.06-.35C2.79 15.25 3.51 7.59 9.05 7.31c1.35.07 2.29.74 3.08.8 1.18-.24 2.31-.93 3.57-.84 1.51.12 2.65.72 3.4 1.8-3.12 1.87-2.38 5.98.48 7.13-.57 1.5-1.31 2.99-2.54 4.09l.01-.01zM12.03 7.25c-.15-2.23 1.66-4.07 3.74-4.25.29 2.58-2.34 4.5-3.74 4.25z" }) })),
     },
 };
 function FederatedAuthSection({ providers, onProviderClick, isLoading }) {
@@ -35,11 +58,17 @@ function FederatedAuthSection({ providers, onProviderClick, isLoading }) {
         return null;
     }
     return ((0, jsx_runtime_1.jsx)("div", { className: "space-y-3", children: providers.map((provider) => {
-            const config = providerIcons[provider];
-            return ((0, jsx_runtime_1.jsxs)("button", { type: "button", onClick: () => onProviderClick(provider), disabled: isLoading, className: `w-full px-4 py-3 rounded-lg border-2 font-semibold transition-colors flex items-center justify-center gap-2 disabled:opacity-50 disabled:cursor-not-allowed`, style: {
-                    border: '1px solid var(--border-default)',
-                    color: 'var(--text-primary)',
-                    background: 'var(--bg-default)',
-                }, children: [config.svg, "Continue with ", config.label] }, provider));
+            const icon = providerIcons[provider];
+            const brand = PROVIDER_BRAND[provider] ?? {
+                label: `Continue with ${provider}`,
+                background: 'var(--bg-default, #ffffff)',
+                color: 'var(--text-primary, #111827)',
+                border: 'var(--border-default, #e5e7eb)',
+            };
+            return ((0, jsx_runtime_1.jsxs)("button", { type: "button", onClick: () => onProviderClick(provider), disabled: isLoading, "data-provider": provider, className: `w-full px-4 py-3 rounded-lg border-2 font-semibold transition-colors flex items-center justify-center gap-2 disabled:opacity-50 disabled:cursor-not-allowed`, style: {
+                    border: `1px solid ${brand.border}`,
+                    color: brand.color,
+                    background: brand.background,
+                }, children: [icon.svg, brand.label] }, provider));
         }) }));
 }

package/dist/components/auth/PasswordResetBridge.d.ts

@@ -0,0 +1,17 @@
+/**
+ * PAY-2121: mount this once on your app's `/` page. When the IdP's post-verify
+ * redirect lands on `/#password_reset_required=true&reset_token=<t>&email=<e>`
+ * (a FRAGMENT), this performs ONE replace to the kit's reset surface and clears
+ * the hash. With any other fragment it renders nothing and leaves `/` alone.
+ *
+ * It renders nothing and reads no user data - it only inspects the fragment.
+ *
+ * @example
+ * // app/page.tsx
+ * import { PasswordResetBridge } from '@payez/next-mvp/components/auth/PasswordResetBridge';
+ * export default function Home() {
+ *   return (&lt;&gt;&lt;PasswordResetBridge /&gt;&lt;/&gt;);
+ * }
+ */
+export declare function PasswordResetBridge(): null;
+export default PasswordResetBridge;

package/dist/components/auth/PasswordResetBridge.js

@@ -0,0 +1,32 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PasswordResetBridge = PasswordResetBridge;
+const react_1 = require("react");
+const password_reset_bridge_1 = require("../../auth/password-reset-bridge");
+/**
+ * PAY-2121: mount this once on your app's `/` page. When the IdP's post-verify
+ * redirect lands on `/#password_reset_required=true&reset_token=<t>&email=<e>`
+ * (a FRAGMENT), this performs ONE replace to the kit's reset surface and clears
+ * the hash. With any other fragment it renders nothing and leaves `/` alone.
+ *
+ * It renders nothing and reads no user data - it only inspects the fragment.
+ *
+ * @example
+ * // app/page.tsx
+ * import { PasswordResetBridge } from '@payez/next-mvp/components/auth/PasswordResetBridge';
+ * export default function Home() {
+ *   return (&lt;&gt;&lt;PasswordResetBridge /&gt;&lt;/&gt;);
+ * }
+ */
+function PasswordResetBridge() {
+    (0, react_1.useEffect)(() => {
+        if (typeof window === 'undefined')
+            return;
+        const target = (0, password_reset_bridge_1.passwordResetRedirect)(window.location.hash);
+        if (target)
+            window.location.replace(target);
+    }, []);
+    return null;
+}
+exports.default = PasswordResetBridge;