zz-meridian 0.7.0 → 0.8.0

package/README.md

@@ -9,7 +9,7 @@ dashboard depends on it afterwards.
 Give your coding agent (Codex, Claude Code, or any agent that can run a shell) this, with what you want in your own
 words at the end:
 
-> Run `npx zz-meridian@latest skill --global`, then follow the zz-meridian skill it installs to: <what you want>.
+> Run `npx zz-meridian@latest skill --global`, then follow the zz-meridian skill it installs to: [what you want, in your own words].
 
 The skill picks the command from what you said and what is in the folder, and names it before running anything:
 `adopt` to change this Next.js App Router project in place ("make this admin panel look professional"), `create` for a

package/dist/adopt.js

@@ -258,8 +258,12 @@ Rename or move them, then run adopt again.`);
         writes.set(`${dir}/icon.ts`, exactImports(`${dir}/icon.ts`, readPayload('app/icon.ts'), known));
     const ignore = path.join(root, '.gitignore');
     const ignored = fs.existsSync(ignore) ? fs.readFileSync(ignore, 'utf8') : '';
-    if (!/^\/?out\/?$/m.test(ignored))
-        writes.set('.gitignore', `${ignored.trimEnd()}\n\n# zz-meridian: verify's report and the screenshots\n/out/\n`);
+    // verify's report and screenshots, and an update in progress: Meridian's own, never the team's to commit. The manifest,
+    // keep.json and history/ are committed, since the next update reads them.
+    const bare = (l) => l.trim().replace(/^\//, '').replace(/\/$/, '');
+    const unignored = ['/out/', '/.meridian/update/', '/.meridian/update.lock'].filter((l) => !ignored.split('\n').some((x) => bare(x) === bare(l)));
+    if (unignored.length)
+        writes.set('.gitignore', `${ignored.trimEnd()}\n\n# zz-meridian: verify's report and an update in progress\n${unignored.join('\n')}\n`);
     // ── Write: every target checked first, so a bad one stops it before anything changes ─────────────────
     try {
         for (const rel of writes.keys())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Bring ZZ Meridian, a dashboard design system, into a Next.js project, or start a new dashboard on it. Copies the files in; nothing depends on this package at runtime.",
   "license": "MIT",
   "type": "module",

package/payload/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 Every release of ZZ Meridian, newest first. Versions follow semver: a removed or renamed token, prop or card is major; a new card, token or variant is minor; a corrected value is a patch. Each entry says what breaks and what to do instead.
 
+## [0.8.0] · 2026-10-06
+
+### Added
+
+- **A demo password in front of the whole product.** With `DEMO_PASSWORD` set at run time, `proxy.ts` sends every route to the sign-in page (an API answers 401), whose panel becomes "Open the demo": one password field, a 30-day signed session (`src/lib/demo-gate.ts`, keyed by `DEMO_SECRET` when set), and opening the page again signs out. Without it nothing changes: the panel is the product's sign-in and nothing is gated. The sign-in panel now streams in behind a Suspense boundary, so the rest of the page still prerenders. Meridian's own demo deploys to CapRover from this repository (`Dockerfile`, `captain-definition`, neither in the package).
+
+### Changed
+
+- **`update` is tested from the last three releases.** The release updates a project of the release before, adopted and created, through finalize; the weekly run the last three. Every published origin used to run at each release, which took 11 of its 18 minutes and grew with every release. From an older project, update in steps (`references/update.md`).
+
+### Fixed
+
+- **A project leaves an update in progress and each person's agent settings out of git.** Its `.gitignore` (the template's, for a created project; three lines `adopt` adds, for an adopted one) ignores `.meridian/update/` and `.meridian/update.lock`, the staged copies, backups and lock of an unfinished update, which a commit mid-session used to take in; a created project also ignores `.claude/settings.local.json` and `.claude/*.lock`. The manifest, `keep.json`, `.meridian/history/` and both copies of the skill stay committed: the next update and the team's agents read them. In a project made before 0.8.0, add those lines to `.gitignore`.
+- **The one sentence shows its blank.** It ended in `<what you want>`, which GitHub and npm read as an HTML tag and dropped, so it read "installs to: .". It ends in `[what you want, in your own words]`.
+
 ## [0.7.0] · 2026-10-06
 
 ### Changed

package/payload/README.md

@@ -74,15 +74,16 @@ Dark is the default, written on `:root`; the light theme follows the operating s
 | `scripts/` | Generators, gates, `brand.ts` and `verify.ts` (see `CONTRIBUTING.md`) |
 | `skills/zz-meridian/` | The agent skill (Claude Code, Codex) that builds dashboards on this template or brings it into yours |
 | `cli/` | The `zz-meridian` npm package: `create`, `adopt`, `update`, `brand` and `skill`, its build, its smoke test and the fixture app (`docs/distribution.md`) |
-| `.github/workflows/release.yml` | The release, each check once: a timed default verify and the consumer path from the tarball (every published origin updated), then npm with provenance, the registry's bytes and provenance checked, then the tag (`.claude/commands/release.md`) |
+| `.github/workflows/release.yml` | The release, each check once: a timed default verify and the consumer path from the tarball (the release before updated; the last three weekly), then npm with provenance, the registry's bytes and provenance checked, then the tag (`.claude/commands/release.md`) |
 | `.github/workflows/weekly.yml` | Weekly, never at release: `verify --full --perf` (perf a report) and the consumer smoke's recovery and failure cases; nothing waits on it |
+| `Dockerfile`, `captain-definition` | The demo deployment: the template and the Atlas behind `DEMO_PASSWORD` (`proxy.ts`, `app/sign-in/README.md`), deployed to CapRover from this repository; never in the package |
 
 ## Get a dashboard on Meridian, in one sentence
 
 Give your coding agent (Codex, Claude Code, or any agent that can run a shell) this, with what you want in your own
 words at the end:
 
-> Run `npx zz-meridian@latest skill --global`, then follow the zz-meridian skill it installs to: <what you want>.
+> Run `npx zz-meridian@latest skill --global`, then follow the zz-meridian skill it installs to: [what you want, in your own words].
 
 You do not choose between the package's commands; the skill does, from what you said and what is in the folder, and
 names the route before it runs anything:

package/payload/app/sign-in/README.md

@@ -25,6 +25,16 @@ Two columns from 1024px; one below, the panel under the sentence.
 | Invalid email | The field's error: "Enter your work email, like maya@zz-meridian.example." |
 | Sending | The primary button is busy |
 | Sent | The panel says "Check your inbox", names the address, and offers "Use another email" |
+| Demo | With `DEMO_PASSWORD` set at run time, the panel is "Open the demo": one password field (Field, Input `lg`) and "Open the demo" (primary, block, `lg`); a wrong password reads "That is not the demo password." in the field after 600 ms. A match sets a 30-day session and opens the console |
+| Loading | While the panel streams in, its surface holds its place, empty |
+
+## The demo gate
+
+`proxy.ts` and `src/lib/demo-gate.ts` put a password in front of the whole product when `DEMO_PASSWORD` is set: every
+route but this one redirects here (303), and an API answers 401. Opening this page signs the demo out, which is the
+rail's Sign out. `DEMO_SECRET`, when set, keys the session instead of the password. Without `DEMO_PASSWORD` nothing is
+gated and the panel is the product's sign-in. The panel is the only part of the page that reads the request; the rest
+prerenders (`gated-panel.tsx`, behind a Suspense boundary).
 
 ## Data
 

package/payload/app/sign-in/actions.ts

@@ -0,0 +1,19 @@
+'use server';
+
+import { cookies, headers } from 'next/headers';
+import { redirect } from 'next/navigation';
+import { COOKIE, MAX_AGE, samePassword, token } from '@/lib/demo-gate';
+
+export type DemoSignInState = { error: boolean };
+
+/** Checks the demo password: a match sets the session and opens the console, a miss comes back after 600 ms. */
+export async function demoSignIn(_: DemoSignInState, form: FormData): Promise<DemoSignInState> {
+  const given = String(form.get('password') ?? '').slice(0, 512);
+  if (!samePassword(given)) {
+    await new Promise((r) => setTimeout(r, 600));
+    return { error: true };
+  }
+  const secure = (await headers()).get('x-forwarded-proto') === 'https';
+  (await cookies()).set(COOKIE, token(), { httpOnly: true, path: '/', sameSite: 'lax', maxAge: MAX_AGE, secure });
+  redirect('/');
+}

package/payload/app/sign-in/gated-panel.tsx

@@ -0,0 +1,9 @@
+import { connection } from 'next/server';
+import { PasswordPanel, SignInPanel } from './panel';
+import { gated } from '@/lib/demo-gate';
+
+/** The demo's password when `DEMO_PASSWORD` is set at run time, the product's sign-in otherwise; the page around it prerenders. */
+export async function GatedPanel() {
+  await connection();
+  return gated() ? <PasswordPanel /> : <SignInPanel />;
+}

package/payload/app/sign-in/page.tsx

@@ -1,4 +1,6 @@
-import { SignInPanel } from './panel';
+import { Suspense } from 'react';
+import { GatedPanel } from './gated-panel';
+import { PanelFrame } from './panel';
 import { SampleFooter } from '@/views/sample-footer';
 import { Standalone } from '@/views/standalone';
 import { Meridian } from '@/components/charts/meridian';
@@ -18,7 +20,7 @@ export default function SignInPage() {
       kicker={`${app.name} · Console`}
       sentence="Know your API before your customers do."
       lead="Traffic, latency, spend and health for every endpoint, on your desk, on your phone, and inside the assistant you already use."
-      aside={<SignInPanel />}
+      aside={<Suspense fallback={<PanelFrame />}><GatedPanel /></Suspense>}
     >
       {/* The proof is the signature itself: point at a day and the line reads it, as every chart in the console does. */}
       <figure className="mt-12 max-w-xl rounded-xl border border-line bg-surface/60 p-5 backdrop-blur-md max-lg:hidden">

package/payload/app/sign-in/panel.tsx

@@ -1,11 +1,43 @@
 'use client';
 
-import { useState, type FormEvent } from 'react';
-import { ArrowRight, KeyRound, Mail } from 'lucide-react';
+import { useActionState, useState, type FormEvent, type ReactNode } from 'react';
+import { ArrowRight, KeyRound, LockKeyhole, Mail } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import { Field } from '@/components/ui/field';
 import { Input } from '@/components/ui/input';
 import { app, domain } from '@/app.config';
+import { demoSignIn } from './actions';
+
+/** The panel's surface, shared by both panels and the placeholder that holds their place while one streams in. */
+export function PanelFrame({ children }: { children?: ReactNode }) {
+  return (
+    <section aria-labelledby={children ? 'sign-in' : undefined} aria-hidden={children ? undefined : true} className="relative overflow-hidden rounded-xl border border-line bg-surface/80 p-7 shadow-overlay backdrop-blur-xl sm:p-8">
+      <span aria-hidden className="absolute inset-x-8 top-0 h-px bg-linear-to-r from-transparent via-accent-ink/60 to-transparent" />
+      {children ?? <div className="min-h-[22rem]" />}
+    </section>
+  );
+}
+
+/** The demo's panel, when `DEMO_PASSWORD` is set: one password field and one primary action. */
+export function PasswordPanel() {
+  const [state, action, pending] = useActionState(demoSignIn, { error: false });
+  return (
+    <PanelFrame>
+      <form action={action}>
+        <span className="grid size-11 place-items-center rounded-full bg-accent-tint text-accent-ink"><LockKeyhole className="size-5" /></span>
+        <h2 id="sign-in" className="t-section mt-5">Open the demo</h2>
+        <p className="t-small mt-2 text-ink-2">{app.name} on sample data. Enter the password you were given.</p>
+        <input type="text" name="username" value="demo" autoComplete="username" readOnly hidden />
+        <div className="mt-7 flex flex-col gap-4">
+          <Field label="Demo password" error={state.error ? 'That is not the demo password.' : undefined}>
+            {(p) => <Input {...p} name="password" type="password" size="lg" autoComplete="current-password" required autoFocus leading={<KeyRound className="size-4" />} />}
+          </Field>
+          <Button type="submit" variant="primary" size="lg" block busy={pending} trailing={<ArrowRight />}>Open the demo</Button>
+        </div>
+      </form>
+    </PanelFrame>
+  );
+}
 
 /** The sign-in panel: one field, one primary action, SSO beside it. A sent link replaces the form, never a toast. */
 export function SignInPanel() {
@@ -27,8 +59,7 @@ export function SignInPanel() {
     setState('sso');
   };
   return (
-    <section aria-labelledby="sign-in" className="relative overflow-hidden rounded-xl border border-line bg-surface/80 p-7 shadow-overlay backdrop-blur-xl sm:p-8">
-      <span aria-hidden className="absolute inset-x-8 top-0 h-px bg-linear-to-r from-transparent via-accent-ink/60 to-transparent" />
+    <PanelFrame>
       {state === 'sent' ? (
         <div role="status">
           <span className="grid size-11 place-items-center rounded-full bg-accent-tint text-accent-ink"><Mail className="size-5" /></span>
@@ -60,6 +91,6 @@ export function SignInPanel() {
           <p className="t-caption mt-6 text-pretty">By continuing you agree to the Terms and the Privacy notice. We never post anything for you.</p>
         </form>
       )}
-    </section>
+    </PanelFrame>
   );
 }

package/payload/decisions/0010-the-adopter-contract.md

@@ -54,8 +54,10 @@ this is the reason they agree.
   refuses, keeping every backup, when a path it wrote was edited since.
 - `--resume`, `--finalize` and `--abort` belong to the package version that began the session. They read the session's
   own copies and never ask the registry.
-- Updates start from 0.3.0. The four published origins, a project adopted and a project created with 0.3.0 and with
-  0.4.0, are the supported starting points, and the release smoke runs every one of them through update and finalize.
+- Updates start from 0.3.0. An update is tested from the last three releases, adopted and created: the release smoke
+  runs the release before through update and finalize, and the weekly smoke the last three. The window moves with each
+  release and never grows; from an older project, update in steps (`references/update.md`). Every published origin was
+  tested at release until 0.7.0, when the smoke took 11 of the release's 18 minutes and grew with each release.
 
 ### The access seam, scoped caching and live data
 
@@ -96,9 +98,9 @@ this is the reason they agree.
 - Weekly is weekly, release is release, and nothing runs twice. The release gates, each once, on the default verify
   from a clean `.next` on the GitHub-hosted ubuntu-24.04 4-CPU runner (at most 120 s, raised to 180 s in 0.6.0 because the runner's CPU varies, with its browser smoke; the gate
   and its unit tests run inside it) and on the consumer smoke from the tarball: adopt, create with its default verify,
-  and all four published origins updated through finalize. After publishing it checks the registry serves the tested
+  and the release before updated through finalize (the last three weekly). After publishing it checks the registry serves the tested
   tarball (equal sha256) with provenance, and tags last. A weekly workflow runs `verify --full --perf` (the perf part a
-  report) and the consumer smoke's adopted default-verify cases and recovery and failure cases; a failure notifies and
+  report) and the consumer smoke's adopted default-verify cases, the update from the last three releases, and its recovery and failure cases; a failure notifies and
   nothing waits on it.
 
 ### Every breaking interface, with its migration

package/payload/docs/distribution.md

@@ -6,7 +6,7 @@ Status: v1 (`create`, `adopt`, `skill`) shipped in 0.2.0 (decision 0009). v2 (`u
 
 A team gives its coding agent this, with what it wants in its own words at the end:
 
-> Run `npx zz-meridian@latest skill --global`, then follow the zz-meridian skill it installs to: <what you want>.
+> Run `npx zz-meridian@latest skill --global`, then follow the zz-meridian skill it installs to: [what you want, in your own words].
 
 The sentence names no command, because people do not: "change this product into our dashboard", "a new one based on
 this folder, in another folder" and "build an orders console" all ask for a dashboard on Meridian and differ only in
@@ -218,8 +218,10 @@ Modelled on the release pipeline of the owner's earlier packages, one package in
    - `adopt` into `cli/test/fixture-next-app` (a minimal App Router app with one page and its own stylesheet), then
      install, `tsc --noEmit` and `next build`, all green. This is the test that keeps the Route A list complete.
    - `create` into a clean folder, then its default `pnpm verify`. The smoke quotes the coverage line.
-   - `update` from every published origin since 0.3.0 (adopted and created) through finalize, as above. A 0.5.0 origin
-     reports no migration; a created one with nothing to resolve completes in the update itself.
+   - `update` from the release before (adopted and created, read from the registry): a dry-run that writes nothing, the
+     update, what it reports resolved, finalize with the gate and the build, and the team's bytes unchanged. One origin
+     at release and the last three weekly, so the time stays the same however many releases there are; the updater's
+     own stages and each migration have their tests (`--update-all`, `tests/cli-*`).
 5. **Publish** the tarball with `npm` 11.5.1 or newer through trusted publishing (OIDC), with `--provenance`. `pnpm
    publish` does not perform the OIDC exchange.
 6. **The registry's package**: `npx zz-meridian@<version> --version` answers the version, the registry's tarball has the
@@ -234,8 +236,10 @@ Modelled on the release pipeline of the owner's earlier packages, one package in
 
 **Weekly** (`.github/workflows/weekly.yml`, Mondays and on demand, master's current commit): the template's
 `verify --full --perf`, one gate and one build for both (the perf part a report: a p95 over budget is a warning, a
-broken sample a failure), and the consumer smoke's `--adopt --update-all --verify` from a tarball packed from that
-commit: the adopted project's default verify cases and every recovery and failure case of the update. Weekly is weekly
+broken sample a failure), and the consumer smoke's `--adopt --update --origins 3 --update-all --verify` from a tarball packed from that
+commit, labelled as the next patch so `update` treats it as unpublished: the adopted project's default verify cases,
+the update from each of the last three releases, the updater's stages on the 0.3.0 fixture, and every recovery and
+failure case of the update. Weekly is weekly
 and release is release: neither runs what the other does. Each job keeps its log as an artifact. A failure notifies;
 nothing waits on it.
 

package/payload/gitignore

@@ -28,6 +28,16 @@ test-results
 # deployment
 .vercel
 
+# zz-meridian: an update in progress (its staged copies, backups and lock). .meridian/manifest.json, keep.json and
+# history/ are committed: the next update reads them.
+/.meridian/update/
+/.meridian/update.lock
+
+# agents: each person's own settings and runtime files. The skills under .claude/skills and .agents/skills are
+# committed: they are the version of the skill that matches this project's Meridian, and update keeps them so.
+/.claude/settings.local.json
+/.claude/*.lock
+
 # logs
 *-debug.log*
 *-error.log*

package/payload/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian-template",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "private": true,
   "license": "MIT",
   "description": "ZZ Meridian: a dashboard design system and starter. DTCG tokens, five layers of React components and a Design Atlas, in a light and a dark theme.",

package/payload/proxy.ts

@@ -0,0 +1,37 @@
+import { NextResponse, type NextRequest } from 'next/server';
+import { COOKIE, MAX_AGE, expiresOf, gated, token } from '@/lib/demo-gate';
+
+/**
+ * The demo's password gate (`src/lib/demo-gate.ts`), open unless `DEMO_PASSWORD` is set. Every route needs a live
+ * session except the sign-in page and the files a browser fetches for it; an API answers 401 instead of redirecting.
+ * Opening the sign-in page signs the demo out, which is what the rail's Sign out does. A visit past half the session's
+ * life renews it.
+ */
+export function proxy(req: NextRequest) {
+  if (!gated()) return NextResponse.next();
+  const { pathname } = req.nextUrl;
+  const value = req.cookies.get(COOKIE)?.value;
+  if (pathname === '/sign-in') {
+    const res = NextResponse.next();
+    // A POST here is the sign-in itself, which sets the session; only a visit clears it.
+    if (req.method === 'GET' && value) res.cookies.set(COOKIE, '', { path: '/', maxAge: 0 });
+    return res;
+  }
+  const expires = expiresOf(value);
+  if (!expires) {
+    if (pathname.startsWith('/api/')) return NextResponse.json({ error: 'Sign in to the demo first.' }, { status: 401 });
+    const to = req.nextUrl.clone();
+    to.pathname = '/sign-in';
+    to.search = '';
+    return NextResponse.redirect(to, 303);
+  }
+  const res = NextResponse.next();
+  if (expires - Date.now() / 1000 < MAX_AGE / 2) {
+    res.cookies.set(COOKIE, token(), { httpOnly: true, path: '/', sameSite: 'lax', maxAge: MAX_AGE, secure: req.headers.get('x-forwarded-proto') === 'https' });
+  }
+  return res;
+}
+
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon|icon|apple-icon).*)'],
+};

package/payload/scripts/check.ts

@@ -281,11 +281,12 @@ const retirements: Retirement[] = [];
 }
 
 // ── The template's request boundaries ────────────────────────────────────────────────────────────────
-// Two places read the request: the console layout, which hands the shell a promise, and the not-found page, which streams
-// the address in. A `connection()` anywhere else makes the page behind it wait for the request, and a template whose
+// Three places read the request: the console layout, which hands the shell a promise, the not-found page, which streams
+// the address in, and the sign-in page's panel, which streams in as the demo's password or the product's sign-in, set by
+// DEMO_PASSWORD at run time. A `connection()` anywhere else makes the page behind it wait for the request, and a template whose
 // pages all prerender has none. In a product those pages are the team's, so the rule is the template's alone.
 if (!fs.existsSync(manifestFile)) {
-  const BOUNDARIES = [`${APP_DIR}/(dashboard)/layout.tsx`, `${APP_DIR}/not-found.tsx`];
+  const BOUNDARIES = [`${APP_DIR}/(dashboard)/layout.tsx`, `${APP_DIR}/not-found.tsx`, `${APP_DIR}/sign-in/gated-panel.tsx`];
   /** Comments blanked, not removed, so a line number is the file's. */
   const blanked = (f: string) => read(f).replace(/\/\*[\s\S]*?\*\//g, (c) => c.replace(/[^\n]/g, ' ')).replace(/(^|[^:])\/\/[^\n]*/g, '$1');
   const lineOf = (src: string, at: number) => src.slice(0, at).split('\n').length;
@@ -293,7 +294,7 @@ if (!fs.existsSync(manifestFile)) {
   for (const f of sources) {
     if (BOUNDARIES.includes(f)) continue;
     blanked(f).split('\n').forEach((line, i) => {
-      if (/\bconnection\s*\(/.test(line)) problems.push(`${f}:${i + 1}: connection() outside the template's two request boundaries`);
+      if (/\bconnection\s*\(/.test(line)) problems.push(`${f}:${i + 1}: connection() outside the template's three request boundaries`);
     });
   }
   // A page and a view read the sample through src/data, so the day it becomes an API is one file's change. Every
@@ -339,7 +340,8 @@ const TOOLKIT = /^src\/lib\/(format|color|collection|live)\.ts$/;
 // release may add an export the team's code does not use yet. Only the project's own src/lib and src/data are swept.
 // The template, with no manifest, is swept whole.
 const meridians = new Set(Object.keys(effective?.files ?? {}));
-const kept = ['src', 'app', 'scripts'].flatMap((d) => walk(d, /\.tsx?$/)).filter((f) => !/(^|\/)preview\.tsx$/.test(f) && !f.startsWith('app/system/') && !atlasOnly.includes(f));
+// A root proxy.ts is the product's own code too: Next runs it before every request.
+const kept = [...['src', 'app', 'scripts'].flatMap((d) => walk(d, /\.tsx?$/)), ...(fs.existsSync(path.join(ROOT, 'proxy.ts')) ? ['proxy.ts'] : [])].filter((f) => !/(^|\/)preview\.tsx$/.test(f) && !f.startsWith('app/system/') && !atlasOnly.includes(f));
 const resolveSpec = (from: string, spec: string) => {
   const base = spec.startsWith('@/') ? path.join('src', spec.slice(2)) : spec.startsWith('.') ? path.join(path.dirname(from), spec) : null;
   if (!base) return null;

package/payload/skills/zz-meridian/references/update.md

@@ -5,6 +5,10 @@ Meridian would change, and which of those changes need the team's decision. It w
 `npx zz-meridian@latest update` then applies the safe changes and stages the rest. Do not copy files by hand to make up
 for either.
 
+An update is tested from the last three releases. When the manifest's version is older than that (`npm view
+zz-meridian versions` lists them), update in steps: first with the release three after it,
+`npx zz-meridian@<that version> update`, through finalize, then again with `latest`.
+
 ## What it does
 
 It works from `optional:.meridian/manifest.json`, which records the release the project was copied from and a hash of

package/payload/src/lib/demo-gate.ts

@@ -0,0 +1,39 @@
+/**
+ * A password in front of the whole product, for a demo deployment: an HttpOnly cookie holding an expiry and its HMAC.
+ * It is closed only when `DEMO_PASSWORD` is set; without it (local development, and every product that never sets it)
+ * nothing is gated. The key is derived from `DEMO_SECRET` (or, without it, from `DEMO_PASSWORD`), so a session survives
+ * restarts and redeploys, and changing either signs everyone out. A session lasts 30 days and is renewed when a visit
+ * finds it past half its life. Server only.
+ */
+import crypto from 'node:crypto';
+
+export const COOKIE = 'zz_meridian_demo';
+export const MAX_AGE = 30 * 24 * 3600;
+
+const password = () => process.env.DEMO_PASSWORD ?? '';
+/** Whether the gate is closed: only when a password is configured. */
+export const gated = () => password() !== '';
+const key = () => crypto.createHmac('sha256', process.env.DEMO_SECRET || password()).update('zz-meridian-demo-session-v1').digest();
+const sign = (expires: number | string) => crypto.createHmac('sha256', key()).update(String(expires)).digest('hex');
+
+/** A fresh session value: expiry.signature. */
+export function token(): string {
+  const expires = Math.floor(Date.now() / 1000) + MAX_AGE;
+  return `${expires}.${sign(expires)}`;
+}
+
+/** The session's expiry in seconds when the cookie value is genuine and unexpired, else 0. */
+export function expiresOf(value: string | undefined): number {
+  const m = value?.match(/^([0-9]+)\.([0-9a-f]{64})$/);
+  if (!m || Number(m[1]) < Date.now() / 1000) return 0;
+  const a = Buffer.from(m[2]!, 'hex');
+  const b = Buffer.from(sign(m[1]!), 'hex');
+  return a.length === b.length && crypto.timingSafeEqual(a, b) ? Number(m[1]) : 0;
+}
+
+/** Compares with the configured password in constant time, whatever the lengths. */
+export function samePassword(given: string): boolean {
+  const a = crypto.createHash('sha256').update(given).digest();
+  const b = crypto.createHash('sha256').update(password()).digest();
+  return gated() && crypto.timingSafeEqual(a, b);
+}

package/payload/tests/demo-gate.test.ts

@@ -0,0 +1,64 @@
+// @vitest-environment node
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { NextRequest } from 'next/server';
+import { COOKIE, MAX_AGE, expiresOf, gated, samePassword, token } from '@/lib/demo-gate';
+import { proxy } from '../proxy';
+
+const request = (path: string, { cookie, method = 'GET' }: { cookie?: string; method?: string } = {}) =>
+  new NextRequest(`https://demo.example${path}`, { method, headers: cookie ? { cookie: `${COOKIE}=${cookie}` } : {} });
+
+afterEach(() => { delete process.env.DEMO_PASSWORD; delete process.env.DEMO_SECRET; });
+
+describe('the demo gate, without DEMO_PASSWORD', () => {
+  it('is open: every route passes and no password matches', () => {
+    expect(gated()).toBe(false);
+    expect(samePassword('')).toBe(false);
+    expect(proxy(request('/')).headers.get('location')).toBeNull();
+    expect(proxy(request('/api/export/requests')).status).toBe(200);
+  });
+});
+
+describe('the demo gate, with DEMO_PASSWORD', () => {
+  beforeEach(() => { process.env.DEMO_PASSWORD = 'open sesame'; });
+
+  it('accepts the password and nothing else', () => {
+    expect(samePassword('open sesame')).toBe(true);
+    expect(samePassword('open sesam')).toBe(false);
+    expect(samePassword('')).toBe(false);
+  });
+  it('signs a session it can read back, and refuses a forged, an expired or a re-keyed one', () => {
+    const t = token();
+    expect(expiresOf(t)).toBeGreaterThan(Date.now() / 1000 + MAX_AGE - 5);
+    expect(expiresOf(`${Number(t.split('.')[0]) + 1}.${t.split('.')[1]}`)).toBe(0);
+    expect(expiresOf(`1.${t.split('.')[1]}`)).toBe(0);
+    expect(expiresOf(undefined)).toBe(0);
+    process.env.DEMO_SECRET = 'rotated';
+    expect(expiresOf(t)).toBe(0);
+  });
+  it('sends a visitor without a session to the sign-in page, and answers an API with 401', () => {
+    const page = proxy(request('/system'));
+    expect(page.status).toBe(303);
+    expect(new URL(page.headers.get('location')!).pathname).toBe('/sign-in');
+    expect(proxy(request('/api/assistant', { method: 'POST' })).status).toBe(401);
+  });
+  it('lets a session through, and renews one past half its life', () => {
+    const fresh = proxy(request('/', { cookie: token() }));
+    expect(fresh.headers.get('location')).toBeNull();
+    expect(fresh.cookies.get(COOKIE)).toBeUndefined();
+    vi.useFakeTimers();
+    try {
+      const t = token();
+      vi.setSystemTime(Date.now() + 20 * 24 * 3600 * 1000);
+      const renewed = proxy(request('/', { cookie: t })).cookies.get(COOKIE)?.value;
+      expect(renewed).not.toBe(t);
+      expect(expiresOf(renewed)).toBeGreaterThan(expiresOf(t));
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+  it('signs the demo out when the sign-in page is opened, and leaves the sign-in itself alone', () => {
+    expect(proxy(request('/sign-in')).status).toBe(200);
+    expect(proxy(request('/sign-in', { cookie: token() })).cookies.get(COOKIE)?.value).toBe('');
+    expect(proxy(request('/sign-in', { cookie: token(), method: 'POST' })).cookies.get(COOKIE)).toBeUndefined();
+  });
+});