[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_626":627,"_628":629},"routes/_app.x.$handle.$name",{"_98":97,"_32":45,"_106":88,"_27":53,"_13":14,"_107":-5,"_11":108,"_109":110,"_111":112,"_113":114,"_115":116,"_20":-5,"_117":-5,"_118":-5,"_119":25,"_120":121,"_122":123,"_124":-5,"_125":-5,"_126":127},"routes/_app.x.$handle.$name.branch.$branch.version.$version.diff",{"_11":12,"_13":14,"_15":16,"_17":-5,"_18":-5},"project",{"_43":44,"_32":45,"_38":46,"_47":-5,"_48":25,"_49":50,"_51":50,"_52":53,"_54":-5,"_18":55,"_56":-5,"_57":25,"_58":-5,"_59":-5,"_60":61,"_62":63,"_64":65,"_66":67,"_68":69,"_70":-5,"_71":72,"_73":72,"_74":75,"_76":75,"_77":75,"_78":72,"_79":72,"_80":81,"_82":83,"_84":85,"_86":25},"version",206,"changes",[19],"aiChatInfo","userId",{"_20":21,"_22":23,"_24":25,"_26":25,"_27":28,"_29":28},"file",{"_30":31,"_32":33,"_34":20,"_35":37,"_38":39,"_40":14,"_41":42,"_24":25},"previous",{"_30":31,"_32":33,"_34":20,"_35":36},"deleted",false,"deletedHere","path","docs/wayfinder-archive/integrations-v1/README.md","latestPath","fileId","b17b36ee-7d51-11f1-bf82-1607ee4eb77e","name","README.md","fileType","content","# 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","# Wayfinder archive — Integrations v1\n\nA completed wayfinder effort, archived here as a historical record. The map\nreached its destination on 2026-07-11; all tickets are closed.\n\n- [`map.md`](map.md) — the map: destination, decisions-so-far (the route\n walked), and out-of-scope notes.\n- [`tickets/`](tickets/) — the eight resolved tickets, each with its\n `## Resolution`.\n\n**Destination reached:** a working v1 of the `integrations` val — the published\n`Integration` contract (`defineIntegration`, `createRouter`), both\n`val-issue-tracker` and `scoped-blob-viewer` migrated onto it, a hello-world\nexample, and README author docs.\n\nThis effort is done; it is not resumed. The next effort (leading candidate:\n**fine-grained auth for routed integrations**, see the map's Out of scope\nsection) is a fresh wayfinder map, started at `wayfinder/` from a clean slate.\n","createdAt",["D",1784043354774],"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",{"_98":97,"_105":101},"org",{"_98":97,"_99":-5,"_100":101,"_18":55,"_102":103,"_104":25},"branch",{"_13":87,"_32":88,"_43":42,"_89":44,"_90":-5,"_91":-5,"_92":-5,"_93":-5,"_94":-5,"_95":45,"_96":97},"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",{"_43":44,"_32":45,"_38":621,"_47":-5,"_48":25,"_49":50,"_51":50,"_52":53,"_54":-5,"_18":55,"_56":-5,"_57":25,"_58":-5,"_59":-5,"_60":61,"_62":63,"_64":65,"_66":67,"_68":622,"_70":-5,"_71":72,"_73":72,"_74":75,"_76":75,"_77":75,"_78":72,"_79":72,"_80":623,"_82":624,"_84":625,"_86":25},"tree",[248,268,272,288,289,290,291,292,293,294,295,296,297],"files",[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,296,297],"counts",{"_238":61,"_239":190,"_240":61,"_241":242,"_243":244},"contents",[128,129,130,131,132,133,134,135,136,137,138,139,140],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles",true,"grants","orgs","customDomains",{},{"_43":232,"_32":233,"_30":234,"_144":-5,"_41":42,"_40":235,"_146":123,"_38":236,"_13":61,"_34":224,"_35":-5,"_24":25,"_151":-5,"_27":237},{"_43":226,"_32":227,"_30":228,"_144":-5,"_41":42,"_40":229,"_146":123,"_38":230,"_13":61,"_34":224,"_35":-5,"_24":25,"_151":-5,"_27":231},{"_43":219,"_32":220,"_30":221,"_144":-5,"_41":42,"_40":222,"_146":123,"_38":223,"_13":61,"_34":224,"_35":-5,"_24":25,"_151":-5,"_27":225},{"_43":213,"_32":214,"_30":215,"_144":-5,"_41":42,"_40":182,"_146":123,"_38":216,"_13":61,"_34":20,"_35":217,"_24":25,"_151":-5,"_27":218},{"_43":206,"_32":207,"_30":208,"_144":-5,"_41":42,"_40":209,"_146":25,"_38":210,"_13":182,"_34":20,"_35":211,"_24":25,"_151":-5,"_27":212},{"_43":199,"_32":200,"_30":201,"_144":-5,"_41":42,"_40":202,"_146":123,"_38":203,"_13":182,"_34":20,"_35":204,"_24":25,"_151":-5,"_27":205},{"_43":193,"_32":33,"_30":194,"_144":-5,"_41":42,"_40":195,"_146":25,"_38":196,"_13":158,"_34":20,"_35":197,"_24":25,"_151":-5,"_27":198},{"_43":185,"_32":186,"_30":187,"_144":-5,"_41":42,"_40":188,"_146":25,"_38":189,"_13":190,"_34":20,"_35":191,"_24":25,"_151":-5,"_27":192},{"_43":177,"_32":178,"_30":179,"_144":-5,"_41":42,"_40":180,"_146":25,"_38":181,"_13":182,"_34":20,"_35":183,"_24":25,"_151":-5,"_27":184},{"_43":168,"_32":169,"_30":170,"_144":-5,"_41":42,"_40":171,"_146":123,"_38":172,"_13":173,"_34":174,"_35":175,"_24":25,"_151":-5,"_27":176},{"_43":161,"_32":162,"_30":163,"_144":-5,"_41":42,"_40":164,"_146":25,"_38":165,"_13":158,"_34":149,"_35":166,"_24":25,"_151":-5,"_27":167},{"_43":153,"_32":154,"_30":155,"_144":-5,"_41":42,"_40":156,"_146":25,"_38":157,"_13":158,"_34":149,"_35":159,"_24":25,"_151":-5,"_27":160},{"_43":141,"_32":142,"_30":143,"_144":-5,"_41":42,"_40":145,"_146":25,"_38":147,"_13":148,"_34":149,"_35":150,"_24":25,"_151":-5,"_27":152},"daefb13d-1b54-4a47-b783-a72793450cfd","router_test.ts","47cd43fc-7cb8-11f1-bf06-1607ee4eb77e","parentId",202,"latest",["D",1784043355428],2,"script","import { assert, assertEquals, assertThrows } from \"@std/assert\";\nimport {\n createRouteHandler,\n defineIntegration,\n type IntegrationContext,\n type 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 let lastCtx: IntegrationContext | undefined;\n const integration = defineIntegration({\n name,\n slug,\n handler: async (req, ctx) => {\n lastCtx = ctx;\n const url = new URL(req.url);\n if (req.method === \"POST\") {\n return new Response(`echo:${await req.text()}`);\n }\n if (url.pathname === \"/redirect\") {\n return new Response(null, {\n status: 302,\n headers: { Location: \"/?ok=done\" },\n });\n }\n if (url.pathname === \"/redirect-external\") {\n return new Response(null, {\n status: 302,\n headers: { Location: \"https://example.com/x\" },\n });\n }\n if (url.pathname === \"/redirect-protocol-relative\") {\n return new Response(null, {\n status: 302,\n headers: { Location: \"//example.com/x\" },\n });\n }\n return new Response(`path:${url.pathname}`);\n },\n });\n return { integration, ctx: () => lastCtx };\n}\n\nfunction router(opts: Partial, getUser = anon) {\n return createRouteHandler(\n { integrations: [], auth: false, ...opts },\n getUser,\n );\n}\n\n// ---------------------------------------------------------------------------\n// Validation\n// ---------------------------------------------------------------------------\n\nDeno.test(\"defineIntegration rejects invalid slugs\", () => {\n for (const slug of [\"\", \"Bad\", \"has_underscore\", \"has space\", \"café\"]) {\n assertThrows(\n () =>\n defineIntegration({ name: \"x\", slug, handler: () => new Response() }),\n Error,\n \"invalid\",\n );\n }\n});\n\nDeno.test(\"reserved slugs throw\", () => {\n assertThrows(\n () =>\n defineIntegration({\n name: \"x\",\n slug: \"auth\",\n handler: () => new Response(),\n }),\n Error,\n \"reserved\",\n );\n});\n\nDeno.test(\"duplicate slugs throw at construction\", () => {\n const a = echoIntegration(\"toy\").integration;\n const b = echoIntegration(\"toy\").integration;\n assertThrows(() => router({ integrations: [a, b] }), Error, \"Duplicate\");\n});\n\nDeno.test(\"defineIntegration returns a callable integration serving both modes\", async () => {\n const integration = defineIntegration({\n name: \"Toy Thing\",\n slug: \"toy\",\n handler: (_req, ctx) => new Response(`user:${ctx?.user ?? \"none\"}`),\n });\n // Integration fields survive on the callable (incl. `name`, which must\n // shadow the function's own read-only name).\n assertEquals(integration.name, \"Toy Thing\");\n assertEquals(integration.slug, \"toy\");\n // Standalone: called as a plain HTTP handler, no ctx.\n const standalone = await integration(new Request(\"https://r.test/\"));\n assertEquals(await standalone.text(), \"user:none\");\n // Routed: ctx flows through to the wrapped handler.\n const routed = await integration(new Request(\"https://r.test/\"), {\n user: \"nbbaier\",\n prefix: \"/toy\",\n });\n assertEquals(await routed.text(), \"user:nbbaier\");\n});\n\n// ---------------------------------------------------------------------------\n// Dispatch\n// ---------------------------------------------------------------------------\n\nDeno.test(\"dispatch strips the prefix and passes ctx\", async () => {\n const { integration, ctx } = echoIntegration(\"toy\");\n const handle = router({ integrations: [integration] });\n const res = await handle(new Request(\"https://r.test/toy/deep/path?q=1\"));\n assertEquals(await res.text(), \"path:/deep/path\");\n assertEquals(ctx()?.prefix, \"/toy\");\n assertEquals(ctx()?.user, null);\n});\n\nDeno.test(\"bare /slug canonicalizes to /slug/ preserving the query\", async () => {\n const { integration } = echoIntegration(\"toy\");\n const handle = router({ integrations: [integration] });\n const res = await handle(new Request(\"https://r.test/toy?q=1\"));\n assertEquals(res.status, 302);\n assertEquals(res.headers.get(\"Location\"), \"/toy/?q=1\");\n});\n\nDeno.test(\"POST bodies survive the rewrite\", async () => {\n const { integration } = echoIntegration(\"toy\");\n const handle = router({ integrations: [integration] });\n const res = await handle(\n new Request(\"https://r.test/toy/\", { method: \"POST\", body: \"hello\" }),\n );\n assertEquals(await res.text(), \"echo:hello\");\n});\n\nDeno.test(\"unknown paths 404; root serves the directory\", async () => {\n const { integration } = echoIntegration(\"toy\", \"Toy Thing\");\n const handle = router({ integrations: [integration], title: \"My Tools\" });\n assertEquals((await handle(new Request(\"https://r.test/nope\"))).status, 404);\n const dir = await handle(new Request(\"https://r.test/\"));\n assertEquals(dir.status, 200);\n const html = await dir.text();\n assert(html.includes(\"My Tools\"));\n assert(html.includes(\"Toy Thing\"));\n assert(html.includes(`href=\"toy/\"`)); // relative link, per the hygiene rule\n});\n\nDeno.test(\"directory badges missing requiredEnv\", async () => {\n const integration = defineIntegration({\n name: \"Needy\",\n slug: \"needy\",\n requiredEnv: [\"DEFINITELY_NOT_SET_FOR_TESTS_XYZ\"],\n handler: () => new Response(),\n });\n const handle = router({ integrations: [integration] });\n const html = await (await handle(new Request(\"https://r.test/\"))).text();\n assert(html.includes(\"missing env\"));\n assert(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 const { integration } = echoIntegration(\"toy\");\n const handle = router({ integrations: [integration] });\n const res = await handle(new Request(\"https://r.test/toy/redirect\"));\n assertEquals(res.headers.get(\"Location\"), \"/toy/?ok=done\");\n});\n\nDeno.test(\"absolute and protocol-relative Locations pass through untouched\", async () => {\n const { integration } = echoIntegration(\"toy\");\n const handle = router({ integrations: [integration] });\n const abs = await handle(new Request(\"https://r.test/toy/redirect-external\"));\n assertEquals(abs.headers.get(\"Location\"), \"https://example.com/x\");\n const proto = await handle(\n new Request(\"https://r.test/toy/redirect-protocol-relative\"),\n );\n assertEquals(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 const { integration } = echoIntegration(\"toy\");\n const handle = router({ integrations: [integration], auth: {} });\n const res = await handle(new Request(\"https://r.test/toy/\"));\n assertEquals(res.status, 401);\n assert((await res.text()).includes(\"/auth/login\"));\n const post = await handle(\n new Request(\"https://r.test/toy/\", { method: \"POST\", body: \"x\" }),\n );\n assertEquals(post.status, 302);\n assertEquals(post.headers.get(\"Location\"), \"/\");\n});\n\nDeno.test(\"auth on: logged-in user reaches the integration with ctx.user set\", async () => {\n const { integration, ctx } = echoIntegration(\"toy\");\n const handle = router(\n { integrations: [integration], auth: {} },\n as(\"nbbaier\"),\n );\n const res = await handle(new Request(\"https://r.test/toy/\"));\n assertEquals(res.status, 200);\n assertEquals(ctx()?.user, \"nbbaier\");\n});\n\nDeno.test(\"allowlist: outsiders get 403, listed users get in\", async () => {\n const { integration } = echoIntegration(\"toy\");\n const opts = { integrations: [integration], auth: { users: [\"nbbaier\"] } };\n const outsider = router(opts, as(\"mallory\"));\n assertEquals(\n (await outsider(new Request(\"https://r.test/toy/\"))).status,\n 403,\n );\n const owner = router(opts, as(\"nbbaier\"));\n assertEquals((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 const { integration, ctx } = echoIntegration(\"toy\");\n const handle = router({ integrations: [integration], auth: false });\n const res = await handle(new Request(\"https://r.test/toy/\"));\n assertEquals(res.status, 200);\n assertEquals(ctx()?.user, null);\n});\n","label",[142],"04a8d65f-b0e4-4875-9a22-78de10557143","router.ts","47659324-7cb8-11f1-b846-1607ee4eb77e",182,["D",1784043352342],3,"// 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 getOAuthUserData,\n oauthMiddleware,\n} from \"https://esm.town/v/std/oauth/middleware.ts\";\n\nexport interface IntegrationContext {\n /** Val Town username from router-owned OAuth; null when auth is off. */\n user: string | null;\n /** Mount prefix, e.g. \"/issues\". */\n prefix: string;\n}\n\nexport type IntegrationHandler = (\n req: Request,\n ctx?: IntegrationContext,\n) => Response | Promise;\n\nexport interface Integration {\n name: string;\n slug: string;\n description?: string;\n /** Env vars the integration needs; missing ones badge the directory page. */\n requiredEnv?: string[];\n handler: 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 /** Order here is the directory page order. */\n integrations: Integration[];\n /** Default: on, any logged-in Val Town user. `false` disables the gate. */\n auth?: RouterAuthOptions;\n title?: 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 return RESERVED_SLUGS.some((r) =>\n typeof r === \"string\" ? r === slug : r.test(slug)\n );\n}\n\nfunction validateSlug(slug: string): void {\n if (!SLUG_PATTERN.test(slug)) {\n throw new Error(\n `Integration slug \"${slug}\" is invalid: slugs must match ${SLUG_PATTERN}.`,\n );\n }\n if (isReserved(slug)) {\n throw new Error(`Integration slug \"${slug}\" is reserved by the router.`);\n }\n}\n\nexport function defineIntegration(\n integration: Integration,\n): CallableIntegration {\n validateSlug(integration.slug);\n const callable =\n ((req: Request, ctx?: IntegrationContext) =>\n integration.handler(req, ctx)) as CallableIntegration;\n for (const [key, value] of Object.entries(integration)) {\n if (value === undefined) continue;\n // defineProperty, not assignment: a function's own `name` is read-only\n // (but configurable), and Integration.name must shadow it.\n Object.defineProperty(callable, key, {\n value,\n enumerable: true,\n configurable: true,\n writable: true,\n });\n }\n return callable;\n}\n\n// ---------------------------------------------------------------------------\n// HTML\n// ---------------------------------------------------------------------------\n\nfunction escapeHtml(s: string): string {\n return s.replace(\n /[&<>\"']/g,\n (c) =>\n ({\n \"&\": \"&\",\n \"<\": \"<\",\n \">\": \">\",\n '\"': \""\",\n \"'\": \"'\",\n })[c] as string,\n );\n}\n\nfunction page(title: string, body: string, status = 200): Response {\n return new Response(\n `\n\n${escapeHtml(title)}\n${body}`,\n { status, headers: { \"Content-Type\": \"text/html; charset=utf-8\" } },\n );\n}\n\nfunction missingEnv(keys: string[] | undefined): string[] {\n if (!keys) return [];\n return keys.filter((k) => {\n try {\n return !Deno.env.get(k);\n } catch {\n return false; // no env permission — don't false-alarm\n }\n });\n}\n\nfunction directoryPage(\n options: RouterOptions,\n user: string | null,\n authEnabled: boolean,\n): Response {\n const title = options.title ?? \"Integrations\";\n const items = options.integrations\n .map((i) => {\n const missing = missingEnv(i.requiredEnv);\n return `

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

${escapeHtml(i.description)}

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

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

`\n : \"\"\n }

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

@${escapeHtml(user)} ·\n

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

${escapeHtml(title)}

${who}

\n${\n options.integrations.length === 0\n ? `

No integrations registered.

`\n : `

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

${escapeHtml(title)}

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

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

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

`\n }`,\n 401,\n );\n}\n\n// ---------------------------------------------------------------------------\n// Router\n// ---------------------------------------------------------------------------\n\nfunction allowedUsers(auth: RouterAuthOptions | undefined): string[] | null {\n if (auth === false || auth?.users == null) return null;\n return 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 const location = res.headers.get(\"Location\");\n if (!location || !ROOT_ABSOLUTE.test(location)) return res;\n const rewritten = new Response(res.body, res);\n rewritten.headers.set(\"Location\", prefix + location);\n return rewritten;\n}\n\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 options: RouterOptions,\n getUser: GetUser,\n): (req: Request) => Promise {\n const seen = new Set();\n for (const i of options.integrations) {\n validateSlug(i.slug);\n if (seen.has(i.slug)) {\n throw new Error(`Duplicate integration slug \"${i.slug}\".`);\n }\n seen.add(i.slug);\n }\n\n const authEnabled = options.auth !== false;\n const allowlist = allowedUsers(options.auth);\n\n return async (req: Request): Promise => {\n const url = new URL(req.url);\n\n let user: string | null = null;\n if (authEnabled) {\n user = await getUser(req);\n if (!user) {\n if (req.method !== \"GET\") {\n return new Response(null, {\n status: 302,\n headers: { Location: \"/\" },\n });\n }\n return loginPage(options);\n }\n if (allowlist && !allowlist.includes(user)) {\n return page(\n options.title ?? \"Integrations\",\n `

403

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

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

404

← back to the directory

`,\n 404,\n );\n };\n}\n\nasync function oauthUser(req: Request): Promise {\n const session = await getOAuthUserData(req);\n return session?.user?.username ?? null;\n}\n\nexport function createRouter(\n options: RouterOptions,\n): (req: Request) => Response | Promise {\n const handler = createRouteHandler(options, oauthUser);\n return options.auth === false ? handler : oauthMiddleware(handler);\n}\n",[154],"203aa147-43bd-4aa7-9db4-94932c42262b","mod.ts","4795d00c-7cb8-11f1-a2c1-1607ee4eb77e",205,["D",1784043356125],"export {\n type CallableIntegration,\n // The OAuth-free router core with user lookup injected — the public test\n // seam for integration authors to exercise routed mode without a session.\n createRouteHandler,\n createRouter,\n defineIntegration,\n type Integration,\n type IntegrationContext,\n type IntegrationHandler,\n type RouterAuthOptions,\n type RouterOptions,\n} from \"./router.ts\";\n",[162],"e7c0407c-34ff-4b62-a8b0-1aaca374f16f","main.ts","477921dc-7cb8-11f1-94e8-1607ee4eb77e",180,["D",1784043352057],7,"http","// This val's own consumer of its router.\nimport { blobAdmin } from \"https://esm.town/v/nbbaier/scoped-blob-viewer/mod.ts\";\nimport { issueTracker } from \"https://esm.town/v/nbbaier/val-issue-tracker/mod.ts\";\nimport { helloWorld } from \"./example/hello.ts\";\nimport { createRouter } from \"./mod.ts\";\n\nexport default createRouter({\n title: \"Integrations\",\n auth: { users: \"nbbaier\" },\n integrations: [issueTracker({}), blobAdmin({}), helloWorld()],\n});\n",[169],"59470606-2afa-4f5d-956d-757e96e516c7","deno.json","525df192-7c9d-11f1-a2d0-1607ee4eb77e",196,["D",1784043352965],4,"{\n \"compilerOptions\": {\n \"lib\": [\n \"dom\",\n \"dom.iterable\",\n \"dom.asynciterable\",\n \"deno.ns\",\n \"deno.unstable\"\n ],\n \"noImplicitAny\": false,\n \"strict\": false,\n \"types\": [\"https://www.val.town/types/valtown.d.ts\"]\n },\n \"experimental\": {\n \"unstable-node-globals\": true,\n \"unstable-sloppy-imports\": true,\n \"unstable-temporal\": true,\n \"unstable-worker-options\": true\n },\n \"imports\": {\n \"@biomejs/biome\": \"npm:@biomejs/biome@^2.5.2\",\n \"@std/assert\": \"jsr:@std/assert@^1.0.19\"\n },\n \"lint\": {\n \"include\": [\"*.ts\", \"*.tsx\", \"example/*.ts\"],\n \"rules\": {\n \"exclude\": [\"no-explicit-any\", \"no-import-prefix\"]\n }\n },\n \"lock\": false,\n \"nodeModulesDir\": \"auto\",\n \"tasks\": {\n \"fmt\": \"biome check . --write\",\n \"lint\": \"deno lint\",\n \"typecheck\": \"VAL_TOWN_API_KEY=test deno check --allow-import=esm.town,www.val.town,esm.sh,jsr.io main.ts mod.ts router.ts router_test.ts example/hello.ts example/hello_test.ts\",\n \"test\": \"VAL_TOWN_API_KEY=test deno test --allow-env --allow-import=esm.town,www.val.town,esm.sh,jsr.io\",\n \"check\": \"deno task fmt && deno task lint && deno task typecheck && deno task test\"\n }\n}\n",[178],"492b38f5-7c66-484d-9a31-9ee8ca5ca590","biome.json","52555852-7c9d-11f1-80bb-1607ee4eb77e",204,["D",1784043355938],1,"{\n \"$schema\": \"https://biomejs.dev/schemas/2.5.2/schema.json\",\n \"vcs\": {\n \"enabled\": false,\n \"clientKind\": \"git\",\n \"useIgnoreFile\": false\n },\n \"files\": {\n \"ignoreUnknown\": false\n },\n \"formatter\": {\n \"enabled\": true,\n \"indentStyle\": \"tab\"\n },\n \"linter\": {\n \"enabled\": true,\n \"rules\": {\n \"preset\": \"recommended\"\n }\n },\n \"javascript\": {\n \"formatter\": {\n \"quoteStyle\": \"double\"\n }\n },\n \"assist\": {\n \"enabled\": true,\n \"actions\": {\n \"source\": {\n \"organizeImports\": \"on\"\n }\n }\n }\n}\n",[186],"6513922a-9eb5-4352-bbf7-c758ab5287fb","de745920-7d4f-11f1-896c-1607ee4eb77e",203,["D",1784043355309],"# integrations\n\nA contract and router for mounting reusable web apps — **integrations** — into a\nsingle Val Town val. One val, one login, one URL; many project-level tools\\\nserved underneath it.\n\n```\nhttps://you-integrations.web.val.run/ → directory page\n /issues/ → the issue tracker\n /blobs/ → the blob viewer\n /hello/ → your integration\n```\n\nThe router mounts each integration **in-process** and dispatches by path prefix\n(no per-integration redirects, no separate logins). It owns authentication,\nserves a directory page at `/`, and passes each integration a small context —\nthe logged-in user and its mount prefix. See [`docs/adr/`](docs/adr/) for the\narchitecture decisions behind this.\n\n## The pattern\n\nAn **integration** is a mountable sub-app over a Val Town scoped resource: a\nself-contained web app — UI, routes, and its own authorization — wrapped around\none val-scoped thing (a SQLite-backed domain, the blob store). The contract here\nis that shape extracted from two apps that already had it\n([`val-issue-tracker`](https://www.val.town/x/nbbaier/val-issue-tracker) and\n[`scoped-blob-viewer`](https://www.val.town/x/nbbaier/scoped-blob-viewer)).\n\nWhat makes it more than a mounted sub-router is Val Town's scoping: because\nscoped SQLite/blob bind to whichever val's runtime is **executing** the code, an\nintegration operates on its **host val's** data and identity just by being\nimported — no tokens, no config. Three properties fall out of that:\n\n- **Host-scoped, not self-scoped** — drop it into any val and it points at that\n val's storage automatically.\n- **Portable / dual-mode** — the same value runs standalone (a val's HTTP\n export) or routed (mounted at `/slug/`), thanks to relative-only links and a\n callable contract.\n- **Composable** — it keeps its own authorization but lifts authentication up to\n the host or router, so many integrations stack behind one origin and one\n login.\n\nThe closest analogies are Rails engines or Hono/Express sub-apps mounted at a\nprefix — but host-scoped, so mounting also inherits the host's data and identity\nfor free.\n\nThere are two audiences below:\n**[mounting integrations](#mounting-integrations)** if you want to run a router,\nand **[writing an integration](#writing-an-integration)** if you want to build\none.\n\n---\n\n## Mounting integrations\n\nImport the integrations you want and hand them to `createRouter`. Its return\nvalue is a plain HTTP handler — make it your val's default export.\n\n```ts\nimport { createRouter } from \"https://esm.town/v/nbbaier/integrations/mod.ts\";\nimport { issueTracker } from \"https://esm.town/v/nbbaier/val-issue-tracker/mod.ts\";\nimport { blobAdmin } from \"https://esm.town/v/nbbaier/scoped-blob-viewer/mod.ts\";\n\nexport default createRouter({\n title: \"My Tools\",\n auth: { users: \"nbbaier\" },\n integrations: [issueTracker({}), blobAdmin({})],\n});\n```\n\nEach integration is served at `//`, listed on the directory page at `/`,\nand shares the host val's scoped SQLite and blob storage. See\n[`INTEGRATIONS.md`](INTEGRATIONS.md) for the registry of known integrations and\ntheir import paths.\n\n### Auth\n\nThe router owns the OAuth gate — one login covers every integration.\n\n| `auth` value | Who gets in |\n| ----------------------------- | -------------------------------------------- |\n| _omitted_ (default) | Any logged-in Val Town account |\n| `{ users: \"alice\" }` | Only `@alice` |\n| `{ users: [\"alice\", \"bob\"] }` | Only `@alice` or `@bob` |\n| `false` | No gate — the router is open, `user` is null |\n\nWhen the gate is on, set an `OAUTH_STATE_ENCRYPTION_KEY` env var (any random\n32-byte hex string) or login will fail. The login page warns you if it's\nmissing, and the directory page badges any integration whose `requiredEnv` vars\nare unset.\n\n### Reserved paths\n\nThe router keeps `/` (the directory page) and `/auth/*` (the OAuth routes) for\nitself. Integration slugs are validated against these — see\n[reserved slugs](#reserved-slugs).\n\n---\n\n## Writing an integration\n\nAn integration is metadata plus a fetch handler. You ship an\n`(options) => Integration` **factory**; users register the factory's return\nvalue with a router, or mount it standalone as a val's HTTP export. The same\nvalue serves both modes.\n\nHere is the entire worked example ([`example/hello.ts`](example/hello.ts)) —\ncopy it to start your own. Every line is contract surface, not app logic. A\nline-by-line walkthrough lives in [`example/README.md`](example/README.md).\n\n```ts\nimport { defineIntegration } from \"https://esm.town/v/nbbaier/integrations/mod.ts\";\n\nexport interface HelloWorldOptions {\n subject?: string;\n}\n\nexport function helloWorld(options: HelloWorldOptions = {}) {\n const subject = options.subject ?? \"world\";\n return defineIntegration({\n name: \"Hello World\",\n slug: \"hello\",\n description: \"The smallest possible integration — the worked example.\",\n requiredEnv: [\"HELLO_GREETING\"],\n handler: (req, ctx) => {\n const greeting = Deno.env.get(\"HELLO_GREETING\") ?? \"Hello\";\n const who = ctx?.user ? `@${ctx.user}` : subject;\n const body = new URL(req.url).pathname === \"/about\"\n ? `

A toy integration.

back

`\n : `

${greeting}, ${who}!

about

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

A toy integration.

back

`\n : `

${greeting}, ${who}!

about

`;\n return new Response(`${body}`, {\n headers: { \"Content-Type\": \"text/html; charset=utf-8\" },\n });\n },\n });\n}\n\nexport default helloWorld();\n",[],[227,458],"ea1eb4f0-a41d-4a0b-83fd-89d05b2bc036","de3d453e-7d4f-11f1-a875-1607ee4eb77e",131,["D",1783792711187],"# The worked example\n\n[`hello.ts`](hello.ts) is the smallest honest integration — every line is\ncontract surface, not app logic. Copy it to start your own, and read this file\nalongside it. For the full contract, see the [top-level README](../README.md).\n\n## Walkthrough\n\n**The factory.** Authors export an `(options) => Integration` factory, not a\nbare `Integration`:\n\n```ts\nexport function helloWorld(options: HelloWorldOptions = {}) {\n```\n\nAll configuration lives in the closure (`subject` here), never on the\n`Integration` object. Take an options bag even when you need no config\n(`options = {}`) so the calling convention stays uniform across integrations.\n\n**The contract object.** `defineIntegration` takes the metadata plus a handler:\n\n```ts\nreturn defineIntegration({\n\tname: \"Hello World\",\n\tslug: \"hello\",\n\tdescription: \"…\",\n\trequiredEnv: [\"HELLO_GREETING\"],\n\thandler: (req, ctx) => { … },\n});\n```\n\n- `slug` is where the router mounts you (`/hello/`). It must match\n `^[a-z0-9-]+$` and avoid the reserved slugs; `defineIntegration` throws at\n construction if it doesn't.\n- `requiredEnv` lists the env vars you read. Unset ones badge the router's\n directory page — they never block the integration.\n\n**Read env at request time.**\n\n```ts\nconst greeting = Deno.env.get(\"HELLO_GREETING\") ?? \"Hello\";\n```\n\nRead env vars inside the handler, never at import time. Import-time reads run\nbefore the val's environment is available and break standalone mounting.\n\n**The dual-mode idiom.**\n\n```ts\nconst who = ctx?.user ? `@${ctx.user}` : subject;\n```\n\n`ctx` is present when routed, absent when standalone — its absence is how the\nhandler knows no router is in front of it. `ctx?.user` is the router-provided\nVal Town username; fall back to your own default when it's missing.\n\n**Relative links only.**\n\n```ts\n`about`; // not href=\"/about\"\n```\n\nRelative URLs resolve inside the mount prefix when routed and at the root when\nstandalone, with no branching. Root-absolute paths (`/about`) break under a\nmount — see the top-level README's prefix rules and\n[ADR 0002](../docs/adr/0002-location-header-rewriting.md).\n\n**Standalone export.**\n\n```ts\nexport default helloWorld();\n```\n\nBecause `defineIntegration` returns a _callable_ integration, the same value is\nboth an `Integration` (for `createRouter`) and an HTTP handler (as a val's\ndefault export). One factory return value, two mounting modes — see\n[ADR 0003](../docs/adr/0003-callable-integrations.md).\n\n## Testing\n\n[`hello_test.ts`](hello_test.ts) exercises both modes:\n\n- **Routed** — via `createRouteHandler`, the OAuth-free test seam, with a user\n injected. It asserts the routed user is greeted and that links stay relative.\n- **Standalone** — call the default export (and the factory with a custom\n `subject`) directly, with no `ctx`, and check the fallback subject.\n",[],[227,33],["D",1783788334625],[269,270,271],[227],"dc2ce713-2a27-4288-a862-e61bfee630e1","273b54e6-7cb1-11f1-9d45-1607ee4eb77e","b0f10802-7d51-11f1-bd58-1607ee4eb77e",200,["D",1784043354970],11,"---\ntitle: Integrations v1 — contract + meta-router for Val Town project integrations\nlabels: [wayfinder:map]\nstatus: closed\n---\n\n## Destination\n\nA working v1 of the `integrations` val: a published `Integration` contract\n(`Integration` type, `defineIntegration`, `createRouter`) with\n`val-issue-tracker` and `scoped-blob-viewer` fully migrated onto it, a toy\nhello-world integration, and README contract docs for third-party authors.\n\n## Notes\n\n- **This map carries execution.** The destination is working code, so tickets\n build and migrate, not just decide.\n- Domain: Val Town platform (Deno runtime, scoped SQLite/blob, std/oauth).\n Sessions should consult the `valtown:http-endpoints`, `valtown:oauth`,\n `valtown:sqlite-storage` skills, and use `find_val_town_skills` for anything\n platform-specific.\n- Ubiquitous language lives in `CONTEXT.md` (repo root) — consult it every\n session and maintain it via `/domain-modeling`: challenge drift, sharpen new\n terms inline as they crystallise. ADRs go in `docs/adr/` (created lazily),\n offered only for hard-to-reverse, surprising, real-trade-off decisions.\n- Repos (local working dirs): `~/Code/vt-projects/integrations` (this val,\n currently an empty `main.ts`), `~/Code/vt-projects/val-issue-tracker`,\n `~/Code/vt-projects/scoped-blob-viewer`.\n- Standing preferences from the charter session (2026-07-10):\n - Astro/vite-style composition: authors ship `(options) => Integration`\n factories; users write\n `createRouter({ integrations: [issueTracker({...})] })`. Options live in\n each factory's closure, never in the `Integration` type.\n - The router owns auth: one OAuth gate, `/auth/*` mounted once, user passed\n down. Design intent — pending runtime verification in the prototype.\n - Router serves a minimal directory page at `/` (name, description, link per\n integration, ⚠️ badge for missing `requiredEnv`). `/` and `/auth/*` are\n reserved paths; slugs validated against them and each other.\n - Both existing integrations migrate fully AND remain standalone-mountable\n (the factory serves both modes).\n - Biome is the canonical formatter (tab-indented), not `deno fmt`.\n- Tracker conventions (local markdown): tickets live in `wayfinder/tickets/`,\n one file each, frontmatter `id`, `title`, `labels`, `status: open|closed`,\n `assignee`, `blocked-by: [ids]`. Claim = set `assignee`. Frontier = open,\n unassigned, all `blocked-by` closed. Resolutions go in a `## Resolution`\n section on the ticket.\n\n## Decisions so far\n\n\n\n- [Prototype the dispatch architecture](tickets/001-prototype-dispatch-architecture.md)\n — in-process prefix mount\n ([ADR 0001](../../adr/0001-dispatch-architecture.md)): one origin,\n router-owned auth verified, hygiene = \"relative URLs only\" with\n router-enforced trailing-slash canonicalization.\n- [Pin the v1 contract](tickets/002-pin-the-v1-contract.md) —\n `handler(req, ctx)` with ctx-as-Hono-env alignment; router rewrites\n root-absolute `Location` headers\n ([ADR 0002](../../adr/0002-location-header-rewriting.md)); slugs\n `^[a-z0-9-]+$` with `[\"auth\", /^_/]` reserved, throw at construction; auth is\n a gate (`users` allowlist), not a role system.\n- [Build integrations v1](tickets/003-build-integrations-v1.md) — shipped:\n `mod.ts`/`router.ts` implement the contract with zero deviations, 14 tests\n green, live directory at this val's `main.ts` (login-gated, empty until the\n hello-world integration lands).\n- [Decide the publishing and versioning story](tickets/008-publishing-and-versioning.md)\n — unpinned `esm.town/.../mod.ts` imports + `?v=` escape hatch; breaking\n changes ship as a new entrypoint, never on `mod.ts`; post-v1, main is the\n release channel (branch + green `deno task check` to merge); val stays public.\n- [Migrate val-issue-tracker onto the contract](tickets/004-migrate-val-issue-tracker.md)\n — dual-mode via callable `defineIntegration`\n ([ADR 0003](../../adr/0003-callable-integrations.md)); `ctx.user` feeds the\n tracker's role model (null → read-only viewer, no login redirects in routed\n mode); bearer-token API gates stack behind a gated router; contract additions:\n `CallableIntegration` type, `createRouteHandler` made public as the test seam.\n Live at the integrations val's `/issues/`; answered the permission-model fog.\n- [Migrate scoped-blob-viewer onto the contract](tickets/005-migrate-scoped-blob-viewer.md)\n — dual-mode via callable `defineIntegration`, live at the integrations val's\n `/blobs/`; the prefix-hygiene stress test **passed with zero contract fights**\n (base-threaded links + root-absolute redirects rewritten per ADR 0002, no new\n contract surface). `owner` authorizes from `ctx.user` (all-or-nothing, no\n read-only role); JSX moved to `app.tsx` with `mod.ts` a JSX-free barrel so it\n type-checks locally — a lesson for ticket 7's docs.\n- [Add the hello-world example integration](tickets/006-hello-world-example-integration.md)\n — shipped `example/hello.ts`: a dependency-free `(options) => Integration`\n factory demonstrating the full contract (dual-mode `ctx?.user`, a\n genuinely-read `requiredEnv`, relative-only links), registered live in\n `main.ts`, tested both modes; kept out of `mod.ts` — it's the copyable worked\n example for ticket 7's docs.\n- [Write the third-party author docs](tickets/007-third-party-author-docs.md) —\n shipped `README.md` (both audiences) + `example/README.md` walkthrough; the\n explainability test passed with **zero contract changes**. Review pass also\n unified factory naming (`create*` → `issueTracker`/`blobAdmin`) across all\n three repos and restructured the val-issue-tracker README to the house\n standalone/routed shape. All three repos green. **Destination reached.**\n\n## Not yet specified\n\n\n\n## Out of scope\n\n- **Remixable template val** for integration authors — good idea, explicitly\n deferred past v1; revisit as a fresh effort once the contract has survived two\n real migrations.\n- **Full dashboard** at `/` (health checks, status, per-integration state) — v1\n ships the minimal directory page only.\n- **Auto-discovery** of sibling HTTP endpoints via `std/utils` `listFiles` —\n only interesting under the redirect architecture; not part of v1 either way.\n- **Registry/marketplace** of third-party integrations.\n- **Machine-credential pass-through** — letting bearer-token clients traverse a\n gated router without an OAuth session (surfaced by the val-issue-tracker\n migration). v1 accepts stacked gates: headless agents target a standalone or\n ungated mount. Revisit only if a real integration can't live with that.\n- **Fine-grained auth for routed integrations** _(leading candidate for the next\n effort)_ — a gated router applies one all-or-nothing login wall at the front\n door, so an integration's own finer auth model is flattened when routed.\n Example: the issue tracker standalone allows anonymous public reads (the\n `viewer` role), but behind a gated router the login wall blocks anonymous\n visitors entirely, so that public-read capability is lost. v1's permission\n model is deliberately all-or-nothing (router authenticates, integration\n authorizes from `ctx.user`); expressing per-integration or per-route\n visibility — a public-read integration, or public-read + gated-write routes,\n on an otherwise-gated router — is a richer model beyond the v1 destination.\n Surfaced while writing the ticket-7 docs; revisit as a fresh map, not a\n resumption of this one.\n",[],[233,484,485,330],"wayfinder-archive","integrations-v1","7567a65a-a81e-4567-8044-474fa6d354df",["D",1784043354774],[],[233,484,485,33],"28063973-da7c-4d1b-962c-5b99865ef94a","008-publishing-and-versioning.md","7454ac76-7cb8-11f1-9441-1607ee4eb77e","b1080eee-7d51-11f1-b73f-1607ee4eb77e",193,["D",1784043353502],"---\nid: 8\ntitle: Decide the publishing and versioning story\nlabels: [wayfinder:grilling]\nstatus: closed\nassignee: nbbaier\nblocked-by: []\n---\n\n## Question\n\nGraduated from the map's \"Publishing/versioning story\" fog once the contract was\nbuilt. What does \"released\" mean for the `integrations` contract?\n\n- **Canonical import URL**: `https://esm.town/v/nbbaier/integrations/mod.ts`\n presumably — confirm, and decide whether docs recommend pinning (esm.town\n `?v=` versions) or tracking latest.\n- **Breaking-change policy for third parties**: the `Integration` type and the\n router's behavioral guarantees (ctx shape, Location rewriting, reserved slugs,\n trailing-slash canonicalization) are the public API. What's the compatibility\n promise, and where is it stated? (The `/^_/` reservation already encodes one\n forever-promise.)\n- **Val privacy/discoverability**: does the val need to be public/unlisted for\n third-party imports to resolve?\n\nSmall ticket; the answers feed the README (ticket 7), which must show real\nimport URLs and state the compatibility stance.\n\nHITL: grill briefly (/grilling).\n\n## Resolution\n\nDecided 2026-07-10 by grilling. Four parts:\n\n- **Canonical import**: `https://esm.town/v/nbbaier/integrations/mod.ts`,\n recommended **unpinned** (platform culture; bugfixes flow), with esm.town's\n `?v=NN` version pinning documented as the stability escape hatch.\n- **Stability promise** (goes in a README \"Stability\" section, ticket 7): the\n public API is the exported types plus the router's behavioral guarantees (ctx\n shape / `c.env` alignment, Location rewriting, trailing-slash\n canonicalization, reserved slugs incl. the forever-`/^_/` namespace). Additive\n changes land on `mod.ts` anytime; **breaking changes never land on `mod.ts`**\n — they ship as a new entrypoint (e.g. `v2/mod.ts`) with old semantics\n preserved.\n- **Branch discipline, post-v1**: unpinned imports track the val's main tip, so\n **main is the release channel and merge = release**. Contract-touching work\n happens on a branch (`vt checkout -b`); merge only with `deno task check`\n green; don't leave `vt watch` running against main while editing\n `router.ts`/`mod.ts`. Non-code files (`wayfinder/`, `docs/`, `CONTEXT.md`) are\n exempt. Layering: `?v=` protects downstream from deliberate change, branch\n discipline from accidental breakage — unpinned-by- default is only honest with\n both.\n- **Privacy**: the val is public (verified via API) and must stay\n public/unlisted for esm.town imports to resolve.\n",[],[233,484,485,347,491],"67fd1dc4-01c0-4942-81c0-49dfc720ed95","007-third-party-author-docs.md","272f2194-7cb1-11f1-81a5-1607ee4eb77e",199,["D",1784043354408],5,"---\nid: 7\ntitle: Write the third-party author docs\nlabels: [wayfinder:task]\nstatus: closed\nassignee: nico\nblocked-by: [4, 5, 8]\n---\n\n## Question\n\nWrite the `integrations` README for the two audiences: users mounting a router\n(`createRouter` quickstart) and authors building integrations (the contract —\n`Integration` fields, the factory convention, prefix rules, what the router\nprovides vs what authors must do, `requiredEnv`, reserved slugs), with the\nhello-world integration as the worked example.\n\nBlocked on both migrations deliberately: the docs are the explainability test of\na contract that survived two real apps. If a rule needs a wall of caveats to\ndocument, that's feedback for the contract, not prose to polish — surface it\nrather than shipping it.\n\nSurface added by the ticket-4 migration, to be covered too:\n\n- Callable integrations (ADR 0003): `defineIntegration` returns a value that is\n both an `Integration` and a standalone HTTP handler — the dual-mode story for\n authors.\n- `createRouteHandler` as the public, OAuth-free test seam (mount your\n integration under a real router with an injected user).\n- Permission composition: the router authenticates, the integration authorizes\n from `ctx.user`; `ctx.user: null` means an ungated router (no login exists);\n integration-level token APIs sit behind the router's gate when it has one.\n\nAFK draft, HITL review pass.\n\n## Resolution\n\nShipped `README.md` for both audiences — _Mounting integrations_ (`createRouter`\nquickstart, the `auth` table, reserved paths) and _Writing an integration_ (the\n`Integration` contract, factory convention, handler + `IntegrationContext`,\n`requiredEnv`, reserved slugs), with `example/hello.ts` as the worked example.\nThe ticket-4 surface is all covered: callable dual-mode integrations (ADR 0003),\n`createRouteHandler` as the OAuth-free test seam, and permission composition\n(`ctx.user` null → ungated → don't redirect; token APIs stack behind the gate).\n\n**The explainability test passed** — every contract rule stated in a clean\nparagraph, no wall of caveats, so no contract changes fell out of writing the\ndocs. Two migrations having landed \"zero contract fights\" held up under prose.\n\nRefinements made during the HITL review pass:\n\n- **Naming convention unified** to the `helloWorld` style: `createIssueTracker`\n → `issueTracker`, `createBlobAdmin` → `blobAdmin`, renamed across all three\n repos (closed tickets left as the migration audit record). `*Options` types\n already matched the `HelloWorldOptions` style and were left.\n- **Example docs extracted**: `example/hello.ts` stripped of teaching comments;\n a line-by-line walkthrough moved to new `example/README.md`.\n- **val-issue-tracker README restructured** onto scoped-blob-viewer's\n standalone/routed shape (the house style for integration READMEs).\n\nAll three repos green (`deno task check`): integrations 17 tests,\nval-issue-tracker 23, scoped-blob-viewer 5. The two migrated vals were\nrepublished so the integrations val's remote imports resolve against the new\nnames.\n\nSurfaced but ruled out of scope: **fine-grained auth for routed integrations**\n(a gated router's all-or-nothing login wall flattens an integration's own finer\nauth model — e.g. the tracker's anonymous public reads vanish behind a gated\nrouter). Beyond v1's settled all-or-nothing gate; filed as the leading candidate\nfor the next effort.\n",[],[233,484,485,347,500],"8b0b405f-beb6-421c-8149-2dbc881fea3b","006-hello-world-example-integration.md","27198942-7cb1-11f1-bf6f-1607ee4eb77e",195,["D",1784043354417],"---\nid: 6\ntitle: Add the hello-world example integration\nlabels: [wayfinder:task]\nstatus: closed\nassignee: nbbaier\nblocked-by: [3]\n---\n\n## Question\n\nWrite the toy integration (~30 lines) that lives in the `integrations` repo,\ndoubles as the docs' worked example, and demonstrates the whole contract surface\nhonestly: `defineIntegration`, an `(options) => Integration` factory, reading\nthe router-provided user, one `requiredEnv` declaration, and prefix-correct\nlinks per the ticket-2 rules.\n\nMount it in this val's own `main.ts` so the live directory page always shows a\nworking example. Keep it genuinely trivial — its job is to be copied by\nthird-party authors, so every line should be contract, not app.\n\nAFK.\n\n## Resolution\n\nShipped 2026-07-11. [`hello.ts`](../../../../example/hello.ts) — ~40 lines,\ndeployed live.\n\n- **The whole contract surface, honestly:** an `(options) => Integration`\n factory (`helloWorld({ subject? })`, config in the closure), built with\n `defineIntegration`, reading `ctx?.user` via the dual-mode idiom (greets\n `@user` when routed+logged-in, the `subject` option standalone), one\n `requiredEnv: [\"HELLO_GREETING\"]` it genuinely reads at request time (falls\n back to \"Hello\"; unset = the directory's ⚠️ badge, deliberately demonstrating\n the feature), and relative-only links (`about`, `./`) per the ticket-2 prefix\n rules. `export default helloWorld()` at the bottom shows standalone mode on\n the same callable.\n- **Plain `(req, ctx)` handler, no Hono** — the toy stays dependency-free so\n every line is contract; the Hono idiom is val-issue-tracker's job to show.\n- **Registered in `main.ts`** after the issue tracker; pushed via `vt push` and\n verified live (401 login gate serving correctly; directory is owner-gated by\n design).\n- Tests: [`hello_test.ts`](../../../../example/hello_test.ts) — routed\n greeting + relative links, standalone fallback, both modes through the real\n dispatch. 17/17 green under `deno task check`.\n- Not exported from `mod.ts`: the example is a copyable file, not contract\n surface. Ticket 7's docs should link/inline it as the worked example.\n",[],[233,484,485,347,509],"5967bccd-9118-42d2-b83f-f06ed086b606","005-migrate-scoped-blob-viewer.md","2721832c-7cb1-11f1-adf5-1607ee4eb77e",194,["D",1784043354253],"---\nid: 5\ntitle: Migrate scoped-blob-viewer onto the contract\nlabels: [wayfinder:task]\nstatus: closed\nassignee: nbbaier\nblocked-by: [3]\n---\n\n## Question\n\nMigrate `~/Code/vt-projects/scoped-blob-viewer` to be a conforming integration\nwhile keeping standalone mounting working\n(`export default\ncreateBlobAdmin({...})` stays valid).\n\nThis is the deliberate stress test for prefix hygiene: `mod.ts` is one file of\nlink-heavy server-rendered HTML — absolute `href`s (`/view?key=...`,\n`/raw?key=...`), form `action`s (`/create`, `/delete`, `/rename`), and redirect\ntargets (`c.redirect(\"/?ok=...\")`) all break under a mount prefix unless the\nticket-2 rules handle them. If the migration fights the contract, that's signal,\nnot something to hack around — feed it back.\n\nAlso: it currently wraps `oauthMiddleware` itself with an `owner` allowlist;\nthat gate moves to the router, and its `LoginPage` setup-check for\n`OAUTH_STATE_ENCRYPTION_KEY` becomes a `requiredEnv` declaration.\n\nAFK.\n\n## Resolution\n\nMigrated 2026-07-11; both modes live and green, and the stress test passed —\n**the prefix-hygiene rules held without a single contract fight.**\n\n- `createBlobAdmin` now returns a callable Integration built with\n `defineIntegration` from the published contract\n (`https://esm.town/v/nbbaier/integrations/mod.ts`).\n `export default\n createBlobAdmin({ owner: \"nbbaier\" })` stays a valid\n standalone HTTP export, and the same value registers with `createRouter`.\n Standalone wraps this val's own `oauthMiddleware`; routed mode never does\n (`handler: (req, ctx) => ctx ? app.fetch(req, ctx) : standalone(req)`).\n- **Prefix hygiene (the point of the ticket):** every link/form action in the\n link-heavy HTML threads `base = ctx.prefix ?? \"\"` (via a `base` Hono var set\n in the auth middleware); redirects stay root-absolute (`/?ok=`, `/view?...`)\n and get router-rewritten per ADR 0002; `/auth/*` links stay origin-level in\n both modes. `blob.*` calls unchanged — scoped storage needs no prefix\n handling. **No contract additions were needed** — unlike the tracker\n migration, this one consumed the contract exactly as ticket 4 left it\n (callable integrations, `createRouteHandler` seam, Location rewriting).\n- **Permission composition:** `owner` stays this panel's own authorization\n layer, now checked against `ctx.user` when routed and the OAuth session when\n standalone. Unlike the tracker there is no read-only role — an admin panel is\n all-or-nothing — so a non-owner (including the `null` user of an ungated\n router, which can't satisfy an allowlist) gets 403, not a downgraded view.\n `auth: false` is fully open in both modes, as before.\n `OAUTH_STATE_ENCRYPTION_KEY` is declared as `requiredEnv` so a router's\n directory badges it when unset.\n- **File layout — reusable lesson for the docs ticket (7):** JSX in a `.ts` file\n runs on Val Town but can't be type-checked by plain `deno check`. So,\n mirroring the tracker, the JSX moved to `app.tsx` and `mod.ts` became a\n JSX-free re-export barrel — keeping the stable `.../scoped-blob-viewer/mod.ts`\n import path AND making the module locally checkable. Authors shipping JSX\n integrations should do the same.\n- Added a `deno task check` (fmt/lint/typecheck/test) the val never had, plus\n `mod_test.ts`: 5 tests via an injected in-memory `BlobStore` seam covering\n contract metadata, routed prefix-threading, the owner gate (owner/non-owner/\n null), root-absolute redirects, and end-to-end composition under the real\n router (`createRouteHandler`). All green in both repos.\n- Live: pushed both vals. `createBlobAdmin({})` registered in the integrations\n val's `main.ts`, mounted at `/blobs/` (401-gated as configured — the router\n serving 401 rather than 500 confirms it accepted the value as an Integration\n at construction). Standalone blob-viewer val serves its own data unchanged.\n- Same gotcha as ticket 4: the viewer imports the contract unpinned and Deno\n caches remote modules — after pushing scoped-blob-viewer, run\n `deno cache\n --reload=https://esm.town/v/nbbaier/scoped-blob-viewer/mod.ts`\n in the integrations val before its `deno task check`.\n",[],[233,484,485,347,517],"d4717d74-7335-4b52-89cf-2e8a45ba493c","004-migrate-val-issue-tracker.md","04d622d6-7d52-11f1-8ed3-1607ee4eb77e",198,["D",1784043354657],"---\nid: 4\ntitle: Migrate val-issue-tracker onto the contract\nlabels: [wayfinder:task]\nstatus: closed\nassignee: nbbaier\nblocked-by: [3]\n---\n\n## Question\n\nMigrate `~/Code/vt-projects/val-issue-tracker` to be a conforming integration\nwhile keeping standalone mounting working (charter constraint: the factory\nserves both modes — `export default createIssueTracker({...})` stays valid).\n\nKnown hard parts:\n\n- It self-manages OAuth **and** a role model (maintainer/contributor/viewer)\n **and** a bearer-token JSON API under `/api`. Router-owned auth replaces the\n OAuth gate; how the router-provided user feeds the role model, and what\n happens to bearer-token writes behind the router, is the map's\n \"permission-model composition\" fog — resolving this ticket should graduate or\n answer it.\n- Prefix hygiene per the ticket-2 rules if architecture (A) won: absolute\n links/form actions throughout `app.tsx` / `components.tsx` / `ui.tsx`, and the\n `/source` redirect.\n- Its test suite (`deno task check`) must stay green in both modes.\n\nAFK mostly; flag anything that contradicts the contract rather than working\naround it.\n\n## Resolution\n\nMigrated 2026-07-11; both modes live and green.\n\n- `createIssueTracker` now returns a callable Integration built with\n `defineIntegration` from the published contract\n (`https://esm.town/v/nbbaier/integrations/mod.ts`):\n `export default\n createIssueTracker({})` stays a valid standalone HTTP\n export, and the same value registers with `createRouter`. Standalone wraps the\n tracker's own `oauthMiddleware`; routed mode never does.\n- **Permission composition (answers the map's fog):** the router owns\n authentication; the tracker's maintainer/contributor/viewer model stays its\n own authorization layer, fed by `ctx.user` — maintainer if in the\n `maintainers` set, else `defaultRole`; `ctx.user: null` (ungated router) is a\n read-only viewer with login UI hidden, since no login flow exists there.\n Tracker `auth: false` still means \"everyone is maintainer\" in both modes.\n Routed mode never redirects to `/auth/login` (Location rewriting would turn it\n into a 404 under the prefix) — viewers get a 403 page instead.\n- **Bearer-token `/api`:** unchanged at the integration layer; gates stack.\n Behind a gated router the JSON API additionally requires the router's OAuth\n session, so headless agents target a standalone or ungated mount.\n Machine-credential pass-through ruled out of scope for v1 (map updated).\n- **Prefix hygiene:** every HTML link/form action threads\n `base = ctx.prefix ?? \"\"` (Layout + all pages); redirects stay root-absolute\n and get router-rewritten per ADR 0002; `/auth/*` links stay origin-level\n (correct in both modes); Referer-based redirects pass through as full URLs.\n- **Contract feedback — implemented as additive changes, not workarounds:** (1)\n `defineIntegration` returns a callable Integration\n ([ADR 0003](../../../adr/0003-callable-integrations.md); new\n `CallableIntegration` / `IntegrationHandler` types) — without it the two\n mounting styles needed different factory return values; (2)\n `createRouteHandler` promoted to `mod.ts` as the public OAuth-free test seam —\n the tracker's routed tests mount under the real router with an injected user.\n- Tests: val-issue-tracker 23 green (2 new: routed roles + prefixed links;\n end-to-end under the real router), integrations 15 green — `deno task\n check`\n in both repos. Live: tracker mounted at the integrations val (`/issues/`,\n 401-gated as configured); the standalone tracker val serves its existing data\n unchanged.\n- Gotcha for later tickets: the tracker imports the contract unpinned, and Deno\n caches remote modules — after pushing integrations, run\n `deno cache\n --reload=https://esm.town/v/nbbaier/integrations/mod.ts` in\n dependents before `deno task check`.\n",[],[233,484,485,347,525],"47b9947e-f00a-4565-a321-00461ccd2e5c","003-build-integrations-v1.md","27129ee8-7cb1-11f1-9ee9-1607ee4eb77e",191,["D",1784043353864],"---\nid: 3\ntitle: Build integrations v1 — contract exports, router, directory page\nlabels: [wayfinder:task]\nstatus: closed\nassignee: nbbaier\nblocked-by: [2]\n---\n\n## Question\n\nImplement the pinned contract in the `integrations` val\n(`~/Code/vt-projects/integrations`, currently an empty `main.ts`):\n\n- `mod.ts` exporting `Integration`, `defineIntegration`, `createRouter`.\n- The router per the ticket-1 architecture and ticket-2 API: dispatch,\n router-owned OAuth gate, user passed to integrations.\n- The directory page at `/`: name, description, link per registered integration;\n ⚠️ badge when a `requiredEnv` var is unset (`Deno.env.get(...)`).\n- Slug/reserved-path validation with clear construction-time errors.\n- `main.ts` as this val's own consumer (mirroring how `val-issue-tracker`'s\n `main.ts` consumes its `mod.ts`) — it can mount the hello-world integration\n once ticket 6 exists.\n- Tests where the repo's siblings set precedent (`deno task check` style: biome\n fmt, lint, typecheck, test).\n\nAFK: buildable solo once the contract is pinned; resolution records what shipped\nand any contract deviations discovered while building (feed those back into the\nmap).\n\n## Resolution\n\nBuilt and deployed 2026-07-10. What shipped:\n\n- `router.ts` — the implementation: `Integration` / `IntegrationContext` /\n `RouterOptions` types, `defineIntegration` (charset + reserved validation),\n `createRouteHandler(options, getUser)` (the OAuth-free core, user lookup\n injected — this is the test seam), and `createRouter` (wires\n `getOAuthUserData` + wraps with `oauthMiddleware` unless `auth: false`).\n- `mod.ts` — public re-exports only; third parties import this.\n- `router_test.ts` — 14 tests, all green via `deno task check` (fmt, lint,\n typecheck, test — tasks added to `deno.json` mirroring val-issue-tracker):\n validation throws, prefix strip + ctx, trailing-slash canonicalization\n preserving query, buffered POST bodies, 404/directory, requiredEnv badge,\n Location rewriting incl. protocol-relative (`//host`) and absolute\n pass-through, and the full auth matrix (anon GET→401 login page, anon\n non-GET→302 home, allowlist 403/200, `auth: false`→`ctx.user` null).\n- `main.ts` (HTTP) — this val's consumer:\n `createRouter({ title:\n \"Integrations\", auth: { users: \"nbbaier\" }, integrations: [] })`.\n Live at https://nbbaier--477921dc7cb811f194e81607ee4eb77e.web.val.run —\n verified serving the login page (401, allowlist named, no env warning). The\n hello-world integration (ticket 6) registers here.\n- Housekeeping: fixed the template's Deno-2-deprecated `lint.files` config.\n\nContract deviations discovered while building: **none** — the pinned API\nimplemented cleanly. One addition the contract didn't specify: anonymous non-GET\nrequests bounce 302 home rather than rendering the login page (precedent from\nscoped-blob-viewer; a stale form POST shouldn't render HTML into a POST\nresponse).\n",[],[233,484,485,347,533],"23a5d0cf-f5b6-4eb2-9812-9d4a11f8b301","002-pin-the-v1-contract.md","274f5dce-7cb1-11f1-ab0f-1607ee4eb77e",192,["D",1784043354039],"---\nid: 2\ntitle: Pin the v1 contract — Integration type, defineIntegration, createRouter API\nlabels: [wayfinder:grilling]\nstatus: closed\nassignee: nbbaier\nblocked-by: [1]\n---\n\n## Question\n\nFinalize the exact public API of `integrations/mod.ts`. The charter settled the\nshape; this ticket pins the details the architecture decision unlocks.\n\nSettled by the charter (do not relitigate):\n\n```ts\ninterface Integration {\n name: string; // \"Issue Tracker\"\n slug: string; // \"issues\" → mount prefix\n description?: string;\n requiredEnv?: string[]; // e.g. [\"OAUTH_STATE_ENCRYPTION_KEY\"] → ⚠️ on the directory page\n handler: (req: Request) => Response | Promise;\n}\n```\n\nAuthors export `(options) => Integration` factories built with\n`defineIntegration`; users write\n`createRouter({ integrations: [issueTracker({...})], auth: {...} })`.\n\nTo pin here:\n\n- **Handler signature**: how does the router pass the authenticated user (and\n anything else, e.g. the mount prefix) to the integration? Extra context arg\n (`(req, ctx)`), request header, or a richer handler type? Depends on the\n ticket-1 architecture.\n- **Prefix rules**: if (A) won, the exact contract for links/forms/assets under\n a mount prefix — what the router guarantees (e.g. strips the prefix? passes it\n in ctx?) and what authors must do. If this takes three paragraphs of caveats,\n that is a design smell to feed back.\n- **Slug validation**: charset, uniqueness, reserved names (`auth`, plus the\n root). When does `createRouter` reject — construction time, with what error?\n- **`createRouter` options**: `auth` shape (`owner`/allowed users, off switch),\n `title` for the directory page, anything else v1 actually needs. Keep minimal.\n- **What `defineIntegration` actually does** beyond identity/typing —\n validation? defaults?\n\nHITL: grill through these one at a time (/grilling, /domain-modeling).\n\n## Resolution\n\nDecided 2026-07-10 by grilling. The v1 public API of `integrations/mod.ts`:\n\n```ts\ninterface IntegrationContext {\n user: string | null; // Val Town username via router-owned OAuth\n prefix: string; // mount prefix, e.g. \"/issues\"\n}\n\ninterface Integration {\n name: string;\n slug: string;\n description?: string;\n requiredEnv?: string[];\n handler: (\n req: Request,\n ctx?: IntegrationContext,\n ) => Response | Promise;\n}\n\ninterface RouterOptions {\n integrations: Integration[]; // order = directory order\n auth?: { users?: string | string[] } | false; // default ON, any logged-in user\n title?: string; // directory header, default \"Integrations\"\n}\n```\n\n- **Context as second argument, nothing in headers.** `handler(req, ctx)`.\n Aligns with Hono: an integration exporting `app.fetch` reads `c.env.user` /\n `c.env.prefix` directly (`Hono<{ Bindings: IntegrationContext }>` for typing)\n — same object reference, no adapter. Standalone mode passes no ctx, so\n `c.env?.user` is the dual-mode idiom. No identity headers = no spoofing\n surface.\n- **Response rewriting: root-absolute `Location` headers get the prefix\n prepended** by the router\n ([ADR 0002](../../../adr/0002-location-header-rewriting.md)). HTML is never\n rewritten — authors use relative URLs or `ctx.prefix`. Result:\n `c.redirect(\"/?ok=...\")` and the whole redirect-after-POST idiom work\n unmodified in BOTH modes with zero branching.\n- **Slugs:** `^[a-z0-9-]+$`, unique per router, checked against\n `RESERVED_SLUGS: (string | RegExp)[] = [\"auth\", /^_/]` — `auth` because\n std/oauth hardcodes `/auth/*`; `/^_/` publishes the underscore namespace as\n router-owned forever (unspellable under the charset today; guards a future\n loosening). Violations **throw at construction** with the offending slug\n named, so bad config fails the deploy, never serves silently broken routes.\n- **Auth is a gate, not a role system.** `auth.users` is an allowlist of who may\n enter; what they may DO stays integration-domain logic fed by `ctx.user`\n (issue tracker keeps maintainer/contributor — that seam belongs to its\n migration ticket). `auth: false` opts out; `ctx.user` is then null.\n- **Nothing else in v1**: no per-integration auth overrides, no hooks, no custom\n directory renderer — v2-shaped until a migration proves a need.\n",[],[233,484,485,347,541],"ab88431c-09c9-4286-a423-ac19b73d7146","001-prototype-dispatch-architecture.md","04f1644c-7d52-11f1-acde-1607ee4eb77e",197,["D",1784043354558],"---\nid: 1\ntitle: Prototype the dispatch architecture — in-process mount (A) vs sibling-endpoint redirect (B′)\nlabels: [wayfinder:prototype]\nstatus: closed\nassignee: nbbaier\nblocked-by: []\n---\n\n## Question\n\nWhich dispatch architecture does `createRouter` use? Build cheap stubs of both\non Val Town and decide from the evidence. This is the load-bearing mechanical\nunknown; nearly every other ticket blocks on it.\n\n**(A) In-process mount.** One HTTP endpoint; the router holds `Integration`\nhandlers and dispatches by path prefix (`/issues/*` → issue tracker's fetch\nhandler with a rewritten path). One origin: a true single URL, one OAuth\nsession. Costs to verify:\n\n- **Prefix hygiene**: both existing integrations emit absolute paths\n (`/view?key=...`, form `action=\"/delete\"`, `/auth/login`) that break under a\n `/blobs` prefix. How painful is making a real app prefix-correct — does Hono\n `basePath`/route-mounting get most of the way, or is it a caveat-laden\n contract on every author?\n- **OAuth composition**: can the router wrap `oauthMiddleware` once at the top,\n mount `/auth/*` once, and pass the authenticated user down to integrations\n (the \"router owns auth\" design intent)? Verify `getOAuthUserData` works from\n inside a prefix-mounted child handler.\n\n**(B′) Sibling endpoint files + redirecting directory.** Each integration is its\nown HTTP file in the host val (own URL, but scoped SQLite/blob is val-scoped, so\nstorage is still shared — confirmed platform fact). The router endpoint is a\nlauncher that 302s `/issues` to the sibling's URL. Existing integrations work\nunmodified today. Costs to verify:\n\n- Separate origins → separate cookie jars → per-integration OAuth logins. How\n bad does that feel in practice?\n- \"Mounting\" = creating a file per integration + telling the router about it;\n the astro-style `createRouter({ integrations: [...] })` API can't hold the\n handlers, only metadata/URLs.\n\n**Thumb on the scale**: the charter's astro/vite composition model\n(`createRouter` receives integration instances) presupposes (A). (B′) wins only\nif prefix hygiene or OAuth composition turns out genuinely nasty.\n\nPlatform notes: `Response.redirect` is broken on Val Town — use Hono\n`c.redirect` or a manual 302. Each HTTP file's URL comes from `links.endpoint`\nvia `list_files` / `create_file`; never construct it by hand.\n\nHITL: build the stubs, then react to them together before recording the\ndecision.\n\nThe decision meets all three ADR criteria (hard to reverse, surprising without\ncontext, real trade-off): record it as the repo's first ADR at\n`docs/adr/0001-dispatch-architecture.md` in addition to the resolution comment.\n\n## Resolution\n\n**Architecture (A) — in-process prefix mount.** Decided 2026-07-10 after both\nstubs ran live; recorded as\n[ADR 0001](../../../adr/0001-dispatch-architecture.md). The prototype (`proto/`,\nsince deleted) established:\n\n- **Dispatch works.** The router matches `/slug` prefixes, rewrites the URL\n (child sees `/`), and passes `x-mount-prefix`. POSTs survive with a buffered\n body (`await req.blob()` — streams need re-wrapping care).\n- **Prefix hygiene is a one-line rule, not a wall of caveats.** With the router\n canonicalizing `/slug` → `/slug/` (302, reverse-proxy convention), plain\n relative links AND relative form actions resolve correctly. Only root-absolute\n paths (`/two`, `action=\"/add\"`) break. Contract rule: use relative URLs or the\n provided prefix; never root-absolute.\n- **Router-owned auth verified.** `oauthMiddleware` wrapped once at the router;\n after one login, children saw the user both via a router-set header\n (`x-router-user`) and by calling `getOAuthUserData` directly on the rewritten\n request — cookies flow through. Integrations need no OAuth code.\n- **Scoped SQLite is shared across all mount styles** (val-scoped, verified in\n both directions), so (B′) held no storage advantage.\n- **(B′) rejected**: split origins mean per-integration logins and a\n launcher-only \"single URL\", and the astro-style\n `createRouter({ integrations: [...] })` API can't exist — mounting would mean\n creating a file per integration instead of just importing a factory (a real UX\n loss).\n",[],[233,484,485,347,549],"72785ed1-e6af-4eb2-a126-35d7610911ca",113,["D",1783792524099],[258,259,260,261,262,263,264,265],[233,484,485,347],"4943a8e8-7e18-4b5e-9cf5-01f32b53ffb3","b0de7188-7d51-11f1-b8b2-1607ee4eb77e",112,["D",1783792523949],[257,266,267],[233,484,485],"159d8575-7826-4301-a89a-db8a19f128a9",111,["D",1783792523821],[256],[233,484],"35a2ffe0-d0ae-4420-8534-c2df9f07b369","building-host-scoped-integrations.md","7b67cef6-7d69-11f1-821f-1607ee4eb77e","2428d405-c9ba-409c-80a1-535778f75f37",201,["D",1784043354935],"# Building host-scoped integrations: mounting, self-identification, SPAs, versioning\n\nField notes from a build session: porting a client-side React SPA onto the\nintegrations contract and probing how a mounted integration sees its host.\n\nEmpirical claims were verified against a live toy (`toy-spa-integration`)\nmounted three ways. Items tagged _(from the contract)_ were reasoned from\n`router.ts`, not exercised live.\n\n---\n\n## 1. The ways an integration can be mounted\n\nAn integration is just a `(req, ctx?) => Response` handler (a callable\n`Integration`). Two things vary independently: the **mount mechanism** — which\ndecides whether `ctx` is passed and whether prefix/redirect handling applies —\nand the **host val**, which is always whichever val Val Town executed.\n\n| Mechanism | Host val (`= VALTOWN_ENTRYPOINT`) | `ctx` | Path handler sees | Router services |\n| --------------------------------------------------------------------------------------- | --------------------------------- | -------------------- | -------------------- | --------------------------------------------------------------------- |\n| Standalone, own val — `export default factory()` in the integration's own val | the integration's own val | absent | root | none |\n| Standalone, wrapper val — another val does `import {factory}; export default factory()` | the wrapper val | absent | root | none |\n| Routed — `createRouter({ integrations:[factory()] })` | the router val | `{ user, prefix }` | prefix-stripped | prefix canonicalize, Location rewrite, directory page, OAuth gate |\n| Routed test seam — `createRouteHandler(opts, getUser)` | the val running it | `{ user, prefix }` | prefix-stripped | routing, no OAuth _(from the contract)_ |\n| Manual — host calls the handler itself, no `createRouter` | that host val | whatever host passes | whatever host strips | none — you reimplement strip + Location rewrite _(from the contract)_ |\n\nNotes:\n\n- The two standalone rows are the **same mechanism**\n (`export default\n factory()`, no `ctx`); only which val holds the export\n differs, and that is what flips the host.\n- Routed: `ctx.prefix` is `/slug` (no trailing slash), and the handler receives\n the path already stripped of it. With Hono, `ctx` arrives as `c.env`.\n- `createRouter` returns a bare handler, not an `Integration` (no\n `slug`/`name`), so routers don't nest into another router's `integrations[]`\n without re-wrapping in `defineIntegration`.\n\nTwo orthogonal axes for classifying an integration:\n\n- **Interface** — full web UI / API-only / both. (The issue tracker is already\n both.)\n- **Subject** — self-owned domain (issues, subscriptions) vs\n host-reflective/introspective (docs, version history, env). Host-reflective\n can wear any interface.\n\n---\n\n## 2. Host self-identification\n\nVal Town injects `VALTOWN_ENTRYPOINT` — the `import.meta.url` of the file it\nexecuted — into the process env. The `std/utils` file helpers default to it. So\nfrom inside a mounted integration:\n\n- `parseVal()` → `{ username, name, version, branch }` of the **host** (the\n executed val).\n- `listFiles()` → the host's full file tree. This is the multi-file answer:\n enumerate, then `readFile` each source.\n- `readFile(path)` → the host's source for one file. Use `readFile`, not\n `readFileTranspiled`, to keep JSDoc and type annotations.\n- `getValId()` → the host's UUID (rename-stable cache key).\n- `parseVal(import.meta.url)` → the integration's **own** val (overrides the\n default).\n\n**Rule:** host = the executed val; self = `import.meta.url`, always. Everything\nhost-scoped (blob, SQLite, `parseVal`, `listFiles`) keys off the host by the\nsame execution-context mechanism that scoped storage already uses.\n\nVerified with a `whoami` probe returning `{ host, self }`:\n\n- Standalone, own val → `host == self` (the toy).\n- Standalone, wrapper val → `host` = wrapper, `self` = toy.\n- Routed → `host` = router, `self` = toy; `hostFileCount` reflected the router's\n files, not the toy's.\n\nImplication for a host-reflective integration (e.g. a docs generator): default\nsubject = `parseVal()` (the host); keep any `?val=` query param as an _override_\nfor a \"document any val\" mode. Scoped blob is already per-host, so a\ngenerated-content cache auto-isolates — key entries by `parseVal().version` to\ninvalidate on redeploy. Reads use the host's scoped token, so private host\nsource is readable; expose rendered output deliberately.\n\n---\n\n## 3. A client-side SPA as an integration frontend\n\nThe router strips the prefix (the handler runs as if at root) and rewrites\n**Location headers only**, never bodies. So a SPA survives mounting when split\ninto three surfaces by who serves them:\n\n1. **HTML shell** — served by the handler at `/`. Every browser-resolved URL in\n it is **relative** (or an absolute esm.town URL), never root-absolute.\n2. **Client bundle** — referenced by an **absolute esm.town URL**\n (`https://esm.town/v/you/val/frontend/index.tsx`). Prefix-immune; the browser\n fetches it straight from esm.town, so the host only proxies shell + API.\n Requires the integration val to be public/unlisted — a private val's esm.town\n URL won't serve to the browser. Alternative: serve it through the handler\n with `staticHTTPServer(import.meta.url, app.fetch)`, passing\n `import.meta.url` explicitly (its default `VALTOWN_ENTRYPOINT` would\n otherwise serve the **host's** files as your frontend).\n3. **Host-data API** (`/api/*`) — the only genuinely host-scoped surface;\n reached by **relative** `fetch(\"api/...\")`.\n\nTwo rules make it work:\n\n- Everything the browser resolves is relative. The router canonicalizes `/slug`\n → `/slug/` (trailing slash) so relative URLs resolve inside the mount.\n- The client derives its API base once at boot:\n `const API_BASE = new URL(\".\", location.href)`, then\n `fetch(new URL(\"api/state\", API_BASE))`. No server injection; works at `/`\n standalone and `/slug/` mounted.\n\nUse **hash-based** client routing so `location.pathname` stays at the mount root\nand the derived base stays valid (path routing would need a shell catch-all plus\na base-aware router). The React component tree itself doesn't change to mount —\nonly these edges do.\n\n---\n\n## 4. Versioning: cross-val imports are lockfile-pinned\n\nWhen a host imports an integration across the esm.town boundary\n(`import { x } from \"https://esm.town/v/you/int/mod.ts\"`), the resolved version\nis written into the **host val's lockfile** and is sticky by design.\n\n- An unpinned specifier is **not** live-latest and **not** refreshed by a\n redeploy — the redeploy honors the existing lock entry. (A single edit-fused\n request can transiently resolve latest in a cold isolate, which is misleading;\n steady-state traffic keeps the locked version.)\n- Forcing an update requires **re-resolution**: reset the lockfile, or cycle the\n specifier (pin → unpin). After that, unpinned re-resolves to current and locks\n again.\n- Pin `@ver-branch` (e.g. `@8-main`) for a deterministic version you control —\n it's an immutable URL and never moves.\n\nVerified: added a route to the toy, then hit it through a wrapper that imported\nunpinned. The new route 404'd (the wrapper was locked to the pre-change version)\nwhile unchanged routes still worked. Pinning the wrapper to the old version\nreproduced the 404 deterministically; resetting the lock and unpinning brought\nthe new route back.\n\nGuidance for shipping integrations: tell consumers \"unpinned is a locked\nsnapshot you update by re-resolving; pin `@ver` for stability.\" This is also why\nthe contract ships breaking changes as a **new entrypoint** rather than mutating\n`mod.ts` — existing hosts stay locked to whatever they resolved.\n",[],[233,581,573],"notes","652c10c5-892e-45b9-8646-fc241d0be5f7",135,["D",1783802742029],[254],[233,581],"79e95003-6a1e-4723-8bd9-149183490a34","0003-callable-integrations.md","38b33f42-7d40-11f1-9235-1607ee4eb77e","c2500b00-7cb3-11f1-accf-1607ee4eb77e",190,["D",1784043353617],"# defineIntegration returns a callable Integration\n\n`defineIntegration` returns the `Integration` object made directly callable as\nan HTTP handler (`CallableIntegration = Integration & IntegrationHandler`;\ncalling it with no ctx is standalone mode). The charter requires every\nintegration factory to serve both modes — `export default myFactory({...})` as a\nstandalone HTTP val AND `createRouter({ integrations: [myFactory({...})] })` —\nand an `Integration` is a plain object, not a function, so without this the two\nmounting styles would need different factory return values (`.handler` in one\nplace, the object in the other). Making the contract helper produce the hybrid\ngives every author dual-mode support for free; the val-issue-tracker migration\nproved the need.\n\n## Consequences\n\n- `export default myFactory({...})` is a valid HTTP val export; the platform\n calls it with no ctx, which is exactly the standalone signal the contract\n already defined (`ctx` absent).\n- Integration fields are attached with `Object.defineProperty` because a\n function's own `name` is read-only-but-configurable and `Integration.name`\n must shadow it.\n- The router still calls `.handler(req, ctx)`; plain object literals that merely\n satisfy the `Integration` type keep working when registered, they just aren't\n standalone-mountable.\n",[],[233,596,588],"adr","833d0d53-68c3-41a6-955f-a3bdb86856f2","0002-location-header-rewriting.md","cf4fd38c-7cb6-11f1-b356-1607ee4eb77e",188,["D",1784043353264],"# The router rewrites root-absolute Location headers, and only those\n\nWhen a mounted integration responds with a `Location` header starting with `/`,\nthe router prepends the mount prefix (`Location: /?ok=x` → `/issues/?ok=x`);\nHTML bodies are never rewritten. We chose this asymmetry — over rewriting\nnothing (strict authoring rule) or rewriting everything (full reverse-proxy) —\nbecause HTML links have the document base URL as a safety net, so relative links\nare natural to write, while redirects are generated far from any notion of\n\"where am I mounted\"; covering `Location` makes the ubiquitous\nredirect-after-POST idiom (`c.redirect(\"/?ok=...\")`) work unmodified in both\nrouted and standalone modes with zero branching, exactly like nginx's\n`proxy_redirect`.\n\n## Consequences\n\n- An integration cannot reach the router root or a sibling integration via a\n bare `/...` redirect; it uses `ctx.prefix` or a full absolute URL. Rare and\n deliberate by design.\n- Body rewriting stays the author's responsibility: relative URLs, or\n `ctx.prefix` when an absolute path is unavoidable.\n",[],[233,596,598],"aff11007-0c7c-43aa-9d2a-2b44ddb4d951","0001-dispatch-architecture.md","c2a2a518-7cb3-11f1-af02-1607ee4eb77e",187,["D",1784043353120],"# In-process prefix dispatch, not sibling-endpoint redirects\n\nThe router (`createRouter`) mounts integrations **in-process**: one HTTP\nendpoint holds every registered integration's fetch handler and dispatches by\npath prefix (`/issues/*` → issue tracker), rewriting the request URL and passing\nmount context along. We prototyped both this and the alternative — each\nintegration as its own sibling HTTP file in the host val, with a directory\nendpoint 302-ing out — and chose in-process (2026-07-10, prototype since\ndeleted; evidence recorded on wayfinder ticket 1).\n\n## Considered Options\n\n**Sibling endpoints + redirecting directory** was rejected. Its one real\nadvantage — existing integrations work unmodified — evaporated when the\nprototype showed the in-process authoring burden collapses to a one-line rule:\nwith the router canonicalizing `/slug` → `/slug/`, plain relative URLs just\nwork, and only root-absolute paths break. What it could never offer: each\nsibling file is its own origin, so users log in separately per integration, the\nsingle URL is only a launcher, and `createRouter({ integrations: [...] })` can't\nexist — mounting means creating a file per integration instead of importing a\nfactory.\n\n## Consequences\n\n- One origin: one OAuth login for every integration. Verified: the router wraps\n `oauthMiddleware` once, and `getOAuthUserData` works both in the router and\n inside a prefix-mounted child (session cookies survive the request rewrite).\n- Integration authors must use relative URLs (or the provided mount prefix) and\n never root-absolute paths; the router guarantees trailing-slash\n canonicalization of the mount root.\n- Scoped SQLite/blob need no special handling — storage is val-scoped, so\n in-process children naturally share the host val's data (verified; true of the\n rejected option too).\n- Request bodies are re-wrapped during URL rewriting; the router buffers them\n rather than streaming.\n",[],[233,596,606],"b8d5d5fd-e95b-4cdc-831d-08861e689a73",32,["D",1783724692595],[250,251,252],[233,596],["D",1783724692393],[249,253,255],[233],["D",1783715038579],["D",1789525245864],{"_98":97,"_105":101},{"_98":97,"_99":-5,"_100":101,"_18":55,"_102":103,"_104":25},{"_13":87,"_32":88,"_43":42,"_89":44,"_90":-5,"_91":-5,"_92":-5,"_93":-5,"_94":-5,"_95":45,"_96":97},"ctx",{"_80":-5,"_125":659,"_660":661,"_662":663,"_664":25,"_665":25,"_666":25,"_667":123,"_668":-5,"_669":-7,"_670":-7,"_671":61,"_672":25,"_673":25,"_674":-5,"_675":25,"_676":25,"_677":25,"_678":-5},"ENV",{"_630":631,"_632":633,"_634":88,"_635":636,"_637":638,"_639":640,"_641":642,"_643":644,"_645":646,"_647":648,"_649":650,"_651":652,"_653":654,"_655":656,"_657":658},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","9e167d8120a57de5d747867e0b686da51bcc19a4","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 · v206