@spfn/auth 0.3.0-beta.21 → 0.3.0-beta.23

package/dist/nextjs/server.d.ts

@@ -484,4 +484,110 @@ declare function escapeHtml(value: string): string;
  */
 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 };
+/**
+ * @spfn/auth - The sign-out-everywhere page (Next.js route handlers)
+ *
+ * The page the mailed revoke-all link opens. `GET` describes the link and draws
+ * the button, `POST` presses it, and neither decides anything: both forward the
+ * token to `/_auth/keys/revoke-all/{confirm,consume}`, which answers either what
+ * to draw or the same 404 it answers for every token that names nothing.
+ *
+ * Four rules shape everything below, and each of them is an attack or a mishap
+ * that would otherwise work:
+ *
+ * - **The token is never anywhere but a hidden field and an API body.** Not in a
+ *   `Location`, not in a log line, not in the text of the page. It is a bearer
+ *   capability, and the request logger records the path of every request.
+ * - **There is no session here, so the CSRF token cannot come from one.** The
+ *   whole point of the link is an owner on a device they do not trust. `GET`
+ *   mints 32 random bytes, sets them in a cookie scoped to this page's path, and
+ *   mirrors them into the form; `POST` compares the two. A cross-site form has
+ *   neither half.
+ * - **Opening the page signs nobody out.** `GET` calls `confirm`, which the API
+ *   guarantees changes nothing, so a mail scanner that prefetches the link has
+ *   done nothing. `consume` is only ever reached from `POST`.
+ * - **Every refusal reads the same.** A 404 from either endpoint means unknown,
+ *   expired, spent, superseded or retired, and the screen says none of them:
+ *   telling them apart would tell whoever holds a random value that it named
+ *   something real.
+ */
+
+/**
+ * Everything the page needs at each of its three stages, raw and unescaped.
+ *
+ * A custom `render` receives this and owns the whole body, so at `confirm` it
+ * must echo `fields` and `csrfToken` back as hidden inputs: the POST is refused
+ * without the token, and the API re-reads the link from the field rather than
+ * trusting what the GET was once shown.
+ *
+ * `fields` and `csrfToken` are empty at the other two stages — there is no form
+ * left to submit once the link has been spent or found invalid.
+ *
+ * Every string here goes through {@link escapeHtml} before it reaches the page,
+ * `fields.token` above all: it is whatever was in the query of a link somebody
+ * was sent.
+ */
+interface RevokeAllPageView {
+    /** `confirm` draws the button, `done` reports the sign-out, `invalid` refuses. */
+    stage: 'confirm' | 'done' | 'invalid';
+    /** ISO instant the link stops working. `confirm` only. */
+    expiresAt?: string;
+    /** Devices the link would sign out. `confirm` only. */
+    activeKeyCount?: number;
+    /** Devices the link did sign out. `done` only. */
+    revokedCount?: number;
+    /** The form's hidden inputs — `token` at `confirm`, empty otherwise. */
+    fields: Record<string, string>;
+    /** Value the POST's `csrf` field must carry. Empty outside `confirm`. */
+    csrfToken: string;
+}
+/**
+ * Options for {@link createRevokeAllPageHandlers}
+ */
+interface RevokeAllPageHandlerOptions {
+    /**
+     * Replace the default page body
+     *
+     * Status, headers, the cookie and the field set stay the handler's; this
+     * owns the HTML, at all three stages.
+     */
+    render?: (view: RevokeAllPageView) => string;
+}
+/** The pair a route file re-exports as `export const { GET, POST } = ...`. */
+interface RevokeAllPageHandlers {
+    GET: (request: NextRequest) => Promise<NextResponse>;
+    POST: (request: NextRequest) => Promise<NextResponse>;
+}
+/**
+ * Create the sign-out-everywhere page's route handlers
+ *
+ * `GET` draws the page the mailed link opens and `POST` takes the form it
+ * submits. Mount both at `SPFN_AUTH_REVOKE_ALL_CONFIRM_PATH` —
+ * `/account/revoke-all` unless that variable says otherwise — which is the path
+ * `createRevokeAllLink` builds its URL on.
+ *
+ * There is no session on this page and none is wanted: an owner who no longer
+ * trusts the device in front of them is exactly who the link is for. What stands
+ * in for the session is the token in the query, and what stands in for a
+ * session-derived CSRF token is a random value `GET` sets in a path-scoped
+ * cookie and mirrors into the form.
+ *
+ * Every answer carries `Cache-Control: no-store` and
+ * `Content-Security-Policy: frame-ancestors 'none'`: a page whose one button
+ * signs out every device is a page worth clickjacking, and a copy of it in a
+ * shared cache is a copy of the token.
+ *
+ * @param options - An optional renderer; the defaults need nothing else
+ * @returns `{ GET, POST }`, ready to re-export from a route file
+ *
+ * @example
+ * ```typescript
+ * // app/account/revoke-all/route.ts
+ * import { createRevokeAllPageHandlers } from '@spfn/auth/nextjs/server';
+ *
+ * export const { GET, POST } = createRevokeAllPageHandlers();
+ * ```
+ */
+declare function createRevokeAllPageHandlers(options?: RevokeAllPageHandlerOptions): RevokeAllPageHandlers;
+
+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 RevokeAllPageHandlerOptions, type RevokeAllPageHandlers, type RevokeAllPageView, type SaveSessionOptions, type SessionCookieNames, SessionData, clearPendingSession, clearSession, clearSessionCookies, createOAuth2AuthorizeHandlers, createOAuthCallbackHandler, createRevokeAllPageHandlers, escapeHtml, getAuthSessionData, getPendingSession, getSession, getUserPermissions, getUserRole, hasAnyPermission, hasAnyRole, saveSession, sealPendingSession, sessionCookieNames, unsealPendingSession };

