acd87b6
@@ -0,0 +1,4 @@
node_modules/
*.db
*.db-wal
*.db-shm
@@ -0,0 +1,131 @@
# Working on this app
You are one of the crew on this repository. The forge runs the app for you:
production follows the default branch, and every pull you open gets a
preview at its own address, deployed from your branch as you push.
## The rules
- Work on the branch you were given. You cannot move the default branch;
  a person merges your pull once it is reviewed.
- Keep state under `FORGE_APP_DATA`. Never write elsewhere at runtime.
- Run `bun test` before you push. `forge.json`'s `app.test` runs it beside
  the app on every deploy, not before it: the preview comes up the moment
  the app answers and says `live`, or `serving · tests failed` the moment
  the suite disagrees. Every behaviour you add gets a test that would fail
  without it.
- `src/tty.ts` is the app's terminal. The exact command that reaches it is
  `FORGE_APP_SSH` at runtime; print that verbatim wherever the app tells
  people how to connect. What a person can do on the page they can do here,
  and nothing more: the terminal gates its reads and writes exactly as the
  page does (`FORGE_APP_USER_ROLE` is the forge's word on who is there), and a
  write made there reaches web viewers live like any other.
- Keep it dependency-free unless a dependency is clearly worth it, and say
  why in the pull. A dependency is code you now maintain.
- When you are done, push and stop. Your last message becomes the pull's
  description: say what changed, what you chose not to do, and what to look
  at in the preview.
## The shape
One implementation, many doors. Every operation is a function in
`src/actions.ts` — `(db, who, input)` in, data or a named failure out — and
the page (`src/routes.ts`, `src/page.ts`), the JSON API (`src/routes.ts`),
the MCP server (`src/mcp.ts`) and the terminal (`src/tty.ts`) call it. A
door reads its wire format and shapes the answer; it decides nothing. A
rule in an action holds at every door at once; a rule anywhere else is a
bug waiting for the door you forgot.
Identity comes from the forge (`src/who.ts`): `anon`, `user` or `admin`,
verified by signature, never by a cookie the app invents.
Every request passes the door (`src/security.ts`) before a route sees it:
writes are rationed, a write from another site is refused, and a request
under a resource's `api` path is refused — before its body is read — when
the table lets that person through that door for no row at all. The door
asks the same table the actions do; it never compares roles by hand, and
the action still decides about the real row. Do not route around it.
Every change is written down. An action that creates, updates or deletes
returns through `audited` (`src/actions.ts`), which appends a row to the
`audit` table — who, the resource and verb, the row, when, and whether
they were let — refused attempts included; the door records the writes it
turns away. Admins read it at `GET /api/audit` (the `audit` resource in
`contract.json`). Recording never fails a request: a row that cannot be
written is a log line.
Who may do what is a table, not code: `contract.json`. It declares the
roles — each names the roles below it, and how it is held: by everyone, by
the identity the forge signed, or by a row's column naming the person — and,
for every resource, the least role each of create, read, update, delete and
list needs. An action asks `permit(who, resource, verb, row)`
(`src/contract.ts`) and obeys the answer; it never compares `who.role`
itself. `src/can.ts` is the forge's evaluator, carried verbatim: do not
edit it. `src/contract.test.ts` acts as every identity at every door and
fails when a door and the table disagree.
A new kind of person is a new role in the table, under an existing one. A
change to a cell is a change of policy: say so in the pull's description.
A cell loosened — anything an identity could not do before that it can
after — is a wall: the forge shows the pull to a person and never lands it
on its own. Do not loosen a cell unless the issue asks for exactly that;
prefer a new role under an existing one, or a new resource, to widening a
door that was decided.
To add a concept:
- **An action** — a function in `src/actions.ts` that asks `permit`, its
  resource's row in `contract.json`, its door in `src/contract.test.ts`,
  and a test in `src/actions.test.ts` for what the table cannot say.
- **A migration** — append to `migrations` in `src/db.ts`. Never edit one
  that has run. `bun run src/db.ts --check` shows the version.
- **A page** — a row in `src/routes.ts` and a function in `src/page.ts`.
  With a second page, move them under `src/pages/` and keep one `layout`.
- **An API route** — a row in `src/routes.ts` that calls the action and
  answers with `answer(...)`; the status follows the failure. Give it an
  `api` entry beside it (a sentence, the body and answer as JSON Schema)
  and run `bun run contract:emit`: `contract/openapi.json` is committed,
  served at `/openapi.json`, and `bun test` fails while it is stale. A
  resource's routes live under the `api` path its `contract.json` entry
  names, so the door and the forge's probe find them.
- **A tool** — an entry in `tools` in `src/mcp.ts`: a name, one sentence,
  a JSON schema, the action.
- **A terminal command** — a key in `src/tty.ts` that calls the action and
  reports on the status line.
- **Something live** — `emit(type, data)` in the action, and
  `data-live="<types>"` on the region of the page that shows it.
- **A colour, a space, a size** — a token in `design/tokens.json` (a
  colour needs its dark value in `$extensions.mode.dark`), used as
  `var(--…)`. `bun run lint:design` refuses a raw `#hex`, `rgb(` or
  `hsl(` anywhere in `src/` or `static/`, and a `var(--…)` that names no
  token; `src/design.test.ts` runs it, and holds every pair of colours a
  person reads to 4.5:1 in both themes.
## The bar
- Security: every input is validated at the boundary and every output is
  escaped; every response carries the floor in `src/http.ts` (keep it,
  extend it); a POST that is not same-origin is refused; writes are
  rationed per person; secrets come from the environment (Settings → App →
  Environment), never the repository; no `eval`, no shell built from user
  text. A request body is capped by the bytes actually read (`readBody`),
  never by a Content-Length. `HEAD` answers like `GET`. A private thing
  needs an identity from `who`, and a cookie the app sets itself is
  `HttpOnly; SameSite=Lax`.
- Speed: the first paint is server-rendered HTML; JavaScript is small, in
  `static/`, linked by content (`asset()`) and cached for a year; no
  layout shift; what changes arrives over `/events`, never by polling;
  work that can wait is done after the response.
- A phone is a first-class client: the page works at 360px wide with no
  horizontal scroll, every control is at least 44px on a side
  (`--size-tap`), an input's text is never below 16px (a phone zooms into
  a smaller one), focus is always visible, whoever asked for less motion
  gets none, and the keyboard reaches everything a mouse does.
- Beauty is the tokens': light and dark both, from one file. A new page
  uses `layout`, which carries the tokens, the description and the Open
  Graph and card metadata a shared link unfurls with — pass the page's
  path so `og:url` is its own.
- Finish: the app boots, `/healthz` answers `{ ok, version, uptime }`
  (the forge polls it; keep it cheap and apart from the page), `/`
  answers, `bun test` is green, the README says how to use it and what is
  real versus simulated, `forge.json` says how to run it.
@@ -0,0 +1,125 @@
# glyph
Type a prompt, get SVG logos and icons drawn by Claude; preview in your theme, copy or download.
This is an app: the forge runs it. Production follows the default branch;
every open pull gets a preview at its own address with its own copy of the
data. Everything the app keeps lives under `FORGE_APP_DATA`, which is what
makes "production data" and "preview data" two different things.
```sh
PORT=8080 FORGE_APP_DATA=./data bun run src/server.ts   # run it here
bun test                                                # what `forge.json`'s app.test runs on every push
FORGE_APP_DATA=./data bun run src/tty.ts                # the terminal
FORGE_APP_DATA=./data bun run src/db.ts --check         # schema version, integrity
bun run lint:design                                     # no colour but the tokens'
bun run contract:emit                                   # rewrite contract/openapi.json from the routes
```
`app.test` in `forge.json` runs beside `app.run` in every deploy, not before
it: the preview comes up the moment the app answers, and says `live`, or
`serving · tests failed` the moment the suite disagrees.
## The shape
One implementation, many doors. `src/actions.ts` is every operation as a
plain function — `(db, who, input)` in, data or a named failure out — and
the page, the JSON API, the MCP server and the terminal all call it and
decide nothing themselves. `AGENTS.md` says how to add to it.
| file                               | what it is                                                     |
| ---------------------------------- | -------------------------------------------------------------- |
| `src/actions.ts`                   | list, add, delete; the audit trail, read                       |
| `contract.json`                    | who may do what: roles, and the least role each verb needs     |
| `src/contract.ts`, `src/can.ts`    | the table, read at boot; the forge's evaluator, verbatim       |
| `src/security.ts`                  | the door: rationing, same origin, the table before the body    |
| `src/audit.ts`                     | every change and every refused one, as a row                   |
| `src/who.ts`                       | who is asking, from the forge's signed headers                 |
| `src/db.ts`                        | SQLite under `FORGE_APP_DATA`, WAL, forward-only migrations    |
| `src/live.ts`                      | the in-process bus and `GET /events`                           |
| `src/mcp.ts`                       | the actions as MCP tools at `POST /mcp`                        |
| `src/routes.ts`                    | every path, in one table, each API route described beside it   |
| `src/openapi.ts`                   | the routes as OpenAPI; committed at `contract/openapi.json`    |
| `src/page.ts`                      | the HTML, rendered on the server, with its share metadata      |
| `design/tokens.json`, `src/tokens.ts` | the look as data, light and dark; compiled to `/tokens.css` |
| `src/http.ts`                      | the floor: headers, body cap, files                            |
| `src/server.ts`                    | boot: open the database, serve                                 |
| `src/tty.ts`                       | the terminal, over the same actions                            |
| `src/env.ts`                       | what the forge told this process                               |
| `static/app.css`, `static/live.js` | the look in the tokens' words, and the list that stays current |
## What every app stands on
- **The door.** Before a route sees a request, `src/security.ts` rations
  writes (and a stranger's API calls), refuses a write from another site,
  and turns away — before the body is read — anyone the table lets through
  a resource's door for no row at all: 401 for a stranger, 403 for anyone
  else. The action still decides about the real row.
- **The audit trail.** Every change, and every change refused, is a row:
  who, which resource and verb, which row, when, and whether they were
  let. Admins read it at `GET /api/audit`. A row that cannot be written
  is a log line, never a failed request.
- **The API, described.** `GET /openapi.json` is `contract/openapi.json`,
  written from the routes by `bun run contract:emit`; each operation names
  its cell of the table (`x-contract`). `bun test` fails while it is stale.
- **Up, or not.** `GET /healthz` answers `{ ok, version, uptime }`; the
  forge waits on it before it sends anyone to a deploy.
- **The look.** `design/tokens.json` holds every colour, space and size,
  light and dark; nothing else spells out a colour (`bun run lint:design`),
  and every pair a person reads meets 4.5:1 in both themes.
- **The open web.** A shared link unfurls (description, Open Graph, a
  card); `/robots.txt` keeps crawlers to the page, and out of previews
  entirely; `/.well-known/security.txt` sends a reporter to the forge
  that runs the app.
## Who you are
The forge says who is asking on every request it proxies, and the app
verifies the signature (`src/who.ts`); nothing else is trusted. Three tiers:
- **anon** — anyone. Reads.
- **user** — signed in to the forge and able to see this app. Adds notes, as
  themselves, and removes their own.
- **admin** — able to write this repository. Removes any note.
"Sign in" is `/__forge/signin?to=<path>` and "Sign out" is
`/__forge/signout`; the forge answers both on the app's own host, and
`/__forge/report` too: it sends anyone, with no account, to report a
problem on this app's repository, if that repository is public.
## Any interface
The same actions, the same rules, at every door. A script is the person
whose forge grant it carries; a bare script is anonymous.
```sh
curl https://<app>/api/notes
curl -X POST https://<app>/api/notes -H 'content-type: application/json' -d '{"body":"hi"}'
curl -X DELETE https://<app>/api/notes/1
```
As an MCP server, for Claude Code or Claude Desktop — `list_notes`,
`add_note`, `delete_note`:
```sh
claude mcp add --transport http __TITLE__ https://<app>/mcp
```
```json
{
  "mcpServers": { "__TITLE__": { "type": "http", "url": "https://<app>/mcp" } }
}
```
The page stays current over `/events`: a note someone else adds or removes
appears without a reload. Without JavaScript it is the same page, one
reload behind.
The terminal opens with the exact command in `FORGE_APP_SSH` when the app
runs (`ssh -p 2222 <name>@<forge>` — the app is the login name, the forge
the host; `<name>--<pull>@<forge>` for a preview's). It is `src/tty.ts` on
a real pty over the same data, as the account at the keyboard.
The forge sets `PORT`, `FORGE_APP_DATA`, `FORGE_APP_ENV` (`production` or
`preview`), `FORGE_APP_URL`, `FORGE_APP_COMMIT`, `FORGE_APP_SSH` and
`FORGE_APP_IDENTITY_KEY` when it starts the app. `forge.json` says how.
@@ -0,0 +1,30 @@
{
  "roles": {
    "anon": { "above": [], "held": { "by": "everyone" } },
    "user": { "above": ["anon"], "held": { "by": "identity", "role": "user" } },
    "author": { "above": ["user"], "held": { "by": "row", "column": "author_id" } },
    "admin": { "above": ["author"], "held": { "by": "identity", "role": "admin" } }
  },
  "resources": {
    "note": {
      "api": "/api/notes",
      "can": {
        "create": "user",
        "read": "anon",
        "update": "author",
        "delete": "author",
        "list": "anon"
      }
    },
    "audit": {
      "api": "/api/audit",
      "can": {
        "create": "nobody",
        "read": "admin",
        "update": "nobody",
        "delete": "nobody",
        "list": "admin"
      }
    }
  }
}
@@ -0,0 +1,578 @@
{
  "openapi": "3.1.0",
  "info": {
    "title": "glyph",
    "version": "0.1.0",
    "description": "Type a prompt, get SVG logos and icons drawn by Claude; preview in your theme, copy or download."
  },
  "paths": {
    "/api/notes": {
      "get": {
        "summary": "The notes, newest first.",
        "operationId": "getApiNotes",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The notes, newest first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Note"
                  }
                }
              }
            }
          },
          "default": {
            "description": "{ error, message }: why not",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-contract": {
          "resource": "note",
          "verb": "list",
          "least": "anon"
        }
      },
      "post": {
        "summary": "Add a note as the person asking.",
        "operationId": "postApiNotes",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "body": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 500
                  }
                },
                "required": [
                  "body"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Add a note as the person asking.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Note"
                }
              }
            }
          },
          "default": {
            "description": "{ error, message }: why not",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-contract": {
          "resource": "note",
          "verb": "create",
          "least": "user"
        }
      }
    },
    "/api/notes/{id}": {
      "get": {
        "summary": "One note.",
        "operationId": "getApiNotesId",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One note.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Note"
                }
              }
            }
          },
          "default": {
            "description": "{ error, message }: why not",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-contract": {
          "resource": "note",
          "verb": "read",
          "least": "anon"
        }
      },
      "patch": {
        "summary": "Change a note's words.",
        "operationId": "patchApiNotesId",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "body": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 500
                  }
                },
                "required": [
                  "body"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Change a note's words.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Note"
                }
              }
            }
          },
          "default": {
            "description": "{ error, message }: why not",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-contract": {
          "resource": "note",
          "verb": "update",
          "least": "author"
        }
      },
      "delete": {
        "summary": "Remove a note.",
        "operationId": "deleteApiNotesId",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Remove a note.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "id"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "{ error, message }: why not",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-contract": {
          "resource": "note",
          "verb": "delete",
          "least": "author"
        }
      }
    },
    "/api/audit": {
      "get": {
        "summary": "The audit trail, newest first; `before` pages back by id.",
        "operationId": "getApiAudit",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            }
          },
          {
            "name": "before",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The audit trail, newest first; `before` pages back by id.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/AuditRow"
                  }
                }
              }
            }
          },
          "default": {
            "description": "{ error, message }: why not",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-contract": {
          "resource": "audit",
          "verb": "list",
          "least": "admin"
        }
      }
    },
    "/api/audit/{id}": {
      "get": {
        "summary": "One row of the audit trail.",
        "operationId": "getApiAuditId",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One row of the audit trail.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditRow"
                }
              }
            }
          },
          "default": {
            "description": "{ error, message }: why not",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-contract": {
          "resource": "audit",
          "verb": "read",
          "least": "admin"
        }
      }
    },
    "/mcp": {
      "post": {
        "summary": "One JSON-RPC 2.0 message to the MCP server; its tools are the actions.",
        "operationId": "postMcp",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "jsonrpc": {
                    "const": "2.0"
                  },
                  "id": {},
                  "method": {
                    "type": "string"
                  },
                  "params": {
                    "type": "object"
                  }
                },
                "required": [
                  "jsonrpc",
                  "method"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One JSON-RPC 2.0 message to the MCP server; its tools are the actions.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "default": {
            "description": "{ error, message }: why not",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/healthz": {
      "get": {
        "summary": "Whether the app is up: its version, commit, environment and seconds since it started.",
        "operationId": "getHealthz",
        "responses": {
          "200": {
            "description": "Whether the app is up: its version, commit, environment and seconds since it started.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "version": {
                      "type": "string"
                    },
                    "commit": {
                      "type": "string"
                    },
                    "env": {
                      "type": "string"
                    },
                    "uptime": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "ok",
                    "version",
                    "uptime"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "{ error, message }: why not",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Note": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "body": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "author_id": {
            "type": "string"
          },
          "author_name": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "body",
          "author_id",
          "author_name",
          "created_at",
          "updated_at"
        ]
      },
      "AuditRow": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "who_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "who_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "role": {
            "enum": [
              "anon",
              "user",
              "admin"
            ]
          },
          "resource": {
            "type": "string"
          },
          "verb": {
            "type": "string"
          },
          "target": {
            "type": [
              "string",
              "null"
            ]
          },
          "allowed": {
            "enum": [
              0,
              1
            ]
          },
          "outcome": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "at",
          "role",
          "resource",
          "verb",
          "allowed",
          "outcome"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      }
    }
  }
}
@@ -0,0 +1,95 @@
{
  "$description": "The look, as data (W3C design tokens). Every colour the app shows is here and nowhere else: src/tokens.ts compiles this to /tokens.css at boot, and bun run lint:design refuses a raw colour anywhere else. A colour's $value is the light theme; $extensions.mode.dark is the dark one.",
  "color": {
    "$type": "color",
    "bg": {
      "$value": "#f6f6f3",
      "$extensions": { "mode": { "dark": "#131312" } }
    },
    "surface": {
      "$value": "#ffffff",
      "$extensions": { "mode": { "dark": "#1d1d1b" } }
    },
    "fg": {
      "$value": "#1c1c1a",
      "$extensions": { "mode": { "dark": "#ecece7" } }
    },
    "muted": {
      "$value": "#6b6b65",
      "$extensions": { "mode": { "dark": "#9a9a93" } }
    },
    "line": {
      "$value": "#e3e3dd",
      "$extensions": { "mode": { "dark": "#2c2c29" } }
    },
    "accent": {
      "$value": "#2f5bea",
      "$extensions": { "mode": { "dark": "#7c96ff" } }
    },
    "accent-fg": {
      "$value": "#ffffff",
      "$extensions": { "mode": { "dark": "#0f1a4d" } }
    },
    "danger": {
      "$value": "#c2410c",
      "$extensions": { "mode": { "dark": "#fb923c" } }
    },
    "toast-bg": {
      "$value": "#1c1c1a",
      "$extensions": { "mode": { "dark": "#ecece7" } }
    },
    "toast-fg": {
      "$value": "#f6f6f3",
      "$extensions": { "mode": { "dark": "#131312" } }
    },
    "shadow": {
      "$value": "#0000002e",
      "$extensions": { "mode": { "dark": "#00000080" } }
    }
  },
  "space": {
    "$type": "dimension",
    "1": { "$value": "0.25rem" },
    "2": { "$value": "0.5rem" },
    "3": { "$value": "0.75rem" },
    "4": { "$value": "1rem" },
    "5": { "$value": "1.5rem" },
    "6": { "$value": "2.5rem" }
  },
  "radius": {
    "$type": "dimension",
    "md": { "$value": "10px" },
    "pill": { "$value": "999px" }
  },
  "size": {
    "$type": "dimension",
    "tap": {
      "$value": "44px",
      "$description": "The least a control measures on a side."
    }
  },
  "font": {
    "$type": "fontFamily",
    "sans": {
      "$value": ["system-ui", "-apple-system", "Segoe UI", "sans-serif"]
    },
    "mono": {
      "$value": ["ui-monospace", "SFMono-Regular", "Menlo", "monospace"]
    }
  },
  "text": {
    "$type": "dimension",
    "sm": { "$value": "0.875rem" },
    "base": {
      "$value": "1rem",
      "$description": "Never below 16px: a phone zooms into a smaller input."
    },
    "lg": { "$value": "1.125rem" },
    "xl": { "$value": "1.5rem" }
  },
  "leading": {
    "$type": "number",
    "body": { "$value": 1.55 },
    "tight": { "$value": 1.2 }
  }
}
@@ -0,0 +1,8 @@
{
  "app": {
    "run": "bun run src/server.ts",
    "test": "bun test",
    "health": "/healthz",
    "tty": "bun run src/tty.ts"
  }
}
@@ -0,0 +1,13 @@
{
  "name": "glyph",
  "version": "0.1.0",
  "description": "Type a prompt, get SVG logos and icons drawn by Claude; preview in your theme, copy or download.",
  "private": true,
  "type": "module",
  "scripts": {
    "start": "bun run src/server.ts",
    "test": "bun test",
    "lint:design": "bun run scripts/lint-design.ts",
    "contract:emit": "bun run scripts/contract-emit.ts"
  }
}
@@ -0,0 +1,14 @@
/**
 * Write the API's description where git keeps it: contract/openapi.json,
 * from the routes' own `api` entries (src/openapi.ts). Run it after
 * changing a route or a cell of contract.json; the tests say when it is due.
 */
import { mkdirSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import { emit } from "../src/openapi.ts";
const dir = join(import.meta.dir, "..", "contract");
mkdirSync(dir, { recursive: true });
writeFileSync(join(dir, "openapi.json"), emit());
console.log("wrote contract/openapi.json");
@@ -0,0 +1,77 @@
/**
 * Every colour comes from `design/tokens.json`. This refuses a raw one —
 * `#hex`, `rgb(`, `hsl(` — anywhere else the app draws from: `static/`
 * and `src/`, tests aside. A colour spelled out in a stylesheet is a colour
 * the dark theme never hears about. It refuses a `var(--…)` in a stylesheet
 * that names no token, too: a typo there is a page quietly unstyled.
 *
 *   bun run lint:design    exit 1 and one line per raw colour, or silence
 */
import { readdirSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { tokens } from "../src/tokens.ts";
const RAW =
  /(?<![\w&])#(?:[0-9a-f]{8}|[0-9a-f]{6}|[0-9a-f]{3,4})(?![\w-])|\b(?:rgba?|hsla?)\(/gi;
/** The raw colours in one file's text: `path:line: …`, one per find. */
export function rawColours(path: string, text: string): string[] {
  return text
    .split("\n")
    .flatMap((line, i) =>
      [...line.matchAll(RAW)].map(
        (m) =>
          `${path}:${i + 1}: raw colour ${m[0]} — name it in design/tokens.json and use var(--…)`,
      ),
    );
}
/** The custom properties a stylesheet uses that no token defines. */
export function unknownTokens(
  path: string,
  text: string,
  known = new Set(tokens.map((t) => t.name)),
): string[] {
  return text
    .split("\n")
    .flatMap((line, i) =>
      [...line.matchAll(/var\((--[\w-]+)/g)]
        .filter((m) => !known.has(m[1]!))
        .map(
          (m) =>
            `${path}:${i + 1}: ${m[1]} is not a token in design/tokens.json`,
        ),
    );
}
/** The files the lint reads: what the page is drawn from, never the tokens themselves or the tests. */
export function drawnFrom(root: string): string[] {
  const walk = (dir: string): string[] =>
    readdirSync(join(root, dir), { withFileTypes: true }).flatMap((entry) => {
      const path = join(dir, entry.name);
      if (entry.isDirectory()) return walk(path);
      return /\.(css|js|ts|html)$/.test(entry.name) &&
        !/\.test\.ts$/.test(entry.name)
        ? [path]
        : [];
    });
  return ["static", "src"].flatMap(walk);
}
export function lint(root: string): string[] {
  return drawnFrom(root).flatMap((path) => {
    const text = readFileSync(join(root, path), "utf8");
    return [
      ...rawColours(path, text),
      ...(path.endsWith(".css") ? unknownTokens(path, text) : []),
    ];
  });
}
if (import.meta.main) {
  const problems = lint(join(import.meta.dir, ".."));
  // Generated app's lint CLI: stderr is its output.
  for (const problem of problems) console.error(problem);
  process.exit(problems.length === 0 ? 0 : 1);
}
@@ -0,0 +1,58 @@
import { expect, test } from "bun:test";
import { mkdtempSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { addNote, deleteNote, listNotes } from "./actions.ts";
import { openDb } from "./db.ts";
import type { Who } from "./who.ts";
const db = openDb(mkdtempSync(join(tmpdir(), "app-actions-")));
const anon: Who = { role: "anon" };
const alice: Who = { role: "user", id: "u1", name: "alice" };
const bob: Who = { role: "user", id: "u2", name: "bob" };
const root: Who = { role: "admin", id: "u0", name: "root" };
test("anyone reads; only a signed-in person adds, as themselves", () => {
  expect(listNotes(db, anon)).toEqual({ ok: true, value: [] });
  const refused = addNote(db, anon, { body: "hello" });
  expect(refused.ok).toBe(false);
  if (!refused.ok) expect(refused.error).toBe("signin_required");
  const added = addNote(db, alice, { body: "  hello  " });
  expect(added.ok).toBe(true);
  if (!added.ok) return;
  expect(added.value.body).toBe("hello");
  expect(added.value.author_id).toBe("u1");
  expect(added.value.author_name).toBe("alice");
  const all = listNotes(db, anon);
  expect(all.ok && all.value.length).toBe(1);
});
test("a note is one to five hundred characters", () => {
  for (const body of ["", "   ", "x".repeat(501)]) {
    const r = addNote(db, alice, { body });
    expect(r.ok).toBe(false);
    if (!r.ok) expect(r.error).toBe("invalid");
  }
});
test("only the author or an admin removes a note", () => {
  const mine = addNote(db, alice, { body: "mine" });
  if (!mine.ok) throw new Error(mine.message);
  const byBob = deleteNote(db, bob, { id: mine.value.id });
  expect(byBob.ok).toBe(false);
  if (!byBob.ok) expect(byBob.error).toBe("forbidden");
  const byAnon = deleteNote(db, anon, { id: mine.value.id });
  expect(byAnon.ok).toBe(false);
  if (!byAnon.ok) expect(byAnon.error).toBe("signin_required");
  expect(deleteNote(db, alice, { id: mine.value.id }).ok).toBe(true);
  const gone = deleteNote(db, alice, { id: mine.value.id });
  expect(gone.ok).toBe(false);
  if (!gone.ok) expect(gone.error).toBe("not_found");
  const bobs = addNote(db, bob, { body: "bob's" });
  if (!bobs.ok) throw new Error(bobs.message);
  expect(deleteNote(db, root, { id: bobs.value.id }).ok).toBe(true);
  const odd = deleteNote(db, root, { id: 1.5 });
  expect(odd.ok).toBe(false);
  if (!odd.ok) expect(odd.error).toBe("invalid");
});
@@ -0,0 +1,271 @@
/**
 * Everything the app can do, as plain functions: `(db, who, input)` in,
 * data or a named failure out. The page, the JSON API, the MCP server and
 * the terminal are doors onto these and decide nothing themselves — so a
 * rule written here holds at every door, and a new door is only a new
 * way to call.
 */
import type { Database } from "bun:sqlite";
import { record, type AuditRow } from "./audit.ts";
import { permit } from "./contract.ts";
import { emit } from "./live.ts";
import type { Who } from "./who.ts";
export interface Note {
  readonly id: number;
  readonly body: string;
  readonly author_id: string;
  readonly author_name: string;
  readonly created_at: string;
  readonly updated_at: string;
}
export type Failure = "signin_required" | "forbidden" | "not_found" | "invalid";
export type Result<T> =
  | { ok: true; value: T }
  | { ok: false; error: Failure; message: string };
const ok = <T>(value: T): Result<T> => ({ ok: true, value });
const fail = <T>(error: Failure, message: string): Result<T> => ({
  ok: false,
  error,
  message,
});
export const BODY_MAX = 500;
/** The refusal for a "no": who is not signed in is asked to; who is, is told. */
const refuse = <T>(who: Who, signIn: string, no: string): Result<T> =>
  who.role === "anon" ? fail("signin_required", signIn) : fail("forbidden", no);
/**
 * A change, written into the audit trail whichever way it went: the row it
 * made or touched, or the one it was refused. Every action that changes
 * something returns through here, so the trail holds at every door.
 */
const audited = <T extends { readonly id: number }>(
  db: Database,
  who: Who,
  resource: string,
  verb: "create" | "update" | "delete",
  target: number | undefined,
  result: Result<T>,
): Result<T> => {
  record(db, {
    who,
    resource,
    verb,
    target: result.ok ? result.value.id : target,
    outcome: result.ok ? "ok" : result.error,
  });
  return result;
};
export function listNotes(
  db: Database,
  who: Who,
  input: { limit?: number } = {},
): Result<Note[]> {
  const limit = Math.min(
    Math.max(Math.trunc(input.limit ?? 100) || 100, 1),
    500,
  );
  // "yes" is every note. When the table gives `list` to a role a row holds
  // (`author`), the answer names the columns instead, and the list is the
  // notes that name whoever asks. The names are the contract's, checked when
  // it was read; the value is bound.
  const may = permit(who, "note", "list");
  if (may === "no")
    return refuse(who, "Sign in to see notes.", "You may not see these notes.");
  if (may === "yes")
    return ok(
      db
        .query<Note, [number]>("SELECT * FROM note ORDER BY id DESC LIMIT ?1")
        .all(limit),
    );
  const mine = may.where.map((column) => `${column} = ?2`).join(" OR ");
  return ok(
    db
      .query<
        Note,
        [number, string]
      >(`SELECT * FROM note WHERE ${mine} ORDER BY id DESC LIMIT ?1`)
      .all(limit, who.role === "anon" ? "" : who.id),
  );
}
export const addNote = (
  db: Database,
  who: Who,
  input: { body: string },
): Result<Note> =>
  audited(db, who, "note", "create", undefined, add(db, who, input));
function add(db: Database, who: Who, input: { body: string }): Result<Note> {
  // The table decides; the type only learns it here: whoever may create is
  // signed in, and carries a name to write beside the note.
  if (who.role === "anon" || permit(who, "note", "create") !== "yes")
    return refuse(who, "Sign in to add a note.", "You may not add a note.");
  const body = input.body.trim();
  if (body.length === 0 || body.length > BODY_MAX)
    return fail("invalid", `A note is 1 to ${BODY_MAX} characters.`);
  const note = db
    .query<
      Note,
      [string, string, string]
    >("INSERT INTO note (body, author_id, author_name) VALUES (?1, ?2, ?3) RETURNING *")
    .get(body, who.id, who.name)!;
  emit("note.added", note);
  return ok(note);
}
/**
 * One note, for `who` to do `verb` to. The door is asked before the row is
 * looked for, so whoever may not is told that and never learns whether the
 * row exists; whoever may, and asked for nothing, hears `not_found`.
 */
function noteFor(
  db: Database,
  who: Who,
  verb: "read" | "update" | "delete",
  id: number,
  said: { signIn: string; no: string },
): Result<Note> {
  const note = Number.isInteger(id)
    ? db.query<Note, [number]>("SELECT * FROM note WHERE id = ?1").get(id)
    : null;
  // With no row to show, the door is asked about a row of their own: whoever
  // could not pass even then is refused, and learns nothing about what
  // exists; whoever could is told there is no such note.
  const row: Readonly<Record<string, unknown>> =
    note === null ? { author_id: who.role === "anon" ? null : who.id } : { ...note };
  if (permit(who, "note", verb, row) !== "yes")
    return refuse(who, said.signIn, said.no);
  if (note !== null) return ok(note);
  if (!Number.isInteger(id))
    return fail("invalid", "A note id is a whole number.");
  return fail("not_found", "No such note.");
}
export function getNote(
  db: Database,
  who: Who,
  input: { id: number },
): Result<Note> {
  return noteFor(db, who, "read", input.id, {
    signIn: "Sign in to read this note.",
    no: "You may not read this note.",
  });
}
export const updateNote = (
  db: Database,
  who: Who,
  input: { id: number; body: string },
): Result<Note> =>
  audited(db, who, "note", "update", input.id, update(db, who, input));
function update(
  db: Database,
  who: Who,
  input: { id: number; body: string },
): Result<Note> {
  const found = noteFor(db, who, "update", input.id, {
    signIn: "Sign in to edit a note.",
    no: "Only the author or an admin can edit a note.",
  });
  if (!found.ok) return found;
  const body = input.body.trim();
  if (body.length === 0 || body.length > BODY_MAX)
    return fail("invalid", `A note is 1 to ${BODY_MAX} characters.`);
  const note = db
    .query<
      Note,
      [string, number]
    >("UPDATE note SET body = ?1, updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now') WHERE id = ?2 RETURNING *")
    .get(body, found.value.id)!;
  emit("note.changed", note);
  return ok(note);
}
export const deleteNote = (
  db: Database,
  who: Who,
  input: { id: number },
): Result<{ id: number }> =>
  audited(db, who, "note", "delete", input.id, remove(db, who, input));
function remove(
  db: Database,
  who: Who,
  input: { id: number },
): Result<{ id: number }> {
  const found = noteFor(db, who, "delete", input.id, {
    signIn: "Sign in to remove a note.",
    no: "Only the author or an admin can remove a note.",
  });
  if (!found.ok) return found;
  db.query("DELETE FROM note WHERE id = ?1").run(found.value.id);
  emit("note.removed", { id: found.value.id });
  return ok({ id: found.value.id });
}
/** Whether `who` may remove `note`: the table's answer, for the page and the terminal to draw from. */
export const canDelete = (who: Who, note: Note): boolean =>
  permit(who, "note", "delete", { ...note }) === "yes";
/**
 * The audit trail, newest first, for whoever the table lets read it (an
 * admin, as the scaffold has it). `before` pages back by id. Audit rows name
 * no author, so a cell that gave `list` to a row's role would find nothing
 * of its own: anything but "yes" is a refusal here.
 */
export function listAudit(
  db: Database,
  who: Who,
  input: { limit?: number; before?: number } = {},
): Result<AuditRow[]> {
  if (permit(who, "audit", "list") !== "yes")
    return refuse(
      who,
      "Sign in to read the audit trail.",
      "Only an admin can read the audit trail.",
    );
  const limit = Math.min(
    Math.max(Math.trunc(input.limit ?? 100) || 100, 1),
    500,
  );
  const before = Number.isInteger(input.before)
    ? input.before!
    : Number.MAX_SAFE_INTEGER;
  return ok(
    db
      .query<
        AuditRow,
        [number, number]
      >("SELECT * FROM audit WHERE id < ?1 ORDER BY id DESC LIMIT ?2")
      .all(before, limit),
  );
}
export function getAudit(
  db: Database,
  who: Who,
  input: { id: number },
): Result<AuditRow> {
  const row = Number.isInteger(input.id)
    ? db
        .query<AuditRow, [number]>("SELECT * FROM audit WHERE id = ?1")
        .get(input.id)
    : null;
  if (permit(who, "audit", "read", { ...row }) !== "yes")
    return refuse(
      who,
      "Sign in to read the audit trail.",
      "Only an admin can read the audit trail.",
    );
  if (row !== null) return ok(row);
  if (!Number.isInteger(input.id))
    return fail("invalid", "An audit id is a whole number.");
  return fail("not_found", "No such audit row.");
}
@@ -0,0 +1,188 @@
/**
 * The trail: an allowed change and a refused one each leave a row, through
 * the real server; only an admin reads them; and a trail that cannot be
 * written costs a log line, never the request.
 */
import { afterAll, expect, spyOn, test } from "bun:test";
import { mkdtempSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { addNote } from "./actions.ts";
import type { AuditRow } from "./audit.ts";
import { openDb } from "./db.ts";
import { serve } from "./server.ts";
import { sign } from "./who.ts";
const KEY = "a-key-only-the-forge-holds";
const server = serve({
  port: 0,
  dataDir: mkdtempSync(join(tmpdir(), "app-audit-")),
  identityKey: KEY,
});
const base = `http://${server.hostname}:${server.port}`;
afterAll(() => server.stop(true));
const as = (
  id: string,
  name: string,
  role: "user" | "admin" = "user",
): Record<string, string> => {
  const identity = `${id}|${name}|${role}|${Date.now() + 60_000}`;
  return {
    "x-forge-identity": identity,
    "x-forge-signature": sign(identity, KEY),
  };
};
const alice = as("u1", "alice");
const bob = as("u2", "bob");
const root = as("u0", "root", "admin");
const call = (
  path: string,
  init: RequestInit = {},
  who: Record<string, string> = {},
) =>
  fetch(base + path, {
    ...init,
    headers: { "content-type": "application/json", ...who },
  });
const trail = async (): Promise<AuditRow[]> =>
  (await (await call("/api/audit", {}, root)).json()) as AuditRow[];
test("an allowed change and a refused one each leave a row", async () => {
  const made = await call(
    "/api/notes",
    { method: "POST", body: JSON.stringify({ body: "kept" }) },
    alice,
  );
  expect(made.status).toBe(201);
  const note = (await made.json()) as { id: number };
  // Refused at the door: a stranger may create nothing.
  expect(
    (
      await call("/api/notes", {
        method: "POST",
        body: JSON.stringify({ body: "x" }),
      })
    ).status,
  ).toBe(401);
  // Refused by the action: bob could delete a note of his own, not alice's.
  expect(
    (await call(`/api/notes/${note.id}`, { method: "DELETE" }, bob)).status,
  ).toBe(403);
  // Refused as cross-site, before the table is asked.
  const forged = await fetch(`${base}/api/notes/${note.id}`, {
    method: "DELETE",
    headers: { ...alice, "sec-fetch-site": "cross-site" },
  });
  expect(forged.status).toBe(403);
  const rows = (await trail()).slice(0, 4).reverse();
  expect(
    rows.map(
      ({ who_name, role, resource, verb, target, allowed, outcome }) => ({
        who_name,
        role,
        resource,
        verb,
        target,
        allowed,
        outcome,
      }),
    ),
  ).toEqual([
    {
      who_name: "alice",
      role: "user",
      resource: "note",
      verb: "create",
      target: String(note.id),
      allowed: 1,
      outcome: "ok",
    },
    {
      who_name: null,
      role: "anon",
      resource: "note",
      verb: "create",
      target: null,
      allowed: 0,
      outcome: "signin_required",
    },
    {
      who_name: "bob",
      role: "user",
      resource: "note",
      verb: "delete",
      target: String(note.id),
      allowed: 0,
      outcome: "forbidden",
    },
    {
      who_name: "alice",
      role: "user",
      resource: "note",
      verb: "delete",
      target: null,
      allowed: 0,
      outcome: "cross_site",
    },
  ]);
  for (const row of rows)
    expect(Date.parse(row.at)).toBeGreaterThan(Date.now() - 60_000);
});
test("reading is not an event: a GET leaves no row", async () => {
  const before = (await trail()).length;
  await call("/api/notes");
  await call("/", {}, alice);
  expect((await trail()).length).toBe(before);
});
test("only an admin reads the trail, at every door the table names", async () => {
  expect((await call("/api/audit")).status).toBe(401);
  expect((await call("/api/audit", {}, alice)).status).toBe(403);
  const rows = await trail();
  expect(rows.length).toBeGreaterThan(0);
  expect((await call(`/api/audit/${rows[0]!.id}`, {}, root)).status).toBe(200);
  expect((await call(`/api/audit/${rows[0]!.id}`, {}, alice)).status).toBe(403);
  expect((await call("/api/audit/999999", {}, root)).status).toBe(404);
  // Nobody writes the trail through a door: not even an admin.
  expect(
    (await call("/api/audit", { method: "POST", body: "{}" }, root)).status,
  ).toBe(403);
  expect(
    (await call(`/api/audit/${rows[0]!.id}`, { method: "DELETE" }, root))
      .status,
  ).toBe(403);
  // Paging back: `before` an id is everything older.
  const older = (await (
    await call(`/api/audit?before=${rows[0]!.id}&limit=1`, {}, root)
  ).json()) as AuditRow[];
  expect(older.map((r) => r.id)).toEqual([rows[1]!.id]);
});
test("a trail that cannot be written is a log line, and the change still happens", () => {
  const db = openDb(mkdtempSync(join(tmpdir(), "app-audit-broken-")));
  db.exec("DROP TABLE audit");
  const said = spyOn(console, "error").mockImplementation(() => {});
  try {
    const added = addNote(
      db,
      { role: "user", id: "u1", name: "alice" },
      { body: "still here" },
    );
    expect(added.ok).toBe(true);
    expect(said).toHaveBeenCalledTimes(1);
    const line = JSON.parse(String(said.mock.calls[0]![0]));
    expect(line.audit).toMatchObject({
      who_name: "alice",
      resource: "note",
      verb: "create",
      allowed: 1,
      outcome: "ok",
    });
    expect(line.unrecorded).toContain("audit");
  } finally {
    said.mockRestore();
  }
});
@@ -0,0 +1,90 @@
/**
 * The audit trail: every attempt to change something, as one row — who,
 * what (a resource and a verb from the contract), on which row, when, and
 * whether they were let. Refusals are rows too: a stranger knocking on a
 * door that stays shut is exactly what an owner wants to read later.
 *
 * Recording never fails a request. A row that cannot be written becomes a
 * line in the log, with everything the row would have said, and the
 * request goes on; the log is where the forge keeps a run's output.
 *
 * Reads are not recorded (a page view is not an event), and neither is a
 * request refused for coming too fast: a flood must not become the history,
 * or push the real history out.
 */
import type { Database } from "bun:sqlite";
import type { Who } from "./who.ts";
export interface AuditRow {
  readonly id: number;
  readonly at: string;
  readonly who_id: string | null;
  readonly who_name: string | null;
  readonly role: string;
  readonly resource: string;
  readonly verb: string;
  readonly target: string | null;
  readonly allowed: 0 | 1;
  /** `ok`, or the failure: `signin_required`, `forbidden`, `invalid`, `not_found`, `cross_site`. */
  readonly outcome: string;
}
export interface Attempt {
  readonly who: Who;
  readonly resource: string;
  readonly verb: string;
  readonly target?: string | number | undefined;
  readonly outcome: string;
}
/** The newest rows kept; older ones go as new ones come. */
export const KEEP = 50_000;
/** Was it let? Only the door says no; a bad body or a missing row got past it. */
export const allowed = (outcome: string): boolean =>
  outcome !== "signin_required" &&
  outcome !== "forbidden" &&
  outcome !== "cross_site";
export function record(db: Database, attempt: Attempt): void {
  const { who, resource, verb, target, outcome } = attempt;
  const row = {
    who_id: who.role === "anon" ? null : who.id,
    who_name: who.role === "anon" ? null : who.name,
    role: who.role,
    resource,
    verb,
    target: target === undefined ? null : String(target),
    allowed: allowed(outcome) ? 1 : 0,
    outcome,
  };
  try {
    const { lastInsertRowid } = db
      .query(
        "INSERT INTO audit (who_id, who_name, role, resource, verb, target, allowed, outcome) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)",
      )
      .run(
        row.who_id,
        row.who_name,
        row.role,
        row.resource,
        row.verb,
        row.target,
        row.allowed,
        row.outcome,
      );
    db.query("DELETE FROM audit WHERE id <= ?1").run(
      Number(lastInsertRowid) - KEEP,
    );
  } catch (error) {
    // Generated app: one JSON line to stderr, its own log.
    console.error(
      JSON.stringify({
        audit: row,
        at: new Date().toISOString(),
        unrecorded: String(error),
      }),
    );
  }
}
@@ -0,0 +1,389 @@
/**
 * Who may do what, decided from a table.
 *
 * An app's permissions are data: `contract.json` declares its roles and, for
 * every resource, the least role each of the five verbs needs. This file is
 * the whole evaluator. It is self-contained on purpose — no imports, no
 * classes, nothing but values and total functions — because it is carried
 * verbatim into every app the forge scaffolds, read by the forge to audit an
 * app without running it, and meant to be ported line for line.
 *
 * Roles form an order, not a list. `above` names the roles directly below a
 * role, and a role may do whatever anything below it may. How a role is
 * *held* is a value too: by everyone, by an identity the forge signed, or by
 * the row naming the actor. Adding a role adds a line to the contract and
 * nothing here: the evaluator is the same size for three roles or three
 * hundred.
 *
 * Everything fails closed: an undeclared resource, verb or role is "no".
 */
export type Verb = "create" | "read" | "update" | "delete" | "list";
export const VERBS: readonly Verb[] = [
  "create",
  "read",
  "update",
  "delete",
  "list",
];
/** The cell that lets nobody in. Not a role: nothing can be above it. */
export const NOBODY = "nobody";
/** How a role is held. */
export type Held =
  /** By anyone at all, signed in or not. A contract has exactly one. */
  | { readonly by: "everyone" }
  /** By an identity the forge signed as carrying `role`. */
  | { readonly by: "identity"; readonly role: string }
  /** By the row: its `column` holds the actor's id. */
  | { readonly by: "row"; readonly column: string };
export interface Role {
  /** The roles directly below this one. */
  readonly above: readonly string[];
  readonly held: Held;
}
export interface Resource {
  /** The least role each verb needs, or `nobody`. */
  readonly can: Readonly<Record<Verb, string>>;
  /**
   * The collection path of this resource's JSON API, when it has one: five
   * doors follow by convention (`GET api` lists, `POST api` creates,
   * `GET`/`PATCH`/`DELETE api/<id>` read, update and delete one), which is
   * how the forge can knock on a running app and compare with the table.
   */
  readonly api?: string;
}
export interface Contract {
  readonly roles: Readonly<Record<string, Role>>;
  readonly resources: Readonly<Record<string, Resource>>;
}
/**
 * Who is asking: an id when signed in, and the roles the forge signed. An
 * empty id is nobody: it never names a row, however a row was filled.
 */
export interface Actor {
  readonly id: string | null;
  readonly roles: readonly string[];
}
/**
 * The answer. `where` is for a verb with no row in hand (`list`): the actor
 * may have exactly the rows whose named columns hold their id.
 */
export type Decision = "yes" | "no" | { readonly where: readonly string[] };
/**
 * A declared thing by name, and nothing else: `constructor` and its kin are
 * on every object and are not roles.
 */
function own<T>(of: Readonly<Record<string, T>>, name: string): T | undefined {
  return Object.prototype.hasOwnProperty.call(of, name) ? of[name] : undefined;
}
/**
 * Every role with everything at or below it, computed once per contract
 * and kept beside it. A door is asked on every request, and an order of a
 * few hundred roles must answer in the time a hash lookup takes, not the
 * time a walk takes; the walk happens once, when a contract is first used.
 * The cache is keyed by the contract object itself, so it needs no
 * invalidation: a new contract is a new object.
 */
const closures = new WeakMap<Contract, Map<string, Set<string>>>();
function closureOf(contract: Contract): Map<string, Set<string>> {
  const kept = closures.get(contract);
  if (kept !== undefined) return kept;
  const out = new Map<string, Set<string>>();
  for (const name of Object.keys(contract.roles)) {
    const seen = new Set<string>([name]);
    const walk = [name];
    while (walk.length > 0) {
      const at = walk.pop()!;
      for (const below of own(contract.roles, at)?.above ?? [])
        if (!seen.has(below)) {
          seen.add(below);
          walk.push(below);
        }
    }
    out.set(name, seen);
  }
  closures.set(contract, out);
  return out;
}
/** Whether role `low` is `high` or below it; an undeclared role is neither. */
export function atOrBelow(
  contract: Contract,
  low: string,
  high: string,
): boolean {
  return closureOf(contract).get(high)?.has(low) ?? false;
}
export function decide(
  contract: Contract,
  resource: string,
  verb: Verb,
  actor: Actor,
  row?: Readonly<Record<string, unknown>>,
): Decision {
  const can = own(contract.resources, resource)?.can;
  const need = can === undefined ? undefined : own(can, verb);
  if (need === undefined || own(contract.roles, need) === undefined)
    return "no";
  const where: string[] = [];
  for (const name of Object.keys(contract.roles)) {
    if (!atOrBelow(contract, need, name)) continue;
    const held = contract.roles[name]!.held;
    if (held.by === "everyone") return "yes";
    if (held.by === "identity") {
      if (actor.roles.includes(held.role)) return "yes";
      continue;
    }
    if (actor.id === null || actor.id === "") continue;
    if (row !== undefined) {
      if (own(row, held.column) === actor.id) return "yes";
    } else if (verb === "list" && !where.includes(held.column))
      where.push(held.column);
  }
  return where.length > 0 ? { where } : "no";
}
/** `decide`, for the doors that only need yes or no about one row. */
export const may = (
  contract: Contract,
  resource: string,
  verb: Verb,
  actor: Actor,
  row?: Readonly<Record<string, unknown>>,
): boolean => decide(contract, resource, verb, actor, row) === "yes";
// ---- reading a contract: strict, total, every problem named ----
export type Read =
  | { readonly ok: true; readonly contract: Contract }
  | { readonly ok: false; readonly problems: readonly string[] };
const isObject = (v: unknown): v is Record<string, unknown> =>
  typeof v === "object" && v !== null && !Array.isArray(v);
const NAME = /^[a-z][a-z0-9_]{0,39}$/;
/** An absolute path of plain segments: no query, no dot-segments, no host. */
const API_PATH = /^\/(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_-]+$/;
function readHeld(v: unknown): Held | undefined {
  if (!isObject(v)) return undefined;
  if (v["by"] === "everyone") return { by: "everyone" };
  if (v["by"] === "identity" && typeof v["role"] === "string")
    return NAME.test(v["role"])
      ? { by: "identity", role: v["role"] }
      : undefined;
  if (v["by"] === "row" && typeof v["column"] === "string")
    return NAME.test(v["column"])
      ? { by: "row", column: v["column"] }
      : undefined;
  return undefined;
}
/** Parse and check a contract from untrusted JSON text. */
export function readContract(text: string): Read {
  let raw: unknown;
  try {
    raw = JSON.parse(text);
  } catch {
    return { ok: false, problems: ["contract.json is not JSON"] };
  }
  if (!isObject(raw) || !isObject(raw["roles"]) || !isObject(raw["resources"]))
    return {
      ok: false,
      problems: ["a contract is an object with `roles` and `resources`"],
    };
  const problems: string[] = [];
  const roles: Record<string, Role> = {};
  for (const [name, v] of Object.entries(raw["roles"])) {
    const held = isObject(v) ? readHeld(v["held"]) : undefined;
    const above = isObject(v) ? (v["above"] ?? []) : undefined;
    if (!NAME.test(name) || name === NOBODY)
      problems.push(`role \`${name}\`: not a usable name`);
    else if (
      held === undefined ||
      !Array.isArray(above) ||
      !above.every((a): a is string => typeof a === "string")
    )
      problems.push(`role \`${name}\`: needs \`held\` and a list \`above\``);
    else roles[name] = { above, held };
  }
  const resources: Record<string, Resource> = {};
  for (const [name, v] of Object.entries(raw["resources"])) {
    const can = isObject(v) && isObject(v["can"]) ? v["can"] : undefined;
    if (!NAME.test(name) || !isObject(v) || can === undefined) {
      problems.push(`resource \`${name}\`: needs a name and a \`can\` table`);
      continue;
    }
    const cells = {} as Record<Verb, string>;
    for (const verb of VERBS) {
      const cell = can[verb];
      if (typeof cell === "string") cells[verb] = cell;
      else
        problems.push(`${name}.${verb}: every verb names a role or \`nobody\``);
    }
    for (const extra of Object.keys(can))
      if (!VERBS.includes(extra as Verb))
        problems.push(`${name}.${extra}: not one of ${VERBS.join(", ")}`);
    const api = v["api"];
    if (api !== undefined && (typeof api !== "string" || !API_PATH.test(api)))
      problems.push(
        `resource \`${name}\`: \`api\` is an absolute path of plain segments, like /api/${name}s`,
      );
    resources[name] =
      typeof api === "string" && API_PATH.test(api)
        ? { can: cells, api }
        : { can: cells };
  }
  const contract: Contract = { roles, resources };
  problems.push(...check(contract));
  // A cell read here and checked there is one problem, said once.
  const unique = [...new Set(problems)];
  return unique.length > 0
    ? { ok: false, problems: unique }
    : { ok: true, contract };
}
/** What is wrong with a contract that parsed. Empty means sound. */
export function check(contract: Contract): string[] {
  const problems: string[] = [];
  const names = Object.keys(contract.roles);
  const floors = names.filter((n) => contract.roles[n]!.held.by === "everyone");
  if (floors.length !== 1)
    problems.push("exactly one role is held by everyone: the floor");
  // Two roles held by one identity are one role with two names: the table
  // would show two columns that are the same person.
  const byIdentity = new Map<string, string>();
  for (const name of names) {
    const held = contract.roles[name]!.held;
    if (held.by !== "identity") continue;
    const other = byIdentity.get(held.role);
    if (other !== undefined)
      problems.push(
        `roles \`${other}\` and \`${name}\` are both held by the identity \`${held.role}\``,
      );
    else byIdentity.set(held.role, name);
  }
  for (const name of names) {
    for (const below of contract.roles[name]!.above) {
      if (own(contract.roles, below) === undefined)
        problems.push(
          `role \`${name}\` is above \`${below}\`, which is not declared`,
        );
      else if (atOrBelow(contract, name, below))
        problems.push(`role \`${name}\` is both above and below \`${below}\``);
    }
    const floor = floors[0];
    if (floor !== undefined && !atOrBelow(contract, floor, name))
      problems.push(
        `role \`${name}\` does not stand on the floor \`${floor}\``,
      );
  }
  for (const [resource, { can }] of Object.entries(contract.resources))
    for (const verb of VERBS) {
      const need = own(can, verb);
      if (need === undefined) {
        problems.push(
          `${resource}.${verb}: every verb names a role or \`nobody\``,
        );
        continue;
      }
      if (need === NOBODY) continue;
      const role = own(contract.roles, need);
      if (role === undefined)
        problems.push(
          `${resource}.${verb} needs \`${need}\`, which is not declared`,
        );
      else if (verb === "create" && role.held.by === "row")
        problems.push(
          `${resource}.create needs \`${need}\`, which a row holds: there is no row yet`,
        );
    }
  return problems;
}
// ---- the table: the contract as the audit reads it ----
export interface Cell {
  readonly resource: string;
  readonly verb: Verb;
  /** Who is asking: the floor, or a role an identity carries. */
  readonly as: string;
  /** `own`: only the rows that name the actor. */
  readonly answer: "yes" | "no" | "own";
}
/**
 * Who someone can be. A role a row holds is not one of them: it is what an
 * actor is *to a row*, and shows in the table as `own`.
 */
export const identities = (contract: Contract): string[] =>
  Object.keys(contract.roles).filter(
    (name) => contract.roles[name]!.held.by !== "row",
  );
/**
 * The facts that make someone `identity` and nothing more: the forge acts as
 * each identity this way, for the table here and for the audit's probes.
 * `mine` is a row that names the actor wherever a row can; `theirs` names
 * someone else. Anything that is not an identity acts as a stranger.
 */
export function actingAs(
  contract: Contract,
  identity: string,
): {
  actor: Actor;
  mine: Record<string, unknown>;
  theirs: Record<string, unknown>;
} {
  const held = own(contract.roles, identity)?.held;
  const actor: Actor =
    held?.by === "identity"
      ? { id: "the-actor", roles: [held.role] }
      : { id: null, roles: [] };
  const mine: Record<string, unknown> = {};
  const theirs: Record<string, unknown> = {};
  for (const role of Object.values(contract.roles))
    if (role.held.by === "row") {
      mine[role.held.column] = "the-actor";
      theirs[role.held.column] = "someone-else";
    }
  return { actor, mine, theirs };
}
/** Every resource, verb and identity, answered. The policy, as a table. */
export function table(contract: Contract): Cell[] {
  const out: Cell[] = [];
  for (const resource of Object.keys(contract.resources))
    for (const verb of VERBS)
      for (const as of identities(contract)) {
        const { actor, mine, theirs } = actingAs(contract, as);
        const rowless = verb === "create" || verb === "list";
        const any = decide(
          contract,
          resource,
          verb,
          actor,
          rowless ? undefined : theirs,
        );
        const owned = rowless
          ? any
          : decide(contract, resource, verb, actor, mine);
        out.push({
          resource,
          verb,
          as,
          answer: any === "yes" ? "yes" : owned === "no" ? "no" : "own",
        });
      }
  return out;
}
@@ -0,0 +1,117 @@
/**
 * Every door answers as the table says. The test acts as each identity the
 * contract declares — on a note that names them and on one that names
 * someone else — and calls the real actions. A rule written by hand in an
 * action, or a cell changed without its door, fails here.
 */
import { expect, test } from "bun:test";
import { mkdtempSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
  addNote,
  deleteNote,
  getAudit,
  getNote,
  listAudit,
  listNotes,
  updateNote,
} from "./actions.ts";
import { record } from "./audit.ts";
import { actingAs, identities, table, type Verb } from "./can.ts";
import { contract } from "./contract.ts";
import { openDb } from "./db.ts";
import type { Who } from "./who.ts";
const db = openDb(mkdtempSync(join(tmpdir(), "app-contract-")));
/** The identity the evaluator acts as, as the forge would have signed it. */
function whoIs(identity: string): Who {
  const { actor } = actingAs(contract, identity);
  const role = actor.roles[0];
  if (actor.id === null || (role !== "user" && role !== "admin"))
    return { role: "anon" };
  return { role, id: actor.id, name: identity };
}
const noteBy = (authorId: string): number =>
  db
    .query<
      { id: number },
      [string]
    >("INSERT INTO note (body, author_id, author_name) VALUES ('n', ?1, ?1) RETURNING id")
    .get(authorId)!.id;
const auditRow = (): number => {
  record(db, {
    who: { role: "anon" },
    resource: "note",
    verb: "create",
    outcome: "signin_required",
  });
  return db.query<{ id: number }, []>("SELECT max(id) AS id FROM audit").get()!
    .id;
};
/** One door per verb an action serves: did it let `who` through, on `row`? */
const doors: Record<
  string,
  Partial<Record<Verb, (who: Who, authorId: string) => boolean>>
> = {
  note: {
    create: (who) => addNote(db, who, { body: "hello" }).ok,
    list: (who) => listNotes(db, who).ok,
    read: (who, authorId) => getNote(db, who, { id: noteBy(authorId) }).ok,
    update: (who, authorId) =>
      updateNote(db, who, { id: noteBy(authorId), body: "changed" }).ok,
    delete: (who, authorId) => deleteNote(db, who, { id: noteBy(authorId) }).ok,
  },
  // The trail is written by the app itself, never through a door: there
  // is no action that creates, changes or removes a row of it.
  audit: {
    list: (who) => listAudit(db, who).ok,
    read: (who) => getAudit(db, who, { id: auditRow() }).ok,
    create: () => false,
    update: () => false,
    delete: () => false,
  },
};
test("the contract names the identities the forge signs", () => {
  expect(identities(contract).sort()).toEqual(["admin", "anon", "user"]);
});
test("every resource in the contract has every door here", () => {
  expect(Object.keys(doors).sort()).toEqual(
    Object.keys(contract.resources).sort(),
  );
  for (const resource of Object.keys(contract.resources))
    expect(Object.keys(doors[resource] ?? {}).sort()).toEqual([
      "create",
      "delete",
      "list",
      "read",
      "update",
    ]);
});
test("every door answers as the table says, as every identity", () => {
  let asked = 0;
  for (const cell of table(contract)) {
    const door = doors[cell.resource]?.[cell.verb];
    if (door === undefined) continue;
    const who = whoIs(cell.as);
    const { mine, theirs } = actingAs(contract, cell.as);
    const onMine = door(who, String(mine["author_id"]));
    const onTheirs = door(who, String(theirs["author_id"]));
    const said = `${cell.resource}.${cell.verb} as ${cell.as}`;
    asked++;
    if (cell.answer === "yes")
      expect([said, onMine, onTheirs]).toEqual([said, true, true]);
    else if (cell.answer === "no")
      expect([said, onMine, onTheirs]).toEqual([said, false, false]);
    else if (cell.verb === "list") expect([said, onMine]).toEqual([said, true]);
    else expect([said, onMine, onTheirs]).toEqual([said, true, false]);
  }
  expect(asked).toBeGreaterThan(0);
});
@@ -0,0 +1,40 @@
/**
 * Who may do what. `contract.json` is the table — the roles, and the least
 * role each verb on each resource needs — and `src/can.ts` is the forge's
 * evaluator, carried here verbatim. Actions ask `permit` and nothing else
 * in the app decides who may do what, so the table *is* the policy: it can
 * be read, compared and audited without running anything.
 *
 * A contract that does not read is not a warning. The app does not start.
 */
import { readFileSync } from "node:fs";
import {
  decide,
  readContract,
  type Actor,
  type Decision,
  type Verb,
} from "./can.ts";
import type { Who } from "./who.ts";
const read = readContract(
  readFileSync(new URL("../contract.json", import.meta.url), "utf8"),
);
if (!read.ok) throw new Error(`contract.json: ${read.problems.join("; ")}`);
export const contract = read.contract;
/** The forge's word for who is asking, as the evaluator takes it. */
export const actorOf = (who: Who): Actor =>
  who.role === "anon"
    ? { id: null, roles: [] }
    : { id: who.id, roles: [who.role] };
/** May `who` do `verb` to `resource` — to `row`, when there is one? */
export const permit = (
  who: Who,
  resource: string,
  verb: Verb,
  row?: Readonly<Record<string, unknown>>,
): Decision => decide(contract, resource, verb, actorOf(who), row);
@@ -0,0 +1,23 @@
import { expect, test } from "bun:test";
import { mkdtempSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { check, migrate, migrations, openDb } from "./db.ts";
test("migrations apply once, in order, and the file checks out", () => {
  const dir = mkdtempSync(join(tmpdir(), "app-db-"));
  const db = openDb(dir);
  expect(check(db).version).toBe(migrations.length);
  // Opening again finds nothing to do — a migration that has run is history.
  expect(migrate(db)).toBe(migrations.length);
  expect(() => openDb(dir)).not.toThrow();
  expect(check(db)).toEqual({ version: migrations.length, integrity: "ok" });
  expect(
    db.query<{ journal_mode: string }, []>("PRAGMA journal_mode").get()
      ?.journal_mode,
  ).toBe("wal");
  expect(
    db.query<{ foreign_keys: number }, []>("PRAGMA foreign_keys").get()
      ?.foreign_keys,
  ).toBe(1);
});
@@ -0,0 +1,96 @@
/**
 * The database: one SQLite file under FORGE_APP_DATA, so production and
 * every preview each have their own. WAL so readers never wait on the
 * writer (the terminal is a second process on the same file), foreign keys
 * on, and a forward-only list of migrations applied once, in a
 * transaction, when the file is opened.
 *
 *   bun run src/db.ts --check    the schema version and an integrity check
 */
import { Database } from "bun:sqlite";
import { mkdirSync } from "node:fs";
import { join } from "node:path";
import { dataDir } from "./env.ts";
/** Append, never edit: a migration that has run is history. */
export const migrations: string[] = [
  `CREATE TABLE note (
    id INTEGER PRIMARY KEY,
    body TEXT NOT NULL CHECK (length(body) BETWEEN 1 AND 500),
    author_id TEXT NOT NULL,
    author_name TEXT NOT NULL,
    created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
    updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
  )`,
  `CREATE INDEX note_author ON note (author_id)`,
  // Who tried to change what, and whether they were let. Appended by
  // src/audit.ts, never edited; read by admins at GET /api/audit.
  `CREATE TABLE audit (
    id INTEGER PRIMARY KEY,
    at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
    who_id TEXT,
    who_name TEXT,
    role TEXT NOT NULL,
    resource TEXT NOT NULL,
    verb TEXT NOT NULL,
    target TEXT,
    allowed INTEGER NOT NULL CHECK (allowed IN (0, 1)),
    outcome TEXT NOT NULL
  )`,
];
export function openDb(dir = dataDir): Database {
  mkdirSync(dir, { recursive: true });
  const db = new Database(join(dir, "app.db"));
  db.exec("PRAGMA journal_mode = WAL");
  db.exec("PRAGMA foreign_keys = ON");
  db.exec("PRAGMA busy_timeout = 5000");
  migrate(db);
  return db;
}
/** Apply the migrations past the recorded version, all or none. Returns the version. */
export function migrate(db: Database): number {
  db.exec(
    "CREATE TABLE IF NOT EXISTS schema_version (version INTEGER PRIMARY KEY, applied_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')))",
  );
  return db.transaction(() => {
    const current = db
      .query<
        { version: number },
        []
      >("SELECT coalesce(max(version), 0) AS version FROM schema_version")
      .get()!.version;
    migrations.slice(current).forEach((sql, i) => {
      db.exec(sql);
      db.query("INSERT INTO schema_version (version) VALUES (?1)").run(
        current + i + 1,
      );
    });
    return migrations.length;
  })();
}
export function check(db: Database): { version: number; integrity: string } {
  const version = db
    .query<
      { version: number },
      []
    >("SELECT max(version) AS version FROM schema_version")
    .get()!.version;
  const integrity = db
    .query<{ integrity_check: string }, []>("PRAGMA integrity_check")
    .get()!.integrity_check;
  return { version, integrity };
}
if (import.meta.main) {
  const db = openDb();
  const { version, integrity } = check(db);
  console.log(`schema version ${version}`);
  if (process.argv.includes("--check")) {
    console.log(`integrity ${integrity}`);
    process.exit(integrity === "ok" ? 0 : 1);
  }
}
@@ -0,0 +1,111 @@
/**
 * The look holds: the tokens compile to both themes, every pair of colours
 * a person must read meets WCAG AA in both, and no colour is spelled out
 * anywhere but design/tokens.json.
 */
import { expect, test } from "bun:test";
import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { lint, rawColours, unknownTokens } from "../scripts/lint-design.ts";
import { compile, flatten, token, tokens, tokensCss } from "./tokens.ts";
test("the tokens compile: light on :root, dark for the system and for data-theme", () => {
  expect(tokensCss).toContain(`--color-bg: ${token("color-bg")};`);
  expect(tokensCss).toContain("--space-4: 1rem;");
  expect(tokensCss).toContain(
    '--font-sans: system-ui, -apple-system, "Segoe UI", sans-serif;',
  );
  expect(tokensCss).toContain("@media (prefers-color-scheme: dark)");
  expect(tokensCss).toContain(':root:not([data-theme="light"])');
  expect(tokensCss).toContain(':root[data-theme="dark"]');
  // Every colour has a dark value, or the dark theme would inherit a light one.
  for (const t of tokens.filter((t) => t.type === "color"))
    expect([t.name, t.dark !== undefined]).toEqual([t.name, true]);
  expect(
    tokensCss.split(`--color-bg: ${token("color-bg", "dark")};`).length,
  ).toBe(3);
});
test("tokens that do not read stop the app, with the path named", () => {
  expect(() => flatten({ color: { bg: { $value: "#fff" } } })).toThrow(
    "color.bg: no $type",
  );
  expect(() =>
    flatten({
      color: { $type: "color", bg: { $value: "red; } body { display: none" } },
    }),
  ).toThrow("color.bg: $value is not a CSS value");
  expect(() =>
    flatten({ color: { $type: "color", "b g": { $value: "#fff" } } }),
  ).toThrow("not a name CSS can carry");
  expect(
    compile(flatten({ size: { $type: "dimension", tap: { $value: "44px" } } })),
  ).toContain("--size-tap: 44px;");
});
// WCAG 2 relative luminance and contrast, from a #rrggbb.
const luminance = (hex: string): number => {
  const [r, g, b] = [1, 3, 5].map((i) => {
    const c = parseInt(hex.slice(i, i + 2), 16) / 255;
    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
  }) as [number, number, number];
  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
};
const contrast = (a: string, b: string): number => {
  const [x, y] = [luminance(a), luminance(b)].sort((p, q) => q - p) as [
    number,
    number,
  ];
  return (x + 0.05) / (y + 0.05);
};
test("every pair a person reads is at least 4.5:1, in both themes", () => {
  const pairs = [
    ["color-fg", "color-bg"],
    ["color-fg", "color-surface"],
    ["color-muted", "color-bg"],
    ["color-muted", "color-surface"],
    ["color-accent", "color-bg"],
    ["color-accent", "color-surface"],
    ["color-accent-fg", "color-accent"],
    ["color-toast-fg", "color-toast-bg"],
  ] as const;
  for (const mode of ["light", "dark"] as const)
    for (const [fg, bg] of pairs) {
      const ratio = contrast(token(fg, mode), token(bg, mode));
      expect([mode, fg, bg, ratio >= 4.5]).toEqual([mode, fg, bg, true]);
    }
});
test("the app spells out no colour but in its tokens", () => {
  expect(lint(join(import.meta.dir, ".."))).toEqual([]);
});
test("the lint refuses a raw colour and a token that is not there", () => {
  expect(
    rawColours(
      "a.css",
      ".x { color: #ff0000; }\n.y { background: rgb(0 0 0); }",
    ),
  ).toEqual([
    "a.css:1: raw colour #ff0000 — name it in design/tokens.json and use var(--…)",
    "a.css:2: raw colour rgb( — name it in design/tokens.json and use var(--…)",
  ]);
  // Not colours: an entity, an id selector's word, a pull number.
  expect(rawColours("a.ts", "`&#39;` #notes pull #12 #abcdefg")).toEqual([]);
  expect(
    unknownTokens(
      "a.css",
      ".x { color: var(--color-fg); gap: var(--spcae-2); }",
    ),
  ).toEqual(["a.css:1: --spcae-2 is not a token in design/tokens.json"]);
  const root = mkdtempSync(join(tmpdir(), "app-lint-"));
  mkdirSync(join(root, "static"));
  mkdirSync(join(root, "src"));
  writeFileSync(join(root, "static", "extra.css"), "a {\n  color: #fff;\n}\n");
  writeFileSync(join(root, "src", "ok.test.ts"), "const red = '#f00';\n");
  expect(lint(root)).toEqual([
    "static/extra.css:2: raw colour #fff — name it in design/tokens.json and use var(--…)",
  ]);
});
@@ -0,0 +1,32 @@
/**
 * What the forge told this process, read once and named once. Every other
 * module takes these from here, so nothing else spells an environment
 * variable — and running the app by hand needs none of them.
 */
import pkg from "../package.json";
export const title: string = pkg.name;
/** The app's own version (package.json): what `/healthz` and `/openapi.json` say. */
export const version: string = pkg.version ?? "0.0.0";
/** When this process started, for `/healthz`'s uptime. */
export const startedAt: number = Date.now();
export const description: string = pkg.description || "A new app on the forge.";
export const dataDir: string = process.env.FORGE_APP_DATA ?? "./data";
export const env: string = process.env.FORGE_APP_ENV ?? "local";
export const commit: string = (process.env.FORGE_APP_COMMIT ?? "").slice(0, 7);
/** Where this process runs, for a person: `production`, `preview of pull #3`, `local`. */
export const where: string =
  env === "preview"
    ? `preview of pull #${process.env.FORGE_APP_PULL ?? "?"}`
    : env;
/** The exact command that opens this environment's terminal. Print it verbatim, never a guess. */
export const ssh: string | undefined = process.env.FORGE_APP_SSH;
/** The address the forge serves us at — what a browser sees, never the socket's. */
export const publicOrigin: string = new URL(
  process.env.FORGE_APP_URL ?? "http://localhost",
).origin;
/** The forge that runs us. Its own well-known files (security.txt) speak for its apps. */
export const forgeUrl: string | undefined = process.env.FORGE_URL;
/** The key the forge signs identities with (`who.ts`). Unset, everyone is anonymous. */
export const identityKey: string = process.env.FORGE_APP_IDENTITY_KEY ?? "";
@@ -0,0 +1,193 @@
/**
 * The floor every response stands on, and the few things a route needs to
 * read a request safely. Nothing in here knows what a note is; who may
 * come in at all is `security.ts`.
 */
import { createHash } from "node:crypto";
import { existsSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { env, publicOrigin } from "./env.ts";
// Scripts and styles come from this origin (inline styles allowed, inline
// scripts not), nothing frames us, browsers never guess a content type, and
// referrers stay on this site. Once served over https, always: browsers
// remember for a year. Anything but production asks not to be indexed: a
// preview is a draft, and its address goes away with its pull.
export const SECURITY: Record<string, string> = {
  "content-security-policy":
    "default-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; frame-ancestors 'none'; base-uri 'none'; form-action 'self'",
  "x-content-type-options": "nosniff",
  "referrer-policy": "strict-origin-when-cross-origin",
  "permissions-policy": "camera=(), microphone=(), geolocation=()",
  ...(publicOrigin.startsWith("https:")
    ? { "strict-transport-security": "max-age=31536000" }
    : {}),
  ...(env === "production" ? {} : { "x-robots-tag": "noindex" }),
};
export const escape = (s: string): string =>
  s.replace(
    /[&<>"']/g,
    (c) =>
      ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[
        c
      ] ?? c,
  );
export const html = (
  body: string,
  status = 200,
  headers: Record<string, string> = {},
): Response =>
  new Response(body, {
    status,
    headers: {
      "content-type": "text/html; charset=utf-8",
      ...SECURITY,
      ...headers,
    },
  });
export const json = (data: unknown, status = 200): Response =>
  new Response(JSON.stringify(data), {
    status,
    headers: { "content-type": "application/json; charset=utf-8", ...SECURITY },
  });
export const text = (body: string, status = 200): Response =>
  new Response(body, {
    status,
    headers: { "content-type": "text/plain; charset=utf-8", ...SECURITY },
  });
/** Back to the page, with a word for it to show once (`readNotice`). */
export const back = (notice?: string): Response =>
  new Response(null, {
    status: 303,
    headers: {
      location: "/",
      ...SECURITY,
      ...(notice === undefined
        ? {}
        : { "set-cookie": cookie("notice", encodeURIComponent(notice), 30) }),
    },
  });
/** The notice a redirect left, and the header that clears it. */
export function readNotice(request: Request): {
  notice?: string;
  clear: Record<string, string>;
} {
  const raw = /(?:^|;\s*)notice=([^;]*)/.exec(
    request.headers.get("cookie") ?? "",
  )?.[1];
  if (raw === undefined) return { clear: {} };
  return {
    notice: decodeURIComponent(raw),
    clear: { "set-cookie": cookie("notice", "", 0) },
  };
}
// Every cookie the app sets itself is HttpOnly and SameSite=Lax, and Secure
// wherever the public address is https.
const cookie = (name: string, value: string, maxAge: number): string =>
  `${name}=${value}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${maxAge}${publicOrigin.startsWith("https:") ? "; Secure" : ""}`;
// A request body is read up to a cap and no further, counting the bytes as
// they arrive. A declared Content-Length is a claim: a chunked request has
// none, and a lie is free. Undefined means "too large" — refuse it. Past the
// cap the rest is drained and dropped so the connection stays usable for
// the next request; past eight times the cap it is cut off instead.
export const BODY_MAX = 64 * 1024;
export async function readBody(
  request: Request,
  max = BODY_MAX,
): Promise<Uint8Array | undefined> {
  const reader = request.body?.getReader();
  if (reader === undefined) return new Uint8Array();
  const parts: Uint8Array[] = [];
  let size = 0;
  for (;;) {
    const { done, value } = await reader.read();
    if (done) break;
    size += value.byteLength;
    if (size > max) {
      for (;;) {
        const next = await reader.read();
        if (next.done) return undefined;
        size += next.value.byteLength;
        if (size > max * 8) {
          await reader.cancel();
          return undefined;
        }
      }
    }
    parts.push(value);
  }
  const body = new Uint8Array(size);
  let at = 0;
  for (const part of parts) {
    body.set(part, at);
    at += part.byteLength;
  }
  return body;
}
/** The form fields of a capped body, decoded the way the browser sent them. */
export async function readForm(request: Request) {
  const body = await readBody(request);
  if (body === undefined) return undefined;
  return new Request(request.url, {
    method: "POST",
    headers: { "content-type": request.headers.get("content-type") ?? "" },
    body: new Uint8Array(body),
  }).formData();
}
/** The JSON of a capped body: `undefined` when too large, `null` when not JSON. */
export async function readJson(request: Request): Promise<unknown> {
  const body = await readBody(request);
  if (body === undefined) return undefined;
  try {
    return JSON.parse(new TextDecoder().decode(body));
  } catch {
    return null;
  }
}
/** A JSON object's fields, whatever the wire carried. */
export const fields = (value: unknown): Record<string, unknown> =>
  typeof value === "object" && value !== null && !Array.isArray(value)
    ? (value as Record<string, unknown>)
    : {};
// Files under ./static are served as they are. A page links each one by
// its content (`/static/app.css?v=3f2a9c1e`), and that address is cached
// for a year: a change is a new address, never a stale cache.
const STATIC = join(import.meta.dir, "..", "static");
const versions = new Map<string, string>();
export function asset(name: string): string {
  let v = versions.get(name);
  if (v === undefined) {
    v = createHash("sha256")
      .update(readFileSync(join(STATIC, name)))
      .digest("hex")
      .slice(0, 8);
    versions.set(name, v);
  }
  return `/static/${name}?v=${v}`;
}
export function staticFile(name: string, versioned: boolean): Response {
  const path = join(STATIC, name);
  if (name.includes("/") || name.includes("..") || !existsSync(path))
    return text("not found", 404);
  return new Response(Bun.file(path), {
    headers: {
      "cache-control": versioned
        ? "public, max-age=31536000, immutable"
        : "no-cache",
      ...SECURITY,
    },
  });
}
@@ -0,0 +1,81 @@
/**
 * Realtime without a framework. Actions `emit` what changed; `GET /events`
 * streams it to every open page as server-sent events, numbered, with the
 * last hundred kept so a client that reconnects with `Last-Event-ID` (or
 * `?since=`) hears what it missed. `static/live.js` turns the stream into
 * DOM events. The bus is this process's: the terminal is another process,
 * and its writes show on the next load rather than live.
 */
export interface LiveEvent {
  readonly id: number;
  readonly type: string;
  readonly data: unknown;
}
const KEEP = 100;
const HEARTBEAT_MS = 25_000;
const kept: LiveEvent[] = [];
const listeners = new Set<(event: LiveEvent) => void>();
let last = 0;
export function emit(type: string, data: unknown): LiveEvent {
  const event: LiveEvent = { id: ++last, type, data };
  kept.push(event);
  if (kept.length > KEEP) kept.shift();
  for (const listen of listeners) listen(event);
  return event;
}
export function subscribe(listen: (event: LiveEvent) => void): () => void {
  listeners.add(listen);
  return () => listeners.delete(listen);
}
/** `GET /events`: a stream that replays what `since` missed, then follows. */
export function events(request: Request): Response {
  const since = Number(
    request.headers.get("last-event-id") ??
      new URL(request.url).searchParams.get("since") ??
      0,
  );
  const encoder = new TextEncoder();
  let stop = (): void => {};
  const stream = new ReadableStream<Uint8Array>({
    start(controller) {
      const write = (text: string): void => {
        try {
          controller.enqueue(encoder.encode(text));
        } catch {
          stop();
        }
      };
      const send = (event: LiveEvent): void =>
        write(
          `id: ${event.id}\ndata: ${JSON.stringify({ type: event.type, data: event.data })}\n\n`,
        );
      const heartbeat = setInterval(() => write(":\n\n"), HEARTBEAT_MS);
      const unsubscribe = subscribe(send);
      stop = () => {
        clearInterval(heartbeat);
        unsubscribe();
        try {
          controller.close();
        } catch {}
      };
      request.signal.addEventListener("abort", stop);
      write("retry: 2000\n\n");
      for (const event of kept) if (event.id > since) send(event);
    },
    cancel() {
      stop();
    },
  });
  return new Response(stream, {
    headers: {
      "content-type": "text/event-stream",
      "cache-control": "no-store",
      "x-accel-buffering": "no",
    },
  });
}
@@ -0,0 +1,123 @@
/**
 * An MCP server over plain HTTP: `POST /mcp` takes one JSON-RPC 2.0
 * message and answers with JSON (streamable HTTP without the stream —
 * nothing here needs to push). The tools are the actions, called with the
 * same identity the page gets, so an agent speaking MCP through the forge
 * is the person whose grant it carries, and a bare one is anonymous.
 */
import type { Database } from "bun:sqlite";
import { addNote, deleteNote, listNotes, type Result } from "./actions.ts";
import { title } from "./env.ts";
import { fields } from "./http.ts";
import type { Who } from "./who.ts";
interface Tool {
  readonly name: string;
  readonly description: string;
  readonly inputSchema: Record<string, unknown>;
  readonly run: (
    db: Database,
    who: Who,
    args: Record<string, unknown>,
  ) => Result<unknown>;
}
export const tools: readonly Tool[] = [
  {
    name: "list_notes",
    description: "The notes, newest first.",
    inputSchema: {
      type: "object",
      properties: {
        limit: {
          type: "integer",
          minimum: 1,
          maximum: 500,
          description: "At most this many (100).",
        },
      },
    },
    run: (db, who, args) =>
      listNotes(db, who, { limit: Number(args.limit ?? 100) }),
  },
  {
    name: "add_note",
    description:
      "Add a note as the signed-in person. Anonymous callers cannot.",
    inputSchema: {
      type: "object",
      properties: { body: { type: "string", maxLength: 500 } },
      required: ["body"],
    },
    run: (db, who, args) => addNote(db, who, { body: String(args.body ?? "") }),
  },
  {
    name: "delete_note",
    description: "Remove a note by id. Only its author or an admin can.",
    inputSchema: {
      type: "object",
      properties: { id: { type: "integer" } },
      required: ["id"],
    },
    run: (db, who, args) => deleteNote(db, who, { id: Number(args.id) }),
  },
];
/** One JSON-RPC message in, an HTTP status and a body out (a notification gets 202 and no body). */
export function rpc(
  db: Database,
  who: Who,
  message: unknown,
): { status: number; body?: unknown } {
  const m = fields(message);
  const id = m.id ?? null;
  const reply = (result: unknown) => ({
    status: 200,
    body: { jsonrpc: "2.0", id, result },
  });
  const refuse = (code: number, text: string) => ({
    status: 200,
    body: { jsonrpc: "2.0", id, error: { code, message: text } },
  });
  if (m.jsonrpc !== "2.0" || typeof m.method !== "string")
    return refuse(-32600, "not a JSON-RPC 2.0 request");
  if (m.id === undefined) return { status: 202 };
  const params = fields(m.params);
  switch (m.method) {
    case "initialize":
      return reply({
        protocolVersion: "2025-06-18",
        capabilities: { tools: {} },
        serverInfo: { name: title, version: "1" },
      });
    case "ping":
      return reply({});
    case "tools/list":
      return reply({
        tools: tools.map(({ name, description, inputSchema }) => ({
          name,
          description,
          inputSchema,
        })),
      });
    case "tools/call": {
      const tool = tools.find((t) => t.name === params.name);
      if (tool === undefined)
        return refuse(-32602, `no tool named ${String(params.name)}`);
      const result = tool.run(db, who, fields(params.arguments));
      return reply(
        result.ok
          ? { content: [{ type: "text", text: JSON.stringify(result.value) }] }
          : {
              content: [
                { type: "text", text: `${result.error}: ${result.message}` },
              ],
              isError: true,
            },
      );
    }
    default:
      return refuse(-32601, `no method ${m.method}`);
  }
}
@@ -0,0 +1,76 @@
/**
 * The API's description is the routes' own, committed: emitting it twice
 * says the same bytes, the file in git is what the table says now, and the
 * app serves exactly that file.
 */
import { afterAll, expect, test } from "bun:test";
import { mkdtempSync, readFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { emit, openapi } from "./openapi.ts";
import { routes } from "./routes.ts";
import { serve } from "./server.ts";
const committed = readFileSync(
  new URL("../contract/openapi.json", import.meta.url),
  "utf8",
);
test("emission is stable", () => {
  expect(emit()).toBe(emit());
});
test("contract/openapi.json is what the routes say now (else: bun run contract:emit)", () => {
  const now = JSON.parse(emit());
  const stale = !Bun.deepEquals(JSON.parse(committed), now);
  if (stale)
    // Generated app's contract CLI: stderr is its output.
    console.error(
      "contract/openapi.json is stale: run `bun run contract:emit` and commit it",
    );
  expect(stale).toBe(false);
});
test("every API route is described, and every door names its cell of the table", () => {
  const doc = openapi() as {
    paths: Record<
      string,
      Record<
        string,
        { "x-contract"?: { resource: string; verb: string; least: string } }
      >
    >;
  };
  for (const route of routes.filter((r) => r.path.startsWith("/api/"))) {
    const op =
      doc.paths[route.path.replace(/:(\w+)/g, "{$1}")]?.[
        route.method.toLowerCase()
      ];
    expect([route.method, route.path, op !== undefined]).toEqual([
      route.method,
      route.path,
      true,
    ]);
    expect(typeof op?.["x-contract"]?.least).toBe("string");
  }
  expect(doc.paths["/api/audit"]?.get?.["x-contract"]).toEqual({
    resource: "audit",
    verb: "list",
    least: "admin",
  });
});
test("GET /openapi.json serves the committed file", async () => {
  const server = serve({
    port: 0,
    dataDir: mkdtempSync(join(tmpdir(), "app-openapi-")),
    identityKey: "k",
  });
  afterAll(() => server.stop(true));
  const response = await fetch(
    `http://${server.hostname}:${server.port}/openapi.json`,
  );
  expect(response.status).toBe(200);
  expect(response.headers.get("content-type")).toContain("application/json");
  expect(await response.text()).toBe(committed);
});
@@ -0,0 +1,102 @@
/**
 * The API, described: every route in `routes.ts` that declares `api`, as an
 * OpenAPI 3.1 document. Each operation also names the contract cell it is
 * (`x-contract`: the resource, the verb, and the least role the table asks
 * for), so a change of policy is a change here too, and shows in the pull.
 *
 *   bun run contract:emit    write contract/openapi.json from the table
 *
 * `src/openapi.test.ts` fails when the committed file and the routes
 * disagree: the description can go stale only in a commit that fails.
 */
import { contract } from "./contract.ts";
import { description, title, version } from "./env.ts";
import { AUDIT_ROW, ERROR, NOTE, routes, type Schema } from "./routes.ts";
import { doorOf } from "./security.ts";
// The shapes said once, under components, and referred to wherever they appear.
const NAMED = new Map<Schema, string>([
  [NOTE, "Note"],
  [AUDIT_ROW, "AuditRow"],
  [ERROR, "Error"],
]);
const named = (schema: Schema): Schema => {
  const name = NAMED.get(schema);
  if (name !== undefined) return { $ref: `#/components/schemas/${name}` };
  return Object.fromEntries(
    Object.entries(schema).map(([key, value]) => [
      key,
      typeof value === "object" && value !== null && !Array.isArray(value)
        ? named(value as Schema)
        : value,
    ]),
  );
};
const content = (schema: Schema) => ({
  "application/json": { schema: named(schema) },
});
export function openapi(): Record<string, unknown> {
  const paths: Record<string, Record<string, unknown>> = {};
  for (const route of routes) {
    if (route.api === undefined) continue;
    const { summary, body, answer, status, query } = route.api;
    const path = route.path.replace(/:(\w+)/g, "{$1}");
    const params = [...route.path.matchAll(/:(\w+)/g)].map(([, name]) => ({
      name,
      in: "path",
      required: true,
      schema: { type: "integer" },
    }));
    const door = doorOf(route.method, route.path.replace(/:\w+/g, "0"));
    const least =
      door === undefined
        ? undefined
        : contract.resources[door.resource]?.can[door.verb];
    paths[path] ??= {};
    paths[path][route.method.toLowerCase()] = {
      summary,
      operationId: `${route.method.toLowerCase()}${path.replace(/[{}]/g, "").replace(/(^|[/._-])(\w)/g, (_, __, c: string) => c.toUpperCase())}`,
      ...(params.length > 0 || query !== undefined
        ? {
            parameters: [
              ...params,
              ...Object.entries(query ?? {}).map(([name, schema]) => ({
                name,
                in: "query",
                schema: named(schema),
              })),
            ],
          }
        : {}),
      ...(body === undefined
        ? {}
        : { requestBody: { required: true, content: content(body) } }),
      responses: {
        [String(status ?? 200)]: {
          description: summary,
          content: content(answer),
        },
        default: {
          description: "{ error, message }: why not",
          content: content(ERROR),
        },
      },
      ...(door === undefined ? {} : { "x-contract": { ...door, least } }),
    };
  }
  return {
    openapi: "3.1.0",
    info: { title, version, description },
    paths,
    components: {
      schemas: Object.fromEntries(
        [...NAMED].map(([schema, name]) => [name, schema]),
      ),
    },
  };
}
/** The file's text: stable, so the same table always writes the same bytes. */
export const emit = (): string => `${JSON.stringify(openapi(), null, 2)}\n`;
@@ -0,0 +1,728 @@
/**
 * OpenTelemetry in one file, with nothing to install: W3C trace context in
 * and out, spans, metrics and logs exported as OTLP/JSON over plain `fetch`. The
 * forge traces its own requests with it, and every app the forge scaffolds
 * carries this same file as `src/otel.ts` — one implementation, read by both.
 *
 * Configured by the standard variables, so any OpenTelemetry collector works:
 *
 *   OTEL_EXPORTER_OTLP_ENDPOINT   e.g. http://otel-collector:4318 (unset = off)
 *   OTEL_SERVICE_NAME             what this process is called in a trace
 *   OTEL_RESOURCE_ATTRIBUTES      k=v,k=v added to every span and metric
 *   OTEL_SDK_DISABLED=true        off, whatever else is set
 *
 * With no endpoint every call here is a cheap no-op: spans are still made
 * (so code reads the same) but nothing is kept or sent. Export never throws
 * and never blocks a request; a collector that is down costs a dropped
 * batch, not an error page. The queue is bounded — the oldest spans go first.
 */
import { AsyncLocalStorage } from "node:async_hooks";
import { randomBytes } from "node:crypto";
// The real fetch, taken before anyone (an app's own setup) can replace the
// global with `tracedFetch`: export and tracedFetch's own call use it, so
// neither traces itself.
const nativeFetch: typeof fetch = globalThis.fetch.bind(globalThis);
export type Attr = string | number | boolean;
export type Attrs = Record<string, Attr | undefined>;
export const SpanKind = { internal: 1, server: 2, client: 3 } as const;
export type SpanKindName = keyof typeof SpanKind;
export interface SpanContext {
  readonly traceId: string;
  readonly spanId: string;
  readonly sampled: boolean;
}
interface Config {
  readonly endpoint: string | undefined;
  readonly service: string;
  readonly resource: Attrs;
}
const env = (name: string): string | undefined => {
  const value = process.env[name]?.trim();
  return value === "" ? undefined : value;
};
/** `k=v,k=v` as the spec writes it (values may be percent-encoded). */
export function parseResourceAttributes(raw: string | undefined): Attrs {
  const out: Attrs = {};
  for (const pair of (raw ?? "").split(",")) {
    const at = pair.indexOf("=");
    if (at <= 0) continue;
    const key = pair.slice(0, at).trim();
    let value = pair.slice(at + 1).trim();
    try {
      value = decodeURIComponent(value);
    } catch {
      // A stray % is kept as written.
    }
    if (key !== "") out[key] = value;
  }
  return out;
}
function configFromEnv(): Config {
  const disabled = env("OTEL_SDK_DISABLED") === "true";
  const resource = parseResourceAttributes(env("OTEL_RESOURCE_ATTRIBUTES"));
  const service =
    env("OTEL_SERVICE_NAME") ??
    (typeof resource["service.name"] === "string"
      ? resource["service.name"]
      : "unknown_service:bun");
  return {
    endpoint: disabled
      ? undefined
      : env("OTEL_EXPORTER_OTLP_ENDPOINT")?.replace(/\/+$/, ""),
    service,
    resource,
  };
}
let config: Config = configFromEnv();
/** Re-read the environment, or set explicitly (tests, embedders). */
export function configure(next?: Partial<Config>): void {
  config = { ...configFromEnv(), ...next };
}
export const enabled = (): boolean => config.endpoint !== undefined;
// ---- trace context ----------------------------------------------------------
const hex = (bytes: number): string => randomBytes(bytes).toString("hex");
const ZERO_TRACE = "0".repeat(32);
const ZERO_SPAN = "0".repeat(16);
/** `00-<trace>-<span>-<flags>`, or undefined for anything malformed. */
export function parseTraceparent(
  header: string | null | undefined,
): SpanContext | undefined {
  const match = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/.exec(
    (header ?? "").trim().toLowerCase(),
  );
  if (match === null) return undefined;
  const [, version, traceId, spanId, flags] = match as unknown as [
    string,
    string,
    string,
    string,
    string,
  ];
  if (version === "ff" || traceId === ZERO_TRACE || spanId === ZERO_SPAN)
    return undefined;
  return { traceId, spanId, sampled: (Number.parseInt(flags, 16) & 1) === 1 };
}
export const formatTraceparent = (ctx: SpanContext): string =>
  `00-${ctx.traceId}-${ctx.spanId}-${ctx.sampled ? "01" : "00"}`;
// ---- spans ------------------------------------------------------------------
/** Wall-clock nanoseconds, as a decimal string (OTLP/JSON's uint64 form). */
const nowNs = (): bigint =>
  BigInt(Math.round((performance.timeOrigin + performance.now()) * 1e3)) *
  1000n;
export class Span implements SpanContext {
  readonly traceId: string;
  readonly spanId: string;
  readonly parentSpanId: string | undefined;
  readonly sampled: boolean;
  readonly startNs: bigint;
  endNs: bigint | undefined;
  readonly attributes: Attrs;
  status: { code: 0 | 1 | 2; message?: string } = { code: 0 };
  readonly events: { name: string; timeNs: bigint; attributes: Attrs }[] = [];
  constructor(
    public name: string,
    readonly kind: SpanKindName,
    parent: SpanContext | undefined,
    attributes: Attrs,
    startTime?: number,
  ) {
    // A span recorded after the fact (a run that finished) says when it began.
    this.startNs = startTime === undefined ? nowNs() : BigInt(Math.round(startTime * 1e3)) * 1000n;
    this.traceId = parent?.traceId ?? hex(16);
    this.parentSpanId = parent?.spanId;
    this.sampled = parent?.sampled ?? true;
    this.spanId = hex(8);
    this.attributes = { ...attributes };
  }
  set(key: string, value: Attr | undefined): this {
    if (value !== undefined) this.attributes[key] = value;
    return this;
  }
  event(name: string, attributes: Attrs = {}): this {
    this.events.push({ name, timeNs: nowNs(), attributes });
    return this;
  }
  /** Mark failed. An exception's message is kept; its stack is not. */
  fail(error: unknown): this {
    const message = error instanceof Error ? error.message : String(error);
    this.status = { code: 2, message };
    this.event("exception", {
      "exception.type": error instanceof Error ? error.name : typeof error,
      "exception.message": message,
    });
    return this;
  }
  end(): void {
    if (this.endNs !== undefined) return;
    this.endNs = nowNs();
    if (this.sampled && enabled()) enqueue(this);
  }
  get durationSeconds(): number {
    return Number((this.endNs ?? nowNs()) - this.startNs) / 1e9;
  }
}
const active = new AsyncLocalStorage<Span>();
/** The span the current code runs inside, if any. */
export const currentSpan = (): Span | undefined => active.getStore();
export interface SpanOptions {
  readonly kind?: SpanKindName;
  /** Parent explicitly; default is the current span. `null` = a new trace. */
  readonly parent?: SpanContext | null;
  readonly attributes?: Attrs;
  /** When it began, in epoch milliseconds, if before now. */
  readonly startTime?: number;
}
export function startSpan(name: string, options: SpanOptions = {}): Span {
  const parent =
    options.parent === null ? undefined : (options.parent ?? currentSpan());
  return new Span(name, options.kind ?? "internal", parent, options.attributes ?? {}, options.startTime);
}
/**
 * Run `fn` inside a new span: it is current for everything `fn` awaits, it
 * ends when `fn` settles, and a throw marks it failed (and still throws).
 */
export async function span<T>(
  name: string,
  fn: (span: Span) => T | Promise<T>,
  options: SpanOptions = {},
): Promise<T> {
  const s = startSpan(name, options);
  try {
    return await active.run(s, () => fn(s));
  } catch (error) {
    s.fail(error);
    throw error;
  } finally {
    s.end();
  }
}
/** Run `fn` with `s` as the current span, without ending it. */
export const withSpan = <T>(s: Span, fn: () => T): T => active.run(s, fn);
// ---- HTTP -------------------------------------------------------------------
/**
 * A server span for one request, parented on the caller's `traceparent`.
 * Records `http.server.request.duration` too. `route` names the matched
 * route template (`/notes/:id`) once it is known — set it on the span.
 */
export async function serveSpan<R extends Response | undefined>(
  request: Request,
  handle: (span: Span) => R | Promise<R>,
  attributes: Attrs = {},
): Promise<R> {
  const url = new URL(request.url);
  const s = startSpan(request.method, {
    kind: "server",
    parent: parseTraceparent(request.headers.get("traceparent")) ?? null,
    attributes: {
      "http.request.method": request.method,
      "url.path": url.pathname,
      "url.scheme":
        request.headers.get("x-forwarded-proto") ?? url.protocol.slice(0, -1),
      "server.address": (
        request.headers.get("x-forwarded-host") ??
        request.headers.get("host") ??
        url.hostname
      ).replace(/:\d+$/, ""),
      "user_agent.original": request.headers.get("user-agent") ?? undefined,
      ...attributes,
    },
  });
  let status = 500;
  try {
    const response = await active.run(s, () => handle(s));
    // undefined = the socket was upgraded (a websocket): it answered 101.
    status = response?.status ?? 101;
    return response;
  } catch (error) {
    s.fail(error);
    throw error;
  } finally {
    endServerSpan(s, status);
  }
}
/**
 * Trace a whole `Bun.serve` options object: its `fetch` runs inside
 * `serveSpan`, everything else (websocket handlers, port, error) untouched.
 * The one-line retrofit for an app that routes by hand:
 *
 *   Bun.serve(traceServe({ port, fetch(request, server) { ... } }))
 *
 * A route template isn't known here, so spans are named by method only —
 * set `http.route` on `currentSpan()` from the handler if you route by name.
 */
export function traceServe<
  T extends { fetch: (request: Request, ...rest: never[]) => unknown },
>(options: T): T {
  const inner = options.fetch;
  return {
    ...options,
    fetch(this: unknown, request: Request, ...rest: never[]) {
      return serveSpan(
        request,
        async () =>
          (await inner.call(this, request, ...rest)) as Response | undefined,
      );
    },
  };
}
/**
 * Finish a server span made by hand (a framework's request hooks): status,
 * the `METHOD /route` name, and the duration histogram — what `serveSpan`
 * does in its `finally`.
 */
export function endServerSpan(s: Span, status: number): void {
  const method = s.attributes["http.request.method"];
  s.set("http.response.status_code", status);
  if (status >= 500 && s.status.code === 0) s.status = { code: 2 };
  const route = s.attributes["http.route"];
  if (typeof route === "string" && typeof method === "string")
    s.name = `${method} ${route}`;
  s.end();
  requestDuration.record(s.durationSeconds, {
    "http.request.method": typeof method === "string" ? method : undefined,
    "http.route": typeof route === "string" ? route : undefined,
    "http.response.status_code": status,
  });
}
/**
 * `fetch` that makes a client span and hands the callee our `traceparent`,
 * so its spans join this trace. Same signature as `fetch`.
 */
export async function tracedFetch(
  input: string | URL | Request,
  init: RequestInit = {},
): Promise<Response> {
  const request =
    input instanceof Request
      ? new Request(input, init)
      : new Request(String(input), init);
  const url = new URL(request.url);
  return span(
    `${request.method}`,
    async (s) => {
      const headers = new Headers(request.headers);
      headers.set("traceparent", formatTraceparent(s));
      const response = await nativeFetch(new Request(request, { headers }));
      s.set("http.response.status_code", response.status);
      if (response.status >= 500) s.status = { code: 2 };
      return response;
    },
    {
      kind: "client",
      attributes: {
        "http.request.method": request.method,
        "server.address": url.hostname,
        "server.port": url.port === "" ? undefined : Number(url.port),
        "url.full": `${url.origin}${url.pathname}`,
      },
    },
  );
}
// ---- metrics ----------------------------------------------------------------
const DURATION_BUCKETS = [
  0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10,
];
const attrKey = (attrs: Attrs): string =>
  JSON.stringify(
    Object.entries(attrs)
      .filter(([, v]) => v !== undefined)
      .sort(([a], [b]) => (a < b ? -1 : 1)),
  );
interface Instrument {
  readonly name: string;
  readonly unit: string;
  readonly description: string;
  toOtlp(startNs: string, nowNs: string): unknown | undefined;
}
const instruments: Instrument[] = [];
const processStartNs = nowNs().toString();
export interface Histogram {
  record(value: number, attributes?: Attrs): void;
}
/** A cumulative explicit-bucket histogram. Keep attribute values few. */
export function histogram(
  name: string,
  options: { unit?: string; description?: string; buckets?: number[] } = {},
): Histogram {
  const bounds = options.buckets ?? DURATION_BUCKETS;
  const points = new Map<
    string,
    { attrs: Attrs; count: number; sum: number; buckets: number[] }
  >();
  instruments.push({
    name,
    unit: options.unit ?? "s",
    description: options.description ?? "",
    toOtlp(startNs, timeNs) {
      if (points.size === 0) return undefined;
      return {
        histogram: {
          aggregationTemporality: 2,
          dataPoints: [...points.values()].map((p) => ({
            attributes: otlpAttrs(p.attrs),
            startTimeUnixNano: startNs,
            timeUnixNano: timeNs,
            count: String(p.count),
            sum: p.sum,
            bucketCounts: p.buckets.map(String),
            explicitBounds: bounds,
          })),
        },
      };
    },
  });
  return {
    record(value, attributes = {}) {
      if (!enabled() || !Number.isFinite(value)) return;
      const key = attrKey(attributes);
      let p = points.get(key);
      if (p === undefined) {
        p = {
          attrs: attributes,
          count: 0,
          sum: 0,
          buckets: new Array(bounds.length + 1).fill(0),
        };
        points.set(key, p);
      }
      p.count += 1;
      p.sum += value;
      let i = bounds.findIndex((b) => value <= b);
      if (i === -1) i = bounds.length;
      p.buckets[i] = (p.buckets[i] ?? 0) + 1;
    },
  };
}
export interface Counter {
  add(value?: number, attributes?: Attrs): void;
}
/** A cumulative monotonic sum. */
export function counter(
  name: string,
  options: { unit?: string; description?: string } = {},
): Counter {
  const points = new Map<string, { attrs: Attrs; value: number }>();
  instruments.push({
    name,
    unit: options.unit ?? "1",
    description: options.description ?? "",
    toOtlp(startNs, timeNs) {
      if (points.size === 0) return undefined;
      return {
        sum: {
          aggregationTemporality: 2,
          isMonotonic: true,
          dataPoints: [...points.values()].map((p) => ({
            attributes: otlpAttrs(p.attrs),
            startTimeUnixNano: startNs,
            timeUnixNano: timeNs,
            asDouble: p.value,
          })),
        },
      };
    },
  });
  return {
    add(value = 1, attributes = {}) {
      if (!enabled() || !(value >= 0)) return;
      const key = attrKey(attributes);
      const p = points.get(key);
      if (p === undefined) points.set(key, { attrs: attributes, value });
      else p.value += value;
    },
  };
}
/** A value read at export time: queue depth, rows in a table, players online. */
export function gauge(
  name: string,
  read: () => number | { value: number; attributes?: Attrs }[],
  options: { unit?: string; description?: string } = {},
): void {
  instruments.push({
    name,
    unit: options.unit ?? "1",
    description: options.description ?? "",
    toOtlp(_startNs, timeNs) {
      let values: { value: number; attributes?: Attrs }[];
      try {
        const got = read();
        values = typeof got === "number" ? [{ value: got }] : got;
      } catch {
        return undefined;
      }
      if (values.length === 0) return undefined;
      return {
        gauge: {
          dataPoints: values.map((v) => ({
            attributes: otlpAttrs(v.attributes ?? {}),
            timeUnixNano: timeNs,
            asDouble: v.value,
          })),
        },
      };
    },
  });
}
/** The semantic-convention HTTP server histogram `serveSpan` records into. */
const requestDuration = histogram("http.server.request.duration", {
  unit: "s",
  description: "Duration of HTTP server requests.",
});
// ---- logs -------------------------------------------------------------------
export type Severity = "debug" | "info" | "warn" | "error";
const SEVERITY_NUMBER: Record<Severity, number> = { debug: 5, info: 9, warn: 13, error: 17 };
export interface LogOptions {
  readonly severity?: Severity;
  readonly attributes?: Attrs;
  /**
   * Who is speaking, when it is not this process: the forge files each
   * app's output under the app's own `service.name`. Added to (and wins
   * over) this process's resource.
   */
  readonly resource?: Attrs;
}
interface LogEntry {
  readonly timeNs: bigint;
  readonly body: string;
  readonly severity: Severity;
  readonly attributes: Attrs;
  readonly resource: Attrs | undefined;
  readonly traceId: string | undefined;
  readonly spanId: string | undefined;
}
const MAX_LOG_QUEUE = 4096;
let logQueue: LogEntry[] = [];
/**
 * One log record, tied to the current span when there is one. A no-op
 * without an endpoint; never throws, never blocks.
 */
export function emitLog(body: string, options: LogOptions = {}): void {
  if (!enabled()) return;
  const s = currentSpan();
  logQueue.push({
    timeNs: nowNs(),
    body,
    severity: options.severity ?? "info",
    attributes: options.attributes ?? {},
    resource: options.resource,
    traceId: s?.traceId,
    spanId: s?.spanId,
  });
  // The oldest go first: a flood keeps its newest lines.
  if (logQueue.length > MAX_LOG_QUEUE) logQueue = logQueue.slice(-MAX_LOG_QUEUE);
  startTimer();
}
/** Log records in OTLP/JSON, grouped by who spoke. */
export function logsToOtlp(entries: readonly LogEntry[]): unknown {
  const byResource = new Map<string, { resource: Attrs | undefined; records: unknown[] }>();
  for (const e of entries) {
    const key = e.resource === undefined ? "" : attrKey(e.resource);
    let group = byResource.get(key);
    if (group === undefined) byResource.set(key, (group = { resource: e.resource, records: [] }));
    group.records.push({
      timeUnixNano: e.timeNs.toString(),
      observedTimeUnixNano: e.timeNs.toString(),
      severityNumber: SEVERITY_NUMBER[e.severity],
      severityText: e.severity.toUpperCase(),
      body: { stringValue: e.body },
      attributes: otlpAttrs(e.attributes),
      ...(e.traceId === undefined ? {} : { traceId: e.traceId }),
      ...(e.spanId === undefined ? {} : { spanId: e.spanId }),
    });
  }
  return {
    resourceLogs: [...byResource.values()].map((g) => ({
      resource: resource(g.resource),
      scopeLogs: [{ scope: SCOPE, logRecords: g.records }],
    })),
  };
}
// ---- export -----------------------------------------------------------------
function otlpValue(value: Attr): Record<string, unknown> {
  if (typeof value === "boolean") return { boolValue: value };
  if (typeof value === "number")
    return Number.isInteger(value)
      ? { intValue: String(value) }
      : { doubleValue: value };
  return { stringValue: value };
}
export function otlpAttrs(attrs: Attrs): unknown[] {
  return Object.entries(attrs)
    .filter((e): e is [string, Attr] => e[1] !== undefined)
    .map(([key, value]) => ({ key, value: otlpValue(value) }));
}
const resource = (over?: Attrs) => ({
  attributes: otlpAttrs({
    "telemetry.sdk.name": "forge-otel",
    "telemetry.sdk.language": "js",
    "process.runtime.name": process.versions.bun === undefined ? "node" : "bun",
    "process.runtime.version": process.versions.bun ?? process.versions.node,
    ...config.resource,
    "service.name": config.service,
    ...over,
  }),
});
const SCOPE = { name: "forge-otel", version: "1" };
/** One span in OTLP/JSON (ids are lowercase hex, times decimal ns). */
export function spanToOtlp(s: Span): unknown {
  return {
    traceId: s.traceId,
    spanId: s.spanId,
    ...(s.parentSpanId === undefined ? {} : { parentSpanId: s.parentSpanId }),
    name: s.name,
    kind: SpanKind[s.kind],
    startTimeUnixNano: s.startNs.toString(),
    endTimeUnixNano: (s.endNs ?? s.startNs).toString(),
    attributes: otlpAttrs(s.attributes),
    events: s.events.map((e) => ({
      name: e.name,
      timeUnixNano: e.timeNs.toString(),
      attributes: otlpAttrs(e.attributes),
    })),
    status: s.status,
  };
}
const MAX_QUEUE = 2048;
const BATCH = 512;
let queue: Span[] = [];
let timer: ReturnType<typeof setInterval> | undefined;
let lastMetrics = 0;
function enqueue(s: Span): void {
  queue.push(s);
  if (queue.length > MAX_QUEUE) queue = queue.slice(-MAX_QUEUE);
  startTimer();
}
function startTimer(): void {
  if (timer === undefined) {
    timer = setInterval(() => void flush(), 5_000);
    // Telemetry must never be the reason a process stays alive.
    (timer as { unref?: () => void }).unref?.();
  }
}
async function post(path: string, body: unknown): Promise<boolean> {
  if (config.endpoint === undefined) return false;
  try {
    const response = await nativeFetch(`${config.endpoint}${path}`, {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify(body),
      signal: AbortSignal.timeout(5_000),
    });
    return response.ok;
  } catch {
    return false;
  }
}
/** Send what is queued now. Resolves when sent (or dropped); never throws. */
export async function flush(): Promise<void> {
  while (queue.length > 0) {
    const batch = queue.splice(0, BATCH);
    await post("/v1/traces", {
      resourceSpans: [
        { resource: resource(), scopeSpans: [{ scope: SCOPE, spans: batch.map(spanToOtlp) }] },
      ],
    });
  }
  while (logQueue.length > 0) {
    const batch = logQueue.splice(0, BATCH);
    await post("/v1/logs", logsToOtlp(batch));
  }
  if (Date.now() - lastMetrics >= 30_000) {
    lastMetrics = Date.now();
    await flushMetrics();
  }
}
export function metricsToOtlp(): unknown | undefined {
  const timeNs = nowNs().toString();
  const metrics = instruments.flatMap((i) => {
    const data = i.toOtlp(processStartNs, timeNs);
    return data === undefined
      ? []
      : [{ name: i.name, unit: i.unit, description: i.description, ...(data as object) }];
  });
  if (metrics.length === 0) return undefined;
  return {
    resourceMetrics: [
      { resource: resource(), scopeMetrics: [{ scope: SCOPE, metrics }] },
    ],
  };
}
export async function flushMetrics(): Promise<void> {
  if (!enabled()) return;
  const body = metricsToOtlp();
  if (body !== undefined) await post("/v1/metrics", body);
}
/** Start the periodic exporter even before the first span (metrics-only apps). */
export function start(): void {
  if (!enabled() || timer !== undefined) return;
  timer = setInterval(() => void flush(), 5_000);
  (timer as { unref?: () => void }).unref?.();
}
@@ -0,0 +1,123 @@
/**
 * The page, rendered on the server: the first paint is complete HTML, and
 * `static/live.js` keeps the notes fresh afterwards. When a second page
 * arrives, move `layout` to `src/pages/layout.ts` and give each page a file.
 */
import { canDelete, type Note } from "./actions.ts";
import {
  commit,
  description,
  env,
  publicOrigin,
  ssh,
  title,
  where,
} from "./env.ts";
import { asset, escape } from "./http.ts";
import { token, tokensHref } from "./tokens.ts";
import type { Who } from "./who.ts";
/**
 * The frame every page shares: the tokens and the look, who you are, and
 * what a link to the page says when it is shared — a title, a sentence
 * and the address, for Open Graph and the card a chat app unfurls.
 */
export function layout(body: string, who: Who, path = "/"): string {
  const door =
    who.role === "anon"
      ? `<a class="button button-quiet" href="/__forge/signin?to=/">Sign in</a>`
      : `<span class="you"><b>${escape(who.name)}</b>${who.role === "admin" ? " · admin" : ""}</span>
        <a class="button button-quiet" href="/__forge/signout">Sign out</a>`;
  return `<!doctype html>
<html lang="en">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="color-scheme" content="light dark">
<meta name="theme-color" content="${token("color-bg")}" media="(prefers-color-scheme: light)">
<meta name="theme-color" content="${token("color-bg", "dark")}" media="(prefers-color-scheme: dark)">
<link rel="icon" href="data:,">
<title>${escape(title)}</title>
<meta name="description" content="${escape(description)}">
<meta property="og:type" content="website">
<meta property="og:site_name" content="${escape(title)}">
<meta property="og:title" content="${escape(title)}">
<meta property="og:description" content="${escape(description)}">
<meta property="og:url" content="${escape(publicOrigin + path)}">
<meta name="twitter:card" content="summary">
<meta name="twitter:title" content="${escape(title)}">
<meta name="twitter:description" content="${escape(description)}">
<link rel="stylesheet" href="${tokensHref}">
<link rel="stylesheet" href="${asset("app.css")}">
<script type="module" src="${asset("live.js")}"></script>
<body>
<div class="page">
  <header class="head">
    <div>
      <h1>${escape(title)}</h1>
      <p class="muted">${escape(description)}</p>
    </div>
    <nav class="row">
      <span class="pill" data-env="${escape(env)}">${escape(where)}</span>${commit ? `<span class="muted mono">${escape(commit)}</span>` : ""}
      ${door}
    </nav>
  </header>
  <main>${body}</main>
  <footer class="muted">
    ${ssh === undefined ? "" : `<p>Terminal: <code>${escape(ssh)}</code></p>`}
    <p>Also at <a href="/api/notes">/api/notes</a> (<a href="/openapi.json">described</a>) and <code>POST /mcp</code>, with the same rules.</p>
    <p>Something wrong? <a href="/__forge/report">Report a problem</a>, no account needed.</p>
  </footer>
</div>
</body>
</html>
`;
}
export function home(input: {
  who: Who;
  notes: readonly Note[];
  notice?: string | undefined;
}): string {
  const { who, notes, notice } = input;
  const composer =
    who.role === "anon"
      ? `<p class="muted">Reading as a guest. <a href="/__forge/signin?to=/">Sign in</a> to add a note.</p>`
      : `<form class="row" method="post" action="/notes">
        <input class="input" name="body" placeholder="Write a note" aria-label="New note" required maxlength="500" autocomplete="off" autofocus>
        <button class="button">Add</button>
      </form>`;
  const list =
    notes.length === 0
      ? `<p class="empty">No notes yet. Notes written here stay in ${escape(where)} data.</p>`
      : `<ul class="list">${notes.map((note) => item(note, who)).join("")}</ul>`;
  return layout(
    `<section class="card">${composer}</section>
  <section id="notes" data-live="note.added note.removed">${list}</section>
  ${notice === undefined ? "" : `<p class="toast" role="status">${escape(notice)}</p>`}`,
    who,
  );
}
const item = (note: Note, who: Who): string => `<li class="note">
  <div>
    <p>${escape(note.body)}</p>
    <small class="muted">${escape(note.author_name)} · <time datetime="${escape(note.created_at)}">${ago(note.created_at)}</time></small>
  </div>
  ${
    canDelete(who, note)
      ? `<form method="post" action="/notes/${note.id}/delete"><button class="button button-quiet" aria-label="Remove this note">Remove</button></form>`
      : ""
  }
</li>`;
const ago = (iso: string): string => {
  const s = Math.max(0, (Date.now() - Date.parse(iso)) / 1000);
  if (s < 60) return "just now";
  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
  if (s < 86400) return `${Math.floor(s / 3600)}h ago`;
  return new Date(iso).toLocaleDateString("en", {
    month: "short",
    day: "numeric",
  });
};
@@ -0,0 +1,464 @@
/**
 * Every path the app answers, in one table. A route reads its request,
 * calls an action, and shapes the answer for its door — HTML for a
 * browser, JSON for a script — and that is all a route does.
 *
 * A route that is part of the API says so beside itself (`api`): one
 * sentence, and the shape of what it takes and gives, as JSON Schema.
 * `bun run contract:emit` writes those into `contract/openapi.json`, the
 * tests fail when the committed file and this table disagree, and
 * `GET /openapi.json` serves it. The shapes describe; the checks that hold
 * are still the actions' own.
 */
import type { Database } from "bun:sqlite";
import { existsSync, readFileSync } from "node:fs";
import {
  addNote,
  BODY_MAX,
  deleteNote,
  getAudit,
  getNote,
  listAudit,
  listNotes,
  updateNote,
  type Failure,
  type Result,
} from "./actions.ts";
import { commit, env, forgeUrl, startedAt, version } from "./env.ts";
import {
  back,
  fields,
  html,
  json,
  readForm,
  readJson,
  readNotice,
  SECURITY,
  staticFile,
  text,
} from "./http.ts";
import { events } from "./live.ts";
import { rpc } from "./mcp.ts";
import { home } from "./page.ts";
import { tokensCss } from "./tokens.ts";
import type { Who } from "./who.ts";
export interface Context {
  readonly request: Request;
  readonly url: URL;
  readonly db: Database;
  readonly who: Who;
  readonly params: Record<string, string>;
}
/** A JSON Schema, as plain data. */
export type Schema = Readonly<Record<string, unknown>>;
/** What an API route is, for the description: never consulted to decide anything. */
export interface Api {
  readonly summary: string;
  /** The body it reads. */
  readonly body?: Schema;
  /** What it answers when it succeeds, and with which status (200). */
  readonly answer: Schema;
  readonly status?: number;
  /** The query parameters it reads. */
  readonly query?: Readonly<Record<string, Schema>>;
}
export interface Route {
  readonly method: "GET" | "POST" | "PATCH" | "DELETE";
  readonly path: string;
  readonly handle: (ctx: Context) => Response | Promise<Response>;
  readonly api?: Api;
}
// The shapes the API speaks in, named once.
export const NOTE: Schema = {
  type: "object",
  properties: {
    id: { type: "integer" },
    body: { type: "string", minLength: 1, maxLength: BODY_MAX },
    author_id: { type: "string" },
    author_name: { type: "string" },
    created_at: { type: "string", format: "date-time" },
    updated_at: { type: "string", format: "date-time" },
  },
  required: [
    "id",
    "body",
    "author_id",
    "author_name",
    "created_at",
    "updated_at",
  ],
};
const NOTE_BODY: Schema = {
  type: "object",
  properties: { body: { type: "string", minLength: 1, maxLength: BODY_MAX } },
  required: ["body"],
};
export const AUDIT_ROW: Schema = {
  type: "object",
  properties: {
    id: { type: "integer" },
    at: { type: "string", format: "date-time" },
    who_id: { type: ["string", "null"] },
    who_name: { type: ["string", "null"] },
    role: { enum: ["anon", "user", "admin"] },
    resource: { type: "string" },
    verb: { type: "string" },
    target: { type: ["string", "null"] },
    allowed: { enum: [0, 1] },
    outcome: { type: "string" },
  },
  required: ["id", "at", "role", "resource", "verb", "allowed", "outcome"],
};
export const ERROR: Schema = {
  type: "object",
  properties: { error: { type: "string" }, message: { type: "string" } },
  required: ["error"],
};
const LIMIT: Schema = {
  type: "integer",
  minimum: 1,
  maximum: 500,
  default: 100,
};
const list = (items: Schema): Schema => ({ type: "array", items });
const STATUS: Record<Failure, number> = {
  signin_required: 401,
  forbidden: 403,
  not_found: 404,
  invalid: 422,
};
/** A result as JSON: the value, or `{ error, message }` with the matching status. */
const answer = <T>(result: Result<T>, status = 200): Response =>
  result.ok
    ? json(result.value, status)
    : json(
        { error: result.error, message: result.message },
        STATUS[result.error],
      );
/** A result for a form: back to the page, with what went wrong if it did. */
const done = <T>(result: Result<T>): Response =>
  result.ok ? back() : back(result.message);
/** A whole number from the query, or undefined. */
const whole = (value: string | null): number | undefined =>
  value !== null && /^\d+$/.test(value) ? Number(value) : undefined;
// The API's description, read from git once: what the tests hold equal to this table.
const OPENAPI = new URL("../contract/openapi.json", import.meta.url);
const openapi = existsSync(OPENAPI) ? readFileSync(OPENAPI, "utf8") : undefined;
export const routes: readonly Route[] = [
  // The page. Forms post and come back; the list stays live over /events.
  {
    method: "GET",
    path: "/",
    handle: (c) => {
      const { notice, clear } = readNotice(c.request);
      const notes = listNotes(c.db, c.who);
      return html(
        home({ who: c.who, notes: notes.ok ? notes.value : [], notice }),
        200,
        clear,
      );
    },
  },
  {
    method: "POST",
    path: "/notes",
    handle: async (c) => {
      const form = await readForm(c.request);
      if (form === undefined) return text("too large", 413);
      return done(
        addNote(c.db, c.who, { body: String(form.get("body") ?? "") }),
      );
    },
  },
  {
    method: "POST",
    path: "/notes/:id/delete",
    handle: (c) => done(deleteNote(c.db, c.who, { id: Number(c.params.id) })),
  },
  // The JSON API: the same actions, the same identity, plain status codes.
  {
    method: "GET",
    path: "/api/notes",
    handle: (c) =>
      answer(
        listNotes(c.db, c.who, {
          limit: Number(c.url.searchParams.get("limit") ?? 100),
        }),
      ),
    api: {
      summary: "The notes, newest first.",
      query: { limit: LIMIT },
      answer: list(NOTE),
    },
  },
  {
    method: "POST",
    path: "/api/notes",
    handle: async (c) => {
      const body = await readJson(c.request);
      if (body === undefined) return json({ error: "too_large" }, 413);
      return answer(
        addNote(c.db, c.who, { body: String(fields(body).body ?? "") }),
        201,
      );
    },
    api: {
      summary: "Add a note as the person asking.",
      body: NOTE_BODY,
      answer: NOTE,
      status: 201,
    },
  },
  {
    method: "GET",
    path: "/api/notes/:id",
    handle: (c) => answer(getNote(c.db, c.who, { id: Number(c.params.id) })),
    api: { summary: "One note.", answer: NOTE },
  },
  {
    method: "PATCH",
    path: "/api/notes/:id",
    handle: async (c) => {
      const body = await readJson(c.request);
      if (body === undefined) return json({ error: "too_large" }, 413);
      return answer(
        updateNote(c.db, c.who, {
          id: Number(c.params.id),
          body: String(fields(body).body ?? ""),
        }),
      );
    },
    api: { summary: "Change a note's words.", body: NOTE_BODY, answer: NOTE },
  },
  {
    method: "DELETE",
    path: "/api/notes/:id",
    handle: (c) => answer(deleteNote(c.db, c.who, { id: Number(c.params.id) })),
    api: {
      summary: "Remove a note.",
      answer: {
        type: "object",
        properties: { id: { type: "integer" } },
        required: ["id"],
      },
    },
  },
  // Who tried to change what: the audit trail, for whoever the table lets read it.
  {
    method: "GET",
    path: "/api/audit",
    handle: (c) =>
      answer(
        listAudit(c.db, c.who, {
          limit: whole(c.url.searchParams.get("limit")) ?? 100,
          ...(whole(c.url.searchParams.get("before")) === undefined
            ? {}
            : { before: whole(c.url.searchParams.get("before"))! }),
        }),
      ),
    api: {
      summary: "The audit trail, newest first; `before` pages back by id.",
      query: { limit: LIMIT, before: { type: "integer" } },
      answer: list(AUDIT_ROW),
    },
  },
  {
    method: "GET",
    path: "/api/audit/:id",
    handle: (c) => answer(getAudit(c.db, c.who, { id: Number(c.params.id) })),
    api: { summary: "One row of the audit trail.", answer: AUDIT_ROW },
  },
  // Live events, and the MCP server (the tools are the actions too).
  { method: "GET", path: "/events", handle: (c) => events(c.request) },
  {
    method: "POST",
    path: "/mcp",
    handle: async (c) => {
      const message = await readJson(c.request);
      if (message === undefined) return json({ error: "too_large" }, 413);
      if (message === null)
        return json({
          jsonrpc: "2.0",
          id: null,
          error: { code: -32700, message: "parse error" },
        });
      const { status, body } = rpc(c.db, c.who, message);
      return body === undefined
        ? new Response(null, { status })
        : json(body, status);
    },
    api: {
      summary:
        "One JSON-RPC 2.0 message to the MCP server; its tools are the actions.",
      body: {
        type: "object",
        properties: {
          jsonrpc: { const: "2.0" },
          id: {},
          method: { type: "string" },
          params: { type: "object" },
        },
        required: ["jsonrpc", "method"],
      },
      answer: { type: "object" },
    },
  },
  {
    method: "GET",
    path: "/mcp",
    handle: () => text("this endpoint speaks JSON-RPC over POST", 405),
  },
  // Up or not, for the forge and for anyone watching: a separate path from
  // the page, so a health check never renders it.
  {
    method: "GET",
    path: "/healthz",
    handle: (c) => {
      let ok = true;
      try {
        c.db.query("SELECT 1").get();
      } catch {
        ok = false;
      }
      const uptime = Math.floor((Date.now() - startedAt) / 1000);
      return new Response(
        JSON.stringify({ ok, version, commit, env, uptime }),
        {
          status: ok ? 200 : 503,
          headers: {
            "content-type": "application/json; charset=utf-8",
            "cache-control": "no-store",
            ...SECURITY,
          },
        },
      );
    },
    api: {
      summary:
        "Whether the app is up: its version, commit, environment and seconds since it started.",
      answer: {
        type: "object",
        properties: {
          ok: { type: "boolean" },
          version: { type: "string" },
          commit: { type: "string" },
          env: { type: "string" },
          uptime: { type: "integer" },
        },
        required: ["ok", "version", "uptime"],
      },
    },
  },
  {
    method: "GET",
    path: "/openapi.json",
    handle: () =>
      openapi === undefined
        ? text("not found", 404)
        : new Response(openapi, {
            headers: {
              "content-type": "application/json; charset=utf-8",
              "cache-control": "no-cache",
              ...SECURITY,
            },
          }),
  },
  // The look: design/tokens.json, compiled at boot, cached for a year when linked by content.
  {
    method: "GET",
    path: "/tokens.css",
    handle: (c) =>
      new Response(tokensCss, {
        headers: {
          "content-type": "text/css; charset=utf-8",
          "cache-control": c.url.searchParams.has("v")
            ? "public, max-age=31536000, immutable"
            : "no-cache",
          ...SECURITY,
        },
      }),
  },
  // What the web expects of a site. Crawlers read the page, not the API;
  // a preview is a draft and is read by nobody. Where to report a
  // vulnerability is the forge's to say: it runs this app.
  {
    method: "GET",
    path: "/robots.txt",
    handle: () =>
      text(
        env === "production"
          ? "User-agent: *\nDisallow: /api/\nDisallow: /mcp\nDisallow: /events\nDisallow: /__forge/\n"
          : "User-agent: *\nDisallow: /\n",
      ),
  },
  {
    method: "GET",
    path: "/.well-known/security.txt",
    handle: () =>
      forgeUrl === undefined
        ? text("not found", 404)
        : new Response(null, {
            status: 302,
            headers: {
              location: new URL(
                "/.well-known/security.txt",
                forgeUrl,
              ).toString(),
              ...SECURITY,
            },
          }),
  },
  // Files under ./static, cached for a year when linked by content (`asset`).
  {
    method: "GET",
    path: "/static/:file",
    handle: (c) => staticFile(c.params.file ?? "", c.url.searchParams.has("v")),
  },
];
/** The route for a method and path, with what its `:names` matched. */
export function match(
  method: string,
  pathname: string,
): { route: Route; params: Record<string, string> } | undefined {
  const parts = pathname.split("/");
  for (const route of routes) {
    if (route.method !== method) continue;
    const pattern = route.path.split("/");
    if (pattern.length !== parts.length) continue;
    const params: Record<string, string> = {};
    const hit = pattern.every((p, i) => {
      if (p.startsWith(":")) {
        // A malformed escape is no match, never a thrown error.
        try {
          params[p.slice(1)] = decodeURIComponent(parts[i] ?? "");
          return true;
        } catch {
          return false;
        }
      }
      return p === parts[i];
    });
    if (hit) return { route, params };
  }
  return undefined;
}
@@ -0,0 +1,173 @@
/**
 * The door turns away, before a byte of the body is read, exactly who the
 * table says could never pass — and nobody it would let through.
 */
import { afterAll, expect, test } from "bun:test";
import { mkdtempSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { readContract } from "./can.ts";
import { openDb } from "./db.ts";
import {
  allow,
  door,
  doorOf,
  mayKnock,
  openToStrangers,
  STRANGERS,
} from "./security.ts";
import { serve } from "./server.ts";
import { sign } from "./who.ts";
const KEY = "a-key-only-the-forge-holds";
const server = serve({
  port: 0,
  dataDir: mkdtempSync(join(tmpdir(), "app-door-")),
  identityKey: KEY,
});
const base = `http://${server.hostname}:${server.port}`;
afterAll(() => server.stop(true));
const as = (id: string, role: "user" | "admin"): Record<string, string> => {
  const identity = `${id}|${id}|${role}|${Date.now() + 60_000}`;
  return {
    "x-forge-identity": identity,
    "x-forge-signature": sign(identity, KEY),
  };
};
test("a path is a resource's door by the contract's api, and nothing else is", () => {
  expect(doorOf("GET", "/api/notes")).toEqual({
    resource: "note",
    verb: "list",
  });
  expect(doorOf("POST", "/api/notes")).toEqual({
    resource: "note",
    verb: "create",
  });
  expect(doorOf("GET", "/api/notes/7")).toEqual({
    resource: "note",
    verb: "read",
  });
  expect(doorOf("PATCH", "/api/notes/7")).toEqual({
    resource: "note",
    verb: "update",
  });
  expect(doorOf("DELETE", "/api/notes/7")).toEqual({
    resource: "note",
    verb: "delete",
  });
  expect(doorOf("GET", "/api/audit")).toEqual({
    resource: "audit",
    verb: "list",
  });
  for (const [method, path] of [
    ["PUT", "/api/notes"],
    ["GET", "/api/notes/7/x"],
    ["GET", "/api/notesy"],
    ["GET", "/api/notes/"],
    ["POST", "/notes"],
  ] as const)
    expect(doorOf(method, path)).toBeUndefined();
});
test("the door refuses only what no row would open", () => {
  const anon = { role: "anon" } as const;
  const alice = { role: "user", id: "u1", name: "alice" } as const;
  const root = { role: "admin", id: "u0", name: "root" } as const;
  expect(mayKnock(anon, "note", "list")).toBe(true);
  expect(mayKnock(anon, "note", "create")).toBe(false);
  expect(mayKnock(anon, "note", "delete")).toBe(false);
  // alice may delete a note of her own, so the door lets her ask; the action decides which.
  expect(mayKnock(alice, "note", "delete")).toBe(true);
  expect(mayKnock(alice, "audit", "list")).toBe(false);
  expect(mayKnock(root, "audit", "list")).toBe(true);
  expect(mayKnock(root, "audit", "create")).toBe(false);
});
test("a stranger is refused /api before the body is read, when the contract closes it", async () => {
  // A body past the cap: read, it would be 413. The door answers first.
  const huge = "x".repeat(128 * 1024);
  const refused = await fetch(`${base}/api/notes`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: huge,
  });
  expect(refused.status).toBe(401);
  const signedIn = await fetch(`${base}/api/notes`, {
    method: "POST",
    headers: { "content-type": "application/json", ...as("u1", "user") },
    body: huge,
  });
  expect(signedIn.status).toBe(413);
  expect(await refused.json()).toEqual({
    error: "signin_required",
    message: "Sign in first.",
  });
  expect((await fetch(`${base}/api/audit`)).status).toBe(401);
  expect((await fetch(`${base}/api/audit/1`)).status).toBe(401);
  expect(
    (await fetch(`${base}/api/audit`, { headers: as("u1", "user") })).status,
  ).toBe(403);
  // What the table opens stays open.
  expect((await fetch(`${base}/api/notes`)).status).toBe(200);
  expect((await fetch(`${base}/api/notes/0`)).status).toBe(404);
  expect((await fetch(`${base}/openapi.json`)).status).toBe(200);
});
test("the API's description is shut to strangers when the table opens them no door", () => {
  const closed = readContract(
    JSON.stringify({
      roles: {
        anon: { above: [], held: { by: "everyone" } },
        user: { above: ["anon"], held: { by: "identity", role: "user" } },
      },
      resources: {
        note: {
          api: "/api/notes",
          can: {
            create: "user",
            read: "user",
            update: "user",
            delete: "user",
            list: "user",
          },
        },
      },
    }),
  );
  if (!closed.ok) throw new Error(closed.problems.join("; "));
  expect(openToStrangers(closed.contract)).toBe(false);
  expect(openToStrangers()).toBe(true);
});
test("strangers are rationed at the API, reads too", () => {
  const db = openDb(mkdtempSync(join(tmpdir(), "app-door-rate-")));
  const knock = () =>
    door(
      db,
      new Request("http://app/api/notes"),
      new URL("http://app/api/notes"),
      { role: "anon" },
      "203.0.113.7",
    );
  const answers = Array.from({ length: STRANGERS.burst + 5 }, knock);
  expect(answers.slice(0, STRANGERS.burst).every((a) => a === undefined)).toBe(
    true,
  );
  expect(answers.at(-1)?.status).toBe(429);
  // The page itself is not the API: a stranger reading it is never rationed here.
  expect(
    door(
      db,
      new Request("http://app/"),
      new URL("http://app/"),
      { role: "anon" },
      "203.0.113.7",
    ),
  ).toBeUndefined();
  // A bucket refills.
  const t = Date.now();
  for (let i = 0; i < 25; i++) allow("k", { burst: 20, perSecond: 2 }, t);
  expect(allow("k", { burst: 20, perSecond: 2 }, t)).toBe(false);
  expect(allow("k", { burst: 20, perSecond: 2 }, t + 1000)).toBe(true);
});
@@ -0,0 +1,189 @@
/**
 * The door: what every request passes before a route sees it, and before
 * a byte of its body is read. Three checks, in order:
 *
 * 1. **Rationing.** Writes are rationed per person (per address, for a
 *    stranger), and a stranger's calls to the API are rationed too.
 * 2. **Same origin.** A write that a browser says came from another site
 *    is refused: that is another page making this person's browser act.
 * 3. **The contract.** A request under a resource's `api` is that
 *    resource's verb (see docs/CONTRACT.md in the forge: `GET api` lists,
 *    `POST api` creates, `GET|PATCH|DELETE api/<id>` read, update,
 *    delete). If the table lets this person through that door for no row
 *    at all, they are refused here — 401 for a stranger, 403 for anyone
 *    else. The action asks again, about the real row; the door only turns
 *    away who could never pass. `/openapi.json` is shut to strangers when
 *    the table opens no door to them.
 *
 * Nothing here compares roles by hand: the answer is `decide`'s, from the
 * same table the actions read. Refused writes go into the audit trail.
 */
import type { Database } from "bun:sqlite";
import { record } from "./audit.ts";
import { decide, VERBS, type Contract, type Verb } from "./can.ts";
import { actorOf, contract } from "./contract.ts";
import { publicOrigin } from "./env.ts";
import { json, text } from "./http.ts";
import type { Who } from "./who.ts";
// A browser on another site can make a person's browser POST here; it cannot
// make that request look same-origin. Browsers say where a request came from
// (Sec-Fetch-Site, or Origin); a request that names another site is refused.
// A script sends neither and is judged by its identity instead.
export const sameOrigin = (request: Request): boolean => {
  const site = request.headers.get("sec-fetch-site");
  if (site !== null) return site === "same-origin" || site === "none";
  const origin = request.headers.get("origin");
  return origin === null || origin === publicOrigin;
};
// A bucket of `burst` tokens that refills at `perSecond`. In memory, so a
// restart forgets — which is the right size for one process on one machine.
export interface Rate {
  readonly burst: number;
  readonly perSecond: number;
}
export const WRITES: Rate = { burst: 20, perSecond: 2 };
/** A stranger's API calls, reads too. Behind the forge every stranger shares one address, so this is all of them together. */
export const STRANGERS: Rate = { burst: 60, perSecond: 10 };
const buckets = new Map<string, { tokens: number; at: number }>();
export function allow(
  key: string,
  rate: Rate = WRITES,
  now = Date.now(),
): boolean {
  const bucket = buckets.get(key) ?? { tokens: rate.burst, at: now };
  bucket.tokens = Math.min(
    rate.burst,
    bucket.tokens + ((now - bucket.at) / 1000) * rate.perSecond,
  );
  bucket.at = now;
  buckets.set(key, bucket);
  if (buckets.size > 10_000)
    for (const [k, b] of buckets) if (now - b.at > 60_000) buckets.delete(k);
  if (bucket.tokens < 1) return false;
  bucket.tokens -= 1;
  return true;
}
const ROW_VERB: Readonly<Record<string, Verb>> = {
  GET: "read",
  PATCH: "update",
  DELETE: "delete",
};
const SET_VERB: Readonly<Record<string, Verb>> = {
  GET: "list",
  POST: "create",
};
/** The resource and verb a request is, by the contract's `api` paths; undefined for any other path. */
export function doorOf(
  method: string,
  pathname: string,
  table: Contract = contract,
): { resource: string; verb: Verb } | undefined {
  for (const [resource, { api }] of Object.entries(table.resources)) {
    if (api === undefined) continue;
    if (pathname === api) {
      const verb = SET_VERB[method];
      return verb === undefined ? undefined : { resource, verb };
    }
    const rest = pathname.startsWith(`${api}/`)
      ? pathname.slice(api.length + 1)
      : undefined;
    if (rest !== undefined && rest !== "" && !rest.includes("/")) {
      const verb = ROW_VERB[method];
      return verb === undefined ? undefined : { resource, verb };
    }
  }
  return undefined;
}
/**
 * Could `who` pass this door for any row at all? The door asks about a row
 * that names them in every column a role is held by — the best row they
 * could hope for — so it refuses only what no row would open.
 */
export function mayKnock(
  who: Who,
  resource: string,
  verb: Verb,
  table: Contract = contract,
): boolean {
  const actor = actorOf(who);
  const columns = Object.values(table.roles).flatMap((role) =>
    role.held.by === "row" ? [role.held.column] : [],
  );
  const best =
    verb === "list" || verb === "create" || actor.id === null
      ? undefined
      : Object.fromEntries(columns.map((column) => [column, actor.id]));
  return decide(table, resource, verb, actor, best) !== "no";
}
/** Does the table open any door with an `api` to a stranger? Then the API's description is theirs to read. */
export const openToStrangers = (table: Contract = contract): boolean =>
  Object.entries(table.resources).some(
    ([resource, { api }]) =>
      api !== undefined &&
      VERBS.some((verb) => mayKnock({ role: "anon" }, resource, verb, table)),
  );
const describedToStrangers = openToStrangers();
/**
 * The door. `undefined` lets the request through to its route; a response
 * is the refusal. `from` is the caller's address, for rationing a stranger.
 */
export function door(
  db: Database,
  request: Request,
  url: URL,
  who: Who,
  from: string,
): Response | undefined {
  const method = request.method === "HEAD" ? "GET" : request.method;
  const writing = method !== "GET";
  const stranger = who.role === "anon";
  const api =
    url.pathname.startsWith("/api/") ||
    url.pathname === "/mcp" ||
    url.pathname === "/openapi.json";
  const key = stranger ? `ip:${from}` : `user:${who.id}`;
  if (writing && !allow(key)) return text("too many requests", 429);
  if (stranger && api && !allow(`api:${from}`, STRANGERS))
    return text("too many requests", 429);
  const found = doorOf(method, url.pathname);
  if (writing && !sameOrigin(request)) {
    record(db, {
      who,
      resource: found?.resource ?? url.pathname,
      verb: found?.verb ?? method,
      outcome: "cross_site",
    });
    return text("forbidden", 403);
  }
  const shut =
    found === undefined
      ? url.pathname === "/openapi.json" && stranger && !describedToStrangers
      : !mayKnock(who, found.resource, found.verb);
  if (!shut) return undefined;
  const outcome = stranger ? "signin_required" : "forbidden";
  if (writing && found !== undefined)
    record(db, {
      who,
      resource: found.resource,
      verb: found.verb,
      target:
        url.pathname === contract.resources[found.resource]?.api
          ? undefined
          : url.pathname.split("/").at(-1),
      outcome,
    });
  return stranger
    ? json({ error: outcome, message: "Sign in first." }, 401)
    : json({ error: outcome, message: "You may not." }, 403);
}
@@ -0,0 +1,342 @@
import { afterAll, expect, test } from "bun:test";
import { mkdtempSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { env } from "./env.ts";
import { serve } from "./server.ts";
import { sign } from "./who.ts";
const KEY = "a-key-only-the-forge-holds";
const server = serve({
  port: 0,
  dataDir: mkdtempSync(join(tmpdir(), "app-")),
  identityKey: KEY,
});
const base = `http://${server.hostname}:${server.port}`;
afterAll(() => server.stop(true));
/** The headers the forge sends for a signed-in person. */
const as = (
  id: string,
  name: string,
  role: "user" | "admin" = "user",
): Record<string, string> => {
  const identity = `${id}|${name}|${role}|${Date.now() + 60_000}`;
  return {
    "x-forge-identity": identity,
    "x-forge-signature": sign(identity, KEY),
  };
};
const alice = as("u1", "alice");
const bob = as("u2", "bob");
const root = as("u0", "root", "admin");
const jsonBody = (body: unknown): RequestInit => ({
  headers: { "content-type": "application/json" },
  body: JSON.stringify(body),
});
const api = (
  path: string,
  init: RequestInit = {},
  who: Record<string, string> = {},
) =>
  fetch(base + path, {
    ...init,
    headers: { ...(init.headers as Record<string, string>), ...who },
  });
const rpc = (message: unknown, who: Record<string, string> = {}) =>
  api("/mcp", { method: "POST", ...jsonBody(message) }, who).then(
    (r) => r.json() as Promise<any>,
  );
test("the page knows who you are and offers the right door", async () => {
  const guest = await (await fetch(base + "/")).text();
  expect(guest).toContain("<h1>");
  expect(guest).toContain("/__forge/signin?to=/");
  expect(guest).toContain('href="/__forge/report"');
  expect(guest).not.toContain('action="/notes"');
  const signed = await (await api("/", {}, alice)).text();
  expect(signed).toContain("<b>alice</b>");
  expect(signed).toContain("/__forge/signout");
  expect(signed).toContain('action="/notes"');
});
test("a form post adds as the person; a guest is sent to sign in", async () => {
  const form = new FormData();
  form.set("body", "hello from a form");
  const refused = await api("/notes", {
    method: "POST",
    body: form,
    redirect: "manual",
  });
  expect(refused.status).toBe(303);
  expect(refused.headers.get("set-cookie")).toContain("notice=");
  expect(refused.headers.get("set-cookie")).toContain("SameSite=Lax");
  expect(await (await fetch(base + "/")).text()).not.toContain(
    "hello from a form",
  );
  const posted = await api(
    "/notes",
    { method: "POST", body: form, redirect: "manual" },
    alice,
  );
  expect(posted.status).toBe(303);
  expect(posted.headers.get("set-cookie")).toBeNull();
  const page = await (await api("/", {}, alice)).text();
  expect(page).toContain("hello from a form");
  expect(page).toContain("alice ·");
});
test("the JSON API is the same actions with the same identity", async () => {
  const created = await api(
    "/api/notes",
    { method: "POST", ...jsonBody({ body: "over the api" }) },
    alice,
  );
  expect(created.status).toBe(201);
  const note = (await created.json()) as { id: number; author_name: string };
  expect(note.author_name).toBe("alice");
  const listed = (await (await fetch(base + "/api/notes")).json()) as {
    id: number;
  }[];
  expect(listed.map((n) => n.id)).toContain(note.id);
  expect(
    (await api("/api/notes", { method: "POST", ...jsonBody({ body: "anon" }) }))
      .status,
  ).toBe(401);
  expect(
    (await api(`/api/notes/${note.id}`, { method: "DELETE" }, bob)).status,
  ).toBe(403);
  expect(
    (await api(`/api/notes/${note.id}`, { method: "DELETE" }, alice)).status,
  ).toBe(200);
  expect(
    (await api(`/api/notes/${note.id}`, { method: "DELETE" }, alice)).status,
  ).toBe(404);
  expect(
    (
      await api(
        "/api/notes",
        { method: "POST", ...jsonBody({ body: "" }) },
        alice,
      )
    ).status,
  ).toBe(422);
});
test("the MCP server lists the tools and calls them as the caller", async () => {
  const hello = await rpc({
    jsonrpc: "2.0",
    id: 1,
    method: "initialize",
    params: {},
  });
  expect(hello.result.capabilities).toEqual({ tools: {} });
  const listed = await rpc({ jsonrpc: "2.0", id: 2, method: "tools/list" });
  expect(listed.result.tools.map((t: { name: string }) => t.name)).toEqual([
    "list_notes",
    "add_note",
    "delete_note",
  ]);
  const call = (name: string, args: unknown, who = {}) =>
    rpc(
      {
        jsonrpc: "2.0",
        id: 3,
        method: "tools/call",
        params: { name, arguments: args },
      },
      who,
    );
  const refused = await call("add_note", { body: "as nobody" });
  expect(refused.result.isError).toBe(true);
  const added = await call("add_note", { body: "over mcp" }, root);
  expect(added.result.isError).toBeUndefined();
  const note = JSON.parse(added.result.content[0].text);
  expect(note.author_name).toBe("root");
  const notes = JSON.parse(
    (await call("list_notes", {})).result.content[0].text,
  );
  expect(notes.map((n: { id: number }) => n.id)).toContain(note.id);
  expect(
    (await call("delete_note", { id: note.id }, root)).result.isError,
  ).toBeUndefined();
  expect(
    (await rpc({ jsonrpc: "2.0", id: 4, method: "nothing" })).error.code,
  ).toBe(-32601);
  const notified = await api("/mcp", {
    method: "POST",
    ...jsonBody({ jsonrpc: "2.0", method: "notifications/initialized" }),
  });
  expect(notified.status).toBe(202);
});
test("a change is on the event stream, and a late client hears what it missed", async () => {
  const stream = await fetch(base + "/events");
  expect(stream.headers.get("content-type")).toBe("text/event-stream");
  const reader = stream.body!.getReader();
  const next = async (): Promise<{ id: string; type: string }> => {
    let buffer = "";
    for (;;) {
      const { value } = await reader.read();
      buffer += new TextDecoder().decode(value);
      const frame = /id: (\d+)\ndata: (.*)\n\n/.exec(buffer);
      if (frame) return { id: frame[1]!, type: JSON.parse(frame[2]!).type };
    }
  };
  await api(
    "/api/notes",
    { method: "POST", ...jsonBody({ body: "live" }) },
    alice,
  );
  const heard = await next();
  expect(heard.type).toBe("note.added");
  await reader.cancel();
  const late = await fetch(base + "/events", {
    headers: { "last-event-id": String(Number(heard.id) - 1) },
  });
  const replay = new TextDecoder().decode(
    (await late.body!.getReader().read()).value,
  );
  expect(replay).toContain(`id: ${heard.id}\n`);
  expect(replay).toContain("note.added");
});
test("writes are rationed per person", async () => {
  const flood = as("u9", "flood");
  const answers = await Promise.all(
    Array.from({ length: 40 }, () =>
      api(
        "/api/notes",
        { method: "POST", ...jsonBody({ body: "again" }) },
        flood,
      ),
    ),
  );
  const codes = answers.map((r) => r.status);
  expect(codes).toContain(201);
  expect(codes).toContain(429);
});
test("stands on the security floor", async () => {
  const response = await fetch(base + "/");
  expect(response.headers.get("content-security-policy")).toContain(
    "default-src 'self'",
  );
  expect(response.headers.get("x-content-type-options")).toBe("nosniff");
  expect(
    (await fetch(base + "/api/notes")).headers.get("content-security-policy"),
  ).toContain("default-src");
});
test("a body is capped by the bytes read, whatever it claims", async () => {
  const response = await api(
    "/notes",
    {
      method: "POST",
      headers: { "content-type": "application/x-www-form-urlencoded" },
      body: "body=" + "x".repeat(1024 * 1024),
    },
    alice,
  );
  expect(response.status).toBe(413);
});
test("HEAD sees the app up", async () => {
  const response = await fetch(base + "/", { method: "HEAD" });
  expect(response.status).toBe(200);
  expect(await response.text()).toBe("");
});
test("refuses a cross-site post", async () => {
  const form = new FormData();
  form.set("body", "from another site");
  const posted = await api(
    "/notes",
    {
      method: "POST",
      body: form,
      redirect: "manual",
      headers: {
        origin: "https://evil.example",
        "sec-fetch-site": "cross-site",
      },
    },
    alice,
  );
  expect(posted.status).toBe(403);
});
test("static files are cached for a year when linked by content", async () => {
  const page = await (await fetch(base + "/")).text();
  const href = /href="(\/static\/app\.css\?v=[0-9a-f]{8})"/.exec(page)?.[1];
  expect(href).toBeDefined();
  const css = await fetch(base + href!);
  expect(css.headers.get("cache-control")).toContain("immutable");
  expect(
    (await fetch(base + "/static/app.css")).headers.get("cache-control"),
  ).toBe("no-cache");
  expect((await fetch(base + "/static/..%2Fpackage.json")).status).toBe(404);
});
test("/healthz says up, apart from the page", async () => {
  const response = await fetch(base + "/healthz");
  expect(response.status).toBe(200);
  expect(response.headers.get("cache-control")).toBe("no-store");
  const health = (await response.json()) as Record<string, unknown>;
  expect(health.ok).toBe(true);
  expect(health.version).toMatch(/^\d+\.\d+\.\d+/);
  expect(Number.isInteger(health.uptime)).toBe(true);
  expect((await fetch(base + "/healthz", { method: "HEAD" })).status).toBe(200);
});
test("a link to the page unfurls: description, Open Graph, a card", async () => {
  const page = await (await fetch(base + "/")).text();
  for (const meta of [
    'name="description"',
    'property="og:title"',
    'property="og:description"',
    'property="og:url"',
    'property="og:type" content="website"',
    'name="twitter:card" content="summary"',
    'name="theme-color"',
  ])
    expect([meta, page.includes(meta)]).toEqual([meta, true]);
});
test("the look is the tokens: /tokens.css is linked by content and cached for a year", async () => {
  const page = await (await fetch(base + "/")).text();
  const href = /href="(\/tokens\.css\?v=[0-9a-f]{8})"/.exec(page)?.[1];
  expect(href).toBeDefined();
  const css = await fetch(base + href!);
  expect(css.headers.get("content-type")).toContain("text/css");
  expect(css.headers.get("cache-control")).toContain("immutable");
  expect(await css.text()).toContain("--color-bg:");
  // The tokens come first, so every rule after them can use them.
  expect(page.indexOf("/tokens.css")).toBeLessThan(
    page.indexOf("/static/app.css"),
  );
});
test("what the web expects: robots.txt, and security.txt from the forge that runs us", async () => {
  // Production is read by crawlers, the API is not; anything else is a
  // draft and asks not to be indexed at all.
  const robots = await (await fetch(base + "/robots.txt")).text();
  const noindex = (await fetch(base + "/")).headers.get("x-robots-tag");
  if (env === "production") {
    expect(robots).toContain("Disallow: /api/\n");
    expect(noindex).toBeNull();
  } else {
    expect(robots).toBe("User-agent: *\nDisallow: /\n");
    expect(noindex).toBe("noindex");
  }
  const security = await fetch(base + "/.well-known/security.txt", {
    redirect: "manual",
  });
  if (process.env.FORGE_URL === undefined) expect(security.status).toBe(404);
  else {
    expect(security.status).toBe(302);
    expect(security.headers.get("location")).toBe(
      new URL("/.well-known/security.txt", process.env.FORGE_URL).toString(),
    );
  }
});
@@ -0,0 +1,90 @@
/**
 * The process the forge runs. `serve` opens the database and listens:
 * every request gets the floor (`http.ts`), an identity (`who.ts`), the
 * door (`security.ts`) and one route (`routes.ts`) — so a request from
 * another site, from someone going too fast, or from someone the contract
 * turns away is refused before a byte of it is read. Run directly, it
 * serves what the forge said; a test calls `serve` with its own.
 */
import { openDb } from "./db.ts";
import { dataDir, identityKey, title, where } from "./env.ts";
import { html, text } from "./http.ts";
import { serveSpan } from "./otel.ts";
import { match } from "./routes.ts";
import { door } from "./security.ts";
import { who } from "./who.ts";
export interface ServeOptions {
  readonly port: number;
  readonly hostname?: string | undefined;
  readonly dataDir: string;
  readonly identityKey: string;
}
export function serve(options: ServeOptions) {
  const db = openDb(options.dataDir);
  return Bun.serve({
    port: options.port,
    hostname: options.hostname ?? "127.0.0.1",
    // A connection that says nothing for a minute is dropped. The event
    // stream heartbeats every 25 seconds to stay well inside that.
    idleTimeout: 60,
    // Every request is a span (src/otel.ts), a child of the forge's: it
    // shows in the platform's traces with its route, status and timing.
    // Wrap slow work in `span("name", () => ...)` to see it there too.
    fetch: (request, server) =>
      serveSpan(request, async (span) => {
        const url = new URL(request.url);
        const me = who(request, options.identityKey);
        const refused = door(
          db,
          request,
          url,
          me,
          server.requestIP(request)?.address ?? "?",
        );
        if (refused !== undefined) return head(request, refused);
        const found = match(
          request.method === "HEAD" ? "GET" : request.method,
          url.pathname,
        );
        if (found === undefined) return text("not found", 404);
        span.set("http.route", found.route.path);
        const response = await found.route.handle({
          request,
          url,
          db,
          who: me,
          params: found.params,
        });
        return head(request, response);
      }),
    // A bug answers with the floor and nothing else: never the runtime's
    // own error page, which carries source and paths, and never without
    // the headers. The detail goes to the log, where it belongs.
    error(error) {
      // Inside the generated app, which has no forge log module.
      console.error(error);
      return html("<h1>Something went wrong</h1>", 500);
    },
  });
}
// HEAD is GET without the body: a health check sees the app up.
const head = (request: Request, response: Response): Response =>
  request.method === "HEAD"
    ? new Response(null, { status: response.status, headers: response.headers })
    : response;
if (import.meta.main) {
  const server = serve({
    port: Number(process.env.PORT ?? 8080),
    hostname: process.env.HOST,
    dataDir,
    identityKey,
  });
  console.log(
    `${title} listening on http://${server.hostname}:${server.port} (${where})`,
  );
}
@@ -0,0 +1,109 @@
/**
 * The look, compiled. `design/tokens.json` is the app's design tokens in the
 * W3C format — groups, `$value`, a `$type` a group hands down — and this
 * turns them into custom properties once, at boot: `color.bg` becomes
 * `--color-bg`. A colour's `$value` is the light theme and
 * `$extensions.mode.dark` the dark one; dark follows the system unless
 * `<html data-theme="light|dark">` decides. The page links the result as
 * `/tokens.css`, and every other stylesheet speaks only in `var(--…)`.
 *
 * Tokens that do not read are not a warning. The app does not start.
 */
import { createHash } from "node:crypto";
import { readFileSync } from "node:fs";
export interface Token {
  /** The custom property: `--color-bg`. */
  readonly name: string;
  readonly type: string;
  readonly light: string;
  readonly dark?: string;
}
const isGroup = (v: unknown): v is Record<string, unknown> =>
  typeof v === "object" && v !== null && !Array.isArray(v);
/** Every token in the tree, in order, with its type and both themes' values. */
export function flatten(
  tree: unknown,
  path: string[] = [],
  type = "",
): Token[] {
  if (!isGroup(tree))
    throw new Error(`${path.join(".") || "tokens"}: not a group`);
  const here = typeof tree.$type === "string" ? tree.$type : type;
  if ("$value" in tree) {
    const name = `--${path.join("-")}`;
    if (!/^--[a-z0-9-]+$/.test(name))
      throw new Error(`${path.join(".")}: not a name CSS can carry`);
    if (here === "") throw new Error(`${path.join(".")}: no $type`);
    const dark =
      isGroup(tree.$extensions) && isGroup(tree.$extensions.mode)
        ? tree.$extensions.mode.dark
        : undefined;
    return [
      {
        name,
        type: here,
        light: css(tree.$value, path),
        ...(dark === undefined ? {} : { dark: css(dark, path) }),
      },
    ];
  }
  return Object.entries(tree)
    .filter(([key]) => !key.startsWith("$"))
    .flatMap(([key, child]) => flatten(child, [...path, key], here));
}
// A value is a string, a number, or a font stack; nothing in it may close
// the declaration it sits in.
function css(value: unknown, path: string[]): string {
  const text = Array.isArray(value)
    ? value
        .map((f) =>
          /^[\w-]+$/.test(String(f)) ? String(f) : JSON.stringify(String(f)),
        )
        .join(", ")
    : typeof value === "string" || typeof value === "number"
      ? String(value)
      : "";
  if (text === "" || /[;{}<]/.test(text))
    throw new Error(`${path.join(".")}: $value is not a CSS value`);
  return text;
}
/** The stylesheet: every token on `:root`, the dark ones twice — for the system's choice and for the page's. */
export function compile(tokens: readonly Token[]): string {
  const block = (selector: string, lines: string[]): string =>
    `${selector} {\n${lines.map((l) => `  ${l}\n`).join("")}}\n`;
  const light = tokens.map((t) => `${t.name}: ${t.light};`);
  const dark = tokens.flatMap((t) =>
    t.dark === undefined ? [] : [`${t.name}: ${t.dark};`],
  );
  return [
    block(":root", ["color-scheme: light dark;", ...light]),
    block(':root[data-theme="light"]', ["color-scheme: light;"]),
    `@media (prefers-color-scheme: dark) {\n${block(':root:not([data-theme="light"])', dark)}}\n`,
    block(':root[data-theme="dark"]', ["color-scheme: dark;", ...dark]),
  ].join("\n");
}
export const tokens: readonly Token[] = flatten(
  JSON.parse(
    readFileSync(new URL("../design/tokens.json", import.meta.url), "utf8"),
  ),
);
export const tokensCss: string = compile(tokens);
/** `/tokens.css`, addressed by its content, so it can be cached for a year. */
export const tokensHref = `/tokens.css?v=${createHash("sha256").update(tokensCss).digest("hex").slice(0, 8)}`;
/** One token's value, for the few places a colour must be spelled out (the browser's own chrome). */
export const token = (
  name: string,
  mode: "light" | "dark" = "light",
): string => {
  const found = tokens.find((t) => t.name === `--${name}`);
  if (found === undefined) throw new Error(`no token ${name}`);
  return mode === "dark" ? (found.dark ?? found.light) : found.light;
};
@@ -0,0 +1,115 @@
/**
 * The app in a terminal. The forge runs this on a pty when someone
 * `ssh`es to the app, over the same data as the page and through the same
 * actions, as the account at the keyboard. j/k move, a adds, d removes the
 * note under the cursor, q leaves. Plain ANSI, no dependencies.
 */
import {
  addNote,
  canDelete,
  deleteNote,
  listNotes,
  type Note,
} from "./actions.ts";
import { openDb } from "./db.ts";
import { ssh, title, where } from "./env.ts";
import { whoAtTty } from "./who.ts";
const db = openDb();
const me = whoAtTty();
const esc = "\x1b[";
const dim = (s: string): string => `${esc}2m${s}${esc}0m`;
const bold = (s: string): string => `${esc}1m${s}${esc}0m`;
const out = (s: string): void => {
  process.stdout.write(s);
};
let cursor = 0;
let typing: string | undefined;
let said = "";
const notes = (): Note[] => {
  const listed = listNotes(db, me);
  return listed.ok ? listed.value : [];
};
function draw(): void {
  const rows = notes();
  const lines = [
    `${bold(title)}  ${dim(where)}  ${dim(me.role === "anon" ? "guest" : `${me.name}${me.role === "admin" ? " (admin)" : ""}`)}`,
    ssh === undefined ? "" : dim(`connect: ${ssh}`),
    "",
  ];
  if (rows.length === 0)
    lines.push(
      dim(
        me.role === "anon"
          ? "No notes yet."
          : "No notes yet. Press a to add one.",
      ),
    );
  rows.forEach((note, i) => {
    const body = i === cursor ? bold(note.body) : note.body;
    lines.push(
      `${i === cursor ? "▸" : " "} ${body}  ${dim(`${note.author_name} · ${note.created_at.slice(0, 16).replace("T", " ")}`)}`,
    );
  });
  lines.push("");
  if (typing !== undefined) lines.push(`New note: ${typing}${esc}7m ${esc}0m`);
  else if (said !== "") lines.push(said);
  else
    lines.push(
      dim(
        me.role === "anon"
          ? "j/k move · q quit · sign in with a key the forge knows to add"
          : "j/k move · a add · d delete · q quit",
      ),
    );
  out(`${esc}2J${esc}H${lines.join("\r\n")}`);
}
process.stdin.setRawMode?.(true);
process.stdin.resume();
process.stdin.setEncoding("utf8");
draw();
process.stdin.on("data", (key: string) => {
  said = "";
  if (typing !== undefined) {
    if (key === "\r") {
      const added = addNote(db, me, { body: typing });
      if (!added.ok) said = added.message;
      typing = undefined;
      cursor = 0;
    } else if (key === "\x1b") typing = undefined;
    else if (key === "\x7f") typing = typing.slice(0, -1);
    else if (key >= " ") typing += key;
    draw();
    return;
  }
  if (key === "q" || key === "\x03") {
    out(`${esc}2J${esc}H`);
    process.exit(0);
  }
  const rows = notes();
  if (key === "j" || key === "\x1b[B")
    cursor = Math.min(cursor + 1, Math.max(0, rows.length - 1));
  if (key === "k" || key === "\x1b[A") cursor = Math.max(cursor - 1, 0);
  if (key === "a") {
    if (me.role === "anon") said = "Sign in to add a note.";
    else typing = "";
  }
  if (key === "d") {
    const note = rows[cursor];
    if (note === undefined) said = "Nothing to remove.";
    else if (!canDelete(me, note))
      said = "Only the author or an admin can remove a note.";
    else {
      const removed = deleteNote(db, me, { id: note.id });
      if (!removed.ok) said = removed.message;
      cursor = Math.min(cursor, Math.max(0, rows.length - 2));
    }
  }
  draw();
});
process.stdout.on("resize", draw);
@@ -0,0 +1,59 @@
import { expect, test } from "bun:test";
import { sign, who, whoAtTty } from "./who.ts";
const KEY = "a-key-only-the-forge-holds";
const later = Date.now() + 60_000;
const request = (identity: string, signature: string): Request =>
  new Request("http://app/", {
    headers: { "x-forge-identity": identity, "x-forge-signature": signature },
  });
test("a signed identity is who it says", () => {
  const identity = `u1|alice|admin|${later}`;
  expect(who(request(identity, sign(identity, KEY)), KEY)).toEqual({
    role: "admin",
    id: "u1",
    name: "alice",
  });
});
test("a forged, tampered, expired or unsigned identity is anonymous", () => {
  const identity = `u1|alice|admin|${later}`;
  expect(who(request(identity, sign(identity, "another key")), KEY)).toEqual({
    role: "anon",
  });
  expect(
    who(request(`u1|alice|admin|${later + 1}`, sign(identity, KEY)), KEY),
  ).toEqual({ role: "anon" });
  const expired = `u1|alice|user|${Date.now() - 1}`;
  expect(who(request(expired, sign(expired, KEY)), KEY)).toEqual({
    role: "anon",
  });
  const odd = `u1|alice|owner|${later}`;
  expect(who(request(odd, sign(odd, KEY)), KEY)).toEqual({ role: "anon" });
  expect(who(new Request("http://app/"), KEY)).toEqual({ role: "anon" });
  // No key configured: nothing verifies, whoever signed it.
  expect(who(request(identity, sign(identity, KEY)), "")).toEqual({
    role: "anon",
  });
});
test("the terminal trusts its environment", () => {
  expect(whoAtTty({})).toEqual({ role: "anon" });
  expect(whoAtTty({ FORGE_APP_USER: "alice" })).toEqual({
    role: "user",
    id: "alice",
    name: "alice",
  });
  expect(
    whoAtTty({
      FORGE_APP_USER: "alice",
      FORGE_APP_USER_ID: "u1",
      FORGE_APP_USER_ROLE: "admin",
    }),
  ).toEqual({
    role: "admin",
    id: "u1",
    name: "alice",
  });
});
@@ -0,0 +1,67 @@
/**
 * Who is asking. The forge signs every request it proxies to the app:
 *
 *   x-forge-identity:  <userId>|<username>|<role>|<expiresMs>
 *   x-forge-signature: base64url(HMAC-SHA256(FORGE_APP_IDENTITY_KEY, that string))
 *
 * `role` is `user` (signed in and allowed to see this app) or `admin`
 * (allowed to write its repository). The forge strips these two headers
 * from whatever a client sends, so a signature that verifies is the only
 * trust there is: no headers, no key, a bad signature or a stamp in the
 * past all mean `anon`. Nothing here reads a cookie.
 */
import { createHmac, timingSafeEqual } from "node:crypto";
export type Who =
  | { role: "anon" }
  | { role: "user" | "admin"; id: string; name: string };
export const ANON: Who = { role: "anon" };
export function who(request: Request, key: string, now = Date.now()): Who {
  const identity = request.headers.get("x-forge-identity");
  const signature = request.headers.get("x-forge-signature");
  if (key === "" || identity === null || signature === null) return ANON;
  if (!same(sign(identity, key), signature)) return ANON;
  const parts = identity.split("|");
  if (parts.length !== 4) return ANON;
  const [id, name, role, expires] = parts as [string, string, string, string];
  if (role !== "user" && role !== "admin") return ANON;
  if (
    id === "" ||
    name === "" ||
    !/^\d+$/.test(expires) ||
    Number(expires) <= now
  )
    return ANON;
  return { role, id, name };
}
/** The signature the forge computes. Exported so a test can be the forge. */
export const sign = (identity: string, key: string): string =>
  createHmac("sha256", key).update(identity).digest("base64url");
const same = (a: string, b: string): boolean => {
  const x = Buffer.from(a);
  const y = Buffer.from(b);
  return x.length === y.length && timingSafeEqual(x, y);
};
/**
 * The person at the terminal. A tty session is started by the forge itself,
 * so its environment is trusted: `FORGE_APP_USER` is the account at the
 * keyboard (empty for a guest), `FORGE_APP_USER_ID` and `FORGE_APP_USER_ROLE`
 * say the rest when the forge knows them.
 */
export function whoAtTty(
  env: Record<string, string | undefined> = process.env,
): Who {
  const name = env.FORGE_APP_USER ?? "";
  if (name === "") return ANON;
  return {
    role: env.FORGE_APP_USER_ROLE === "admin" ? "admin" : "user",
    id: env.FORGE_APP_USER_ID ?? name,
    name,
  };
}
@@ -0,0 +1,209 @@
/* The look, in the tokens' words. Every value that is a choice — a colour, a
   space, a radius, a size — is a var(--…) from /tokens.css, which
   design/tokens.json compiles to at boot; `bun run lint:design` refuses a raw
   colour here. Light and dark are the tokens' business, not this file's. */
/* The page. */
html {
  -webkit-text-size-adjust: 100%;
  text-size-adjust: 100%;
}
body {
  margin: 0;
  background: var(--color-bg);
  color: var(--color-fg);
  font: var(--text-base) / var(--leading-body) var(--font-sans);
}
.page {
  max-width: 40rem;
  margin: 0 auto;
  padding: var(--space-5) var(--space-4) var(--space-6);
}
.head {
  display: flex;
  flex-wrap: wrap;
  justify-content: space-between;
  align-items: flex-start;
  gap: var(--space-3) var(--space-4);
  margin-bottom: var(--space-5);
}
h1 {
  margin: 0;
  font-size: var(--text-xl);
  font-weight: 650;
  letter-spacing: -0.01em;
  line-height: var(--leading-tight);
}
p {
  margin: 0;
}
a {
  color: var(--color-accent);
  text-decoration-thickness: 1px;
  text-underline-offset: 0.15em;
}
code,
.mono {
  font-family: var(--font-mono);
  font-size: var(--text-sm);
}
:focus-visible {
  outline: 2px solid var(--color-accent);
  outline-offset: 2px;
}
.muted {
  color: var(--color-muted);
}
.you {
  color: var(--color-muted);
  white-space: nowrap;
}
/* Blocks. */
.card {
  background: var(--color-surface);
  border: 1px solid var(--color-line);
  border-radius: var(--radius-md);
  padding: var(--space-4);
  margin-bottom: var(--space-5);
}
.row {
  display: flex;
  align-items: center;
  gap: var(--space-2);
}
.list {
  list-style: none;
  margin: 0;
  padding: 0;
}
.note {
  display: flex;
  justify-content: space-between;
  align-items: flex-start;
  gap: var(--space-3);
  padding: var(--space-3) 0;
  border-top: 1px solid var(--color-line);
}
.note:first-child {
  border-top: 0;
}
.note p {
  overflow-wrap: anywhere;
}
.note small {
  font-size: var(--text-sm);
}
.empty {
  padding: var(--space-6) var(--space-4);
  text-align: center;
  color: var(--color-muted);
  border: 1px dashed var(--color-line);
  border-radius: var(--radius-md);
}
footer {
  margin-top: var(--space-6);
  font-size: var(--text-sm);
  display: grid;
  gap: var(--space-1);
}
footer code {
  overflow-wrap: anywhere;
}
/* Controls: at least 44px on a side, keyboard and mouse alike. */
.input {
  flex: 1;
  min-width: 0;
  min-height: var(--size-tap);
  padding: 0 var(--space-3);
  font: inherit;
  font-size: max(16px, var(--text-base));
  color: inherit;
  background: var(--color-bg);
  border: 1px solid var(--color-line);
  border-radius: var(--radius-md);
}
.input::placeholder {
  color: var(--color-muted);
}
.button {
  min-height: var(--size-tap);
  padding: 0 var(--space-4);
  font: inherit;
  font-weight: 600;
  color: var(--color-accent-fg);
  background: var(--color-accent);
  border: 1px solid transparent;
  border-radius: var(--radius-md);
  cursor: pointer;
  white-space: nowrap;
  text-decoration: none;
  display: inline-flex;
  align-items: center;
}
.button:hover {
  filter: brightness(1.08);
}
.button-quiet {
  color: var(--color-muted);
  background: transparent;
  padding: 0 var(--space-3);
}
.button-quiet:hover {
  color: var(--color-fg);
  border-color: var(--color-line);
  filter: none;
}
.pill {
  display: inline-block;
  padding: 0.1rem 0.6rem;
  font-size: var(--text-sm);
  font-weight: 600;
  color: var(--color-muted);
  border: 1px solid var(--color-line);
  border-radius: var(--radius-pill);
}
.pill[data-env="production"] {
  color: var(--color-accent);
  border-color: currentColor;
}
/* A word from the last request, shown once, gone in a moment. */
.toast {
  position: fixed;
  left: 50%;
  bottom: var(--space-5);
  transform: translateX(-50%);
  max-width: calc(100% - 2 * var(--space-4));
  padding: var(--space-3) var(--space-4);
  color: var(--color-toast-fg);
  background: var(--color-toast-bg);
  border-radius: var(--radius-pill);
  box-shadow: 0 8px 24px var(--color-shadow);
  animation: toast 6s forwards;
}
@keyframes toast {
  0%,
  85% {
    opacity: 1;
  }
  100% {
    opacity: 0;
    visibility: hidden;
  }
}
/* Motion is a courtesy: whoever asked for less gets none. */
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
  .toast {
    animation: none;
  }
}
@@ -0,0 +1,68 @@
// The page stays current without a reload. /events is a stream of what
// changed; each event becomes `live` and `live:<type>` on `document`, and
// any element with data-live="<types>" is refetched and swapped when one of
// its types arrives — server-rendered, so the page never renders twice.
// Without this file the page is the same page, one reload behind.
let since = "";
let tries = 0;
let source;
function connect() {
  source = new EventSource(since ? `/events?since=${since}` : "/events");
  source.onopen = () => {
    if (tries > 0) refresh(); // Reconnected: whatever was missed, catch up.
    tries = 0;
  };
  source.onmessage = (message) => {
    since = message.lastEventId;
    const { type, data } = JSON.parse(message.data);
    document.dispatchEvent(new CustomEvent("live", { detail: { type, data } }));
    document.dispatchEvent(new CustomEvent(`live:${type}`, { detail: data }));
  };
  // The browser retries a dropped connection itself; a refused one it gives
  // up on, and then we try again, later each time.
  source.onerror = () => {
    if (source.readyState !== EventSource.CLOSED) return;
    source.close();
    setTimeout(connect, Math.min(30_000, 1000 * 2 ** tries++));
  };
}
let refreshing = false;
let again = false;
async function refresh(types) {
  const regions = [...document.querySelectorAll("[data-live]")].filter(
    (el) =>
      types === undefined ||
      el.dataset.live.split(" ").some((t) => types.includes(t)),
  );
  if (regions.length === 0) return;
  if (refreshing) {
    again = true;
    return;
  }
  refreshing = true;
  try {
    const response = await fetch(location.href, {
      headers: { accept: "text/html" },
    });
    const fresh = new DOMParser().parseFromString(
      await response.text(),
      "text/html",
    );
    for (const el of regions) {
      const next = fresh.getElementById(el.id);
      if (next) el.replaceWith(next);
    }
  } finally {
    refreshing = false;
    if (again) {
      again = false;
      refresh();
    }
  }
}
document.addEventListener("live", (event) => refresh([event.detail.type]));
connect();
		@@ -0,0 +1,131 @@
	1	# Working on this app
	2
	3	You are one of the crew on this repository. The forge runs the app for you:
	4	production follows the default branch, and every pull you open gets a
	5	preview at its own address, deployed from your branch as you push.
	6
	7	## The rules
	8
	9	- Work on the branch you were given. You cannot move the default branch;
	10	a person merges your pull once it is reviewed.
	11	- Keep state under `FORGE_APP_DATA`. Never write elsewhere at runtime.
	12	- Run `bun test` before you push. `forge.json`'s `app.test` runs it beside
	13	the app on every deploy, not before it: the preview comes up the moment
	14	the app answers and says `live`, or `serving · tests failed` the moment
	15	the suite disagrees. Every behaviour you add gets a test that would fail
	16	without it.
	17	- `src/tty.ts` is the app's terminal. The exact command that reaches it is
	18	`FORGE_APP_SSH` at runtime; print that verbatim wherever the app tells
	19	people how to connect. What a person can do on the page they can do here,
	20	and nothing more: the terminal gates its reads and writes exactly as the
	21	page does (`FORGE_APP_USER_ROLE` is the forge's word on who is there), and a
	22	write made there reaches web viewers live like any other.
	23	- Keep it dependency-free unless a dependency is clearly worth it, and say
	24	why in the pull. A dependency is code you now maintain.
	25	- When you are done, push and stop. Your last message becomes the pull's
	26	description: say what changed, what you chose not to do, and what to look
	27	at in the preview.
	28
	29	## The shape
	30
	31	One implementation, many doors. Every operation is a function in
	32	`src/actions.ts` — `(db, who, input)` in, data or a named failure out — and
	33	the page (`src/routes.ts`, `src/page.ts`), the JSON API (`src/routes.ts`),
	34	the MCP server (`src/mcp.ts`) and the terminal (`src/tty.ts`) call it. A
	35	door reads its wire format and shapes the answer; it decides nothing. A
	36	rule in an action holds at every door at once; a rule anywhere else is a
	37	bug waiting for the door you forgot.
	38
	39	Identity comes from the forge (`src/who.ts`): `anon`, `user` or `admin`,
	40	verified by signature, never by a cookie the app invents.
	41
	42	Every request passes the door (`src/security.ts`) before a route sees it:
	43	writes are rationed, a write from another site is refused, and a request
	44	under a resource's `api` path is refused — before its body is read — when
	45	the table lets that person through that door for no row at all. The door
	46	asks the same table the actions do; it never compares roles by hand, and
	47	the action still decides about the real row. Do not route around it.
	48
	49	Every change is written down. An action that creates, updates or deletes
	50	returns through `audited` (`src/actions.ts`), which appends a row to the
	51	`audit` table — who, the resource and verb, the row, when, and whether
	52	they were let — refused attempts included; the door records the writes it
	53	turns away. Admins read it at `GET /api/audit` (the `audit` resource in
	54	`contract.json`). Recording never fails a request: a row that cannot be
	55	written is a log line.
	56
	57	Who may do what is a table, not code: `contract.json`. It declares the
	58	roles — each names the roles below it, and how it is held: by everyone, by
	59	the identity the forge signed, or by a row's column naming the person — and,
	60	for every resource, the least role each of create, read, update, delete and
	61	list needs. An action asks `permit(who, resource, verb, row)`
	62	(`src/contract.ts`) and obeys the answer; it never compares `who.role`
	63	itself. `src/can.ts` is the forge's evaluator, carried verbatim: do not
	64	edit it. `src/contract.test.ts` acts as every identity at every door and
	65	fails when a door and the table disagree.
	66
	67	A new kind of person is a new role in the table, under an existing one. A
	68	change to a cell is a change of policy: say so in the pull's description.
	69	A cell loosened — anything an identity could not do before that it can
	70	after — is a wall: the forge shows the pull to a person and never lands it
	71	on its own. Do not loosen a cell unless the issue asks for exactly that;
	72	prefer a new role under an existing one, or a new resource, to widening a
	73	door that was decided.
	74
	75	To add a concept:
	76
	77	- An action — a function in `src/actions.ts` that asks `permit`, its
	78	resource's row in `contract.json`, its door in `src/contract.test.ts`,
	79	and a test in `src/actions.test.ts` for what the table cannot say.
	80	- A migration — append to `migrations` in `src/db.ts`. Never edit one
	81	that has run. `bun run src/db.ts --check` shows the version.
	82	- A page — a row in `src/routes.ts` and a function in `src/page.ts`.
	83	With a second page, move them under `src/pages/` and keep one `layout`.
	84	- An API route — a row in `src/routes.ts` that calls the action and
	85	answers with `answer(...)`; the status follows the failure. Give it an
	86	`api` entry beside it (a sentence, the body and answer as JSON Schema)
	87	and run `bun run contract:emit`: `contract/openapi.json` is committed,
	88	served at `/openapi.json`, and `bun test` fails while it is stale. A
	89	resource's routes live under the `api` path its `contract.json` entry
	90	names, so the door and the forge's probe find them.
	91	- A tool — an entry in `tools` in `src/mcp.ts`: a name, one sentence,
	92	a JSON schema, the action.
	93	- A terminal command — a key in `src/tty.ts` that calls the action and
	94	reports on the status line.
	95	- Something live — `emit(type, data)` in the action, and
	96	`data-live="<types>"` on the region of the page that shows it.
	97	- A colour, a space, a size — a token in `design/tokens.json` (a
	98	colour needs its dark value in `$extensions.mode.dark`), used as
	99	`var(--…)`. `bun run lint:design` refuses a raw `#hex`, `rgb(` or
	100	`hsl(` anywhere in `src/` or `static/`, and a `var(--…)` that names no
	101	token; `src/design.test.ts` runs it, and holds every pair of colours a
	102	person reads to 4.5:1 in both themes.
	103
	104	## The bar
	105
	106	- Security: every input is validated at the boundary and every output is
	107	escaped; every response carries the floor in `src/http.ts` (keep it,
	108	extend it); a POST that is not same-origin is refused; writes are
	109	rationed per person; secrets come from the environment (Settings → App →
	110	Environment), never the repository; no `eval`, no shell built from user
	111	text. A request body is capped by the bytes actually read (`readBody`),
	112	never by a Content-Length. `HEAD` answers like `GET`. A private thing
	113	needs an identity from `who`, and a cookie the app sets itself is
	114	`HttpOnly; SameSite=Lax`.
	115	- Speed: the first paint is server-rendered HTML; JavaScript is small, in
	116	`static/`, linked by content (`asset()`) and cached for a year; no
	117	layout shift; what changes arrives over `/events`, never by polling;
	118	work that can wait is done after the response.
	119	- A phone is a first-class client: the page works at 360px wide with no
	120	horizontal scroll, every control is at least 44px on a side
	121	(`--size-tap`), an input's text is never below 16px (a phone zooms into
	122	a smaller one), focus is always visible, whoever asked for less motion
	123	gets none, and the keyboard reaches everything a mouse does.
	124	- Beauty is the tokens': light and dark both, from one file. A new page
	125	uses `layout`, which carries the tokens, the description and the Open
	126	Graph and card metadata a shared link unfurls with — pass the page's
	127	path so `og:url` is its own.
	128	- Finish: the app boots, `/healthz` answers `{ ok, version, uptime }`
	129	(the forge polls it; keep it cheap and apart from the page), `/`
	130	answers, `bun test` is green, the README says how to use it and what is
	131	real versus simulated, `forge.json` says how to run it.
		@@ -0,0 +1,125 @@
	1	# glyph
	2
	3	Type a prompt, get SVG logos and icons drawn by Claude; preview in your theme, copy or download.
	4
	5	This is an app: the forge runs it. Production follows the default branch;
	6	every open pull gets a preview at its own address with its own copy of the
	7	data. Everything the app keeps lives under `FORGE_APP_DATA`, which is what
	8	makes "production data" and "preview data" two different things.
	9
	10	```sh
	11	PORT=8080 FORGE_APP_DATA=./data bun run src/server.ts # run it here
	12	bun test # what `forge.json`'s app.test runs on every push
	13	FORGE_APP_DATA=./data bun run src/tty.ts # the terminal
	14	FORGE_APP_DATA=./data bun run src/db.ts --check # schema version, integrity
	15	bun run lint:design # no colour but the tokens'
	16	bun run contract:emit # rewrite contract/openapi.json from the routes
	17	```
	18
	19	`app.test` in `forge.json` runs beside `app.run` in every deploy, not before
	20	it: the preview comes up the moment the app answers, and says `live`, or
	21	`serving · tests failed` the moment the suite disagrees.
	22
	23	## The shape
	24
	25	One implementation, many doors. `src/actions.ts` is every operation as a
	26	plain function — `(db, who, input)` in, data or a named failure out — and
	27	the page, the JSON API, the MCP server and the terminal all call it and
	28	decide nothing themselves. `AGENTS.md` says how to add to it.
	29
	30	\| file \| what it is \|
	31	\| ---------------------------------- \| -------------------------------------------------------------- \|
	32	\| `src/actions.ts` \| list, add, delete; the audit trail, read \|
	33	\| `contract.json` \| who may do what: roles, and the least role each verb needs \|
	34	\| `src/contract.ts`, `src/can.ts` \| the table, read at boot; the forge's evaluator, verbatim \|
	35	\| `src/security.ts` \| the door: rationing, same origin, the table before the body \|
	36	\| `src/audit.ts` \| every change and every refused one, as a row \|
	37	\| `src/who.ts` \| who is asking, from the forge's signed headers \|
	38	\| `src/db.ts` \| SQLite under `FORGE_APP_DATA`, WAL, forward-only migrations \|
	39	\| `src/live.ts` \| the in-process bus and `GET /events` \|
	40	\| `src/mcp.ts` \| the actions as MCP tools at `POST /mcp` \|
	41	\| `src/routes.ts` \| every path, in one table, each API route described beside it \|
	42	\| `src/openapi.ts` \| the routes as OpenAPI; committed at `contract/openapi.json` \|
	43	\| `src/page.ts` \| the HTML, rendered on the server, with its share metadata \|
	44	\| `design/tokens.json`, `src/tokens.ts` \| the look as data, light and dark; compiled to `/tokens.css` \|
	45	\| `src/http.ts` \| the floor: headers, body cap, files \|
	46	\| `src/server.ts` \| boot: open the database, serve \|
	47	\| `src/tty.ts` \| the terminal, over the same actions \|
	48	\| `src/env.ts` \| what the forge told this process \|
	49	\| `static/app.css`, `static/live.js` \| the look in the tokens' words, and the list that stays current \|
	50
	51	## What every app stands on
	52
	53	- The door. Before a route sees a request, `src/security.ts` rations
	54	writes (and a stranger's API calls), refuses a write from another site,
	55	and turns away — before the body is read — anyone the table lets through
	56	a resource's door for no row at all: 401 for a stranger, 403 for anyone
	57	else. The action still decides about the real row.
	58	- The audit trail. Every change, and every change refused, is a row:
	59	who, which resource and verb, which row, when, and whether they were
	60	let. Admins read it at `GET /api/audit`. A row that cannot be written
	61	is a log line, never a failed request.
	62	- The API, described. `GET /openapi.json` is `contract/openapi.json`,
	63	written from the routes by `bun run contract:emit`; each operation names
	64	its cell of the table (`x-contract`). `bun test` fails while it is stale.
	65	- Up, or not. `GET /healthz` answers `{ ok, version, uptime }`; the
	66	forge waits on it before it sends anyone to a deploy.
	67	- The look. `design/tokens.json` holds every colour, space and size,
	68	light and dark; nothing else spells out a colour (`bun run lint:design`),
	69	and every pair a person reads meets 4.5:1 in both themes.
	70	- The open web. A shared link unfurls (description, Open Graph, a
	71	card); `/robots.txt` keeps crawlers to the page, and out of previews
	72	entirely; `/.well-known/security.txt` sends a reporter to the forge
	73	that runs the app.
	74
	75	## Who you are
	76
	77	The forge says who is asking on every request it proxies, and the app
	78	verifies the signature (`src/who.ts`); nothing else is trusted. Three tiers:
	79
	80	- anon — anyone. Reads.
	81	- user — signed in to the forge and able to see this app. Adds notes, as
	82	themselves, and removes their own.
	83	- admin — able to write this repository. Removes any note.
	84
	85	"Sign in" is `/__forge/signin?to=<path>` and "Sign out" is
	86	`/__forge/signout`; the forge answers both on the app's own host, and
	87	`/__forge/report` too: it sends anyone, with no account, to report a
	88	problem on this app's repository, if that repository is public.
	89
	90	## Any interface
	91
	92	The same actions, the same rules, at every door. A script is the person
	93	whose forge grant it carries; a bare script is anonymous.
	94
	95	```sh
	96	curl https://<app>/api/notes
	97	curl -X POST https://<app>/api/notes -H 'content-type: application/json' -d '{"body":"hi"}'
	98	curl -X DELETE https://<app>/api/notes/1
	99	```
	100
	101	As an MCP server, for Claude Code or Claude Desktop — `list_notes`,
	102	`add_note`, `delete_note`:
	103
	104	```sh
	105	claude mcp add --transport http __TITLE__ https://<app>/mcp
	106	```
	107
	108	```json
	109	{
	110	"mcpServers": { "__TITLE__": { "type": "http", "url": "https://<app>/mcp" } }
	111	}
	112	```
	113
	114	The page stays current over `/events`: a note someone else adds or removes
	115	appears without a reload. Without JavaScript it is the same page, one
	116	reload behind.
	117
	118	The terminal opens with the exact command in `FORGE_APP_SSH` when the app
	119	runs (`ssh -p 2222 <name>@<forge>` — the app is the login name, the forge
	120	the host; `<name>--<pull>@<forge>` for a preview's). It is `src/tty.ts` on
	121	a real pty over the same data, as the account at the keyboard.
	122
	123	The forge sets `PORT`, `FORGE_APP_DATA`, `FORGE_APP_ENV` (`production` or
	124	`preview`), `FORGE_APP_URL`, `FORGE_APP_COMMIT`, `FORGE_APP_SSH` and
	125	`FORGE_APP_IDENTITY_KEY` when it starts the app. `forge.json` says how.
		@@ -0,0 +1,30 @@
	1	{
	2	"roles": {
	3	"anon": { "above": [], "held": { "by": "everyone" } },
	4	"user": { "above": ["anon"], "held": { "by": "identity", "role": "user" } },
	5	"author": { "above": ["user"], "held": { "by": "row", "column": "author_id" } },
	6	"admin": { "above": ["author"], "held": { "by": "identity", "role": "admin" } }
	7	},
	8	"resources": {
	9	"note": {
	10	"api": "/api/notes",
	11	"can": {
	12	"create": "user",
	13	"read": "anon",
	14	"update": "author",
	15	"delete": "author",
	16	"list": "anon"
	17	}
	18	},
	19	"audit": {
	20	"api": "/api/audit",
	21	"can": {
	22	"create": "nobody",
	23	"read": "admin",
	24	"update": "nobody",
	25	"delete": "nobody",
	26	"list": "admin"
	27	}
	28	}
	29	}
	30	}
		@@ -0,0 +1,578 @@
	1	{
	2	"openapi": "3.1.0",
	3	"info": {
	4	"title": "glyph",
	5	"version": "0.1.0",
	6	"description": "Type a prompt, get SVG logos and icons drawn by Claude; preview in your theme, copy or download."
	7	},
	8	"paths": {
	9	"/api/notes": {
	10	"get": {
	11	"summary": "The notes, newest first.",
	12	"operationId": "getApiNotes",
	13	"parameters": [
	14	{
	15	"name": "limit",
	16	"in": "query",
	17	"schema": {
	18	"type": "integer",
	19	"minimum": 1,
	20	"maximum": 500,
	21	"default": 100
	22	}
	23	}
	24	],
	25	"responses": {
	26	"200": {
	27	"description": "The notes, newest first.",
	28	"content": {
	29	"application/json": {
	30	"schema": {
	31	"type": "array",
	32	"items": {
	33	"$ref": "#/components/schemas/Note"
	34	}
	35	}
	36	}
	37	}
	38	},
	39	"default": {
	40	"description": "{ error, message }: why not",
	41	"content": {
	42	"application/json": {
	43	"schema": {
	44	"$ref": "#/components/schemas/Error"
	45	}
	46	}
	47	}
	48	}
	49	},
	50	"x-contract": {
	51	"resource": "note",
	52	"verb": "list",
	53	"least": "anon"
	54	}
	55	},
	56	"post": {
	57	"summary": "Add a note as the person asking.",
	58	"operationId": "postApiNotes",
	59	"requestBody": {
	60	"required": true,
	61	"content": {
	62	"application/json": {
	63	"schema": {
	64	"type": "object",
	65	"properties": {
	66	"body": {
	67	"type": "string",
	68	"minLength": 1,
	69	"maxLength": 500
	70	}
	71	},
	72	"required": [
	73	"body"
	74	]
	75	}
	76	}
	77	}
	78	},
	79	"responses": {
	80	"201": {
	81	"description": "Add a note as the person asking.",
	82	"content": {
	83	"application/json": {
	84	"schema": {
	85	"$ref": "#/components/schemas/Note"
	86	}
	87	}
	88	}
	89	},
	90	"default": {
	91	"description": "{ error, message }: why not",
	92	"content": {
	93	"application/json": {
	94	"schema": {
	95	"$ref": "#/components/schemas/Error"
	96	}
	97	}
	98	}
	99	}
	100	},
	101	"x-contract": {
	102	"resource": "note",
	103	"verb": "create",
	104	"least": "user"
	105	}
	106	}
	107	},
	108	"/api/notes/{id}": {
	109	"get": {
	110	"summary": "One note.",
	111	"operationId": "getApiNotesId",
	112	"parameters": [
	113	{
	114	"name": "id",
	115	"in": "path",
	116	"required": true,
	117	"schema": {
	118	"type": "integer"
	119	}
	120	}
	121	],
	122	"responses": {
	123	"200": {
	124	"description": "One note.",
	125	"content": {
	126	"application/json": {
	127	"schema": {
	128	"$ref": "#/components/schemas/Note"
	129	}
	130	}
	131	}
	132	},
	133	"default": {
	134	"description": "{ error, message }: why not",
	135	"content": {
	136	"application/json": {
	137	"schema": {
	138	"$ref": "#/components/schemas/Error"
	139	}
	140	}
	141	}
	142	}
	143	},
	144	"x-contract": {
	145	"resource": "note",
	146	"verb": "read",
	147	"least": "anon"
	148	}
	149	},
	150	"patch": {
	151	"summary": "Change a note's words.",
	152	"operationId": "patchApiNotesId",
	153	"parameters": [
	154	{
	155	"name": "id",
	156	"in": "path",
	157	"required": true,
	158	"schema": {
	159	"type": "integer"
	160	}
	161	}
	162	],
	163	"requestBody": {
	164	"required": true,
	165	"content": {
	166	"application/json": {
	167	"schema": {
	168	"type": "object",
	169	"properties": {
	170	"body": {
	171	"type": "string",
	172	"minLength": 1,
	173	"maxLength": 500
	174	}
	175	},
	176	"required": [
	177	"body"
	178	]
	179	}
	180	}
	181	}
	182	},
	183	"responses": {
	184	"200": {
	185	"description": "Change a note's words.",
	186	"content": {
	187	"application/json": {
	188	"schema": {
	189	"$ref": "#/components/schemas/Note"
	190	}
	191	}
	192	}
	193	},
	194	"default": {
	195	"description": "{ error, message }: why not",
	196	"content": {
	197	"application/json": {
	198	"schema": {
	199	"$ref": "#/components/schemas/Error"
	200	}
	201	}
	202	}
	203	}
	204	},
	205	"x-contract": {
	206	"resource": "note",
	207	"verb": "update",
	208	"least": "author"
	209	}
	210	},
	211	"delete": {
	212	"summary": "Remove a note.",
	213	"operationId": "deleteApiNotesId",
	214	"parameters": [
	215	{
	216	"name": "id",
	217	"in": "path",
	218	"required": true,
	219	"schema": {
	220	"type": "integer"
	221	}
	222	}
	223	],
	224	"responses": {
	225	"200": {
	226	"description": "Remove a note.",
	227	"content": {
	228	"application/json": {
	229	"schema": {
	230	"type": "object",
	231	"properties": {
	232	"id": {
	233	"type": "integer"
	234	}
	235	},
	236	"required": [
	237	"id"
	238	]
	239	}
	240	}
	241	}
	242	},
	243	"default": {
	244	"description": "{ error, message }: why not",
	245	"content": {
	246	"application/json": {
	247	"schema": {
	248	"$ref": "#/components/schemas/Error"
	249	}
	250	}
	251	}
	252	}
	253	},
	254	"x-contract": {
	255	"resource": "note",
	256	"verb": "delete",
	257	"least": "author"
	258	}
	259	}
	260	},
	261	"/api/audit": {
	262	"get": {
	263	"summary": "The audit trail, newest first; `before` pages back by id.",
	264	"operationId": "getApiAudit",
	265	"parameters": [
	266	{
	267	"name": "limit",
	268	"in": "query",
	269	"schema": {
	270	"type": "integer",
	271	"minimum": 1,
	272	"maximum": 500,
	273	"default": 100
	274	}
	275	},
	276	{
	277	"name": "before",
	278	"in": "query",
	279	"schema": {
	280	"type": "integer"
	281	}
	282	}
	283	],
	284	"responses": {
	285	"200": {
	286	"description": "The audit trail, newest first; `before` pages back by id.",
	287	"content": {
	288	"application/json": {
	289	"schema": {
	290	"type": "array",
	291	"items": {
	292	"$ref": "#/components/schemas/AuditRow"
	293	}
	294	}
	295	}
	296	}
	297	},
	298	"default": {
	299	"description": "{ error, message }: why not",
	300	"content": {
	301	"application/json": {
	302	"schema": {
	303	"$ref": "#/components/schemas/Error"
	304	}
	305	}
	306	}
	307	}
	308	},
	309	"x-contract": {
	310	"resource": "audit",
	311	"verb": "list",
	312	"least": "admin"
	313	}
	314	}
	315	},
	316	"/api/audit/{id}": {
	317	"get": {
	318	"summary": "One row of the audit trail.",
	319	"operationId": "getApiAuditId",
	320	"parameters": [
	321	{
	322	"name": "id",
	323	"in": "path",
	324	"required": true,
	325	"schema": {
	326	"type": "integer"
	327	}
	328	}
	329	],
	330	"responses": {
	331	"200": {
	332	"description": "One row of the audit trail.",
	333	"content": {
	334	"application/json": {
	335	"schema": {
	336	"$ref": "#/components/schemas/AuditRow"
	337	}
	338	}
	339	}
	340	},
	341	"default": {
	342	"description": "{ error, message }: why not",
	343	"content": {
	344	"application/json": {
	345	"schema": {
	346	"$ref": "#/components/schemas/Error"
	347	}
	348	}
	349	}
	350	}
	351	},
	352	"x-contract": {
	353	"resource": "audit",
	354	"verb": "read",
	355	"least": "admin"
	356	}
	357	}
	358	},
	359	"/mcp": {
	360	"post": {
	361	"summary": "One JSON-RPC 2.0 message to the MCP server; its tools are the actions.",
	362	"operationId": "postMcp",
	363	"requestBody": {
	364	"required": true,
	365	"content": {
	366	"application/json": {
	367	"schema": {
	368	"type": "object",
	369	"properties": {
	370	"jsonrpc": {
	371	"const": "2.0"
	372	},
	373	"id": {},
	374	"method": {
	375	"type": "string"
	376	},
	377	"params": {
	378	"type": "object"
	379	}
	380	},
	381	"required": [
	382	"jsonrpc",
	383	"method"
	384	]
	385	}
	386	}
	387	}
	388	},
	389	"responses": {
	390	"200": {
	391	"description": "One JSON-RPC 2.0 message to the MCP server; its tools are the actions.",
	392	"content": {
	393	"application/json": {
	394	"schema": {
	395	"type": "object"
	396	}
	397	}
	398	}
	399	},
	400	"default": {
	401	"description": "{ error, message }: why not",
	402	"content": {
	403	"application/json": {
	404	"schema": {
	405	"$ref": "#/components/schemas/Error"
	406	}
	407	}
	408	}
	409	}
	410	}
	411	}
	412	},
	413	"/healthz": {
	414	"get": {
	415	"summary": "Whether the app is up: its version, commit, environment and seconds since it started.",
	416	"operationId": "getHealthz",
	417	"responses": {
	418	"200": {
	419	"description": "Whether the app is up: its version, commit, environment and seconds since it started.",
	420	"content": {
	421	"application/json": {
	422	"schema": {
	423	"type": "object",
	424	"properties": {
	425	"ok": {
	426	"type": "boolean"
	427	},
	428	"version": {
	429	"type": "string"
	430	},
	431	"commit": {
	432	"type": "string"
	433	},
	434	"env": {
	435	"type": "string"
	436	},
	437	"uptime": {
	438	"type": "integer"
	439	}
	440	},
	441	"required": [
	442	"ok",
	443	"version",
	444	"uptime"
	445	]
	446	}
	447	}
	448	}
	449	},
	450	"default": {
	451	"description": "{ error, message }: why not",
	452	"content": {
	453	"application/json": {
	454	"schema": {
	455	"$ref": "#/components/schemas/Error"
	456	}
	457	}
	458	}
	459	}
	460	}
	461	}
	462	}
	463	},
	464	"components": {
	465	"schemas": {
	466	"Note": {
	467	"type": "object",
	468	"properties": {
	469	"id": {
	470	"type": "integer"
	471	},
	472	"body": {
	473	"type": "string",
	474	"minLength": 1,
	475	"maxLength": 500
	476	},
	477	"author_id": {
	478	"type": "string"
	479	},
	480	"author_name": {
	481	"type": "string"
	482	},
	483	"created_at": {
	484	"type": "string",
	485	"format": "date-time"
	486	},
	487	"updated_at": {
	488	"type": "string",
	489	"format": "date-time"
	490	}
	491	},
	492	"required": [
	493	"id",
	494	"body",
	495	"author_id",
	496	"author_name",
	497	"created_at",
	498	"updated_at"
	499	]
	500	},
	501	"AuditRow": {
	502	"type": "object",
	503	"properties": {
	504	"id": {
	505	"type": "integer"
	506	},
	507	"at": {
	508	"type": "string",
	509	"format": "date-time"
	510	},
	511	"who_id": {
	512	"type": [
	513	"string",
	514	"null"
	515	]
	516	},
	517	"who_name": {
	518	"type": [
	519	"string",
	520	"null"
	521	]
	522	},
	523	"role": {
	524	"enum": [
	525	"anon",
	526	"user",
	527	"admin"
	528	]
	529	},
	530	"resource": {
	531	"type": "string"
	532	},
	533	"verb": {
	534	"type": "string"
	535	},
	536	"target": {
	537	"type": [
	538	"string",
	539	"null"
	540	]
	541	},
	542	"allowed": {
	543	"enum": [
	544	0,
	545	1
	546	]
	547	},
	548	"outcome": {
	549	"type": "string"
	550	}
	551	},
	552	"required": [
	553	"id",
	554	"at",
	555	"role",
	556	"resource",
	557	"verb",
	558	"allowed",
	559	"outcome"
	560	]
	561	},
	562	"Error": {
	563	"type": "object",
	564	"properties": {
	565	"error": {
	566	"type": "string"
	567	},
	568	"message": {
	569	"type": "string"
	570	}
	571	},
	572	"required": [
	573	"error"
	574	]
	575	}
	576	}
	577	}
	578	}
		@@ -0,0 +1,95 @@
	1	{
	2	"$description": "The look, as data (W3C design tokens). Every colour the app shows is here and nowhere else: src/tokens.ts compiles this to /tokens.css at boot, and bun run lint:design refuses a raw colour anywhere else. A colour's $value is the light theme; $extensions.mode.dark is the dark one.",
	3	"color": {
	4	"$type": "color",
	5	"bg": {
	6	"$value": "#f6f6f3",
	7	"$extensions": { "mode": { "dark": "#131312" } }
	8	},
	9	"surface": {
	10	"$value": "#ffffff",
	11	"$extensions": { "mode": { "dark": "#1d1d1b" } }
	12	},
	13	"fg": {
	14	"$value": "#1c1c1a",
	15	"$extensions": { "mode": { "dark": "#ecece7" } }
	16	},
	17	"muted": {
	18	"$value": "#6b6b65",
	19	"$extensions": { "mode": { "dark": "#9a9a93" } }
	20	},
	21	"line": {
	22	"$value": "#e3e3dd",
	23	"$extensions": { "mode": { "dark": "#2c2c29" } }
	24	},
	25	"accent": {
	26	"$value": "#2f5bea",
	27	"$extensions": { "mode": { "dark": "#7c96ff" } }
	28	},
	29	"accent-fg": {
	30	"$value": "#ffffff",
	31	"$extensions": { "mode": { "dark": "#0f1a4d" } }
	32	},
	33	"danger": {
	34	"$value": "#c2410c",
	35	"$extensions": { "mode": { "dark": "#fb923c" } }
	36	},
	37	"toast-bg": {
	38	"$value": "#1c1c1a",
	39	"$extensions": { "mode": { "dark": "#ecece7" } }
	40	},
	41	"toast-fg": {
	42	"$value": "#f6f6f3",
	43	"$extensions": { "mode": { "dark": "#131312" } }
	44	},
	45	"shadow": {
	46	"$value": "#0000002e",
	47	"$extensions": { "mode": { "dark": "#00000080" } }
	48	}
	49	},
	50	"space": {
	51	"$type": "dimension",
	52	"1": { "$value": "0.25rem" },
	53	"2": { "$value": "0.5rem" },
	54	"3": { "$value": "0.75rem" },
	55	"4": { "$value": "1rem" },
	56	"5": { "$value": "1.5rem" },
	57	"6": { "$value": "2.5rem" }
	58	},
	59	"radius": {
	60	"$type": "dimension",
	61	"md": { "$value": "10px" },
	62	"pill": { "$value": "999px" }
	63	},
	64	"size": {
	65	"$type": "dimension",
	66	"tap": {
	67	"$value": "44px",
	68	"$description": "The least a control measures on a side."
	69	}
	70	},
	71	"font": {
	72	"$type": "fontFamily",
	73	"sans": {
	74	"$value": ["system-ui", "-apple-system", "Segoe UI", "sans-serif"]
	75	},
	76	"mono": {
	77	"$value": ["ui-monospace", "SFMono-Regular", "Menlo", "monospace"]
	78	}
	79	},
	80	"text": {
	81	"$type": "dimension",
	82	"sm": { "$value": "0.875rem" },
	83	"base": {
	84	"$value": "1rem",
	85	"$description": "Never below 16px: a phone zooms into a smaller input."
	86	},
	87	"lg": { "$value": "1.125rem" },
	88	"xl": { "$value": "1.5rem" }
	89	},
	90	"leading": {
	91	"$type": "number",
	92	"body": { "$value": 1.55 },
	93	"tight": { "$value": 1.2 }
	94	}
	95	}
		@@ -0,0 +1,8 @@
	1	{
	2	"app": {
	3	"run": "bun run src/server.ts",
	4	"test": "bun test",
	5	"health": "/healthz",
	6	"tty": "bun run src/tty.ts"
	7	}
	8	}
		@@ -0,0 +1,13 @@
	1	{
	2	"name": "glyph",
	3	"version": "0.1.0",
	4	"description": "Type a prompt, get SVG logos and icons drawn by Claude; preview in your theme, copy or download.",
	5	"private": true,
	6	"type": "module",
	7	"scripts": {
	8	"start": "bun run src/server.ts",
	9	"test": "bun test",
	10	"lint:design": "bun run scripts/lint-design.ts",
	11	"contract:emit": "bun run scripts/contract-emit.ts"
	12	}
	13	}
		@@ -0,0 +1,14 @@
	1	/**
	2	* Write the API's description where git keeps it: contract/openapi.json,
	3	* from the routes' own `api` entries (src/openapi.ts). Run it after
	4	* changing a route or a cell of contract.json; the tests say when it is due.
	5	*/
	6
	7	import { mkdirSync, writeFileSync } from "node:fs";
	8	import { join } from "node:path";
	9	import { emit } from "../src/openapi.ts";
	10
	11	const dir = join(import.meta.dir, "..", "contract");
	12	mkdirSync(dir, { recursive: true });
	13	writeFileSync(join(dir, "openapi.json"), emit());
	14	console.log("wrote contract/openapi.json");
		@@ -0,0 +1,77 @@
	1	/**
	2	* Every colour comes from `design/tokens.json`. This refuses a raw one —
	3	* `#hex`, `rgb(`, `hsl(` — anywhere else the app draws from: `static/`
	4	* and `src/`, tests aside. A colour spelled out in a stylesheet is a colour
	5	* the dark theme never hears about. It refuses a `var(--…)` in a stylesheet
	6	* that names no token, too: a typo there is a page quietly unstyled.
	7	*
	8	* bun run lint:design exit 1 and one line per raw colour, or silence
	9	*/
	10
	11	import { readdirSync, readFileSync } from "node:fs";
	12	import { join } from "node:path";
	13	import { tokens } from "../src/tokens.ts";
	14
	15	const RAW =
	16	/(?<![\w&])#(?:[0-9a-f]{8}\|[0-9a-f]{6}\|[0-9a-f]{3,4})(?![\w-])\|\b(?:rgba?\|hsla?)\(/gi;
	17
	18	/** The raw colours in one file's text: `path:line: …`, one per find. */
	19	export function rawColours(path: string, text: string): string[] {
	20	return text
	21	.split("\n")
	22	.flatMap((line, i) =>
	23	[...line.matchAll(RAW)].map(
	24	(m) =>
	25	`${path}:${i + 1}: raw colour ${m[0]} — name it in design/tokens.json and use var(--…)`,
	26	),
	27	);
	28	}
	29
	30	/** The custom properties a stylesheet uses that no token defines. */
	31	export function unknownTokens(
	32	path: string,
	33	text: string,
	34	known = new Set(tokens.map((t) => t.name)),
	35	): string[] {
	36	return text
	37	.split("\n")
	38	.flatMap((line, i) =>
	39	[...line.matchAll(/var\((--[\w-]+)/g)]
	40	.filter((m) => !known.has(m[1]!))
	41	.map(
	42	(m) =>
	43	`${path}:${i + 1}: ${m[1]} is not a token in design/tokens.json`,
	44	),
	45	);
	46	}
	47
	48	/** The files the lint reads: what the page is drawn from, never the tokens themselves or the tests. */
	49	export function drawnFrom(root: string): string[] {
	50	const walk = (dir: string): string[] =>
	51	readdirSync(join(root, dir), { withFileTypes: true }).flatMap((entry) => {
	52	const path = join(dir, entry.name);
	53	if (entry.isDirectory()) return walk(path);
	54	return /\.(css\|js\|ts\|html)$/.test(entry.name) &&
	55	!/\.test\.ts$/.test(entry.name)
	56	? [path]
	57	: [];
	58	});
	59	return ["static", "src"].flatMap(walk);
	60	}
	61
	62	export function lint(root: string): string[] {
	63	return drawnFrom(root).flatMap((path) => {
	64	const text = readFileSync(join(root, path), "utf8");
	65	return [
	66	...rawColours(path, text),
	67	...(path.endsWith(".css") ? unknownTokens(path, text) : []),
	68	];
	69	});
	70	}
	71
	72	if (import.meta.main) {
	73	const problems = lint(join(import.meta.dir, ".."));
	74	// Generated app's lint CLI: stderr is its output.
	75	for (const problem of problems) console.error(problem);
	76	process.exit(problems.length === 0 ? 0 : 1);
	77	}
		@@ -0,0 +1,58 @@
	1	import { expect, test } from "bun:test";
	2	import { mkdtempSync } from "node:fs";
	3	import { tmpdir } from "node:os";
	4	import { join } from "node:path";
	5	import { addNote, deleteNote, listNotes } from "./actions.ts";
	6	import { openDb } from "./db.ts";
	7	import type { Who } from "./who.ts";
	8
	9	const db = openDb(mkdtempSync(join(tmpdir(), "app-actions-")));
	10	const anon: Who = { role: "anon" };
	11	const alice: Who = { role: "user", id: "u1", name: "alice" };
	12	const bob: Who = { role: "user", id: "u2", name: "bob" };
	13	const root: Who = { role: "admin", id: "u0", name: "root" };
	14
	15	test("anyone reads; only a signed-in person adds, as themselves", () => {
	16	expect(listNotes(db, anon)).toEqual({ ok: true, value: [] });
	17	const refused = addNote(db, anon, { body: "hello" });
	18	expect(refused.ok).toBe(false);
	19	if (!refused.ok) expect(refused.error).toBe("signin_required");
	20	const added = addNote(db, alice, { body: " hello " });
	21	expect(added.ok).toBe(true);
	22	if (!added.ok) return;
	23	expect(added.value.body).toBe("hello");
	24	expect(added.value.author_id).toBe("u1");
	25	expect(added.value.author_name).toBe("alice");
	26	const all = listNotes(db, anon);
	27	expect(all.ok && all.value.length).toBe(1);
	28	});
	29
	30	test("a note is one to five hundred characters", () => {
	31	for (const body of ["", " ", "x".repeat(501)]) {
	32	const r = addNote(db, alice, { body });
	33	expect(r.ok).toBe(false);
	34	if (!r.ok) expect(r.error).toBe("invalid");
	35	}
	36	});
	37
	38	test("only the author or an admin removes a note", () => {
	39	const mine = addNote(db, alice, { body: "mine" });
	40	if (!mine.ok) throw new Error(mine.message);
	41	const byBob = deleteNote(db, bob, { id: mine.value.id });
	42	expect(byBob.ok).toBe(false);
	43	if (!byBob.ok) expect(byBob.error).toBe("forbidden");
	44	const byAnon = deleteNote(db, anon, { id: mine.value.id });
	45	expect(byAnon.ok).toBe(false);
	46	if (!byAnon.ok) expect(byAnon.error).toBe("signin_required");
	47	expect(deleteNote(db, alice, { id: mine.value.id }).ok).toBe(true);
	48	const gone = deleteNote(db, alice, { id: mine.value.id });
	49	expect(gone.ok).toBe(false);
	50	if (!gone.ok) expect(gone.error).toBe("not_found");
	51
	52	const bobs = addNote(db, bob, { body: "bob's" });
	53	if (!bobs.ok) throw new Error(bobs.message);
	54	expect(deleteNote(db, root, { id: bobs.value.id }).ok).toBe(true);
	55	const odd = deleteNote(db, root, { id: 1.5 });
	56	expect(odd.ok).toBe(false);
	57	if (!odd.ok) expect(odd.error).toBe("invalid");
	58	});