@atelic-action/ui 0.11.0 → 0.12.1

package/README.md

@@ -2,7 +2,7 @@
 
 Shared UI for the Atelic templates: the site chrome (header, menu, footer, sticky CTA bar, and credit band), the not found page and the routing that keeps it alive, the scroll spy hook, and the one base stylesheet. The marketing and artifact templates install it instead of carrying their own copies, so a chrome fix lands once and every site picks it up with `bun update`.
 
-The package ships source, not a build. Its TSX and CSS arrive as written and compile inside each site's own Vite.
+The package ships source, not a build. Its TSX and CSS arrive as written and compile inside each site's own Vite. The one exception is the access gate's server side, which ships compiled (see [The Access Gate](#the-access-gate)).
 
 ## Install
 
@@ -46,6 +46,10 @@ The package sheets sit inside `@layer atelic-ui`, so any rule a site writes outs
 | `@atelic-action/ui/email/render` | `renderEmail` and `renderFailureEmail`, the only entry that imports `react-dom/server` |
 | `@atelic-action/ui/tokens` | `Palette`, `atelicPalette`, `Fonts`, `atelicFonts`, `toThemeCSS`, `themeTokenMap` |
 | `@atelic-action/ui/hooks` | `useScrollSpy` and its `PageStop` type |
+| `@atelic-action/ui/gate` | `signToken`, `verifyToken`, `safeNext`, `needsSession`, and the token types |
+| `@atelic-action/ui/gate/request-link` | `POST`, the handler that emails a sign in link, and `createRequestLink` |
+| `@atelic-action/ui/gate/verify` | `GET`, the handler that turns a link into a session |
+| `@atelic-action/ui/gate/middleware` | The routing middleware as the default export, and `createMiddleware` |
 | `@atelic-action/ui/routing` | `staticNotFoundRouting`, the router options behind the not found page |
 | `@atelic-action/ui/styles/base.css` | Resets, the `.mkt` canvas, typography, and layout helpers |
 | `@atelic-action/ui/styles/chrome.css` | Styles for everything under `chrome` |
@@ -116,6 +120,59 @@ export function NotFoundPage() {
 
 `staticNotFoundRouting` is for prerendered sites only. On a live app the pending state is a real loading moment and the page would flash through every slow load, so an app sets `defaultNotFoundComponent` alone. A browser test is the only proof any of this works; template-marketing's `e2e/not-found.spec.ts` is the one to copy.
 
+## The Access Gate
+
+The gate puts a whole host behind an email sign in with no database: a reader on the allowlist asks for a link, the link starts a signed session cookie, and the middleware holds every page and file back from anyone without one. It is opt in and fails open, so a host with no `GATE_SESSION_SECRET` is fully public.
+
+Vercel finds these three files by path, so a site keeps them, each a re export:
+
+```ts
+// api/auth/request-link.ts
+export { POST } from "@atelic-action/ui/gate/request-link";
+
+// api/auth/verify.ts
+export { GET } from "@atelic-action/ui/gate/verify";
+
+// middleware.ts
+export { default } from "@atelic-action/ui/gate/middleware";
+
+// The platform reads the matcher from this file and nowhere else. Only the
+// two sign in functions skip the middleware; any other function is held.
+export const config = { matcher: ["/((?!api/auth/).*)"] };
+```
+
+The default middleware holds back everything `needsSession` does: all of a host but the login page, what that page loads (`/assets/` apart from `/assets/doc/`, `/fonts/`, `/brand/`, the favicon and logo), everything under `/api/auth/` (the two sign in functions, and the one place under `/api/` where a host must add nothing private), `robots.txt`, `health.json`, and a website build proxied under `/proto`. A site whose matcher already leaves its open paths out passes its own test, and one whose link opens something other than a document names it:
+
+```ts
+import { createMiddleware } from "@atelic-action/ui/gate/middleware";
+export default createMiddleware({ needsSession: () => true });
+
+import { createRequestLink } from "@atelic-action/ui/gate/request-link";
+export const POST = createRequestLink({ noun: "preview" });
+```
+
+| Env | Read by | What it does |
+|---|---|---|
+| `GATE_SESSION_SECRET` | all three | The signing secret, and the switch: unset, the gate is off. Use 32 random bytes or more |
+| `GATE_ALLOWLIST` | all three | Comma separated emails that may receive a link. Taking an address off, then redeploying, refuses its outstanding link and ends its session |
+| `RESEND_API_KEY` | request link | The sending only key the link goes out on |
+| `GATE_BASE_URL` | request link | The host the link points at; a bare host is read as https, and plain http is refused unless it is local. Unset, production uses the project's own domain and a preview uses the deployment it was asked on |
+| `GATE_FROM`, `GATE_SUBJECT`, `GATE_LINK_TTL_MIN` | request link | Sender, subject, and link lifetime in minutes (15, a day at most) |
+| `GATE_SESSION_DAYS`, `GATE_WATERMARK_MODE` | verify | Session lifetime in days (7, a year at most), and `pill` or `tiled` |
+
+What it holds to, each with a test in `tst/gate/`:
+
+- Give each host its own secret. A token carries no host, so two hosts sharing a secret would accept each other's sessions.
+- Tokens are compact JWTs under HS256, signed and verified by [jose](https://github.com/panva/jose). The algorithm is pinned, and a link token is never accepted as a session or a session as a link.
+- The emailed link is never built from a forwarded header, since a caller can name any host there.
+- A link request answers the same way after the same two second wait whether or not the address was on the allowlist, and a send still running shortly before then is given up. A send that fails says so in the function's log and nowhere else.
+- The post sign in destination is held to a path on the same host, 512 characters at most (`safeNext`).
+- An open path opens only as written; the held corner is held in any case. Under `/api/`, only `/api/auth/` is open.
+
+What it does not do, by having no store: a link can be used more than once until it expires, and link requests are not rate limited. Rotating the secret ends every session at once. The `gate_email` and `gate_wm` cookies that feed the watermark are readable and unsigned on purpose: the watermark is drawn in the reader's own browser, so it deters and attributes nothing a reader set on removing it could not already remove.
+
+This is the one corner of the package that ships compiled. Vercel runs a function's and a middleware's package imports as shipped and compiles nothing inside `node_modules`, so `bun run build` emits `src/gate/` to `dist/gate/`, and `prepack` runs it before every publish.
+
 ## Email
 
 `@atelic-action/ui/email` is the runner email design as React components, ported one to one from the jq library the runners compose their mail from (homebase `runners/lib/email.jq`). The components are born inline: every layout is a table, every style is an inline style object, and there is no CSS file and no `className`, because Gmail strips a style block and ignores media queries on some accounts. The same components therefore mount on a web page as happily as they render into a mail client.

package/dist/gate/config.d.ts

@@ -0,0 +1,15 @@
+/**
+ * How the gate reads its settings from the environment. Shared by the two
+ * sign in functions and the middleware, so each reads a value the same way.
+ */
+/** Whether an address is on the comma separated allowlist. */
+export declare function isAllowed(email: string, allowlist: string | undefined): boolean;
+/**
+ * A setting that has to be a positive, finite number, or its default. A
+ * lifetime of zero, a negative one, or Infinity would mint a token that is
+ * already dead or that cannot be signed at all. A fraction is allowed (half
+ * a day), so a caller rounds what it derives to whole seconds. Anything past
+ * the ceiling is held to it: a lifetime of 1e308 days is a typo, and the
+ * seconds it works out to cannot be signed.
+ */
+export declare function positive(value: string | undefined, fallback: number, ceiling: number): number;

package/dist/gate/config.js

@@ -0,0 +1,28 @@
+/**
+ * How the gate reads its settings from the environment. Shared by the two
+ * sign in functions and the middleware, so each reads a value the same way.
+ */
+/** Whether an address is on the comma separated allowlist. */
+export function isAllowed(email, allowlist) {
+    const wanted = email.trim().toLowerCase();
+    if (!wanted)
+        return false;
+    return (allowlist ?? "")
+        .split(",")
+        .map((entry) => entry.trim().toLowerCase())
+        .includes(wanted);
+}
+/**
+ * A setting that has to be a positive, finite number, or its default. A
+ * lifetime of zero, a negative one, or Infinity would mint a token that is
+ * already dead or that cannot be signed at all. A fraction is allowed (half
+ * a day), so a caller rounds what it derives to whole seconds. Anything past
+ * the ceiling is held to it: a lifetime of 1e308 days is a typo, and the
+ * seconds it works out to cannot be signed.
+ */
+export function positive(value, fallback, ceiling) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return fallback;
+    return Math.min(parsed, ceiling);
+}

package/dist/gate/index.d.ts

@@ -0,0 +1,3 @@
+export { safeNext } from "./next.js";
+export { signToken, type TokenClaims, type TokenPurpose, verifyToken } from "./tokens.js";
+export { needsSession } from "./wall.js";

package/dist/gate/index.js

@@ -0,0 +1,3 @@
+export { safeNext } from "./next.js";
+export { signToken, verifyToken } from "./tokens.js";
+export { needsSession } from "./wall.js";

package/dist/gate/middleware.d.ts

@@ -0,0 +1,7 @@
+export interface MiddlewareOptions {
+    /** Whether a path needs a session once the gate is armed. */
+    needsSession?: (pathname: string) => boolean;
+}
+export declare function createMiddleware(options?: MiddlewareOptions): (request: Request) => Promise<Response | undefined>;
+declare const _default: (request: Request) => Promise<Response | undefined>;
+export default _default;

package/dist/gate/middleware.js

@@ -0,0 +1,56 @@
+/**
+ * Access gate: the routing middleware.
+ *
+ * Opt in and fail open: with no GATE_SESSION_SECRET set the gate is dormant
+ * and every request passes, so a site is fully public. Set the secret (and an
+ * allowlist) on the Vercel project and this same code starts enforcing: a
+ * request without a valid session cookie is redirected to /login. The
+ * session's address has to be on the allowlist still, so taking one off (and
+ * redeploying) ends that reader's session.
+ *
+ * A site's root `middleware.ts` exports this as its default beside its own
+ * `config`, which the platform reads from that file and nowhere else:
+ *
+ *   export { default } from "@atelic-action/ui/gate/middleware";
+ *   export const config = { matcher: ["/((?!api/auth/).*)"] };
+ *
+ * That matcher keeps only the two sign in functions away from the middleware,
+ * so any other function a host adds is held like a page. The default holds
+ * back everything `needsSession` in wall.ts does. A site
+ * whose matcher already leaves its open paths out passes its own test to
+ * `createMiddleware`.
+ */
+import { isAllowed } from "./config.js";
+import { verifyToken } from "./tokens.js";
+import { needsSession as wallNeedsSession } from "./wall.js";
+function readCookie(header, name) {
+    const match = header.match(new RegExp(`(?:^|;\\s*)${name}=([^;]+)`));
+    if (!match)
+        return undefined;
+    try {
+        return decodeURIComponent(match[1]);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function createMiddleware(options = {}) {
+    const needsSession = options.needsSession ?? wallNeedsSession;
+    return async function middleware(request) {
+        const secret = process.env.GATE_SESSION_SECRET;
+        if (!secret)
+            return; // gate off, let everything through
+        const url = new URL(request.url);
+        if (!needsSession(url.pathname))
+            return; // what the login page needs to render
+        const cookies = request.headers.get("cookie") ?? "";
+        const claims = await verifyToken(readCookie(cookies, "gate_session"), secret);
+        if (claims?.p === "session" && isAllowed(claims.e, process.env.GATE_ALLOWLIST)) {
+            return; // valid session, continue to the site
+        }
+        const login = new URL("/login", url.origin);
+        login.searchParams.set("next", url.pathname + url.search);
+        return Response.redirect(login.toString(), 302);
+    };
+}
+export default createMiddleware();

package/dist/gate/next.d.ts

@@ -0,0 +1 @@
+export declare function safeNext(value: unknown): string;

package/dist/gate/next.js

@@ -0,0 +1,23 @@
+/**
+ * The post sign in destination, held to a path on this host. A value that
+ * starts with one slash is not enough: a browser reads `//host` as protocol
+ * relative and `/\host` the same way, and drops tabs and newlines before it
+ * parses, so `/\t/host` arrives as `//host`. The value also becomes a
+ * Location header, which throws on anything outside Latin 1, so the path is
+ * held to printable ASCII, and to a length no real path here comes near, so
+ * a request cannot grow the emailed link without bound. Anything else falls
+ * back to the root.
+ */
+const LONGEST = 512;
+export function safeNext(value) {
+    if (typeof value !== "string" || !value.startsWith("/") || value.startsWith("//"))
+        return "/";
+    if (value.length > LONGEST)
+        return "/";
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (code === 0x5c || code <= 0x20 || code >= 0x7f)
+            return "/";
+    }
+    return value;
+}

package/dist/gate/request-link.d.ts

@@ -0,0 +1,16 @@
+export interface RequestLinkOptions {
+    /** What the link opens, as the email names it. Defaults to "document". */
+    noun?: string;
+}
+/**
+ * Where the emailed link points. Never a forwarded header: a caller can name
+ * any host there, and the link carries a signed token. The configured base
+ * wins, read as a host (a bare one is taken as https, and plain http is
+ * accepted only for a local one); on production the project's own domain is
+ * next; otherwise the host the platform routed this
+ * request to, which is the deployment itself.
+ */
+export declare function linkBase(request: Request, env: Record<string, string | undefined>): string;
+export declare function createRequestLink(options?: RequestLinkOptions): (request: Request) => Promise<Response>;
+/** The handler a document host exports as is. */
+export declare const POST: (request: Request) => Promise<Response>;

package/dist/gate/request-link.js

@@ -0,0 +1,161 @@
+/**
+ * Access gate: request a sign in link.
+ *
+ * Emails a signed link through Resend, but only to an allowlisted address.
+ * The response is the same whether or not the email matched, in its body and
+ * in how long it takes, so the allowlist cannot be probed. A site's
+ * `api/auth/request-link.ts` re exports `POST` from here.
+ *
+ * Env (set on the Vercel project):
+ * - GATE_SESSION_SECRET   signing secret; also the gate's on and off switch
+ * - GATE_ALLOWLIST        comma separated emails allowed to receive a link
+ * - RESEND_API_KEY        sending only Resend key
+ * - GATE_FROM             sender display name (optional)
+ * - GATE_SUBJECT          email subject (optional)
+ * - GATE_LINK_TTL_MIN     link lifetime in minutes (optional, default 15)
+ * - GATE_BASE_URL         the host the link points at (optional, see linkBase)
+ */
+import { escapeHTML } from "../lib/escapeHTML.js";
+import { isAllowed, positive } from "./config.js";
+import { safeNext } from "./next.js";
+import { signToken } from "./tokens.js";
+const DEFAULT_FROM = "Atelic <forms@atelic.me>";
+/** A day: a sign in link that outlives it is a standing key, not a link. */
+const LONGEST_LINK_MIN = 24 * 60;
+/** How long every valid request takes to answer, whatever it did. */
+const ANSWER_AFTER_MS = 2000;
+/**
+ * How long a send may run before it is given up. Shorter than the answer, so
+ * a slow send can never make an allowlisted address answer later than a
+ * stranger.
+ */
+const SEND_WITHIN_MS = 1700;
+function json(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "Content-Type": "application/json" },
+    });
+}
+/**
+ * Where the emailed link points. Never a forwarded header: a caller can name
+ * any host there, and the link carries a signed token. The configured base
+ * wins, read as a host (a bare one is taken as https, and plain http is
+ * accepted only for a local one); on production the project's own domain is
+ * next; otherwise the host the platform routed this
+ * request to, which is the deployment itself.
+ */
+export function linkBase(request, env) {
+    const configured = env.GATE_BASE_URL?.trim();
+    if (configured) {
+        try {
+            const base = new URL(/^https?:\/\//i.test(configured) ? configured : `https://${configured}`);
+            const local = base.hostname === "localhost" || base.hostname === "127.0.0.1";
+            if (base.protocol === "https:" || local)
+                return base.origin;
+            console.error("gate: GATE_BASE_URL is plain http, falling back to the request's own host");
+        }
+        catch {
+            console.error("gate: GATE_BASE_URL is not a URL, falling back to the request's own host");
+        }
+    }
+    if (env.VERCEL_ENV === "production" && env.VERCEL_PROJECT_PRODUCTION_URL) {
+        return `https://${env.VERCEL_PROJECT_PRODUCTION_URL}`;
+    }
+    return new URL(request.url).origin;
+}
+function linkEmailHTML(rawLink, rawNoun) {
+    const link = escapeHTML(rawLink);
+    const noun = escapeHTML(rawNoun);
+    // Gmail renders inline styles only, no style blocks.
+    return `
+		<div style="font-family: Helvetica, Arial, sans-serif; color: #211c17; line-height: 1.6; max-width: 520px;">
+			<p style="margin: 0 0 12px; font-size: 24px; font-weight: 600;">Your private link to the ${noun}.</p>
+			<p style="margin: 0 0 24px; color: #4a4137;">Click below to open the site. The link is tied to your inbox and expires shortly. Once you are in, you stay signed in for a while.</p>
+			<a href="${link}" style="display: inline-block; background: #211c17; color: #ffffff; font-weight: 600; text-decoration: none; padding: 14px 26px; border-radius: 8px;">Open the ${noun} &rarr;</a>
+			<p style="margin: 24px 0 0; font-size: 13px; color: #4a4137;">If the button does not work, paste this link into your browser:<br><span style="color: #6b5f4f; word-break: break-all;">${link}</span></p>
+			<p style="margin: 28px 0 0; font-size: 13px; color: #8a7c68;">If you did not expect this, you can ignore it.</p>
+		</div>`;
+}
+/**
+ * Sends the link, and says so in the function's log when it could not. The
+ * log is the only place a failed send shows: the response never tells.
+ */
+async function sendLink(to, link, noun) {
+    const apiKey = process.env.RESEND_API_KEY;
+    if (!apiKey) {
+        console.error("gate: no RESEND_API_KEY, so no sign in link was sent");
+        return;
+    }
+    const controller = new AbortController();
+    const giveUp = setTimeout(() => controller.abort(), SEND_WITHIN_MS);
+    try {
+        const response = await fetch("https://api.resend.com/emails", {
+            method: "POST",
+            signal: controller.signal,
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                from: process.env.GATE_FROM || DEFAULT_FROM,
+                to: [to],
+                subject: process.env.GATE_SUBJECT || `Your private link to the ${noun}`,
+                html: linkEmailHTML(link, noun),
+                text: `Your private link to the ${noun}:\n\n${link}\n\nIf you did not expect this, you can ignore it.`,
+            }),
+        });
+        if (!response.ok) {
+            console.error(`gate: Resend answered ${response.status}, so no sign in link was sent`);
+        }
+    }
+    finally {
+        clearTimeout(giveUp);
+    }
+}
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export function createRequestLink(options = {}) {
+    const noun = options.noun ?? "document";
+    return async function POST(request) {
+        let data;
+        try {
+            data = await request.json();
+        }
+        catch {
+            return json(400, { ok: false, error: "Invalid request body." });
+        }
+        if (typeof data !== "object" || data === null || Array.isArray(data)) {
+            return json(400, { ok: false, error: "Invalid request body." });
+        }
+        const fields = data;
+        const email = String(fields.email ?? "")
+            .trim()
+            .toLowerCase();
+        const next = safeNext(fields.next);
+        const secret = process.env.GATE_SESSION_SECRET;
+        // Every valid request answers after the same wait, so a send in flight
+        // reads no differently from no send at all.
+        const answered = wait(ANSWER_AFTER_MS);
+        if (secret && isAllowed(email, process.env.GATE_ALLOWLIST)) {
+            const ttlMinutes = positive(process.env.GATE_LINK_TTL_MIN, 15, LONGEST_LINK_MIN);
+            try {
+                const token = await signToken({
+                    e: email,
+                    x: Math.floor(Date.now() / 1000) + Math.max(1, Math.round(ttlMinutes * 60)),
+                    p: "link",
+                    n: next,
+                }, secret);
+                const link = `${linkBase(request, process.env)}/api/auth/verify?token=${encodeURIComponent(token)}`;
+                await sendLink(email, link, noun);
+            }
+            catch (error) {
+                // The response must not reveal whether a send happened; the log may.
+                const reason = error instanceof Error ? error.name : "unknown error";
+                console.error(`gate: the sign in link was not sent (${reason})`);
+            }
+        }
+        await answered;
+        return json(200, { ok: true });
+    };
+}
+/** The handler a document host exports as is. */
+export const POST = createRequestLink();

