3ddfef1 · 6968a54 · f9e68de · 4cb0cda · dac268e · a96572b
@@ -238,7 +238,7 @@
bytes in `tools/list`. After changing a tool run `bun scripts/mcp-table.ts`;
| `whoami_can` | `role`, `passkeys` | What you can do: your role and its roles-table row, yes or no each | 231 |
| `write_file` | — | No shell? Commit one file to a branch | 342 |
| `report` | — | Report a problem in a public repository, no account needed | 468 |
| `start` | — | Start building with no account: an account, a repo, a live app and a token in one call | 358 |
| `start` | `contribute` | Start building with no account: an account, a repo, a live app and a token in one call | 387 |
<!-- mcp-tools:end -->
The complete list, with schemas, is MCP `tools/list` called with a token.
@@ -0,0 +1,19 @@
# Outside agents: a contribute token with no account (#12012)
An agent with its own sandbox (Codex cloud, Jules, Claude Code, Cursor) contributes by clone and push. It needs no account and spawns no forge.
**The owner says yes first.** On a repository's settings page, *Outside agents* › *Allow outside agents*. Only a public, original, unarchived repository takes them. The same list shows each live token (agent, claimed origin, expiry, last use) with *Revoke*, after a confirm. The terminal has the same screen (palette: *Outside agents*, a repository's admins only): `a` allows or stops allowing, `x` revokes after a confirm; each write is an event, so an open settings page follows it.
**The agent asks for a token.**
```
POST /api/v1/contribute   {"agent": "codex", "repo": "owner/name", "origin": "codex cloud"}
```
or the MCP `start` tool with `action: "contribute"` (same arguments). The answer, shown once, holds the token, `git.push` (a push URL for `HEAD:contrib/<agent>/<segment>/<topic>`) and `expiresAt`.
- **Scope:** read public repositories; push `contrib/<agent>/<segment>/*` on that one repository; open pulls from those branches (`POST /api/v1/repos/<owner>/<name>/pulls`, `head: "contrib/<agent>/<segment>/<topic>"`); read and update its own pulls, checks included. Everything else answers 403 (`src/http/contribute_gate.ts`, `allows` in `src/core/contribute_token.ts`). It never reaches the default branch and a person merges.
- **Lifetime:** 24 hours. `POST /api/v1/contribute` with the token presented renews it once, by another day, never past a week from minting.
- **Own branches:** the agent name is claimed, so two tokens may share one. The `<segment>` is derived from the token's own id and is in the `branches` and `git.push` the mint answers; the pre-receive hook refuses any ref outside it, so one token cannot push over or delete another's branches.
- **Limits:** 5 tokens an hour and 20 a day per address (hashed), 120 requests a minute per token; at most 5 pulls open per token, 20 opened a day per token and 30 a day from all of a repository's outside tokens (counted from the pull rows; over it answers 429).
- **Claimed, not verified:** the agent name and origin are what the agent said. The forge makes a throwaway guest account per token (no password, no crew, no credits) so a pull has an author; the account stays after the token ends.
@@ -0,0 +1,175 @@
/**
 * The contribute call (#12012): an outside agent names itself and a repository
 * that opted in, and gets a token for one day with no account of its own. The
 * forge makes a throwaway guest account for the mint (no password, no crew, no
 * credits) so a pull the agent opens has an author. Name and origin are stored
 * as claimed. Minting is capped per address, counted from the rows it leaves.
 * The repository owner's yes is `contribute_open` (`setOutsideContributions`).
 */
import type { App } from "../app.ts";
import {
  MINTS_PER_DAY,
  MINTS_PER_HOUR,
  contribNamespace,
  type Minted,
  contributeOpen,
  isAgentName,
  isOrigin,
  mintContribute,
  mintsSince,
  renewContribute,
  revokeContribute,
  setContributeOpen,
} from "../core/contribute_token.ts";
import { getRepo, canAdmin, type Repo } from "../core/repos.ts";
import { createUser, type User } from "../core/users.ts";
import { err, ok, type Result } from "../kernel/result.ts";
import { isMirror } from "../origins/write-through.ts";
import { isContributionFork } from "../core/contribute.ts";
import { nameSlug } from "./start.ts";
import { noEmail } from "./users.ts";
export type ContributeTokenError =
  | "invalid_agent"
  | "invalid_origin"
  | "invalid_repo"
  | "not_open"
  | "rate_limited"
  | "already_renewed"
  | "failed";
export const CONTRIBUTE_TOKEN_WORDS: Readonly<Record<ContributeTokenError, string>> = {
  invalid_agent: "agent is a name of at most 64 letters, digits, . _ -, starting with a letter or digit",
  invalid_origin: "origin is where you run from, as plain text of at most 200 characters (claimed, not verified)",
  invalid_repo: "repo is owner/name",
  not_open: "this repository does not take outside contributions: it is private, archived, a copy, or its owner has not allowed them",
  rate_limited: "Too many tokens from here; wait and ask again.",
  already_renewed: "this token was renewed once already; ask for a new one",
  failed: "The token could not be made; nothing was kept. Try again.",
};
export const CONTRIBUTE_TOKEN_HINT =
  "send {agent, repo: \"owner/name\", origin?}: agent is your name, origin where you run (both claimed, not verified)";
export interface ContributeTokenRefusal {
  readonly error: ContributeTokenError;
  readonly retryAfter?: number;
}
/**
 * Whether `repo` takes outside contributions: public, a real original, not archived,
 * and its owner said yes.
 */
export function takesOutside(app: App, repo: Repo): boolean {
  return (
    repo.visibility === "public" &&
    repo.sealedFor === null &&
    repo.archivedAt === null &&
    !isMirror(app, repo) &&
    !isContributionFork(app.db, repo.id) &&
    contributeOpen(app.db, repo.id)
  );
}
export interface ContributeTokenMade extends Minted {
  readonly repo: string;
  readonly agent: string;
  /** The branches this token may push. */
  readonly branches: string;
  readonly git: { readonly url: string; readonly push: string };
  readonly claimed: true;
  readonly renewable: true;
}
export async function mintContributeToken(
  app: App,
  input: { agent?: unknown; origin?: unknown; repo?: unknown },
  source: string,
  origin: string,
  now: Date = new Date(),
): Promise<Result<ContributeTokenMade, ContributeTokenRefusal>> {
  const refuse = (error: ContributeTokenError, retryAfter?: number) =>
    err<ContributeTokenRefusal>(retryAfter === undefined ? { error } : { error, retryAfter });
  if (!isAgentName(input.agent)) return refuse("invalid_agent");
  const claimed = input.origin === undefined ? "" : input.origin;
  if (!isOrigin(claimed)) return refuse("invalid_origin");
  const [owner, name, ...rest] = typeof input.repo === "string" ? input.repo.split("/") : [];
  if (!owner || !name || rest.length > 0) return refuse("invalid_repo");
  // A repository that is missing and one that is closed answer alike.
  const repo = getRepo(app.db, owner, name);
  if (repo === undefined || !takesOutside(app, repo)) return refuse("not_open");
  const agent = input.agent;
  const capped = (): boolean =>
    mintsSince(app.db, now.getTime() - 3_600_000, source) >= MINTS_PER_HOUR ||
    mintsSince(app.db, now.getTime() - 86_400_000, source) >= MINTS_PER_DAY;
  if (capped()) return refuse("rate_limited", 3600);
  const base = nameSlug(agent) || "agent";
  const username = `contrib-${base}-${crypto.randomUUID().slice(0, 6)}`.slice(0, 39);
  const made = await createUser(app.db, {
    origin: "start",
    username,
    email: noEmail(username),
    displayName: agent,
    trusted: true,
  });
  if (!made.ok) return refuse("failed");
  const user: User = made.value;
  let minted: Minted | undefined;
  app.db.transaction(() => {
    // Counted again inside the write: concurrent calls cannot overshoot.
    if (capped()) return;
    minted = mintContribute(app.db, { userId: user.id, repoId: repo.id, agent, origin: claimed, source }, now);
  })();
  if (minted === undefined) {
    // The cap held inside the write: the account made for this mint goes with it.
    app.db.transaction(() => {
      app.db.query("DELETE FROM email_check WHERE user_id = ?1").run(user.id);
      app.db.query("DELETE FROM user WHERE id = ?1").run(user.id);
    })();
    return refuse("rate_limited", 3600);
  }
  const namespace = contribNamespace(agent, minted.id);
  app.bus.append({ kind: "contribute.token", repoId: repo.id, actorId: user.id, payload: { agent } });
  const url = `${origin}/${repo.ownerName}/${repo.name}.git`;
  return ok({
    ...minted,
    repo: `${repo.ownerName}/${repo.name}`,
    agent,
    branches: `contrib/${namespace}/*`,
    git: {
      url,
      push: `git push ${url.replace("://", `://${user.username}:${minted.token}@`)} HEAD:contrib/${namespace}/<topic>`,
    },
    claimed: true,
    renewable: true,
  });
}
/** Extend the token the caller holds by another day, once. */
export function renewContributeToken(
  app: App,
  tokenId: string,
  now: Date = new Date(),
): Result<{ expiresAt: string }, ContributeTokenRefusal> {
  const done = renewContribute(app.db, tokenId, now);
  if (done.ok) return ok({ expiresAt: done.expiresAt });
  return err({ error: done.error === "already_renewed" ? "already_renewed" : "failed" });
}
/** A repository admin's yes or no to outside contributions. */
export function setOutsideContributions(app: App, actor: User | undefined, repo: Repo, on: boolean): Result<{ on: boolean }, "not_found"> {
  if (!canAdmin(app.db, repo, actor)) return err("not_found");
  setContributeOpen(app.db, repo.id, on);
  app.bus.append({ kind: "contribute.open", repoId: repo.id, actorId: actor!.id, payload: { on } });
  return ok({ on });
}
/** A repository admin revokes one outside agent's token; every door says so on the bus. */
export function revokeOutsideToken(app: App, actor: User | undefined, repo: Repo, tokenId: string): Result<{ revoked: true }, "not_found"> {
  if (!canAdmin(app.db, repo, actor)) return err("not_found");
  if (!revokeContribute(app.db, repo.id, tokenId)) return err("not_found");
  app.bus.append({ kind: "contribute.revoked", repoId: repo.id, actorId: actor!.id, payload: { token: tokenId } });
  return ok({ revoked: true });
}
@@ -128,6 +128,11 @@
async function proposalRoute(
}
export interface OpenPullInput {
  /**
   * Set by the handler for an outside agent's contribute token (`http/api.ts`):
   * its limits are the token's, not a guest's.
   */
  outsideAgent?: boolean;
  title: string;
  body?: string;
  baseBranch: string;
@@ -173,6 +178,7 @@
export async function openPull(
  // A guest who cannot write here sends from their own contribution fork, and
  // a low number of pulls a day. Asked first, so a mirror's path never starts.
  const guest =
    input.outsideAgent !== true &&
    !requireAbility(app, user.value, "make_it_yours").ok &&
    (!canWrite(app.db, baseRepo, user.value) || isContributionFork(app.db, baseRepo.id))
      ? takeGuestPull(app, user.value, baseRepo, input.headRepo, Date.now())
@@ -279,6 +279,7 @@
export { route as postApiV1BoardsPins } from "./postApiV1BoardsPins.ts";
export { route as postApiV1BoardsQuery } from "./postApiV1BoardsQuery.ts";
export { route as postApiV1Builds } from "./postApiV1Builds.ts";
export { route as postApiV1Codes } from "./postApiV1Codes.ts";
export { route as postApiV1Contribute } from "./postApiV1Contribute.ts";
export { route as postApiV1ConversationConfirmsId } from "./postApiV1ConversationConfirmsId.ts";
export { route as postApiV1ConversationFiles } from "./postApiV1ConversationFiles.ts";
export { route as postApiV1ConversationMessages } from "./postApiV1ConversationMessages.ts";
@@ -0,0 +1,20 @@
import type { Route } from "../shared.ts";
export const route: Route = {
  method: "post",
  path: "/api/v1/contribute",
  summary:
    "An outside agent's token with no account: for { agent, repo, origin? } (a repository whose owner allows outside agents) answers 201 with a token that lasts 24 hours, may push contrib/<agent>/* there and open pulls from them, shown once; agent and origin are claimed, not verified. Presenting that token renews it, once",
  auth: false,
  role: "anonymous",
  status: 201,
  body: { agent: "string", repo: "string", origin: "string" },
  refusals: {
    invalid_agent: "agent is not an acceptable name (422)",
    invalid_origin: "origin is not plain text of at most 200 characters (422)",
    invalid_repo: "repo is not owner/name (422)",
    not_open: "no such repository, or one that takes no outside contributions (404)",
    rate_limited: "too many tokens from this address (429)",
    already_renewed: "the token was renewed once already (409)",
  },
};
@@ -0,0 +1,251 @@
/**
 * Contribute tokens (#12012): the credential an outside agent with its own
 * sandbox (Codex cloud, Jules, Claude Code, Cursor) is handed to contribute by
 * clone and push. It is an ordinary `rw` token for a throwaway guest account the
 * forge makes, limited by `http/contribute_gate.ts` to: reading public
 * repositories, pushing `contrib/<agent>/…` branches on the one repository that
 * opted in, opening and reading its own pulls there. It expires in a day,
 * renews once, and the agent's name and origin are kept as claimed, never
 * verified. `allows` is the scope check: plain data in, a yes or no out.
 */
import type { Database } from "bun:sqlite";
import { isSafeRef } from "../git/guard.ts";
import { sha256 } from "../kernel/hash.ts";
import { createToken } from "./tokens.ts";
export interface ContributeScope {
  readonly tokenId: string;
  readonly repoId: string;
  readonly agent: string;
  /** `<agent>/<segment>`: the branches under `contrib/` this token alone may touch. */
  readonly namespace: string;
}
/**
 * A segment of the push namespace that only this token has. The agent name is
 * claimed, so two tokens may share one; the segment (from the token's random id)
 * keeps one from force-pushing over or deleting the other's branches.
 */
export const contribSegment = (tokenId: string): string => sha256(`contribute-segment:${tokenId}`).slice(0, 8);
export const contribNamespace = (agent: string, tokenId: string): string => `${agent}/${contribSegment(tokenId)}`;
export const CONTRIBUTE_TTL_MS = 24 * 3600_000;
/** A renewal never carries a token past this long after it was minted. */
export const CONTRIBUTE_MAX_LIFE_MS = 7 * 24 * 3600_000;
export const MINTS_PER_HOUR = 5;
export const MINTS_PER_DAY = 20;
/**
 * Pulls one token may have open, and may open in a day; and all of a repository's
 * outside tokens together in a day.
 */
export const OPEN_PULLS_PER_TOKEN = 5;
export const PULLS_PER_TOKEN_DAY = 20;
export const PULLS_PER_REPO_DAY = 30;
export const AGENT_MAX = 64;
export const ORIGIN_MAX = 200;
/** An agent's claimed name: letters, digits, . _ - ; it starts with a letter or digit. */
export const isAgentName = (name: unknown): name is string =>
  typeof name === "string" && name.length <= AGENT_MAX && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) && !/\.\./.test(name);
/** Where the agent says it runs from: short plain text, nothing a page could misread. */
export const isOrigin = (origin: unknown): origin is string =>
  typeof origin === "string" && origin.length <= ORIGIN_MAX && !/[\x00-\x1f\x7f<>]/.test(origin);
/** Whether `ref` (full `refs/heads/…`) is a branch under `contrib/<agent>/`. */
export function inContribNamespace(ref: string, agent: string): boolean {
  const prefix = `refs/heads/contrib/${agent}/`;
  if (!ref.startsWith(prefix) || ref.length > 200 || !isSafeRef(ref)) return false;
  return ref
    .slice(prefix.length)
    .split("/")
    .every((part) => /^[A-Za-z0-9._-]+$/.test(part) && !/^\.+$/.test(part));
}
/** A pull's head branch name (no `refs/heads/`) inside the namespace. */
export const headInContribNamespace = (head: string, agent: string): boolean =>
  inContribNamespace(`refs/heads/${head}`, agent);
/**
 * Why this token's user may not open another pull on `repoId` now, or undefined.
 * Counted from the pull rows themselves: open ones by this author, and the day's
 * by this author and by every outside token's author on the repository.
 */
export function pullCapReached(
  db: Database,
  repoId: string,
  userId: string,
  now: Date,
): "token_open" | "token_day" | "repo_day" | undefined {
  const count = (sql: string, ...args: string[]): number =>
    db.query<{ n: number }, string[]>(sql).get(...args)?.n ?? 0;
  const since = new Date(now.getTime() - 86_400_000).toISOString();
  const mine = "SELECT COUNT(*) AS n FROM issue WHERE repo_id = ?1 AND kind = 'pull' AND author_id = ?2";
  if (count(`${mine} AND state = 'open'`, repoId, userId) >= OPEN_PULLS_PER_TOKEN) return "token_open";
  if (count(`${mine} AND created_at >= ?3`, repoId, userId, since) >= PULLS_PER_TOKEN_DAY) return "token_day";
  const all = count(
    `SELECT COUNT(*) AS n FROM issue
      WHERE repo_id = ?1 AND kind = 'pull' AND created_at >= ?2
        AND author_id IN (SELECT t.user_id FROM token t JOIN contribute_token c ON c.token_id = t.id WHERE c.repo_id = ?1)`,
    repoId,
    since,
  );
  return all >= PULLS_PER_REPO_DAY ? "repo_day" : undefined;
}
/** What a request is, as the scope check reads it. */
export interface ContributeAsk {
  readonly method: string;
  readonly path: string;
  /** `service` of a git info/refs request. */
  readonly service?: string | null;
  /** The pull number the path names, when that pull is the token's own. */
  readonly ownPull?: boolean;
}
/** Forge-wide reads open to the token. */
const FORGE_READS = new Set(["/api/v1/here", "/api/v1/search", "/api/v1/explore", "/api/v1/openapi.json", "/api/v1/contribute"]);
/**
 * Whether the token may make this request. `repo` is the one it was minted
 * for. Allow-listed: a route added tomorrow is closed to it until written here.
 * Handlers still apply the guest account's own access on top, so a private
 * repository stays hidden.
 */
export function allows(scope: ContributeScope, repo: { owner: string; name: string }, ask: ContributeAsk): boolean {
  const read = ask.method === "GET" || ask.method === "HEAD";
  const path = ask.path.toLowerCase();
  if (read && FORGE_READS.has(path)) return true;
  if (ask.method === "POST" && path === "/api/v1/contribute") return true; // renews
  const at = `/${repo.owner}/${repo.name}`.toLowerCase();
  const api = `/api/v1/repos${at}`;
  // The one repository: push, open a pull, and update or read its own.
  if (read && path === `${at}.git/info/refs` && ask.service === "git-receive-pack") return true;
  // Any public repository may be read: its API, and a fetch.
  if (read && path.startsWith("/api/v1/repos/")) return true;
  if (read && /^\/[^/]+\/[^/]+\.git\/info\/refs$/.test(path)) return ask.service === "git-upload-pack";
  if (ask.method === "POST" && /^\/[^/]+\/[^/]+\.git\/git-upload-pack$/.test(path)) return true;
  if (ask.method === "POST" && path === `${at}.git/git-receive-pack`) return true;
  if (ask.method === "POST" && path === `${api}/pulls`) return true;
  if ((ask.method === "PATCH" || ask.method === "POST") && ask.ownPull === true && path.startsWith(`${api}/pulls/`)) return true;
  return false;
}
/** The pull number a path names under `repo`'s pulls, or undefined. */
export function pullNumberIn(path: string, repo: { owner: string; name: string }): number | undefined {
  const head = `/api/v1/repos/${repo.owner}/${repo.name}/pulls/`.toLowerCase();
  const lower = path.toLowerCase();
  if (!lower.startsWith(head)) return undefined;
  const m = /^([1-9][0-9]{0,8})(?:\/|$)/.exec(lower.slice(head.length));
  return m ? Number(m[1]) : undefined;
}
// ---- the rows ----
/** A source (an address) is kept only as a hash: enough to count, never to read. */
const sourceKey = (source: string): string => sha256(`contribute-source:${source}`).slice(0, 24);
export const contributeOpen = (db: Database, repoId: string): boolean =>
  db.query("SELECT 1 FROM contribute_open WHERE repo_id = ?1").get(repoId) !== null;
export function setContributeOpen(db: Database, repoId: string, on: boolean): void {
  if (on) db.query("INSERT OR IGNORE INTO contribute_open (repo_id) VALUES (?1)").run(repoId);
  else db.query("DELETE FROM contribute_open WHERE repo_id = ?1").run(repoId);
}
export function mintsSince(db: Database, since: number, source: string): number {
  return (
    db
      .query<{ n: number }, [string, number]>("SELECT COUNT(*) AS n FROM contribute_mint WHERE source = ?1 AND made_at >= ?2")
      .get(sourceKey(source), since)?.n ?? 0
  );
}
export interface Minted {
  readonly id: string;
  readonly token: string;
  readonly expiresAt: string;
}
/** Mint the token for `userId` on `repoId`, and count it against `source`. */
export function mintContribute(
  db: Database,
  input: { userId: string; repoId: string; agent: string; origin: string; source: string },
  now: Date,
): Minted {
  const expiresAt = new Date(now.getTime() + CONTRIBUTE_TTL_MS).toISOString();
  const minted = createToken(db, input.userId, `contribute:${input.agent}`, "rw", { expiresAt });
  db.query(
    "INSERT INTO contribute_token (token_id, repo_id, agent, origin, minted_at) VALUES (?1, ?2, ?3, ?4, ?5)",
  ).run(minted.id, input.repoId, input.agent, input.origin, now.toISOString());
  db.query("INSERT INTO contribute_mint (source, made_at) VALUES (?1, ?2)").run(sourceKey(input.source), now.getTime());
  // The ledger only needs the last day.
  db.query("DELETE FROM contribute_mint WHERE made_at < ?1").run(now.getTime() - 2 * 24 * 3600_000);
  return { ...minted, expiresAt };
}
/** Extend a token by another day, once, never past a week from its minting. */
export function renewContribute(
  db: Database,
  tokenId: string,
  now: Date,
): { ok: true; expiresAt: string } | { ok: false; error: "already_renewed" | "not_found" } {
  const row = db
    .query<{ minted_at: string; renewed: number }, [string]>("SELECT minted_at, renewed FROM contribute_token WHERE token_id = ?1")
    .get(tokenId);
  if (row === null) return { ok: false, error: "not_found" };
  if (row.renewed !== 0) return { ok: false, error: "already_renewed" };
  const until = Math.min(now.getTime() + CONTRIBUTE_TTL_MS, Date.parse(row.minted_at) + CONTRIBUTE_MAX_LIFE_MS);
  const expiresAt = new Date(until).toISOString();
  db.transaction(() => {
    db.query("UPDATE token SET expires_at = ?1 WHERE id = ?2").run(expiresAt, tokenId);
    db.query("UPDATE contribute_token SET renewed = 1 WHERE token_id = ?1").run(tokenId);
  })();
  return { ok: true, expiresAt };
}
export interface ContributeTokenInfo {
  readonly id: string;
  readonly agent: string;
  /** As the agent claimed it; never verified. */
  readonly origin: string;
  readonly mintedAt: string;
  readonly expiresAt: string;
  readonly lastUsedAt: string | null;
  readonly renewed: boolean;
}
/** The live tokens on a repository: unexpired, newest first. */
export function listContribute(db: Database, repoId: string, now: Date): ContributeTokenInfo[] {
  return db
    .query<
      { id: string; agent: string; origin: string; minted_at: string; expires_at: string; last_used_at: string | null; renewed: number },
      [string, string]
    >(
      `SELECT c.token_id AS id, c.agent, c.origin, c.minted_at, t.expires_at, t.last_used_at, c.renewed
         FROM contribute_token c JOIN token t ON t.id = c.token_id
        WHERE c.repo_id = ?1 AND t.expires_at > ?2 ORDER BY c.minted_at DESC, c.token_id DESC`,
    )
    .all(repoId, now.toISOString())
    .map((r) => ({
      id: r.id,
      agent: r.agent,
      origin: r.origin,
      mintedAt: r.minted_at,
      expiresAt: r.expires_at,
      lastUsedAt: r.last_used_at,
      renewed: r.renewed === 1,
    }));
}
/** Revoke one token of `repoId`; false when it is not one of that repository's. */
export function revokeContribute(db: Database, repoId: string, tokenId: string): boolean {
  const own = db
    .query("SELECT 1 FROM contribute_token WHERE token_id = ?1 AND repo_id = ?2")
    .get(tokenId, repoId);
  if (own === null) return false;
  db.query("DELETE FROM token WHERE id = ?1").run(tokenId);
  return db.query("SELECT 1 FROM token WHERE id = ?1").get(tokenId) === null;
}
@@ -270,6 +270,8 @@
export function classifiedAudience(kind: string): EventAudience | undefined {
    kind === "repo.source_added" ||
    kind === "repo.source_removed" ||
    kind === "repo.crew_outsiders" ||
    // An outside agent's token and the owner's yes to them are the admins' (#12012).
    kind.startsWith("contribute.") ||
    // A valve turn names a repository and the owner's budget: for those who administer it (`actions/valves.ts`).
    kind === "valve.turned" ||
    // A clog starting names the forge's own pile-up: the owner's to hear (#6524).
@@ -0,0 +1,1 @@
554897fea4417afac1f59ee8109d32bfad31859aee147c859236f3e96c1802af
@@ -0,0 +1,28 @@
// Outside agents' short-lived contribute tokens (#12012). `contribute_open` is a repository
// owner's yes to them; `contribute_token` names what an ordinary token is limited to (the
// repository, the agent name and origin as claimed, whether it has been renewed); `contribute_mint`
// counts mints per hashed address. Deleting a repository deletes its tokens. New tables only.
export default `
  CREATE TABLE contribute_open (
    repo_id TEXT PRIMARY KEY REFERENCES repo(id) ON DELETE CASCADE
  );
  CREATE TABLE contribute_token (
    token_id  TEXT PRIMARY KEY REFERENCES token(id) ON DELETE CASCADE,
    repo_id   TEXT NOT NULL,
    agent     TEXT NOT NULL,
    origin    TEXT NOT NULL,
    minted_at TEXT NOT NULL,
    renewed   INTEGER NOT NULL DEFAULT 0
  );
  CREATE INDEX contribute_token_repo ON contribute_token(repo_id);
  CREATE TABLE contribute_mint (
    source  TEXT NOT NULL,
    made_at INTEGER NOT NULL
  );
  CREATE INDEX contribute_mint_source ON contribute_mint(source, made_at);
  CREATE TRIGGER contribute_token_repo_gone BEFORE DELETE ON repo
  BEGIN
    DELETE FROM token WHERE id IN (SELECT token_id FROM contribute_token WHERE repo_id = OLD.id);
  END;
  `;
@@ -9,6 +9,7 @@
import { sha256 } from "../kernel/hash.ts";
import { id, secret } from "../kernel/id.ts";
import { err, ok, type Result } from "../kernel/result.ts";
import type { Proposal } from "./proposal_token.ts";
import { contribNamespace, type ContributeScope } from "./contribute_token.ts";
import type { RunScope } from "./run_token.ts";
import { getUserById, isActive, type User } from "./users.ts";
@@ -71,7 +72,7 @@
export function verifyToken(
  db: Database,
  presented: string,
): Result<
  { user: User; scope: TokenScope; name: string; proposal?: Proposal; run?: RunScope; via?: string },
  { user: User; scope: TokenScope; name: string; proposal?: Proposal; run?: RunScope; via?: string; contribute?: ContributeScope },
  "invalid_token"
> {
  const row = db
@@ -89,15 +90,19 @@
export function verifyToken(
        r_repo: string | null;
        r_fork: string | null;
        v_via: string | null;
        c_repo: string | null;
        c_agent: string | null;
      },
      [string]
    >(
      `SELECT t.id, t.user_id, t.name, t.scope, t.last_used_at, t.expires_at,
              p.repo_id AS p_repo, p.child AS p_child, p.origin AS p_origin,
              r.repo_id AS r_repo, r.fork_id AS r_fork, v.via AS v_via
              r.repo_id AS r_repo, r.fork_id AS r_fork, v.via AS v_via,
              c.repo_id AS c_repo, c.agent AS c_agent
         FROM token t LEFT JOIN proposal_token p ON p.token_id = t.id
                      LEFT JOIN run_token r ON r.token_id = t.id
                      LEFT JOIN via_token v ON v.token_id = t.id
                      LEFT JOIN contribute_token c ON c.token_id = t.id
        WHERE t.token_hash = ?1`,
    )
    .get(sha256(presented));
@@ -139,6 +144,19 @@
export function verifyToken(
      scope: row.scope,
      run: { repoId: row.r_repo, forkId: row.r_fork! },
    });
  // An outside agent's token is bound to one repository (`http/contribute_gate.ts`).
  if (row.c_repo !== null)
    return ok({
      user,
      name: row.name,
      scope: row.scope,
      contribute: {
        tokenId: row.id,
        repoId: row.c_repo,
        agent: row.c_agent!,
        namespace: contribNamespace(row.c_agent!, row.id),
      },
    });
  // The forge's own agent, speaking for this person (`core/via_token.ts`).
  if (row.v_via !== null) return ok({ user, name: row.name, scope: row.scope, via: row.v_via });
  return ok({ user, name: row.name, scope: row.scope });
@@ -17,6 +17,8 @@
export interface HookRequest {
  readonly actorId: string;
  /** A proposal token's child: every ref must be inside `child/<name>/`. */
  readonly proposalChild?: string;
  /** An outside agent's name: every ref must be inside `contrib/<agent>/`. */
  readonly contribAgent?: string;
  readonly updates: readonly RefUpdate[];
  /**
   * Quarantine environment forwarded from the hook process. Any git command
@@ -62,6 +62,8 @@
export function hookEnv(input: {
  actorId: string;
  /** Set for a proposal token: the one namespace its push may touch. */
  proposalChild?: string;
  /** Set for an outside agent's contribute token: the one namespace its push may touch. */
  contribAgent?: string;
}): Record<string, string> {
  const self = selfInvocation();
  const env: Record<string, string> = {
@@ -73,6 +75,7 @@
export function hookEnv(input: {
  };
  if (input.proposalChild !== undefined)
    env.FORGE_PROPOSAL_CHILD = input.proposalChild;
  if (input.contribAgent !== undefined) env.FORGE_CONTRIB_AGENT = input.contribAgent;
  if (self.entry !== undefined) env.FORGE_ENTRY = self.entry;
  return env;
}
@@ -127,6 +130,9 @@
export async function runHookClient(hook: HookName): Promise<never> {
        ...(process.env.FORGE_PROPOSAL_CHILD !== undefined
          ? { proposalChild: process.env.FORGE_PROPOSAL_CHILD }
          : {}),
        ...(process.env.FORGE_CONTRIB_AGENT !== undefined
          ? { contribAgent: process.env.FORGE_CONTRIB_AGENT }
          : {}),
        updates: parseHookStdin(stdin),
        gitEnv,
      }),
@@ -193,6 +193,12 @@
import {
  pullProposalOf,
  recordPullProposal,
} from "../core/proposal_token.ts";
import { OPEN_PULLS_PER_TOKEN, headInContribNamespace, pullCapReached } from "../core/contribute_token.ts";
/** Tokens with a pull being opened now: one at a time, so the count cannot be raced. */
const contributePulling = new Set<string>();
import { takesOutside } from "../actions/contribute_token.ts";
import { contributeMint } from "./api/contribute_token.ts";
import {
  getUserByName,
  hiddenFrom,
@@ -1326,6 +1332,9 @@
export function apiRoutes(router: Router<Handler>): void {
    return timePhase(ctx.request, "render", () => json(body));
  });
  // An outside agent's short-lived token (#12012): mint, or renew the one presented.
  router.add("POST", "/api/v1/contribute", contributeMint);
  boardRoutes(router);
  displayRoutes(router);
@@ -2657,6 +2666,10 @@
export function apiRoutes(router: Router<Handler>): void {
    if (denied) return denied;
    const repo = loadRepo(ctx);
    if (!repo) return notFound();
    // An outside agent's token opens a pull from its own contrib/<agent>/… branch of this
    // repository, never from another repository, and never past what it was minted for.
    const outside = ctx.auth.contribute;
    if (outside !== undefined && (outside.repoId !== repo.id || !takesOutside(ctx.app, repo))) return forbidden();
    // A proposal token's body is small, and its pull comes from a branch of
    // its own child's namespace in this repository, never from another one.
    const proposal = ctx.auth.proposal;
@@ -2669,6 +2682,15 @@
export function apiRoutes(router: Router<Handler>): void {
        : await boundedBody(ctx.request, PROPOSAL_BODY_MAX);
    if (input === "too_large")
      return apiError("too_large", 413, `at most ${PROPOSAL_BODY_MAX} bytes`);
    if (
      outside !== undefined &&
      (str(input.headRepo) !== "" || !headInContribNamespace(str(input.head), outside.namespace))
    )
      return apiError(
        "invalid_head",
        422,
        `a contribute pull comes from a contrib/${outside.namespace}/… branch of this repository`,
      );
    if (
      proposal !== undefined &&
      (str(input.headRepo) !== "" ||
@@ -2695,15 +2717,38 @@
export function apiRoutes(router: Router<Handler>): void {
      if (run !== undefined && headRepo.id !== run.forkId && headRepo.id !== run.repoId)
        return notFound();
    }
    const created = await openPull(ctx.app, ctx.auth.user, repo, {
      title: str(input.title),
    // An outside agent opens a few pulls: each starts checks and a preview on the
    // owner's repository. Counted from the pull rows, one open at a time per token.
    if (outside !== undefined) {
      const capped = pullCapReached(ctx.app.db, repo.id, ctx.auth.user!.id, new Date());
      if (capped !== undefined || contributePulling.has(outside.tokenId))
        return tryAgain(
          "rate_limited",
          429,
          capped === "repo_day"
            ? "this repository has taken as many pulls from outside agents as it takes in a day; try tomorrow"
            : capped === "token_open"
              ? `this token has ${OPEN_PULLS_PER_TOKEN} pulls open; wait for one to close`
              : "too many pulls opened by this token; try again later",
          capped === undefined ? 1 : 3600,
        );
      contributePulling.add(outside.tokenId);
    }
    let created: Awaited<ReturnType<typeof openPull>>;
    try {
      created = await openPull(ctx.app, ctx.auth.user, repo, {
        title: str(input.title),
      body: str(input.body),
      baseBranch: str(input.base),
      headBranch: str(input.head),
      ...(headRepo ? { headRepo } : {}),
      // A person's deliberate yes to fixing a sealed report from a public branch.
      ...(input.confirmPublic === true ? { confirmPublic: true } : {}),
      ...(outside === undefined ? {} : { outsideAgent: true }),
    });
    } finally {
      if (outside !== undefined) contributePulling.delete(outside.tokenId);
    }
    if (!created.ok && created.error === "sealed_in_public")
      return apiError(
        "sealed_in_public",
@@ -0,0 +1,41 @@
/**
 * `POST /api/v1/contribute` (#12012): an outside agent names itself and a
 * repository that takes outside contributions and gets a token for a day, with
 * no account. With a contribute token presented, the same call renews that
 * token once instead. The rules and limits are `actions/contribute_token.ts`.
 * A browser page from another site is refused: an agent is not one.
 */
import {
  CONTRIBUTE_TOKEN_HINT,
  CONTRIBUTE_TOKEN_WORDS,
  mintContributeToken,
  renewContributeToken,
} from "../../actions/contribute_token.ts";
import { REQUEST_MAX } from "../../core/reports.ts";
import { crossOrigin, type Handler } from "../context.ts";
import { clientBucket } from "../peer.ts";
import { apiError, boundedBody, json, tryAgain } from "../respond.ts";
export const contributeMint: Handler = async (ctx) => {
  if (crossOrigin(ctx.request, ctx.url, ctx.app.log))
    return apiError("forbidden", 403, "send this call from your agent, not from a page on another site");
  const noStore = { "cache-control": "no-store" };
  const held = ctx.auth.contribute;
  if (held !== undefined) {
    const renewed = renewContributeToken(ctx.app, held.tokenId);
    if (renewed.ok) return json({ renewed: true, expiresAt: renewed.value.expiresAt }, 200, noStore);
    return apiError(renewed.error.error, 409, CONTRIBUTE_TOKEN_WORDS[renewed.error.error]);
  }
  // Any other credential is not an outside agent's: the call is for those without one.
  if (ctx.auth.user !== undefined) return apiError("forbidden", 403, "you are signed in: use your own token to push");
  const input = await boundedBody(ctx.request, REQUEST_MAX);
  if (input === "too_large") return apiError("too_large", 413, CONTRIBUTE_TOKEN_HINT);
  const made = await mintContributeToken(ctx.app, input, clientBucket(ctx.request), ctx.url.origin);
  if (made.ok) return json(made.value, 201, noStore);
  const refusal = made.error;
  const said = CONTRIBUTE_TOKEN_WORDS[refusal.error];
  if (refusal.error === "rate_limited") return tryAgain("rate_limited", 429, said, refusal.retryAfter ?? 3600);
  if (refusal.error === "not_open") return apiError("not_open", 404, said);
  if (refusal.error === "failed") return apiError("failed", 500, said);
  return apiError(refusal.error, 422, `${said}; ${CONTRIBUTE_TOKEN_HINT}`);
};
@@ -3,6 +3,7 @@
 * route params, and authentication resolved once as plain data.
 */
import type { ContributeScope } from "../core/contribute_token.ts";
import type { Proposal } from "../core/proposal_token.ts";
import type { App } from "../app.ts";
import type { RunScope } from "../core/run_token.ts";
@@ -29,6 +30,8 @@
export interface Auth {
  /** Set for a crew run's token: the repositories it may reach
   * (`http/run_gate.ts`). */
  readonly run?: RunScope;
  /** Set for an outside agent's contribute token (`http/contribute_gate.ts`). */
  readonly contribute?: ContributeScope;
  /** Set for a via token: the forge's own agent, speaking for this person in
   * this conversation (`conversation:<id>`, `core/via_token.ts`). */
  readonly through?: string;
@@ -0,0 +1,65 @@
/**
 * The one gate every contribute-token request passes, before any handler
 * (#12012). The token (`core/contribute_token.ts`) reads public repositories,
 * pushes and opens pulls on the one repository it was minted for, and reads or
 * updates its own pulls there; `allows` is the list, and everything else
 * answers `forbidden`. Its requests are limited per token per minute. Which
 * refs a push may touch is decided at the ref update (`handleHook`), and which
 * branch a pull may come from, in the pulls handler.
 */
import type { App } from "../app.ts";
import { allows, pullNumberIn } from "../core/contribute_token.ts";
import { getPull } from "../core/pulls.ts";
import { getRepoById } from "../core/repos.ts";
import { RateLimiter } from "../core/ratelimit.ts";
import type { Auth } from "./context.ts";
import { apiError, tryAgain } from "./respond.ts";
const limiters = new WeakMap<App, RateLimiter>();
/** Requests per token per minute. Not switched off by FORGE_RATE_LIMIT=0. */
export const CONTRIBUTE_PER_MINUTE = 120;
function limiter(app: App): RateLimiter {
  let one = limiters.get(app);
  if (one === undefined) {
    one = new RateLimiter({ perMinute: CONTRIBUTE_PER_MINUTE, adminPerMinute: CONTRIBUTE_PER_MINUTE, enabled: true });
    limiters.set(app, one);
  }
  return one;
}
const refuse = (): Response =>
  apiError(
    "forbidden",
    403,
    "a contribute token reads public repositories, pushes contrib/<agent>/<token>/… branches on its repository and opens or updates its own pulls there",
  );
/** The refusal for this request, or undefined when it may proceed. */
export function contributeGate(app: App, request: Request, url: URL, auth: Auth): Response | undefined {
  const scope = auth.contribute;
  if (scope === undefined) return undefined;
  const repo = getRepoById(app.db, scope.repoId);
  if (repo === undefined) return refuse();
  const verdict = limiter(app).take(scope.tokenId, "rw");
  if (!verdict.allowed)
    return tryAgain(
      "rate_limited",
      429,
      `too many requests: ${verdict.limit} per minute per token; retry in ${verdict.retryAfter}s`,
      verdict.retryAfter,
    );
  const at = { owner: repo.ownerName, name: repo.name };
  const number = pullNumberIn(url.pathname, at);
  const pull = number === undefined ? undefined : getPull(app.db, repo.id, number);
  const ownPull = pull !== undefined && pull.authorId === auth.user?.id;
  const ok = allows(scope, at, {
    method: request.method,
    path: url.pathname,
    service: url.searchParams.get("service"),
    ownPull,
  });
  return ok ? undefined : refuse();
}
@@ -34,6 +34,7 @@
import { TOKEN_FREE_TOOLS } from "../core/mcp_card.ts";
import { proofOf } from "./report_filer.ts";
import { fileReport } from "../actions/reports.ts";
import { START_HINT, START_WORDS, startBuilding } from "../actions/start.ts";
import { CONTRIBUTE_TOKEN_HINT, CONTRIBUTE_TOKEN_WORDS, mintContributeToken } from "../actions/contribute_token.ts";
import { REPORT_RECEIVED } from "../actions/report_words.ts";
import { BODY_MAX, REQUEST_MAX, TITLE_MAX } from "../core/reports.ts";
import { everydayOf } from "../core/everyday.ts";
@@ -317,8 +318,8 @@
export const START_TOOL = {
      description: { type: "string", maxLength: 2000 },
      agent: { type: "string", maxLength: 64 },
      code: { type: "string", maxLength: 100 },
      action: { type: "string", enum: ["contribute"] },
    },
    required: ["name"],
  },
} as const;
@@ -408,6 +409,16 @@
async function startAnswer(ctx: Ctx, id: unknown, args: Args): Promise<unknown>
    id,
    result: { content: [{ type: "text", text: t }], ...(isError ? { isError } : {}) },
  });
  if (args["action"] === "contribute") {
    const made = await mintContributeToken(ctx.app, args, clientBucket(ctx.request), ctx.url.origin);
    if (made.ok) return text(JSON.stringify(made.value));
    const said = CONTRIBUTE_TOKEN_WORDS[made.error.error];
    return text(
      `${made.error.error}: ${said}${made.error.retryAfter === undefined ? "" : ` (try again in ${made.error.retryAfter} seconds)`} ${CONTRIBUTE_TOKEN_HINT}`,
      true,
    );
  }
  if (typeof args["name"] !== "string") return text(`invalid_name: ${START_WORDS.invalid_name} ${START_HINT}`, true);
  const started = await startBuilding(ctx.app, args, clientBucket(ctx.request), ctx.url.origin);
  if (started.ok) return text(JSON.stringify(started.value));
  const e = started.error;
@@ -498,11 +498,14 @@
import { targetForShortCode } from "../origins/oauth.ts";
import { apiRoutes } from "./api.ts";
import { pageParamRefused } from "./cursor_lists.ts";
import { inNamespace } from "../core/proposal_token.ts";
import { proposalTokenMint, proposalTokenRevoke } from "../web/pages/proposal-tokens.ts";
import { inContribNamespace } from "../core/contribute_token.ts";
import { takesOutside } from "../actions/contribute_token.ts";
import { contributeOpenSet, contributeTokenRevoke, proposalTokenMint, proposalTokenRevoke } from "../web/pages/proposal-tokens.ts";
import { adminGate } from "./admin_gate.ts";
import { movedResponse } from "./moved.ts";
import { originGate } from "./origin_gate.ts";
import { proposalGate } from "./proposal_gate.ts";
import { contributeGate } from "./contribute_gate.ts";
import { runGate } from "./run_gate.ts";
import { viaGate } from "./via_gate.ts";
import { checksRecheckRoutes } from "./checks_recheck.ts";
@@ -693,6 +696,7 @@
async function resolveAuth(app: App, request: Request): Promise<Auth> {
        tokenName: verified.value.name,
        ...(verified.value.proposal ? { proposal: verified.value.proposal } : {}),
        ...(verified.value.run ? { run: verified.value.run } : {}),
        ...(verified.value.contribute ? { contribute: verified.value.contribute } : {}),
        ...(verified.value.via ? { through: verified.value.via } : {}),
      };
    }
@@ -721,6 +725,7 @@
async function resolveAuth(app: App, request: Request): Promise<Auth> {
            ? { proposal: verified.value.proposal }
            : {}),
          ...(verified.value.run ? { run: verified.value.run } : {}),
          ...(verified.value.contribute ? { contribute: verified.value.contribute } : {}),
          ...(verified.value.via ? { through: verified.value.via } : {}),
        };
      }
@@ -1213,6 +1218,7 @@
export function buildRouter(): Router<Handler> {
            repoId,
            actorId: ctx.auth.user?.id ?? "",
            ...(ctx.auth.proposal ? { proposalChild: ctx.auth.proposal.child } : {}),
            ...(ctx.auth.contribute ? { contribAgent: ctx.auth.contribute.namespace } : {}),
          }),
          ...cap,
        },
@@ -1582,6 +1588,8 @@
export function buildRouter(): Router<Handler> {
    "/:owner/:name/settings/proposal-tokens/:id/delete",
    proposalTokenRevoke,
  );
  router.add("POST", "/:owner/:name/settings/contribute-tokens/open", contributeOpenSet);
  router.add("POST", "/:owner/:name/settings/contribute-tokens/:id/delete", contributeTokenRevoke);
  router.add("GET", "/:owner/:name/settings/app", appSettingsPage);
  router.add("GET", "/:owner/:name/settings/app/traffic", appSourcesPage);
  router.add("GET", "/:owner/:name/settings/app/statement", statementPage);
@@ -1787,8 +1795,11 @@
async function withGitAccess(
  if (write) {
    if (!ctx.auth.user) return gitChallenge();
    if (isPacksMirror(repo) && canRead(ctx.app.db, repo, ctx.auth.user)) return gitRefused(ctx, MIRROR_PUSH_REFUSED);
    // An outside agent's token may push its one repository;
    // which refs is the hook's (`contribAgent`).
    const outside = ctx.auth.contribute?.repoId === repo.id && takesOutside(ctx.app, repo);
    if (
      !canWrite(ctx.app.db, repo, ctx.auth.user) ||
      !(outside || canWrite(ctx.app.db, repo, ctx.auth.user)) ||
      !scopeAllows(ctx.auth.scope ?? "ro", "rw")
    ) {
      return notFound();
@@ -2108,6 +2119,16 @@
async function handleHook(app: App, request: Request): Promise<Response> {
          { status: 403 },
        );
      }
      // An outside agent's token pushes inside `contrib/<agent>/` and nowhere else.
      if (
        input.contribAgent !== undefined &&
        !inContribNamespace(update.ref, input.contribAgent)
      ) {
        return new Response(
          `${update.ref}: this token pushes only contrib/${input.contribAgent}/… branches`,
          { status: 403 },
        );
      }
      // The pull namespace belongs to the forge, never to pushers.
      if (update.ref.startsWith("refs/pull/")) {
        return new Response(`${update.ref}: refs/pull/* is reserved`, {
@@ -3019,6 +3040,9 @@
async function answerGet(
  // request it makes ends here, before the limiter or any handler.
  const proposalRefusal = proposalGate(app, request, url, auth);
  if (proposalRefusal !== undefined) return proposalRefusal;
  // An outside agent's token reaches public reads and its one repository.
  const contributeRefusal = contributeGate(app, request, url, auth);
  if (contributeRefusal !== undefined) return contributeRefusal;
  // A crew run's token reaches its own repository and nothing else.
  const runRefusal = runGate(app, request, url, auth);
  if (runRefusal !== undefined) return runRefusal;
@@ -0,0 +1,117 @@
/**
 * Outside agents, in the terminal (#12012): the settings page's block
 * (`web/pages/proposal-tokens.ts`) from the same actions
 * (`actions/contribute_token.ts`), gated the same way: a repository's admins.
 * `a` allows outside agents or stops allowing them; `x` revokes the token under
 * the cursor, after a confirm. Each write is an event on the bus, so an open
 * settings page redraws, and this screen follows a write made there.
 */
import { revokeOutsideToken, setOutsideContributions, takesOutside } from "../../actions/contribute_token.ts";
import { contributeOpen, listContribute, type ContributeTokenInfo } from "../../core/contribute_token.ts";
import { canAdmin, type Repo } from "../../core/repos.ts";
import type { Ctx, Screen } from "../app/app.ts";
import { binding } from "../app/keys.ts";
import type { Command } from "../app/palette.ts";
import type { Session } from "../session.ts";
import { style } from "../term/style.ts";
import { truncate } from "../term/width.ts";
import { fill, len, split } from "../ui/layout.ts";
import { ListState, confirmScreen, drawList, later, live, type ListRow } from "./common.ts";
/** Settings › Outside agents' gate: an admin of the repository. */
export const mayManageOutside = (f: Session, repo: Repo): boolean => f.user !== undefined && canAdmin(f.db, repo, f.user);
/**
 * The live tokens, for an admin; none for anyone else, and none while outside
 * agents are not allowed.
 */
export function outsideRows(f: Session, repo: Repo): ContributeTokenInfo[] {
  return mayManageOutside(f, repo) && contributeOpen(f.db, repo.id) ? listContribute(f.db, repo.id, new Date()) : [];
}
export function outsideAgentsScreen(f: Session, ctx: Ctx, repo: Repo): Screen {
  const state = new ListState();
  const where = `${repo.ownerName}/${repo.name}`;
  const screen: Screen = {
    title: `${where} — Outside agents`,
    keys: [binding(["j", "k"], "move cursor"), binding(["a"], "allow or stop allowing"), binding(["x"], "revoke token")],
    async load(signal) {
      live(f, signal, { repoId: repo.id, where: (e) => e.kind.startsWith("contribute.") }, () => ctx.invalidate());
    },
    render(area, s) {
      const c = ctx.theme.c;
      const may = mayManageOutside(f, repo);
      const open = contributeOpen(f.db, repo.id);
      const [head, list] = split(area, "v", [len(1), fill(1)]);
      const said = !may
        ? "An admin of this repository manages outside agents."
        : !open
          ? "Outside agents may not ask for a token. a allows them."
          : takesOutside(f.app, repo)
            ? "Outside agents may ask for a day's token. a stops allowing them; x revokes."
            : "Allowed, but not offered now: only a public, original, unarchived repository takes them.";
      s.text(head!.x, head!.y, truncate(said, head!.w), style(c.mutedFg, c.bg), head!.x + head!.w);
      const rows: ListRow[] = outsideRows(f, repo).map((t) => ({
        title: t.agent,
        note: `${t.origin === "" ? "no origin given" : t.origin} · claimed, not verified`,
        meta: `expires ${t.expiresAt.slice(0, 16).replace("T", " ")}`,
      }));
      drawList(s, list!, c, state, rows);
    },
    key(e) {
      const all = outsideRows(f, repo);
      if (state.key(e, all.length)) return true;
      if (e.ctrl || e.alt || (e.key !== "a" && e.key !== "x")) return false;
      if (!mayManageOutside(f, repo)) {
        ctx.toast("An admin of this repository manages outside agents.", "danger");
        return true;
      }
      if (e.key === "a") {
        const on = !contributeOpen(f.db, repo.id);
        const set = setOutsideContributions(f.app, f.user, repo, on);
        ctx.toast(
          !set.ok
            ? "An admin of this repository manages outside agents."
            : on
              ? "Outside agents may ask for a token."
              : "Outside agents may no longer ask. Tokens already made work until revoked.",
          set.ok ? undefined : "danger",
        );
        ctx.invalidate();
        return true;
      }
      const at = all[state.index];
      if (at === undefined) return true;
      void later(ctx, () =>
        confirmScreen(ctx, screen, {
          title: "Revoke token",
          body: [`${at.agent}'s token stops working now. Pulls it opened stay.`],
          actions: [{ label: "Cancel", variant: "ghost" }, { label: "Revoke" }],
          selected: 0,
          onChoose: (i) => {
            if (i !== 1) return;
            const done = revokeOutsideToken(f.app, f.user, repo, at.id);
            ctx.toast(done.ok ? `${at.agent}'s token revoked.` : "No such token.", done.ok ? undefined : "danger");
            ctx.invalidate();
          },
        }),
      );
      return true;
    },
  };
  return screen;
}
/** The palette's command while a repository the viewer administers is open. */
export function outsideAgentsCommands(f: Session, ctx: Ctx, repo: Repo | undefined): Command[] {
  if (repo === undefined || !mayManageOutside(f, repo)) return [];
  return [
    {
      id: "outside-agents",
      title: `${repo.ownerName}/${repo.name} — Outside agents`,
      hint: "allow outside agents' day tokens, see and revoke the live ones",
      run: () => ctx.push(outsideAgentsScreen(f, ctx, repo)),
    },
  ];
}
@@ -171,6 +171,7 @@
import { variantsCommands } from "./variants.ts";
import { autonomyCommands } from "./autonomy.ts";
import { trafficCommands } from "./trafficview.ts";
import { chaptersCommands } from "./chapters.ts";
import { outsideAgentsCommands } from "./outsideagents.ts";
import { schedulesCommands } from "./schedules.ts";
import { landCommands } from "./landasis.ts";
import { shiftCommands } from "./subtitle_shift.ts";
@@ -2003,6 +2004,7 @@
export function workspaceScreen(
      ...autonomyCommands(f, ctx, repo),
      ...trafficCommands(f, ctx, repo),
      ...schedulesCommands(f, ctx, repo),
      ...outsideAgentsCommands(f, ctx, repo),
      ...landCommands(f, ctx, repo),
      ...shiftCommands(f, ctx, repo, () => screen),
      ...dataImportCommands(f, ctx, repo),
@@ -0,0 +1,22 @@
/**
 * Settings: the outside agents' block (#12012) follows tokens made or revoked from any
 * door without a reload. Its own stream, only on a settings page that has the block, so
 * the repository page's script carries none of it.
 */
export const outsideAgentsJs = /* js */ `
(function () {
  if (!document.getElementById('contribute-tokens')) return;
  var es = new EventSource(location.pathname.split('/').slice(0, 3).join('/') + '/stream');
  function refresh() {
    fetch(location.pathname).then(function (r) { return r.text(); }).then(function (t) {
      var h = document.createElement('div');
      h.innerHTML = t;
      var mine = document.getElementById('contribute-tokens'), next = h.querySelector('#contribute-tokens');
      if (mine && next && mine.innerHTML !== next.innerHTML) mine.replaceWith(next);
    }).catch(function () {});
  }
  ['contribute.open', 'contribute.token', 'contribute.revoked'].forEach(function (k) {
    es.addEventListener(k, refresh);
  });
})();
`;
@@ -6,21 +6,60 @@
 */
import { listProposals, mintProposal, revokeProposal } from "../../actions/proposal_tokens.ts";
import { canWrite, type Repo } from "../../core/repos.ts";
import { revokeOutsideToken, setOutsideContributions, takesOutside } from "../../actions/contribute_token.ts";
import { contributeOpen, listContribute } from "../../core/contribute_token.ts";
import { canAdmin, canWrite, type Repo } from "../../core/repos.ts";
import { isAccountItself, type Ctx } from "../../http/context.ts";
import { loadRepo, repoBase, repoNotFound, NOT_YOURS_TO_DO, forbiddenPage } from "../chrome.ts";
import { field, readForm } from "../form.ts";
import { html, type Html } from "../html.ts";
import { liveMount } from "../live.ts";
import { flashTo } from "../layout.ts";
import { btn, confirmAction, field as formField, time } from "../ui.ts";
/**
 * Outside agents' contribute tokens (#12012): the owner's yes, and each live token
 * with Revoke (after a confirm). Admins only.
 */
function contributeTokensSection(ctx: Ctx, repo: Repo): Html | null {
  if (!canAdmin(ctx.app.db, repo, ctx.auth.user)) return null;
  const base = repoBase(repo);
  const open = contributeOpen(ctx.app.db, repo.id);
  const tokens = open ? listContribute(ctx.app.db, repo.id, new Date()) : [];
  return html`<section class="settings-block mb" id="contribute-tokens">
    <form method="post" action="${base}/settings/contribute-tokens/open">
      <input type="hidden" name="on" value="${open ? "0" : "1"}" />
      <p class="muted"><strong>Outside agents</strong> with their own sandbox may ask for a token that lasts a day, push <code>contrib/&lt;name&gt;/…</code> branches here and open pulls, with no account. Names and origins are claimed, not verified.${open && !takesOutside(ctx.app, repo)
        ? " Not offered now: only a public, original, unarchived repository takes them."
        : ""} ${btn(open ? "Stop allowing" : "Allow", { variant: open ? "secondary" : "primary", size: "sm" })}</p>
    </form>
    ${tokens.length === 0
      ? null
      : html`<dl class="status-rows">
          ${tokens.map(
            (t) => html`<div class="status-row">
              <dt>${t.agent}</dt>
              <dd>
                <span class="mono">${t.origin === "" ? "no origin given" : t.origin}</span>
                <span class="muted">· claimed, not verified · expires ${time(t.expiresAt)} · last used ${t.lastUsedAt ? time(t.lastUsedAt) : "never"}</span>
              </dd>
              <dd class="status-act">
                ${confirmAction({ action: `${base}/settings/contribute-tokens/${t.id}/delete`, verb: "Revoke", size: "sm" })}
              </dd>
            </div>`,
          )}
        </dl>`}
  </section>`;
}
/** The section, or null for someone who cannot write here. */
export function proposalTokensSection(ctx: Ctx, repo: Repo): Html | null {
  if (!canWrite(ctx.app.db, repo, ctx.auth.user)) return null;
  const outside = contributeTokensSection(ctx, repo);
  const base = repoBase(repo);
  const listed = listProposals(ctx.app, ctx.auth.user, repo);
  const tokens = listed.ok ? listed.value : [];
  return html`<section class="settings-block" id="proposal-tokens">
  return html`${outside}${outside === null ? null : liveMount({ repo: base })}<section class="settings-block" id="proposal-tokens">
    <h2>Proposal tokens</h2>
    <p class="muted">Lets one child forge fork this code, push <code>child/&lt;name&gt;/…</code> branches and open pulls. Lasts 30 days.</p>
    ${tokens.length === 0
@@ -95,3 +134,30 @@
export async function proposalTokenRevoke(ctx: Ctx): Promise<Response> {
    ? { message: "Proposal token revoked." }
    : { tone: "danger", message: "No such proposal token." });
}
// POST /:owner/:name/settings/contribute-tokens/open
export async function contributeOpenSet(ctx: Ctx): Promise<Response> {
  const repo = loadRepo(ctx);
  if (!repo) return repoNotFound(ctx);
  const form = await readForm(ctx, "rw");
  if (form instanceof Response) return form;
  const on = field(form, "on") === "1";
  const set = setOutsideContributions(ctx.app, ctx.auth.user, repo, on);
  if (!set.ok) return forbiddenPage(ctx, NOT_YOURS_TO_DO);
  return flashTo(ctx, `${repoBase(repo)}/settings`, {
    message: on ? "Outside agents may ask for a token for this repository." : "Outside agents may no longer ask for a token. Tokens already made still work until revoked.",
  });
}
// POST /:owner/:name/settings/contribute-tokens/:id/delete
export async function contributeTokenRevoke(ctx: Ctx): Promise<Response> {
  const repo = loadRepo(ctx);
  if (!repo) return repoNotFound(ctx);
  const form = await readForm(ctx, "rw");
  if (form instanceof Response) return form;
  if (!canAdmin(ctx.app.db, repo, ctx.auth.user)) return forbiddenPage(ctx, NOT_YOURS_TO_DO);
  const revoked = revokeOutsideToken(ctx.app, ctx.auth.user, repo, ctx.params.id ?? "");
  return flashTo(ctx, `${repoBase(repo)}/settings`, revoked.ok
    ? { message: "Outside agent's token revoked." }
    : { tone: "danger", message: "No such token." });
}
@@ -667,6 +667,15 @@
const DESTRUCTIVE: {
      phrase: "",
    }),
  },
  {
    pattern: /^\/([^/]+)\/([^/]+)\/settings\/contribute-tokens\/([^/]+)\/delete$/,
    describe: (m) => ({
      verb: "Revoke",
      title: "Revoke this outside agent's token?",
      detail: `The agent can no longer push contrib/<name>/… branches or open pulls on ${m[1]}/${m[2]}. Pulls it already opened stay.`,
      phrase: "",
    }),
  },
  {
    pattern: /^\/([^/]+)\/([^/]+)\/settings\/mirror\/stop$/,
    describe: (m, ctx) => {
@@ -111,6 +111,8 @@
import {
  tlEvent,
} from "../ui.ts";
import { cutWaveFor } from "../../actions/cut_wave.ts";
import { liveClientJs } from "../live.ts";
import { outsideAgentsJs } from "./outside-agents-live.ts";
import { proposalTokensSection } from "./proposal-tokens.ts";
import { secretsSection } from "./secrets.ts";
import { checkMemoryAt } from "../../apps/check-memory.ts";
@@ -204,7 +206,7 @@
export function settingsPageResponse(
      crumbs: crumbsFor(repo),
      palette: repoPalette(ctx, repo),
      ...(styleCss !== undefined ? { styleCss } : {}),
      scriptJs: teamJs,
      scriptJs: `${teamJs}\n${liveClientJs}\n${outsideAgentsJs}`,
      body: html`${repoHeader(ctx, repo, "settings", { compact: true })}
      ${settingsLayout(sections(repoBase(repo), active), body)}`,
    },
@@ -0,0 +1,373 @@
/**
 * An outside agent's short-lived contribute token (#12012): mint, renew, revoke,
 * expiry, refusal for a repository that does not take outside contributions,
 * the scope check, and the doors (HTTP, git push, a pull, MCP).
 */
import { afterAll, beforeAll, describe, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { mintContributeToken, renewContributeToken, setOutsideContributions } from "../src/actions/contribute_token.ts";
import { commitToBranch, createRepo } from "../src/actions/repos.ts";
import { createApp, type App } from "../src/app.ts";
import {
  CONTRIBUTE_MAX_LIFE_MS,
  CONTRIBUTE_TTL_MS,
  MINTS_PER_HOUR,
  OPEN_PULLS_PER_TOKEN,
  PULLS_PER_REPO_DAY,
  contribNamespace,
  contribSegment,
  allows,
  headInContribNamespace,
  inContribNamespace,
  pullCapReached,
  isAgentName,
  listContribute,
  revokeContribute,
} from "../src/core/contribute_token.ts";
import type { Repo } from "../src/core/repos.ts";
import { verifyToken } from "../src/core/tokens.ts";
import { createUser, type User } from "../src/core/users.ts";
import { serve, type Servers } from "../src/http/server.ts";
import { gitClientEnv } from "./helpers/git-client.ts";
import { quietLogs } from "./helpers/globals.ts";
quietLogs();
const scope = { tokenId: "t", repoId: "r", agent: "codex", namespace: "codex/abcd1234" };
const lib = { owner: "alice", name: "lib" };
describe("the scope check", () => {
  const ask = (method: string, path: string, extra: object = {}) => allows(scope, lib, { method, path, ...extra });
  test("reads public things, pushes and opens pulls on its one repository, and nothing else", () => {
    expect(ask("GET", "/api/v1/repos/bob/other")).toBe(true);
    expect(ask("GET", "/bob/other.git/info/refs", { service: "git-upload-pack" })).toBe(true);
    expect(ask("POST", "/bob/other.git/git-upload-pack")).toBe(true);
    expect(ask("GET", "/alice/lib.git/info/refs", { service: "git-receive-pack" })).toBe(true);
    expect(ask("POST", "/alice/lib.git/git-receive-pack")).toBe(true);
    expect(ask("POST", "/api/v1/repos/alice/lib/pulls")).toBe(true);
    expect(ask("PATCH", "/api/v1/repos/alice/lib/pulls/3", { ownPull: true })).toBe(true);
    expect(ask("PATCH", "/api/v1/repos/alice/lib/pulls/3")).toBe(false); // not its own
    expect(ask("POST", "/bob/other.git/git-receive-pack")).toBe(false);
    expect(ask("GET", "/bob/other.git/info/refs", { service: "git-receive-pack" })).toBe(false);
    expect(ask("POST", "/api/v1/repos/bob/other/pulls")).toBe(false);
    expect(ask("POST", "/api/v1/repos/alice/lib/proposal-tokens")).toBe(false);
    expect(ask("DELETE", "/api/v1/repos/alice/lib")).toBe(false);
    expect(ask("GET", "/api/v1/user")).toBe(false);
    expect(ask("POST", "/mcp")).toBe(false);
  });
  test("its branches are contrib/<agent>/ and hostile names are outside it", () => {
    expect(inContribNamespace("refs/heads/contrib/codex/abcd1234/fix-1", "codex/abcd1234")).toBe(true);
    expect(headInContribNamespace("contrib/codex/abcd1234/a/b", "codex/abcd1234")).toBe(true);
    for (const ref of [
      "refs/heads/main",
      "refs/heads/contrib/other/x",
      "refs/heads/contrib/codex/abcd1234",
      "refs/heads/contrib/codex/fix-1", // no segment: another token's ground
      "refs/heads/contrib/codex/ffff0000/fix-1", // another token's segment
      "refs/heads/contrib/codex/abcd1234/../../main",
      "refs/heads/contrib/codex/abcd1234/a b",
      "refs/tags/contrib/codex/abcd1234/x",
      "refs/pull/1/head",
    ])
      expect(inContribNamespace(ref, "codex/abcd1234")).toBe(false);
    for (const bad of ["", "-x", "a/b", "a b", "a..b", "x".repeat(65)]) expect(isAgentName(bad)).toBe(false);
    expect(isAgentName("Codex_cloud-2")).toBe(true);
  });
});
describe("minting, renewing, revoking", () => {
  let dataDir: string;
  let app: App;
  let servers: Servers;
  let alice: User;
  let pub: Repo;
  let closed: Repo;
  let work: string;
  const now = new Date("2026-11-14T00:00:00Z");
  const git = async (args: string[], cwd = work) => {
    const proc = Bun.spawn(["git", "-c", "credential.helper=", ...args], {
      cwd,
      env: gitClientEnv({ GIT_TERMINAL_PROMPT: "0" }),
      stdout: "pipe",
      stderr: "pipe",
    });
    const [out, err] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()]);
    return { code: await proc.exited, out, err };
  };
  const post = (path: string, body: unknown, token?: string, headers: Record<string, string> = {}) =>
    fetch(`${servers.url}${path}`, {
      method: "POST",
      headers: { "content-type": "application/json", ...(token ? { authorization: `Bearer ${token}` } : {}), ...headers },
      body: JSON.stringify(body),
    });
  beforeAll(async () => {
    dataDir = await mkdtemp(join(tmpdir(), "forge-contrib-token-"));
    app = createApp({ dataDir, port: 0, host: "forge.test" });
    servers = await serve(app);
    const made = await createUser(app.db, {
      origin: "seed",
      trusted: true,
      username: "alice",
      email: "[email protected]",
      password: "a-good-passphrase",
      adminIfFirst: true,
    });
    if (!made.ok) throw new Error(made.error);
    alice = made.value;
    for (const [name, visibility] of [["lib", "public"], ["secret", "private"]] as const) {
      const r = await createRepo(app, alice, { name, visibility });
      if (!r.ok) throw new Error(String(r.error));
      if (name === "lib") pub = r.value;
      else closed = r.value;
      const seeded = await commitToBranch(app, alice, r.value, {
        branch: "main",
        message: "Start",
        files: [{ path: "README.md", content: "hi\n" }],
      });
      if (!seeded.ok) throw new Error(JSON.stringify(seeded.error));
    }
    work = join(dataDir, "work");
    expect((await git(["clone", `${servers.url}/alice/lib.git`, work], dataDir)).code).toBe(0);
    await git(["config", "user.email", "[email protected]"]);
    await git(["config", "user.name", "codex"]);
    await Bun.write(join(work, "fix.md"), "a fix\n");
    await git(["add", "."]);
    await git(["commit", "-m", "A fix"]);
  });
  afterAll(async () => {
    await servers.stop();
    await rm(dataDir, { recursive: true, force: true });
  });
  const mint = (repo: string, agent = "codex", source = "203.0.113.1", at = now) =>
    mintContributeToken(app, { agent, origin: "codex cloud, claimed", repo }, source, "https://forge.test", at);
  test("a repository that does not allow outside contributions is refused, and so is every other that cannot", async () => {
    // Not opted in yet.
    const first = await mint("alice/lib", "codex", "198.51.100.9");
    expect(first.ok).toBe(false);
    expect(!first.ok && first.error.error).toBe("not_open");
    // A missing one answers alike.
    const none = await mint("alice/nope", "codex", "198.51.100.9");
    expect(!none.ok && none.error.error).toBe("not_open");
    // A private repository does not take them even when the owner said yes.
    setOutsideContributions(app, alice, closed, true);
    const priv = await mint("alice/secret", "codex", "198.51.100.9");
    expect(!priv.ok && priv.error.error).toBe("not_open");
    // Bad input is named.
    const bad = await mintContributeToken(app, { agent: "a b", repo: "alice/lib" }, "198.51.100.9", "https://forge.test", now);
    expect(!bad.ok && bad.error.error).toBe("invalid_agent");
    const badOrigin = await mintContributeToken(app, { agent: "x", origin: "<script>", repo: "alice/lib" }, "198.51.100.9", "https://forge.test", now);
    expect(!badOrigin.ok && badOrigin.error.error).toBe("invalid_origin");
  });
  test("an owner's yes lets it mint; the token expires, renews once, and is revoked", async () => {
    expect(setOutsideContributions(app, alice, pub, true).ok).toBe(true);
    const made = await mint("alice/lib");
    if (!made.ok) throw new Error(JSON.stringify(made.error));
    expect(made.value.branches).toBe(`contrib/codex/${contribSegment(made.value.id)}/*`);
    expect(Date.parse(made.value.expiresAt) - now.getTime()).toBe(CONTRIBUTE_TTL_MS);
    const verified = verifyToken(app.db, made.value.token);
    expect(verified.ok && verified.value.contribute).toEqual({
      tokenId: made.value.id,
      repoId: pub.id,
      agent: "codex",
      namespace: contribNamespace("codex", made.value.id),
    });
    expect(verified.ok && verified.value.user.isAdmin).toBe(false);
    // Listed with what it claimed.
    const listed = listContribute(app.db, pub.id, now);
    expect(listed.map((t) => [t.agent, t.origin])).toEqual([["codex", "codex cloud, claimed"]]);
    // Renews once, a day on.
    const later = new Date(now.getTime() + 20 * 3600_000);
    const renewed = renewContributeToken(app, made.value.id, later);
    expect(renewed.ok && Date.parse(renewed.value.expiresAt)).toBe(later.getTime() + CONTRIBUTE_TTL_MS);
    expect(Date.parse((renewed.ok && renewed.value.expiresAt) || "")).toBeLessThanOrEqual(now.getTime() + CONTRIBUTE_MAX_LIFE_MS);
    const again = renewContributeToken(app, made.value.id, later);
    expect(!again.ok && again.error.error).toBe("already_renewed");
    // Expiry is seen: not listed after, and the token no longer verifies.
    app.db.query("UPDATE token SET expires_at = ?1 WHERE id = ?2").run(new Date(Date.now() - 1000).toISOString(), made.value.id);
    expect(verifyToken(app.db, made.value.token).ok).toBe(false);
    expect(listContribute(app.db, pub.id, new Date()).length).toBe(0);
    // Revoke: another repository's id cannot revoke it; its own can.
    const second = await mint("alice/lib", "jules", "203.0.113.2");
    if (!second.ok) throw new Error("mint");
    expect(revokeContribute(app.db, closed.id, second.value.id)).toBe(false);
    expect(verifyToken(app.db, second.value.token).ok).toBe(true);
    expect(revokeContribute(app.db, pub.id, second.value.id)).toBe(true);
    expect(verifyToken(app.db, second.value.token).ok).toBe(false);
  });
  test("minting is limited per address", async () => {
    for (let i = 0; i < MINTS_PER_HOUR; i++) expect((await mint("alice/lib", "busy", "192.0.2.7")).ok).toBe(true);
    const over = await mint("alice/lib", "busy", "192.0.2.7");
    expect(!over.ok && over.error.error).toBe("rate_limited");
    expect((await mint("alice/lib", "busy", "192.0.2.8")).ok).toBe(true);
  });
  test("over HTTP: mint with no account, push under contrib/<agent>/ only, open a pull, renew once", async () => {
    const res = await post("/api/v1/contribute", { agent: "cursor", repo: "alice/lib", origin: "cursor cloud" });
    expect(res.status).toBe(201);
    const made = (await res.json()) as { token: string; git: { url: string }; expiresAt: string };
    expect(made.token).toStartWith("forge_");
    expect(res.headers.get("cache-control")).toBe("no-store");
    const closedRes = await post("/api/v1/contribute", { agent: "cursor", repo: "alice/secret" });
    expect(closedRes.status).toBe(404);
    expect((await post("/api/v1/contribute", { agent: "", repo: "alice/lib" })).status).toBe(422);
    const verifiedMade = verifyToken(app.db, made.token) as { ok: true; value: { user: User; contribute: { namespace: string } } };
    const user = verifiedMade.value.user.username;
    const ns = verifiedMade.value.contribute.namespace;
    const remote = (ref: string) => git(["push", `${servers.url.replace("://", `://${user}:${made.token}@`)}/alice/lib.git`, `HEAD:${ref}`]);
    const toMain = await remote("main");
    expect(toMain.code).not.toBe(0);
    expect(toMain.err).toContain(`this token pushes only contrib/${ns}/`);
    expect((await remote("refs/heads/contrib/other/x")).code).not.toBe(0);
    expect((await remote(`refs/heads/contrib/${ns}/../../main`)).code).not.toBe(0);
    // Another repository is not its own.
    const elsewhere = await git(["push", `${servers.url.replace("://", `://${user}:${made.token}@`)}/alice/secret.git`, `HEAD:refs/heads/contrib/${ns}/x`]);
    expect(elsewhere.code).not.toBe(0);
    const landed = await remote(`refs/heads/contrib/${ns}/fix`);
    expect(landed.err).not.toContain("refused");
    expect(landed.code).toBe(0);
    const auth = { authorization: `Bearer ${made.token}` };
    const opened = await post("/api/v1/repos/alice/lib/pulls", { title: "A fix", base: "main", head: `contrib/${ns}/fix` }, made.token);
    expect(opened.status).toBe(201);
    const pull = (await opened.json()) as { number: number };
    // Its head must be its own namespace.
    expect((await post("/api/v1/repos/alice/lib/pulls", { title: "x", base: "main", head: "main" }, made.token)).status).toBe(422);
    // It reads its pull back, checks included, but may not merge or reach anything else.
    const read = await fetch(`${servers.url}/api/v1/repos/alice/lib/pulls/${pull.number}`, { headers: auth });
    expect(read.status).toBe(200);
    expect((await post(`/api/v1/repos/alice/lib/pulls/${pull.number}/merge`, {}, made.token)).status).not.toBe(200);
    expect((await fetch(`${servers.url}/api/v1/tokens`, { headers: auth })).status).toBe(403);
    expect((await post("/mcp", { jsonrpc: "2.0", id: 1, method: "tools/list" }, made.token)).status).toBe(403);
    // Renews once through the same call.
    const renewed = await post("/api/v1/contribute", {}, made.token);
    expect(renewed.status).toBe(200);
    expect(((await renewed.json()) as { renewed: boolean }).renewed).toBe(true);
    expect((await post("/api/v1/contribute", {}, made.token)).status).toBe(409);
    // The owner revokes it from the settings list: the token stops working.
    const listed = listContribute(app.db, pub.id, new Date()).find((t) => t.agent === "cursor")!;
    expect(revokeContribute(app.db, pub.id, listed.id)).toBe(true);
    expect((await fetch(`${servers.url}/api/v1/repos/alice/lib`, { headers: auth })).status).toBe(200); // public, as anyone
    expect((await post("/api/v1/repos/alice/lib/pulls", { title: "y", base: "main", head: `contrib/${ns}/fix` }, made.token)).status).toBe(401);
  });
  test("an owner's no ends the offer and the token's push", async () => {
    const res = await post("/api/v1/contribute", { agent: "late", repo: "alice/lib" }, undefined);
    const made = (await res.json()) as { token: string };
    setOutsideContributions(app, alice, pub, false);
    expect((await post("/api/v1/contribute", { agent: "again", repo: "alice/lib" })).status).toBe(404);
    expect((await post("/api/v1/repos/alice/lib/pulls", { title: "z", base: "main", head: "contrib/late/x" }, made.token)).status).toBe(403);
    setOutsideContributions(app, alice, pub, true);
  });
  test("the start tool's contribute action mints through MCP with no token", async () => {
    const res = await post("/mcp", {
      jsonrpc: "2.0",
      id: 1,
      method: "tools/call",
      params: { name: "start", arguments: { action: "contribute", agent: "jules", repo: "alice/lib", origin: "jules.google" } },
    }, undefined, { accept: "application/json, text/event-stream" });
    const body = (await res.json()) as { result: { isError?: boolean; content: { text: string }[] } };
    expect(body.result.isError).toBeUndefined();
    const made = JSON.parse(body.result.content[0]!.text) as { token: string; branches: string };
    expect(made.branches).toMatch(/^contrib\/jules\/[0-9a-f]{8}\/\*$/);
    expect(made.token).toStartWith("forge_");
  });
  test("two tokens that claim the same name cannot push over, or delete, each other's branches", async () => {
    setOutsideContributions(app, alice, pub, true);
    const a = await mint("alice/lib", "twin", "203.0.113.50");
    const b = await mint("alice/lib", "twin", "203.0.113.51");
    if (!a.ok || !b.ok) throw new Error("mint");
    const nsA = contribNamespace("twin", a.value.id);
    const nsB = contribNamespace("twin", b.value.id);
    expect(nsA).not.toBe(nsB);
    const as = (t: typeof a.value) => {
      const verified = verifyToken(app.db, t.token) as { ok: true; value: { user: User } };
      return `${servers.url.replace("://", `://${verified.value.user.username}:${t.token}@`)}/alice/lib.git`;
    };
    expect((await git(["push", as(a.value), `HEAD:refs/heads/contrib/${nsA}/work`])).code).toBe(0);
    await git(["commit", "--allow-empty", "-m", "Another head"]);
    // B pushes into A's namespace, force-pushes over its branch, and deletes it: all refused.
    expect((await git(["push", "--force", as(b.value), `HEAD:refs/heads/contrib/${nsA}/work`])).code).not.toBe(0);
    expect((await git(["push", as(b.value), `:refs/heads/contrib/${nsA}/work`])).code).not.toBe(0);
    // The bare claimed name, with no segment, is nobody's.
    expect((await git(["push", as(b.value), "HEAD:refs/heads/contrib/twin/work"])).code).not.toBe(0);
    expect((await git(["push", as(b.value), `HEAD:refs/heads/contrib/${nsB}/work`])).code).toBe(0);
    // A's branch is still there, and A may delete its own.
    const heads = (await git(["ls-remote", as(a.value)])).out;
    expect(heads).toContain(`refs/heads/contrib/${nsA}/work`);
    expect((await git(["push", as(a.value), `:refs/heads/contrib/${nsA}/work`])).code).toBe(0);
  });
  test("a token opens at most a few pulls, and a repository takes a day's worth from all of them", async () => {
    setOutsideContributions(app, alice, pub, true);
    const made = await mint("alice/lib", "spam", "203.0.113.60");
    if (!made.ok) throw new Error("mint");
    const ns = contribNamespace("spam", made.value.id);
    const verified = verifyToken(app.db, made.value.token) as { ok: true; value: { user: User } };
    const url = `${servers.url.replace("://", `://${verified.value.user.username}:${made.value.token}@`)}/alice/lib.git`;
    const refs = Array.from({ length: OPEN_PULLS_PER_TOKEN + 1 }, (_, i) => `HEAD:refs/heads/contrib/${ns}/p${i}`);
    expect((await git(["push", url, ...refs])).code).toBe(0);
    const open = (i: number) => post("/api/v1/repos/alice/lib/pulls", { title: `P${i}`, base: "main", head: `contrib/${ns}/p${i}` }, made.value.token);
    for (let i = 0; i < OPEN_PULLS_PER_TOKEN; i++) expect((await open(i)).status).toBe(201);
    const over = await open(OPEN_PULLS_PER_TOKEN);
    expect(over.status).toBe(429);
    expect(over.headers.get("retry-after")).not.toBeNull();
    // Counted from the rows: closing one frees a place.
    app.db.query("UPDATE issue SET state = 'closed' WHERE repo_id = ?1 AND author_id = ?2 AND number = (SELECT MIN(number) FROM issue WHERE repo_id = ?1 AND author_id = ?2)").run(pub.id, verified.value.user.id);
    expect((await open(OPEN_PULLS_PER_TOKEN)).status).toBe(201);
    // The repository's own day: pulls by many outside tokens together.
    const others: User[] = [];
    for (let i = 0; others.length < Math.ceil(PULLS_PER_REPO_DAY / 4); i++) {
      const m = await mint("alice/lib", `many${i}`, `198.18.0.${i}`);
      if (!m.ok) throw new Error("mint");
      others.push((verifyToken(app.db, m.value.token) as { ok: true; value: { user: User } }).value.user);
    }
    let n = 1000;
    for (const u of others)
      for (let k = 0; k < 4; k++)
        app.db
          .query("INSERT INTO issue (id, repo_id, number, kind, title, author_id, state) VALUES (?1, ?2, ?3, 'pull', 'x', ?4, 'closed')")
          .run(`seed-${n}`, pub.id, n++, u.id);
    expect(pullCapReached(app.db, pub.id, others[0]!.id, new Date())).toBe("repo_day");
    const late = await mint("alice/lib", "late2", "198.19.0.1");
    if (!late.ok) throw new Error("mint");
    const lateUser = (verifyToken(app.db, late.value.token) as { ok: true; value: { user: User } }).value.user;
    expect(pullCapReached(app.db, pub.id, lateUser.id, new Date())).toBe("repo_day");
    // A day later the count is clear.
    expect(pullCapReached(app.db, pub.id, lateUser.id, new Date(Date.now() + 2 * 86_400_000))).toBeUndefined();
  });
  test("a mint that loses the race to the cap leaves no account behind", async () => {
    const source = "203.0.113.77";
    for (let i = 0; i < MINTS_PER_HOUR - 1; i++) expect((await mint("alice/lib", "pre", source)).ok).toBe(true);
    const users = () => app.db.query<{ n: number }, []>("SELECT COUNT(*) AS n FROM user").get()!.n;
    const before = users();
    const both = await Promise.all([mint("alice/lib", "race", source), mint("alice/lib", "race", source)]);
    expect(both.filter((r) => r.ok).length).toBe(1);
    // One account for the one token, none for the refused mint.
    expect(users()).toBe(before + 1);
  });
});
@@ -45,7 +45,7 @@
const RANDOM_CASES = 4;
type Schema = { type?: string | string[]; properties?: Record<string, Schema>; required?: string[]; items?: Schema; enum?: unknown[] };
const BIG = "x".repeat(10 * 1024);
const BIG = "x".repeat(8 * 1024);
const nested = (depth: number): unknown => (depth === 0 ? { a: "../" } : { a: nested(depth - 1), b: [nested(0)] });
/** Hostile values in no particular type, for any field. */
@@ -101,7 +101,8 @@
function wrongFor(schema: Schema): unknown[] {
function cases(name: string, schema: Schema, r: Rand): unknown[] {
  const props = Object.entries(schema.properties ?? {});
  const all: unknown[] = [undefined, {}, "not-an-object", [1, 2], null];
  // Every field at once: each wrong type, a 10 kB string, a `../` path.
  // Every field at once: each wrong type, an 8 kB string, a `../` path.
  // All fields at once must stay under the 64 KiB anonymous body cap.
  for (const pickAt of [0, 3, 4]) {
    const args: Record<string, unknown> = {};
    for (const [k, s] of props) args[k] = wrongFor(s)[pickAt % wrongFor(s).length];
@@ -110,6 +110,7 @@
async function callers(): Promise<Record<string, string[]>> {
test("every caller of createUser says where its account comes from", async () => {
  // A new way in is added here on purpose: a stranger's door, or a named exemption.
  expect(await callers()).toEqual({
    "src/actions/contribute_token.ts": ["start"],
    "src/actions/crew.ts": ["agent"],
    "src/actions/first_admin.ts": ["first-admin"],
    "src/actions/spawn.ts": ["spawn", "spawn"],
@@ -0,0 +1,119 @@
/**
 * Outside agents in the terminal (#12012): the settings page's block, from the
 * same actions and the same gate (a repository's admins). A write made here
 * reaches the bus, which is what redraws an open settings page.
 */
import { afterAll, beforeAll, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { mintContributeToken } from "../src/actions/contribute_token.ts";
import { createApp, type App } from "../src/app.ts";
import { contributeOpen, listContribute } from "../src/core/contribute_token.ts";
import { createRepo, type Repo } from "../src/core/repos.ts";
import { createSession } from "../src/core/sessions.ts";
import { createUser, getUserByName, type User } from "../src/core/users.ts";
import { serve, type Servers } from "../src/http/server.ts";
import { createForgeApp } from "../src/tui/forge.ts";
import { outsideAgentsCommands, outsideAgentsScreen } from "../src/tui/screens/outsideagents.ts";
import { headlessTerminal } from "../src/tui/term/terminal.ts";
import { adminCookie } from "./helpers/admin.ts";
import { settleApp } from "./helpers/tui.ts";
let dir: string;
let app: App;
let servers: Servers;
let admin: User;
let bob: User;
let repo: Repo;
let adminHeader: string;
beforeAll(async () => {
  dir = await mkdtemp(join(tmpdir(), "forge-outside-tui-"));
  app = createApp({ dataDir: dir, port: 0 });
  servers = await serve(app);
  adminHeader = await adminCookie(app, { username: "trevato", email: "[email protected]", password: "a-good-passphrase" });
  admin = getUserByName(app.db, "trevato")!;
  const made = await createUser(app.db, { origin: "seed", trusted: true, username: "bob", email: "[email protected]", password: "a-good-passphrase" });
  if (!made.ok) throw new Error(made.error);
  bob = made.value;
  createSession(app.db, bob.id);
  const r = await createRepo(app.db, app.reposRoot, { ownerId: admin.id, name: "lib", visibility: "public", description: "", defaultBranch: "main" });
  if (!r.ok) throw new Error(r.error);
  repo = r.value;
});
afterAll(async () => {
  await servers.stop();
  app.close();
  await rm(dir, { recursive: true, force: true });
});
const key = (k: string) => ({ type: "key" as const, key: k, ctrl: false, alt: false, shift: false });
function open(user: User) {
  const { app: tui, session } = createForgeApp(
    app,
    { sshUsername: user.username, remoteAddress: "127.0.0.1", fingerprint: "SHA256:test", user },
    { terminal: headlessTerminal(120, 40), exitHooks: false },
  );
  tui.start();
  tui.ctx.push(outsideAgentsScreen(session, tui.ctx, repo));
  return { tui, session };
}
const web = async (path: string, cookie: string) => await (await fetch(`${servers.url}${path}`, { headers: { cookie } })).text();
test("an admin allows, sees a token, and revokes it, and each write is an event the page follows", async () => {
  const events: string[] = [];
  const off = app.bus.subscribe((e) => {
    if (e.repoId === repo.id) events.push(e.kind);
  });
  const { tui, session } = open(admin);
  await settleApp(tui);
  expect(tui.screen.toText()).toContain("Outside agents may not ask for a token");
  expect(await web("/trevato/lib/settings", adminHeader)).toContain("Allow");
  tui.dispatch(key("a"));
  await settleApp(tui);
  expect(contributeOpen(app.db, repo.id)).toBe(true);
  expect(events).toContain("contribute.open");
  expect(await web("/trevato/lib/settings", adminHeader)).toContain("Stop allowing");
  const made = await mintContributeToken(app, { agent: "codex", origin: "codex cloud", repo: "trevato/lib" }, "203.0.113.5", "https://forge.test");
  if (!made.ok) throw new Error(JSON.stringify(made.error));
  tui.ctx.invalidate();
  await settleApp(tui);
  expect(tui.screen.toText()).toContain("codex");
  expect(tui.screen.toText()).toContain("claimed, not verified");
  // Revoke asks first: cancelling keeps the token, confirming ends it.
  tui.dispatch(key("x"));
  await settleApp(tui);
  expect(tui.screen.toText()).toContain("Revoke token");
  tui.dispatch(key("esc"));
  await settleApp(tui);
  expect(listContribute(app.db, repo.id, new Date()).length).toBe(1);
  tui.dispatch(key("x"));
  await settleApp(tui);
  tui.dispatch(key("right"));
  tui.dispatch(key("enter"));
  await settleApp(tui);
  expect(listContribute(app.db, repo.id, new Date()).length).toBe(0);
  expect(events).toContain("contribute.revoked");
  tui.dispatch(key("a"));
  await settleApp(tui);
  expect(contributeOpen(app.db, repo.id)).toBe(false);
  expect(outsideAgentsCommands(session, tui.ctx, repo).length).toBe(1);
  off();
  tui.stop?.();
});
test("only a repository's admin has the screen's keys and its palette entry", async () => {
  const { tui, session } = open(bob);
  await settleApp(tui);
  expect(outsideAgentsCommands(session, tui.ctx, repo)).toEqual([]);
  expect(tui.screen.toText()).toContain("An admin of this repository manages outside agents.");
  tui.dispatch(key("a"));
  await settleApp(tui);
  expect(contributeOpen(app.db, repo.id)).toBe(false);
  tui.stop?.();
});
		@@ -238,7 +238,7 @@ bytes in `tools/list`. After changing a tool run `bun scripts/mcp-table.ts`;
238	238	\| `whoami_can` \| `role`, `passkeys` \| What you can do: your role and its roles-table row, yes or no each \| 231 \|
239	239	\| `write_file` \| — \| No shell? Commit one file to a branch \| 342 \|
240	240	\| `report` \| — \| Report a problem in a public repository, no account needed \| 468 \|
241		\| `start` \| — \| Start building with no account: an account, a repo, a live app and a token in one call \| 358 \|
	241	\| `start` \| `contribute` \| Start building with no account: an account, a repo, a live app and a token in one call \| 387 \|
242	242	<!-- mcp-tools:end -->
243	243
244	244	The complete list, with schemas, is MCP `tools/list` called with a token.
		@@ -0,0 +1,19 @@
	1	# Outside agents: a contribute token with no account (#12012)
	2
	3	An agent with its own sandbox (Codex cloud, Jules, Claude Code, Cursor) contributes by clone and push. It needs no account and spawns no forge.
	4
	5	The owner says yes first. On a repository's settings page, Outside agents › Allow outside agents. Only a public, original, unarchived repository takes them. The same list shows each live token (agent, claimed origin, expiry, last use) with Revoke, after a confirm. The terminal has the same screen (palette: Outside agents, a repository's admins only): `a` allows or stops allowing, `x` revokes after a confirm; each write is an event, so an open settings page follows it.
	6
	7	The agent asks for a token.
	8
	9	```
	10	POST /api/v1/contribute {"agent": "codex", "repo": "owner/name", "origin": "codex cloud"}
	11	```
	12
	13	or the MCP `start` tool with `action: "contribute"` (same arguments). The answer, shown once, holds the token, `git.push` (a push URL for `HEAD:contrib/<agent>/<segment>/<topic>`) and `expiresAt`.
	14
	15	- Scope: read public repositories; push `contrib/<agent>/<segment>/*` on that one repository; open pulls from those branches (`POST /api/v1/repos/<owner>/<name>/pulls`, `head: "contrib/<agent>/<segment>/<topic>"`); read and update its own pulls, checks included. Everything else answers 403 (`src/http/contribute_gate.ts`, `allows` in `src/core/contribute_token.ts`). It never reaches the default branch and a person merges.
	16	- Lifetime: 24 hours. `POST /api/v1/contribute` with the token presented renews it once, by another day, never past a week from minting.
	17	- Own branches: the agent name is claimed, so two tokens may share one. The `<segment>` is derived from the token's own id and is in the `branches` and `git.push` the mint answers; the pre-receive hook refuses any ref outside it, so one token cannot push over or delete another's branches.
	18	- Limits: 5 tokens an hour and 20 a day per address (hashed), 120 requests a minute per token; at most 5 pulls open per token, 20 opened a day per token and 30 a day from all of a repository's outside tokens (counted from the pull rows; over it answers 429).
	19	- Claimed, not verified: the agent name and origin are what the agent said. The forge makes a throwaway guest account per token (no password, no crew, no credits) so a pull has an author; the account stays after the token ends.
		@@ -0,0 +1,175 @@
	1	/**
	2	* The contribute call (#12012): an outside agent names itself and a repository
	3	* that opted in, and gets a token for one day with no account of its own. The
	4	* forge makes a throwaway guest account for the mint (no password, no crew, no
	5	* credits) so a pull the agent opens has an author. Name and origin are stored
	6	* as claimed. Minting is capped per address, counted from the rows it leaves.
	7	* The repository owner's yes is `contribute_open` (`setOutsideContributions`).
	8	*/
	9	import type { App } from "../app.ts";
	10	import {
	11	MINTS_PER_DAY,
	12	MINTS_PER_HOUR,
	13	contribNamespace,
	14	type Minted,
	15	contributeOpen,
	16	isAgentName,
	17	isOrigin,
	18	mintContribute,
	19	mintsSince,
	20	renewContribute,
	21	revokeContribute,
	22	setContributeOpen,
	23	} from "../core/contribute_token.ts";
	24	import { getRepo, canAdmin, type Repo } from "../core/repos.ts";
	25	import { createUser, type User } from "../core/users.ts";
	26	import { err, ok, type Result } from "../kernel/result.ts";
	27	import { isMirror } from "../origins/write-through.ts";
	28	import { isContributionFork } from "../core/contribute.ts";
	29	import { nameSlug } from "./start.ts";
	30	import { noEmail } from "./users.ts";
	31
	32	export type ContributeTokenError =
	33	\| "invalid_agent"
	34	\| "invalid_origin"
	35	\| "invalid_repo"
	36	\| "not_open"
	37	\| "rate_limited"
	38	\| "already_renewed"
	39	\| "failed";
	40
	41	export const CONTRIBUTE_TOKEN_WORDS: Readonly<Record<ContributeTokenError, string>> = {
	42	invalid_agent: "agent is a name of at most 64 letters, digits, . _ -, starting with a letter or digit",
	43	invalid_origin: "origin is where you run from, as plain text of at most 200 characters (claimed, not verified)",
	44	invalid_repo: "repo is owner/name",
	45	not_open: "this repository does not take outside contributions: it is private, archived, a copy, or its owner has not allowed them",
	46	rate_limited: "Too many tokens from here; wait and ask again.",
	47	already_renewed: "this token was renewed once already; ask for a new one",
	48	failed: "The token could not be made; nothing was kept. Try again.",
	49	};
	50
	51	export const CONTRIBUTE_TOKEN_HINT =
	52	"send {agent, repo: \"owner/name\", origin?}: agent is your name, origin where you run (both claimed, not verified)";
	53
	54	export interface ContributeTokenRefusal {
	55	readonly error: ContributeTokenError;
	56	readonly retryAfter?: number;
	57	}
	58
	59	/**
	60	* Whether `repo` takes outside contributions: public, a real original, not archived,
	61	* and its owner said yes.
	62	*/
	63	export function takesOutside(app: App, repo: Repo): boolean {
	64	return (
	65	repo.visibility === "public" &&
	66	repo.sealedFor === null &&
	67	repo.archivedAt === null &&
	68	!isMirror(app, repo) &&
	69	!isContributionFork(app.db, repo.id) &&
	70	contributeOpen(app.db, repo.id)
	71	);
	72	}
	73
	74	export interface ContributeTokenMade extends Minted {
	75	readonly repo: string;
	76	readonly agent: string;
	77	/** The branches this token may push. */
	78	readonly branches: string;
	79	readonly git: { readonly url: string; readonly push: string };
	80	readonly claimed: true;
	81	readonly renewable: true;
	82	}
	83
	84	export async function mintContributeToken(
	85	app: App,
	86	input: { agent?: unknown; origin?: unknown; repo?: unknown },
	87	source: string,
	88	origin: string,
	89	now: Date = new Date(),
	90	): Promise<Result<ContributeTokenMade, ContributeTokenRefusal>> {
	91	const refuse = (error: ContributeTokenError, retryAfter?: number) =>
	92	err<ContributeTokenRefusal>(retryAfter === undefined ? { error } : { error, retryAfter });
	93	if (!isAgentName(input.agent)) return refuse("invalid_agent");
	94	const claimed = input.origin === undefined ? "" : input.origin;
	95	if (!isOrigin(claimed)) return refuse("invalid_origin");
	96	const [owner, name, ...rest] = typeof input.repo === "string" ? input.repo.split("/") : [];
	97	if (!owner \|\| !name \|\| rest.length > 0) return refuse("invalid_repo");
	98	// A repository that is missing and one that is closed answer alike.
	99	const repo = getRepo(app.db, owner, name);
	100	if (repo === undefined \|\| !takesOutside(app, repo)) return refuse("not_open");
	101	const agent = input.agent;
	102
	103	const capped = (): boolean =>
	104	mintsSince(app.db, now.getTime() - 3_600_000, source) >= MINTS_PER_HOUR \|\|
	105	mintsSince(app.db, now.getTime() - 86_400_000, source) >= MINTS_PER_DAY;
	106	if (capped()) return refuse("rate_limited", 3600);
	107
	108	const base = nameSlug(agent) \|\| "agent";
	109	const username = `contrib-${base}-${crypto.randomUUID().slice(0, 6)}`.slice(0, 39);
	110	const made = await createUser(app.db, {
	111	origin: "start",
	112	username,
	113	email: noEmail(username),
	114	displayName: agent,
	115	trusted: true,
	116	});
	117	if (!made.ok) return refuse("failed");
	118	const user: User = made.value;
	119	let minted: Minted \| undefined;
	120	app.db.transaction(() => {
	121	// Counted again inside the write: concurrent calls cannot overshoot.
	122	if (capped()) return;
	123	minted = mintContribute(app.db, { userId: user.id, repoId: repo.id, agent, origin: claimed, source }, now);
	124	})();
	125	if (minted === undefined) {
	126	// The cap held inside the write: the account made for this mint goes with it.
	127	app.db.transaction(() => {
	128	app.db.query("DELETE FROM email_check WHERE user_id = ?1").run(user.id);
	129	app.db.query("DELETE FROM user WHERE id = ?1").run(user.id);
	130	})();
	131	return refuse("rate_limited", 3600);
	132	}
	133	const namespace = contribNamespace(agent, minted.id);
	134	app.bus.append({ kind: "contribute.token", repoId: repo.id, actorId: user.id, payload: { agent } });
	135	const url = `${origin}/${repo.ownerName}/${repo.name}.git`;
	136	return ok({
	137	...minted,
	138	repo: `${repo.ownerName}/${repo.name}`,
	139	agent,
	140	branches: `contrib/${namespace}/*`,
	141	git: {
	142	url,
	143	push: `git push ${url.replace("://", `://${user.username}:${minted.token}@`)} HEAD:contrib/${namespace}/<topic>`,
	144	},
	145	claimed: true,
	146	renewable: true,
	147	});
	148	}
	149
	150	/** Extend the token the caller holds by another day, once. */
	151	export function renewContributeToken(
	152	app: App,
	153	tokenId: string,
	154	now: Date = new Date(),
	155	): Result<{ expiresAt: string }, ContributeTokenRefusal> {
	156	const done = renewContribute(app.db, tokenId, now);
	157	if (done.ok) return ok({ expiresAt: done.expiresAt });
	158	return err({ error: done.error === "already_renewed" ? "already_renewed" : "failed" });
	159	}
	160
	161	/** A repository admin's yes or no to outside contributions. */
	162	export function setOutsideContributions(app: App, actor: User \| undefined, repo: Repo, on: boolean): Result<{ on: boolean }, "not_found"> {
	163	if (!canAdmin(app.db, repo, actor)) return err("not_found");
	164	setContributeOpen(app.db, repo.id, on);
	165	app.bus.append({ kind: "contribute.open", repoId: repo.id, actorId: actor!.id, payload: { on } });
	166	return ok({ on });
	167	}
	168
	169	/** A repository admin revokes one outside agent's token; every door says so on the bus. */
	170	export function revokeOutsideToken(app: App, actor: User \| undefined, repo: Repo, tokenId: string): Result<{ revoked: true }, "not_found"> {
	171	if (!canAdmin(app.db, repo, actor)) return err("not_found");
	172	if (!revokeContribute(app.db, repo.id, tokenId)) return err("not_found");
	173	app.bus.append({ kind: "contribute.revoked", repoId: repo.id, actorId: actor!.id, payload: { token: tokenId } });
	174	return ok({ revoked: true });
	175	}
		@@ -128,6 +128,11 @@ async function proposalRoute(
128	128	}
129	129
130	130	export interface OpenPullInput {
	131	/**
	132	* Set by the handler for an outside agent's contribute token (`http/api.ts`):
	133	* its limits are the token's, not a guest's.
	134	*/
	135	outsideAgent?: boolean;
131	136	title: string;
132	137	body?: string;
133	138	baseBranch: string;
		@@ -173,6 +178,7 @@ export async function openPull(
173	178	// A guest who cannot write here sends from their own contribution fork, and
174	179	// a low number of pulls a day. Asked first, so a mirror's path never starts.
175	180	const guest =
	181	input.outsideAgent !== true &&
176	182	!requireAbility(app, user.value, "make_it_yours").ok &&
177	183	(!canWrite(app.db, baseRepo, user.value) \|\| isContributionFork(app.db, baseRepo.id))
178	184	? takeGuestPull(app, user.value, baseRepo, input.headRepo, Date.now())
		@@ -279,6 +279,7 @@ export { route as postApiV1BoardsPins } from "./postApiV1BoardsPins.ts";
279	279	export { route as postApiV1BoardsQuery } from "./postApiV1BoardsQuery.ts";
280	280	export { route as postApiV1Builds } from "./postApiV1Builds.ts";
281	281	export { route as postApiV1Codes } from "./postApiV1Codes.ts";
	282	export { route as postApiV1Contribute } from "./postApiV1Contribute.ts";
282	283	export { route as postApiV1ConversationConfirmsId } from "./postApiV1ConversationConfirmsId.ts";
283	284	export { route as postApiV1ConversationFiles } from "./postApiV1ConversationFiles.ts";
284	285	export { route as postApiV1ConversationMessages } from "./postApiV1ConversationMessages.ts";
		@@ -0,0 +1,20 @@
	1	import type { Route } from "../shared.ts";
	2
	3	export const route: Route = {
	4	method: "post",
	5	path: "/api/v1/contribute",
	6	summary:
	7	"An outside agent's token with no account: for { agent, repo, origin? } (a repository whose owner allows outside agents) answers 201 with a token that lasts 24 hours, may push contrib/<agent>/* there and open pulls from them, shown once; agent and origin are claimed, not verified. Presenting that token renews it, once",
	8	auth: false,
	9	role: "anonymous",
	10	status: 201,
	11	body: { agent: "string", repo: "string", origin: "string" },
	12	refusals: {
	13	invalid_agent: "agent is not an acceptable name (422)",
	14	invalid_origin: "origin is not plain text of at most 200 characters (422)",
	15	invalid_repo: "repo is not owner/name (422)",
	16	not_open: "no such repository, or one that takes no outside contributions (404)",
	17	rate_limited: "too many tokens from this address (429)",
	18	already_renewed: "the token was renewed once already (409)",
	19	},
	20	};
		@@ -0,0 +1,251 @@
	1	/**
	2	* Contribute tokens (#12012): the credential an outside agent with its own
	3	* sandbox (Codex cloud, Jules, Claude Code, Cursor) is handed to contribute by
	4	* clone and push. It is an ordinary `rw` token for a throwaway guest account the
	5	* forge makes, limited by `http/contribute_gate.ts` to: reading public
	6	* repositories, pushing `contrib/<agent>/…` branches on the one repository that
	7	* opted in, opening and reading its own pulls there. It expires in a day,
	8	* renews once, and the agent's name and origin are kept as claimed, never
	9	* verified. `allows` is the scope check: plain data in, a yes or no out.
	10	*/
	11
	12	import type { Database } from "bun:sqlite";
	13	import { isSafeRef } from "../git/guard.ts";
	14	import { sha256 } from "../kernel/hash.ts";
	15	import { createToken } from "./tokens.ts";
	16
	17	export interface ContributeScope {
	18	readonly tokenId: string;
	19	readonly repoId: string;
	20	readonly agent: string;
	21	/** `<agent>/<segment>`: the branches under `contrib/` this token alone may touch. */
	22	readonly namespace: string;
	23	}
	24
	25	/**
	26	* A segment of the push namespace that only this token has. The agent name is
	27	* claimed, so two tokens may share one; the segment (from the token's random id)
	28	* keeps one from force-pushing over or deleting the other's branches.
	29	*/
	30	export const contribSegment = (tokenId: string): string => sha256(`contribute-segment:${tokenId}`).slice(0, 8);
	31
	32	export const contribNamespace = (agent: string, tokenId: string): string => `${agent}/${contribSegment(tokenId)}`;
	33
	34	export const CONTRIBUTE_TTL_MS = 24 * 3600_000;
	35	/** A renewal never carries a token past this long after it was minted. */
	36	export const CONTRIBUTE_MAX_LIFE_MS = 7 * 24 * 3600_000;
	37	export const MINTS_PER_HOUR = 5;
	38	export const MINTS_PER_DAY = 20;
	39	/**
	40	* Pulls one token may have open, and may open in a day; and all of a repository's
	41	* outside tokens together in a day.
	42	*/
	43	export const OPEN_PULLS_PER_TOKEN = 5;
	44	export const PULLS_PER_TOKEN_DAY = 20;
	45	export const PULLS_PER_REPO_DAY = 30;
	46	export const AGENT_MAX = 64;
	47	export const ORIGIN_MAX = 200;
	48
	49	/** An agent's claimed name: letters, digits, . _ - ; it starts with a letter or digit. */
	50	export const isAgentName = (name: unknown): name is string =>
	51	typeof name === "string" && name.length <= AGENT_MAX && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) && !/\.\./.test(name);
	52
	53	/** Where the agent says it runs from: short plain text, nothing a page could misread. */
	54	export const isOrigin = (origin: unknown): origin is string =>
	55	typeof origin === "string" && origin.length <= ORIGIN_MAX && !/[\x00-\x1f\x7f<>]/.test(origin);
	56
	57	/** Whether `ref` (full `refs/heads/…`) is a branch under `contrib/<agent>/`. */
	58	export function inContribNamespace(ref: string, agent: string): boolean {
	59	const prefix = `refs/heads/contrib/${agent}/`;
	60	if (!ref.startsWith(prefix) \|\| ref.length > 200 \|\| !isSafeRef(ref)) return false;
	61	return ref
	62	.slice(prefix.length)
	63	.split("/")
	64	.every((part) => /^[A-Za-z0-9._-]+$/.test(part) && !/^\.+$/.test(part));
	65	}
	66
	67	/** A pull's head branch name (no `refs/heads/`) inside the namespace. */
	68	export const headInContribNamespace = (head: string, agent: string): boolean =>
	69	inContribNamespace(`refs/heads/${head}`, agent);
	70
	71	/**
	72	* Why this token's user may not open another pull on `repoId` now, or undefined.
	73	* Counted from the pull rows themselves: open ones by this author, and the day's
	74	* by this author and by every outside token's author on the repository.
	75	*/
	76	export function pullCapReached(
	77	db: Database,
	78	repoId: string,
	79	userId: string,
	80	now: Date,
	81	): "token_open" \| "token_day" \| "repo_day" \| undefined {
	82	const count = (sql: string, ...args: string[]): number =>
	83	db.query<{ n: number }, string[]>(sql).get(...args)?.n ?? 0;
	84	const since = new Date(now.getTime() - 86_400_000).toISOString();
	85	const mine = "SELECT COUNT(*) AS n FROM issue WHERE repo_id = ?1 AND kind = 'pull' AND author_id = ?2";
	86	if (count(`${mine} AND state = 'open'`, repoId, userId) >= OPEN_PULLS_PER_TOKEN) return "token_open";
	87	if (count(`${mine} AND created_at >= ?3`, repoId, userId, since) >= PULLS_PER_TOKEN_DAY) return "token_day";
	88	const all = count(
	89	`SELECT COUNT(*) AS n FROM issue
	90	WHERE repo_id = ?1 AND kind = 'pull' AND created_at >= ?2
	91	AND author_id IN (SELECT t.user_id FROM token t JOIN contribute_token c ON c.token_id = t.id WHERE c.repo_id = ?1)`,
	92	repoId,
	93	since,
	94	);
	95	return all >= PULLS_PER_REPO_DAY ? "repo_day" : undefined;
	96	}
	97
	98	/** What a request is, as the scope check reads it. */
	99	export interface ContributeAsk {
	100	readonly method: string;
	101	readonly path: string;
	102	/** `service` of a git info/refs request. */
	103	readonly service?: string \| null;
	104	/** The pull number the path names, when that pull is the token's own. */
	105	readonly ownPull?: boolean;
	106	}
	107
	108	/** Forge-wide reads open to the token. */
	109	const FORGE_READS = new Set(["/api/v1/here", "/api/v1/search", "/api/v1/explore", "/api/v1/openapi.json", "/api/v1/contribute"]);
	110
	111	/**
	112	* Whether the token may make this request. `repo` is the one it was minted
	113	* for. Allow-listed: a route added tomorrow is closed to it until written here.
	114	* Handlers still apply the guest account's own access on top, so a private
	115	* repository stays hidden.
	116	*/
	117	export function allows(scope: ContributeScope, repo: { owner: string; name: string }, ask: ContributeAsk): boolean {
	118	const read = ask.method === "GET" \|\| ask.method === "HEAD";
	119	const path = ask.path.toLowerCase();
	120	if (read && FORGE_READS.has(path)) return true;
	121	if (ask.method === "POST" && path === "/api/v1/contribute") return true; // renews
	122	const at = `/${repo.owner}/${repo.name}`.toLowerCase();
	123	const api = `/api/v1/repos${at}`;
	124	// The one repository: push, open a pull, and update or read its own.
	125	if (read && path === `${at}.git/info/refs` && ask.service === "git-receive-pack") return true;
	126	// Any public repository may be read: its API, and a fetch.
	127	if (read && path.startsWith("/api/v1/repos/")) return true;
	128	if (read && /^\/[^/]+\/[^/]+\.git\/info\/refs$/.test(path)) return ask.service === "git-upload-pack";
	129	if (ask.method === "POST" && /^\/[^/]+\/[^/]+\.git\/git-upload-pack$/.test(path)) return true;
	130	if (ask.method === "POST" && path === `${at}.git/git-receive-pack`) return true;
	131	if (ask.method === "POST" && path === `${api}/pulls`) return true;
	132	if ((ask.method === "PATCH" \|\| ask.method === "POST") && ask.ownPull === true && path.startsWith(`${api}/pulls/`)) return true;
	133	return false;
	134	}
	135
	136	/** The pull number a path names under `repo`'s pulls, or undefined. */
	137	export function pullNumberIn(path: string, repo: { owner: string; name: string }): number \| undefined {
	138	const head = `/api/v1/repos/${repo.owner}/${repo.name}/pulls/`.toLowerCase();
	139	const lower = path.toLowerCase();
	140	if (!lower.startsWith(head)) return undefined;
	141	const m = /^([1-9][0-9]{0,8})(?:\/\|$)/.exec(lower.slice(head.length));
	142	return m ? Number(m[1]) : undefined;
	143	}
	144
	145	// ---- the rows ----
	146
	147	/** A source (an address) is kept only as a hash: enough to count, never to read. */
	148	const sourceKey = (source: string): string => sha256(`contribute-source:${source}`).slice(0, 24);
	149
	150	export const contributeOpen = (db: Database, repoId: string): boolean =>
	151	db.query("SELECT 1 FROM contribute_open WHERE repo_id = ?1").get(repoId) !== null;
	152
	153	export function setContributeOpen(db: Database, repoId: string, on: boolean): void {
	154	if (on) db.query("INSERT OR IGNORE INTO contribute_open (repo_id) VALUES (?1)").run(repoId);
	155	else db.query("DELETE FROM contribute_open WHERE repo_id = ?1").run(repoId);
	156	}
	157
	158	export function mintsSince(db: Database, since: number, source: string): number {
	159	return (
	160	db
	161	.query<{ n: number }, [string, number]>("SELECT COUNT(*) AS n FROM contribute_mint WHERE source = ?1 AND made_at >= ?2")
	162	.get(sourceKey(source), since)?.n ?? 0
	163	);
	164	}
	165
	166	export interface Minted {
	167	readonly id: string;
	168	readonly token: string;
	169	readonly expiresAt: string;
	170	}
	171
	172	/** Mint the token for `userId` on `repoId`, and count it against `source`. */
	173	export function mintContribute(
	174	db: Database,
	175	input: { userId: string; repoId: string; agent: string; origin: string; source: string },
	176	now: Date,
	177	): Minted {
	178	const expiresAt = new Date(now.getTime() + CONTRIBUTE_TTL_MS).toISOString();
	179	const minted = createToken(db, input.userId, `contribute:${input.agent}`, "rw", { expiresAt });
	180	db.query(
	181	"INSERT INTO contribute_token (token_id, repo_id, agent, origin, minted_at) VALUES (?1, ?2, ?3, ?4, ?5)",
	182	).run(minted.id, input.repoId, input.agent, input.origin, now.toISOString());
	183	db.query("INSERT INTO contribute_mint (source, made_at) VALUES (?1, ?2)").run(sourceKey(input.source), now.getTime());
	184	// The ledger only needs the last day.
	185	db.query("DELETE FROM contribute_mint WHERE made_at < ?1").run(now.getTime() - 2 * 24 * 3600_000);
	186	return { ...minted, expiresAt };
	187	}
	188
	189	/** Extend a token by another day, once, never past a week from its minting. */
	190	export function renewContribute(
	191	db: Database,
	192	tokenId: string,
	193	now: Date,
	194	): { ok: true; expiresAt: string } \| { ok: false; error: "already_renewed" \| "not_found" } {
	195	const row = db
	196	.query<{ minted_at: string; renewed: number }, [string]>("SELECT minted_at, renewed FROM contribute_token WHERE token_id = ?1")
	197	.get(tokenId);
	198	if (row === null) return { ok: false, error: "not_found" };
	199	if (row.renewed !== 0) return { ok: false, error: "already_renewed" };
	200	const until = Math.min(now.getTime() + CONTRIBUTE_TTL_MS, Date.parse(row.minted_at) + CONTRIBUTE_MAX_LIFE_MS);
	201	const expiresAt = new Date(until).toISOString();
	202	db.transaction(() => {
	203	db.query("UPDATE token SET expires_at = ?1 WHERE id = ?2").run(expiresAt, tokenId);
	204	db.query("UPDATE contribute_token SET renewed = 1 WHERE token_id = ?1").run(tokenId);
	205	})();
	206	return { ok: true, expiresAt };
	207	}
	208
	209	export interface ContributeTokenInfo {
	210	readonly id: string;
	211	readonly agent: string;
	212	/** As the agent claimed it; never verified. */
	213	readonly origin: string;
	214	readonly mintedAt: string;
	215	readonly expiresAt: string;
	216	readonly lastUsedAt: string \| null;
	217	readonly renewed: boolean;
	218	}
	219
	220	/** The live tokens on a repository: unexpired, newest first. */
	221	export function listContribute(db: Database, repoId: string, now: Date): ContributeTokenInfo[] {
	222	return db
	223	.query<
	224	{ id: string; agent: string; origin: string; minted_at: string; expires_at: string; last_used_at: string \| null; renewed: number },
	225	[string, string]
	226	>(
	227	`SELECT c.token_id AS id, c.agent, c.origin, c.minted_at, t.expires_at, t.last_used_at, c.renewed
	228	FROM contribute_token c JOIN token t ON t.id = c.token_id
	229	WHERE c.repo_id = ?1 AND t.expires_at > ?2 ORDER BY c.minted_at DESC, c.token_id DESC`,
	230	)
	231	.all(repoId, now.toISOString())
	232	.map((r) => ({
	233	id: r.id,
	234	agent: r.agent,
	235	origin: r.origin,
	236	mintedAt: r.minted_at,
	237	expiresAt: r.expires_at,
	238	lastUsedAt: r.last_used_at,
	239	renewed: r.renewed === 1,
	240	}));
	241	}
	242
	243	/** Revoke one token of `repoId`; false when it is not one of that repository's. */
	244	export function revokeContribute(db: Database, repoId: string, tokenId: string): boolean {
	245	const own = db
	246	.query("SELECT 1 FROM contribute_token WHERE token_id = ?1 AND repo_id = ?2")
	247	.get(tokenId, repoId);
	248	if (own === null) return false;
	249	db.query("DELETE FROM token WHERE id = ?1").run(tokenId);
	250	return db.query("SELECT 1 FROM token WHERE id = ?1").get(tokenId) === null;
	251	}
		@@ -270,6 +270,8 @@ export function classifiedAudience(kind: string): EventAudience \| undefined {
270	270	kind === "repo.source_added" \|\|
271	271	kind === "repo.source_removed" \|\|
272	272	kind === "repo.crew_outsiders" \|\|
	273	// An outside agent's token and the owner's yes to them are the admins' (#12012).
	274	kind.startsWith("contribute.") \|\|
273	275	// A valve turn names a repository and the owner's budget: for those who administer it (`actions/valves.ts`).
274	276	kind === "valve.turned" \|\|
275	277	// A clog starting names the forge's own pile-up: the owner's to hear (#6524).
		@@ -0,0 +1,1 @@
	1	554897fea4417afac1f59ee8109d32bfad31859aee147c859236f3e96c1802af
		@@ -0,0 +1,28 @@
	1	// Outside agents' short-lived contribute tokens (#12012). `contribute_open` is a repository
	2	// owner's yes to them; `contribute_token` names what an ordinary token is limited to (the
	3	// repository, the agent name and origin as claimed, whether it has been renewed); `contribute_mint`
	4	// counts mints per hashed address. Deleting a repository deletes its tokens. New tables only.
	5	export default `
	6	CREATE TABLE contribute_open (
	7	repo_id TEXT PRIMARY KEY REFERENCES repo(id) ON DELETE CASCADE
	8	);
	9	CREATE TABLE contribute_token (
	10	token_id TEXT PRIMARY KEY REFERENCES token(id) ON DELETE CASCADE,
	11	repo_id TEXT NOT NULL,
	12	agent TEXT NOT NULL,
	13	origin TEXT NOT NULL,
	14	minted_at TEXT NOT NULL,
	15	renewed INTEGER NOT NULL DEFAULT 0
	16	);
	17	CREATE INDEX contribute_token_repo ON contribute_token(repo_id);
	18	CREATE TABLE contribute_mint (
	19	source TEXT NOT NULL,
	20	made_at INTEGER NOT NULL
	21	);
	22	CREATE INDEX contribute_mint_source ON contribute_mint(source, made_at);
	23
	24	CREATE TRIGGER contribute_token_repo_gone BEFORE DELETE ON repo
	25	BEGIN
	26	DELETE FROM token WHERE id IN (SELECT token_id FROM contribute_token WHERE repo_id = OLD.id);
	27	END;
	28	`;