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

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

scout/forge:scout/14420-api-v1-here-says-who-a-start-token-is-an → main 4 commits fork 1 thread · 1 unresolved

  • Merged. scout/14420-api-v1-here-says-who-a-start-token-is-an was merged into main as 257cdfc.

Review

Sign in to review this change.
6 files changed +171 −5
src/actions/here.ts +54
@@ -28,8 +28,10 @@ import {
2828 canRead,
2929 canWrite,
3030 getRepo,
31 listReposOwnedBy,
3132 type Repo,
3233 } from "../core/repos.ts";
34 import { startOfAccount } from "../core/starts.ts";
3335 import { getUserByName, hiddenFrom } from "../core/users.ts";
3436 import { cappedQuery } from "../core/query_limit.ts";
3537 import { SYSTEM_NAMES } from "../core/reserved.ts";
@@ -89,6 +91,8 @@ export interface Manifest {
8991 };
9092 readonly you:
9193 | { 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 }
9296 | {
9397 readonly as: "reader" | "writer" | "owner" | "agent";
9498 readonly name: string;
@@ -146,6 +150,56 @@ export function manifestFor(
146150 scope: TokenScope | undefined,
147151 origin: string,
148152 path: string,
153 ): Result<Manifest, "not_found"> {

Identity must not come from a name the client can choose. tokenName !== START_TOKEN lets any account mint a token called start and be labelled as a start token with a trimmed can. Use a server-set marker instead.

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,
149203 ): Result<Manifest, "not_found"> {
150204 const common = {
151205 mcp: mcpPointers(origin),
src/contract/openapi/routes/getApiV1Here.ts +1 −1
@@ -1,3 +1,3 @@
11 import type { Route } from "../shared.ts";
22
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";
439439 import { upstreamRoutes } from "./api/upstream.ts";
440440 import type { Router } from "./router.ts";
441441 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";
443443 import { egressRowsFor, egressTotalsFor } from "../spawn/process_counters.ts";
444444 import { egressMetrics } from "../apps/egress_metrics.ts";
445445 import { forgeMetrics } from "../metrics/forge.ts";
@@ -4173,6 +4173,8 @@ export function apiRoutes(router: Router<Handler>): void {
41734173 // manifest every page links to. It differs by caller, so it is never cached.
41744174 router.add("GET", "/api/v1/here", (ctx) => {
41754175 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);
41764178 const path = ctx.url.searchParams.get("path") ?? "/";
41774179 const found = timePhase(ctx.request, "here", () =>
41784180 manifestFor(
src/http/context.ts +2
@@ -41,6 +41,8 @@ export interface Auth {
4141 /** Set when a Basic password was turned away by the sign-in windows or the
4242 * hash gate, not found wrong: the request answers 429, not 401. */
4343 readonly retryAfter?: number;
44 /** Set when a bearer or basic credential was sent and matched nothing. */
45 readonly refused?: true;
4446 }
4547
4648 /**
src/http/server.ts +6 −3
@@ -721,6 +721,8 @@ import {
721721 // ---- auth ----
722722
723723 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 };
724726
725727 async function resolveAuth(app: App, request: Request): Promise<Auth> {
726728 // 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> {
761763 // client sends — another forge connecting to this one as an origin.
762764 if (isTokenScheme(header)) {
763765 const secret = tokenSecret(header);
764 if (secret === null) return NO_AUTH;
766 if (secret === null) return NO_MATCH;
765767 const verified = verifyToken(app.db, secret);
766768 if (verified.ok) {
767769 return {
@@ -775,7 +777,7 @@ async function resolveAuth(app: App, request: Request): Promise<Auth> {
775777 ...(verified.value.via ? { through: verified.value.via } : {}),
776778 };
777779 }
778 return NO_AUTH;
780 return NO_MATCH;
779781 }
780782
781783 // 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> {
804806 ...(verified.value.via ? { through: verified.value.via } : {}),
805807 };
806808 }
807 return NO_AUTH;
809 return NO_MATCH;
808810 }
809811 if (username !== "" && secret !== "") {
810812 // 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> {
820822 // read this as bad credentials.
821823 if (verified.error.reason === "throttled")
822824 return { ...NO_AUTH, retryAfter: verified.error.retryAfter };
825 return NO_MATCH;
823826 }
824827 }
825828 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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs