bc552b2 · 51882d9 · a70a895 · 2cd7122 · eb71574 · 8b55eaf
@@ -13,7 +13,8 @@
routers learn it is going, so a roll refuses nobody (`docs/ops/ROLL.md`).
Connecting origins
adds `FORGE_URL` (the canonical public base URL, needed for OAuth callbacks),
`FORGE_GITHUB_CLIENT_ID` / `FORGE_GITHUB_CLIENT_SECRET`, and
`FORGE_ORIGIN_ALLOW` (hosts an operator vouches for on a LAN). Behind a
`FORGE_ORIGIN_ALLOW` (hosts an operator vouches for on a LAN, for discovery
and for that origin's git). Behind a
platform edge that signs people in for every app it serves, `FORGE_EDGE_TOKEN`
is the edge's secret: a request carrying it and `X-Plat-User` is that person,
signed in by the platform if an account of that name exists. An unknown login
@@ -70,7 +70,7 @@
them is correct.
## Connecting and mirroring, as a person does it
Outbound git refuses a host that resolves to a private address. A site admin can vouch for exact host names (the owner's own Forgejo, reached by its in-cluster address): `FORGE_OUTBOUND_TRUSTED_HOSTS=git.example.test` (comma or space separated), plus the same list editable by an admin on **Settings → Origins**. A trusted host may resolve privately for origin sync, mirror, migrate and write-through; trust is by name, never by address range, and webhooks never read it. The origin row says "trusted internal host". In the terminal, the palette's **Trusted hosts** reads and saves the same list (admins only, same audit). An entry that is not a bare host name (an address, a wildcard, a URL) is refused with its name, on the page and in the terminal, never silently dropped.
Outbound git refuses a host that resolves to a private address. A site admin can vouch for exact host names (the owner's own Forgejo, reached by its in-cluster address): `FORGE_OUTBOUND_TRUSTED_HOSTS=git.example.test` (comma or space separated), plus the same list editable by an admin on **Settings → Origins**. A trusted host may resolve privately for origin sync, mirror, migrate and write-through; trust is by name, never by address range, and webhooks never read it. A host name in `FORGE_ORIGIN_ALLOW` is trusted the same way for its origin's mirror, sync and fetch, so an origin that connects can be mirrored; an address named there is not (trust is by name). The origin row says "trusted internal host". In the terminal, the palette's **Trusted hosts** reads and saves the same list (admins only, same audit). An entry that is not a bare host name (an address, a wildcard, a URL) is refused with its name, on the page and in the terminal, never silently dropped.
A pull from an outsider's fork on the origin is someone else's code, so its
check and preview wait. A person with write access lets that exact head run:
@@ -198,6 +198,15 @@
and it is never written to a log. Both surfaces render the link as a QR code
also offers OSC 52 copy, which reaches the user's own terminal rather than the
server's clipboard.
The flow's own page (`/settings/origins/flows/:id`) links to that sealed
URL and to nothing else — never to one from its query string — after
checking it again: the instance's `/login/oauth/authorize`, the flow's
client id and callback, a PKCE challenge. A `to` an older link still
carries must equal it exactly. A flow past its ten minutes says "This
connect link expired", with a fresh **Connect**.
(`test/origin-flow-page.test.ts`; `test/oauth-connect-browser.test.ts`
clicks Authorize and Continue in headless Chromium.)
Discovery: `github.com` is known by name. Otherwise `GET /api/v1/version` —
NodeInfo is the one thing here resembling a standard and no live Forgejo
serves it, so it is only an opportunistic first probe. The version string is
@@ -211,7 +220,11 @@
resolves the name and refuses any private answer (`vetHost`, at every hop,
dialling the address it judged), refuses non-http schemes, follows no redirect
off-host, reaches loopback only in dev (`FORGE_DEV=1`), caps the body at 64 KB and times out in 5 s. An operator can vouch for a LAN
or plaintext host with `FORGE_ORIGIN_ALLOW=host[,host…]`; there is no
per-user toggle, because the risk it accepts belongs to the server.
per-user toggle, because the risk it accepts belongs to the server. A host
name vouched for there is trusted for that origin's git as well (mirror,
sync, fetch, push), as `FORGE_OUTBOUND_TRUSTED_HOSTS` is: by name, pinned to
the answer that passed. So an origin that connects can be mirrored. An
address literal named there reaches discovery only: trust is by name.
**Refresh.** A Forgejo OAuth access token lives about an hour, so it is
refreshed a minute before it expires rather than after a 401. Refreshes are
@@ -403,13 +416,38 @@
the mirror: each sync that moves the mirror's default branch fast-forwards
the fork's, so long as nothing was committed on it directly (`docs/APPS.md`,
"Forks follow their parents").
The `owner:branch` form is verified against the fakes in
`test/fork-flow.test.ts` (both dialects, with real git behind them) and it
matches both forges' documented shape. **It has not yet been run against a
live Forgejo instance**, and that is the one thing worth doing before
leaning on it: Forgejo's `head` is an undocumented plain string, and a real
instance is the only thing that can settle whether it resolves the owner the
way GitHub does.
**Reading is enough to propose.** Carrying the branch into the origin
repository needs push rights there. An account that can only read it — and
anyone at all, for a repository the operator protects
(`FORGE_ORIGIN_DENY_PUSH`) — proposes through its own fork at the origin
instead (`src/origins/fork-route.ts`): the fork it has is found (the
picker's cache, then its two possible names, then the upstream's own list
of forks for one the account owns under any name, `GET
/repos/{o}/{r}/forks`, bounded) or made (`POST
/repos/{o}/{r}/forks`, under `<owner>-<name>` when the account already uses
the name for something else); the branch is pushed into that fork, leased on
where it stands there; and the pull opens on the origin repository with the
head `<account>:<branch>`. Which way is asked of the origin when the pull
is opened (`permissions.push`), and a direct push the origin refuses falls
back to the fork. A protected repository is never pushed to from here at
all — push-through, a carried branch and a branch made on its mirror are
refused (`origin_protected`) — because a branch pushed into a repository
runs its workflows with its Actions secrets, and a pull from a fork runs
them without (Forgejo `services/actions/secret.go:43`). The same fork is
what `contribute` uses on its fork path (`ensureFork`), and a fork of a
mirror whose origin it will reach through a fork says so on its button:
**Propose via your fork**. `test/propose-via-fork.test.ts` runs it against
a real forge serving git behind the fake API.
The `owner:branch` head form is Forgejo's (v15, `routers/api/v1/repo/
pull.go`): `parseCompareInfo` splits the head on its colon (:1092), looks
the owner up (:1098) and takes that owner's fork of the base as the head
repository (`GetForkedRepo`, :1127), whatever the fork is named; the base
needs read access to code and pulls (:1162), the head read access to code
(:1175-1181). Verified live on Forgejo 15.0.9 on 2026-10-16: a read-only
account opened two pulls on a private scratch repository through its fork,
one from a branch and one from the fork's default branch (`<account>/main`),
and the scratch repository never gained a branch.
**Review states.** A review is a _verdict_ on a pull at one commit —
`approved`, `changes_requested` or `commented` — stored in `review` beside
@@ -446,6 +484,99 @@
local client (`src/cli/`) reads them over the API, clones under
`~/src/<host>/<owner>/<repo>`, keeps them fetched, and reports
ahead/behind/dirty. The server never knows local state.
## A token that lacks a scope
Forgejo answers a token without a scope with a 403 that names it (`token
does not have at least one of required scope(s): [read:user]`). The API
client reads that body (4 KB at most) and keeps only scope-shaped words, so
connecting says "This token is missing User: Read." (`missing_scopes`, 422)
and a sync error says "the token is missing Issue: Read" — not "the token
was refused", which a person cannot tell from a wrong or expired one. The
token form lists what a Forgejo token needs and, once the instance is
known, links to
`<host>/user/settings/applications/tokens/new?name=forge&resource=all&scope=read:user&scope=write:repository&scope=write:issue`,
which Forgejo 15 opens with those already chosen; on Gitea or an older
Forgejo the list says what to pick. `test/origin-token-scopes.test.ts`.
## The operator guard
A forge keeps an origin's credential on a machine where agents run, so the
risk is the account a person authorized — never the owner of this forge. On
a *guarded* host — one the operator registered an application for
(`FORGE_ORIGIN_CLIENT_ID`), or one a push rule covers
(`FORGE_ORIGIN_DENY_PUSH`) — every credential is checked after `whoami` and
before anything is stored, on all three ways in (a pasted token, the code
flow, the device flow). Both variables are read per call.
- An account that **administers the instance** (Forgejo's `is_admin`,
  GitHub's `site_admin`) is refused: "`<login>` is an administrator of
  `<host>`. Sign in to Forgejo with your everyday non-admin account and try
  again." (`admin_account`)
- An account that **can push to a protected repository** is refused, with
  the repositories named (`can_push`). The check asks the origin for
  `permissions.push` — the account's real rights, whatever scopes its token
  claims. Every pattern with no `*` is asked about by name (`GET
  /repos/{o}/{r}`, four at a time, however many there are). A wildcard
  walks the repositories the account can see (`walkRepos`): on Forgejo
  `/repos/search?uid=` sorted by id — every repository it owns,
  collaborates on or reaches through a team, every way to push — so a
  repository pushed or made during the walk cannot move into a page already
  read; with no fallback to another listing; and complete only when the
  distinct repositories seen equal `X-Total-Count`, which must not change
  between pages. On GitHub, `/user/repos` oldest first. The walk is bounded
  (20 pages); an account with more, a page that fails, or a count that does
  not add up is refused (`guard_unchecked`) — the guard fails closed. A
  confirmed hit always wins: an account seen to push to a protected
  repository is refused for that (`can_push`), even when another lookup
  failed or the walk did not finish.
- A refusal stores nothing. On the code flow the grant is revoked where the
  provider allows it (GitHub with a client secret); Forgejo has no
  revocation endpoint, so the message says the forge did not keep the token
  and where to remove the grant.
`FORGE_ORIGIN_DENY_PUSH` patterns: `owner/name`, `*` for any run of
characters inside one part, a bare `owner` meaning `owner/*`, case-
insensitive. A bare pattern covers every origin (so it also turns the
administrator check on for every origin); `host:pattern` covers one host.
Unguarded hosts behave exactly as before, so a person who runs their own
Forgejo can still connect it as its administrator.
The walk is also the person's list of repositories: on a guarded host it is
written to the picker's cache at connect, for free.
**Checked again, after it is stored** (`src/origins/credential.ts`). A
grant outlives the rights it was given with, so the guard runs again on
what is already stored:
- **On every OAuth refresh**, on the new token, before it is used: the
  request that needed the refresh fails if the account is refused.
- **By a sweep** on the sync tick: an origin on a guarded host that was never
  checked (connected before the guard, or before the operator named its
  host) at once — so on boot — and every other once a day. One origin per
  tick, half a second between its requests, so the sweep adds a trickle to
  the origin it protects. A connect that passed the guard counts as a check.
- A refusal marks the origin `needs_reauth` with the guard's sentence as
  its reason. From that moment every use of the credential fails — sync,
  write-through, push-through (no git credential is handed out), the crew's
  pulls through it — and Settings → Origins says to re-authorize, with the
  reason. A credential the origin no longer accepts (a grant revoked there)
  is refused at once. A refresh never clears `needs_reauth` — one racing a
  refusal cannot undo it; only connecting again, through the guard, does.
- **Writes wait on a check.** On a guarded host an origin whose account has
  not passed the guard — never checked yet, or a check that cannot run (the
  origin down, a count that moved) — reads and syncs but writes nothing:
  write-through (`origin_paused`), push-through, branches carried up, forks
  and pulls made there, and, in the adapter itself, any request that is not
  a read (`ProviderCredential.writable`). Settings → Origins says
  "Couldn't verify this connection; writes paused" with **Check again**
  (`POST /settings/origins/:id/check`, once a minute per origin). A failing
  check is tried again in 15 minutes; one that has not run for a day refuses
  the origin.
- When each origin last passed lives in its cursor store (`guard_checked_at`
  and friends): a cache — lose it, and the origin is checked once more.
`test/origin-guard.test.ts`.
## When a token expires
A credential dies: a token is revoked, a refresh token is spent, an OAuth
@@ -885,10 +1016,6 @@
carries token material, a `state`, or a `code`.
  it wants a spawn path of its own, and "fetching git objects" was worth more
  than that today.
- **No LFS.** A mirror of an LFS repo has the pointers, not the objects.
- **The `owner:branch` head form is unverified against a live Forgejo.** It
  is exercised against the fake in both dialects and matches the documented
  shape; Forgejo's own `head` is an undocumented plain string. Try it against
  a real instance before relying on it in anger.
- **Contributing needs a workbench.** `contribute` mirrors your fork (and, on
  the push-rights path, the upstream) if it is not mirrored already, so the
  first contribution to a large repository pays for a clone and an import.
@@ -896,6 +1023,9 @@
carries token material, a `state`, or a `code`.
  review through the origin sends the state and the body; anchored comments
  are still posted one at a time. Both forges accept comments inside the
  review payload, which is the obvious next step.
- **The guard's window is a day.** An account that gains push rights to a
  protected repository keeps its credential until the next refresh or the
  next daily sweep, whichever is first.
- **Key rotation is not built.** The sealed blob carries a `v1` version tag
  so it can be, but losing `secret.key` today means reconnecting the origins.
- **DNS rebinding is not closed.** The SSRF policy checks address _literals_;
@@ -0,0 +1,8 @@
# The operator guard and proposing through your fork (#8938)
The operator may name hosts to guard (`FORGE_ORIGIN_CLIENT_ID`, `FORGE_ORIGIN_DENY_PUSH`; see "The operator guard" in [`docs/ORIGINS.md`](../ORIGINS.md)). On such a host an origin is refused when its account administers the instance or can push to a protected repository.
- **Paused:** when the guard cannot verify an account (the host is down, say), the origin still reads and syncs but writes nothing. `/settings/origins` shows "Couldn't verify this connection; writes paused" with a **Check again** button (`POST /settings/origins/:id/check`, once a minute per origin). A refused origin shows **Needs re-auth**.
- **In the terminal:** Connected origins marks a paused origin `writes paused`, says why on the top line, and `v` checks it again, saying what it found in the page's words (`CHECK_WORDS`, `src/actions/origin_words.ts`). Test: `test/tui-origins-guard.test.ts`.
- **Try it:** set `FORGE_ORIGIN_DENY_PUSH=system/*` and connect a token that can push there on Settings → Origins; it is refused with the repository named.
- **Propose via your fork:** an account that can only read a repository, or any repository the operator protects, proposes through the account's own fork there (`src/origins/fork-route.ts`, `contribute` in `src/actions/contribute.ts`). Test: `test/propose-via-fork.test.ts`; the guard: `test/origin-guard.test.ts`.
@@ -545,14 +545,18 @@
export function besideOthers(
  return { red: stillRed, besideOthers: cleared, line };
}
const HEADER = /^(\S+\.test\.[cm]?[jt]sx?):$/;
// Under GitHub-style Actions (GITHUB_ACTIONS=true, which Forgejo's runner
// sets too) bun opens each file's tests with `::group::path:` instead of
// `path:`; the group marker is not part of the path.
const HEADER = /^(?:::group::)?(\S+\.test\.[cm]?[jt]sx?):$/;
const FAILED = /^\(fail\) /;
/**
 * The files whose tests failed in one `bun test` report, in the order the
 * report reached them: bun prints `path:` before a file's tests and
 * `(fail) name` for each one that failed. A report that names no failing
 * test (a crash, a file that would not load) yields none.
 * report reached them: bun prints `path:` (in an Actions job,
 * `::group::path:`) before a file's tests and `(fail) name` for each one
 * that failed. A report that names no failing test (a crash, a file that
 * would not load) yields none.
 */
export function failingFiles(output: string): string[] {
  const found: string[] = [];
@@ -30,7 +30,8 @@
import {
import { resolveOid } from "../git/merge.ts";
import { repoDir } from "../git/repos.ts";
import { err, ok, type Result } from "../kernel/result.ts";
import { providerForOrigin } from "../origins/credential.ts";
import { providerForOrigin, writesPaused } from "../origins/credential.ts";
import { denied } from "../origins/operator.ts";
import { redact, secretsIn } from "../origins/credentials.ts";
import { pushToOrigin, type PushUpdate } from "../origins/git-mirror.ts";
import type { WriteThroughError } from "../origins/write-through.ts";
@@ -179,6 +180,9 @@
export async function originPush(
  if (!link) return ok(undefined);
  if (link.origin.userId !== actor.id) return err("origin_owner_only");
  if (link.cloneUrl === "") return err("origin_unreachable");
  if (writesPaused(app, link.origin.id) !== undefined)
    return err("origin_paused");
  if (denied(link.origin, link.fullName)) return err("origin_protected");
  const provider = providerForOrigin(app, link.origin);
  if (!provider.ok) return err("origin_unreachable");
@@ -35,7 +35,6 @@
import { requireVerified } from "./verify.ts";
import type { App } from "../app.ts";
import {
  findOriginFork,
  getOriginFor,
  getOriginRepo,
  mirrorOf,
@@ -50,43 +49,32 @@
import { isSafeRef } from "../git/guard.ts";
import { repoDir } from "../git/repos.ts";
import type { CommitResult } from "../git/write.ts";
import { err, ok, type Result } from "../kernel/result.ts";
import { providerForOrigin } from "../origins/credential.ts";
import { providerForOrigin, writesPaused } from "../origins/credential.ts";
import { fetchRefFrom } from "../origins/git-mirror.ts";
import { importIssue } from "../origins/import.ts";
import { settled, type MirrorJob } from "../origins/jobs.ts";
import { mirrorRepo, startMirror } from "../origins/mirror.ts";
import { ensureFork, forkDeadline } from "../origins/fork-route.ts";
      
        sentinelcrew
        11d ago
        
      
      Re-export sits between imports; move it below them.
    
import { denied } from "../origins/operator.ts";
import type { Provider, RemoteRepo } from "../origins/types.ts";
import type { WriteThroughError } from "../origins/write-through.ts";
import { createBranch } from "./branches.ts";
import { editFiles, type EditFile, type EditFilesError } from "./contents.ts";
import { requireUser } from "./access.ts";
export { forkDeadline };
// ---- forking at the origin ----
/**
 * How long to wait for a fork to exist. GitHub's docs say most forks are
 * ready "within five minutes" and are in practice ready in one or two
 * seconds; thirty is long enough for the common case and short enough that a
 * request does not hang on the pathological one.
 */
const FORK_DEADLINE_MS = 30_000;
/**
 * The deadline `forkOrigin` uses when its caller names none. Mutable for the
 * same reason `firstFetchRetry` is: a test that wants the timeout shortens it
 * and puts back what it found.
 */
export const forkDeadline: { ms: number } = { ms: FORK_DEADLINE_MS };
/** Backoff between polls, in ms; the last value repeats until the deadline. */
const FORK_BACKOFF = [250, 500, 1_000, 2_000, 3_000] as const;
export type ForkOriginError =
  | "unauthorized"
  | "unverified"
  | "not_found"
  | "origin_unreachable"
  | "origin_refused"
  /** The connection is not verified against the operator's rules yet. */
  | "origin_paused"
  /** The origin took the request and the fork never appeared in time. */
  | "fork_timeout";
@@ -135,6 +123,7 @@
export async function forkOrigin(
  // Somebody else's connected account does not exist for you (invariant 9).
  const origin = getOriginFor(app.db, user.value.id, originId);
  if (!origin) return err("not_found");
  if (writesPaused(app, origin.id) !== undefined) return err("origin_paused");
  const provider = providerForOrigin(app, origin);
  if (!provider.ok) return err("origin_unreachable");
@@ -144,62 +133,15 @@
export async function forkOrigin(
      upstream.error.error === "not_found" ? "not_found" : "origin_unreachable",
    );
  const found = await existingFork(
  const forked = await ensureFork(
    app,
    origin,
    provider.value,
    upstream.value.fullName,
    options.waitMs ?? forkDeadline.ms,
  );
  let existed = found !== undefined;
  let remote = found;
  if (remote === undefined) {
    const asked = await provider.value.forkRepo(upstream.value.fullName);
    if (!asked.ok) {
      // An origin that forks in the request itself can take longer than we
      // wait for an answer, and still have done it. Before calling that a
      // failure, look for the fork under its conventional name.
      const name = upstream.value.fullName.split("/")[1] ?? "";
      const late =
        asked.error.error === "unreachable" &&
        name !== "" &&
        origin.login !== ""
          ? await awaitFork(
              provider.value,
              `${origin.login}/${name}`,
              options.waitMs ?? forkDeadline.ms,
            )
          : undefined;
      if (
        late === undefined ||
        !late.ok ||
        !sameRepo(late.value.parent, upstream.value.fullName)
      )
        return err(
          asked.error.error === "unreachable" ||
            asked.error.error === "rate_limited"
            ? "origin_unreachable"
            : "origin_refused",
        );
      remote = late.value;
    } else {
      const ready = await awaitFork(
        provider.value,
        asked.value.fullName,
        options.waitMs ?? forkDeadline.ms,
      );
      if (!ready.ok) return ready;
      remote = ready.value;
    }
    existed = false;
  }
  rememberOriginRepo(app.db, origin.id, {
    ...remote,
    // Both forges report the parent on `getRepo`; if this one did not, we
    // know it anyway, because we are the reason the fork exists.
    parent: remote.parent ?? upstream.value.fullName,
  });
  if (!forked.ok) return forked;
  const { remote, existed } = forked.value;
  app.bus.append({
    kind: "repo.forked",
@@ -251,58 +193,6 @@
export async function forkOrigin(
  return ok({ remote, mirror, job, existed });
}
/**
 * The fork of `upstream` this account already has, if any. The cache is
 * asked first (it is the picker's own answer and costs nothing); failing
 * that, the conventional name is asked for directly, because a fork made
 * outside this forge is not in the cache and forking again would be wrong.
 */
async function existingFork(
  app: App,
  origin: Origin,
  provider: Provider,
  upstream: string,
): Promise<RemoteRepo | undefined> {
  const cached = findOriginFork(app.db, origin.id, upstream);
  if (cached !== undefined) {
    const fresh = await provider.getRepo(cached.fullName);
    if (fresh.ok && sameRepo(fresh.value.parent, upstream)) return fresh.value;
  }
  const name = upstream.split("/")[1] ?? "";
  if (name === "" || origin.login === "") return undefined;
  const guess = await provider.getRepo(`${origin.login}/${name}`);
  if (guess.ok && sameRepo(guess.value.parent, upstream)) return guess.value;
  return undefined;
}
const sameRepo = (a: string | null, b: string): boolean =>
  a !== null && a.toLowerCase() === b.toLowerCase();
/** Poll until the origin admits the fork exists, or the deadline passes. */
async function awaitFork(
  provider: Provider,
  fullName: string,
  waitMs: number,
): Promise<Result<RemoteRepo, ForkOriginError>> {
  const deadline = Date.now() + waitMs;
  for (let attempt = 0; ; attempt++) {
    const found = await provider.getRepo(fullName);
    // An empty fork is still a fork; what we are waiting for is the row.
    if (found.ok) return ok(found.value);
    if (found.error.error !== "not_found")
      return err(
        found.error.error === "unreachable" ||
          found.error.error === "rate_limited"
          ? "origin_unreachable"
          : "origin_refused",
      );
    const wait =
      FORK_BACKOFF[Math.min(attempt, FORK_BACKOFF.length - 1)] ?? 3_000;
    if (Date.now() + wait > deadline) return err("fork_timeout");
    await new Promise((resolve) => setTimeout(resolve, wait));
  }
}
/** The local mirror of a remote repo at this origin, or undefined. */
function localMirror(
  app: App,
@@ -381,6 +271,7 @@
export async function contribute(
  if (!proven.ok) return proven;
  const origin = getOriginFor(app.db, user.value.id, input.originId);
  if (!origin) return err("not_found");
  if (writesPaused(app, origin.id) !== undefined) return err("origin_paused");
  const branch = input.branch.trim();
  if (!isSafeRef(branch) || branch.startsWith("refs/"))
    return err("invalid_branch");
@@ -404,7 +295,11 @@
export async function contribute(
    if (!listed.value.some((b) => b.name === base)) return err("unknown_base");
  }
  return upstream.value.permissions.push
  // Push rights decide the shape — except on a repository the operator
  // protects, which is never pushed to from here: always the fork.
  const direct =
    upstream.value.permissions.push && !denied(origin, upstream.value.fullName);
  return direct
    ? await contributeDirect(app, user.value, origin, upstream.value, {
        ...input,
        branch,
@@ -30,3 +30,12 @@
export function connectWords(error: string): string {
  };
  return words[error] ?? "That connection could not be made.";
}
/** What "Check again" found, in one sentence, on the page and in the terminal. */
export const CHECK_TOO_SOON = "It was checked a moment ago. Try again in a minute.";
export const CHECK_WORDS = {
  passed: "Verified. Writes through this connection are on again.",
  unguarded: "This connection has nothing to verify.",
  unchecked: "It still could not be verified, so writes stay paused. Try again in a few minutes.",
  refused: "This connection was refused. Reconnect it with an account the operator allows.",
} as const;
@@ -28,6 +28,7 @@
import {
  findOrigin,
  getOriginById,
  getOriginFor,
  hostOf,
  siteOf,
  linkRepoToOrigin,
  listDetachedMirrors,
@@ -55,7 +56,13 @@
import type { User } from "../core/users.ts";
import { repoDir } from "../git/repos.ts";
import { bustOrigin } from "../view/cache.ts";
import { discover } from "../origins/discover.ts";
import { providerForOrigin } from "../origins/credential.ts";
import {
  lastGuardTry,
  noteGuardPassed,
  providerForOrigin,
  recheckOrigin,
  type Recheck,
} from "../origins/credential.ts";
import { safeRemoteUrl } from "../origins/credentials.ts";
import { configureMirror, mirrorRemoteUrl } from "../origins/git-mirror.ts";
import { getJob, type MirrorJob } from "../origins/jobs.ts";
@@ -85,8 +92,10 @@
import {
  type AppRow,
  type FlowRow,
} from "../origins/oauth.ts";
import { checkCredential, type GuardRefusal } from "../origins/operator.ts";
import { forgetProvider, providerFor } from "../origins/providers/index.ts";
import { forgetTokenReach } from "../origins/token-reach.ts";
import { scopeWords } from "../origins/providers/http.ts";
import {
  requestSyncNow,
  syncOrigin,
@@ -96,6 +105,7 @@
import { open } from "../kernel/secret.ts";
import {
  staticCredential,
  type OriginKind,
  type RemoteRepo,
} from "../origins/types.ts";
import { err, ok, type Result } from "../kernel/result.ts";
import {
@@ -158,13 +168,16 @@
export interface ConnectInput {
 * Connect with a pasted token — the fallback path, and the only one that
 * works with no OAuth application registered anywhere. The token is
 * validated against the origin before it is stored, and `login` comes from
 * the origin's answer rather than anything the user typed.
 * the origin's answer rather than anything the user typed. On a host the
 * operator guards, the account behind it is checked too (`checkCredential`)
 * and a refusal stores nothing: it comes back as a `GuardRefusal`, with the
 * sentence to show.
 */
export async function connectOrigin(
  app: App,
  actor: User | undefined,
  input: ConnectInput,
): Promise<Result<Connected, ConnectError>> {
): Promise<Result<Connected, ConnectError | GuardRefusal | ScopeRefusal>> {
  const user = requireUser(actor);
  if (!user.ok) return user;
  if (tooManyAttempts(app, user.value.id)) return err("rate_limited");
@@ -177,7 +190,7 @@
export async function connectOrigin(
  );
  if (!found.ok) return err(found.error);
  const identity = await providerFor(
  const provider = providerFor(
    staticCredential({
      kind: found.value.kind,
      apiUrl: found.value.apiUrl,
@@ -185,11 +198,24 @@
export async function connectOrigin(
      software: softwareOf(found.value.software),
      token: input.token.trim(),
    }),
  ).whoami();
  if (!identity.ok)
  );
  const identity = await provider.whoami();
  if (!identity.ok) {
    // A token the origin knows but finds too narrow is not a bad token: say
    // which scope it lacks, in the words of the page that makes tokens.
    const missing = identity.error.missingScopes ?? [];
    if (missing.length > 0)
      return err({
        error: "missing_scopes",
        message: `This token is missing ${scopeWords(missing)}. ${TOKEN_NEEDS}`,
        scopes: missing,
      });
    return err(
      identity.error.error === "unreachable" ? "unreachable" : "bad_token",
    );
  }
  const guard = await checkCredential(provider, identity.value);
  if (!guard.ok) return err(guard.error);
  const stored = storeOrigin(app, user.value, {
    kind: found.value.kind,
@@ -201,9 +227,15 @@
export async function connectOrigin(
    software: softwareOf(found.value.software),
  });
  if (!stored.ok) return stored;
  if (guard.value.checked) noteGuardPassed(app, stored.value.id);
  return ok({
    ...stored.value,
    reattached: await afterConnect(app, user.value, stored.value),
    reattached: await afterConnect(
      app,
      user.value,
      stored.value,
      guard.value.listed,
    ),
  });
}
@@ -216,7 +248,8 @@
export type ReplaceTokenError =
  | "rate_limited"
  | "bad_token"
  | "unreachable"
  | "other_account";
  | "other_account"
  | GuardRefusal["error"];
/**
 * Put a new pasted token on an origin that is already connected — one that
@@ -239,7 +272,7 @@
export async function replaceOriginToken(
  const secret = token.trim();
  if (secret === "") return err("bad_token");
  const identity = await providerFor(
  const provider = providerFor(
    staticCredential({
      kind: origin.kind,
      apiUrl: origin.apiUrl,
@@ -247,13 +280,18 @@
export async function replaceOriginToken(
      software: origin.software,
      token: secret,
    }),
  ).whoami();
  );
  const identity = await provider.whoami();
  if (!identity.ok)
    return err(
      identity.error.error === "unreachable" ? "unreachable" : "bad_token",
    );
  if (identity.value.login.toLowerCase() !== origin.login.toLowerCase())
    return err("other_account");
  // A new token is a new credential: on a guarded host it passes the same
  // check a connect does, and a refusal leaves the old token as it was.
  const guard = await checkCredential(provider, identity.value);
  if (!guard.ok) return err(guard.error.error);
  renewOrigin(app.db, app.config.dataDir, origin.id, {
    token: secret,
@@ -261,6 +299,7 @@
export async function replaceOriginToken(
  });
  forgetProvider({ dataDir: app.config.dataDir, originId: origin.id });
  forgetTokenReach(app.config.dataDir, origin.id);
  if (guard.value.checked) noteGuardPassed(app, origin.id);
  app.bus.append({
    kind: "origin.connected",
    actorId: user.value.id,
@@ -277,6 +316,27 @@
export async function replaceOriginToken(
  return ok(renewed);
}
/** What a token for a Forgejo origin needs, in the token page's words. */
export const TOKEN_NEEDS =
  "A token for this forge needs User: Read, Repository: Read and write, and Issue: Read and write.";
/** A token the origin refused for a scope it lacks: which, by name. */
export interface ScopeRefusal {
  readonly error: "missing_scopes";
  readonly message: string;
  /** In the origin's words: `read:user`. */
  readonly scopes: readonly string[];
}
/** A refused connect as a stable code and the words to show for it. */
export function connectRefusal(
  error: ConnectError | GuardRefusal | ScopeRefusal,
): { code: string; message: string | undefined } {
  return typeof error === "string"
    ? { code: error, message: undefined }
    : { code: error.error, message: error.message };
}
/** A connected origin, and the frozen mirrors connecting it brought back. */
export type Connected = Origin & {
  readonly reattached: readonly Reattachment[];
@@ -406,6 +466,34 @@
export function listUserOrigins(app: App, actor: User): Origin[] {
  return listOrigins(app.db, actor.id);
}
// ---- checking again ----
/** How soon a person may ask for another check of the same origin. */
const CHECK_AGAIN_MS = 60_000;
/**
 * "Check again": the operator guard on one of the actor's origins, now
 * (`recheckOrigin`). The way out of paused writes without waiting for the
 * sweep — and, like it, refused outright when the account fails the guard.
 * Once a minute per origin at most: it is a walk of the origin's API.
 */
export async function checkOriginAgain(
  app: App,
  actor: User | undefined,
  originId: string,
): Promise<Result<Recheck, "unauthorized" | "not_found" | "too_soon">> {
  const user = requireUser(actor);
  if (!user.ok) return user;
  const origin = getOriginFor(app.db, user.value.id, originId);
  if (!origin) return err("not_found");
  const last = lastGuardTry(app, origin.id);
  if (last !== undefined && Date.now() - Date.parse(last) < CHECK_AGAIN_MS)
    return err("too_soon");
  const provider = providerForOrigin(app, origin);
  if (!provider.ok) return ok("refused");
  return ok(await recheckOrigin(app, origin, provider.value, { pauseMs: 250 }));
}
// ---- OAuth ----
export type OAuthStartError =
@@ -726,7 +814,7 @@
async function completeConnect(
    expiresAt: string | null;
  },
): Promise<{ status: "done" | "failed"; detail: string; originId?: string }> {
  const identity = await providerFor(
  const provider = providerFor(
    staticCredential({
      kind: registration.kind,
      apiUrl: registration.apiUrl,
@@ -735,9 +823,31 @@
async function completeConnect(
      software: registration.software ?? "",
      token: tokens.accessToken,
    }),
  ).whoami();
  );
  const identity = await provider.whoami();
  if (!identity.ok)
    return { status: "failed", detail: "the new token did not work" };
    return {
      status: "failed",
      detail:
        (identity.error.missingScopes ?? []).length > 0
          ? `The grant is missing ${scopeWords(identity.error.missingScopes!)}. The application asks for it; remove the grant on the instance and connect again.`
          : "the new token did not work",
    };
  // The account that consented is the one checked: an administrator's grant
  // or a protected repository's pusher is refused here, before anything is
  // stored, and the grant is revoked where the provider lets us.
  const guard = await checkCredential(provider, identity.value);
  if (!guard.ok) {
    const revoked = await revokeGrant(registration, tokens.accessToken);
    return {
      status: "failed",
      detail: `${guard.error.message} ${
        revoked.ok
          ? "The grant was revoked."
          : `This forge did not keep the token. You can remove the grant at ${hostOf(registration.webUrl)} under Settings → Applications.`
      }`,
    };
  }
  const stored = storeOrigin(app, user, {
    kind: registration.kind,
@@ -752,7 +862,8 @@
async function completeConnect(
  });
  if (!stored.ok)
    return { status: "failed", detail: ORIGIN_ALREADY_CONNECTED };
  await afterConnect(app, user, stored.value);
  if (guard.value.checked) noteGuardPassed(app, stored.value.id);
  await afterConnect(app, user, stored.value, guard.value.listed);
  return { status: "done", detail: "", originId: stored.value.id };
}
@@ -991,7 +1102,12 @@
async function afterConnect(
  app: App,
  user: User,
  origin: Origin,
  listed: readonly RemoteRepo[] | null = null,
): Promise<Reattachment[]> {
  // The guard listed what the account can see: that is the picker's list,
  // at once — no second walk of the same pages. Anywhere the guard did not
  // walk, the picker fetches it when it is opened, as before.
  if (listed !== null) cacheOriginRepos(app.db, origin.id, listed);
  const out: Reattachment[] = [];
  for (const mirror of listDetachedMirrors(app.db, {
    site: siteOf(origin.webUrl),
@@ -81,9 +81,34 @@
import {
} from "./access.ts";
import { canWrite } from "../core/repos.ts";
import { refreshPullHead as refreshHead } from "../core/following.ts";
import { getOriginRepo } from "../core/origins.ts";
import { watchPullsSoon } from "../origins/hook.ts";
import { carryBranchThrough } from "../origins/push-through.ts";
import { ownHost, pullSourceOf, sourceTrailers } from "../core/trusted_sources.ts";
import { carryBranchThrough } from "../origins/push-through.ts";
import { ensureFork, forkHead, pushToFork } from "../origins/fork-route.ts";
import { denied } from "../origins/operator.ts";
import type { WriteThrough } from "../origins/write-through.ts";
/**
 * How a fork of a mirror proposes to the mirror's origin: `direct`, its
 * branch pushed into the origin repository, when the account may push
 * there; `fork`, through the account's own fork at the origin, when it may
 * only read — and always for a repository the operator protects
 * (`FORGE_ORIGIN_DENY_PUSH`), which this forge never pushes to. The rights
 * are the origin's own answer, asked now; when it cannot be asked, the
 * cached one, and failing that the direct way, whose refusal falls back to
 * the fork.
 */
async function proposalRoute(
  app: App,
  through: WriteThrough,
): Promise<"direct" | "fork"> {
  if (denied(through.origin, through.fullName)) return "fork";
  const live = await through.provider.getRepo(through.fullName);
  if (live.ok) return live.value.permissions.push ? "direct" : "fork";
  const cached = getOriginRepo(app.db, through.origin.id, through.fullName);
  return cached?.canPush === false ? "fork" : "direct";
}
export interface OpenPullInput {
  title: string;
@@ -135,10 +160,13 @@
export async function openPull(
    if (title === "") return err("empty_title");
    // A native fork of this mirror proposing upstream: its branch is
    // carried to the origin first, under the connecting account's
    // credential like any push through, and the origin opens the pull
    // from the branch it now holds.
    // credential, and the origin opens the pull from it. Directly into the
    // origin repository when the account can push there; otherwise — and
    // always for a repository the operator protects — into the account's
    // own fork at the origin, the pull's head then `<owner>:<branch>`.
    const head = input.headRepo;
    let carriedAs = input.headBranch;
    let pullHead = input.headBranch;
    if (head !== undefined && head.id !== baseRepo.id) {
      if (
        !canRead(app.db, head, user.value) ||
@@ -152,15 +180,50 @@
export async function openPull(
      // name.
      if (input.headBranch === input.baseBranch)
        carriedAs = `${head.ownerName}/${input.headBranch}`;
      const carried = await carryBranchThrough(
        app,
        baseRepo,
        head,
        input.headBranch,
        user.value.id,
        carriedAs,
      );
      if (!carried.ok) return err(refusal(carried.error.message));
      pullHead = carriedAs;
      const route = await proposalRoute(app, through.value);
      let viaFork = route === "fork";
      if (route === "direct") {
        const carried = await carryBranchThrough(
          app,
          baseRepo,
          head,
          input.headBranch,
          user.value.id,
          carriedAs,
        );
        // The origin said no to the push itself: the account cannot write
        // there after all. Reading is enough to propose, from a fork.
        if (!carried.ok && carried.error.byOrigin !== true)
          return err(refusal(carried.error.message));
        viaFork = !carried.ok;
      }
      if (viaFork) {
        const forked = await ensureFork(
          app,
          through.value.origin,
          through.value.provider,
          through.value.fullName,
        );
        if (!forked.ok)
          return err(
            forked.error === "origin_unreachable" ||
              forked.error === "fork_timeout"
              ? "origin_unreachable"
              : "origin_refused",
          );
        const pushed = await pushToFork(
          app,
          through.value.origin,
          through.value.provider,
          forked.value.remote,
          repoDir(app.reposRoot, head.ownerName, head.name),
          input.headBranch,
          carriedAs,
        );
        if (!pushed.ok) return err("origin_refused");
        pullHead = forkHead(forked.value.remote, carriedAs);
      }
    }
    const created = await through.value.provider.createPull(
      through.value.fullName,
@@ -168,7 +231,7 @@
export async function openPull(
        title,
        body: input.body ?? "",
        base: input.baseBranch,
        head: carriedAs,
        head: pullHead,
      },
    );
    if (!created.ok) return err(refusal(created.error.error));
@@ -219,10 +219,14 @@
export function storeRefreshed(
  originId: string,
  next: { token: string; refresh?: string; expiresAt?: string | null },
): void {
  // A refresh never clears `needs_reauth`: one that races a refusal (the
  // operator guard's sweep, a dead grant) must not undo it. Only connecting
  // again — `renewOrigin`, after the guard passed — brings an origin back.
  db.query(
    `UPDATE origin SET token_enc = ?1,
       refresh_token_enc = CASE WHEN ?2 = '' THEN refresh_token_enc ELSE ?2 END,
       expires_at = ?3, needs_reauth = 0, last_error = ''
       expires_at = ?3,
       last_error = CASE WHEN needs_reauth = 1 THEN last_error ELSE '' END
     WHERE id = ?4`,
  ).run(
    seal(dataDir, next.token, originId),
@@ -644,6 +644,18 @@
export function originAware(error: string, status = 422): Response {
      409,
      "the origin refused this change; nothing was changed here either",
    );
  if (error === "origin_protected")
    return apiError(
      "origin_protected",
      409,
      "the operator protects this repository at its origin: nothing is pushed to it from here; propose the change from your fork",
    );
  if (error === "origin_paused")
    return apiError(
      "origin_paused",
      409,
      "this connection is not verified against the operator's rules yet, so writes through it are paused; nothing was changed",
    );
  return respondAccess(error, status);
}
@@ -8,7 +8,7 @@
import { contribute, forkOrigin } from "../../actions/contribute.ts";
import { CAPPED_WORDS } from "../../actions/mail.ts";
import { ORIGIN_UNREACHABLE } from "../../actions/origin_app_words.ts";
import { connectOrigin, deleteOriginApp, disconnectOrigin, listOriginApps, listPinned, listRemoteRepos, listUserOrigins, mirrorJobFor, pinRepo, pollOAuthConnect, registerOriginApp, startMirrorJob, startOAuthConnect, syncOriginNow, unpinRepo } from "../../actions/origins.ts";
import { connectOrigin, connectRefusal, deleteOriginApp, disconnectOrigin, listOriginApps, listPinned, listRemoteRepos, listUserOrigins, mirrorJobFor, pinRepo, pollOAuthConnect, registerOriginApp, startMirrorJob, startOAuthConnect, syncOriginNow, unpinRepo } from "../../actions/origins.ts";
import { addSshKey, changePassword, deleteSshKey, updateProfile } from "../../actions/users.ts";
import { VERIFY_WORDS } from "../../actions/verify_words.ts";
import { resendVerification } from "../../actions/verify.ts";
@@ -260,12 +260,16 @@
export function userRoutes(router: Router<Handler>): void {
        : {}),
      token: str(input.token),
    });
    if (!connected.ok)
    if (!connected.ok) {
      // A refusal that names its own reason (a missing scope) keeps it;
      // every other code has its sentence here.
      const refused = connectRefusal(connected.error);
      return apiError(
        connected.error,
        connected.error === "rate_limited" ? 429 : 422,
        connectMessage(connected.error),
        refused.code,
        refused.code === "rate_limited" ? 429 : 422,
        refused.message ?? connectMessage(refused.code),
      );
    }
    // The frozen mirrors connecting this account brought back, and the ones
    // it could not, each with its reason.
    return json(
@@ -102,6 +102,7 @@
import {
  originAppCreate,
  originAppDelete,
  originConnectToken,
  originCheckSubmit,
  originDisconnect,
  originOAuthStart,
  originSyncSubmit,
@@ -240,7 +241,7 @@
export function settingsRoutes(router: Router<Handler>, knownPatterns: () => rea
      ? "error=state"
      : done.value.status === "done"
        ? "connected=1"
        : `error=${encodeURIComponent(done.value.detail.slice(0, 120))}`;
        : `error=${encodeURIComponent(done.value.detail.slice(0, 300))}`;
    return new Response(null, {
      status: 303,
      headers: { location: `/settings/origins?${query}` },
@@ -263,6 +264,8 @@
export function settingsRoutes(router: Router<Handler>, knownPatterns: () => rea
  // shape for the same reason `flows` and `apps` are.
  router.add("GET", "/settings/origins/:id/mirror/:job", mirrorJobPage);
  router.add("POST", "/settings/origins/:id/sync", originSyncSubmit);
  // "Check again": the operator guard on a connection whose writes are paused.
  router.add("POST", "/settings/origins/:id/check", originCheckSubmit);
  router.add("POST", "/settings/origins/:id/delete", originDisconnect);
  router.add("POST", "/settings/origins/:id/token", originReplaceToken);
  router.add("GET", "/settings/keys", keysPage);
@@ -37,6 +37,7 @@
import { drainStreams } from "./http/sse.ts";
import { serve } from "./http/server.ts";
import { checkDue } from "./actions/upstream_follow.ts";
import { runSync } from "./origins/sync.ts";
import { runGuardSweep } from "./origins/credential.ts";
import { startForgeSsh } from "./tui/ssh.ts";
import { AppsRuntime } from "./apps/runtime.ts";
import { listApps } from "./core/apps.ts";
@@ -572,8 +573,14 @@
function positive(value: string | undefined, fallback: number): number {
// pushed to: an origin is due every ten minutes by default, and the tick only
// asks who is due — so this costs one indexed read a minute when nothing is
// connected. Like runDelivery, runSync never throws into the timer.
const syncTimer = setInterval(() => runSync(app), 60_000);
// The operator guard's sweep of stored origins rides the same tick: one
// origin a tick, the never-checked first (so on boot), every other daily.
const syncTimer = setInterval(() => {
  runSync(app);
  void runGuardSweep(app);
}, 60_000);
runSync(app); // one pass on boot: a forge that was down has fetching to do
void runGuardSweep(app);
// Which green pulls no longer merge as they stand, so the asks can leave
// them out (`crew/stale_asks.ts`): git answers, off the request path, and an
@@ -17,9 +17,14 @@
import type { App } from "../app.ts";
import {
  cacheOriginRepos,
  clearCursor,
  getCursor,
  getOriginById,
  listAllOrigins,
  markNeedsReauth,
  sealedSecrets,
  setCursor,
  storeRefreshed,
  type Origin,
} from "../core/origins.ts";
@@ -27,8 +32,14 @@
import { createLog } from "../kernel/log.ts";
import { open } from "../kernel/secret.ts";
import { err, ok, type Result } from "../kernel/result.ts";
import { appFor, refresh, type AppRegistration } from "./oauth.ts";
import { providerFor } from "./providers/index.ts";
import type { Provider, ProviderCredential, ProviderResult } from "./types.ts";
import { checkCredential, guarded } from "./operator.ts";
import { forgetProvider, providerFor } from "./providers/index.ts";
import {
  staticCredential,
  type Provider,
  type ProviderCredential,
  type ProviderResult,
} from "./types.ts";
const log = createLog("origins");
@@ -60,6 +71,12 @@
export function credentialFor(
    authKind: origin.authKind,
    software: origin.software,
    token: () => resolveToken(app, origin.id),
    writable: () => {
      const paused = writesPaused(app, origin.id);
      return paused === undefined
        ? { ok: true, value: true }
        : { ok: false, error: { error: "forbidden", message: paused } };
    },
  });
}
@@ -189,6 +206,190 @@
async function refreshOnce(app: App, originId: string): Promise<void> {
    actorId: origin.userId,
    payload: { originId, host: origin.webUrl },
  });
  // A grant outlives the rights it was given with. The account behind the
  // new token is checked again before the token is used for anything: one
  // that has since become an administrator, or can now push to a protected
  // repository, is cut off here, and `resolveToken` sees it at once.
  const fresh = getOriginById(app.db, originId);
  if (fresh !== undefined && guarded(fresh))
    await recheckOrigin(
      app,
      fresh,
      providerFor(
        staticCredential({
          kind: fresh.kind,
          apiUrl: fresh.apiUrl,
          webUrl: fresh.webUrl,
          login: fresh.login,
          authKind: "oauth",
          token: next.value.accessToken,
        }),
      ),
    );
}
// ---- the operator guard, again, on what is already stored ----
/** When the account last passed the guard. A cache: lose it, check again. */
const CHECKED = "guard_checked_at";
/** When the guard first could not run, while it still cannot. */
const UNCHECKED_SINCE = "guard_unchecked_since";
/** When the sweep last tried this origin, passed or not. */
const TRIED = "guard_tried_at";
/** A stored origin is checked again this often. */
export const GUARD_EVERY_MS = 24 * 60 * 60_000;
/** A check that could not run is tried again after this long. */
const GUARD_RETRY_MS = 15 * 60_000;
/** A check that cannot run for this long refuses the origin: fail closed. */
const GUARD_GIVE_UP_MS = 24 * 60 * 60_000;
/** The sweep's pause between requests: one origin at a time, gently. */
const SWEEP_PAUSE_MS = 500;
/** What a write through a paused origin is told, everywhere. */
export const WRITES_PAUSED =
  "This forge could not verify this connection against the operator's rules, so writes through it are paused. Reads and sync go on. Check it again under Settings → Origins.";
/**
 * Why writes through this origin are paused, or undefined when they are
 * not. On a guarded host an origin writes only once its account has passed
 * the guard, and not while a check is failing: until then it may read and
 * sync, and nothing it does reaches the origin — no write-through, no push,
 * no fork or pull made there. (A refused origin is `needs_reauth`, and does
 * nothing at all.) Fails closed: an origin never checked is paused too,
 * until the sweep or a person's "Check again" checks it.
 */
export function writesPaused(app: App, originId: string): string | undefined {
  const origin = getOriginById(app.db, originId);
  if (origin === undefined || origin.needsReauth || !guarded(origin))
    return undefined;
  const checked = getCursor(app.db, originId, CHECKED);
  const failing = getCursor(app.db, originId, UNCHECKED_SINCE);
  return checked === undefined || failing !== undefined
    ? WRITES_PAUSED
    : undefined;
}
/** When the guard last tried this origin, if it ever did. */
export function lastGuardTry(app: App, originId: string): string | undefined {
  return getCursor(app.db, originId, TRIED);
}
/** Record that this origin's account passed the guard now (a connect did). */
export function noteGuardPassed(app: App, originId: string): void {
  setCursor(app.db, originId, CHECKED, new Date().toISOString());
  clearCursor(app.db, originId, UNCHECKED_SINCE);
}
export type Recheck = "passed" | "refused" | "unchecked" | "unguarded";
/**
 * The guard (`origins/operator.ts`) on an origin already stored: after an
 * OAuth refresh, and on the sweep. A refusal marks it `needs_reauth` with
 * the guard's sentence as the reason, so nothing — sync, write-through,
 * push-through, the crew's pulls — uses the credential again until a person
 * reconnects with an account the operator allows. A check that cannot run
 * is retried; one that has not run for a day refuses the origin as well.
 */
export async function recheckOrigin(
  app: App,
  origin: Origin,
  provider: Provider,
  options: { pauseMs?: number } = {},
): Promise<Recheck> {
  if (!guarded(origin)) return "unguarded";
  if (getOriginById(app.db, origin.id)?.needsReauth !== false) return "refused";
  setCursor(app.db, origin.id, TRIED, new Date().toISOString());
  const identity = await provider.whoami();
  const verdict = identity.ok
    ? await checkCredential(provider, identity.value, process.env, options)
    : undefined;
  if (verdict?.ok === true) {
    noteGuardPassed(app, origin.id);
    if (verdict.value.listed !== null)
      cacheOriginRepos(app.db, origin.id, verdict.value.listed);
    return "passed";
  }
  if (verdict !== undefined && verdict.error.error !== "guard_unchecked") {
    refuse(app, origin, verdict.error.message);
    return "refused";
  }
  // A credential the origin no longer takes (a grant revoked there) is a
  // reconnect, said now, not a day of quiet failures.
  if (!identity.ok && identity.error.error === "unauthorized") {
    refuse(app, origin, "The origin no longer accepts this credential. Reconnect it.");
    return "refused";
  }
  const since = getCursor(app.db, origin.id, UNCHECKED_SINCE);
  if (since === undefined) {
    setCursor(app.db, origin.id, UNCHECKED_SINCE, new Date().toISOString());
  } else if (Date.now() - Date.parse(since) >= GUARD_GIVE_UP_MS) {
    refuse(
      app,
      origin,
      "This forge could not check this account against the operator's rules for a day. Reconnect it.",
    );
    return "refused";
  }
  return "unchecked";
}
function refuse(app: App, origin: Origin, reason: string): void {
  // Already refused (a refresh's check inside this one): its reason stands.
  if (getOriginById(app.db, origin.id)?.needsReauth !== false) return;
  markNeedsReauth(app.db, origin.id, reason);
  forgetProvider({ dataDir: app.config.dataDir, originId: origin.id });
  announceReauth(app, origin, reason);
  log.warn("origin refused by the operator guard", {
    origin: origin.id,
    host: origin.webUrl,
  });
}
/** Whether the sweep owes this origin a check now. */
function due(app: App, origin: Origin, now: number): boolean {
  if (origin.needsReauth || !guarded(origin)) return false;
  const tried = getCursor(app.db, origin.id, TRIED);
  if (tried !== undefined && now - Date.parse(tried) < GUARD_RETRY_MS)
    return false;
  const checked = getCursor(app.db, origin.id, CHECKED);
  return checked === undefined || now - Date.parse(checked) >= GUARD_EVERY_MS;
}
const sweeping = new WeakSet<App>();
/**
 * The guard over every stored origin on a guarded host: one never checked
 * (connected before the guard existed, or before the operator named its
 * host) at once, every other once a day. One origin per call — the sync
 * tick calls it each minute — with its requests spaced out, so the sweep
 * never adds more than a trickle to the origin it protects. Single-flight
 * per forge; never throws.
 */
export function runGuardSweep(app: App): Promise<void> {
  if (sweeping.has(app)) return Promise.resolve();
  const now = Date.now();
  // Paused origins first: their writes wait on this check.
  const owed = listAllOrigins(app.db).filter((o) => due(app, o, now));
  const origin =
    owed.find((o) => writesPaused(app, o.id) !== undefined) ?? owed[0];
  if (origin === undefined) return Promise.resolve();
  sweeping.add(app);
  return (async () => {
    const provider = providerForOrigin(app, origin);
    if (!provider.ok) return;
    await recheckOrigin(app, origin, provider.value, {
      pauseMs: SWEEP_PAUSE_MS,
    });
  })()
    .catch((error: unknown) => {
      log.warn("origin guard sweep failed", {
        origin: origin.id,
        error: String(error),
      });
    })
    .finally(() => sweeping.delete(app));
}
function announceReauth(app: App, origin: Origin, reason: string): void {
@@ -54,6 +54,25 @@
function allowedHosts(env: Record<string, string | undefined>): Set<string> {
  );
}
/**
 * Whether the operator named this URL's host in `FORGE_ORIGIN_ALLOW`: its
 * `host:port` for that port, or its bare hostname for every port. Discovery
 * reads it, and so does the mirror's git (`origins/git-mirror.ts`), so a
 * host an origin may be connected from is a host it may be mirrored from.
 */
export function operatorAllowed(
  href: string,
  env: Record<string, string | undefined> = process.env,
): boolean {
  const url = URL.parse(href);
  if (url === null) return false;
  const allowed = allowedHosts(env);
  return (
    allowed.has(url.host.toLowerCase()) ||
    allowed.has(url.hostname.toLowerCase())
  );
}
/** A development instance (`FORGE_DEV=1`, also set for the test suite). */
function isDev(env: Record<string, string | undefined>): boolean {
  return env.FORGE_DEV === "1";
@@ -147,11 +166,7 @@
export function allowedOrigin(
  if (url.hostname === "") return undefined;
  if (url.protocol !== "https:" && url.protocol !== "http:") return undefined;
  const allowed = allowedHosts(env);
  const named =
    allowed.has(url.host.toLowerCase()) ||
    allowed.has(url.hostname.toLowerCase());
  if (named) return url.origin;
  if (operatorAllowed(url.href, env)) return url.origin;
  if (isDev(env) && isLoopback(url.hostname)) return url.origin;
  if (url.protocol !== "https:") return undefined;
  if (isPrivateLiteral(url.hostname)) return undefined;
@@ -294,12 +309,9 @@
function exempt(
  href: string,
  env: Record<string, string | undefined>,
): boolean {
  const url = new URL(href);
  const allowed = allowedHosts(env);
  return (
    allowed.has(url.host.toLowerCase()) ||
    allowed.has(url.hostname.toLowerCase()) ||
    (isDev(env) && isLoopback(url.hostname))
    operatorAllowed(href, env) ||
    (isDev(env) && isLoopback(new URL(href).hostname))
  );
}
@@ -0,0 +1,268 @@
/**
 * Proposing through the account's own fork at the origin — the way to
 * contribute to a repository the account can only read, and the only way
 * this forge ever proposes to a repository the operator protects.
 *
 * Reading is enough to contribute: anyone who can read a repository can fork
 * it and open a pull from the fork. On Forgejo 15 the pull's head is
 * `<owner>:<branch>`: `parseCompareInfo` (routers/api/v1/repo/pull.go:1092)
 * splits it on the colon, looks the owner up (:1098) and takes the head
 * repository to be that owner's fork of the base (`GetForkedRepo`, :1127),
 * whatever the fork is named; the base needs only read access for code and
 * pulls (:1162), the head read access for code (:1175-1181). GitHub reads
 * the same form. And a pull from a fork runs the base's workflows without
 * its Actions secrets (services/actions/secret.go:43), which is why a
 * protected repository is always proposed to from a fork, never from a
 * branch pushed into it.
 *
 * This file holds the pieces both callers share: finding or making the fork
 * (`contribute`'s fork step, and `openPull` on a mirror), and carrying a
 * branch into it. Pushing into the account's own fork is never a push to the
 * repository being proposed to.
 */
import type { App } from "../app.ts";
import {
  findOriginFork,
  getOriginRepo,
  originForRepo,
  rememberOriginRepo,
  type Origin,
} from "../core/origins.ts";
import type { Repo } from "../core/repos.ts";
import { denied } from "./operator.ts";
import { resolveOid } from "../git/merge.ts";
import { err, ok, type Result } from "../kernel/result.ts";
import { writesPaused } from "./credential.ts";
import { redact, secretsIn } from "./credentials.ts";
import { pushToOrigin } from "./git-mirror.ts";
import type { Provider, RemoteRepo } from "./types.ts";
/**
 * How long to wait for a fork to exist. GitHub's docs say most forks are
 * ready "within five minutes" and are in practice ready in one or two
 * seconds; thirty is long enough for the common case and short enough that a
 * request does not hang on the pathological one.
 */
const FORK_DEADLINE_MS = 30_000;
/**
 * The deadline a fork waits for when its caller names none. Mutable for the
 * same reason `firstFetchRetry` is: a test that wants the timeout shortens it
 * and puts back what it found.
 */
export const forkDeadline: { ms: number } = { ms: FORK_DEADLINE_MS };
/** Backoff between polls, in ms; the last value repeats until the deadline. */
const FORK_BACKOFF = [250, 500, 1_000, 2_000, 3_000] as const;
/** Pushing a branch into the fork: the same cap as any push through. */
const PUSH_TIMEOUT_MS = 120_000;
export type EnsureForkError =
  | "origin_unreachable"
  | "origin_refused"
  /** The origin took the request and the fork never appeared in time. */
  | "fork_timeout";
export const sameRepo = (a: string | null, b: string): boolean =>
  a !== null && a.toLowerCase() === b.toLowerCase();
/**
 * The name a fork takes when the account already has an unrelated
 * repository by the upstream's name: `<upstream owner>-<name>`.
 */
const secondName = (upstream: string): string => upstream.replace("/", "-");
/**
 * The fork of `upstream` this account already has, if any. The cache is
 * asked first (it is the picker's own answer and costs nothing); failing
 * that, the two names a fork made here can have are asked for directly — a
 * fork made outside this forge is not in the cache, and forking again would
 * be refused by the origin (one fork per account).
 */
export async function existingFork(
  app: App,
  origin: Origin,
  provider: Provider,
  upstream: string,
): Promise<RemoteRepo | undefined> {
  const cached = findOriginFork(app.db, origin.id, upstream);
  if (cached !== undefined) {
    const fresh = await provider.getRepo(cached.fullName);
    if (fresh.ok && sameRepo(fresh.value.parent, upstream)) return fresh.value;
  }
  const name = upstream.split("/")[1] ?? "";
  if (name === "" || origin.login === "") return undefined;
  for (const guess of [name, secondName(upstream)]) {
    const found = await provider.getRepo(`${origin.login}/${guess}`);
    if (found.ok && sameRepo(found.value.parent, upstream)) return found.value;
  }
  // Renamed, or made under a name of its own: the upstream's own list of
  // forks names it by owner (bounded; one account has one fork of a repo).
  const forks = await provider.listForks(upstream);
  if (!forks.ok) return undefined;
  const mine = forks.value.find(
    (f) => f.owner.toLowerCase() === origin.login.toLowerCase(),
  );
  if (mine === undefined) return undefined;
  const fresh = await provider.getRepo(mine.fullName);
  return fresh.ok ? fresh.value : undefined;
}
/** Poll until the origin admits the fork exists, or the deadline passes. */
export async function awaitFork(
  provider: Provider,
  fullName: string,
  waitMs: number,
): Promise<Result<RemoteRepo, EnsureForkError>> {
  const deadline = Date.now() + waitMs;
  for (let attempt = 0; ; attempt++) {
    const found = await provider.getRepo(fullName);
    // An empty fork is still a fork; what we are waiting for is the row.
    if (found.ok) return ok(found.value);
    if (found.error.error !== "not_found")
      return err(
        found.error.error === "unreachable" ||
          found.error.error === "rate_limited"
          ? "origin_unreachable"
          : "origin_refused",
      );
    const wait =
      FORK_BACKOFF[Math.min(attempt, FORK_BACKOFF.length - 1)] ?? 3_000;
    if (Date.now() + wait > deadline) return err("fork_timeout");
    await new Promise((resolve) => setTimeout(resolve, wait));
  }
}
/**
 * The account's fork of `upstream` at the origin: the one it has, or a new
 * one. Idempotent — GitHub answers a repeat `POST /forks` with the existing
 * fork and Forgejo answers 409, so the check is ours. When the account
 * already owns an unrelated repository by the upstream's name, the fork is
 * made under a second name (`<owner>-<name>`); the pull's head form names
 * the owner, not the repository, so the name does not matter to it.
 */
export async function ensureFork(
  app: App,
  origin: Origin,
  provider: Provider,
  upstream: string,
  waitMs: number = forkDeadline.ms,
): Promise<Result<{ remote: RemoteRepo; existed: boolean }, EnsureForkError>> {
  const found = await existingFork(app, origin, provider, upstream);
  if (found !== undefined) {
    remember(app, origin, found, upstream);
    return ok({ remote: found, existed: true });
  }
  const name = upstream.split("/")[1] ?? "";
  const failed = (error: string): EnsureForkError =>
    error === "unreachable" || error === "rate_limited"
      ? "origin_unreachable"
      : "origin_refused";
  let asked = await provider.forkRepo(upstream);
  if (!asked.ok && asked.error.error !== "unreachable" && name !== "") {
    // Refused: the usual reason is a repository of the account's own by
    // the same name. Then the fork takes the second name.
    const taken = await provider.getRepo(`${origin.login}/${name}`);
    if (taken.ok && !sameRepo(taken.value.parent, upstream))
      asked = await provider.forkRepo(upstream, secondName(upstream));
  }
  let remote: RemoteRepo;
  if (asked.ok) {
    const ready = await awaitFork(provider, asked.value.fullName, waitMs);
    if (!ready.ok) return ready;
    remote = ready.value;
  } else {
    // An origin that forks in the request itself can take longer than we
    // wait for an answer, and still have done it. Before calling that a
    // failure, look for the fork under its conventional name.
    if (asked.error.error !== "unreachable" || name === "" || origin.login === "")
      return err(failed(asked.error.error));
    const late = await awaitFork(provider, `${origin.login}/${name}`, waitMs);
    if (!late.ok || !sameRepo(late.value.parent, upstream))
      return err(failed(asked.error.error));
    remote = late.value;
  }
  remember(app, origin, remote, upstream);
  return ok({ remote, existed: false });
}
/** The picker row for the fork, with the parent we know it has. */
function remember(
  app: App,
  origin: Origin,
  remote: RemoteRepo,
  upstream: string,
): void {
  // Both forges report the parent on `getRepo`; if this one did not, we
  // know it anyway, because we are the reason the fork exists.
  rememberOriginRepo(app.db, origin.id, {
    ...remote,
    parent: remote.parent ?? upstream,
  });
}
/**
 * Whether a proposal to this mirror's origin goes through the account's
 * fork, as far as this forge knows without asking: the operator protects
 * the repository, or the picker's cache says the account cannot push there.
 * What a surface says on its button; `openPull` asks the origin itself.
 */
export function proposesViaFork(app: App, mirror: Repo): boolean {
  const link = originForRepo(app.db, mirror.id);
  if (link === undefined) return false;
  if (denied(link.origin, link.fullName)) return true;
  return getOriginRepo(app.db, link.origin.id, link.fullName)?.canPush === false;
}
/** The pull's head for a branch of the account's fork: `<owner>:<branch>`. */
export const forkHead = (fork: RemoteRepo, branch: string): string =>
  `${fork.owner}:${branch}`;
/**
 * Carry a branch of a local repository into the account's fork at the
 * origin, as `as`, leased on where that branch stands in the fork now (a
 * new branch must not exist yet). Answers the tip it carried.
 */
export async function pushToFork(
  app: App,
  origin: Origin,
  provider: Provider,
  fork: RemoteRepo,
  dir: string,
  branch: string,
  as: string,
): Promise<Result<string, string>> {
  // Its callers ask too; this is the push itself asking, so no path that
  // forgets cannot write through an origin whose account is not verified.
  const paused = writesPaused(app, origin.id);
  if (paused !== undefined) return err(paused);
  const tip = await resolveOid(dir, `refs/heads/${branch}`);
  if (tip === undefined) return err(`there is no branch ${branch} to propose`);
  if (fork.cloneUrl === "") return err(`${fork.fullName} has no clone URL`);
  const authEnv = await provider.gitAuthEnv(fork.cloneUrl);
  if (Object.keys(authEnv).length === 0)
    return err("this origin needs to be reconnected");
  const branches = await provider.listBranches(fork.fullName);
  if (!branches.ok) return err(`${fork.fullName} could not be read`);
  const held =
    branches.value.find((b) => b.name === as)?.oid ?? "0".repeat(40);
  if (held === tip) return ok(tip);
  const pushed = await pushToOrigin(
    dir,
    fork.cloneUrl,
    [{ ref: `refs/heads/${as}`, oldOid: held, newOid: tip }],
    authEnv,
    { timeoutMs: PUSH_TIMEOUT_MS },
  );
  if (!pushed.ok)
    return err(
      redact(
        `${fork.fullName} refused the branch: ${pushed.error.message}`,
        ...secretsIn(authEnv),
      ),
    );
  return ok(tip);
}
@@ -25,6 +25,7 @@
import { listRefs } from "../git/read.ts";
import { ZERO_OID } from "../git/hooks.ts";
import { err, ok, type Result } from "../kernel/result.ts";
import { trustedHosts } from "./trusted-hosts.ts";
import { operatorAllowed } from "./discover.ts";
import { vetHost, type OutboundOptions } from "../kernel/outbound.ts";
import { pinFor, remoteGitEnv } from "../git/remote-env.ts";
import { redact, safeRemoteUrl, secretsIn } from "./credentials.ts";
@@ -66,7 +67,13 @@
export async function vettedEnv(
  protocols?: string,
): Promise<Result<Record<string, string>, GitMirrorError>> {
  const host = new URL(url).hostname;
  const vetted = await vetHost(host, { ...outbound, trusted: trustedHosts() });
  // A host the operator vouched for as an origin (`FORGE_ORIGIN_ALLOW`) is
  // trusted for that origin's git as an admin-trusted host is: by name, and
  // pinned to the answer that passed. Otherwise it connects and can never
  // be mirrored. An address literal named there is not trusted: trust is by
  // name, never by address (`origins/trusted-hosts.ts`).
  const trusted = operatorAllowed(url) ? [...trustedHosts(), host] : trustedHosts();
  const vetted = await vetHost(host, { ...outbound, trusted });
  if (!vetted.ok)
    return err({
      message: vetted.error === "refused" ? MIRROR_REFUSED : MIRROR_UNRESOLVED,
@@ -527,6 +527,27 @@
export function targetForShortCode(
  return opened.ok ? opened.value : undefined;
}
/**
 * Where a pending flow sends the person — the authorize URL a code flow was
 * started with, or a device flow's verification page — as it was sealed on
 * the row when the flow began. Expiry is the caller's to judge (a page says
 * "expired"; a short link just stops answering).
 */
export function flowTarget(
  db: Database,
  dataDir: string,
  flowId: string,
): string | undefined {
  const row = db
    .query<RawFlow, [string]>(
      "SELECT * FROM oauth_flow WHERE id = ?1 AND status = 'pending'",
    )
    .get(flowId);
  if (!row || row.target_enc === "") return undefined;
  const opened = open(dataDir, row.target_enc, row.id);
  return opened.ok ? opened.value : undefined;
}
export function getFlow(db: Database, flowId: string): FlowRow | undefined {
  const row = db
    .query<RawFlow, [string]>("SELECT * FROM oauth_flow WHERE id = ?1")
@@ -0,0 +1,305 @@
/**
 * What the operator decides about the credentials people connect, read from
 * the environment on each call: the guard.
 *
 * On a guarded host — one the operator registered an OAuth application for
 * (`FORGE_ORIGIN_CLIENT_ID`), or one a push rule covers
 * (`FORGE_ORIGIN_DENY_PUSH`) — a credential is checked before it is stored,
 * after each OAuth refresh, and daily (`origins/credential.ts`). An account
 * that administers the instance is refused, and so is an account that can
 * push to a repository `FORGE_ORIGIN_DENY_PUSH` protects. The risk is the
 * account the person authorized, not who owns this forge: a forge holds its
 * credential where agents run.
 *
 * A leaf module: parsing and one check over a `Provider`, no database.
 */
import { err, ok, type Result } from "../kernel/result.ts";
import type { Provider, RemoteIdentity, RemoteRepo } from "./types.ts";
type Env = Record<string, string | undefined>;
/** `git.example` from `https://git.example:8443/api/v1`: lower-case, no port. */
export function hostnameOf(url: string): string {
  // A bare `host:port` parses as a URL whose scheme is the host.
  const parsed = URL.parse(url.includes("://") ? url : `https://${url}`);
  return parsed === null ? "" : parsed.hostname.toLowerCase();
}
/**
 * The hostnames the operator registered an OAuth application for, in the
 * order it named them — the same entries `operatorClientId` reads.
 */
export function operatorHosts(env: Env = process.env): string[] {
  const out: string[] = [];
  for (const entry of (env.FORGE_ORIGIN_CLIENT_ID ?? "").split(",")) {
    const at = entry.indexOf("=");
    if (at === -1) continue;
    const host = entry.slice(0, at).trim().toLowerCase();
    if (host !== "" && entry.slice(at + 1).trim() !== "" && !out.includes(host))
      out.push(host);
  }
  return out;
}
/**
 * One entry of a list keyed by host: `host:owner/name` or `owner/name`.
 * The host is everything before the last `:` ahead of the first `/`, so a
 * port (`git.example:8443:owner/name`) survives; it is matched by hostname.
 */
function splitHost(entry: string): { host: string | null; rest: string } {
  const slash = entry.indexOf("/");
  const head = slash === -1 ? entry : entry.slice(0, slash);
  const colon = head.lastIndexOf(":");
  if (colon === -1) return { host: null, rest: entry };
  return {
    host: hostnameOf(entry.slice(0, colon)) || null,
    rest: entry.slice(colon + 1),
  };
}
// ---- the push guard ----
export interface DenyRule {
  /** The hostname it covers, or null for every origin. */
  readonly host: string | null;
  /** `owner/name`, `*` for any run of characters within one part. */
  readonly pattern: string;
  /** No wildcard: one repository, asked about by name. */
  readonly exact: boolean;
  readonly matches: (fullName: string) => boolean;
}
const PART = /^[A-Za-z0-9._*-]+$/;
/**
 * `FORGE_ORIGIN_DENY_PUSH`: comma-separated `owner/name` patterns, `*` for
 * any run of characters inside one part (`system/*`, `acme/app-*`). A bare
 * `owner` means `owner/*`. A `host:` in front limits an entry to that host;
 * without one it covers every origin. Case does not matter, as on Forgejo.
 */
export function denyPushRules(env: Env = process.env): DenyRule[] {
  const out: DenyRule[] = [];
  for (const raw of (env.FORGE_ORIGIN_DENY_PUSH ?? "").split(",")) {
    const entry = raw.trim();
    if (entry === "") continue;
    const { host, rest } = splitHost(entry);
    const parts = rest.split("/");
    const [owner, name = "*"] = parts;
    if (parts.length > 2 || owner === undefined) continue;
    if (!PART.test(owner) || !PART.test(name)) continue;
    const pattern = `${owner}/${name}`.toLowerCase();
    const re = new RegExp(
      `^${pattern
        .split("*")
        .map((s) => s.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
        .join("[^/]*")}$`,
    );
    out.push({
      host,
      pattern,
      exact: !pattern.includes("*"),
      matches: (fullName) => re.test(fullName.toLowerCase()),
    });
  }
  return out;
}
/** The rules that cover one host. */
export function rulesForHost(
  rules: readonly DenyRule[],
  host: string,
): DenyRule[] {
  return rules.filter((r) => r.host === null || r.host === host);
}
/**
 * Whether the operator protects this repository on this origin
 * (`FORGE_ORIGIN_DENY_PUSH`). Such a repository is never pushed to from
 * this forge, whatever the credential could do: a change to it is proposed
 * from the account's own fork (`origins/fork-route.ts`), whose pulls run the
 * base's workflows without its secrets.
 */
export function denied(
  origin: { apiUrl: string; webUrl: string },
  fullName: string,
  env: Env = process.env,
): boolean {
  const rules = denyPushRules(env);
  return hostsOf(origin).some((h) =>
    rulesForHost(rules, h).some((r) => r.matches(fullName)),
  );
}
/** The hostnames an origin answers to: its web host and its API host. */
const hostsOf = (origin: { apiUrl: string; webUrl: string }): string[] =>
  [...new Set([hostnameOf(origin.webUrl), hostnameOf(origin.apiUrl)])].filter(
    (h) => h !== "",
  );
/**
 * Whether the guard covers this origin: the operator registered an
 * application for its host, or a push rule covers it. Anywhere else a
 * person connects what they like, as before.
 */
export function guarded(
  origin: { apiUrl: string; webUrl: string },
  env: Env = process.env,
): boolean {
  const hosts = hostsOf(origin);
  const operator = operatorHosts(env);
  if (hosts.some((h) => operator.includes(h))) return true;
  const rules = denyPushRules(env);
  return hosts.some((h) => rulesForHost(rules, h).length > 0);
}
export type GuardError = "admin_account" | "can_push" | "guard_unchecked";
/** Why a credential was refused, in one sentence a person can act on. */
export interface GuardRefusal {
  readonly error: GuardError;
  readonly message: string;
  /** For `can_push`: the protected repositories it can push to. */
  readonly repos: readonly string[];
}
export interface GuardPass {
  /**
   * The repositories the account can see, when the walk ran (every guarded
   * host): the picker's cache, filled for free.
   */
  readonly listed: readonly RemoteRepo[] | null;
  /** The guard covered this host and the account passed it. */
  readonly checked: boolean;
}
/** Pages of the account's repositories the check walks: 20 × the page size. */
export const GUARD_MAX_PAGES = 20;
/**
 * Repositories named outright are asked about this many at a time. Every
 * one is asked about: a rule past some count is never skipped.
 */
const EXACT_AT_ONCE = 4;
const forgeName = (kind: Provider["kind"]): string =>
  kind === "github" ? "GitHub" : kind === "gitea" ? "Gitea" : "Forgejo";
function named(repos: readonly string[]): string {
  const shown = repos.slice(0, 3).join(", ");
  return repos.length > 3 ? `${shown} and ${repos.length - 3} more` : shown;
}
const unchecked = (): GuardRefusal => ({
  error: "guard_unchecked",
  message:
    "This forge could not check which repositories this account can push to. Try again in a minute.",
  repos: [],
});
const pause = (ms: number): Promise<void> =>
  ms > 0 ? new Promise((resolve) => setTimeout(resolve, ms)) : Promise.resolve();
/**
 * Check a credential: before it is stored, after each OAuth refresh, and on
 * the daily sweep of stored origins (`origins/credential.ts`). `identity` is
 * what `whoami` just said about it; `provider` is built on the same
 * credential. `pauseMs` spaces the requests out — the sweep's, so a forge
 * re-checking its origins never leans on the origin it checks.
 *
 * The push check asks the origin for `permissions.push` — the account's
 * real rights, whatever scopes the token claims. A repository named outright
 * is asked about by name (`GET /repos/{o}/{r}`), every one of them; a
 * wildcard walks every repository the account can see (`walkRepos`), which
 * on Forgejo is every repository it owns, collaborates on or reaches through
 * a team — every way to push. The walk is ordered so nothing moves under it,
 * bounded, and counted; one that fails or does not finish refuses the
 * account rather than waving it through: the guard fails closed.
 */
export async function checkCredential(
  provider: Provider,
  identity: RemoteIdentity,
  env: Env = process.env,
  options: { pauseMs?: number } = {},
): Promise<Result<GuardPass, GuardRefusal>> {
  if (!guarded(provider, env)) return ok({ listed: null, checked: false });
  const host = hostnameOf(provider.webUrl);
  if (identity.siteAdmin)
    return err({
      error: "admin_account",
      message: `${identity.login} is an administrator of ${host}. Sign in to ${forgeName(provider.kind)} with your everyday non-admin account and try again.`,
      repos: [],
    });
  const rules = hostsOf(provider).flatMap((h) =>
    rulesForHost(denyPushRules(env), h),
  );
  const pushable = new Set<string>();
  const pauseMs = options.pauseMs ?? 0;
  // A confirmed hit is the answer, whatever else could not be read: an
  // account that can push to one protected repository is refused for that,
  // never let off as "could not check" because another lookup failed.
  const hit = (): Result<GuardPass, GuardRefusal> => {
    const repos = [...pushable].sort();
    return err({
      error: "can_push",
      message: `${identity.login} can push to ${named(repos)}. This forge does not accept an account that can push there. Connect an account without that access.`,
      repos,
    });
  };
  const exact = [...new Set(rules.filter((r) => r.exact).map((r) => r.pattern))];
  let failed = false;
  for (let at = 0; at < exact.length; at += EXACT_AT_ONCE) {
    if (at > 0) await pause(pauseMs);
    const answers = await Promise.all(
      exact.slice(at, at + EXACT_AT_ONCE).map((name) => provider.getRepo(name)),
    );
    for (const found of answers) {
      if (found.ok) {
        if (found.value.permissions.push) pushable.add(found.value.fullName);
        continue;
      }
      // A repository the account cannot see is one it cannot push to.
      if (found.error.error === "not_found" || found.error.error === "forbidden")
        continue;
      failed = true;
    }
    if (pushable.size > 0) return hit();
  }
  // The walk runs on every guarded host: it is the person's list of
  // repositories too, which the picker shows the moment they are back.
  // Only a wildcard rule needs it whole, so only then does a short or failed
  // walk refuse the account — after any hit in what it did read.
  const needed = rules.some((r) => !r.exact);
  if (needed) await pause(exact.length > 0 ? pauseMs : 0);
  const walked = await provider.walkRepos({
    maxPages: GUARD_MAX_PAGES,
    pauseMs,
  });
  if (needed && walked.ok)
    for (const repo of walked.value.repos)
      if (repo.permissions.push && rules.some((r) => r.matches(repo.fullName)))
        pushable.add(repo.fullName);
  if (pushable.size > 0) return hit();
  if (failed) return err(unchecked());
  if (needed) {
    if (!walked.ok) return err(unchecked());
    if (!walked.value.complete)
      return err(
        walked.value.why === "too_many"
          ? {
              error: "guard_unchecked",
              message:
                "This account can see more repositories than this forge can check. Connect an account with access to fewer repositories.",
              repos: [],
            }
          : unchecked(),
      );
  }
  return ok({
    listed: walked.ok && walked.value.complete ? [...walked.value.repos] : null,
    checked: true,
  });
}
@@ -41,6 +41,8 @@
export class ForgeProvider extends ForgejoProvider {
      login,
      displayName: asString(field(result.value.data, "displayName")) || login,
      htmlUrl: `${this.webUrl}/${login}`,
      // `isAdmin` on a forge's own `/user`: the guard refuses such an account.
      siteAdmin: field(result.value.data, "isAdmin") === true,
    });
  }
@@ -81,6 +83,10 @@
export class ForgeProvider extends ForgejoProvider {
        default_branch: field(raw, "defaultBranch"),
        clone_url: `${web}.git`,
        html_url: web,
        // A forge's repository JSON carries no rights. Unknown is not
        // "cannot push": the direct way is tried, and its refusal falls
        // back to the account's own fork.
        permissions: { push: true, admin: false },
      }),
    );
  }
@@ -43,6 +43,7 @@
import type {
  RemoteReview,
  RemoteReviewState,
  RemoteTreeEntry,
  RepoWalk,
} from "../types.ts";
import {
  NO_ACCOUNT,
@@ -141,6 +142,9 @@
export class ForgejoProvider implements Provider {
      htmlUrl:
        asString(field(result.value.data, "html_url")) ||
        `${this.webUrl}/${login}`,
      // Forgejo states it about the account asking (`/user` is always that
      // account), and only then: it is no secret from the account itself.
      siteAdmin: asBool(field(result.value.data, "is_admin")),
    });
  }
@@ -184,6 +188,60 @@
export class ForgejoProvider implements Provider {
    });
  }
  /**
   * `listRepos` is for a person looking; this is for a check that must see
   * everything. It sorts by id, so a repository pushed or made while the walk
   * runs cannot move into a page already read; it never falls back to
   * `/user/repos`, whose order differs; and it is complete only when the
   * distinct repositories seen equal `X-Total-Count`, which must say the
   * same on every page. Anything else fails, and the guard refuses.
   */
  async walkRepos(options: {
    maxPages: number;
    pauseMs?: number;
  }): Promise<ProviderResult<RepoWalk>> {
    if (this.uid === undefined) {
      const me = await this.whoami();
      if (!me.ok) return me;
    }
    if (this.uid === undefined)
      return fail("invalid_response", "the origin gave no id for the account");
    const limit = await this.pageSize();
    const seen = new Map<string, RemoteRepo>();
    const read = (
      complete: boolean,
      why?: RepoWalk["why"],
    ): ProviderResult<RepoWalk> =>
      succeed({
        repos: [...seen.values()],
        complete,
        ...(why === undefined ? {} : { why }),
      });
    let total: number | undefined;
    for (let page = 1; page <= options.maxPages; page++) {
      if (page > 1 && (options.pauseMs ?? 0) > 0)
        await new Promise((resolve) => setTimeout(resolve, options.pauseMs));
      const result = await this.api.call({
        path: "/repos/search",
        query: { uid: this.uid, sort: "id", order: "asc", limit, page },
      });
      if (!result.ok) return read(false, "failed");
      const counted = Number(result.value.headers.get("x-total-count") ?? "");
      if (!Number.isInteger(counted) || counted < 0) return read(false, "moved");
      if (total !== undefined && counted !== total) return read(false, "moved");
      total = counted;
      const rows = asArray(field(result.value.data, "data"));
      for (const raw of rows) {
        const repo = toRepo(raw);
        seen.set(repo.remoteId || repo.fullName.toLowerCase(), repo);
      }
      if (seen.size === total) return read(true);
      // More than counted, or a page that ends the list short of the count.
      if (seen.size > total || rows.length < limit) return read(false, "moved");
    }
    return read(false, "too_many");
  }
  async getRepo(fullName: string): Promise<ProviderResult<RemoteRepo>> {
    const named = splitFullName(fullName);
    if (!named) return fail("not_found", `not a repository name: ${fullName}`);
@@ -719,9 +777,10 @@
export class ForgejoProvider implements Provider {
  ): Promise<ProviderResult<RemoteIssue>> {
    const named = splitFullName(fullName);
    if (!named) return fail("not_found", `not a repository name: ${fullName}`);
    // `head` is an undocumented plain string here. `branch` is certain;
    // whether `owner:branch` works for a cross-repo pull is unverified, which
    // is why the fork-and-contribute flow is not offered yet (docs/ORIGINS.md).
    // `head` is a plain string here: a branch of this repository, or
    // `owner:branch` for a branch of a fork (Forgejo's parseCompareInfo,
    // checked on Forgejo 15.0.9). A reader proposes with the second form
    // (`origins/fork-route.ts`).
    const result = await this.api.call({
      path: `/repos/${seg(named.owner)}/${seg(named.name)}/pulls`,
      method: "POST",
@@ -736,13 +795,38 @@
export class ForgejoProvider implements Provider {
    return succeed(toPull(result.value.data));
  }
  async forkRepo(fullName: string): Promise<ProviderResult<RemoteRepo>> {
  async listForks(
    fullName: string,
  ): Promise<ProviderResult<readonly RemoteRepo[]>> {
    const named = splitFullName(fullName);
    if (!named) return fail("not_found", `not a repository name: ${fullName}`);
    const limit = await this.pageSize();
    const forks: RemoteRepo[] = [];
    for (let page = 1; page <= MAX_INTERNAL_PAGES; page++) {
      const result = await this.api.call({
        path: `/repos/${seg(named.owner)}/${seg(named.name)}/forks`,
        query: { limit, page },
      });
      if (!result.ok) return result;
      const rows = asArray(result.value.data);
      forks.push(...rows.map((r) => toRepo(r)));
      if (nextPage(result.value.headers, rows.length, limit, page) === null) break;
    }
    return succeed(forks);
  }
  async forkRepo(
    fullName: string,
    name?: string,
  ): Promise<ProviderResult<RemoteRepo>> {
    const named = splitFullName(fullName);
    if (!named) return fail("not_found", `not a repository name: ${fullName}`);
    const result = await this.api.call({
      path: `/repos/${seg(named.owner)}/${seg(named.name)}/forks`,
      method: "POST",
      body: {},
      // Both forges take `name` (Forgejo's CreateForkOption, GitHub's
      // create-fork body); without it the fork takes the upstream's name.
      body: name === undefined ? {} : { name },
    });
    if (!result.ok) return result;
    return succeed(toRepo(result.value.data));
@@ -31,6 +31,7 @@
import type {
  RemoteReviewState,
  RemoteTreeEntry,
  TokenReach,
  RepoWalk,
} from "../types.ts";
import {
  NO_ACCOUNT,
@@ -107,6 +108,7 @@
export class GitHubProvider implements Provider {
      htmlUrl:
        asString(field(result.value.data, "html_url")) ||
        `${this.webUrl}/${login}`,
      siteAdmin: asBool(field(result.value.data, "site_admin")),
    });
  }
@@ -150,6 +152,42 @@
export class GitHubProvider implements Provider {
    });
  }
  /**
   * The guard's walk on GitHub: `/user/repos` oldest first, so a repository
   * made while the walk runs lands on a later page rather than shifting an
   * earlier one, and `Link` decides the end. GitHub counts nothing here,
   * so there is no total to check against; a failed page fails the walk.
   */
  async walkRepos(options: {
    maxPages: number;
    pauseMs?: number;
  }): Promise<ProviderResult<RepoWalk>> {
    const repos = new Map<string, RemoteRepo>();
    for (let page = 1; page <= options.maxPages; page++) {
      if (page > 1 && (options.pauseMs ?? 0) > 0)
        await new Promise((resolve) => setTimeout(resolve, options.pauseMs));
      const result = await this.api.call({
        path: "/user/repos",
        query: {
          per_page: PER_PAGE,
          page,
          sort: "created",
          direction: "asc",
          affiliation: "owner,collaborator,organization_member",
        },
      });
      if (!result.ok)
        return succeed({ repos: [...repos.values()], complete: false, why: "failed" });
      for (const raw of asArray(result.value.data)) {
        const repo = toRepo(raw);
        repos.set(repo.remoteId || repo.fullName.toLowerCase(), repo);
      }
      if (!linkNext(result.value.headers))
        return succeed({ repos: [...repos.values()], complete: true });
    }
    return succeed({ repos: [...repos.values()], complete: false, why: "too_many" });
  }
  async getRepo(fullName: string): Promise<ProviderResult<RemoteRepo>> {
    const named = splitFullName(fullName);
    if (!named) return fail("not_found", `not a repository name: ${fullName}`);
@@ -692,13 +730,38 @@
export class GitHubProvider implements Provider {
    return succeed(toPull(result.value.data));
  }
  async forkRepo(fullName: string): Promise<ProviderResult<RemoteRepo>> {
  async listForks(
    fullName: string,
  ): Promise<ProviderResult<readonly RemoteRepo[]>> {
    const named = splitFullName(fullName);
    if (!named) return fail("not_found", `not a repository name: ${fullName}`);
    const forks: RemoteRepo[] = [];
    for (let page = 1; page <= MAX_INTERNAL_PAGES; page++) {
      const result = await this.api.call({
        path: `/repos/${seg(named.owner)}/${seg(named.name)}/forks`,
        query: { per_page: PER_PAGE, page },
      });
      if (!result.ok) return result;
      const rows = asArray(result.value.data);
      forks.push(...rows.map((r) => toRepo(r)));
      if (!linkNext(result.value.headers)) break;
    }
    return succeed(forks);
  }
  async forkRepo(
    fullName: string,
    name?: string,
  ): Promise<ProviderResult<RemoteRepo>> {
    const named = splitFullName(fullName);
    if (!named) return fail("not_found", `not a repository name: ${fullName}`);
    const result = await this.api.call({
      path: `/repos/${seg(named.owner)}/${seg(named.name)}/forks`,
      method: "POST",
      body: {},
      // Both forges take `name` (Forgejo's CreateForkOption, GitHub's
      // create-fork body); without it the fork takes the upstream's name.
      body: name === undefined ? {} : { name },
    });
    if (!result.ok) return result;
    return succeed(toRepo(result.value.data));
@@ -36,6 +36,47 @@
export const fail = (
  error: { error, message, ...(retryAt === undefined ? {} : { retryAt }) },
});
/**
 * The scopes in a Forgejo or Gitea refusal — `token does not have at least
 * one of required scope(s): [read:user]` — or none. Only scope-shaped words
 * are kept, so nothing else the body says can ride along into a message.
 */
export function missingScopes(body: string): string[] {
  const listed = /required scope\(s\): \[([^\]]{0,200})\]/.exec(body);
  if (!listed) return [];
  return (listed[1] ?? "")
    .split(/[\s,]+/)
    .filter((s) => /^(read|write):[a-z]{1,20}$/.test(s));
}
const CATEGORY: Record<string, string> = {
  activitypub: "ActivityPub",
  admin: "Admin",
  issue: "Issue",
  misc: "Misc",
  notification: "Notification",
  organization: "Organization",
  package: "Package",
  repository: "Repository",
  user: "User",
};
/**
 * Scopes as the token page names them: `read:user` is "User: Read" and
 * `write:issue` "Issue: Read and write" (write includes read there).
 */
export function scopeWords(scopes: readonly string[]): string {
  const words = scopes.map((scope) => {
    const [level, category = ""] = scope.split(":");
    const name =
      CATEGORY[category] ?? category.charAt(0).toUpperCase() + category.slice(1);
    return `${name}: ${level === "write" ? "Read and write" : "Read"}`;
  });
  return words.length <= 1
    ? (words[0] ?? "")
    : `${words.slice(0, -1).join(", ")} or ${words.at(-1)}`;
}
export const succeed = <T>(value: T): ProviderResult<T> => ({
  ok: true,
  value,
@@ -175,6 +216,14 @@
export class ApiClient {
    const method = request.method ?? "GET";
    const maxBytes = options.maxBytes ?? this.maxBytes;
    // Anything that is not a read asks the credential first: an origin whose
    // account could not be verified (the operator guard) reads but does not
    // write, and this is the one door every write through an adapter takes.
    if (method !== "GET" && method !== "HEAD" && this.credential.writable) {
      const may = this.credential.writable();
      if (!may.ok) return may;
    }
    // Resolved per call: an OAuth token may have been refreshed since the
    // last one, and a token that cannot be resolved must not become a
    // credential-less request that reads as "not found".
@@ -252,8 +301,28 @@
export class ApiClient {
    if (response.status === 401)
      return fail("unauthorized", "the origin rejected this token");
    if (response.status === 403)
      return fail("forbidden", "the token may not do that on the origin");
    if (response.status === 403) {
      // Forgejo and Gitea say which scope a token lacks; that sentence is
      // worth one small read, because "may not" alone sends a person to
      // guess between a wrong token, an expired one and a narrow one.
      let said = "";
      try {
        said = (await readCapped(response, 4096, signal)) ?? "";
      } catch {
        said = "";
      }
      const missing = missingScopes(said);
      return missing.length === 0
        ? fail("forbidden", "the token may not do that on the origin")
        : {
            ok: false,
            error: {
              error: "forbidden",
              message: `the token is missing ${scopeWords(missing)}`,
              missingScopes: missing,
            },
          };
    }
    if (response.status === 404)
      return fail("not_found", "the origin has no such thing");
    if (response.status >= 500)
@@ -37,9 +37,10 @@
import { FORWARDED_GIT_ENV, type RefUpdate } from "../git/hook-protocol.ts";
import { fetchInto, resolveOid, writeRef } from "../git/merge.ts";
import { repoDir } from "../git/repos.ts";
import { err, ok, type Result } from "../kernel/result.ts";
import { providerForOrigin } from "./credential.ts";
import { providerForOrigin, writesPaused } from "./credential.ts";
import { redact, secretsIn } from "./credentials.ts";
import { pushToOrigin, snapshotRefs } from "./git-mirror.ts";
import { denied } from "./operator.ts";
/** A push-through must not outlive a pusher's patience. */
const TIMEOUT_MS = 60_000;
@@ -47,6 +48,8 @@
const TIMEOUT_MS = 60_000;
export interface PushThroughRefusal {
  /** Shown to the pusher verbatim; already scrubbed of credentials. */
  readonly message: string;
  /** The origin itself refused the push (no rights there), not this forge. */
  readonly byOrigin?: boolean;
}
/**
@@ -129,6 +132,10 @@
export async function carryBranchThrough(
const ZERO_OID_STRING = "0".repeat(40);
/** What a push to a protected repository is told, everywhere. */
export const protectedMessage = (webUrl: string, fullName: string): string =>
  `${fullName} on ${webUrl} is protected by this forge's operator: nothing is pushed to it from here. Propose the change from your fork instead.`;
/** The origin's refusal, in its words, with the credential kept out of them. */
function refusedBy(
  link: NonNullable<ReturnType<typeof originForRepo>>,
@@ -145,6 +152,7 @@
function refusedBy(
      `${link.fullName} on ${link.origin.webUrl} refused this push: ${message}`,
      ...secretsIn(authEnv),
    ),
    byOrigin: true,
  };
}
@@ -191,6 +199,14 @@
async function wayThrough(
      message: "this mirror has no upstream clone URL; re-mirror it",
    });
  const paused = writesPaused(app, link.origin.id);
  if (paused !== undefined)
    return err({ message: `${link.origin.webUrl}: ${paused}` });
  // A repository the operator protects is never pushed to from here, even
  // by an account that could: changes to it go up as pulls from a fork.
  if (denied(link.origin, link.fullName))
    return err({ message: protectedMessage(link.origin.webUrl, link.fullName) });
  const provider = providerForOrigin(app, link.origin);
  if (!provider.ok)
    return err({
@@ -64,6 +64,12 @@
export function replaceTokenMessage(error: string): string {
    unreachable: "That instance could not be reached.",
    rate_limited: "Too many connect attempts. Wait a few minutes.",
    unauthorized: "Sign in first.",
    admin_account:
      "That token is an administrator's. This forge does not accept one; use an everyday account's.",
    can_push:
      "That token can push to a protected repository. This forge does not accept one that can.",
    guard_unchecked:
      "This forge could not check what that token can do. Try again in a minute.",
  };
  return words[error] ?? "That token could not be put on this origin.";
}
@@ -241,6 +241,13 @@
export interface RemoteIdentity {
  readonly login: string;
  readonly displayName: string;
  readonly htmlUrl: string;
  /**
   * The account administers the whole instance: Forgejo's and Gitea's
   * `is_admin`, GitHub's `site_admin`. A credential of such an account can
   * write every repository there is, which is what the operator guard
   * (`origins/operator.ts`) refuses on the hosts it covers.
   */
  readonly siteAdmin: boolean;
}
export type ProviderError =
@@ -256,6 +263,26 @@
export interface ProviderFailure {
  readonly message: string;
  /** For `rate_limited`: when to try again. */
  readonly retryAt?: string;
  /**
   * For `forbidden`: the token scopes the origin said it lacks, in the
   * origin's own words (`read:user`), when it said (Forgejo, Gitea).
   */
  readonly missingScopes?: readonly string[];
}
/**
 * Every repository a credential can see, read for a check that must not miss
 * one. `complete` is false when the pages ran out before the list did.
 */
export interface RepoWalk {
  /** What was read, complete or not: a protected repository among them counts. */
  readonly repos: readonly RemoteRepo[];
  readonly complete: boolean;
  /**
   * Why it is not complete: the pages ran out (`too_many`), the list moved
   * or its count did not add up (`moved`), or a page failed (`failed`).
   */
  readonly why?: "too_many" | "moved" | "failed";
}
/** A page of a list, with the cursor for the next page (null at the end). */
@@ -296,6 +323,18 @@
export interface Provider {
   */
  tokenReach?(): Promise<ProviderResult<TokenReach>>;
  listRepos(cursor?: string): Promise<ProviderResult<Page<RemoteRepo>>>;
  /**
   * Every repository the credential can see, for the operator guard
   * (`origins/operator.ts`): in an order a repository cannot move in while
   * the walk runs (by id, or by creation), with no fallback to another
   * endpoint, at most `maxPages` pages and `pauseMs` between them. A page
   * that fails, or a count that does not add up, ends it incomplete, with
   * what was read so far; only a walk that cannot start fails.
   */
  walkRepos(options: {
    maxPages: number;
    pauseMs?: number;
  }): Promise<ProviderResult<RepoWalk>>;
  getRepo(fullName: string): Promise<ProviderResult<RemoteRepo>>;
  // ---- reads for browsing a repository we have not mirrored ----
@@ -436,12 +475,21 @@
export interface Provider {
      body: string;
    },
  ): Promise<ProviderResult<RemoteReviewState>>;
  /**
   * The forks of a repository, as many as fit a bounded walk: what finds an
   * account's fork when it goes by a name this forge did not give it.
   */
  listForks(fullName: string): Promise<ProviderResult<readonly RemoteRepo[]>>;
  /**
   * Fork a repo into the credential's account. GitHub creates the fork
   * *asynchronously* and answers 202 with a repo that does not exist yet, so
   * a caller must poll `getRepo` until it does (`actions/contribute.ts`).
   */
  forkRepo(fullName: string): Promise<ProviderResult<RemoteRepo>>;
  forkRepo(
    fullName: string,
    /** The fork's name, when not the upstream's own (a name already taken). */
    name?: string,
  ): Promise<ProviderResult<RemoteRepo>>;
  /**
   * Archive a repo (`PATCH /repos/{o}/{r}` with `archived: true`): read-only
   * on the origin from then on. Needs admin there; without it the answer is
@@ -499,6 +547,12 @@
export interface ProviderCredential {
   * credential is gone or unrefreshable, and the origin needs reconnecting.
   */
  token(): Promise<ProviderResult<string>>;
  /**
   * Whether the credential may change anything on the origin now: asked
   * before every request that is not a read. A refusal is `forbidden`, with
   * the reason. Absent, it always may (a credential checked by nobody).
   */
  writable?(): ProviderResult<true>;
}
/** A credential that is just a stored secret — the PAT path, and tests. */
@@ -15,13 +15,17 @@
import { originForRepo, type Origin } from "../core/origins.ts";
import type { Repo } from "../core/repos.ts";
import type { User } from "../core/users.ts";
import { err, ok, type Result } from "../kernel/result.ts";
import { providerForOrigin } from "./credential.ts";
import { providerForOrigin, writesPaused } from "./credential.ts";
import type { Provider } from "./types.ts";
export type WriteThroughError =
  | "origin_owner_only"
  | "origin_unreachable"
  | "origin_refused";
  | "origin_refused"
  /** The account behind the origin is not verified against the operator's rules yet. */
  | "origin_paused"
  /** The operator protects the origin repository: propose from a fork. */
  | "origin_protected";
export interface WriteThrough {
  readonly provider: Provider;
@@ -49,6 +53,8 @@
export function writeThroughFor(
  const link = originForRepo(app.db, repo.id);
  if (!link) return ok(undefined);
  if (link.origin.userId !== actor.id) return err("origin_owner_only");
  if (writesPaused(app, link.origin.id) !== undefined)
    return err("origin_paused");
  const provider = providerForOrigin(app, link.origin);
  if (!provider.ok) return err("origin_unreachable");
  return ok({
@@ -982,6 +982,8 @@
const MESSAGES: Record<string, string> = {
  mirrored: "this repo mirrors an origin — do it there",
  origin_owner_only: "only whoever connected this origin can write through it",
  origin_refused: "the origin refused that; nothing changed here",
  origin_paused: "this connection is not verified yet; writes are paused",
  origin_protected: "the operator protects this repository at its origin: nothing is pushed to it from here; propose the change from your fork",
  origin_unreachable: "the origin could not be reached; nothing changed",
  already_connected: ORIGIN_ALREADY_CONNECTED,
  already_mirrored: "that repository is already mirrored here",
@@ -4,9 +4,10 @@
 * it after a confirm — through `actions/origins.ts`, in `origin_words.ts`'s words.
 */
import { connectOrigin, disconnectOrigin, listUserOrigins, syncOriginNow } from "../../actions/origins.ts";
import { DISCONNECT_DETAIL, NO_SUCH_ORIGIN, connectWords, disconnectedWords, syncedWords } from "../../actions/origin_words.ts";
import { connectOrigin, checkOriginAgain, connectRefusal, disconnectOrigin, listUserOrigins, syncOriginNow } from "../../actions/origins.ts";
import { CHECK_TOO_SOON, CHECK_WORDS, DISCONNECT_DETAIL, NO_SUCH_ORIGIN, connectWords, disconnectedWords, syncedWords } from "../../actions/origin_words.ts";
import { mirrorsByOrigin } from "../../core/origins.ts";
import { writesPaused } from "../../origins/credential.ts";
import { FORGE_NOT_CARRIED, FORGE_SIGN_IN_ON_PAGE } from "../../origins/words.ts";
import type { Ctx, Screen } from "../app/app.ts";
import { binding } from "../app/keys.ts";
@@ -27,16 +28,19 @@
export function connectionsScreen(f: Session, ctx: Ctx): Screen {
  const screen: Screen = {
    title: "Connected origins",
    keys: [binding(["j", "k"], "move cursor"), binding(["c"], "connect"), binding(["s"], "sync now"), binding(["d"], "disconnect"), binding(["esc"], "back")],
    keys: [binding(["j", "k"], "move cursor"), binding(["c"], "connect"), binding(["s"], "sync now"), binding(["v"], "verify again"), binding(["d"], "disconnect"), binding(["esc"], "back")],
    render(area, s) {
      const c = ctx.theme.c;
      const [head, list] = split(area, "v", [len(1), fill(1)]);
      const all = origins();
      const picked = all[state.index];
      const pausedNote = picked !== undefined && writesPaused(f.app, picked.id) !== undefined;
      const text =
        picked?.software === "forge"
          ? `Another forge. ${FORGE_NOT_CARRIED}`
          : all.length === 0
          : pausedNote
            ? "Couldn't verify this connection; writes paused. Reading and syncing go on. Press v to check again."
            : all.length === 0
            ? `No origin connected. Press c to connect one. ${FORGE_SIGN_IN_ON_PAGE}`
            : `The hosts your mirrors come from. ${FORGE_SIGN_IN_ON_PAGE}`;
      s.text(head!.x, head!.y, truncate(text, head!.w), style(c.mutedFg, c.bg), head!.x + head!.w);
@@ -50,9 +54,9 @@
export function connectionsScreen(f: Session, ctx: Ctx): Screen {
          const k = n.get(o.id)?.count ?? 0;
          return {
            title: `${host(o.webUrl)} · ${o.login}`,
            ...(o.lastError !== "" ? { tone: "danger" as const } : {}),
            ...(o.lastError !== "" || writesPaused(f.app, o.id) !== undefined ? { tone: "danger" as const } : {}),
            secondary: `${o.software === "forge" ? "another forge · " : ""}${k} repositor${k === 1 ? "y" : "ies"} · ${day(o.lastSyncAt)}`,
            meta: o.lastError !== "" ? o.lastError : o.authKind === "oauth" ? "OAuth" : "token",
            meta: o.lastError !== "" ? o.lastError : writesPaused(f.app, o.id) !== undefined ? "writes paused" : o.authKind === "oauth" ? "OAuth" : "token",
          };
        }),
      );
@@ -79,7 +83,7 @@
export function connectionsScreen(f: Session, ctx: Ctx): Screen {
                    if (token.trim() === "") return "Paste the token.";
                    ctx.toast(`Connecting ${hostText}…`);
                    return connectOrigin(f.app, user, { host: hostText, token }).then((r) => {
                      ctx.toast(r.ok ? `Connected ${r.value.login} at ${host(r.value.webUrl)}.` : connectWords(r.error), r.ok ? "success" : "danger");
                      ctx.toast(r.ok ? `Connected ${r.value.login} at ${host(r.value.webUrl)}.` : connectRefusal(r.error).message ?? connectWords(connectRefusal(r.error).code), r.ok ? "success" : "danger");
                      ctx.invalidate();
                    });
                  },
@@ -105,6 +109,17 @@
export function connectionsScreen(f: Session, ctx: Ctx): Screen {
          .catch(() => ctx.toast("The sync failed.", "danger"));
        return true;
      }
      if (e.key === "v") {
        ctx.toast(`Checking ${host(o.webUrl)}…`);
        void checkOriginAgain(f.app, user, o.id)
          .then((r) => {
            if (!r.ok) ctx.toast(r.error === "too_soon" ? CHECK_TOO_SOON : NO_SUCH_ORIGIN, "danger");
            else ctx.toast(CHECK_WORDS[r.value], r.value === "passed" || r.value === "unguarded" ? "success" : "danger");
            ctx.invalidate();
          })
          .catch(() => ctx.toast("The check failed.", "danger"));
        return true;
      }
      if (e.key === "d") {
        ctx.push(
          confirmScreen(ctx, screen, {
@@ -349,6 +349,10 @@
export const CREATE_ERRORS: Record<string, string> = {
    "The origin could not be reached, so nothing was created.",
  origin_refused:
    "The origin refused that branch, so nothing was created here.",
  origin_protected:
    "The operator protects this repository at its origin, so no branch is pushed to it from here. Propose the change from your fork.",
  origin_paused:
    "This connection is not verified yet, so writes through it are paused. Nothing was created. Check it again under Settings → Origins.",
  forbidden: "You need write access to create a branch.",
  unauthorized: "You need write access to create a branch.",
  not_found: "You need write access to create a branch.",
@@ -950,6 +950,8 @@
export function forkFailure(error: string): string {
    return "The origin could not be reached. Nothing was created.";
  if (error === "origin_refused")
    return "The origin refused to fork that repository.";
  if (error === "origin_paused")
    return "This connection is not verified yet, so writes through it are paused. Check it again under Settings → Origins.";
  if (error === "mirror_failed")
    return "The fork was made, but a local copy of it could not be.";
  if (error === "unauthorized") return "Sign in first.";
@@ -126,6 +126,10 @@
export function editErrorText(error: unknown): string {
      return "The origin could not be reached, so nothing was written here either.";
    if (error === "origin_refused")
      return "The origin refused this change, so nothing landed here either.";
    if (error === "origin_protected")
      return "The operator protects this repository at its origin, so nothing is pushed to it from here. Propose the change from your fork.";
    if (error === "origin_paused")
      return "This connection is not verified yet, so writes through it are paused. Check it again under Settings → Origins.";
    return "That edit could not be saved.";
  }
  const e = error as { kind?: string; branch?: string; message?: string };
@@ -43,6 +43,7 @@
import { loadRepo, notFoundPage, repoBase, signInFirst } from "../chrome.ts";
import { convergeWords, followModeOf, takeOrTell, takeWords } from "../../actions/follow.ts";
import { FOLLOWS_NOTHING, proposeRefusalWords } from "../../actions/follow_words.ts";
import { openProposal, proposeUpstream } from "../../actions/upstream.ts";
import { proposesViaFork } from "../../origins/fork-route.ts";
import { field, readForm } from "../form.ts";
import { html, when, type Html } from "../html.ts";
import { flashOrJson } from "../layout.ts";
@@ -284,11 +285,18 @@
export function followingCard(
      proposal === undefined
        ? html`<form method="post" action="${base}/following">
            <input type="hidden" name="do" value="propose" />
            ${btn("Propose upstream", {
              size: "sm",
              type: "submit",
              icon: "merge",
            })}
            ${proposesViaFork(ctx.app, parent)
              ? btn("Propose via your fork", {
                  size: "sm",
                  type: "submit",
                  icon: "fork",
                  title: `Your account can only read ${parent.ownerName}/${parent.name}'s origin, or its operator protects it: the change goes to your own fork there, and the pull opens from it`,
                })
              : btn("Propose upstream", {
                  size: "sm",
                  type: "submit",
                  icon: "merge",
                })}
          </form>`
        : btn("See the upstream proposal", {
            size: "sm",
@@ -9,7 +9,7 @@
 */
import { pollOAuthConnect } from "../../actions/origins.ts";
import { getFlowFor } from "../../origins/oauth.ts";
import { flowExpired, flowTarget, getFlowFor } from "../../origins/oauth.ts";
import type { Ctx } from "../../http/context.ts";
import { forgeBaseUrl } from "../../http/api.ts";
import { qrEncode, qrSvg } from "../../design/qr.ts";
@@ -49,14 +49,15 @@
export function originFlowPage(ctx: Ctx): Response {
    return redirect(`${then ?? "/settings/origins"}?connected=1`);
  if (flow.status === "failed")
    return redirect(
      `/settings/origins?error=${encodeURIComponent(flow.detail.slice(0, 120))}`,
      `/settings/origins?error=${encodeURIComponent(flow.detail.slice(0, 300))}`,
    );
  // A pending flow past its time leads nowhere: not to a consent screen
  // for a state that will be refused, nor to a code that no longer works.
  if (flowExpired(flow)) return expiredFlow(ctx, flow, then);
  const pollAction = `/settings/origins/flows/${flow.id}/poll${then === undefined ? "" : `?${thenQuery(then)}`}`;
  const authorize =
    flow.flow === "code"
      ? authorizeLink(ctx.url.searchParams.get("to") ?? "", flow.webUrl)
      : undefined;
  const authorize = flow.flow === "code" ? authorizeFor(ctx, flow) : undefined;
  const base = forgeBaseUrl(ctx.url, ctx.app.config.host);
  const shortLink =
    base === "" || flow.shortCode === "" ? "" : `${base}/go/${flow.shortCode}`;
@@ -211,24 +212,74 @@
function qrScale(modules: number): number {
}
/**
 * The authorize URL for a code flow, checked before it becomes a link.
 *
 * It arrives on the query string because the flow row stores a *device*
 * flow's verification URI and nothing for a code flow. A crafted link could
 * therefore reach this page, so the URL is accepted only when it points at
 * the same instance the flow already names and carries a PKCE challenge —
 * the worst a forged one can do is send you to another page on the forge you
 * asked to connect.
 * The authorize URL a code flow goes on to: the one sealed on the flow when
 * it began (`flowTarget`), never one from the query string — a link a
 * stranger crafted would otherwise choose the client and the callback. It is
 * checked again before it becomes a link: the instance's own
 * `/login/oauth/authorize`, with the flow's client id and callback and a
 * PKCE challenge. An older link that still carries `to` continues only when
 * `to` is exactly that URL.
 */
function authorizeLink(raw: string, webUrl: string): string | undefined {
  const url = URL.parse(raw);
  const instance = URL.parse(webUrl);
function authorizeFor(
  ctx: Ctx,
  flow: { id: string; webUrl: string; clientId: string; redirectUri: string },
): string | undefined {
  const stored = flowTarget(ctx.app.db, ctx.app.config.dataDir, flow.id);
  if (stored === undefined) return undefined;
  const asked = ctx.url.searchParams.get("to");
  if (asked !== null && asked !== stored) return undefined;
  const url = URL.parse(stored);
  const instance = URL.parse(flow.webUrl);
  if (!url || !instance) return undefined;
  if (url.origin !== instance.origin) return undefined;
  const at = `${instance.pathname.replace(/\/+$/, "")}/login/oauth/authorize`;
  if (url.pathname !== at) return undefined;
  if (url.searchParams.get("client_id") !== flow.clientId) return undefined;
  if (url.searchParams.get("redirect_uri") !== flow.redirectUri) return undefined;
  if (url.searchParams.get("code_challenge") === null) return undefined;
  return url.toString();
}
/**
 * A connect that ran out of time before it was finished: said so, with the
 * way to start again.
 */
function expiredFlow(
  ctx: Ctx,
  flow: { kind: string; webUrl: string },
  then: Then,
): Response {
  return page({
    ctx,
    title: "Connecting an origin",
    body: html`<div class="page-head"><h1>Connecting an origin</h1></div>
      <div class="narrow-wide">
        ${card(
          html`<p class="mb">
              This connect link expired. Nothing was connected. Start again:
            </p>
            <form method="post" action="/settings/origins/oauth">
              <input type="hidden" name="host" value="${flow.webUrl}" />
              ${flow.kind === "github"
                ? html`<input type="hidden" name="kind" value="github" />`
                : null}
              ${then === undefined
                ? null
                : html`<input type="hidden" name="then" value="migrate" />`}
              ${btn(`Connect ${hostLabel(flow.webUrl)}`, {
                variant: "primary",
                icon: "external",
              })}
            </form>`,
          {
            head: html`${icon("alert")}
              <h2>This connect link expired</h2>`,
          },
        )}
      </div>`,
  });
}
/**
 * POST /settings/origins/flows/:id/poll — ask the origin once, on the user's
 * behalf. The forge does the polling, so a browser (or a phone) only ever
@@ -265,7 +316,7 @@
export async function originFlowPoll(ctx: Ctx): Promise<Response> {
    return redirect(`${then ?? "/settings/origins"}?connected=1`);
  if (status === "failed")
    return redirect(
      `/settings/origins?error=${encodeURIComponent(detail.slice(0, 120))}`,
      `/settings/origins?error=${encodeURIComponent(detail.slice(0, 300))}`,
    );
  return redirect(
    `/settings/origins/flows/${ctx.params.id ?? ""}${then === undefined ? "" : `?${thenQuery(then)}`}`,
@@ -19,7 +19,9 @@
import { FORGE_NOT_CARRIED } from "../../origins/words.ts";
import {
  checkOriginAgain,
  connectOrigin,
  connectRefusal,
  deleteOriginApp,
  disconnectOrigin,
  listOriginApps,
@@ -35,6 +37,8 @@
import {
  connectWords,
  disconnectedWords,
  syncedWords,
  CHECK_TOO_SOON,
  CHECK_WORDS,
} from "../../actions/origin_words.ts";
import {
  editableHosts,
@@ -46,6 +50,7 @@
import {
} from "../../origins/trusted-hosts.ts";
import { reattachMessage } from "./frozen.ts";
import { replaceTokenMessage } from "../../origins/token-reach.ts";
import { writesPaused } from "../../origins/credential.ts";
import {
  listDetachedMirrors,
  mirrorsByOrigin,
@@ -328,7 +333,25 @@
function reauthNote(origin: Origin, mirrors: number): Html {
  </p>`;
}
function originCard(origin: Origin, mirrors: number): Html {
/**
 * An origin whose account the operator guard could not verify reads and
 * syncs but writes nothing (`writesPaused`): said where the origin is, with
 * the way out, a check now.
 */
function pausedNote(origin: Origin): Html {
  return html`<div class="toast mt" data-tone="attn" role="status">
    ${icon("alert")}
    <div class="toast-body">
      Couldn't verify this connection; writes paused. Reading and syncing go
      on.
    </div>
    <form method="post" action="/settings/origins/${origin.id}/check">
      ${btn("Check again", { size: "sm", variant: "outline", icon: "sync" })}
    </form>
  </div>`;
}
function originCard(origin: Origin, mirrors: number, paused = false): Html {
  const base = `/settings/origins/${origin.id}`;
  return card(
    html`<ul class="list setting-list">
@@ -364,6 +387,7 @@
function originCard(origin: Origin, mirrors: number): Html {
        origin.software === "forge",
        () => html`<p class="small mt">Another forge. ${FORGE_NOT_CARRIED}</p>`,
      )}
      ${when(paused, () => pausedNote(origin))}
      <div class="bar mt">
        <form method="post" action="${base}/sync">
          ${btn("Sync now", { size: "sm", icon: "sync" })}
@@ -640,8 +664,9 @@
function tokenSection(values: ConnectValues): Html {
        required: true,
        mono: true,
        autocomplete: "off",
        hint: "Needs repository and issue access. It is never displayed after this.",
        hint: "It is never displayed after this.",
      })}
      ${tokenNeeds(values.tokenHost)}
      <div class="form-actions">${btn("Connect", { variant: "primary" })}</div>
    </form>`;
}
@@ -681,6 +706,41 @@
function trustedHostsCard(text: string, error?: string): Html {
  );
}
/**
 * What a Forgejo or Gitea token needs, in the words of the page that makes
 * one, and — once the instance is known — a link to that page with the
 * name and the scopes already chosen. Forgejo 15 fills its form from the
 * query (`/user/settings/applications/tokens/new`); an older one or Gitea
 * opens the plain form, and the list says what to pick.
 */
function tokenNeeds(host: string): Html {
  const site =
    host === ""
      ? null
      : URL.parse(host.includes("://") ? host : `https://${host}`);
  const link =
    site === null || site.hostname === "github.com" || site.hostname === "github"
      ? undefined
      : `${site.origin}/user/settings/applications/tokens/new?name=forge&resource=all&scope=read:user&scope=write:repository&scope=write:issue`;
  return html`<div class="small muted">
    <p>For Forgejo or Gitea, the token needs:</p>
    <ul>
      <li>User: Read</li>
      <li>Repository: Read and write</li>
      <li>Issue: Read and write</li>
      <li>Everything else: No access</li>
    </ul>
    ${link === undefined
      ? null
      : html`<p>
          <a href="${link}" target="_blank" rel="noopener noreferrer"
            >Make this token at ${site!.host}</a
          >, with these already chosen. On Gitea or an older Forgejo, open
          Settings → Applications there instead.
        </p>`}
  </div>`;
}
// ---- the page ----
function originsView(
@@ -715,7 +775,13 @@
function originsView(
          note: "Connect GitHub, a Forgejo instance or a Gitea instance and its repositories become mirrorable here.",
        })
      : html`<div class="stack">
          ${origins.map((o) => originCard(o, mirrors.get(o.id)?.count ?? 0))}
          ${origins.map((o) =>
            originCard(
              o,
              mirrors.get(o.id)?.count ?? 0,
              writesPaused(ctx.app, o.id) !== undefined,
            ),
          )}
        </div>`}
    ${frozenCard(frozen)}
    ${mayEditTrustedHosts(user)
@@ -871,7 +937,7 @@
export function originsPage(ctx: Ctx): Response {
          <div class="toast-body">
            ${error === "state"
              ? "That authorization could not be matched to a connect you started here. Start again."
              : error.slice(0, 200)}
              : error.slice(0, 300)}
          </div>
        </div>`
      : null;
@@ -901,7 +967,8 @@
export async function originConnectToken(ctx: Ctx): Promise<Response> {
    // secret is a smaller cost than a secret sitting in a value attribute.
    const values = blankValues();
    values.tokenHost = host;
    values.tokenError = connectMessage(connected.error);
    const refused = connectRefusal(connected.error);
    values.tokenError = refused.message ?? connectMessage(refused.code);
    return shell(ctx, originsView(ctx, values), 422);
  }
  const { reattached } = connected.value;
@@ -979,11 +1046,8 @@
export async function originOAuthStart(ctx: Ctx): Promise<Response> {
        : connectMessage(started.error.error);
    return shell(ctx, originsView(ctx, values), 422);
  }
  const query = new URLSearchParams(
    started.value.flow === "code" ? { to: started.value.url } : {},
  );
  if (then !== undefined) query.set("then", "migrate");
  const qs = query.size === 0 ? "" : `?${query}`;
  // The flow's page knows where to go from the flow itself, not the link.
  const qs = then === undefined ? "" : "?then=migrate";
  return redirect(`/settings/origins/flows/${started.value.flowId}${qs}`);
}
@@ -1072,6 +1136,29 @@
export function notFoundNote(): Html {
}
// ---- one origin ----
// POST /settings/origins/:id/check — "Check again": the operator guard, now.
export async function originCheckSubmit(ctx: Ctx): Promise<Response> {
  const denied = accountOnly(ctx);
  if (denied) return denied;
  const form = await readForm(ctx, "admin");
  if (form instanceof Response) return form;
  const to = "/settings/origins";
  const checked = await checkOriginAgain(ctx.app, ctx.auth.user, ctx.params.id ?? "");
  if (!checked.ok)
    return flashTo(ctx, to, {
      tone: checked.error === "too_soon" ? "attn" : "danger",
      message:
        checked.error === "too_soon" ? CHECK_TOO_SOON : "No such connection.",
    });
  return flashTo(ctx, to, {
    tone:
      checked.value === "passed" || checked.value === "unguarded"
        ? "success"
        : "danger",
    message: CHECK_WORDS[checked.value],
  });
}
// POST /settings/origins/:id/sync
export async function originSyncSubmit(ctx: Ctx): Promise<Response> {
  const denied = accountOnly(ctx);
@@ -92,6 +92,10 @@
export function originError(error: string): string | undefined {
    origin_owner_only:
      "Only the person who connected this origin can write through it. Your comment would otherwise appear upstream under their name.",
    origin_refused: "The origin refused that. Nothing was changed here either.",
    origin_protected:
      "The operator protects this repository at its origin, so nothing is pushed to it from here. Propose the change from your fork.",
    origin_paused:
      "This connection is not verified yet, so writes through it are paused. Nothing was changed. Check it again under Settings → Origins.",
    origin_unreachable: "The origin could not be reached. Nothing was changed.",
  };
  return words[error];
@@ -32,6 +32,7 @@
import {
  type Origin,
} from "../core/origins.ts";
import { canWrite, countsForRepos, type Repo } from "../core/repos.ts";
import { denied } from "../origins/operator.ts";
import type { Ctx } from "../http/context.ts";
import type {
  RepoFacts,
@@ -193,7 +194,10 @@
function mirrorFacts(
  const link = originForRepo(ctx.app.db, repo.id);
  if (link === undefined) return { upstream, propose: undefined };
  const cached = getOriginRepo(ctx.app.db, link.origin.id, link.fullName);
  if (cached?.canPush !== false) return { upstream, propose: undefined };
  // A repository the operator protects takes no pushes from here, whatever
  // the account could do: it, too, is proposed to through a fork.
  if (cached?.canPush !== false && !denied(link.origin, link.fullName))
    return { upstream, propose: undefined };
  return {
    upstream,
    propose: {
@@ -50,7 +50,7 @@
describe("the note door on a mirrored app", () => {
    github = serveFakeForge(newFakeState("github", "alice", secret));
    forgetProviders(dataDir);
    const connected = await connectOrigin(app, alice, { host: github.url, kind: "github", token: secret });
    if (!connected.ok) throw new Error(connected.error);
    if (!connected.ok) throw new Error(JSON.stringify(connected.error));
    const created = await newApp(app, alice, { name: "mirrored", description: "Words", visibility: "public" });
    if (!created.ok) throw new Error(String(created.error));
    const repo = getRepo(app.db, "alice", "mirrored")!;
@@ -222,6 +222,19 @@
export interface FakeState {
   * unset, the fake is a fine-grained token, which names none.
   */
  scopes?: string;
  /**
   * A scope the token lacks for `/user` (`read:user`): answered as Forgejo
   * answers it, a 403 that names the scope.
   */
  userScopeMissing?: string;
  /** The account administers the instance: `is_admin` / `site_admin` on `/user`. */
  siteAdmin?: boolean;
  /** Called before each page of a repository listing is answered: the world moving mid-walk. */
  onRepoPage?: (page: number) => void;
  /** What `X-Total-Count` says on a repository listing, when it should lie. */
  repoTotalOverride?: number;
  /** Repositories (`owner/name`) whose `GET /repos/{o}/{r}` answers 500. */
  failRepos?: Set<string>;
}
export interface FakeForge {
@@ -396,6 +409,14 @@
function route(
  if (rest === "/settings/api")
    return jsonResponse({ max_response_items: state.maxResponseItems });
  if (rest === "/user" && state.userScopeMissing !== undefined)
    return jsonResponse(
      {
        message: `token does not have at least one of required scope(s): [${state.userScopeMissing}]`,
        url: `${url.origin}/api/swagger`,
      },
      403,
    );
  if (rest === "/user")
    return jsonResponse(
      {
@@ -404,23 +425,42 @@
function route(
        full_name: state.login,
        name: state.login,
        html_url: `${url.origin}/${state.login}`,
        ...(state.kind === "github"
          ? { site_admin: state.siteAdmin === true }
          : { is_admin: state.siteAdmin === true }),
      },
      200,
      state.scopes === undefined ? {} : { "x-oauth-scopes": state.scopes },
    );
  if (rest === "/user/repos" || rest === "/repos/search") {
    // Paged as Forgejo pages: `limit` clamped to the instance's ceiling,
    // `page` from 1, and `sort` (id, or updated: most recent first) when
    // asked; with no `limit`, everything at once, as before.
    const page = Math.max(1, Number(q.get("page") ?? "1") || 1);
    state.onRepoPage?.(page);
    const visibility = q.get("visibility");
    const rows = state.repos
      .filter(
        (r) =>
          visibility === null ||
          visibility === "all" ||
          (visibility === "private") === (r.private ?? false),
      )
    const ordered = state.repos.filter(
      (r) =>
        visibility === null ||
        visibility === "all" ||
        (visibility === "private") === (r.private ?? false),
    );
    if (q.get("sort") === "id") ordered.sort((a, b) => a.id - b.id);
    if (q.get("sort") === "updated")
      ordered.sort((a, b) => (b.pushedAt ?? "").localeCompare(a.pushedAt ?? ""));
    const asked = Number(q.get("limit") ?? "");
    const limit =
      Number.isFinite(asked) && asked > 0
        ? Math.min(asked, state.maxResponseItems)
        : ordered.length;
    const rows = ordered
      .slice((page - 1) * limit, page * limit)
      .map((r) => repoJson(state, r));
    const payload = rest === "/repos/search" ? { ok: true, data: rows } : rows;
    return jsonResponse(payload, 200, { "x-total-count": String(rows.length) });
    return jsonResponse(payload, 200, {
      "x-total-count": String(state.repoTotalOverride ?? state.repos.length),
    });
  }
  // Cross-repo issue search. Both forges hang it off a path that *looks*
@@ -461,15 +501,30 @@
function route(
    if (parse(bodyText).archived === true) repo.archived = true;
    return jsonResponse(repoJson(state, repo));
  }
  if (tail === "") return jsonResponse(repoJson(state, repo));
  if (tail === "") {
    if (state.failRepos?.has(fullName))
      return jsonResponse({ message: "internal error" }, 500);
    return jsonResponse(repoJson(state, repo));
  }
  // ---- forking ----
  if (tail === "/forks" && method === "GET") {
    const forks = state.repos.filter((r) => r.parent === fullName);
    return jsonResponse(forks.map((r) => repoJson(state, r)), 200, {
      "x-total-count": String(forks.length),
    });
  }
  if (tail === "/forks" && method === "POST") {
    if (state.refuseFork !== "")
      return jsonResponse({ message: state.refuseFork }, 409);
    const name = fullName.split("/")[1]!;
    // `name` is the fork's own name when given (both forges take it).
    const asked = parse(bodyText).name;
    const name = typeof asked === "string" && asked !== "" ? asked : fullName.split("/")[1]!;
    const forkName = `${state.login}/${name}`;
    const already = state.repos.find((r) => r.fullName === forkName);
    // A name the account already uses for something else: Forgejo's 409.
    if (already !== undefined && already.parent !== fullName)
      return jsonResponse({ message: "repository is already exist" }, 409);
    if (already === undefined) {
      state.repos.push({
        id: state.nextId++,
@@ -1169,6 +1224,8 @@
export interface FakeOAuth {
  expiresIn: number;
  /** Hand back a new refresh token on every refresh, as rotation does. */
  rotate: boolean;
  /** Called while a refresh is being answered: something racing it. */
  onRefresh?: () => void;
  /** Answer the next refresh with this OAuth error code. */
  refreshError: string;
  /** Every token-endpoint request body, parsed. */
@@ -1247,6 +1304,7 @@
export function oauthRoute(
        });
      if (form.refresh_token !== oauth.refreshToken)
        return jsonResponse({ error: "unauthorized_client" });
      oauth.onRefresh?.();
      oauth.accessToken = `gho_refreshed${oauth.tokenRequests.length}00000000000000000`;
      if (oauth.rotate)
        oauth.refreshToken = `ghr_rotated${oauth.tokenRequests.length}0000000000000000000`;
@@ -46,11 +46,13 @@
class Cdp {
  private nextId = 1;
  private readonly pending = new Map<number, (msg: CdpMessage) => void>();
  private readonly waiters = new Map<string, () => void>();
  private readonly listeners = new Map<string, ((params: any) => void)[]>();
  constructor(private readonly ws: WebSocket) {
    ws.addEventListener("message", (event) => {
      const msg = JSON.parse(event.data as string) as CdpMessage & {
        method?: string;
        params?: unknown;
      };
      if (msg.id !== undefined) {
        this.pending.get(msg.id)?.(msg);
@@ -58,10 +60,17 @@
class Cdp {
      } else if (msg.method !== undefined) {
        this.waiters.get(msg.method)?.();
        this.waiters.delete(msg.method);
        for (const listen of this.listeners.get(msg.method) ?? [])
          listen(msg.params);
      }
    });
  }
  /** Every time `method` fires as an event, with its params. */
  on(method: string, listen: (params: any) => void): void {
    this.listeners.set(method, [...(this.listeners.get(method) ?? []), listen]);
  }
  send(method: string, params: object = {}): Promise<any> {
    const id = this.nextId++;
    return within(5_000, method, new Promise((resolve, reject) => {
@@ -316,3 +325,128 @@
export function chromiumRuns(binary: string): boolean {
    rmSync(profile, { recursive: true, force: true });
  }
}
/** What a browser did after a click: where it went, and what it refused. */
export interface Followed {
  /** Every URL the page asked for, in order (navigations and redirects). */
  readonly requested: string[];
  /** The page's URL when following stopped. */
  readonly finalUrl: string;
  /**
   * Console errors, log entries and `securitypolicyviolation` events: a
   * Content-Security-Policy refusal lands here, however the browser says it.
   */
  readonly errors: string[];
}
/**
 * Load `url` with a session cookie, then run each of `steps` (an
 * expression evaluated in the page — a click) after the page before it has
 * loaded, and follow the browser until a requested URL satisfies `until` or
 * `timeoutMs` passes. What a real browser enforces and an HTTP client does
 * not — a page's CSP on the redirect that follows its form — is exactly
 * what this sees.
 */
export async function clickAndFollow(
  binary: string,
  input: {
    url: string;
    cookie: { name: string; value: string };
    steps: readonly string[];
    until: (url: string) => boolean;
    /** Done for another reason the page cannot see (a server got the request). */
    done?: () => boolean;
    timeoutMs?: number;
  },
): Promise<Followed> {
  const profile = mkdtempSync(join(tmpdir(), "forge-click-"));
  const proc = Bun.spawn(
    [
      binary,
      "--headless=new",
      "--no-sandbox",
      "--disable-gpu",
      "--disable-dev-shm-usage",
      "--disable-background-networking",
      "--disable-crash-reporter",
      "--no-first-run",
      `--user-data-dir=${profile}`,
      "--remote-debugging-port=0",
    ],
    { env: childEnv({}), stdin: "ignore", stdout: "ignore", stderr: "pipe" },
  );
  let ws: WebSocket | undefined;
  const requested: string[] = [];
  const errors: string[] = [];
  try {
    const browserWsUrl = await Promise.race([
      readDebuggerUrl(proc.stderr),
      Bun.sleep(10_000).then((): string => {
        throw new Error("chromium never printed its devtools address");
      }),
    ]);
    const target = await findPageTarget(browserWsUrl);
    ws = new WebSocket(target.webSocketDebuggerUrl);
    await new Promise<void>((resolve, reject) => {
      ws!.addEventListener("open", () => resolve());
      ws!.addEventListener("error", () =>
        reject(new Error("chromium's devtools socket refused the connection")),
      );
    });
    const cdp = new Cdp(ws);
    cdp.on("Network.requestWillBeSent", (p) => requested.push(String(p.request?.url ?? "")));
    cdp.on("Log.entryAdded", (p) => {
      if (p.entry?.level === "error" || p.entry?.source === "security")
        errors.push(String(p.entry?.text ?? ""));
    });
    cdp.on("Runtime.consoleAPICalled", (p) => {
      if (p.type === "error")
        errors.push((p.args ?? []).map((a: any) => String(a.value ?? a.description ?? "")).join(" "));
    });
    cdp.on("Audits.issueAdded", (p) => {
      const csp = p.issue?.details?.contentSecurityPolicyIssueDetails;
      if (csp !== undefined)
        errors.push(`CSP issue: ${csp.violatedDirective} ${csp.blockedURL ?? ""}`);
    });
    await cdp.send("Page.enable");
    await cdp.send("Network.enable");
    await cdp.send("Log.enable");
    await cdp.send("Runtime.enable");
    await cdp.send("Audits.enable");
    // Every document reports its own CSP refusals, before anything else runs.
    await cdp.send("Page.addScriptToEvaluateOnNewDocument", {
      source: `document.addEventListener("securitypolicyviolation", (e) =>
        console.error("CSP violation: " + e.violatedDirective + " " + e.blockedURI));`,
    });
    await cdp.send("Network.setCookie", {
      name: input.cookie.name,
      value: input.cookie.value,
      url: input.url,
    });
    const deadline = Date.now() + (input.timeoutMs ?? 15_000);
    const reached = () =>
      requested.some(input.until) || (input.done?.() ?? false);
    let loaded = cdp.once("Page.loadEventFired");
    await cdp.send("Page.navigate", { url: input.url });
    await Promise.race([loaded, Bun.sleep(Math.max(0, deadline - Date.now()))]);
    for (const step of input.steps) {
      if (reached()) break;
      loaded = cdp.once("Page.loadEventFired");
      // As a person's click: a user gesture, so a link that opens a tab does.
      await cdp.send("Runtime.evaluate", { expression: step, userGesture: true });
      await Promise.race([loaded, Bun.sleep(Math.max(0, deadline - Date.now()))]);
    }
    while (!reached() && Date.now() < deadline) await Bun.sleep(100);
    // Late reports of what the last navigation refused.
    await Bun.sleep(300);
    const where = await cdp
      .send("Runtime.evaluate", { expression: "location.href", returnByValue: true })
      .catch(() => ({ result: { value: "" } }));
    return { requested, finalUrl: String(where.result?.value ?? ""), errors };
  } finally {
    ws?.close();
    proc.kill("SIGKILL");
    await proc.exited.catch(() => {});
    rmSync(profile, { recursive: true, force: true });
  }
}
@@ -116,7 +116,7 @@
describe("migrate: after", () => {
      kind: "github",
      token: secret,
    });
    if (!connected.ok) throw new Error(connected.error);
    if (!connected.ok) throw new Error(JSON.stringify(connected.error));
    originId = connected.value.id;
    stopMirror = startMirrorOut(app, async (a, repo) => {
      try {
@@ -13,7 +13,7 @@
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createApp, type App } from "../src/app.ts";
import { connectOrigin, listRemoteRepos } from "../src/actions/origins.ts";
import { connectOrigin, connectRefusal, listRemoteRepos } from "../src/actions/origins.ts";
import { listOrigins } from "../src/core/origins.ts";
import { createSession } from "../src/core/sessions.ts";
import { createUser, type User } from "../src/core/users.ts";
@@ -122,7 +122,7 @@
test("a classic token without `repo` says public only and links the new-token pa
      kind: "github",
      token: "public-only-token",
    });
    if (!connected.ok) throw new Error(connected.error);
    if (!connected.ok) throw new Error(connectRefusal(connected.error).code);
    const originId = connected.value.id;
    const page = await get("/migrate");
@@ -293,7 +293,7 @@
test("the terminal's migrate screen says public only, names the new-token page,
      kind: "github",
      token: "carol-public",
    });
    if (!connected.ok) throw new Error(connected.error);
    if (!connected.ok) throw new Error(connectRefusal(connected.error).code);
    tui.start();
    await settleApp(tui);
    terminal.feed("M");
@@ -744,7 +744,7 @@
describe("migrate", () => {
        kind: "github",
        token: upstreamSecret,
      });
      if (!connected.ok) throw new Error(connected.error);
      if (!connected.ok) throw new Error(JSON.stringify(connected.error));
      const agent = await createAgent(app, alice, {
        username: "mover",
        model: "",
@@ -893,7 +893,7 @@
describe("migrate", () => {
        kind: "github",
        token: upstreamSecret,
      });
      if (!connected.ok) throw new Error(connected.error);
      if (!connected.ok) throw new Error(JSON.stringify(connected.error));
      const job = await migrate(alice, {
        source: { originId: connected.value.id, fullName: "octo/forked-pulls" },
      });
@@ -1004,7 +1004,7 @@
describe("migrate", () => {
    try {
      forgetProviders(dataDir);
      const connected = await connectOrigin(app, alice, { host: github.url, kind: "github", token: upstreamSecret });
      if (!connected.ok) throw new Error(connected.error);
      if (!connected.ok) throw new Error(JSON.stringify(connected.error));
      const value = `${connected.value.id}/octo/arm`;
      // The row links to its branches; the list shows each last commit,
@@ -0,0 +1,97 @@
/**
 * Connecting an origin, clicked in a real browser. An HTTP client follows a
 * form's redirect wherever it points; a browser first checks the posting
 * page's `form-action` policy against it, and refuses a redirect off this
 * forge without a word on the page. So this drives headless Chromium
 * (`test/helpers/chrome.ts`): click Authorize on Settings → Origins, then
 * Continue on the flow's page, and see the browser actually ask the origin
 * for its consent screen — the URL stored on the flow — with no
 * Content-Security-Policy refusal on the way.
 */
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 { createApp, type App } from "../src/app.ts";
import { registerOriginApp } from "../src/actions/origins.ts";
import { createSession } from "../src/core/sessions.ts";
import { createUser } from "../src/core/users.ts";
import { serve, type Servers } from "../src/http/server.ts";
import { findChromium } from "../src/looks/capture.ts";
import { clickAndFollow } from "./helpers/chrome.ts";
import { quietLogs, withoutEnv } from "./helpers/globals.ts";
import {
  newFakeOAuth,
  newFakeState,
  serveFakeForge,
  type FakeForge,
} from "./fake-origin.ts";
quietLogs();
withoutEnv("FORGE_URL");
const CLIENT_ID = "forge-browser-client";
const chromium = findChromium();
if (chromium === undefined)
  console.log(
    "SKIPPING: no chromium on this machine (FORGE_CHROMIUM), so the connect buttons cannot be clicked",
  );
describe.skipIf(chromium === undefined)("connecting an origin in a real browser", () => {
  let dir: string;
  let app: App;
  let servers: Servers;
  let fake: FakeForge;
  const consentAsked = (since: number) =>
    fake.state.requests
      .slice(since)
      .some((r) => r.method === "GET" && r.path === "/login/oauth/authorize");
  const refusals = (errors: readonly string[]) =>
    errors.filter((e) => /content security policy|csp/i.test(e));
  beforeAll(async () => {
    const state = newFakeState("forgejo", "octo", "octo-browser-token");
    state.oauth = newFakeOAuth(CLIENT_ID);
    fake = serveFakeForge(state);
    dir = await mkdtemp(join(tmpdir(), "forge-connect-browser-"));
    app = createApp({ dataDir: dir, port: 0 });
    servers = await serve(app);
  }, 20_000);
  afterAll(async () => {
    fake.stop();
    servers.stop();
    app.close();
    await rm(dir, { recursive: true, force: true });
  });
  test("Settings → Origins: Authorize, then Continue, reaches the consent screen", async () => {
    const made = await createUser(app.db, {
      username: "bea",
      email: "[email protected]",
      password: "a-long-browser-passphrase",
      origin: "seed",
      trusted: true,
    });
    if (!made.ok) throw new Error(made.error);
    const registered = await registerOriginApp(app, made.value, {
      host: fake.url,
      clientId: CLIENT_ID,
    });
    expect(registered.ok).toBe(true);
    const before = fake.state.requests.length;
    const followed = await clickAndFollow(chromium!, {
      url: `${servers.url}/settings/origins?host=${encodeURIComponent(fake.url)}`,
      cookie: { name: "forge_session", value: createSession(app.db, made.value.id).token },
      steps: [
        `[...document.querySelectorAll('button')].find((b) => b.textContent.trim() === 'Authorize').click()`,
        `[...document.querySelectorAll('a')].find((a) => a.textContent.includes('Continue to the instance')).click()`,
      ],
      until: (url) => url.startsWith(`${fake.url}/login/oauth/authorize`),
      done: () => consentAsked(before),
    });
    expect(refusals(followed.errors)).toEqual([]);
    expect(consentAsked(before)).toBe(true);
  }, 30_000);
});
@@ -0,0 +1,166 @@
/**
 * A host the operator names in `FORGE_ORIGIN_ALLOW` is one an origin may be
 * connected from, so it is one that origin may be mirrored from too. Before,
 * discovery let such a host through and the mirror's git refused it as a
 * private address: the origin connected, and every mirror, sync and fetch
 * from it then failed. The mirror now trusts that name the way it trusts
 * `FORGE_OUTBOUND_TRUSTED_HOSTS`: by name, pinned to the answer that passed,
 * never by address.
 */
import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
import { networkInterfaces, tmpdir } from "node:os";
import { join, normalize } from "node:path";
import {
  fetchMirror,
  MIRROR_REFUSED,
  provideMirrorOutboundForTest,
  vettedEnv,
} from "../src/origins/git-mirror.ts";
import { loadTrustedHosts } from "../src/origins/trusted-hosts.ts";
import { gitClientEnv } from "./helpers/git-client.ts";
const inCluster = async () => ["10.43.191.15"];
/** Run `fn` with `FORGE_ORIGIN_ALLOW` set (or unset), and put it back. */
async function withAllow<T>(value: string | undefined, fn: () => Promise<T>): Promise<T> {
  const before = process.env.FORGE_ORIGIN_ALLOW;
  if (value === undefined) delete process.env.FORGE_ORIGIN_ALLOW;
  else process.env.FORGE_ORIGIN_ALLOW = value;
  try {
    return await fn();
  } finally {
    if (before === undefined) delete process.env.FORGE_ORIGIN_ALLOW;
    else process.env.FORGE_ORIGIN_ALLOW = before;
  }
}
/** The address git is pinned to, from the environment the mirror hands it. */
function pinOf(env: Record<string, string>): string | undefined {
  for (let i = 0; i < Number(env["GIT_CONFIG_COUNT"] ?? "0"); i++)
    if (env[`GIT_CONFIG_KEY_${i}`] === "http.curloptResolve")
      return env[`GIT_CONFIG_VALUE_${i}`];
  return undefined;
}
afterEach(() => {
  loadTrustedHosts(undefined, {});
  provideMirrorOutboundForTest({ allow: ["127.0.0.1", "::1"] });
});
test("a name the operator allows as an origin passes the mirror's vet, pinned to its answer", async () => {
  provideMirrorOutboundForTest({ resolve: inCluster });
  const url = "https://git.lan/acme/app.git";
  const refused = await withAllow(undefined, () => vettedEnv(url, {}));
  expect(!refused.ok && refused.error.message).toBe(MIRROR_REFUSED);
  const passed = await withAllow("git.lan", () => vettedEnv(url, {}));
  if (!passed.ok) throw new Error(passed.error.message);
  expect(pinOf(passed.value)).toContain("10.43.191.15");
});
test("the allowance is the name's: another name at the same address, or another port, is refused", async () => {
  provideMirrorOutboundForTest({ resolve: inCluster });
  await withAllow("git.lan:8443", async () => {
    const port = await vettedEnv("https://git.lan:8443/acme/app.git", {});
    expect(port.ok).toBe(true);
    for (const url of [
      "https://git.lan/acme/app.git",
      "https://git.lan:9443/acme/app.git",
      "https://other.lan:8443/acme/app.git",
    ]) {
      const refused = await vettedEnv(url, {});
      expect(!refused.ok && refused.error.message).toBe(MIRROR_REFUSED);
    }
  });
});
test("an address the operator names is not trusted for git: trust is by name", async () => {
  await withAllow("10.43.191.15", async () => {
    const refused = await vettedEnv("https://10.43.191.15/acme/app.git", {});
    expect(!refused.ok && refused.error.message).toBe(MIRROR_REFUSED);
  });
});
/** This machine's first private, non-loopback IPv4 address, if it has one. */
function privateAddress(): string | undefined {
  for (const list of Object.values(networkInterfaces()))
    for (const a of list ?? [])
      if (
        a.family === "IPv4" &&
        !a.internal &&
        /^(10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.)/.test(a.address)
      )
        return a.address;
  return undefined;
}
const lan = privateAddress();
if (lan === undefined)
  console.log("SKIPPING the end-to-end half: this machine has no private, non-loopback address");
describe.skipIf(lan === undefined)("an allowed origin inside the network, end to end", () => {
  let dir: string;
  let git: ReturnType<typeof Bun.serve>;
  let served = 0;
  const run = (args: string[], cwd: string): string => {
    const done = Bun.spawnSync(["git", ...args], { cwd, env: gitClientEnv() });
    if (done.exitCode !== 0) throw new Error(`git ${args.join(" ")}: ${done.stderr.toString()}`);
    return done.stdout.toString().trim();
  };
  beforeAll(async () => {
    dir = await mkdtemp(join(tmpdir(), "forge-allow-mirror-"));
    // A repository served as any static web server serves one (git's "dumb"
    // HTTP), on this machine's private address only.
    run(["init", "-q", "-b", "main", "work"], dir);
    await Bun.write(join(dir, "work", "README.md"), "# app\n");
    run(["add", "README.md"], join(dir, "work"));
    run(["commit", "-q", "-m", "first"], join(dir, "work"));
    run(["clone", "-q", "--bare", "work", "app.git"], dir);
    run(["update-server-info"], join(dir, "app.git"));
    run(["init", "-q", "--bare", "mirror.git"], dir);
    const root = join(dir, "app.git");
    git = Bun.serve({
      hostname: lan!,
      port: 0,
      fetch(request) {
        served++;
        const path = decodeURIComponent(new URL(request.url).pathname);
        if (!path.startsWith("/acme/app.git/")) return new Response("", { status: 404 });
        const file = normalize(join(root, path.slice("/acme/app.git/".length)));
        if (!file.startsWith(root)) return new Response("", { status: 404 });
        return new Response(Bun.file(file));
      },
      error: () => new Response("", { status: 404 }),
    });
  });
  afterAll(async () => {
    git.stop(true);
    await rm(dir, { recursive: true, force: true });
  });
  test("not allowed, the name that resolves to it is refused before anything is fetched", async () => {
    provideMirrorOutboundForTest({ resolve: async () => [lan!] });
    const before = served;
    const refused = await withAllow(undefined, () =>
      fetchMirror(join(dir, "mirror.git"), `http://git.lan:${git.port}/acme/app.git`, {}),
    );
    expect(!refused.ok && refused.error.message).toBe(MIRROR_REFUSED);
    expect(served).toBe(before);
  });
  test("allowed, the same name is mirrored over git", async () => {
    provideMirrorOutboundForTest({ resolve: async () => [lan!] });
    const fetched = await withAllow(`git.lan:${git.port}`, () =>
      fetchMirror(join(dir, "mirror.git"), `http://git.lan:${git.port}/acme/app.git`, {}),
    );
    if (!fetched.ok) throw new Error(fetched.error.message);
    expect(run(["rev-parse", "refs/heads/main"], join(dir, "mirror.git"))).toBe(
      run(["rev-parse", "HEAD"], join(dir, "work")),
    );
  });
});
@@ -0,0 +1,165 @@
/**
 * A connect in flight goes on only to the authorize URL sealed on its flow.
 *
 * The flow page used to take that URL from its own query string (`?to=`),
 * checked only for the instance's origin and a PKCE challenge: a crafted
 * link could pick another application's client id or another callback on
 * the same instance. Now the page reads the URL the flow was started with,
 * checks it again (path, client id, callback, challenge), and refuses a `to`
 * that is not exactly that URL. A flow past its time says so, with a fresh
 * Connect, instead of sending anyone to a consent screen for a dead state.
 */
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 { createApp, type App } from "../src/app.ts";
import { registerOriginApp } from "../src/actions/origins.ts";
import { createSession } from "../src/core/sessions.ts";
import { createUser, type User } from "../src/core/users.ts";
import { serve, type Servers } from "../src/http/server.ts";
import { flowTarget } from "../src/origins/oauth.ts";
import { quietLogs, withoutEnv } from "./helpers/globals.ts";
import {
  newFakeOAuth,
  newFakeState,
  serveFakeForge,
  type FakeForge,
} from "./fake-origin.ts";
quietLogs();
withoutEnv("FORGE_URL");
const CLIENT_ID = "forge-flow-page-client";
describe("the connect flow page", () => {
  let dir: string;
  let app: App;
  let servers: Servers;
  let fake: FakeForge;
  let user: User;
  let cookie = "";
  const browse = (path: string, form?: Record<string, string>) =>
    fetch(`${servers.url}${path}`, {
      method: form === undefined ? "GET" : "POST",
      headers: {
        cookie,
        ...(form === undefined ? {} : { origin: new URL(servers.url).origin }),
      },
      redirect: "manual",
      ...(form === undefined ? {} : { body: new URLSearchParams(form) }),
    });
  /** Start a code flow from Settings → Origins: its page, and its id. */
  const start = async (): Promise<{ page: string; id: string }> => {
    const started = await browse("/settings/origins/oauth", { host: fake.url });
    expect(started.status).toBe(303);
    const page = started.headers.get("location")!;
    expect(page).toStartWith("/settings/origins/flows/");
    return { page, id: page.split("/").at(-1)!.split("?")[0]! };
  };
  const continueTo = (html: string): string | undefined =>
    /href="([^"]*\/login\/oauth\/authorize[^"]*)"/.exec(html)?.[1]?.replaceAll("&amp;", "&");
  beforeAll(async () => {
    const state = newFakeState("forgejo", "octo", "octo-flow-page-token");
    state.oauth = newFakeOAuth(CLIENT_ID);
    fake = serveFakeForge(state);
    dir = await mkdtemp(join(tmpdir(), "forge-flow-page-"));
    app = createApp({ dataDir: dir, port: 0 });
    servers = await serve(app);
    const made = await createUser(app.db, {
      username: "ada",
      email: "[email protected]",
      password: "a-long-flow-page-passphrase",
      origin: "seed",
      trusted: true,
    });
    if (!made.ok) throw new Error(made.error);
    user = made.value;
    cookie = `forge_session=${createSession(app.db, user.id).token}`;
    const registered = await registerOriginApp(app, user, {
      host: fake.url,
      clientId: CLIENT_ID,
    });
    if (!registered.ok) throw new Error(registered.error);
  });
  afterAll(async () => {
    fake.stop();
    servers.stop();
    app.close();
    await rm(dir, { recursive: true, force: true });
  });
  test("the redirect carries no URL; the page links to the one stored on the flow", async () => {
    const { page, id } = await start();
    expect(page).not.toContain("to=");
    const stored = flowTarget(app.db, dir, id)!;
    const url = new URL(stored);
    expect(url.pathname).toBe("/login/oauth/authorize");
    expect(url.searchParams.get("client_id")).toBe(CLIENT_ID);
    expect(continueTo(await (await browse(page)).text())).toBe(stored);
  });
  test("a crafted `to` for another application on the same instance is refused", async () => {
    const { page, id } = await start();
    const crafted = new URL(flowTarget(app.db, dir, id)!);
    crafted.searchParams.set("client_id", "someone-elses-client");
    const html = await (
      await browse(`${page}?to=${encodeURIComponent(crafted.toString())}`)
    ).text();
    expect(continueTo(html)).toBeUndefined();
    expect(html).not.toContain("someone-elses-client");
    expect(html).toContain("cannot be continued from here");
  });
  test("a crafted `to` with another callback is refused too; the exact stored URL still goes on", async () => {
    const { page, id } = await start();
    const stored = flowTarget(app.db, dir, id)!;
    const elsewhere = new URL(stored);
    elsewhere.searchParams.set("redirect_uri", "https://evil.example/callback");
    const refused = await (
      await browse(`${page}?to=${encodeURIComponent(elsewhere.toString())}`)
    ).text();
    expect(continueTo(refused)).toBeUndefined();
    const exact = await (await browse(`${page}?to=${encodeURIComponent(stored)}`)).text();
    expect(continueTo(exact)).toBe(stored);
  });
  test("an expired flow is refused, with a fresh Connect in its place", async () => {
    const { page, id } = await start();
    app.db
      .query("UPDATE oauth_flow SET expires_at = ?1 WHERE id = ?2")
      .run(new Date(Date.now() - 60_000).toISOString(), id);
    const html = await (await browse(page)).text();
    expect(html).toContain("This connect link expired");
    expect(continueTo(html)).toBeUndefined();
    expect(html).toContain('action="/settings/origins/oauth"');
    expect(html).toContain(`value="${fake.url}"`);
  });
  test("a connect started from migrate carries only `then`, and its expired page starts again from there", async () => {
    const started = await browse("/settings/origins/oauth", {
      host: fake.url,
      then: "migrate",
    });
    expect(started.status).toBe(303);
    const page = started.headers.get("location")!;
    expect(page).toEndWith("?then=migrate");
    expect(page).not.toContain("to=");
    const id = page.split("/").at(-1)!.split("?")[0]!;
    expect(continueTo(await (await browse(page)).text())).toBe(
      flowTarget(app.db, dir, id)!,
    );
    app.db
      .query("UPDATE oauth_flow SET expires_at = ?1 WHERE id = ?2")
      .run(new Date(Date.now() - 60_000).toISOString(), id);
    const html = await (await browse(page)).text();
    expect(html).toContain("This connect link expired");
    expect(html).toContain('name="then" value="migrate"');
  });
});
@@ -0,0 +1,796 @@
/**
 * The operator guard on the account behind an origin (`origins/operator.ts`,
 * `origins/credential.ts`).
 *
 * A forge keeps an origin's credential where its agents run, so the risk is
 * the account a person authorized. On a host the operator guards, an
 * account that administers the instance is refused, and so is one that can
 * push to a repository `FORGE_ORIGIN_DENY_PUSH` protects: on a pasted token,
 * on an OAuth consent, after each refresh, and on the daily sweep of what is
 * already stored. A check that cannot finish pauses writes (reads go on)
 * until it can, and refuses the origin after a day.
 *
 * The adversarial cases carry the weight: a walk that moves, a count that
 * lies, a lookup that fails beside a hit, a refresh that races a refusal.
 */
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 { createApp, type App } from "../src/app.ts";
import { serve, type Servers } from "../src/http/server.ts";
import {
  checkOriginAgain,
  connectOrigin,
  replaceOriginToken,
  startMirrorJob,
  startOAuthConnect,
  syncOriginNow,
} from "../src/actions/origins.ts";
import { contribute, forkOrigin } from "../src/actions/contribute.ts";
import { openIssueThrough } from "../src/actions/issues.ts";
import { originPush } from "../src/actions/branches.ts";
import { carryBranchThrough, pushThrough } from "../src/origins/push-through.ts";
import {
  getCursor,
  listOriginRepos,
  listOrigins,
  markNeedsReauth,
  setCursor,
  storeRefreshed,
} from "../src/core/origins.ts";
import { createUser, getUserByName, type User } from "../src/core/users.ts";
import { createSession } from "../src/core/sessions.ts";
import { settled } from "../src/origins/jobs.ts";
import {
  denyPushRules,
  guarded,
  GUARD_MAX_PAGES,
  operatorHosts,
} from "../src/origins/operator.ts";
import {
  providerForOrigin,
  recheckOrigin,
  runGuardSweep,
  writesPaused,
} from "../src/origins/credential.ts";
import { forgetProviders } from "../src/origins/providers/index.ts";
import { promote } from "./helpers/members.ts";
import { seedAdmin } from "./helpers/admin.ts";
import { fastFirstFetch, quietLogs, withoutEnv } from "./helpers/globals.ts";
import {
  newFakeOAuth,
  newFakeState,
  serveFakeForge,
  type FakeForge,
  type FakeState,
} from "./fake-origin.ts";
quietLogs();
fastFirstFetch();
const ENV = ["FORGE_ORIGIN_CLIENT_ID", "FORGE_ORIGIN_DENY_PUSH", "FORGE_URL"] as const;
withoutEnv(...ENV);
const LOGIN = "octo";
const TOKEN = "octo-guard-secret-7c1e";
const PASSWORD = "a-long-guard-passphrase";
const CLIENT_ID = "forge-guard-client";
const basic = (user: string, secret: string): string =>
  `Basic ${Buffer.from(`${user}:${secret}`).toString("base64")}`;
/** Run `fn` with these variables set, and put back what was there. */
async function withEnv<T>(
  vars: Partial<Record<(typeof ENV)[number], string>>,
  fn: () => Promise<T>,
): Promise<T> {
  const before = new Map<string, string | undefined>();
  for (const [name, value] of Object.entries(vars)) {
    before.set(name, process.env[name]);
    process.env[name] = value;
  }
  try {
    return await fn();
  } finally {
    for (const [name, value] of before) {
      if (value === undefined) delete process.env[name];
      else process.env[name] = value;
    }
  }
}
// ---- the parsing, with no forge at all ----
describe("the operator's variables", () => {
  test("operator hosts are FORGE_ORIGIN_CLIENT_ID's, by hostname", () => {
    expect(
      operatorHosts({
        FORGE_ORIGIN_CLIENT_ID: " Git.Example=abc , other.example=d,broken,=x,empty=",
      }),
    ).toEqual(["git.example", "other.example"]);
    expect(operatorHosts({})).toEqual([]);
  });
  test("deny-push rules: bare for every host, host: for one, owner alone is owner/*", () => {
    const rules = denyPushRules({
      FORGE_ORIGIN_DENY_PUSH:
        "system/*, git.example:platform/*, Infra, a/b/c, bad name/x, acme/app-*,git.example:8443:ops/deploy",
    });
    expect(rules.map((r) => [r.host, r.pattern, r.exact])).toEqual([
      [null, "system/*", false],
      ["git.example", "platform/*", false],
      [null, "infra/*", false],
      [null, "acme/app-*", false],
      ["git.example", "ops/deploy", true],
    ]);
    const [system, , infra, apps] = rules;
    expect(system!.matches("System/Open-Platform")).toBe(true);
    expect(system!.matches("systems/x")).toBe(false);
    expect(infra!.matches("infra/anything")).toBe(true);
    expect(apps!.matches("acme/app-jobs")).toBe(true);
    expect(apps!.matches("acme/jobs")).toBe(false);
  });
  test("a host is guarded when the operator registered it or a rule covers it", () => {
    const at = { apiUrl: "https://git.example/api/v1", webUrl: "https://git.example" };
    expect(guarded(at, {})).toBe(false);
    expect(guarded(at, { FORGE_ORIGIN_CLIENT_ID: "git.example=id" })).toBe(true);
    expect(guarded(at, { FORGE_ORIGIN_DENY_PUSH: "other.example:system/*" })).toBe(false);
    expect(guarded(at, { FORGE_ORIGIN_DENY_PUSH: "system/*" })).toBe(true);
  });
});
// ---- against a fake Forgejo and a real forge serving its git ----
describe("the guard against an operator's Forgejo", () => {
  let upstreamDir: string;
  let upstreamApp: App;
  let upstream: Servers;
  let fake: FakeForge;
  let state: FakeState;
  /** A forge of our own, with one member, and its session cookie. */
  interface Local {
    dir: string;
    app: App;
    servers: Servers;
    cookie: string;
    alice: User;
  }
  const locals: Local[] = [];
  /** A member of `app`, made directly (sign-ups are limited per address). */
  const member = async (app: App, username: string): Promise<User> => {
    const made = await createUser(app.db, {
      username,
      email: `${username}@forge.test`,
      password: PASSWORD,
      origin: "seed",
      trusted: true,
    });
    if (!made.ok) throw new Error(`no account ${username}: ${made.error}`);
    // A member, as an owner would make it: a guest owns no repository.
    promote(app.db, made.value);
    return getUserByName(app.db, username)!;
  };
  const boot = async (): Promise<Local> => {
    const dir = await mkdtemp(join(tmpdir(), "forge-guard-"));
    const app = createApp({ dataDir: dir, port: 0 });
    const servers = await serve(app);
    const alice = await member(app, "alice");
    const local = {
      dir,
      app,
      servers,
      cookie: `forge_session=${createSession(app.db, alice.id).token}`,
      alice,
    };
    locals.push(local);
    return local;
  };
  /** A browser request: session cookie, manual redirects, a real Origin. */
  const browse = (
    local: Local,
    path: string,
    form?: Record<string, string>,
    cookie = local.cookie,
  ): Promise<Response> => {
    const headers = new Headers({ cookie });
    if (form !== undefined) headers.set("origin", new URL(local.servers.url).origin);
    return fetch(`${local.servers.url}${path}`, {
      method: form === undefined ? "GET" : "POST",
      headers,
      redirect: "manual",
      ...(form === undefined ? {} : { body: new URLSearchParams(form) }),
    });
  };
  const host = (): string => new URL(fake.url).hostname;
  beforeAll(async () => {
    upstreamDir = await mkdtemp(join(tmpdir(), "forge-guard-up-"));
    upstreamApp = createApp({ dataDir: upstreamDir, port: 0 });
    upstream = await serve(upstreamApp);
    // The git host's own account: seeded, so it may make repositories.
    const seeded = await seedAdmin(upstreamApp, {
      username: LOGIN,
      email: "[email protected]",
      password: TOKEN,
    });
    if (!seeded.ok) throw new Error(`no git-host account: ${seeded.error}`);
    await fetch(`${upstream.url}/api/v1/repos`, {
      method: "POST",
      headers: { "content-type": "application/json", authorization: basic(LOGIN, TOKEN) },
      body: JSON.stringify({ name: "widgets", visibility: "public" }),
    });
    await fetch(`${upstream.url}/api/v1/repos/octo/widgets/contents`, {
      method: "POST",
      headers: { "content-type": "application/json", authorization: basic(LOGIN, TOKEN) },
      body: JSON.stringify({
        branch: "main",
        message: "first",
        files: [{ path: "README.md", content: "# widgets\n" }],
      }),
    });
    state = newFakeState("forgejo", LOGIN, TOKEN);
    state.repos.push(
      {
        id: 41,
        fullName: "octo/widgets",
        cloneUrl: `${upstream.url}/octo/widgets.git`,
        htmlUrl: `${upstream.url}/octo/widgets`,
        pushedAt: "2026-10-01T00:00:00Z",
      },
      {
        id: 42,
        fullName: "acme-corp/jobs",
        cloneUrl: `${upstream.url}/octo/widgets.git`,
        pushedAt: "2026-10-02T00:00:00Z",
      },
      {
        id: 43,
        fullName: "system/deploy",
        cloneUrl: `${upstream.url}/octo/widgets.git`,
        push: false,
        admin: false,
      },
    );
    baseline = state.repos.map((r) => ({ ...r }));
    state.oauth = newFakeOAuth(CLIENT_ID);
    fake = serveFakeForge(state);
  });
  afterAll(async () => {
    fake.stop();
    upstream.stop();
    upstreamApp.close();
    for (const local of locals) {
      local.servers.stop();
      local.app.close();
      forgetProviders(local.dir);
      await rm(local.dir, { recursive: true, force: true });
    }
    await rm(upstreamDir, { recursive: true, force: true });
  });
  /** The fake as it starts every test: an ordinary account, nothing protected. */
  let baseline: FakeState["repos"] = [];
  const reset = (): void => {
    state.siteAdmin = false;
    delete state.onRepoPage;
    delete state.repoTotalOverride;
    delete state.failRepos;
    delete state.oauth!.onRefresh;
    state.maxResponseItems = 50;
    state.oauth!.expiresIn = 3600;
    state.repos = baseline.map((r) => ({ ...r }));
  };
  const deploy = () => state.repos.find((r) => r.fullName === "system/deploy")!;
  const operator = () => ({ FORGE_ORIGIN_CLIENT_ID: `${host()}=${CLIENT_ID}` });
  /**
   * Authorize on the instance with the operator's application, and come back
   * to the forge's callback. Run inside `withEnv(operator())`.
   */
  const consent = async (local: Local): Promise<Response> => {
    const started = await startOAuthConnect(local.app, local.alice, {
      host: fake.url,
      redirectUri: `${local.servers.url}/settings/origins/callback`,
    });
    if (!started.ok) throw new Error(`no flow: ${started.error.message}`);
    const at = new URL(started.value.url);
    return browse(
      local,
      `/settings/origins/callback?state=${encodeURIComponent(at.searchParams.get("state")!)}&code=${state.oauth!.authCode}`,
    );
  };
  /** A refusal from the guard, or a thrown test. */
  const guardError = (result: Awaited<ReturnType<typeof connectOrigin>>) => {
    if (result.ok || typeof result.error === "string" || !("repos" in result.error))
      throw new Error("not a guard refusal");
    return result.error;
  };
  // ---- a pasted token ----
  describe("on a pasted token", () => {
    let local: Local;
    let n = 0;
    /** A fresh account per attempt: connecting is rate-limited per person. */
    const person = (): Promise<User> => member(local.app, `p${++n}`);
    const paste = (who: User) =>
      connectOrigin(local.app, who, { host: fake.url, token: TOKEN });
    beforeAll(async () => {
      local = await boot();
    });
    test("an administrator's token is refused on the operator's host, and nothing is stored", async () => {
      reset();
      state.siteAdmin = true;
      const who = await person();
      const refused = await withEnv(operator(), () => paste(who));
      reset();
      const error = guardError(refused);
      expect(error.error).toBe("admin_account");
      expect(error.message).toContain("everyday non-admin account");
      expect(listOrigins(local.app.db, who.id)).toHaveLength(0);
    });
    test("the same token connects where the operator guards nothing, as before", async () => {
      reset();
      state.siteAdmin = true;
      const connected = await paste(await person());
      reset();
      expect(connected.ok).toBe(true);
    });
    test("replacing a stored token meets the same guard, and a refusal keeps the old token", async () => {
      reset();
      const who = await person();
      const connected = await paste(who);
      if (!connected.ok) throw new Error("no origin to replace the token of");
      const swap = (token: string) =>
        replaceOriginToken(local.app, who, connected.value.id, token);
      state.siteAdmin = true;
      const refused = await withEnv(operator(), () => swap(TOKEN));
      expect(refused.ok).toBe(false);
      if (!refused.ok) expect(refused.error).toBe("admin_account");
      // Where the operator guards nothing, the same token is replaced as before.
      expect((await swap(TOKEN)).ok).toBe(true);
      state.siteAdmin = false;
      const passed = await withEnv(operator(), () => swap(TOKEN));
      reset();
      expect(passed.ok).toBe(true);
    });
    test("a token that can push to a protected repository is refused, naming it", async () => {
      reset();
      deploy().push = true;
      const who = await person();
      const refused = await withEnv({ FORGE_ORIGIN_DENY_PUSH: "system/*" }, () => paste(who));
      reset();
      const error = guardError(refused);
      expect(error.error).toBe("can_push");
      expect(error.repos).toEqual(["system/deploy"]);
      expect(error.message).toContain("system/deploy");
      expect(listOrigins(local.app.db, who.id)).toHaveLength(0);
    });
    test("a repository named outright is asked about by name", async () => {
      reset();
      deploy().push = true;
      const who = await person();
      const before = state.requests.length;
      const refused = await withEnv({ FORGE_ORIGIN_DENY_PUSH: "system/deploy" }, () =>
        paste(who),
      );
      const asked = state.requests.slice(before).map((r) => r.path);
      reset();
      expect(guardError(refused).repos).toEqual(["system/deploy"]);
      expect(asked).toContain("/api/v1/repos/system/deploy");
    });
    test("an account that cannot push there connects, and its repositories are cached at once", async () => {
      reset();
      const connected = await withEnv({ FORGE_ORIGIN_DENY_PUSH: "system/*" }, async () =>
        paste(await person()),
      );
      if (!connected.ok) throw new Error("connect failed");
      const cached = listOriginRepos(local.app.db, connected.value.id).map((r) => r.fullName);
      expect(cached.sort()).toEqual(["acme-corp/jobs", "octo/widgets", "system/deploy"]);
      // It passed, so its writes are not paused.
      await withEnv({ FORGE_ORIGIN_DENY_PUSH: "system/*" }, async () => {
        expect(writesPaused(local.app, connected.value.id)).toBeUndefined();
      });
    });
    test("an account with more repositories than the guard reads is refused, not waved through", async () => {
      reset();
      // A page of one, and more repositories than the walk has pages.
      state.maxResponseItems = 1;
      for (let i = 0; i < GUARD_MAX_PAGES; i++)
        state.repos.push({ id: 500 + i, fullName: `octo/extra-${i}`, cloneUrl: "", push: false });
      const who = await person();
      const refused = await withEnv({ FORGE_ORIGIN_DENY_PUSH: "system/*" }, () => paste(who));
      reset();
      expect(guardError(refused).error).toBe("guard_unchecked");
      expect(listOrigins(local.app.db, who.id)).toHaveLength(0);
    });
    test("a protected repository pushed mid-walk cannot slip past: the walk is by id, with no fallback", async () => {
      reset();
      state.maxResponseItems = 1;
      deploy().push = true;
      deploy().pushedAt = "2020-01-01T00:00:00Z";
      // Between pages, the protected repository becomes the most recently
      // updated: in a newest-first listing it would jump to the page already read.
      state.onRepoPage = (page) => {
        if (page === 2) deploy().pushedAt = new Date().toISOString();
      };
      const before = state.requests.length;
      const refused = await withEnv({ FORGE_ORIGIN_DENY_PUSH: "system/*" }, async () =>
        paste(await person()),
      );
      const requests = state.requests.slice(before);
      const walked = requests.filter((r) => r.path.endsWith("/repos/search"));
      reset();
      expect(guardError(refused).repos).toEqual(["system/deploy"]);
      expect(walked.length).toBeGreaterThanOrEqual(3);
      for (const r of walked) expect(r.query).toContain("sort=id");
      expect(requests.some((r) => r.path.endsWith("/user/repos"))).toBe(false);
    });
    test("a count that does not add up refuses: one the origin overstates, and one that changes mid-walk", async () => {
      reset();
      state.repoTotalOverride = 4;
      const overstated = await withEnv({ FORGE_ORIGIN_DENY_PUSH: "system/*" }, async () =>
        paste(await person()),
      );
      reset();
      expect(guardError(overstated).error).toBe("guard_unchecked");
      state.maxResponseItems = 1;
      state.onRepoPage = (page) => {
        if (page === 2) state.repos = state.repos.filter((r) => r.fullName !== "octo/widgets");
      };
      const shrunk = await withEnv({ FORGE_ORIGIN_DENY_PUSH: "system/*" }, async () =>
        paste(await person()),
      );
      reset();
      expect(guardError(shrunk).error).toBe("guard_unchecked");
    });
    test("a confirmed hit is refused as one, even when another lookup fails", async () => {
      reset();
      deploy().push = true;
      state.repos.push({ id: 44, fullName: "ops/broken", cloneUrl: "", push: false });
      state.failRepos = new Set(["ops/broken"]);
      const refused = await withEnv(
        { FORGE_ORIGIN_DENY_PUSH: "ops/broken,system/deploy" },
        async () => paste(await person()),
      );
      reset();
      const error = guardError(refused);
      expect(error.error).toBe("can_push");
      expect(error.repos).toEqual(["system/deploy"]);
    });
    test("a hit in a walk that did not finish is refused as one, not as unchecked", async () => {
      reset();
      deploy().push = true;
      state.maxResponseItems = 1;
      // The count says one more than there is: the walk ends incomplete, after
      // it has read the protected repository.
      state.repoTotalOverride = 4;
      const refused = await withEnv({ FORGE_ORIGIN_DENY_PUSH: "system/*" }, async () =>
        paste(await person()),
      );
      reset();
      const error = guardError(refused);
      expect(error.error).toBe("can_push");
      expect(error.repos).toEqual(["system/deploy"]);
    });
    test("every repository named outright is asked about, the sixtieth too", async () => {
      reset();
      deploy().push = true;
      const names = [...Array.from({ length: 59 }, (_, i) => `ops/repo-${i}`), "system/deploy"];
      const before = state.requests.length;
      const refused = await withEnv({ FORGE_ORIGIN_DENY_PUSH: names.join(",") }, async () =>
        paste(await person()),
      );
      const asked = state.requests
        .slice(before)
        .filter((r) => /^\/api\/v1\/repos\/(ops|system)\//.test(r.path));
      reset();
      expect(guardError(refused).repos).toEqual(["system/deploy"]);
      expect(asked).toHaveLength(60);
    });
    test("the web form says the guard's sentence and keeps no token", async () => {
      reset();
      state.siteAdmin = true;
      const who = await person();
      const cookie = `forge_session=${createSession(local.app.db, who.id).token}`;
      const response = await withEnv(operator(), () =>
        browse(local, "/settings/origins/token", { host: fake.url, token: TOKEN }, cookie),
      );
      reset();
      expect(response.status).toBe(422);
      const page = await response.text();
      expect(page).toContain("is an administrator of localhost");
      expect(page).not.toContain(TOKEN);
      expect(listOrigins(local.app.db, who.id)).toHaveLength(0);
    });
  });
  // ---- an OAuth consent ----
  describe("on an OAuth consent", () => {
    test("an administrator who consents is refused with the sentence, and nothing is kept", async () => {
      reset();
      state.siteAdmin = true;
      const local = await boot();
      await withEnv(operator(), async () => {
        const back = await consent(local);
        reset();
        expect(back.status).toBe(303);
        const to = back.headers.get("location")!;
        expect(to).toStartWith("/settings/origins?error=");
        const page = await (await browse(local, to)).text();
        expect(page).toContain("everyday non-admin account");
        expect(page).toContain("did not keep the token");
        // The whole sentence, with where to remove the grant: not cut short.
        expect(page).toContain("under Settings → Applications.");
        expect(listOrigins(local.app.db, local.alice.id)).toHaveLength(0);
      });
    });
    test("an everyday account consents, connects, and writes at once", async () => {
      reset();
      const local = await boot();
      await withEnv(operator(), async () => {
        const back = await consent(local);
        expect(back.headers.get("location")).toBe("/settings/origins?connected=1");
        const origins = listOrigins(local.app.db, local.alice.id);
        expect(origins).toHaveLength(1);
        expect(origins[0]!.authKind).toBe("oauth");
        expect(writesPaused(local.app, origins[0]!.id)).toBeUndefined();
      });
    });
  });
  // ---- what is already stored ----
  describe("stored origins, checked again", () => {
    const deny = () => ({ ...operator(), FORGE_ORIGIN_DENY_PUSH: "system/*" });
    test("a refresh checks the account again and cuts it off before the new token is used", async () => {
      reset();
      // A token that expires inside the refresh margin: the next use refreshes it.
      state.oauth!.expiresIn = 30;
      const local = await boot();
      await withEnv(deny(), async () => {
        await consent(local);
        const origin = listOrigins(local.app.db, local.alice.id)[0]!;
        expect(origin.needsReauth).toBe(false);
        // Since it connected, the account was given push on a protected repository.
        deploy().push = true;
        const provider = providerForOrigin(local.app, origin);
        if (!provider.ok) throw new Error("no provider");
        const used = await provider.value.whoami();
        expect(used.ok).toBe(false);
        expect(state.oauth!.tokenRequests.at(-1)?.grant_type).toBe("refresh_token");
        const after = listOrigins(local.app.db, local.alice.id)[0]!;
        expect(after.needsReauth).toBe(true);
        expect(after.lastError).toContain("system/deploy");
        // Nothing travels on it any more: no git credential either.
        expect(await provider.value.gitAuthEnv(`${upstream.url}/octo/widgets.git`)).toEqual({});
        const page = await (await browse(local, "/settings/origins")).text();
        expect(page).toContain("can push to system/deploy");
        expect(page).toContain(`Re-authorize ${LOGIN} at`);
      });
      reset();
    });
    test("the sweep refuses an origin connected before the guard, and leaves it refused", async () => {
      reset();
      deploy().push = true;
      const local = await boot();
      // Connected with nothing guarded: the forge as it was before the guard.
      const connected = await connectOrigin(local.app, local.alice, { host: fake.url, token: TOKEN });
      if (!connected.ok) throw new Error("connect failed");
      await withEnv(deny(), async () => {
        await runGuardSweep(local.app);
        const after = listOrigins(local.app.db, local.alice.id)[0]!;
        expect(after.needsReauth).toBe(true);
        expect(after.lastError).toContain("system/deploy");
        // A refused origin is not checked again until someone reconnects it.
        const before = state.requests.length;
        await runGuardSweep(local.app);
        expect(state.requests.length).toBe(before);
      });
      reset();
    });
    test("while a connection cannot be verified, every write is paused and reads go on", async () => {
      reset();
      const local = await boot();
      const connected = await withEnv(deny(), () =>
        connectOrigin(local.app, local.alice, { host: fake.url, token: TOKEN }),
      );
      if (!connected.ok) throw new Error("connect failed");
      const id = connected.value.id;
      const job = startMirrorJob(local.app, local.alice, id, "octo/widgets", "widgets");
      if (!job.ok) throw new Error("mirror refused");
      const mirror = (await settled(job.value.id))!.repo!;
      await withEnv(deny(), async () => {
        // The check runs, and cannot finish: a count that does not add up.
        state.repoTotalOverride = 99;
        const checked = await checkOriginAgain(local.app, local.alice, id);
        delete state.repoTotalOverride;
        expect(checked.ok && checked.value).toBe("unchecked");
        expect(writesPaused(local.app, id)).toBeDefined();
        expect(listOrigins(local.app.db, local.alice.id)[0]!.needsReauth).toBe(false);
        const writesBefore = state.requests.filter((r) => r.method !== "GET").length;
        // Write-through, a push, a branch carried up, a fork, a contribution:
        // every one refused here, before the origin is asked.
        const issue = await openIssueThrough(local.app, local.alice, mirror, { title: "x" });
        expect(!issue.ok && issue.error).toBe("origin_paused");
        const push = await originPush(local.app, local.alice, mirror);
        expect(!push.ok && push.error).toBe("origin_paused");
        const carried = await carryBranchThrough(local.app, mirror, mirror, "topic", local.alice.id);
        expect(!carried.ok && carried.error.message).toContain("writes through it are paused");
        const pushed = await pushThrough(local.app, mirror, [], {}, local.alice.id);
        expect(pushed.ok).toBe(false);
        const forked = await forkOrigin(local.app, local.alice, id, "acme-corp/jobs");
        expect(!forked.ok && forked.error).toBe("origin_paused");
        const proposed = await contribute(local.app, local.alice, {
          originId: id,
          fullName: "octo/widgets",
          branch: "topic",
          files: [{ path: "a.txt", content: "a" }],
        });
        expect(!proposed.ok && proposed.error).toBe("origin_paused");
        // And the adapter itself refuses any request that is not a read.
        const provider = providerForOrigin(local.app, listOrigins(local.app.db, local.alice.id)[0]!);
        if (!provider.ok) throw new Error("no provider");
        const direct = await provider.value.createIssue("octo/widgets", { title: "x", body: "" });
        expect(!direct.ok && direct.error.error).toBe("forbidden");
        expect(state.requests.filter((r) => r.method !== "GET").length).toBe(writesBefore);
        // Reads go on.
        expect((await provider.value.whoami()).ok).toBe(true);
        const synced = await syncOriginNow(local.app, local.alice, id);
        expect(synced.ok && synced.value.error).toBe("");
        // Settings → Origins says so, with the way out.
        const page = await (await browse(local, "/settings/origins")).text();
        expect(page).toContain("Couldn't verify this connection; writes paused");
        expect(page).toContain(`action="/settings/origins/${id}/check"`);
        // Asked again at once: too soon, said on the page it was asked from.
        const again = await browse(local, `/settings/origins/${id}/check`, {});
        expect(again.status).toBe(303);
        expect(again.headers.get("location")).toBe("/settings/origins");
        expect(writesPaused(local.app, id)).toBeDefined();
        // A check that passes turns writes back on.
        const passed = await recheckOrigin(
          local.app,
          listOrigins(local.app.db, local.alice.id)[0]!,
          provider.value,
        );
        expect(passed).toBe("passed");
        expect(writesPaused(local.app, id)).toBeUndefined();
        const opened = await openIssueThrough(local.app, local.alice, mirror, { title: "now" });
        expect(opened.ok).toBe(true);
        const after = await (await browse(local, "/settings/origins")).text();
        expect(after).not.toContain("writes paused");
        // One that has not run for a day refuses the origin.
        state.repoTotalOverride = 99;
        setCursor(
          local.app.db,
          id,
          "guard_unchecked_since",
          new Date(Date.now() - 25 * 60 * 60_000).toISOString(),
        );
        expect(
          await recheckOrigin(local.app, listOrigins(local.app.db, local.alice.id)[0]!, provider.value),
        ).toBe("refused");
        delete state.repoTotalOverride;
        expect(listOrigins(local.app.db, local.alice.id)[0]!.needsReauth).toBe(true);
      });
      reset();
    });
    test("Check again on Settings → Origins runs the guard and says what it found", async () => {
      reset();
      const local = await boot();
      // Connected before the guard: never checked, so paused once guarded.
      const connected = await connectOrigin(local.app, local.alice, { host: fake.url, token: TOKEN });
      if (!connected.ok) throw new Error("connect failed");
      const id = connected.value.id;
      await withEnv(deny(), async () => {
        expect(writesPaused(local.app, id)).toBeDefined();
        const checked = await browse(local, `/settings/origins/${id}/check`, {});
        expect(checked.status).toBe(303);
        expect(checked.headers.get("location")).toBe("/settings/origins");
        const flash = (checked.headers.get("set-cookie") ?? "").split(";")[0]!;
        const page = await (
          await browse(local, "/settings/origins", undefined, `${local.cookie}; ${flash}`)
        ).text();
        expect(page).toContain("Verified. Writes through this connection are on again.");
        expect(writesPaused(local.app, id)).toBeUndefined();
        // Another person's origin is not theirs to check.
        const bob = await member(local.app, "bob");
        const theirs = await checkOriginAgain(local.app, bob, id);
        expect(!theirs.ok && theirs.error).toBe("not_found");
      });
      reset();
    });
    test("a refresh that races a refusal never undoes it", async () => {
      reset();
      state.oauth!.expiresIn = 30;
      const local = await boot();
      await withEnv(deny(), async () => {
        await consent(local);
        const origin = listOrigins(local.app.db, local.alice.id)[0]!;
        // The sweep refuses the origin while its refresh is on the wire.
        state.oauth!.onRefresh = () =>
          markNeedsReauth(local.app.db, origin.id, "refused by the sweep");
        const provider = providerForOrigin(local.app, origin);
        if (!provider.ok) throw new Error("no provider");
        const used = await provider.value.whoami();
        expect(state.oauth!.tokenRequests.at(-1)?.grant_type).toBe("refresh_token");
        expect(used.ok).toBe(false);
        const after = listOrigins(local.app.db, local.alice.id)[0]!;
        expect(after.needsReauth).toBe(true);
        expect(after.lastError).toBe("refused by the sweep");
      });
      // And the store itself: a refresh written after a refusal keeps it.
      const origin = listOrigins(local.app.db, local.alice.id)[0]!;
      storeRefreshed(local.app.db, local.dir, origin.id, { token: "t", expiresAt: null });
      expect(listOrigins(local.app.db, local.alice.id)[0]!.needsReauth).toBe(true);
      reset();
    });
    test("the sweep checks one origin at a time, stamps the ones that pass, and then rests", async () => {
      reset();
      const local = await boot();
      const bob = await member(local.app, "bob");
      for (const who of [local.alice, bob]) {
        const made = await connectOrigin(local.app, who, { host: fake.url, token: TOKEN });
        if (!made.ok) throw new Error("connect failed");
      }
      const ids = [local.alice, bob].map((u) => listOrigins(local.app.db, u.id)[0]!.id);
      const stamped = () =>
        ids.filter((id) => getCursor(local.app.db, id, "guard_checked_at") !== undefined).length;
      await withEnv(deny(), async () => {
        expect(stamped()).toBe(0);
        await runGuardSweep(local.app);
        expect(stamped()).toBe(1);
        await runGuardSweep(local.app);
        expect(stamped()).toBe(2);
        const before = state.requests.length;
        await runGuardSweep(local.app);
        expect(state.requests.length).toBe(before);
      });
      expect(listOrigins(local.app.db, bob.id)[0]!.needsReauth).toBe(false);
    });
  });
});
@@ -0,0 +1,128 @@
/**
 * A token that lacks a scope is told which one, in the words of the page
 * that makes tokens; the token form says what a token needs, and links to
 * that page with the scopes already chosen.
 *
 * Forgejo answers a missing scope with a 403 whose body names it
 * (`token does not have at least one of required scope(s): [read:user]`).
 * Read as a bare "forbidden" that became "That token was refused by the
 * origin", and a person could not tell a wrong token from a narrow one.
 */
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 { createApp, type App } from "../src/app.ts";
import { connectOrigin } from "../src/actions/origins.ts";
import { listOrigins } from "../src/core/origins.ts";
import { createSession } from "../src/core/sessions.ts";
import { createUser, type User } from "../src/core/users.ts";
import { serve, type Servers } from "../src/http/server.ts";
import { missingScopes, scopeWords } from "../src/origins/providers/http.ts";
import { forgetProviders } from "../src/origins/providers/index.ts";
import { quietLogs } from "./helpers/globals.ts";
import { newFakeState, serveFakeForge, type FakeForge } from "./fake-origin.ts";
quietLogs();
const TOKEN = "octo-scope-words-token";
describe("a scope refusal, read", () => {
  test("Forgejo's 403 names the scopes; anything else names none", () => {
    expect(
      missingScopes(
        '{"message":"token does not have at least one of required scope(s): [read:user]"}',
      ),
    ).toEqual(["read:user"]);
    expect(
      missingScopes("required scope(s): [read:issue write:issue, <script>]"),
    ).toEqual(["read:issue", "write:issue"]);
    expect(missingScopes('{"message":"forbidden"}')).toEqual([]);
    expect(missingScopes("")).toEqual([]);
  });
  test("scopes in the token page's words", () => {
    expect(scopeWords(["read:user"])).toBe("User: Read");
    expect(scopeWords(["write:issue"])).toBe("Issue: Read and write");
    expect(scopeWords(["read:repository", "read:organization"])).toBe(
      "Repository: Read or Organization: Read",
    );
  });
});
describe("connecting with a token that lacks a scope", () => {
  let dir: string;
  let app: App;
  let servers: Servers;
  let fake: FakeForge;
  let user: User;
  let cookie = "";
  beforeAll(async () => {
    fake = serveFakeForge(newFakeState("forgejo", "octo", TOKEN));
    dir = await mkdtemp(join(tmpdir(), "forge-token-scopes-"));
    app = createApp({ dataDir: dir, port: 0 });
    servers = await serve(app);
    const made = await createUser(app.db, {
      username: "ada",
      email: "[email protected]",
      password: "a-long-token-passphrase",
      origin: "seed",
      trusted: true,
    });
    if (!made.ok) throw new Error(made.error);
    user = made.value;
    cookie = `forge_session=${createSession(app.db, user.id).token}`;
  });
  afterAll(async () => {
    fake.stop();
    servers.stop();
    app.close();
    forgetProviders(dir);
    await rm(dir, { recursive: true, force: true });
  });
  test("is told which scope, and nothing is stored", async () => {
    fake.state.userScopeMissing = "read:user";
    const refused = await connectOrigin(app, user, { host: fake.url, token: TOKEN });
    delete fake.state.userScopeMissing;
    if (refused.ok || typeof refused.error === "string")
      throw new Error("not a scope refusal");
    expect(refused.error.error).toBe("missing_scopes");
    expect(refused.error.message).toContain("This token is missing User: Read.");
    expect(listOrigins(app.db, user.id)).toHaveLength(0);
  });
  test("the API says the same, as a code a client can branch on", async () => {
    fake.state.userScopeMissing = "read:user";
    const response = await fetch(`${servers.url}/api/v1/user/origins`, {
      method: "POST",
      headers: {
        "content-type": "application/json",
        cookie,
        origin: new URL(servers.url).origin,
      },
      body: JSON.stringify({ host: fake.url, token: TOKEN }),
    });
    delete fake.state.userScopeMissing;
    expect(response.status).toBe(422);
    const body = (await response.json()) as { error: string; message: string };
    expect(body.error).toBe("missing_scopes");
    expect(body.message).toContain("User: Read");
    expect(JSON.stringify(body)).not.toContain(TOKEN);
  });
  test("the token form says what a token needs, and links to a prefilled one", async () => {
    const page = await (
      await fetch(`${servers.url}/settings/origins?host=${encodeURIComponent(fake.url)}`, {
        headers: { cookie },
      })
    ).text();
    expect(page).toContain("Repository: Read and write");
    expect(page).toContain(
      `${fake.url}/user/settings/applications/tokens/new?name=forge&amp;resource=all&amp;scope=read:user&amp;scope=write:repository&amp;scope=write:issue`,
    );
  });
});
@@ -0,0 +1,408 @@
/**
 * Contributing with read access (owner, 2026-10-16): "If you have code read
 * you can clone or fork; with pull requests you can open a PR." A fork of a
 * mirror proposes upstream through the account's own fork at the origin
 * when it cannot push to the origin repository — and always for a
 * repository the operator protects, which this forge never pushes to.
 *
 * Two real forges and a fake API in front of one of them, as in
 * `fork-flow.test.ts`: the upstream forge is the git host the fake's clone
 * URLs point at, so a push that "landed" can be read back from its repos.
 */
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 { createApp, type App } from "../src/app.ts";
import { serve, type Servers } from "../src/http/server.ts";
import { originPush } from "../src/actions/branches.ts";
import { editFiles } from "../src/actions/contents.ts";
import { contribute } from "../src/actions/contribute.ts";
import { connectOrigin, startMirrorJob } from "../src/actions/origins.ts";
import { openPull } from "../src/actions/pulls.ts";
import { forkRepo } from "../src/actions/repos.ts";
import { proposeUpstream } from "../src/actions/upstream.ts";
import {
  clearCursor,
  getOriginFor,
  mirrorOf,
  type Origin,
} from "../src/core/origins.ts";
import { getForkOf, getRepoById, type Repo } from "../src/core/repos.ts";
import { createUser, getUserByName, type User } from "../src/core/users.ts";
import { promote } from "./helpers/members.ts";
import { tokenFor } from "./helpers/tokens.ts";
import { resolveOid } from "../src/git/merge.ts";
import { repoDir } from "../src/git/repos.ts";
import { noteGuardPassed, providerForOrigin } from "../src/origins/credential.ts";
import { ensureFork, pushToFork } from "../src/origins/fork-route.ts";
import { settled } from "../src/origins/jobs.ts";
import { carryBranchThrough } from "../src/origins/push-through.ts";
import { fastFirstFetch, quietLogs, withoutEnv } from "./helpers/globals.ts";
import { proveAll } from "./helpers/verified.ts";
import {
  newFakeState,
  serveFakeForge,
  type FakeForge,
  type FakeState,
} from "./fake-origin.ts";
quietLogs();
fastFirstFetch();
withoutEnv("FORGE_ORIGIN_CLIENT_ID", "FORGE_ORIGIN_DENY_PUSH", "FORGE_URL");
const ME = "me";
const UP = "octo";
const PASSWORD = "propose-via-fork-pass";
const basic = (user: string, secret: string): string =>
  `Basic ${Buffer.from(`${user}:${secret}`).toString("base64")}`;
describe("proposing through the account's own fork", () => {
  let upDir: string;
  let upApp: App;
  let up: Servers;
  let dir: string;
  let app: App;
  let servers: Servers;
  let fake: FakeForge;
  let state: FakeState;
  let token = "";
  let alice: User;
  let origin: Origin;
  const upstream = (path: string, as: string, body?: unknown): Promise<Response> =>
    fetch(`${up.url}${path}`, {
      method: body === undefined ? "GET" : "POST",
      headers: { "content-type": "application/json", authorization: basic(as, PASSWORD) },
      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
    });
  /**
   * An ordinary, proven account on a forge, and a full token for it. Made
   * directly: sign-ups make no admin and are limited per address, and the
   * API mints `admin` tokens for admins only (`test/helpers/tokens.ts`).
   * Not an admin on purpose: the git host must refuse `me` a push to a
   * repository `me` only reads.
   */
  async function account(app: App, username: string): Promise<string> {
    const made = await createUser(app.db, {
      username,
      email: `${username}@p.dev`,
      password: PASSWORD,
      origin: "seed",
      trusted: true,
    });
    if (!made.ok) throw new Error(`no account ${username}: ${made.error}`);
    // A member, as an owner would make it: a guest owns no repository.
    promote(app.db, made.value);
    return tokenFor(app, username, "admin");
  }
  async function seed(name: string, owner = UP): Promise<void> {
    await upstream("/api/v1/repos", owner, { name, visibility: "public" });
    await upstream(`/api/v1/repos/${owner}/${name}/contents`, owner, {
      branch: "main",
      message: "first",
      files: [{ path: "a.txt", content: "one\n" }],
    });
  }
  const git = (owner: string, name: string) => `${up.url}/${owner}/${name}.git`;
  /** Where a branch stands on the upstream forge's own copy of a repository. */
  const tipUp = (owner: string, name: string, branch: string) =>
    resolveOid(repoDir(upApp.reposRoot, owner, name), `refs/heads/${branch}`);
  const asked = (method: string, suffix: string) =>
    state.requests.filter((r) => r.method === method && r.path.endsWith(suffix));
  const lastPullHead = (fullName: string): string =>
    String(
      (JSON.parse(asked("POST", `/repos/${fullName}/pulls`).at(-1)?.body ?? "{}") as {
        head?: string;
      }).head,
    );
  /**
   * The workbench: the origin repo mirrored, forked here, one branch
   * committed. The mirror and the fork are made once and found after, so
   * each test stands alone in any order.
   */
  async function workbench(
    fullName: string,
    branch: string,
  ): Promise<{ mirror: Repo; fork: Repo }> {
    const name = fullName.split("/")[1]!;
    let mirrorId = mirrorOf(app.db, origin.id, fullName);
    if (mirrorId === undefined) {
      const job = startMirrorJob(app, alice, origin.id, fullName, `${name}-mirror`);
      if (!job.ok) throw new Error("mirror refused");
      mirrorId = (await settled(job.value.id))!.repo!.id;
    }
    const mirror = getRepoById(app.db, mirrorId)!;
    let fork = getForkOf(app.db, alice.id, mirror.id);
    if (fork === undefined) {
      const made = await forkRepo(app, alice, mirror, `${name}-work`);
      if (!made.ok) throw new Error(`fork: ${made.error}`);
      fork = made.value;
    }
    const edited = await editFiles(app, alice, fork, {
      newBranch: branch,
      files: [{ path: `${branch}.txt`, content: `${branch}\n` }],
    });
    if (!edited.ok) throw new Error("edit failed");
    return { mirror, fork };
  }
  async function withEnv<T>(name: string, value: string, fn: () => Promise<T>): Promise<T> {
    const before = process.env[name];
    process.env[name] = value;
    try {
      return await fn();
    } finally {
      if (before === undefined) delete process.env[name];
      else process.env[name] = before;
    }
  }
  beforeAll(async () => {
    upDir = await mkdtemp(join(tmpdir(), "forge-pvf-up-"));
    upApp = createApp({ dataDir: upDir, port: 0 });
    up = await serve(upApp);
    await account(upApp, UP);
    token = await account(upApp, ME);
    proveAll(upApp);
    for (const name of ["gears", "widgets", "pushy"]) await seed(name);
    await seed("own", ME);
    // `me` really forks the upstreams it will propose to, so the fork's clone
    // URL is a repository that exists and that `me` may push to.
    for (const name of ["gears", "widgets", "pushy"]) {
      const forked = await upstream(`/api/v1/repos/${UP}/${name}/forks`, ME, {});
      expect(forked.status).toBe(201);
    }
    state = newFakeState("forgejo", ME, token);
    state.repos.push(
      // Read only: the premise.
      { id: 1, fullName: `${UP}/gears`, cloneUrl: git(UP, "gears"), push: false, admin: false },
      { id: 2, fullName: `${UP}/widgets`, cloneUrl: git(UP, "widgets"), push: false, admin: false },
      // The API says yes, git says no: a stale or wrong answer.
      { id: 3, fullName: `${UP}/pushy`, cloneUrl: git(UP, "pushy"), push: true, admin: false },
      { id: 4, fullName: `${ME}/own`, cloneUrl: git(ME, "own"), push: true, admin: true },
      // A name `me` already uses for something that is not a fork.
      { id: 5, fullName: `${UP}/thing`, cloneUrl: git(UP, "gears"), push: false },
      { id: 6, fullName: `${ME}/thing`, cloneUrl: git(ME, "own"), push: true },
      // A fork the account renamed: neither name this forge would guess.
      { id: 7, fullName: `${UP}/renamed`, cloneUrl: git(UP, "gears"), push: false },
      {
        id: 8,
        fullName: `${ME}/a-name-of-its-own`,
        cloneUrl: git(ME, "own"),
        fork: true,
        parent: `${UP}/renamed`,
        push: true,
      },
    );
    fake = serveFakeForge(state);
    dir = await mkdtemp(join(tmpdir(), "forge-pvf-"));
    app = createApp({ dataDir: dir, port: 0 });
    servers = await serve(app);
    await account(app, "alice");
    proveAll(app);
    alice = getUserByName(app.db, "alice")!;
    const connected = await connectOrigin(app, alice, { host: fake.url, token });
    if (!connected.ok) throw new Error("connect failed");
    origin = getOriginFor(app.db, alice.id, connected.value.id)!;
  });
  afterAll(async () => {
    fake.stop();
    servers.stop();
    up.stop();
    app.close();
    upApp.close();
    await rm(dir, { recursive: true, force: true });
    await rm(upDir, { recursive: true, force: true });
  });
  test("a read-only account proposes through its own fork, and the pull's head is <owner>:<branch>", async () => {
    const { mirror, fork } = await workbench(`${UP}/gears`, "topic");
    const pull = await openPull(app, alice, mirror, {
      title: "A change from a reader",
      baseBranch: "main",
      headBranch: "topic",
      headRepo: fork,
    });
    expect(pull.ok).toBe(true);
    expect(asked("POST", `/repos/${UP}/gears/forks`).length).toBeLessThanOrEqual(1);
    expect(lastPullHead(`${UP}/gears`)).toBe(`${ME}:topic`);
    // The branch is in the account's fork, and nowhere near the upstream.
    const tip = await resolveOid(repoDir(app.reposRoot, fork.ownerName, fork.name), "refs/heads/topic");
    expect(await tipUp(ME, "gears", "topic")).toBe(tip!);
    expect(await tipUp(UP, "gears", "topic")).toBeUndefined();
  });
  test("the fork is reused, not made twice", async () => {
    for (const branch of ["second", "third"]) {
      const { mirror, fork } = await workbench(`${UP}/gears`, branch);
      const pull = await openPull(app, alice, mirror, {
        title: `Proposal ${branch}`,
        baseBranch: "main",
        headBranch: branch,
        headRepo: fork,
      });
      expect(pull.ok).toBe(true);
      expect(lastPullHead(`${UP}/gears`)).toBe(`${ME}:${branch}`);
      // However many proposals, one fork was ever asked for.
      expect(asked("POST", `/repos/${UP}/gears/forks`)).toHaveLength(1);
    }
  });
  test("a fork's own default branch goes up under its owner's name, and the page says how", async () => {
    // gears: read-only in every test, so the picker's cache never says
    // otherwise (the protected-repository test lends widgets push rights).
    const { fork } = await workbench(`${UP}/gears`, "unused");
    const landed = await editFiles(app, alice, fork, {
      files: [{ path: "main.txt", content: "on main\n" }],
    });
    expect(landed.ok).toBe(true);
    const page = await (
      await fetch(`${servers.url}/${fork.ownerName}/${fork.name}`, {
        headers: { authorization: basic("alice", PASSWORD) },
      })
    ).text();
    expect(page).toContain("Propose via your fork");
    const proposed = await proposeUpstream(app, alice, fork);
    expect(proposed.ok).toBe(true);
    expect(lastPullHead(`${UP}/gears`)).toBe(`${ME}:alice/main`);
    expect(await tipUp(ME, "gears", "alice/main")).toBeDefined();
    expect(await tipUp(UP, "gears", "alice/main")).toBeUndefined();
  });
  test("an account that can push still pushes directly: no fork", async () => {
    const { mirror, fork } = await workbench(`${ME}/own`, "direct");
    const pull = await openPull(app, alice, mirror, {
      title: "Straight in",
      baseBranch: "main",
      headBranch: "direct",
      headRepo: fork,
    });
    expect(pull.ok).toBe(true);
    expect(asked("POST", `/repos/${ME}/own/forks`)).toHaveLength(0);
    expect(lastPullHead(`${ME}/own`)).toBe("direct");
    expect(await tipUp(ME, "own", "direct")).toBeDefined();
  });
  test("a push the origin refuses falls back to the fork", async () => {
    const { mirror, fork } = await workbench(`${UP}/pushy`, "fallback");
    const pull = await openPull(app, alice, mirror, {
      title: "Said yes, meant no",
      baseBranch: "main",
      headBranch: "fallback",
      headRepo: fork,
    });
    expect(pull.ok).toBe(true);
    expect(await tipUp(UP, "pushy", "fallback")).toBeUndefined();
    expect(asked("POST", `/repos/${UP}/pushy/forks`)).toHaveLength(1);
    expect(lastPullHead(`${UP}/pushy`)).toBe(`${ME}:fallback`);
  });
  test("a protected repository is never pushed to, even by an account that could: always the fork", async () => {
    await withEnv("FORGE_ORIGIN_DENY_PUSH", `${UP}/widgets`, async () => {
      // Checked when it connected; the account gained push rights since.
      noteGuardPassed(app, origin.id);
      state.repos.find((r) => r.fullName === `${UP}/widgets`)!.push = true;
      const { mirror, fork } = await workbench(`${UP}/widgets`, "guarded");
      const forksBefore = asked("POST", `/repos/${UP}/widgets/forks`).length;
      // The direct ways in are refused before anything moves.
      const carried = await carryBranchThrough(app, mirror, fork, "guarded", alice.id);
      expect(!carried.ok && carried.error.message).toContain("protected by this forge's operator");
      const pushed = await originPush(app, alice, mirror);
      expect(!pushed.ok && pushed.error).toBe("origin_protected");
      const pull = await openPull(app, alice, mirror, {
        title: "To a protected repository",
        baseBranch: "main",
        headBranch: "guarded",
        headRepo: fork,
      });
      expect(pull.ok).toBe(true);
      expect(lastPullHead(`${UP}/widgets`)).toBe(`${ME}:guarded`);
      expect(await tipUp(UP, "widgets", "guarded")).toBeUndefined();
      expect(asked("POST", `/repos/${UP}/widgets/forks`).length).toBeLessThanOrEqual(forksBefore + 1);
      // contribute takes its fork path there too.
      const made = await contribute(app, alice, {
        originId: origin.id,
        fullName: `${UP}/widgets`,
        branch: "contributed",
        files: [{ path: "c.txt", content: "c\n" }],
        openPull: { title: "Contributed" },
      });
      expect(made.ok && made.value.via).toBe("fork");
      expect(lastPullHead(`${UP}/widgets`)).toBe(`${ME}:contributed`);
      expect(await tipUp(UP, "widgets", "contributed")).toBeUndefined();
      state.repos.find((r) => r.fullName === `${UP}/widgets`)!.push = false;
    });
  });
  test("a name the account already uses: the fork takes a second name, then is found again", async () => {
    const provider = providerForOrigin(app, origin);
    if (!provider.ok) throw new Error("no provider");
    const first = await ensureFork(app, origin, provider.value, `${UP}/thing`);
    expect(first.ok && first.value.remote.fullName).toBe(`${ME}/${UP}-thing`);
    expect(first.ok && first.value.existed).toBe(false);
    const posts = asked("POST", `/repos/${UP}/thing/forks`).length;
    const again = await ensureFork(app, origin, provider.value, `${UP}/thing`);
    expect(again.ok && again.value.existed).toBe(true);
    expect(asked("POST", `/repos/${UP}/thing/forks`)).toHaveLength(posts);
  });
  test("a fork under a name of its own is found through the upstream's forks, not made again", async () => {
    const provider = providerForOrigin(app, origin);
    if (!provider.ok) throw new Error("no provider");
    const found = await ensureFork(app, origin, provider.value, `${UP}/renamed`);
    expect(found.ok && found.value.existed).toBe(true);
    expect(found.ok && found.value.remote.fullName).toBe(`${ME}/a-name-of-its-own`);
    expect(asked("GET", `/repos/${UP}/renamed/forks`).length).toBeGreaterThan(0);
    expect(asked("POST", `/repos/${UP}/renamed/forks`)).toHaveLength(0);
  });
  test("pushing into the fork asks for itself whether writes are paused", async () => {
    const provider = providerForOrigin(app, origin);
    if (!provider.ok) throw new Error("no provider");
    const fork = await ensureFork(app, origin, provider.value, `${UP}/gears`);
    if (!fork.ok) throw new Error("no fork");
    const { fork: local } = await workbench(`${UP}/gears`, "paused");
    await withEnv("FORGE_ORIGIN_DENY_PUSH", "nobody/nothing", async () => {
      // Guarded now, and never checked: writes wait for a check.
      clearCursor(app.db, origin.id, "guard_checked_at");
      const pushed = await pushToFork(
        app,
        getOriginFor(app.db, alice.id, origin.id)!,
        provider.value,
        fork.value.remote,
        repoDir(app.reposRoot, local.ownerName, local.name),
        "paused",
        "paused",
      );
      expect(!pushed.ok && pushed.error).toContain("writes through it are paused");
    });
    expect(await tipUp(ME, "gears", "paused")).toBeUndefined();
  });
  test("the guard is unchanged: an account that can push to a protected repository is refused", async () => {
    await account(app, "bob");
    proveAll(app);
    const bob = getUserByName(app.db, "bob")!;
    state.repos.find((r) => r.fullName === `${UP}/widgets`)!.push = true;
    const refused = await withEnv("FORGE_ORIGIN_DENY_PUSH", `${UP}/widgets`, () =>
      connectOrigin(app, bob, { host: fake.url, token }),
    );
    state.repos.find((r) => r.fullName === `${UP}/widgets`)!.push = false;
    expect(refused.ok).toBe(false);
    if (!refused.ok && typeof refused.error !== "string")
      expect(refused.error.error).toBe("can_push");
  });
});
@@ -686,6 +686,28 @@
describe("failingFiles", () => {
    expect(failingFiles(report)).toEqual(["test/b.test.ts", "test/c.test.ts"]);
  });
  test("an Actions job's report: the group marker is not part of the path", () => {
    // bun under GITHUB_ACTIONS=true (Forgejo's runner sets it too), as a
    // runner logged it: read as a path, `::group::test/b.test.ts` was run
    // again alone, could not be found, and nothing was ever cleared.
    const report = [
      "bun test v1.3.14 (0d9b296a)",
      "",
      "::group::test/a.test.ts:",
      "(pass) fine",
      "",
      "::endgroup::",
      "",
      "::group::test/b.test.ts:",
      "error: expect(received).toBeUndefined()",
      "::error file=test/b.test.ts,line=6,col=68,title=error: expect(received).toBeUndefined()::Received: true",
      "(fail) victim [0.09ms]",
      "",
      "::endgroup::",
    ].join("\n");
    expect(failingFiles(report)).toEqual(["test/b.test.ts"]);
  });
  test("a report that names no failing test names no file", () => {
    expect(failingFiles("test/a.test.ts:\nerror: cannot load\n")).toEqual([]);
    expect(failingFiles("(fail) before any header")).toEqual([]);
@@ -130,7 +130,7 @@
beforeAll(async () => {
  fake = serveFakeForge(state);
  forgetProviders(dir);
  const connected = await connectOrigin(app, alice, { host: fake.url, token: secret });
  if (!connected.ok) throw new Error(connected.error);
  if (!connected.ok) throw new Error(JSON.stringify(connected.error));
  const agent = await createAgent(app, alice, { username: "porter", model: "", brief: "Moves things in." });
  if (!agent.ok) throw new Error(String(agent.error));
@@ -289,7 +289,7 @@
describe("migrate from the terminal", () => {
    try {
      for (const [host, token] of [[fake.url, secretToken], [down.url, "tok-ghost"]] as const) {
        const connected = await connectOrigin(app, erin.value, { host, token });
        if (!connected.ok) throw new Error(connected.error);
        if (!connected.ok) throw new Error(JSON.stringify(connected.error));
      }
      down.state.rateLimitFor = 1000;
      await withTui(erin.value, async ({ tui, terminal }) => {
@@ -0,0 +1,84 @@
/** The operator guard in the terminal: a paused origin says so, with its reason, and `v` checks it again. */
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 { createApp, type App as Forge } from "../src/app.ts";
import { CHECK_WORDS } from "../src/actions/origin_words.ts";
import { createOrigin, getOriginFor } from "../src/core/origins.ts";
import { lastGuardTry } from "../src/origins/credential.ts";
import { createUser, getUserByName } from "../src/core/users.ts";
import { createForgeApp } from "../src/tui/forge.ts";
import type { TuiIdentity } from "../src/tui/session.ts";
import { headlessTerminal } from "../src/tui/term/terminal.ts";
import { quietLogs } from "./helpers/globals.ts";
import { settleApp } from "./helpers/tui.ts";
quietLogs();
describe("a paused origin in the terminal", () => {
  let dataDir: string;
  let forge: Forge;
  let before: string | undefined;
  let userId = "";
  let originId = "";
  beforeAll(async () => {
    before = process.env.FORGE_ORIGIN_DENY_PUSH;
    process.env.FORGE_ORIGIN_DENY_PUSH = "system/*";
    dataDir = await mkdtemp(join(tmpdir(), "forge-tui-guard-"));
    forge = createApp({ dataDir, port: 0 });
    const made = await createUser(forge.db, {
      origin: "seed",
      trusted: true,
      username: "dana",
      email: "[email protected]",
      password: "a-good-passphrase",
      adminIfFirst: true,
    });
    if (!made.ok) throw new Error(made.error);
    userId = made.value.id;
    const o = createOrigin(forge.db, dataDir, {
      userId: made.value.id,
      kind: "gitea",
      apiUrl: "http://127.0.0.1:9/api/v1",
      webUrl: "http://127.0.0.1:9",
      login: "dana",
      token: "t0ken-not-shown",
    });
    if (!o.ok) throw new Error(o.error);
    originId = o.value.id;
  });
  afterAll(async () => {
    if (before === undefined) delete process.env.FORGE_ORIGIN_DENY_PUSH;
    else process.env.FORGE_ORIGIN_DENY_PUSH = before;
    forge.close();
    await rm(dataDir, { recursive: true, force: true });
  });
  test("the list shows writes paused and its reason; v checks again and says what it found", async () => {
    const terminal = headlessTerminal(160, 32);
    const identity = { sshUsername: "t", remoteAddress: "127.0.0.1", user: getUserByName(forge.db, "dana")! } as TuiIdentity;
    const { app } = createForgeApp(forge, identity, { terminal, exitHooks: false });
    app.start();
    const key = async (k: string, ctrl = false) => {
      app.dispatch({ type: "key", key: k, ctrl, alt: false, shift: false });
      await settleApp(app);
    };
    try {
      await key("k", true);
      for (const ch of "Connected origins") await key(ch);
      await key("enter");
      expect(app.screen.toText()).toContain("writes paused");
      expect(app.screen.toText()).toContain("Press v to check again");
      await key("v");
      for (let i = 0; i < 40 && getOriginFor(forge.db, userId, originId) !== undefined && lastGuardTry(forge, originId) === undefined; i++)
        await Bun.sleep(100);
      await key("k");
      expect(app.screen.toText()).toContain(CHECK_WORDS.unchecked.slice(0, 30));
    } finally {
      app.stop();
    }
  }, 20_000);
});
		@@ -13,7 +13,8 @@ routers learn it is going, so a roll refuses nobody (`docs/ops/ROLL.md`).
13	13	Connecting origins
14	14	adds `FORGE_URL` (the canonical public base URL, needed for OAuth callbacks),
15	15	`FORGE_GITHUB_CLIENT_ID` / `FORGE_GITHUB_CLIENT_SECRET`, and
16		`FORGE_ORIGIN_ALLOW` (hosts an operator vouches for on a LAN). Behind a
	16	`FORGE_ORIGIN_ALLOW` (hosts an operator vouches for on a LAN, for discovery
	17	and for that origin's git). Behind a
17	18	platform edge that signs people in for every app it serves, `FORGE_EDGE_TOKEN`
18	19	is the edge's secret: a request carrying it and `X-Plat-User` is that person,
19	20	signed in by the platform if an account of that name exists. An unknown login
		@@ -70,7 +70,7 @@ them is correct.
70	70
71	71	## Connecting and mirroring, as a person does it
72	72
73		Outbound git refuses a host that resolves to a private address. A site admin can vouch for exact host names (the owner's own Forgejo, reached by its in-cluster address): `FORGE_OUTBOUND_TRUSTED_HOSTS=git.example.test` (comma or space separated), plus the same list editable by an admin on Settings → Origins. A trusted host may resolve privately for origin sync, mirror, migrate and write-through; trust is by name, never by address range, and webhooks never read it. The origin row says "trusted internal host". In the terminal, the palette's Trusted hosts reads and saves the same list (admins only, same audit). An entry that is not a bare host name (an address, a wildcard, a URL) is refused with its name, on the page and in the terminal, never silently dropped.
	73	Outbound git refuses a host that resolves to a private address. A site admin can vouch for exact host names (the owner's own Forgejo, reached by its in-cluster address): `FORGE_OUTBOUND_TRUSTED_HOSTS=git.example.test` (comma or space separated), plus the same list editable by an admin on Settings → Origins. A trusted host may resolve privately for origin sync, mirror, migrate and write-through; trust is by name, never by address range, and webhooks never read it. A host name in `FORGE_ORIGIN_ALLOW` is trusted the same way for its origin's mirror, sync and fetch, so an origin that connects can be mirrored; an address named there is not (trust is by name). The origin row says "trusted internal host". In the terminal, the palette's Trusted hosts reads and saves the same list (admins only, same audit). An entry that is not a bare host name (an address, a wildcard, a URL) is refused with its name, on the page and in the terminal, never silently dropped.
74	74
75	75	A pull from an outsider's fork on the origin is someone else's code, so its
76	76	check and preview wait. A person with write access lets that exact head run:
		@@ -198,6 +198,15 @@ and it is never written to a log. Both surfaces render the link as a QR code
198	198	also offers OSC 52 copy, which reaches the user's own terminal rather than the
199	199	server's clipboard.
200	200
	201	The flow's own page (`/settings/origins/flows/:id`) links to that sealed
	202	URL and to nothing else — never to one from its query string — after
	203	checking it again: the instance's `/login/oauth/authorize`, the flow's
	204	client id and callback, a PKCE challenge. A `to` an older link still
	205	carries must equal it exactly. A flow past its ten minutes says "This
	206	connect link expired", with a fresh Connect.
	207	(`test/origin-flow-page.test.ts`; `test/oauth-connect-browser.test.ts`
	208	clicks Authorize and Continue in headless Chromium.)
	209
201	210	Discovery: `github.com` is known by name. Otherwise `GET /api/v1/version` —
202	211	NodeInfo is the one thing here resembling a standard and no live Forgejo
203	212	serves it, so it is only an opportunistic first probe. The version string is
		@@ -211,7 +220,11 @@ resolves the name and refuses any private answer (`vetHost`, at every hop,
211	220	dialling the address it judged), refuses non-http schemes, follows no redirect
212	221	off-host, reaches loopback only in dev (`FORGE_DEV=1`), caps the body at 64 KB and times out in 5 s. An operator can vouch for a LAN
213	222	or plaintext host with `FORGE_ORIGIN_ALLOW=host[,host…]`; there is no
214		per-user toggle, because the risk it accepts belongs to the server.
	223	per-user toggle, because the risk it accepts belongs to the server. A host
	224	name vouched for there is trusted for that origin's git as well (mirror,
	225	sync, fetch, push), as `FORGE_OUTBOUND_TRUSTED_HOSTS` is: by name, pinned to
	226	the answer that passed. So an origin that connects can be mirrored. An
	227	address literal named there reaches discovery only: trust is by name.
215	228
216	229	Refresh. A Forgejo OAuth access token lives about an hour, so it is
217	230	refreshed a minute before it expires rather than after a 401. Refreshes are
		@@ -403,13 +416,38 @@ the mirror: each sync that moves the mirror's default branch fast-forwards
403	416	the fork's, so long as nothing was committed on it directly (`docs/APPS.md`,
404	417	"Forks follow their parents").
405	418
406		The `owner:branch` form is verified against the fakes in
407		`test/fork-flow.test.ts` (both dialects, with real git behind them) and it
408		matches both forges' documented shape. **It has not yet been run against a
409		live Forgejo instance**, and that is the one thing worth doing before
410		leaning on it: Forgejo's `head` is an undocumented plain string, and a real
411		instance is the only thing that can settle whether it resolves the owner the
412		way GitHub does.
	419	Reading is enough to propose. Carrying the branch into the origin
	420	repository needs push rights there. An account that can only read it — and
	421	anyone at all, for a repository the operator protects
	422	(`FORGE_ORIGIN_DENY_PUSH`) — proposes through its own fork at the origin
	423	instead (`src/origins/fork-route.ts`): the fork it has is found (the
	424	picker's cache, then its two possible names, then the upstream's own list
	425	of forks for one the account owns under any name, `GET
	426	/repos/{o}/{r}/forks`, bounded) or made (`POST
	427	/repos/{o}/{r}/forks`, under `<owner>-<name>` when the account already uses
	428	the name for something else); the branch is pushed into that fork, leased on
	429	where it stands there; and the pull opens on the origin repository with the
	430	head `<account>:<branch>`. Which way is asked of the origin when the pull
	431	is opened (`permissions.push`), and a direct push the origin refuses falls
	432	back to the fork. A protected repository is never pushed to from here at
	433	all — push-through, a carried branch and a branch made on its mirror are
	434	refused (`origin_protected`) — because a branch pushed into a repository
	435	runs its workflows with its Actions secrets, and a pull from a fork runs
	436	them without (Forgejo `services/actions/secret.go:43`). The same fork is
	437	what `contribute` uses on its fork path (`ensureFork`), and a fork of a
	438	mirror whose origin it will reach through a fork says so on its button:
	439	Propose via your fork. `test/propose-via-fork.test.ts` runs it against
	440	a real forge serving git behind the fake API.
	441
	442	The `owner:branch` head form is Forgejo's (v15, `routers/api/v1/repo/
	443	pull.go`): `parseCompareInfo` splits the head on its colon (:1092), looks
	444	the owner up (:1098) and takes that owner's fork of the base as the head
	445	repository (`GetForkedRepo`, :1127), whatever the fork is named; the base
	446	needs read access to code and pulls (:1162), the head read access to code
	447	(:1175-1181). Verified live on Forgejo 15.0.9 on 2026-10-16: a read-only
	448	account opened two pulls on a private scratch repository through its fork,
	449	one from a branch and one from the fork's default branch (`<account>/main`),
	450	and the scratch repository never gained a branch.
413	451
414	452	Review states. A review is a _verdict_ on a pull at one commit —
415	453	`approved`, `changes_requested` or `commented` — stored in `review` beside
		@@ -446,6 +484,99 @@ local client (`src/cli/`) reads them over the API, clones under
446	484	`~/src/<host>/<owner>/<repo>`, keeps them fetched, and reports
447	485	ahead/behind/dirty. The server never knows local state.
448	486
	487	## A token that lacks a scope
	488
	489	Forgejo answers a token without a scope with a 403 that names it (`token
	490	does not have at least one of required scope(s): [read:user]`). The API
	491	client reads that body (4 KB at most) and keeps only scope-shaped words, so
	492	connecting says "This token is missing User: Read." (`missing_scopes`, 422)
	493	and a sync error says "the token is missing Issue: Read" — not "the token
	494	was refused", which a person cannot tell from a wrong or expired one. The
	495	token form lists what a Forgejo token needs and, once the instance is
	496	known, links to
	497	`<host>/user/settings/applications/tokens/new?name=forge&resource=all&scope=read:user&scope=write:repository&scope=write:issue`,
	498	which Forgejo 15 opens with those already chosen; on Gitea or an older
	499	Forgejo the list says what to pick. `test/origin-token-scopes.test.ts`.
	500
	501	## The operator guard
	502
	503	A forge keeps an origin's credential on a machine where agents run, so the
	504	risk is the account a person authorized — never the owner of this forge. On
	505	a guarded host — one the operator registered an application for
	506	(`FORGE_ORIGIN_CLIENT_ID`), or one a push rule covers
	507	(`FORGE_ORIGIN_DENY_PUSH`) — every credential is checked after `whoami` and
	508	before anything is stored, on all three ways in (a pasted token, the code
	509	flow, the device flow). Both variables are read per call.
	510
	511	- An account that administers the instance (Forgejo's `is_admin`,
	512	GitHub's `site_admin`) is refused: "`<login>` is an administrator of
	513	`<host>`. Sign in to Forgejo with your everyday non-admin account and try
	514	again." (`admin_account`)
	515	- An account that can push to a protected repository is refused, with
	516	the repositories named (`can_push`). The check asks the origin for
	517	`permissions.push` — the account's real rights, whatever scopes its token
	518	claims. Every pattern with no `*` is asked about by name (`GET
	519	/repos/{o}/{r}`, four at a time, however many there are). A wildcard
	520	walks the repositories the account can see (`walkRepos`): on Forgejo
	521	`/repos/search?uid=` sorted by id — every repository it owns,
	522	collaborates on or reaches through a team, every way to push — so a
	523	repository pushed or made during the walk cannot move into a page already
	524	read; with no fallback to another listing; and complete only when the
	525	distinct repositories seen equal `X-Total-Count`, which must not change
	526	between pages. On GitHub, `/user/repos` oldest first. The walk is bounded
	527	(20 pages); an account with more, a page that fails, or a count that does
	528	not add up is refused (`guard_unchecked`) — the guard fails closed. A
	529	confirmed hit always wins: an account seen to push to a protected
	530	repository is refused for that (`can_push`), even when another lookup
	531	failed or the walk did not finish.
	532	- A refusal stores nothing. On the code flow the grant is revoked where the
	533	provider allows it (GitHub with a client secret); Forgejo has no
	534	revocation endpoint, so the message says the forge did not keep the token
	535	and where to remove the grant.
	536
	537	`FORGE_ORIGIN_DENY_PUSH` patterns: `owner/name`, `*` for any run of
	538	characters inside one part, a bare `owner` meaning `owner/*`, case-
	539	insensitive. A bare pattern covers every origin (so it also turns the
	540	administrator check on for every origin); `host:pattern` covers one host.
	541	Unguarded hosts behave exactly as before, so a person who runs their own
	542	Forgejo can still connect it as its administrator.
	543
	544	The walk is also the person's list of repositories: on a guarded host it is
	545	written to the picker's cache at connect, for free.
	546
	547	Checked again, after it is stored (`src/origins/credential.ts`). A
	548	grant outlives the rights it was given with, so the guard runs again on
	549	what is already stored:
	550
	551	- On every OAuth refresh, on the new token, before it is used: the
	552	request that needed the refresh fails if the account is refused.
	553	- By a sweep on the sync tick: an origin on a guarded host that was never
	554	checked (connected before the guard, or before the operator named its
	555	host) at once — so on boot — and every other once a day. One origin per
	556	tick, half a second between its requests, so the sweep adds a trickle to
	557	the origin it protects. A connect that passed the guard counts as a check.
	558	- A refusal marks the origin `needs_reauth` with the guard's sentence as
	559	its reason. From that moment every use of the credential fails — sync,
	560	write-through, push-through (no git credential is handed out), the crew's
	561	pulls through it — and Settings → Origins says to re-authorize, with the
	562	reason. A credential the origin no longer accepts (a grant revoked there)
	563	is refused at once. A refresh never clears `needs_reauth` — one racing a
	564	refusal cannot undo it; only connecting again, through the guard, does.
	565	- Writes wait on a check. On a guarded host an origin whose account has
	566	not passed the guard — never checked yet, or a check that cannot run (the
	567	origin down, a count that moved) — reads and syncs but writes nothing:
	568	write-through (`origin_paused`), push-through, branches carried up, forks
	569	and pulls made there, and, in the adapter itself, any request that is not
	570	a read (`ProviderCredential.writable`). Settings → Origins says
	571	"Couldn't verify this connection; writes paused" with Check again
	572	(`POST /settings/origins/:id/check`, once a minute per origin). A failing
	573	check is tried again in 15 minutes; one that has not run for a day refuses
	574	the origin.
	575	- When each origin last passed lives in its cursor store (`guard_checked_at`
	576	and friends): a cache — lose it, and the origin is checked once more.
	577
	578	`test/origin-guard.test.ts`.
	579
449	580	## When a token expires
450	581
451	582	A credential dies: a token is revoked, a refresh token is spent, an OAuth
		@@ -885,10 +1016,6 @@ carries token material, a `state`, or a `code`.
885	1016	it wants a spawn path of its own, and "fetching git objects" was worth more
886	1017	than that today.
887	1018	- No LFS. A mirror of an LFS repo has the pointers, not the objects.
888		- The `owner:branch` head form is unverified against a live Forgejo. It
889		is exercised against the fake in both dialects and matches the documented
890		shape; Forgejo's own `head` is an undocumented plain string. Try it against
891		a real instance before relying on it in anger.
892	1019	- Contributing needs a workbench. `contribute` mirrors your fork (and, on
893	1020	the push-rights path, the upstream) if it is not mirrored already, so the
894	1021	first contribution to a large repository pays for a clone and an import.
		@@ -896,6 +1023,9 @@ carries token material, a `state`, or a `code`.
896	1023	review through the origin sends the state and the body; anchored comments
897	1024	are still posted one at a time. Both forges accept comments inside the
898	1025	review payload, which is the obvious next step.
	1026	- The guard's window is a day. An account that gains push rights to a
	1027	protected repository keeps its credential until the next refresh or the
	1028	next daily sweep, whichever is first.
899	1029	- Key rotation is not built. The sealed blob carries a `v1` version tag
900	1030	so it can be, but losing `secret.key` today means reconnecting the origins.
901	1031	- DNS rebinding is not closed. The SSRF policy checks address _literals_;
		@@ -0,0 +1,8 @@
	1	# The operator guard and proposing through your fork (#8938)
	2
	3	The operator may name hosts to guard (`FORGE_ORIGIN_CLIENT_ID`, `FORGE_ORIGIN_DENY_PUSH`; see "The operator guard" in [`docs/ORIGINS.md`](../ORIGINS.md)). On such a host an origin is refused when its account administers the instance or can push to a protected repository.
	4
	5	- Paused: when the guard cannot verify an account (the host is down, say), the origin still reads and syncs but writes nothing. `/settings/origins` shows "Couldn't verify this connection; writes paused" with a Check again button (`POST /settings/origins/:id/check`, once a minute per origin). A refused origin shows Needs re-auth.
	6	- In the terminal: Connected origins marks a paused origin `writes paused`, says why on the top line, and `v` checks it again, saying what it found in the page's words (`CHECK_WORDS`, `src/actions/origin_words.ts`). Test: `test/tui-origins-guard.test.ts`.
	7	- Try it: set `FORGE_ORIGIN_DENY_PUSH=system/*` and connect a token that can push there on Settings → Origins; it is refused with the repository named.
	8	- Propose via your fork: an account that can only read a repository, or any repository the operator protects, proposes through the account's own fork there (`src/origins/fork-route.ts`, `contribute` in `src/actions/contribute.ts`). Test: `test/propose-via-fork.test.ts`; the guard: `test/origin-guard.test.ts`.
		@@ -545,14 +545,18 @@ export function besideOthers(
545	545	return { red: stillRed, besideOthers: cleared, line };
546	546	}
547	547
548		const HEADER = /^(\S+\.test\.[cm]?[jt]sx?):$/;
	548	// Under GitHub-style Actions (GITHUB_ACTIONS=true, which Forgejo's runner
	549	// sets too) bun opens each file's tests with `::group::path:` instead of
	550	// `path:`; the group marker is not part of the path.
	551	const HEADER = /^(?:::group::)?(\S+\.test\.[cm]?[jt]sx?):$/;
549	552	const FAILED = /^\(fail\) /;
550	553
551	554	/**
552	555	* The files whose tests failed in one `bun test` report, in the order the
553		* report reached them: bun prints `path:` before a file's tests and
554		* `(fail) name` for each one that failed. A report that names no failing
555		* test (a crash, a file that would not load) yields none.
	556	* report reached them: bun prints `path:` (in an Actions job,
	557	* `::group::path:`) before a file's tests and `(fail) name` for each one
	558	* that failed. A report that names no failing test (a crash, a file that
	559	* would not load) yields none.
556	560	*/
557	561	export function failingFiles(output: string): string[] {
558	562	const found: string[] = [];
		@@ -30,7 +30,8 @@ import {
30	30	import { resolveOid } from "../git/merge.ts";
31	31	import { repoDir } from "../git/repos.ts";
32	32	import { err, ok, type Result } from "../kernel/result.ts";
33		import { providerForOrigin } from "../origins/credential.ts";
	33	import { providerForOrigin, writesPaused } from "../origins/credential.ts";
	34	import { denied } from "../origins/operator.ts";
34	35	import { redact, secretsIn } from "../origins/credentials.ts";
35	36	import { pushToOrigin, type PushUpdate } from "../origins/git-mirror.ts";
36	37	import type { WriteThroughError } from "../origins/write-through.ts";
		@@ -179,6 +180,9 @@ export async function originPush(
179	180	if (!link) return ok(undefined);
180	181	if (link.origin.userId !== actor.id) return err("origin_owner_only");
181	182	if (link.cloneUrl === "") return err("origin_unreachable");
	183	if (writesPaused(app, link.origin.id) !== undefined)
	184	return err("origin_paused");
	185	if (denied(link.origin, link.fullName)) return err("origin_protected");
182	186
183	187	const provider = providerForOrigin(app, link.origin);
184	188	if (!provider.ok) return err("origin_unreachable");
		@@ -35,7 +35,6 @@
35	35	import { requireVerified } from "./verify.ts";
36	36	import type { App } from "../app.ts";
37	37	import {
38		findOriginFork,
39	38	getOriginFor,
40	39	getOriginRepo,
41	40	mirrorOf,
		@@ -50,43 +49,32 @@ import { isSafeRef } from "../git/guard.ts";
50	49	import { repoDir } from "../git/repos.ts";
51	50	import type { CommitResult } from "../git/write.ts";
52	51	import { err, ok, type Result } from "../kernel/result.ts";
53		import { providerForOrigin } from "../origins/credential.ts";
	52	import { providerForOrigin, writesPaused } from "../origins/credential.ts";
54	53	import { fetchRefFrom } from "../origins/git-mirror.ts";
55	54	import { importIssue } from "../origins/import.ts";
56	55	import { settled, type MirrorJob } from "../origins/jobs.ts";
57	56	import { mirrorRepo, startMirror } from "../origins/mirror.ts";
	57	import { ensureFork, forkDeadline } from "../origins/fork-route.ts";
		sentinelcrew 11d ago Re-export sits between imports; move it below them.
	58
	59	import { denied } from "../origins/operator.ts";
58	60	import type { Provider, RemoteRepo } from "../origins/types.ts";
59	61	import type { WriteThroughError } from "../origins/write-through.ts";
60	62	import { createBranch } from "./branches.ts";
61	63	import { editFiles, type EditFile, type EditFilesError } from "./contents.ts";
62	64	import { requireUser } from "./access.ts";
63	65
	66	export { forkDeadline };
	67
64	68	// ---- forking at the origin ----
65	69
66		/**
67		* How long to wait for a fork to exist. GitHub's docs say most forks are
68		* ready "within five minutes" and are in practice ready in one or two
69		* seconds; thirty is long enough for the common case and short enough that a
70		* request does not hang on the pathological one.
71		*/
72		const FORK_DEADLINE_MS = 30_000;
73
74		/**
75		* The deadline `forkOrigin` uses when its caller names none. Mutable for the
76		* same reason `firstFetchRetry` is: a test that wants the timeout shortens it
77		* and puts back what it found.
78		*/
79		export const forkDeadline: { ms: number } = { ms: FORK_DEADLINE_MS };
80
81		/** Backoff between polls, in ms; the last value repeats until the deadline. */
82		const FORK_BACKOFF = [250, 500, 1_000, 2_000, 3_000] as const;
83
84	70	export type ForkOriginError =
85	71	\| "unauthorized"
86	72	\| "unverified"
87	73	\| "not_found"
88	74	\| "origin_unreachable"
89	75	\| "origin_refused"
	76	/** The connection is not verified against the operator's rules yet. */
	77	\| "origin_paused"
90	78	/** The origin took the request and the fork never appeared in time. */
91	79	\| "fork_timeout";
92	80
		@@ -135,6 +123,7 @@ export async function forkOrigin(
135	123	// Somebody else's connected account does not exist for you (invariant 9).
136	124	const origin = getOriginFor(app.db, user.value.id, originId);
137	125	if (!origin) return err("not_found");
	126	if (writesPaused(app, origin.id) !== undefined) return err("origin_paused");
138	127	const provider = providerForOrigin(app, origin);
139	128	if (!provider.ok) return err("origin_unreachable");
140	129
		@@ -144,62 +133,15 @@ export async function forkOrigin(
144	133	upstream.error.error === "not_found" ? "not_found" : "origin_unreachable",
145	134	);
146	135
147		const found = await existingFork(
	136	const forked = await ensureFork(
148	137	app,
149	138	origin,
150	139	provider.value,
151	140	upstream.value.fullName,
	141	options.waitMs ?? forkDeadline.ms,
152	142	);
153		let existed = found !== undefined;
154		let remote = found;
155
156		if (remote === undefined) {
157		const asked = await provider.value.forkRepo(upstream.value.fullName);
158		if (!asked.ok) {
159		// An origin that forks in the request itself can take longer than we
160		// wait for an answer, and still have done it. Before calling that a
161		// failure, look for the fork under its conventional name.
162		const name = upstream.value.fullName.split("/")[1] ?? "";
163		const late =
164		asked.error.error === "unreachable" &&
165		name !== "" &&
166		origin.login !== ""
167		? await awaitFork(
168		provider.value,
169		`${origin.login}/${name}`,
170		options.waitMs ?? forkDeadline.ms,
171		)
172		: undefined;
173		if (
174		late === undefined \|\|
175		!late.ok \|\|
176		!sameRepo(late.value.parent, upstream.value.fullName)
177		)
178		return err(
179		asked.error.error === "unreachable" \|\|
180		asked.error.error === "rate_limited"
181		? "origin_unreachable"
182		: "origin_refused",
183		);
184		remote = late.value;
185		} else {
186		const ready = await awaitFork(
187		provider.value,
188		asked.value.fullName,
189		options.waitMs ?? forkDeadline.ms,
190		);
191		if (!ready.ok) return ready;
192		remote = ready.value;
193		}
194		existed = false;
195		}
196
197		rememberOriginRepo(app.db, origin.id, {
198		...remote,
199		// Both forges report the parent on `getRepo`; if this one did not, we
200		// know it anyway, because we are the reason the fork exists.
201		parent: remote.parent ?? upstream.value.fullName,
202		});
	143	if (!forked.ok) return forked;
	144	const { remote, existed } = forked.value;
203	145
204	146	app.bus.append({
205	147	kind: "repo.forked",
		@@ -251,58 +193,6 @@ export async function forkOrigin(
251	193	return ok({ remote, mirror, job, existed });
252	194	}
253	195
254		/**
255		* The fork of `upstream` this account already has, if any. The cache is
256		* asked first (it is the picker's own answer and costs nothing); failing
257		* that, the conventional name is asked for directly, because a fork made
258		* outside this forge is not in the cache and forking again would be wrong.
259		*/
260		async function existingFork(
261		app: App,
262		origin: Origin,
263		provider: Provider,
264		upstream: string,
265		): Promise<RemoteRepo \| undefined> {
266		const cached = findOriginFork(app.db, origin.id, upstream);
267		if (cached !== undefined) {
268		const fresh = await provider.getRepo(cached.fullName);
269		if (fresh.ok && sameRepo(fresh.value.parent, upstream)) return fresh.value;
270		}
271		const name = upstream.split("/")[1] ?? "";
272		if (name === "" \|\| origin.login === "") return undefined;
273		const guess = await provider.getRepo(`${origin.login}/${name}`);
274		if (guess.ok && sameRepo(guess.value.parent, upstream)) return guess.value;
275		return undefined;
276		}
277
278		const sameRepo = (a: string \| null, b: string): boolean =>
279		a !== null && a.toLowerCase() === b.toLowerCase();
280
281		/** Poll until the origin admits the fork exists, or the deadline passes. */
282		async function awaitFork(
283		provider: Provider,
284		fullName: string,
285		waitMs: number,
286		): Promise<Result<RemoteRepo, ForkOriginError>> {
287		const deadline = Date.now() + waitMs;
288		for (let attempt = 0; ; attempt++) {
289		const found = await provider.getRepo(fullName);
290		// An empty fork is still a fork; what we are waiting for is the row.
291		if (found.ok) return ok(found.value);
292		if (found.error.error !== "not_found")
293		return err(
294		found.error.error === "unreachable" \|\|
295		found.error.error === "rate_limited"
296		? "origin_unreachable"
297		: "origin_refused",
298		);
299		const wait =
300		FORK_BACKOFF[Math.min(attempt, FORK_BACKOFF.length - 1)] ?? 3_000;
301		if (Date.now() + wait > deadline) return err("fork_timeout");
302		await new Promise((resolve) => setTimeout(resolve, wait));
303		}
304		}
305
306	196	/** The local mirror of a remote repo at this origin, or undefined. */
307	197	function localMirror(
308	198	app: App,
		@@ -381,6 +271,7 @@ export async function contribute(
381	271	if (!proven.ok) return proven;
382	272	const origin = getOriginFor(app.db, user.value.id, input.originId);
383	273	if (!origin) return err("not_found");
	274	if (writesPaused(app, origin.id) !== undefined) return err("origin_paused");
384	275	const branch = input.branch.trim();
385	276	if (!isSafeRef(branch) \|\| branch.startsWith("refs/"))
386	277	return err("invalid_branch");
		@@ -404,7 +295,11 @@ export async function contribute(
404	295	if (!listed.value.some((b) => b.name === base)) return err("unknown_base");
405	296	}
406	297
407		return upstream.value.permissions.push
	298	// Push rights decide the shape — except on a repository the operator
	299	// protects, which is never pushed to from here: always the fork.
	300	const direct =
	301	upstream.value.permissions.push && !denied(origin, upstream.value.fullName);
	302	return direct
408	303	? await contributeDirect(app, user.value, origin, upstream.value, {
409	304	...input,
410	305	branch,
		@@ -30,3 +30,12 @@ export function connectWords(error: string): string {
30	30	};
31	31	return words[error] ?? "That connection could not be made.";
32	32	}
	33
	34	/** What "Check again" found, in one sentence, on the page and in the terminal. */
	35	export const CHECK_TOO_SOON = "It was checked a moment ago. Try again in a minute.";
	36	export const CHECK_WORDS = {
	37	passed: "Verified. Writes through this connection are on again.",
	38	unguarded: "This connection has nothing to verify.",
	39	unchecked: "It still could not be verified, so writes stay paused. Try again in a few minutes.",
	40	refused: "This connection was refused. Reconnect it with an account the operator allows.",
	41	} as const;
		@@ -28,6 +28,7 @@ import {
28	28	findOrigin,
29	29	getOriginById,
30	30	getOriginFor,
	31	hostOf,
31	32	siteOf,
32	33	linkRepoToOrigin,
33	34	listDetachedMirrors,
		@@ -55,7 +56,13 @@ import type { User } from "../core/users.ts";
55	56	import { repoDir } from "../git/repos.ts";
56	57	import { bustOrigin } from "../view/cache.ts";
57	58	import { discover } from "../origins/discover.ts";
58		import { providerForOrigin } from "../origins/credential.ts";
	59	import {
	60	lastGuardTry,
	61	noteGuardPassed,
	62	providerForOrigin,
	63	recheckOrigin,
	64	type Recheck,
	65	} from "../origins/credential.ts";
59	66	import { safeRemoteUrl } from "../origins/credentials.ts";
60	67	import { configureMirror, mirrorRemoteUrl } from "../origins/git-mirror.ts";
61	68	import { getJob, type MirrorJob } from "../origins/jobs.ts";
		@@ -85,8 +92,10 @@ import {
85	92	type AppRow,
86	93	type FlowRow,
87	94	} from "../origins/oauth.ts";
	95	import { checkCredential, type GuardRefusal } from "../origins/operator.ts";
88	96	import { forgetProvider, providerFor } from "../origins/providers/index.ts";
89	97	import { forgetTokenReach } from "../origins/token-reach.ts";
	98	import { scopeWords } from "../origins/providers/http.ts";
90	99	import {
91	100	requestSyncNow,
92	101	syncOrigin,
		@@ -96,6 +105,7 @@ import { open } from "../kernel/secret.ts";
96	105	import {
97	106	staticCredential,
98	107	type OriginKind,
	108	type RemoteRepo,
99	109	} from "../origins/types.ts";
100	110	import { err, ok, type Result } from "../kernel/result.ts";
101	111	import {
		@@ -158,13 +168,16 @@ export interface ConnectInput {
158	168	* Connect with a pasted token — the fallback path, and the only one that
159	169	* works with no OAuth application registered anywhere. The token is
160	170	* validated against the origin before it is stored, and `login` comes from
161		* the origin's answer rather than anything the user typed.
	171	* the origin's answer rather than anything the user typed. On a host the
	172	* operator guards, the account behind it is checked too (`checkCredential`)
	173	* and a refusal stores nothing: it comes back as a `GuardRefusal`, with the
	174	* sentence to show.
162	175	*/
163	176	export async function connectOrigin(
164	177	app: App,
165	178	actor: User \| undefined,
166	179	input: ConnectInput,
167		): Promise<Result<Connected, ConnectError>> {
	180	): Promise<Result<Connected, ConnectError \| GuardRefusal \| ScopeRefusal>> {
168	181	const user = requireUser(actor);
169	182	if (!user.ok) return user;
170	183	if (tooManyAttempts(app, user.value.id)) return err("rate_limited");
		@@ -177,7 +190,7 @@ export async function connectOrigin(
177	190	);
178	191	if (!found.ok) return err(found.error);
179	192
180		const identity = await providerFor(
	193	const provider = providerFor(
181	194	staticCredential({
182	195	kind: found.value.kind,
183	196	apiUrl: found.value.apiUrl,
		@@ -185,11 +198,24 @@ export async function connectOrigin(
185	198	software: softwareOf(found.value.software),
186	199	token: input.token.trim(),
187	200	}),
188		).whoami();
189		if (!identity.ok)
	201	);
	202	const identity = await provider.whoami();
	203	if (!identity.ok) {
	204	// A token the origin knows but finds too narrow is not a bad token: say
	205	// which scope it lacks, in the words of the page that makes tokens.
	206	const missing = identity.error.missingScopes ?? [];
	207	if (missing.length > 0)
	208	return err({
	209	error: "missing_scopes",
	210	message: `This token is missing ${scopeWords(missing)}. ${TOKEN_NEEDS}`,
	211	scopes: missing,
	212	});
190	213	return err(
191	214	identity.error.error === "unreachable" ? "unreachable" : "bad_token",
192	215	);
	216	}
	217	const guard = await checkCredential(provider, identity.value);
	218	if (!guard.ok) return err(guard.error);
193	219
194	220	const stored = storeOrigin(app, user.value, {
195	221	kind: found.value.kind,
		@@ -201,9 +227,15 @@ export async function connectOrigin(
201	227	software: softwareOf(found.value.software),
202	228	});
203	229	if (!stored.ok) return stored;
	230	if (guard.value.checked) noteGuardPassed(app, stored.value.id);
204	231	return ok({
205	232	...stored.value,
206		reattached: await afterConnect(app, user.value, stored.value),
	233	reattached: await afterConnect(
	234	app,
	235	user.value,
	236	stored.value,
	237	guard.value.listed,
	238	),
207	239	});
208	240	}
209	241
		@@ -216,7 +248,8 @@ export type ReplaceTokenError =
216	248	\| "rate_limited"
217	249	\| "bad_token"
218	250	\| "unreachable"
219		\| "other_account";
	251	\| "other_account"
	252	\| GuardRefusal["error"];
220	253
221	254	/**
222	255	* Put a new pasted token on an origin that is already connected — one that
		@@ -239,7 +272,7 @@ export async function replaceOriginToken(
239	272	const secret = token.trim();
240	273	if (secret === "") return err("bad_token");
241	274
242		const identity = await providerFor(
	275	const provider = providerFor(
243	276	staticCredential({
244	277	kind: origin.kind,
245	278	apiUrl: origin.apiUrl,
		@@ -247,13 +280,18 @@ export async function replaceOriginToken(
247	280	software: origin.software,
248	281	token: secret,
249	282	}),
250		).whoami();
	283	);
	284	const identity = await provider.whoami();
251	285	if (!identity.ok)
252	286	return err(
253	287	identity.error.error === "unreachable" ? "unreachable" : "bad_token",
254	288	);
255	289	if (identity.value.login.toLowerCase() !== origin.login.toLowerCase())
256	290	return err("other_account");
	291	// A new token is a new credential: on a guarded host it passes the same
	292	// check a connect does, and a refusal leaves the old token as it was.
	293	const guard = await checkCredential(provider, identity.value);
	294	if (!guard.ok) return err(guard.error.error);
257	295
258	296	renewOrigin(app.db, app.config.dataDir, origin.id, {
259	297	token: secret,
		@@ -261,6 +299,7 @@ export async function replaceOriginToken(
261	299	});
262	300	forgetProvider({ dataDir: app.config.dataDir, originId: origin.id });
263	301	forgetTokenReach(app.config.dataDir, origin.id);
	302	if (guard.value.checked) noteGuardPassed(app, origin.id);
264	303	app.bus.append({
265	304	kind: "origin.connected",
266	305	actorId: user.value.id,
		@@ -277,6 +316,27 @@ export async function replaceOriginToken(
277	316	return ok(renewed);
278	317	}
279	318
	319	/** What a token for a Forgejo origin needs, in the token page's words. */
	320	export const TOKEN_NEEDS =
	321	"A token for this forge needs User: Read, Repository: Read and write, and Issue: Read and write.";
	322
	323	/** A token the origin refused for a scope it lacks: which, by name. */
	324	export interface ScopeRefusal {
	325	readonly error: "missing_scopes";
	326	readonly message: string;
	327	/** In the origin's words: `read:user`. */
	328	readonly scopes: readonly string[];
	329	}
	330
	331	/** A refused connect as a stable code and the words to show for it. */
	332	export function connectRefusal(
	333	error: ConnectError \| GuardRefusal \| ScopeRefusal,
	334	): { code: string; message: string \| undefined } {
	335	return typeof error === "string"
	336	? { code: error, message: undefined }
	337	: { code: error.error, message: error.message };
	338	}
	339
280	340	/** A connected origin, and the frozen mirrors connecting it brought back. */
281	341	export type Connected = Origin & {
282	342	readonly reattached: readonly Reattachment[];
		@@ -406,6 +466,34 @@ export function listUserOrigins(app: App, actor: User): Origin[] {
406	466	return listOrigins(app.db, actor.id);
407	467	}
408	468
	469	// ---- checking again ----
	470
	471	/** How soon a person may ask for another check of the same origin. */
	472	const CHECK_AGAIN_MS = 60_000;
	473
	474	/**
	475	* "Check again": the operator guard on one of the actor's origins, now
	476	* (`recheckOrigin`). The way out of paused writes without waiting for the
	477	* sweep — and, like it, refused outright when the account fails the guard.
	478	* Once a minute per origin at most: it is a walk of the origin's API.
	479	*/
	480	export async function checkOriginAgain(
	481	app: App,
	482	actor: User \| undefined,
	483	originId: string,
	484	): Promise<Result<Recheck, "unauthorized" \| "not_found" \| "too_soon">> {
	485	const user = requireUser(actor);
	486	if (!user.ok) return user;
	487	const origin = getOriginFor(app.db, user.value.id, originId);
	488	if (!origin) return err("not_found");
	489	const last = lastGuardTry(app, origin.id);
	490	if (last !== undefined && Date.now() - Date.parse(last) < CHECK_AGAIN_MS)
	491	return err("too_soon");
	492	const provider = providerForOrigin(app, origin);
	493	if (!provider.ok) return ok("refused");
	494	return ok(await recheckOrigin(app, origin, provider.value, { pauseMs: 250 }));
	495	}
	496
409	497	// ---- OAuth ----
410	498
411	499	export type OAuthStartError =
		@@ -726,7 +814,7 @@ async function completeConnect(
726	814	expiresAt: string \| null;
727	815	},
728	816	): Promise<{ status: "done" \| "failed"; detail: string; originId?: string }> {
729		const identity = await providerFor(
	817	const provider = providerFor(
730	818	staticCredential({
731	819	kind: registration.kind,
732	820	apiUrl: registration.apiUrl,
		@@ -735,9 +823,31 @@ async function completeConnect(
735	823	software: registration.software ?? "",
736	824	token: tokens.accessToken,
737	825	}),
738		).whoami();
	826	);
	827	const identity = await provider.whoami();
739	828	if (!identity.ok)
740		return { status: "failed", detail: "the new token did not work" };
	829	return {
	830	status: "failed",
	831	detail:
	832	(identity.error.missingScopes ?? []).length > 0
	833	? `The grant is missing ${scopeWords(identity.error.missingScopes!)}. The application asks for it; remove the grant on the instance and connect again.`
	834	: "the new token did not work",
	835	};
	836	// The account that consented is the one checked: an administrator's grant
	837	// or a protected repository's pusher is refused here, before anything is
	838	// stored, and the grant is revoked where the provider lets us.
	839	const guard = await checkCredential(provider, identity.value);
	840	if (!guard.ok) {
	841	const revoked = await revokeGrant(registration, tokens.accessToken);
	842	return {
	843	status: "failed",
	844	detail: `${guard.error.message} ${
	845	revoked.ok
	846	? "The grant was revoked."
	847	: `This forge did not keep the token. You can remove the grant at ${hostOf(registration.webUrl)} under Settings → Applications.`
	848	}`,
	849	};
	850	}
741	851
742	852	const stored = storeOrigin(app, user, {
743	853	kind: registration.kind,
		@@ -752,7 +862,8 @@ async function completeConnect(
752	862	});
753	863	if (!stored.ok)
754	864	return { status: "failed", detail: ORIGIN_ALREADY_CONNECTED };
755		await afterConnect(app, user, stored.value);
	865	if (guard.value.checked) noteGuardPassed(app, stored.value.id);
	866	await afterConnect(app, user, stored.value, guard.value.listed);
756	867	return { status: "done", detail: "", originId: stored.value.id };
757	868	}
758	869
		@@ -991,7 +1102,12 @@ async function afterConnect(
991	1102	app: App,
992	1103	user: User,
993	1104	origin: Origin,
	1105	listed: readonly RemoteRepo[] \| null = null,
994	1106	): Promise<Reattachment[]> {
	1107	// The guard listed what the account can see: that is the picker's list,
	1108	// at once — no second walk of the same pages. Anywhere the guard did not
	1109	// walk, the picker fetches it when it is opened, as before.
	1110	if (listed !== null) cacheOriginRepos(app.db, origin.id, listed);
995	1111	const out: Reattachment[] = [];
996	1112	for (const mirror of listDetachedMirrors(app.db, {
997	1113	site: siteOf(origin.webUrl),
		@@ -81,9 +81,34 @@ import {
81	81	} from "./access.ts";
82	82	import { canWrite } from "../core/repos.ts";
83	83	import { refreshPullHead as refreshHead } from "../core/following.ts";
	84	import { getOriginRepo } from "../core/origins.ts";
84	85	import { watchPullsSoon } from "../origins/hook.ts";
85		import { carryBranchThrough } from "../origins/push-through.ts";
86	86	import { ownHost, pullSourceOf, sourceTrailers } from "../core/trusted_sources.ts";
	87	import { carryBranchThrough } from "../origins/push-through.ts";
	88	import { ensureFork, forkHead, pushToFork } from "../origins/fork-route.ts";
	89	import { denied } from "../origins/operator.ts";
	90	import type { WriteThrough } from "../origins/write-through.ts";
	91
	92	/**
	93	* How a fork of a mirror proposes to the mirror's origin: `direct`, its
	94	* branch pushed into the origin repository, when the account may push
	95	* there; `fork`, through the account's own fork at the origin, when it may
	96	* only read — and always for a repository the operator protects
	97	* (`FORGE_ORIGIN_DENY_PUSH`), which this forge never pushes to. The rights
	98	* are the origin's own answer, asked now; when it cannot be asked, the
	99	* cached one, and failing that the direct way, whose refusal falls back to
	100	* the fork.
	101	*/
	102	async function proposalRoute(
	103	app: App,
	104	through: WriteThrough,
	105	): Promise<"direct" \| "fork"> {
	106	if (denied(through.origin, through.fullName)) return "fork";
	107	const live = await through.provider.getRepo(through.fullName);
	108	if (live.ok) return live.value.permissions.push ? "direct" : "fork";
	109	const cached = getOriginRepo(app.db, through.origin.id, through.fullName);
	110	return cached?.canPush === false ? "fork" : "direct";
	111	}
87	112
88	113	export interface OpenPullInput {
89	114	title: string;
		@@ -135,10 +160,13 @@ export async function openPull(
135	160	if (title === "") return err("empty_title");
136	161	// A native fork of this mirror proposing upstream: its branch is
137	162	// carried to the origin first, under the connecting account's
138		// credential like any push through, and the origin opens the pull
139		// from the branch it now holds.
	163	// credential, and the origin opens the pull from it. Directly into the
	164	// origin repository when the account can push there; otherwise — and
	165	// always for a repository the operator protects — into the account's
	166	// own fork at the origin, the pull's head then `<owner>:<branch>`.
140	167	const head = input.headRepo;
141	168	let carriedAs = input.headBranch;
	169	let pullHead = input.headBranch;
142	170	if (head !== undefined && head.id !== baseRepo.id) {
143	171	if (
144	172	!canRead(app.db, head, user.value) \|\|
		@@ -152,15 +180,50 @@ export async function openPull(
152	180	// name.
153	181	if (input.headBranch === input.baseBranch)
154	182	carriedAs = `${head.ownerName}/${input.headBranch}`;
155		const carried = await carryBranchThrough(
156		app,
157		baseRepo,
158		head,
159		input.headBranch,
160		user.value.id,
161		carriedAs,
162		);
163		if (!carried.ok) return err(refusal(carried.error.message));
	183	pullHead = carriedAs;
	184	const route = await proposalRoute(app, through.value);
	185	let viaFork = route === "fork";
	186	if (route === "direct") {
	187	const carried = await carryBranchThrough(
	188	app,
	189	baseRepo,
	190	head,
	191	input.headBranch,
	192	user.value.id,
	193	carriedAs,
	194	);
	195	// The origin said no to the push itself: the account cannot write
	196	// there after all. Reading is enough to propose, from a fork.
	197	if (!carried.ok && carried.error.byOrigin !== true)
	198	return err(refusal(carried.error.message));
	199	viaFork = !carried.ok;
	200	}
	201	if (viaFork) {
	202	const forked = await ensureFork(
	203	app,
	204	through.value.origin,
	205	through.value.provider,
	206	through.value.fullName,
	207	);
	208	if (!forked.ok)
	209	return err(
	210	forked.error === "origin_unreachable" \|\|
	211	forked.error === "fork_timeout"
	212	? "origin_unreachable"
	213	: "origin_refused",
	214	);
	215	const pushed = await pushToFork(
	216	app,
	217	through.value.origin,
	218	through.value.provider,
	219	forked.value.remote,
	220	repoDir(app.reposRoot, head.ownerName, head.name),
	221	input.headBranch,
	222	carriedAs,
	223	);
	224	if (!pushed.ok) return err("origin_refused");
	225	pullHead = forkHead(forked.value.remote, carriedAs);
	226	}
164	227	}
165	228	const created = await through.value.provider.createPull(
166	229	through.value.fullName,
		@@ -168,7 +231,7 @@ export async function openPull(
168	231	title,
169	232	body: input.body ?? "",
170	233	base: input.baseBranch,
171		head: carriedAs,
	234	head: pullHead,
172	235	},
173	236	);
174	237	if (!created.ok) return err(refusal(created.error.error));
		@@ -219,10 +219,14 @@ export function storeRefreshed(
219	219	originId: string,
220	220	next: { token: string; refresh?: string; expiresAt?: string \| null },
221	221	): void {
	222	// A refresh never clears `needs_reauth`: one that races a refusal (the
	223	// operator guard's sweep, a dead grant) must not undo it. Only connecting
	224	// again — `renewOrigin`, after the guard passed — brings an origin back.
222	225	db.query(
223	226	`UPDATE origin SET token_enc = ?1,
224	227	refresh_token_enc = CASE WHEN ?2 = '' THEN refresh_token_enc ELSE ?2 END,
225		expires_at = ?3, needs_reauth = 0, last_error = ''
	228	expires_at = ?3,
	229	last_error = CASE WHEN needs_reauth = 1 THEN last_error ELSE '' END
226	230	WHERE id = ?4`,
227	231	).run(
228	232	seal(dataDir, next.token, originId),