[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_622":623,"_624":625},"routes/_app.x.$handle.$name",{"_96":95,"_31":43,"_104":86,"_26":51,"_13":14,"_105":-5,"_11":106,"_107":108,"_109":110,"_111":112,"_113":114,"_20":-5,"_115":-5,"_116":-5,"_117":24,"_118":119,"_120":121,"_122":-5,"_123":-5,"_124":125},"routes/_app.x.$handle.$name.branch.$branch.version.$version.diff",{"_11":12,"_13":14,"_15":16,"_17":-5,"_18":-5},"project",{"_41":42,"_31":43,"_36":44,"_45":-5,"_46":24,"_47":48,"_49":48,"_50":51,"_52":-5,"_18":53,"_54":-5,"_55":24,"_56":-5,"_57":-5,"_58":59,"_60":61,"_62":63,"_64":65,"_66":67,"_68":-5,"_69":70,"_71":70,"_72":73,"_74":73,"_75":73,"_76":70,"_77":70,"_78":79,"_80":81,"_82":83,"_84":24},"version",168,"changes",[19],"aiChatInfo","userId",{"_20":21,"_22":-7,"_23":24,"_25":24,"_26":27,"_28":27},"file",{"_29":30,"_31":32,"_33":20,"_34":35,"_36":37,"_38":14,"_39":40,"_23":24},"previous","deleted",false,"deletedHere","path","wayfinder/assets/009-identify-val-owner-at-runtime.md","latestPath","fileId","e775649c-7f0c-11f1-bafc-1607ee4eb77e","name","009-identify-val-owner-at-runtime.md","fileType","content","# Can the router identify the val owner at runtime?\n\nResearch summary for ticket [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` — https://esm.town/v/std/utils@283-main/parseImportMeta.ts\n- `std/oauth` callback (`isOrgMember`) — https://esm.town/v/std/oauth@233-main/middleware/index.ts\n (public `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 https://docs.val.town/reference/environment-variables/\n and Runtime 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 `https://esm.town/v//@-/...`.\n `parseVal()` regex-captures `username` = **the owner handle of the entrypoint\n (host) val**, 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.\nThat is strong primary evidence of an undocumented-but-relied-upon platform env\nvar, not 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\n\"owner-of-the-val OR member-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 come\nfrom 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\nhandle strings match casing/format between `user.username` and the parsed\n`username`. Those 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.** `Deno.env.get(\"VALTOWN_ENTRYPOINT\")`\n → `parseVal().username` yields the executing (entrypoint) val's owner handle\n with no session. Undocumented in public docs but relied on by std/utils and\n 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\n org 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 `getOAuthUserData(req)?.user.username === parseVal().username`.\n No HITL login probe is required to justify it; a probe only empirically\n confirms VALTOWN_ENTRYPOINT is populated and the handles match string-for-string.\n Do NOT downgrade to explicit self-listing.\n","createdAt",["D",1783982882094],"branchVersion","branchId","e42b787b-83d6-45c3-a695-f58ae023cdb8","id","3688ffe3-491b-42ec-b390-53d2293f502f","integrations",["D",1783715038579],"deletedAt","legacyEnvVars","privacy","public","httpPrivacy","description","","imageUrl","5d1042a9-7b0b-499d-8a72-3a8ac7a4e185","pinnedFileId","pinPreview","pinMigrated","screenshotVersion","likeCount",0,"orgId","5f80108f-7ca4-4327-b77b-089dbe4b5a82","tursoName","3688ffe3491b42ecb39053d2293f502f","tursoHostname","3688ffe3491b42ecb39053d2293f502f-val-town.aws-us-east-2.turso.io","tursoMeasuredAt",["D",1789525245864],"pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_96":95,"_103":99},"org",{"_96":95,"_97":-5,"_98":99,"_18":53,"_100":101,"_102":24},"branch",{"_13":85,"_31":86,"_41":40,"_87":42,"_88":-5,"_89":-5,"_90":-5,"_91":-5,"_92":-5,"_93":43,"_94":95},"isOwned",261,"main","projectId","forkedBranchId","forkedBranchVersion","forkedProjectPrivacy","forkedProjectId","forkedProjectOrgId","projectName","userHandle","nbbaier","handle","displayName","avatar","https://secure.gravatar.com/avatar/0129a541b7b3574e92c4afd06c5e32da&d=identicon","tier","pro","canRestrictVals","profileImageUrl","branchName","adoptOrgId",{"_41":42,"_31":43,"_36":617,"_45":-5,"_46":24,"_47":48,"_49":48,"_50":51,"_52":-5,"_18":53,"_54":-5,"_55":24,"_56":-5,"_57":-5,"_58":59,"_60":61,"_62":63,"_64":65,"_66":618,"_68":-5,"_69":70,"_71":70,"_72":73,"_74":73,"_75":73,"_76":70,"_77":70,"_78":619,"_80":620,"_82":621,"_84":24},"tree",[246,266,270,286,287,288,289,290,291,292,293,294,295],"files",[246,247,248,249,250,251,252,253,254,255,256,257,258,259,260,261,262,263,264,265,266,267,268,269,270,271,272,273,274,275,276,277,278,279,280,281,282,283,284,285,286,287,288,289,290,291,292,293,294,295],"counts",{"_236":59,"_237":146,"_238":59,"_239":240,"_241":242},"contents",[126,127,128,129,130,131,132,133,134,135,136,137,138],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles",true,"grants","orgs","customDomains",{},{"_41":230,"_31":231,"_29":232,"_142":-5,"_39":40,"_38":233,"_144":121,"_36":234,"_13":59,"_33":222,"_34":-5,"_23":24,"_149":-5,"_26":235},{"_41":224,"_31":225,"_29":226,"_142":-5,"_39":40,"_38":227,"_144":121,"_36":228,"_13":59,"_33":222,"_34":-5,"_23":24,"_149":-5,"_26":229},{"_41":217,"_31":218,"_29":219,"_142":-5,"_39":40,"_38":220,"_144":121,"_36":221,"_13":59,"_33":222,"_34":-5,"_23":24,"_149":-5,"_26":223},{"_41":210,"_31":211,"_29":212,"_142":-5,"_39":40,"_38":213,"_144":121,"_36":214,"_13":59,"_33":20,"_34":215,"_23":24,"_149":-5,"_26":216},{"_41":203,"_31":204,"_29":205,"_142":-5,"_39":40,"_38":206,"_144":24,"_36":207,"_13":180,"_33":20,"_34":208,"_23":24,"_149":-5,"_26":209},{"_41":196,"_31":197,"_29":198,"_142":-5,"_39":40,"_38":199,"_144":24,"_36":200,"_13":180,"_33":20,"_34":201,"_23":24,"_149":-5,"_26":202},{"_41":189,"_31":190,"_29":191,"_142":-5,"_39":40,"_38":192,"_144":24,"_36":193,"_13":156,"_33":20,"_34":194,"_23":24,"_149":-5,"_26":195},{"_41":183,"_31":184,"_29":185,"_142":-5,"_39":40,"_38":156,"_144":24,"_36":186,"_13":59,"_33":20,"_34":187,"_23":24,"_149":-5,"_26":188},{"_41":175,"_31":176,"_29":177,"_142":-5,"_39":40,"_38":178,"_144":24,"_36":179,"_13":180,"_33":20,"_34":181,"_23":24,"_149":-5,"_26":182},{"_41":166,"_31":167,"_29":168,"_142":-5,"_39":40,"_38":169,"_144":24,"_36":170,"_13":171,"_33":172,"_34":173,"_23":24,"_149":-5,"_26":174},{"_41":159,"_31":160,"_29":161,"_142":-5,"_39":40,"_38":162,"_144":24,"_36":163,"_13":156,"_33":147,"_34":164,"_23":24,"_149":-5,"_26":165},{"_41":151,"_31":152,"_29":153,"_142":-5,"_39":40,"_38":154,"_144":24,"_36":155,"_13":156,"_33":147,"_34":157,"_23":24,"_149":-5,"_26":158},{"_41":139,"_31":140,"_29":141,"_142":-5,"_39":40,"_38":143,"_144":24,"_36":145,"_13":146,"_33":147,"_34":148,"_23":24,"_149":-5,"_26":150},"e82a3846-9a4b-4c4c-98cd-9618b617cea5","router_test.ts","47cd43fc-7cb8-11f1-bf06-1607ee4eb77e","parentId",71,"latest",["D",1783785020744],1,"script","import { assert, assertEquals, assertThrows } from \"@std/assert\";\nimport {\n\tcreateRouteHandler,\n\tdefineIntegration,\n\ttype IntegrationContext,\n\ttype RouterOptions,\n} from \"./router.ts\";\n\nconst anon = () => Promise.resolve(null);\nconst as = (user: string) => () => Promise.resolve(user);\n\nfunction echoIntegration(slug: string, name = slug) {\n\tlet lastCtx: IntegrationContext | undefined;\n\tconst integration = defineIntegration({\n\t\tname,\n\t\tslug,\n\t\thandler: async (req, ctx) => {\n\t\t\tlastCtx = ctx;\n\t\t\tconst url = new URL(req.url);\n\t\t\tif (req.method === \"POST\") {\n\t\t\t\treturn new Response(`echo:${await req.text()}`);\n\t\t\t}\n\t\t\tif (url.pathname === \"/redirect\") {\n\t\t\t\treturn new Response(null, {\n\t\t\t\t\tstatus: 302,\n\t\t\t\t\theaders: { Location: \"/?ok=done\" },\n\t\t\t\t});\n\t\t\t}\n\t\t\tif (url.pathname === \"/redirect-external\") {\n\t\t\t\treturn new Response(null, {\n\t\t\t\t\tstatus: 302,\n\t\t\t\t\theaders: { Location: \"https://example.com/x\" },\n\t\t\t\t});\n\t\t\t}\n\t\t\tif (url.pathname === \"/redirect-protocol-relative\") {\n\t\t\t\treturn new Response(null, {\n\t\t\t\t\tstatus: 302,\n\t\t\t\t\theaders: { Location: \"//example.com/x\" },\n\t\t\t\t});\n\t\t\t}\n\t\t\treturn new Response(`path:${url.pathname}`);\n\t\t},\n\t});\n\treturn { integration, ctx: () => lastCtx };\n}\n\nfunction router(opts: Partial, getUser = anon) {\n\treturn createRouteHandler(\n\t\t{ integrations: [], auth: false, ...opts },\n\t\tgetUser,\n\t);\n}\n\n// ---------------------------------------------------------------------------\n// Validation\n// ---------------------------------------------------------------------------\n\nDeno.test(\"defineIntegration rejects invalid slugs\", () => {\n\tfor (const slug of [\"\", \"Bad\", \"has_underscore\", \"has space\", \"café\"]) {\n\t\tassertThrows(\n\t\t\t() =>\n\t\t\t\tdefineIntegration({ name: \"x\", slug, handler: () => new Response() }),\n\t\t\tError,\n\t\t\t\"invalid\",\n\t\t);\n\t}\n});\n\nDeno.test(\"reserved slugs throw\", () => {\n\tassertThrows(\n\t\t() =>\n\t\t\tdefineIntegration({\n\t\t\t\tname: \"x\",\n\t\t\t\tslug: \"auth\",\n\t\t\t\thandler: () => new Response(),\n\t\t\t}),\n\t\tError,\n\t\t\"reserved\",\n\t);\n});\n\nDeno.test(\"duplicate slugs throw at construction\", () => {\n\tconst a = echoIntegration(\"toy\").integration;\n\tconst b = echoIntegration(\"toy\").integration;\n\tassertThrows(() => router({ integrations: [a, b] }), Error, \"Duplicate\");\n});\n\nDeno.test(\"defineIntegration returns a callable integration serving both modes\", async () => {\n\tconst integration = defineIntegration({\n\t\tname: \"Toy Thing\",\n\t\tslug: \"toy\",\n\t\thandler: (_req, ctx) => new Response(`user:${ctx?.user ?? \"none\"}`),\n\t});\n\t// Integration fields survive on the callable (incl. `name`, which must\n\t// shadow the function's own read-only name).\n\tassertEquals(integration.name, \"Toy Thing\");\n\tassertEquals(integration.slug, \"toy\");\n\t// Standalone: called as a plain HTTP handler, no ctx.\n\tconst standalone = await integration(new Request(\"https://r.test/\"));\n\tassertEquals(await standalone.text(), \"user:none\");\n\t// Routed: ctx flows through to the wrapped handler.\n\tconst routed = await integration(new Request(\"https://r.test/\"), {\n\t\tuser: \"nbbaier\",\n\t\tprefix: \"/toy\",\n\t});\n\tassertEquals(await routed.text(), \"user:nbbaier\");\n});\n\n// ---------------------------------------------------------------------------\n// Dispatch\n// ---------------------------------------------------------------------------\n\nDeno.test(\"dispatch strips the prefix and passes ctx\", async () => {\n\tconst { integration, ctx } = echoIntegration(\"toy\");\n\tconst handle = router({ integrations: [integration] });\n\tconst res = await handle(new Request(\"https://r.test/toy/deep/path?q=1\"));\n\tassertEquals(await res.text(), \"path:/deep/path\");\n\tassertEquals(ctx()?.prefix, \"/toy\");\n\tassertEquals(ctx()?.user, null);\n});\n\nDeno.test(\"bare /slug canonicalizes to /slug/ preserving the query\", async () => {\n\tconst { integration } = echoIntegration(\"toy\");\n\tconst handle = router({ integrations: [integration] });\n\tconst res = await handle(new Request(\"https://r.test/toy?q=1\"));\n\tassertEquals(res.status, 302);\n\tassertEquals(res.headers.get(\"Location\"), \"/toy/?q=1\");\n});\n\nDeno.test(\"POST bodies survive the rewrite\", async () => {\n\tconst { integration } = echoIntegration(\"toy\");\n\tconst handle = router({ integrations: [integration] });\n\tconst res = await handle(\n\t\tnew Request(\"https://r.test/toy/\", { method: \"POST\", body: \"hello\" }),\n\t);\n\tassertEquals(await res.text(), \"echo:hello\");\n});\n\nDeno.test(\"unknown paths 404; root serves the directory\", async () => {\n\tconst { integration } = echoIntegration(\"toy\", \"Toy Thing\");\n\tconst handle = router({ integrations: [integration], title: \"My Tools\" });\n\tassertEquals((await handle(new Request(\"https://r.test/nope\"))).status, 404);\n\tconst dir = await handle(new Request(\"https://r.test/\"));\n\tassertEquals(dir.status, 200);\n\tconst html = await dir.text();\n\tassert(html.includes(\"My Tools\"));\n\tassert(html.includes(\"Toy Thing\"));\n\tassert(html.includes(`href=\"toy/\"`)); // relative link, per the hygiene rule\n});\n\nDeno.test(\"directory badges missing requiredEnv\", async () => {\n\tconst integration = defineIntegration({\n\t\tname: \"Needy\",\n\t\tslug: \"needy\",\n\t\trequiredEnv: [\"DEFINITELY_NOT_SET_FOR_TESTS_XYZ\"],\n\t\thandler: () => new Response(),\n\t});\n\tconst handle = router({ integrations: [integration] });\n\tconst html = await (await handle(new Request(\"https://r.test/\"))).text();\n\tassert(html.includes(\"missing env\"));\n\tassert(html.includes(\"DEFINITELY_NOT_SET_FOR_TESTS_XYZ\"));\n});\n\n// ---------------------------------------------------------------------------\n// Location rewriting (ADR 0002)\n// ---------------------------------------------------------------------------\n\nDeno.test(\"root-absolute Location headers get the prefix prepended\", async () => {\n\tconst { integration } = echoIntegration(\"toy\");\n\tconst handle = router({ integrations: [integration] });\n\tconst res = await handle(new Request(\"https://r.test/toy/redirect\"));\n\tassertEquals(res.headers.get(\"Location\"), \"/toy/?ok=done\");\n});\n\nDeno.test(\"absolute and protocol-relative Locations pass through untouched\", async () => {\n\tconst { integration } = echoIntegration(\"toy\");\n\tconst handle = router({ integrations: [integration] });\n\tconst abs = await handle(new Request(\"https://r.test/toy/redirect-external\"));\n\tassertEquals(abs.headers.get(\"Location\"), \"https://example.com/x\");\n\tconst proto = await handle(\n\t\tnew Request(\"https://r.test/toy/redirect-protocol-relative\"),\n\t);\n\tassertEquals(proto.headers.get(\"Location\"), \"//example.com/x\");\n});\n\n// ---------------------------------------------------------------------------\n// Auth gate\n// ---------------------------------------------------------------------------\n\nDeno.test(\"auth on: anonymous GET gets the login page, non-GET bounces home\", async () => {\n\tconst { integration } = echoIntegration(\"toy\");\n\tconst handle = router({ integrations: [integration], auth: {} });\n\tconst res = await handle(new Request(\"https://r.test/toy/\"));\n\tassertEquals(res.status, 401);\n\tassert((await res.text()).includes(\"/auth/login\"));\n\tconst post = await handle(\n\t\tnew Request(\"https://r.test/toy/\", { method: \"POST\", body: \"x\" }),\n\t);\n\tassertEquals(post.status, 302);\n\tassertEquals(post.headers.get(\"Location\"), \"/\");\n});\n\nDeno.test(\"auth on: logged-in user reaches the integration with ctx.user set\", async () => {\n\tconst { integration, ctx } = echoIntegration(\"toy\");\n\tconst handle = router(\n\t\t{ integrations: [integration], auth: {} },\n\t\tas(\"nbbaier\"),\n\t);\n\tconst res = await handle(new Request(\"https://r.test/toy/\"));\n\tassertEquals(res.status, 200);\n\tassertEquals(ctx()?.user, \"nbbaier\");\n});\n\nDeno.test(\"allowlist: outsiders get 403, listed users get in\", async () => {\n\tconst { integration } = echoIntegration(\"toy\");\n\tconst opts = { integrations: [integration], auth: { users: [\"nbbaier\"] } };\n\tconst outsider = router(opts, as(\"mallory\"));\n\tassertEquals(\n\t\t(await outsider(new Request(\"https://r.test/toy/\"))).status,\n\t\t403,\n\t);\n\tconst owner = router(opts, as(\"nbbaier\"));\n\tassertEquals((await owner(new Request(\"https://r.test/toy/\"))).status, 200);\n});\n\nDeno.test(\"auth off: ctx.user is null and everything is open\", async () => {\n\tconst { integration, ctx } = echoIntegration(\"toy\");\n\tconst handle = router({ integrations: [integration], auth: false });\n\tconst res = await handle(new Request(\"https://r.test/toy/\"));\n\tassertEquals(res.status, 200);\n\tassertEquals(ctx()?.user, null);\n});\n","label",[140],"6d9c7cc6-2910-4978-adbd-ba54003f0921","router.ts","47659324-7cb8-11f1-b846-1607ee4eb77e",67,["D",1783785020715],2,"// The integrations contract and router. Public surface is re-exported from\n// mod.ts; import from there. See docs/adr/ for the dispatch architecture\n// (0001) and Location-rewriting (0002) decisions.\nimport {\n\tgetOAuthUserData,\n\toauthMiddleware,\n} from \"https://esm.town/v/std/oauth/middleware.ts\";\n\nexport interface IntegrationContext {\n\t/** Val Town username from router-owned OAuth; null when auth is off. */\n\tuser: string | null;\n\t/** Mount prefix, e.g. \"/issues\". */\n\tprefix: string;\n}\n\nexport type IntegrationHandler = (\n\treq: Request,\n\tctx?: IntegrationContext,\n) => Response | Promise;\n\nexport interface Integration {\n\tname: string;\n\tslug: string;\n\tdescription?: string;\n\t/** Env vars the integration needs; missing ones badge the directory page. */\n\trequiredEnv?: string[];\n\thandler: IntegrationHandler;\n}\n\n/**\n * An Integration that is also directly callable as an HTTP handler, so the\n * same factory return value serves both modes (ADR 0003):\n *\n * export default myIntegration({...}); // standalone val\n * createRouter({ integrations: [myIntegration({...})] }); // routed\n */\nexport type CallableIntegration = Integration & IntegrationHandler;\n\nexport type RouterAuthOptions = { users?: string | string[] } | false;\n\nexport interface RouterOptions {\n\t/** Order here is the directory page order. */\n\tintegrations: Integration[];\n\t/** Default: on, any logged-in Val Town user. `false` disables the gate. */\n\tauth?: RouterAuthOptions;\n\ttitle?: string;\n}\n\nconst SLUG_PATTERN = /^[a-z0-9-]+$/;\n// \"auth\" is std/oauth's fixed /auth/* mount; /^_/ is the router-owned\n// namespace, reserved forever so the set never needs to grow again.\nconst RESERVED_SLUGS: (string | RegExp)[] = [\"auth\", /^_/];\n\nfunction isReserved(slug: string): boolean {\n\treturn RESERVED_SLUGS.some((r) =>\n\t\ttypeof r === \"string\" ? r === slug : r.test(slug),\n\t);\n}\n\nfunction validateSlug(slug: string): void {\n\tif (!SLUG_PATTERN.test(slug)) {\n\t\tthrow new Error(\n\t\t\t`Integration slug \"${slug}\" is invalid: slugs must match ${SLUG_PATTERN}.`,\n\t\t);\n\t}\n\tif (isReserved(slug)) {\n\t\tthrow new Error(`Integration slug \"${slug}\" is reserved by the router.`);\n\t}\n}\n\nexport function defineIntegration(\n\tintegration: Integration,\n): CallableIntegration {\n\tvalidateSlug(integration.slug);\n\tconst callable = ((req: Request, ctx?: IntegrationContext) =>\n\t\tintegration.handler(req, ctx)) as CallableIntegration;\n\tfor (const [key, value] of Object.entries(integration)) {\n\t\tif (value === undefined) continue;\n\t\t// defineProperty, not assignment: a function's own `name` is read-only\n\t\t// (but configurable), and Integration.name must shadow it.\n\t\tObject.defineProperty(callable, key, {\n\t\t\tvalue,\n\t\t\tenumerable: true,\n\t\t\tconfigurable: true,\n\t\t\twritable: true,\n\t\t});\n\t}\n\treturn callable;\n}\n\n// ---------------------------------------------------------------------------\n// HTML\n// ---------------------------------------------------------------------------\n\nfunction escapeHtml(s: string): string {\n\treturn s.replace(\n\t\t/[&<>\"']/g,\n\t\t(c) =>\n\t\t\t({\n\t\t\t\t\"&\": \"&\",\n\t\t\t\t\"<\": \"<\",\n\t\t\t\t\">\": \">\",\n\t\t\t\t'\"': \""\",\n\t\t\t\t\"'\": \"'\",\n\t\t\t})[c] as string,\n\t);\n}\n\nfunction page(title: string, body: string, status = 200): Response {\n\treturn new Response(\n\t\t`\n\n${escapeHtml(title)}\n${body}`,\n\t\t{ status, headers: { \"Content-Type\": \"text/html; charset=utf-8\" } },\n\t);\n}\n\nfunction missingEnv(keys: string[] | undefined): string[] {\n\tif (!keys) return [];\n\treturn keys.filter((k) => {\n\t\ttry {\n\t\t\treturn !Deno.env.get(k);\n\t\t} catch {\n\t\t\treturn false; // no env permission — don't false-alarm\n\t\t}\n\t});\n}\n\nfunction directoryPage(\n\toptions: RouterOptions,\n\tuser: string | null,\n\tauthEnabled: boolean,\n): Response {\n\tconst title = options.title ?? \"Integrations\";\n\tconst items = options.integrations\n\t\t.map((i) => {\n\t\t\tconst missing = missingEnv(i.requiredEnv);\n\t\t\treturn `

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

${escapeHtml(i.description)}

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

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

`\n\t\t: \"\"\n}

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

@${escapeHtml(user)} ·\n

`\n\t\t\t: \"\"\n\t\t: \"\";\n\n\treturn page(\n\t\ttitle,\n\t\t`

${escapeHtml(title)}

${who}

\n${\n\toptions.integrations.length === 0\n\t\t? `

No integrations registered.

`\n\t\t: `

${items}`\n}`,\n\t);\n}\n\nfunction loginPage(options: RouterOptions): Response {\n\tconst title = options.title ?? \"Integrations\";\n\tconst users = allowedUsers(options.auth);\n\tconst hasKey = missingEnv([\"OAUTH_STATE_ENCRYPTION_KEY\"]).length === 0;\n\treturn page(\n\t\ttitle,\n\t\t`

${escapeHtml(title)}

${\n\t\t\tusers\n\t\t\t\t? `Access is restricted to ${users.map((u) => `@${escapeHtml(u)}`).join(\", \")}.`\n\t\t\t\t: \"Open to any logged-in Val Town account.\"\n\t\t}

\n${\n\thasKey\n\t\t? \"\"\n\t\t: `

⚠️ 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\t\t401,\n\t);\n}\n\n// ---------------------------------------------------------------------------\n// Router\n// ---------------------------------------------------------------------------\n\nfunction allowedUsers(auth: RouterAuthOptions | undefined): string[] | null {\n\tif (auth === false || auth?.users == null) return null;\n\treturn Array.isArray(auth.users) ? auth.users : [auth.users];\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\tconst location = res.headers.get(\"Location\");\n\tif (!location || !ROOT_ABSOLUTE.test(location)) return res;\n\tconst rewritten = new Response(res.body, res);\n\trewritten.headers.set(\"Location\", prefix + location);\n\treturn rewritten;\n}\n\ntype GetUser = (req: Request) => Promise;\n\n/**\n * The route handler minus the OAuth wrapper, with user lookup injected —\n * exported for tests. Use createRouter, which wires the real lookup.\n */\nexport function createRouteHandler(\n\toptions: RouterOptions,\n\tgetUser: GetUser,\n): (req: Request) => Promise {\n\tconst seen = new Set();\n\tfor (const i of options.integrations) {\n\t\tvalidateSlug(i.slug);\n\t\tif (seen.has(i.slug)) {\n\t\t\tthrow new Error(`Duplicate integration slug \"${i.slug}\".`);\n\t\t}\n\t\tseen.add(i.slug);\n\t}\n\n\tconst authEnabled = options.auth !== false;\n\tconst allowlist = allowedUsers(options.auth);\n\n\treturn async (req: Request): Promise => {\n\t\tconst url = new URL(req.url);\n\n\t\tlet user: string | null = null;\n\t\tif (authEnabled) {\n\t\t\tuser = await getUser(req);\n\t\t\tif (!user) {\n\t\t\t\tif (req.method !== \"GET\") {\n\t\t\t\t\treturn new Response(null, {\n\t\t\t\t\t\tstatus: 302,\n\t\t\t\t\t\theaders: { Location: \"/\" },\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\treturn loginPage(options);\n\t\t\t}\n\t\t\tif (allowlist && !allowlist.includes(user)) {\n\t\t\t\treturn page(\n\t\t\t\t\toptions.title ?? \"Integrations\",\n\t\t\t\t\t`

403

Signed in as @${escapeHtml(user)}, but access is restricted to\n${allowlist.map((u) => `@${escapeHtml(u)}`).join(\", \")}.

\n`,\n\t\t\t\t\t403,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\n\t\tfor (const i of options.integrations) {\n\t\t\tconst prefix = `/${i.slug}`;\n\t\t\t// Canonicalize /slug → /slug/ so relative URLs resolve inside the mount.\n\t\t\tif (url.pathname === prefix) {\n\t\t\t\treturn new Response(null, {\n\t\t\t\t\tstatus: 302,\n\t\t\t\t\theaders: { Location: `${prefix}/${url.search}` },\n\t\t\t\t});\n\t\t\t}\n\t\t\tif (url.pathname.startsWith(`${prefix}/`)) {\n\t\t\t\tconst childUrl = new URL(url);\n\t\t\t\tchildUrl.pathname = url.pathname.slice(prefix.length);\n\t\t\t\tconst childReq = new Request(childUrl, {\n\t\t\t\t\tmethod: req.method,\n\t\t\t\t\theaders: req.headers,\n\t\t\t\t\t// Buffered, not streamed: Request re-wrapping needs a settled body.\n\t\t\t\t\tbody:\n\t\t\t\t\t\treq.method === \"GET\" || req.method === \"HEAD\"\n\t\t\t\t\t\t\t? undefined\n\t\t\t\t\t\t\t: await req.blob(),\n\t\t\t\t});\n\t\t\t\tconst res = await i.handler(childReq, { user, prefix });\n\t\t\t\treturn rewriteLocation(res, prefix);\n\t\t\t}\n\t\t}\n\n\t\tif (url.pathname === \"/\") {\n\t\t\treturn directoryPage(options, user, authEnabled);\n\t\t}\n\n\t\treturn page(\n\t\t\t\"Not found\",\n\t\t\t`

404

← back to the directory

`,\n\t\t\t404,\n\t\t);\n\t};\n}\n\nasync function oauthUser(req: Request): Promise {\n\tconst session = await getOAuthUserData(req);\n\treturn session?.user?.username ?? null;\n}\n\nexport function createRouter(\n\toptions: RouterOptions,\n): (req: Request) => Response | Promise {\n\tconst handler = createRouteHandler(options, oauthUser);\n\treturn options.auth === false ? handler : oauthMiddleware(handler);\n}\n",[152],"431aa351-c131-419a-8700-373a1ffbc577","mod.ts","4795d00c-7cb8-11f1-a2c1-1607ee4eb77e",72,["D",1783785117512],"export {\n\ttype CallableIntegration,\n\t// The OAuth-free router core with user lookup injected — the public test\n\t// seam for integration authors to exercise routed mode without a session.\n\tcreateRouteHandler,\n\tcreateRouter,\n\tdefineIntegration,\n\ttype Integration,\n\ttype IntegrationContext,\n\ttype IntegrationHandler,\n\ttype RouterAuthOptions,\n\ttype RouterOptions,\n} from \"./router.ts\";\n",[160],"a0943a33-567d-47bb-8723-6e5dcd5c71fd","main.ts","477921dc-7cb8-11f1-94e8-1607ee4eb77e",107,["D",1783791740998],6,"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\ttitle: \"Integrations\",\n\tauth: { users: \"nbbaier\" },\n\tintegrations: [issueTracker({}), blobAdmin({}), helloWorld()],\n});\n",[167],"7dc7ffcd-ef7c-42fc-9ed6-201654c6a901","deno.json","525df192-7c9d-11f1-a2d0-1607ee4eb77e",99,["D",1783788334915],3,"{\n\t\"compilerOptions\": {\n\t\t\"lib\": [\n\t\t\t\"dom\",\n\t\t\t\"dom.iterable\",\n\t\t\t\"dom.asynciterable\",\n\t\t\t\"deno.ns\",\n\t\t\t\"deno.unstable\"\n\t\t],\n\t\t\"noImplicitAny\": false,\n\t\t\"strict\": false,\n\t\t\"types\": [\"https://www.val.town/types/valtown.d.ts\"]\n\t},\n\t\"experimental\": {\n\t\t\"unstable-node-globals\": true,\n\t\t\"unstable-sloppy-imports\": true,\n\t\t\"unstable-temporal\": true,\n\t\t\"unstable-worker-options\": true\n\t},\n\t\"imports\": {\n\t\t\"@biomejs/biome\": \"npm:@biomejs/biome@^2.5.2\",\n\t\t\"@std/assert\": \"jsr:@std/assert@^1.0.19\"\n\t},\n\t\"lint\": {\n\t\t\"include\": [\"*.ts\", \"*.tsx\", \"example/*.ts\"],\n\t\t\"rules\": {\n\t\t\t\"exclude\": [\"no-explicit-any\", \"no-import-prefix\"]\n\t\t}\n\t},\n\t\"lock\": false,\n\t\"nodeModulesDir\": \"auto\",\n\t\"tasks\": {\n\t\t\"fmt\": \"biome check . --write\",\n\t\t\"lint\": \"deno lint\",\n\t\t\"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\t\t\"test\": \"VAL_TOWN_API_KEY=test deno test --allow-env --allow-import=esm.town,www.val.town,esm.sh,jsr.io\",\n\t\t\"check\": \"deno task fmt && deno task lint && deno task typecheck && deno task test\"\n\t}\n}\n",[176],"572f178d-7191-48b5-953e-7ac6c0917590","biome.json","52555852-7c9d-11f1-80bb-1607ee4eb77e",["D",1783715055805],"{\n\t\"$schema\": \"https://biomejs.dev/schemas/2.5.2/schema.json\",\n\t\"vcs\": {\n\t\t\"enabled\": false,\n\t\t\"clientKind\": \"git\",\n\t\t\"useIgnoreFile\": false\n\t},\n\t\"files\": {\n\t\t\"ignoreUnknown\": false\n\t},\n\t\"formatter\": {\n\t\t\"enabled\": true,\n\t\t\"indentStyle\": \"tab\"\n\t},\n\t\"linter\": {\n\t\t\"enabled\": true,\n\t\t\"rules\": {\n\t\t\t\"preset\": \"recommended\"\n\t\t}\n\t},\n\t\"javascript\": {\n\t\t\"formatter\": {\n\t\t\t\"quoteStyle\": \"double\"\n\t\t}\n\t},\n\t\"assist\": {\n\t\t\"enabled\": true,\n\t\t\"actions\": {\n\t\t\t\"source\": {\n\t\t\t\t\"organizeImports\": \"on\"\n\t\t\t}\n\t\t}\n\t}\n}\n",[184],"7de21f57-a3c4-4b97-8670-04d3f87d0fa5","README.md","de745920-7d4f-11f1-896c-1607ee4eb77e",133,["D",1783793917943],"# 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\nhere is 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: [**mounting integrations**](#mounting-integrations)\nif you want to run a router, and [**writing an integration**](#writing-an-integration)\nif you want to build one.\n\n---\n\n## Mounting integrations\n\nImport the integrations you want and hand them to `createRouter`. Its return value\nis 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 [reserved\nslugs](#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 =\n 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\n\"no router\" 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\n canonicalizes `/` → `//` so relative resolution always has a\n trailing-slash 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),\n it stacks _behind_ the router's gate when the router has one. A headless\n client that can't hold an OAuth session should target your **standalone** or\n an 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 user lookup\ninjected, so you can exercise routed mode without a real session.\n\n```ts\nimport { createRouteHandler } from \"https://esm.town/v/nbbaier/integrations/mod.ts\";\n\nconst handler = createRouteHandler(\n { integrations: [helloWorld()], auth: false },\n () => Promise.resolve(\"alice\"), // inject the \"logged-in\" user\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 user lookup (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",[190],"8193b56a-42d4-49ed-8749-149f58354be4","INTEGRATIONS.md","b16cb92a-7d51-11f1-b759-1607ee4eb77e",132,["D",1783792711200],"# 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); `ISSUE_TRACKER_API_KEY`\n 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:** [`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",[197],"0738d1b7-4e44-4db2-a469-1e3d1c1feb28","CONTEXT.md","2744ac76-7cb1-11f1-b0e8-1607ee4eb77e",134,["D",1783793918053],"# 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**:\nA self-contained web app — metadata plus a fetch handler — that operates on the\nhost val's scoped storage and is registered with a router.\n_Avoid_: plugin, addon, module, app\n\n**Callable integration**:\nWhat `defineIntegration` returns — the Integration object made directly\ncallable as an HTTP handler, so one factory return value serves standalone\nmode (`export default myFactory({...})`) and routed mode alike.\n_Avoid_: hybrid, function-object\n\n**Integration factory**:\nThe `(options) => Integration` function an integration author exports; all\nconfiguration lives in its closure, never in the Integration itself.\n_Avoid_: constructor, builder, plugin function\n\n**Router**:\nThe HTTP handler `createRouter` produces. It owns auth, serves the directory\npage, and dispatches requests to registered integrations.\n_Avoid_: meta-router, gateway, hub\n\n**Host val**:\nThe val in which a router (or a standalone integration) is mounted. Its scoped\nSQLite and blob storage are what integrations read and write.\n_Avoid_: parent val, project, consumer\n\n**Integration context**:\nThe object the router passes as a handler's second argument (`user`,\n`prefix`). Absent in standalone mode — its absence is how an integration\nknows no router is present. Surfaces as `c.env` in Hono-based integrations.\n_Avoid_: env, request context, session\n\n**Reserved slugs**:\nSlugs `createRouter` rejects because the router owns those paths: `auth`\n(std/oauth's fixed routes) and the `_`-prefixed namespace (all future\nrouter-owned surface).\n\n**Slug**:\nAn integration's short, unique, URL-safe identifier within one router; it\ndetermines where the integration is served.\n_Avoid_: id, key, name (name is the human-readable label)\n\n**Directory page**:\nThe router's page at `/`: the list of registered integrations with links and\nmissing-`requiredEnv` warnings.\n_Avoid_: dashboard (the richer, out-of-scope idea), homepage, index\n\n**Reserved paths**:\nPaths the router keeps for itself (`/` and `/auth/*`); slugs must not collide\nwith them.\n\n**Standalone mode**:\nMounting an integration's handler directly as a val's HTTP export, no router\ninvolved. Every integration must keep working this way.\n_Avoid_: legacy mode, direct mode\n\n**Routed mode**:\nMounting an integration by registering it with a router via its factory.\n_Avoid_: managed mode, hosted mode\n",[204],"a9db1ec5-6e06-4624-be74-8baaa2d47729",".vtignore","52638df0-7c9d-11f1-b73f-1607ee4eb77e",4,["D",1783715055884],".git\n.vscode\n.cursor\n.claude\n.DS_Store\nnode_modules\nvendor",[211],"667be803-e80f-480e-a009-f1ac8c9e0a34","wayfinder","15510276-7ef5-11f1-aa6c-1607ee4eb77e",139,["D",1783972651469],"directory",[218],"963ec3f1-4692-4fbf-bfed-f54fe2d276f3","example","efe83c56-7d47-11f1-9667-1607ee4eb77e",95,["D",1783788334625],[225],"a29dc277-7931-4cf4-b228-0524d69fcc23","docs","c22f6a9e-7cb3-11f1-a763-1607ee4eb77e",31,["D",1783724692393],[231],"pulls","branches","forks","envVars",{"_243":146,"_245":59},"connections",{"_243":59,"_244":59},"count","unfilledCount","emptyCount",{"_41":230,"_31":231,"_29":232,"_142":-5,"_39":40,"_38":233,"_144":121,"_36":614,"_13":59,"_33":222,"_34":-5,"_23":24,"_149":-5,"_297":615,"_26":616},{"_41":609,"_31":592,"_29":586,"_142":232,"_39":40,"_38":610,"_144":121,"_36":611,"_13":59,"_33":222,"_34":-5,"_23":24,"_149":-5,"_297":612,"_26":613},{"_41":601,"_31":602,"_29":603,"_142":586,"_39":40,"_38":604,"_144":24,"_36":605,"_13":59,"_33":20,"_34":606,"_23":24,"_149":-5,"_297":607,"_26":608},{"_41":593,"_31":594,"_29":595,"_142":586,"_39":40,"_38":596,"_144":24,"_36":597,"_13":156,"_33":20,"_34":598,"_23":24,"_149":-5,"_297":599,"_26":600},{"_41":583,"_31":584,"_29":585,"_142":586,"_39":40,"_38":587,"_144":24,"_36":588,"_13":59,"_33":20,"_34":589,"_23":24,"_149":-5,"_297":590,"_26":591},{"_41":578,"_31":577,"_29":571,"_142":232,"_39":40,"_38":579,"_144":121,"_36":580,"_13":59,"_33":222,"_34":-5,"_23":24,"_149":-5,"_297":581,"_26":582},{"_41":568,"_31":569,"_29":570,"_142":571,"_39":40,"_38":572,"_144":24,"_36":573,"_13":180,"_33":20,"_34":574,"_23":24,"_149":-5,"_297":575,"_26":576},{"_41":563,"_31":478,"_29":558,"_142":232,"_39":40,"_38":564,"_144":121,"_36":565,"_13":59,"_33":222,"_34":-5,"_23":24,"_149":-5,"_297":566,"_26":567},{"_41":557,"_31":479,"_29":471,"_142":558,"_39":40,"_38":559,"_144":121,"_36":560,"_13":59,"_33":222,"_34":-5,"_23":24,"_149":-5,"_297":561,"_26":562},{"_41":552,"_31":344,"_29":490,"_142":471,"_39":40,"_38":553,"_144":121,"_36":554,"_13":59,"_33":222,"_34":-5,"_23":24,"_149":-5,"_297":555,"_26":556},{"_41":544,"_31":545,"_29":546,"_142":490,"_39":40,"_38":547,"_144":24,"_36":548,"_13":59,"_33":20,"_34":549,"_23":24,"_149":-5,"_297":550,"_26":551},{"_41":536,"_31":537,"_29":538,"_142":490,"_39":40,"_38":539,"_144":24,"_36":540,"_13":156,"_33":20,"_34":541,"_23":24,"_149":-5,"_297":542,"_26":543},{"_41":528,"_31":529,"_29":530,"_142":490,"_39":40,"_38":531,"_144":24,"_36":532,"_13":332,"_33":20,"_34":533,"_23":24,"_149":-5,"_297":534,"_26":535},{"_41":520,"_31":521,"_29":522,"_142":490,"_39":40,"_38":523,"_144":24,"_36":524,"_13":59,"_33":20,"_34":525,"_23":24,"_149":-5,"_297":526,"_26":527},{"_41":512,"_31":513,"_29":514,"_142":490,"_39":40,"_38":515,"_144":24,"_36":516,"_13":180,"_33":20,"_34":517,"_23":24,"_149":-5,"_297":518,"_26":519},{"_41":504,"_31":505,"_29":506,"_142":490,"_39":40,"_38":507,"_144":24,"_36":508,"_13":213,"_33":20,"_34":509,"_23":24,"_149":-5,"_297":510,"_26":511},{"_41":496,"_31":497,"_29":498,"_142":490,"_39":40,"_38":499,"_144":24,"_36":500,"_13":213,"_33":20,"_34":501,"_23":24,"_149":-5,"_297":502,"_26":503},{"_41":487,"_31":488,"_29":489,"_142":490,"_39":40,"_38":491,"_144":24,"_36":492,"_13":156,"_33":20,"_34":493,"_23":24,"_149":-5,"_297":494,"_26":495},{"_41":480,"_31":190,"_29":481,"_142":471,"_39":40,"_38":482,"_144":24,"_36":483,"_13":59,"_33":20,"_34":484,"_23":24,"_149":-5,"_297":485,"_26":486},{"_41":469,"_31":328,"_29":470,"_142":471,"_39":40,"_38":472,"_144":24,"_36":473,"_13":474,"_33":20,"_34":475,"_23":24,"_149":-5,"_297":476,"_26":477},{"_41":224,"_31":225,"_29":226,"_142":-5,"_39":40,"_38":227,"_144":121,"_36":466,"_13":59,"_33":222,"_34":-5,"_23":24,"_149":-5,"_297":467,"_26":468},{"_41":459,"_31":190,"_29":460,"_142":226,"_39":40,"_38":461,"_144":121,"_36":462,"_13":146,"_33":20,"_34":463,"_23":24,"_149":-5,"_297":464,"_26":465},{"_41":451,"_31":452,"_29":453,"_142":226,"_39":40,"_38":454,"_144":24,"_36":455,"_13":146,"_33":147,"_34":456,"_23":24,"_149":-5,"_297":457,"_26":458},{"_41":443,"_31":444,"_29":445,"_142":226,"_39":40,"_38":446,"_144":24,"_36":447,"_13":59,"_33":147,"_34":448,"_23":24,"_149":-5,"_297":449,"_26":450},{"_41":217,"_31":218,"_29":219,"_142":-5,"_39":40,"_38":220,"_144":121,"_36":440,"_13":59,"_33":222,"_34":-5,"_23":24,"_149":-5,"_297":441,"_26":442},{"_41":435,"_31":419,"_29":415,"_142":219,"_39":40,"_38":436,"_144":121,"_36":437,"_13":59,"_33":222,"_34":-5,"_23":24,"_149":-5,"_297":438,"_26":439},{"_41":427,"_31":428,"_29":429,"_142":415,"_39":40,"_38":430,"_144":24,"_36":431,"_13":59,"_33":20,"_34":432,"_23":24,"_149":-5,"_297":433,"_26":434},{"_41":420,"_31":394,"_29":421,"_142":415,"_39":40,"_38":422,"_144":24,"_36":423,"_13":59,"_33":20,"_34":424,"_23":24,"_149":-5,"_297":425,"_26":426},{"_41":414,"_31":32,"_29":30,"_142":415,"_39":40,"_38":14,"_144":24,"_36":416,"_13":59,"_33":20,"_34":35,"_23":24,"_149":-5,"_297":417,"_26":418},{"_41":409,"_31":344,"_29":338,"_142":219,"_39":40,"_38":410,"_144":121,"_36":411,"_13":59,"_33":222,"_34":-5,"_23":24,"_149":-5,"_297":412,"_26":413},{"_41":401,"_31":402,"_29":403,"_142":338,"_39":40,"_38":404,"_144":24,"_36":405,"_13":146,"_33":20,"_34":406,"_23":24,"_149":-5,"_297":407,"_26":408},{"_41":393,"_31":394,"_29":395,"_142":338,"_39":40,"_38":396,"_144":24,"_36":397,"_13":156,"_33":20,"_34":398,"_23":24,"_149":-5,"_297":399,"_26":400},{"_41":385,"_31":386,"_29":387,"_142":338,"_39":40,"_38":388,"_144":24,"_36":389,"_13":146,"_33":20,"_34":390,"_23":24,"_149":-5,"_297":391,"_26":392},{"_41":377,"_31":378,"_29":379,"_142":338,"_39":40,"_38":380,"_144":24,"_36":381,"_13":146,"_33":20,"_34":382,"_23":24,"_149":-5,"_297":383,"_26":384},{"_41":369,"_31":370,"_29":371,"_142":338,"_39":40,"_38":372,"_144":24,"_36":373,"_13":156,"_33":20,"_34":374,"_23":24,"_149":-5,"_297":375,"_26":376},{"_41":361,"_31":362,"_29":363,"_142":338,"_39":40,"_38":364,"_144":24,"_36":365,"_13":146,"_33":20,"_34":366,"_23":24,"_149":-5,"_297":367,"_26":368},{"_41":353,"_31":354,"_29":355,"_142":338,"_39":40,"_38":356,"_144":24,"_36":357,"_13":146,"_33":20,"_34":358,"_23":24,"_149":-5,"_297":359,"_26":360},{"_41":345,"_31":346,"_29":347,"_142":338,"_39":40,"_38":348,"_144":24,"_36":349,"_13":59,"_33":20,"_34":350,"_23":24,"_149":-5,"_297":351,"_26":352},{"_41":336,"_31":32,"_29":337,"_142":338,"_39":40,"_38":339,"_144":24,"_36":340,"_13":59,"_33":20,"_34":341,"_23":24,"_149":-5,"_297":342,"_26":343},{"_41":327,"_31":328,"_29":329,"_142":219,"_39":40,"_38":330,"_144":24,"_36":331,"_13":332,"_33":20,"_34":333,"_23":24,"_149":-5,"_297":334,"_26":335},{"_41":210,"_31":211,"_29":212,"_142":-5,"_39":40,"_38":213,"_144":121,"_36":324,"_13":59,"_33":20,"_34":215,"_23":24,"_149":-5,"_297":325,"_26":326},{"_41":203,"_31":204,"_29":205,"_142":-5,"_39":40,"_38":206,"_144":24,"_36":321,"_13":180,"_33":20,"_34":208,"_23":24,"_149":-5,"_297":322,"_26":323},{"_41":196,"_31":197,"_29":198,"_142":-5,"_39":40,"_38":199,"_144":24,"_36":318,"_13":180,"_33":20,"_34":201,"_23":24,"_149":-5,"_297":319,"_26":320},{"_41":189,"_31":190,"_29":191,"_142":-5,"_39":40,"_38":192,"_144":24,"_36":315,"_13":156,"_33":20,"_34":194,"_23":24,"_149":-5,"_297":316,"_26":317},{"_41":183,"_31":184,"_29":185,"_142":-5,"_39":40,"_38":156,"_144":24,"_36":312,"_13":59,"_33":20,"_34":187,"_23":24,"_149":-5,"_297":313,"_26":314},{"_41":175,"_31":176,"_29":177,"_142":-5,"_39":40,"_38":178,"_144":24,"_36":309,"_13":180,"_33":20,"_34":181,"_23":24,"_149":-5,"_297":310,"_26":311},{"_41":166,"_31":167,"_29":168,"_142":-5,"_39":40,"_38":169,"_144":24,"_36":306,"_13":171,"_33":172,"_34":173,"_23":24,"_149":-5,"_297":307,"_26":308},{"_41":159,"_31":160,"_29":161,"_142":-5,"_39":40,"_38":162,"_144":24,"_36":303,"_13":156,"_33":147,"_34":164,"_23":24,"_149":-5,"_297":304,"_26":305},{"_41":151,"_31":152,"_29":153,"_142":-5,"_39":40,"_38":154,"_144":24,"_36":300,"_13":156,"_33":147,"_34":157,"_23":24,"_149":-5,"_297":301,"_26":302},{"_41":139,"_31":140,"_29":141,"_142":-5,"_39":40,"_38":143,"_144":24,"_36":296,"_13":146,"_33":147,"_34":148,"_23":24,"_149":-5,"_297":298,"_26":299},["D",1783785020744],"children",[],[140],["D",1783785020715],[],[152],["D",1783785117512],[],[160],["D",1783791740998],[],[167],["D",1783788334915],[],[176],["D",1783715055805],[],[184],["D",1783793917943],[],[190],["D",1783792711200],[],[197],["D",1783793918053],[],[204],["D",1783715055884],[],[211],"9fbab088-c6ce-45a8-a75e-cbb592cf15bd","map.md","15b0f316-7ef5-11f1-bccf-1607ee4eb77e",167,["D",1783982882268],5,"---\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\nby which 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\ncontract API 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\n and investigations; the only artifacts are research summaries, a throwaway\n spike, 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 —\n any load-bearing runtime unknown (std/oauth middleware behavior,\n bearer-token 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\n be 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\n viewer would otherwise hand anonymous full admin); the tracker's bearer\n key is router-opaque, so machine credentials must reach the integration\n unvalidated; and the ctx must distinguish anonymous-on-gated-router from\n ungated-router (`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\n coarse opt-in flag (\"safe for session-less traffic, period\"); the router\n enforces at dispatch, passes `Authorization` through untouched (no\n router-minted scheme), and the ctx gains a login-location signal so\n anonymous-on-gated ≠ ungated. `auth: false` + an unflagged integration\n throws at `createRouter`. Includes the flag × type × router-auth\n composition table and the five spike assumptions 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\n Town runtime. Anonymous reaches flagged surfaces while unflagged ones 401;\n a bearer non-GET write completes with header+body echoed byte-identical and\n no redirect (router never touches `Authorization`); the tracker-analog's\n interleaved public/gated routes behave as standalone (`GET /new` still 403s);\n the login signal renders on anonymous-but-allowed pages and login returns a\n session; and origin-bound sessions **don't** bite — routed mode is a single\n origin, so a session covers every slug. Spike val `nbbaier/wayfinder-auth-spike`\n linked on 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\n to see more\" (no count); hitting a private integration's URL directly →\n the single router-owned **login page (401)**, matching standalone, not a\n 404; 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 ticket-2\n need) and **widen** only loudly, via a per-integration, explicitly-named,\n host-side **escape hatch** to force-mount an unflagged integration on an\n `auth: false` router (option shape + any warning log → 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 `getOAuthUserData(req)?.user.username\n === parseVal().username`. This unblocks ticket 7's implicit-owner allowlist\n semantics. Use the direct comparison, not the session's `isOrgMember`\n (frozen at login, optional, too broad). One cheap spike confirmation\n (`VALTOWN_ENTRYPOINT` populated in the routed isolate) folds into the ADR\n 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\n and prescribes nothing new. The flag is inert standalone (no router to enforce\n it — an unflagged integration was already public standalone). Sessions never\n flow through `ctx`: an integration wanting login wires its own std/oauth and\n reads `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## 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.)\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",[],[218,328],"8d02cb36-68d4-4ac4-9999-9f561987b6c1","e744067c-7f0c-11f1-a751-1607ee4eb77e","1578b62c-7ef5-11f1-9836-1607ee4eb77e",164,["D",1783982882103],"---\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\"]`\n= owner + user1). That rule needs the router to answer \"is this logged-in user\nthe owner?\" at runtime — and today it has no owner handle; `getOAuthUserData`\nonly reports who logged in. Per the map's lock bar, this runtime unknown must\nbe pinned 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\n and false/meaningless for personal vals?\n- If neither yields a reliable owner identity from primary sources alone, say\n so — that downgrades implicit-owner to needing a **HITL login probe** (fold\n into 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: [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 `Deno.env.get(\"VALTOWN_ENTRYPOINT\")`)\n returns the owner's handle from `Deno.env` alone. Caveat: `VALTOWN_ENTRYPOINT`\n is undocumented publicly — but std/utils and std/oauth both rely on it in\n 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\n comparison 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",[],[218,344,32],"tickets","34b76a7d-d970-4cfa-afcb-0b4891f9d686","008-flag-standalone-interaction.md","e732694e-7f0c-11f1-98dd-1607ee4eb77e",162,["D",1783982882025],"---\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\ndirectly as a val's HTTP export, no router present (`CONTEXT.md`: standalone\nmode; ctx absent). What does the flag, and the whole session-less auth model,\nmean when there 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`,\nand the login-location signal — is a channel between a router and an\nintegration. Standalone has no router, so none of it applies, and its absence\nis the signal an integration already keys off (`ctx`-absence = \"no router\npresent,\" per CONTEXT.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\n own std/oauth and reads the session directly via `getOAuthUserData(req)` —\n the 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\n standalone — `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",[],[218,344,346],"77232188-a1cb-4912-a2d1-a926c23ab2ee","007-allowlist-composition-host-overrides.md","c5c495d0-7efc-11f1-9d03-1607ee4eb77e",166,["D",1783982882108],"---\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\n router with a `users` allowlist — i.e. does the allowlist restrict *who\n may log in* or *who may enter at all*?\n- Host-side narrowing: can a host make a flagged integration more private\n than it declares (mount the tracker but suppress its public surface)?\n Ruled adjacent in ticket 3's Q1; decide whether it's in this ADR or\n explicitly 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\nhost narrows 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\nhost on a locked-down (owner-only) router still exposes its flagged\nintegrations' public surface to anonymous; that is what the flag means. The two\nconcerns don't compose because they answer different questions (\"who is\ntrusted\" vs \"is this surface public\").\n\n**2. Allowlist semantics — the host val owner is always implicitly\nallowlisted** (realizable at runtime per [ticket 9](009-identify-val-owner-at-runtime.md)\nvia `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,\n so 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",[],[218,344,354],"3ef7245e-2191-41cb-a4f1-d7fbe9b671e4","006-router-surface-partial-gating.md","c5ba0980-7efc-11f1-b774-1607ee4eb77e",163,["D",1783982882033],"---\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,\nrouter enforces at dispatch), what does the router's *own* surface show an\nanonymous visitor when some integrations are flagged public and others gated?\n\n- The directory page at `/`: does an anonymous visitor see it at all? Only\n the flagged integrations? Everything, with gated ones marked? Today\n anonymous GETs get the login page unconditionally.\n- The login wall: where does it live once `/` may be public — per-gated-slug,\n or a dedicated page?\n- Unflagged prefixes for anonymous visitors: login wall (current behavior)\n vs 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\nwe don't contort the surface to hide that a private integration exists; we\noptimize for least-surprise and for matching standalone behavior. This\ndecides every sub-question below.\n\n**1. Directory page `/` — conditional visibility.** `/` is reachable\nsession-less **iff at least one integration is flagged public**. A router\nwith nothing flagged is fully private and keeps today's behavior exactly:\nanonymous GET `/` → login wall. The new anonymous-`/` surface only switches\non once the operator has opted something into public. (Dovetails with ticket\n3's invariant: a router with no public surface behaves as it does today.)\n\n**2. Directory listing for anonymous — flagged only, plus a generic teaser.**\nA logged-out visitor sees only the flagged (public) integrations. Private\nones are not listed. When hidden integrations exist, the page shows a generic\n**\"log in to see more\"** affordance — **no count** (the count is marginal for\nsomeone about to log in, and \"there are exactly N private tools\" is the one\nstructural fact worth not printing). Logged-in users see the full list. Shown\nonly when something is actually hidden.\n\n**3. Anonymous hits a private (unflagged) integration's URL directly →\nlogin page (401).** Not a 404. Enumeration isn't a threat we're defending\nagainst, and a login page is exactly what the same integration shows in\n**standalone** mode when hit logged-out — matching it is least-surprise. This\nalso fixes the login-wall location: it's the **single router-owned login\npage**, served with 401 at whatever gated URL you hit — not per-integration,\nnot a separate dedicated route. The directory's \"log in to see more\" link\npoints at the same page. Net stance: we don't *advertise* private\nintegrations (sub-question 2), but we don't *conceal their existence* from\nsomeone who hits the URL either. Coherent, given hiding-existence isn't a goal.\n\n**4. Anonymous non-GET (stale-tab form POST) to a private integration →\nkeep today's 302 redirect to `/`.** The realistic trigger is session expiry\nin a left-open tab: a POST arrives with no valid session. A login page can't\nsensibly be *rendered* as the response to a form submit, so the visitor is\nbounced to `/`, where the log-in link lives. A bare 401 (cleaner for machine\nclients) was rejected as less browser-friendly; a machine POSTing to a\n*private* integration is a misconfiguration — the integration it wants should\nbe flagged, in which case the POST flows straight to the handler.\n\n**Surfaced, placed elsewhere (not part of this ADR):**\n- **Directory-page customization** (ship a default UI vs. bring-your-own) —\n a 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\n to its own ticket on this map (created alongside this resolution).\n",[],[218,344,362],"f895c483-d0a0-4f4b-8e08-f398a8362416","005-lock-the-adr.md","15a23088-7ef5-11f1-a818-1607ee4eb77e",165,["D",1783982882184],"---\nid: 5\ntitle: Write and lock the ADR\nlabels: [wayfinder:grilling]\nstatus: open\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\nrouter, and the authority split between integration and router/host. Cover\nboth problem halves, the rejected alternatives with reasons, and the spike\nevidence for each load-bearing assumption. Grill the draft with the human\nuntil it locks; update `CONTEXT.md` language if the decision minted new terms.\n\nLocking this ADR is the map's destination. HITL.\n",[],[218,344,370],"0dc69f4a-994a-4750-9d7f-a7ebce0c358e","004-spike-leading-mechanism.md","159e4d7e-7ef5-11f1-bf46-1607ee4eb77e",161,["D",1783976749965],"---\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)\nsurvive contact with the runtime? Build a throwaway spike — a scratch val or\nlocal harness, 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\n credential 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\ncandidate. If it kills it, ticket 3 reopens with the new facts. HITL — built\nvia /prototype, reviewed with the human.\n\n## Resolution\n\n**The candidate locks. All five of ticket 3's load-bearing assumptions\nsurvived contact 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",[],[218,344,378],"4c1b8723-774f-4f77-9f26-ef000f850f5e","003-candidate-mechanisms-authority-split.md","15a64542-7ef5-11f1-9fa9-1607ee4eb77e",158,["D",1783975953991],"---\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,\nand where does authority live — what does an integration declare vs what does\nthe router/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\nbearer-token machines — and name the leading candidate plus the load-bearing\nassumptions the spike (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\neven when public and gated routes interleave, as the tracker's do).\n\nThe decisions:\n\n1. **Authority split** — the integration declares session-less reachability;\n the router enforces at dispatch. Host-side *narrowing* overrides deferred\n to 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,\n and 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\n \"router has no login\" with \"visitor hasn't logged in\": conceptually the\n router tells the integration where login lives, or that it doesn't exist.\n Exact field 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\n hatch, 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\nchecking the integration does itself (A: flag, no checks; B: flag, checks;\nC: 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\n page while an unflagged one on the same router still shows the login\n wall — and login works alongside.\n2. A bearer-token non-GET API write completes through the gated router,\n headers 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,\n and logging in through it returns with a session.\n5. std/oauth's origin-bound sessions (ticket 1 caveat) — check whether they\n bite in practice.\n\n(Decision 5 needs no spike — startup validation, no runtime unknown.)\n",[],[218,344,386],"7a7d50d3-99d4-4c17-8cf0-c87c86adfa50","002-requirements-inventory.md","15c020b6-7ef5-11f1-a76a-1607ee4eb77e",152,["D",1783974383599],"---\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\nthe authority-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\ntickets) and 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\n the 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: [Real-integration auth requirements\ninventory](../assets/002-requirements-inventory.md). Answers to the\nquestion's four bullets:\n\n- **Tracker:** anonymous standalone surface = all GET HTML pages plus the\n entire GET `/api/*` (API reads bypass auth unconditionally) — but *not*\n all GETs (`GET /new` is contributor-gated), so only the integration can\n draw the public line. Writes are per-route gates\n (contributor/manager/maintainer). `/api` non-GET requires a **static\n shared bearer key** (`options.apiKey ?? ISSUE_TRACKER_API_KEY`), plain\n string equality, no scopes — maintainer-equivalent power, and\n **router-opaque** (the router cannot validate it). Behind a gated router\n today, all of that is flattened: anonymous HTML reads, anonymous API\n reads, and the whole bearer write path die at the 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\n stay expressible at zero declaration cost. Hazard found: with `owner`\n omitted, its routed branch **skips the allowlist check entirely**, so any\n mechanism that passes session-less requests through without integration\n opt-in would hand anonymous visitors full blob admin. Strong evidence\n that session-less reachability must be integration-declared, default\n 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\n can't validate the credential; a router-minted scheme would force two\n secrets per client (cost for ticket 003 to weigh).\n- **Requirements:** 12 scenario rows (R1–R12) plus six derived\n requirements in the asset. Headlines: per-route granularity (not\n per-integration, not \"all GETs\"); opt-in with gated default; machine\n credentials delivered to declared surfaces without OAuth; **anonymous ≠\n ungated** — the tracker's `authUi` needs the ctx to distinguish\n \"session-less on a gated router\" from \"router has no auth\", which plain\n `ctx.user: null` conflates today; fully-gated default stays cheap;\n session-user behavior untouched.\n",[],[218,344,394],"ed51e34e-a865-4c99-a9bb-6d8e09d3667b","001-research-std-oauth-constraints.md","15db6c2c-7ef5-11f1-b292-1607ee4eb77e",150,["D",1783974211392],"---\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\ndoes it 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\n runs — every request, only `/auth/*`, something else? Can the wrapped\n handler see a 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)\n and 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: [std/oauth constraints on selective\ngating](../assets/001-std-oauth-constraints.md). Answers to the question's\nfour bullets:\n\n- **What the middleware intercepts:** exactly six root-level paths by exact\n pathname match (`/auth/login`, `/auth/callback`, `/auth/logout`,\n `/auth/logo`, three static `/auth/client/*` files). Every other request —\n session or not — passes to the wrapped handler unmodified, with no 401,\n redirect, or session check anywhere on that path. The wrapped handler can\n freely serve session-less requests; v1's blanket 401 is router code, not a\n std/oauth constraint.\n- **`getOAuthUserData` outside the middleware:** fully independent and\n side-effect-free. Missing cookie, decrypt failure, or expiry all return\n `null` — no redirect/401. A router can call it unwrapped and treat `null`\n as 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`\n (Path=/, HttpOnly, Secure, SameSite=None, 30d). Exact-match routing means a\n prefix-mounted integration can never expose its own auth routes — OAuth\n must be mounted once, at the router root. An unwrapped router loses login\n entirely 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\n hypothesis is unopposed at this layer.\n",[],[218,344,402],"02bfc32c-ad0e-4e0f-a307-a1f723ccc45b",140,["D",1783972651716],[276,277,278,279,280,281,282,283,284],[218,344],"6ffc6f20-1e01-451e-8647-d58bd571643b","b6fe4ec8-7ef8-11f1-b47f-1607ee4eb77e",["D",1783982882094],[],[218,419,32],"assets","5f547a75-6c5b-4354-9b04-377d16ef9acf","1ddd8c44-7ef9-11f1-a862-1607ee4eb77e",153,["D",1783974383631],"# Real-integration auth requirements inventory\n\nResearch asset for [ticket 002](../tickets/002-requirements-inventory.md).\nFacts gathered 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\nof writing (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).\nSo the public surface is *not* \"all GETs\" — the tracker's own role model\ndraws the line, 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)\n(`app.tsx:161-195`). All authorization lives in `app.tsx`; the store does\nnone. In routed mode a rejected viewer gets **403, never a redirect to\n`/auth/login`** (ADR 0002 Location-rewriting makes that a 404 under a\nprefix; 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\ngrants **all** write operations (maintainer-equivalent). The `actor` field in\nrequest bodies is free-text provenance, not authorization (`api.ts:115`).\nCrucially: **the credential is integration-local — the router has no way to\nvalidate it.**\n\n**What a gated router flattens today.** The v1 router 401s (GET → login\npage) or 302s (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\n session 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\n sees the `Authorization` header. v1 ticket 004 accepted this as \"stacked\n gates: headless agents target a standalone or ungated mount.\"\n\n**A ctx nuance the mechanism must preserve or improve.** The tracker's\n`authUi` flag (`app.tsx:124`) shows login/logout UI only where a working\nlogin flow exists. Today `ctx.user: null` means \"ungated router — no login\nflow, hide the UI, everyone is viewer.\" Under fine-grained auth a *gated*\nrouter would also deliver session-less requests (to public routes) — and\nthere a login flow **does** exist and the UI should show \"Log in.\" So the\ncontext must let an integration distinguish **\"anonymous, but login is\navailable\"** from **\"no auth at all\"** — plain `ctx.user: null` currently\nconflates 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\ngate in one `app.use(\"*\")` middleware (`app.tsx:349-380`); no roles, no\nread-only tier, no anonymous surface, no machine/API credential of any kind.\nEvery route — including `/raw` byte serving — sits behind the session gate.\nAn admin panel over the host val's blob storage has no meaningful\npublic-read subset. **This is the \"fully gated integration\" case: the model\nmust express it cleanly, ideally as 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\nsatisfy a non-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** —\n\"any logged-in user\" semantics are implemented as *no check*\n(`app.tsx:361`: `if (owners && ...)`). Today the gated router guarantees\n`ctx.user` is a real session user, so that's safe. If a v2 router started\npassing session-less requests through with a null-ish user and no opt-in\nfrom the integration, an owner-less blob viewer would grant **anonymous\nvisitors full admin** (read/write/delete blobs). Existing integrations were\nwritten assuming the router's wall; any mechanism that lowers it must be\n**opt-in per integration** (evidence for the null hypothesis's\nintegration-declares side, against pure router-side or pass-through-by-\ndefault shapes).\n\n## 3. Plausible headless-client cases\n\nWho actually calls the tracker's `/api` behind a router, with what\ncredential:\n\n- **Coding-agent sessions** (the dominant real case — e.g. wayfinder/\n blueprint-style workflows driving an issue tracker): create/close/comment\n on issues via `ISSUE_TRACKER_API_KEY` as a bearer token. No browser, no\n OAuth session, key supplied via env.\n- **CI/scripts**: a repo's automation filing or closing issues on merge —\n same static bearer key.\n- **Sibling vals / crons on the same account**: a scheduled val posting\n status 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\nand no cookie jar** — a 302-to-login response is indistinguishable from\nfailure. The router cannot validate this credential (it's the integration's\nsecret), which constrains the machine-credential design: either the router\npasses unrecognized `Authorization` headers through to a surface the\nintegration declared machine-reachable, or the router mints its own\ncredential and headless clients must hold **two** secrets (router's + the\ntracker's key) — a real cost to weigh in ticket 003.\n\n## 4. Requirements the mechanism must satisfy\n\nScenario rows. Setup: v1-style router, **auth on** (default gate: any\nlogged-in Val Town user), tracker mounted at `/issues`, blob viewer at\n`/blobs`. \"Today\" = v1 behavior; \"Required\" = what fine-grained auth must\nproduce.\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\n is the only party that knows its public surface.\n2. **Opt-in, default gated.** Integrations written under v1 assume the\n router's wall (blob viewer's owner-less mode would be anonymous-admin\n otherwise). Session-less reachability must be something an integration\n declares, never something the router grants unilaterally (R9, §2).\n3. **Machine credentials reach the integration unauthenticated by the\n router.** The tracker's bearer key is integration-local and\n router-opaque; the mechanism must deliver the `Authorization` header to a\n declared surface without demanding an OAuth session (R5–R6), and\n machine responses must stay JSON (no login-HTML or redirect responses to\n bearer clients).\n4. **Anonymous ≠ ungated.** The context must distinguish \"session-less\n request admitted to a public surface of a gated router\" from \"router has\n no auth at 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,\n and the std/oauth flow work exactly as in v1.\n",[],[218,419,394],"bad385a5-1269-4b40-a6e1-bb1d4b15288e","001-std-oauth-constraints.md","b70fa7cc-7ef8-11f1-b47f-1607ee4eb77e",148,["D",1783974211337],"# std/oauth constraints on selective gating\n\nResearch summary for ticket [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` — https://www.val.town/x/std/oauth/code/middleware/index.ts\n (the public `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\nspecial-cases exactly six paths by **exact pathname match** and hands\neverything else to the wrapped 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\nrequests is 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\nlogin' helper\").\n\n## F2. `getOAuthUserData` is side-effect-free and works unwrapped\n\n`getOAuthUserData(req)` (middleware/index.ts) reads the `vt_session` cookie;\nif absent it returns `null` immediately. On decrypt failure it logs and\nreturns `null`. `decryptSession` (session.ts) additionally returns `null` on\nexpiry and catches all parse/decrypt errors. No redirect, no 401, no response\nmutation, no dependence on running inside `oauthMiddleware`. A router can\ncall it on any request — wrapped or not — and treat `null` as \"anonymous\"\nwith zero side effects. This directly supports passing `ctx.user: null`\nthrough to integrations.\n\n## F3. Sessions are origin-bound via the encryption-key lookup\n\n`getOAuthUserData` derives `redirectUri = new URL(req.url).origin +\n\"/auth/callback\"` from the **incoming request** and passes it to\n`decryptSession`. The AES-GCM key (crypto.ts, `getOrCreateEncryptionKeyMaterial`)\ncomes 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\n integration code inside its own val, everything shares the router's origin\n and blob storage — any code in the process can decrypt the session.\n- **Cross-val session sharing does not work by default**: a separately\n deployed integration val has a different origin (browser won't send the\n cookie) and different key material. Sharing would require same origin plus\n a shared `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\n don't 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\n`redirectUri` via 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,\nat the router level, at the root — integrations behind the router cannot run\ntheir own `oauthMiddleware` meaningfully. Conversely, a router running\n*unwrapped* loses login entirely on that origin (no `/auth/*` routes exist),\nthough `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\n401 a machine client sees today is router code. The middleware imposes no\nconstraint on the machine-credential design — router-defined scheme vs.\npass-through is a free 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\n as the user), optional `refreshToken`/`idToken`, `expiresAt`, and\n `isOrgMember` (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,\ncall `getOAuthUserData` per request, dispatch anonymous requests\n(`ctx.user: null`) to declared-public surfaces, and pass `Authorization`\nheaders through untouched. The load-bearing runtime unknowns left for the\nspike are the origin/key-caching nuance (F3) and end-to-end login coexisting\nwith anonymous + bearer traffic on one router.\n",[],[218,419,428],"499e72d9-c820-45ab-bd89-a13ddef3c6fc",147,["D",1783974211223],[272,273,274],[218,419],["D",1783972651469],[271,275,285],[218],"a9cb612e-1a70-4e8f-a7c6-6ba803292c96","hello_test.ts","f0100e98-7d47-11f1-af4f-1607ee4eb77e",98,["D",1783788334758],"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\tconst handler = createRouteHandler(\n\t\t{ integrations: [helloWorld()], auth: false },\n\t\t() => Promise.resolve(\"nbbaier\"),\n\t);\n\t// auth: false leaves ctx.user null, so inject the user via the test seam's\n\t// dispatch instead: call the integration the way the router does.\n\tconst res = await helloWorld().handler(new Request(\"https://example.com/\"), {\n\t\tuser: \"nbbaier\",\n\t\tprefix: \"/hello\",\n\t});\n\tconst body = await res.text();\n\tassert(body.includes(\"@nbbaier\"));\n\tassert(body.includes(`href=\"about\"`));\n\tassert(\n\t\t!body.includes(`href=\"/`),\n\t\t\"links must be relative, not root-absolute\",\n\t);\n\n\tconst routed = await handler(new Request(\"https://example.com/hello/about\"));\n\tassertEquals(routed.status, 200);\n\tassert((await routed.text()).includes(`href=\"./\"`));\n});\n\nDeno.test(\"hello-world works standalone with the subject fallback\", async () => {\n\tconst res = await helloStandalone(new Request(\"https://example.com/\"));\n\tassertEquals(res.status, 200);\n\tassert((await res.text()).includes(\"world\"));\n\n\tconst custom = await helloWorld({ subject: \"Val Town\" }).handler(\n\t\tnew Request(\"https://example.com/\"),\n\t);\n\tassert((await custom.text()).includes(\"Val Town\"));\n});\n",[],[225,444],"e8ff1c5e-61fc-459e-9069-7093f357ede7","hello.ts","f004bfac-7d47-11f1-9667-1607ee4eb77e",108,["D",1783791741170],"// 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\tsubject?: string;\n}\n\nexport function helloWorld(options: HelloWorldOptions = {}) {\n\tconst subject = options.subject ?? \"world\";\n\treturn defineIntegration({\n\t\tname: \"Hello World\",\n\t\tslug: \"hello\",\n\t\tdescription: \"The smallest possible integration — the worked example.\",\n\t\trequiredEnv: [\"HELLO_GREETING\"],\n\t\thandler: (req, ctx) => {\n\t\t\tconst greeting = Deno.env.get(\"HELLO_GREETING\") ?? \"Hello\";\n\t\t\tconst who = ctx?.user ? `@${ctx.user}` : subject;\n\t\t\tconst body =\n\t\t\t\tnew URL(req.url).pathname === \"/about\"\n\t\t\t\t\t? `

A toy integration.

back

`\n\t\t\t\t\t: `

${greeting}, ${who}!

about

`;\n\t\t\treturn new Response(`${body}`, {\n\t\t\t\theaders: { \"Content-Type\": \"text/html; charset=utf-8\" },\n\t\t\t});\n\t\t},\n\t});\n}\n\nexport default helloWorld();\n",[],[225,452],"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",[],[225,190],["D",1783788334625],[267,268,269],[225],"56cb78b9-88f5-4502-b5de-273be423cf19","273b54e6-7cb1-11f1-9d45-1607ee4eb77e","b0f10802-7d51-11f1-bd58-1607ee4eb77e",114,["D",1783792524257],10,"---\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 `createRouter({ integrations: [issueTracker({...})] })`.\n Options live in 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 ([ADR 0001](../../adr/0001-dispatch-architecture.md)):\n one origin, 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) — `handler(req, ctx)`\n with ctx-as-Hono-env alignment; router rewrites root-absolute `Location`\n headers ([ADR 0002](../../adr/0002-location-header-rewriting.md)); slugs\n `^[a-z0-9-]+$` with `[\"auth\", /^_/]` reserved, throw at construction; auth\n is 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\n 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\n the tracker's role model (null → read-only viewer, no login redirects in\n routed mode); bearer-token API gates stack behind a gated router; contract\n additions: `CallableIntegration` type, `createRouteHandler` made public as\n the test seam. Live at the integrations val's `/issues/`; answered the\n 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` factory\n demonstrating the full contract (dual-mode `ctx?.user`, a genuinely-read\n `requiredEnv`, relative-only links), registered live in `main.ts`, tested\n both modes; kept out of `mod.ts` — it's the copyable worked example for\n 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\n two real migrations.\n- **Full dashboard** at `/` (health checks, status, per-integration state) —\n v1 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\n a gated router without an OAuth session (surfaced by the val-issue-tracker\n migration). v1 accepts stacked gates: headless agents target a standalone\n or ungated mount. Revisit only if a real integration can't live with that.\n- **Fine-grained auth for routed integrations** _(leading candidate for the\n next effort)_ — a gated router applies one all-or-nothing login wall at the\n front door, so an integration's own finer auth model is flattened when\n routed. Example: the issue tracker standalone allows anonymous public reads\n (the `viewer` role), but behind a gated router the login wall blocks\n anonymous visitors entirely, so that public-read capability is lost. v1's\n permission model is deliberately all-or-nothing (router authenticates,\n integration authorizes from `ctx.user`); expressing per-integration or\n per-route visibility — a public-read integration, or public-read + gated-write\n routes, on an otherwise-gated router — is a richer model beyond the v1\n destination. Surfaced while writing the ticket-7 docs; revisit as a fresh\n map, not a resumption of this one.\n",[],[231,478,479,328],"wayfinder-archive","integrations-v1","6d194520-4783-4ae0-9616-d39561e89377","b17b36ee-7d51-11f1-bf82-1607ee4eb77e",122,["D",1783792524832],"# 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 walked),\n and out-of-scope notes.\n- [`tickets/`](tickets/) — the eight resolved tickets, each with its `## 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",[],[231,478,479,190],"d3620b53-63dc-46d0-9e4c-4209a06affb3","008-publishing-and-versioning.md","7454ac76-7cb8-11f1-9441-1607ee4eb77e","b1080eee-7d51-11f1-b73f-1607ee4eb77e",118,["D",1783792524500],"---\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\nwas built. 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\n (esm.town `?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\n slugs, trailing-slash canonicalization) are the public API. What's the\n compatibility promise, and where is it stated? (The `/^_/` reservation\n already encodes one 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\n (ctx shape / `c.env` alignment, Location rewriting, trailing-slash\n canonicalization, reserved slugs incl. the forever-`/^_/` namespace).\n Additive changes land on `mod.ts` anytime; **breaking changes never land on\n `mod.ts`** — they ship as a new entrypoint (e.g. `v2/mod.ts`) with old\n semantics preserved.\n- **Branch discipline, post-v1**: unpinned imports track the val's main tip,\n so **main is the release channel and merge = release**. Contract-touching\n work happens on a branch (`vt checkout -b`); merge only with\n `deno task check` green; don't leave `vt watch` running against main while\n editing `router.ts`/`mod.ts`. Non-code files (`wayfinder/`, `docs/`,\n `CONTEXT.md`) are exempt. Layering: `?v=` protects downstream from\n deliberate change, branch discipline from accidental breakage — unpinned-by-\n default is only honest with both.\n- **Privacy**: the val is public (verified via API) and must stay\n public/unlisted for esm.town imports to resolve.\n",[],[231,478,479,344,488],"6a448add-bc45-4bb7-8977-a2e51168f65b","007-third-party-author-docs.md","272f2194-7cb1-11f1-81a5-1607ee4eb77e",117,["D",1783792524262],"---\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\nof a contract that survived two real apps. If a rule needs a wall of caveats\nto document, that's feedback for the contract, not prose to polish — surface\nit rather 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\n is both an `Integration` and a standalone HTTP handler — the dual-mode\n story for 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\n authorizes from `ctx.user`; `ctx.user: null` means an ungated router (no\n login exists); integration-level token APIs sit behind the router's gate\n 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, val-issue-tracker\n23, scoped-blob-viewer 5. The two migrated vals were republished so the\nintegrations val's remote imports resolve against the new names.\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",[],[231,478,479,344,497],"1690e329-2e8e-4562-a408-fd923f6021c2","006-hello-world-example-integration.md","27198942-7cb1-11f1-bf6f-1607ee4eb77e",116,["D",1783792524281],"---\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\nsurface honestly: `defineIntegration`, an `(options) => Integration` factory,\nreading the router-provided user, one `requiredEnv` declaration, and\nprefix-correct links 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, deployed 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\n (falls back to \"Hello\"; unset = the directory's ⚠️ badge, deliberately\n demonstrating the feature), and relative-only links (`about`, `./`) per the\n ticket-2 prefix rules. `export default helloWorld()` at the bottom shows\n standalone mode on 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`\n and verified live (401 login gate serving correctly; directory is\n owner-gated by design).\n- Tests: [`hello_test.ts`](../../../../example/hello_test.ts) — routed greeting + relative\n links, standalone fallback, both modes through the real dispatch. 17/17\n 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",[],[231,478,479,344,505],"45fbb922-76e0-45ca-8495-322306c43e62","005-migrate-scoped-blob-viewer.md","2721832c-7cb1-11f1-adf5-1607ee4eb77e",115,["D",1783792524281],"---\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 (`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\nredirect targets (`c.redirect(\"/?ok=...\")`) all break under a mount prefix\nunless the ticket-2 rules handle them. If the migration fights the contract,\nthat's signal, not 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`). `export default\n createBlobAdmin({ owner: \"nbbaier\" })` stays a valid standalone HTTP export,\n and the same value registers with `createRouter`. Standalone wraps this val's\n 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. `OAUTH_STATE_ENCRYPTION_KEY`\n is declared as `requiredEnv` so a router's directory badges it when unset.\n- **File layout — reusable lesson for the docs ticket (7):** JSX in a `.ts`\n file 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\n `.../scoped-blob-viewer/mod.ts` import path AND making the module locally\n checkable. Authors shipping JSX 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 `deno cache\n --reload=https://esm.town/v/nbbaier/scoped-blob-viewer/mod.ts` in the\n integrations val before its `deno task check`.\n",[],[231,478,479,344,513],"fd8d4653-aa84-4bf2-bb70-0e0a9c128b47","004-migrate-val-issue-tracker.md","04d622d6-7d52-11f1-8ed3-1607ee4eb77e",128,["D",1783792664697],"---\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\n or 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\n the `/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`): `export default\n createIssueTracker({})` stays a valid standalone HTTP export, and the same\n value registers with `createRouter`. Standalone wraps the tracker's own\n `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\n a 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\n it 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:**\n (1) `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\n seam — the tracker's routed tests mount under the real router with an\n 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` in both repos. Live: tracker mounted at the integrations val\n (`/issues/`, 401-gated as configured); the standalone tracker val serves\n its existing data unchanged.\n- Gotcha for later tickets: the tracker imports the contract unpinned, and\n Deno caches remote modules — after pushing integrations, run `deno cache\n --reload=https://esm.town/v/nbbaier/integrations/mod.ts` in dependents\n before `deno task check`.\n",[],[231,478,479,344,521],"ca063689-322a-4702-8446-8daf48aae580","003-build-integrations-v1.md","27129ee8-7cb1-11f1-9ee9-1607ee4eb77e",121,["D",1783792524489],"---\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\n integration; ⚠️ badge when a `requiredEnv` var is unset\n (`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:\n biome fmt, lint, typecheck, test).\n\nAFK: buildable solo once the contract is pinned; resolution records what\nshipped and any contract deviations discovered while building (feed those back\ninto the map).\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: `createRouter({ title:\n \"Integrations\", auth: { users: \"nbbaier\" }, integrations: [] })`. Live at\n https://nbbaier--477921dc7cb811f194e81607ee4eb77e.web.val.run — verified\n 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\nnon-GET requests bounce 302 home rather than rendering the login page\n(precedent from scoped-blob-viewer; a stale form POST shouldn't render HTML\ninto a POST response).\n",[],[231,478,479,344,529],"5eb8c63d-bcdd-417a-890e-bdc9e5c5b828","002-pin-the-v1-contract.md","274f5dce-7cb1-11f1-ab0f-1607ee4eb77e",119,["D",1783792524595],"---\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\nthe shape; 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\n it in ctx?) and what authors must do. If this takes three paragraphs of\n caveats, 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\n 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\tuser: string | null; // Val Town username via router-owned OAuth\n\tprefix: string; // mount prefix, e.g. \"/issues\"\n}\n\ninterface Integration {\n\tname: string;\n\tslug: string;\n\tdescription?: string;\n\trequiredEnv?: string[];\n\thandler: (req: Request, ctx?: IntegrationContext) => Response | Promise;\n}\n\ninterface RouterOptions {\n\tintegrations: Integration[]; // order = directory order\n\tauth?: { users?: string | string[] } | false; // default ON, any logged-in user\n\ttitle?: 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\n typing) — same object reference, no adapter. Standalone mode passes no ctx,\n so `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 ([ADR 0002](../../../adr/0002-location-header-rewriting.md)).\n HTML is never 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\n may enter; what they may DO stays integration-domain logic fed by\n `ctx.user` (issue tracker keeps maintainer/contributor — that seam belongs\n to its migration ticket). `auth: false` opts out; `ctx.user` is then null.\n- **Nothing else in v1**: no per-integration auth overrides, no hooks, no\n custom directory renderer — v2-shaped until a migration proves a need.\n",[],[231,478,479,344,537],"4a4e470c-45b1-4258-972d-511378f28d4e","001-prototype-dispatch-architecture.md","04f1644c-7d52-11f1-acde-1607ee4eb77e",130,["D",1783792664698],"---\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\nits own HTTP file in the host val (own URL, but scoped SQLite/blob is\nval-scoped, so storage is still shared — confirmed platform fact). The router\nendpoint is a launcher that 302s `/issues` to the sibling's URL. Existing\nintegrations work unmodified 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\nonly if 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 [ADR 0001](../../../adr/0001-dispatch-architecture.md).\nThe prototype (`proto/`, since 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\n router canonicalizing `/slug` → `/slug/` (302, reverse-proxy convention),\n plain relative links AND relative form actions resolve correctly. Only\n root-absolute paths (`/two`, `action=\"/add\"`) break. Contract rule: use\n relative URLs or the provided prefix; never root-absolute.\n- **Router-owned auth verified.** `oauthMiddleware` wrapped once at the\n router; after one login, children saw the user both via a router-set header\n (`x-router-user`) and by calling `getOAuthUserData` directly on the\n rewritten request — cookies flow through. Integrations need no OAuth code.\n- **Scoped SQLite is shared across all mount styles** (val-scoped, verified\n in 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\n mean creating a file per integration instead of just importing a factory\n (a real UX loss).\n",[],[231,478,479,344,545],"72785ed1-e6af-4eb2-a126-35d7610911ca",113,["D",1783792524099],[256,257,258,259,260,261,262,263],[231,478,479,344],"4943a8e8-7e18-4b5e-9cf5-01f32b53ffb3","b0de7188-7d51-11f1-b8b2-1607ee4eb77e",112,["D",1783792523949],[255,264,265],[231,478,479],"159d8575-7826-4301-a89a-db8a19f128a9",111,["D",1783792523821],[254],[231,478],"151c95c8-1822-4e02-a59f-8585f823e2f3","building-host-scoped-integrations.md","7b67cef6-7d69-11f1-821f-1607ee4eb77e","2428d405-c9ba-409c-80a1-535778f75f37",138,["D",1783802814383],"# 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.",[],[231,577,569],"notes","652c10c5-892e-45b9-8646-fc241d0be5f7",135,["D",1783802742029],[252],[231,577],"e6888750-1cd9-420f-922a-381b22a205ad","0003-callable-integrations.md","38b33f42-7d40-11f1-9235-1607ee4eb77e","c2500b00-7cb3-11f1-accf-1607ee4eb77e",68,["D",1783785020716],"# defineIntegration returns a callable Integration\n\n`defineIntegration` returns the `Integration` object made directly callable\nas an 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({...})`\nas a standalone HTTP val AND `createRouter({ integrations: [myFactory({...})] })`\n— and an `Integration` is a plain object, not a function, so without this the\ntwo mounting styles would need different factory return values (`.handler` in\none place, the object in the other). Making the contract helper produce the\nhybrid gives every author dual-mode support for free; the val-issue-tracker\nmigration proved 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\n merely satisfy the `Integration` type keep working when registered, they\n just aren't standalone-mountable.\n",[],[231,592,584],"adr","37dcf046-3898-4ff2-80a4-b684d1d7852d","0002-location-header-rewriting.md","cf4fd38c-7cb6-11f1-b356-1607ee4eb77e",50,["D",1783726398517],"# The router rewrites root-absolute Location headers, and only those\n\nWhen a mounted integration responds with a `Location` header starting with\n`/`, the router prepends the mount prefix (`Location: /?ok=x` →\n`/issues/?ok=x`); HTML bodies are never rewritten. We chose this asymmetry —\nover rewriting nothing (strict authoring rule) or rewriting everything (full\nreverse-proxy) — because HTML links have the document base URL as a safety\nnet, so relative links are natural to write, while redirects are generated\nfar from any notion of \"where am I mounted\"; covering `Location` makes the\nubiquitous redirect-after-POST idiom (`c.redirect(\"/?ok=...\")`) work\nunmodified in both routed and standalone modes with zero branching, exactly\nlike nginx's `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",[],[231,592,594],"ccb529f3-9e06-4ec0-808e-d7e4b8093b08","0001-dispatch-architecture.md","c2a2a518-7cb3-11f1-af02-1607ee4eb77e",38,["D",1783724692803],"# 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\npassing mount context along. We prototyped both this and the alternative —\neach integration as its own sibling HTTP file in the host val, with a\ndirectory endpoint 302-ing out — and chose in-process (2026-07-10, prototype\nsince deleted; 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,\nthe single URL is only a launcher, and `createRouter({ integrations: [...] })`\ncan't exist — mounting means creating a file per integration instead of\nimporting a factory.\n\n## Consequences\n\n- One origin: one OAuth login for every integration. Verified: the router\n wraps `oauthMiddleware` once, and `getOAuthUserData` works both in the\n router and inside a prefix-mounted child (session cookies survive the\n request rewrite).\n- Integration authors must use relative URLs (or the provided mount prefix)\n and 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\n the rejected option too).\n- Request bodies are re-wrapped during URL rewriting; the router buffers them\n rather than streaming.\n",[],[231,592,602],"b8d5d5fd-e95b-4cdc-831d-08861e689a73",32,["D",1783724692595],[248,249,250],[231,592],["D",1783724692393],[247,251,253],[231],["D",1783715038579],["D",1789525245864],{"_96":95,"_103":99},{"_96":95,"_97":-5,"_98":99,"_18":53,"_100":101,"_102":24},{"_13":85,"_31":86,"_41":40,"_87":42,"_88":-5,"_89":-5,"_90":-5,"_91":-5,"_92":-5,"_93":43,"_94":95},"ctx",{"_78":-5,"_123":655,"_656":657,"_658":659,"_660":24,"_661":24,"_662":24,"_663":121,"_664":-5,"_665":-7,"_666":-7,"_667":59,"_668":24,"_669":24,"_670":-5,"_671":24,"_672":24,"_673":24,"_674":-5},"ENV",{"_626":627,"_628":629,"_630":86,"_631":632,"_633":634,"_635":636,"_637":638,"_639":640,"_641":642,"_643":644,"_645":646,"_647":648,"_649":650,"_651":652,"_653":654},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","5015b8df46402d8bba4f485ecc37aec202b0e06b","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"]

Diff · v168