Public: anyone can read this; the crew can change it.
/api/v1/here says who a start token is, and says a token it does not know is not recognised #14425
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/14420-api-v1-here-says-who-a-start-token-is-an → main 4 commits fork 1 thread · 1 unresolved
6 files
changed +171
−5
src/actions/here.ts +54
| @@ -28,8 +28,10 @@ import { | ||
| 28 | 28 | canRead, |
| 29 | 29 | canWrite, |
| 30 | 30 | getRepo, |
| 31 | listReposOwnedBy, | |
| 31 | 32 | type Repo, |
| 32 | 33 | } from "../core/repos.ts"; |
| 34 | import { startOfAccount } from "../core/starts.ts"; | |
| 33 | 35 | import { getUserByName, hiddenFrom } from "../core/users.ts"; |
| 34 | 36 | import { cappedQuery } from "../core/query_limit.ts"; |
| 35 | 37 | import { SYSTEM_NAMES } from "../core/reserved.ts"; |
| @@ -89,6 +91,8 @@ export interface Manifest { | ||
| 89 | 91 | }; |
| 90 | 92 | readonly you: |
| 91 | 93 | | { readonly as: "anonymous" } |
| 94 | /** A start token (`POST /api/v1/start`): its account and the repository it made. */ | |
| 95 | | { readonly as: "start"; readonly user: string; readonly repo?: string } | |
| 92 | 96 | | { |
| 93 | 97 | readonly as: "reader" | "writer" | "owner" | "agent"; |
| 94 | 98 | readonly name: string; |
| @@ -146,6 +150,56 @@ export function manifestFor( | ||
| 146 | 150 | scope: TokenScope | undefined, |
| 147 | 151 | origin: string, |
| 148 | 152 | path: string, |
| 153 | ): Result<Manifest, "not_found"> { | |
| 154 | const found = pageManifest(app, viewer, scope, origin, path); | |
| 155 | if (!found.ok || viewer === undefined) return found; | |
| 156 | // The marker is the row `actions/start.ts` wrote for the account, never a | |
| 157 | // token's name, which its holder chooses. | |
| 158 | const made = startOfAccount(app.db, viewer.id); | |
| 159 | if (made === undefined || made.claimedAt !== null) return found; | |
| 160 | return ok(asStart(app, viewer, found.value)); | |
| 161 | } | |
| 162 | ||
| 163 | /** The words of a credential that matches nothing (401 `invalid_token`). */ | |
| 164 | export const INVALID_TOKEN_WORDS = "that token or password matches no account here"; | |
| 165 | export const INVALID_TOKEN_HINT = | |
| 166 | "send no credential to look around; to build, POST /api/v1/start for a new token, or sign in"; | |
| 167 | ||
| 168 | /** | |
| 169 | * A start token's manifest: who it is, and only what it may do: push to and | |
| 170 | * read its repository, and report. Not what its account is refused (an issue, | |
| 171 | * a pull, a token). | |
| 172 | */ | |
| 173 | function asStart(app: App, viewer: User, m: Manifest): Manifest { | |
| 174 | const repo = listReposOwnedBy(app.db, viewer.id)[0]; | |
| 175 | const name = repo === undefined ? undefined : `${repo.ownerName}/${repo.name}`; | |
| 176 | const r = `/api/v1/repos/${name}`; | |
| 177 | const own: Action[] = | |
| 178 | name === undefined | |
| 179 | ? [] | |
| 180 | : [ | |
| 181 | { | |
| 182 | do: "push to your repository with git (basic auth: your username and this token)", | |
| 183 | noMcp: "git is not an MCP tool", | |
| 184 | account: false, | |
| 185 | }, | |
| 186 | { do: "read your repository", http: `GET ${r}`, account: false }, | |
| 187 | ]; | |
| 188 | const report = m.can.filter((a) => a.mcp === "report"); | |
| 189 | const read = m.can.filter((a) => a.mcp === "explore" || a.mcp === "search"); | |
| 190 | return { | |
| 191 | ...m, | |
| 192 | you: { as: "start", user: viewer.username, ...(name === undefined ? {} : { repo: name }) }, | |
| 193 | can: [...own, ...read, ...report], | |
| 194 | }; | |
| 195 | } | |
| 196 | ||
| 197 | function pageManifest( | |
| 198 | app: App, | |
| 199 | viewer: User | undefined, | |
| 200 | scope: TokenScope | undefined, | |
| 201 | origin: string, | |
| 202 | path: string, | |
| 149 | 203 | ): Result<Manifest, "not_found"> { |
| 150 | 204 | const common = { |
| 151 | 205 | mcp: mcpPointers(origin), |
src/contract/openapi/routes/getApiV1Here.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import type { Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/here", summary: "The manifest of what you can do at `path` (default /), given who you are: { here, you, can, mcp, docs }; never cached", auth: false, role: "anonymous", query: { path: "string" }, refusals: { not_found: "404: the path names no page you can read" } }; | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/here", summary: "The manifest of what you can do at `path` (default /), given who you are (`you` is `{as: start, user, repo}` for a start token, whose `can` is push, read, report): { here, you, can, mcp, docs }; never cached", auth: false, role: "anonymous", query: { path: "string" }, refusals: { invalid_token: "401, a bearer or basic credential was sent and matches no account or token: start again (POST /api/v1/start) or sign in; send none to be anonymous", not_found: "404: the path names no page you can read" } }; |
src/http/api.ts +3 −1
| @@ -439,7 +439,7 @@ import { featureRoutes } from "./api/features.ts"; | ||
| 439 | 439 | import { upstreamRoutes } from "./api/upstream.ts"; |
| 440 | 440 | import type { Router } from "./router.ts"; |
| 441 | 441 | import { clientAddress } from "./peer.ts"; |
| 442 | import { manifestFor } from "../actions/here.ts"; | |
| 442 | import { INVALID_TOKEN_HINT, INVALID_TOKEN_WORDS, manifestFor } from "../actions/here.ts"; | |
| 443 | 443 | import { egressRowsFor, egressTotalsFor } from "../spawn/process_counters.ts"; |
| 444 | 444 | import { egressMetrics } from "../apps/egress_metrics.ts"; |
| 445 | 445 | import { forgeMetrics } from "../metrics/forge.ts"; |
| @@ -4173,6 +4173,8 @@ export function apiRoutes(router: Router<Handler>): void { | ||
| 4173 | 4173 | // manifest every page links to. It differs by caller, so it is never cached. |
| 4174 | 4174 | router.add("GET", "/api/v1/here", (ctx) => { |
| 4175 | 4175 | notePhase(ctx.request, "session", takeSessionTime(ctx.request)); |
| 4176 | // A credential that matches nothing is not a signed-out visitor. | |
| 4177 | if (ctx.auth.refused === true) return apiError("invalid_token", 401, INVALID_TOKEN_WORDS, INVALID_TOKEN_HINT); | |
| 4176 | 4178 | const path = ctx.url.searchParams.get("path") ?? "/"; |
| 4177 | 4179 | const found = timePhase(ctx.request, "here", () => |
| 4178 | 4180 | manifestFor( |
src/http/context.ts +2
| @@ -41,6 +41,8 @@ export interface Auth { | ||
| 41 | 41 | /** Set when a Basic password was turned away by the sign-in windows or the |
| 42 | 42 | * hash gate, not found wrong: the request answers 429, not 401. */ |
| 43 | 43 | readonly retryAfter?: number; |
| 44 | /** Set when a bearer or basic credential was sent and matched nothing. */ | |
| 45 | readonly refused?: true; | |
| 44 | 46 | } |
| 45 | 47 | |
| 46 | 48 | /** |
src/http/server.ts +6 −3
| @@ -721,6 +721,8 @@ import { | ||
| 721 | 721 | // ---- auth ---- |
| 722 | 722 | |
| 723 | 723 | const NO_AUTH: Auth = { user: undefined, scope: undefined, via: "none" }; |
| 724 | /** A credential was sent and matched nothing: still no one, but `here` says so. */ | |
| 725 | const NO_MATCH: Auth = { ...NO_AUTH, refused: true }; | |
| 724 | 726 | |
| 725 | 727 | async function resolveAuth(app: App, request: Request): Promise<Auth> { |
| 726 | 728 | // A read-only standby knows no one: a session or token of the main forge |
| @@ -761,7 +763,7 @@ async function resolveAuth(app: App, request: Request): Promise<Auth> { | ||
| 761 | 763 | // client sends — another forge connecting to this one as an origin. |
| 762 | 764 | if (isTokenScheme(header)) { |
| 763 | 765 | const secret = tokenSecret(header); |
| 764 | if (secret === null) return NO_AUTH; | |
| 766 | if (secret === null) return NO_MATCH; | |
| 765 | 767 | const verified = verifyToken(app.db, secret); |
| 766 | 768 | if (verified.ok) { |
| 767 | 769 | return { |
| @@ -775,7 +777,7 @@ async function resolveAuth(app: App, request: Request): Promise<Auth> { | ||
| 775 | 777 | ...(verified.value.via ? { through: verified.value.via } : {}), |
| 776 | 778 | }; |
| 777 | 779 | } |
| 778 | return NO_AUTH; | |
| 780 | return NO_MATCH; | |
| 779 | 781 | } |
| 780 | 782 | |
| 781 | 783 | // Basic (git, and API convenience): `user:secret`. A forge_ secret is a |
| @@ -804,7 +806,7 @@ async function resolveAuth(app: App, request: Request): Promise<Auth> { | ||
| 804 | 806 | ...(verified.value.via ? { through: verified.value.via } : {}), |
| 805 | 807 | }; |
| 806 | 808 | } |
| 807 | return NO_AUTH; | |
| 809 | return NO_MATCH; | |
| 808 | 810 | } |
| 809 | 811 | if (username !== "" && secret !== "") { |
| 810 | 812 | // Counted in the sign-in windows like every password door; past them |
| @@ -820,6 +822,7 @@ async function resolveAuth(app: App, request: Request): Promise<Auth> { | ||
| 820 | 822 | // read this as bad credentials. |
| 821 | 823 | if (verified.error.reason === "throttled") |
| 822 | 824 | return { ...NO_AUTH, retryAfter: verified.error.retryAfter }; |
| 825 | return NO_MATCH; | |
| 823 | 826 | } |
| 824 | 827 | } |
| 825 | 828 | return NO_AUTH; |
test/here-start-token.test.ts added +105
| @@ -0,0 +1,105 @@ | ||
| 1 | /** | |
| 2 | * /api/v1/here tells the truth about the credential held (#14420): a start | |
| 3 | * token is a start token, a credential that matches nothing is a 401, no | |
| 4 | * credential is anonymous, and an account token is unchanged. | |
| 5 | */ | |
| 6 | import { afterAll, beforeAll, expect, test } from "bun:test"; | |
| 7 | import { mkdtemp, rm } from "node:fs/promises"; | |
| 8 | import { tmpdir } from "node:os"; | |
| 9 | import { join } from "node:path"; | |
| 10 | import { startBuilding } from "../src/actions/start.ts"; | |
| 11 | import { createApp, type App } from "../src/app.ts"; | |
| 12 | import { createToken } from "../src/core/tokens.ts"; | |
| 13 | import { createUser } from "../src/core/users.ts"; | |
| 14 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 15 | ||
| 16 | let dir = ""; | |
| 17 | let app: App, servers: Servers; | |
| 18 | let startToken = "", startUser = "", startRepo = "", accountToken = ""; | |
| 19 | ||
| 20 | beforeAll(async () => { | |
| 21 | dir = await mkdtemp(join(tmpdir(), "forge-here-start-")); | |
| 22 | app = createApp({ dataDir: dir, port: 0 }); | |
| 23 | servers = await serve(app); | |
| 24 | const made = await createUser(app.db, { | |
| 25 | origin: "seed", trusted: true, username: "ada", email: "[email protected]", | |
| 26 | password: "a-good-passphrase", adminIfFirst: true, | |
| 27 | }); | |
| 28 | if (!made.ok) throw new Error(String(made.error)); | |
| 29 | accountToken = createToken(app.db, made.value.id, "mine", "rw").token; | |
| 30 | const started = await startBuilding(app, { name: "probe" }, "198.51.100.7", servers.url); | |
| 31 | if (!started.ok) throw new Error(JSON.stringify(started.error)); | |
| 32 | startToken = started.value.token; | |
| 33 | startUser = started.value.user.username; | |
| 34 | startRepo = started.value.repo; | |
| 35 | }); | |
| 36 | afterAll(async () => { | |
| 37 | await servers.stop(); | |
| 38 | await rm(dir, { recursive: true, force: true }); | |
| 39 | }); | |
| 40 | ||
| 41 | const here = (headers: Record<string, string> = {}, path = "/") => | |
| 42 | fetch(`${servers.url}/api/v1/here?path=${path}`, { headers }); | |
| 43 | ||
| 44 | test("a start token is a start token, and can lists only what it may do", async () => { | |
| 45 | const res = await here({ authorization: `Bearer ${startToken}` }); | |
| 46 | expect(res.status).toBe(200); | |
| 47 | const body = (await res.json()) as { you: Record<string, string>; can: { do: string; http?: string }[] }; | |
| 48 | expect(body.you).toEqual({ as: "start", user: startUser, repo: startRepo }); | |
| 49 | expect(JSON.stringify(body)).not.toContain(startToken); | |
| 50 | expect(body.can.some((a) => a.do.startsWith("push"))).toBe(true); | |
| 51 | expect(body.can.some((a) => a.http === `GET /api/v1/repos/${startRepo}`)).toBe(true); | |
| 52 | expect(body.can.some((a) => a.http?.includes("/reports"))).toBe(true); | |
| 53 | expect(body.can.some((a) => a.http?.includes("/issues"))).toBe(false); | |
| 54 | }); | |
| 55 | ||
| 56 | test("a start token over basic is the same", async () => { | |
| 57 | const basic = `Basic ${btoa(`${startUser}:${startToken}`)}`; | |
| 58 | const body = (await (await here({ authorization: basic })).json()) as { you: { as: string } }; | |
| 59 | expect(body.you.as).toBe("start"); | |
| 60 | }); | |
| 61 | ||
| 62 | test("a credential that matches nothing is 401 invalid_token", async () => { | |
| 63 | for (const authorization of ["Bearer bogus", "token bogus", `Basic ${btoa("nobody:forge_nope")}`, `Basic ${btoa("nobody:wrong")}`]) { | |
| 64 | const res = await here({ authorization }); | |
| 65 | expect(res.status).toBe(401); | |
| 66 | const body = (await res.json()) as { error: string; hint: string }; | |
| 67 | expect(body.error).toBe("invalid_token"); | |
| 68 | expect(body.hint).toContain("/api/v1/start"); | |
| 69 | } | |
| 70 | }); | |
| 71 | ||
| 72 | test("no credential is anonymous", async () => { | |
| 73 | const res = await here(); | |
| 74 | expect(res.status).toBe(200); | |
| 75 | expect(((await res.json()) as { you: unknown }).you).toEqual({ as: "anonymous" }); | |
| 76 | }); | |
| 77 | ||
| 78 | test("an account token is unchanged", async () => { | |
| 79 | const res = await here({ authorization: `Bearer ${accountToken}` }); | |
| 80 | expect(res.status).toBe(200); | |
| 81 | expect(((await res.json()) as { you: { as: string; name: string } }).you).toMatchObject({ as: "reader", name: "ada" }); | |
| 82 | }); | |
| 83 | ||
| 84 | test("the MCP here tool says the same words for a start token", async () => { | |
| 85 | const res = await fetch(`${servers.url}/mcp`, { | |
| 86 | method: "POST", | |
| 87 | headers: { authorization: `Bearer ${startToken}`, "content-type": "application/json", accept: "application/json, text/event-stream" }, | |
| 88 | body: JSON.stringify({ | |
| 89 | jsonrpc: "2.0", id: 1, method: "tools/call", | |
| 90 | params: { name: "here", arguments: { url: `${servers.url}/` } }, | |
| 91 | }), | |
| 92 | }); | |
| 93 | const answer = (await res.json()) as any; | |
| 94 | const body = JSON.parse(answer.result.content[0].text); | |
| 95 | expect(body.you).toEqual({ as: "start", user: startUser, repo: startRepo }); | |
| 96 | expect(body.can.some((a: any) => a.do.startsWith("push"))).toBe(true); | |
| 97 | }); | |
| 98 | ||
| 99 | test("a token named start on an ordinary account is not a start token", async () => { | |
| 100 | const named = createToken(app.db, (await createUser(app.db, { | |
| 101 | origin: "seed", trusted: true, username: "bob", email: "[email protected]", password: "a-good-passphrase", | |
| 102 | }) as any).value.id, "start", "rw").token; | |
| 103 | const body = (await (await here({ authorization: `Bearer ${named}` })).json()) as { you: { as: string } }; | |
| 104 | expect(body.you.as).toBe("reader"); | |
| 105 | }); |
new above
offline
Identity must not come from a name the client can choose.
tokenName !== START_TOKENlets any account mint a token calledstartand be labelled as a start token with a trimmedcan. Use a server-set marker instead.