acrylblends 1.0.1 → 1.0.2

package/docs/framework/agents/index.md

@@ -33,6 +33,24 @@ The `agent` template (a Cordis app; `acryl-app` is its old name and still works)
 
 See [Acryl in a Cordis app](../cordis/acryl-in-a-cordis-app.md), [Plugin lifecycle](../cordis/plugin-lifecycle.md) and [Mounting](../cordis/mounting.md).
 
+## The agent panel and the terminals
+
+The panel is a chat button on every page of the running app, and `driver-pty` adds real terminals to it. Both are **development only** (see [what runs in production](../guides/production.md)). They need the rows of the `agent` template (`agent` and `extensions`, with the `model`, `tools` and `memory` the agent brings), so start from that template:
+
+```sh
+npm create acrylblends@latest my-app agent
+cd my-app
+npm install
+npx acrylblends add agent-panel driver-pty
+npm install
+npm run dev
+```
+
+- `add` puts the `agent-panel` row (and `driver-pty`'s after it) in `blend.yaml` before the `routes` row and registers both in `src/app.ts`. On an app without the `agent` and `extensions` rows, such as `blank`, it refuses before it copies anything and says which rows are missing.
+- **The panel's coding agents are yours.** `claude`, `codex` and `pi` run on the machine that runs the app, in the app folder, with the login of the person who started it: `claude` and `codex` use their own signed-in sessions, and `pi` is offered when `DEEPSEEK_API_KEY` is set or `pi` has stored a DeepSeek login (`~/.pi/agent/auth.json`). A program that is not installed, or is not logged in, is not offered; nothing is shared between machines, and a workshop laptop needs its own login. The panel's own `agent` (the offline scripted one) needs none.
+- `pi` has to be an executable on the `PATH`; a shell function that wraps the binary is fine as long as the binary itself is found by `which pi`.
+- `driver-pty` brings `node-pty`, which ships prebuilt binaries for macOS, Windows and Linux. npm 11 and pnpm warn that its install script was not run (they ask you to approve dependency install scripts); you can ignore the warning. If no `pty:` terminal is offered and the app prints why at start, approve and rebuild: `npm approve-scripts node-pty`, then `npm rebuild node-pty` (pnpm: `pnpm approve-builds`).
+
 ## Checking that an agent can use the docs
 
 The repository has a manual gate: it creates a fresh app, starts a headless coding agent inside it with a one-line task (for example "add a /customers/count route with a test"),

package/docs/framework/cordis/migration-to-1-0.md

@@ -7,12 +7,13 @@
 An app made by `acrylblends init` carries copies of the framework plugins (`acryl-router`, `acryl-node-server`, `acryl-door`, `extensions`, ...) in `plugins/`. `acrylblends upgrade` brings them to the version of the installed package:
 
 ```sh
-npm install acrylblends@latest        # in an app that depends on the package; the agent template does not
-npx acrylblends upgrade --dry-run     # what would change, and the diff of every file you edited
-npx acrylblends upgrade               # do it
+npx acrylblends@latest upgrade --dry-run   # what would change, and the diff of every file you edited
+npx acrylblends@latest upgrade             # do it
 npm install && npm run check && npm test
 ```
 
+**Write `@latest`.** A bare `npx acrylblends upgrade` runs the `acrylblends` the app has installed, and an app made before 1.0 has a 0.x copy with no `upgrade` verb. It does not upgrade anything: depending on the platform and the version it prints its old help and exits 0 (so nothing happens and nothing says so), or answers "unknown command" and exits 2. `npx acrylblends@latest` fetches the current package and runs that. (After the first upgrade the app depends on 1.x, and the bare form works too.)
+
 - A file nobody edited is replaced. A file the app edited stops the upgrade: nothing is changed, the diff of what would be lost is shown, and the command exits 1. Move your change out of the plugin (a plugin of your own in `plugins/<name>/` is never touched), or run `npx acrylblends upgrade --force`, which saves the edited versions in `.acrylblends/upgrade-backup/<time>/` before replacing them.
 - `--diff` prints the diff of every changed file, not only the edited ones. `acrylblends upgrade acryl-router extensions` upgrades only those plugins.
 - A file of your own inside a library plugin folder (a note, a test) is kept and reported. A plugin that a newer version needs and the app lacks is added.

package/docs/framework/getting-started/desktop.md

@@ -36,6 +36,26 @@ In a Blend app, the same two commands (`npx acrylblends add desktop`, `npm insta
 `npm install` does not download Electron's binary (Electron 44 has no install script). The first `npm run desktop` does: about 100 MB, once per machine, then it is cached. Behind a proxy or mirror set `ELECTRON_MIRROR`
 (and `ELECTRON_CACHE` to reuse a download); if the download is blocked, run `npx install-electron` where the mirror is reachable.
 
+## Linux: Ubuntu 23.10 and later
+
+Ubuntu 23.10 and later restrict unprivileged user namespaces (`kernel.apparmor_restrict_unprivileged_userns=1`). Chromium's sandbox needs them, and an Electron unpacked by npm into `node_modules` has no AppArmor profile, so Electron stops at the start with "The SUID sandbox helper binary was found, but is not configured correctly" before the app runs.
+
+`npm run desktop` starts through `plugins/desktop/launch.ts`, which reads that sysctl. **Only when it is `1` on Linux** it starts Electron with `--no-sandbox` and prints one line saying so; on macOS, on Windows and on any Linux without the restriction Electron starts with its sandbox, as it always does. The window's renderer is still locked down (context isolation, no Node in the page, web security); what is lost is Chromium's process sandbox around it.
+
+To keep the sandbox, give Electron an AppArmor profile that allows `userns`, as the VS Code and Chrome `.deb` packages do. Save this as `/etc/apparmor.d/my-app-electron` (the path is the one in your app's `node_modules`), then `sudo apparmor_parser -r /etc/apparmor.d/my-app-electron`:
+
+```text
+abi <abi/4.0>,
+include <tunables/global>
+
+profile my-app-electron /path/to/my-app/node_modules/electron/dist/electron flags=(unconfined) {
+  userns,
+  include if exists <local/my-app-electron>
+}
+```
+
+The launcher then still sees the sysctl as `1` and passes `--no-sandbox`; set `ACRYLBLENDS_DESKTOP_SANDBOX=1` to start with the sandbox anyway.
+
 ## A different start page
 
 The window opens on `/`. To open another path, set it in `package.json`: `"acrylblends": { "desktopPath": "/todo" }`.

package/docs/framework/guides/create-acrylblends.md

@@ -54,6 +54,8 @@ bun create acrylblends@latest my-app --template nodejs
 | `[directory]` | The folder to create. It must not exist or must be empty. Asked for when it is missing. | `my-app` |
 | `[source]` | A template from outside the package: `github:owner/repo[#ref]`, `@scope/name[@version]` or a packed `.tgz` file. See [Templates from a repository or a package](#templates-from-a-repository-or-a-package). | `github:acme/starter` |
 | `--template <template>` | One of `blank`, `nodejs`, `notes`, `chat`, `todo`, `agent` (the same list as `acrylblends init --template`; `acryl-app` is accepted as `agent`). Skips the template question; a bare name after the directory means the same. | `--template notes` |
+| `--from <id \| source>` | A starter from the registry by its id (`acrylblends.notes-desktop`), or any source above. Only starters that declare `runtime: acrylblends` are made; an ACRYL app starter is refused. See [Starters from the registry](#starters-from-the-registry). | `-- --from acrylblends.notes-desktop` |
+| `--registry <source>` | Read the ids from this registry instead of the public one: `github:owner/repo` or a folder, with an `index.json` (at its root or in `registry/`). | `-- --from login.thing --registry github:acryldev/workshop-2026-11-20` |
 | `--install` | Install the dependencies with the package manager after creating the project. For a template from a source, the install scripts it will run are listed first. | `--install` |
 | `--pm <packageManager>` | The package manager for `--install`: `npm`, `pnpm`, `yarn` or `bun`. Defaults to the one that started the initializer. | `--pm pnpm` |
 | `--yes`, `-y` | Ask nothing: use `nodejs` unless `--template` is given, and the directory `acryl-app`. | `-y` |
@@ -61,6 +63,25 @@ bun create acrylblends@latest my-app --template nodejs
 
 The templates are inside the package, so creating a project needs no network except for `--install`.
 
+## Starters from the registry
+
+The [registry](https://acrylblends.github.io/blends) lists starters people published. Each is a whole app (`blend.yaml`, `plugins/`, `src/`, `package.json`, `README.md`) that other people can start from, and its index says which runtime it is for:
+
+```sh
+npm create acrylblends@latest my-notes -- --from acrylblends.notes-desktop
+cd my-notes
+npm install
+npm run dev
+```
+
+- npm needs the `--` before `--from`; with `pnpm`, `yarn` and `bun` it is not needed.
+- A starter with `runtime: acrylblends` is an `acrylblends` app: this command downloads its folder, gives the manifest to the new app (`metadata.id: acrylblends.my-notes`, `visibility: private`; the starter's id and licence stay the starter's), checks it for anything that looks like a secret, and writes it. Nothing in it is installed or run: `npm install` is yours to run, and the dependencies of the starter (a desktop starter brings `electron`) are in its `package.json`.
+- A starter for the ACRYL app (`runtime: acryl`, the older `acryl.*` entries) is refused with one line that says so, because its plugins run only inside the ACRYL app. Nothing is written.
+- An unknown id lists the starters this command can make.
+- The ids come from `https://acrylblends.github.io/registry/index.json`. `--registry github:owner/repo` reads another registry with the same layout (`index.json` and `blends/<id>/`), a team's own or a workshop's; `--registry ./folder` reads one on disk.
+
+To publish a starter of your own, see [the registry README](https://github.com/acrylblends/acrylblends.github.io/tree/main/registry): the folder of your app under `blends/<id>/` with an `acryl.template.json`, in a pull request.
+
 ## Templates from a repository or a package
 
 A second argument after the directory makes the app from someone else's template:

package/docs/framework/guides/production.md

@@ -11,6 +11,7 @@
 | **The agent panel** (`agent-panel`) | **experimental**: a script tag on every HTML page and `/api/agent-panel/*` | does nothing (no tag, no routes). `ACRYL_DOOR=off` too |
 | **The PTY driver** (`driver-pty`) | **experimental**: terminal drivers in the panel, `/api/driver-pty/*` | does nothing. `ACRYL_DOOR=off` too |
 | **Live plugin install and the agent** (`extensions`, `builder`, `agent`: `POST /ask`) | **experimental**: install, update, remove and reload plugins while the app runs; the agent builds them | left out: the `nodejs`, `notes` and `chat` templates drop the `extensions` row, and the `agent` template drops `agent`, `builder` and `extensions` (since 1.0.1) unless `ACRYL_PRODUCTION_KEEP` names them |
+| **The chat template's model endpoint** (`POST /api/chat`) | answers anyone | **closed** (503) unless `CHAT_ACCESS_TOKEN` is set, or `ACRYL_PRODUCTION_KEEP=chat` makes it public with a warning and a per-address limit (since 1.0.2) |
 | `acrylblends/bun` | **experimental**: one smoke gate runs it on Bun | the same |
 
 Experimental means: it works and is gated, its interface may still change in a minor version, and it is not for the public internet. The door and the panel are loopback and own-page only, with a per-run secret and an audit log; that is a convenience fence for a developer's machine, not an authentication system.
@@ -22,6 +23,15 @@ The `agent` template mounts an agent behind `POST /ask` that spends the model ke
 - To keep a row anyway, name it: `ACRYL_PRODUCTION_KEEP=agent,builder,extensions` (a comma list). Each row kept prints a `WARNING` line at start saying what it gives a visitor. Put your own login in front before you do.
 - **An app made by 1.0.0 keeps its own `src/app.ts` and `src/routes.ts`**, which `acrylblends upgrade` never touches (they are your files). Until you change them: deploy with the `agent`, `builder` and `extensions` rows set to `disabled: true` in `blend.yaml`, or start from another template, or copy the new `src/app.ts` and `src/routes.ts` of a fresh `acrylblends init my-app --template agent` over yours.
 
+## The `chat` template in production
+
+The chat template answers with the owner's model key, so anyone who can reach it spends that key. Since 1.0.2, with `NODE_ENV=production` it is **closed**: every route but `GET /health` answers 503 until you choose one of:
+
+- `CHAT_ACCESS_TOKEN=<a long random string>`: the browser asks for a login and takes any user name with the token as the password. Share the token with the people who may use the chat.
+- `ACRYL_PRODUCTION_KEEP=chat`: the chat is public, with a `WARNING` line at start and a limit of `CHAT_RATE_PER_MINUTE` messages a minute from one address (default 20; behind a proxy you run, set `TRUST_PROXY=1` so the limit counts the visitor, not the proxy). Prefer your own login in front.
+
+An app made by 1.0.0 or 1.0.1 keeps its own `src/routes.ts`: copy `src/access.ts`, `src/chat-app.ts` and `src/routes.ts` from a fresh `acrylblends init my-app --template chat`, or put a login in front.
+
 ## What live plugin install does and does not promise
 
 Installing a plugin (`ctx.extensions.install`, the door's `plugin add`, the builder's `install_plugin`) is a **correctness check, not a security boundary**:
@@ -41,6 +51,6 @@ Installing a plugin (`ctx.extensions.install`, the door's `plugin add`, the buil
 ## Checklist for a deployment
 
 1. `NODE_ENV=production` (the process manager or the Dockerfile sets it; the templates' Dockerfile does).
-2. With the `agent` template, leave `ACRYL_PRODUCTION_KEEP` unset (1.0.1 and later), or remove the agent rows.
+2. With the `agent` template, leave `ACRYL_PRODUCTION_KEEP` unset (1.0.1 and later), or remove the agent rows. With the `chat` template, set `CHAT_ACCESS_TOKEN` (1.0.2 and later) or put your own login in front.
 3. Do not set `allowInProduction` on the door unless the host is a single-user desktop app.
 4. Keep `ACRYL_DOOR=off` in any environment where an agent should not be able to see the page.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acrylblends",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "The Acryl web framework (import { Acryl } from \"acrylblends\") and the acrylblends command that scaffolds Cordis apps.",
   "license": "MIT",
   "type": "module",

package/plugins/agent-panel/headless.ts

@@ -1,5 +1,8 @@
 /** The panel's own drivers, all `chat`: the app's agent, and the coding agents (`claude`, `codex`, `pi`) started headless in the app folder. */
 import { spawn, spawnSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
 import type { ChatDriver, ChatEvent } from './drivers.ts'
 
@@ -62,11 +65,30 @@ export function onPath(program: string): boolean {
   return found.status === 0
 }
 
-/** The headless programs this machine can offer: installed (pi also needs its key in the environment). */
+/** Whether pi can reach DeepSeek: the key in the environment, or the one pi stored for itself when its owner logged in (`~/.pi/agent/auth.json`, a `deepseek` entry). */
+export function piHasDeepseekKey(
+  env: NodeJS.ProcessEnv = process.env,
+  home: string = homedir(),
+): boolean {
+  if (env.DEEPSEEK_API_KEY) return true
+  try {
+    const stored = JSON.parse(
+      readFileSync(
+        join(env.PI_CODING_AGENT_DIR ?? join(home, '.pi', 'agent'), 'auth.json'),
+        'utf8',
+      ),
+    ) as Record<string, { key?: unknown } | undefined>
+    return typeof stored.deepseek?.key === 'string' && stored.deepseek.key !== ''
+  } catch {
+    return false
+  }
+}
+
+/** The headless programs this machine can offer: installed (an executable on the PATH; a wrapper function around it is fine) and, for pi, able to reach its model. */
 export function availableHeadless(wanted?: readonly HeadlessName[]): HeadlessName[] {
   const found: HeadlessName[] = []
   for (const driver of wanted ?? (['claude', 'codex', 'pi'] as const)) {
-    if (driver === 'pi' && !process.env.DEEPSEEK_API_KEY) continue
+    if (driver === 'pi' && !piHasDeepseekKey()) continue
     if (onPath(driver)) found.push(driver)
   }
   return found

package/plugins/desktop/launch.ts

@@ -0,0 +1,48 @@
+/**
+ * `npm run desktop`: starts Electron on `main.ts` next to this file. It exists for one case: on Linux where the kernel restricts unprivileged user namespaces
+ * (Ubuntu 23.10 and later: `kernel.apparmor_restrict_unprivileged_userns=1`), Chromium's sandbox cannot start for an Electron that npm unpacked into node_modules, and Electron
+ * aborts before any of our code runs. There, and only there, it starts with `--no-sandbox` and says so; everywhere else Electron starts exactly as it does with the sandbox on.
+ */
+import { spawn } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** The sysctl that makes the sandbox fail for an Electron without an AppArmor profile; its value, or `undefined` where it does not exist (every system but a recent Ubuntu). */
+export const RESTRICT_USERNS = '/proc/sys/kernel/apparmor_restrict_unprivileged_userns'
+
+/** Whether the sandbox cannot start here: Linux, with the restriction on. `read` returns a file's text, or throws when there is none. */
+export function sandboxBlocked(
+  platform: string,
+  read: (path: string) => string = (path) => readFileSync(path, 'utf8'),
+): boolean {
+  if (platform !== 'linux') return false
+  try {
+    return read(RESTRICT_USERNS).trim() === '1'
+  } catch {
+    return false
+  }
+}
+
+export const SANDBOX_NOTICE =
+  "desktop: this Linux restricts unprivileged user namespaces (kernel.apparmor_restrict_unprivileged_userns=1), so Electron's sandbox cannot start; starting with --no-sandbox. " +
+  'To keep the sandbox, give Electron an AppArmor profile that allows `userns` (the way the VS Code and Chrome packages do): see docs/framework/getting-started/desktop.md'
+
+/** The arguments for Electron: the entry file, with `--no-sandbox` first when the sandbox is blocked. */
+export function electronArgs(entry: string, blocked: boolean): string[] {
+  return blocked ? ['--no-sandbox', entry] : [entry]
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const electron = createRequire(import.meta.url)('electron') as string
+  // ACRYLBLENDS_DESKTOP_SANDBOX=1: the owner has given Electron an AppArmor profile and wants the sandbox.
+  const blocked =
+    process.env.ACRYLBLENDS_DESKTOP_SANDBOX !== '1' && sandboxBlocked(process.platform)
+  if (blocked) console.warn(SANDBOX_NOTICE)
+  const child = spawn(electron, electronArgs(join(import.meta.dirname, 'main.ts'), blocked), {
+    stdio: 'inherit',
+  })
+  for (const signal of ['SIGINT', 'SIGTERM'] as const) process.on(signal, () => child.kill(signal))
+  child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)))
+}

package/plugins/desktop/plugin.json

@@ -9,7 +9,7 @@
     "electron": "44.9.3"
   },
   "scripts": {
-    "desktop": "electron plugins/desktop/main.ts"
+    "desktop": "node plugins/desktop/launch.ts"
   },
   "omit": ["**/*.test.*"],
   "mount": "nothing to mount: run `npm install`, then `npm run desktop` (the window opens on the app's own server; every electron call is in plugins/desktop)"

package/plugins/desktop-web/launch.ts

@@ -0,0 +1,48 @@
+/**
+ * `npm run desktop`: starts Electron on `main.ts` next to this file. It exists for one case: on Linux where the kernel restricts unprivileged user namespaces
+ * (Ubuntu 23.10 and later: `kernel.apparmor_restrict_unprivileged_userns=1`), Chromium's sandbox cannot start for an Electron that npm unpacked into node_modules, and Electron
+ * aborts before any of our code runs. There, and only there, it starts with `--no-sandbox` and says so; everywhere else Electron starts exactly as it does with the sandbox on.
+ */
+import { spawn } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** The sysctl that makes the sandbox fail for an Electron without an AppArmor profile; its value, or `undefined` where it does not exist (every system but a recent Ubuntu). */
+export const RESTRICT_USERNS = '/proc/sys/kernel/apparmor_restrict_unprivileged_userns'
+
+/** Whether the sandbox cannot start here: Linux, with the restriction on. `read` returns a file's text, or throws when there is none. */
+export function sandboxBlocked(
+  platform: string,
+  read: (path: string) => string = (path) => readFileSync(path, 'utf8'),
+): boolean {
+  if (platform !== 'linux') return false
+  try {
+    return read(RESTRICT_USERNS).trim() === '1'
+  } catch {
+    return false
+  }
+}
+
+export const SANDBOX_NOTICE =
+  "desktop: this Linux restricts unprivileged user namespaces (kernel.apparmor_restrict_unprivileged_userns=1), so Electron's sandbox cannot start; starting with --no-sandbox. " +
+  'To keep the sandbox, give Electron an AppArmor profile that allows `userns` (the way the VS Code and Chrome packages do): see docs/framework/getting-started/desktop.md'
+
+/** The arguments for Electron: the entry file, with `--no-sandbox` first when the sandbox is blocked. */
+export function electronArgs(entry: string, blocked: boolean): string[] {
+  return blocked ? ['--no-sandbox', entry] : [entry]
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const electron = createRequire(import.meta.url)('electron') as string
+  // ACRYLBLENDS_DESKTOP_SANDBOX=1: the owner has given Electron an AppArmor profile and wants the sandbox.
+  const blocked =
+    process.env.ACRYLBLENDS_DESKTOP_SANDBOX !== '1' && sandboxBlocked(process.platform)
+  if (blocked) console.warn(SANDBOX_NOTICE)
+  const child = spawn(electron, electronArgs(join(import.meta.dirname, 'main.ts'), blocked), {
+    stdio: 'inherit',
+  })
+  for (const signal of ['SIGINT', 'SIGTERM'] as const) process.on(signal, () => child.kill(signal))
+  child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)))
+}

package/plugins/desktop-web/plugin.json

@@ -9,7 +9,7 @@
     "electron": "44.9.3"
   },
   "scripts": {
-    "desktop": "electron plugins/desktop-web/main.ts"
+    "desktop": "node plugins/desktop-web/launch.ts"
   },
   "gitignore": [".acrylblends/"],
   "omit": ["**/*.test.*"],

package/templates/chat/AGENTS.md

@@ -13,4 +13,4 @@ A Cordis app: `blend.yaml` lists the plugins that are mounted (`acryl-router`, `
 
 ## Before you ship
 
-Read `docs/framework/getting-started/deploy.md`. In short: `npm ci --omit=dev`, `npm run build`, `NODE_ENV=production npm start`; the app listens on `127.0.0.1` (`HOST=0.0.0.0` only in a container); the SQLite file goes outside the code folder (`CHAT_DB=/var/lib/chat/chat.sqlite`) and is backed up; the model key is an environment variable of the service (a root-only environment file for systemd), never a file in the repository. Anyone who can reach the app can spend your key: put it behind a login or on a private network before it is public.
+Read `docs/framework/getting-started/deploy.md`. In short: `npm ci --omit=dev`, `npm run build`, `NODE_ENV=production npm start`; the app listens on `127.0.0.1` (`HOST=0.0.0.0` only in a container); the SQLite file goes outside the code folder (`CHAT_DB=/var/lib/chat/chat.sqlite`) and is backed up; the model key is an environment variable of the service (a root-only environment file for systemd), never a file in the repository. Anyone who can reach the app can spend your key, so with `NODE_ENV=production` the chat is **closed**: every route but `GET /health` answers 503 (`src/access.ts`). Set `CHAT_ACCESS_TOKEN` (the browser asks for it; any user name, the token as the password), or name the chat in `ACRYL_PRODUCTION_KEEP=chat` to make it public on purpose: that prints a `WARNING` at start and limits one address to `CHAT_RATE_PER_MINUTE` messages a minute (default 20). Prefer your own login in front of a public chat.

package/templates/chat/src/access.ts

@@ -0,0 +1,110 @@
+import { createHash, timingSafeEqual } from 'node:crypto'
+import { connectionOf, createMiddleware } from '../plugins/acryl-router/src/helpers/index.ts'
+import type { Context } from '../plugins/acryl-router/src/index.ts'
+import { basicAuth } from '../plugins/acryl-router/src/middleware/index.ts'
+
+/** Who may use the chat, and what the app prints about it at start. */
+export type Access =
+  /** Development, and every test: no gate. */
+  | { kind: 'open' }
+  /** Production with `ACRYL_PRODUCTION_KEEP=chat`: anyone, with a per-IP rate limit. */
+  | { kind: 'public'; perMinute: number; trustProxy: boolean }
+  /** Production with `CHAT_ACCESS_TOKEN`: the browser asks for it (any user name, the token as the password). */
+  | { kind: 'token'; token: string }
+  /** Production with neither: every route but `/health` answers 503. */
+  | { kind: 'closed' }
+
+export interface Decision {
+  readonly access: Access
+  /** Lines to print at start (a `WARNING` for a public chat, the reason for a closed one). */
+  readonly notices: readonly string[]
+}
+
+/**
+ * Anyone who can reach the chat spends the model key, so in production it is closed by default. Name the chat in `ACRYL_PRODUCTION_KEEP` to make it public
+ * (loudly, with a rate limit), or set `CHAT_ACCESS_TOKEN` to ask for a shared token.
+ */
+export function chatAccess(env: Readonly<Record<string, string | undefined>>): Decision {
+  if (env.NODE_ENV !== 'production') return { access: { kind: 'open' }, notices: [] }
+  const keep = (env.ACRYL_PRODUCTION_KEEP ?? '')
+    .split(',')
+    .map((name) => name.trim())
+    .filter(Boolean)
+  if (keep.includes('chat')) {
+    const perMinute = Number(env.CHAT_RATE_PER_MINUTE)
+    return {
+      access: {
+        kind: 'public',
+        perMinute: Number.isInteger(perMinute) && perMinute > 0 ? perMinute : 20,
+        trustProxy: env.TRUST_PROXY === '1',
+      },
+      notices: [
+        'WARNING: the chat is public in production because ACRYL_PRODUCTION_KEEP names "chat": anyone who can reach it spends your model key (each address is limited to a few messages a minute). Put your own login in front of it, or set CHAT_ACCESS_TOKEN instead.',
+      ],
+    }
+  }
+  const token = env.CHAT_ACCESS_TOKEN?.trim()
+  if (token) return { access: { kind: 'token', token }, notices: [] }
+  return {
+    access: { kind: 'closed' },
+    notices: [
+      'The chat is closed: with NODE_ENV=production it needs CHAT_ACCESS_TOKEN (the browser asks for it) or ACRYL_PRODUCTION_KEEP=chat to be public. Every route but /health answers 503 until then.',
+    ],
+  }
+}
+
+const digest = (text: string) => createHash('sha256').update(text).digest()
+
+/** The middleware for an access mode, mounted before the routes. `/health` is always open. */
+export function accessGate(access: Access) {
+  if (access.kind === 'open') return undefined
+  if (access.kind === 'closed')
+    return createMiddleware(async (c, next) => {
+      if (c.req.path === '/health') return next()
+      return c.json(
+        {
+          error:
+            'The chat is closed. Set CHAT_ACCESS_TOKEN, or ACRYL_PRODUCTION_KEEP=chat to make it public.',
+        },
+        503,
+      )
+    })
+  if (access.kind === 'token') {
+    const expected = digest(access.token)
+    const ask = basicAuth({
+      realm: 'chat',
+      verifyUser: (_user, password) => timingSafeEqual(digest(password), expected),
+    })
+    return createMiddleware(async (c, next) => (c.req.path === '/health' ? next() : ask(c, next)))
+  }
+  return rateLimit(access.perMinute, access.trustProxy)
+}
+
+/** At most `perMinute` messages a minute from one address (`POST /api/chat`); the table forgets an address a minute after its last message. */
+function rateLimit(perMinute: number, trustProxy: boolean) {
+  const seen = new Map<string, number[]>()
+  const addressOf = (c: Context) => {
+    if (trustProxy) {
+      const forwarded = c.req.header('x-forwarded-for')?.split(',').at(-1)?.trim()
+      if (forwarded) return forwarded
+    }
+    return connectionOf(c).remoteAddress ?? 'unknown'
+  }
+  return createMiddleware(async (c, next) => {
+    if (c.req.method !== 'POST' || c.req.path !== '/api/chat') return next()
+    const now = Date.now()
+    for (const [address, times] of seen)
+      if (now - (times.at(-1) ?? 0) > 60_000) seen.delete(address)
+    const address = addressOf(c)
+    const recent = (seen.get(address) ?? []).filter((time) => now - time < 60_000)
+    if (recent.length >= perMinute) {
+      seen.set(address, recent)
+      const wait = Math.ceil((60_000 - (now - (recent[0] ?? now))) / 1000)
+      c.header('retry-after', String(wait))
+      return c.json({ error: 'Too many messages. Try again in a minute.' }, 429)
+    }
+    recent.push(now)
+    seen.set(address, recent)
+    return next()
+  })
+}

package/templates/chat/src/chat-app.ts

@@ -5,6 +5,7 @@ import {
   streamSSE,
 } from '../plugins/acryl-router/src/helpers/index.ts'
 import { Acryl } from '../plugins/acryl-router/src/index.ts'
+import { type Access, accessGate } from './access.ts'
 import { chatStore } from './db.ts'
 import { type Llm, openAiCompatible } from './llm.ts'
 import { chatPage } from './page.tsx'
@@ -32,9 +33,14 @@ const ChatSchema: StandardSchema<ChatInput> = {
   },
 }
 
-export function createApp(db: Db, llm: Llm = openAiCompatible) {
+/** `access` is who may use the chat (default: anyone, as in development and in the tests); see `src/access.ts`. */
+export function createApp(db: Db, llm: Llm = openAiCompatible, access: Access = { kind: 'open' }) {
   const store = chatStore(db)
   const app = new Acryl()
+  const gate = accessGate(access)
+  if (gate) app.use(gate)
+
+  app.get('/health', (c) => c.json({ ok: true }))
 
   app.get('/', async (c) => {
     const id = Number(c.req.query('c'))

package/templates/chat/src/routes.ts

@@ -1,5 +1,6 @@
 import type { Context } from '@deepseek-ai/cordis'
 import type {} from '../plugins/acryl-db/src/cordis.ts'
+import { chatAccess } from './access.ts'
 import { createApp } from './chat-app.ts'
 import { openAiCompatible } from './llm.ts'
 import { createClient } from './runtime.ts'
@@ -9,7 +10,10 @@ export const routes = {
   name: 'routes',
   inject: ['router', 'db'],
   apply(ctx: Context) {
-    ctx.router.route('/', createApp(ctx.db, openAiCompatible))
+    // In production the chat is closed unless it has a token or is made public on purpose: anyone who reaches it spends the model key.
+    const { access, notices } = chatAccess(process.env)
+    for (const line of notices) console.warn(line)
+    ctx.router.route('/', createApp(ctx.db, openAiCompatible, access))
     ctx.router.route('/client', createClient())
   },
 }

package/templates/chat/test/chat.test.ts

@@ -7,6 +7,7 @@ import { fileURLToPath } from 'node:url'
 import type {} from '../plugins/acryl-db/src/cordis.ts'
 import type { Db } from '../plugins/acryl-db/src/index.ts'
 import { pinnedInstance, withPort } from '../plugins/instance/index.ts'
+import { chatAccess } from '../src/access.ts'
 import { createApp as boot } from '../src/app.ts'
 import { createApp } from '../src/chat-app.ts'
 import type { Llm } from '../src/llm.ts'
@@ -196,3 +197,67 @@ test('the chat page loads its client component, served by the running app', asyn
   assert.match(module.headers.get('content-type') ?? '', /javascript/)
   assert.equal((await running.root.router.request('/client/@acrylblends/jsx-dom.js')).status, 200)
 })
+
+const production = (env: Record<string, string> = {}) =>
+  chatAccess({ NODE_ENV: 'production', ...env })
+
+test('in development the chat is open and prints nothing', () => {
+  const { access, notices } = chatAccess({})
+  assert.equal(access.kind, 'open')
+  assert.deepEqual(notices, [])
+})
+
+test('in production the chat is closed until it has a token or is made public on purpose', async () => {
+  const closed = production()
+  assert.equal(closed.access.kind, 'closed')
+  assert.match(closed.notices.join(), /closed/)
+  const { llm, asked } = mock(['x'])
+  const app = createApp(await memoryDb(), llm, closed.access)
+  for (const path of ['/', '/api/conversations'])
+    assert.equal((await app.request(path)).status, 503, path)
+  assert.equal((await app.request('/api/chat', post({ message: 'hi' }))).status, 503)
+  assert.equal((await app.request('/health')).status, 200)
+  assert.equal(asked.length, 0)
+})
+
+test('with CHAT_ACCESS_TOKEN the browser must send it, as the password of a basic login', async () => {
+  const gated = production({ CHAT_ACCESS_TOKEN: 'a-long-shared-token' })
+  assert.equal(gated.access.kind, 'token')
+  assert.deepEqual(gated.notices, [])
+  const { llm, asked } = mock(['ok'])
+  const app = createApp(await memoryDb(), llm, gated.access)
+  const login = (password: string) => ({
+    ...post({ message: 'hi' }),
+    headers: {
+      'content-type': 'application/json',
+      authorization: `Basic ${Buffer.from(`me:${password}`).toString('base64')}`,
+    },
+  })
+  assert.equal((await app.request('/api/chat', post({ message: 'hi' }))).status, 401)
+  assert.equal((await app.request('/api/chat', login('wrong'))).status, 401)
+  assert.equal((await app.request('/health')).status, 200)
+  assert.equal(asked.length, 0)
+  const ok = await app.request('/api/chat', login('a-long-shared-token'))
+  assert.equal(ok.status, 200)
+  assert.deepEqual(
+    events(await ok.text()).map(([e]) => e),
+    ['meta', 'token', 'done'],
+  )
+})
+
+test('ACRYL_PRODUCTION_KEEP=chat makes the chat public with a loud WARNING and a per-address rate limit', async () => {
+  const open = production({ ACRYL_PRODUCTION_KEEP: 'agent, chat', CHAT_RATE_PER_MINUTE: '2' })
+  assert.equal(open.access.kind, 'public')
+  assert.match(open.notices.join(), /^WARNING: the chat is public in production/)
+  const { llm, asked } = mock(['ok'])
+  const app = createApp(await memoryDb(), llm, open.access)
+  const send = () => app.request('/api/chat', post({ message: 'hi' }))
+  assert.equal((await (await send()).text()).includes('event: done'), true)
+  assert.equal((await send()).status, 200)
+  const limited = await send()
+  assert.equal(limited.status, 429)
+  assert.ok(Number(limited.headers.get('retry-after')) > 0)
+  assert.equal(asked.length, 2)
+  // Other routes are not counted.
+  assert.equal((await app.request('/api/conversations')).status, 200)
+})

package/templates/notes/test/notes.test.ts

@@ -62,7 +62,7 @@ test('the home page sends a visitor to the notes, which send them to log in', as
 test('sign up validates, refuses a duplicate, and starts a session', async () => {
   const app = createApp(await memoryDb())
   assert.match(await (await app.request('/signup')).text(), /Create account/)
-  const bad = await app.request('/signup', form({ email: 'nope', password: 'short' }))
+  const bad = await app.request('/signup', form({ email: 'nope', password: 'no way' }))
   assert.equal(bad.status, 400)
   const text = await bad.text()
   assert.match(text, /valid email/)

package/templates/todo/src/main.ts

@@ -9,6 +9,8 @@ const chosen = selectInstance({
 })
 const app = await createApp(chosen)
 console.log(`${APP_NAME} listening on ${app.url} (data in ${chosen.home})`)
+// The list is served under /todo, not at the address above: say where to open it.
+console.log(`open ${app.url}/todo`)
 
 const stop = async () => {
   await app.stop()