@spfn/auth 0.3.0-beta.2 → 0.3.0-beta.20

package/dist/nextjs/client.js

@@ -2,7 +2,27 @@
 
 // src/nextjs/components/oauth-callback.tsx
 import { useEffect, useState } from "react";
+
+// src/lib/return-path.ts
+var URL_STRIPPED_CHARACTER = /[\t\n\r]/;
+function isSafeReturnPath(returnPath) {
+  if (!returnPath.startsWith("/")) {
+    return false;
+  }
+  if (returnPath.startsWith("//") || returnPath.includes("\\")) {
+    return false;
+  }
+  if (returnPath.includes("..") || URL_STRIPPED_CHARACTER.test(returnPath)) {
+    return false;
+  }
+  return !/^\/[^/?#]*:/.test(returnPath);
+}
+
+// src/nextjs/components/oauth-callback.tsx
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+function toSafePath(value) {
+  return value && isSafeReturnPath(value) ? value : "/";
+}
 function OAuthCallback({
   apiBasePath = "/api/rpc",
   loadingComponent,
@@ -18,7 +38,7 @@ function OAuthCallback({
         const params = new URLSearchParams(window.location.search);
         const userId = params.get("userId");
         const keyId = params.get("keyId");
-        const returnUrl = params.get("returnUrl") || "/";
+        const returnUrl = toSafePath(params.get("returnUrl"));
         const errorParam = params.get("error");
         if (errorParam) {
           throw new Error(errorParam);
@@ -46,7 +66,7 @@ function OAuthCallback({
         }
         const data = await response.json();
         onSuccess?.(userId);
-        window.location.href = data.returnUrl || returnUrl;
+        window.location.href = toSafePath(data.returnUrl || returnUrl);
       } catch (err) {
         const message = err instanceof Error ? err.message : "OAuth failed";
         setError(message);
@@ -75,6 +95,7 @@ function OAuthCallback({
   return null;
 }
 export {
-  OAuthCallback
+  OAuthCallback,
+  isSafeReturnPath
 };
 //# sourceMappingURL=client.js.map

package/dist/nextjs/client.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/nextjs/components/oauth-callback.tsx"],"sourcesContent":["'use client';\n\n/**\n * OAuthCallback Component\n *\n * OAuth 콜백 페이지용 클라이언트 컴포넌트\n * URL params에서 userId, keyId를 추출하여 oauthFinalize API 호출 후 returnUrl로 리다이렉트\n *\n * @example\n * ```tsx\n * // app/auth/callback/page.tsx\n * export { OAuthCallback as default } from '@spfn/auth/nextjs/client';\n * ```\n */\n\nimport { useEffect, useState } from 'react';\n\nexport interface OAuthCallbackProps\n{\n    /**\n     * API base path for RPC calls\n     * @default '/api/rpc'\n     */\n    apiBasePath?: string;\n\n    /**\n     * Custom loading component\n     */\n    loadingComponent?: React.ReactNode;\n\n    /**\n     * Custom error component\n     */\n    errorComponent?: (error: string) => React.ReactNode;\n\n    /**\n     * Callback after successful OAuth\n     */\n    onSuccess?: (userId: string) => void;\n\n    /**\n     * Callback on error\n     */\n    onError?: (error: string) => void;\n}\n\nexport function OAuthCallback({\n    apiBasePath = '/api/rpc',\n    loadingComponent,\n    errorComponent,\n    onSuccess,\n    onError,\n}: OAuthCallbackProps)\n{\n    const [error, setError] = useState<string | null>(null);\n    const [isLoading, setIsLoading] = useState(true);\n\n    useEffect(() =>\n    {\n        async function finalizeOAuth()\n        {\n            try\n            {\n                const params = new URLSearchParams(window.location.search);\n                const userId = params.get('userId');\n                const keyId = params.get('keyId');\n                const returnUrl = params.get('returnUrl') || '/';\n                const errorParam = params.get('error');\n\n                // Handle error from backend\n                if (errorParam)\n                {\n                    throw new Error(errorParam);\n                }\n\n                if (!userId || !keyId)\n                {\n                    throw new Error('Missing required parameters');\n                }\n\n                // Call oauthFinalize API\n                const response = await fetch(`${apiBasePath}/oauthFinalize`, {\n                    method: 'POST',\n                    headers: {\n                        'Content-Type': 'application/json',\n                    },\n                    credentials: 'include',\n                    body: JSON.stringify({\n                        body: {\n                            userId,\n                            keyId,\n                            returnUrl,\n                        },\n                    }),\n                });\n\n                if (!response.ok)\n                {\n                    const data = await response.json().catch(() => ({}));\n                    throw new Error(data.message || 'Failed to finalize OAuth');\n                }\n\n                const data = await response.json();\n\n                onSuccess?.(userId);\n\n                // Redirect to returnUrl\n                window.location.href = data.returnUrl || returnUrl;\n            }\n            catch (err)\n            {\n                const message = err instanceof Error ? err.message : 'OAuth failed';\n                setError(message);\n                setIsLoading(false);\n                onError?.(message);\n            }\n        }\n\n        finalizeOAuth();\n    }, [apiBasePath, onSuccess, onError]);\n\n    if (error)\n    {\n        if (errorComponent)\n        {\n            return <>{errorComponent(error)}</>;\n        }\n\n        return (\n            <div style={{ padding: '20px', textAlign: 'center' }}>\n                <h2>Authentication Error</h2>\n                <p style={{ color: 'red' }}>{error}</p>\n                <button onClick={() => window.location.href = '/'}>\n                    Go Home\n                </button>\n            </div>\n        );\n    }\n\n    if (isLoading)\n    {\n        if (loadingComponent)\n        {\n            return <>{loadingComponent}</>;\n        }\n\n        return (\n            <div style={{ padding: '20px', textAlign: 'center' }}>\n                <p>Completing authentication...</p>\n            </div>\n        );\n    }\n\n    return null;\n}\n\nexport default OAuthCallback;\n"],"mappings":";;;AAeA,SAAS,WAAW,gBAAgB;AA8GjB,wBAIP,YAJO;AA/EZ,SAAS,cAAc;AAAA,EAC1B,cAAc;AAAA,EACd;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACJ,GACA;AACI,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAwB,IAAI;AACtD,QAAM,CAAC,WAAW,YAAY,IAAI,SAAS,IAAI;AAE/C,YAAU,MACV;AACI,mBAAe,gBACf;AACI,UACA;AACI,cAAM,SAAS,IAAI,gBAAgB,OAAO,SAAS,MAAM;AACzD,cAAM,SAAS,OAAO,IAAI,QAAQ;AAClC,cAAM,QAAQ,OAAO,IAAI,OAAO;AAChC,cAAM,YAAY,OAAO,IAAI,WAAW,KAAK;AAC7C,cAAM,aAAa,OAAO,IAAI,OAAO;AAGrC,YAAI,YACJ;AACI,gBAAM,IAAI,MAAM,UAAU;AAAA,QAC9B;AAEA,YAAI,CAAC,UAAU,CAAC,OAChB;AACI,gBAAM,IAAI,MAAM,6BAA6B;AAAA,QACjD;AAGA,cAAM,WAAW,MAAM,MAAM,GAAG,WAAW,kBAAkB;AAAA,UACzD,QAAQ;AAAA,UACR,SAAS;AAAA,YACL,gBAAgB;AAAA,UACpB;AAAA,UACA,aAAa;AAAA,UACb,MAAM,KAAK,UAAU;AAAA,YACjB,MAAM;AAAA,cACF;AAAA,cACA;AAAA,cACA;AAAA,YACJ;AAAA,UACJ,CAAC;AAAA,QACL,CAAC;AAED,YAAI,CAAC,SAAS,IACd;AACI,gBAAMA,QAAO,MAAM,SAAS,KAAK,EAAE,MAAM,OAAO,CAAC,EAAE;AACnD,gBAAM,IAAI,MAAMA,MAAK,WAAW,0BAA0B;AAAA,QAC9D;AAEA,cAAM,OAAO,MAAM,SAAS,KAAK;AAEjC,oBAAY,MAAM;AAGlB,eAAO,SAAS,OAAO,KAAK,aAAa;AAAA,MAC7C,SACO,KACP;AACI,cAAM,UAAU,eAAe,QAAQ,IAAI,UAAU;AACrD,iBAAS,OAAO;AAChB,qBAAa,KAAK;AAClB,kBAAU,OAAO;AAAA,MACrB;AAAA,IACJ;AAEA,kBAAc;AAAA,EAClB,GAAG,CAAC,aAAa,WAAW,OAAO,CAAC;AAEpC,MAAI,OACJ;AACI,QAAI,gBACJ;AACI,aAAO,gCAAG,yBAAe,KAAK,GAAE;AAAA,IACpC;AAEA,WACI,qBAAC,SAAI,OAAO,EAAE,SAAS,QAAQ,WAAW,SAAS,GAC/C;AAAA,0BAAC,QAAG,kCAAoB;AAAA,MACxB,oBAAC,OAAE,OAAO,EAAE,OAAO,MAAM,GAAI,iBAAM;AAAA,MACnC,oBAAC,YAAO,SAAS,MAAM,OAAO,SAAS,OAAO,KAAK,qBAEnD;AAAA,OACJ;AAAA,EAER;AAEA,MAAI,WACJ;AACI,QAAI,kBACJ;AACI,aAAO,gCAAG,4BAAiB;AAAA,IAC/B;AAEA,WACI,oBAAC,SAAI,OAAO,EAAE,SAAS,QAAQ,WAAW,SAAS,GAC/C,8BAAC,OAAE,0CAA4B,GACnC;AAAA,EAER;AAEA,SAAO;AACX;","names":["data"]}
+{"version":3,"sources":["../../src/nextjs/components/oauth-callback.tsx","../../src/lib/return-path.ts"],"sourcesContent":["'use client';\n\n/**\n * OAuthCallback Component\n *\n * OAuth 콜백 페이지용 클라이언트 컴포넌트\n * URL params에서 userId, keyId를 추출하여 oauthFinalize API 호출 후 returnUrl로 리다이렉트\n *\n * @example\n * ```tsx\n * // app/auth/callback/page.tsx\n * export { OAuthCallback as default } from '@spfn/auth/nextjs/client';\n * ```\n */\n\nimport { useEffect, useState } from 'react';\n\nimport { isSafeReturnPath } from '../../lib/return-path';\n\n/**\n * The destination to navigate to, or `/` when the value would leave the app.\n *\n * Both the query parameter and the value echoed by `oauthFinalize` pass through\n * here. A callback URL is something a user can be handed, so neither is trusted\n * to be a path inside the app — without this an absolute URL in `?returnUrl=`\n * would make a genuine login end on someone else's origin.\n */\nfunction toSafePath(value: string | null | undefined): string\n{\n    return value && isSafeReturnPath(value) ? value : '/';\n}\n\nexport interface OAuthCallbackProps\n{\n    /**\n     * API base path for RPC calls\n     * @default '/api/rpc'\n     */\n    apiBasePath?: string;\n\n    /**\n     * Custom loading component\n     */\n    loadingComponent?: React.ReactNode;\n\n    /**\n     * Custom error component\n     */\n    errorComponent?: (error: string) => React.ReactNode;\n\n    /**\n     * Callback after successful OAuth\n     */\n    onSuccess?: (userId: string) => void;\n\n    /**\n     * Callback on error\n     */\n    onError?: (error: string) => void;\n}\n\nexport function OAuthCallback({\n    apiBasePath = '/api/rpc',\n    loadingComponent,\n    errorComponent,\n    onSuccess,\n    onError,\n}: OAuthCallbackProps)\n{\n    const [error, setError] = useState<string | null>(null);\n    const [isLoading, setIsLoading] = useState(true);\n\n    useEffect(() =>\n    {\n        async function finalizeOAuth()\n        {\n            try\n            {\n                const params = new URLSearchParams(window.location.search);\n                const userId = params.get('userId');\n                const keyId = params.get('keyId');\n                const returnUrl = toSafePath(params.get('returnUrl'));\n                const errorParam = params.get('error');\n\n                // Handle error from backend\n                if (errorParam)\n                {\n                    throw new Error(errorParam);\n                }\n\n                if (!userId || !keyId)\n                {\n                    throw new Error('Missing required parameters');\n                }\n\n                // Call oauthFinalize API\n                const response = await fetch(`${apiBasePath}/oauthFinalize`, {\n                    method: 'POST',\n                    headers: {\n                        'Content-Type': 'application/json',\n                    },\n                    credentials: 'include',\n                    body: JSON.stringify({\n                        body: {\n                            userId,\n                            keyId,\n                            returnUrl,\n                        },\n                    }),\n                });\n\n                if (!response.ok)\n                {\n                    const data = await response.json().catch(() => ({}));\n                    throw new Error(data.message || 'Failed to finalize OAuth');\n                }\n\n                const data = await response.json();\n\n                onSuccess?.(userId);\n\n                // Redirect to returnUrl\n                window.location.href = toSafePath(data.returnUrl || returnUrl);\n            }\n            catch (err)\n            {\n                const message = err instanceof Error ? err.message : 'OAuth failed';\n                setError(message);\n                setIsLoading(false);\n                onError?.(message);\n            }\n        }\n\n        finalizeOAuth();\n    }, [apiBasePath, onSuccess, onError]);\n\n    if (error)\n    {\n        if (errorComponent)\n        {\n            return <>{errorComponent(error)}</>;\n        }\n\n        return (\n            <div style={{ padding: '20px', textAlign: 'center' }}>\n                <h2>Authentication Error</h2>\n                <p style={{ color: 'red' }}>{error}</p>\n                <button onClick={() => window.location.href = '/'}>\n                    Go Home\n                </button>\n            </div>\n        );\n    }\n\n    if (isLoading)\n    {\n        if (loadingComponent)\n        {\n            return <>{loadingComponent}</>;\n        }\n\n        return (\n            <div style={{ padding: '20px', textAlign: 'center' }}>\n                <p>Completing authentication...</p>\n            </div>\n        );\n    }\n\n    return null;\n}\n\nexport default OAuthCallback;\n","/**\n * @spfn/auth - Return-path validation\n *\n * One rule for every flow that hands a caller-supplied destination back to the\n * browser: the verified-email signup link, the password reset link, and the\n * OAuth start/callback seams. Apps that build their own destination before\n * calling an auth route import the same function rather than writing a second\n * rule that drifts from this one.\n *\n * The module imports nothing on purpose — it is part of the client bundle\n * (`@spfn/auth/nextjs/client`), which must not pull server code in behind it.\n */\n\n/**\n * The characters a URL parser deletes from anywhere in its input before it reads\n * the input as a URL: ASCII tab, LF and CR (WHATWG URL, \"remove all ASCII tab or\n * newline\"). The rule below reads the value as written, so a value holding one of\n * them is not the value the browser parses — `/<tab>/evil.com` is read as the\n * protocol-relative `//evil.com` and lands on another origin. Refusing the three\n * outright also keeps a raw CR or LF out of any `Location` header the value\n * reaches, which is what would split that header in two.\n */\nconst URL_STRIPPED_CHARACTER = /[\\t\\n\\r]/;\n\n/**\n * Whether a return path can be handed back to the browser.\n *\n * Only a path within the app is allowed. The rejected shapes are the ones that\n * turn a return path into an open redirect: an absolute URL, a protocol-relative\n * `//host` that a browser reads as another origin, a backslash that some\n * browsers normalize into a slash, any `..` traversal, and any character a URL\n * parser strips before parsing (see above).\n *\n * The value is judged exactly as written: nothing is percent-decoded here. A\n * `/a%0d%0a` is therefore a path containing those six literal characters and is\n * accepted — no decoder downstream turns it back into header bytes.\n */\nexport function isSafeReturnPath(returnPath: string): boolean\n{\n    if (!returnPath.startsWith('/'))\n    {\n        return false;\n    }\n\n    if (returnPath.startsWith('//') || returnPath.includes('\\\\'))\n    {\n        return false;\n    }\n\n    if (returnPath.includes('..') || URL_STRIPPED_CHARACTER.test(returnPath))\n    {\n        return false;\n    }\n\n    // A path cannot carry a protocol prefix; `/\\thttps:` and friends are caught\n    // above, this catches `/foo:bar` forms that some parsers read as an authority.\n    return !/^\\/[^/?#]*:/.test(returnPath);\n}\n"],"mappings":";;;AAeA,SAAS,WAAW,gBAAgB;;;ACOpC,IAAM,yBAAyB;AAexB,SAAS,iBAAiB,YACjC;AACI,MAAI,CAAC,WAAW,WAAW,GAAG,GAC9B;AACI,WAAO;AAAA,EACX;AAEA,MAAI,WAAW,WAAW,IAAI,KAAK,WAAW,SAAS,IAAI,GAC3D;AACI,WAAO;AAAA,EACX;AAEA,MAAI,WAAW,SAAS,IAAI,KAAK,uBAAuB,KAAK,UAAU,GACvE;AACI,WAAO;AAAA,EACX;AAIA,SAAO,CAAC,cAAc,KAAK,UAAU;AACzC;;;ADmFmB,wBAIP,YAJO;AAjHnB,SAAS,WAAW,OACpB;AACI,SAAO,SAAS,iBAAiB,KAAK,IAAI,QAAQ;AACtD;AA+BO,SAAS,cAAc;AAAA,EAC1B,cAAc;AAAA,EACd;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACJ,GACA;AACI,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAwB,IAAI;AACtD,QAAM,CAAC,WAAW,YAAY,IAAI,SAAS,IAAI;AAE/C,YAAU,MACV;AACI,mBAAe,gBACf;AACI,UACA;AACI,cAAM,SAAS,IAAI,gBAAgB,OAAO,SAAS,MAAM;AACzD,cAAM,SAAS,OAAO,IAAI,QAAQ;AAClC,cAAM,QAAQ,OAAO,IAAI,OAAO;AAChC,cAAM,YAAY,WAAW,OAAO,IAAI,WAAW,CAAC;AACpD,cAAM,aAAa,OAAO,IAAI,OAAO;AAGrC,YAAI,YACJ;AACI,gBAAM,IAAI,MAAM,UAAU;AAAA,QAC9B;AAEA,YAAI,CAAC,UAAU,CAAC,OAChB;AACI,gBAAM,IAAI,MAAM,6BAA6B;AAAA,QACjD;AAGA,cAAM,WAAW,MAAM,MAAM,GAAG,WAAW,kBAAkB;AAAA,UACzD,QAAQ;AAAA,UACR,SAAS;AAAA,YACL,gBAAgB;AAAA,UACpB;AAAA,UACA,aAAa;AAAA,UACb,MAAM,KAAK,UAAU;AAAA,YACjB,MAAM;AAAA,cACF;AAAA,cACA;AAAA,cACA;AAAA,YACJ;AAAA,UACJ,CAAC;AAAA,QACL,CAAC;AAED,YAAI,CAAC,SAAS,IACd;AACI,gBAAMA,QAAO,MAAM,SAAS,KAAK,EAAE,MAAM,OAAO,CAAC,EAAE;AACnD,gBAAM,IAAI,MAAMA,MAAK,WAAW,0BAA0B;AAAA,QAC9D;AAEA,cAAM,OAAO,MAAM,SAAS,KAAK;AAEjC,oBAAY,MAAM;AAGlB,eAAO,SAAS,OAAO,WAAW,KAAK,aAAa,SAAS;AAAA,MACjE,SACO,KACP;AACI,cAAM,UAAU,eAAe,QAAQ,IAAI,UAAU;AACrD,iBAAS,OAAO;AAChB,qBAAa,KAAK;AAClB,kBAAU,OAAO;AAAA,MACrB;AAAA,IACJ;AAEA,kBAAc;AAAA,EAClB,GAAG,CAAC,aAAa,WAAW,OAAO,CAAC;AAEpC,MAAI,OACJ;AACI,QAAI,gBACJ;AACI,aAAO,gCAAG,yBAAe,KAAK,GAAE;AAAA,IACpC;AAEA,WACI,qBAAC,SAAI,OAAO,EAAE,SAAS,QAAQ,WAAW,SAAS,GAC/C;AAAA,0BAAC,QAAG,kCAAoB;AAAA,MACxB,oBAAC,OAAE,OAAO,EAAE,OAAO,MAAM,GAAI,iBAAM;AAAA,MACnC,oBAAC,YAAO,SAAS,MAAM,OAAO,SAAS,OAAO,KAAK,qBAEnD;AAAA,OACJ;AAAA,EAER;AAEA,MAAI,WACJ;AACI,QAAI,kBACJ;AACI,aAAO,gCAAG,4BAAiB;AAAA,IAC/B;AAEA,WACI,oBAAC,SAAI,OAAO,EAAE,SAAS,QAAQ,WAAW,SAAS,GAC/C,8BAAC,OAAE,0CAA4B,GACnC;AAAA,EAER;AAEA,SAAO;AACX;","names":["data"]}

package/dist/nextjs/server.d.ts

@@ -1,8 +1,9 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { S as SessionData } from '../session-DTHahDQ9.js';
+import { S as SessionData } from '../session-Dfwu5g2W.js';
+export { i as isSafeReturnPath } from '../session-Dfwu5g2W.js';
 import { K as KeyAlgorithmType } from '../types-DYyhze28.js';
-import { NextRequest, NextResponse } from 'next/server';
+import { NextResponse, NextRequest } from 'next/server';
 
 interface RequireAuthProps {
     /**
@@ -278,6 +279,61 @@ declare function getPendingSession(): Promise<PendingSessionData | null>;
  */
 declare function clearPendingSession(): Promise<void>;
 
+/**
+ * Session cookie names for Next.js
+ *
+ * The names carry the `SPFN_PORT` suffix, so they are only knowable at call
+ * time — this module is the one place an app reads them from.
+ */
+
+/**
+ * The cookie names that make up a browser session
+ */
+interface SessionCookieNames {
+    /** Encrypted session data */
+    session: string;
+    /** Current key ID (for key rotation) */
+    keyId: string;
+    /** Pending OAuth session — present only mid-flow */
+    oauthPending: string;
+    /** CSRF token — the only one the browser can read */
+    csrf: string;
+}
+/**
+ * Names of the cookies that make up a browser session
+ *
+ * Read at call time, never at import: the names carry the `SPFN_PORT` suffix,
+ * and an app that spells them itself keeps clearing the old name after a
+ * release renames one.
+ *
+ * @example
+ * ```typescript
+ * const names = sessionCookieNames();
+ * const raw = request.cookies.get(names.session);
+ * ```
+ */
+declare function sessionCookieNames(): SessionCookieNames;
+/**
+ * Expire every session cookie on a response
+ *
+ * For the route handler or middleware that answers "the API refused your
+ * session" — it empties the jar so the next request arrives anonymous. The
+ * path matches the one the setters use, because a delete under a different
+ * path leaves the cookie in place. Absent cookies are not an error.
+ *
+ * @param response - Response to expire the cookies on
+ * @returns The same response, so the call chains
+ *
+ * @example
+ * ```typescript
+ * export function GET(): NextResponse
+ * {
+ *     return clearSessionCookies(NextResponse.redirect(new URL('/login', request.url)));
+ * }
+ * ```
+ */
+declare function clearSessionCookies(response: NextResponse): NextResponse;
+
 /**
  * OAuth Handlers for Next.js
  *
@@ -314,4 +370,118 @@ interface OAuthCallbackOptions {
  */
 declare function createOAuthCallbackHandler(options?: OAuthCallbackOptions): (request: NextRequest) => Promise<NextResponse>;
 
-export { type OAuthCallbackOptions, type PendingSessionData, type PublicSession, RequireAuth, type RequireAuthProps, RequirePermission, type RequirePermissionProps, RequireRole, type RequireRoleProps, type SaveSessionOptions, SessionData, clearPendingSession, clearSession, createOAuthCallbackHandler, getAuthSessionData, getPendingSession, getSession, getUserPermissions, getUserRole, hasAnyPermission, hasAnyRole, saveSession, sealPendingSession, unsealPendingSession };
+/**
+ * @spfn/auth - OAuth 2.1 consent screen (Next.js route handlers)
+ *
+ * The authorization server lives on the API origin; this is the one piece of it
+ * that cannot, because consent is a decision only the signed-in person can make
+ * and the session cookie is on the web app. `GET` draws the screen, `POST` takes
+ * the answer, and neither of them decides anything: both forward the request to
+ * `/_auth/oauth2/authorize`, which validates it against the registration and
+ * hands back either what to draw or the refusal to act on.
+ *
+ * Three rules shape everything below, and each of them is an attack that would
+ * otherwise work:
+ *
+ * - **The only URLs this file redirects to are `loginPath` and a URI the API
+ *   returned.** The request's own `redirect_uri` is forwarded and never built
+ *   into a `Location` — an unregistered one is exactly the open redirect the
+ *   registration check exists to close, and the API is the only side that can
+ *   tell the two apart.
+ * - **Everything interpolated into the page is escaped.** `client_name` arrives
+ *   from unauthenticated dynamic registration, and `state` and `resource` come
+ *   from the query string of a link somebody was sent.
+ * - **The POST carries its own CSRF token.** The handler's server-side call to
+ *   the API mints the CSRF header itself and so would always pass; the check
+ *   that matters is the browser form's, and it is made before the API is called
+ *   at all.
+ */
+
+/** One scope, with the sentence the consent screen reads aloud for it. */
+interface OAuth2ConsentScope {
+    name: string;
+    description: string;
+}
+/**
+ * Everything a consent screen needs, raw and unescaped.
+ *
+ * A custom `render` receives this and owns the whole body, so it must echo
+ * `fields` and `csrfToken` back as hidden inputs: the POST is refused without
+ * the token, and the API re-validates the request from the fields rather than
+ * trusting what the GET was once shown.
+ *
+ * Every string here is caller-supplied. Put each one through {@link escapeHtml}.
+ */
+interface OAuth2ConsentView {
+    /** Registered name of the client asking. Unauthenticated input. */
+    clientName: string;
+    /** Host the code would be sent to — the one fact about the client that is checkable. */
+    redirectHost: string;
+    scopes: OAuth2ConsentScope[];
+    /** RFC 8707 target the token would be good against. */
+    resource: string;
+    /** Every authorize parameter the request carried, verbatim, to echo as hidden inputs. */
+    fields: Record<string, string>;
+    /** Value the POST's `csrf` field must carry. */
+    csrfToken: string;
+}
+/**
+ * Options for {@link createOAuth2AuthorizeHandlers}
+ */
+interface OAuth2AuthorizeHandlerOptions {
+    /**
+     * Where to send a visitor with no session, e.g. `/login`
+     *
+     * The handler appends `?returnUrl=` pointing at this request, so the login
+     * lands back on the consent screen with its parameters intact.
+     */
+    loginPath: string;
+    /**
+     * Replace the default consent page body
+     *
+     * Status, headers and the field set stay the handler's; this owns the HTML.
+     */
+    render?: (view: OAuth2ConsentView) => string;
+}
+/** The pair a route file re-exports as `export const { GET, POST } = ...`. */
+interface OAuth2AuthorizeHandlers {
+    GET: (request: NextRequest) => Promise<NextResponse>;
+    POST: (request: NextRequest) => Promise<NextResponse>;
+}
+/**
+ * Escape a string for interpolation into HTML text or a quoted attribute.
+ *
+ * Exported because a custom `render` needs the same escaping the default body
+ * applies: `client_name` comes from unauthenticated dynamic registration, and
+ * `state` is whatever was in the link the browser followed.
+ *
+ * @param value - Raw string
+ * @returns The same string with `& < > " '` replaced by entities
+ */
+declare function escapeHtml(value: string): string;
+/**
+ * Create the consent screen's route handlers
+ *
+ * `GET` renders the screen for an `/oauth/authorize` request and `POST` takes
+ * the form it submits. Mount both at the path published as
+ * `authorization_endpoint` in the authorization server metadata —
+ * `/oauth/authorize` unless `authorizationServer.authorizeUrl` says otherwise.
+ *
+ * Every answer carries `Cache-Control: no-store`; every page also carries
+ * `Content-Security-Policy: frame-ancestors 'none'`, because a consent screen
+ * that can be framed is a consent screen that can be clickjacked.
+ *
+ * @param options - Where to send an unauthenticated visitor, and an optional renderer
+ * @returns `{ GET, POST }`, ready to re-export from a route file
+ *
+ * @example
+ * ```typescript
+ * // app/oauth/authorize/route.ts
+ * import { createOAuth2AuthorizeHandlers } from '@spfn/auth/nextjs/server';
+ *
+ * export const { GET, POST } = createOAuth2AuthorizeHandlers({ loginPath: '/login' });
+ * ```
+ */
+declare function createOAuth2AuthorizeHandlers(options: OAuth2AuthorizeHandlerOptions): OAuth2AuthorizeHandlers;
+
+export { type OAuth2AuthorizeHandlerOptions, type OAuth2AuthorizeHandlers, type OAuth2ConsentScope, type OAuth2ConsentView, type OAuthCallbackOptions, type PendingSessionData, type PublicSession, RequireAuth, type RequireAuthProps, RequirePermission, type RequirePermissionProps, RequireRole, type RequireRoleProps, type SaveSessionOptions, type SessionCookieNames, SessionData, clearPendingSession, clearSession, clearSessionCookies, createOAuth2AuthorizeHandlers, createOAuthCallbackHandler, escapeHtml, getAuthSessionData, getPendingSession, getSession, getUserPermissions, getUserRole, hasAnyPermission, hasAnyRole, saveSession, sealPendingSession, sessionCookieNames, unsealPendingSession };