Public: anyone can read this; the crew can change it.

An anonymous reader of a public repository sees an allow-listed set of fields, and a test fails on a new one #13902

Merged opened this

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

Merged

torque/forge:torque/13868-an-anonymous-reader-of-a-public-reposito → main 5 commits fork 2 threads · 2 unresolved

  • Merged. torque/13868-an-anonymous-reader-of-a-public-reposito was merged into main as e226a74.

Review

Sign in to review this change.
11 files changed +487 −29
src/contract/openapi.ts +19 −1
@@ -11,7 +11,7 @@
1111 * so pulls describing different routes do not collide (#5936).
1212 */
1313
14 import type { QueryType, Role, Route } from "./openapi/shared.ts";
14 import type { QueryType, ReplyShape, Role, Route } from "./openapi/shared.ts";
1515 import { OAUTH_SCOPES, type OAuthScope } from "../core/oauth.ts";
1616 import { tagList, tagOf } from "./tags.ts";
1717 import * as each from "./openapi/routes/index.ts";
@@ -56,6 +56,21 @@ const schema = (t: QueryType) =>
5656 ? { type: t.split("|") }
5757 : (t === "object" ? { type: "object" } : t === "array" ? { type: "array", items: { type: "object" } } : { type: t });
5858
59 /** Several titled shapes as `anyOf`; a cursor list carries them in `items` beside `next_cursor`. */
60 function shapesSchema(shapes: Readonly<Record<string, ReplyShape>>, list: boolean) {
61 const one = {
62 anyOf: Object.entries(shapes).map(([title, s]) => ({
63 title,
64 description: s.says,
65 type: "object",
66 properties: Object.fromEntries(Object.entries(s.fields).map(([k, t]) => [k, schema(t)])),
67 })),
68 };
69 return list
70 ? { type: "object", properties: { items: { type: "array", items: one }, next_cursor: { type: ["string", "null"] } } }
71 : one;
72 }
73
5974 /** The roles each role may act as: an admin is a member, a member is anonymous too. */
6075 const REACHES: Readonly<Record<Role, readonly Role[]>> = {
6176 anonymous: ["anonymous"],
@@ -123,6 +138,9 @@ export function openapi(origin: string, version: string, role: Role): Record<str
123138 responses: {
124139 [String(r.status ?? 200)]: {
125140 description: "Done",
141 ...(r.replyShapes === undefined
142 ? {}
143 : { content: { "application/json": { schema: shapesSchema(r.replyShapes, pagesByCursor(r)) } } }),
126144 ...(r.reply === undefined
127145 ? {}
128146 : {
src/contract/openapi/routes/getApiV1Repos.ts +2 −2
@@ -1,4 +1,4 @@
1 import { type Route, limitTo } from "../shared.ts";
1 import { REPO_LIST_SHAPES, type Route, limitTo } from "../shared.ts";
22 import { LIST_LIMIT_MAX } from "../../../core/issues.ts";
33
4 export const route: Route = { method: "get", path: "/api/v1/repos", summary: "List repositories the viewer can see; tagged with a weak ETag, and a repeat with If-None-Match gets 304 until a listed repository changes", auth: false, role: "anonymous", alsoStatus: [304], query: { limit: limitTo(LIST_LIMIT_MAX), cursor: "string" }, refusals: { invalid_limit: "limit is not a whole number from 1 to 200 (422)", invalid_cursor: "cursor is not the next_cursor of a previous page (422)" } };
4 export const route: Route = { method: "get", path: "/api/v1/repos", summary: "List repositories the viewer can see; tagged with a weak ETag, and a repeat with If-None-Match gets 304 until a listed repository changes or the viewer gains or loses write access; each item is the reader's fields to anyone who cannot write that repository, the whole object to who can", auth: false, role: "anonymous", alsoStatus: [304], replyShapes: REPO_LIST_SHAPES, query: { limit: limitTo(LIST_LIMIT_MAX), cursor: "string" }, refusals: { invalid_limit: "limit is not a whole number from 1 to 200 (422)", invalid_cursor: "cursor is not the next_cursor of a previous page (422)" } };
src/contract/openapi/routes/getApiV1ReposOwnerName.ts +3 −2
@@ -1,10 +1,11 @@
1 import { REPO, type Route } from "../shared.ts";
1 import { REPO, REPO_SHAPES, type Route } from "../shared.ts";
22
33 export const route: Route = {
44 method: "get",
55 path: REPO,
66 summary:
7 "Read one repository; `provenance` is where a migrated one came from ({ source, sourceUrl, parents: [{ fullName, url }], migratedAt }), null when it was not migrated or its owner hid it; `upstream` is the stored follow check ({ repo, behind, checkedAt, conflict }), shown to an admin of the repository, null when it follows nothing or to anyone else; `credit` is a mirror's { upstream: { fullName, htmlUrl, viaFork }, licence, authors }, null for a repository that is not a mirror",
7 "Read one repository; `provenance` is where a migrated one came from ({ source, sourceUrl, parents: [{ fullName, url }], migratedAt }), null when it was not migrated or its owner hid it; `upstream` is the stored follow check ({ repo, behind, checkedAt, conflict }), shown to an admin of the repository, null when it follows nothing or to anyone else; `credit` is a mirror's { upstream: { fullName, htmlUrl, viaFork }, licence, authors }, null for a repository that is not a mirror; a caller who cannot write it gets the reader's fields, without the crew's settings",
8 replyShapes: REPO_SHAPES,
89 auth: false,
910 role: "anonymous",
1011 refusals: { not_found: "404: no such repository, or it is not readable by the caller" },
src/contract/openapi/routes/getApiV1Templates.ts +2 −2
@@ -1,4 +1,4 @@
1 import { type Route, limitTo } from "../shared.ts";
1 import { REPO_LIST_SHAPES, type Route, limitTo } from "../shared.ts";
22 import { LIST_LIMIT_MAX } from "../../../core/issues.ts";
33
4 export const route: Route = { method: "get", path: "/api/v1/templates", summary: "List the repositories an admin marked as templates for new forges, only those the viewer can see; answers { items, next_cursor }", auth: false, role: "anonymous", query: { limit: limitTo(LIST_LIMIT_MAX), cursor: "string" }, refusals: { invalid_limit: "limit is not a whole number from 1 to 200 (422)", invalid_cursor: "cursor is not the next_cursor of a previous page (422)" } };
4 export const route: Route = { method: "get", path: "/api/v1/templates", summary: "List the repositories an admin marked as templates for new forges, only those the viewer can see; answers { items, next_cursor }", auth: false, role: "anonymous", replyShapes: REPO_LIST_SHAPES, query: { limit: limitTo(LIST_LIMIT_MAX), cursor: "string" }, refusals: { invalid_limit: "limit is not a whole number from 1 to 200 (422)", invalid_cursor: "cursor is not the next_cursor of a previous page (422)" } };
src/contract/openapi/routes/getApiV1UsersUsernameRepos.ts +2 −2
@@ -1,4 +1,4 @@
1 import { type Route, limitTo } from "../shared.ts";
1 import { REPO_LIST_SHAPES, type Route, limitTo } from "../shared.ts";
22 import { LIST_LIMIT_MAX } from "../../../core/issues.ts";
33
4 export const route: Route = { method: "get", path: "/api/v1/users/{username}/repos", summary: "List the repositories a person owns that the caller may see (private ones only to those with access); answers { items, next_cursor }, paged by `limit` and `cursor`. Carries a weak `ETag` (owner, viewer, page and a marker over the rows the caller may see); a repeat with a matching `If-None-Match` answers 304 with no body until one of them is added, pushed to, renamed, changes visibility or its open counts move", auth: false, role: "anonymous", query: { limit: limitTo(LIST_LIMIT_MAX), cursor: "string" }, refusals: { invalid_limit: "limit is not a whole number from 1 to 200 (422)", invalid_cursor: "cursor is not the next_cursor of a previous page (422)" } };
4 export const route: Route = { method: "get", path: "/api/v1/users/{username}/repos", summary: "List the repositories a person owns that the caller may see (private ones only to those with access); answers { items, next_cursor }, paged by `limit` and `cursor`. Carries a weak `ETag` (owner, viewer, the caller's write access, page and a marker over the rows the caller may see); a repeat with a matching `If-None-Match` answers 304 with no body until one of them is added, pushed to, renamed, changes visibility or its open counts move, or the caller gains or loses write access", auth: false, role: "anonymous", replyShapes: REPO_LIST_SHAPES, query: { limit: limitTo(LIST_LIMIT_MAX), cursor: "string" }, refusals: { invalid_limit: "limit is not a whole number from 1 to 200 (422)", invalid_cursor: "cursor is not the next_cursor of a previous page (422)" } };
src/contract/openapi/shared.ts +32
@@ -5,6 +5,12 @@
55 */
66
77 import { LIST_LIMIT_MAX } from "../../core/issues.ts";
8 import {
9 LIST_READER_FIELDS,
10 LIST_WRITER_FIELDS,
11 SINGLE_READER_FIELDS,
12 SINGLE_WRITER_FIELDS,
13 } from "../../core/repo_fields.ts";
814
915 /** A plain type name, or an integer with the bounds its handler refuses outside of (`min`/`max` become `minimum`/`maximum`). */
1016 export type QueryType = string | { readonly type: "integer"; readonly min?: number; readonly max?: number };
@@ -44,10 +50,36 @@ export interface Route {
4450 readonly errorStatus?: Readonly<Record<number, string>>;
4551 /** The success body's fields, by name and type, when it is worth a schema. */
4652 readonly reply?: Readonly<Record<string, string>>;
53 /**
54 * The success body as one of several shapes, by title, when who asks
55 * changes what comes back (published as `anyOf`; a cursor list's `items`).
56 */
57 readonly replyShapes?: Readonly<Record<string, ReplyShape>>;
4758 /** The refusals it answers, by stable `error` code. */
4859 readonly refusals?: Readonly<Record<string, string>>;
4960 }
5061
62 /** One shape of a reply: who gets it, and its fields by name and type. */
63 export interface ReplyShape {
64 readonly says: string;
65 readonly fields: Readonly<Record<string, string>>;
66 }
67
68 const READER_SAYS = "Anyone who can read it but not write it, signed in or not: the reader's fields only";
69 const WRITER_SAYS = "Its owner, an admin or a writer: the whole object, the crew's settings included";
70
71 /** One repository's read, as a reader and as a writer see it (`core/repo_fields.ts`, #13868). */
72 export const REPO_SHAPES: Readonly<Record<string, ReplyShape>> = {
73 reader: { says: READER_SAYS, fields: SINGLE_READER_FIELDS },
74 writer: { says: WRITER_SAYS, fields: SINGLE_WRITER_FIELDS },
75 };
76
77 /** A list item, as a reader and as a writer see it: the stored row and its counts, no more. */
78 export const REPO_LIST_SHAPES: Readonly<Record<string, ReplyShape>> = {
79 reader: { says: READER_SAYS, fields: LIST_READER_FIELDS },
80 writer: { says: WRITER_SAYS, fields: LIST_WRITER_FIELDS },
81 };
82
5183 /** What `listQuery` in `http/api.ts` reads from a list of issues or pulls. */
5284 export const LIST_QUERY = { state: "string", limit: limitTo(LIST_LIMIT_MAX), cursor: "integer", label: "string", author: "string" };
5385
src/core/repo_fields.ts added +151
@@ -0,0 +1,151 @@
1 /**
2 * Who sees which fields of a repository (#13868). A person who can write it —
3 * its owner, an admin, a writer — gets the whole object; everyone else, signed
4 * in or not, gets the reader's fields and nothing more. The crew's settings
5 * (autonomy, slots, who decides, the planner's issue, the sealed base) are the
6 * owner's business, not a reader's.
7 *
8 * Two replies hand out a repository, and each has its own shape: a list item
9 * (`GET /api/v1/repos`, a user's repositories, templates) is the stored row
10 * with its open counts; a single read (`GET /api/v1/repos/{owner}/{name}`,
11 * the MCP `repo` tool) adds what is worked out for one repository. The
12 * contract's schemas are drawn from these lists, and `READER_FIELDS` — the
13 * union a reader may ever get — is the allow-list. A field added to the
14 * repository is hidden from readers until someone puts it here on purpose;
15 * `test/repo-fields.test.ts` names any key that slips past, and any key a
16 * shape claims that the reply does not send.
17 *
18 * Each field carries its contract type (`contract/openapi.ts` `schema`).
19 */
20
21 import type { Database } from "bun:sqlite";
22 import { accessAllows, orgAccessByOrg, type Access } from "./orgs.ts";
23 import { isPacksMirror } from "../packs/owner.ts";
24 import type { User } from "./users.ts";
25 import { canWrite, type Repo } from "./repos.ts";
26
27 /** What a reader gets of a list item: the stored row's public part and its open counts. */
28 export const LIST_READER_FIELDS = {
29 id: "string",
30 ownerName: "string",
31 name: "string",
32 visibility: "string",
33 description: "string",
34 defaultBranch: "string",
35 protectDefault: "boolean",
36 requireReview: "boolean",
37 requireChecks: "boolean",
38 landing: "string",
39 template: "boolean",
40 forkParentId: "string|null",
41 archivedAt: "string|null",
42 origin: "object|null",
43 counts: "object",
44 } as const satisfies Readonly<Record<string, string>>;

audience, upstream and credit are only on the single read. REPO_SHAPES publishes this list for the list routes too, so the schema claims fields the lists never send. Split the shapes or mark these optional.

45
46 /**
47 * What a reader gets of a single read: a list item's, and what is worked out for one repository.
48 */
49 export const SINGLE_READER_FIELDS = {
50 ...LIST_READER_FIELDS,
51 pinned: "boolean",
52 provenance: "object|null",
53 audience: "object",
54 upstream: "object|null",
55 credit: "object|null",
56 } as const satisfies Readonly<Record<string, string>>;
57
58 /** Every field a reader may ever be handed: the allow-list `readerView` cuts to. */
59 export const READER_FIELDS = SINGLE_READER_FIELDS;
60
61 /** What a writer gets besides, on either reply: the crew's settings and the owner's id. */
62 const CREW_FIELDS = {
63 ownerId: "string",
64 autonomy: "string",
65 autonomyDirection: "string",
66 autonomySlots: "integer",
67 plannerSlots: "integer",
68 reviewerSlots: "integer",
69 polishShare: "integer",
70 autonomyBy: "string|null",
71 crewOutsiders: "boolean",
72 decisionsBy: "string",
73 plansNeedNod: "boolean",
74 directionIssueId: "string|null",
75 sealedFor: "string|null",
76 } as const satisfies Readonly<Record<string, string>>;
77
78 /** A list item as a writer gets it: the stored row whole, `detached` included. */
79 export const LIST_WRITER_FIELDS = {
80 ...LIST_READER_FIELDS,
81 ...CREW_FIELDS,
82 detached: "object|null",
83 } as const satisfies Readonly<Record<string, string>>;
84
85 /** A single read as a writer gets it; `detached` is folded into `origin` there. */
86 export const SINGLE_WRITER_FIELDS = {
87 ...SINGLE_READER_FIELDS,
88 ...CREW_FIELDS,
89 } as const satisfies Readonly<Record<string, string>>;
90
91 const READER_KEYS: ReadonlySet<string> = new Set(Object.keys(READER_FIELDS));
92
93 /** `shape` cut to the reader's fields; keys not on the list are dropped. */
94 export function readerView<T extends object>(shape: T): Partial<T> {
95 return Object.fromEntries(
96 Object.entries(shape).filter(([k]) => READER_KEYS.has(k)),
97 ) as Partial<T>;
98 }
99
100 /** Whether `user` gets the whole object of `repo`: only who can write it. */
101 export function seesWholeRepo(
102 db: Database,
103 repo: Repo,
104 user: User | undefined,
105 ): boolean {
106 return user !== undefined && canWrite(db, repo, user);
107 }
108
109 /** `shape` (built from `repo`) as `user` may see it. */
110 export function repoFor<T extends object>(
111 db: Database,
112 repo: Repo,
113 user: User | undefined,
114 shape: T,
115 ): T | Partial<T> {
116 return seesWholeRepo(db, repo, user) ? shape : readerView(shape);
117 }
118
119 /**
120 * What a viewer may write, read once for a whole list: `canWrite` row by row
121 * without a query per row. The rule is `canWrite`'s, clause for clause — a
122 * packs mirror only to its owner; otherwise the owner, a site admin, or a
123 * write or admin team in the owning org — and the only stored fact it rests
124 * on is the viewer's teams, read in one query.
125 *
126 * `marker` names that fact, so a list's ETag moves when the viewer gains or
127 * loses write access and a client holding the tag is not left with the old
128 * shape: anonymous, a site admin, or the orgs the viewer writes in.
129 */
130 export interface WriteAccess {
131 readonly marker: string;
132 writes(repo: Repo): boolean;
133 }
134
135 export function writeAccess(db: Database, user: User | undefined): WriteAccess {
136 if (user === undefined) return { marker: "anon", writes: () => false };
137 const orgs: ReadonlyMap<string, Access> = user.isAdmin ? new Map() : orgAccessByOrg(db, user);
138 const writesIn = [...orgs].filter(([, a]) => accessAllows(a, "write")).map(([org]) => org).sort();
139 return {
140 marker: user.isAdmin ? "admin" : `w${Bun.hash(writesIn.join(",")).toString(36)}`,
141 writes: (repo) => {
142 if (isPacksMirror(repo)) return user.id === repo.ownerId;
143 return user.id === repo.ownerId || user.isAdmin || accessAllows(orgs.get(repo.ownerId) ?? "none", "write");
144 },
145 };
146 }
147
148 /** A list's rows, each cut to what the viewer behind `access` may see of it. */
149 export function reposFor<T extends Repo>(access: WriteAccess, repos: readonly T[]): (T | Partial<T>)[] {
150 return repos.map((r) => (access.writes(r) ? r : readerView(r)));
151 }
src/http/api.ts +22 −7
@@ -144,6 +144,7 @@ import {
144144 import { OFFSET_LIMIT_MAX, offsetPage, offsetQuery } from "./offset_page.ts";
145145 import { EVENTS_LIMIT_MAX, eventsLimit, eventsPage, validEventsCursor, validEventsKind } from "../core/events_page.ts";
146146 import { audienceFor } from "../core/audience.ts";
147 import { repoFor, reposFor, writeAccess, type WriteAccess } from "../core/repo_fields.ts";
147148 import { creditFacts } from "../actions/credit_facts.ts";
148149 import {
149150 forkParentFor,
@@ -563,7 +564,7 @@ const NO_COUNTS: RepoCounts = { openIssues: 0, openPulls: 0 };
563564 */
564565 function repoJson(ctx: Ctx, repo: Repo) {
565566 const { detached: _detached, ...rest } = repo;
566 return {
567 return repoFor(ctx.app.db, repo, ctx.auth.user, {
567568 ...rest,
568569 origin: originFacts(repo),
569570 counts:
@@ -580,7 +581,16 @@ function repoJson(ctx: Ctx, repo: Repo) {
580581 ? undefined
581582 : forkParentFor(ctx.app.db, repo, ctx.auth.user),
582583 ),
583 };
584 });
585 }
586
587 /**
588 * A page of repositories, each cut to what this viewer may see of it
589 * (#13868); write access is read once for the page, not once per row.
590 */
outdated

repoFor runs canWrite per item, so a 200-item page costs up to 200 queries. Resolve write access once per owner or in one query. The ETag of the list routes also has to change with write access (see the review body).

591 function repoPage(ctx: Ctx, items: Repo[], limit: number, access: WriteAccess = writeAccess(ctx.app.db, ctx.auth.user)) {
592 const page = paged(items, limit, (r) => r.id);
593 return { ...page, items: reposFor(access, page.items) };
584594 }
585595
586596 /**
@@ -1283,8 +1293,10 @@ export function apiRoutes(router: Router<Handler>): void {
12831293 const owned = { ...query, owner: user.username };
12841294 const marker = timePhase(ctx.request, "tag", () => visibleReposMarker(ctx.app.db, ctx.auth.user, owned));
12851295 const viewer = ctx.auth.user === undefined ? "anon" : `u${Bun.hash(ctx.auth.user.id).toString(36)}`;
1296 // Which shape each row takes moves with the viewer's write access (#13868).
1297 const access = writeAccess(ctx.app.db, ctx.auth.user);
12861298 const headers = {
1287 etag: `W/"user-repos-${Bun.hash(`${user.id}|${viewer}|${query.limit}|${query.cursor ?? ""}|${marker}`).toString(36)}"`,
1299 etag: `W/"user-repos-${Bun.hash(`${user.id}|${viewer}|${access.marker}|${query.limit}|${query.cursor ?? ""}|${marker}`).toString(36)}"`,
12881300 "cache-control": "private, no-cache",
12891301 vary: "authorization, cookie",
12901302 };
@@ -1293,7 +1305,7 @@ export function apiRoutes(router: Router<Handler>): void {
12931305 listReposByOwner(ctx.app.db, user.username, ctx.auth.user, query),
12941306 );
12951307 return timePhase(ctx.request, "render", () =>
1296 json(paged(items, query.limit, (r) => r.id), 200, headers),
1308 json(repoPage(ctx, items, query.limit, access), 200, headers),
12971309 );
12981310 });
12991311
@@ -1634,14 +1646,16 @@ export function apiRoutes(router: Router<Handler>): void {
16341646 // not built, counted or serialised (#9115).
16351647 const marker = timePhase(ctx.request, "tag", () => visibleReposMarker(ctx.app.db, ctx.auth.user, query));
16361648 const viewer = ctx.auth.user === undefined ? "anon" : `u${Bun.hash(ctx.auth.user.id).toString(36)}`;
1649 // Which shape each row takes moves with the viewer's write access (#13868).
1650 const access = writeAccess(ctx.app.db, ctx.auth.user);
16371651 const headers = {
1638 etag: `W/"repos-${Bun.hash(`${viewer}|${query.limit}|${query.cursor ?? ""}|${marker}`).toString(36)}"`,
1652 etag: `W/"repos-${Bun.hash(`${viewer}|${access.marker}|${query.limit}|${query.cursor ?? ""}|${marker}`).toString(36)}"`,
16391653 "cache-control": "private, no-cache",
16401654 vary: "authorization, cookie",
16411655 };
16421656 if (holds(ctx.request, headers.etag)) return new Response(null, { status: 304, headers });
16431657 const items = timePhase(ctx.request, "repos", () => listReposVisibleTo(ctx.app.db, ctx.auth.user, query));
1644 return timePhase(ctx.request, "render", () => json(paged(items, query.limit, (r) => r.id), 200, headers));
1658 return timePhase(ctx.request, "render", () => json(repoPage(ctx, items, query.limit, access), 200, headers));
16451659 });
16461660
16471661 // The repositories marked as templates for new forges (#12431): the same
@@ -1650,7 +1664,7 @@ export function apiRoutes(router: Router<Handler>): void {
16501664 const query = repoQuery(ctx);
16511665 if (query instanceof Response) return query;
16521666 const items = listReposVisibleTo(ctx.app.db, ctx.auth.user, { ...query, templatesOnly: true });
1653 return json(paged(items, query.limit, (r) => r.id), 200, {
1667 return json(repoPage(ctx, items, query.limit), 200, {
16541668 "cache-control": "private, no-cache",
16551669 vary: "authorization, cookie",
16561670 });
@@ -1694,6 +1708,7 @@ export function apiRoutes(router: Router<Handler>): void {
16941708 notePhase(ctx.request, "credit", performance.now() - credited);
16951709 const rendering = performance.now();
16961710 const upstream = upstreamFacts(ctx.app.db, repo, ctx.auth.user);
1711 // `facts` is already cut to the viewer; the three added are reader fields.
16971712 const res = json({ ...facts, audience, upstream, credit });
16981713 notePhase(ctx.request, "render", performance.now() - rendering);
16991714 return res;
src/http/mcp/tools/repo.ts +16 −12
@@ -1,6 +1,7 @@
11 import { provenanceFacts } from "../../../core/provenance.ts";
22 import { forkParentFor } from "../../../core/repos.ts";
33 import { audienceFor } from "../../../core/audience.ts";
4 import { repoFor } from "../../../core/repo_fields.ts";
45 import { upstreamFacts } from "../../../actions/upstream_follow.ts";
56 import { creditFacts } from "../../../actions/credit_facts.ts";
67 import { type ChapterActError, close, fill, open, preview, refusalWords, type Refused } from "../../../actions/chapters.ts";
@@ -10,7 +11,7 @@ import { good, str, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../share
1011
1112 export const tool: Tool = {
1213 name: "repo",
13 doc: "`{ repo }`: one repository's description, visibility, autonomy, `audience { level, who, sentence }` and `provenance` (where a migrated one came from, `null` when hidden), `credit` (a mirror's upstream, licence, authors; `null` otherwise), the same as `GET /api/v1/repos/:owner/:name`; `action` (`open|add|remove|close` with `chapter`, `number` for add/remove; a person who administers it, `rw` token) says what it would do, and with `confirm: true` does it, as the page; `view: \"chapters\"` lists its chapters with state, and with `chapter` names one's items (`done|building|left`) and `progress` (the page's sentence)",
14 doc: "`{ repo }`: one repository's description, visibility, autonomy (to a writer), `audience { level, who, sentence }` and `provenance` (where a migrated one came from, `null` when hidden), `credit` (a mirror's upstream, licence, authors; `null` otherwise), the same as `GET /api/v1/repos/:owner/:name`; `action` (`open|add|remove|close` with `chapter`, `number` for add/remove; a person who administers it, `rw` token) says what it would do, and with `confirm: true` does it, as the page; `view: \"chapters\"` lists its chapters with state, and with `chapter` names one's items (`done|building|left`) and `progress` (the page's sentence)",
1415 description:
1516 "One repository you can read, as GET /api/v1/repos/:owner/:name.",
1617 inputSchema: {
@@ -60,19 +61,22 @@ export const tool: Tool = {
6061 items: items.map((i) => ({ number: i.number, title: i.title, status: i.status, doneAt: i.doneAt })),
6162 });
6263 }
64 // The same field list as the HTTP read (#13868): `autonomy` only to a writer.
6365 return good({
6466 repo: `${repo.ownerName}/${repo.name}`,
65 description: repo.description,
66 visibility: repo.visibility,
67 autonomy: repo.autonomy,
68 audience: audienceFor(ctx.app.db, repo, user),
69 provenance: provenanceFacts(
70 ctx.app.db,
71 repo,
72 forkParentFor(ctx.app.db, repo, user),
73 ),
74 upstream: upstreamFacts(ctx.app.db, repo, user),
75 credit: await creditFacts(ctx.app, repo, user),
67 ...repoFor(ctx.app.db, repo, user, {
68 description: repo.description,
69 visibility: repo.visibility,
70 autonomy: repo.autonomy,
71 audience: audienceFor(ctx.app.db, repo, user),
72 provenance: provenanceFacts(
73 ctx.app.db,
74 repo,
75 forkParentFor(ctx.app.db, repo, user),
76 ),
77 upstream: upstreamFacts(ctx.app.db, repo, user),
78 credit: await creditFacts(ctx.app, repo, user),
79 }),
7680 });
7781 },
7882 };
test/decisions-by-doors.test.ts +7 −1
@@ -145,9 +145,15 @@ describe("the standing rule over the API", () => {
145145 expect((await patch(admin["founder"]!, { description: "x" })).status).toBe(200);
146146 expect(rule()).toBe("decider_tell");
147147 const read = await fetch(`${servers.url}/api/v1/repos/acme/svc`, {
148 headers: { authorization: `Bearer ${admin["mallory"]}` },
148 headers: { authorization: `Bearer ${admin["founder"]}` },
149149 });
150150 expect(((await read.json()) as { decisionsBy: string }).decisionsBy).toBe("decider_tell");
151 // The rule is the owner's setting: a reader who cannot write is not handed it (#13868).
152 const stranger = await fetch(`${servers.url}/api/v1/repos/acme/svc`, {
153 headers: { authorization: `Bearer ${admin["mallory"]}` },
154 });
155 expect(stranger.status).toBe(200);
156 expect("decisionsBy" in ((await stranger.json()) as object)).toBe(false);
151157 await patch(admin["founder"]!, { decisionsBy: "me" });
152158 });
153159 });
test/repo-fields.test.ts added +231
@@ -0,0 +1,231 @@
1 /**
2 * Who sees which fields of a repository (#13868): an anonymous reader and a
3 * signed-in non-writer get the keys `READER_FIELDS` lists and no others; the
4 * owner keeps the whole object. Every read that hands out a repository is
5 * asked, and a key off the list fails naming itself.
6 */
7 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
8 import { mkdtemp, rm } from "node:fs/promises";
9 import { tmpdir } from "node:os";
10 import { join } from "node:path";
11 import { createApp, type App } from "../src/app.ts";
12 import { createRepo } from "../src/actions/repos.ts";
13 import { openapi } from "../src/contract/openapi.ts";
14 import {
15 LIST_READER_FIELDS,
16 LIST_WRITER_FIELDS,
17 READER_FIELDS,
18 SINGLE_READER_FIELDS,
19 SINGLE_WRITER_FIELDS,
20 readerView,
21 writeAccess,
22 } from "../src/core/repo_fields.ts";
23 import { addTeamMember, createOrg, createTeam, removeTeamMember } from "../src/core/orgs.ts";
24 import { canWrite, getRepo, listReposVisibleTo } from "../src/core/repos.ts";
25 import { createSession } from "../src/core/sessions.ts";
26 import { createUser, type User } from "../src/core/users.ts";
27 import type { Ctx } from "../src/http/context.ts";
28 import { tool as repoTool } from "../src/http/mcp/tools/repo.ts";
29 import { serve, type Servers } from "../src/http/server.ts";
30 import { quietLogs } from "./helpers/globals.ts";
31
32 quietLogs();
33
34 let dataDir: string;
35 let app: App;
36 let servers: Servers;
37 let alice: User;
38 let bob: User;
39 let carol: User;
40 const cookies: Record<string, string> = {};
41 const cells = process.env["FORGE_CELLS"];
42
43 async function person(username: string): Promise<User> {
44 const made = await createUser(app.db, {
45 origin: "seed",
46 trusted: true,
47 username,
48 email: `${username}@forge.local`,
49 password: "a-good-passphrase",
50 adminIfFirst: username === "alice",
51 });
52 if (!made.ok) throw new Error(String(made.error));
53 cookies[username] = `forge_session=${createSession(app.db, made.value.id).token}`;
54 return made.value;
55 }
56
57 beforeAll(async () => {
58 process.env["FORGE_CELLS"] = "off";
59 dataDir = await mkdtemp(join(tmpdir(), "forge-repo-fields-"));
60 app = createApp({ dataDir, port: 0 });
61 servers = await serve(app);
62 alice = await person("alice");
63 bob = await person("bob");
64 carol = await person("carol");
65 const repo = await createRepo(app, alice, { name: "r", visibility: "public" });
66 if (!repo.ok) throw new Error(String(repo.error));
67 app.db.query("UPDATE repo SET is_template = 1 WHERE id = ?1").run(repo.value.id);
68 });
69 afterAll(async () => {
70 await servers.stop();
71 app.close();
72 if (cells === undefined) delete process.env["FORGE_CELLS"];
73 else process.env["FORGE_CELLS"] = cells;
74 await rm(dataDir, { recursive: true, force: true });
75 });
76
77 async function get(path: string, who?: string): Promise<any> {
78 const res = await fetch(`${servers.url}${path}`, { headers: who === undefined ? {} : { cookie: cookies[who]! } });
79 expect(res.status).toBe(200);
80 return res.json();
81 }
82
83 /** The keys of `shape` that are not on the reader's list: empty, or the failure names them. */
84 function offList(shape: Record<string, unknown>): string[] {
85 return Object.keys(shape).filter((k) => !(k in READER_FIELDS));
86 }
87
88 type Read = [path: string, shape: Record<string, unknown>, kind: "list" | "single"];
89
90 /** Every repository object each read hands `who`, and which reply it came in. */
91 async function reads(who?: string): Promise<Read[]> {
92 const one = (path: string, body: any): Read => {
93 const item = body.items.find((r: any) => r.name === "r");
94 expect(item, path).toBeDefined();
95 return [path, item, "list"];
96 };
97 return [
98 one("/api/v1/repos", await get("/api/v1/repos", who)),
99 one("/api/v1/users/alice/repos", await get("/api/v1/users/alice/repos", who)),
100 one("/api/v1/templates", await get("/api/v1/templates", who)),
101 ["/api/v1/repos/alice/r", await get("/api/v1/repos/alice/r", who), "single"],
102 ];
103 }
104
105 const sorted = (o: object) => Object.keys(o).sort();
106
107 describe("an anonymous reader and a non-writer", () => {
108 for (const who of [undefined, "bob"]) {
109 test(`${who ?? "anonymous"} gets only the reader's fields, on every read`, async () => {
110 for (const [path, shape, kind] of await reads(who)) {
111 expect({ path, offList: offList(shape) }).toEqual({ path, offList: [] });
112 // The schema for this reply names exactly what it sends: no more, no fewer.
113 const published = kind === "list" ? LIST_READER_FIELDS : SINGLE_READER_FIELDS;
114 expect({ path, keys: sorted(shape) }).toEqual({ path, keys: sorted(published) });
115 expect(shape["name"]).toBe("r");
116 expect(shape["ownerName"]).toBe("alice");
117 }
118 });
119 }
120
121 test("the MCP `repo` tool hands bob no crew settings", async () => {
122 const url = new URL("http://forge.test/mcp");
123 const ctx: Ctx = { app, request: new Request(url.href), url, params: {}, auth: { user: bob, scope: "ro", via: "token" }, theme: undefined };
124 const read = await repoTool.run(ctx, bob, { repo: "alice/r" });
125 expect(read.ok).toBe(true);
126 const { repo: _name, ...shape } = (read as { value: Record<string, unknown> }).value;
127 expect(offList(shape)).toEqual([]);
128 expect(shape["visibility"]).toBe("public");
129 });
130 });
131
132 describe("the owner", () => {
133 test("keeps the whole object, the crew's settings included", async () => {
134 for (const [path, shape, kind] of await reads("alice")) {
135 for (const k of ["ownerId", "autonomy", "autonomyBy", "plannerSlots", "reviewerSlots", "polishShare", "decisionsBy", "plansNeedNod", "sealedFor", "directionIssueId"])
136 expect({ path, k, has: k in shape }).toEqual({ path, k, has: true });
137 const published = kind === "list" ? LIST_WRITER_FIELDS : SINGLE_WRITER_FIELDS;
138 expect({ path, keys: sorted(shape) }).toEqual({ path, keys: sorted(published) });
139 }
140 const url = new URL("http://forge.test/mcp");
141 const ctx: Ctx = { app, request: new Request(url.href), url, params: {}, auth: { user: alice, scope: "ro", via: "token" }, theme: undefined };
142 const read = await repoTool.run(ctx, alice, { repo: "alice/r" });
143 expect((read as { value: Record<string, unknown> }).value["autonomy"]).toBeDefined();
144 });
145 });
146
147 test("readerView drops a key that is not on the list, and keeps one that is", () => {
148 const repo = getRepo(app.db, "alice", "r")!;
149 const cut = readerView({ ...repo, aNewSetting: 1 });
150 expect("aNewSetting" in cut).toBe(false);
151 expect("autonomy" in cut).toBe(false);
152 expect(cut.defaultBranch).toBe(repo.defaultBranch);
153 });
154
155 test("the contract shows both shapes of each reply, a list's without the single read's additions", () => {
156 const doc = openapi("https://f.test", "1", "anonymous") as any;
157 const schemaOf = (path: string) => doc.paths[path].get.responses["200"].content["application/json"].schema;
158 const single = schemaOf("/api/v1/repos/{owner}/{name}").anyOf;
159 expect(single.map((s: any) => s.title)).toEqual(["reader", "writer"]);
160 expect(Object.keys(single[0].properties)).toEqual(Object.keys(SINGLE_READER_FIELDS));
161 expect(Object.keys(single[1].properties)).toEqual(Object.keys(SINGLE_WRITER_FIELDS));
162 for (const path of ["/api/v1/repos", "/api/v1/users/{username}/repos", "/api/v1/templates"]) {
163 const list = schemaOf(path).properties.items.items.anyOf;
164 expect(list.map((s: any) => s.title)).toEqual(["reader", "writer"]);
165 expect(Object.keys(list[0].properties)).toEqual(Object.keys(LIST_READER_FIELDS));
166 expect(Object.keys(list[1].properties)).toEqual(Object.keys(LIST_WRITER_FIELDS));
167 expect(list[0].properties.autonomy).toBeUndefined();
168 for (const k of ["audience", "upstream", "credit", "pinned", "provenance"])
169 expect({ path, k, listed: k in list[0].properties }).toEqual({ path, k, listed: false });
170 }
171 });
172
173 describe("write access, read once for a list", () => {
174 test("agrees with canWrite on every row: owner, site admin, org writer, org reader, anonymous", async () => {
175 const org = createOrg(app.db, "acme", alice.id);
176 if (!org.ok) throw new Error(String(org.error));
177 const writers = createTeam(app.db, org.value.id, "writers", "write");
178 const readers = createTeam(app.db, org.value.id, "readers", "read");
179 if (!writers.ok || !readers.ok) throw new Error("team");
180 expect(addTeamMember(app.db, writers.value, bob.id)).toBe(true);
181 expect(addTeamMember(app.db, readers.value, carol.id)).toBe(true);
182 const made = await createRepo(app, alice, { owner: "acme", name: "w", visibility: "public" });
183 if (!made.ok) throw new Error(String(made.error));
184 const rows = listReposVisibleTo(app.db, alice, { limit: 200 });
185 expect(rows.length).toBeGreaterThanOrEqual(2);
186 for (const user of [undefined, alice, bob, carol]) {
187 const access = writeAccess(app.db, user);
188 for (const r of rows)
189 expect({ who: user?.username, repo: r.name, writes: access.writes(r) }).toEqual({
190 who: user?.username,
191 repo: r.name,
192 writes: canWrite(app.db, r, user),
193 });
194 }
195 expect(writeAccess(app.db, bob).writes(getRepo(app.db, "acme", "w")!)).toBe(true);
196 expect(writeAccess(app.db, carol).writes(getRepo(app.db, "acme", "w")!)).toBe(false);
197 });
198
199 test("the list ETags move when the viewer gains or loses write access, and the shape follows", async () => {
200 const org = createOrg(app.db, "beta", alice.id);
201 if (!org.ok) throw new Error(String(org.error));
202 const team = createTeam(app.db, org.value.id, "writers", "write");
203 if (!team.ok) throw new Error(String(team.error));
204 const made = await createRepo(app, alice, { owner: "beta", name: "b", visibility: "public" });
205 if (!made.ok) throw new Error(String(made.error));
206 const ask = async (path: string, etag?: string) => {
207 const headers: Record<string, string> = { cookie: cookies["carol"]! };
208 if (etag !== undefined) headers["if-none-match"] = etag;
209 return fetch(`${servers.url}${path}`, { headers });
210 };
211 const item = async (res: Response) => ((await res.json()) as any).items.find((r: any) => r.name === "b");
212 for (const path of ["/api/v1/repos", "/api/v1/users/beta/repos"]) {
213 const before = await ask(path);
214 const tag = before.headers.get("etag")!;
215 expect("autonomy" in (await item(before))).toBe(false);
216 expect((await ask(path, tag)).status).toBe(304);
217
218 expect(addTeamMember(app.db, team.value, carol.id)).toBe(true);
219 const gained = await ask(path, tag);
220 expect({ path, status: gained.status }).toEqual({ path, status: 200 });
221 expect("autonomy" in (await item(gained))).toBe(true);
222 const writerTag = gained.headers.get("etag")!;
223 expect(writerTag).not.toBe(tag);
224
225 expect(removeTeamMember(app.db, team.value, carol.id)).toBe(true);
226 const lost = await ask(path, writerTag);
227 expect({ path, status: lost.status }).toEqual({ path, status: 200 });
228 expect("autonomy" in (await item(lost))).toBe(false);
229 }
230 });
231 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs