Site Pin Gate

Site PIN gate: one PIN in front of the whole site

A PIN gate is the smallest possible access control: one shared secret, one cookie, zero user accounts. Its whole value is that the app behind it never knows it exists. The insight that shapes this module is that everything dangerous lives in the two places the gate touches the outside world: the return path it redirects to, and the cookie it hands out. Everything else is a form and a cookie check.

Written by the engineer who has shipped this module. The earlier implementation it was audited against was a temporary gate on a marketing site kept private ahead of its launch. The facts and rules below are what the behaviour contract and the handler suite verify; references/provenance.md has the record.

When to use

A public-by-default Next.js site that must be hidden for a while: before launch, during a client or investor review, on a staging domain. Everyone who should see it can be told one PIN. The gate sits in proxy.ts (Next 16) or middleware.ts (Next 13 to 15) and is removed by unsetting one env var.

When NOT to use

Architecture

request --> proxy.ts / middleware.ts (the matcher decides what is even seen)
              |
              +- SITE_PIN unset ...........................> app (gate off)
              |
              +- cookie == HMAC(secret, pin) ..............> app
              |
              +- GET  /__unlock ..........> 303 /
              +- POST /__unlock  bad body > 400 gate page
              |                  over budget 429 gate page + Retry-After
              |                  wrong PIN . 401 gate page (return path kept)
              |                  right PIN . 303 safe return path + Set-Cookie
              |
              +- anything else ............> 401 gate page, no-store, noindex

Critical facts

1. An unset PIN is an open site, silently. The most likely production failure is the env var set in one environment and not another. Smoke-test every environment; the check is one curl.
2. The matcher is the security boundary. Whatever it excludes is public. Build assets always are; the sitemap, robots.txt, OG images and /api are public only if you exclude them, and a pages-only matcher publishes the route list of an unlaunched site through sitemap.xml.
3. The cookie is a bearer token derived from the PIN. Rotating the PIN logs every browser out with no store to clear. Without SITE_GATE_SECRET it is a plain fingerprint of the PIN, and a leaked cookie is then a leaked PIN.
4. The PIN's length is the real defence. The attempt budget is per server instance and best-effort. A four-digit PIN is ten thousand requests.
5. The gate page is self-contained by design. The proxy runs before the app, with no stylesheet, no components and no i18n provider. Inline CSS and a strings table are not laziness.

Hard rules

Never validate a return path with startsWith('/'). //evil.example, /\evil.example and ///evil.example all pass it and all leave the site. Resolve the value against the request origin and compare origins.

Never answer a successful form POST with a 307. The browser repeats the request with its method and body, so the PIN is posted again to the page it lands on, and once more through any locale redirect. Use 303.

Never put the PIN, or an unkeyed hash of it, in the cookie. A cookie the operator can read is a cookie an operator's laptop can leak. Key the token with SITE_GATE_SECRET.

Never compare the PIN or the cookie with ===. Route both through a constant-time comparison of equal-length digests.

Never let request.formData() throw to the platform. It rejects any body that is not form-encoded, and an unhandled rejection in the proxy is a stack trace instead of a rejected attempt. Answer 400.

Never choose the matcher by default, and never mount the unlock path under a locale prefix or an app route. What the matcher excludes is public; a colliding unlock path would never render, because the gate answers it first.

Invocation

Name the PIN back before writing it, so a single word meant as a topic ("staging") is not silently armed as one. Trimmed, it must be 1 to 128 characters: blank arms nothing, and the form caps its field at 128, so a longer PIN is a gate no browser can open. Under eight characters is enumerable and 1111 is ten thousand guesses against a per-instance, best-effort budget (fact 4): use it, say what it is worth, and that rotating it is one deploy.

The PIN goes to .env.local and nowhere else: never a template, a test, a commit or .env.example; deployed environments take theirs from the platform's env store (operations.md). SITE_GATE_SECRET is not the argument's business: openssl rand -hex 32, never derived from the PIN.

uninstall is a launch, so confirm the site is meant to be public, then follow Uninstalling in operations.md. To lock again later, keep the code and unset SITE_PIN instead.

Quick start

1. Probe the host and fill in the seam table: adaptation.md.
2. Copy the config, pure helpers and attempt store: module.md.
3. Copy the page renderer and the handler, wire them into proxy.ts or middleware.ts, and choose the matcher: handler.md.
4. Set SITE_PIN (the invocation's PIN, if one was given) and SITE_GATE_SECRET per environment, then run the smoke checks: operations.md.
5. Run the shipped tests in the host's runner: testing.md.

Reference directory

Part of the Timerise Skills index, which lists the sibling skills.