package/dist/gate/tokens.d.ts

@@ -0,0 +1,18 @@
+export type TokenPurpose = "link" | "session";
+export interface TokenClaims {
+    /** Subject email. */
+    e: string;
+    /** Expiry, epoch seconds. */
+    x: number;
+    /** Purpose; keeps a short lived link token from being replayed as a session. */
+    p: TokenPurpose;
+    /** Post sign in path (link tokens only). */
+    n?: string;
+}
+export declare function signToken(claims: TokenClaims, secret: string): Promise<string>;
+/**
+ * The claims of a token this secret signed and that has not expired, or null
+ * for anything else. The algorithm is pinned, so a token naming another one
+ * (or none) is refused before its signature is read.
+ */
+export declare function verifyToken(token: string | undefined | null, secret: string): Promise<TokenClaims | null>;

package/dist/gate/tokens.js

@@ -0,0 +1,43 @@
+/**
+ * Signed tokens for the access gate: compact JWTs under HS256, signed and
+ * verified by jose over Web Crypto, so the same module runs in the routing
+ * middleware and in the serverless sign in functions. The secret is always
+ * passed in by the caller from the environment, so nothing here can reach a
+ * client bundle.
+ */
+import { jwtVerify, SignJWT } from "jose";
+const encoder = new TextEncoder();
+export async function signToken(claims, secret) {
+    const body = { p: claims.p };
+    if (claims.n !== undefined)
+        body.n = claims.n;
+    return new SignJWT(body)
+        .setProtectedHeader({ alg: "HS256" })
+        .setSubject(claims.e)
+        .setExpirationTime(claims.x)
+        .sign(encoder.encode(secret));
+}
+/**
+ * The claims of a token this secret signed and that has not expired, or null
+ * for anything else. The algorithm is pinned, so a token naming another one
+ * (or none) is refused before its signature is read.
+ */
+export async function verifyToken(token, secret) {
+    if (!token || !secret)
+        return null;
+    try {
+        const { payload } = await jwtVerify(token, encoder.encode(secret), {
+            algorithms: ["HS256"],
+            requiredClaims: ["sub", "exp"],
+        });
+        const { sub, exp, p, n } = payload;
+        if (typeof sub !== "string" || typeof exp !== "number")
+            return null;
+        if (p !== "link" && p !== "session")
+            return null;
+        return { e: sub, x: exp, p, ...(typeof n === "string" ? { n } : {}) };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/gate/verify.d.ts

@@ -0,0 +1 @@
+export declare function GET(request: Request): Promise<Response>;

package/dist/gate/verify.js

@@ -0,0 +1,54 @@
+/**
+ * Access gate: verify a sign in link and start a session.
+ *
+ * Validates the signed token from the emailed link, sets the signed session
+ * cookie (plus a readable email cookie for the watermark), and redirects
+ * into the site. A site's `api/auth/verify.ts` re exports `GET` from here.
+ *
+ * Env (set on the Vercel project):
+ * - GATE_SESSION_SECRET    signing secret; also the gate's on and off switch
+ * - GATE_ALLOWLIST         the link's address must still be on it
+ * - GATE_SESSION_DAYS      session lifetime in days (optional, default 7)
+ * - GATE_WATERMARK_MODE    "pill" (default) or "tiled"
+ */
+import { isAllowed, positive } from "./config.js";
+import { safeNext } from "./next.js";
+import { signToken, verifyToken } from "./tokens.js";
+/** A year: past it a session is no longer something anyone remembers granting. */
+const LONGEST_SESSION_DAYS = 365;
+function cookie(name, value, maxAge, httpOnly) {
+    const flags = ["Path=/", "Secure", "SameSite=Lax", `Max-Age=${maxAge}`];
+    if (httpOnly)
+        flags.unshift("HttpOnly");
+    return `${name}=${encodeURIComponent(value)}; ${flags.join("; ")}`;
+}
+function redirect(location, headers) {
+    const merged = headers ?? new Headers();
+    merged.set("Location", location);
+    // The request carried a token in its URL and the answer may carry cookies:
+    // nothing keeps a copy, and the next page learns nothing of the link.
+    merged.set("Cache-Control", "no-store");
+    merged.set("Referrer-Policy", "no-referrer");
+    return new Response(null, { status: 302, headers: merged });
+}
+export async function GET(request) {
+    const secret = process.env.GATE_SESSION_SECRET;
+    if (!secret)
+        return redirect("/login?e=expired");
+    const token = new URL(request.url).searchParams.get("token");
+    const claims = await verifyToken(token, secret);
+    // An address taken off the allowlist after its link went out gets no session.
+    if (claims?.p !== "link" || !isAllowed(claims.e, process.env.GATE_ALLOWLIST)) {
+        return redirect("/login?e=expired");
+    }
+    const days = positive(process.env.GATE_SESSION_DAYS, 7, LONGEST_SESSION_DAYS);
+    // Whole seconds: a browser ignores a Max-Age that is not an integer.
+    const maxAge = Math.max(1, Math.round(days * 24 * 60 * 60));
+    const session = await signToken({ e: claims.e, x: Math.floor(Date.now() / 1000) + maxAge, p: "session" }, secret);
+    const mode = process.env.GATE_WATERMARK_MODE || "pill";
+    const headers = new Headers();
+    headers.append("Set-Cookie", cookie("gate_session", session, maxAge, true));
+    headers.append("Set-Cookie", cookie("gate_email", claims.e, maxAge, false));
+    headers.append("Set-Cookie", cookie("gate_wm", mode, maxAge, false));
+    return redirect(safeNext(claims.n), headers);
+}

package/dist/gate/wall.d.ts

@@ -0,0 +1,47 @@
+/**
+ * What the access wall holds back. With the wall armed, every request needs
+ * a session except what the login page itself needs to render: the practice's
+ * FOOTPRINT.md says anything carrying a private signal is never hosted
+ * publicly, and on a private artifact that includes the owner's screenshots
+ * under /images/, the printed PDF, and the built chunks a document's content
+ * compiles into.
+ *
+ * The open paths are read from what the built /login page actually loads:
+ * its hashed CSS and JS under /assets/, the fonts its stylesheet declares,
+ * the favicon in its head, and the brand marks the header draws, which every
+ * prerendered page preloads because the router's pending page carries the
+ * header (each site's e2e/wall.spec.ts fails when the login page asks for
+ * anything else); plus the two sign in functions under /api/auth/, the login page itself,
+ * robots.txt, and the uptime monitor's health.json. /assets/doc/ is the one
+ * part of /assets/ held back: the build writes every chunk carrying a
+ * private content module there (the private chunks build plugin), so a document's
+ * copy and numbers never sit in a file the login page can load.
+ *
+ * A logo is a brand mark and is not private; a screenshot is evidence and
+ * may be. So brand marks, the sender's and the recipient's, live under
+ * public/brand/ and stay open, so the header and the login page can draw
+ * them, and the owner's screens live under public/images/ and are held. The
+ * sender's mark at /logo.svg and the favicon stay open where they are,
+ * because every cut already points at them there.
+ *
+ * The business's website build, when one is previewed, is proxied under
+ * /proto by a rewrite in the host's vercel.json. It is a public thing by design and carries no private reading, so
+ * it stays open on a private host too: a prospect reads the prototype
+ * without a sign in while the documents beside it stay behind the wall.
+ *
+ * Pure and dependency free, so the middleware imports it and the tests call
+ * it directly.
+ */
+/**
+ * Whether a request for this path needs a session when the wall is armed.
+ * The path is read the way a file server would read it (decoded, repeated
+ * slashes collapsed) so an encoded or doubled slash cannot walk a held file
+ * out through an open prefix; anything that will not decode, or still climbs
+ * a directory once decoded, is held, and so is one that still carries a
+ * percent sign, since a second decode somewhere downstream would make it a
+ * different path than the one judged here. Case is folded for the held corner
+ * alone, so no spelling of it slips out, while an open path opens only as
+ * written: the host serves files by exact case, and a path that merely looks
+ * like an open one names some other file.
+ */
+export declare function needsSession(pathname: string): boolean;

package/dist/gate/wall.js

@@ -0,0 +1,76 @@
+/**
+ * What the access wall holds back. With the wall armed, every request needs
+ * a session except what the login page itself needs to render: the practice's
+ * FOOTPRINT.md says anything carrying a private signal is never hosted
+ * publicly, and on a private artifact that includes the owner's screenshots
+ * under /images/, the printed PDF, and the built chunks a document's content
+ * compiles into.
+ *
+ * The open paths are read from what the built /login page actually loads:
+ * its hashed CSS and JS under /assets/, the fonts its stylesheet declares,
+ * the favicon in its head, and the brand marks the header draws, which every
+ * prerendered page preloads because the router's pending page carries the
+ * header (each site's e2e/wall.spec.ts fails when the login page asks for
+ * anything else); plus the two sign in functions under /api/auth/, the login page itself,
+ * robots.txt, and the uptime monitor's health.json. /assets/doc/ is the one
+ * part of /assets/ held back: the build writes every chunk carrying a
+ * private content module there (the private chunks build plugin), so a document's
+ * copy and numbers never sit in a file the login page can load.
+ *
+ * A logo is a brand mark and is not private; a screenshot is evidence and
+ * may be. So brand marks, the sender's and the recipient's, live under
+ * public/brand/ and stay open, so the header and the login page can draw
+ * them, and the owner's screens live under public/images/ and are held. The
+ * sender's mark at /logo.svg and the favicon stay open where they are,
+ * because every cut already points at them there.
+ *
+ * The business's website build, when one is previewed, is proxied under
+ * /proto by a rewrite in the host's vercel.json. It is a public thing by design and carries no private reading, so
+ * it stays open on a private host too: a prospect reads the prototype
+ * without a sign in while the documents beside it stay behind the wall.
+ *
+ * Pure and dependency free, so the middleware imports it and the tests call
+ * it directly.
+ */
+const OPEN_EXACT = new Set([
+    "/login",
+    "/login/",
+    "/favicon.svg",
+    "/logo.svg",
+    "/robots.txt",
+    "/health.json",
+    "/proto",
+]);
+const OPEN_PREFIXES = ["/api/auth/", "/assets/", "/brand/", "/fonts/", "/proto/"];
+/** The one corner of an open prefix that stays behind the wall. */
+const HELD_PREFIXES = ["/assets/doc/"];
+/**
+ * Whether a request for this path needs a session when the wall is armed.
+ * The path is read the way a file server would read it (decoded, repeated
+ * slashes collapsed) so an encoded or doubled slash cannot walk a held file
+ * out through an open prefix; anything that will not decode, or still climbs
+ * a directory once decoded, is held, and so is one that still carries a
+ * percent sign, since a second decode somewhere downstream would make it a
+ * different path than the one judged here. Case is folded for the held corner
+ * alone, so no spelling of it slips out, while an open path opens only as
+ * written: the host serves files by exact case, and a path that merely looks
+ * like an open one names some other file.
+ */
+export function needsSession(pathname) {
+    let path;
+    try {
+        path = decodeURIComponent(pathname);
+    }
+    catch {
+        return true;
+    }
+    path = path.replace(/\/{2,}/g, "/");
+    if (path.includes("..") || path.includes("\\") || path.includes("%"))
+        return true;
+    const folded = path.toLowerCase();
+    if (HELD_PREFIXES.some((prefix) => folded.startsWith(prefix)))
+        return true;
+    if (OPEN_EXACT.has(path))
+        return false;
+    return !OPEN_PREFIXES.some((prefix) => path.startsWith(prefix));
+}