package/dist/nextjs/server.js

@@ -778,6 +778,187 @@ function createOAuth2AuthorizeHandlers(options) {
   }
   return { GET, POST };
 }
+
+// src/nextjs/revoke-all-page-handlers.ts
+import { cookies as cookies4 } from "next/headers.js";
+import { NextResponse as NextResponse3 } from "next/server";
+import { authApi as authApi3 } from "@spfn/auth";
+import { logger as logger4 } from "@spfn/core/logger";
+var CSRF_COOKIE = "spfn_revoke_all_csrf";
+var CSRF_TTL_SECONDS = 15 * 60;
+var FORM_CONTENT_TYPE = "application/x-www-form-urlencoded";
+function screen2(status, body) {
+  return new NextResponse3(body, {
+    status,
+    headers: {
+      "Content-Type": "text/html; charset=utf-8",
+      "Content-Security-Policy": "frame-ancestors 'none'",
+      "Cache-Control": "no-store"
+    }
+  });
+}
+function refusalScreen2(status, heading, message) {
+  return screen2(status, [
+    "<!DOCTYPE html>",
+    '<html lang="en"><head><meta charset="utf-8"><title>Sign out everywhere</title></head>',
+    `<body><h1>${heading}</h1><p>${message}</p></body></html>`
+  ].join("\n"));
+}
+function missingTokenScreen() {
+  return refusalScreen2(
+    400,
+    "Incomplete link",
+    "This address is missing the part that identifies the request. Open the link from your email again, in full."
+  );
+}
+function unavailableScreen2() {
+  return refusalScreen2(
+    500,
+    "Sign-out unavailable",
+    "This link could not be checked. Nothing was changed. Please try again."
+  );
+}
+function unverifiedScreen() {
+  return refusalScreen2(
+    403,
+    "Request could not be verified",
+    "This form did not carry the token the page set for it. Open the link from your email again and press the button on the page it opens."
+  );
+}
+function unsupportedScreen() {
+  return refusalScreen2(
+    415,
+    "Unsupported request",
+    "This page is answered for a browser form. Open the link from your email again."
+  );
+}
+function hiddenFields2(fields, csrfToken) {
+  return [...Object.entries(fields), ["csrf", csrfToken]].map(([name, value]) => `<input type="hidden" name="${escapeHtml(name)}" value="${escapeHtml(value)}">`).join("\n        ");
+}
+function confirmBody(view) {
+  return `<h1>Sign out everywhere</h1>
+    <p>This will sign out <strong>${view.activeKeyCount}</strong> signed-in device(s), including
+        this one. You will need to sign in again afterwards.</p>
+    <p>The link stops working at <time datetime="${escapeHtml(view.expiresAt ?? "")}"
+        >${escapeHtml(view.expiresAt ?? "")}</time>.</p>
+    <form method="post">
+        ${hiddenFields2(view.fields, view.csrfToken)}
+        <button type="submit">Sign out every device</button>
+    </form>`;
+}
+function stageBody(view) {
+  if (view.stage === "confirm") {
+    return confirmBody(view);
+  }
+  if (view.stage === "done") {
+    return `<h1>Signed out</h1>
+    <p>${view.revokedCount} device(s) signed out. Sign in again to carry on.</p>`;
+  }
+  return `<h1>Link no longer valid</h1>
+    <p>This link cannot be used. Ask for a new one, and open the most recent email you were sent.</p>`;
+}
+function defaultRender2(view) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="utf-8"><title>Sign out everywhere</title></head>
+<body>
+    ${stageBody(view)}
+</body>
+</html>`;
+}
+function stageView(stage, revokedCount) {
+  return { stage, revokedCount, fields: {}, csrfToken: "" };
+}
+function statusOf2(thrown) {
+  const error = thrown;
+  return Number(error?.status ?? error?.statusCode ?? 0);
+}
+function answerRefusal2(thrown, render) {
+  if (statusOf2(thrown) === 404) {
+    return screen2(404, render(stageView("invalid")));
+  }
+  logger4.error("Revoke-all link could not be answered", { status: statusOf2(thrown) });
+  return unavailableScreen2();
+}
+function mintCsrfToken() {
+  return Array.from(crypto.getRandomValues(new Uint8Array(32))).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function setCsrfCookie(response, csrfToken, path) {
+  response.cookies.set(CSRF_COOKIE, csrfToken, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === "production",
+    sameSite: "strict",
+    path,
+    maxAge: CSRF_TTL_SECONDS
+  });
+  return response;
+}
+function clearCsrfCookie(response, path) {
+  response.cookies.delete({ name: CSRF_COOKIE, path });
+  return response;
+}
+async function renderConfirm(request, token, render) {
+  const described = await authApi3.confirmRevokeAllLink.call({ body: { token } });
+  const csrfToken = mintCsrfToken();
+  const response = screen2(200, render({
+    stage: "confirm",
+    expiresAt: described.expiresAt,
+    activeKeyCount: described.activeKeyCount,
+    fields: { token },
+    csrfToken
+  }));
+  return setCsrfCookie(response, csrfToken, request.nextUrl.pathname);
+}
+async function refuseUnverifiedPost2(form) {
+  const presented = form.get("csrf");
+  const expected = (await cookies4()).get(CSRF_COOKIE)?.value;
+  if (!expected || !matchesCsrfToken(expected, typeof presented === "string" ? presented : null)) {
+    return unverifiedScreen();
+  }
+  return null;
+}
+function isFormPost2(request) {
+  return (request.headers.get("content-type") ?? "").startsWith(FORM_CONTENT_TYPE);
+}
+async function consume(token, render) {
+  const { revokedCount } = await authApi3.consumeRevokeAllLink.call({ body: { token } });
+  return screen2(200, render(stageView("done", revokedCount)));
+}
+function createRevokeAllPageHandlers(options = {}) {
+  const render = options.render ?? defaultRender2;
+  async function GET(request) {
+    const token = request.nextUrl.searchParams.get("token");
+    if (!token) {
+      return missingTokenScreen();
+    }
+    try {
+      return await renderConfirm(request, token, render);
+    } catch (error) {
+      return answerRefusal2(error, render);
+    }
+  }
+  async function POST(request) {
+    if (!isFormPost2(request)) {
+      return unsupportedScreen();
+    }
+    const form = await request.formData();
+    const refusal = await refuseUnverifiedPost2(form);
+    if (refusal) {
+      return refusal;
+    }
+    const path = request.nextUrl.pathname;
+    const token = form.get("token");
+    if (typeof token !== "string" || !token) {
+      return clearCsrfCookie(missingTokenScreen(), path);
+    }
+    try {
+      return clearCsrfCookie(await consume(token, render), path);
+    } catch (error) {
+      return clearCsrfCookie(answerRefusal2(error, render), path);
+    }
+  }
+  return { GET, POST };
+}
 export {
   RequireAuth,
   RequirePermission,
@@ -787,6 +968,7 @@ export {
   clearSessionCookies,
   createOAuth2AuthorizeHandlers,
   createOAuthCallbackHandler,
+  createRevokeAllPageHandlers,
   escapeHtml,
   getAuthSessionData,
   getPendingSession,