${escapeHtml(i.name)}\n${i.description ? `

${escapeHtml(i.description)}

` : \"\"}\n${\n missing.length > 0\n ? `

⚠️ missing env: ${\n missing\n .map((k) => `${escapeHtml(k)}`)\n .join(\", \")\n }

`\n : \"\"\n }

`;\n })\n .join(\"\\n\");\n\n const who = authEnabled\n ? user\n ? `

@${escapeHtml(user)} ·\n

`\n : \"\"\n : \"\";\n\n // A single generic prompt on the anonymous public directory: no count of what\n // is hidden, just an invitation to log in for the full listing.\n const more = anonymousPublic\n ? `

`\n : \"\";\n\n return page(\n title,\n `

${escapeHtml(title)}

${who}

\n${\n visible.length === 0\n ? `

No integrations registered.

`\n : `

${items}`\n }\n${more}`,\n );\n}\n\nfunction loginPage(options: RouterOptions): Response {\n const title = options.title ?? \"Integrations\";\n const hasKey = missingEnv([\"OAUTH_STATE_ENCRYPTION_KEY\"]).length === 0;\n return page(\n title,\n `

${escapeHtml(title)}

Access is restricted to ${\n audienceDescription(options.auth)\n }.

\n${\n hasKey\n ? \"\"\n : `

⚠️ This val has no OAUTH_STATE_ENCRYPTION_KEY env var;\nlogin will fail until one is set (any random 32-byte hex string).

`\n }`,\n 401,\n );\n}\n\nfunction forbiddenPage(options: RouterOptions, user: string): Response {\n return page(\n options.title ?? \"Integrations\",\n `

403

Signed in as @${escapeHtml(user)}, but access is restricted to\n${audienceDescription(options.auth)}.

\n`,\n 403,\n );\n}\n\n// ---------------------------------------------------------------------------\n// Router\n// ---------------------------------------------------------------------------\n\n// The router-owned login path (std/oauth's fixed /auth/* mount). Surfaced to\n// flagged integrations as the login-location signal so they can render a\n// working \"log in\" link.\nconst LOGIN_PATH = \"/auth/login\";\n\n/**\n * The `users` allowlist normalized to a plain list (omitted / `auth: false` ⇒\n * `[]`). It governs only the privileged surface; the host val owner is always\n * implicitly admitted on top of whatever this contains, and `\"*\"` widens it to\n * any logged-in account. See `isAdmitted`.\n */\nfunction configuredUsers(auth: RouterAuthOptions | undefined): string[] {\n if (auth === false || auth?.users == null) return [];\n return Array.isArray(auth.users) ? auth.users : [auth.users];\n}\n\n/**\n * Whether a logged-in `user` may reach the privileged surface. Owner is always\n * implicit (`user === owner` is never refused); `\"*\"` admits anyone logged in;\n * otherwise the user must be named. Omitted / `[]` ⇒ owner-only.\n */\nfunction isAdmitted(\n user: string,\n owner: string | null,\n users: string[],\n): boolean {\n if (owner != null && user === owner) return true;\n if (users.includes(\"*\")) return true;\n return users.includes(user);\n}\n\n/**\n * Human-readable description of who may reach the privileged surface, for the\n * login and 403 pages. Owner is always implicitly included.\n */\nfunction audienceDescription(auth: RouterAuthOptions | undefined): string {\n const users = configuredUsers(auth);\n if (users.includes(\"*\")) return \"any logged-in Val Town account\";\n const named = users.filter((u) => u !== \"*\");\n const parts = [\"the val owner\", ...named.map((u) => `@${escapeHtml(u)}`)];\n return parts.map((p) => `${p}`).join(\", \");\n}\n\n// Root-absolute (single leading slash): \"/x\" yes; \"//host/x\" and full URLs no.\nconst ROOT_ABSOLUTE = /^\\/(?!\\/)/;\n\nfunction rewriteLocation(res: Response, prefix: string): Response {\n const location = res.headers.get(\"Location\");\n if (!location || !ROOT_ABSOLUTE.test(location)) return res;\n const rewritten = new Response(res.body, res);\n rewritten.headers.set(\"Location\", prefix + location);\n return rewritten;\n}\n\n/**\n * Who is logged in (`user`) and who owns the host val (`owner`), resolved\n * together. Both are Val Town handles or null. The owner is the host handle\n * from the auto-injected `VALTOWN_ENTRYPOINT`; a later ticket makes it always\n * implicitly allowlisted, but nothing consumes it yet.\n */\nexport type Identity = { user: string | null; owner: string | null };\nexport type ResolveIdentity = (req: Request) => Promise;\n\n/**\n * The route handler minus the OAuth wrapper, with identity resolution injected\n * — the single test seam. Use createRouter, which wires the real resolver.\n */\nexport function createRouteHandler(\n options: RouterOptions,\n resolveIdentity: ResolveIdentity,\n): (req: Request) => Promise {\n const seen = new Set();\n for (const i of options.integrations) {\n validateSlug(i.slug);\n if (seen.has(i.slug)) {\n throw new Error(`Duplicate integration slug \"${i.slug}\".`);\n }\n seen.add(i.slug);\n }\n\n const authEnabled = options.auth !== false;\n\n // Startup validation for a session-less (`auth: false`) router. With no\n // router-owned login every request arrives session-less, so an unflagged\n // integration — the default \"fully gated\" — has no gate to fall back on and\n // would silently receive anonymous traffic with nothing declared safe. That\n // contradiction throws here, at construction, in the same failure class as a\n // duplicate slug. The one sanctioned way to proceed knowingly is the escape\n // hatch: listing the slug in `allowUnflagged` force-mounts it and the\n // widening is logged below. The hatch is per-slug, so a *new* unflagged\n // integration added later still throws — it never becomes \"allow all\n // unflagged.\" (A gated router needs none of this: it walls unflagged\n // integrations at dispatch, so `allowUnflagged` is inert when auth is on.)\n // The host-side *narrowing* seam is named on `RouterOptions.allowUnflagged`.\n if (!authEnabled) {\n const allowUnflagged = new Set(options.allowUnflagged ?? []);\n const forceMounted: string[] = [];\n for (const i of options.integrations) {\n if (isFlagged(i)) continue;\n if (!allowUnflagged.has(i.slug)) {\n throw new Error(\n `Integration \"${i.slug}\" is unflagged on an auth:false (session-less) ` +\n `router: it would receive requests with no logged-in user and ` +\n `nothing declared safe. Either set \\`sessionLess: true\\` on the ` +\n `integration, or knowingly force-mount it by listing \"${i.slug}\" in ` +\n `the router's \\`allowUnflagged\\`.`,\n );\n }\n forceMounted.push(i.slug);\n }\n if (forceMounted.length > 0) {\n console.warn(\n `[integrations] Escape hatch: force-mounting unflagged integration(s) ` +\n `${\n forceMounted.map((s) => `\"${s}\"`).join(\", \")\n } on an auth:false router ` +\n `via \\`allowUnflagged\\`. Each receives session-less traffic with ` +\n `nothing declared safe; its own per-route authorization is the only ` +\n `line drawn.`,\n );\n }\n // A hatch entry that force-mounts nothing — a stale/typo'd slug, or one\n // naming an already-flagged integration — has no effect. Surface it so the\n // hatch stays honest (the whole point is explicit, visible widening) and a\n // typo never quietly does nothing.\n const inert = [...allowUnflagged].filter((s) => !forceMounted.includes(s));\n if (inert.length > 0) {\n console.warn(\n `[integrations] \\`allowUnflagged\\` lists slug(s) ` +\n `${inert.map((s) => `\"${s}\"`).join(\", \")} that force-mount nothing ` +\n `(no such unflagged integration on this router); the entr${\n inert.length === 1 ? \"y has\" : \"ies have\"\n } no effect.`,\n );\n }\n }\n\n const users = configuredUsers(options.auth);\n // Login-location signal: the login path when the router owns login, null\n // when it doesn't (auth off). Passed to every routed handler via ctx.\n const loginLocation = authEnabled ? LOGIN_PATH : null;\n\n // The router-owned login wall for a session-less request: the login page for\n // GET, a bounce home for non-GET (so HTML never lands in a POST response).\n const loginWall = (req: Request): Response =>\n req.method !== \"GET\"\n ? new Response(null, { status: 302, headers: { Location: \"/\" } })\n : loginPage(options);\n\n // The full gate for router-owned surface (directory, 404) and unflagged\n // integrations: anonymous hits the login wall; a logged-in user who is\n // neither the owner nor allowlisted is forbidden. Returns null when the\n // request may proceed. The allowlist governs only this privileged surface —\n // a flagged integration bypasses it entirely (below).\n const fullGate = (\n req: Request,\n user: string | null,\n owner: string | null,\n ): Response | null => {\n if (!authEnabled) return null;\n if (user == null) return loginWall(req);\n if (!isAdmitted(user, owner, users)) return forbiddenPage(options, user);\n return null;\n };\n\n return async (req: Request): Promise => {\n const url = new URL(req.url);\n\n let user: string | null = null;\n let owner: string | null = null;\n if (authEnabled) {\n const identity = await resolveIdentity(req);\n user = identity.user;\n owner = identity.owner;\n }\n\n const matched = options.integrations.find(\n (i) =>\n url.pathname === `/${i.slug}` || url.pathname.startsWith(`/${i.slug}/`),\n );\n\n if (matched) {\n const prefix = `/${matched.slug}`;\n // A flagged integration is public: the allowlist never gates its surface,\n // so it bypasses the full gate for anonymous AND logged-in visitors alike\n // (ctx.user is still passed so the integration draws its own per-route\n // line). The router never reads or strips Authorization, so a bearer\n // client's header reaches a flagged integration byte-intact.\n if (!isFlagged(matched)) {\n const gated = fullGate(req, user, owner);\n if (gated) return gated;\n }\n\n // Canonicalize /slug → /slug/ so relative URLs resolve inside the mount.\n if (url.pathname === prefix) {\n return new Response(null, {\n status: 302,\n headers: { Location: `${prefix}/${url.search}` },\n });\n }\n\n const childUrl = new URL(url);\n childUrl.pathname = url.pathname.slice(prefix.length);\n const childReq = new Request(childUrl, {\n method: req.method,\n headers: req.headers,\n // Buffered, not streamed: Request re-wrapping needs a settled body.\n body: req.method === \"GET\" || req.method === \"HEAD\"\n ? undefined\n : await req.blob(),\n });\n const res = await matched.handler(childReq, {\n user,\n prefix,\n login: loginLocation,\n });\n return rewriteLocation(res, prefix);\n }\n\n if (url.pathname === \"/\") {\n // The directory is public iff at least one integration is flagged;\n // otherwise today's login wall stands. When public it bypasses the gate —\n // the router is not an anti-enumeration boundary, so least-surprise and\n // standalone-parity decide its surface: an anonymous visitor sees only the\n // flagged integrations plus a single generic \"log in to see more\" (no name\n // or count of the private ones), and a logged-in visitor sees the full\n // listing. (Future seam: host-side narrowing could hide a flagged\n // integration from this listing — no mechanism ships in v1.)\n const anyFlagged = options.integrations.some(isFlagged);\n if (!anyFlagged) {\n const gated = fullGate(req, user, owner);\n if (gated) return gated;\n }\n const anonymousPublic = authEnabled && user == null;\n return directoryPage(options, user, authEnabled, anonymousPublic);\n }\n\n // Other router-owned surface (the 404) stays fully gated.\n const gated = fullGate(req, user, owner);\n if (gated) return gated;\n\n return page(\n \"Not found\",\n `

404

← back to the directory

`,\n 404,\n );\n };\n}\n\nasync function resolveOAuthIdentity(req: Request): Promise {\n const session = await getOAuthUserData(req);\n return {\n user: session?.user?.username ?? null,\n // Host handle from the auto-injected VALTOWN_ENTRYPOINT — resolves to the\n // host val even from an imported child module, no login needed (ADR 0004\n // spike). Read here in the resolver, never inside the handler, so tests can\n // inject a fake owner.\n owner: parseVal().username ?? null,\n };\n}\n\nexport function createRouter(\n options: RouterOptions,\n): (req: Request) => Response | Promise {\n const handler = createRouteHandler(options, resolveOAuthIdentity);\n return options.auth === false ? handler : oauthMiddleware(handler);\n}\n",[147],"4bd98d90-c906-41ac-93de-8c596c97738f","mod.ts","4795d00c-7cb8-11f1-a2c1-1607ee4eb77e",237,["D",1784047632088],4,"export {\n type CallableIntegration,\n // The OAuth-free router core with an identity resolver injected — the public\n // test seam for integration authors to exercise routed mode without a session.\n createRouteHandler,\n createRouter,\n defineIntegration,\n type Identity,\n type Integration,\n type IntegrationContext,\n type IntegrationHandler,\n type ResolveIdentity,\n type RouterAuthOptions,\n type RouterOptions,\n} from \"./router.ts\";\n",[155],"e7c0407c-34ff-4b62-a8b0-1aaca374f16f","main.ts","477921dc-7cb8-11f1-94e8-1607ee4eb77e",180,["D",1784043352057],7,"http","// This val's own consumer of its router.\nimport { blobAdmin } from \"https://esm.town/v/nbbaier/scoped-blob-viewer/mod.ts\";\nimport { issueTracker } from \"https://esm.town/v/nbbaier/val-issue-tracker/mod.ts\";\nimport { helloWorld } from \"./example/hello.ts\";\nimport { createRouter } from \"./mod.ts\";\n\nexport default createRouter({\n title: \"Integrations\",\n auth: { users: \"nbbaier\" },\n integrations: [issueTracker({}), blobAdmin({}), helloWorld()],\n});\n",[163],"ffd06021-2d59-4fdb-87e5-a6e61a690617","deno.json","525df192-7c9d-11f1-a2d0-1607ee4eb77e",254,["D",1784050565037],"{\n \"compilerOptions\": {\n \"lib\": [\n \"dom\",\n \"dom.iterable\",\n \"dom.asynciterable\",\n \"deno.ns\",\n \"deno.unstable\"\n ],\n \"noImplicitAny\": false,\n \"strict\": false,\n \"types\": [\"https://www.val.town/types/valtown.d.ts\"]\n },\n \"experimental\": {\n \"unstable-node-globals\": true,\n \"unstable-sloppy-imports\": true,\n \"unstable-temporal\": true,\n \"unstable-worker-options\": true\n },\n \"imports\": {\n \"@std/assert\": \"jsr:@std/assert@^1.0.19\"\n },\n \"lint\": {\n \"include\": [\"*.ts\", \"*.tsx\", \"example/*.ts\"],\n \"rules\": {\n \"exclude\": [\"no-explicit-any\", \"no-import-prefix\"]\n }\n },\n \"lock\": false,\n \"nodeModulesDir\": \"auto\",\n \"tasks\": {\n \"lint\": \"deno lint\",\n \"typecheck\": \"VAL_TOWN_API_KEY=test deno check --allow-import=esm.town,www.val.town,esm.sh,jsr.io main.ts mod.ts router.ts router_test.ts example/hello.ts example/hello_test.ts\",\n \"test\": \"VAL_TOWN_API_KEY=test deno test --allow-env --allow-import=esm.town,www.val.town,esm.sh,jsr.io\",\n \"check\": \"deno fmt && deno task lint && deno task typecheck && deno task test\"\n }\n}\n",[172],"8a25733f-ba84-4ed4-aafd-5dee4de1ba57","README.md","de745920-7d4f-11f1-896c-1607ee4eb77e",238,["D",1784047632109],"# integrations\n\nA contract and router for mounting reusable web apps — **integrations** — into a\nsingle Val Town val. One val, one login, one URL; many project-level tools\\\nserved underneath it.\n\n```\nhttps://you-integrations.web.val.run/ → directory page\n /issues/ → the issue tracker\n /blobs/ → the blob viewer\n /hello/ → your integration\n```\n\nThe router mounts each integration **in-process** and dispatches by path prefix\n(no per-integration redirects, no separate logins). It owns authentication,\nserves a directory page at `/`, and passes each integration a small context —\nthe logged-in user and its mount prefix. See [`docs/adr/`](docs/adr/) for the\narchitecture decisions behind this.\n\n## The pattern\n\nAn **integration** is a mountable sub-app over a Val Town scoped resource: a\nself-contained web app — UI, routes, and its own authorization — wrapped around\none val-scoped thing (a SQLite-backed domain, the blob store). The contract here\nis that shape extracted from two apps that already had it\n([`val-issue-tracker`](https://www.val.town/x/nbbaier/val-issue-tracker) and\n[`scoped-blob-viewer`](https://www.val.town/x/nbbaier/scoped-blob-viewer)).\n\nWhat makes it more than a mounted sub-router is Val Town's scoping: because\nscoped SQLite/blob bind to whichever val's runtime is **executing** the code, an\nintegration operates on its **host val's** data and identity just by being\nimported — no tokens, no config. Three properties fall out of that:\n\n- **Host-scoped, not self-scoped** — drop it into any val and it points at that\n val's storage automatically.\n- **Portable / dual-mode** — the same value runs standalone (a val's HTTP\n export) or routed (mounted at `/slug/`), thanks to relative-only links and a\n callable contract.\n- **Composable** — it keeps its own authorization but lifts authentication up to\n the host or router, so many integrations stack behind one origin and one\n login.\n\nThe closest analogies are Rails engines or Hono/Express sub-apps mounted at a\nprefix — but host-scoped, so mounting also inherits the host's data and identity\nfor free.\n\nThere are two audiences below:\n**[mounting integrations](#mounting-integrations)** if you want to run a router,\nand **[writing an integration](#writing-an-integration)** if you want to build\none.\n\n---\n\n## Mounting integrations\n\nImport the integrations you want and hand them to `createRouter`. Its return\nvalue is a plain HTTP handler — make it your val's default export.\n\n```ts\nimport { createRouter } from \"https://esm.town/v/nbbaier/integrations/mod.ts\";\nimport { issueTracker } from \"https://esm.town/v/nbbaier/val-issue-tracker/mod.ts\";\nimport { blobAdmin } from \"https://esm.town/v/nbbaier/scoped-blob-viewer/mod.ts\";\n\nexport default createRouter({\n title: \"My Tools\",\n auth: { users: \"nbbaier\" },\n integrations: [issueTracker({}), blobAdmin({})],\n});\n```\n\nEach integration is served at `//`, listed on the directory page at `/`,\nand shares the host val's scoped SQLite and blob storage. See\n[`INTEGRATIONS.md`](INTEGRATIONS.md) for the registry of known integrations and\ntheir import paths.\n\n### Auth\n\nThe router owns the OAuth gate — one login covers every integration.\n\n| `auth` value | Who gets in |\n| ----------------------------- | -------------------------------------------- |\n| _omitted_ (default) | Any logged-in Val Town account |\n| `{ users: \"alice\" }` | Only `@alice` |\n| `{ users: [\"alice\", \"bob\"] }` | Only `@alice` or `@bob` |\n| `false` | No gate — the router is open, `user` is null |\n\nWhen the gate is on, set an `OAUTH_STATE_ENCRYPTION_KEY` env var (any random\n32-byte hex string) or login will fail. The login page warns you if it's\nmissing, and the directory page badges any integration whose `requiredEnv` vars\nare unset.\n\n### Reserved paths\n\nThe router keeps `/` (the directory page) and `/auth/*` (the OAuth routes) for\nitself. Integration slugs are validated against these — see\n[reserved slugs](#reserved-slugs).\n\n---\n\n## Writing an integration\n\nAn integration is metadata plus a fetch handler. You ship an\n`(options) => Integration` **factory**; users register the factory's return\nvalue with a router, or mount it standalone as a val's HTTP export. The same\nvalue serves both modes.\n\nHere is the entire worked example ([`example/hello.ts`](example/hello.ts)) —\ncopy it to start your own. Every line is contract surface, not app logic. A\nline-by-line walkthrough lives in [`example/README.md`](example/README.md).\n\n```ts\nimport { defineIntegration } from \"https://esm.town/v/nbbaier/integrations/mod.ts\";\n\nexport interface HelloWorldOptions {\n subject?: string;\n}\n\nexport function helloWorld(options: HelloWorldOptions = {}) {\n const subject = options.subject ?? \"world\";\n return defineIntegration({\n name: \"Hello World\",\n slug: \"hello\",\n description: \"The smallest possible integration — the worked example.\",\n requiredEnv: [\"HELLO_GREETING\"],\n handler: (req, ctx) => {\n const greeting = Deno.env.get(\"HELLO_GREETING\") ?? \"Hello\";\n const who = ctx?.user ? `@${ctx.user}` : subject;\n const body = new URL(req.url).pathname === \"/about\"\n ? `

A toy integration.

back

`\n : `

${greeting}, ${who}!

about

`;\n return new Response(`${body}`, {\n headers: { \"Content-Type\": \"text/html; charset=utf-8\" },\n });\n },\n });\n}\n\nexport default helloWorld();\n```\n\nThe comments those lines used to carry now live in the walkthrough; the prose\nbelow covers the same ground for the contract as a whole.\n\n### The `Integration` contract\n\n`defineIntegration` takes one object:\n\n| Field | Type | Required | Meaning |\n| ------------- | -------------------- | -------- | ----------------------------------------------------------- |\n| `name` | `string` | yes | Human-readable label shown on the directory page. |\n| `slug` | `string` | yes | URL-safe id; the integration is served at `//`. |\n| `description` | `string` | no | Shown under the name on the directory page. |\n| `requiredEnv` | `string[]` | no | Env vars this integration reads; unset ones badge the page. |\n| `handler` | `IntegrationHandler` | yes | The fetch handler: `(req, ctx?) => Response \\| Promise<…>`. |\n\n### The factory convention\n\nExport a function, not a bare `Integration`. Configuration goes in the closure,\nnever on the object — that keeps the `Integration` type free of app-specific\noptions and lets users write `myFactory({ ...config })`. If your integration\nneeds no config, take an options bag anyway (`options = {}`) so the calling\nconvention stays uniform.\n\n### The handler and its context\n\n```ts\ntype IntegrationHandler = (\n req: Request,\n ctx?: IntegrationContext,\n) => Response | Promise;\n\ninterface IntegrationContext {\n user: string | null; // Val Town username from the router's OAuth; null if the gate is off.\n prefix: string; // Mount prefix, e.g. \"/hello\".\n}\n```\n\n`ctx` is **present when routed, absent when standalone** — its absence is how\nyour handler knows no router is in front of it. `ctx?.user` is the dual-mode\nidiom. If you use Hono, `ctx` arrives as `c.env`.\n\n### Dual-mode: one factory, two mounts\n\n`defineIntegration` returns a **callable integration** — the `Integration`\nobject made directly callable as an HTTP handler\n(`CallableIntegration = Integration & IntegrationHandler`). So the same return\nvalue works both ways with no branching:\n\n```ts\nexport default helloWorld(); // standalone HTTP val\ncreateRouter({ integrations: [helloWorld()] }); // routed\n```\n\nThe platform calls the standalone export with no `ctx`, which is exactly the \"no\nrouter\" signal the contract already defines. See\n[ADR 0003](docs/adr/0003-callable-integrations.md).\n\n### Prefix rules: keep links relative\n\nThe router mounts you under `//`. To survive that, follow one rule:\n\n- **Use relative URLs** (`href=\"about\"`, `href=\"./\"`) — never root-absolute\n (`href=\"/about\"`). Relative links resolve inside the mount prefix when routed\n and at the root when standalone, with zero branching. The router canonicalizes\n `/` → `//` so relative resolution always has a trailing-slash\n base.\n- **Redirects are handled for you.** The router rewrites root-absolute\n `Location` headers, prepending your prefix — so the redirect-after-POST idiom\n `c.redirect(\"/?ok=1\")` becomes `//?ok=1` automatically. HTML bodies are\n never rewritten; that stays your job (relative links). See\n [ADR 0002](docs/adr/0002-location-header-rewriting.md).\n- **To reach outside your mount** (the router root, a sibling), use `ctx.prefix`\n or a full absolute URL — a bare `/...` won't get there by design.\n\nTwo real integrations (`val-issue-tracker`, `scoped-blob-viewer`) migrated onto\nthis with zero contract fights. If a rule ever needs a wall of caveats in your\napp, that's a bug in the contract — open an issue rather than working around it.\n\n### `requiredEnv`\n\nList the env vars you read. The router checks them at request time and badges\nthe directory page for any that are unset — it never blocks the integration.\nRead the vars with `Deno.env.get()` **at request time**, never at import time\n(import-time reads run before the val's env is available and break standalone\nmounting).\n\n### Reserved slugs\n\n`createRouter` and `defineIntegration` reject invalid or reserved slugs by\nthrowing at construction (fail fast, not at request time):\n\n- Must match `^[a-z0-9-]+$`.\n- `auth` is reserved (std/oauth owns `/auth/*`).\n- The `_`-prefixed namespace is reserved forever for router-owned surface.\n- Slugs must be unique within a router.\n\n### Permission composition\n\nThe router **authenticates**; your integration **authorizes**. Read `ctx.user`\nand decide what that user may do:\n\n- `ctx.user` is a username when the router's gate let them in.\n- `ctx.user` is `null` when the router is ungated (`auth: false`) — meaning no\n login exists at all, so don't redirect to one; degrade to a read-only or\n public view.\n- If your integration has its own credential check (e.g. a bearer-token API), it\n stacks _behind_ the router's gate when the router has one. A headless client\n that can't hold an OAuth session should target your **standalone** or an\n ungated mount. (v1 accepts this stacking deliberately — see the map's\n out-of-scope notes.)\n\n### Testing without OAuth\n\n`createRouteHandler` is the public test seam: the router core with identity\nresolution injected, so you can exercise routed mode without a real session. The\nresolver returns `{ user, owner }` — who is logged in and who owns the host val.\n\n```ts\nimport { createRouteHandler } from \"https://esm.town/v/nbbaier/integrations/mod.ts\";\n\nconst handler = createRouteHandler(\n { integrations: [helloWorld()], auth: false },\n // inject the \"logged-in\" user (and, if it matters, the host owner)\n () => Promise.resolve({ user: \"alice\", owner: null }),\n);\nconst res = await handler(new Request(\"https://example.com/hello/about\"));\n```\n\nYou can also call your integration's `.handler(req, ctx)` directly with a\nhand-built `ctx` to test dispatch in isolation. See\n[`example/hello_test.ts`](example/hello_test.ts).\n\n---\n\n## API reference\n\nAll exports come from `mod.ts`:\n\n| Export | Kind | Purpose |\n| --------------------- | -------- | ------------------------------------------------------------------- |\n| `createRouter` | function | Build the HTTP handler that mounts integrations (users). |\n| `defineIntegration` | function | Wrap an `Integration` into a dual-mode callable (authors). |\n| `createRouteHandler` | function | OAuth-free router core with injected identity resolver (test seam). |\n| `Integration` | type | The contract object: `name`, `slug`, `handler`, … |\n| `CallableIntegration` | type | `Integration & IntegrationHandler` — the dual-mode value. |\n| `IntegrationHandler` | type | `(req, ctx?) => Response \\| Promise`. |\n| `IntegrationContext` | type | `{ user: string \\| null; prefix: string }`. |\n| `RouterOptions` | type | Argument to `createRouter`. |\n| `RouterAuthOptions` | type | The `auth` field: `{ users?: string \\| string[] } \\| false`. |\n\n## Publishing and versioning\n\nImport the contract from `mod.ts` **unpinned** for the latest v1:\n\n```ts\nimport { createRouter } from \"https://esm.town/v/nbbaier/integrations/mod.ts\";\n```\n\nPin a version with Val Town's `?v=` escape hatch if you need to\n(`…/mod.ts?v=42`). `mod.ts` is the stable v1 entrypoint — breaking changes ship\nas a **new entrypoint**, never on `mod.ts`. Post-v1, `main` is the release\nchannel: changes land through a branch with a green `deno task check`.\n\n## Development\n\n```sh\ndeno task check # fmt + lint + typecheck + test\n```\n\nBiome (tab-indented) is the canonical formatter. Tests live alongside the code\n(`router_test.ts`, `example/hello_test.ts`).\n",[179],"f1a7b430-e6fb-4e34-acc4-a5630a1a8967","INTEGRATIONS.md","b16cb92a-7d51-11f1-b759-1607ee4eb77e",186,["D",1784043352856],"# Integration registry\n\nKnown integrations built on the [`integrations`](README.md) contract. Each is a\ncallable `(options) => Integration` factory — import it and register it with\n`createRouter`, or mount it standalone as a val's HTTP export.\n\n| Integration | Factory | Slug | Import |\n| ------------------- | -------------- | -------- | ------------------------------------------------------ |\n| Issue tracker | `issueTracker` | `issues` | `https://esm.town/v/nbbaier/val-issue-tracker/mod.ts` |\n| Blob viewer | `blobAdmin` | `blobs` | `https://esm.town/v/nbbaier/scoped-blob-viewer/mod.ts` |\n| Hello World example | `helloWorld` | `hello` | `./example/hello.ts` (in this repo) |\n\n```ts\nimport { createRouter } from \"https://esm.town/v/nbbaier/integrations/mod.ts\";\nimport { issueTracker } from \"https://esm.town/v/nbbaier/val-issue-tracker/mod.ts\";\nimport { blobAdmin } from \"https://esm.town/v/nbbaier/scoped-blob-viewer/mod.ts\";\n\nexport default createRouter({\n auth: { users: \"nbbaier\" },\n integrations: [issueTracker({}), blobAdmin({})],\n});\n```\n\n## Integrations\n\n### Issue tracker — `issueTracker`\n\nA lightweight GitHub-flavoured issue tracker for Val Town's scoped SQLite:\nissues, labels, assignees, blocking edges, comments, and a bearer-authenticated\nJSON API. Role model (viewer / contributor / maintainer) resolves from\n`ctx.user`.\n\n- **Repo:** [`val-issue-tracker`](https://val.town/x/nbbaier/val-issue-tracker)\n- **Env:** `OAUTH_STATE_ENCRYPTION_KEY` (when auth is on);\n `ISSUE_TRACKER_API_KEY` for JSON writes.\n\n### Blob viewer — `blobAdmin`\n\nAn admin panel for val-scoped blob storage — list, view, edit (text/JSON),\npreview images, upload, download, rename, copy, delete. Authorizes an `owner`\nfrom `ctx.user` (all-or-nothing).\n\n- **Repo:**\n [`scoped-blob-viewer`](https://val.town/x/nbbaier/scoped-blob-viewer)\n- **Env:** `OAUTH_STATE_ENCRYPTION_KEY` (when auth is on).\n\n### Hello World example — `helloWorld`\n\nThe smallest honest integration — the copyable worked example that ships in this\nrepo. Not a published val; copy [`example/hello.ts`](example/hello.ts) to start\nyour own. See [`example/README.md`](example/README.md) for the walkthrough.\n\n- **Env:** `HELLO_GREETING` (optional; demonstrates `requiredEnv`).\n\n## Adding an integration\n\nBuild an `(options) => Integration` factory with `defineIntegration` (see\n[Writing an integration](README.md#writing-an-integration)), publish it as a\nval, then add a row to the table above and a short entry under **Integrations**.\n",[186],"54cc50c6-b62f-4249-90e7-6391cd740332","CONTEXT.md","2744ac76-7cb1-11f1-b0e8-1607ee4eb77e",208,["D",1784043476720],"# Integrations\n\nThe contract and router for mounting reusable web apps (\"integrations\") into a\nVal Town val, so one val exposes many project-level tools through a single URL.\n\n## The pattern\n\nAn integration is a **mountable sub-app over a Val Town scoped resource** — a\nself-contained web app (UI, routes, and its own authorization) wrapped around\none val-scoped thing (a SQLite-backed domain, the blob store). The contract is\nthis shape extracted from `val-issue-tracker` and `scoped-blob-viewer`, which\nalready shared it.\n\nThe defining twist is Val Town scoping: scoped SQLite/blob bind to whichever\nval's runtime is **executing** the code, so an integration operates on its\n**host val's** data and identity just by being imported — no tokens, no config.\nFrom that follow its three properties:\n\n- **Host-scoped, not self-scoped** — it acts on the executing val's storage, so\n importing it points it at that val's data.\n- **Portable / dual-mode** — relative-only links and a callable contract let the\n same value run standalone (a val's HTTP export) or routed (mounted at\n `/slug/`).\n- **Composable** — it keeps authorization but lifts authentication to the host\n or router, so many stack behind one origin and one login.\n\nAnalogy: Rails engines or Hono/Express sub-apps mounted at a prefix, but\nhost-scoped — mounting inherits the host's data and identity for free.\n\n## Language\n\n**Integration**: A self-contained web app — metadata plus a fetch handler — that\noperates on the host val's scoped storage and is registered with a router.\n_Avoid_: plugin, addon, module, app\n\n**Callable integration**: What `defineIntegration` returns — the Integration\nobject made directly callable as an HTTP handler, so one factory return value\nserves standalone mode (`export default myFactory({...})`) and routed mode\nalike. _Avoid_: hybrid, function-object\n\n**Integration factory**: The `(options) => Integration` function an integration\nauthor exports; all configuration lives in its closure, never in the Integration\nitself. _Avoid_: constructor, builder, plugin function\n\n**Router**: The HTTP handler `createRouter` produces. It owns auth, serves the\ndirectory page, and dispatches requests to registered integrations. _Avoid_:\nmeta-router, gateway, hub\n\n**Host val**: The val in which a router (or a standalone integration) is\nmounted. Its scoped SQLite and blob storage are what integrations read and\nwrite. _Avoid_: parent val, project, consumer\n\n**Integration context**: The object the router passes as a handler's second\nargument (`user`, `prefix`). Absent in standalone mode — its absence is how an\nintegration knows no router is present. Surfaces as `c.env` in Hono-based\nintegrations. _Avoid_: env, request context, session\n\n**Reserved slugs**: Slugs `createRouter` rejects because the router owns those\npaths: `auth` (std/oauth's fixed routes) and the `_`-prefixed namespace (all\nfuture router-owned surface).\n\n**Slug**: An integration's short, unique, URL-safe identifier within one router;\nit determines where the integration is served. _Avoid_: id, key, name (name is\nthe human-readable label)\n\n**Directory page**: The router's page at `/`: the list of registered\nintegrations with links and missing-`requiredEnv` warnings. _Avoid_: dashboard\n(the richer, out-of-scope idea), homepage, index\n\n**Reserved paths**: Paths the router keeps for itself (`/` and `/auth/*`); slugs\nmust not collide with them.\n\n**Standalone mode**: Mounting an integration's handler directly as a val's HTTP\nexport, no router involved. Every integration must keep working this way.\n_Avoid_: legacy mode, direct mode\n\n**Routed mode**: Mounting an integration by registering it with a router via its\nfactory. _Avoid_: managed mode, hosted mode\n\n**Session-less flag**: The single coarse opt-in an integration declares to mean\n\"safe to receive requests with no logged-in user, period.\" The router enforces\nit at dispatch; unflagged (the default) is fully gated. It is the _ceiling_ of\npublic exposure, not a route list — the integration's own per-route\nauthorization draws the fine line. _Avoid_: public flag, anonymous flag,\nallowlist (a different axis). See\n[ADR 0004](docs/adr/0004-session-less-auth.md).\n\n**Login-location signal**: The routed-only context field telling an integration\n_where login lives, or that none exists_ — so a flagged integration renders a\nworking log-in link under a router that owns login and omits it otherwise. It\ndisambiguates `user: null` (\"visitor hasn't logged in\") from \"router has no\nlogin.\" _Avoid_: auth flag, isAuthenticated. (Exact field name → build.)\n\n**Allowlist**: The router's `users` config governing _who may log in / gains the\nprivileged surface_. Orthogonal to the session-less flag (which governs the\n_public_ surface). The host val owner is always implicitly allowlisted; omitted\n`users` means owner-only. _Avoid_: users list (as a synonym for the whole\nconcept), whitelist.\n\n**Escape hatch**: The one host-side, per-integration, explicitly-named override\nthat force-mounts an _unflagged_ integration on an `auth: false` router (which\notherwise throws). The single sanctioned _widening_ of exposure; a host narrows\nsilently but widens only loudly. _Avoid_: force flag, unsafe mode, override\n(unqualified).\n",[193],"a5b1570a-c78d-43fd-9cbc-c3e9f7a53f48","CLAUDE.md","90778238-7f9d-11f1-973d-1607ee4eb77e",236,["D",1784046054696],1,"## Agent skills\n\n### Issue tracker\n\nIssues and specs live as markdown files under `docs/issues//`. See\n`docs/agents/issue-tracker.md`.\n\n### Triage labels\n\nDefault label vocabulary (`needs-triage`, `needs-info`, `ready-for-agent`,\n`ready-for-human`, `wontfix`) used as-is. See `docs/agents/triage-labels.md`.\n\n### Domain docs\n\nSingle-context: one `CONTEXT.md` + `docs/adr/` at the repo root. See\n`docs/agents/domain.md`.\n",[200],"15ef8d9a-daa1-4feb-b294-cb63bd88180b","AGENTS.md","9070f4b8-7f9d-11f1-ad6d-1607ee4eb77e",234,["D",1784046054839],[208],"a9db1ec5-6e06-4624-be74-8baaa2d47729",".vtignore","52638df0-7c9d-11f1-b73f-1607ee4eb77e",["D",1783715055884],".git\n.vscode\n.cursor\n.claude\n.DS_Store\nnode_modules\nvendor",[214],"667be803-e80f-480e-a009-f1ac8c9e0a34","wayfinder","15510276-7ef5-11f1-aa6c-1607ee4eb77e",139,["D",1783972651469],"directory",[220],"963ec3f1-4692-4fbf-bfed-f54fe2d276f3","example","efe83c56-7d47-11f1-9667-1607ee4eb77e",95,["D",1783788334625],[227],"a29dc277-7931-4cf4-b228-0524d69fcc23","docs","c22f6a9e-7cb3-11f1-a763-1607ee4eb77e",31,["D",1783724692393],[233],"pulls","forks","envVars",{"_244":204,"_246":52},"connections",{"_244":52,"_245":52},"count","unfilledCount","emptyCount",{"_20":232,"_13":233,"_130":234,"_132":-5,"_133":21,"_134":235,"_136":109,"_22":780,"_29":52,"_139":224,"_141":-5,"_143":38,"_144":-5,"_317":781,"_91":782},{"_20":775,"_13":750,"_130":744,"_132":234,"_133":21,"_134":776,"_136":109,"_22":777,"_29":52,"_139":224,"_141":-5,"_143":38,"_144":-5,"_317":778,"_91":779},{"_20":767,"_13":768,"_130":769,"_132":744,"_133":21,"_134":770,"_136":109,"_22":771,"_29":204,"_139":102,"_141":772,"_143":38,"_144":-5,"_317":773,"_91":774},{"_20":759,"_13":760,"_130":761,"_132":744,"_133":21,"_134":762,"_136":109,"_22":763,"_29":422,"_139":102,"_141":764,"_143":38,"_144":-5,"_317":765,"_91":766},{"_20":751,"_13":752,"_130":753,"_132":744,"_133":21,"_134":754,"_136":109,"_22":755,"_29":204,"_139":102,"_141":756,"_143":38,"_144":-5,"_317":757,"_91":758},{"_20":741,"_13":742,"_130":743,"_132":744,"_133":21,"_134":745,"_136":109,"_22":746,"_29":52,"_139":102,"_141":747,"_143":38,"_144":-5,"_317":748,"_91":749},{"_20":736,"_13":719,"_130":713,"_132":234,"_133":21,"_134":737,"_136":109,"_22":738,"_29":52,"_139":224,"_141":-5,"_143":38,"_144":-5,"_317":739,"_91":740},{"_20":728,"_13":729,"_130":730,"_132":713,"_133":21,"_134":731,"_136":109,"_22":732,"_29":204,"_139":102,"_141":733,"_143":38,"_144":-5,"_317":734,"_91":735},{"_20":720,"_13":721,"_130":722,"_132":713,"_133":21,"_134":723,"_136":109,"_22":724,"_29":204,"_139":102,"_141":725,"_143":38,"_144":-5,"_317":726,"_91":727},{"_20":710,"_13":711,"_130":712,"_132":713,"_133":21,"_134":714,"_136":109,"_22":715,"_29":204,"_139":102,"_141":716,"_143":38,"_144":-5,"_317":717,"_91":718},{"_20":705,"_13":620,"_130":700,"_132":234,"_133":21,"_134":706,"_136":109,"_22":707,"_29":52,"_139":224,"_141":-5,"_143":38,"_144":-5,"_317":708,"_91":709},{"_20":699,"_13":621,"_130":614,"_132":700,"_133":21,"_134":701,"_136":109,"_22":702,"_29":52,"_139":224,"_141":-5,"_143":38,"_144":-5,"_317":703,"_91":704},{"_20":694,"_13":620,"_130":625,"_132":614,"_133":21,"_134":695,"_136":109,"_22":696,"_29":52,"_139":224,"_141":-5,"_143":38,"_144":-5,"_317":697,"_91":698},{"_20":686,"_13":687,"_130":688,"_132":625,"_133":21,"_134":689,"_136":109,"_22":690,"_29":204,"_139":102,"_141":691,"_143":38,"_144":-5,"_317":692,"_91":693},{"_20":678,"_13":679,"_130":680,"_132":625,"_133":21,"_134":681,"_136":109,"_22":682,"_29":204,"_139":102,"_141":683,"_143":38,"_144":-5,"_317":684,"_91":685},{"_20":670,"_13":671,"_130":672,"_132":625,"_133":21,"_134":673,"_136":109,"_22":674,"_29":204,"_139":102,"_141":675,"_143":38,"_144":-5,"_317":676,"_91":677},{"_20":662,"_13":663,"_130":664,"_132":625,"_133":21,"_134":665,"_136":109,"_22":666,"_29":204,"_139":102,"_141":667,"_143":38,"_144":-5,"_317":668,"_91":669},{"_20":654,"_13":655,"_130":656,"_132":625,"_133":21,"_134":657,"_136":109,"_22":658,"_29":381,"_139":102,"_141":659,"_143":38,"_144":-5,"_317":660,"_91":661},{"_20":647,"_13":648,"_130":649,"_132":625,"_133":21,"_134":30,"_136":109,"_22":650,"_29":381,"_139":102,"_141":651,"_143":38,"_144":-5,"_317":652,"_91":653},{"_20":639,"_13":640,"_130":641,"_132":625,"_133":21,"_134":642,"_136":109,"_22":643,"_29":422,"_139":102,"_141":644,"_143":38,"_144":-5,"_317":645,"_91":646},{"_20":631,"_13":632,"_130":633,"_132":625,"_133":21,"_134":634,"_136":109,"_22":635,"_29":204,"_139":102,"_141":636,"_143":38,"_144":-5,"_317":637,"_91":638},{"_20":622,"_13":623,"_130":624,"_132":625,"_133":21,"_134":626,"_136":109,"_22":627,"_29":204,"_139":102,"_141":628,"_143":38,"_144":-5,"_317":629,"_91":630},{"_20":611,"_13":612,"_130":613,"_132":614,"_133":21,"_134":615,"_136":109,"_22":616,"_29":52,"_139":102,"_141":617,"_143":38,"_144":-5,"_317":618,"_91":619},{"_20":606,"_13":605,"_130":599,"_132":234,"_133":21,"_134":607,"_136":109,"_22":608,"_29":52,"_139":224,"_141":-5,"_143":38,"_144":-5,"_317":609,"_91":610},{"_20":596,"_13":597,"_130":598,"_132":599,"_133":21,"_134":600,"_136":109,"_22":601,"_29":159,"_139":102,"_141":602,"_143":38,"_144":-5,"_317":603,"_91":604},{"_20":591,"_13":506,"_130":586,"_132":234,"_133":21,"_134":592,"_136":109,"_22":593,"_29":52,"_139":224,"_141":-5,"_143":38,"_144":-5,"_317":594,"_91":595},{"_20":585,"_13":507,"_130":499,"_132":586,"_133":21,"_134":587,"_136":109,"_22":588,"_29":52,"_139":224,"_141":-5,"_143":38,"_144":-5,"_317":589,"_91":590},{"_20":580,"_13":367,"_130":518,"_132":499,"_133":21,"_134":581,"_136":109,"_22":582,"_29":52,"_139":224,"_141":-5,"_143":38,"_144":-5,"_317":583,"_91":584},{"_20":572,"_13":573,"_130":574,"_132":518,"_133":21,"_134":575,"_136":109,"_22":576,"_29":204,"_139":102,"_141":577,"_143":38,"_144":-5,"_317":578,"_91":579},{"_20":564,"_13":565,"_130":566,"_132":518,"_133":21,"_134":567,"_136":109,"_22":568,"_29":422,"_139":102,"_141":569,"_143":38,"_144":-5,"_317":570,"_91":571},{"_20":556,"_13":557,"_130":558,"_132":518,"_133":21,"_134":559,"_136":109,"_22":560,"_29":151,"_139":102,"_141":561,"_143":38,"_144":-5,"_317":562,"_91":563},{"_20":548,"_13":549,"_130":550,"_132":518,"_133":21,"_134":551,"_136":109,"_22":552,"_29":204,"_139":102,"_141":553,"_143":38,"_144":-5,"_317":554,"_91":555},{"_20":540,"_13":541,"_130":542,"_132":518,"_133":21,"_134":543,"_136":109,"_22":544,"_29":159,"_139":102,"_141":545,"_143":38,"_144":-5,"_317":546,"_91":547},{"_20":532,"_13":533,"_130":534,"_132":518,"_133":21,"_134":535,"_136":109,"_22":536,"_29":138,"_139":102,"_141":537,"_143":38,"_144":-5,"_317":538,"_91":539},{"_20":524,"_13":525,"_130":526,"_132":518,"_133":21,"_134":527,"_136":109,"_22":528,"_29":138,"_139":102,"_141":529,"_143":38,"_144":-5,"_317":530,"_91":531},{"_20":515,"_13":516,"_130":517,"_132":518,"_133":21,"_134":519,"_136":109,"_22":520,"_29":422,"_139":102,"_141":521,"_143":38,"_144":-5,"_317":522,"_91":523},{"_20":508,"_13":179,"_130":509,"_132":499,"_133":21,"_134":510,"_136":109,"_22":511,"_29":204,"_139":102,"_141":512,"_143":38,"_144":-5,"_317":513,"_91":514},{"_20":497,"_13":351,"_130":498,"_132":499,"_133":21,"_134":500,"_136":109,"_22":501,"_29":502,"_139":102,"_141":503,"_143":38,"_144":-5,"_317":504,"_91":505},{"_20":226,"_13":227,"_130":228,"_132":-5,"_133":21,"_134":229,"_136":109,"_22":494,"_29":52,"_139":224,"_141":-5,"_143":38,"_144":-5,"_317":495,"_91":496},{"_20":487,"_13":179,"_130":488,"_132":228,"_133":21,"_134":489,"_136":109,"_22":490,"_29":204,"_139":102,"_141":491,"_143":38,"_144":-5,"_317":492,"_91":493},{"_20":479,"_13":480,"_130":481,"_132":228,"_133":21,"_134":482,"_136":109,"_22":483,"_29":381,"_139":140,"_141":484,"_143":38,"_144":-5,"_317":485,"_91":486},{"_20":471,"_13":472,"_130":473,"_132":228,"_133":21,"_134":474,"_136":109,"_22":475,"_29":159,"_139":140,"_141":476,"_143":38,"_144":-5,"_317":477,"_91":478},{"_20":219,"_13":220,"_130":221,"_132":-5,"_133":21,"_134":222,"_136":109,"_22":468,"_29":52,"_139":224,"_141":-5,"_143":38,"_144":-5,"_317":469,"_91":470},{"_20":463,"_13":447,"_130":441,"_132":221,"_133":21,"_134":464,"_136":109,"_22":465,"_29":52,"_139":224,"_141":-5,"_143":38,"_144":-5,"_317":466,"_91":467},{"_20":455,"_13":456,"_130":457,"_132":441,"_133":21,"_134":458,"_136":109,"_22":459,"_29":204,"_139":102,"_141":460,"_143":38,"_144":-5,"_317":461,"_91":462},{"_20":448,"_13":418,"_130":449,"_132":441,"_133":21,"_134":450,"_136":109,"_22":451,"_29":204,"_139":102,"_141":452,"_143":38,"_144":-5,"_317":453,"_91":454},{"_20":439,"_13":359,"_130":440,"_132":441,"_133":21,"_134":442,"_136":109,"_22":443,"_29":204,"_139":102,"_141":444,"_143":38,"_144":-5,"_317":445,"_91":446},{"_20":434,"_13":367,"_130":361,"_132":221,"_133":21,"_134":435,"_136":109,"_22":436,"_29":52,"_139":224,"_141":-5,"_143":38,"_144":-5,"_317":437,"_91":438},{"_20":426,"_13":427,"_130":428,"_132":361,"_133":21,"_134":429,"_136":109,"_22":430,"_29":381,"_139":102,"_141":431,"_143":38,"_144":-5,"_317":432,"_91":433},{"_20":417,"_13":418,"_130":419,"_132":361,"_133":21,"_134":420,"_136":109,"_22":421,"_29":422,"_139":102,"_141":423,"_143":38,"_144":-5,"_317":424,"_91":425},{"_20":409,"_13":410,"_130":411,"_132":361,"_133":21,"_134":412,"_136":109,"_22":413,"_29":381,"_139":102,"_141":414,"_143":38,"_144":-5,"_317":415,"_91":416},{"_20":401,"_13":402,"_130":403,"_132":361,"_133":21,"_134":404,"_136":109,"_22":405,"_29":381,"_139":102,"_141":406,"_143":38,"_144":-5,"_317":407,"_91":408},{"_20":393,"_13":394,"_130":395,"_132":361,"_133":21,"_134":396,"_136":109,"_22":397,"_29":159,"_139":102,"_141":398,"_143":38,"_144":-5,"_317":399,"_91":400},{"_20":385,"_13":386,"_130":387,"_132":361,"_133":21,"_134":388,"_136":109,"_22":389,"_29":381,"_139":102,"_141":390,"_143":38,"_144":-5,"_317":391,"_91":392},{"_20":376,"_13":377,"_130":378,"_132":361,"_133":21,"_134":379,"_136":109,"_22":380,"_29":381,"_139":102,"_141":382,"_143":38,"_144":-5,"_317":383,"_91":384},{"_20":368,"_13":369,"_130":370,"_132":361,"_133":21,"_134":371,"_136":109,"_22":372,"_29":204,"_139":102,"_141":373,"_143":38,"_144":-5,"_317":374,"_91":375},{"_20":358,"_13":359,"_130":360,"_132":361,"_133":21,"_134":362,"_136":109,"_22":363,"_29":204,"_139":102,"_141":364,"_143":38,"_144":-5,"_317":365,"_91":366},{"_20":350,"_13":351,"_130":352,"_132":221,"_133":21,"_134":353,"_136":109,"_22":354,"_29":167,"_139":102,"_141":355,"_143":38,"_144":-5,"_317":356,"_91":357},{"_20":213,"_13":214,"_130":215,"_132":-5,"_133":21,"_134":159,"_136":109,"_22":347,"_29":52,"_139":102,"_141":217,"_143":38,"_144":-5,"_317":348,"_91":349},{"_20":207,"_13":208,"_130":209,"_132":-5,"_133":21,"_134":210,"_136":109,"_22":344,"_29":204,"_139":102,"_141":205,"_143":38,"_144":-5,"_317":345,"_91":346},{"_20":199,"_13":200,"_130":201,"_132":-5,"_133":21,"_134":202,"_136":109,"_22":341,"_29":204,"_139":102,"_141":205,"_143":38,"_144":-5,"_317":342,"_91":343},{"_20":192,"_13":193,"_130":194,"_132":-5,"_133":21,"_134":195,"_136":109,"_22":338,"_29":138,"_139":102,"_141":197,"_143":38,"_144":-5,"_317":339,"_91":340},{"_20":185,"_13":186,"_130":187,"_132":-5,"_133":21,"_134":188,"_136":109,"_22":335,"_29":159,"_139":102,"_141":190,"_143":38,"_144":-5,"_317":336,"_91":337},{"_20":178,"_13":179,"_130":180,"_132":-5,"_133":21,"_134":181,"_136":109,"_22":332,"_29":159,"_139":102,"_141":183,"_143":38,"_144":-5,"_317":333,"_91":334},{"_20":171,"_13":172,"_130":173,"_132":-5,"_133":21,"_134":174,"_136":109,"_22":329,"_29":151,"_139":102,"_141":176,"_143":38,"_144":-5,"_317":330,"_91":331},{"_20":162,"_13":163,"_130":164,"_132":-5,"_133":21,"_134":165,"_136":109,"_22":326,"_29":167,"_139":168,"_141":169,"_143":38,"_144":-5,"_317":327,"_91":328},{"_20":154,"_13":155,"_130":156,"_132":-5,"_133":21,"_134":157,"_136":109,"_22":323,"_29":159,"_139":140,"_141":160,"_143":38,"_144":-5,"_317":324,"_91":325},{"_20":146,"_13":147,"_130":148,"_132":-5,"_133":21,"_134":149,"_136":109,"_22":320,"_29":151,"_139":140,"_141":152,"_143":38,"_144":-5,"_317":321,"_91":322},{"_20":128,"_13":129,"_130":131,"_132":-5,"_133":21,"_134":135,"_136":109,"_22":316,"_29":138,"_139":140,"_141":142,"_143":38,"_144":-5,"_317":318,"_91":319},["D",1784051707465],"children",[],[129],["D",1784051707432],[],[147],["D",1784047632088],[],[155],["D",1784043352057],[],[163],["D",1784050565037],[],[172],["D",1784047632109],[],[179],["D",1784043352856],[],[186],["D",1784043476720],[],[193],["D",1784046054696],[],[200],["D",1784046054839],[],[208],["D",1783715055884],[],[214],"0e3b18ba-e32d-493f-83cf-066e50c87c19","map.md","15b0f316-7ef5-11f1-bccf-1607ee4eb77e",210,["D",1784043476702],"---\ntitle: Fine-grained auth for routed integrations — mechanism + authority decision\nlabels: [wayfinder:map]\nstatus: open\n---\n\n## Destination\n\nA locked, spike-validated decision — an ADR in `docs/adr/` — on fine-grained\nauth for routed integrations, answering two things: (1) the runtime mechanism by\nwhich session-less requests (anonymous humans and bearer-token machines)\ntraverse a gated router to reach integrations, and (2) where authority lives —\nwhat an integration declares vs what the router/host decides. Concrete contract\nAPI shape, type names, migration, and build belong to a later effort.\n\n## Notes\n\n- **This map plans; it does not carry execution.** Tickets resolve decisions and\n investigations; the only artifacts are research summaries, a throwaway spike,\n and the ADR. The build is a fresh effort handed the locked decision.\n- **Lock bar is spike-validated:** the ADR may not lock on analysis alone — any\n load-bearing runtime unknown (std/oauth middleware behavior, bearer-token\n coexistence) must be verified running first.\n- Problem scope covers **both** flattened-auth problems from v1's out-of-scope\n list: anonymous public reads (the tracker's viewer role is lost behind the\n login wall) and machine-credential pass-through (bearer-token clients can't\n reach the tracker's `/api` behind a gated router). Both stem from the router\n 401ing every session-less request before the integration sees it.\n- **Null hypothesis to falsify, not a foregone conclusion:** extend v1's split\n \"router authenticates, integration authorizes\" — the integration declares\n which of its surface is reachable without a session, the router enforces at\n dispatch and passes `ctx.user: null` through.\n- Domain: Val Town platform (Deno runtime, std/oauth). Sessions should consult\n the `valtown:oauth` and `valtown:http-endpoints` skills, and\n `find_val_town_skills` for anything platform-specific.\n- Ubiquitous language lives in `CONTEXT.md` (repo root) — consult it every\n session and maintain it via `/domain-modeling`. ADRs go in `docs/adr/`\n (0001–0003 exist; this map's destination is the next one).\n- Prior effort: the archived v1 map at `docs/wayfinder-archive/integrations-v1/`\n — see especially the val-issue-tracker migration ticket (004) for how the\n current permission model composes, and the map's Out of scope section where\n this effort was scoped.\n- Repos (local working dirs): `~/Code/vt-projects/integrations` (contract +\n router), `~/Code/vt-projects/val-issue-tracker`,\n `~/Code/vt-projects/scoped-blob-viewer`.\n- Tracker conventions (local markdown): tickets live in `wayfinder/tickets/`,\n one file each, frontmatter `id`, `title`, `labels`, `status: open|closed`,\n `assignee`, `blocked-by: [ids]`. Claim = set `assignee`. Frontier = open,\n unassigned, all `blocked-by` closed. Resolutions go in a `## Resolution`\n section on the ticket.\n\n## Decisions so far\n\n\n\n- [Research std/oauth constraints on selective gating](tickets/001-research-std-oauth-constraints.md)\n — std/oauth imposes no constraint: the middleware only serves root-level\n `/auth/*` and passes everything else through untouched (no 401/redirect);\n `getOAuthUserData` is side-effect-free and returns `null` for anonymous;\n bearer headers are never read. All gating authority already sits behind the\n middleware, so the null hypothesis is unopposed at this layer. OAuth must be\n mounted once at the router root (exact-match routes); sessions are\n origin-bound via key lookup — a spike watch-item.\n- [Inventory real-integration auth requirements](tickets/002-requirements-inventory.md)\n — 12 scenario rows + 6 derived requirements: granularity must be per-route\n (the tracker's public surface isn't \"all GETs\"); session-less reachability\n must be integration-declared with a gated default (an owner-less blob viewer\n would otherwise hand anonymous full admin); the tracker's bearer key is\n router-opaque, so machine credentials must reach the integration unvalidated;\n and the ctx must distinguish anonymous-on-gated-router from ungated-router\n (`ctx.user: null` conflates them today).\n- [Choose the mechanism and authority split](tickets/003-candidate-mechanisms-authority-split.md)\n — null hypothesis confirmed and sharpened: the integration declares one coarse\n opt-in flag (\"safe for session-less traffic, period\"); the router enforces at\n dispatch, passes `Authorization` through untouched (no router-minted scheme),\n and the ctx gains a login-location signal so anonymous-on-gated ≠ ungated.\n `auth: false` + an unflagged integration throws at `createRouter`. Includes\n the flag × type × router-auth composition table and the five spike assumptions\n ticket 4 must verify.\n- [Spike the leading mechanism](tickets/004-spike-leading-mechanism.md) —\n candidate **locks**: all five load-bearing assumptions survived the Val Town\n runtime. Anonymous reaches flagged surfaces while unflagged ones 401; a bearer\n non-GET write completes with header+body echoed byte-identical and no redirect\n (router never touches `Authorization`); the tracker-analog's interleaved\n public/gated routes behave as standalone (`GET /new` still 403s); the login\n signal renders on anonymous-but-allowed pages and login returns a session; and\n origin-bound sessions **don't** bite — routed mode is a single origin, so a\n session covers every slug. Spike val `nbbaier/wayfinder-auth-spike` linked on\n the ticket, kept until the ADR locks. Ticket 3 did not reopen.\n\n- [Router's own surface under partial gating](tickets/006-router-surface-partial-gating.md)\n — the router is **not** an anti-enumeration boundary (Val Town rarely hosts\n sensitive data), so least-surprise and standalone-parity decide it. `/` is\n public **iff ≥1 integration is flagged** (else today's login wall stands);\n anonymous sees **only flagged** integrations listed plus a generic \"log in to\n see more\" (no count); hitting a private integration's URL directly → the\n single router-owned **login page (401)**, matching standalone, not a 404;\n anonymous non-GET (stale-tab POST) → keep today's **302 to `/`**.\n\n- [Allowlist composition and host overrides](tickets/007-allowlist-composition-host-overrides.md)\n — the `users` allowlist and the flag are **orthogonal**: the allowlist gates\n _who may log in_ (the privileged surface), never a flagged integration's\n public surface, which anonymous reaches regardless. The **host val owner is\n always implicitly allowlisted** (realizable per ticket 9); `[]` = owner-only,\n `[\"*\"]` = owner + anyone, `[\"user1\"]` = owner + user1, and **omitted =\n owner-only** (a safe-by-default change from today's \"anyone\"). Authority runs\n one direction: the flag is the **ceiling** of public exposure — the host may\n **narrow** silently (mechanism deferred as a named extension point; no\n ticket-2 need) and **widen** only loudly, via a per-integration,\n explicitly-named, host-side **escape hatch** to force-mount an unflagged\n integration on an `auth: false` router (option shape + any warning log →\n build).\n\n- [Can the router identify the val owner at runtime?](tickets/009-identify-val-owner-at-runtime.md)\n — **yes, analytically.** The owner handle is available with no login via\n `parseVal().username` (from the auto-injected `VALTOWN_ENTRYPOINT` env var);\n \"is this user the owner?\" reduces to\n `getOAuthUserData(req)?.user.username\n === parseVal().username`. This\n unblocks ticket 7's implicit-owner allowlist semantics. Use the direct\n comparison, not the session's `isOrgMember` (frozen at login, optional, too\n broad). One cheap spike confirmation (`VALTOWN_ENTRYPOINT` populated in the\n routed isolate) folds into the ADR session.\n\n- [The session-less flag in standalone mode](tickets/008-flag-standalone-interaction.md)\n — the whole session-less model is **routed-only**; standalone is unchanged and\n prescribes nothing new. The flag is inert standalone (no router to enforce it\n — an unflagged integration was already public standalone). Sessions never flow\n through `ctx`: an integration wanting login wires its own std/oauth and reads\n `getOAuthUserData(req)` directly (the tracker already does this,\n `app.tsx:117–145`) — only the _source_ of the \"current user\" changes by mode\n (`ctx.user` ⟷ `getOAuthUserData`). Login-link mirrors it: standalone the\n integration owns its own `/auth/login`; the login-location signal is one more\n routed-only `ctx` field. No upstream ticket reopens. **The ADR states this\n boundary in a short \"Standalone\" section but prescribes no mechanism.**\n\n- [Write and lock the ADR](tickets/005-lock-the-adr.md) — **destination\n reached.** [ADR 0004](../docs/adr/0004-session-less-auth.md) is locked:\n session-less requests reach integrations via one coarse integration-declared\n flag the router enforces at dispatch; `Authorization` passes through\n untouched; the ctx gains a login-location signal; the `users` allowlist is\n orthogonal (owner implicitly allowlisted, omitted = owner-only); the host may\n narrow silently and widen only via an explicit per-integration escape hatch.\n Consolidates tickets 3/4/6/7/8/9 with rejected alternatives and spike\n evidence. The final runtime unknown (owner identification) was confirmed\n running before lock; minted terms added to `CONTEXT.md`. The build is a fresh\n effort chartered by this ADR.\n\n## Not yet specified\n\n(Empty — machine-credential specifics were resolved inside the mechanism\ndecision; the router's-own-surface and allowlist/host-override questions\ngraduated to tickets 6 and 7. The ADR-lock ticket was the terminal frontier\nticket; no fog remains.)\n\n## Out of scope\n\n- **The build** — contract API shape, option/type names, `ctx` field changes,\n migrating the tracker and blob viewer, docs. A later effort takes the locked\n ADR as its charter.\n- **Directory-page customization** — whether `createRouter` ships a default\n directory UI with a config to bring your own. Surfaced resolving ticket 6;\n it's a presentation axis, not an auth decision, so it's a separate future\n wayfinding mission, not part of this ADR.\n",[],[220,351],"4a5ca57c-17ce-4f40-a4d1-0fefef5d9001","009-identify-val-owner-at-runtime.md","e744067c-7f0c-11f1-a751-1607ee4eb77e","1578b62c-7ef5-11f1-9836-1607ee4eb77e",169,["D",1784043350927],"---\nid: 9\ntitle: Can the router identify the val owner at runtime?\nlabels: [wayfinder:research]\nstatus: closed\nassignee: nbbaier\nblocked-by: []\n---\n\n## Question\n\nTicket 7's `users` allowlist semantics make the host val's owner **implicitly\nallowlisted** (`users: []` = owner-only; `[\"*\"]` = owner + anyone; `[\"user1\"]` =\nowner + user1). That rule needs the router to answer \"is this logged-in user the\nowner?\" at runtime — and today it has no owner handle; `getOAuthUserData` only\nreports who logged in. Per the map's lock bar, this runtime unknown must be\npinned to primary sources before the ADR can lock.\n\n- Does Val Town expose the **executing val's owner handle** at runtime — an env\n var, a `std` API, or anything in the request context — without a login?\n- Precisely what is the session's **`isOrgMember`** computed from? Read\n `https://esm.town/v/std/oauth/middleware.ts` and its callback/source. Does it\n reliably mean \"the logged-in user owns or co-owns this val,\" **including for a\n personal val whose owner belongs to no org**? Or is it strictly org-scoped and\n false/meaningless for personal vals?\n- If neither yields a reliable owner identity from primary sources alone, say so\n — that downgrades implicit-owner to needing a **HITL login probe** (fold into\n spike val `nbbaier/wayfinder-auth-spike`) or to **explicit self-listing**\n (drop \"implicit\"; owner must appear in the array).\n\nOutput: a markdown summary in `wayfinder/assets/`, each fact with a pointer to\nthe source line that proves it. AFK — resolvable by a `/research` subagent\nreading platform docs and the std/oauth source.\n\n## Resolution\n\nFull findings:\n[Can the router identify the val owner at\nruntime?](../assets/009-identify-val-owner-at-runtime.md). **Implicit-owner is\nrealizable analytically — no login probe required.**\n\n- **Owner handle at runtime, no login: yes.** The auto-injected env var\n `VALTOWN_ENTRYPOINT` names the executing (host) val; `parseVal().username`\n (std/utils `parseImportMeta.ts`, default arg\n `Deno.env.get(\"VALTOWN_ENTRYPOINT\")`) returns the owner's handle from\n `Deno.env` alone. Caveat: `VALTOWN_ENTRYPOINT` is undocumented publicly — but\n std/utils and std/oauth both rely on it in production.\n- **`isOrgMember` does mean \"owner\" for personal vals** — it's computed as\n `me.username === parseVal().username || userOrgs.some(o => o.username === orgHandle)`,\n so disjunct 1 is true exactly when the logged-in user is the owner. But it's\n frozen at login into the 30-day cookie, optional, and broader than owner (any\n org co-member trips it) — so **don't** use it for the allowlist.\n- **Decision: identify the owner by direct per-request comparison** —\n `getOAuthUserData(req)?.user.username === parseVal().username`. Both operands\n are primary-source-established; the platform already does this same comparison\n internally. Do not fall back to explicit self-listing.\n- **Spike watch-item for the ADR session (ticket 5):** the sole residual is\n empirical — confirm `VALTOWN_ENTRYPOINT` is populated in the router's routed\n isolate and the handle strings match. One line in the existing spike val\n `nbbaier/wayfinder-auth-spike`; non-blocking per the analysis, but folds in\n cheaply before the ADR locks to honor the map's run-it-first bar.\n",[],[220,367,359],"tickets","643838f3-0ff6-411d-8062-febcf102c109","008-flag-standalone-interaction.md","e732694e-7f0c-11f1-98dd-1607ee4eb77e",174,["D",1784043351240],"---\nid: 8\ntitle: The session-less flag in standalone mode\nlabels: [wayfinder:grilling]\nstatus: closed\nassignee: nbbaier\nblocked-by: []\n---\n\n## Question\n\nThe session-less flag (ticket 3) is a declaration the _router_ enforces at\ndispatch. But every integration must also run **standalone** — mounted directly\nas a val's HTTP export, no router present (`CONTEXT.md`: standalone mode; ctx\nabsent). What does the flag, and the whole session-less auth model, mean when\nthere is no router to enforce it?\n\n- **Does the flag carry any meaning standalone, or is it purely router-facing\n metadata?** A flagged integration run standalone has no router login wall in\n front of it — is it simply \"always reachable,\" and is that a problem for an\n integration that relied on the router to gate it (the ticket-3 Type C blob\n viewer, which declares _no_ flag precisely because it needs gating)?\n- **Who provides login standalone?** Routed mode gives the integration a\n router-owned OAuth login (std/oauth) and a ctx login-signal. Standalone has\n neither. Does an integration that wants a login in standalone mode wire its\n own std/oauth, and does anything in this model need to say so?\n- **Is this in the ADR or explicitly deferred?** The destination is auth for\n _routed_ integrations. Decide whether the ADR states the standalone boundary\n (even just \"flag is router-only; standalone is unaffected / the author's own\n responsibility\") or punts it entirely to the build/a later effort.\n\nHITL — /grilling.\n\n## Resolution\n\n**The session-less auth model is entirely routed-only; standalone is unchanged\nand prescribes nothing new.** Everything this effort adds — the flag, `ctx`, and\nthe login-location signal — is a channel between a router and an integration.\nStandalone has no router, so none of it applies, and its absence is the signal\nan integration already keys off (`ctx`-absence = \"no router present,\" per\nCONTEXT.md).\n\nThree decisions, grounded in the reference integration (`val-issue-tracker`\nalready ships exactly this):\n\n1. **The flag is inert standalone — purely router-facing metadata.** It's a\n declaration a _router_ reads and enforces at dispatch; standalone has no\n dispatch step to read it. A flagged integration run standalone is reachable,\n but so is an unflagged one — standalone has never had a host gate. This is\n not a regression the flag introduces: the Type C blob viewer (declares _no_\n flag precisely to get routed-mode gating) was _already_ fully public run\n standalone with no router. The flag changes nothing about that.\n\n2. **Sessions never flow through `ctx` standalone — the integration\n authenticates itself.** An integration wanting login standalone wires its own\n std/oauth and reads the session directly via `getOAuthUserData(req)` — the\n same call the router makes routed. `val-issue-tracker` demonstrates the\n three-way branch (`app.tsx:117–145`, `525–527`): routed+`ctx` → use\n `ctx.user` (must not wrap OAuth again); standalone+`auth` → wrap own\n `oauthMiddleware`, read `getOAuthUserData`; standalone+no-auth → open. The\n unifying principle: an integration always authorizes off a \"current user\"\n value; only its _source_ changes by mode (`ctx.user` routed ⟷\n `getOAuthUserData(req)` standalone). Gated inner routes work identically in\n both modes — they read a user that arrived by a different road. This model\n adds nothing; it's the pre-existing contract. (Whether to ship helper\n utilities for integration builders is an implementation question for the\n build, not this decision.)\n\n3. **The login-_link_ story mirrors the session-source rule; nothing upstream\n reopens.** Routed was settled in tickets 3 & 6: link target is the single\n router-owned login page (ticket 6.3), visibility governed by the ctx\n login-location signal (ticket 3, decision 4). Standalone is the reflection:\n the integration owns its own `/auth/*`, so its login link targets its own\n `/auth/login` and its visibility comes from its own OAuth config — the\n login-location signal is simply one more routed-only `ctx` field, absent\n standalone, its absence again meaning \"you own login.\" (Root-relative\n `/auth/login` resolves to the router routed and to the integration standalone\n — `app.tsx:167`.)\n\n**ADR treatment:** the ADR _states_ this standalone boundary in a short\n\"Standalone\" section but prescribes no mechanism — one paragraph: the flag,\n`ctx`, and the login-location signal are all routed-only; standalone the\nrouter's authority is absent, so authentication, login, and login-link are the\nintegration's own responsibility, as the reference integration already does.\nStated, not deferred, because the destination covers \"what the router decides\"\nand this is exactly where that authority ends; it guards a reader against\nassuming the flag/signal do anything standalone; and it's a boundary statement,\nnot a mechanism, so it drags no build detail into the ADR.\n",[],[220,367,369],"61f7ed59-3073-4bf9-ad89-ac035d43f052","007-allowlist-composition-host-overrides.md","c5c495d0-7efc-11f1-9d03-1607ee4eb77e",170,["D",1784043350955],2,"---\nid: 7\ntitle: Allowlist composition and host overrides\nlabels: [wayfinder:grilling]\nstatus: closed\nassignee: nbbaier\nblocked-by: []\n---\n\n## Question\n\nHow does the session-less flag (ticket 3) compose with the router's `users`\nallowlist, and what host-side overrides exist?\n\n- Is a flagged integration's public surface reachable session-less on a router\n with a `users` allowlist — i.e. does the allowlist restrict _who may log in_\n or _who may enter at all_?\n- Host-side narrowing: can a host make a flagged integration more private than\n it declares (mount the tracker but suppress its public surface)? Ruled\n adjacent in ticket 3's Q1; decide whether it's in this ADR or explicitly\n deferred.\n- Escape hatch for ticket 3's decision 5: may a host knowingly mount an\n unflagged integration on an `auth: false` router (today: `createRouter`\n throws)? If yes, what's the acknowledgment shape — conceptually, not names.\n\nHITL — /grilling.\n\n## Resolution\n\nThe allowlist and the flag are **orthogonal axes**, and the authority runs one\ndirection: the integration's flag is the _ceiling_ of public exposure, the host\nnarrows silently and widens only loudly.\n\n**1. Allowlist ⟂ flag.** The `users` allowlist governs _who may log in / gains\nthe privileged surface_. It does **not** gate a flagged integration's public\nsurface — anonymous reaches flagged surfaces regardless of the allowlist. A host\non a locked-down (owner-only) router still exposes its flagged integrations'\npublic surface to anonymous; that is what the flag means. The two concerns don't\ncompose because they answer different questions (\"who is trusted\" vs \"is this\nsurface public\").\n\n**2. Allowlist semantics — the host val owner is always implicitly allowlisted**\n(realizable at runtime per [ticket 9](009-identify-val-owner-at-runtime.md) via\n`getOAuthUserData(req)?.user.username === parseVal().username`):\n\n| `users` value | Who may log in |\n| -------------------- | ----------------------------------------- |\n| `[]` | owner only |\n| `[\"*\"]` | owner + anyone who can log in to Val Town |\n| `[\"user1\"]` | owner + user1 |\n| omitted / `auth: {}` | owner only (safe default) |\n\nThe bare/omitted default collapsing to **owner-only** is a deliberate change\nfrom today's code (today an unspecified `users` lets _anyone_ logged in enter);\nleast-privilege-by-default is correct for a tool that inherits the host val's\ndata. Exact wildcard spelling (`\"*\"`) is a naming detail for the build.\n\n**3. Host-side narrowing — principle stated, mechanism deferred.** The host\n_may_ make a flagged integration more private than it declares (gate its public\nsurface on one deployment). This is the safe direction and needs no\nacknowledgment. But **no ticket-2 requirement demands the mechanism**, so v1\nships none: host-side per-integration narrowing is recorded as a **named\nextension point**, not built. The host's actual authority in v1 is: `auth`\non/off, the `users` allowlist, and the escape hatch below.\n\n**4. The one sanctioned widening — escape hatch for decision 5.** A host _may_\nknowingly force-mount an **unflagged** integration on an `auth: false` router\n(today: `createRouter` throws). The decided shape:\n\n- **Host-side, in the router config** — never on the integration. The author's\n declaration stays \"I need gating\" (no flag); the host overrides it for their\n own deployment only, taking on the exposure. An override on the integration\n would just _be_ the flag.\n- **Per-integration, explicitly named** — the host names which unflagged\n integrations they're force-mounting. Not a blanket \"disable safety\" switch, so\n adding a _new_ unflagged integration later still throws. Can never happen\n silently.\n- **Startup surfaces it visibly.** The required loudness is the explicit naming\n in config; whether `createRouter` _also_ emits a warning log — and the exact\n option name/shape — is deferred to the build.\n\nThis is the single widening the authority model permits, consistent with\n\"narrows silently, widens only explicitly.\"\n",[],[220,367,377],"0b80aa0e-be3f-4a20-8d9c-3aaf1357dc04","006-router-surface-partial-gating.md","c5ba0980-7efc-11f1-b774-1607ee4eb77e",171,["D",1784043350941],"---\nid: 6\ntitle: Router's own surface under partial gating\nlabels: [wayfinder:grilling]\nstatus: closed\nassignee: nbbaier\nblocked-by: []\n---\n\n## Question\n\nWith the mechanism locked (ticket 3: per-integration session-less flag, router\nenforces at dispatch), what does the router's _own_ surface show an anonymous\nvisitor when some integrations are flagged public and others gated?\n\n- The directory page at `/`: does an anonymous visitor see it at all? Only the\n flagged integrations? Everything, with gated ones marked? Today anonymous GETs\n get the login page unconditionally.\n- The login wall: where does it live once `/` may be public — per-gated-slug, or\n a dedicated page?\n- Unflagged prefixes for anonymous visitors: login wall (current behavior) vs\n 404 (don't reveal what's mounted)?\n- Non-GET session-less requests to unflagged integrations currently 302 to `/` —\n does that survive?\n\nHITL — /grilling.\n\n## Resolution\n\nGuiding stance (set during the grilling): the router is **not** an\nanti-enumeration boundary. Val Town rarely hosts high-sensitivity data, so we\ndon't contort the surface to hide that a private integration exists; we optimize\nfor least-surprise and for matching standalone behavior. This decides every\nsub-question below.\n\n**1. Directory page `/` — conditional visibility.** `/` is reachable\nsession-less **iff at least one integration is flagged public**. A router with\nnothing flagged is fully private and keeps today's behavior exactly: anonymous\nGET `/` → login wall. The new anonymous-`/` surface only switches on once the\noperator has opted something into public. (Dovetails with ticket 3's invariant:\na router with no public surface behaves as it does today.)\n\n**2. Directory listing for anonymous — flagged only, plus a generic teaser.** A\nlogged-out visitor sees only the flagged (public) integrations. Private ones are\nnot listed. When hidden integrations exist, the page shows a generic **\"log in\nto see more\"** affordance — **no count** (the count is marginal for someone\nabout to log in, and \"there are exactly N private tools\" is the one structural\nfact worth not printing). Logged-in users see the full list. Shown only when\nsomething is actually hidden.\n\n**3. Anonymous hits a private (unflagged) integration's URL directly → login\npage (401).** Not a 404. Enumeration isn't a threat we're defending against, and\na login page is exactly what the same integration shows in **standalone** mode\nwhen hit logged-out — matching it is least-surprise. This also fixes the\nlogin-wall location: it's the **single router-owned login page**, served with\n401 at whatever gated URL you hit — not per-integration, not a separate\ndedicated route. The directory's \"log in to see more\" link points at the same\npage. Net stance: we don't _advertise_ private integrations (sub-question 2),\nbut we don't _conceal their existence_ from someone who hits the URL either.\nCoherent, given hiding-existence isn't a goal.\n\n**4. Anonymous non-GET (stale-tab form POST) to a private integration → keep\ntoday's 302 redirect to `/`.** The realistic trigger is session expiry in a\nleft-open tab: a POST arrives with no valid session. A login page can't sensibly\nbe _rendered_ as the response to a form submit, so the visitor is bounced to\n`/`, where the log-in link lives. A bare 401 (cleaner for machine clients) was\nrejected as less browser-friendly; a machine POSTing to a _private_ integration\nis a misconfiguration — the integration it wants should be flagged, in which\ncase the POST flows straight to the handler.\n\n**Surfaced, placed elsewhere (not part of this ADR):**\n\n- **Directory-page customization** (ship a default UI vs. bring-your-own) — a\n separate axis from auth; recorded in the map's Out of scope as a future\n wayfinding mission.\n- **How the session-less flag interacts with standalone mode** — graduated to\n its own ticket on this map (created alongside this resolution).\n",[],[220,367,386],"8a18dddb-7226-4984-bfb2-ec0a5dc19049","005-lock-the-adr.md","15a23088-7ef5-11f1-a818-1607ee4eb77e",207,["D",1784043476679],"---\nid: 5\ntitle: Write and lock the ADR\nlabels: [wayfinder:grilling]\nstatus: closed\nassignee: nbbaier\nblocked-by: [4, 6, 7, 8, 9]\n---\n\n## Question\n\nWrite the ADR (next number in `docs/adr/`) recording the decision the spike\nvalidated: the mechanism by which session-less requests traverse a gated router,\nand the authority split between integration and router/host. Cover both problem\nhalves, the rejected alternatives with reasons, and the spike evidence for each\nload-bearing assumption. Grill the draft with the human until it locks; update\n`CONTEXT.md` language if the decision minted new terms.\n\nLocking this ADR is the map's destination. HITL.\n\n## Resolution\n\n**Locked.**\n[ADR 0004 — Session-less requests reach integrations by a single\nintegration-declared flag](../../docs/adr/0004-session-less-auth.md) is written\nand locked. It consolidates the six closed decision tickets (mechanism +\nauthority split from ticket 3, spike evidence from ticket 4, router surface from\nticket 6, allowlist/host-overrides from ticket 7, standalone boundary from\nticket 8, owner identification from ticket 9), the rejected alternatives with\nreasons, and both problem halves (anonymous public reads, bearer-token\npass-through).\n\nGrilled to lock over two questions:\n\n1. **Silent breaking change** — `omitted users → owner-only` reverses today's\n \"any logged-in user.\" Human confirmed the default is right and no explicit\n Consequences line is needed; existing integrations get a (non-heavy) fix in\n the build effort.\n2. **The map's spike bar vs. the last unverified unknown** — owner\n identification (`VALTOWN_ENTRYPOINT`/`parseVal`) still rested on ticket 9's\n _analysis_. Ran a one-time confirmation (throwaway\n `nbbaier/wayfinder-owner-confirm`, since deleted): on an anonymous request\n `VALTOWN_ENTRYPOINT` is populated, `parseVal().username` → the host owner's\n handle, and `parseVal()` inside an _imported child module_ still resolves to\n the host entrypoint (not the child's own val). So the owner-comparison and\n the `omitted = owner-only` default are runtime-sound. Folded into the ADR's\n Consequences.\n\nHousekeeping: minted terms (**session-less flag**, **login-location signal**,\n**allowlist**, **escape hatch**) added to `CONTEXT.md`. Spike val\n`nbbaier/wayfinder-auth-spike` may now be deleted (kept only until this lock);\nleft to the human. No upstream ticket reopened.\n\nThe build — contract API shape, option/type names, `ctx` changes, tracker +\nblob-viewer migration, docs — is a fresh effort chartered by this ADR.\n",[],[220,367,394],"04efa955-a7d0-480d-afb7-98a782f8232e","004-spike-leading-mechanism.md","159e4d7e-7ef5-11f1-bf46-1607ee4eb77e",176,["D",1784043351437],"---\nid: 4\ntitle: Spike the leading mechanism\nlabels: [wayfinder:prototype]\nstatus: closed\nassignee: nico.baier@gmail.com\nblocked-by: [3]\n---\n\n## Question\n\nDo the leading mechanism's load-bearing assumptions (named by ticket 3) survive\ncontact with the runtime? Build a throwaway spike — a scratch val or local\nharness, not production code — that demonstrates, at minimum:\n\n- an anonymous request reaching a declared-public surface through a gated\n router, while a gated surface on the same router still demands a session;\n- a bearer-token request reaching the machine surface per the chosen credential\n story;\n- std/oauth's login flow still working alongside.\n\nThe spike is an asset linked from this ticket; it locks or kills the candidate.\nIf it kills it, ticket 3 reopens with the new facts. HITL — built via\n/prototype, reviewed with the human.\n\n## Resolution\n\n**The candidate locks. All five of ticket 3's load-bearing assumptions survived\ncontact with the Val Town runtime. Ticket 3 does not reopen.**\n\n**Asset — the spike:** `nbbaier/wayfinder-auth-spike` (unlisted val, live at\n`https://nbbaier--a37ce4867efd11f19b5b1607ee4eb77e.web.val.run/`). A throwaway\nmini-router modelling the locked mechanism — NOT the real (unbuilt) contract:\neach stub integration declares one coarse `sessionless` flag; the router\nenforces at dispatch; `Authorization` passes through untouched; ctx carries a\n`loginLocation` signal. Three stubs cover types A/B/C from ticket 3's table\n(public docs, tracker-analog with interleaved public/gated routes, unflagged\nsecret). **Keep until ticket 5's ADR locks — it's the evidence — then delete.**\n\n**Assumption-by-assumption verdict:**\n\n1. **Selective pass-through — CONFIRMED.** Anonymous `GET /docs/` → 200 public\n page; anonymous `GET /secret/` (unflagged) → 401 login wall, on the same\n router. Login works alongside: the oauth flow completed and returned a\n session. Confirms ticket 1's finding running — `oauthMiddleware` owns only\n `/auth/*` and the router's own dispatch check draws the gate line.\n2. **Bearer non-GET write — CONFIRMED, and cleanly.** `POST /tracker/api/issues`\n with `Bearer ` → 200; the integration echoed `receivedAuthHeader` and\n `receivedBody` back **byte-identical** — the router never read, minted, or\n rewrote the credential. No redirect (the fetch tool refuses to follow one and\n would have errored — it got a direct 200). The same POST with **no** auth →\n **401 from the integration**, not the router: proof the session-less non-GET\n reached the handler and the integration authorised itself (decision 3).\n3. **Tracker-analog behaves as standalone — CONFIRMED.** Anonymous `/tracker/` →\n 200 public, `/tracker/api/issues` → 200 read, `GET /tracker/new` → 403\n refuses. One flagged integration with interleaved public/gated routes, the\n coarse flag opening the door and the integration's own per-route checks\n drawing the fine line — exactly why coarse-flag beat route-lists in ticket 3.\n4. **Login signal renders usefully — CONFIRMED (HITL, browser).** Anonymous-but-\n allowed pages (`/docs/`, `/tracker/`) render the public surface _and_ a\n working log-in link — `user: null` with `loginLocation` set, not conflated\n with \"no login exists.\" Clicking it logged in and returned with a session.\n5. **Origin-bound sessions do NOT bite — CONFIRMED (HITL, browser).** Ticket 1's\n watch-item is a non-issue in routed mode. Logged in, the session stuck across\n every dispatch path — `/docs/`, `/tracker/`, and decisively `/secret/` (a 401\n wall while anonymous, now reachable). Routed mode is a **single origin**; the\n session cookie set at `/auth/callback` covers every slug beneath it. Origin-\n binding could only bite an integration that establishes/consumes a session at\n a _different_ origin — which routed mode never does. A fact for the ADR.\n\n**For ticket 5 (the ADR):** every load-bearing runtime unknown named in ticket 3\nnow has running evidence, clearing the map's spike-validated lock bar. The one\nfinding worth writing into the ADR beyond confirmation: assumption 5's _reason_\n— session coverage is a property of routed mode's single origin, so the ticket-1\norigin-binding caveat needs no mechanism to defend against it. No assumption was\nkilled; no new fog surfaced.\n",[],[220,367,402],"2615f700-419d-422c-b3e0-f23d351174d4","003-candidate-mechanisms-authority-split.md","15a64542-7ef5-11f1-9fa9-1607ee4eb77e",189,["D",1784043351140],"---\nid: 3\ntitle: Choose the mechanism and authority split\nlabels: [wayfinder:grilling]\nstatus: closed\nassignee: nbbaier\nblocked-by: [1, 2]\n---\n\n## Question\n\nWith the std/oauth facts (ticket 1) and the real requirements (ticket 2) in\nhand: which mechanism lets session-less requests traverse the gated router, and\nwhere does authority live — what does an integration declare vs what does the\nrouter/host decide?\n\nGrill against the map's null hypothesis (extend v1's \"router authenticates,\nintegration authorizes\": integration declares its session-less-reachable\nsurface, router enforces at dispatch, `ctx.user: null` passes through) and at\nleast the rival shapes: router-side host config, pass-everything-through, and\ndual/split mounts. Cover both problem halves — anonymous humans and bearer-token\nmachines — and name the leading candidate plus the load-bearing assumptions the\nspike (ticket 4) must verify.\n\nHITL — one question at a time via /grilling and /domain-modeling.\n\n## Resolution\n\n**Leading candidate: the null hypothesis, confirmed and sharpened.** The\nintegration declares, the router enforces — and the declaration is a single\nflag. Grilled against router-side host config (fails on knowledge: only the\ntracker knows its public line is \"all GET pages except `/new`, plus GET\n`/api/*`\"), pass-everything-through (disqualified by the blob-viewer hazard —\nanonymous full admin), and dual/split mounts (forces integrations to split even\nwhen public and gated routes interleave, as the tracker's do).\n\nThe decisions:\n\n1. **Authority split** — the integration declares session-less reachability; the\n router enforces at dispatch. Host-side _narrowing_ overrides deferred to\n ticket 7.\n2. **The declaration is one coarse opt-in flag**, meaning \"safe to receive\n session-less traffic, period\" — not a route list or predicate. The\n integration's own per-route authorization (already required for standalone\n mode) draws the fine line, so there is no second, drift-prone copy of the\n route table. Default: unflagged = fully gated, at zero declaration cost.\n3. **Machine credentials pass through untouched.** The router never reads\n `Authorization`; a bearer request is just another session-less request, and\n the integration validates its own key (it's router-opaque anyway). No\n router-minted scheme — that would mean two secrets per headless client.\n4. **The ctx gains a login signal** so `user: null` stops conflating \"router has\n no login\" with \"visitor hasn't logged in\": conceptually the router tells the\n integration where login lives, or that it doesn't exist. Exact field\n name/shape belongs to the build effort.\n5. **Contradictions fail at startup**: `auth: false` plus an unflagged\n integration makes `createRouter` throw (like duplicate slugs). Escape hatch,\n if any, designed with ticket 7's host overrides.\n\n**How flag × integration type × router auth compose:**\n\n| | Type A — public docs (flag ✓, no internal checks) | Type B — tracker (flag ✓, internal checks) | Type C — blob viewer (no flag) |\n| ------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| **Router auth on** | Everyone reaches everything; login just adds a username it ignores | Anonymous get the public surface + a working log-in link; login unlocks role-gated routes; scripts hit the API with the tracker's key | Session-less traffic stopped at the router's front door; only logged-in (allowlisted) users get through |\n| **Router auth off** | Same — everyone reaches everything | Public surface and bearer API work; ctx says \"no login exists\" so no log-in link, role-gated routes unreachable — degraded but safe | **`createRouter` throws** — contradiction caught before anyone is exposed |\n\nThe flag isn't \"which type am I\" — type is expressed by flag + how much checking\nthe integration does itself (A: flag, no checks; B: flag, checks; C: no flag).\n\n**Load-bearing assumptions the spike (ticket 4) must verify:**\n\n1. Selective pass-through: anonymous reaches a flagged integration's public page\n while an unflagged one on the same router still shows the login wall — and\n login works alongside.\n2. A bearer-token non-GET API write completes through the gated router, headers\n and body intact, no redirects.\n3. The real tracker behind a router, visited anonymously, behaves exactly as\n standalone: public pages load, API reads work, `GET /new` still refuses.\n4. The login signal renders usefully: anonymous sees a working log-in link, and\n logging in through it returns with a session.\n5. std/oauth's origin-bound sessions (ticket 1 caveat) — check whether they bite\n in practice.\n\n(Decision 5 needs no spike — startup validation, no runtime unknown.)\n",[],[220,367,410],"07142fc1-ea74-46f6-9145-8ca156991104","002-requirements-inventory.md","15c020b6-7ef5-11f1-a76a-1607ee4eb77e",173,["D",1784043351081],3,"---\nid: 2\ntitle: Inventory real-integration auth requirements\nlabels: [wayfinder:research]\nstatus: closed\nassignee: nbbaier\nblocked-by: []\n---\n\n## Question\n\nWhat do the real integrations concretely need from fine-grained auth? Ground the\nauthority-split decision in actual cases, not hypotheticals. Read\n`~/Code/vt-projects/val-issue-tracker` and\n`~/Code/vt-projects/scoped-blob-viewer` (and the v1 archive's migration tickets)\nand enumerate:\n\n- The tracker's model: which surface is anonymous-readable standalone (viewer\n role), which is write-gated, how the bearer-token `/api` authenticates, and\n exactly what capability is lost behind a gated router today.\n- The blob viewer's model: all-or-nothing `owner` — does it want any\n fine-grained surface at all, or is it the \"fully gated integration\" case the\n model must also express cleanly?\n- Plausible headless-client cases: who calls the tracker's `/api` behind a\n router in practice, and with what credential?\n- From these, the requirements list the mechanism must satisfy — expressed as\n concrete \"this request, this credential, this expected outcome\" rows.\n\nOutput: a markdown summary linked from this ticket. AFK.\n\n## Resolution\n\nFull inventory:\n[Real-integration auth requirements\ninventory](../assets/002-requirements-inventory.md). Answers to the question's\nfour bullets:\n\n- **Tracker:** anonymous standalone surface = all GET HTML pages plus the entire\n GET `/api/*` (API reads bypass auth unconditionally) — but _not_ all GETs\n (`GET /new` is contributor-gated), so only the integration can draw the public\n line. Writes are per-route gates (contributor/manager/maintainer). `/api`\n non-GET requires a **static shared bearer key**\n (`options.apiKey ?? ISSUE_TRACKER_API_KEY`), plain string equality, no scopes\n — maintainer-equivalent power, and **router-opaque** (the router cannot\n validate it). Behind a gated router today, all of that is flattened: anonymous\n HTML reads, anonymous API reads, and the whole bearer write path die at the\n router's 401/302.\n- **Blob viewer:** genuinely all-or-nothing — no roles, no public subset, no\n machine credential; it is the \"fully gated integration\" case and should stay\n expressible at zero declaration cost. Hazard found: with `owner` omitted, its\n routed branch **skips the allowlist check entirely**, so any mechanism that\n passes session-less requests through without integration opt-in would hand\n anonymous visitors full blob admin. Strong evidence that session-less\n reachability must be integration-declared, default gated.\n- **Headless clients:** coding-agent sessions, CI scripts, and sibling\n vals/crons — all holding the one static env key, sending\n `Authorization: Bearer`, expecting JSON, following no redirects. Router can't\n validate the credential; a router-minted scheme would force two secrets per\n client (cost for ticket 003 to weigh).\n- **Requirements:** 12 scenario rows (R1–R12) plus six derived requirements in\n the asset. Headlines: per-route granularity (not per-integration, not \"all\n GETs\"); opt-in with gated default; machine credentials delivered to declared\n surfaces without OAuth; **anonymous ≠ ungated** — the tracker's `authUi` needs\n the ctx to distinguish \"session-less on a gated router\" from \"router has no\n auth\", which plain `ctx.user: null` conflates today; fully-gated default stays\n cheap; session-user behavior untouched.\n",[],[220,367,418],"5f2bba55-8f2e-4f71-aa4f-bf91dbf4ffaa","001-research-std-oauth-constraints.md","15db6c2c-7ef5-11f1-b292-1607ee4eb77e",175,["D",1784043351366],"---\nid: 1\ntitle: Research std/oauth constraints on selective gating\nlabels: [wayfinder:research]\nstatus: closed\nassignee: nbbaier\nblocked-by: []\n---\n\n## Question\n\nWhat does Val Town's std/oauth actually do with session-less requests, and does\nit permit per-route/selective gating at all? Read the middleware source\n(`https://esm.town/v/std/oauth/middleware.ts` and whatever it imports) and\nestablish the facts the mechanism decision depends on:\n\n- What does `oauthMiddleware(handler)` intercept before the wrapped handler runs\n — every request, only `/auth/*`, something else? Can the wrapped handler see a\n session-less request and choose to serve it anyway?\n- What do `getOAuthUserData` and the session cookie require — can the router\n call it outside `oauthMiddleware` and get `null` for anonymous requests\n without redirect/401 side effects?\n- Where does the login flow live (`/auth/login`, callback, state encryption) and\n what breaks if the router runs _unwrapped_ and mounts OAuth selectively?\n- Anything about the middleware that would fight a router that dispatches\n anonymous requests to some prefixes and demands a session for others.\n\nOutput: a markdown summary linked from this ticket (`wayfinder/assets/` or\nsimilar), stating each fact with a pointer to the source line that proves it.\nAFK.\n\n## Resolution\n\nFull findings:\n[std/oauth constraints on selective\ngating](../assets/001-std-oauth-constraints.md). Answers to the question's four\nbullets:\n\n- **What the middleware intercepts:** exactly six root-level paths by exact\n pathname match (`/auth/login`, `/auth/callback`, `/auth/logout`, `/auth/logo`,\n three static `/auth/client/*` files). Every other request — session or not —\n passes to the wrapped handler unmodified, with no 401, redirect, or session\n check anywhere on that path. The wrapped handler can freely serve session-less\n requests; v1's blanket 401 is router code, not a std/oauth constraint.\n- **`getOAuthUserData` outside the middleware:** fully independent and\n side-effect-free. Missing cookie, decrypt failure, or expiry all return `null`\n — no redirect/401. A router can call it unwrapped and treat `null` as\n anonymous. Caveat: decryption is origin-bound (key looked up per request\n origin, cached in memory ignoring origin), so sessions don't port across a\n val's multiple origins — a spike watch-item.\n- **Where the login flow lives:** hardcoded root-level `/auth/*` PKCE flow;\n client auto-registered per redirect URI; session cookie `vt_session` (Path=/,\n HttpOnly, Secure, SameSite=None, 30d). Exact-match routing means a\n prefix-mounted integration can never expose its own auth routes — OAuth must\n be mounted once, at the router root. An unwrapped router loses login entirely\n on that origin, though `getOAuthUserData` still works.\n- **What would fight selective dispatch:** nothing. std/oauth never reads\n `Authorization` headers (bearer coexistence is free) and holds no gating\n authority — all of it already sits behind the middleware. The null hypothesis\n is unopposed at this layer.\n",[],[220,367,427],"02bfc32c-ad0e-4e0f-a307-a1f723ccc45b",140,["D",1783972651716],[295,296,297,298,299,300,301,302,303],[220,367],"916ae06e-b639-436b-a7f7-046bb1964887","e775649c-7f0c-11f1-bafc-1607ee4eb77e","b6fe4ec8-7ef8-11f1-b47f-1607ee4eb77e",179,["D",1784043351663],"# Can the router identify the val owner at runtime?\n\nResearch summary for ticket\n[Can the router identify the val owner at\nruntime?](../tickets/009-identify-val-owner-at-runtime.md). Sources read\n2026-07-13. Imports are unversioned in real usage; the pinned versions below are\nwhat the current `-main` redirect resolved to, and content may drift.\n\nPrimary sources:\n\n- `std/utils` re-exports — https://esm.town/v/std/utils@283-main/index.ts\n- `std/utils` `parseVal` —\n https://esm.town/v/std/utils@283-main/parseImportMeta.ts\n- `std/oauth` callback (`isOrgMember`) —\n https://esm.town/v/std/oauth@233-main/middleware/index.ts (public\n `middleware.ts` just `export * from \"./middleware/index.ts\"`)\n- `std/oauth` session type — https://esm.town/v/std/oauth@233-main/session.ts\n- Docs — Environment variables\n https://docs.val.town/reference/environment-variables/ and Runtime\n https://docs.val.town/reference/runtime/\n\n---\n\n## Q1. Is the executing val's OWNER handle available at runtime without a login? — YES\n\nThe owner handle is exposed through an auto-injected environment variable,\n`VALTOWN_ENTRYPOINT`, and parsed by the standard `parseVal()` helper. No login,\nno session, no request context is required — it is present in the isolate's\nenvironment.\n\nProof, `parseImportMeta.ts` (std/utils@283-main):\n\n```ts\nexport function parseVal(metaImportUrl: string = Deno.env.get(\"VALTOWN_ENTRYPOINT\") || \"\"): Val {\n const pattern =\n /^https:\\/\\/esm\\.town\\/(v|p)\\/([^/]+)\\/([^@]+)@(\\d+)-(.+?)(\\/.*)?$/;\n const match = metaImportUrl.match(pattern);\n if (!match) throw new Error(`Invalid ESM Town URL format: ${metaImportUrl}`);\n let [, prefix, username, name, version, branch, path = \"\"] = match;\n ...\n return { username, name, version, branch, path, links: {...} };\n}\n```\n\n- `VALTOWN_ENTRYPOINT` holds the entrypoint module URL of the running\n deployment, shape\n `https://esm.town/v//@-/...`. `parseVal()`\n regex-captures `username` = **the owner handle of the entrypoint (host) val**,\n plus `name`, `version`, `branch`. Source: the default parameter\n `Deno.env.get(\"VALTOWN_ENTRYPOINT\")` and the capture group `([^/]+)` →\n `username` (parseImportMeta.ts).\n- Called with no argument it reads `VALTOWN_ENTRYPOINT`, i.e. the **entrypoint**\n val — the top-level deployed val the request is running against, not whichever\n imported module the call sits in. So for the router, `parseVal().username` is\n the router/host val's owner. (parseImportMeta.ts, default arg + docstring:\n \"Defaults to `Deno.env.get(\"VALTOWN_ENTRYPOINT\")`\".)\n- It is available with **no login**: it is `Deno.env`, read synchronously, with\n no reference to the request, cookie, or session.\n\nCaveat on documentation: `VALTOWN_ENTRYPOINT` is **not listed in the public\ndocs**. The Environment variables page\n(https://docs.val.town/reference/environment-variables/) and the Runtime page\n(https://docs.val.town/reference/runtime/) do not enumerate auto-injected\nvariables at all. The evidence that it exists and is populated at runtime is\nthat (a) `std/utils.parseVal()` defaults to it, and (b) `std/oauth`'s login\ncallback calls bare `parseVal()` in production and would throw\n`Invalid ESM Town URL format` on an empty string if it were unset — see Q2. That\nis strong primary evidence of an undocumented-but-relied-upon platform env var,\nnot an official contract.\n\nWhat is NOT available: no documented `std` API returns \"the owner\" as a named\nfield, and nothing in the HTTP request/`Request` object carries it. The only\nruntime source of the owner handle is `VALTOWN_ENTRYPOINT` (directly, or via\n`parseVal().username`).\n\n---\n\n## Q2. What is `isOrgMember` computed from? Does it mean \"logged-in user owns this val,\" including personal vals? — It TRUE-s for the personal-val owner, but it is an OR that also includes org membership; the name/docstring understate it.\n\nComputing code, `handleCallback` in middleware/index.ts (std/oauth@233-main),\nruns once at `/auth/callback` after the token exchange:\n\n```ts\nconst client = new ValTown({ bearerToken: tokens.access_token });\nconst orgHandle = parseVal().username;\nconst [me, userOrgs] = await Promise.all([\n client.me.profile.retrieve(),\n Array.fromAsync(client.orgs.list({})),\n]);\nconst isOrgMember = me.username === orgHandle ||\n userOrgs.some((o) => o.username === orgHandle);\n```\n\nDecomposition, term by term (all from the block above):\n\n- `orgHandle = parseVal().username` — the **owner handle of the running\n (entrypoint) val** (same VALTOWN_ENTRYPOINT source as Q1). It is named\n \"orgHandle\" but is literally just the val owner's handle, whether that owner\n is an org or a personal account.\n- `me` = the **logged-in user's** profile (`client.me.profile.retrieve()` using\n the user's freshly minted access token).\n- `userOrgs` = the orgs the logged-in user belongs to (`client.orgs.list`).\n- `isOrgMember` is a **disjunction**:\n 1. `me.username === orgHandle` → true exactly when **the logged-in user IS the\n val's owner** (their personal handle equals the val-owner handle). This is\n the personal-val case, and it is TRUE.\n 2. `userOrgs.some(o => o.username === orgHandle)` → true when the val is owned\n by an **org the logged-in user is a member of**.\n\nTherefore, on a **personal val whose owner belongs to no org**: disjunct 2 is\nfalse (the owner handle is a user, never in the user's org list), but disjunct 1\nis `me.username === orgHandle`, which is **true precisely for the owner** and\nfalse for everyone else. So `isOrgMember` is NOT meaningless for personal vals —\nit correctly resolves to \"this logged-in user is the owner.\" The field name and\nthe session docstring (\"Whether the user is a member of this val's org, checked\nat login time\", session.ts) undersell it: the code makes it \"owner-of-the-val OR\nmember-of-the-val's-org.\"\n\nReliability caveats (source-backed):\n\n- **It is frozen at login time, not per request.** session.ts comment: \"checked\n at login time\"; `createSessionData` stores `isOrgMember` into the payload that\n `encryptSession` seals into the 30-day cookie (session.ts). If val ownership\n or org membership changes after login, the cookie's `isOrgMember` is stale\n until re-login.\n- **It is optional.** `isOrgMember?: boolean` (session.ts `SessionData`); it may\n be `undefined`.\n- **It conflates owner with org co-member.** For an org-owned val, ANY org\n member gets `true`, not just the specific owner. If the router needs strictly\n \"is the owner\" and not \"is any org co-member,\" `isOrgMember` is too broad.\n\nBecause of all three, the more robust primary-source route for the router is to\n**recompute the owner match itself, fresh, each request**:\n`getOAuthUserData(req).user.username === parseVal().username`. Both operands\ncome from primary APIs already established (getOAuthUserData in asset 001;\nparseVal/VALTOWN_ENTRYPOINT in Q1), it is not frozen at login, and it is exactly\n\"owner,\" not \"owner-or-org-member.\"\n\n---\n\n## Q3. Can the router identify the owner from primary sources alone, or is a live login probe required? — ANALYTICALLY realizable from primary sources alone.\n\n- The **owner handle** is obtainable at runtime with zero login via\n `Deno.env.get(\"VALTOWN_ENTRYPOINT\")` → `parseVal().username` (Q1).\n- \"Is this logged-in user the owner?\" reduces to a **string equality** the\n router can compute itself:\n `getOAuthUserData(req)?.user.username === parseVal().username`. Both sides are\n primary-source-established. No additional platform capability is needed.\n- The platform already performs exactly this comparison in `std/oauth` (disjunct\n 1 of `isOrgMember`), which independently corroborates that the mechanism\n works.\n\nSo implicit-owner does **not** require a HITL login probe to be _designed or\njustified_ — it is realizable analytically. A login probe in\n`nbbaier/wayfinder-auth-spike` would only _empirically confirm_ two things the\nsources already imply: (a) `VALTOWN_ENTRYPOINT` is in fact populated in the\nrouter's own deployment/isolate (it is undocumented, Q1), and (b) the handle\nstrings match casing/format between `user.username` and the parsed `username`.\nThose are verification niceties, not blockers to the ADR.\n\nRecommended for the ADR: implement implicit-owner via the **direct per-request\ncomparison** (`user.username === parseVal().username`), NOT via the session's\n`isOrgMember`, because `isOrgMember` is frozen at login, optional, and broader\nthan \"owner\" (it also true-s for org co-members) — see Q2 caveats.\n\n---\n\n## Bottom line for the decision\n\n- **Owner handle at runtime, no login: available.**\n `Deno.env.get(\"VALTOWN_ENTRYPOINT\")` → `parseVal().username` yields the\n executing (entrypoint) val's owner handle with no session. Undocumented in\n public docs but relied on by std/utils and std/oauth (primary evidence).\n- **`isOrgMember`: TRUE for the personal-val owner** via disjunct\n `me.username === parseVal().username`, but it is an OR that also includes org\n membership, is computed once at login, is optional, and is broader than\n \"owner.\" Usable as a signal, but not the clean primitive.\n- **Implicit-owner is realizable ANALYTICALLY**, from primary sources alone, via\n the direct comparison\n `getOAuthUserData(req)?.user.username === parseVal().username`. No HITL login\n probe is required to justify it; a probe only empirically confirms\n VALTOWN_ENTRYPOINT is populated and the handles match string-for-string. Do\n NOT downgrade to explicit self-listing.\n",[],[220,447,359],"assets","9fe3a739-f65d-445d-90f6-c7d2366b0abb","1ddd8c44-7ef9-11f1-a862-1607ee4eb77e",181,["D",1784043351873],"# Real-integration auth requirements inventory\n\nResearch asset for [ticket 002](../tickets/002-requirements-inventory.md). Facts\ngathered from `~/Code/vt-projects/val-issue-tracker`,\n`~/Code/vt-projects/scoped-blob-viewer`, the v1 archive\n(`docs/wayfinder-archive/integrations-v1/`), and the current contract\n(`router.ts` in this repo). File:line citations refer to those repos at time of\nwriting (2026-07-13).\n\n## 1. The tracker's model (val-issue-tracker)\n\n**Roles.** Three, computed per-request, never persisted: `viewer` /\n`contributor` / `maintainer` (`app.tsx:43`, resolution at `app.tsx:117-145`).\nMaintainers = the running val's owner + `options.maintainers`; logged-in\nnon-maintainers get `defaultRole` (default `contributor`). Identity is a bare\nVal Town handle string.\n\n**Anonymous-readable surface, standalone.** Anonymous visitors are assigned\n`viewer` (`app.tsx:142`) — this is the public-read mode, hardcoded, cannot be\nturned off. Readable without a session:\n\n- all GET HTML pages: `/` (issue list), `/issue/:id` (detail + comments),\n `/labels`, `/source`;\n- the **entire GET `/api/*` surface** — API reads bypass auth unconditionally\n (`api.ts:97`).\n\nNot anonymous-readable: `GET /new` (form render is contributor-gated). So the\npublic surface is _not_ \"all GETs\" — the tracker's own role model draws the\nline, per-route.\n\n**Write gating.** Per-route imperative gates, not middleware: `contributor()`\n(create/comment), `manager()` (maintainer OR issue-creator, for\nedit/close/label), `maintainer()` (delete, label admin) (`app.tsx:161-195`). All\nauthorization lives in `app.tsx`; the store does none. In routed mode a rejected\nviewer gets **403, never a redirect to `/auth/login`** (ADR 0002\nLocation-rewriting makes that a 404 under a prefix; decided in v1 ticket 004).\n\n**Bearer-token `/api`.** JSON API at `/api` (`api.ts`). Non-GET requires\n`Authorization: Bearer ` matching a **single static shared secret** —\n`options.apiKey ?? Deno.env.get(\"ISSUE_TRACKER_API_KEY\")` — by plain string\nequality (`api.ts:106-112`). No scopes, no issuance/rotation: a valid key grants\n**all** write operations (maintainer-equivalent). The `actor` field in request\nbodies is free-text provenance, not authorization (`api.ts:115`). Crucially:\n**the credential is integration-local — the router has no way to validate it.**\n\n**What a gated router flattens today.** The v1 router 401s (GET → login page) or\n302s (non-GET → home) every session-less request before dispatch\n(`router.ts:251-259`). Lost behind a gated router:\n\n1. all anonymous HTML reads (the viewer role — nobody without a Val Town session\n can even see the issue list);\n2. all anonymous `GET /api/*` reads;\n3. **the entire bearer-token write path** — headless clients hold the API key\n but no OAuth session, so the router turns them away before the tracker sees\n the `Authorization` header. v1 ticket 004 accepted this as \"stacked gates:\n headless agents target a standalone or ungated mount.\"\n\n**A ctx nuance the mechanism must preserve or improve.** The tracker's `authUi`\nflag (`app.tsx:124`) shows login/logout UI only where a working login flow\nexists. Today `ctx.user: null` means \"ungated router — no login flow, hide the\nUI, everyone is viewer.\" Under fine-grained auth a _gated_ router would also\ndeliver session-less requests (to public routes) — and there a login flow\n**does** exist and the UI should show \"Log in.\" So the context must let an\nintegration distinguish **\"anonymous, but login is available\"** from **\"no auth\nat all\"** — plain `ctx.user: null` currently conflates them.\n\n## 2. The blob viewer's model (scoped-blob-viewer)\n\n**All-or-nothing, and it wants to stay that way.** Single owner-allowlist gate\nin one `app.use(\"*\")` middleware (`app.tsx:349-380`); no roles, no read-only\ntier, no anonymous surface, no machine/API credential of any kind. Every route —\nincluding `/raw` byte serving — sits behind the session gate. An admin panel\nover the host val's blob storage has no meaningful public-read subset. **This is\nthe \"fully gated integration\" case: the model must express it cleanly, ideally\nas the zero-declaration default.**\n\n**Routed behavior.** Trusts `ctx.user` for authentication, applies its own\n`owners` allowlist on top; the `null` user of an ungated router cannot satisfy a\nnon-empty allowlist → 403 (`app.tsx:357-366`).\n\n**A hazard for pass-everything-through designs.** When `owner` is omitted,\n`owners` is `null` and the routed branch **skips the check entirely** — \"any\nlogged-in user\" semantics are implemented as _no check_ (`app.tsx:361`:\n`if (owners && ...)`). Today the gated router guarantees `ctx.user` is a real\nsession user, so that's safe. If a v2 router started passing session-less\nrequests through with a null-ish user and no opt-in from the integration, an\nowner-less blob viewer would grant **anonymous visitors full admin**\n(read/write/delete blobs). Existing integrations were written assuming the\nrouter's wall; any mechanism that lowers it must be **opt-in per integration**\n(evidence for the null hypothesis's integration-declares side, against pure\nrouter-side or pass-through-by- default shapes).\n\n## 3. Plausible headless-client cases\n\nWho actually calls the tracker's `/api` behind a router, with what credential:\n\n- **Coding-agent sessions** (the dominant real case — e.g. wayfinder/\n blueprint-style workflows driving an issue tracker): create/close/comment on\n issues via `ISSUE_TRACKER_API_KEY` as a bearer token. No browser, no OAuth\n session, key supplied via env.\n- **CI/scripts**: a repo's automation filing or closing issues on merge — same\n static bearer key.\n- **Sibling vals / crons on the same account**: a scheduled val posting status\n issues — holds the env key, not a session.\n\nCommon shape: one long-lived static secret per tracker instance, sent as\n`Authorization: Bearer`, expecting JSON in and out, **no redirect-following and\nno cookie jar** — a 302-to-login response is indistinguishable from failure. The\nrouter cannot validate this credential (it's the integration's secret), which\nconstrains the machine-credential design: either the router passes unrecognized\n`Authorization` headers through to a surface the integration declared\nmachine-reachable, or the router mints its own credential and headless clients\nmust hold **two** secrets (router's + the tracker's key) — a real cost to weigh\nin ticket 003.\n\n## 4. Requirements the mechanism must satisfy\n\nScenario rows. Setup: v1-style router, **auth on** (default gate: any logged-in\nVal Town user), tracker mounted at `/issues`, blob viewer at `/blobs`. \"Today\" =\nv1 behavior; \"Required\" = what fine-grained auth must produce.\n\n| # | Request | Credential | Today | Required outcome |\n| --- | ------------------------------------------------------- | --------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |\n| R1 | `GET /issues/` (issue list) | none | 401 login page | 200, tracker renders as `viewer`, login UI visible |\n| R2 | `GET /issues/issue/42` | none | 401 login page | 200, read-only detail view |\n| R3 | `GET /issues/api/issues` | none | 401 login page | 200 JSON (tracker's API reads are public) |\n| R4 | `POST /issues/new` (form write) | none | 302 home | rejected — 403 (or router-level equivalent); never a write, never a login redirect loop for HTML |\n| R5 | `POST /issues/api/issues` | valid tracker bearer key | 302 home (flattened) | 201, issue created — key validated **by the tracker**, no OAuth session involved |\n| R6 | `POST /issues/api/issues` | invalid bearer key | 302 home | 401 JSON from the tracker (not a login HTML page) |\n| R7 | `GET /issues/` | valid Val Town session | 200, role per maintainers/defaultRole | unchanged |\n| R8 | `POST /issues/issue/42/close` | session, contributor, not creator | 403 from tracker | unchanged (role model untouched for session users) |\n| R9 | `GET /blobs/` | none | 401 login page | **still 401 login page** — fully gated integration is unaffected, ideally with zero new declarations |\n| R10 | `GET /blobs/` or `/blobs/raw?...` | any bearer token | 401/302 | still rejected — an unrecognized machine credential must not grant entry anywhere the integration didn't declare machine-reachable |\n| R11 | `GET /auth/login` → OAuth flow | — | works | unchanged — std/oauth login must coexist with the pass-through paths (spike watch-item) |\n| R12 | `GET /issues/` on an **ungated** router (`auth: false`) | none | 200 as viewer, login UI hidden | unchanged — and distinguishable from R1's \"anonymous on a gated router\" so the tracker can show/hide login UI correctly |\n\nDerived requirements list:\n\n1. **Per-route granularity, not per-integration.** The tracker needs public\n reads _and_ gated writes on the same integration (R1–R4 vs R8). A\n per-integration public/private bit is insufficient. The boundary is not\n expressible as \"all GETs\" either (`GET /new` is gated) — the integration is\n the only party that knows its public surface.\n2. **Opt-in, default gated.** Integrations written under v1 assume the router's\n wall (blob viewer's owner-less mode would be anonymous-admin otherwise).\n Session-less reachability must be something an integration declares, never\n something the router grants unilaterally (R9, §2).\n3. **Machine credentials reach the integration unauthenticated by the router.**\n The tracker's bearer key is integration-local and router-opaque; the\n mechanism must deliver the `Authorization` header to a declared surface\n without demanding an OAuth session (R5–R6), and machine responses must stay\n JSON (no login-HTML or redirect responses to bearer clients).\n4. **Anonymous ≠ ungated.** The context must distinguish \"session-less request\n admitted to a public surface of a gated router\" from \"router has no auth at\n all\" (R1 vs R12) — the tracker's `authUi` depends on it.\n5. **The fully gated integration stays the cheap default** (R9): zero or\n near-zero declaration cost, no behavior change.\n6. **Session-user behavior is untouched** (R7, R8, R11): roles, allowlists, and\n the std/oauth flow work exactly as in v1.\n",[],[220,447,418],"95a6bc9c-bb8e-4036-857a-3e7607b15d63","001-std-oauth-constraints.md","b70fa7cc-7ef8-11f1-b47f-1607ee4eb77e",178,["D",1784043351775],"# std/oauth constraints on selective gating\n\nResearch summary for ticket\n[Research std/oauth constraints on selective\ngating](../tickets/001-research-std-oauth-constraints.md). Sources read\n2026-07-13 (unversioned imports — content may drift):\n\n- `middleware/index.ts` —\n https://www.val.town/x/std/oauth/code/middleware/index.ts (the public\n `middleware.ts` just re-exports it)\n- `session.ts` — https://www.val.town/x/std/oauth/code/session.ts\n- `oauth.ts` — https://www.val.town/x/std/oauth/code/oauth.ts\n- `crypto.ts` — https://www.val.town/x/std/oauth/code/crypto.ts\n\n## F1. The middleware gates nothing — every non-`/auth/*` request passes through\n\n`createMiddleware` (middleware/index.ts) is a plain dispatcher. It special-cases\nexactly six paths by **exact pathname match** and hands everything else to the\nwrapped handler unmodified:\n\n```js\nif (url.pathname === \"/auth/login\") return handleLogin(req, opts);\nif (url.pathname === \"/auth/callback\") return handleCallback(req);\nif (url.pathname === \"/auth/logout\") return handleLogout(req);\nif (url.pathname === \"/auth/logo\") return handleLogo(url);\nif (authFileRoute) return handleAuthFile(authFileRoute); // 3 static /auth/client/* files\nreturn appFetch(req);\n```\n\nThere is **no 401, no redirect, no session check anywhere on the pass-through\npath**. A session-less request to any app route reaches the wrapped handler,\nwhich is free to serve it. The v1 router's blanket 401 of session-less requests\nis therefore the _router's own code_, not a std/oauth constraint.\nSelective/per-route gating is not just permitted — it's the only gating model\nstd/oauth supports (the skill doc confirms: \"There's no built-in 'require login'\nhelper\").\n\n## F2. `getOAuthUserData` is side-effect-free and works unwrapped\n\n`getOAuthUserData(req)` (middleware/index.ts) reads the `vt_session` cookie; if\nabsent it returns `null` immediately. On decrypt failure it logs and returns\n`null`. `decryptSession` (session.ts) additionally returns `null` on expiry and\ncatches all parse/decrypt errors. No redirect, no 401, no response mutation, no\ndependence on running inside `oauthMiddleware`. A router can call it on any\nrequest — wrapped or not — and treat `null` as \"anonymous\" with zero side\neffects. This directly supports passing `ctx.user: null` through to\nintegrations.\n\n## F3. Sessions are origin-bound via the encryption-key lookup\n\n`getOAuthUserData` derives\n`redirectUri = new URL(req.url).origin +\n\"/auth/callback\"` from the **incoming\nrequest** and passes it to `decryptSession`. The AES-GCM key (crypto.ts,\n`getOrCreateEncryptionKeyMaterial`) comes from, in order:\n\n1. `OAUTH_STATE_ENCRYPTION_KEY` env var (if set),\n2. blob `oauth_encryption_key:${redirectUri}` in the **running val's** blob\n storage,\n3. freshly generated 32-byte key, persisted to that blob.\n\nConsequences:\n\n- **In-process routing is trivially fine**: if the router dispatches integration\n code inside its own val, everything shares the router's origin and blob\n storage — any code in the process can decrypt the session.\n- **Cross-val session sharing does not work by default**: a separately deployed\n integration val has a different origin (browser won't send the cookie) and\n different key material. Sharing would require same origin plus a shared\n `OAUTH_STATE_ENCRYPTION_KEY`.\n- **Caching caveat for the spike**: `cachedEncryptionKey` is cached in memory\n _ignoring_ `redirectUri`. If one isolate serves two origins (e.g. custom\n domain + `*.val.run`), the first origin's key gets reused for the second,\n decrypt fails, and `getOAuthUserData` returns `null` — sessions silently don't\n port across origins of the same val.\n\n## F4. The login flow is hardcoded to root-level `/auth/*` — one OAuth wrapper per origin\n\n`handleLogin`/`handleCallback` (middleware/index.ts) implement a PKCE flow\nagainst `https://val.town`, with the client auto-registered per `redirectUri`\nvia Dynamic Client Registration and cached in blob\n(`oauth_client:${redirectUri}`, oauth.ts). State is encrypted with the same\norigin-scoped key, 10-minute expiry. The callback sets `vt_session`\n(`Path=/; HttpOnly; Secure; SameSite=None; Max-Age=30d`).\n\nBecause route matching is exact (`url.pathname === \"/auth/login\"`), a\nprefix-mounted integration (`/tracker/auth/login`) can **never** hit its own\nmiddleware's auth routes. So on a routed origin, OAuth must be mounted once, at\nthe router level, at the root — integrations behind the router cannot run their\nown `oauthMiddleware` meaningfully. Conversely, a router running _unwrapped_\nloses login entirely on that origin (no `/auth/*` routes exist), though\n`getOAuthUserData` itself would still function.\n\n## F5. Bearer tokens are invisible to the middleware — coexistence is free\n\nNothing in std/oauth reads or writes the `Authorization` header. The only\ncredential it knows is the `vt_session` cookie. A bearer-token request to any\nnon-`/auth/*` path passes straight through (F1) with its header intact. Any 401\na machine client sees today is router code. The middleware imposes no constraint\non the machine-credential design — router-defined scheme vs. pass-through is a\nfree choice for the mechanism ticket.\n\n## F6. Minor API facts\n\n- `oauthMiddleware(appFetch)` or `oauthMiddleware(opts, appFetch)`; opts are\n `clientName` and `scopes` (default scopes\n `\"openid offline_access profile user_r\"`).\n- Session payload includes `user`, `accessToken` (a Val Town API token acting as\n the user), optional `refreshToken`/`idToken`, `expiresAt`, and `isOrgMember`\n (computed once at callback time against the val's owner org).\n- `SameSite=None` on the session cookie — sessions survive cross-site/iframe\n contexts; login has a framed variant (`sec-fetch-dest: iframe`).\n\n## Bottom line for the mechanism decision\n\nstd/oauth does not fight the null hypothesis at all. The middleware is a\nlogin-flow provider plus a nullable session reader; **all** gating authority\nalready sits with the code behind it. The router can wrap once at the root, call\n`getOAuthUserData` per request, dispatch anonymous requests (`ctx.user: null`)\nto declared-public surfaces, and pass `Authorization` headers through untouched.\nThe load-bearing runtime unknowns left for the spike are the origin/key-caching\nnuance (F3) and end-to-end login coexisting with anonymous + bearer traffic on\none router.\n",[],[220,447,456],"499e72d9-c820-45ab-bd89-a13ddef3c6fc",147,["D",1783974211223],[291,292,293],[220,447],["D",1783972651469],[290,294,304],[220],"295c1aa9-de77-4bc2-a23b-7dd9f5b19477","hello_test.ts","f0100e98-7d47-11f1-af4f-1607ee4eb77e",257,["D",1784051707472],"import { assert, assertEquals } from \"@std/assert\";\nimport { createRouteHandler } from \"../router.ts\";\nimport helloStandalone, { helloWorld } from \"./hello.ts\";\n\nDeno.test(\"hello-world greets the routed user with relative links\", async () => {\n // \"hello\" is unflagged, so on an auth:false router it must be knowingly\n // force-mounted through the escape hatch — bare, construction would throw\n // (ticket 05). Silence the one-time startup log it emits.\n const warn = console.warn;\n console.warn = () => {};\n let handler;\n try {\n handler = createRouteHandler(\n { integrations: [helloWorld()], auth: false, allowUnflagged: [\"hello\"] },\n () => Promise.resolve({ user: \"nbbaier\", owner: null }),\n );\n } finally {\n console.warn = warn;\n }\n // auth: false leaves ctx.user null, so inject the user via the test seam's\n // dispatch instead: call the integration the way the router does.\n const res = await helloWorld().handler(new Request(\"https://example.com/\"), {\n user: \"nbbaier\",\n prefix: \"/hello\",\n login: \"/auth/login\",\n });\n const body = await res.text();\n assert(body.includes(\"@nbbaier\"));\n assert(body.includes(`href=\"about\"`));\n assert(\n !body.includes(`href=\"/`),\n \"links must be relative, not root-absolute\",\n );\n\n const routed = await handler(new Request(\"https://example.com/hello/about\"));\n assertEquals(routed.status, 200);\n assert((await routed.text()).includes(`href=\"./\"`));\n});\n\nDeno.test(\"hello-world works standalone with the subject fallback\", async () => {\n const res = await helloStandalone(new Request(\"https://example.com/\"));\n assertEquals(res.status, 200);\n assert((await res.text()).includes(\"world\"));\n\n const custom = await helloWorld({ subject: \"Val Town\" }).handler(\n new Request(\"https://example.com/\"),\n );\n assert((await custom.text()).includes(\"Val Town\"));\n});\n",[],[227,472],"7325d148-6081-4f02-bced-9a29415b510b","hello.ts","f004bfac-7d47-11f1-9667-1607ee4eb77e",185,["D",1784043352529],"// The worked example. See ./README.md for a walkthrough; copy this file to\n// start your own integration.\nimport { defineIntegration } from \"../mod.ts\";\n\nexport interface HelloWorldOptions {\n subject?: string;\n}\n\nexport function helloWorld(options: HelloWorldOptions = {}) {\n const subject = options.subject ?? \"world\";\n return defineIntegration({\n name: \"Hello World\",\n slug: \"hello\",\n description: \"The smallest possible integration — the worked example.\",\n requiredEnv: [\"HELLO_GREETING\"],\n handler: (req, ctx) => {\n const greeting = Deno.env.get(\"HELLO_GREETING\") ?? \"Hello\";\n const who = ctx?.user ? `@${ctx.user}` : subject;\n const body = new URL(req.url).pathname === \"/about\"\n ? `

A toy integration.

back

`\n : `

${greeting}, ${who}!

about

`;\n return new Response(`${body}`, {\n headers: { \"Content-Type\": \"text/html; charset=utf-8\" },\n });\n },\n });\n}\n\nexport default helloWorld();\n",[],[227,480],"ea1eb4f0-a41d-4a0b-83fd-89d05b2bc036","de3d453e-7d4f-11f1-a875-1607ee4eb77e",131,["D",1783792711187],"# The worked example\n\n[`hello.ts`](hello.ts) is the smallest honest integration — every line is\ncontract surface, not app logic. Copy it to start your own, and read this file\nalongside it. For the full contract, see the [top-level README](../README.md).\n\n## Walkthrough\n\n**The factory.** Authors export an `(options) => Integration` factory, not a\nbare `Integration`:\n\n```ts\nexport function helloWorld(options: HelloWorldOptions = {}) {\n```\n\nAll configuration lives in the closure (`subject` here), never on the\n`Integration` object. Take an options bag even when you need no config\n(`options = {}`) so the calling convention stays uniform across integrations.\n\n**The contract object.** `defineIntegration` takes the metadata plus a handler:\n\n```ts\nreturn defineIntegration({\n\tname: \"Hello World\",\n\tslug: \"hello\",\n\tdescription: \"…\",\n\trequiredEnv: [\"HELLO_GREETING\"],\n\thandler: (req, ctx) => { … },\n});\n```\n\n- `slug` is where the router mounts you (`/hello/`). It must match\n `^[a-z0-9-]+$` and avoid the reserved slugs; `defineIntegration` throws at\n construction if it doesn't.\n- `requiredEnv` lists the env vars you read. Unset ones badge the router's\n directory page — they never block the integration.\n\n**Read env at request time.**\n\n```ts\nconst greeting = Deno.env.get(\"HELLO_GREETING\") ?? \"Hello\";\n```\n\nRead env vars inside the handler, never at import time. Import-time reads run\nbefore the val's environment is available and break standalone mounting.\n\n**The dual-mode idiom.**\n\n```ts\nconst who = ctx?.user ? `@${ctx.user}` : subject;\n```\n\n`ctx` is present when routed, absent when standalone — its absence is how the\nhandler knows no router is in front of it. `ctx?.user` is the router-provided\nVal Town username; fall back to your own default when it's missing.\n\n**Relative links only.**\n\n```ts\n`about`; // not href=\"/about\"\n```\n\nRelative URLs resolve inside the mount prefix when routed and at the root when\nstandalone, with no branching. Root-absolute paths (`/about`) break under a\nmount — see the top-level README's prefix rules and\n[ADR 0002](../docs/adr/0002-location-header-rewriting.md).\n\n**Standalone export.**\n\n```ts\nexport default helloWorld();\n```\n\nBecause `defineIntegration` returns a _callable_ integration, the same value is\nboth an `Integration` (for `createRouter`) and an HTTP handler (as a val's\ndefault export). One factory return value, two mounting modes — see\n[ADR 0003](../docs/adr/0003-callable-integrations.md).\n\n## Testing\n\n[`hello_test.ts`](hello_test.ts) exercises both modes:\n\n- **Routed** — via `createRouteHandler`, the OAuth-free test seam, with a user\n injected. It asserts the routed user is greeted and that links stay relative.\n- **Standalone** — call the default export (and the factory with a custom\n `subject`) directly, with no `ctx`, and check the fallback subject.\n",[],[227,179],["D",1783788334625],[286,287,288],[227],"dc2ce713-2a27-4288-a862-e61bfee630e1","273b54e6-7cb1-11f1-9d45-1607ee4eb77e","b0f10802-7d51-11f1-bd58-1607ee4eb77e",200,["D",1784043354970],11,"---\ntitle: Integrations v1 — contract + meta-router for Val Town project integrations\nlabels: [wayfinder:map]\nstatus: closed\n---\n\n## Destination\n\nA working v1 of the `integrations` val: a published `Integration` contract\n(`Integration` type, `defineIntegration`, `createRouter`) with\n`val-issue-tracker` and `scoped-blob-viewer` fully migrated onto it, a toy\nhello-world integration, and README contract docs for third-party authors.\n\n## Notes\n\n- **This map carries execution.** The destination is working code, so tickets\n build and migrate, not just decide.\n- Domain: Val Town platform (Deno runtime, scoped SQLite/blob, std/oauth).\n Sessions should consult the `valtown:http-endpoints`, `valtown:oauth`,\n `valtown:sqlite-storage` skills, and use `find_val_town_skills` for anything\n platform-specific.\n- Ubiquitous language lives in `CONTEXT.md` (repo root) — consult it every\n session and maintain it via `/domain-modeling`: challenge drift, sharpen new\n terms inline as they crystallise. ADRs go in `docs/adr/` (created lazily),\n offered only for hard-to-reverse, surprising, real-trade-off decisions.\n- Repos (local working dirs): `~/Code/vt-projects/integrations` (this val,\n currently an empty `main.ts`), `~/Code/vt-projects/val-issue-tracker`,\n `~/Code/vt-projects/scoped-blob-viewer`.\n- Standing preferences from the charter session (2026-07-10):\n - Astro/vite-style composition: authors ship `(options) => Integration`\n factories; users write\n `createRouter({ integrations: [issueTracker({...})] })`. Options live in\n each factory's closure, never in the `Integration` type.\n - The router owns auth: one OAuth gate, `/auth/*` mounted once, user passed\n down. Design intent — pending runtime verification in the prototype.\n - Router serves a minimal directory page at `/` (name, description, link per\n integration, ⚠️ badge for missing `requiredEnv`). `/` and `/auth/*` are\n reserved paths; slugs validated against them and each other.\n - Both existing integrations migrate fully AND remain standalone-mountable\n (the factory serves both modes).\n - Biome is the canonical formatter (tab-indented), not `deno fmt`.\n- Tracker conventions (local markdown): tickets live in `wayfinder/tickets/`,\n one file each, frontmatter `id`, `title`, `labels`, `status: open|closed`,\n `assignee`, `blocked-by: [ids]`. Claim = set `assignee`. Frontier = open,\n unassigned, all `blocked-by` closed. Resolutions go in a `## Resolution`\n section on the ticket.\n\n## Decisions so far\n\n\n\n- [Prototype the dispatch architecture](tickets/001-prototype-dispatch-architecture.md)\n — in-process prefix mount\n ([ADR 0001](../../adr/0001-dispatch-architecture.md)): one origin,\n router-owned auth verified, hygiene = \"relative URLs only\" with\n router-enforced trailing-slash canonicalization.\n- [Pin the v1 contract](tickets/002-pin-the-v1-contract.md) —\n `handler(req, ctx)` with ctx-as-Hono-env alignment; router rewrites\n root-absolute `Location` headers\n ([ADR 0002](../../adr/0002-location-header-rewriting.md)); slugs\n `^[a-z0-9-]+$` with `[\"auth\", /^_/]` reserved, throw at construction; auth is\n a gate (`users` allowlist), not a role system.\n- [Build integrations v1](tickets/003-build-integrations-v1.md) — shipped:\n `mod.ts`/`router.ts` implement the contract with zero deviations, 14 tests\n green, live directory at this val's `main.ts` (login-gated, empty until the\n hello-world integration lands).\n- [Decide the publishing and versioning story](tickets/008-publishing-and-versioning.md)\n — unpinned `esm.town/.../mod.ts` imports + `?v=` escape hatch; breaking\n changes ship as a new entrypoint, never on `mod.ts`; post-v1, main is the\n release channel (branch + green `deno task check` to merge); val stays public.\n- [Migrate val-issue-tracker onto the contract](tickets/004-migrate-val-issue-tracker.md)\n — dual-mode via callable `defineIntegration`\n ([ADR 0003](../../adr/0003-callable-integrations.md)); `ctx.user` feeds the\n tracker's role model (null → read-only viewer, no login redirects in routed\n mode); bearer-token API gates stack behind a gated router; contract additions:\n `CallableIntegration` type, `createRouteHandler` made public as the test seam.\n Live at the integrations val's `/issues/`; answered the permission-model fog.\n- [Migrate scoped-blob-viewer onto the contract](tickets/005-migrate-scoped-blob-viewer.md)\n — dual-mode via callable `defineIntegration`, live at the integrations val's\n `/blobs/`; the prefix-hygiene stress test **passed with zero contract fights**\n (base-threaded links + root-absolute redirects rewritten per ADR 0002, no new\n contract surface). `owner` authorizes from `ctx.user` (all-or-nothing, no\n read-only role); JSX moved to `app.tsx` with `mod.ts` a JSX-free barrel so it\n type-checks locally — a lesson for ticket 7's docs.\n- [Add the hello-world example integration](tickets/006-hello-world-example-integration.md)\n — shipped `example/hello.ts`: a dependency-free `(options) => Integration`\n factory demonstrating the full contract (dual-mode `ctx?.user`, a\n genuinely-read `requiredEnv`, relative-only links), registered live in\n `main.ts`, tested both modes; kept out of `mod.ts` — it's the copyable worked\n example for ticket 7's docs.\n- [Write the third-party author docs](tickets/007-third-party-author-docs.md) —\n shipped `README.md` (both audiences) + `example/README.md` walkthrough; the\n explainability test passed with **zero contract changes**. Review pass also\n unified factory naming (`create*` → `issueTracker`/`blobAdmin`) across all\n three repos and restructured the val-issue-tracker README to the house\n standalone/routed shape. All three repos green. **Destination reached.**\n\n## Not yet specified\n\n\n\n## Out of scope\n\n- **Remixable template val** for integration authors — good idea, explicitly\n deferred past v1; revisit as a fresh effort once the contract has survived two\n real migrations.\n- **Full dashboard** at `/` (health checks, status, per-integration state) — v1\n ships the minimal directory page only.\n- **Auto-discovery** of sibling HTTP endpoints via `std/utils` `listFiles` —\n only interesting under the redirect architecture; not part of v1 either way.\n- **Registry/marketplace** of third-party integrations.\n- **Machine-credential pass-through** — letting bearer-token clients traverse a\n gated router without an OAuth session (surfaced by the val-issue-tracker\n migration). v1 accepts stacked gates: headless agents target a standalone or\n ungated mount. Revisit only if a real integration can't live with that.\n- **Fine-grained auth for routed integrations** _(leading candidate for the next\n effort)_ — a gated router applies one all-or-nothing login wall at the front\n door, so an integration's own finer auth model is flattened when routed.\n Example: the issue tracker standalone allows anonymous public reads (the\n `viewer` role), but behind a gated router the login wall blocks anonymous\n visitors entirely, so that public-read capability is lost. v1's permission\n model is deliberately all-or-nothing (router authenticates, integration\n authorizes from `ctx.user`); expressing per-integration or per-route\n visibility — a public-read integration, or public-read + gated-write routes,\n on an otherwise-gated router — is a richer model beyond the v1 destination.\n Surfaced while writing the ticket-7 docs; revisit as a fresh map, not a\n resumption of this one.\n",[],[233,506,507,351],"wayfinder-archive","integrations-v1","7567a65a-a81e-4567-8044-474fa6d354df","b17b36ee-7d51-11f1-bf82-1607ee4eb77e",206,["D",1784043354774],"# Wayfinder archive — Integrations v1\n\nA completed wayfinder effort, archived here as a historical record. The map\nreached its destination on 2026-07-11; all tickets are closed.\n\n- [`map.md`](map.md) — the map: destination, decisions-so-far (the route\n walked), and out-of-scope notes.\n- [`tickets/`](tickets/) — the eight resolved tickets, each with its\n `## Resolution`.\n\n**Destination reached:** a working v1 of the `integrations` val — the published\n`Integration` contract (`defineIntegration`, `createRouter`), both\n`val-issue-tracker` and `scoped-blob-viewer` migrated onto it, a hello-world\nexample, and README author docs.\n\nThis effort is done; it is not resumed. The next effort (leading candidate:\n**fine-grained auth for routed integrations**, see the map's Out of scope\nsection) is a fresh wayfinder map, started at `wayfinder/` from a clean slate.\n",[],[233,506,507,179],"28063973-da7c-4d1b-962c-5b99865ef94a","008-publishing-and-versioning.md","7454ac76-7cb8-11f1-9441-1607ee4eb77e","b1080eee-7d51-11f1-b73f-1607ee4eb77e",193,["D",1784043353502],"---\nid: 8\ntitle: Decide the publishing and versioning story\nlabels: [wayfinder:grilling]\nstatus: closed\nassignee: nbbaier\nblocked-by: []\n---\n\n## Question\n\nGraduated from the map's \"Publishing/versioning story\" fog once the contract was\nbuilt. What does \"released\" mean for the `integrations` contract?\n\n- **Canonical import URL**: `https://esm.town/v/nbbaier/integrations/mod.ts`\n presumably — confirm, and decide whether docs recommend pinning (esm.town\n `?v=` versions) or tracking latest.\n- **Breaking-change policy for third parties**: the `Integration` type and the\n router's behavioral guarantees (ctx shape, Location rewriting, reserved slugs,\n trailing-slash canonicalization) are the public API. What's the compatibility\n promise, and where is it stated? (The `/^_/` reservation already encodes one\n forever-promise.)\n- **Val privacy/discoverability**: does the val need to be public/unlisted for\n third-party imports to resolve?\n\nSmall ticket; the answers feed the README (ticket 7), which must show real\nimport URLs and state the compatibility stance.\n\nHITL: grill briefly (/grilling).\n\n## Resolution\n\nDecided 2026-07-10 by grilling. Four parts:\n\n- **Canonical import**: `https://esm.town/v/nbbaier/integrations/mod.ts`,\n recommended **unpinned** (platform culture; bugfixes flow), with esm.town's\n `?v=NN` version pinning documented as the stability escape hatch.\n- **Stability promise** (goes in a README \"Stability\" section, ticket 7): the\n public API is the exported types plus the router's behavioral guarantees (ctx\n shape / `c.env` alignment, Location rewriting, trailing-slash\n canonicalization, reserved slugs incl. the forever-`/^_/` namespace). Additive\n changes land on `mod.ts` anytime; **breaking changes never land on `mod.ts`**\n — they ship as a new entrypoint (e.g. `v2/mod.ts`) with old semantics\n preserved.\n- **Branch discipline, post-v1**: unpinned imports track the val's main tip, so\n **main is the release channel and merge = release**. Contract-touching work\n happens on a branch (`vt checkout -b`); merge only with `deno task check`\n green; don't leave `vt watch` running against main while editing\n `router.ts`/`mod.ts`. Non-code files (`wayfinder/`, `docs/`, `CONTEXT.md`) are\n exempt. Layering: `?v=` protects downstream from deliberate change, branch\n discipline from accidental breakage — unpinned-by- default is only honest with\n both.\n- **Privacy**: the val is public (verified via API) and must stay\n public/unlisted for esm.town imports to resolve.\n",[],[233,506,507,367,516],"67fd1dc4-01c0-4942-81c0-49dfc720ed95","007-third-party-author-docs.md","272f2194-7cb1-11f1-81a5-1607ee4eb77e",199,["D",1784043354408],"---\nid: 7\ntitle: Write the third-party author docs\nlabels: [wayfinder:task]\nstatus: closed\nassignee: nico\nblocked-by: [4, 5, 8]\n---\n\n## Question\n\nWrite the `integrations` README for the two audiences: users mounting a router\n(`createRouter` quickstart) and authors building integrations (the contract —\n`Integration` fields, the factory convention, prefix rules, what the router\nprovides vs what authors must do, `requiredEnv`, reserved slugs), with the\nhello-world integration as the worked example.\n\nBlocked on both migrations deliberately: the docs are the explainability test of\na contract that survived two real apps. If a rule needs a wall of caveats to\ndocument, that's feedback for the contract, not prose to polish — surface it\nrather than shipping it.\n\nSurface added by the ticket-4 migration, to be covered too:\n\n- Callable integrations (ADR 0003): `defineIntegration` returns a value that is\n both an `Integration` and a standalone HTTP handler — the dual-mode story for\n authors.\n- `createRouteHandler` as the public, OAuth-free test seam (mount your\n integration under a real router with an injected user).\n- Permission composition: the router authenticates, the integration authorizes\n from `ctx.user`; `ctx.user: null` means an ungated router (no login exists);\n integration-level token APIs sit behind the router's gate when it has one.\n\nAFK draft, HITL review pass.\n\n## Resolution\n\nShipped `README.md` for both audiences — _Mounting integrations_ (`createRouter`\nquickstart, the `auth` table, reserved paths) and _Writing an integration_ (the\n`Integration` contract, factory convention, handler + `IntegrationContext`,\n`requiredEnv`, reserved slugs), with `example/hello.ts` as the worked example.\nThe ticket-4 surface is all covered: callable dual-mode integrations (ADR 0003),\n`createRouteHandler` as the OAuth-free test seam, and permission composition\n(`ctx.user` null → ungated → don't redirect; token APIs stack behind the gate).\n\n**The explainability test passed** — every contract rule stated in a clean\nparagraph, no wall of caveats, so no contract changes fell out of writing the\ndocs. Two migrations having landed \"zero contract fights\" held up under prose.\n\nRefinements made during the HITL review pass:\n\n- **Naming convention unified** to the `helloWorld` style: `createIssueTracker`\n → `issueTracker`, `createBlobAdmin` → `blobAdmin`, renamed across all three\n repos (closed tickets left as the migration audit record). `*Options` types\n already matched the `HelloWorldOptions` style and were left.\n- **Example docs extracted**: `example/hello.ts` stripped of teaching comments;\n a line-by-line walkthrough moved to new `example/README.md`.\n- **val-issue-tracker README restructured** onto scoped-blob-viewer's\n standalone/routed shape (the house style for integration READMEs).\n\nAll three repos green (`deno task check`): integrations 17 tests,\nval-issue-tracker 23, scoped-blob-viewer 5. The two migrated vals were\nrepublished so the integrations val's remote imports resolve against the new\nnames.\n\nSurfaced but ruled out of scope: **fine-grained auth for routed integrations**\n(a gated router's all-or-nothing login wall flattens an integration's own finer\nauth model — e.g. the tracker's anonymous public reads vanish behind a gated\nrouter). Beyond v1's settled all-or-nothing gate; filed as the leading candidate\nfor the next effort.\n",[],[233,506,507,367,525],"8b0b405f-beb6-421c-8149-2dbc881fea3b","006-hello-world-example-integration.md","27198942-7cb1-11f1-bf6f-1607ee4eb77e",195,["D",1784043354417],"---\nid: 6\ntitle: Add the hello-world example integration\nlabels: [wayfinder:task]\nstatus: closed\nassignee: nbbaier\nblocked-by: [3]\n---\n\n## Question\n\nWrite the toy integration (~30 lines) that lives in the `integrations` repo,\ndoubles as the docs' worked example, and demonstrates the whole contract surface\nhonestly: `defineIntegration`, an `(options) => Integration` factory, reading\nthe router-provided user, one `requiredEnv` declaration, and prefix-correct\nlinks per the ticket-2 rules.\n\nMount it in this val's own `main.ts` so the live directory page always shows a\nworking example. Keep it genuinely trivial — its job is to be copied by\nthird-party authors, so every line should be contract, not app.\n\nAFK.\n\n## Resolution\n\nShipped 2026-07-11. [`hello.ts`](../../../../example/hello.ts) — ~40 lines,\ndeployed live.\n\n- **The whole contract surface, honestly:** an `(options) => Integration`\n factory (`helloWorld({ subject? })`, config in the closure), built with\n `defineIntegration`, reading `ctx?.user` via the dual-mode idiom (greets\n `@user` when routed+logged-in, the `subject` option standalone), one\n `requiredEnv: [\"HELLO_GREETING\"]` it genuinely reads at request time (falls\n back to \"Hello\"; unset = the directory's ⚠️ badge, deliberately demonstrating\n the feature), and relative-only links (`about`, `./`) per the ticket-2 prefix\n rules. `export default helloWorld()` at the bottom shows standalone mode on\n the same callable.\n- **Plain `(req, ctx)` handler, no Hono** — the toy stays dependency-free so\n every line is contract; the Hono idiom is val-issue-tracker's job to show.\n- **Registered in `main.ts`** after the issue tracker; pushed via `vt push` and\n verified live (401 login gate serving correctly; directory is owner-gated by\n design).\n- Tests: [`hello_test.ts`](../../../../example/hello_test.ts) — routed\n greeting + relative links, standalone fallback, both modes through the real\n dispatch. 17/17 green under `deno task check`.\n- Not exported from `mod.ts`: the example is a copyable file, not contract\n surface. Ticket 7's docs should link/inline it as the worked example.\n",[],[233,506,507,367,533],"5967bccd-9118-42d2-b83f-f06ed086b606","005-migrate-scoped-blob-viewer.md","2721832c-7cb1-11f1-adf5-1607ee4eb77e",194,["D",1784043354253],"---\nid: 5\ntitle: Migrate scoped-blob-viewer onto the contract\nlabels: [wayfinder:task]\nstatus: closed\nassignee: nbbaier\nblocked-by: [3]\n---\n\n## Question\n\nMigrate `~/Code/vt-projects/scoped-blob-viewer` to be a conforming integration\nwhile keeping standalone mounting working\n(`export default\ncreateBlobAdmin({...})` stays valid).\n\nThis is the deliberate stress test for prefix hygiene: `mod.ts` is one file of\nlink-heavy server-rendered HTML — absolute `href`s (`/view?key=...`,\n`/raw?key=...`), form `action`s (`/create`, `/delete`, `/rename`), and redirect\ntargets (`c.redirect(\"/?ok=...\")`) all break under a mount prefix unless the\nticket-2 rules handle them. If the migration fights the contract, that's signal,\nnot something to hack around — feed it back.\n\nAlso: it currently wraps `oauthMiddleware` itself with an `owner` allowlist;\nthat gate moves to the router, and its `LoginPage` setup-check for\n`OAUTH_STATE_ENCRYPTION_KEY` becomes a `requiredEnv` declaration.\n\nAFK.\n\n## Resolution\n\nMigrated 2026-07-11; both modes live and green, and the stress test passed —\n**the prefix-hygiene rules held without a single contract fight.**\n\n- `createBlobAdmin` now returns a callable Integration built with\n `defineIntegration` from the published contract\n (`https://esm.town/v/nbbaier/integrations/mod.ts`).\n `export default\n createBlobAdmin({ owner: \"nbbaier\" })` stays a valid\n standalone HTTP export, and the same value registers with `createRouter`.\n Standalone wraps this val's own `oauthMiddleware`; routed mode never does\n (`handler: (req, ctx) => ctx ? app.fetch(req, ctx) : standalone(req)`).\n- **Prefix hygiene (the point of the ticket):** every link/form action in the\n link-heavy HTML threads `base = ctx.prefix ?? \"\"` (via a `base` Hono var set\n in the auth middleware); redirects stay root-absolute (`/?ok=`, `/view?...`)\n and get router-rewritten per ADR 0002; `/auth/*` links stay origin-level in\n both modes. `blob.*` calls unchanged — scoped storage needs no prefix\n handling. **No contract additions were needed** — unlike the tracker\n migration, this one consumed the contract exactly as ticket 4 left it\n (callable integrations, `createRouteHandler` seam, Location rewriting).\n- **Permission composition:** `owner` stays this panel's own authorization\n layer, now checked against `ctx.user` when routed and the OAuth session when\n standalone. Unlike the tracker there is no read-only role — an admin panel is\n all-or-nothing — so a non-owner (including the `null` user of an ungated\n router, which can't satisfy an allowlist) gets 403, not a downgraded view.\n `auth: false` is fully open in both modes, as before.\n `OAUTH_STATE_ENCRYPTION_KEY` is declared as `requiredEnv` so a router's\n directory badges it when unset.\n- **File layout — reusable lesson for the docs ticket (7):** JSX in a `.ts` file\n runs on Val Town but can't be type-checked by plain `deno check`. So,\n mirroring the tracker, the JSX moved to `app.tsx` and `mod.ts` became a\n JSX-free re-export barrel — keeping the stable `.../scoped-blob-viewer/mod.ts`\n import path AND making the module locally checkable. Authors shipping JSX\n integrations should do the same.\n- Added a `deno task check` (fmt/lint/typecheck/test) the val never had, plus\n `mod_test.ts`: 5 tests via an injected in-memory `BlobStore` seam covering\n contract metadata, routed prefix-threading, the owner gate (owner/non-owner/\n null), root-absolute redirects, and end-to-end composition under the real\n router (`createRouteHandler`). All green in both repos.\n- Live: pushed both vals. `createBlobAdmin({})` registered in the integrations\n val's `main.ts`, mounted at `/blobs/` (401-gated as configured — the router\n serving 401 rather than 500 confirms it accepted the value as an Integration\n at construction). Standalone blob-viewer val serves its own data unchanged.\n- Same gotcha as ticket 4: the viewer imports the contract unpinned and Deno\n caches remote modules — after pushing scoped-blob-viewer, run\n `deno cache\n --reload=https://esm.town/v/nbbaier/scoped-blob-viewer/mod.ts`\n in the integrations val before its `deno task check`.\n",[],[233,506,507,367,541],"d4717d74-7335-4b52-89cf-2e8a45ba493c","004-migrate-val-issue-tracker.md","04d622d6-7d52-11f1-8ed3-1607ee4eb77e",198,["D",1784043354657],"---\nid: 4\ntitle: Migrate val-issue-tracker onto the contract\nlabels: [wayfinder:task]\nstatus: closed\nassignee: nbbaier\nblocked-by: [3]\n---\n\n## Question\n\nMigrate `~/Code/vt-projects/val-issue-tracker` to be a conforming integration\nwhile keeping standalone mounting working (charter constraint: the factory\nserves both modes — `export default createIssueTracker({...})` stays valid).\n\nKnown hard parts:\n\n- It self-manages OAuth **and** a role model (maintainer/contributor/viewer)\n **and** a bearer-token JSON API under `/api`. Router-owned auth replaces the\n OAuth gate; how the router-provided user feeds the role model, and what\n happens to bearer-token writes behind the router, is the map's\n \"permission-model composition\" fog — resolving this ticket should graduate or\n answer it.\n- Prefix hygiene per the ticket-2 rules if architecture (A) won: absolute\n links/form actions throughout `app.tsx` / `components.tsx` / `ui.tsx`, and the\n `/source` redirect.\n- Its test suite (`deno task check`) must stay green in both modes.\n\nAFK mostly; flag anything that contradicts the contract rather than working\naround it.\n\n## Resolution\n\nMigrated 2026-07-11; both modes live and green.\n\n- `createIssueTracker` now returns a callable Integration built with\n `defineIntegration` from the published contract\n (`https://esm.town/v/nbbaier/integrations/mod.ts`):\n `export default\n createIssueTracker({})` stays a valid standalone HTTP\n export, and the same value registers with `createRouter`. Standalone wraps the\n tracker's own `oauthMiddleware`; routed mode never does.\n- **Permission composition (answers the map's fog):** the router owns\n authentication; the tracker's maintainer/contributor/viewer model stays its\n own authorization layer, fed by `ctx.user` — maintainer if in the\n `maintainers` set, else `defaultRole`; `ctx.user: null` (ungated router) is a\n read-only viewer with login UI hidden, since no login flow exists there.\n Tracker `auth: false` still means \"everyone is maintainer\" in both modes.\n Routed mode never redirects to `/auth/login` (Location rewriting would turn it\n into a 404 under the prefix) — viewers get a 403 page instead.\n- **Bearer-token `/api`:** unchanged at the integration layer; gates stack.\n Behind a gated router the JSON API additionally requires the router's OAuth\n session, so headless agents target a standalone or ungated mount.\n Machine-credential pass-through ruled out of scope for v1 (map updated).\n- **Prefix hygiene:** every HTML link/form action threads\n `base = ctx.prefix ?? \"\"` (Layout + all pages); redirects stay root-absolute\n and get router-rewritten per ADR 0002; `/auth/*` links stay origin-level\n (correct in both modes); Referer-based redirects pass through as full URLs.\n- **Contract feedback — implemented as additive changes, not workarounds:** (1)\n `defineIntegration` returns a callable Integration\n ([ADR 0003](../../../adr/0003-callable-integrations.md); new\n `CallableIntegration` / `IntegrationHandler` types) — without it the two\n mounting styles needed different factory return values; (2)\n `createRouteHandler` promoted to `mod.ts` as the public OAuth-free test seam —\n the tracker's routed tests mount under the real router with an injected user.\n- Tests: val-issue-tracker 23 green (2 new: routed roles + prefixed links;\n end-to-end under the real router), integrations 15 green — `deno task\n check`\n in both repos. Live: tracker mounted at the integrations val (`/issues/`,\n 401-gated as configured); the standalone tracker val serves its existing data\n unchanged.\n- Gotcha for later tickets: the tracker imports the contract unpinned, and Deno\n caches remote modules — after pushing integrations, run\n `deno cache\n --reload=https://esm.town/v/nbbaier/integrations/mod.ts` in\n dependents before `deno task check`.\n",[],[233,506,507,367,549],"47b9947e-f00a-4565-a321-00461ccd2e5c","003-build-integrations-v1.md","27129ee8-7cb1-11f1-9ee9-1607ee4eb77e",191,["D",1784043353864],"---\nid: 3\ntitle: Build integrations v1 — contract exports, router, directory page\nlabels: [wayfinder:task]\nstatus: closed\nassignee: nbbaier\nblocked-by: [2]\n---\n\n## Question\n\nImplement the pinned contract in the `integrations` val\n(`~/Code/vt-projects/integrations`, currently an empty `main.ts`):\n\n- `mod.ts` exporting `Integration`, `defineIntegration`, `createRouter`.\n- The router per the ticket-1 architecture and ticket-2 API: dispatch,\n router-owned OAuth gate, user passed to integrations.\n- The directory page at `/`: name, description, link per registered integration;\n ⚠️ badge when a `requiredEnv` var is unset (`Deno.env.get(...)`).\n- Slug/reserved-path validation with clear construction-time errors.\n- `main.ts` as this val's own consumer (mirroring how `val-issue-tracker`'s\n `main.ts` consumes its `mod.ts`) — it can mount the hello-world integration\n once ticket 6 exists.\n- Tests where the repo's siblings set precedent (`deno task check` style: biome\n fmt, lint, typecheck, test).\n\nAFK: buildable solo once the contract is pinned; resolution records what shipped\nand any contract deviations discovered while building (feed those back into the\nmap).\n\n## Resolution\n\nBuilt and deployed 2026-07-10. What shipped:\n\n- `router.ts` — the implementation: `Integration` / `IntegrationContext` /\n `RouterOptions` types, `defineIntegration` (charset + reserved validation),\n `createRouteHandler(options, getUser)` (the OAuth-free core, user lookup\n injected — this is the test seam), and `createRouter` (wires\n `getOAuthUserData` + wraps with `oauthMiddleware` unless `auth: false`).\n- `mod.ts` — public re-exports only; third parties import this.\n- `router_test.ts` — 14 tests, all green via `deno task check` (fmt, lint,\n typecheck, test — tasks added to `deno.json` mirroring val-issue-tracker):\n validation throws, prefix strip + ctx, trailing-slash canonicalization\n preserving query, buffered POST bodies, 404/directory, requiredEnv badge,\n Location rewriting incl. protocol-relative (`//host`) and absolute\n pass-through, and the full auth matrix (anon GET→401 login page, anon\n non-GET→302 home, allowlist 403/200, `auth: false`→`ctx.user` null).\n- `main.ts` (HTTP) — this val's consumer:\n `createRouter({ title:\n \"Integrations\", auth: { users: \"nbbaier\" }, integrations: [] })`.\n Live at https://nbbaier--477921dc7cb811f194e81607ee4eb77e.web.val.run —\n verified serving the login page (401, allowlist named, no env warning). The\n hello-world integration (ticket 6) registers here.\n- Housekeeping: fixed the template's Deno-2-deprecated `lint.files` config.\n\nContract deviations discovered while building: **none** — the pinned API\nimplemented cleanly. One addition the contract didn't specify: anonymous non-GET\nrequests bounce 302 home rather than rendering the login page (precedent from\nscoped-blob-viewer; a stale form POST shouldn't render HTML into a POST\nresponse).\n",[],[233,506,507,367,557],"23a5d0cf-f5b6-4eb2-9812-9d4a11f8b301","002-pin-the-v1-contract.md","274f5dce-7cb1-11f1-ab0f-1607ee4eb77e",192,["D",1784043354039],"---\nid: 2\ntitle: Pin the v1 contract — Integration type, defineIntegration, createRouter API\nlabels: [wayfinder:grilling]\nstatus: closed\nassignee: nbbaier\nblocked-by: [1]\n---\n\n## Question\n\nFinalize the exact public API of `integrations/mod.ts`. The charter settled the\nshape; this ticket pins the details the architecture decision unlocks.\n\nSettled by the charter (do not relitigate):\n\n```ts\ninterface Integration {\n name: string; // \"Issue Tracker\"\n slug: string; // \"issues\" → mount prefix\n description?: string;\n requiredEnv?: string[]; // e.g. [\"OAUTH_STATE_ENCRYPTION_KEY\"] → ⚠️ on the directory page\n handler: (req: Request) => Response | Promise;\n}\n```\n\nAuthors export `(options) => Integration` factories built with\n`defineIntegration`; users write\n`createRouter({ integrations: [issueTracker({...})], auth: {...} })`.\n\nTo pin here:\n\n- **Handler signature**: how does the router pass the authenticated user (and\n anything else, e.g. the mount prefix) to the integration? Extra context arg\n (`(req, ctx)`), request header, or a richer handler type? Depends on the\n ticket-1 architecture.\n- **Prefix rules**: if (A) won, the exact contract for links/forms/assets under\n a mount prefix — what the router guarantees (e.g. strips the prefix? passes it\n in ctx?) and what authors must do. If this takes three paragraphs of caveats,\n that is a design smell to feed back.\n- **Slug validation**: charset, uniqueness, reserved names (`auth`, plus the\n root). When does `createRouter` reject — construction time, with what error?\n- **`createRouter` options**: `auth` shape (`owner`/allowed users, off switch),\n `title` for the directory page, anything else v1 actually needs. Keep minimal.\n- **What `defineIntegration` actually does** beyond identity/typing —\n validation? defaults?\n\nHITL: grill through these one at a time (/grilling, /domain-modeling).\n\n## Resolution\n\nDecided 2026-07-10 by grilling. The v1 public API of `integrations/mod.ts`:\n\n```ts\ninterface IntegrationContext {\n user: string | null; // Val Town username via router-owned OAuth\n prefix: string; // mount prefix, e.g. \"/issues\"\n}\n\ninterface Integration {\n name: string;\n slug: string;\n description?: string;\n requiredEnv?: string[];\n handler: (\n req: Request,\n ctx?: IntegrationContext,\n ) => Response | Promise;\n}\n\ninterface RouterOptions {\n integrations: Integration[]; // order = directory order\n auth?: { users?: string | string[] } | false; // default ON, any logged-in user\n title?: string; // directory header, default \"Integrations\"\n}\n```\n\n- **Context as second argument, nothing in headers.** `handler(req, ctx)`.\n Aligns with Hono: an integration exporting `app.fetch` reads `c.env.user` /\n `c.env.prefix` directly (`Hono<{ Bindings: IntegrationContext }>` for typing)\n — same object reference, no adapter. Standalone mode passes no ctx, so\n `c.env?.user` is the dual-mode idiom. No identity headers = no spoofing\n surface.\n- **Response rewriting: root-absolute `Location` headers get the prefix\n prepended** by the router\n ([ADR 0002](../../../adr/0002-location-header-rewriting.md)). HTML is never\n rewritten — authors use relative URLs or `ctx.prefix`. Result:\n `c.redirect(\"/?ok=...\")` and the whole redirect-after-POST idiom work\n unmodified in BOTH modes with zero branching.\n- **Slugs:** `^[a-z0-9-]+$`, unique per router, checked against\n `RESERVED_SLUGS: (string | RegExp)[] = [\"auth\", /^_/]` — `auth` because\n std/oauth hardcodes `/auth/*`; `/^_/` publishes the underscore namespace as\n router-owned forever (unspellable under the charset today; guards a future\n loosening). Violations **throw at construction** with the offending slug\n named, so bad config fails the deploy, never serves silently broken routes.\n- **Auth is a gate, not a role system.** `auth.users` is an allowlist of who may\n enter; what they may DO stays integration-domain logic fed by `ctx.user`\n (issue tracker keeps maintainer/contributor — that seam belongs to its\n migration ticket). `auth: false` opts out; `ctx.user` is then null.\n- **Nothing else in v1**: no per-integration auth overrides, no hooks, no custom\n directory renderer — v2-shaped until a migration proves a need.\n",[],[233,506,507,367,565],"ab88431c-09c9-4286-a423-ac19b73d7146","001-prototype-dispatch-architecture.md","04f1644c-7d52-11f1-acde-1607ee4eb77e",197,["D",1784043354558],"---\nid: 1\ntitle: Prototype the dispatch architecture — in-process mount (A) vs sibling-endpoint redirect (B′)\nlabels: [wayfinder:prototype]\nstatus: closed\nassignee: nbbaier\nblocked-by: []\n---\n\n## Question\n\nWhich dispatch architecture does `createRouter` use? Build cheap stubs of both\non Val Town and decide from the evidence. This is the load-bearing mechanical\nunknown; nearly every other ticket blocks on it.\n\n**(A) In-process mount.** One HTTP endpoint; the router holds `Integration`\nhandlers and dispatches by path prefix (`/issues/*` → issue tracker's fetch\nhandler with a rewritten path). One origin: a true single URL, one OAuth\nsession. Costs to verify:\n\n- **Prefix hygiene**: both existing integrations emit absolute paths\n (`/view?key=...`, form `action=\"/delete\"`, `/auth/login`) that break under a\n `/blobs` prefix. How painful is making a real app prefix-correct — does Hono\n `basePath`/route-mounting get most of the way, or is it a caveat-laden\n contract on every author?\n- **OAuth composition**: can the router wrap `oauthMiddleware` once at the top,\n mount `/auth/*` once, and pass the authenticated user down to integrations\n (the \"router owns auth\" design intent)? Verify `getOAuthUserData` works from\n inside a prefix-mounted child handler.\n\n**(B′) Sibling endpoint files + redirecting directory.** Each integration is its\nown HTTP file in the host val (own URL, but scoped SQLite/blob is val-scoped, so\nstorage is still shared — confirmed platform fact). The router endpoint is a\nlauncher that 302s `/issues` to the sibling's URL. Existing integrations work\nunmodified today. Costs to verify:\n\n- Separate origins → separate cookie jars → per-integration OAuth logins. How\n bad does that feel in practice?\n- \"Mounting\" = creating a file per integration + telling the router about it;\n the astro-style `createRouter({ integrations: [...] })` API can't hold the\n handlers, only metadata/URLs.\n\n**Thumb on the scale**: the charter's astro/vite composition model\n(`createRouter` receives integration instances) presupposes (A). (B′) wins only\nif prefix hygiene or OAuth composition turns out genuinely nasty.\n\nPlatform notes: `Response.redirect` is broken on Val Town — use Hono\n`c.redirect` or a manual 302. Each HTTP file's URL comes from `links.endpoint`\nvia `list_files` / `create_file`; never construct it by hand.\n\nHITL: build the stubs, then react to them together before recording the\ndecision.\n\nThe decision meets all three ADR criteria (hard to reverse, surprising without\ncontext, real trade-off): record it as the repo's first ADR at\n`docs/adr/0001-dispatch-architecture.md` in addition to the resolution comment.\n\n## Resolution\n\n**Architecture (A) — in-process prefix mount.** Decided 2026-07-10 after both\nstubs ran live; recorded as\n[ADR 0001](../../../adr/0001-dispatch-architecture.md). The prototype (`proto/`,\nsince deleted) established:\n\n- **Dispatch works.** The router matches `/slug` prefixes, rewrites the URL\n (child sees `/`), and passes `x-mount-prefix`. POSTs survive with a buffered\n body (`await req.blob()` — streams need re-wrapping care).\n- **Prefix hygiene is a one-line rule, not a wall of caveats.** With the router\n canonicalizing `/slug` → `/slug/` (302, reverse-proxy convention), plain\n relative links AND relative form actions resolve correctly. Only root-absolute\n paths (`/two`, `action=\"/add\"`) break. Contract rule: use relative URLs or the\n provided prefix; never root-absolute.\n- **Router-owned auth verified.** `oauthMiddleware` wrapped once at the router;\n after one login, children saw the user both via a router-set header\n (`x-router-user`) and by calling `getOAuthUserData` directly on the rewritten\n request — cookies flow through. Integrations need no OAuth code.\n- **Scoped SQLite is shared across all mount styles** (val-scoped, verified in\n both directions), so (B′) held no storage advantage.\n- **(B′) rejected**: split origins mean per-integration logins and a\n launcher-only \"single URL\", and the astro-style\n `createRouter({ integrations: [...] })` API can't exist — mounting would mean\n creating a file per integration instead of just importing a factory (a real UX\n loss).\n",[],[233,506,507,367,573],"72785ed1-e6af-4eb2-a126-35d7610911ca",113,["D",1783792524099],[275,276,277,278,279,280,281,282],[233,506,507,367],"4943a8e8-7e18-4b5e-9cf5-01f32b53ffb3","b0de7188-7d51-11f1-b8b2-1607ee4eb77e",112,["D",1783792523949],[274,283,284],[233,506,507],"159d8575-7826-4301-a89a-db8a19f128a9",111,["D",1783792523821],[273],[233,506],"35a2ffe0-d0ae-4420-8534-c2df9f07b369","building-host-scoped-integrations.md","7b67cef6-7d69-11f1-821f-1607ee4eb77e","2428d405-c9ba-409c-80a1-535778f75f37",201,["D",1784043354935],"# Building host-scoped integrations: mounting, self-identification, SPAs, versioning\n\nField notes from a build session: porting a client-side React SPA onto the\nintegrations contract and probing how a mounted integration sees its host.\n\nEmpirical claims were verified against a live toy (`toy-spa-integration`)\nmounted three ways. Items tagged _(from the contract)_ were reasoned from\n`router.ts`, not exercised live.\n\n---\n\n## 1. The ways an integration can be mounted\n\nAn integration is just a `(req, ctx?) => Response` handler (a callable\n`Integration`). Two things vary independently: the **mount mechanism** — which\ndecides whether `ctx` is passed and whether prefix/redirect handling applies —\nand the **host val**, which is always whichever val Val Town executed.\n\n| Mechanism | Host val (`= VALTOWN_ENTRYPOINT`) | `ctx` | Path handler sees | Router services |\n| --------------------------------------------------------------------------------------- | --------------------------------- | -------------------- | -------------------- | --------------------------------------------------------------------- |\n| Standalone, own val — `export default factory()` in the integration's own val | the integration's own val | absent | root | none |\n| Standalone, wrapper val — another val does `import {factory}; export default factory()` | the wrapper val | absent | root | none |\n| Routed — `createRouter({ integrations:[factory()] })` | the router val | `{ user, prefix }` | prefix-stripped | prefix canonicalize, Location rewrite, directory page, OAuth gate |\n| Routed test seam — `createRouteHandler(opts, getUser)` | the val running it | `{ user, prefix }` | prefix-stripped | routing, no OAuth _(from the contract)_ |\n| Manual — host calls the handler itself, no `createRouter` | that host val | whatever host passes | whatever host strips | none — you reimplement strip + Location rewrite _(from the contract)_ |\n\nNotes:\n\n- The two standalone rows are the **same mechanism**\n (`export default\n factory()`, no `ctx`); only which val holds the export\n differs, and that is what flips the host.\n- Routed: `ctx.prefix` is `/slug` (no trailing slash), and the handler receives\n the path already stripped of it. With Hono, `ctx` arrives as `c.env`.\n- `createRouter` returns a bare handler, not an `Integration` (no\n `slug`/`name`), so routers don't nest into another router's `integrations[]`\n without re-wrapping in `defineIntegration`.\n\nTwo orthogonal axes for classifying an integration:\n\n- **Interface** — full web UI / API-only / both. (The issue tracker is already\n both.)\n- **Subject** — self-owned domain (issues, subscriptions) vs\n host-reflective/introspective (docs, version history, env). Host-reflective\n can wear any interface.\n\n---\n\n## 2. Host self-identification\n\nVal Town injects `VALTOWN_ENTRYPOINT` — the `import.meta.url` of the file it\nexecuted — into the process env. The `std/utils` file helpers default to it. So\nfrom inside a mounted integration:\n\n- `parseVal()` → `{ username, name, version, branch }` of the **host** (the\n executed val).\n- `listFiles()` → the host's full file tree. This is the multi-file answer:\n enumerate, then `readFile` each source.\n- `readFile(path)` → the host's source for one file. Use `readFile`, not\n `readFileTranspiled`, to keep JSDoc and type annotations.\n- `getValId()` → the host's UUID (rename-stable cache key).\n- `parseVal(import.meta.url)` → the integration's **own** val (overrides the\n default).\n\n**Rule:** host = the executed val; self = `import.meta.url`, always. Everything\nhost-scoped (blob, SQLite, `parseVal`, `listFiles`) keys off the host by the\nsame execution-context mechanism that scoped storage already uses.\n\nVerified with a `whoami` probe returning `{ host, self }`:\n\n- Standalone, own val → `host == self` (the toy).\n- Standalone, wrapper val → `host` = wrapper, `self` = toy.\n- Routed → `host` = router, `self` = toy; `hostFileCount` reflected the router's\n files, not the toy's.\n\nImplication for a host-reflective integration (e.g. a docs generator): default\nsubject = `parseVal()` (the host); keep any `?val=` query param as an _override_\nfor a \"document any val\" mode. Scoped blob is already per-host, so a\ngenerated-content cache auto-isolates — key entries by `parseVal().version` to\ninvalidate on redeploy. Reads use the host's scoped token, so private host\nsource is readable; expose rendered output deliberately.\n\n---\n\n## 3. A client-side SPA as an integration frontend\n\nThe router strips the prefix (the handler runs as if at root) and rewrites\n**Location headers only**, never bodies. So a SPA survives mounting when split\ninto three surfaces by who serves them:\n\n1. **HTML shell** — served by the handler at `/`. Every browser-resolved URL in\n it is **relative** (or an absolute esm.town URL), never root-absolute.\n2. **Client bundle** — referenced by an **absolute esm.town URL**\n (`https://esm.town/v/you/val/frontend/index.tsx`). Prefix-immune; the browser\n fetches it straight from esm.town, so the host only proxies shell + API.\n Requires the integration val to be public/unlisted — a private val's esm.town\n URL won't serve to the browser. Alternative: serve it through the handler\n with `staticHTTPServer(import.meta.url, app.fetch)`, passing\n `import.meta.url` explicitly (its default `VALTOWN_ENTRYPOINT` would\n otherwise serve the **host's** files as your frontend).\n3. **Host-data API** (`/api/*`) — the only genuinely host-scoped surface;\n reached by **relative** `fetch(\"api/...\")`.\n\nTwo rules make it work:\n\n- Everything the browser resolves is relative. The router canonicalizes `/slug`\n → `/slug/` (trailing slash) so relative URLs resolve inside the mount.\n- The client derives its API base once at boot:\n `const API_BASE = new URL(\".\", location.href)`, then\n `fetch(new URL(\"api/state\", API_BASE))`. No server injection; works at `/`\n standalone and `/slug/` mounted.\n\nUse **hash-based** client routing so `location.pathname` stays at the mount root\nand the derived base stays valid (path routing would need a shell catch-all plus\na base-aware router). The React component tree itself doesn't change to mount —\nonly these edges do.\n\n---\n\n## 4. Versioning: cross-val imports are lockfile-pinned\n\nWhen a host imports an integration across the esm.town boundary\n(`import { x } from \"https://esm.town/v/you/int/mod.ts\"`), the resolved version\nis written into the **host val's lockfile** and is sticky by design.\n\n- An unpinned specifier is **not** live-latest and **not** refreshed by a\n redeploy — the redeploy honors the existing lock entry. (A single edit-fused\n request can transiently resolve latest in a cold isolate, which is misleading;\n steady-state traffic keeps the locked version.)\n- Forcing an update requires **re-resolution**: reset the lockfile, or cycle the\n specifier (pin → unpin). After that, unpinned re-resolves to current and locks\n again.\n- Pin `@ver-branch` (e.g. `@8-main`) for a deterministic version you control —\n it's an immutable URL and never moves.\n\nVerified: added a route to the toy, then hit it through a wrapper that imported\nunpinned. The new route 404'd (the wrapper was locked to the pre-change version)\nwhile unchanged routes still worked. Pinning the wrapper to the old version\nreproduced the 404 deterministically; resetting the lock and unpinning brought\nthe new route back.\n\nGuidance for shipping integrations: tell consumers \"unpinned is a locked\nsnapshot you update by re-resolving; pin `@ver` for stability.\" This is also why\nthe contract ships breaking changes as a **new entrypoint** rather than mutating\n`mod.ts` — existing hosts stay locked to whatever they resolved.\n",[],[233,605,597],"notes","652c10c5-892e-45b9-8646-fc241d0be5f7",135,["D",1783802742029],[271],[233,605],"e13fac8d-01b6-4986-b456-9b39af8239e5","spec.md","fc3a0cfa-7f9f-11f1-8206-1607ee4eb77e","fbfc07ac-7f9f-11f1-8be1-1607ee4eb77e",224,["D",1784046053288],"# Spec: Session-less auth for routed integrations\n\nStatus: ready-for-agent\n\nCharter:\n[ADR 0004 — Session-less requests reach integrations by a single\nintegration-declared flag](../../adr/0004-session-less-auth.md). This spec is\nthe build that ADR charters. Domain terms (Session-less flag, Login-location\nsignal, Allowlist, Escape hatch, Host val, Router, Integration context) are\ndefined in `CONTEXT.md` and used as-is here.\n\n## Problem Statement\n\nToday a router with auth on refuses **every** session-less request with a login\nwall before any integration sees it. Two real needs fall off that wall:\n\n- **Anonymous public reads are impossible.** The issue tracker has a viewer role\n meant for people who aren't logged in, but behind a gated router that role is\n unreachable — the login wall 401s them first. A host who wants \"anyone can\n read the issues, only my team can write\" cannot express it.\n- **Machine clients can't reach a bearer-authenticated API.** The tracker's\n `/api` authenticates its own bearer key, but behind a gated router the\n bearer-token client is just another session-less request and gets bounced to\n the login page — it never reaches the integration that would have honored its\n key.\n\nBoth stem from the same thing: the router's gate is all-or-nothing, and\n`ctx.user: null` can't tell an integration whether it's anonymous-on-a-gated-\nrouter or running with no router at all.\n\n## Solution\n\nAn integration opts into session-less traffic by declaring **one coarse flag**\nmeaning \"safe to receive requests with no logged-in user, period.\" The router\nenforces the flag at dispatch: a session-less request reaches a **flagged**\nintegration untouched (with `ctx.user: null`), and hits the login wall for an\n**unflagged** one (the default). The integration's own per-route authorization —\nwhich it already has for standalone mode — draws the fine line inside its\nsurface, so there is no second, drift-prone copy of the route table living in\nthe router.\n\nFrom the outside:\n\n- A host mounts the tracker as flagged: anonymous visitors read issues, the\n tracker's own role model still blocks `/new` and gates writes, and a\n bearer-token client reaches `/api` with its `Authorization` header intact\n because the router never touches it.\n- An unflagged integration (e.g. the blob admin) stays fully gated with zero\n extra declaration — safe by default.\n- The context now tells a flagged integration **where login lives, or that it\n doesn't**, so it can render a working \"log in\" link under a router that owns\n login and omit it when none exists.\n\n## User Stories\n\n1. As an integration author, I want to declare my integration safe for\n session-less traffic with a single flag, so that anonymous and machine\n clients can reach it without me hand-listing routes.\n2. As an integration author, I want the flag to be coarse (one boolean, not a\n route list or predicate), so that I don't maintain a second copy of my route\n table that can drift from my real authorization logic.\n3. As an integration author, I want my existing per-route authorization to\n remain the fine line, so that flagging the integration doesn't change how I\n protect individual routes.\n4. As an integration author who declares nothing, I want my integration fully\n gated by default, so that forgetting the flag is the safe outcome, not an\n exposure.\n5. As an integration author, I want the same integration to behave identically\n standalone (where the flag is inert) as it does routed, so that I reason\n about one authorization model.\n6. As an integration author, I want a context signal telling me where login\n lives, so that I can render a working log-in link when a router owns login\n and omit it when there is none.\n7. As an integration author, I want to distinguish \"the visitor hasn't logged\n in\" from \"the router has no login at all,\" so that my anonymous UI is correct\n in both routed-with-login and ungated deployments.\n8. As an anonymous visitor, I want to read a flagged integration's public\n surface without logging in, so that public content is actually public.\n9. As an anonymous visitor hitting a flagged integration's gated route, I want\n the integration's own authorization to stop me (as it does standalone), so\n that the public flag never over-exposes an internal route.\n10. As an anonymous visitor, I want the directory page to list only the flagged\n integrations plus a generic \"log in to see more,\" so that I can find public\n tools without the router leaking the names or count of private ones.\n11. As an anonymous visitor hitting a private integration's URL directly, I want\n the router's login page (401), so that the experience matches standalone and\n isn't a confusing 404.\n12. As an anonymous visitor making a non-GET request with no session (e.g. a\n stale-tab POST), I want to be bounced home (302 to `/`), so that I don't get\n HTML rendered into a POST response.\n13. As a machine/bearer client, I want my `Authorization` header to pass through\n the router untouched to a flagged integration, so that the integration can\n validate its own key with no router-minted second secret.\n14. As a machine/bearer client, I want to complete non-GET writes (POST/PUT/…)\n through the gated router, so that my automated workflow against a flagged\n integration's API works unchanged.\n15. As a host deploying a router, I want unflagged integrations to stay gated\n even when other integrations on the same router are public, so that\n interleaved public/private surfaces coexist on one origin.\n16. As a host, I want the directory page (`/`) to be public exactly when at\n least one integration is flagged, so that an all-private router still shows\n today's login wall and a router with public tools has a browsable front\n door.\n17. As a host, I want a locked-down `users` allowlist to govern only who gains\n the privileged surface, never to gate a flagged integration's public\n surface, so that \"who is trusted\" and \"is this surface public\" stay\n independent knobs.\n18. As a host, I want the val owner to always be implicitly allowed, so that I\n never lock myself out of my own router.\n19. As a host who omits `users`, I want the router to default to owner-only, so\n that the safe-by-default deployment is my private router, not one open to\n any logged-in Val Town account.\n20. As a host, I want `users: []` to mean owner-only, `users: [\"alice\"]` to mean\n owner plus alice, and `users: [\"*\"]` to mean owner plus anyone logged in, so\n that the allowlist has predictable, ordered semantics.\n21. As a host, I want to knowingly force-mount an unflagged integration on an\n `auth: false` router through an explicit, per-integration escape hatch, so\n that I can opt into exposure deliberately when I understand the risk.\n22. As a host, I want the escape hatch to be surfaced visibly at startup, so\n that a deliberate widening of exposure is never silent.\n23. As a host, I want adding a _new_ unflagged integration later to still throw\n even if an earlier one was escape-hatched, so that the escape hatch never\n becomes a blanket \"allow all unflagged.\"\n24. As a host running `auth: false` with an unflagged, un-escape-hatched\n integration, I want `createRouter` to throw at startup, so that a\n contradiction (session-less traffic with nothing declared safe) fails loud\n and early, like a duplicate slug.\n25. As a host, I want to narrow a flagged integration to be _more_ private on my\n deployment as a future capability, so that I keep the safe direction open —\n while accepting v1 ships no mechanism for it, only a named seam.\n26. As an AFK implementing agent, I want every router behavior reachable through\n a single injected seam with fake identity, so that I can test the full auth\n matrix without a live Val Town OAuth session or entrypoint env.\n27. As a maintainer, I want the tracker and blob viewer migrated to the new\n contract, so that the reference integrations demonstrate flagged and\n unflagged behavior respectively.\n28. As a maintainer, I want the README, INTEGRATIONS.md, and CONTEXT.md updated\n to describe the flag, allowlist semantics, escape hatch, and login-location\n signal, so that third-party authors can adopt the model.\n\n## Implementation Decisions\n\nModules touched: the contract + router (single file, re-exported from `mod.ts`);\nthe router's own consumer; and the two reference integrations in sibling repos.\nNo new module is introduced.\n\n### One seam, identity folded into it\n\nThe existing OAuth-free core stays the single test seam. Its injected dependency\nwidens from \"who is logged in\" to \"who is logged in **and** who owns the host\nval,\" resolved together:\n\n```ts\ntype Identity = { user: string | null; owner: string | null };\ntype ResolveIdentity = (req: Request) => Promise;\n\n// The seam — everything testable through it, no OAuth, no entrypoint env.\ncreateRouteHandler(options: RouterOptions, resolveIdentity: ResolveIdentity)\n```\n\n`createRouter` wires the real resolver: `user` from\n`getOAuthUserData(req)?.user\n?.username`, `owner` from `parseVal().username`\n(host handle from the auto-injected `VALTOWN_ENTRYPOINT`; confirmed at runtime\nto resolve to the host entrypoint even when called from an imported child module\n— ADR 0004 spike evidence). Reading `parseVal()` **inside** the handler is\nrejected: it would be a hidden, untestable dependency. It must enter through\n`resolveIdentity` so tests supply a fake owner.\n\n### The session-less flag on `Integration`\n\n`Integration` gains one optional coarse boolean, the Session-less flag. Absent =\nfully gated (the safe default). Proposed name `sessionLess?: boolean` (avoid\n`public`/`anonymous` per the domain glossary); the implementer may refine the\nname but not the shape — it is a single boolean, never a route list or\npredicate. The flag is inert in standalone mode.\n\n### The login-location signal on `IntegrationContext`\n\n`IntegrationContext` gains a routed-only field carrying **where login lives, or\nthat it doesn't** — the router's login path when the router owns login, and null\nwhen it doesn't (`auth: false`). This disambiguates the two meanings of\n`user: null`. Because `ctx` is only passed in routed mode, the field is\nnaturally absent standalone. Proposed shape `login: string | null` (avoid\n`isAuthenticated`/`authFlag`); implementer may refine the name, not the intent.\n\n### Dispatch enforcement\n\n- On a session-less request (`user == null`) reaching an integration by slug:\n pass through to a **flagged** integration with `ctx.user: null`; for an\n **unflagged** integration apply the login wall — the router-owned login page\n (401) for GET, 302 to `/` for non-GET.\n- `Authorization` is never read or stripped by the router; the existing\n header-forwarding on the child request already carries it through, and this\n must remain true for bearer clients (verified byte-identical in the spike).\n- The owner is **always** allowed the privileged surface: a request whose `user`\n equals `owner` is never 403'd by the allowlist.\n- Allowlist semantics (the `users` option): omitted ⇒ owner-only; `[]` ⇒\n owner-only; `[\"*\"]` ⇒ owner + any logged-in user; `[\"alice\"]` ⇒ owner + alice.\n This is a deliberate, safe-by-default change from today's \"any logged-in\n user.\" The allowlist gates only who reaches the privileged (gated) surface; it\n never gates a flagged integration's public surface.\n\n### The router's own surface\n\n- `/` (the directory page) is public **iff ≥1 integration is flagged**;\n otherwise the login wall stands as today.\n- On the public directory, an anonymous visitor sees **only flagged**\n integrations listed, plus a single generic \"log in to see more\" (no count of\n hidden ones).\n- Hitting a private (unflagged) integration's URL directly while anonymous ⇒ the\n single router-owned login page (401), not a 404.\n- Anonymous non-GET anywhere the gate applies ⇒ 302 to `/`.\n\n### Startup validation and the escape hatch\n\n- `auth: false` combined with an unflagged integration **throws** at router\n construction (same construction-time failure class as a duplicate slug),\n unless that specific integration is escape-hatched.\n- The Escape hatch is a host-side, per-integration, explicitly-named router\n option listing the slugs a host knowingly force-mounts unflagged on an\n `auth: false` router. It lives in the router config (never on the integration\n — that would just _be_ the flag). It is per-slug, so a _new_ unflagged\n integration added later still throws. It is surfaced visibly at startup (a\n startup log). Proposed shape `allowUnflagged?: string[]` on `RouterOptions`\n (avoid `unsafe*`/`forceFlag`/unqualified `override` per the glossary); exact\n option name and the warning-log wording are the implementer's to finalize.\n- Host-side **narrowing** (making a flagged integration more private on one\n deployment) is a **named extension point only** — no mechanism ships in v1. It\n is the safe direction and needs no acknowledgment; leave the seam named in\n code comments / docs.\n\n### Reference-integration migration (sibling repos)\n\n- `val-issue-tracker`: declare the Session-less flag; keep its role model\n reading the current user and its bearer `/api` validation as the per-route\n line; consume the login-location signal to render its log-in link.\n- `scoped-blob-viewer`: remains **unflagged** (owner-only admin surface), and\n exercises the \"private integration behind a public router\" path.\n- The router's own consumer (this val's HTTP export) registers both to\n demonstrate a mixed flagged/unflagged router.\n\n## Testing Decisions\n\n- **Test external behavior only.** Assert on HTTP status, headers (`Location`,\n `Authorization` echoed back), response body, and the `ctx` object passed into\n a stub integration — never on private helpers or internal branching.\n- **Drive everything through the one seam.**\n `createRouteHandler(options,\nresolveIdentity)` with a fake `resolveIdentity`\n returning `{ user, owner }`. This is the direct extension of the existing\n prior art in `router_test.ts`, where `anon`/`as(user)` fakes already inject\n `getUser`; those helpers become `{ user, owner }` fakes (e.g. `anon`,\n `as(user)`, `owner(handle)`).\n- **Prior art to mirror:** the existing dispatch, Location-rewriting, and auth-\n matrix tests in `router_test.ts`; the `echoIntegration` stub that records the\n `ctx` it received and echoes method/body/headers is the model for the new\n session-less and bearer-pass-through assertions.\n- **Modules under test:** the router core (`createRouteHandler`) for all runtime\n behavior; `defineIntegration`/`createRouter` construction for the\n startup-throw cases. The sibling integrations get their own migration tests in\n their repos.\n- **New behavior to cover (non-exhaustive):**\n - Flagged integration receives an anonymous request with `ctx.user: null`;\n unflagged one returns the login page (GET) / 302 (non-GET).\n - A bearer non-GET request to a flagged integration completes and the\n integration sees the `Authorization` header byte-identical (echo it back).\n - Owner is admitted to the privileged surface even under `users: []`.\n - Allowlist matrix: omitted ⇒ owner-only (non-owner logged-in ⇒ 403); `[\"*\"]`\n ⇒ any logged-in user admitted; `[\"alice\"]` ⇒ owner + alice only.\n - Directory: ≥1 flagged ⇒ `/` public, lists only flagged + \"log in to see\n more\"; 0 flagged ⇒ login wall at `/`.\n - Anonymous direct hit on an unflagged slug ⇒ 401 login page (not 404).\n - Startup: `auth: false` + unflagged (no escape hatch) throws; with the slug\n in the escape hatch it mounts.\n - Login-location signal: set to the login path on a flagged anonymous page\n under a login-owning router; null under `auth: false`.\n\n## Out of Scope\n\n- **Directory-page customization** — bring-your-own directory UI / config to\n replace the default listing. A separate future wayfinding mission; this spec\n ships only the default directory with its flagged/anonymous filtering.\n- **A host-side narrowing mechanism** — the ability for a host to make a flagged\n integration _more_ private on one deployment. Named as a seam only; no code\n ships. (Widening via the escape hatch does ship.)\n- **A router-minted bearer/token scheme** — explicitly rejected in ADR 0004 (two\n secrets per headless client for no gain). The integration's own key is the\n only machine credential.\n- **Router-side host configuration of the public surface** (a host-declared\n route list) — rejected in ADR 0004 on knowledge grounds; only the integration\n knows its public line.\n- **Any new standalone-mode auth mechanism** — the whole session-less model is\n routed-only. Standalone is unchanged; an integration wanting login there wires\n its own std/oauth and reads `getOAuthUserData(req)` directly, as the tracker\n already does.\n\n## Further Notes\n\n- The flag is a **ceiling** of public exposure: the host may narrow silently\n (future seam) and widen only loudly (the escape hatch). Authority runs one\n direction.\n- There is deliberately **no `type` field** on an integration. \"Public docs\"\n (flagged, no internal checks), \"the tracker\" (flagged, internal checks), and\n \"the blob viewer\" (unflagged) are distinguished purely by the flag plus how\n much the integration checks itself — not by a declared category.\n- Spike provenance for the load-bearing runtime facts (selective pass-through,\n bearer non-GET intact, interleaved routes standalone-identical, login\n round-trip, single-origin sessions, and `parseVal()` resolving to the host\n from an imported child) is recorded in ADR 0004's Consequences section.\n- Update `CONTEXT.md` if the build lands field/option names that differ from the\n proposals here, so the ubiquitous language stays true to the code.\n",[],[233,620,621,612],"issues","session-less-auth","1e84f58b-ef4c-42eb-91f2-a5e50f37efd1","09-wire-consumer-and-verify.md","fcba6c7e-7f9f-11f1-ba77-1607ee4eb77e","fc0f10b8-7f9f-11f1-ba77-1607ee4eb77e",249,["D",1784050565937],"# 09 — Wire the router's own consumer + end-to-end verify\n\n**What to build:** This val's own router registers the migrated tracker (public)\nand blob viewer (private) as a mixed router, and the full flow is verified live\n— the integration test of the whole effort.\n\n- Update this val's HTTP consumer to mount the migrated integrations as a mixed\n flagged/unflagged router.\n- Verify against the running deployment: an anonymous visitor reaches the\n tracker's viewer surface and sees only it (plus \"log in to see more\") on the\n directory; the blob viewer is gated (login page on direct hit); a bearer\n client completes a write against the tracker's `/api`; the owner logs in and\n reaches both.\n\n**Blocked by:** 06, 07\n\n**Status:** ready-for-agent\n\n- [ ] The consumer mounts the flagged tracker and unflagged blob viewer on one\n router\n- [ ] Live: anonymous reads the tracker's viewer surface; directory lists only\n the tracker + \"log in to see more\"\n- [ ] Live: anonymous direct hit on the blob viewer's slug gets the login page\n (401)\n- [ ] Live: a bearer client completes a write against the tracker's `/api`\n- [ ] Live: the owner logs in and reaches both integrations\n- [ ] The end-to-end behavior matches the spec's Solution section\n",[],[233,620,621,620,623],"54dfbe02-fe67-4c4e-8057-df0f66ab03f2","08-docs-reconciliation.md","fc58976a-7f9f-11f1-91d0-1607ee4eb77e",246,["D",1784050565545],"# 08 — Docs: README, INTEGRATIONS.md, CONTEXT.md reconciliation\n\n**What to build:** The author- and host-facing docs describe the new model, and\nthe ubiquitous language stays true to the code that shipped.\n\n- README: how to declare the Session-less flag, what flagged vs unflagged means,\n the login-location signal for rendering log-in links, the allowlist semantics\n (owner implicit, omitted = owner-only, `[]`/`[\"*\"]`/`[\"user\"]`), and the\n escape hatch as the one sanctioned widening.\n- INTEGRATIONS.md: note which reference integrations are flagged (tracker) vs\n unflagged (blob viewer).\n- CONTEXT.md: reconcile the Session-less-flag, Login-location-signal, Allowlist,\n and Escape-hatch entries to the **final** field/option names if they differ\n from the spec's proposals, so the glossary matches the code.\n\n**Blocked by:** 02, 03, 04, 05\n\n**Status:** ready-for-agent\n\n- [ ] README documents the flag, login-location signal, allowlist semantics, and\n escape hatch with examples\n- [ ] INTEGRATIONS.md marks each reference integration flagged/unflagged\n- [ ] CONTEXT.md field/option names match what actually shipped\n- [ ] No doc still describes the old \"any logged-in user\" default or\n all-or-nothing gate\n",[],[233,620,621,620,632],"df087930-9f57-4dfc-9ad4-c4e91aee531c","07-migrate-scoped-blob-viewer.md","fc27e728-7f9f-11f1-b152-1607ee4eb77e",260,["D",1784052972535],"# 07 — Migrate `scoped-blob-viewer` to the session-less contract (sibling repo)\n\n**What to build:** The blob viewer becomes the reference **unflagged**\nintegration and proves the \"private integration behind a public router\" path\nend-to-end. It declares no flag, stays fully gated, and its owner-only admin\nsurface is never exposed to anonymous traffic even when it shares a router with\nflagged integrations.\n\nWork happens in the sibling repo `~/Code/vt-projects/scoped-blob-viewer`.\n\n- Adopt the updated contract types (flag/`ctx` shape) without declaring the\n flag.\n- Confirm it keeps authorizing its owner from the current user as before.\n- Exercise it on a router that also mounts a flagged integration: the directory\n hides it from anonymous visitors, and a direct anonymous hit on its slug gets\n the router login page (401).\n\n**Blocked by:** 02, 05\n\n**Status:** resolved\n\n- [x] The blob viewer declares no session-less flag and remains fully gated\n- [x] On a mixed router (with a flagged integration present), the anonymous\n directory does not list the blob viewer\n- [x] An anonymous direct hit on the blob viewer's slug returns the router login\n page (401)\n- [x] A logged-in, authorized owner reaches the admin surface as before\n- [x] Standalone mode is unchanged\n- [x] The blob viewer's own tests cover the private-behind-public-router path\n\n## Resolution\n\nWork landed in the sibling repo `~/Code/vt-projects/scoped-blob-viewer`\n(`mod_test.ts` only — no source change needed).\n\n- The blob viewer already declares no `sessionLess` flag and reads `ctx.user`\n for its owner check, so it stays fully gated by default. It imports\n `IntegrationContext` from the contract, so the new `login` field is adopted\n transparently; being unflagged, it never serves anonymous traffic in routed\n mode and so consumes no login-location signal.\n- Adopted the new contract shapes in the tests: the hand-built `ctx` objects now\n carry the required `login` field, and the mounted-router seam now returns\n `{ user, owner }` instead of a bare string.\n- Added a `private behind a public router` test that mounts the unflagged blob\n admin alongside a flagged stub on a gated router and asserts all three\n behaviors: the anonymous directory lists only the flagged integration (blob\n admin absent), an anonymous direct hit on `/blobs/` gets the router-owned\n login page (401, not 404, never the admin surface), and the authorized owner\n reaches the admin panel.\n- `deno task fmt/lint/typecheck/test` all green (6 tests pass) against the\n pushed contract (`integrations@259`).\n\nNot pushed to Val Town — the maintainer pushes vals.\n",[],[233,620,621,620,640],"934e10fe-8911-4889-bd53-ac6c65a78d5f","06-migrate-val-issue-tracker.md","fc91c81e-7f9f-11f1-9727-1607ee4eb77e",["D",1784052972536],"# 06 — Migrate `val-issue-tracker` to the session-less contract (sibling repo)\n\n**What to build:** The issue tracker becomes the reference **flagged**\nintegration. Anonymous visitors reach its viewer surface through a gated router,\nits own role model and bearer `/api` keep drawing the fine line per-route, and\nit renders a working log-in link from the login-location signal.\n\nWork happens in the sibling repo `~/Code/vt-projects/val-issue-tracker`.\n\n- Declare the Session-less flag on the integration.\n- Keep the role model (viewer / contributor / maintainer) reading the current\n user, and keep `/api` validating its own bearer key — this is the per-route\n authorization that the flag does _not_ replace. `/new` and writes stay gated\n by the integration's own checks.\n- Consume the login-location signal to render a working \"log in\" link when a\n router owns login, and omit it otherwise.\n- Source of \"the current user\" still switches by mode — `ctx.user` when routed,\n `getOAuthUserData(req)` when standalone.\n\n**Blocked by:** 02, 05\n\n**Status:** resolved\n\n- [x] The tracker declares the session-less flag\n- [x] Behind a gated router, an anonymous visitor reads the viewer surface\n- [x] `/new` and write actions remain gated by the tracker's own role model\n- [x] A bearer client reaches `/api` and its key is validated by the tracker\n (router passes `Authorization` through)\n- [x] The tracker renders a working log-in link from the login-location signal\n when routed under a login-owning router, and omits it when there is none\n- [x] Standalone mode is unchanged\n- [x] The tracker's own tests cover flagged-routed and standalone behavior\n\n## Comments\n\nMigrated `val-issue-tracker` (sibling repo) to the session-less contract. Two\nfocused production changes in `app.tsx`:\n\n1. **Declared the flag.** `defineIntegration({ …, sessionLess: true })` — the\n tracker is the reference flagged integration. Its viewer role already serves\n anonymous reads and its bearer `/api` and role model still draw the per-route\n line, so declaring it safe for session-less traffic is exactly right. Inert\n standalone.\n2. **Consumed the login-location signal.** The login/logout UI decision switched\n from `ctx.user !== null` to `ctx.login !== null`. Under the old model an\n anonymous request never reached a flagged integration on a gated router, so\n \"has a user\" doubled as \"router owns login\"; now that anonymous requests pass\n through, that proxy was wrong — it hid the log-in link from the very visitors\n who need it. Keying on the login-location signal renders a working \"log in\"\n link under a login-owning router and omits it under an ungated\n (`auth: false`) one. Bonus correctness: the old check could show a _logout_\n link pointing at a `/auth/*` an ungated router doesn't own; the signal fixes\n that too.\n\nThe role model (viewer / contributor / maintainer reading the current user), the\nmode switch (`ctx.user` routed vs `getOAuthUserData(req)` standalone), and the\nbearer `/api` validation are unchanged — the flag doesn't replace per-route\nauthorization, it just lets the request arrive.\n\nTests: existing routed tests updated to the new seam shape (`ctx` carries\n`login`; `resolveIdentity` returns `{ user, owner }`). Two new tests: (a)\nflagged under a gated router — anonymous reads the viewer surface (200), the\nrole model refuses an anonymous write (403), and a bearer client reaches `/api`\nwith `Authorization` byte-intact (valid key ⇒ 201, wrong key ⇒ the tracker's own\n401 through the router); (b) the login-location signal — link shown when\n`ctx.login` is set, omitted when null. `deno task check` (fmt + lint + typecheck\n\n- 25 tests, 2 new) is green.\n\nNote: `/code-review` needs a git repo to diff; both `integrations` and\n`val-issue-tracker` are Val Town-versioned (`.vt`), not git, so it can't run and\nthe change was self-reviewed instead. The tracker changes are applied to the\nworking files in `~/Code/vt-projects/val-issue-tracker` (push via `vt`, as with\ntickets 02/05).\n",[],[233,620,621,620,648],"86befc8d-ef6f-433e-9f5c-c534624811dd","05-startup-validation-escape-hatch.md","fc7420d4-7f9f-11f1-8206-1607ee4eb77e",259,["D",1784051707455],"# 05 — Startup validation + escape hatch\n\n**What to build:** A contradictory router configuration fails loud and early,\nand the one sanctioned way to widen exposure is explicit and visible.\n\n- `auth: false` combined with an **unflagged** integration is a contradiction —\n session-less traffic with nothing declared safe — and **throws** at router\n construction, in the same construction-time failure class as a duplicate slug.\n- The Escape hatch is the only way to proceed knowingly: a host-side,\n per-integration, explicitly-named router option (proposed\n `allowUnflagged?:\n string[]` on `RouterOptions`; name refinable) listing the\n slugs a host force-mounts unflagged on an `auth: false` router. It lives in\n the router config (never on the integration — that would just _be_ the flag),\n is per-slug, and is surfaced visibly at startup (a startup log).\n- Because it is per-slug, adding a **new** unflagged integration later still\n throws — the hatch never becomes a blanket \"allow all unflagged.\"\n- Host-side _narrowing_ (making a flagged integration more private) ships no\n mechanism; leave it as a **named seam** in comments/docs only.\n\n**Blocked by:** 02\n\n**Status:** resolved\n\n- [x] `auth: false` + an unflagged integration (no escape hatch) throws at\n construction\n- [x] Listing that integration's slug in the escape hatch lets the router\n construct and mount it\n- [x] The escape hatch is per-slug: a different, un-listed unflagged integration\n still throws\n- [x] Using the escape hatch is surfaced visibly at startup (a log)\n- [x] The narrowing seam is named in code comments / docs but ships no mechanism\n- [x] Tests cover the throw, the successful force-mount, and the per-slug\n boundary\n\n## Comments\n\nImplemented the startup validation and escape hatch. `RouterOptions` gained\n`allowUnflagged?: string[]` — the host-side, per-slug escape hatch. Construction\n(`createRouteHandler`, shared by both `createRouter` entry paths) now validates:\nwhen `auth: false`, any **unflagged** integration whose slug is not in\n`allowUnflagged` **throws**, in the same construction-time failure class as a\nduplicate slug (the duplicate check still runs first). A force-mounted\nintegration (unflagged + listed) constructs and mounts, and the widening is\nsurfaced with a single `console.warn` startup log naming the slugs. Because the\nhatch is keyed per-slug, a **new** unflagged integration added later still\nthrows — it never becomes \"allow all unflagged.\" The hatch is inert under a\ngated router (`auth !== false`), which already walls unflagged integrations at\ndispatch.\n\nHost-side **narrowing** (making a flagged integration more private) ships no\nmechanism, as specified — it is named as a seam in the `allowUnflagged` doc\ncomment and pointed to from the validation-block comment.\n\nHardening from code review: a hatch entry that force-mounts nothing (a\nstale/typo'd slug, or one naming an already-flagged integration) previously did\nnothing silently; it now emits a \"no effect\" warning so the hatch stays honest\nand visible. This is beyond the ticket checklist but serves its \"explicit and\nvisible\" intent; both review axes flagged the silent-ignore.\n\nTests: 7 new cases (throw, flagged-constructs-without-hatch, force-mount,\nper-slug boundary, startup log, inert-entry warning, inert-under-gated-router).\nSeven existing open-router routing-mechanics tests were made valid by flagging\ntheir fixtures `sessionLess: true` (transparent to their assertions); the \"auth\noff is open\" test and the `hello` example test now demonstrate the escape hatch.\nA `withWarnCapture` test helper asserts and silences the startup log.\n`deno task check` (fmt + lint + typecheck + 42 tests) is green.\n\nNote: `main.ts` runs `auth: { users: \"nbbaier\" }` (auth on), so the new\nvalidation is inert there — no runtime change to the deployed consumer (ticket\n09 handles wiring/verification).\n\nNote: this repo is Val Town-versioned (`.vt`), not a git repo, so the work could\nnot be committed to a git branch.\n",[],[233,620,621,620,655],"75ce441a-5358-40b9-bbe0-5df0ffe0d360","04-router-surface-partial-gating.md","fd0b650c-7f9f-11f1-a2d8-1607ee4eb77e",252,["D",1784050564991],"# 04 — Router's own surface under partial gating\n\n**What to build:** The router's own pages behave sensibly when some integrations\nare public and some are private. The router is not an anti-enumeration boundary,\nso least-surprise and standalone-parity decide its surface.\n\n- The directory page (`/`) is public **iff ≥1 integration is flagged**;\n otherwise today's login wall stands.\n- On the public directory, an anonymous visitor sees **only flagged**\n integrations listed, plus a single generic \"log in to see more\" (no count of\n what's hidden).\n- An anonymous direct hit on a private (unflagged) integration's URL → the\n single router-owned login page (401), matching standalone — **not** a 404.\n- Anonymous non-GET where the gate applies → 302 to `/`.\n\n**Blocked by:** 02\n\n**Status:** resolved\n\n- [x] `/` is publicly viewable when at least one integration is flagged\n- [x] `/` shows the login wall when no integration is flagged\n- [x] The anonymous directory lists only flagged integrations plus a generic\n \"log in to see more\" (no count, no private names)\n- [x] A logged-in user still sees the full directory listing\n- [x] Anonymous direct hit on an unflagged slug returns the router login page\n (401), not 404\n- [x] Anonymous non-GET under the gate returns 302 to `/`\n- [x] Tests cover the ≥1-flagged and 0-flagged directory cases and the\n private-URL path\n\n## Comments\n\nImplemented the router's own surface under partial gating. The `/` branch of\n`createRouteHandler` now computes `anyFlagged` (any integration with the\nsession-less flag) and **bypasses the full gate when ≥1 integration is\nflagged**, so the directory becomes a public front door; with 0 flagged it takes\nthe same `fullGate` as before, keeping today's login wall. `directoryPage`\ngained an `anonymousPublic` param (`authEnabled && user == null`): when set it\nfilters the listing to only flagged integrations and appends a single generic\n\"Log in to see more\" button — no name or count of the private ones leaks. A\nlogged-in visitor (admitted or not) sees the full listing, per the ticket's \"not\nan anti-enumeration boundary\" stance; clicking a private slug still 403s /\nlogin- walls via ticket 02's per-integration gate, so no private surface is\nreachable.\n\nThe two already-satisfied behaviors from ticket 02 — anonymous direct hit on an\nunflagged slug → 401 login page (not 404), and anonymous non-GET under the gate\n→ 302 to `/` — are now covered by explicit ticket-04 tests.\n\nRefactor: extracted an `isFlagged(i)` predicate anchoring the \"flagged\" domain\nconcept, replacing three inline `sessionLess === true` checks (dispatch guard,\n`anyFlagged`, directory filter).\n\nScope note: a non-GET to a **public** `/` renders the directory (200) rather\nthan 302, since the gate doesn't apply there — the ticket scopes non-GET\nbouncing to \"where the gate applies,\" and nothing POSTs to `/`. Left as-is\ndeliberately.\n\n`deno task check` (fmt + lint + typecheck + 35 tests, 6 new) is green. This repo\nis Val Town-versioned (`.vt`), not a git repo, so the work could not be\ncommitted to a git branch.\n",[],[233,620,621,620,663],"33a6e944-a46a-4e54-b8fd-64c864bdb131","03-allowlist-semantics-implicit-owner.md","fc2ffb70-7f9f-11f1-ba77-1607ee4eb77e",245,["D",1784050565339],"# 03 — Allowlist semantics + implicit owner\n\n**What to build:** The router's `users` allowlist governs only _who gains the\nprivileged surface_, with the host val owner always implicitly included, and a\nsafe-by-default meaning when omitted. This is a deliberate change from today's\n\"any logged-in Val Town account.\"\n\nSemantics (owner always implicit):\n\n- omitted `users` ⇒ owner-only\n- `[]` ⇒ owner-only\n- `[\"alice\"]` ⇒ owner + alice\n- `[\"*\"]` ⇒ owner + any logged-in user\n\nThe owner is identified by the resolver from ticket 01 (`user === owner`) and is\nnever refused by the allowlist. The allowlist gates only the privileged (gated)\nsurface — it must never gate a flagged integration's public surface (that axis\nis the session-less flag, orthogonal to this one).\n\n**Blocked by:** 01\n\n**Status:** resolved\n\n- [x] Owner reaches the privileged surface even under `users: []`\n- [x] Omitted `users` behaves as owner-only (a non-owner logged-in user is\n refused, 403)\n- [x] `[\"alice\"]` admits owner and alice, refuses everyone else\n- [x] `[\"*\"]` admits owner and any logged-in user\n- [x] The allowlist never blocks a flagged integration's public surface for an\n anonymous visitor\n- [x] Tests cover the full matrix through the `resolveIdentity` seam (fake\n `user`/`owner`)\n\n## Comments\n\nImplemented owner-aware allowlist semantics. The old `allowedUsers` (null = \"any\nlogged-in\") was replaced by `configuredUsers` (normalizes `users` to a plain\nlist; omitted / `auth: false` ⇒ `[]`) plus `isAdmitted(user, owner,\nusers)`:\nowner is always implicit (`user === owner` never refused), `\"*\"` admits any\nlogged-in account, otherwise the user must be named. So omitted / `[]` ⇒\nowner-only, `[\"alice\"]` ⇒ owner + alice, `[\"*\"]` ⇒ owner + anyone — a deliberate\nsafe-by-default change from \"any logged-in Val Town account.\" The gate now reads\nboth `user` and `owner` from the resolver at dispatch (ticket 01 already\nresolved owner; this is the ticket that consumes it).\n\n**Cross-ticket correction:** the allowlist must never gate a flagged\nintegration's public surface (spec story 17), and \"public\" means public to\neveryone — not just anonymous visitors. Ticket 02's bypass was anonymous-only,\nwhich was harmless while the allowlist defaulted permissive but would 403 a\nlogged-in-non-allowlisted user on a public integration once the default flipped\nto owner-only. Broadened the bypass: a flagged integration skips the full gate\nfor anonymous **and** logged-in visitors alike, still passing `ctx.user` so the\nintegration draws its own per-route line. The gate (login wall + allowlist)\ngoverns only the privileged surface: unflagged integrations and router-owned\npages.\n\nThe login and 403 page copy now use a shared `audienceDescription` helper so\nthey describe the real audience (the val owner, plus any named users, or any\nlogged-in account under `\"*\"`) instead of the stale \"open to any logged-in.\"\n\nDirectory publicness (04) and the `auth: false` startup throw / escape hatch\n(05) remain untouched. `deno task check` (fmt + lint + typecheck + 29 tests, 5\nnew for the allowlist matrix) is green.\n",[],[233,620,621,620,671],"fb0d368d-4ae7-401a-a2e6-5cc30af6a4a6","02-session-less-flag-and-login-signal.md","fc62710e-7f9f-11f1-80a0-1607ee4eb77e",248,["D",1784050565812],"# 02 — Session-less flag + login-location signal\n\n**What to build:** An integration can declare itself safe for session-less\ntraffic, and the router enforces that at dispatch. A request with no logged-in\nuser reaches a **flagged** integration untouched — with `ctx.user: null` and the\nlogin-location signal set — while an **unflagged** integration (the default)\ngets the login wall. A bearer client's `Authorization` header reaches a flagged\nintegration byte-intact because the router never touches it. This is the\nheadline capability of the whole effort.\n\nThe two contract additions (shapes pinned; names refinable by the implementer):\n\n- `Integration` gains a coarse boolean Session-less flag (proposed\n `sessionLess?:\n boolean`) — never a route list or predicate. Absent = fully\n gated.\n- `IntegrationContext` gains a routed-only Login-location signal (proposed\n `login: string | null`) — the router's login path when the router owns login,\n `null` when it doesn't. Disambiguates `user: null` (\"not logged in\") from \"no\n router login.\" Naturally absent standalone, where `ctx` itself is absent.\n\nEnforcement on a session-less request (`user == null`) that resolves to an\nintegration by slug: pass through to a **flagged** integration with\n`ctx.user:\nnull`; for an **unflagged** one apply the login wall — the\nrouter-owned login page (401) for GET, 302 to `/` for non-GET. The router must\nnot read or strip `Authorization` on the forwarded child request.\n\n**Blocked by:** 01\n\n**Status:** resolved\n\n- [x] `Integration` carries a coarse boolean session-less flag; unflagged is the\n default\n- [x] `IntegrationContext` carries the login-location signal; it is populated in\n routed mode only\n- [x] Anonymous request to a flagged integration reaches its handler with\n `ctx.user: null` and `ctx.login` set to the login path\n- [x] Anonymous GET to an unflagged integration returns the router login page\n (401)\n- [x] Anonymous non-GET to an unflagged integration returns 302 to `/`\n- [x] A bearer non-GET request to a flagged integration completes and the\n handler sees `Authorization` echoed byte-identical\n- [x] The flag is inert in standalone mode (no `ctx`, no enforcement)\n- [x] Tests drive all of the above through the `resolveIdentity` seam with fake\n identity\n\n## Comments\n\nImplemented the session-less flag and login-location signal. `Integration`\ngained `sessionLess?: boolean` (absent = fully gated); `IntegrationContext`\ngained `login: string | null` (the router's login path when it owns login, else\nnull — routed-only, naturally absent standalone).\n\nDispatch was restructured to gate **per matched integration** instead of once at\nthe top: identity resolves up front, the router finds the target integration by\nslug, and a session-less request (`user == null`) either passes through to a\n**flagged** integration untouched (`ctx.user: null`, `ctx.login` set) or takes\nthe shared `fullGate` (login page for GET, 302 `/` for non-GET) for an unflagged\none. Router-owned surface (directory, 404) still takes `fullGate`. The child\nrequest keeps copying `req.headers` wholesale, so a bearer client's\n`Authorization` reaches a flagged integration byte-intact — the router never\nreads or strips it.\n\nOwner-aware allowlisting (03), directory publicness (04), and the `auth: false`\nstartup throw / escape hatch (05) are intentionally left untouched; the code\ncomments name those seams. `deno task check` (fmt + lint + typecheck + 24 tests,\n6 new) is green.\n\nNote: this repo is Val Town-versioned (`.vt`), not a git repo, so the work could\nnot be committed to a git branch.\n",[],[233,620,621,620,679],"02e81b39-50f8-4b81-ac4c-547c0c74bcd1","01-prefactor-fold-owner-into-seam.md","fc49cbc2-7f9f-11f1-ba77-1607ee4eb77e",240,["D",1784047632100],"# 01 — Prefactor: fold owner identity into the router seam\n\n**What to build:** The router's single test seam learns _who owns the host val_\nalongside _who is logged in_, resolved together, with no change in behavior yet.\nThe OAuth-free core `createRouteHandler` takes one injected identity resolver\ninstead of a bare user lookup; `createRouter` wires the real one. Owner is\nresolved and available at dispatch but not yet consumed, so the whole existing\nauth matrix stays green. This settles the seam signature every later ticket\nbuilds on.\n\nThe seam shape (from the spec — pins the decision precisely):\n\n```ts\ntype Identity = { user: string | null; owner: string | null };\ntype ResolveIdentity = (req: Request) => Promise;\n\ncreateRouteHandler(options: RouterOptions, resolveIdentity: ResolveIdentity)\n```\n\n`createRouter` resolves `user` from `getOAuthUserData(req)?.user?.username` and\n`owner` from `parseVal().username` (the host handle from the auto-injected\n`VALTOWN_ENTRYPOINT`; ADR 0004 confirmed it resolves to the host even when\ncalled from an imported child module). Reading `parseVal()` inside the handler\nis rejected — owner must enter through the resolver so tests can supply a fake.\n\n**Blocked by:** None — can start immediately.\n\n**Status:** resolved\n\n- [x] `createRouteHandler` takes `resolveIdentity(req) => { user, owner }` in\n place of the bare user lookup\n- [x] `createRouter` wires the real resolver: `user` from `getOAuthUserData`,\n `owner` from `parseVal().username`\n- [x] Existing test fakes (`anon`, `as(user)`) return `{ user, owner }`; a\n helper for setting the owner exists\n- [x] Owner is resolved but consumed nowhere yet — no behavior change\n- [x] The entire existing router test suite passes unchanged (`deno task check`)\n- [x] A test asserts the resolver's `owner` reaches dispatch (even though\n nothing acts on it yet)\n\n## Comments\n\nImplemented the seam widening. `router.ts` now exports `Identity` /\n`ResolveIdentity`; `createRouteHandler` resolves the full identity at dispatch\nand reads only `user` (owner intentionally unconsumed until the allowlist\nticket). `createRouter` wires `resolveOAuthIdentity` (user from\n`getOAuthUserData`, owner from `parseVal().username`). Test fakes became\n`{ user, owner }` (`anon`, `as(user, owner?)`, new `owner(handle)`), and a new\ntest spies the resolver to assert the owner reaches dispatch. `deno task check`\n(fmt + lint + typecheck + 18 tests) is green.\n",[],[233,620,621,620,687],"2917025a-4eb4-41f8-8d9a-4d42b22e926f",221,["D",1784046053043],[260,261,262,263,264,265,266,267,268],[233,620,621,620],"aced932d-ed9a-43e6-b367-19f42975132d","fbdd8192-7f9f-11f1-8dc1-1607ee4eb77e",220,["D",1784046052922],[259,269],[233,620,621],"aa4a6455-59c8-4d23-9d6d-d79f83132cc2",219,["D",1784046052716],[258],[233,620],"8e1a1b2e-8c56-4196-b260-924cbbf03cfa","triage-labels.md","907ccfb8-7f9d-11f1-b6d2-1607ee4eb77e","9059e8a4-7f9d-11f1-87ab-1607ee4eb77e",235,["D",1784046053899],"# Triage Labels\n\nThe skills speak in terms of five canonical triage roles. This file maps those\nroles to the actual label strings used in this repo's issue tracker.\n\n| Label in mattpocock/skills | Label in our tracker | Meaning |\n| -------------------------- | -------------------- | ---------------------------------------- |\n| `needs-triage` | `needs-triage` | Maintainer needs to evaluate this issue |\n| `needs-info` | `needs-info` | Waiting on reporter for more information |\n| `ready-for-agent` | `ready-for-agent` | Fully specified, ready for an AFK agent |\n| `ready-for-human` | `ready-for-human` | Requires human implementation |\n| `wontfix` | `wontfix` | Will not be actioned |\n\nWhen a skill mentions a role (e.g. \"apply the AFK-ready triage label\"), use the\ncorresponding label string from this table.\n\nEdit the right-hand column to match whatever vocabulary you actually use.\n",[],[233,719,711],"agents","1e101ee6-b307-45fe-b71e-fbb6737eba1c","issue-tracker.md","9084574c-7f9d-11f1-901a-1607ee4eb77e",232,["D",1784046054418],"# Issue tracker: Local Markdown\n\nIssues and specs (you may know a spec as a PRD) for this repo live as markdown\nfiles in `docs/issues/`.\n\n## Conventions\n\n- One feature per directory: `docs/issues//`\n- The spec is `docs/issues//spec.md`\n- Implementation issues are one file per ticket at\n `docs/issues//issues/-.md`, numbered from `01` — never\n a single combined tickets file\n- Triage state is recorded as a `Status:` line near the top of each issue file\n (see `triage-labels.md` for the role strings)\n- Comments and conversation history append to the bottom of the file under a\n `## Comments` heading\n\n## When a skill says \"publish to the issue tracker\"\n\nCreate a new file under `docs/issues//` (creating the directory if\nneeded).\n\n## When a skill says \"fetch the relevant ticket\"\n\nRead the file at the referenced path. The user will normally pass the path or\nthe issue number directly.\n\n## Wayfinding operations\n\nUsed by `/wayfinder`. The **map** is a file with one **child** file per ticket.\n\n- **Map**: `docs/issues//map.md` — the Notes / Decisions-so-far / Fog\n body.\n- **Child ticket**: `docs/issues//issues/NN-.md`, numbered from\n `01`, with the question in the body. A `Type:` line records the ticket type\n (`research`/`prototype`/`grilling`/`task`); a `Status:` line records\n `claimed`/`resolved`.\n- **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked\n when every file it lists is `resolved`.\n- **Frontier**: scan `docs/issues//issues/` for files that are open,\n unblocked, and unclaimed; first by number wins.\n- **Claim**: set `Status: claimed` and save before any work.\n- **Resolve**: append the answer under an `## Answer` heading, set\n `Status: resolved`, then append a context pointer (gist + link) to the map's\n Decisions-so-far in `map.md`.\n",[],[233,719,721],"a0284b24-08af-4f62-9c03-c2bc7e4d09f8","domain.md","90970da6-7f9d-11f1-bb0f-1607ee4eb77e",231,["D",1784046053955],"# Domain Docs\n\nHow the engineering skills should consume this repo's domain documentation when\nexploring the codebase.\n\n## Before exploring, read these\n\n- **`CONTEXT.md`** at the repo root, or\n- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one\n `CONTEXT.md` per context. Read each one relevant to the topic.\n- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In\n multi-context repos, also check `src//docs/adr/` for context-scoped\n decisions.\n\nIf any of these files don't exist, **proceed silently**. Don't flag their\nabsence; don't suggest creating them upfront. The `/domain-modeling` skill\n(reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates\nthem lazily when terms or decisions actually get resolved.\n\n## File structure\n\nSingle-context repo (most repos):\n\n```\n/\n├── CONTEXT.md\n├── docs/adr/\n│ ├── 0001-event-sourced-orders.md\n│ └── 0002-postgres-for-write-model.md\n└── src/\n```\n\nMulti-context repo (presence of `CONTEXT-MAP.md` at the root):\n\n```\n/\n├── CONTEXT-MAP.md\n├── docs/adr/ ← system-wide decisions\n└── src/\n ├── ordering/\n │ ├── CONTEXT.md\n │ └── docs/adr/ ← context-specific decisions\n └── billing/\n ├── CONTEXT.md\n └── docs/adr/\n```\n\n## Use the glossary's vocabulary\n\nWhen your output names a domain concept (in an issue title, a refactor proposal,\na hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift\nto synonyms the glossary explicitly avoids.\n\nIf the concept you need isn't in the glossary yet, that's a signal — either\nyou're inventing language the project doesn't use (reconsider) or there's a real\ngap (note it for `/domain-modeling`).\n\n## Flag ADR conflicts\n\nIf your output contradicts an existing ADR, surface it explicitly rather than\nsilently overriding:\n\n> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_\n",[],[233,719,729],"e6fa7b96-39fd-4acf-9d85-c5c12bafb14d",213,["D",1784045013350],[254,255,256],[233,719],"1f3c8412-a3b8-4177-a484-f4aea9808ae2","0004-session-less-auth.md","fc89fc34-7f99-11f1-8a90-1607ee4eb77e","c2500b00-7cb3-11f1-accf-1607ee4eb77e",209,["D",1784043476704],"# Session-less requests reach integrations by a single integration-declared flag\n\nA routed integration opts into session-less traffic with **one coarse flag**\nmeaning \"safe to receive requests with no logged-in user, period.\" The router\nenforces that flag at dispatch: a request with no session reaches a flagged\nintegration untouched and is refused (login wall) for an unflagged one. This is\nthe map's null hypothesis — extend v1's \"router authenticates, integration\nauthorizes\" — confirmed and sharpened by a spike\n(`nbbaier/wayfinder-auth-spike`, 2026-07-13). It resolves both problems v1\ndeferred: anonymous public reads (the tracker's viewer role was lost behind the\nlogin wall) and machine-credential pass-through (bearer-token clients couldn't\nreach `/api` behind a gated router).\n\nThe flag is _not_ a route list or predicate. The integration's own per-route\nauthorization — already required for standalone mode — draws the fine line, so\nthere is no second, drift-prone copy of the route table. `type` is not declared:\nan integration is \"public docs\" (flag, no internal checks), \"the tracker\" (flag,\ninternal checks), or \"the blob viewer\" (no flag) purely by flag + how much it\nchecks itself. Default: unflagged = fully gated, at zero declaration cost.\n\n## Authority split\n\nThe integration declares the **ceiling** of public exposure; the host may\n**narrow** silently and **widen** only loudly.\n\n- **Integration declares, router enforces.** The flag is the integration\n author's claim about its own surface. The router is the only enforcement\n point, at dispatch.\n- **Machine credentials pass through untouched.** The router never reads\n `Authorization`; a bearer request is just another session-less request, and\n the integration validates its own key (router-opaque anyway). No router-minted\n token scheme — that would mean two secrets per headless client.\n- **The `users` allowlist is orthogonal to the flag.** The allowlist governs\n _who may log in / gains the privileged surface_; it never gates a flagged\n integration's public surface. A locked-down owner-only router still exposes\n its flagged integrations' public surface to anonymous — that is what the flag\n means. \"Who is trusted\" and \"is this surface public\" are different questions.\n- **The host val owner is always implicitly allowlisted**, realizable at runtime\n via `getOAuthUserData(req)?.user.username === parseVal().username` (the owner\n handle comes from the auto-injected `VALTOWN_ENTRYPOINT`, no login needed). So\n `[]` = owner only, `[\"*\"]` = owner + anyone, `[\"user1\"]` = owner + user1, and\n **omitted = owner only** — a deliberate, safe-by-default change from today's\n \"any logged-in user.\"\n- **Host-side narrowing is a named extension point, not built.** No requirement\n demands a mechanism for a host to make a flagged integration _more_ private on\n one deployment, so v1 ships none but names the seam. It is the safe direction\n and needs no acknowledgment.\n- **The one sanctioned widening: an escape hatch.** A host may knowingly\n force-mount an _unflagged_ integration on an `auth: false` router (which\n otherwise throws). It lives host-side in the router config (never on the\n integration — that would just _be_ the flag), is per-integration and\n explicitly named (so a _new_ unflagged integration later still throws), and is\n surfaced visibly at startup. Exact option name and any warning log → build.\n\n## The context gains a login-location signal\n\n`ctx.user: null` conflates \"the router has no login\" with \"the visitor hasn't\nlogged in.\" The context gains a signal telling the integration _where login\nlives, or that it doesn't_ — so a flagged integration can render a working\nlog-in link when a router owns login, and omit it when none exists. Exact field\nname and shape → build.\n\n## The router's own surface\n\nThe router is **not** an anti-enumeration boundary (Val Town rarely hosts\nsensitive data), so least-surprise and standalone-parity decide its surface:\n\n- `/` (the directory page) is public **iff ≥1 integration is flagged**;\n otherwise today's login wall stands.\n- Anonymous sees **only flagged** integrations listed, plus a generic \"log in to\n see more\" (no count of what's hidden).\n- Hitting a private integration's URL directly → the single router-owned **login\n page (401)**, matching standalone, not a 404.\n- Anonymous non-GET (e.g. a stale-tab POST) → today's **302 to `/`**.\n\n## Standalone mode\n\nThe whole session-less model is **routed-only**; standalone is unchanged and\nthis ADR prescribes no new standalone mechanism. The flag is inert standalone\n(no router to enforce it; an unflagged integration was already public\nstandalone). Sessions never flow through `ctx`: an integration wanting login\nwires its own std/oauth and reads `getOAuthUserData(req)` directly (the tracker\nalready does this, `app.tsx:117–145`). Only the _source_ of \"the current user\"\nchanges by mode — `ctx.user` when routed, `getOAuthUserData` when standalone —\nand the login-location signal is one more routed-only `ctx` field.\n\n## Startup validation\n\n`auth: false` plus an unflagged integration is a contradiction — session-less\ntraffic with nothing declared safe — and makes `createRouter` **throw**, like a\nduplicate slug. The escape hatch above is the only way to proceed knowingly.\n\n## Considered Options\n\n- **Router-side host config of the public surface** — rejected on _knowledge_:\n only the tracker knows its public line is \"all GET pages except `/new`, plus\n GET `/api/*`.\" Pushing that to the host duplicates and desyncs the route\n table.\n- **Pass everything through, integration decides all** — rejected on the\n blob-viewer hazard: an owner-less viewer would hand anonymous full admin. A\n gated default is required.\n- **Dual / split mounts (a public mount + a gated mount)** — rejected: forces\n integrations to split even when public and gated routes interleave, as the\n tracker's do (`GET /` public, `GET /new` gated).\n- **A router-minted bearer scheme** — rejected: two secrets per headless client\n for no gain, since the integration's own key is what actually authorizes.\n\n## Consequences — spike evidence\n\nAll five load-bearing assumptions survived the Val Town runtime\n(`nbbaier/wayfinder-auth-spike`, kept until this ADR merges):\n\n- **Selective pass-through works.** Anonymous reaches flagged surfaces while\n unflagged ones on the same router 401; login works alongside.\n- **Bearer non-GET writes pass intact.** A bearer write completed through the\n gated router with header and body echoed byte-identical, no redirect — the\n router never touches `Authorization`.\n- **Interleaved public/gated routes behave standalone-identically.** The\n tracker-analog's `GET /new` still 403s behind the router.\n- **The login signal renders and login round-trips.** Anonymous-but-allowed\n pages show a working log-in link; logging in returns a session.\n- **Origin-bound sessions don't bite.** Routed mode is a single origin, so one\n session covers every slug (the ticket-1 caveat is moot here).\n\nOwner identification was confirmed running (2026-07-14, throwaway\n`nbbaier/wayfinder-owner-confirm`, since deleted): on an anonymous request,\n`VALTOWN_ENTRYPOINT` is populated, `parseVal().username` returns the host\nowner's handle, and — critically — `parseVal()` called inside an _imported child\nmodule_ still resolves to the host entrypoint, not the child's own val. So\n`getOAuthUserData(req)?.user.username === parseVal().username` and the\n`omitted = owner-only` default are runtime-sound, closing the last load-bearing\nunknown behind the map's spike-validation bar.\n\n## Out of scope\n\nThe build — contract API shape, option and type names, the `ctx` field changes,\nmigrating the tracker and blob viewer, docs — is a fresh effort chartered by\nthis ADR. Directory-page customization (bring-your-own directory UI) is a\nseparate future mission.\n",[],[233,750,742],"adr","79e95003-6a1e-4723-8bd9-149183490a34","0003-callable-integrations.md","38b33f42-7d40-11f1-9235-1607ee4eb77e",190,["D",1784043353617],"# defineIntegration returns a callable Integration\n\n`defineIntegration` returns the `Integration` object made directly callable as\nan HTTP handler (`CallableIntegration = Integration & IntegrationHandler`;\ncalling it with no ctx is standalone mode). The charter requires every\nintegration factory to serve both modes — `export default myFactory({...})` as a\nstandalone HTTP val AND `createRouter({ integrations: [myFactory({...})] })` —\nand an `Integration` is a plain object, not a function, so without this the two\nmounting styles would need different factory return values (`.handler` in one\nplace, the object in the other). Making the contract helper produce the hybrid\ngives every author dual-mode support for free; the val-issue-tracker migration\nproved the need.\n\n## Consequences\n\n- `export default myFactory({...})` is a valid HTTP val export; the platform\n calls it with no ctx, which is exactly the standalone signal the contract\n already defined (`ctx` absent).\n- Integration fields are attached with `Object.defineProperty` because a\n function's own `name` is read-only-but-configurable and `Integration.name`\n must shadow it.\n- The router still calls `.handler(req, ctx)`; plain object literals that merely\n satisfy the `Integration` type keep working when registered, they just aren't\n standalone-mountable.\n",[],[233,750,752],"833d0d53-68c3-41a6-955f-a3bdb86856f2","0002-location-header-rewriting.md","cf4fd38c-7cb6-11f1-b356-1607ee4eb77e",188,["D",1784043353264],"# The router rewrites root-absolute Location headers, and only those\n\nWhen a mounted integration responds with a `Location` header starting with `/`,\nthe router prepends the mount prefix (`Location: /?ok=x` → `/issues/?ok=x`);\nHTML bodies are never rewritten. We chose this asymmetry — over rewriting\nnothing (strict authoring rule) or rewriting everything (full reverse-proxy) —\nbecause HTML links have the document base URL as a safety net, so relative links\nare natural to write, while redirects are generated far from any notion of\n\"where am I mounted\"; covering `Location` makes the ubiquitous\nredirect-after-POST idiom (`c.redirect(\"/?ok=...\")`) work unmodified in both\nrouted and standalone modes with zero branching, exactly like nginx's\n`proxy_redirect`.\n\n## Consequences\n\n- An integration cannot reach the router root or a sibling integration via a\n bare `/...` redirect; it uses `ctx.prefix` or a full absolute URL. Rare and\n deliberate by design.\n- Body rewriting stays the author's responsibility: relative URLs, or\n `ctx.prefix` when an absolute path is unavoidable.\n",[],[233,750,760],"aff11007-0c7c-43aa-9d2a-2b44ddb4d951","0001-dispatch-architecture.md","c2a2a518-7cb3-11f1-af02-1607ee4eb77e",187,["D",1784043353120],"# In-process prefix dispatch, not sibling-endpoint redirects\n\nThe router (`createRouter`) mounts integrations **in-process**: one HTTP\nendpoint holds every registered integration's fetch handler and dispatches by\npath prefix (`/issues/*` → issue tracker), rewriting the request URL and passing\nmount context along. We prototyped both this and the alternative — each\nintegration as its own sibling HTTP file in the host val, with a directory\nendpoint 302-ing out — and chose in-process (2026-07-10, prototype since\ndeleted; evidence recorded on wayfinder ticket 1).\n\n## Considered Options\n\n**Sibling endpoints + redirecting directory** was rejected. Its one real\nadvantage — existing integrations work unmodified — evaporated when the\nprototype showed the in-process authoring burden collapses to a one-line rule:\nwith the router canonicalizing `/slug` → `/slug/`, plain relative URLs just\nwork, and only root-absolute paths break. What it could never offer: each\nsibling file is its own origin, so users log in separately per integration, the\nsingle URL is only a launcher, and `createRouter({ integrations: [...] })` can't\nexist — mounting means creating a file per integration instead of importing a\nfactory.\n\n## Consequences\n\n- One origin: one OAuth login for every integration. Verified: the router wraps\n `oauthMiddleware` once, and `getOAuthUserData` works both in the router and\n inside a prefix-mounted child (session cookies survive the request rewrite).\n- Integration authors must use relative URLs (or the provided mount prefix) and\n never root-absolute paths; the router guarantees trailing-slash\n canonicalization of the mount root.\n- Scoped SQLite/blob need no special handling — storage is val-scoped, so\n in-process children naturally share the host val's data (verified; true of the\n rejected option too).\n- Request bodies are re-wrapped during URL rewriting; the router buffers them\n rather than streaming.\n",[],[233,750,768],"b8d5d5fd-e95b-4cdc-831d-08861e689a73",32,["D",1783724692595],[249,250,251,252],[233,750],["D",1783724692393],[248,253,257,270,272],[233],["D",1783715038579],["D",1789525245864],{"_11":12,"_89":85},{"_11":12,"_83":-5,"_84":85,"_45":46,"_86":87,"_88":38},{"_29":30,"_13":26,"_20":21,"_27":28,"_31":-5,"_32":-5,"_78":-5,"_79":-5,"_80":-5,"_81":14,"_82":12},"ctx",{"_71":-5,"_111":821,"_822":823,"_824":825,"_826":38,"_827":38,"_828":38,"_829":109,"_830":-5,"_831":-7,"_832":-7,"_833":52,"_834":38,"_835":38,"_836":-5,"_837":38,"_838":38,"_839":38,"_840":-5},"ENV",{"_792":793,"_794":795,"_796":26,"_797":798,"_799":800,"_801":802,"_803":804,"_805":806,"_807":808,"_809":810,"_811":812,"_813":814,"_815":816,"_817":818,"_819":820},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]

Branches1

Branches
1