Compare commits

..

16 Commits

Author SHA1 Message Date
diegosouzapw
b470798f23 docs(ci): AGENTS.md says how a PR lands on a release branch and how a sync-back lands
The sync-back section prescribed a direct push that the default branch has refused since
the ruleset Require PR on default branch: a sync-back lands through a pull request merged
with a merge commit, which scripts/release/sync-next-cycle.mjs opens since #20645.

New section Landing on a release branch: omni-queue. In shadow mode a manual merge waits
for the queue's verdict on the PR's final head (green checks prove a PR against the base
they ran on: #19132); in live mode the label is the landing.
2026-11-21 02:54:24 -03:00
Diego Rodrigues de Sa e Souza
1771948e1a feat(ci): omni-queue owner voice and signed merge commits (both off) (#20792)
* feat(ci): omni-queue owner voice and signed merge commits, both off

Owner voice (config `voice`, default "app"): with "owner", the queue's
comments and label removals on pull requests, the dashboard issue and its
comments, base-red comments and the tree-divergence issue go out with
OMNI_QUEUE_LAND_TOKEN (scripts/merge-queue/voice.mjs). Reads, commit
statuses, refs, the state branch and re-runs stay the App's. A missing
token or a 401/403 retries the same write with the App's token and records
one error event per tick. commentOnce trusts markers by the App or by the
owner's login read from the token itself (GET /user).

Signed merge commits (config landing.signing, default "none"): with "ssh"
and landing.actor "owner", composeCandidate signs every merge commit with
the key the tick job writes from the OMNI_QUEUE_SIGNING_KEY secret to a
0600 file under RUNNER_TEMP (removed by an always() step). git gets the
path as per-command configuration through the environment. A missing key
or a failed signature composes unsigned and records one error event per
batch.

The shipped config keeps both off and mode shadow.

* docs(changelog): add the fragment for the omni-queue owner voice and signed merges (#20792)

* test(ci): compare the signed commit's committer by prefix, not a built regex (#20792)
2026-11-21 02:39:36 -03:00
Diego Rodrigues de Sa e Souza
59e3965a8a test(ci): audit only git-tracked files for retired provider asset references (#20827)
The retired-asset audit in provider-assets-generic-fallback.test.mjs walked the
working tree at module load and read every text file whole. In the omni-queue
base check, "Fast Quality Gates" builds config/quality/test-impact-map.json
(gitignored, ~556 MB on release/v3.8.55) before running the whole unit suite,
and readFile(path, "utf8") on it threw "RangeError: Invalid string length"
(run 44795004759).

The audit now lists files with git ls-files (same scope rules; the old walk
stays as the fallback for a tree without git metadata), reads each file with a
64 MiB bound, and reports oversized or unreadable files by name instead of
aborting. A regression test builds a temporary git repository with an
untracked 600 MB sparse file in a walked directory.
2026-11-21 02:32:46 -03:00
Diego Rodrigues de Sa e Souza
76b26b8ead Merge pull request #20824 from cheaper-inference/fix/codeql-media-poll-clamp
fix(security): clamp media polling and guard syntx provider rules (CodeQL #1389, #1392)
2026-11-21 00:58:11 -03:00
Diego Rodrigues de Sa e Souza
c8688bcd69 Merge pull request #20820 from cheaper-inference/fix/admission-bypass-process-secret
fix(security): require the per-process token for the internal admission bypass
2026-11-21 00:57:59 -03:00
Diego Rodrigues de Sa e Souza
59bf5d718f Merge pull request #20819 from cheaper-inference/fix/codeql-operator-only-path-roots
fix(security): operator-only credential and denied roots for corpus and vault paths (CodeQL #1371, #1372, #1373)
2026-11-21 00:57:48 -03:00
Diego Rodrigues de Sa e Souza
78a20f38dc Merge pull request #20776 from cheaper-inference/fix/subscription-quota-400-status-gate
fix(security): gate subscription quota text on HTTP 400 behind a structured code
2026-11-21 00:57:36 -03:00
diegosouzapw
d7727a7e99 Merge remote-tracking branch 'origin/release/v3.8.55' into fix/subscription-quota-400-status-gate 2026-11-20 18:47:10 -03:00
diegosouzapw
4625936608 chore(changelog): number the media polling fragment for #20824 2026-11-20 18:32:15 -03:00
diegosouzapw
c28fec4e9f chore(changelog): name the fragment after PR #20820 2026-11-20 18:23:37 -03:00
diegosouzapw
0d56007238 fix(security): clamp media polling and guard syntx provider rules (CodeQL #1389, #1392)
Caller-supplied poll_interval_ms, timeout_ms and poll_timeout_ms on the
NanoBanana, Magnific, Black Forest Labs and RenderHour image handlers are
clamped (30 s interval, 10 min window) by a shared helper that never
shortens a default. The RenderHour poller passes the request abort signal
to sleep(). applySyntxProviderRules only runs own entries of the rules
table.
2026-11-20 18:22:31 -03:00
diegosouzapw
035b02bcd1 chore(changelog): number the fragment for #20819 2026-11-20 18:12:44 -03:00
diegosouzapw
380b6a7786 fix(security): operator-only credential and denied roots for corpus and vault paths (CodeQL #1371, #1372, #1373)
POST /api/settings/local-corpus (rootPath) and POST /api/settings/obsidian/webdav
(vaultPath) now require an operator credential (dashboard session or local CLI) through
requireOperatorCredential; API keys of any scope and access tokens get 403. The webdav
route passes alwaysRequireAuth because /api/settings/obsidian is ALWAYS_PROTECTED.

Both roots also refuse the filesystem root, the home directory itself and the system
directories /etc /usr /bin /sbin /var /proc /sys /dev /boot /root (and below), compared
after path.resolve and realpath, with a fixed 400 message. The vault keeps its DATA_DIR
overlap refusal.
2026-11-20 18:05:40 -03:00
diegosouzapw
eec0dbba04 fix(security): require the per-process token for the internal admission bypass
isInternalAdmissionBypass() accepted the bypass header together with a
bearer equal to resolveSelfLoopBearer(), which is the deployment env key
when one is configured. That key is an ordinary API key clients hold, so
it proved nothing about where a request came from.

Apply the rule from #19292: only the per-process self-hop token (held in
memory on globalThis, compared in constant time) grants the bypass and
the internal upstream-start cap. The vision bridge describe call, the
only caller that sends the bypass header, now also sends the token; it
only does so for this process's own listener.
2026-11-20 17:35:35 -03:00
diegosouzapw
667e8bf086 chore(changelog): name the fragment after #20776 2026-11-20 10:26:33 -03:00
diegosouzapw
763fa9896d fix(security): gate subscription quota text on HTTP 400 behind a structured code
Apply the #20567 status contract to the subscription/plan quota text
signals ("usage limit reached", "plan limit", weekly/session usage
limits). On a 400 such a phrase now counts only with a structured
credit/quota code or for the message-only allow-listed providers
(command-code, bai, openai-compatible-*), so a phrase repeated from the
request no longer classifies as QUOTA_EXHAUSTED or puts a shared LLM or
search connection on hold. 429, 403 and every other status are
unchanged.

The status rule is extracted from isCreditsExhaustedForStatus into
quotaTextSignalCountsForStatus and reused by the classifier, the
fallback engine and the search cooldown.
2026-11-20 10:22:56 -03:00
59 changed files with 3565 additions and 591 deletions

View File

@@ -22,7 +22,11 @@ name: omni-queue
# • Both jobs run in the `omni-queue` environment, which holds the App's credentials and the
# owner's OMNI_QUEUE_LAND_TOKEN and admits the default branch only, by its exact name: a
# workflow on a candidate branch cannot read them. The App writes omni-queue/land, the status release rulesets
# require, so its private key is the root of trust. The land token reaches the tick only.
# require, so its private key is the root of trust. The land token reaches the tick only
# (the landing with landing.actor "owner"; the comments, label removals and issues with
# config voice "owner"). The owner's merge-commit signing key (OMNI_QUEUE_SIGNING_KEY,
# config landing.signing "ssh") reaches one step of the tick, which writes it to a 0600 file
# under RUNNER_TEMP; the job's last step removes it, whatever happened.
# • action=bless (the explicit emergency exit): the tick writes omni-queue/land on ONE commit
# for a hotfix, sync-back or base repair, after checking that both the dispatcher
# (github.actor) and whoever triggered the run (github.triggering_actor, the re-runner of a
@@ -235,10 +239,35 @@ jobs:
echo "name=${login}"
echo "email=${id}+${login}@users.noreply.github.com"
} >> "$GITHUB_OUTPUT"
# config.landing.signing "ssh": the owner's SSH signing key, for the queue's merge commits
# (scripts/merge-queue/compose.mjs reads it at compose.signingKeyPath(RUNNER_TEMP) and hands
# git the path as per-command configuration, never as an argument). The key exists only in
# this step's environment and in a file only the runner user can read; it is never
# printed. Without the secret nothing is written and a tick that is asked to sign composes
# unsigned, with one `error` event per batch. This step never fails the job: a key it
# cannot write is the same case (signing never blocks the queue).
- name: Write the merge-commit signing key
env:
OMNI_QUEUE_SIGNING_KEY: ${{ secrets.OMNI_QUEUE_SIGNING_KEY }}
run: |
set -uo pipefail
if [ -z "${OMNI_QUEUE_SIGNING_KEY:-}" ]; then
echo "no merge-commit signing key in the environment: nothing written"
exit 0
fi
umask 077
if ! { mkdir -p "$RUNNER_TEMP/omni-queue-signing" \
&& chmod 700 "$RUNNER_TEMP/omni-queue-signing" \
&& printf '%s\n' "$OMNI_QUEUE_SIGNING_KEY" > "$RUNNER_TEMP/omni-queue-signing/signing-key" \
&& chmod 600 "$RUNNER_TEMP/omni-queue-signing/signing-key"; }; then
rm -rf "$RUNNER_TEMP/omni-queue-signing"
echo "::warning::the merge-commit signing key could not be written: merge commits stay unsigned"
fi
# Inputs travel through env and are assembled into an argv array: no expression is ever
# expanded inside the script body. Scheduled, workflow_run and pull_request_target ticks
# pass no base (the tick discovers the bases with work). The owner's land token is used
# only by the landing itself when config.landing.actor is "owner" (never printed).
# by the landing itself when config.landing.actor is "owner", and by the queue's comments,
# label removals and issues when config.voice is "owner" (never printed).
# GITHUB_ACTOR and GITHUB_TRIGGERING_ACTOR are the runner's own default variables, named
# here because a bless is checked against both: the original dispatcher, whose inputs a
# re-run keeps, and whoever triggered this run (the re-runner of a re-run).
@@ -265,3 +294,8 @@ jobs:
if [ -n "${INPUT_SHA:-}" ]; then args+=(--sha "$INPUT_SHA"); fi
fi
node scripts/merge-queue/tick.mjs "${args[@]}"
# Last step, whatever happened before it (failure, cancellation): the signing key leaves
# the runner. Needs no secret; nothing to remove is not an error.
- name: Remove the merge-commit signing key
if: always()
run: rm -rf "$RUNNER_TEMP/omni-queue-signing"

View File

@@ -326,12 +326,33 @@ If red: never treat or "fix" the inherited failures in your branch (a base-red f
freeze-gated `fix/release-vX.Y.Z-basereds` PR); a PR opened anyway carries
`⚠️ base-red inherited: #<issue>` in its body. Full procedure: `docs/ops/WORKTREE_ISOLATION.md`.
### Sync-back landings are fast-forward, never squash
### Landing on a release branch: omni-queue
A `main → release/vX+1` sync-back lands as the merge commit it already is
(`git push origin <head>:refs/heads/release/vX+1`), never squashed — a squash drops `main` from
the release ancestry and the next sync-back re-conflicts on every file (551 on v3.8.50 → v3.8.51).
After landing, `git merge-base --is-ancestor origin/main origin/release/vX+1` must be true.
`release/vX.Y.Z` branches are served by the project's merge queue (runbook:
[`docs/ops/OMNI_QUEUE.md`](docs/ops/OMNI_QUEUE.md)). Read its `mode` in
`config/merge-queue/config.json` on the default branch before landing anything:
- **`shadow`** — the queue tests but lands nothing; merges are manual. Green checks on a PR head
prove the PR against the base they ran on, not against today's base, so before a manual merge
apply the `omni-queue` label at the PR's final head and wait for the queue's verdict on that
head (`npm run queue -- why <PR>`, `npm run queue -- history --base <branch>`): `would-land` →
merge; `culprit-found` / `would-dequeue` → do not merge, fix first. A merge train whose full CI
is green on the current base tip, or a head that already contains the base tip, needs no
separate verdict.
- **`live`** — the `omni-queue` label is the landing. Never run a merge command or push against
the branch: its ruleset refuses both.
Apply the label only to a PR the owner authorized you to land; a PR that touches a protected path
also needs `protected-approved`, which is the owner's decision per PR. Never push to
`omni-queue-state` or `omni-queue/**`.
### Sync-back landings are merge commits, never squash
A `main → release/vX+1` sync-back lands through a pull request merged with a merge commit
(`scripts/release/sync-next-cycle.mjs` opens it; the default branch refuses a direct push), never
squashed — a squash drops `main` from the release ancestry and the next sync-back re-conflicts on
every file (551 on v3.8.50 → v3.8.51). After landing,
`git merge-base --is-ancestor origin/main origin/release/vX+1` must be true.
Steps + baseline-freeze check: `docs/ops/WORKTREE_ISOLATION.md` → "Sync-back landings".
---

View File

@@ -0,0 +1 @@
- **feat(ci):** omni-queue can speak as the owner and sign its merge commits, both off by default. With `voice: "owner"` in `config/merge-queue/config.json`, the queue's comments and label removals on pull requests, the dashboard issue and its comments, base-red comments and the tree-divergence issue go out with `OMNI_QUEUE_LAND_TOKEN`; statuses, refs, the state branch, re-runs and reads stay the App's, and a missing or refused token falls back to the App with one `error` event. With `landing.signing: "ssh"` (owner actor only), every merge commit the queue composes is signed with the owner's key from the `OMNI_QUEUE_SIGNING_KEY` environment secret, and a missing key composes unsigned with one `error` event per batch ([#20792](https://github.com/cheaper-inference/OmniRoute/pull/20792))

View File

@@ -0,0 +1 @@
- **fix(security):** an HTTP 400 counts subscription/plan quota wording ("usage limit reached", "plan limit", weekly/session usage limits) as quota exhaustion only when the structured error code is a credit/quota code or the provider documents a message-only 400 form (`command-code`, `bai`, `openai-compatible-*`), the same contract as #20567, so such a phrase echoed from the request no longer puts a shared LLM or search connection on hold

View File

@@ -0,0 +1 @@
- **fix(security):** Choosing the local corpus root (`POST /api/settings/local-corpus`) or the Obsidian WebDAV vault (`POST /api/settings/obsidian/webdav`) now needs a dashboard session or the local CLI: API keys and access tokens of any scope get 403. Both routes also refuse the filesystem root, the home directory itself and system directories (`/etc`, `/usr`, `/bin`, `/sbin`, `/var`, `/proc`, `/sys`, `/dev`, `/boot`, `/root`) with a fixed 400 (CodeQL #1371, #1372, #1373)

View File

@@ -0,0 +1 @@
- **fix(security):** The internal chat admission bypass and the internal upstream-start cap are granted only on a per-process token held in memory; the deployment env key (`OMNIROUTE_API_KEY` / `ROUTER_API_KEY`) still authenticates requests but no longer marks them as internal

View File

@@ -0,0 +1 @@
- **fix(security):** Image generation on NanoBanana, Magnific, Black Forest Labs and RenderHour caps a caller's `poll_interval_ms` at 30 s and `timeout_ms` / `poll_timeout_ms` at 10 minutes (defaults unchanged), and RenderHour stops waiting between polls when the request is aborted; SYNTX provider rules only run for names defined in the rules table, so an `ai_name` such as `constructor` or `__proto__` no longer reaches an inherited `Object.prototype` member (CodeQL #1389, #1392) ([#20824](https://github.com/cheaper-inference/OmniRoute/pull/20824))

View File

@@ -1 +0,0 @@
- **fix(security):** Compression engines bound their regex work on hostile input: the headroom GCF inline-array check and the RTK raw-output command slug run in linear time, and CCR `grep` rejects patterns with more than one unbounded quantifier and stops a scan that exceeds a 1 s time budget (CodeQL #1301, #1302, #1349)

View File

@@ -14,7 +14,8 @@
"name": "diegosouzapw",
"email": "8016841+diegosouzapw@users.noreply.github.com"
},
"statusContext": "omni-queue/land"
"statusContext": "omni-queue/land",
"signing": "none"
},
"requiredChecks": [
"Gate / CI",
@@ -51,5 +52,6 @@
"config/merge-queue/**",
".mergify.yml"
],
"mode": "shadow"
"mode": "shadow",
"voice": "app"
}

View File

@@ -153,6 +153,7 @@ commit status the release rulesets require (`scripts/merge-queue/config.mjs`):
| `actor` | `app` (the default when absent) or `owner` | `app`: the App's token pushes or merges. `owner`: the owner's token (`OMNI_QUEUE_LAND_TOKEN`) does, and the queue's merge commits carry `landing.identity`. |
| `identity` | `{name, email}`; the email ends in `@users.noreply.github.com` | Required when `actor` is `owner`, refused otherwise. |
| `statusContext` | `[A-Za-z0-9._/-]{1,100}`, starting with `omni-queue/`; default `omni-queue/land` | The commit status the release ruleset requires. It must not equal a name in `requiredChecks` or `aggregateChecks`, nor an approval context (`omni-queue/approval`, `omni-queue/protected-approval`). |
| `signing` | `none` (the default when absent) or `ssh` | `ssh`: every merge commit the queue composes is signed with the owner's SSH key (see [Signed merge commits](#signed-merge-commits-landingsigning)). Refused unless `actor` is `owner`. |
With `actor: "owner"` (the value in the shipped config):
@@ -332,6 +333,119 @@ In live mode:
The land token is fine-grained and valid for 90 days: write the date it expires next to the secret
and rotate it before then.
### Signed merge commits (`landing.signing`)
With `landing.signing: "ssh"` (shipped `none`) the queue signs every merge commit it composes:
batch candidates, bisection halves and recompositions, in shadow and in live mode
(`composeCandidate` in `scripts/merge-queue/compose.mjs`, `git commit-tree -S`). The commits carry
`landing.identity`, so `signing: "ssh"` is refused unless `landing.actor` is `owner`: GitHub
verifies a signature against the signing keys of the committer's account, and the App's bot user
has none.
**Where the key lives.** The private key is the environment secret OMNI_QUEUE_SIGNING_KEY
(environment `omni-queue`, next to the land token). Only the tick job reads it, in one step,
"Write the merge-commit signing key", which writes it to `$RUNNER_TEMP/omni-queue-signing/signing-key`
(directory `0700`, file `0600`); the job's last step, "Remove the merge-commit signing key"
(`if: always()`), deletes the directory whatever happened before it. The tick process never holds
the key: it reads the file's path (`signingKeyPath` in `scripts/merge-queue/compose.mjs`) and
hands it to git as configuration of the `commit-tree` call alone (`gpg.format=ssh`,
`user.signingkey=<path>`), through the environment (`GIT_CONFIG_COUNT`/`KEY`/`VALUE`), never as an
argument. Neither the key nor its path is written to a log line, an event, the state, a comment or
an error message. The step's script, which GitHub prints, names `$RUNNER_TEMP/omni-queue-signing/signing-key`
unexpanded.
**A missing key or a failed signature never blocks the queue.** When signing is configured and the
file is not there (no secret, a write that failed), or git cannot sign (a key that is not a valid
unencrypted SSH private key, for example), the batch is composed unsigned, exactly as without
signing, and one `error` event per batch says so: `<batchId>: <n> merge commit(s) composed
unsigned: <cause>`, where the cause is
`no signing key file in the job (is the OMNI_QUEUE_SIGNING_KEY secret set?)` or
`git could not sign a merge commit (exit <code>)` (see [Merge commits composed
unsigned](#merge-commits-composed-unsigned)). This "degrade and alert" choice keeps the queue
landing when the key breaks; an unsigned queue merge commit then lands without the Verified badge.
**What verifies a candidate does not read signatures.** `verifyComposition` and every other reader
of a candidate (`mergedPrsBetween`, `candidate-base.mjs`, `history-map.mjs`) read trees, parents
and messages (`%B`, which never contains the `gpgsig` header): a signed candidate verifies exactly
as the unsigned composition of the same inputs, and a signed commit with another tree, other
parents or other trailers is refused as before
(`tests/unit/merge-queue/integration/compose-signing.test.mjs` signs with a real ed25519 key and
checks the result with `git verify-commit`).
**The owner's setup**, once, before `signing` is set to `ssh` (GitHub's rules:
[About commit signature verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification),
[Adding a new SSH key to your GitHub account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account),
[Telling Git about your signing key](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key)):
1. Generate a dedicated key, used for nothing else, without a passphrase (the job cannot type one):
`ssh-keygen -t ed25519 -N "" -C "omni-queue merge commits" -f omni-queue-signing`.
2. On the account of `landing.identity` (Settings → SSH and GPG keys → New SSH key), add the public
key `omni-queue-signing.pub` with the key type **Signing Key**. A key added as an authentication
key does not verify commits; the same key used for both must be added twice, and this one
should be a signing key only.
3. Store the full contents of the private key file `omni-queue-signing` as the environment secret
OMNI_QUEUE_SIGNING_KEY of the environment `omni-queue` (never at repository level).
4. Delete both local files. The key exists only in the secret and, as a public key, on the account.
5. In a separate change, set `landing.signing` to `ssh`.
GitHub shows a commit as **Verified** when its signature verifies against a signing key of the
account; the committer of the queue's merge commits is `landing.identity`, the account's
`@users.noreply.github.com` address. With vigilant mode on (Settings → SSH and GPG keys → "Flag
unsigned commits as unverified"), every unsigned commit with that committer shows **Unverified**: a
batch composed unsigned (above) would land so; GitHub advises vigilant mode only to people who sign
every commit. The badge can only be proven on real GitHub: rehearse a landing in the rehearsal
repository before production turns signing on.
**Rotation.** Generate a new key (step 1), add its public key as a signing key (step 2), replace the
secret (step 3), delete the files, then remove the old public key from the account. GitHub keeps a
verification record of every commit it verified: per the first page above, "once a commit signature
is verified, it remains verified within its repository's network", "even if signing keys are
rotated, revoked". If the key leaks, remove it from the account and rotate at once.
### Who speaks (`voice`)
The top-level `voice` key (shipped `app`) chooses whose token performs the queue's writes that
people read on GitHub (`scripts/merge-queue/voice.mjs`). With `app`, every one is the App's
(`omni-queue[bot]`). With `owner`, they go out with the owner's `OMNI_QUEUE_LAND_TOKEN`, the token the
tick already holds for the landing (no second token secret), whatever `landing.actor` says. The
full list is in [What appears as the owner and what appears as the App](#what-appears-as-the-owner-and-what-appears-as-the-app).
- **Reads stay the App's.** Every read (comments, issues, pull requests, statuses) uses the App's
token; the owner's makes only the writes, plus one `GET /user` per run that reads the owner's
login from the token itself.
- **The queue still recognises its own comments.** A comment marker (the hidden key of
`commentOnce`, which makes each comment once) counts only when the comment's author is
`<appSlug>[bot]` or, with `voice: "owner"`, that login read from the token. A marker in anybody
else's comment never counts. Switching `voice` back to `app` makes the owner's earlier comments
unknown again: a comment the owner already posted may be posted once more by the App.
- **Never a lost message.** Without `OMNI_QUEUE_LAND_TOKEN`, or when GitHub answers 401 or 403 to
an owner write (or to the login read), the same write is made with the App's token at once.
Each such write is a line in the tick's decisions
(`owner voice: <write> written with the App's token (<cause>)`), and the first of the tick is an
`error` event, `owner voice unavailable, written with the App's token instead: <cause>`, not
repeated while the newest such event names the same cause (a token missing for days adds one
event, not one per tick). A refused owner write never fails the tick. Any other error (a 5xx, a
timeout) is handled as the App's own errors are: the next tick redoes the write. The failure path
of a failed tick (the stalled alert, a missing dashboard) writes the same way and logs the
fallback. See [Owner voice unavailable](#owner-voice-unavailable).
- **Shadow mode** still writes nothing on a pull request. It writes the dashboard issue, its
stalled alert and the base-red comments, so with `voice: "owner"` shadow mode uses the token
too: without it those writes fall back to the App, with the event above.
- **The approval job is the exception**: it never receives the owner's token (it runs on label
events with minimal permissions), so its "not an approver" comment stays the App's. The tick's
own `not-approver` comment for the same pull request then finds that one by its marker and posts
nothing.
- **Dashboard migration.** A tick finds the dashboard issue of a base by its exact title and the
label `omni-queue-dashboard` among the open issues (the oldest wins), never by its author, and
the queue never closes or recreates an issue by itself. An open dashboard opened by the App
stays the App's issue: with `voice: "owner"` the owner edits its body and posts its comments. To
have a dashboard opened by the owner: set `voice` to `owner`, close the old dashboard issue by
hand, then dispatch a tick for that base (`workflow_dispatch`, action `tick`, its `base`). That
tick opens a new dashboard with the configured voice. Dispatch it at once: a tick run without a
base finds a base with no labeled pull request only through its open dashboard issue
(`discoverBases` in `scripts/merge-queue/tick.mjs`), so until a tick of that base runs, a base
whose only work is a pause or stored withdrawals is not visited.
## Eligibility
A PR can enter a batch only when **all** of these hold (`scripts/merge-queue/eligibility.mjs`;
@@ -1050,40 +1164,41 @@ history holds a type the code does not know is refused, which matters for a roll
[Cut-over and rollback](#cut-over-and-rollback)). `tests/unit/merge-queue/runbook.test.mjs` fails
when this table and `EVENT_TYPES` differ.
| Event | When it happens | What the operator does |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch-started` | A candidate was composed and pushed: a new batch, a recomposition or a bisection segment. The detail names the PRs and the base, and for a root batch with `batch.adaptive` the window it was cut to (`window W`). A lane batch names its lane instead of a window (`lane hotfix` or `lane base-repair`). | Nothing. Its CI is linked from the dashboard. |
| `pr-skipped-conflict` | A PR conflicts with an earlier PR of the same batch. It is left out of this candidate and stays queued for a later batch. | Nothing. If it repeats, the author rebases the PR over the one it conflicts with. |
| `pr-dequeued` | A PR left the queue: `base-conflict` (it no longer merges into the base: label removed, comment), `already-in-base` (both labels removed, comment), or `withdrawn: <why>` before composition (label, head or approval changed). In shadow mode the first two are `would-dequeue` events instead. | For `base-conflict` the author updates the branch and an approver labels it again; the other cases need nothing. |
| `checks-green` | Every required check of the candidate (or of a base check) concluded `success`. | Nothing. The landing (or `would-land`) follows. |
| `checks-red` | A check of the candidate failed. The detail names the failing checks; on a base check it starts with `base-check red`. It ends with `; re-run refused (<status or reason>)` when the re-run of the failed jobs was refused. A batch red again after its re-run records a second one. | Nothing yet: classification follows (a re-run of the failed jobs, infra retry, base check, bisection or culprit). |
| `flaky-rerun` | A red batch or bisection segment that would be bisected, tested against the base or dequeued: its failed jobs are re-run once after its runs end (`flakyReruns`). Detail: `re-running the failed jobs of <batch> once (<jobs>) before <bisecting\|a base check\|dequeuing #n>` (five jobs at most). A green re-run's `checks-green` reads `green after re-running <jobs> (flaky)`. | Nothing. A real failure is blamed later: after the rest of the CI run and the re-run. Jobs that often turn green on the re-run are flaky tests to fix. |
| `checks-timeout` | No verdict after `checksTimeoutMinutes`, or no CI run at all after 45 minutes (`no CI run for candidate`). | For `no CI run`, check the Actions policies and the `omni-queue/**` triggers of `ci.yml` / `quality.yml` (see [Infra failure or timeout](#infra-failure-or-timeout)). |
| `land-blessed` | Live mode: the App wrote the land status (`landing.statusContext`, `success`) on the commits about to land, right before the landing. | Nothing. A `landed` event should follow; if a pause follows, the status was withdrawn. |
| `manual-bless` | An approver's `bless`: the App wrote the land status on one chosen commit. The detail names who and why. | Push or merge that commit yourself (see [Land status and manual bless](#land-status-and-manual-bless)). |
| `landed` | Live mode: the batch reached the base (the `merge-ff` push or every `squash-api` merge). | Nothing. |
| `would-land` | Shadow mode: a green batch that live mode would have landed. The detail can add `merged meanwhile by another path`, `live mode would pause: queue refs unprotected (…)` and, after the name of a check, `could not run (…): live mode would fail the tick`. | Compare with what Mergify merged. Both notes must be gone before `mode: "live"`: apply the queue-refs ruleset, or fix the check that could not run. |
| `would-dequeue` | Shadow mode: live mode would have removed this PR from the queue (label kept, no comment). The detail gives the reason code(s). | Nothing during shadow. |
| `land-rejected` | The batch was not landed: the base moved (`base moved…; recomposing`: the same PRs are recomposed on the tip), the batch changed before landing (`batch changed before landing: …`: the PRs left are recomposed), or a release-freeze holds it (`base-frozen: …; <batch> waits for the freeze to lift`, once per batch: it stays in flight, not recomposed, and lands after the freeze). | Nothing for an occasional one; frequent ones mean something else merges into the base (see [Recomposition when the base moves](#recomposition-when-the-base-moves)). |
| `bisect-split` | A red batch (or a red segment of a bisection) is split; the detail names the segment tested next. | Nothing. |
| `culprit-found` | Bisection or a batch of one isolated the PR that fails. Live: label removed, comment. Shadow, or a head that moved: label kept. | The author fixes the PR and an approver labels it again. |
| `base-check-started` | A red batch on a base with no verdict: the bare base is pushed as a `basecheck-<sha12>` candidate. | Nothing. |
| `base-red-paused` | The base check is red with the same failures as the batch: the base is paused with reason `base-red`. | Fix the base (see [Base-red](#base-red)). The pause lifts when the tip moves. |
| `hang-suspected` | A job hit its time limit on every run of the candidate: treated as a hanging test (base check, then bisection) instead of an infra pause. | Nothing yet; look at the culprit comment when one is named. |
| `infra-retry` | Every failure is infrastructure (or the checks timed out): the same SHA is retried under a new ref (`-r1`, `-r2`, …), while retries of `infraRetries` are left. The detail reads `retry <n>/<infraRetries>: …`. | Nothing. |
| `infra-paused` | An infrastructure failure (or a timeout) with no retry of `infraRetries` left: the base is paused with reason `infra`. With the shipped `infraRetries: 1` that is the second failure; with `0`, the first. When every run only hit a job time limit, the outcome is `hang-suspected` instead (see its row). A base repair under a `base-red` pause is dropped instead, with an `error` event, and the `base-red` pause stays. | Check the Actions status and the candidate's run, then `npm run queue -- resume <base>`. |
| `paused` | A manual pause (`npm run queue -- pause`, or `action=pause`). The detail is the reason, on one line, cut at 200 characters. | `npm run queue -- resume <base>` when ready. |
| `resumed` | A manual resume (`manual resume (was <reason>)`, followed by `; the pause it cleared named commits kept nowhere (both lists full), check their <landing.statusContext> by hand: <sha> (<batchId>), …` when that pause named such commits), a `base-red` pause lifted because the base tip moved (`base moved <sha12> → <sha12> after a base-red pause`), or, in live mode, a `base-red` pause lifted because a PR of the base-repair lane landed (`base repaired by #<n>`). Neither automatic lift happens while `landWithdrawalsOverflow` holds entries: a tick replaces such a `base-red` pause with the full-list pause. | For a detail that names commits kept nowhere: check their land status by hand (see [Paused: landWithdrawals is full](#paused-landwithdrawals-is-full)). Otherwise nothing. |
| `tree-divergence` | `squash-api` only: the base tree after the merges differs from the candidate tree, or an open divergence issue stops a landing. The base is paused with reason `tree-divergence`. | Compare the trees, fix the base, close the issue, resume (see [Tree divergence](#tree-divergence-squash-api-only)). |
| `error` | A tick failed (the detail is its error message); a landing pause (reason `error`: land token, landing refused, composition mismatch, queue refs, base not found, attempts limit); a land-status withdrawal GitHub refused (`<batchId>: could not withdraw …`); a stored withdrawal refused for a day (`… has been refused for more than 24 h, since …; the queue keeps retrying it`); a refused withdrawal that found the `landWithdrawals` list (20) full, kept in `landWithdrawalsOverflow` (`landWithdrawals is full …`; it pauses a base that is not paused, or replaces a `base-red` pause, also one a tick loads together with overflow entries); a refused resume (`resume refused: …`, the pause stays); a candidate gone from origin (`… is gone from origin; recomposing …`), whose PRs are recomposed; check runs on the candidate that are no job of its push runs (`check runs on the candidate that are not jobs of its push runs, ignored for the verdict: …`, once per batch); a base repair dropped after an infrastructure failure under a `base-red` pause (`… failed for infrastructure after … dropped; the base-red pause stays`). A tick that hit a rate limit while landing fails with `landing <batchId> hit a rate limit (…)`. The detail says which. | Read the detail: each pause detail, and each other `error` detail an operator must act on, has an entry in [Incidents](#incidents). A landing that fails on every tick ends in the pause after three attempts. |
| `queue-stalled` | The queue stopped making progress: paused for more than 120 minutes (with reason `error` or `tree-divergence`, at once), a candidate in flight for more than `checksTimeoutMinutes` + 60, eligible PRs and nothing started for more than `batch.maxWaitMinutes` + 30, three ticks in a row that failed, a stored withdrawal refused for more than 60 minutes, or three landings in a row without a verdict. One per episode, with one comment on the dashboard issue that mentions the approvers (see [Health](#health)). The detail lists the reasons. | See [The queue stalled](#the-queue-stalled). |
| Event | When it happens | What the operator does |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch-started` | A candidate was composed and pushed: a new batch, a recomposition or a bisection segment. The detail names the PRs and the base, and for a root batch with `batch.adaptive` the window it was cut to (`window W`). A lane batch names its lane instead of a window (`lane hotfix` or `lane base-repair`). | Nothing. Its CI is linked from the dashboard. |
| `pr-skipped-conflict` | A PR conflicts with an earlier PR of the same batch. It is left out of this candidate and stays queued for a later batch. | Nothing. If it repeats, the author rebases the PR over the one it conflicts with. |
| `pr-dequeued` | A PR left the queue: `base-conflict` (it no longer merges into the base: label removed, comment), `already-in-base` (both labels removed, comment), or `withdrawn: <why>` before composition (label, head or approval changed). In shadow mode the first two are `would-dequeue` events instead. | For `base-conflict` the author updates the branch and an approver labels it again; the other cases need nothing. |
| `checks-green` | Every required check of the candidate (or of a base check) concluded `success`. | Nothing. The landing (or `would-land`) follows. |
| `checks-red` | A check of the candidate failed. The detail names the failing checks; on a base check it starts with `base-check red`. It ends with `; re-run refused (<status or reason>)` when the re-run of the failed jobs was refused. A batch red again after its re-run records a second one. | Nothing yet: classification follows (a re-run of the failed jobs, infra retry, base check, bisection or culprit). |
| `flaky-rerun` | A red batch or bisection segment that would be bisected, tested against the base or dequeued: its failed jobs are re-run once after its runs end (`flakyReruns`). Detail: `re-running the failed jobs of <batch> once (<jobs>) before <bisecting\|a base check\|dequeuing #n>` (five jobs at most). A green re-run's `checks-green` reads `green after re-running <jobs> (flaky)`. | Nothing. A real failure is blamed later: after the rest of the CI run and the re-run. Jobs that often turn green on the re-run are flaky tests to fix. |
| `checks-timeout` | No verdict after `checksTimeoutMinutes`, or no CI run at all after 45 minutes (`no CI run for candidate`). | For `no CI run`, check the Actions policies and the `omni-queue/**` triggers of `ci.yml` / `quality.yml` (see [Infra failure or timeout](#infra-failure-or-timeout)). |
| `land-blessed` | Live mode: the App wrote the land status (`landing.statusContext`, `success`) on the commits about to land, right before the landing. | Nothing. A `landed` event should follow; if a pause follows, the status was withdrawn. |
| `manual-bless` | An approver's `bless`: the App wrote the land status on one chosen commit. The detail names who and why. | Push or merge that commit yourself (see [Land status and manual bless](#land-status-and-manual-bless)). |
| `landed` | Live mode: the batch reached the base (the `merge-ff` push or every `squash-api` merge). | Nothing. |
| `would-land` | Shadow mode: a green batch that live mode would have landed. The detail can add `merged meanwhile by another path`, `live mode would pause: queue refs unprotected (…)` and, after the name of a check, `could not run (…): live mode would fail the tick`. | Compare with what Mergify merged. Both notes must be gone before `mode: "live"`: apply the queue-refs ruleset, or fix the check that could not run. |
| `would-dequeue` | Shadow mode: live mode would have removed this PR from the queue (label kept, no comment). The detail gives the reason code(s). | Nothing during shadow. |
| `land-rejected` | The batch was not landed: the base moved (`base moved…; recomposing`: the same PRs are recomposed on the tip), the batch changed before landing (`batch changed before landing: …`: the PRs left are recomposed), or a release-freeze holds it (`base-frozen: …; <batch> waits for the freeze to lift`, once per batch: it stays in flight, not recomposed, and lands after the freeze). | Nothing for an occasional one; frequent ones mean something else merges into the base (see [Recomposition when the base moves](#recomposition-when-the-base-moves)). |
| `bisect-split` | A red batch (or a red segment of a bisection) is split; the detail names the segment tested next. | Nothing. |
| `culprit-found` | Bisection or a batch of one isolated the PR that fails. Live: label removed, comment. Shadow, or a head that moved: label kept. | The author fixes the PR and an approver labels it again. |
| `base-check-started` | A red batch on a base with no verdict: the bare base is pushed as a `basecheck-<sha12>` candidate. | Nothing. |
| `base-red-paused` | The base check is red with the same failures as the batch: the base is paused with reason `base-red`. | Fix the base (see [Base-red](#base-red)). The pause lifts when the tip moves. |
| `hang-suspected` | A job hit its time limit on every run of the candidate: treated as a hanging test (base check, then bisection) instead of an infra pause. | Nothing yet; look at the culprit comment when one is named. |
| `infra-retry` | Every failure is infrastructure (or the checks timed out): the same SHA is retried under a new ref (`-r1`, `-r2`, …), while retries of `infraRetries` are left. The detail reads `retry <n>/<infraRetries>: …`. | Nothing. |
| `infra-paused` | An infrastructure failure (or a timeout) with no retry of `infraRetries` left: the base is paused with reason `infra`. With the shipped `infraRetries: 1` that is the second failure; with `0`, the first. When every run only hit a job time limit, the outcome is `hang-suspected` instead (see its row). A base repair under a `base-red` pause is dropped instead, with an `error` event, and the `base-red` pause stays. | Check the Actions status and the candidate's run, then `npm run queue -- resume <base>`. |
| `paused` | A manual pause (`npm run queue -- pause`, or `action=pause`). The detail is the reason, on one line, cut at 200 characters. | `npm run queue -- resume <base>` when ready. |
| `resumed` | A manual resume (`manual resume (was <reason>)`, followed by `; the pause it cleared named commits kept nowhere (both lists full), check their <landing.statusContext> by hand: <sha> (<batchId>), …` when that pause named such commits), a `base-red` pause lifted because the base tip moved (`base moved <sha12> → <sha12> after a base-red pause`), or, in live mode, a `base-red` pause lifted because a PR of the base-repair lane landed (`base repaired by #<n>`). Neither automatic lift happens while `landWithdrawalsOverflow` holds entries: a tick replaces such a `base-red` pause with the full-list pause. | For a detail that names commits kept nowhere: check their land status by hand (see [Paused: landWithdrawals is full](#paused-landwithdrawals-is-full)). Otherwise nothing. |
| `tree-divergence` | `squash-api` only: the base tree after the merges differs from the candidate tree, or an open divergence issue stops a landing. The base is paused with reason `tree-divergence`. | Compare the trees, fix the base, close the issue, resume (see [Tree divergence](#tree-divergence-squash-api-only)). |
| `error` | A tick failed (the detail is its error message); a landing pause (reason `error`: land token, landing refused, composition mismatch, queue refs, base not found, attempts limit); a land-status withdrawal GitHub refused (`<batchId>: could not withdraw …`); a stored withdrawal refused for a day (`… has been refused for more than 24 h, since …; the queue keeps retrying it`); a refused withdrawal that found the `landWithdrawals` list (20) full, kept in `landWithdrawalsOverflow` (`landWithdrawals is full …`; it pauses a base that is not paused, or replaces a `base-red` pause, also one a tick loads together with overflow entries); a refused resume (`resume refused: …`, the pause stays); a candidate gone from origin (`… is gone from origin; recomposing …`), whose PRs are recomposed; check runs on the candidate that are no job of its push runs (`check runs on the candidate that are not jobs of its push runs, ignored for the verdict: …`, once per batch); a base repair dropped after an infrastructure failure under a `base-red` pause (`… failed for infrastructure after … dropped; the base-red pause stays`); a batch composed unsigned although `landing.signing` is `ssh` (`<batchId>: <n> merge commit(s) composed unsigned: …`, once per batch); the owner voice falling back to the App's token (`owner voice unavailable, written with the App's token instead: …`, at most once per tick). A tick that hit a rate limit while landing fails with `landing <batchId> hit a rate limit (…)`. The detail says which. | Read the detail: each pause detail, and each other `error` detail an operator must act on, has an entry in [Incidents](#incidents). A landing that fails on every tick ends in the pause after three attempts. |
| `queue-stalled` | The queue stopped making progress: paused for more than 120 minutes (with reason `error` or `tree-divergence`, at once), a candidate in flight for more than `checksTimeoutMinutes` + 60, eligible PRs and nothing started for more than `batch.maxWaitMinutes` + 30, three ticks in a row that failed, a stored withdrawal refused for more than 60 minutes, or three landings in a row without a verdict. One per episode, with one comment on the dashboard issue that mentions the approvers (see [Health](#health)). The detail lists the reasons. | See [The queue stalled](#the-queue-stalled). |
## Configuration keys
`config/merge-queue/config.json`, validated by `validateConfig` in `scripts/merge-queue/config.mjs`.
The workflow reads the copy on the default branch. Every key without a default is required, except
`landing.identity`, which is required or refused depending on `landing.actor` (see its row). An
unknown key, top-level or in `batch`, `landing`, `landing.identity` or `lanes`, is refused.
`landing.identity`, which is required or refused depending on `landing.actor` (see its row), and
`landing.signing: "ssh"`, which needs `landing.actor: "owner"`. An unknown key, top-level or in
`batch`, `landing`, `landing.identity` or `lanes`, is refused.
"Shipped" is the value in the config file of this repository.
`tests/unit/merge-queue/runbook.test.mjs` fails when this table and the keys `validateConfig` reads
differ.
@@ -1106,6 +1221,7 @@ differ.
| `landing.mode` | `merge-ff` or `squash-api` | none; shipped `merge-ff` | How a green batch lands (see [Landing modes](#landing-modes-landingmode)). |
| `landing.actor` | `app` or `owner` | `app`; shipped `owner` | Whose token lands: the App's, or `OMNI_QUEUE_LAND_TOKEN` (see [Who lands](#who-lands-landingactor)). |
| `landing.identity` | `{name, email}`, the email a `@users.noreply.github.com` one | none; required with `actor: "owner"`, refused otherwise | Identity of the queue's merge commits when the owner lands. |
| `landing.signing` | `none` or `ssh` | `none`; shipped `none` | `ssh` signs every merge commit the queue composes with the key of the secret OMNI_QUEUE_SIGNING_KEY; refused unless `landing.actor` is `owner` (see [Signed merge commits](#signed-merge-commits-landingsigning)). |
| `landing.statusContext` | `omni-queue/<name>`, `[A-Za-z0-9._/-]{1,100}` | `omni-queue/land`; shipped `omni-queue/land` | The land status the release ruleset requires. Must not be a required, aggregate or approval context. |
| `requiredChecks` | list of check names, at least one | none; shipped three checks | Checks that must conclude `success` on a candidate (see [Accepting a candidate](#accepting-a-candidate)). |
| `advisoryChecks` | list of check names, none in `requiredChecks` | none; shipped `Build (advisory)` | Checks whose failure does not make a candidate red. |
@@ -1118,6 +1234,7 @@ differ.
| `prChecksRequired` | list of distinct check names | `[]`; shipped `Gate / CI`, `Gate / Quality`, `API Route Typecheck` | Green on a PR head to enter a batch: worst of the suites reporting it; if they disagree, a run superseded by a newer run of the same workflow and event drops ([Eligibility](#eligibility)). |
| `protectedPaths` | list of globs, at least one | none; shipped the agent-instruction surfaces and the queue's control plane | A PR that touches one also needs `protectedApprovalLabel` (see [Eligibility](#eligibility)). |
| `lanes.hotfixLabel` | label name, distinct from every other label of the config | no `lanes` = no lanes; shipped `omni-queue-hotfix` | Applied by an approver to an eligible PR: at the next batch start it is composed alone, ahead of the FIFO. Never replaces what is in flight. Repeated in the tick's job filter. |
| `voice` | `app` or `owner` | `app`; shipped `app` | Whose token posts the queue's comments, removes its labels and writes its issues: the App's, or `OMNI_QUEUE_LAND_TOKEN`, with a fallback to the App's (see [Who speaks](#who-speaks-voice)). |
| `lanes.baseRepairLabel` | label name, distinct from every other label of the config | no `lanes` = no lanes; shipped `omni-queue-base-repair` | Applied by an approver: composed alone (PR gates not required), the only work of a `base-red` pause; its landing lifts the pause. Never in a FIFO batch. Repeated in the tick's job filter. A repair that fails like the base is not composed again at that head (`repairTried`): push a fix (a new head is tried again), or remove this label (anyone who can label the PR can): the PR rejoins the FIFO. |
## CLI
@@ -1426,16 +1543,16 @@ action.
3. **Homepage URL**: the repository URL. **Webhook**: untick "Active" (the queue needs no webhook).
4. **Repository permissions**:
| Permission | Access | What the queue does with it |
| --------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Contents | Read and write | tick: push candidate branches, read and write `state/<base>.json` on `omni-queue-state`, delete candidate branches, read base tips and commits; with `landing.actor: "app"`, the landing push or merges too. approval: read |
| Pull requests | Read and write | tick: read each queued PR (head, base, files, mergeability); write: only the per-PR merge of `squash-api` with `landing.actor: "app"` (`PUT /repos/{owner}/{repo}/pulls/{n}/merge`). Labels and comments on PRs go through the issues endpoints. With the shipped config (`owner`, `merge-ff`) no call of the App uses write here. approval: read the PR |
| Issues | Read and write | tick: the dashboard issue and its stalled comment, comments on the `base-red` issue, the tree-divergence issue, reading `release-freeze` issues and PR timelines, removing labels from and commenting on PRs (live mode only). approval: the "not an approver" comment |
| Commit statuses | Read and write | approval: write `omni-queue/approval` and `omni-queue/protected-approval`. tick: read them, write and withdraw the land status, `bless` |
| Workflows | Read and write | tick: push a candidate (and, with `landing.actor: "app"`, land it) when a PR of the batch changes a file under `.github/workflows/` |
| Checks | Read-only | tick: the check runs and annotations of a candidate, and the PR gates of a PR head |
| Actions | Read and write | tick: list the workflow runs of a candidate ref and of a PR head (read); re-run the failed jobs of a red candidate (write, `flakyReruns`) |
| Metadata | Read-only | always granted |
| Permission | Access | What the queue does with it |
| --------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Contents | Read and write | tick: push candidate branches, read and write `state/<base>.json` on `omni-queue-state`, delete candidate branches, read base tips and commits; with `landing.actor: "app"`, the landing push or merges too. approval: read |
| Pull requests | Read and write | tick: read each queued PR (head, base, files, mergeability); write: only the per-PR merge of `squash-api` with `landing.actor: "app"` (`PUT /repos/{owner}/{repo}/pulls/{n}/merge`). Labels and comments on PRs go through the issues endpoints. With the shipped config (`owner`, `merge-ff`) no call of the App uses write here. approval: read the PR |
| Issues | Read and write | tick: the dashboard issue and its stalled comment, comments on the `base-red` issue, the tree-divergence issue, reading `release-freeze` issues and PR timelines, removing labels from and commenting on PRs (live mode only); with `voice: "owner"` the App makes these writes only when the owner's token is missing or refused. approval: the "not an approver" comment |
| Commit statuses | Read and write | approval: write `omni-queue/approval` and `omni-queue/protected-approval`. tick: read them, write and withdraw the land status, `bless` |
| Workflows | Read and write | tick: push a candidate (and, with `landing.actor: "app"`, land it) when a PR of the batch changes a file under `.github/workflows/` |
| Checks | Read-only | tick: the check runs and annotations of a candidate, and the PR gates of a PR head |
| Actions | Read and write | tick: list the workflow runs of a candidate ref and of a PR head (read); re-run the failed jobs of a red candidate (write, `flakyReruns`) |
| Metadata | Read-only | always granted |
Each job mints its token with only part of this (the `approval` job: contents and pull requests
read, issues and statuses write; the `tick` job: everything above). The tick also reads the
@@ -1488,6 +1605,9 @@ action.
Secrets: OMNI_QUEUE_APP_CLIENT_ID the Client ID from step 5
OMNI_QUEUE_APP_PRIVATE_KEY the full contents of the .pem from step 6
OMNI_QUEUE_LAND_TOKEN the owner's fine-grained token (see below)
OMNI_QUEUE_SIGNING_KEY optional: the owner's SSH signing key, only
for landing.signing "ssh" (see Signed merge
commits)
Repository variable (Settings → Secrets and variables → Actions → Variables)
OMNI_QUEUE_ENABLED "true" only when the queue should run
```
@@ -1500,7 +1620,24 @@ action.
write the expiry date down and rotate it before then. GitHub requires the Workflows permission
for a push of commits that change files under `.github/workflows/`, and the landing is made with
this token: without it, the landing of every batch that touches a workflow is refused. The token
is optional while the queue runs in shadow mode (see [Who lands](#who-lands-landingactor)).
is optional while the queue runs in shadow mode (see [Who lands](#who-lands-landingactor)),
unless `voice` is `owner`.
With `voice: "owner"` ([Who speaks](#who-speaks-voice)) the same token also needs **Issues: Read
and write**: opening and updating an issue (the dashboard, the tree-divergence issue) and
commenting on an issue (the dashboard, the `base-red` issue) are Issues endpoints. Comments on
pull requests and the removal of a label from a pull request are already covered by Pull
requests: Read and write. GitHub's table of
[permissions required for fine-grained personal access tokens](https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens)
lists `POST /repos/{owner}/{repo}/issues` under Issues (write) only;
`PATCH /repos/{owner}/{repo}/issues/{issue_number}`,
`POST /repos/{owner}/{repo}/issues/{issue_number}/comments`,
`DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}` and
`DELETE /repos/{owner}/{repo}/issues/{issue_number}/labels/{name}` under both Issues (write) and
Pull requests (write), marked as needing additional permissions, which on an issue are Issues.
The tick also reads the owner's login with `GET /user`, which that table does not list. A
missing permission is a 403: the write is made by the App (see [Who speaks](#who-speaks-voice)),
and the `error` event names it.
Both jobs of `.github/workflows/omni-queue.yml` declare this environment with
`deployment: false`: they get its secrets and its branch policy, and no deployment record is
@@ -1557,7 +1694,9 @@ this order:
exact name, step 8 above);
2. put its secrets in it: OMNI_QUEUE_APP_CLIENT_ID and OMNI_QUEUE_APP_PRIVATE_KEY, and
`OMNI_QUEUE_LAND_TOKEN`. A shadow run never lands, so it works without the land token, but a live
landing needs it: have it in place at the latest before `mode: "live"`;
landing needs it: have it in place at the latest before `mode: "live"`, and before `voice` is
set to `owner` (shadow mode writes the dashboard issue with it). OMNI_QUEUE_SIGNING_KEY only
before `landing.signing` is set to `ssh`;
3. check that the App's installation has every permission of step 4 above, Actions: Read and
write included, and that the labels of step 9 exist;
4. in a public repository, create the Actions policy that allows the events of
@@ -1862,7 +2001,7 @@ The three uses:
- **Hotfix**: a commit that cannot wait for a batch.
- **Sync-back landing**: the `main → release/vX+1` merge commit, pushed as the merge commit it
already is (see AGENTS.md → "Sync-back landings are fast-forward, never squash").
already is (see AGENTS.md → "Sync-back landings are merge commits, never squash").
- **Base repair**: a fix to a red base that the maintainer lands directly instead of through a
batch.
@@ -1871,6 +2010,38 @@ the pause. While no ruleset requiring the status is applied to the branch (the c
before the cut-over), a bless changes nothing about what can be pushed: it only records the status
and the event.
## What appears as the owner and what appears as the App
With the shipped config (`landing.actor: "owner"`, `voice: "app"`, `landing.signing: "none"`):
| On GitHub | Appears as |
| --------------------------------------------------------------- | ---------------------------------------- |
| "merged by" on a landed pull request (the `merge-ff` push) | the owner (`OMNI_QUEUE_LAND_TOKEN`) |
| author and committer of the queue's merge commits | `landing.identity` (the owner), unsigned |
| every comment on a pull request, every label removal | the App (`omni-queue[bot]`) |
| the dashboard issue, its body, its comments (the stalled alert) | the App |
| comments on the `base-red` issue, the tree-divergence issue | the App |
| commit statuses (`omni-queue/land`, both approvals, a bless) | the App, always |
With `voice: "owner"` the third to fifth rows become the owner (each one the App's again when the
owner's token is missing or refused), and with `landing.signing: "ssh"` the merge commits are
signed with the owner's key.
**Always the App, whatever the config**, and why:
- every commit status: `omni-queue/land` (the release ruleset's door pins it to the App's
integration id), `omni-queue/approval`, `omni-queue/protected-approval`, a `bless`;
- candidate branches `omni-queue/**` and the `omni-queue-state` branch (the queue-refs ruleset
admits the App only);
- re-runs of a candidate's failed jobs;
- every read, including the comment listings the markers are checked against;
- the `approval` job's "not an approver" comment: that job never receives the owner's token;
- a write the owner's token cannot make (missing token, 401 or 403): the App makes it instead, and
an `error` event says so.
**The watchdog speaks as `github-actions[bot]`**: its issue and comments use the workflow's own
token on purpose, so it works when the environment's secrets fail.
## Security posture
- **No PR code runs in the queue workflow.** Both jobs check out the default branch (sparse:
@@ -1887,7 +2058,18 @@ and the event.
trigger on candidate branches.
- **Least privilege**: one App token per job with only the permissions that job needs; the
workflow's own `GITHUB_TOKEN` is read-only. The owner's `OMNI_QUEUE_LAND_TOKEN` reaches only the
tick step, and only the landing uses it.
tick step; the landing uses it with `landing.actor: "owner"`, and the queue's comments, label
removals and issues with `voice: "owner"` (never a commit status, a ref, the state branch or a
re-run). The `approval` job never receives it.
- **The signing key** (OMNI_QUEUE_SIGNING_KEY, `landing.signing: "ssh"`) reaches one step of the
tick job, which writes it to a `0600` file under `RUNNER_TEMP`; the job's last step removes it
(`if: always()`). git gets the path as per-command configuration through the environment, never
as an argument; no log line, event, state, comment or error message holds the key or its path.
A signature changes nothing the queue verifies (see
[Signed merge commits](#signed-merge-commits-landingsigning)).
- **Comment markers are trusted by author**: only markers written by `<appSlug>[bot]`, or by the
owner's login read from the owner's token itself, count; a marker anybody else writes is
ignored.
- **The App key is the root of trust of the status door.** Whoever can use it can write the land
status on any commit. Both jobs run in the `omni-queue` environment, which holds the App's
credentials and the land token and admits the default branch only, so a workflow on a candidate
@@ -1897,6 +2079,9 @@ and the event.
message and escaped in the dashboard; git runs through `scripts/merge-queue/gitexec.mjs` (no
shell, token in the environment as an HTTP header, OMNI_QUEUE_TOKEN and `OMNI_QUEUE_LAND_TOKEN`
removed from the environment of every git process, redacted errors).
- **One thing still speaks as `github-actions[bot]`**: the watchdog
(`.github/workflows/omni-queue-watchdog.yml`, `scripts/merge-queue/watchdog.mjs`) uses its
workflow's own token on purpose, so it keeps working when the environment's secrets fail.
- **Approvals are bound to SHAs**, never to commit dates (see [Eligibility](#eligibility)).
## Incidents
@@ -2160,6 +2345,31 @@ discovery (red runs with `setup failed` or `base discovery failed`, see
that is pending forever (only one tick runs at a time, by design); a closed dashboard issue, on a
base whose only work is not a labeled PR (see [State](#state)).
### Owner voice unavailable
`error` event `owner voice unavailable, written with the App's token instead: <cause>` (with
`voice: "owner"`). Nothing was lost: every write of that tick was made by the App. By cause:
- `OMNI_QUEUE_LAND_TOKEN is not set`: put the token in the environment `omni-queue`;
- `GitHub refused the owner's token (401)` or `… reading its login (401)`: the token expired or was
revoked: rotate it;
- `GitHub refused the owner's token (403)`: a permission is missing, most often Issues: Read and
write (see [Installing the GitHub App](#installing-the-github-app), step 8);
- `the owner's token does not name a user account`: the secret holds some other token.
The event is not repeated while the cause stays the same; the decisions of every tick that falls
back say which write did.
### Merge commits composed unsigned
`error` event `<batchId>: <n> merge commit(s) composed unsigned: <cause>` (with
`landing.signing: "ssh"`). The batch was composed, tested and (live) lands as usual, without the
signature. `no signing key file in the job …`: the secret OMNI_QUEUE_SIGNING_KEY is missing from
the environment or the step that writes it warned that it could not. `git could not sign a merge
commit (exit <code>)`: the secret is not an unencrypted SSH private key (a passphrase, a public key,
a truncated paste); store the private key file's full contents again. To stop signing, set
`landing.signing` back to `none`.
### Dequeued PR
What you see, in live mode: a comment on the PR that starts "❌ omni-queue isolated this PR as the

View File

@@ -24,6 +24,7 @@ import { mapImageSize } from "../translator/image/sizeMapper.ts";
import { getCodexClientVersion, getCodexUserAgent } from "../config/codexClient.ts";
import { isCodexFreePlan } from "../executors/codex/tools.ts";
import { sleep } from "../utils/sleep.ts";
import { clampPollIntervalMs, clampPollTimeoutMs } from "../utils/pollBounds.ts";
import { codexReferenceImageUrl } from "./imageGeneration/providers/codexReferences.ts";
export { shrinkCodexReferenceImage } from "./imageGeneration/providers/codexReferences.ts";
import {
@@ -2965,11 +2966,11 @@ async function handleNanoBananaImageGeneration({
return { success: false, status: 500, error: errorText };
}
const timeoutMs = normalizePositiveNumber(
const timeoutMs = clampPollTimeoutMs(
body.timeout_ms,
normalizePositiveNumber(process.env.NANOBANANA_POLL_TIMEOUT_MS, 120000)
);
const pollIntervalMs = normalizePositiveNumber(
const pollIntervalMs = clampPollIntervalMs(
body.poll_interval_ms,
normalizePositiveNumber(process.env.NANOBANANA_POLL_INTERVAL_MS, 2500)
);

View File

@@ -7,11 +7,11 @@
import { mapImageSize } from "../../../translator/image/sizeMapper.ts";
import { sleep } from "../../../utils/sleep.ts";
import { clampPollIntervalMs, clampPollTimeoutMs } from "../../../utils/pollBounds.ts";
import { sanitizeErrorMessage } from "../../../utils/error.ts";
import {
extractImageInputs,
isHttpUrl,
normalizePositiveNumber,
normalizeProviderImagePayload,
normalizeRequestedImageFormat,
parseSizeToDimensions,
@@ -180,8 +180,8 @@ export async function handleBlackForestLabsImageGeneration({
}
async function pollBlackForestLabsResult({ pollingUrl, token, body, log }) {
const timeoutMs = normalizePositiveNumber(body.timeout_ms, 300000);
const pollIntervalMs = normalizePositiveNumber(body.poll_interval_ms, 1500);
const timeoutMs = clampPollTimeoutMs(body.timeout_ms, 300000);
const pollIntervalMs = clampPollIntervalMs(body.poll_interval_ms, 1500);
const deadline = Date.now() + timeoutMs;
while (Date.now() < deadline) {

View File

@@ -9,6 +9,7 @@
import { saveCallLog } from "../../imageResult.ts";
import { sleep } from "../../../utils/sleep.ts";
import { clampPollIntervalMs, clampPollTimeoutMs } from "../../../utils/pollBounds.ts";
import { sanitizeErrorMessage } from "../../../utils/error.ts";
import {
UPSTREAM_MEDIA_LIMITS,
@@ -19,12 +20,6 @@ import {
const DEFAULT_POLL_INTERVAL_MS = 4000;
const DEFAULT_POLL_TIMEOUT_MS = 180000;
function normalizePositiveNumber(value: unknown, fallback: number): number {
const n = Number(value);
if (!Number.isFinite(n) || n <= 0) return fallback;
return Math.floor(n);
}
interface MagnificProviderConfig {
baseUrl: string;
statusUrl?: string;
@@ -267,8 +262,8 @@ export async function handleMagnificImageGeneration({
const startTime = Date.now();
const token = credentials?.apiKey || "";
const prompt = typeof body.prompt === "string" ? body.prompt : String(body.prompt ?? "");
const pollIntervalMs = normalizePositiveNumber(body.poll_interval_ms, DEFAULT_POLL_INTERVAL_MS);
const pollTimeoutMs = normalizePositiveNumber(body.poll_timeout_ms, DEFAULT_POLL_TIMEOUT_MS);
const pollIntervalMs = clampPollIntervalMs(body.poll_interval_ms, DEFAULT_POLL_INTERVAL_MS);
const pollTimeoutMs = clampPollTimeoutMs(body.poll_timeout_ms, DEFAULT_POLL_TIMEOUT_MS);
if (log) {
log.info(
"IMAGE",

View File

@@ -10,7 +10,6 @@ import {
renderhourBaseUrl,
renderhourConfig,
renderhourFailure,
renderhourNumber,
renderhourToken,
runRenderhourJob,
uploadRenderhourInputs,
@@ -22,6 +21,7 @@ import {
saveImageErrorResult,
saveImageSuccessResult,
} from "../../imageGeneration.ts";
import { clampPollIntervalMs, clampPollTimeoutMs } from "../../../utils/pollBounds.ts";
const MAX_IMAGES_PER_JOB = 4;
@@ -72,8 +72,8 @@ export async function handleRenderhourImageGeneration({
baseUrl,
token,
request,
timeoutMs: renderhourNumber(body.timeout_ms, 300_000),
pollIntervalMs: renderhourNumber(body.poll_interval_ms, 2000),
timeoutMs: clampPollTimeoutMs(body.timeout_ms, 300_000),
pollIntervalMs: clampPollIntervalMs(body.poll_interval_ms, 2000),
log,
signal,
});

View File

@@ -302,7 +302,7 @@ async function pollRenderhourJob({
error: `RenderHour job ${job.id} did not finish within ${Math.round(timeoutMs / 1000)} s`,
};
}
await sleep(delay);
await sleep(delay, signal);
delay = pollIntervalMs;
// Asking about a job also moves it forward on RenderHour's side.
const response = await fetch(`${baseUrl}/v1/generations/${encodeURIComponent(job.id)}`, {

View File

@@ -16,7 +16,7 @@ import { fetchWithCheckedRedirects, isRegistryEndpoint } from "./redirectGuard.t
import type { SearchUrlGuard } from "./baseUrl.ts";
import { HTTP_STATUS } from "../../config/constants.ts";
import { lockBorrowedSearchKey } from "./borrowedKeyLock.ts";
import { isSubscriptionQuotaText } from "../../services/quotaTextCooldowns.ts";
import { isSubscriptionQuotaForStatus } from "../../services/quotaTextCooldowns.ts";
import type { SearchProviderConfig } from "../../config/searchRegistry.ts";
import type { SearchResult } from "../search.ts";
import {
@@ -53,7 +53,9 @@ export function shouldCoolDownSearchConnection(status: number, errorText: string
if (SEARCH_COOLDOWN_STATUSES.has(status)) return true;
const lower = errorText.toLowerCase();
if (SEARCH_CREDIT_EXHAUSTION_PHRASES.some((phrase) => lower.includes(phrase))) return true;
return isSubscriptionQuotaText(lower);
// A 400 can quote the caller's query back: plan/usage-limit wording counts on 400
// only with a structured quota code (same status contract as LLM fallback).
return isSubscriptionQuotaForStatus(status, null, errorText);
}
/** Post-dispatch state cleanup shared by JSON and SSE search providers. */

View File

@@ -138,7 +138,10 @@ import { resolveApiKeyForbiddenFallback } from "./accountFallback/nonRetryableUp
import * as exactModelLock from "./accountFallback/exactModelLock.ts";
import { isCreditsExhaustedWithSharedWallet } from "./accountFallback/sharedWalletCredits.ts";
import { CREDITS_EXHAUSTED_SIGNALS } from "./accountFallback/creditExhaustionSignals.ts";
import { isCreditsExhaustedForStatus } from "./accountFallback/creditsExhaustedForStatus.ts";
import {
isCreditsExhaustedForStatus,
quotaTextSignalCountsForStatus,
} from "./accountFallback/creditsExhaustedForStatus.ts";
export { CREDITS_EXHAUSTED_SIGNALS } from "./accountFallback/creditExhaustionSignals.ts";
import { isMistralAmbiguous401 } from "./accountFallback/mistralAmbiguousAuth.ts";
import { isRegisteredFeatureFlagEnabled } from "../utils/registeredFeatureFlag.ts";
@@ -2306,8 +2309,20 @@ export function checkFallbackError(
// UNCONDITIONALLY (not gated by shouldUseQuotaSignal) because it targets
// apikey-category providers like ollama-cloud, which the oauth-only
// shouldUseQuotaSignal gate deliberately excludes from the subscription
// check above.
if (shouldUseQuotaSignal && !isCreditsExhausted(errorStr) && !isDailyQuotaExhausted(errorStr)) {
// check above. On 400 none of these quota TEXT signals counts without a structured
// code or an allow-listed provider: the message may quote the caller's own input.
const quotaTextCounts = quotaTextSignalCountsForStatus(
status,
provider,
errorStr,
structuredError?.code
);
if (
quotaTextCounts &&
shouldUseQuotaSignal &&
!isCreditsExhausted(errorStr) &&
!isDailyQuotaExhausted(errorStr)
) {
const subResult = buildSubscriptionQuotaFallback(
errorStr,
getUpstreamRetryHint,
@@ -2317,14 +2332,17 @@ export function checkFallbackError(
);
if (subResult) return subResult;
}
const weeklyResult = buildWeeklyQuotaFallback(errorStr, undefined, provider);
const weeklyResult = quotaTextCounts
? buildWeeklyQuotaFallback(errorStr, undefined, provider)
: null;
if (weeklyResult) return weeklyResult;
// Issue #7071 (session usage cap) is the same sibling gap as #3709 above —
// runs UNCONDITIONALLY for the same reason: apikey-category providers
// like ollama-cloud are excluded from the oauth-only shouldUseQuotaSignal
// gate.
const sessionResult =
buildSessionQuotaFallback(errorStr) ?? buildRolling24hQuotaFallback(errorStr);
const sessionResult = quotaTextCounts
? (buildSessionQuotaFallback(errorStr) ?? buildRolling24hQuotaFallback(errorStr))
: null;
if (sessionResult) return sessionResult;
const detectedRetryHint = detectRetryHint();
@@ -2336,6 +2354,7 @@ export function checkFallbackError(
? "body"
: undefined;
if (
quotaTextCounts &&
shouldUseQuotaSignal &&
quotaResetHintMs &&
classifyErrorText(errorStr) === RateLimitReason.QUOTA_EXHAUSTED

View File

@@ -60,6 +60,25 @@ function hasCreditErrorCode(text: string, structured: unknown): boolean {
return codes.some((code) => CREDIT_ERROR_CODES.has(code.trim().toLowerCase()));
}
/**
* Whether a quota/credit TEXT signal found in an upstream error may count at this
* status. Every status except 400 keeps the plain text match; on 400 the signal
* counts only with a structured credit code or for an allow-listed provider (see
* the header). Shared by the credit check below and the subscription/plan quota
* text checks in quotaTextCooldowns.ts.
*/
export function quotaTextSignalCountsForStatus(
status: number,
provider: string | null | undefined,
errorText: string,
structured?: unknown
): boolean {
if (status !== 400) return true;
return (
allowsMessageOnlyCredit400(provider) || hasCreditErrorCode(String(errorText || ""), structured)
);
}
/**
* Status-aware credit exhaustion check shared by the classifier, the fallback
* engine and terminal-status resolution. `structured` is what the caller holds
@@ -73,6 +92,5 @@ export function isCreditsExhaustedForStatus(
): boolean {
const text = String(errorText || "");
if (!isCreditsExhaustedWithSharedWallet(text, CREDITS_EXHAUSTED_SIGNALS)) return false;
if (status !== 400) return true;
return allowsMessageOnlyCredit400(provider) || hasCreditErrorCode(text, structured);
return quotaTextSignalCountsForStatus(status, provider, text, structured);
}

View File

@@ -3,12 +3,9 @@
*
* `full`/absent → whole text (backward-compat). All modes are fail-safe:
* incoherent params or an unsafe regex yield { error }, never throw. The grep
* mode validates the pattern with `safe-regex` (no nested quantifiers), allows at
* most one unbounded quantifier, bounds matches/pattern length, and runs the scan
* under a wall-clock budget (CodeQL #1349): a caller-supplied pattern can still be
* super-linear (`.*x` is quadratic per line), so the budget is the hard bound.
* mode validates the pattern with `safe-regex` (no catastrophic backtracking)
* before compiling, and bounds matches/pattern length.
*/
import vm from "node:vm";
import safeRegex from "safe-regex";
export type CcrMode = "full" | "head" | "tail" | "lines" | "grep" | "stats";
@@ -27,8 +24,6 @@ export type CcrQueryResult = { content: string } | { error: string };
export const MAX_RANGE_LINES = 10_000;
export const MAX_GREP_MATCHES = 1_000;
export const MAX_PATTERN_LEN = 512;
/** Wall-clock budget for one grep scan over a block (ms). */
export const GREP_TIME_BUDGET_MS = 1_000;
const err = (m: string): CcrQueryResult => ({ error: m });
const ok = (c: string): CcrQueryResult => ({ content: c });
@@ -58,104 +53,30 @@ function sliceLines(lines: string[], start?: number, end?: number): CcrQueryResu
return ok(lines.slice(start - 1, Math.min(end, lines.length)).join("\n"));
}
/**
* Number of unbounded quantifiers (`*`, `+`, `{n,}`) outside character classes and
* escapes. Two or more in sequence make the backtracking polynomial in the line length
* (`.*.*.*.*x` is O(n^4)), which `safe-regex`'s star-height check does not catch.
*/
export function countUnboundedQuantifiers(pattern: string): number {
let count = 0;
let i = 0;
while (i < pattern.length) {
const c = pattern[i];
if (c === "\\") {
i += 2;
} else if (c === "[") {
i = classEnd(pattern, i);
} else {
if (c === "*" || c === "+" || (c === "{" && isOpenRange(pattern, i))) count++;
i++;
}
}
return count;
}
/** Index just past the character class that opens at `start` (escapes honoured). */
function classEnd(pattern: string, start: number): number {
let i = start + 1;
while (i < pattern.length && pattern[i] !== "]") i += pattern[i] === "\\" ? 2 : 1;
return i + 1;
}
/** True when an open range quantifier `{n,}` starts at `start`. */
function isOpenRange(pattern: string, start: number): boolean {
let j = start + 1;
while (j < pattern.length && pattern[j] >= "0" && pattern[j] <= "9") j++;
return j > start + 1 && pattern[j] === "," && pattern[j + 1] === "}";
}
// The scan runs in a dedicated context only so `timeout` can stop a runaway regex.
// No host object enters it: inputs are primitives, the result leaves as a JSON string.
const GREP_SCRIPT = new vm.Script(`(() => {
"use strict";
let re;
try { re = new RegExp(grepPattern); } catch { return JSON.stringify({ invalid: true }); }
const matched = [];
let truncated = false;
for (const line of grepText.split("\\n")) {
if (re.test(line)) {
matched.push(line);
if (matched.length >= grepMaxMatches) { truncated = true; break; }
}
}
return JSON.stringify({ matched, truncated });
})()`);
let grepContext: vm.Context | null = null;
function runGrepScan(
text: string,
pattern: string
): { matched: string[]; truncated: boolean } | "invalid" | "timeout" {
grepContext ??= vm.createContext(Object.create(null), {
codeGeneration: { strings: false, wasm: false },
});
grepContext.grepPattern = pattern;
grepContext.grepText = text;
grepContext.grepMaxMatches = MAX_GREP_MATCHES;
let raw: unknown;
try {
raw = GREP_SCRIPT.runInContext(grepContext, { timeout: GREP_TIME_BUDGET_MS });
} catch (e) {
if ((e as { code?: string })?.code === "ERR_SCRIPT_EXECUTION_TIMEOUT") return "timeout";
throw e;
} finally {
grepContext.grepText = "";
grepContext.grepPattern = "";
}
const parsed = JSON.parse(String(raw)) as {
invalid?: boolean;
matched?: string[];
truncated?: boolean;
};
if (parsed.invalid === true) return "invalid";
return { matched: parsed.matched ?? [], truncated: parsed.truncated === true };
}
function grepLines(text: string, pattern?: string, unique?: boolean): CcrQueryResult {
function grepLines(lines: string[], pattern?: string, unique?: boolean): CcrQueryResult {
if (!pattern) return err("grep requires a 'pattern'");
if (pattern.length > MAX_PATTERN_LEN) return err(`pattern exceeds ${MAX_PATTERN_LEN} chars`);
if (!safeRegex(pattern)) return err("pattern rejected: potentially catastrophic backtracking");
if (countUnboundedQuantifiers(pattern) > 1) {
return err("pattern rejected: at most one unbounded quantifier (*, +, {n,}) is allowed");
let re: RegExp;
try {
re = new RegExp(pattern);
} catch {
return err("invalid regex pattern");
}
const scan = runGrepScan(text, pattern);
if (scan === "invalid") return err("invalid regex pattern");
if (scan === "timeout") {
return err(`grep exceeded its ${GREP_TIME_BUDGET_MS} ms time budget; use a narrower pattern`);
const matched: string[] = [];
let truncated = false;
for (const line of lines) {
if (re.test(line)) {
matched.push(line);
if (matched.length >= MAX_GREP_MATCHES) {
truncated = true;
break;
}
}
}
const out = unique ? [...new Set(scan.matched)] : scan.matched;
const out = unique ? [...new Set(matched)] : matched;
const body = out.join("\n");
return ok(scan.truncated ? `${body}\n…[truncated at ${MAX_GREP_MATCHES} matches]` : body);
return ok(truncated ? `${body}\n…[truncated at ${MAX_GREP_MATCHES} matches]` : body);
}
function blockStats(text: string, lines: string[]): CcrQueryResult {
@@ -180,7 +101,7 @@ export function queryBlock(text: string, q: CcrQuery): CcrQueryResult {
case "lines":
return sliceLines(lines, q.start, q.end);
case "grep":
return grepLines(text, q.pattern, q.unique);
return grepLines(lines, q.pattern, q.unique);
case "stats":
return blockStats(text, lines);
default:

View File

@@ -5,7 +5,7 @@ import {
isDailyQuotaExhausted,
isOAuthInvalidToken,
} from "./accountFallback.ts";
import { isSubscriptionQuotaText } from "./quotaTextCooldowns.ts";
import { isSubscriptionQuotaForStatus } from "./quotaTextCooldowns.ts";
import { isCreditsExhaustedForStatus } from "./accountFallback/creditsExhaustedForStatus.ts";
import { isProviderSafetyRefusalBody } from "../utils/providerSafety.ts";
import { isModelScopedAccessDenial } from "./accountFallback/modelScopedAccessDenial.ts";
@@ -453,8 +453,9 @@ export function classifyProviderError(
const bodyStr = responseBodyToString(responseBody);
const creditsExhausted = isCreditsExhaustedForStatus(statusCode, provider, bodyStr);
// Claude's native weekly 429 wording is provider-scoped; omitting provider
// silently classified the long-window quota as a short RPM rate limit.
const subscriptionQuotaExhausted = isSubscriptionQuotaText(bodyStr.toLowerCase(), provider);
// silently classified the long-window quota as a short RPM rate limit. On 400 the
// phrase needs a structured code (same contract as the credit signal above).
const subscriptionQuotaExhausted = isSubscriptionQuotaForStatus(statusCode, provider, bodyStr);
const accountDeactivated = isAccountDeactivated(bodyStr);
const oauthInvalid = isOAuthInvalidToken(bodyStr);
const preserveQuota429 = shouldPreserveQuotaSignalsFor429(provider);

View File

@@ -12,6 +12,7 @@
import { RateLimitReason } from "../config/constants.ts";
import { parseDayGranularityResetMs, parseIsoDateTimeResetMs } from "./quotaResetParsing.ts";
import { quotaTextSignalCountsForStatus } from "./accountFallback/creditsExhaustedForStatus.ts";
type RateLimitReasonValue = (typeof RateLimitReason)[keyof typeof RateLimitReason];
@@ -64,6 +65,26 @@ export function isSubscriptionQuotaText(lower: string, provider?: string | null)
);
}
/**
* Status-aware form of isSubscriptionQuotaText, under the same contract as the
* credit signal (creditsExhaustedForStatus.ts): a 400 often quotes the caller's
* own input back in its message, so on 400 the phrase counts only with a
* structured credit/quota code or for a provider whose documented 400 form is
* message-only. Every other status keeps the plain text match.
*/
export function isSubscriptionQuotaForStatus(
status: number,
provider: string | null | undefined,
errorText: string,
structured?: unknown
): boolean {
const text = String(errorText || "");
return (
isSubscriptionQuotaText(text.toLowerCase(), provider) &&
quotaTextSignalCountsForStatus(status, provider, text, structured)
);
}
export const SUBSCRIPTION_QUOTA_COOLDOWN_MS = 60 * 60 * 1000; // 1 hour
/** Same value space as accountFallback.ts's RetryHintProvenance (kept local to avoid a circular import). */

View File

@@ -172,8 +172,10 @@ export function applySyntxProviderRules(
settings: JsonRecord,
ctx: { modelType: string; fileCount?: number }
): void {
// aiName comes from the caller's model id: only the table's own entries may run, never a
// member inherited from Object.prototype ("constructor", "__proto__", ...). CodeQL #1392.
if (!Object.hasOwn(PROVIDER_RULES, aiName)) return;
const handler = PROVIDER_RULES[aiName];
if (!handler) return;
handler(ctx.modelType || "", ctx.fileCount ?? 0, settings);
}

View File

@@ -0,0 +1,42 @@
/**
* Upper bounds for the polling knobs a caller may send to async media jobs
* (`poll_interval_ms`, `timeout_ms`, `poll_timeout_ms`).
*
* Those values feed `sleep()` and the polling deadline. Without a ceiling one request could hold
* a handler for days while the server kept polling the upstream with the operator's credential
* (CodeQL #1389, js/resource-exhaustion). Same pattern as `resolveCursorImageTimeoutMs` in
* handlers/imageGeneration/providers/cursorAgentImage.ts: only the untrusted request value is
* clamped; the fallback (a built-in or operator-configured default) is trusted and kept as is.
*/
/** Longest single wait between two polls; matches MAX_POLL_RETRY_DELAY_MS in pollRetry.ts. */
export const MAX_CALLER_POLL_INTERVAL_MS = 30_000;
/** Longest total polling window a caller may ask for (10 minutes). */
export const MAX_CALLER_POLL_TIMEOUT_MS = 600_000;
/** A whole number of milliseconds ≥ 1 from the request, or null when absent or unusable. */
function positiveWholeMs(value: unknown): number | null {
const n = Number(value);
if (!Number.isFinite(n)) return null;
const ms = Math.floor(n);
return ms >= 1 ? ms : null;
}
/**
* The caller's value clamped to `ceiling`, or `fallback` when the caller sent none. A fallback
* above the ceiling stays reachable, so a ceiling never shortens a default.
*/
export function clampCallerMs(value: unknown, fallback: number, ceiling: number): number {
const requested = positiveWholeMs(value);
if (requested === null) return fallback;
return Math.min(requested, Math.max(ceiling, fallback));
}
export function clampPollIntervalMs(value: unknown, fallback: number): number {
return clampCallerMs(value, fallback, MAX_CALLER_POLL_INTERVAL_MS);
}
export function clampPollTimeoutMs(value: unknown, fallback: number): number {
return clampCallerMs(value, fallback, MAX_CALLER_POLL_TIMEOUT_MS);
}

View File

@@ -17,7 +17,9 @@
// `success` on pull_request.head.sha, context APPROVAL_CONTEXTS[kind],
// description "approved by <login>" (App token, so the creator is `<appSlug>[bot]`);
// labeled by a non-approver → comment once (key "not-approver"), no status
// (in shadow mode no comment either: shadow writes nothing on a pull request);
// (in shadow mode no comment either: shadow writes nothing on a pull request). Always the
// App's, whatever config.voice says: this job never receives the owner's token (the tick's
// own "not-approver" comment then finds this one by its marker and posts nothing);
// unlabeled → status `failure` "approval withdrawn by <login>" on the same head/context;
// in shadow mode (config.mode) nothing at all is written for a removal.
//

View File

@@ -8,8 +8,16 @@
//
// Nothing here force-pushes. Candidate refs are unique per SHA (contracts.candidateRef), so a
// push either creates a new ref or finds it already at the same SHA.
//
// SIGNED MERGE COMMITS (config landing.signing "ssh"): composeCandidate signs each merge commit
// with `commit-tree -S`, the SSH key file the workflow writes under RUNNER_TEMP
// (signingKeyPath) given to git as configuration of that one command (gpg.format=ssh,
// user.signingkey=<path>) through the environment, so neither the key nor its path is ever an
// argument, a log line, an event or an error message. A missing key or a signature git cannot
// make never blocks the queue: the commit is composed unsigned, exactly as without signing, and
// the result says so (`signing`), for the tick to report once per batch.
import { existsSync, mkdirSync, readdirSync } from "node:fs";
import { existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
import { join, resolve } from "node:path";
import {
@@ -43,6 +51,55 @@ import {
* test or land; the tick drops it from the queue
*/
/**
* Where the tick job's "Write the merge-commit signing key" step leaves the key, under
* RUNNER_TEMP (.github/workflows/omni-queue.yml; tests/unit/merge-queue/workflows.test.mjs pins
* both). The step removes the directory at the end of the job, failed or cancelled included.
*/
export const SIGNING_KEY_DIR = "omni-queue-signing";
export const SIGNING_KEY_FILE = "signing-key";
/** The signing key file of a job whose RUNNER_TEMP is `runnerTemp`; null without one. */
export function signingKeyPath(runnerTemp) {
if (typeof runnerTemp !== "string" || !runnerTemp) return null;
return join(runnerTemp, SIGNING_KEY_DIR, SIGNING_KEY_FILE);
}
/** Why a batch was composed unsigned although signing is asked for: no key in the job. */
export const SIGNING_KEY_MISSING_CAUSE =
"no signing key file in the job (is the OMNI_QUEUE_SIGNING_KEY secret set?)";
/**
* The signer of one composition: `config` (git configuration of the commit-tree call) while
* signing works, `cause` once it does not. Never holds anything but the path.
* @param {{keyPath: string|null}} signing
*/
function createSigner(signing) {
const keyPath = typeof signing?.keyPath === "string" ? signing.keyPath : null;
let file = false;
try {
file = keyPath !== null && statSync(keyPath).isFile();
} catch {
file = false;
}
const report = { signed: 0, unsigned: 0, cause: file ? null : SIGNING_KEY_MISSING_CAUSE };
return {
report,
/** The configuration that signs, or null once signing is known not to work. */
config: () =>
report.cause === null
? [
["gpg.format", "ssh"],
["user.signingkey", keyPath],
]
: null,
fail(code) {
// The exit code only: git's message would carry the key path.
report.cause = `git could not sign a merge commit (exit ${code})`;
},
};
}
/** Local refs of the scratch repository (never pushed anywhere). */
export const LOCAL_BASE_REF = "refs/omni-queue/base";
export const localPrRef = (n) => `refs/omni-queue/pr/${n}`;
@@ -282,11 +339,19 @@ export function haveCommonAncestor(git, a, b) {
* The merge commits take their author/committer identity from the Git runner (createGit
* `identity`, the App bot). Their message is built only from validated fields.
*
* `signing` (config landing.signing "ssh"; absent = no signing, and no `signing` field in the
* result): each merge commit is signed with the SSH key at `signing.keyPath`. A key that is not
* there, or a signature git cannot make, leaves that commit and the rest of the batch unsigned,
* byte for byte what the composition is without signing; the result's `signing` says how many
* commits were signed and why the others were not ({signed, unsigned, cause}; cause null when
* every one was signed). A signature changes nothing else: same tree, parents, identity, message.
*
* @param {{git: Git, base: string, baseSha: string, prs: PrRef[], batchId: string,
* heads: Object<number, string|null>}} input heads = fetchInputs().heads
* @returns {ComposeResult}
* heads: Object<number, string|null>, signing?: {keyPath: string|null}|null}} input
* heads = fetchInputs().heads
* @returns {ComposeResult & {signing?: {signed: number, unsigned: number, cause: string|null}}}
*/
export function composeCandidate({ git, base, baseSha, prs, batchId, heads }) {
export function composeCandidate({ git, base, baseSha, prs, batchId, heads, signing = null }) {
if (!isSha(baseSha)) throw new Error("composeCandidate: invalid baseSha");
const g = scratchGit(git);
/** @type {ComposeResult} */
@@ -301,6 +366,23 @@ export function composeCandidate({ git, base, baseSha, prs, batchId, heads }) {
alreadyContained: [],
alreadyInBase: [],
};
const signer = signing ? createSigner(signing) : null;
/** commit-tree of one merge commit: signed while the signer works, else as without signing. */
const commitMerge = (tree, ours, theirs, message) => {
const config = signer?.config();
if (config) {
const args = ["commit-tree", tree, "-p", ours, "-p", theirs, "-S", "-F", "-"];
const res = g.run(args, { input: message, config, allowFail: true });
const sha = res.stdout.trim();
if (res.code === 0 && isSha(sha)) {
signer.report.signed += 1;
return sha;
}
signer.fail(res.code);
}
if (signer) signer.report.unsigned += 1;
return g.out(["commit-tree", tree, "-p", ours, "-p", theirs, "-F", "-"], { input: message });
};
let current = baseSha;
for (const pr of prs ?? []) {
const fetched = heads?.[pr.n] ?? null;
@@ -329,9 +411,7 @@ export function composeCandidate({ git, base, baseSha, prs, batchId, heads }) {
continue;
}
const message = buildMergeMessage({ pr, base, baseSha, batchId });
current = g.out(["commit-tree", merged.tree, "-p", current, "-p", pr.head, "-F", "-"], {
input: message,
});
current = commitMerge(merged.tree, current, pr.head, message);
if (!isSha(current)) throw new Error("git commit-tree returned no commit id");
result.included.push(pr);
}
@@ -342,6 +422,7 @@ export function composeCandidate({ git, base, baseSha, prs, batchId, heads }) {
result.candidateSha = current;
result.treeSha = g.out(["rev-parse", `${current}^{tree}`]);
}
if (signer) result.signing = { ...signer.report };
return result;
}

View File

@@ -15,6 +15,14 @@ export const DEFAULT_CONFIG_PATH = join(ROOT, "config", "merge-queue", "config.j
export const LANDING_MODES = Object.freeze(["merge-ff", "squash-api"]);
export const LANDING_ACTORS = Object.freeze(["app", "owner"]);
export const QUEUE_MODES = Object.freeze(["shadow", "live"]);
/**
* Who performs the queue's human-visible writes (comments and label removals on pull requests,
* the dashboard issue and its comments, comments on the base-red issue, the tree-divergence
* issue): the App's token, or the owner's (OMNI_QUEUE_LAND_TOKEN), see voice.mjs.
*/
export const VOICES = Object.freeze(["app", "owner"]);
/** `landing.signing`: "ssh" signs every merge commit the queue composes (compose.mjs). */
export const SIGNING_MODES = Object.freeze(["none", "ssh"]);
const CONFIG_KEYS = [
"schemaVersion",
@@ -38,7 +46,8 @@ const CONFIG_KEYS = [
];
/** Keys that may be left out: each one has a default (applied by validateConfig). */
const OPTIONAL_CONFIG_KEYS = ["flakyReruns", "prChecksRequired", "lanes"];
const OPTIONAL_CONFIG_KEYS = ["flakyReruns", "prChecksRequired", "lanes", "voice"];
const DEFAULT_VOICE = "app";
/** Keys of `lanes` (both required when `lanes` is present). */
const LANE_KEYS = ["hotfixLabel", "baseRepairLabel"];
/** Re-runs of a red candidate's failed jobs before it is classified (tick onRed): once. */
@@ -60,8 +69,9 @@ const STATUS_CONTEXT_RE = /^[A-Za-z0-9._/-]{1,100}$/;
*/
const LAND_STATUS_PREFIX = "omni-queue/";
const NOREPLY_EMAIL_RE = /^[^\s@]+@users\.noreply\.github\.com$/;
const LANDING_KEYS = ["mode", "actor", "identity", "statusContext"];
const LANDING_KEYS = ["mode", "actor", "identity", "statusContext", "signing"];
const DEFAULT_LANDING_ACTOR = "app";
const DEFAULT_SIGNING = "none";
const DEFAULT_LAND_STATUS_CONTEXT = "omni-queue/land";
function stringList(value, path, errors, { min = 0, item = nonEmptyString } = {}) {
@@ -80,8 +90,10 @@ function positiveInt(value, path, errors, { min = 1, max = Number.MAX_SAFE_INTEG
/**
* Validate the `landing` block, push every problem onto `errors` and return the block with its
* defaults applied (`actor: "app"`, `statusContext: "omni-queue/land"`), or null when `raw` is not
* an object. The returned block is only used when `errors` stays empty.
* defaults applied (`actor: "app"`, `statusContext: "omni-queue/land"`, `signing: "none"`), or
* null when `raw` is not an object. The returned block is only used when `errors` stays empty.
* `signing: "ssh"` needs `actor: "owner"`: the signed commits carry `landing.identity`, and only
* that account can hold the key GitHub verifies them with (an App's bot user has no signing keys).
*/
function validateLanding(raw, errors) {
if (!isRecord(raw)) {
@@ -126,7 +138,15 @@ function validateLanding(raw, errors) {
// An approval context as the land status would make a label approval a blessing.
else if (Object.values(APPROVAL_CONTEXTS).includes(statusContext))
errors.push("landing.statusContext: must not equal an approval context");
return { ...raw, actor, statusContext };
const signing = Object.hasOwn(raw, "signing") ? raw.signing : DEFAULT_SIGNING;
if (!SIGNING_MODES.includes(signing))
errors.push(`landing.signing: expected one of ${SIGNING_MODES.join(", ")}`);
else if (signing === "ssh" && actor !== "owner")
errors.push(
'landing.signing: "ssh" needs landing.actor "owner" (the signed merge commits carry ' +
"landing.identity, whose account holds the signing key)"
);
return { ...raw, actor, statusContext, signing };
}
/**
@@ -183,9 +203,11 @@ function validateLanes(raw, errors) {
* startSize (optional, default maxSize), halves after
* a red root batch and grows by one after a full one
* lands; without it every batch is up to maxSize
* @property {{mode: "merge-ff"|"squash-api", actor: "app"|"owner", identity?: {name: string, email: string}, statusContext: string}} landing
* @property {{mode: "merge-ff"|"squash-api", actor: "app"|"owner", identity?: {name: string, email: string}, statusContext: string, signing: "none"|"ssh"}} landing
* actor "owner" lands with `identity` (a noreply address);
* statusContext is the commit status the queue publishes
* statusContext is the commit status the queue publishes;
* signing (optional, default "none"): "ssh" signs every
* merge commit the queue composes (owner actor only)
* @property {string[]} requiredChecks check names that must be `success` on the candidate
* @property {string[]} advisoryChecks check names whose failure is tolerated
* @property {string[]} aggregateChecks always() gate checks that fail whenever a job they
@@ -205,6 +227,8 @@ function validateLanes(raw, errors) {
* FIFO; a base-repair PR alone too, and it is the
* only thing a base-red pause processes
* @property {"shadow"|"live"} mode
* @property {"app"|"owner"} voice optional, default "app": whose token posts the queue's
* comments, removes its labels and writes its issues
*/
/**
@@ -320,6 +344,8 @@ export function validateConfig(raw) {
const lanes = validateLanes(raw, errors);
if (!QUEUE_MODES.includes(raw.mode))
errors.push(`mode: expected one of ${QUEUE_MODES.join(", ")}`);
const voice = Object.hasOwn(raw, "voice") ? raw.voice : DEFAULT_VOICE;
if (!VOICES.includes(voice)) errors.push(`voice: expected one of ${VOICES.join(", ")}`);
return errors.length
? { ok: false, config: null, errors }
: {
@@ -331,6 +357,7 @@ export function validateConfig(raw) {
flakyReruns,
prChecksRequired,
lanes,
voice,
}),
errors: [],
};

View File

@@ -4,6 +4,9 @@
// - Credentials travel in the environment (GIT_CONFIG_COUNT/KEY/VALUE → http extraheader), never
// in argv or in the remote URL, and every error message is redacted before it is thrown. The
// tick's OMNI_QUEUE_TOKEN / OMNI_QUEUE_LAND_TOKEN are removed from every git child's environment.
// - Configuration a single command needs (the signing key of a merge commit: compose.mjs) also
// travels as GIT_CONFIG_* entries of that command's environment (run option `config`), never as
// `-c` arguments: argv is logged, the environment is not.
// - Synchronous: one tick is a short, sequential script.
import { spawnSync } from "node:child_process";
@@ -47,6 +50,25 @@ function withoutTokens(env) {
return out;
}
/**
* `env` plus `entries` ([key, value] pairs) appended to its GIT_CONFIG_COUNT/KEY_n/VALUE_n list
* (the token's http header, when there is one, keeps index 0). Git reads these as command-line
* configuration of that one process.
* @param {object} env
* @param {[string, string][]} entries
*/
export function withConfigEntries(env, entries) {
if (!entries?.length) return env;
const count = Number.parseInt(env.GIT_CONFIG_COUNT ?? "", 10);
const start = Number.isSafeInteger(count) && count > 0 ? count : 0;
const out = { ...env, GIT_CONFIG_COUNT: String(start + entries.length) };
entries.forEach(([key, value], i) => {
out[`GIT_CONFIG_KEY_${start + i}`] = key;
out[`GIT_CONFIG_VALUE_${start + i}`] = value;
});
return out;
}
/**
* @typedef {object} GitResult
* @property {number|null} code
@@ -57,8 +79,11 @@ function withoutTokens(env) {
/**
* @typedef {object} Git
* @property {string} cwd
* @property {(args: string[], opts?: {allowFail?: boolean, input?: string, env?: object}) => GitResult} run
* @property {(args: string[], opts?: {input?: string, env?: object}) => string} out stdout trimmed; throws GitError
* @property {(args: string[], opts?: {allowFail?: boolean, input?: string, env?: object,
* config?: [string, string][]}) => GitResult} run config: git configuration of this
* one command, passed through the environment (withConfigEntries), never logged
* @property {(args: string[], opts?: {input?: string, env?: object,
* config?: [string, string][]}) => string} out stdout trimmed; throws GitError
*/
/**
@@ -88,12 +113,13 @@ export function createGit({ cwd, token, env = {}, identity, log = () => {} }) {
...env,
});
function run(args, { allowFail = false, input, env: extra } = {}) {
function run(args, { allowFail = false, input, env: extra, config } = {}) {
const shown = args.map(redact);
log(`git ${shown.join(" ")}`);
const env = extra ? withoutTokens({ ...baseEnv, ...extra }) : baseEnv;
const res = spawnSync("git", args, {
cwd,
env: extra ? withoutTokens({ ...baseEnv, ...extra }) : baseEnv,
env: withConfigEntries(env, config),
input,
encoding: "utf8",
maxBuffer: 256 * 1024 * 1024,

View File

@@ -81,18 +81,24 @@ export class GitHubError extends Error {
* @property {(n: number) => Promise<{id: number, body: string, author: string,
* createdAt: string}[]>} listIssueComments
* @property {(n: number, body: string) => Promise<{id: number}>} createIssueComment
* @property {(n: number, key: string, body: string) => Promise<{posted: boolean}>} commentOnce
* @property {(n: number, key: string, body: string, opts?: {reader?: GitHubClient|null,
* alsoLogins?: string[]}) => Promise<{posted: boolean}>} commentOnce
* posts `body + "\n\n" + contracts.commentMarker(key)` unless a comment on issue/PR n
* already contains that marker (then {posted:false}). The ONLY way queue code comments.
* After posting it re-reads the comments: when two writers raced (approval job + tick,
* or a POST replayed after a 5xx), the lowest comment id wins and the newer duplicate
* this call created is deleted ({posted:false}).
* this call created is deleted ({posted:false}). opts (owner voice, voice.mjs):
* `reader` = the client that lists the comments (the App's: every read stays the
* App's), the POST and DELETE stay this client's; `alsoLogins` = more logins whose
* markers count next to botLogin (the owner's login, read from the owner's token)
* @property {(commentId: number) => Promise<void>} deleteIssueComment 404 = already gone
* @property {(opts: {labels?: string[], state?: "open"|"closed"|"all"}) => Promise<{number: number,
* title: string, body: string, labels: string[], state: string,
* updatedAt: string}[]>} listIssues issues only (PRs filtered out)
* @property {(input: {title: string, body: string, labels?: string[]}) => Promise<{number: number}>} createIssue
* @property {(n: number, patch: {title?: string, body?: string, state?: string}) => Promise<void>} updateIssue
* @property {() => Promise<string>} getAuthenticatedLogin GET /user: the login of the token's
* own account ("" when the answer names none); voice.mjs reads the owner's with it
*
* — commits / checks / statuses —
* @property {(branch: string) => Promise<string|null>} getBranchSha null when absent
@@ -439,7 +445,9 @@ function errorMessage(data, fallback) {
* baseDelayMs/maxDelayMs/nowMs tune the backoff (tests); maxDelayMs (default 120 s) is also
* the longest Retry-After / rate-limit reset wait honored: a longer one throws at once;
* botLogin, when set, makes commentOnce
* count only markers in comments authored by that login (a third party cannot pre-post one);
* count only markers in comments authored by that login, or by a login its caller adds
* (`alsoLogins`: the owner's, read from the owner's own token): a third party cannot pre-post
* one;
* requestTimeoutMs (default 30 s) aborts a hung request, which then counts as a network error.
* @returns {GitHubClient}
*/
@@ -682,19 +690,25 @@ export function createGitHubClient(options) {
deleteIssueComment,
async commentOnce(n, key, body) {
async commentOnce(n, key, body, { reader = null, alsoLogins = [] } = {}) {
const marker = commentMarker(key);
const ours = (c) => c.body.includes(marker) && (!botLogin || c.author === botLogin);
if ((await listIssueComments(n)).some(ours)) return { posted: false };
// Logins whose markers are the queue's own: the App's, and the owner's under the owner
// voice. Exact logins only, as GitHub returns them; nobody else's marker ever counts.
const trusted = botLogin ? new Set([botLogin, ...alsoLogins.filter(Boolean)]) : null;
const ours = (c) => c.body.includes(marker) && (!trusted || trusted.has(c.author));
// Under the owner voice the App's client reads, this (the owner's) client writes.
const list = reader ? (m) => reader.listIssueComments(m) : listIssueComments;
if ((await list(n)).some(ours)) return { posted: false };
const { id } = await createIssueComment(n, `${body}\n\n${marker}`);
// Read-then-write is not atomic: another writer may have posted the same marker meanwhile,
// and each POST replayed after a 5xx may have left one more copy. The lowest id wins; drop
// every newer copy written by our login (never a comment of someone else).
const found = (await listIssueComments(n)).filter(ours).sort((a, b) => a.id - b.id);
// every newer copy written by a trusted login (never a comment of someone else).
const found = (await list(n)).filter(ours).sort((a, b) => a.id - b.id);
const winner = found[0]?.id;
if (winner === undefined || id === undefined) return { posted: true };
const self = botLogin ?? found.find((c) => c.id === id)?.author;
const extra = found.filter((c) => c.id !== winner && (c.id === id || c.author === self));
const self = found.find((c) => c.id === id)?.author;
const mine = (c) => (trusted ? trusted.has(c.author) : c.author === self);
const extra = found.filter((c) => c.id !== winner && (c.id === id || mine(c)));
for (const c of extra) await deleteIssueComment(c.id);
if (extra.length) {
const ids = extra.map((c) => c.id).join(", ");
@@ -722,6 +736,11 @@ export function createGitHubClient(options) {
await request("PATCH", r(`/issues/${n}`), { body: patch });
},
async getAuthenticatedLogin() {
const { data } = await request("GET", "/user");
return typeof data?.login === "string" ? data.login : "";
},
async getBranchSha(branch) {
const res = await request("GET", r(`/git/ref/heads/${encodePath(branch)}`), {
allowStatuses: [404],

View File

@@ -169,6 +169,10 @@ export function mergedPrsBetween(git, expectedBaseSha, candidateSha) {
* key, in any paragraph, is refused rather than resolved). The chain is read with each commit's
* whole message, as the CI reads it; output that cannot be split into whole commits is a
* mismatch. The subject, the author trailer and the commit identity are not checked.
* Nor is a signature (config landing.signing "ssh"): every read here is of the tree, the parents
* and the message (%B, which never holds the gpgsig header), so a signed candidate verifies
* exactly as the unsigned composition of the same inputs, and a signature never makes a commit
* with another tree, parents or trailers pass.
*
* @param {{git: Git, expectedBaseSha: string, candidateSha: string, prs: PrRef[],
* treeSha?: string|null, trees?: boolean}} input the commits must be in the scratch

View File

@@ -14,10 +14,13 @@
// pull-requests: write is used by a squash-api landing (mergePull) only:
// labels and comments on a PR go through the issues endpoints
// GITHUB_REPOSITORY owner/repo
// OMNI_QUEUE_LAND_TOKEN the repository owner's token, used ONLY by the landing itself (the
// merge-ff push or the squash-api merges) when landing.actor is "owner";
// everything else, the land status included, uses OMNI_QUEUE_TOKEN.
// Optional: without it shadow mode runs and a live landing pauses.
// OMNI_QUEUE_LAND_TOKEN the repository owner's token, used by the landing itself (the
// merge-ff push or the squash-api merges) when landing.actor is "owner",
// and, when config.voice is "owner", by the queue's human-visible writes
// (voice.mjs: comments, label removals, the dashboard and other issues;
// its GET /user names the owner's login). Everything else, the land
// status included, uses OMNI_QUEUE_TOKEN. Optional: without it shadow
// mode runs, a live landing pauses and the voice falls back to the App.
// OMNI_QUEUE_GIT_NAME, OMNI_QUEUE_GIT_EMAIL TESTS/SANDBOX ONLY: identity for queue merge
// commits, over everything else. Without it: landing.identity when
// landing.actor is "owner", else OMNI_QUEUE_BOT_NAME +
@@ -27,7 +30,11 @@
// it (the re-runner of a re-run, whose inputs stay the dispatcher's): a
// bless is honoured only when BOTH are logins of config.approvers
// OMNI_QUEUE_CONFIG optional path to an alternative config file (sandbox)
// RUNNER_TEMP scratch directory for the bare compose repository
// RUNNER_TEMP scratch directory for the bare compose repository; with
// config.landing.signing "ssh", the merge-commit signing key is read
// from compose.signingKeyPath(RUNNER_TEMP), written there by the
// workflow from the OMNI_QUEUE_SIGNING_KEY secret (never this process's
// environment); no file = the batch is composed unsigned, one `error` event
// GITHUB_SERVER_URL, GITHUB_RUN_ID for run links in history/dashboard
// GITHUB_API_URL REST API root (default https://api.github.com; GHES / tests)
// OMNI_QUEUE_REMOTE_URL TESTS/SANDBOX ONLY: git remote of the repository instead of
@@ -142,6 +149,11 @@
// mode would have done is recorded instead: `culprit-found` (with a shadow note) and
// `would-dequeue` events, and the head is remembered in state.shadow.processed so it is not
// batched again. Issues the queue owns (dashboard, base-red notice) are still written.
//
// OWNER VOICE (config.voice "owner", voice.mjs): those two, every issue comment (comment) and the
// dashboard and divergence issues go out with the owner's token, each retried with the App's on a
// missing token or a 401/403, recorded once per tick (voiceFallback). Statuses, refs, the state
// branch, re-runs and every read stay the App's.
import { mkdirSync } from "node:fs";
import { tmpdir } from "node:os";
@@ -190,6 +202,13 @@ import { createGitHubClient } from "./github.mjs";
import * as landModule from "./land.mjs";
import { readQueueRefsProtection } from "./refs-guard.mjs";
import { StateConflictError, createStateStore, updateStateWithRetry } from "./state.mjs";
import {
VOICE_FALLBACK_PREFIX,
createOwnerLoginReader,
createOwnerVoice,
voiceFallbackDetail,
voiceFallbackNote,
} from "./voice.mjs";
import { WATCHDOG_LIMIT_MINUTES } from "./watchdog.mjs";
export { StateConflictError };
@@ -223,6 +242,13 @@ export class UnmanagedBaseError extends Error {}
* OMNI_QUEUE_LAND_TOKEN, or null when that token is not set
* @property {object|null} landGh client of the squash-api landing: gh itself when
* landing.actor is "app"; with "owner", one with OMNI_QUEUE_LAND_TOKEN, or null without it
* @property {object|null} [voiceGh] config.voice "owner": the client with
* OMNI_QUEUE_LAND_TOKEN that performs the human-visible writes (voice.mjs); null otherwise or
* without the token (the App writes, the fallback is recorded)
* @property {(() => Promise<string>)|null} [ownerLogin] the owner's login read from that token
* (voice.createOwnerLoginReader); null without voiceGh
* @property {{keyPath: string|null}|null} [signing] config.landing.signing "ssh": the signing
* key file of every merge commit (compose.composeCandidate `signing`); null = no signing
* @property {string} repoDir scratch dir for the bare compose repository
* @property {string} remoteUrl https://github.com/<owner>/<repo>.git
* @property {string|null} [fetchFilter] partial-clone filter for the scratch repository
@@ -580,6 +606,25 @@ class Tick {
? readOnlyGitHub(landGh, this.violations)
: landGh;
this.landGit = null;
/**
* The client of the human-visible writes: the App's own (config.voice "app"), or the owner
* voice (voice.mjs), whose fallbacks to the App's token are recorded by voiceFallback.
*/
this.voice =
this.config.voice === "owner"
? createOwnerVoice({
app: this.gh,
owner: deps.voiceGh
? this.dryRun
? readOnlyGitHub(deps.voiceGh, this.violations)
: deps.voiceGh
: null,
ownerLogin: deps.ownerLogin ?? null,
onFallback: (cause, what) => this.voiceFallback(cause, what),
})
: this.gh;
/** True once this tick recorded a fallback of the owner voice (voiceFallback). */
this.voiceFellBack = false;
this.m = { ...DEFAULT_MODULES, ...(deps.modules ?? {}) };
this.decisions = [];
/** PRs whose queue label this tick removed (GitHub may still list them for a while). */
@@ -738,10 +783,30 @@ class Tick {
return this.s.history.some(predicate);
}
/** Comment on an issue the queue owns (base-red notice, divergence): written in every mode. */
/**
* Comment on an issue the queue owns (base-red notice, divergence, dashboard): written in every
* mode, with the configured voice (this.voice).
*/
async comment(n, key, body) {
if (this.dryRun) return this.note(`would comment on #${n} (${key})`);
await this.gh.commentOnce(n, key, body);
await this.voice.commentOnce(n, key, body);
}
/**
* The owner voice wrote `what` with the App's token for `cause` (voice.mjs: no owner token, or
* GitHub refused it). Every fallback is a note; the first of the tick is also an `error` event,
* unless the newest such event already says exactly this (a token missing for days must not
* add an event, and with it a dashboard change and one more fallback, on every tick).
*/
voiceFallback(cause, what) {
this.note(voiceFallbackNote(what, cause));
if (this.voiceFellBack || !this.s) return;
this.voiceFellBack = true;
const detail = voiceFallbackDetail(cause);
const last = this.s.history.findLast(
(e) => e.type === "error" && String(e.detail ?? "").startsWith(VOICE_FALLBACK_PREFIX)
);
if (last?.detail !== detail) this.event("error", { detail });
}
/** Comment on a PULL REQUEST: never in shadow mode. */
@@ -755,7 +820,7 @@ class Tick {
if (this.shadow) return this.note(`shadow: label "${label}" kept on #${n}`);
this.touched.add(n);
if (this.dryRun) return this.note(`would remove label "${label}" from #${n}`);
await this.gh.removeLabel(n, label);
await this.voice.removeLabel(n, label);
}
/**
@@ -2407,7 +2472,7 @@ class Tick {
let issue = existing?.number ?? null;
if (existing) await this.comment(existing.number, `divergence:${f.batchId}`, body);
else if (this.dryRun) this.note(`would open issue "${title}"`);
else issue = (await this.gh.createIssue({ title, body, labels: [DASHBOARD_LABEL] })).number;
else issue = (await this.voice.createIssue({ title, body, labels: [DASHBOARD_LABEL] })).number;
this.setPaused({
reason: "tree-divergence",
since: this.now(),
@@ -3283,7 +3348,17 @@ class Tick {
prs,
batchId,
heads,
...(this.deps.signing ? { signing: this.deps.signing } : {}),
});
// Signing asked for and not (fully) done: the batch goes on unsigned (never blocked), and the
// operator is told once per batch. The cause names no key material and no path.
if (result.signing && result.signing.unsigned > 0) {
const detail =
`${batchId}: ${result.signing.unsigned} merge commit(s) composed unsigned: ` +
String(result.signing.cause ?? "unknown cause");
this.event("error", { batchId, detail });
this.note(detail);
}
for (const pr of result.excludedBaseConflict ?? []) {
if (this.shadow) {
this.wouldDequeue(pr, "base-conflict", batchId);
@@ -3851,7 +3926,7 @@ class Tick {
return null;
}
try {
return await this.m.dashboard.upsertDashboard({ gh: this.gh, base: this.base, body });
return await this.m.dashboard.upsertDashboard({ gh: this.voice, base: this.base, body });
} catch (error) {
// Cosmetic: never let the dashboard block the state save of real transitions.
this.note(`dashboard update failed: ${error.message}`);
@@ -4076,7 +4151,7 @@ export async function recordTickFailure(deps, base, detail, warn = () => {}, rec
// A base whose stored withdrawals are its only work is found by the next scheduled tick
// through its open dashboard issue (discoverBases): one is created when none is open.
try {
await dashboardIssueOf(deps, base, saved);
await dashboardIssueOf(deps, base, saved, voiceOf(deps, warn));
} catch (error) {
warn(`dashboard of a base with stored withdrawals not created: ${error.message}`);
}
@@ -4461,7 +4536,7 @@ export function amendFailedTick(state, record, options) {
* @param {QueueState} state
* @returns {Promise<number>}
*/
async function dashboardIssueOf(deps, base, state) {
async function dashboardIssueOf(deps, base, state, voice = deps.gh) {
const issue = await findDashboard({ gh: deps.gh, base });
if (issue !== null) return issue;
const body = renderDashboard({
@@ -4473,7 +4548,23 @@ async function dashboardIssueOf(deps, base, state) {
runUrl: deps.runUrl ?? null,
repository: deps.repository,
});
return createDashboard({ gh: deps.gh, base, body });
return createDashboard({ gh: voice, base, body });
}
/**
* The client of the human-visible writes outside a Tick (main()'s failure path): deps.gh with
* config.voice "app", else the owner voice, whose fallbacks to the App's token go to `warn`.
* @param {TickDeps} deps
* @param {(message: string) => void} warn
*/
function voiceOf(deps, warn) {
if (deps.config.voice !== "owner") return deps.gh;
return createOwnerVoice({
app: deps.gh,
owner: deps.voiceGh ?? null,
ownerLogin: deps.ownerLogin ?? null,
onFallback: (cause, what) => warn(voiceFallbackNote(what, cause)),
});
}
/**
@@ -4492,9 +4583,10 @@ async function dashboardIssueOf(deps, base, state) {
async function deliverStalledAlert(deps, base, state, warn) {
const episode = state.stalled;
const key = stalledKey(episode.since);
const voice = voiceOf(deps, warn);
try {
const issue = await dashboardIssueOf(deps, base, state);
await deps.gh.commentOnce(
const issue = await dashboardIssueOf(deps, base, state, voice);
await voice.commentOnce(
issue,
key,
stalledComment({ base, stalled: episode, config: deps.config })
@@ -4658,8 +4750,9 @@ export function parseArgs(argv) {
/**
* Build the TickDeps exactly as the CLI does, from the environment (see the header). The GitHub
* client counts only comment markers written by `${config.appSlug}[bot]`, so a third party
* cannot pre-post a marker to mute a queue comment.
* client counts only comment markers written by `${config.appSlug}[bot]` (and, with the owner
* voice, by the owner's login read from OMNI_QUEUE_LAND_TOKEN itself), so a third party cannot
* pre-post a marker to mute a queue comment.
* @param {object} env process.env-like
* @param {{now?: () => string, log?: (msg: string) => void, gitEnv?: object}} [overrides]
* tests only: injected clock, logger and extra environment for every git process
@@ -4700,25 +4793,28 @@ export function createTickDeps(env, overrides = {}) {
const remoteUrl = env.OMNI_QUEUE_REMOTE_URL || `${serverUrl}/${repository}.git`;
const gitEnv = overrides.gitEnv ?? {};
const gitFor = (cwd) => createGit({ cwd, token, identity, log, env: gitEnv });
// The owner's token, when landing as the owner: never an error here (shadow runs without it);
// a live landing without it pauses (Tick.landOrWouldLand).
const landToken = owner ? env.OMNI_QUEUE_LAND_TOKEN || null : null;
// The owner's token, when landing as the owner or speaking as the owner: never an error here
// (shadow runs without it, the voice falls back to the App); a live landing without it pauses
// (Tick.landOrWouldLand).
const ownerVoice = config.voice === "owner";
const ownerToken = owner || ownerVoice ? env.OMNI_QUEUE_LAND_TOKEN || null : null;
const landToken = owner ? ownerToken : null;
const landGitFor = !owner
? gitFor
: landToken
? (cwd) => createGit({ cwd, token: landToken, identity, log, env: gitEnv })
: null;
const landGh = !owner
? gh
: landToken
? createGitHubClient({
token: landToken,
repository,
apiUrl: env.GITHUB_API_URL || undefined,
botLogin: `${config.appSlug}[bot]`,
log,
})
: null;
const ownerGh = ownerToken
? createGitHubClient({
token: ownerToken,
repository,
apiUrl: env.GITHUB_API_URL || undefined,
botLogin: `${config.appSlug}[bot]`,
log,
})
: null;
const landGh = !owner ? gh : ownerGh;
const voiceGh = ownerVoice ? ownerGh : null;
return {
config,
gh,
@@ -4726,6 +4822,13 @@ export function createTickDeps(env, overrides = {}) {
gitFor,
landGitFor,
landGh,
voiceGh,
ownerLogin: createOwnerLoginReader(voiceGh),
// The key file the workflow wrote (never the key itself); missing = composed unsigned.
signing:
config.landing.signing === "ssh"
? { keyPath: composeModule.signingKeyPath(env.RUNNER_TEMP) }
: null,
repoDir,
remoteUrl,
// A local or file remote cannot serve a partial clone reliably: fetch everything.

View File

@@ -0,0 +1,156 @@
// scripts/merge-queue/voice.mjs — who performs the queue's human-visible writes (config `voice`).
//
// With `voice: "app"` (the default) the tick uses the App's client for everything, as before; this
// module is not involved. With `voice: "owner"` the writes people read on GitHub go out with the
// owner's token (OMNI_QUEUE_LAND_TOKEN, the token the tick already holds for the landing):
// - every comment the tick posts on a pull request, and every label it removes from one;
// - the dashboard issue: opening it, updating its body, its comments (the stalled alert too);
// - comments on the base-red issue, and the tree-divergence issue if the tick opens one.
// Everything else stays the App's: commit statuses (omni-queue/land, the approvals, a bless),
// candidate branches, the omni-queue-state branch, re-runs of workflow jobs, and every read.
//
// NEVER LOSE A MESSAGE. The owner's token absent, or a 401/403 from GitHub on an owner write (or
// on reading the owner's login): the same write is made with the App's token, and the caller is
// told through `onFallback` (the tick records it once per tick, see Tick.voiceFallback). Any other
// error (a 5xx, a timeout) is thrown as the App's own errors are: the next tick redoes the write,
// whose idempotence (commentOnce markers, an absent label, the dashboard upsert) is unchanged.
//
// The queue recognises its own comments by their marker AND their author (github.commentOnce).
// Under the owner voice the owner's login counts too. That login is read from the owner's token
// itself (GET /user, once per process), never from configuration or any other text.
//
// Zero-dependency on purpose, like every module the queue workflow runs.
import { VOICES } from "./config.mjs";
export { VOICES };
/** Start of the `error` event detail that records a fallback (one per tick, Tick.voiceFallback). */
export const VOICE_FALLBACK_PREFIX = "owner voice unavailable";
/** The `error` event detail of a fallback whose cause is `cause`. */
export const voiceFallbackDetail = (cause) =>
`${VOICE_FALLBACK_PREFIX}, written with the App's token instead: ${cause}`;
/** The one-line note (log, decisions) of the write `what` that fell back for `cause`. */
export const voiceFallbackNote = (what, cause) =>
`owner voice: ${what} written with the App's token (${cause})`;
/** A user login (never a bot's: `[bot]` and anything else is refused). */
const USER_LOGIN_RE = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/;
/** The owner's token is not there: the tick runs without OMNI_QUEUE_LAND_TOKEN. */
export const NO_OWNER_TOKEN_CAUSE = "OMNI_QUEUE_LAND_TOKEN is not set";
/** GitHub's answer that a credential cannot make this call (bad token, missing permission). */
const isRefusal = (error) => error?.status === 401 || error?.status === 403;
/** A reason to write as the App, carried from the login read to the write. */
class Fallback extends Error {}
/**
* The owner's login, read once from the owner's token (GET /user) and remembered for the life of
* the process; a refusal (401/403) is remembered too, so a dead token is not asked again on every
* write. Any other failure (a 5xx, a timeout) is not remembered: the next call reads again.
* @param {{getAuthenticatedLogin: () => Promise<string>}|null} ownerGh
* @returns {(() => Promise<string>)|null} null without a client
*/
export function createOwnerLoginReader(ownerGh) {
if (!ownerGh) return null;
let settled = null;
return () => {
if (!settled) {
settled = ownerGh.getAuthenticatedLogin().catch((error) => {
if (!isRefusal(error)) settled = null;
throw error;
});
}
return settled;
};
}
/**
* The client of the owner voice: the writes listed above with the owner's client, each one
* retried with the App's on a refusal; reads with the App's client.
* @param {{app: object, owner: object|null, ownerLogin: (() => Promise<string>)|null,
* onFallback?: (cause: string, what: string) => void}} input
* app = the App's client (github.mjs); owner = the owner's, null when OMNI_QUEUE_LAND_TOKEN is
* not set; ownerLogin = createOwnerLoginReader(owner)
* @returns {{listIssues: Function, commentOnce: Function, removeLabel: Function,
* createIssue: Function, updateIssue: Function}}
*/
export function createOwnerVoice({ app, owner, ownerLogin, onFallback = () => {} }) {
/** The owner's login, or a Fallback naming why the App writes instead. */
async function login() {
if (!owner || !ownerLogin) throw new Fallback(NO_OWNER_TOKEN_CAUSE);
let value;
try {
value = await ownerLogin();
} catch (error) {
if (!isRefusal(error)) throw error;
throw new Fallback(`GitHub refused the owner's token reading its login (${error.status})`);
}
if (typeof value !== "string" || !USER_LOGIN_RE.test(value)) {
throw new Fallback("the owner's token does not name a user account");
}
return value;
}
/**
* One write: with the owner's client, else (no token, a refusal) with the App's. `asApp`
* receives the owner's login when it is known (null otherwise).
*/
async function write(what, asOwner, asApp) {
let known;
try {
known = await login();
} catch (error) {
if (!(error instanceof Fallback)) throw error;
onFallback(error.message, what);
return asApp(null);
}
try {
return await asOwner(known);
} catch (error) {
if (!isRefusal(error)) throw error;
onFallback(`GitHub refused the owner's token (${error.status})`, what);
return asApp(known);
}
}
return {
listIssues: (...args) => app.listIssues(...args),
commentOnce: (n, key, body) =>
write(
`comment ${key} on #${n}`,
(known) => owner.commentOnce(n, key, body, { reader: app, alsoLogins: [known] }),
// The App's retry still counts the owner's earlier markers when the login is known.
(known) =>
known
? app.commentOnce(n, key, body, { alsoLogins: [known] })
: app.commentOnce(n, key, body)
),
removeLabel: (n, label) =>
write(
`label "${label}" removed from #${n}`,
() => owner.removeLabel(n, label),
() => app.removeLabel(n, label)
),
createIssue: (input) =>
write(
`issue "${input?.title ?? ""}" opened`,
() => owner.createIssue(input),
() => app.createIssue(input)
),
updateIssue: (n, patch) =>
write(
`issue #${n} updated`,
() => owner.updateIssue(n, patch),
() => app.updateIssue(n, patch)
),
};
}

View File

@@ -11,6 +11,7 @@ import {
getConfiguredLocalCorpusStatus,
resetLocalCorpusIndex,
} from "@/lib/localCorpus/configured";
import { requireOperatorCredential } from "@/lib/api/operatorCredential";
import { isAuthenticated } from "@/shared/utils/apiAuth";
import { sanitizeErrorMessage } from "@omniroute/open-sse/utils/error";
@@ -20,6 +21,11 @@ const localCorpusSchema = z
})
.strict();
// CodeQL #1371: the root is indexed and served by the MCP local-corpus search tools, so choosing
// it is an operator action. A machine credential (an API key of any scope) gets 403.
const LOCAL_CORPUS_ROOT_FORBIDDEN_MESSAGE =
"Choosing the local corpus root requires a signed-in dashboard session or the local CLI; API keys and access tokens cannot change it.";
export async function GET(request: NextRequest) {
if (!(await isAuthenticated(request))) {
return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
@@ -40,6 +46,10 @@ export async function POST(request: NextRequest) {
if (!(await isAuthenticated(request))) {
return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
}
const operatorVerdict = await requireOperatorCredential(request, {
forbiddenMessage: LOCAL_CORPUS_ROOT_FORBIDDEN_MESSAGE,
});
if (operatorVerdict.ok === false) return operatorVerdict.response;
let body: unknown;
try {

View File

@@ -2,6 +2,7 @@ import { NextRequest, NextResponse } from "next/server";
import { z } from "zod";
import { isAuthenticated } from "@/shared/utils/apiAuth";
import { requireManagementAuth } from "@/lib/api/requireManagementAuth";
import { requireOperatorCredential } from "@/lib/api/operatorCredential";
import { buildErrorBody } from "@omniroute/open-sse/utils/error";
import {
getObsidianSyncStatus,
@@ -15,6 +16,12 @@ const enableSchema = z
})
.strict();
// CodeQL #1372/#1373: the vault becomes the root of a read/write WebDAV service with freshly
// minted credentials, so choosing it is an operator action. The route is ALWAYS_PROTECTED, so an
// open instance (login disabled) does not make a machine credential the operator either.
const WEBDAV_VAULT_FORBIDDEN_MESSAGE =
"Choosing the WebDAV vault requires a signed-in dashboard session or the local CLI; API keys and access tokens cannot change it.";
export async function GET(request: NextRequest) {
if (!(await isAuthenticated(request))) {
return NextResponse.json(buildErrorBody(401, "Authentication required"), { status: 401 });
@@ -32,8 +39,7 @@ export async function GET(request: NextRequest) {
return NextResponse.json({
webdavEnabled: status.webdavEnabled,
webdavUsername: status.webdavEnabled ? status.webdavUsername : null,
webdavPassword:
status.webdavEnabled && hasManagement ? status.webdavPassword : null,
webdavPassword: status.webdavEnabled && hasManagement ? status.webdavPassword : null,
webdavPasswordSet: status.webdavEnabled && Boolean(status.webdavPassword),
vaultPath: status.vaultPath,
});
@@ -47,6 +53,11 @@ export async function POST(request: NextRequest) {
if (!(await isAuthenticated(request))) {
return NextResponse.json(buildErrorBody(401, "Authentication required"), { status: 401 });
}
const operatorVerdict = await requireOperatorCredential(request, {
forbiddenMessage: WEBDAV_VAULT_FORBIDDEN_MESSAGE,
alwaysRequireAuth: true,
});
if (operatorVerdict.ok === false) return operatorVerdict.response;
let rawBody: unknown;
try {
@@ -57,10 +68,7 @@ export async function POST(request: NextRequest) {
const parsed = enableSchema.safeParse(rawBody);
if (!parsed.success) {
return NextResponse.json(
buildErrorBody(400, "Missing or invalid vaultPath"),
{ status: 400 }
);
return NextResponse.json(buildErrorBody(400, "Missing or invalid vaultPath"), { status: 400 });
}
const result = await enableObsidianVaultSync(parsed.data.vaultPath);

View File

@@ -0,0 +1,79 @@
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
/**
* System directories that must never become the root of a host-filesystem surface (the local
* corpus indexed for the MCP search tools, the read/write Obsidian WebDAV vault). The directory
* itself and everything below it are refused, unless the canonical path lives inside the user's
* home directory (a service account whose home is `/root` or `/var/lib/<app>` keeps its folders).
* POSIX only: on Windows the drive root and the home directory itself are refused.
*/
const POSIX_SYSTEM_DIRECTORIES = [
"/etc",
"/usr",
"/bin",
"/sbin",
"/var",
"/proc",
"/sys",
"/dev",
"/boot",
"/root",
] as const;
/** Fixed refusal message: it never echoes the requested path back to the caller. */
export const DENIED_ROOT_DIRECTORY_ERROR =
"This directory cannot be used as a root: choose a dedicated folder, not the filesystem root, the home directory itself or a system directory";
/** Canonical (symlink-resolved) absolute form of a path; falls back to the lexical resolve. */
function canonicalPath(target: string): string {
const resolved = path.resolve(target);
try {
return fs.realpathSync.native(resolved);
} catch {
return resolved;
}
}
/** True when `child` is `parent` itself or lives anywhere below it. */
function isSameOrInside(parent: string, child: string): boolean {
const rel = path.relative(parent, child);
if (rel === "") return true;
if (path.isAbsolute(rel)) return false; // different drive (win32)
return rel !== ".." && !rel.startsWith(`..${path.sep}`);
}
function isFilesystemRoot(target: string): boolean {
return path.parse(target).root === target;
}
/**
* Is `candidate` a directory that must not be exposed as a corpus or vault root? Both the lexical
* (`path.resolve`) and canonical (`realpath`) forms are checked, so a symlink cannot dodge the
* comparison in either direction. Refused: the filesystem root (`/`, a drive root on Windows), the
* user's home directory itself (its subfolders stay allowed) and the POSIX system directories
* above.
*/
export function isDeniedRootDirectory(candidate: string): boolean {
const lexical = path.resolve(candidate);
const canonical = canonicalPath(candidate);
const forms = lexical === canonical ? [canonical] : [lexical, canonical];
if (forms.some(isFilesystemRoot)) return true;
const homeForms = [path.resolve(os.homedir()), canonicalPath(os.homedir())];
if (forms.some((form) => homeForms.includes(form))) return true;
if (process.platform === "win32") return false;
const canonicalHome = homeForms[1];
if (isFilesystemRoot(canonicalHome) === false && isSameOrInside(canonicalHome, canonical)) {
return false;
}
return POSIX_SYSTEM_DIRECTORIES.some((dir) => {
const dirForms = [dir, canonicalPath(dir)];
return dirForms.some((dirForm) => forms.some((form) => isSameOrInside(dirForm, form)));
});
}

View File

@@ -7,6 +7,7 @@ import { fetchRemoteImage } from "@/shared/network/remoteImageFetch";
import { getGuardedDispatcher } from "@omniroute/open-sse/utils/connectGuardDispatcher";
import { getRuntimePorts } from "@/lib/runtime/ports";
import { resolveSelfLoopBearer } from "@/shared/middleware/chatBodyAdmission";
import { ownListenerSelfHopToken, SELF_HOP_HEADER } from "@omniroute/open-sse/utils/selfHop";
import { getBestVisionModel, getFallbackModels, recordLatency } from "./visionBridgeRouter";
import { combineCredentialChecks } from "./visionBridgeKeyScope";
import { REGISTRY } from "@omniroute/open-sse/config/providers";
@@ -818,10 +819,10 @@ async function callVisionModelSingle(
// When routing through OmniRoute's own API, omit the vision-bridge
// guardrail on the sub-request to prevent infinite recursion.
// OmniRoute's own listener authenticates the self-loop bearer (the env key or the
// per-process secret, both accepted by API-key validation), which the admission
// bypass below also requires. Any other endpoint — api.openai.com, or another
// localhost server set as VISION_BRIDGE_BASE_URL — gets only the provider key and
// never an OmniRoute credential; with no provider key the header is omitted.
// per-process secret, both accepted by API-key validation). Any other endpoint —
// api.openai.com, or another localhost server set as VISION_BRIDGE_BASE_URL — gets
// only the provider key and never an OmniRoute credential; with no provider key the
// header is omitted.
// A bare-id call to our own listener keeps an operator VISION_BRIDGE_API_KEY.
const selfLoopBearer =
isOwnOmniRouteBaseUrl(baseUrl) && (useFullModelId || !resolvedApiKey)
@@ -851,10 +852,13 @@ async function callVisionModelSingle(
// Internal self-loop sub-request: the parent request already holds the
// single heavyweight admission lease (`CHAT_MAX_HEAVY_IN_FLIGHT=1`), so a
// large base64-image describe body would be rejected with 503
// `chat_admission_busy` before it is described. The route only honors
// this header when the bearer is the self-loop bearer (set above), so
// external clients cannot use it to bypass admission.
// `chat_admission_busy` before it is described. The route grants the bypass
// only on the per-process token, never on this header or the bearer (the env
// key is a key clients can hold). Production injects undici fetch, which
// skips proxyFetch's own-listener stamp, so the token is set here; this branch
// only runs for our own listener, so the token never leaves the process.
headers["x-omniroute-admission-bypass"] = "internal";
headers[SELF_HOP_HEADER] = ownListenerSelfHopToken();
// Scope the sub-request to the caller's key: the receiving chat request
// applies that key's connection/model policy (honored only alongside the
// self-loop bearer, so it can only narrow access).

View File

@@ -2,6 +2,8 @@ import { createHash } from "node:crypto";
import fs from "node:fs/promises";
import path from "node:path";
import { DENIED_ROOT_DIRECTORY_ERROR, isDeniedRootDirectory } from "../deniedRootDirectories";
const DEFAULT_ALLOWED_EXTENSIONS = new Set([
".cfg",
".csv",
@@ -278,6 +280,9 @@ export async function canonicalizeLocalCorpusRoot(inputPath: string): Promise<st
} catch {
throw new Error("Local corpus root is not accessible");
}
if (isDeniedRootDirectory(canonical)) {
throw new Error(DENIED_ROOT_DIRECTORY_ERROR);
}
if (!stat.isDirectory()) {
throw new Error("Local corpus root must point to a directory");
}

View File

@@ -1,6 +1,7 @@
import fs from "node:fs";
import path from "node:path";
import { resolveDataDir } from "./dataPaths";
import { DENIED_ROOT_DIRECTORY_ERROR, isDeniedRootDirectory } from "./deniedRootDirectories";
import {
getObsidianVaultPath,
setObsidianVaultPath,
@@ -75,6 +76,12 @@ export async function enableObsidianVaultSync(
): Promise<ObsidianSyncEnableResult> {
const resolvedPath = path.resolve(vaultPath);
// The vault root is served read/write by the WebDAV file service: the filesystem root, the
// home directory itself and system directories are never a vault (CodeQL #1372/#1373).
if (isDeniedRootDirectory(resolvedPath)) {
return { success: false, error: DENIED_ROOT_DIRECTORY_ERROR };
}
if (!fs.existsSync(resolvedPath)) {
return { success: false, error: `Vault directory not found: ${resolvedPath}` };
}

View File

@@ -1,11 +1,11 @@
import { createHmac, randomBytes } from "crypto";
import { isOwnListenerSelfHop, SELF_HOP_HEADER } from "@omniroute/open-sse/utils/selfHop.ts";
import { timingSafeCompare } from "@/shared/utils/timingSafeCompare";
import { getProcessStore, sharedSymbol } from "@/shared/utils/processSingleton";
const ADMISSION_BYPASS_VALUE = "internal";
const FINGERPRINT_KEY = "omniroute-admission-fingerprint-v1";
// Descriptive marker an internal sub-request sends next to the process token. It is
// never trusted on its own: any client can set it.
export const ADMISSION_BYPASS_HEADER = "x-omniroute-admission-bypass";
export function resolveSessionId(request: Request): string {
@@ -25,9 +25,9 @@ export function resolveSessionId(request: Request): string {
// operator hasn't set OMNIROUTE_API_KEY/ROUTER_API_KEY (#13679: the previous fallback
// was the checked-in literal "sk_omniroute", a predictable shared secret anyone reading
// the source could forge). Both the in-process caller (audioBridgeHelpers /
// visionBridgeHelpers) and the verifiers (isInternalAdmissionBypass, API-key
// validation) read this same value. It lives on globalThis because the proxy (Next
// middleware bundle) and the route handlers load separate copies of this module.
// visionBridgeHelpers) and the verifier (API-key validation) read this same value. It
// lives on globalThis because the proxy (Next middleware bundle) and the route handlers
// load separate copies of this module.
const SELF_LOOP_SECRET_KEY = sharedSymbol("selfLoopSecret");
const selfLoopStore = globalThis as unknown as Record<symbol, string | undefined>;
@@ -48,20 +48,16 @@ export function resolveSelfLoopBearer(): string {
);
}
/**
* True only for a request this process sent to its own listener: our own fetches (#13593)
* and the internal sub-requests that also send ADMISSION_BYPASS_HEADER (the vision bridge
* describe call) carry the per-process token, held in memory only. The bypass header and
* any API key, the deployment env key (OMNIROUTE_API_KEY / ROUTER_API_KEY) included, are
* things a client can send, so neither vouches for the bypass (same rule as the internal
* test mark, #19292). The token compare is constant-time (isOwnListenerSelfHop).
*/
export function isInternalAdmissionBypass(request: Request): boolean {
// #13593: our own fetch to this listener already holds the parent lease.
if (isOwnListenerSelfHop(request.headers.get(SELF_HOP_HEADER))) return true;
const bypass =
request.headers.get(ADMISSION_BYPASS_HEADER)?.trim().toLowerCase() === ADMISSION_BYPASS_VALUE;
if (!bypass) return false;
const auth = request.headers.get("authorization") || "";
const match = /^bearer\s+(\S+)$/i.exec(auth.trim());
if (!match) return false;
// This gates an admission-lane bypass on a shared secret, so the compare is
// constant-time — `===` leaks matching-prefix length (GHSA-7434 class).
return timingSafeCompare(match[1].trim().toLowerCase(), resolveSelfLoopBearer().toLowerCase());
return isOwnListenerSelfHop(request.headers.get(SELF_HOP_HEADER));
}
function fingerprint(value: string): string {

View File

@@ -0,0 +1,198 @@
// The admission bypass (skip the heavyweight lease, honor the internal upstream-start
// cap) is only for calls this process makes to its own listener. An API key proves
// nothing about where a request came from: the deployment env key
// (OMNIROUTE_API_KEY / ROUTER_API_KEY) is an ordinary key a client can hold. So, as
// with the internal test mark (#19292), only the per-process token held in memory can
// vouch for the bypass.
import test from "node:test";
import assert from "node:assert/strict";
const core = await import("../../src/lib/db/core.ts");
const providersDb = await import("../../src/lib/db/providers.ts");
const { callVisionModel } = await import("../../src/lib/guardrails/visionBridgeHelpers.ts");
const { admitChatRequest, ChatAdmissionController } =
await import("../../src/shared/middleware/chatBodyAdmission.ts");
const { isInternalAdmissionBypass } =
await import("../../src/shared/middleware/chatAdmissionIdentity.ts");
const { INTERNAL_UPSTREAM_START_TIMEOUT_HEADER, resolveInternalUpstreamStartTimeoutMs } =
await import("../../src/sse/services/internalUpstreamStartTimeout.ts");
const { SELF_HOP_HEADER, ownListenerSelfHopToken } =
await import("../../open-sse/utils/selfHop.ts");
const DEPLOY_KEY = "sk-deployment-env-key";
const ENV_KEYS = ["OMNIROUTE_API_KEY", "ROUTER_API_KEY", "VISION_BRIDGE_BASE_URL"] as const;
const savedEnv = new Map(ENV_KEYS.map((key) => [key, process.env[key]]));
function setDeployKey(value: string | undefined) {
delete process.env.ROUTER_API_KEY;
if (value === undefined) delete process.env.OMNIROUTE_API_KEY;
else process.env.OMNIROUTE_API_KEY = value;
}
test.before(async () => {
delete process.env.VISION_BRIDGE_BASE_URL;
await providersDb.createProviderConnection({
provider: "openai",
authType: "apikey",
name: "admission-bypass-openai",
apiKey: "sk-test-openai",
});
});
test.afterEach(() => {
for (const [key, value] of savedEnv) {
if (value === undefined) delete process.env[key];
else process.env[key] = value;
}
});
test.after(() => {
core.resetDbInstance();
});
const bigBody = () =>
JSON.stringify({
model: "openai/gpt-4o-mini",
messages: [{ role: "user", content: "x".repeat(512 * 1024) }],
});
function chatRequest(headers: Record<string, string>, body = bigBody()) {
return new Request("http://localhost/v1/chat/completions", {
method: "POST",
headers: {
"content-type": "application/json",
"content-length": String(body.length),
...headers,
},
body,
});
}
/** Admission outcome while the single heavyweight slot is held by a parent request. */
async function admitWhileBusy(request: Request) {
const controller = new ChatAdmissionController(1);
const parentLease = controller.tryAcquireHeavy();
assert.ok(parentLease);
try {
const result = await admitChatRequest(request, {
controller,
largeBodyBytes: 32,
hardMaxBytes: 10 * 1024 * 1024,
heapPressureCheck: () => true,
});
return { result, activeHeavy: controller.activeHeavy };
} finally {
parentLease.release();
}
}
/** The headers the vision bridge sends on its describe call to this process's listener. */
async function visionSelfLoopHeaders(): Promise<Record<string, string>> {
let headers: Record<string, string> = {};
const fetchImpl: typeof fetch = async (_input, init) => {
headers = { ...((init?.headers ?? {}) as Record<string, string>) };
return Response.json({ choices: [{ message: { content: "A green square" } }] });
};
const result = await callVisionModel("data:image/png;base64,iVBORw0KGgo", {
model: "openai/gpt-4o-mini",
prompt: "Describe",
timeoutMs: 30_000,
maxImages: 1,
routeThroughOmniRoute: true,
fetchImpl,
});
assert.equal(result, "A green square");
return headers;
}
test("a client holding the deployment env key cannot claim the admission bypass", async () => {
setDeployKey(DEPLOY_KEY);
const headers = {
"x-omniroute-admission-bypass": "internal",
authorization: `Bearer ${DEPLOY_KEY}`,
};
assert.equal(isInternalAdmissionBypass(chatRequest(headers)), false);
const { result, activeHeavy } = await admitWhileBusy(chatRequest(headers));
assert.equal(result.admit, false, "the deployment key alone must not skip the admission queue");
if (!result.admit) assert.equal(result.response.status, 503);
assert.equal(activeHeavy, 1);
});
test("a client holding the deployment env key cannot set the internal upstream-start cap", () => {
setDeployKey(DEPLOY_KEY);
const request = chatRequest({
"x-omniroute-admission-bypass": "internal",
authorization: `Bearer ${DEPLOY_KEY}`,
[INTERNAL_UPSTREAM_START_TIMEOUT_HEADER]: "1000",
});
assert.equal(resolveInternalUpstreamStartTimeoutMs(request), undefined);
});
test("a forged or empty process token does not grant the bypass", () => {
setDeployKey(DEPLOY_KEY);
const base = {
"x-omniroute-admission-bypass": "internal",
authorization: `Bearer ${DEPLOY_KEY}`,
};
assert.equal(
isInternalAdmissionBypass(chatRequest({ ...base, [SELF_HOP_HEADER]: "0".repeat(64) })),
false
);
assert.equal(isInternalAdmissionBypass(chatRequest({ ...base, [SELF_HOP_HEADER]: "" })), false);
assert.equal(
isInternalAdmissionBypass(chatRequest({ ...base, [SELF_HOP_HEADER]: DEPLOY_KEY })),
false
);
});
for (const [label, deployKey] of [
["with a deployment env key", DEPLOY_KEY],
["without a deployment env key", undefined],
] as const) {
test(`the vision bridge describe call is still an internal bypass ${label}`, async () => {
setDeployKey(deployKey);
const headers = await visionSelfLoopHeaders();
assert.equal(headers[SELF_HOP_HEADER], ownListenerSelfHopToken());
assert.notEqual(headers[SELF_HOP_HEADER], DEPLOY_KEY);
assert.equal(isInternalAdmissionBypass(chatRequest(headers)), true);
const { result, activeHeavy } = await admitWhileBusy(chatRequest(headers));
assert.equal(result.admit, true, "the describe call must not wait behind its own parent");
assert.equal(activeHeavy, 1, "the bypass must not reserve a second lease");
const capped = chatRequest({ ...headers, [INTERNAL_UPSTREAM_START_TIMEOUT_HEADER]: "5000" });
assert.equal(resolveInternalUpstreamStartTimeoutMs(capped), 5000);
});
}
test("the process token never goes to another endpoint", async () => {
setDeployKey(DEPLOY_KEY);
process.env.VISION_BRIDGE_BASE_URL = "http://localhost:11434/v1";
await providersDb.createProviderConnection({
provider: "gemini",
authType: "apikey",
name: "admission-bypass-gemini",
apiKey: "sk-test-gemini",
});
let headers: Record<string, string> = {};
const fetchImpl: typeof fetch = async (_input, init) => {
headers = { ...((init?.headers ?? {}) as Record<string, string>) };
return Response.json({ choices: [{ message: { content: "A green square" } }] });
};
await callVisionModel("data:image/png;base64,iVBORw0KGgo", {
model: "gemini/gemini-2.5-flash",
prompt: "Describe",
timeoutMs: 30_000,
maxImages: 1,
fetchImpl,
});
assert.equal(headers[SELF_HOP_HEADER], undefined);
assert.equal(headers["x-omniroute-admission-bypass"], undefined);
});

View File

@@ -16,6 +16,8 @@ const {
resolveSelfLoopBearer,
} = admissionModule;
const { withEarlyStreamKeepalive } = await import("../../open-sse/utils/earlyStreamKeepalive.ts");
const { SELF_HOP_HEADER, ownListenerSelfHopToken } =
await import("../../open-sse/utils/selfHop.ts");
const { getActiveRequestCount } = await import("../../src/lib/gracefulShutdown.ts");
/**
@@ -633,6 +635,8 @@ function selfLoopChatRequest(
// test wraps itself in withSelfLoopEnv({}) so it is deterministic even when
// the developer's shell has OMNIROUTE_API_KEY set).
authorization: `Bearer ${resolveSelfLoopBearer()}`,
// The per-process token is what grants the bypass; the header and bearer alone do not.
[SELF_HOP_HEADER]: ownListenerSelfHopToken(),
};
if (contentLength !== null) headers["content-length"] = contentLength;
return new Request("http://x/v1/chat/completions", {
@@ -827,7 +831,7 @@ test("resolveSelfLoopBearer uses ROUTER_API_KEY when OMNIROUTE_API_KEY is unset"
}
});
test("env-key bearer is honored as a self-loop admission bypass (REQUIRE_API_KEY deployment)", async () => {
test("env-key self-loop call bypasses admission when it carries the process token (REQUIRE_API_KEY deployment)", async () => {
const restore = withSelfLoopEnv({ OMNIROUTE_API_KEY: "env-key" });
try {
const controller = new ChatAdmissionController(1);
@@ -845,6 +849,7 @@ test("env-key bearer is honored as a self-loop admission bypass (REQUIRE_API_KEY
"content-type": "application/json",
"x-omniroute-admission-bypass": "internal",
authorization: "Bearer env-key",
[SELF_HOP_HEADER]: ownListenerSelfHopToken(),
"content-length": String(body.length),
},
body,

View File

@@ -1,219 +0,0 @@
/**
* Regex work in the compression engines stays bounded on hostile input
* (CodeQL #1301, #1302, #1349).
*
* - #1301 headroom/gcf needsQuote(): the inline-array check ran in O(n^2) on runs of `[`.
* - #1302 rtk maybePersistRtkRawOutput(): the command slug trim ran in O(n^2) on runs of `_`
* from a client-supplied tool_use command of unbounded length.
* - #1349 ccr grep: a caller-supplied pattern such as `.*.*.*.*x` passed the star-height
* gate and blocked the event loop for minutes on a single long line.
*
* Each block pairs a timing assertion (the pathological input finishes fast or is refused)
* with a behaviour assertion (ordinary input gives the same result as before).
*/
import { describe, it } from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { needsQuote } from "../../../open-sse/services/compression/engines/headroom/gcf/scalar.ts";
import { maybePersistRtkRawOutput } from "../../../open-sse/services/compression/engines/rtk/rawOutput.ts";
import { queryBlock } from "../../../open-sse/services/compression/engines/ccr/ccrQuery.ts";
/** Ceiling for the fixed paths. They run in a few ms when idle; before the fix the same
* inputs took 10 s (#1301), 21 s (#1302) and minutes (#1349). The headroom absorbs a loaded
* CI runner (one fixed case reached 806 ms at load average 44) without hiding a regression. */
const FAST_MS = 1_000;
/** Upper bound for a grep stopped by its 1 s time budget (budget plus scheduling slack). */
const BUDGET_CEILING_MS = 5_000;
function timed<T>(fn: () => T): { value: T; ms: number } {
const t0 = performance.now();
const value = fn();
return { value, ms: performance.now() - t0 };
}
/** Reference semantics of the SPEC 2.4 inline-array rule: some `[` whose first following
* `]` is followed by optional whitespace and a `:`. Written as a plain linear scan. */
function hasInlineArrayHeader(s: string): boolean {
for (let i = 0; i < s.length; i++) {
if (s[i] !== "[") continue;
const close = s.indexOf("]", i + 1);
if (close === -1) return false;
let k = close + 1;
while (k < s.length && /\s/.test(s[k])) k++;
if (s[k] === ":") return true;
}
return false;
}
/** Deterministic PRNG (mulberry32) so the equivalence sample is reproducible. */
function prng(seed: number): () => number {
let a = seed >>> 0;
return () => {
a = (a + 0x6d2b79f5) >>> 0;
let t = a;
t = Math.imul(t ^ (t >>> 15), t | 1);
t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
};
}
describe("#1301 headroom/gcf needsQuote inline-array check", () => {
it("finishes fast on 50k '[' characters", () => {
for (const s of [
"[".repeat(50_000),
"a" + "[".repeat(50_000) + "]",
"[".repeat(50_000) + "]x",
]) {
const { value, ms } = timed(() => needsQuote(s));
assert.equal(value, false);
assert.ok(ms < FAST_MS, `needsQuote took ${ms.toFixed(1)}ms on ${s.length} chars`);
}
});
it("keeps the same verdict on ordinary values", () => {
assert.equal(needsQuote("ERR[404]: Not Found"), true);
assert.equal(needsQuote("[Speaker 1]: Hello"), true);
assert.equal(needsQuote("a[[b]: c"), true);
assert.equal(needsQuote("x[a[b] :y"), true);
assert.equal(needsQuote("arr[0] index"), false);
assert.equal(needsQuote("a]: [b"), false);
assert.equal(needsQuote("a[b] c: d"), false);
});
it("matches the reference rule on a random sample", () => {
const rand = prng(1301);
const alphabet = "[]: ab";
for (let n = 0; n < 20_000; n++) {
const len = Math.floor(rand() * 12);
let body = "";
for (let i = 0; i < len; i++) body += alphabet[Math.floor(rand() * alphabet.length)];
// Leading/trailing 'a' keeps the other needsQuote rules (edge space, numeric, '#'…)
// out of the way, so the verdict depends only on the inline-array rule.
const s = `a${body}a`;
assert.equal(needsQuote(s), hasInlineArrayHeader(s), JSON.stringify(s));
}
});
});
describe("#1302 rtk raw-output command slug", () => {
function persist(command: string) {
const base = process.env.DATA_DIR || os.tmpdir();
const dataDir = fs.mkdtempSync(path.join(base, "rtk-slug-"));
const previous = process.env.DATA_DIR;
process.env.DATA_DIR = dataDir;
try {
return timed(() =>
maybePersistRtkRawOutput("error: build failed\nline 2", { retention: "always", command })
);
} finally {
if (previous === undefined) delete process.env.DATA_DIR;
else process.env.DATA_DIR = previous;
fs.rmSync(dataDir, { recursive: true, force: true });
}
}
function slugOf(pointerPath: string): string {
const match = /^\d+-(.*)-[0-9a-f]{24}\.log$/.exec(path.basename(pointerPath));
assert.ok(match, pointerPath);
return match[1];
}
it("finishes fast on a 50k-underscore command", () => {
for (const command of ["_".repeat(50_000) + "x", "x" + "_".repeat(50_000) + "x"]) {
const { value, ms } = persist(command);
assert.ok(value, "pointer expected");
assert.ok(ms < FAST_MS, `slug took ${ms.toFixed(1)}ms on ${command.length} chars`);
}
});
it("keeps the same slug for ordinary commands", () => {
const cases: Array<[string, string]> = [
["git status --short", "git_status_--short"],
[" npm test -- --watch=false ", "npm_test_--_--watch_false"],
["__init__", "init"],
["cargo build --release && ./target/release/app", "cargo_build_--release_target_release_app"],
["a".repeat(100), "a".repeat(48)],
];
for (const [command, expected] of cases) {
const { value } = persist(command);
assert.ok(value);
assert.equal(slugOf(value.path), expected, command);
}
const { value } = persist("");
assert.ok(value);
assert.equal(slugOf(value.path), "tool-output");
});
});
describe("#1349 ccr grep pattern", () => {
it("refuses a multi-quantifier pattern on a 500+ char line quickly", () => {
const text = "a".repeat(600);
const { value, ms } = timed(() => queryBlock(text, { mode: "grep", pattern: ".*.*.*.*x" }));
assert.ok("error" in value, JSON.stringify(value));
assert.ok(ms < FAST_MS, `grep took ${ms.toFixed(1)}ms`);
});
it("stops a single-quantifier pattern that exceeds the time budget", () => {
// 2 MiB of 4096-char lines: `.*x` is quadratic per line (minutes before the fix).
const text = Array.from({ length: 512 }, () => "a".repeat(4095)).join("\n");
const { value, ms } = timed(() => queryBlock(text, { mode: "grep", pattern: ".*x" }));
assert.ok("error" in value, JSON.stringify(value).slice(0, 200));
assert.match((value as { error: string }).error, /time budget/);
assert.ok(ms < BUDGET_CEILING_MS, `grep took ${ms.toFixed(1)}ms`);
});
it("counts only unbounded quantifiers outside classes and escapes", () => {
const tooMany = ["a.*b.*c", "\\d+\\.\\d+", "x{2,}y+", "a.*?b.+?c"];
for (const pattern of tooMany) {
const r = queryBlock("abc", { mode: "grep", pattern });
assert.ok("error" in r, pattern);
assert.match((r as { error: string }).error, /unbounded quantifier/, pattern);
}
const text = ["l1 ERROR upstream timeout", "l2 *+ literal", "l3 {2,} braces", "l4 ok"].join(
"\n"
);
assert.deepEqual(queryBlock(text, { mode: "grep", pattern: "ERROR.*timeout" }), {
content: "l1 ERROR upstream timeout",
});
assert.deepEqual(queryBlock(text, { mode: "grep", pattern: "[*+]+ literal" }), {
content: "l2 *+ literal",
});
assert.deepEqual(queryBlock(text, { mode: "grep", pattern: "\\*\\+ lit.*" }), {
content: "l2 *+ literal",
});
assert.deepEqual(queryBlock(text, { mode: "grep", pattern: "\\{2,\\} b.*s" }), {
content: "l3 {2,} braces",
});
assert.deepEqual(queryBlock(text, { mode: "grep", pattern: "l[0-9]{1,2} (ok|ERROR)" }), {
content: "l1 ERROR upstream timeout\nl4 ok",
});
});
it("keeps grep results unchanged on an ordinary log block", () => {
const lines = Array.from(
{ length: 5_000 },
(_, i) => `2026-11-20T10:00:${String(i % 60).padStart(2, "0")}Z INFO req=${i} status=200`
);
lines[1234] = "2026-11-20T10:00:34Z ERROR req=1234 upstream timeout";
lines[4321] = "2026-11-20T10:00:01Z WARN req=4321 slow upstream";
const text = lines.join("\n");
const expected = (re: RegExp) => lines.filter((l) => re.test(l)).join("\n");
for (const pattern of ["ERROR", "(WARN|ERROR) req=", "req=12\\d\\d ", "^\\S+ WARN"]) {
assert.deepEqual(
queryBlock(text, { mode: "grep", pattern }),
{ content: expected(new RegExp(pattern)) },
pattern
);
}
assert.deepEqual(queryBlock(text, { mode: "grep", pattern: "INFO", unique: true }), {
content: lines
.filter((l) => l.includes("INFO"))
.slice(0, 1000)
.join("\n")
.concat("\n…[truncated at 1000 matches]"),
});
});
});

View File

@@ -467,7 +467,7 @@ test("stampOwnListenerSelfHop stamps only requests to this process's own listene
assert.equal(new Headers(presetOpts.headers).get("x-omniroute-self-hop"), "preset");
});
test("vision-bridge describe self-loop: recursion-guard headers sent, no self-hop header", async () => {
test("vision-bridge describe self-loop: recursion-guard headers and the process token sent", async () => {
await createProviderConnection({
provider: "openai",
authType: "apikey",
@@ -495,13 +495,10 @@ test("vision-bridge describe self-loop: recursion-guard headers sent, no self-ho
assert.equal(headers["x-omniroute-compression"], "off");
assert.equal(headers["x-omniroute-admission-bypass"], "internal");
assert.equal(headers.Authorization, `Bearer ${resolveSelfLoopBearer()}`);
// characterization: the describe call is built WITHOUT x-omniroute-self-hop. Production
// injects undici fetch (visionBridge.ts) which bypasses proxyFetch's stamp, so admission
// relies on x-omniroute-admission-bypass + the self-loop bearer instead.
assert.equal(
Object.keys(headers).some((h) => h.toLowerCase() === "x-omniroute-self-hop"),
false
);
// characterization: production injects undici fetch (visionBridge.ts), which bypasses
// proxyFetch's stamp, so the describe call sets x-omniroute-self-hop itself: admission
// grants the bypass only on that per-process token, never on the header + bearer alone.
assert.equal(headers["x-omniroute-self-hop"], selfHop.ownListenerSelfHopToken());
// The receiving chat route resolves the recursion-guard header into a disable list that
// makes the nested pre-call pass skip both bridges.

View File

@@ -194,8 +194,8 @@ test("proxyFetch stamps the self-hop header before any dispatch decision", () =>
test("characterization: the vision-bridge describe call uses undici fetch, bypassing the self-hop stamp", () => {
// VisionBridgeGuardrail injects `undiciFetch` as fetchImpl, so the describe self-call never
// passes through proxyFetch.patchedFetchUnrecorded and carries no x-omniroute-self-hop
// header; admission instead relies on x-omniroute-admission-bypass + the self-loop bearer
// passes through proxyFetch.patchedFetchUnrecorded and is never stamped there; the describe
// call sets x-omniroute-self-hop itself, the only thing admission trusts for the bypass
// (pinned behaviorally in guardrail-pipeline-characterization.test.ts).
const bridge = read("src/lib/guardrails/visionBridge.ts");
assert.match(bridge, /import \{ fetch as undiciFetch \} from "undici";/);
@@ -205,7 +205,13 @@ test("characterization: the vision-bridge describe call uses undici fetch, bypas
/fetchImpl: undiciFetch as unknown as typeof fetch,/
);
const helpers = read("src/lib/guardrails/visionBridgeHelpers.ts");
assert.doesNotMatch(helpers, /self-hop|selfHop/);
// The token is set by hand, and only inside the own-listener (self-loop bearer) branch.
const selfLoopBranch = indexOrFail(helpers, "if (selfLoopBearer) {");
assert.match(
helpers.slice(selfLoopBranch, selfLoopBranch + 1200),
/headers\[SELF_HOP_HEADER\] = ownListenerSelfHopToken\(\);/
);
assert.equal(helpers.match(/ownListenerSelfHopToken\(\)/g)?.length, 1);
assert.match(helpers, /headers\["x-omniroute-disabled-guardrails"\] = routeThroughOmniRoute/);
});

View File

@@ -4,6 +4,7 @@ import {
INTERNAL_UPSTREAM_START_TIMEOUT_HEADER,
resolveInternalUpstreamStartTimeoutMs,
} from "../../src/sse/services/internalUpstreamStartTimeout.ts";
import { SELF_HOP_HEADER, ownListenerSelfHopToken } from "../../open-sse/utils/selfHop.ts";
const oldKey = process.env.OMNIROUTE_API_KEY;
process.env.OMNIROUTE_API_KEY = "trusted-internal-test-key";
@@ -13,15 +14,19 @@ test.after(() => {
else process.env.OMNIROUTE_API_KEY = oldKey;
});
function req(value: string, bearer = "trusted-internal-test-key", bypass = "internal") {
return new Request("http://127.0.0.1:20128/v1/chat/completions", {
method: "POST",
headers: {
authorization: `Bearer ${bearer}`,
"x-omniroute-admission-bypass": bypass,
[INTERNAL_UPSTREAM_START_TIMEOUT_HEADER]: value,
},
});
function req(
value: string,
bearer = "trusted-internal-test-key",
bypass = "internal",
selfHop: string | null = ownListenerSelfHopToken()
) {
const headers: Record<string, string> = {
authorization: `Bearer ${bearer}`,
"x-omniroute-admission-bypass": bypass,
[INTERNAL_UPSTREAM_START_TIMEOUT_HEADER]: value,
};
if (selfHop !== null) headers[SELF_HOP_HEADER] = selfHop;
return new Request("http://127.0.0.1:20128/v1/chat/completions", { method: "POST", headers });
}
test("trusted internal caller may set a bounded upstream-start cap", () => {
@@ -31,9 +36,22 @@ test("trusted internal caller may set a bounded upstream-start cap", () => {
});
test("ordinary or forged callers cannot set the internal upstream-start cap", () => {
assert.equal(resolveInternalUpstreamStartTimeoutMs(req("5000", "wrong-key")), undefined);
const envKey = "trusted-internal-test-key";
// The deployment env key is a key clients hold: with the bypass header it still proves nothing.
assert.equal(
resolveInternalUpstreamStartTimeoutMs(req("5000", "trusted-internal-test-key", "no")),
resolveInternalUpstreamStartTimeoutMs(req("5000", envKey, "internal", null)),
undefined
);
assert.equal(
resolveInternalUpstreamStartTimeoutMs(req("5000", "wrong-key", "internal", null)),
undefined
);
assert.equal(
resolveInternalUpstreamStartTimeoutMs(req("5000", envKey, "internal", "0".repeat(64))),
undefined
);
assert.equal(
resolveInternalUpstreamStartTimeoutMs(req("5000", envKey, "internal", "")),
undefined
);
});

View File

@@ -0,0 +1,212 @@
// CodeQL #1389 (js/resource-exhaustion): `poll_interval_ms`, `timeout_ms` and
// `poll_timeout_ms` from the request body reached `sleep()` (open-sse/utils/sleep.ts) and the
// polling deadline with no upper bound, so one request could hold a handler for days while the
// server kept polling the upstream with the operator's credential.
//
// The handlers are driven against a fake upstream that never finishes. Timers created by
// `sleep()` are intercepted (identified by the call stack), recorded, and fired at once while a
// virtual clock advances by the requested delay, so a multi-day wait runs in milliseconds.
import test from "node:test";
import assert from "node:assert/strict";
import { handleImageGeneration } from "../../open-sse/handlers/imageGeneration.ts";
import {
MAX_CALLER_POLL_INTERVAL_MS,
MAX_CALLER_POLL_TIMEOUT_MS,
clampCallerMs,
clampPollIntervalMs,
clampPollTimeoutMs,
} from "../../open-sse/utils/pollBounds.ts";
const HUGE_MS = 1e12; // ~31 years
const INTERVAL_CEILING = 30_000;
const TIMEOUT_CEILING = 600_000;
const originalFetch = globalThis.fetch;
const originalSetTimeout = globalThis.setTimeout;
const originalDateNow = Date.now;
type SleepTrace = { sleeps: number[]; elapsedMs: () => number };
/** Intercepts timers created by utils/sleep.ts and drives a virtual clock with them. */
function installVirtualSleep(): SleepTrace {
const start = originalDateNow();
let offset = 0;
const sleeps: number[] = [];
Date.now = () => start + offset;
globalThis.setTimeout = ((fn: (...args: unknown[]) => void, ms?: number, ...args: unknown[]) => {
const stack = new Error().stack ?? "";
if (!stack.includes("utils/sleep.ts")) return originalSetTimeout(fn, ms, ...args);
const delay = Number(ms) || 0;
sleeps.push(delay);
offset += delay;
return originalSetTimeout(fn, 0, ...args);
}) as typeof setTimeout;
return { sleeps, elapsedMs: () => offset };
}
function restore() {
globalThis.fetch = originalFetch;
globalThis.setTimeout = originalSetTimeout;
Date.now = originalDateNow;
}
test.afterEach(restore);
function json(body: unknown, status = 200): Response {
return new Response(JSON.stringify(body), {
status,
headers: { "content-type": "application/json" },
});
}
/** Upstream fakes that accept the job and report it as still running on every poll. */
const NEVER_FINISHING_UPSTREAMS: Record<string, { model: string; fetch: typeof fetch }> = {
nanobanana: {
model: "nanobanana/nanobanana-flash",
fetch: (async (input: string | URL) => {
const url = String(input);
if (url.includes("/record-info")) return json({ data: { successFlag: 0 } });
return json({ data: { taskId: "task-1" } });
}) as typeof fetch,
},
magnific: {
model: "magnific/realism",
fetch: (async (input: string | URL) => {
const url = String(input);
if (url.endsWith("/task-1"))
return json({ data: { task_id: "task-1", status: "IN_PROGRESS" } });
return json({ data: { task_id: "task-1", status: "CREATED" } });
}) as typeof fetch,
},
"black-forest-labs": {
model: "black-forest-labs/flux-2-pro",
fetch: (async (input: string | URL) => {
const url = String(input);
if (url === "https://api.bfl.ai/result/1") return json({ status: "Pending" });
return json({ id: "1", polling_url: "https://api.bfl.ai/result/1" });
}) as typeof fetch,
},
renderhour: {
model: "renderhour/z-image",
fetch: (async (input: string | URL) => {
const url = String(input);
if (url.endsWith("/v1/generations")) return json({ id: "job-1", status: "queued" }, 201);
return json({ id: "job-1", status: "running" });
}) as typeof fetch,
},
};
async function runNeverFinishing(provider: string, extraBody: Record<string, unknown>) {
const upstream = NEVER_FINISHING_UPSTREAMS[provider];
globalThis.fetch = upstream.fetch;
const trace = installVirtualSleep();
const result = await handleImageGeneration({
body: { model: upstream.model, prompt: "a lighthouse", ...extraBody },
credentials: { apiKey: "test-key" },
log: null,
});
restore();
return { result, trace };
}
for (const provider of Object.keys(NEVER_FINISHING_UPSTREAMS)) {
test(`${provider}: a huge caller poll interval and timeout are clamped to the ceilings`, async () => {
const { result, trace } = await runNeverFinishing(provider, {
poll_interval_ms: HUGE_MS,
timeout_ms: HUGE_MS,
poll_timeout_ms: HUGE_MS,
});
assert.equal(result.success, false, "a job that never finishes must fail");
assert.ok(trace.sleeps.length > 0, "the handler polled at least once");
assert.ok(
Math.max(...trace.sleeps) <= INTERVAL_CEILING,
`longest single sleep ${Math.max(...trace.sleeps)}ms exceeds ${INTERVAL_CEILING}ms`
);
assert.ok(
trace.elapsedMs() <= TIMEOUT_CEILING + INTERVAL_CEILING,
`polling ran for ${trace.elapsedMs()}ms of virtual time, above the ${TIMEOUT_CEILING}ms ceiling`
);
});
test(`${provider}: a small caller poll interval is used as given`, async () => {
const { trace } = await runNeverFinishing(provider, {
poll_interval_ms: 1_000,
timeout_ms: 5_000,
poll_timeout_ms: 5_000,
});
assert.ok(trace.sleeps.length > 0);
assert.ok(
trace.sleeps.every((ms) => ms === 1_000),
`sleeps: ${trace.sleeps.join(",")}`
);
});
}
test("default poll intervals are unchanged when the caller sends none", async () => {
const expected: Record<string, number> = {
nanobanana: 2_500,
magnific: 4_000,
"black-forest-labs": 1_500,
renderhour: 2_000,
};
for (const [provider, interval] of Object.entries(expected)) {
const { trace } = await runNeverFinishing(provider, {});
assert.equal(trace.sleeps[0], interval, `${provider} default poll interval`);
}
});
test("timeout error messages report the clamped value", async () => {
// A huge interval too, so the unclamped code ends after one sleep instead of polling
// ~400 million times (which is the defect itself).
const huge = { timeout_ms: HUGE_MS, poll_interval_ms: HUGE_MS };
const nano = await runNeverFinishing("nanobanana", huge);
assert.match(String(nano.result.error), /timeout after 600000ms/);
const bfl = await runNeverFinishing("black-forest-labs", huge);
assert.match(String(bfl.result.error), /timed out after 600000ms/);
const rh = await runNeverFinishing("renderhour", huge);
assert.match(String(rh.result.error), /within 600 s/);
});
test("renderhour: aborting the request ends the wait between polls", async () => {
globalThis.fetch = (async (input: string | URL, init: RequestInit = {}) => {
init.signal?.throwIfAborted();
const url = String(input);
if (url.endsWith("/v1/generations")) return json({ id: "job-1", status: "queued" }, 201);
return json({ id: "job-1", status: "running" });
}) as typeof fetch;
const controller = new AbortController();
const timer = originalSetTimeout(() => controller.abort(), 50);
const startedAt = originalDateNow();
const result = await handleImageGeneration({
body: { model: "renderhour/z-image", prompt: "a lighthouse", poll_interval_ms: 30_000 },
credentials: { apiKey: "test-key" },
log: null,
signal: controller.signal,
});
clearTimeout(timer);
assert.equal(result.success, false);
assert.ok(
originalDateNow() - startedAt < 10_000,
"the 30 s sleep should end as soon as the request is aborted"
);
});
test("clampCallerMs: bounds caller values, never shrinks the fallback", () => {
assert.equal(MAX_CALLER_POLL_INTERVAL_MS, INTERVAL_CEILING);
assert.equal(MAX_CALLER_POLL_TIMEOUT_MS, TIMEOUT_CEILING);
assert.equal(clampCallerMs(HUGE_MS, 2_000, 30_000), 30_000);
assert.equal(clampCallerMs("1500.9", 2_000, 30_000), 1_500);
assert.equal(clampCallerMs(undefined, 2_000, 30_000), 2_000);
assert.equal(clampCallerMs(0, 2_000, 30_000), 2_000);
assert.equal(clampCallerMs(-5, 2_000, 30_000), 2_000);
assert.equal(clampCallerMs(Number.NaN, 2_000, 30_000), 2_000);
assert.equal(clampCallerMs(Infinity, 2_000, 30_000), 2_000);
assert.equal(clampCallerMs(0.5, 2_000, 30_000), 2_000, "sub-millisecond values would spin");
// A fallback above the ceiling (an operator default) is kept, and a caller may ask for it.
assert.equal(clampCallerMs(undefined, 900_000, 600_000), 900_000);
assert.equal(clampCallerMs(HUGE_MS, 900_000, 600_000), 900_000);
assert.equal(clampPollIntervalMs(HUGE_MS, 2_500), INTERVAL_CEILING);
assert.equal(clampPollTimeoutMs(HUGE_MS, 300_000), TIMEOUT_CEILING);
});

View File

@@ -9,6 +9,7 @@ import { z } from "zod";
import {
DEFAULT_CONFIG_PATH,
LANDING_ACTORS,
VOICES,
isManagedBase,
loadConfig,
validateConfig,
@@ -48,8 +49,11 @@ const LandingSchema = z
.regex(/^omni-queue\/./)
.refine((context) => !Object.values(APPROVAL_CONTEXTS).includes(context))
.default("omni-queue/land"),
// optional: sign the queue's merge commits with the owner's SSH key (owner actor only)
signing: z.enum(["none", "ssh"]).default("none"),
})
.refine((l) => (l.actor === "owner") === (l.identity !== undefined));
.refine((l) => (l.actor === "owner") === (l.identity !== undefined))
.refine((l) => l.signing !== "ssh" || l.actor === "owner");
const ConfigSchema = z
.strictObject({
@@ -92,6 +96,8 @@ const ConfigSchema = z
// optional: the hotfix lane and the base-repair lane, each selected by its own label
lanes: z.strictObject({ hotfixLabel: label, baseRepairLabel: label }).optional(),
mode: z.enum(["shadow", "live"]),
// optional: who performs the queue's comments, label removals and issue writes
voice: z.enum(["app", "owner"]).default("app"),
})
.refine((c) => c.label !== c.protectedApprovalLabel)
// lane labels: distinct from each other and from every other label the queue reads
@@ -124,9 +130,52 @@ test("the shipped config lands as the owner with the noreply identity", () => {
email: "8016841+diegosouzapw@users.noreply.github.com",
},
statusContext: "omni-queue/land",
// shipped OFF: production turns signing on in a separate change, after a rehearsal
signing: "none",
});
});
test("the shipped config keeps the App's voice and unsigned merge commits (both features off)", () => {
assert.deepEqual(VOICES, ["app", "owner"]);
assert.equal(raw.voice, "app");
assert.equal(raw.landing.signing, "none");
assert.equal(raw.mode, "shadow");
});
test("voice: app (the default) or owner; anything else is refused", () => {
const { voice: _shipped, ...withoutVoice } = raw;
const absent = validateConfig(withoutVoice);
assert.equal(absent.ok, true, JSON.stringify(absent.errors));
assert.equal(absent.config.voice, "app", "absent = the App's voice");
const owner = validateConfig({ ...raw, voice: "owner" });
assert.equal(owner.ok, true, JSON.stringify(owner.errors));
assert.equal(owner.config.voice, "owner");
for (const voice of ["Owner", "bot", "", null, true, ["owner"]]) {
const result = validateConfig({ ...raw, voice });
assert.equal(result.ok, false, JSON.stringify(voice));
assert.match(result.errors.join("\n"), /voice: expected one of app, owner/);
}
});
test("landing.signing: none (the default) or ssh, and ssh only when the owner lands", () => {
const { signing: _shipped, ...landing } = raw.landing;
const absent = validateConfig({ ...raw, landing });
assert.equal(absent.ok, true, JSON.stringify(absent.errors));
assert.equal(absent.config.landing.signing, "none");
const ssh = validateConfig({ ...raw, landing: { ...landing, signing: "ssh" } });
assert.equal(ssh.ok, true, JSON.stringify(ssh.errors));
assert.equal(ssh.config.landing.signing, "ssh");
// The App's commits carry the App's bot identity: no account of the owner could verify them.
const asApp = validateConfig({ ...raw, landing: { mode: "merge-ff", signing: "ssh" } });
assert.equal(asApp.ok, false);
assert.match(asApp.errors.join("\n"), /landing\.signing: "ssh" needs landing\.actor "owner"/);
for (const signing of ["gpg", "SSH", true, "", null]) {
const result = validateConfig({ ...raw, landing: { ...landing, signing } });
assert.equal(result.ok, false, JSON.stringify(signing));
assert.match(result.errors.join("\n"), /landing\.signing: expected one of none, ssh/);
}
});
test("landing: actor owner needs a noreply identity", () => {
const bad = validateConfig({ ...raw, landing: { mode: "merge-ff", actor: "owner" } });
assert.equal(bad.ok, false);
@@ -158,6 +207,7 @@ test("landing: defaults keep the App as the actor", () => {
mode: "merge-ff",
actor: "app",
statusContext: "omni-queue/land",
signing: "none",
});
});
@@ -538,6 +588,24 @@ const MUTATIONS = {
(c.lanes.baseRepairLabel = c.protectedApprovalLabel.toUpperCase()),
"lane label equals a block label": (c) => (c.lanes.hotfixLabel = c.blockLabels[0]),
"unknown mode": (c) => (c.mode = "on"),
"unknown voice": (c) => (c.voice = "bot"),
"voice not a string": (c) => (c.voice = true),
"unknown signing": (c) => (c.landing.signing = "gpg"),
"boolean signing": (c) => (c.landing.signing = true),
"ssh signing with the app actor": (c) => {
c.landing.actor = "app";
delete c.landing.identity;
c.landing.signing = "ssh";
},
"valid: owner voice": (c) => (c.voice = "owner"),
"valid: voice left out (default app)": (c) => delete c.voice,
"valid: ssh signing with the owner actor": (c) => (c.landing.signing = "ssh"),
"valid: signing left out (default none)": (c) => delete c.landing.signing,
"valid: owner voice with the app actor": (c) => {
c.voice = "owner";
c.landing.actor = "app";
delete c.landing.identity;
},
"valid: squash-api landing": (c) => (c.landing.mode = "squash-api"),
"valid: app actor without identity": (c) => {
c.landing.actor = "app";

View File

@@ -770,6 +770,127 @@ test("a request that keeps timing out fails with GitHubError status 0", async (t
});
});
// ── owner voice: the owner's token writes, the App's reads, both logins' markers count ──
const OWNER_TOKEN = "github_pat_OwnerFineGrainedToken0123456789";
/** Fake GitHub with the App's token (omni-queue[bot]) and the owner's (`owner-login`). */
async function voiceSetup(t) {
const fake = await startFakeGitHub({ token: TOKEN, actor: "omni-queue[bot]" });
t.after(() => fake.close());
fake.tokenActors.set(OWNER_TOKEN, "owner-login");
const client = (token) =>
createGitHubClient({
token,
repository: fake.repository,
apiUrl: fake.url,
botLogin: "omni-queue[bot]",
sleep: async () => {},
});
return { fake, app: client(TOKEN), owner: client(OWNER_TOKEN) };
}
const marked = (id, key, login) => ({
id,
body: `earlier\n\n${commentMarker(key)}`,
user: { login, type: /\[bot\]$/.test(login) ? "Bot" : "User" },
created_at: "2026-11-13T10:00:00Z",
});
test("getAuthenticatedLogin: the login of the token's user (GET /user)", async (t) => {
const { fake, app, owner } = await voiceSetup(t);
assert.equal(await owner.getAuthenticatedLogin(), "owner-login");
assert.equal(await app.getAuthenticatedLogin(), "omni-queue[bot]");
const reads = fake.requests.filter((r) => r.path === "!/user");
assert.equal(reads.length, 2);
assert.ok(reads.every((r) => r.method === "GET"));
});
test("commentOnce alsoLogins: a marker by that login counts as the queue's own", async (t) => {
const { fake, app } = await voiceSetup(t);
fake.addPull({ number: 21 });
fake.comments.set(21, [marked(1, "culprit:abc", "owner-login")]);
// Without the owner's login only the App's markers count (today's behaviour)...
assert.deepEqual(await app.commentOnce(21, "culprit:abc", "x"), { posted: true });
fake.comments.set(21, [marked(1, "culprit:abc", "owner-login")]);
// ...with it, the owner's earlier comment is the queue's own: nothing is posted again.
assert.deepEqual(await app.commentOnce(21, "culprit:abc", "x", { alsoLogins: ["owner-login"] }), {
posted: false,
});
assert.equal(fake.comments.get(21).length, 1);
});
test("commentOnce alsoLogins: a marker by anybody else still never counts", async (t) => {
const { fake, app } = await voiceSetup(t);
fake.addPull({ number: 22 });
fake.comments.set(22, [marked(1, "culprit:abc", "mallory")]);
assert.deepEqual(await app.commentOnce(22, "culprit:abc", "x", { alsoLogins: ["owner-login"] }), {
posted: true,
});
const comments = fake.comments.get(22);
assert.equal(comments.length, 2, "mallory's planted marker is left alone and ignored");
assert.equal(comments[0].user.login, "mallory");
assert.equal(comments[1].user.login, "omni-queue[bot]");
});
test("commentOnce reader: lists through the reader's token, posts through its own", async (t) => {
const { fake, app, owner } = await voiceSetup(t);
fake.addPull({ number: 23 });
const opts = { reader: app, alsoLogins: ["owner-login"] };
assert.deepEqual(await owner.commentOnce(23, "landed:abc", "Landed", opts), { posted: true });
const [comment] = fake.comments.get(23);
assert.equal(comment.user.login, "owner-login", "the comment is the owner's");
assert.equal(comment.body, `Landed\n\n${commentMarker("landed:abc")}`);
const auth = (r) => String(r.headers.authorization ?? "");
const lists = fake.requests.filter((r) => r.method === "GET" && r.path === "/issues/23/comments");
assert.ok(lists.length >= 1);
assert.ok(
lists.every((r) => auth(r) === `Bearer ${TOKEN}`),
"every read uses the App's token"
);
const posts = fake.requests.filter(
(r) => r.method === "POST" && r.path === "/issues/23/comments"
);
assert.deepEqual(
posts.map((r) => auth(r)),
[`Bearer ${OWNER_TOKEN}`]
);
// The owner's own marker counts on the next call, and on the App's fallback path too.
assert.deepEqual(await owner.commentOnce(23, "landed:abc", "Landed", opts), { posted: false });
assert.deepEqual(
await app.commentOnce(23, "landed:abc", "Landed", { alsoLogins: ["owner-login"] }),
{ posted: false }
);
assert.equal(fake.comments.get(23).length, 1);
});
test("commentOnce reader: a duplicate the owner raced with the App is removed, oldest kept", async (t) => {
const { fake, app } = await voiceSetup(t);
fake.addPull({ number: 24 });
let planted = false;
const racing = createGitHubClient({
token: OWNER_TOKEN,
repository: fake.repository,
apiUrl: fake.url,
botLogin: "omni-queue[bot]",
fetchImpl: async (url, init) => {
if (!planted && init.method === "POST" && url.endsWith("/issues/24/comments")) {
planted = true; // the App's approval job posts between our read and our write
fake.comments.set(24, [marked(1, "not-approver", "omni-queue[bot]")]);
}
return fetch(url, init);
},
});
const result = await racing.commentOnce(24, "not-approver", "mine", {
reader: app,
alsoLogins: ["owner-login"],
});
assert.deepEqual(result, { posted: false });
const comments = fake.comments.get(24);
assert.equal(comments.length, 1, "the owner's newer duplicate was deleted");
assert.equal(comments[0].id, 1);
});
test("commentOnce keeps the oldest when another writer posted the same marker meanwhile", async (t) => {
const fake = await startFakeGitHub({ token: TOKEN, actor: "omni-queue[bot]" });
t.after(() => fake.close());

View File

@@ -27,6 +27,7 @@
//
// Programmable state (plain Maps/arrays of RAW GitHub payloads; mutate freely):
// fake.repoInfo GET /repos/o/r payload ({default_branch: "main", ...})
// GET /user {login, type} of the login the request's token acts as
// fake.addPull({number?, title, user?, base?, head?, labels?, draft?, ...}) → raw pull
// fake.pulls Map<number, rawPull> (labels: [{name}] — shared with the issue endpoints)
// fake.files Map<number, [{filename, previous_filename?, status}]>
@@ -414,6 +415,8 @@ export async function startFakeGitHub(options = {}) {
// ─────────────── routes: [method, RegExp on the repo-relative path, handler] ───────────────
const routes = [
["GET", /^$/, () => json(200, fake.repoInfo)],
// GET /user (outside the repository prefix): the login the bearer token acts as.
["GET", /^!\/user$/, () => json(200, user())],
[
"GET",

View File

@@ -0,0 +1,318 @@
// omni-queue: signed merge commits (compose.composeCandidate with `signing`, config
// landing.signing "ssh") against real git and a real ed25519 key made by ssh-keygen in a
// temporary directory. The signature is checked with `git verify-commit`, never mocked, and a
// signed candidate must be the unsigned composition of the same inputs plus a signature: same
// trees, parents (up to the signed chain itself), author, committer and message.
import assert from "node:assert/strict";
import { spawnSync } from "node:child_process";
import { readFileSync, rmSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import test from "node:test";
import { resolveCandidateBase } from "../../../../scripts/merge-queue/candidate-base.mjs";
import {
SIGNING_KEY_MISSING_CAUSE,
composeCandidate,
fetchInputs,
prepareRepo,
scratchGit,
signingKeyPath,
} from "../../../../scripts/merge-queue/compose.mjs";
import { queuePrByCommit } from "../../../../scripts/merge-queue/history-map.mjs";
import { mergedPrsBetween, verifyComposition } from "../../../../scripts/merge-queue/land.mjs";
import { BOT, createSandbox, inheritedGitEnvCleared, prRef } from "./helpers/git-sandbox.mjs";
const BASE = "release/v1.0.0";
/** Fixed dates: two compositions of the same inputs differ only by what signing adds. */
const DATES = Object.freeze({
GIT_AUTHOR_DATE: "2026-11-20T12:00:00Z",
GIT_COMMITTER_DATE: "2026-11-20T12:00:00Z",
});
/** Why this machine cannot run the signature tests, or null when it can. */
function signingUnavailable() {
const keygen = spawnSync("ssh-keygen", ["-?"], { encoding: "utf8" });
if (keygen.error?.code === "ENOENT") return "ssh-keygen is not installed (needed to sign)";
const version = spawnSync("git", ["--version"], { encoding: "utf8" });
const match = /git version (\d+)\.(\d+)/.exec(version.stdout ?? "");
if (!match) return "git --version could not be read";
const [major, minor] = [Number(match[1]), Number(match[2])];
if (major < 2 || (major === 2 && minor < 34)) {
return `git ${match[1]}.${match[2]} cannot sign with SSH keys (2.34 or later)`;
}
return null;
}
const UNAVAILABLE = signingUnavailable();
/** A throwaway ed25519 key without a passphrase in `dir`: {keyPath, publicKey}, no .pub file. */
function makeKey(dir, name = "signing-key") {
const keyPath = join(dir, name);
const res = spawnSync(
"ssh-keygen",
["-q", "-t", "ed25519", "-N", "", "-C", "omni-queue-test", "-f", keyPath],
{ encoding: "utf8" }
);
assert.equal(res.status, 0, `ssh-keygen failed: ${res.stderr}`);
const publicKey = readFileSync(`${keyPath}.pub`, "utf8").trim();
// As in the job: only the private key is on disk (the workflow writes the secret alone).
rmSync(`${keyPath}.pub`);
return { keyPath, publicKey };
}
function setup(t) {
const sb = createSandbox({ base: BASE });
t.after(() => sb.cleanup());
const scratch = sb.newDir("scratch");
const logs = [];
const git = sb.scratchGit(scratch, {
env: { ...inheritedGitEnvCleared(), ...sb.isolationEnv, ...DATES },
log: (line) => logs.push(line),
});
prepareRepo({ git, remoteUrl: sb.remoteUrl, filter: null });
const keys = sb.newDir("keys");
return { sb, git, scratch, keys, logs };
}
/** Three independent PRs and a fourth that touches what the first touches (still clean). */
function publish(sb) {
return [
prRef(11, sb.publishPr(11, { "a.txt": "A\n" })),
prRef(12, sb.publishPr(12, { "b.txt": "B\n" })),
prRef(13, sb.publishPr(13, { "c/d.txt": "D\n" })),
];
}
function compose(git, prs, signing) {
const { baseSha, heads } = fetchInputs({ git, base: BASE, prs });
return composeCandidate({
git,
base: BASE,
baseSha,
prs,
batchId: "b7",
heads,
...(signing === undefined ? {} : { signing }),
});
}
/** The first-parent chain base..sha, oldest first, each commit as git stores it. */
function chain(git, baseSha, sha) {
const g = scratchGit(git);
const ids = g.out(["rev-list", "--first-parent", "--reverse", `${baseSha}..${sha}`]).split("\n");
return ids.map((id) => {
const raw = g.out(["cat-file", "commit", id]);
const field = (name) =>
raw
.split("\n")
.filter((line) => line.startsWith(`${name} `))
.map((line) => line.slice(name.length + 1));
return {
id,
raw,
tree: field("tree")[0],
parents: field("parent"),
author: field("author")[0],
committer: field("committer")[0],
message: g.out(["log", "-1", "--format=%B", id]),
signed: /^gpgsig -----BEGIN SSH SIGNATURE-----$/m.test(raw),
};
});
}
/** The commit object without its gpgsig header (the header and its continuation lines). */
function withoutSignature(raw) {
const lines = raw.split("\n");
const out = [];
for (let i = 0; i < lines.length; i++) {
if (lines[i].startsWith("gpgsig ")) {
while (lines[i + 1]?.startsWith(" ")) i++;
continue;
}
out.push(lines[i]);
}
return out.join("\n");
}
/** `git verify-commit` against an allowed-signers file listing `publicKey` for the bot. */
function verify(git, keys, sha, publicKey) {
const allowed = join(keys, `allowed-${Math.random().toString(16).slice(2)}`);
writeFileSync(allowed, `${BOT.email} namespaces="git" ${publicKey}\n`);
return scratchGit(git).run(
["-c", "gpg.format=ssh", "-c", `gpg.ssh.allowedSignersFile=${allowed}`, "verify-commit", sha],
{ allowFail: true }
);
}
test("signing: every merge commit is signed, verifies with the key, and is the unsigned composition plus a signature", (t) => {
if (UNAVAILABLE) return t.skip(UNAVAILABLE);
const { sb, git, keys, logs } = setup(t);
const { keyPath, publicKey } = makeKey(keys);
const prs = publish(sb);
const baseSha = sb.baseSha();
const unsigned = compose(git, prs);
const signed = compose(git, prs, { keyPath });
const composeLogs = [...logs]; // what the compositions logged (the checks below log too)
assert.ok(composeLogs.some((line) => /^git commit-tree .* -S -F -$/.test(line)));
assert.equal(unsigned.signing ?? null, null, "no signing asked: no report");
assert.deepEqual(signed.signing, { signed: 3, unsigned: 0, cause: null });
assert.deepEqual(
signed.included.map((p) => p.n),
unsigned.included.map((p) => p.n)
);
assert.equal(signed.treeSha, unsigned.treeSha, "the same tree");
assert.notEqual(signed.candidateSha, unsigned.candidateSha, "a signature is part of the commit");
const plain = chain(git, baseSha, unsigned.candidateSha);
const sealed = chain(git, baseSha, signed.candidateSha);
assert.equal(sealed.length, 3);
for (let i = 0; i < sealed.length; i++) {
const [u, s] = [plain[i], sealed[i]];
assert.equal(u.signed, false, `unsigned commit ${i}`);
assert.equal(s.signed, true, `signed commit ${i}`);
assert.equal(s.tree, u.tree, `tree ${i}`);
assert.equal(s.parents.length, 2);
assert.equal(s.parents[0], i === 0 ? baseSha : sealed[i - 1].id, `first parent ${i}`);
assert.equal(s.parents[1], u.parents[1], `second parent ${i} (the PR head)`);
assert.equal(s.author, u.author, `author ${i}`);
assert.equal(s.committer, u.committer, `committer ${i}`);
assert.ok(s.committer.startsWith(`${BOT.name} <`), `committer ${i} is the queue identity`);
assert.equal(s.message, u.message, `message ${i}`);
assert.equal(verify(git, keys, s.id, publicKey).code, 0, `verify-commit ${i}`);
assert.notEqual(verify(git, keys, u.id, publicKey).code, 0, `unsigned ${i} does not verify`);
}
// Up to its own (signed) first parent, the first commit is byte for byte the unsigned one.
assert.equal(withoutSignature(sealed[0].raw), plain[0].raw);
// Another key does not verify it: the check reads the signature, not just its presence.
const other = makeKey(keys, "other-key");
assert.notEqual(verify(git, keys, signed.candidateSha, other.publicKey).code, 0);
// The key path never shows in the git log lines or the result.
for (const line of composeLogs) {
assert.ok(!line.includes(keys), `log line names the key: ${line}`);
}
assert.ok(!JSON.stringify(signed).includes(keys));
});
test("signing: everything that re-reads a candidate reads a signed one exactly as an unsigned one", (t) => {
if (UNAVAILABLE) return t.skip(UNAVAILABLE);
const { sb, git, keys } = setup(t);
const { keyPath } = makeKey(keys);
const prs = publish(sb);
const baseSha = sb.baseSha();
const unsigned = compose(git, prs);
const signed = compose(git, prs, { keyPath });
for (const res of [unsigned, signed]) {
assert.deepEqual(
verifyComposition({
git,
expectedBaseSha: baseSha,
candidateSha: res.candidateSha,
prs,
treeSha: res.treeSha,
trees: true,
}),
{ ok: true }
);
assert.deepEqual(mergedPrsBetween(git, baseSha, res.candidateSha), [11, 12, 13]);
const message = scratchGit(git).out(["log", "-1", "--format=%B", res.candidateSha]);
assert.deepEqual(resolveCandidateBase({ message, headSha: res.candidateSha }), {
baseSha,
target: BASE,
source: "trailer",
});
const map = queuePrByCommit({
runGit: (args) => scratchGit(git).out(args),
range: `${baseSha}..${res.candidateSha}`,
});
assert.deepEqual(
prs.map((pr) => map.get(pr.head)?.pr),
[11, 12, 13]
);
}
});
test("signing: a signed commit with another tree, parents or trailers is still refused", (t) => {
if (UNAVAILABLE) return t.skip(UNAVAILABLE);
const { sb, git, keys } = setup(t);
const { keyPath } = makeKey(keys);
const prs = publish(sb).slice(0, 1);
const baseSha = sb.baseSha();
const good = compose(git, prs, { keyPath });
const [merge] = chain(git, baseSha, good.candidateSha);
const g = scratchGit(git);
const sign = (args, input) =>
g.out(
[
"-c",
"gpg.format=ssh",
"-c",
`user.signingkey=${keyPath}`,
"commit-tree",
"-S",
...args,
"-F",
"-",
],
{ input }
);
const baseTree = g.out(["rev-parse", `${baseSha}^{tree}`]);
const forged = {
// same parents and message, the base's tree: what lands would not be what was merged
tree: sign([baseTree, "-p", baseSha, "-p", prs[0].head], `${merge.message}\n`),
// same tree and message, a single parent: not a queue merge commit
parents: sign([merge.tree, "-p", baseSha], `${merge.message}\n`),
// same tree and parents, trailers naming another base
message: sign(
[merge.tree, "-p", baseSha, "-p", prs[0].head],
`${merge.message.replace(baseSha, prs[0].head)}\n`
),
};
for (const [what, sha] of Object.entries(forged)) {
const verdict = verifyComposition({
git,
expectedBaseSha: baseSha,
candidateSha: sha,
prs,
trees: true,
});
assert.equal(verdict.ok, false, `a signed commit with another ${what} is refused`);
}
});
test("signing: a missing key composes unsigned, names the cause, and never the path", (t) => {
// No ssh-keygen needed: nothing is signed.
const { sb, git, keys } = setup(t);
const prs = publish(sb);
const missing = join(keys, "no-such-key");
const unsigned = compose(git, prs);
const degraded = compose(git, prs, { keyPath: missing });
assert.equal(degraded.candidateSha, unsigned.candidateSha, "exactly the unsigned composition");
assert.deepEqual(degraded.signing, { signed: 0, unsigned: 3, cause: SIGNING_KEY_MISSING_CAUSE });
assert.ok(!degraded.signing.cause.includes(keys));
const none = compose(git, prs, { keyPath: null });
assert.equal(none.candidateSha, unsigned.candidateSha);
assert.deepEqual(none.signing, { signed: 0, unsigned: 3, cause: SIGNING_KEY_MISSING_CAUSE });
});
test("signing: a key git cannot sign with composes unsigned and says so, without the path", (t) => {
if (UNAVAILABLE) return t.skip(UNAVAILABLE);
const { sb, git, keys, logs } = setup(t);
const bad = join(keys, "not-a-key");
writeFileSync(bad, "this is not an ssh private key\n", { mode: 0o600 });
const prs = publish(sb);
const unsigned = compose(git, prs);
const degraded = compose(git, prs, { keyPath: bad });
assert.equal(degraded.candidateSha, unsigned.candidateSha, "exactly the unsigned composition");
assert.equal(degraded.signing.signed, 0);
assert.equal(degraded.signing.unsigned, 3);
assert.match(degraded.signing.cause, /^git could not sign a merge commit \(exit \d+\)$/);
for (const line of logs) assert.ok(!line.includes(keys), `log line names the key: ${line}`);
});
test("signingKeyPath: the file the workflow writes under RUNNER_TEMP, null without it", () => {
assert.equal(signingKeyPath("/runner/_temp"), "/runner/_temp/omni-queue-signing/signing-key");
assert.equal(signingKeyPath(""), null);
assert.equal(signingKeyPath(undefined), null);
});

View File

@@ -0,0 +1,364 @@
// omni-queue tick with the owner voice (config `voice: "owner"`) and signed merge commits
// (config `landing.signing: "ssh"`): which client performs each write, the fallback to the App's
// token that never loses a message, and the alert when a batch is composed unsigned.
import assert from "node:assert/strict";
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import test from "node:test";
import { loadConfig } from "../../../scripts/merge-queue/config.mjs";
import { commentMarker } from "../../../scripts/merge-queue/contracts.mjs";
import { upsertDashboard } from "../../../scripts/merge-queue/dashboard.mjs";
import { createTickDeps, recordTickFailure } from "../../../scripts/merge-queue/tick.mjs";
import { VOICE_FALLBACK_PREFIX } from "../../../scripts/merge-queue/voice.mjs";
import { startFakeGitHub } from "./helpers/fake-github.mjs";
import { BASE, OWNER_IDENTITY, createFakeGitHub, createHarness } from "./helpers/tick-fakes.mjs";
const OWNER = "owner-login";
/** The writes a pull request or an issue shows to people: what the owner voice performs. */
const VOICE_WRITES = new Set([
"commentOnce",
"createIssueComment",
"removeLabel",
"createIssue",
"updateIssue",
]);
/**
* Turn the owner voice on in a harness: a second fake client (writes recorded with client
* "owner") that shares the App fake's pull requests, issues and comments, as two tokens share
* one repository. `token: false` = OMNI_QUEUE_LAND_TOKEN missing.
*/
function ownerVoice(h, { token = true, login = async () => OWNER } = {}) {
const owner = createFakeGitHub({ calls: h.calls, client: "owner" });
for (const key of ["pulls", "issues", "comments", "timelines", "branches"])
owner[key] = h.gh[key];
h.config.voice = "owner";
h.deps.voiceGh = token ? owner : null;
h.deps.ownerLogin = token ? login : null;
return owner;
}
/**
* The real dashboard upsert (issue create/update through the client it is given), with a body
* that changes with the history, so a tick that records events updates it.
*/
function realDashboard(h) {
h.modules.dashboard.upsertDashboard = upsertDashboard;
h.modules.dashboard.renderDashboard = (input) =>
`dashboard ${input.base}: ${input.state.history.map((e) => e.type).join(", ")}`;
}
const by = (h, client) => h.calls.filter((c) => c.client === client).map((c) => c.name);
const voiceWritesBy = (h, client) => by(h, client).filter((name) => VOICE_WRITES.has(name));
const types = (state) => state.history.map((e) => e.type);
const voiceErrors = (state) =>
state.history.filter((e) => e.type === "error" && e.detail.startsWith(VOICE_FALLBACK_PREFIX));
async function startBatch(h, prs) {
for (const n of prs) h.addPr(n);
await h.tick();
return (await h.state()).inFlight;
}
test("voice app (the default): every write is the App's, as before", async () => {
const h = createHarness({ mode: "live" });
assert.equal(h.config.voice, "app", "shipped default");
realDashboard(h);
const f = await startBatch(h, [1, 2]);
h.runCi(f.candidateSha);
await h.tick();
assert.deepEqual(by(h, "owner"), []);
assert.ok(voiceWritesBy(h, "app").includes("commentOnce"));
assert.ok(voiceWritesBy(h, "app").includes("removeLabel"));
assert.ok(voiceWritesBy(h, "app").includes("createIssue"), "the App opens the dashboard");
});
test("owner voice, live landing: comments, label removals and the dashboard are the owner's; statuses stay the App's", async () => {
const h = createHarness({ mode: "live" });
ownerVoice(h);
realDashboard(h);
const f = await startBatch(h, [1, 2]);
h.runCi(f.candidateSha);
await h.tick();
const state = await h.state();
assert.deepEqual(types(state), ["batch-started", "checks-green", "land-blessed", "landed"]);
assert.deepEqual(voiceWritesBy(h, "app"), [], "the App performs none of the visible writes");
const owner = voiceWritesBy(h, "owner");
assert.equal(owner.filter((n) => n === "removeLabel").length, 4, "two labels on two PRs");
assert.equal(owner.filter((n) => n === "commentOnce").length, 2, "one landed comment each");
assert.equal(owner.filter((n) => n === "createIssue").length, 1, "the dashboard issue");
assert.ok(owner.includes("updateIssue"), "and its body on the next change");
// Commit statuses, the state branch and the candidate are never the owner's.
for (const name of [
"createCommitStatus",
"putFileContent",
"createOrphanBranch",
"deleteBranch",
]) {
assert.ok(!by(h, "owner").includes(name), name);
}
assert.ok(by(h, "app").includes("createCommitStatus"), "the App blesses the candidate");
assert.deepEqual(voiceErrors(state), [], "nothing fell back");
});
test("owner voice, live dequeue: the base-conflict comment and label removal are the owner's", async () => {
const h = createHarness({ mode: "live" });
ownerVoice(h);
h.world.baseConflicts.add(1);
h.addPr(1);
await h.tick();
const owner = h.calls.filter((c) => c.client === "owner" && VOICE_WRITES.has(c.name));
assert.deepEqual(
owner.map((c) => [c.name, c.args[0]]),
[
["removeLabel", 1],
["commentOnce", 1],
]
);
assert.match(owner[1].args[1], /^base-conflict:/);
assert.deepEqual(voiceWritesBy(h, "app"), []);
});
test("owner voice, shadow: nothing on pull requests by anybody; the dashboard is the owner's", async () => {
const h = createHarness({ mode: "shadow" });
ownerVoice(h);
realDashboard(h);
h.world.baseConflicts.add(1);
h.addPr(1);
h.addPr(2);
await h.tick();
const state = await h.state();
assert.ok(types(state).includes("would-dequeue"));
for (const client of ["app", "owner"]) {
for (const name of ["commentOnce", "removeLabel", "createIssueComment"]) {
assert.ok(!by(h, client).includes(name), `${client}: ${name}`);
}
}
assert.deepEqual(voiceWritesBy(h, "owner"), ["createIssue"], "the dashboard issue");
assert.deepEqual(voiceWritesBy(h, "app"), []);
});
test("owner voice, the stalled alert on the dashboard is the owner's", async () => {
const h = createHarness({ mode: "shadow" });
h.config.approvers = ["octo-approver"];
ownerVoice(h);
await h.tick({ action: "pause" });
h.clock.advance(121);
await h.tick();
const state = await h.state();
assert.equal(state.stalled.notified, true);
const alert = h.calls.find((c) => c.name === "commentOnce" && /^stalled:/.test(c.args[1]));
assert.equal(alert.client, "owner");
});
test("owner voice without OMNI_QUEUE_LAND_TOKEN: every message still goes out, as the App, and one error event says so", async () => {
const h = createHarness({ mode: "live" });
ownerVoice(h, { token: false });
realDashboard(h);
const f = await startBatch(h, [1, 2]);
h.runCi(f.candidateSha);
const result = await h.tick();
const state = await h.state();
assert.deepEqual(by(h, "owner"), []);
const app = voiceWritesBy(h, "app");
assert.equal(app.filter((n) => n === "removeLabel").length, 4);
assert.equal(app.filter((n) => n === "commentOnce").length, 2);
assert.ok(app.includes("createIssue"));
// The first tick (dashboard creation) and the landing tick each record it once.
const errors = voiceErrors(state);
assert.equal(errors.length, 1, "one event while the cause stays the same");
assert.match(errors[0].detail, /OMNI_QUEUE_LAND_TOKEN is not set/);
assert.ok(
result.decisions.some((d) => /owner voice: .*#1.* written with the App's token/.test(d)),
result.decisions
);
// A tick that changes nothing else adds no event: the fallback never makes its own churn.
await h.tick();
assert.equal(voiceErrors(await h.state()).length, 1);
});
test("owner voice: a write GitHub refuses (403) is retried as the App within the tick, recorded once", async () => {
const h = createHarness({ mode: "live" });
const owner = ownerVoice(h);
owner.writeError = (method) =>
VOICE_WRITES.has(method)
? Object.assign(new Error(`${method} → 403: Resource not accessible`), { status: 403 })
: null;
realDashboard(h);
const f = await startBatch(h, [1, 2]);
h.runCi(f.candidateSha);
await h.tick();
const state = await h.state();
assert.deepEqual(
types(state).filter((t) => t !== "error"),
["batch-started", "checks-green", "land-blessed", "landed"]
);
const app = voiceWritesBy(h, "app");
assert.equal(app.filter((n) => n === "removeLabel").length, 4, "each refused removal redone");
assert.equal(app.filter((n) => n === "commentOnce").length, 2, "each refused comment redone");
const errors = voiceErrors(state);
assert.equal(errors.length, 1);
assert.match(errors[0].detail, /refused the owner's token \(403\)/);
// Every PR got its landed comment exactly once.
for (const n of [1, 2]) {
const comments = (h.gh.comments.get(n) ?? []).filter((c) =>
c.body.includes(commentMarker(`landed:${h.gh.pulls.get(n).headSha.slice(0, 12)}`))
);
assert.equal(comments.length, 1, `#${n}`);
}
});
test("owner voice, failure path: the stalled alert and a missing dashboard are the owner's, the App's on a refusal", async () => {
for (const refuse of [false, true]) {
const h = createHarness({ mode: "shadow" });
h.config.approvers = ["octo-approver"];
const owner = ownerVoice(h);
if (refuse) {
owner.writeError = () => Object.assign(new Error("→ 401: Bad credentials"), { status: 401 });
}
await h.tick();
const warnings = [];
for (let i = 0; i < 3; i++) {
h.clock.advance(5);
await recordTickFailure(h.deps, BASE, "GitHub 502", (m) => warnings.push(m));
}
const state = await h.state();
assert.equal(state.stalled.notified, true, `refuse=${refuse}: delivered`);
const created = h.calls.find((c) => c.name === "createIssue");
const alert = h.calls.find((c) => c.name === "commentOnce" && /^stalled:/.test(c.args[1]));
const expected = refuse ? "app" : "owner";
assert.equal(created.client, expected, `refuse=${refuse}: dashboard`);
assert.equal(alert.client, expected, `refuse=${refuse}: alert`);
assert.equal(
warnings.some((w) => /owner voice: .* written with the App's token \(.*401/.test(w)),
refuse,
warnings.join("\n")
);
}
});
test("owner voice, dry-run: neither client writes", async () => {
const h = createHarness({ mode: "live" });
ownerVoice(h);
h.world.baseConflicts.add(1);
h.addPr(1);
await h.tick({ action: "dry-run" });
assert.deepEqual(by(h, "owner"), []);
assert.deepEqual(voiceWritesBy(h, "app"), []);
});
// ───────────────────────────── signed merge commits ─────────────────────────────
/** Compose through the fake, reporting `signing` as compose.composeCandidate would. */
function signingReport(h, report) {
const compose = h.modules.compose.composeCandidate;
const seen = [];
h.modules.compose.composeCandidate = (input) => {
seen.push(input.signing);
const result = compose(input);
return input.signing ? { ...result, signing: report(result) } : result;
};
return seen;
}
test("signing on: every composition is asked to sign; an unsigned batch is one error event", async () => {
const h = createHarness({ mode: "shadow", actor: "owner" });
h.config.landing = { ...h.config.landing, signing: "ssh" };
h.deps.signing = { keyPath: "/runner/temp/omni-queue-signing/signing-key" };
const seen = signingReport(h, (r) => ({
signed: 0,
unsigned: r.included.length,
cause: "no signing key file in the job (is the OMNI_QUEUE_SIGNING_KEY secret set?)",
}));
const f = await startBatch(h, [1, 2]);
assert.deepEqual(seen, [h.deps.signing]);
const state = await h.state();
const errors = state.history.filter((e) => e.type === "error");
assert.equal(errors.length, 1);
assert.equal(errors[0].batchId, f.batchId);
assert.equal(
errors[0].detail,
`${f.batchId}: 2 merge commit(s) composed unsigned: no signing key file in the job ` +
"(is the OMNI_QUEUE_SIGNING_KEY secret set?)"
);
assert.ok(!JSON.stringify(state).includes("/runner/temp"), "the key path is never stored");
assert.ok(state.inFlight, "the batch is composed and tested anyway (degrade, never block)");
});
test("signing on: a fully signed batch records nothing; signing off passes nothing", async () => {
const signed = createHarness({ mode: "shadow", actor: "owner" });
signed.config.landing = { ...signed.config.landing, signing: "ssh" };
signed.deps.signing = { keyPath: "/k" };
signingReport(signed, (r) => ({ signed: r.included.length, unsigned: 0, cause: null }));
await startBatch(signed, [1]);
assert.deepEqual(
(await signed.state()).history.filter((e) => e.type === "error"),
[]
);
const off = createHarness({ mode: "shadow" });
const seen = signingReport(off, () => assert.fail("no signing report without signing"));
await startBatch(off, [1]);
assert.deepEqual(seen, [undefined], "composeCandidate is not given `signing`");
});
test("createTickDeps: voice owner gets the owner's client and login reader; signing gets the key path", async (t) => {
const fake = await startFakeGitHub({ token: "ghs_appToken", actor: "omni-queue[bot]" });
t.after(() => fake.close());
fake.tokenActors.set("github_pat_owner", OWNER);
const dir = mkdtempSync(join(tmpdir(), "omni-queue-voice-deps-"));
t.after(() => rmSync(dir, { recursive: true, force: true }));
const owner = {
mode: "merge-ff",
actor: "owner",
identity: { ...OWNER_IDENTITY },
statusContext: "omni-queue/land",
};
const writeConfig = (name, patch) => {
const path = join(dir, name);
writeFileSync(path, JSON.stringify({ ...loadConfig(), ...patch }));
return path;
};
const env = {
OMNI_QUEUE_TOKEN: "ghs_appToken",
GITHUB_REPOSITORY: fake.repository,
GITHUB_API_URL: fake.url,
RUNNER_TEMP: dir,
};
const deps = (patch, extra = {}) =>
createTickDeps({ ...env, ...extra, OMNI_QUEUE_CONFIG: writeConfig("c.json", patch) });
const shipped = deps({}, { OMNI_QUEUE_LAND_TOKEN: "github_pat_owner" });
assert.equal(shipped.voiceGh, null, "voice app: no owner client for the voice");
assert.equal(shipped.ownerLogin, null);
assert.equal(shipped.signing, null, "signing none");
const voiced = deps({ voice: "owner" }, { OMNI_QUEUE_LAND_TOKEN: "github_pat_owner" });
assert.ok(voiced.voiceGh, "the owner's client");
assert.equal(await voiced.ownerLogin(), OWNER, "resolved from the token itself");
assert.equal(await voiced.ownerLogin(), OWNER);
assert.equal(fake.requests.filter((r) => r.path === "!/user").length, 1, "read once");
const tokenless = deps({ voice: "owner" });
assert.equal(tokenless.voiceGh, null, "no token: the voice falls back to the App");
assert.equal(tokenless.ownerLogin, null);
const appActor = deps(
{ voice: "owner", landing: { mode: "merge-ff" } },
{ OMNI_QUEUE_LAND_TOKEN: "github_pat_owner" }
);
assert.ok(appActor.voiceGh, "the voice does not depend on who lands");
assert.equal(appActor.landGh, appActor.gh, "the App still lands with actor app");
const signing = deps({ landing: { ...owner, signing: "ssh" } });
assert.deepEqual(signing.signing, {
keyPath: join(dir, "omni-queue-signing", "signing-key"),
});
const noTemp = createTickDeps({
...env,
RUNNER_TEMP: "",
OMNI_QUEUE_CONFIG: writeConfig("d.json", { landing: { ...owner, signing: "ssh" } }),
});
assert.deepEqual(noTemp.signing, { keyPath: null }, "asked for, no file: degrade and alert");
});

View File

@@ -0,0 +1,238 @@
// omni-queue owner voice (scripts/merge-queue/voice.mjs): which token performs the queue's
// human-visible writes (comments, label removals, the dashboard and other issues), and the
// fallback to the App's token that keeps every message delivered.
import assert from "node:assert/strict";
import test from "node:test";
import {
VOICES,
createOwnerLoginReader,
createOwnerVoice,
} from "../../../scripts/merge-queue/voice.mjs";
/** A refusal as github.mjs throws it (GitHubError carries `status`). */
const refused = (status) =>
Object.assign(new Error(`POST /x → ${status}: Resource not accessible`), {
name: "GitHubError",
status,
});
/**
* A client double: every call is recorded as [name, ...args] in `calls` (shared, tagged with
* `who`); `fail` = (name) => Error|null makes a call throw instead.
*/
function client(who, calls, { fail = () => null } = {}) {
const call =
(name, result) =>
async (...args) => {
calls.push([who, name, ...args]);
const error = fail(name);
if (error) throw error;
return typeof result === "function" ? result(...args) : result;
};
return {
listIssues: call("listIssues", []),
commentOnce: call("commentOnce", { posted: true }),
removeLabel: call("removeLabel", undefined),
createIssue: call("createIssue", { number: 7 }),
updateIssue: call("updateIssue", undefined),
};
}
function setup({ owner = true, ownerFail, appFail, login = async () => "owner-login" } = {}) {
const calls = [];
const fallbacks = [];
const app = client("app", calls, { fail: appFail });
const ownerGh = owner ? client("owner", calls, { fail: ownerFail }) : null;
const voice = createOwnerVoice({
app,
owner: ownerGh,
ownerLogin: owner ? login : null,
onFallback: (cause, what) => fallbacks.push({ cause, what }),
});
return { calls, fallbacks, voice, app };
}
test("VOICES: the App (default) or the owner", () => {
assert.deepEqual(VOICES, ["app", "owner"]);
});
test("owner voice: every human-visible write goes out with the owner's token", async () => {
const { calls, fallbacks, voice, app } = setup();
await voice.commentOnce(12, "culprit:abc", "body");
await voice.removeLabel(12, "omni-queue");
assert.deepEqual(await voice.createIssue({ title: "t", body: "b", labels: ["x"] }), {
number: 7,
});
await voice.updateIssue(7, { body: "b2" });
assert.deepEqual(calls, [
// the owner posts; the App's client reads the comments; both logins' markers count
[
"owner",
"commentOnce",
12,
"culprit:abc",
"body",
{ reader: app, alsoLogins: ["owner-login"] },
],
["owner", "removeLabel", 12, "omni-queue"],
["owner", "createIssue", { title: "t", body: "b", labels: ["x"] }],
["owner", "updateIssue", 7, { body: "b2" }],
]);
assert.deepEqual(fallbacks, []);
});
test("owner voice: commentOnce reads through the App's client", async () => {
const calls = [];
const app = client("app", calls);
const owner = client("owner", calls);
const voice = createOwnerVoice({ app, owner, ownerLogin: async () => "owner-login" });
await voice.commentOnce(3, "k", "b");
const [, , , , , opts] = calls[0];
assert.equal(opts.reader, app, "the App's client lists the comments");
assert.deepEqual(opts.alsoLogins, ["owner-login"]);
});
test("owner voice: reads stay with the App", async () => {
const { calls, voice } = setup();
await voice.listIssues({ labels: ["omni-queue-dashboard"], state: "open" });
assert.deepEqual(calls, [
["app", "listIssues", { labels: ["omni-queue-dashboard"], state: "open" }],
]);
});
test("owner voice without the owner's token: the App writes, and the fallback is reported", async () => {
const { calls, fallbacks, voice } = setup({ owner: false });
await voice.commentOnce(12, "k", "body");
await voice.removeLabel(12, "omni-queue");
await voice.createIssue({ title: "t", body: "b" });
await voice.updateIssue(7, { body: "b2" });
assert.deepEqual(
calls.map(([who, name]) => `${who}:${name}`),
["app:commentOnce", "app:removeLabel", "app:createIssue", "app:updateIssue"]
);
// No owner login is known: the App's commentOnce counts the App's markers only.
assert.deepEqual(calls[0], ["app", "commentOnce", 12, "k", "body"]);
assert.equal(fallbacks.length, 4);
for (const { cause } of fallbacks) assert.match(cause, /OMNI_QUEUE_LAND_TOKEN is not set/);
assert.match(fallbacks[0].what, /#12/);
});
for (const status of [401, 403]) {
test(`owner voice: a ${status} on an owner write is retried with the App's token`, async () => {
const { calls, fallbacks, voice } = setup({ ownerFail: () => refused(status) });
assert.deepEqual(await voice.commentOnce(12, "k", "body"), { posted: true });
await voice.removeLabel(12, "omni-queue");
assert.deepEqual(await voice.createIssue({ title: "t", body: "b" }), { number: 7 });
await voice.updateIssue(7, { body: "b2" });
assert.deepEqual(
calls.map(([who, name]) => `${who}:${name}`),
[
"owner:commentOnce",
"app:commentOnce",
"owner:removeLabel",
"app:removeLabel",
"owner:createIssue",
"app:createIssue",
"owner:updateIssue",
"app:updateIssue",
]
);
// The App's retry still recognises the owner's earlier markers (the login is known).
assert.deepEqual(calls[1], [
"app",
"commentOnce",
12,
"k",
"body",
{ alsoLogins: ["owner-login"] },
]);
assert.deepEqual(calls[3], ["app", "removeLabel", 12, "omni-queue"]);
assert.equal(fallbacks.length, 4);
for (const { cause } of fallbacks) assert.match(cause, new RegExp(`refused.*\\(${status}\\)`));
});
}
test("owner voice: an owner error that is not a refusal is not retried as the App", async () => {
const { calls, fallbacks, voice } = setup({ ownerFail: () => refused(502) });
await assert.rejects(voice.commentOnce(12, "k", "b"), /502/);
assert.deepEqual(
calls.map(([who, name]) => `${who}:${name}`),
["owner:commentOnce"]
);
assert.deepEqual(fallbacks, []);
});
test("owner voice: when the App's fallback write fails too, the error surfaces (never dropped)", async () => {
const { voice } = setup({
ownerFail: () => refused(403),
appFail: () => refused(500),
});
await assert.rejects(voice.updateIssue(7, { body: "b" }), /500/);
});
test("owner voice: an owner login GitHub refuses sends every write as the App", async () => {
let reads = 0;
const login = async () => {
reads += 1;
throw refused(401);
};
const { calls, fallbacks, voice } = setup({ login });
await voice.commentOnce(12, "k", "b");
await voice.removeLabel(12, "omni-queue");
assert.deepEqual(
calls.map(([who, name]) => `${who}:${name}`),
["app:commentOnce", "app:removeLabel"]
);
assert.deepEqual(calls[0], ["app", "commentOnce", 12, "k", "b"]);
assert.equal(fallbacks.length, 2);
assert.match(fallbacks[0].cause, /login.*\(401\)/);
assert.equal(reads, 2, "the voice asks its reader; the reader memoizes (below)");
});
test("owner voice: a login that is not a user's login is never trusted", async () => {
for (const bad of ["", "omni-queue[bot]", "has space", null, "-leading"]) {
const { calls, fallbacks, voice } = setup({ login: async () => bad });
await voice.commentOnce(12, "k", "b");
assert.deepEqual(calls, [["app", "commentOnce", 12, "k", "b"]], JSON.stringify(bad));
assert.match(fallbacks[0].cause, /does not name a user/);
}
});
test("owner voice: a login read that fails without a refusal fails the write (transient)", async () => {
const { calls, voice } = setup({
login: async () => {
throw refused(503);
},
});
await assert.rejects(voice.removeLabel(12, "x"), /503/);
assert.deepEqual(calls, []);
});
test("createOwnerLoginReader: one GET /user per process, a refusal is remembered, a 5xx is not", async () => {
let n = 0;
const answers = [() => "owner-login"];
const gh = {
async getAuthenticatedLogin() {
n += 1;
return answers.shift()();
},
};
const read = createOwnerLoginReader(gh);
assert.equal(await read(), "owner-login");
assert.equal(await read(), "owner-login");
assert.equal(n, 1);
let m = 0;
const failing = createOwnerLoginReader({
async getAuthenticatedLogin() {
m += 1;
if (m === 1) throw refused(503);
throw refused(401);
},
});
await assert.rejects(failing(), /503/);
await assert.rejects(failing(), /401/);
await assert.rejects(failing(), /401/);
assert.equal(m, 2, "the transient error is retried, the refusal is not");
assert.equal(createOwnerLoginReader(null), null);
});

View File

@@ -14,6 +14,7 @@ import {
readdirSync,
readFileSync,
rmSync,
statSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
@@ -21,6 +22,7 @@ import { join } from "node:path";
import test from "node:test";
import { load } from "js-yaml";
import { botIdentity, candidateRef } from "../../../scripts/merge-queue/contracts.mjs";
import { signingKeyPath } from "../../../scripts/merge-queue/compose.mjs";
import { TICK_ACTIONS } from "../../../scripts/merge-queue/tick.mjs";
import { evaluateAdmission } from "../../../scripts/quality/admission-verdict.mjs";
@@ -1042,6 +1044,7 @@ test("least privilege: no default token scopes, App token scoped per job", () =>
"OMNI_QUEUE_APP_CLIENT_ID",
"OMNI_QUEUE_APP_PRIVATE_KEY",
"OMNI_QUEUE_LAND_TOKEN",
"OMNI_QUEUE_SIGNING_KEY",
]);
assert.doesNotMatch(queueText, /GITHUB_TOKEN|github\.token/, "the queue never uses GITHUB_TOKEN");
});
@@ -1134,6 +1137,71 @@ test("omni-queue.yml: the tick may write statuses and receives the land token",
assert.equal(step.env.GITHUB_TRIGGERING_ACTOR, "${{ github.triggering_actor }}");
});
test("omni-queue.yml: the signing key reaches one step of the tick, and the approval job no owner secret", () => {
const holders = Object.entries(queue.jobs).flatMap(([id, job]) =>
job.steps
.filter((s) => JSON.stringify(s).includes("OMNI_QUEUE_SIGNING_KEY"))
.map((s) => `${id}: ${s.name}`)
);
assert.deepEqual(holders, ["tick: Write the merge-commit signing key"]);
const write = stepNamed("tick", "Write the merge-commit signing key");
assert.deepEqual(write.env, { OMNI_QUEUE_SIGNING_KEY: "${{ secrets.OMNI_QUEUE_SIGNING_KEY }}" });
// The approval job runs on label events with minimal permissions: no owner secret at all.
const approval = JSON.stringify(queue.jobs.approval);
assert.doesNotMatch(approval, /OMNI_QUEUE_LAND_TOKEN|OMNI_QUEUE_SIGNING_KEY/);
// Order: the key is on disk before the tick runs, and removed after it, whatever happened.
const names = queue.jobs.tick.steps.map((s) => s.name ?? s.uses);
const at = (name) => names.indexOf(name);
assert.ok(at("Write the merge-commit signing key") < at("Run one queue tick"));
assert.equal(names.at(-1), "Remove the merge-commit signing key");
const remove = stepNamed("tick", "Remove the merge-commit signing key");
assert.equal(remove.if, "always()", "removed on failure and on cancellation too");
assert.equal(remove.env, undefined, "the removal needs no secret");
// The tick reads the file at the path compose.signingKeyPath derives from RUNNER_TEMP.
assert.equal(signingKeyPath("$RUNNER_TEMP"), "$RUNNER_TEMP/omni-queue-signing/signing-key");
assert.match(String(write.run), /"\$RUNNER_TEMP\/omni-queue-signing\/signing-key"/);
// The key is never printed: no tracing, no echo of the variable.
for (const step of [write, remove]) {
assert.doesNotMatch(String(step.run), /set\s+-[a-z]*x|\becho\b[^\n]*OMNI_QUEUE_SIGNING_KEY/);
}
});
test("the signing-key steps write the key 0600 under RUNNER_TEMP, skip without a secret, and remove it", (t) => {
const write = stepNamed("tick", "Write the merge-commit signing key");
const remove = stepNamed("tick", "Remove the merge-commit signing key");
const key =
"-----BEGIN OPENSSH PRIVATE KEY-----\nAAAAfakekeymaterial\n-----END OPENSSH PRIVATE KEY-----";
const temp = mkdtempSync(join(tmpdir(), "omni-queue-runner-temp-"));
t.after(() => rmSync(temp, { recursive: true, force: true }));
const file = join(temp, "omni-queue-signing", "signing-key");
const none = runStep(t, write, { RUNNER_TEMP: temp, OMNI_QUEUE_SIGNING_KEY: "" });
assert.equal(none.code, 0, none.stderr);
assert.equal(existsSync(file), false, "no secret: no file, the tick composes unsigned");
const res = runStep(t, write, { RUNNER_TEMP: temp, OMNI_QUEUE_SIGNING_KEY: key });
assert.equal(res.code, 0, res.stderr);
assert.equal(readFileSync(file, "utf8"), `${key}\n`);
assert.equal(statSync(file).mode & 0o777, 0o600, "readable by the runner user only");
assert.equal(statSync(join(temp, "omni-queue-signing")).mode & 0o777, 0o700);
assert.ok(!`${res.stdout}${res.stderr}`.includes("fakekeymaterial"), "never printed");
assert.ok(!`${res.stdout}${res.stderr}`.includes(temp), "the path is not printed either");
// A key that cannot be written never fails the job: the tick runs and composes unsigned.
const notADir = join(temp, "plain-file");
writeFileSync(notADir, "");
const blocked = runStep(t, write, { RUNNER_TEMP: notADir, OMNI_QUEUE_SIGNING_KEY: key });
assert.equal(blocked.code, 0, blocked.stderr);
assert.match(blocked.stdout, /::warning::the merge-commit signing key could not be written/);
assert.ok(!`${blocked.stdout}${blocked.stderr}`.includes("fakekeymaterial"));
const gone = runStep(t, remove, { RUNNER_TEMP: temp });
assert.equal(gone.code, 0, gone.stderr);
assert.equal(existsSync(join(temp, "omni-queue-signing")), false);
// Removing again (no key was written) is not an error.
assert.equal(runStep(t, remove, { RUNNER_TEMP: temp }).code, 0);
});
test("the tick's test/sandbox overrides are never set by the real workflow", () => {
// tick.createTickDeps honours them so the end-to-end test can point the queue at a local bare
// repository, an alternative config and a fake API; production must use the real remote, the

View File

@@ -49,14 +49,22 @@ function makeRequest(url: string, options?: RequestInit): NextRequest {
return Object.assign(new Request(url, options), { ip: "127.0.0.1" }) as unknown as NextRequest;
}
function postVault(vaultPath: string): Promise<Response> {
return route.POST(
makeRequest("http://localhost/api/settings/obsidian/webdav", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ vaultPath }),
})
);
/**
* POST carrying an operator credential (dashboard session). Choosing the vault is an
* operator-only action on this ALWAYS_PROTECTED route (CodeQL #1372/#1373): the handler no
* longer treats an anonymous open-mode caller as the operator — the authz pipeline already
* refused that caller over HTTP — so the tests below that enable WebDAV sign in first.
*/
async function makeOperatorPost(body: Record<string, unknown>): Promise<NextRequest> {
const req = await makeManagementSessionRequest("http://localhost/api/settings/obsidian/webdav", {
method: "POST",
body,
});
return Object.assign(req, { ip: "127.0.0.1" }) as unknown as NextRequest;
}
async function postVault(vaultPath: string): Promise<Response> {
return route.POST(await makeOperatorPost({ vaultPath }));
}
async function errorMessageOf(res: Response): Promise<string | undefined> {
@@ -113,11 +121,7 @@ test("GET with no config → webdavEnabled:false, all creds null", async () => {
test("POST with a valid temp dir → returns { username, password }, GET shows enabled", async () => {
const vaultDir = fs.mkdtempSync(path.join(os.tmpdir(), "omni-vault-"));
try {
const req = makeRequest("http://localhost/api/settings/obsidian/webdav", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ vaultPath: vaultDir }),
});
const req = await makeOperatorPost({ vaultPath: vaultDir });
const res = await route.POST(req);
assert.equal(res.status, 200);
@@ -154,13 +158,7 @@ test("GET masks the WebDAV password for anonymous callers but reveals it to a ma
const vaultDir = fs.mkdtempSync(path.join(os.tmpdir(), "omni-vault-62vw-"));
try {
// Enable WebDAV so there is a stored password to leak.
const enableRes = await route.POST(
makeRequest("http://localhost/api/settings/obsidian/webdav", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ vaultPath: vaultDir }),
})
);
const enableRes = await route.POST(await makeOperatorPost({ vaultPath: vaultDir }));
assert.equal(enableRes.status, 200);
// Anonymous (open-mode) caller: password masked, flag still set.
@@ -192,11 +190,7 @@ test("GET masks the WebDAV password for anonymous callers but reveals it to a ma
test("POST with a non-existent path → 400, body does NOT contain a stack trace", async () => {
const nonExistentPath = path.join(os.tmpdir(), "omni-nonexistent-vault-" + Date.now());
const req = makeRequest("http://localhost/api/settings/obsidian/webdav", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ vaultPath: nonExistentPath }),
});
const req = await makeOperatorPost({ vaultPath: nonExistentPath });
const res = await route.POST(req);
assert.equal(res.status, 400);
@@ -276,11 +270,7 @@ test("POST with a directory unrelated to the data directory still succeeds (sibl
});
test("POST with invalid body (missing vaultPath) → 400", async () => {
const req = makeRequest("http://localhost/api/settings/obsidian/webdav", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({}),
});
const req = await makeOperatorPost({});
const res = await route.POST(req);
assert.equal(res.status, 400);
});
@@ -289,11 +279,7 @@ test("DELETE after enable → webdavEnabled:false, creds cleared in GET", async
const vaultDir = fs.mkdtempSync(path.join(os.tmpdir(), "omni-vault2-"));
try {
// Enable first
const enableReq = makeRequest("http://localhost/api/settings/obsidian/webdav", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ vaultPath: vaultDir }),
});
const enableReq = await makeOperatorPost({ vaultPath: vaultDir });
const enableRes = await route.POST(enableReq);
assert.equal(enableRes.status, 200);
@@ -322,11 +308,7 @@ test("GET when disabled does not leak password even if stale data exists", async
const vaultDir = fs.mkdtempSync(path.join(os.tmpdir(), "omni-vault3-"));
try {
// Enable, then disable
const enableReq = makeRequest("http://localhost/api/settings/obsidian/webdav", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ vaultPath: vaultDir }),
});
const enableReq = await makeOperatorPost({ vaultPath: vaultDir });
await route.POST(enableReq);
const deleteReq = makeRequest("http://localhost/api/settings/obsidian/webdav", {
method: "DELETE",

View File

@@ -0,0 +1,236 @@
// CodeQL js/path-injection #1371 (src/lib/localCorpus/index.ts) and #1372/#1373
// (src/lib/obsidianSync.ts): the caller-chosen directory behind
// - POST /api/settings/local-corpus (`rootPath`, indexed and served by the MCP search tools)
// - POST /api/settings/obsidian/webdav (`vaultPath`, root of a read/write WebDAV service)
// is a host-filesystem root. Choosing it is an operator action:
// - a machine credential (a manage-scoped API key) gets 403, on both routes;
// - an operator (dashboard session) still sets an ordinary folder such as ~/Documents/vault;
// - the filesystem root, the home directory itself and system directories (/etc, ...) are
// refused with a fixed 400 message that never echoes the requested path.
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { makeManagementSessionRequest } from "../helpers/managementSession.ts";
const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "omniroute-path-roots-data-"));
const FAKE_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "omniroute-path-roots-home-"));
const ORIGINAL_ENV = {
DATA_DIR: process.env.DATA_DIR,
HOME: process.env.HOME,
API_KEY_SECRET: process.env.API_KEY_SECRET,
JWT_SECRET: process.env.JWT_SECRET,
INITIAL_PASSWORD: process.env.INITIAL_PASSWORD,
OMNIROUTE_DISABLE_REDIS_AUTH_CACHE: process.env.OMNIROUTE_DISABLE_REDIS_AUTH_CACHE,
};
process.env.DATA_DIR = TEST_DATA_DIR;
// os.homedir() follows $HOME on POSIX: the "home directory itself" case and the ordinary
// ~/Documents/vault folder both live in a throwaway directory, never in the real home.
process.env.HOME = FAKE_HOME;
process.env.API_KEY_SECRET = "path-roots-api-key-secret";
process.env.JWT_SECRET = "path-roots-jwt-secret";
process.env.OMNIROUTE_DISABLE_REDIS_AUTH_CACHE = "1";
delete process.env.INITIAL_PASSWORD;
const core = await import("../../src/lib/db/core.ts");
const apiKeysDb = await import("../../src/lib/db/apiKeys.ts");
const settingsDb = await import("../../src/lib/db/settings.ts");
const localCorpusDb = await import("../../src/lib/db/localCorpus.ts");
const obsidianDb = await import("../../src/lib/db/obsidian.ts");
const managementPassword = await import("../../src/lib/auth/managementPassword.ts");
const localCorpusRoute = await import("../../src/app/api/settings/local-corpus/route.ts");
const webdavRoute = await import("../../src/app/api/settings/obsidian/webdav/route.ts");
const LOCAL_CORPUS_URL = "http://localhost:20128/api/settings/local-corpus";
const WEBDAV_URL = "http://localhost:20128/api/settings/obsidian/webdav";
const DENIED_ROOT_MESSAGE =
"This directory cannot be used as a root: choose a dedicated folder, not the filesystem root, the home directory itself or a system directory";
const ORDINARY_VAULT = path.join(FAKE_HOME, "Documents", "vault");
fs.mkdirSync(ORDINARY_VAULT, { recursive: true });
await settingsDb.updateSettings({
requireLogin: true,
setupComplete: true,
password: await managementPassword.hashManagementPassword("path-roots-operator-secret"),
});
const manageKey = await apiKeysDb.createApiKey("manage-automation", "machine-paths", ["manage"]);
test.after(() => {
apiKeysDb.resetApiKeyState();
core.resetDbInstance();
fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
fs.rmSync(FAKE_HOME, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
for (const [key, value] of Object.entries(ORIGINAL_ENV)) {
if (value === undefined) delete process.env[key];
else process.env[key] = value;
}
});
test.beforeEach(() => {
localCorpusDb.clearLocalCorpusRoot();
obsidianDb.clearObsidianVaultPath();
obsidianDb.clearWebdavEnabled();
});
function keyRequest(url: string, body: Record<string, unknown>): Request {
return new Request(url, {
method: "POST",
headers: { "content-type": "application/json", authorization: `Bearer ${manageKey.key}` },
body: JSON.stringify(body),
});
}
async function sessionRequest(url: string, body: Record<string, unknown>): Promise<Request> {
return makeManagementSessionRequest(url, { method: "POST", body });
}
type RouteHandler = (request: never) => Promise<Response>;
function post(handler: RouteHandler, request: Request): Promise<Response> {
return (handler as (request: Request) => Promise<Response>)(request);
}
/**
* Error text of either body shape: `{ error: "..." }` (local corpus, which renders the thrown
* Error as "Error: <message>") or `{ error: { message } }` (WebDAV, buildErrorBody).
*/
async function errorText(response: Response): Promise<string> {
const body = (await response.json()) as { error?: unknown };
if (typeof body.error === "string") return body.error.replace(/^Error: /, "");
const nested = body.error as { message?: unknown } | undefined;
return typeof nested?.message === "string" ? nested.message : JSON.stringify(body);
}
// ─── (a) a manage-scoped API key cannot choose the root ────────────────────────────────
test("a manage-scoped API key cannot set the local corpus root (403)", async () => {
const response = await post(
localCorpusRoute.POST,
keyRequest(LOCAL_CORPUS_URL, { rootPath: ORDINARY_VAULT })
);
assert.equal(response.status, 403, await response.clone().text());
assert.equal(localCorpusDb.getLocalCorpusRoot(), null, "root must not be stored");
});
test("a manage-scoped API key cannot set the WebDAV vault path (403)", async () => {
const response = await post(
webdavRoute.POST,
keyRequest(WEBDAV_URL, { vaultPath: ORDINARY_VAULT })
);
assert.equal(response.status, 403, await response.clone().text());
assert.equal(obsidianDb.getWebdavEnabled(), false, "WebDAV must stay disabled");
assert.equal(obsidianDb.getObsidianVaultPath(), null, "vault path must not be stored");
});
test("with login disabled, a manage-scoped API key still cannot set the WebDAV vault path (403)", async () => {
// /api/settings/obsidian is ALWAYS_PROTECTED: an open instance does not turn a machine
// credential into the operator for this credential-issuing surface.
await settingsDb.updateSettings({ requireLogin: false });
try {
const response = await post(
webdavRoute.POST,
keyRequest(WEBDAV_URL, { vaultPath: ORDINARY_VAULT })
);
assert.equal(response.status, 403, await response.clone().text());
assert.equal(obsidianDb.getWebdavEnabled(), false);
} finally {
await settingsDb.updateSettings({ requireLogin: true });
}
});
// ─── (b) the dashboard session keeps working with an ordinary folder ───────────────────
test("a dashboard session sets an ordinary folder (~/Documents/vault) as the local corpus root", async () => {
const response = await post(
localCorpusRoute.POST,
await sessionRequest(LOCAL_CORPUS_URL, { rootPath: ORDINARY_VAULT })
);
assert.equal(response.status, 200, await response.clone().text());
const body = (await response.json()) as { rootPath?: string };
assert.equal(body.rootPath, fs.realpathSync(ORDINARY_VAULT));
assert.equal(localCorpusDb.getLocalCorpusRoot(), fs.realpathSync(ORDINARY_VAULT));
});
test("a dashboard session sets an ordinary folder (~/Documents/vault) as the WebDAV vault", async () => {
const response = await post(
webdavRoute.POST,
await sessionRequest(WEBDAV_URL, { vaultPath: ORDINARY_VAULT })
);
assert.equal(response.status, 200, await response.clone().text());
const body = (await response.json()) as Record<string, unknown>;
assert.equal(body.vaultPath, path.resolve(ORDINARY_VAULT));
assert.ok(typeof body.password === "string" && body.password.length > 0);
assert.equal(obsidianDb.getWebdavEnabled(), true);
});
// ─── (c) dangerous roots are refused with a fixed message ──────────────────────────────
const DENIED_ROOTS: Array<{ label: string; value: () => string }> = [
{ label: "the filesystem root", value: () => path.parse(process.cwd()).root },
{ label: "the home directory itself", value: () => FAKE_HOME },
{ label: "/etc", value: () => "/etc" },
];
for (const denied of DENIED_ROOTS) {
test(`local corpus refuses ${denied.label} with a fixed 400`, async () => {
const response = await post(
localCorpusRoute.POST,
await sessionRequest(LOCAL_CORPUS_URL, { rootPath: denied.value() })
);
assert.equal(response.status, 400);
assert.equal(await errorText(response), DENIED_ROOT_MESSAGE);
assert.equal(localCorpusDb.getLocalCorpusRoot(), null, "root must not be stored");
});
test(`WebDAV vault refuses ${denied.label} with a fixed 400`, async () => {
const response = await post(
webdavRoute.POST,
await sessionRequest(WEBDAV_URL, { vaultPath: denied.value() })
);
assert.equal(response.status, 400);
assert.equal(await errorText(response), DENIED_ROOT_MESSAGE);
assert.equal(obsidianDb.getWebdavEnabled(), false, "WebDAV must stay disabled");
assert.equal(obsidianDb.getObsidianVaultPath(), null, "vault path must not be stored");
});
}
test("a symlink inside the home directory that resolves to /etc is refused on both routes", async () => {
const link = path.join(FAKE_HOME, "etc-link");
try {
fs.symlinkSync("/etc", link, "dir");
} catch {
return; // platform without symlink permission — nothing to assert
}
try {
const corpus = await post(
localCorpusRoute.POST,
await sessionRequest(LOCAL_CORPUS_URL, { rootPath: link })
);
assert.equal(corpus.status, 400);
assert.equal(await errorText(corpus), DENIED_ROOT_MESSAGE);
const vault = await post(
webdavRoute.POST,
await sessionRequest(WEBDAV_URL, { vaultPath: link })
);
assert.equal(vault.status, 400);
assert.equal(await errorText(vault), DENIED_ROOT_MESSAGE);
} finally {
fs.rmSync(link, { force: true });
}
});
// ─── helper: which directories are denied ──────────────────────────────────────────────
test("isDeniedRootDirectory: system directories and their children, root and home itself", async () => {
const { isDeniedRootDirectory } = await import("../../src/lib/deniedRootDirectories.ts");
for (const denied of ["/", FAKE_HOME, `${FAKE_HOME}/`, "/etc", "/etc/ssh", "/usr/local/bin"]) {
assert.equal(isDeniedRootDirectory(denied), true, denied);
}
for (const allowed of [ORDINARY_VAULT, path.join(FAKE_HOME, "Documents"), TEST_DATA_DIR]) {
assert.equal(isDeniedRootDirectory(allowed), false, allowed);
}
});

View File

@@ -1,7 +1,22 @@
import assert from "node:assert/strict";
import { existsSync, readdirSync } from "node:fs";
import { readFile } from "node:fs/promises";
import { dirname, extname, join, relative } from "node:path";
import { execFileSync } from "node:child_process";
import {
closeSync,
existsSync,
ftruncateSync,
lstatSync,
mkdirSync,
mkdtempSync,
openSync,
readdirSync,
realpathSync,
rmSync,
statSync,
writeFileSync,
} from "node:fs";
import { open } from "node:fs/promises";
import { tmpdir } from "node:os";
import { dirname, extname, join, relative, sep } from "node:path";
import test from "node:test";
import { fileURLToPath } from "node:url";
@@ -141,18 +156,23 @@ const TEXT_EXTENSIONS = new Set([
".yml",
]);
function collectTextFiles(absolutePath) {
// The largest audited tracked file is .i18n-state.json at ~4.8 MB (2026-11-20). 64 MiB is
// far above any real tracked text file and far below V8's maximum string length (~512 MiB),
// so a file under the bound always decodes into one string.
const MAX_AUDITED_FILE_BYTES = 64 * 1024 * 1024;
function collectTextFiles(repoRoot, absolutePath) {
const files = [];
for (const entry of readdirSync(absolutePath, { withFileTypes: true })) {
const entryPath = join(absolutePath, entry.name);
const relativePath = relative(root, entryPath);
const relativePath = relative(repoRoot, entryPath);
if (
entry.isDirectory() &&
!SKIPPED_DIRECTORY_NAMES.has(entry.name) &&
relativePath !== "public/providers"
) {
files.push(...collectTextFiles(entryPath));
files.push(...collectTextFiles(repoRoot, entryPath));
} else if (entry.isFile() && TEXT_EXTENSIONS.has(extname(entry.name))) {
files.push(entryPath);
}
@@ -161,21 +181,163 @@ function collectTextFiles(absolutePath) {
return files;
}
const rootTextFiles = readdirSync(root, { withFileTypes: true })
.filter((entry) => entry.isFile())
.map((entry) => join(root, entry.name));
const referenceRoots = readdirSync(root, { withFileTypes: true })
.filter(
(entry) =>
entry.isDirectory() &&
!entry.name.startsWith("_") &&
!SKIPPED_ROOT_DIRECTORY_NAMES.has(entry.name)
)
.map((entry) => entry.name);
const AUDITED_REFERENCE_FILES = [
...rootTextFiles,
...referenceRoots.flatMap((directory) => collectTextFiles(join(root, directory))),
];
// Fallback for a source tree without git metadata: walk the working tree with the scope rules.
function walkAuditedReferenceFiles(repoRoot) {
const entries = readdirSync(repoRoot, { withFileTypes: true });
const rootFiles = entries.filter((entry) => entry.isFile()).map((e) => join(repoRoot, e.name));
const referenceRoots = entries
.filter(
(entry) =>
entry.isDirectory() &&
!entry.name.startsWith("_") &&
!SKIPPED_ROOT_DIRECTORY_NAMES.has(entry.name)
)
.map((entry) => entry.name);
return [
...rootFiles,
...referenceRoots.flatMap((directory) => collectTextFiles(repoRoot, join(repoRoot, directory))),
];
}
// The same scope as the walk, applied to a git path (always "/"-separated).
function isAuditedTrackedPath(relativePath) {
const segments = relativePath.split("/");
// Root-level files are audited whatever their extension, as the walk does.
if (segments.length === 1) return true;
const [rootDirectory] = segments;
if (rootDirectory.startsWith("_") || SKIPPED_ROOT_DIRECTORY_NAMES.has(rootDirectory)) {
return false;
}
if (relativePath.startsWith("public/providers/")) return false;
if (segments.slice(1, -1).some((segment) => SKIPPED_DIRECTORY_NAMES.has(segment))) return false;
return TEXT_EXTENSIONS.has(extname(relativePath));
}
// Location variables set by a git hook would point git at another repository.
function gitEnvironment() {
const env = { ...process.env };
for (const name of [
"GIT_DIR",
"GIT_WORK_TREE",
"GIT_INDEX_FILE",
"GIT_OBJECT_DIRECTORY",
"GIT_COMMON_DIR",
]) {
delete env[name];
}
return env;
}
function runGit(repoRoot, args) {
return execFileSync("git", args, {
cwd: repoRoot,
env: gitEnvironment(),
maxBuffer: 256 * 1024 * 1024,
stdio: ["ignore", "pipe", "pipe"],
});
}
// Tracked regular files of repoRoot, or null when repoRoot is not the top of a git work tree
// (no .git, git missing, or a directory nested inside some other repository).
function listTrackedFiles(repoRoot) {
try {
const topLevel = runGit(repoRoot, ["rev-parse", "--show-toplevel"]).toString("utf8").trim();
if (realpathSync(topLevel) !== realpathSync(repoRoot)) return null;
return runGit(repoRoot, ["ls-files", "-z"]).toString("utf8").split("\0").filter(Boolean);
} catch {
return null;
}
}
function isRegularFile(absolutePath) {
try {
return lstatSync(absolutePath).isFile();
} catch {
return false;
}
}
// The files the retired-reference audit reads: tracked files only, so temporary files,
// logs and fixtures that the test run or the CI job writes into the tree are never read.
function collectAuditedReferenceFiles(repoRoot = root) {
const tracked = listTrackedFiles(repoRoot);
if (tracked === null) {
return { source: "walk", files: walkAuditedReferenceFiles(repoRoot) };
}
const files = tracked
.filter(isAuditedTrackedPath)
.map((relativePath) => join(repoRoot, ...relativePath.split("/")))
// Symlinks, gitlinks and tracked files deleted from the work tree are not read (the walk
// did not read them either).
.filter(isRegularFile);
return { source: "git", files };
}
// Reads at most min(size at open, maxBytes) bytes, so the decoded string can never reach
// V8's maximum string length, even if the file grows while it is read.
async function readBoundedUtf8(filePath, maxBytes) {
const handle = await open(filePath, "r");
try {
const { size } = await handle.stat();
if (size > maxBytes) return { size, content: null };
const buffer = Buffer.allocUnsafe(size);
let total = 0;
while (total < size) {
const { bytesRead } = await handle.read(buffer, total, size - total, total);
if (bytesRead === 0) break;
total += bytesRead;
}
return { size, content: buffer.toString("utf8", 0, total) };
} finally {
await handle.close();
}
}
// Every problem is collected per file, so one oversized or unreadable file is reported by
// name instead of aborting the audit with an unrelated error.
async function auditReferenceFiles(files, repoRoot = root, maxBytes = MAX_AUDITED_FILE_BYTES) {
const findings = { references: [], oversized: [], unreadable: [] };
const readConcurrency = 64;
for (let offset = 0; offset < files.length; offset += readConcurrency) {
const batch = files.slice(offset, offset + readConcurrency);
await Promise.all(
batch.map(async (filePath) => {
const displayPath = relative(repoRoot, filePath).split(sep).join("/");
let result;
try {
result = await readBoundedUtf8(filePath, maxBytes);
} catch (error) {
findings.unreadable.push(`${displayPath} (${error?.code ?? error?.message ?? error})`);
return;
}
if (result.content === null) {
findings.oversized.push(`${displayPath} (${result.size} bytes > ${maxBytes} bytes)`);
return;
}
const match = result.content.match(retiredFilenamePattern);
if (match) findings.references.push(`${displayPath} still references ${match[2]}`);
})
);
}
for (const list of Object.values(findings)) list.sort();
return findings;
}
function assertCleanAudit(findings) {
assert.deepEqual(findings.references, [], findings.references.join("\n"));
assert.deepEqual(
findings.oversized,
[],
`audited files above the ${MAX_AUDITED_FILE_BYTES}-byte bound:\n${findings.oversized.join("\n")}`
);
assert.deepEqual(
findings.unreadable,
[],
`audited files that could not be read:\n${findings.unreadable.join("\n")}`
);
}
test("provider bundle retires exactly the 78 unresolved assets and keeps the generic icon", () => {
assert.equal(retiredAssetNames.length, 78);
@@ -210,16 +372,125 @@ test("provider bundle retires exactly the 78 unresolved assets and keeps the gen
assert.ok(distributedAssets.includes("cli-generic.svg"));
});
test("tracked source and documentation surfaces have no retired asset reference", async () => {
const readConcurrency = 64;
test("tracked source and documentation surfaces have no retired asset reference", async (t) => {
const { source, files } = collectAuditedReferenceFiles();
t.diagnostic(
`audited ${files.length} files (${source === "git" ? "git ls-files" : "tree walk"})`
);
assert.ok(files.length > 0, "the audit must read at least one file");
for (let offset = 0; offset < AUDITED_REFERENCE_FILES.length; offset += readConcurrency) {
const batch = AUDITED_REFERENCE_FILES.slice(offset, offset + readConcurrency);
const contents = await Promise.all(batch.map((filePath) => readFile(filePath, "utf8")));
assertCleanAudit(await auditReferenceFiles(files));
});
for (const [index, content] of contents.entries()) {
const match = content.match(retiredFilenamePattern);
assert.equal(match, null, `${relative(root, batch[index])} still references ${match?.[2]}`);
const SPARSE_FIXTURE_BYTES = 600 * 1024 * 1024;
// A file larger than V8's maximum string length that costs no disk: open, ftruncate, close.
function createSparseFile(filePath, bytes) {
const fd = openSync(filePath, "wx");
try {
ftruncateSync(fd, bytes);
} finally {
closeSync(fd);
}
const stats = statSync(filePath);
if (stats.size !== bytes) throw new Error(`size is ${stats.size} bytes, expected ${bytes}`);
if (typeof stats.blocks === "number" && stats.blocks * 512 > 1024 * 1024) {
throw new Error(`the file system allocated ${stats.blocks * 512} bytes (not sparse)`);
}
}
function gitIsAvailable() {
try {
execFileSync("git", ["--version"], { env: gitEnvironment(), stdio: "ignore" });
return true;
} catch {
return false;
}
}
// Regression: the queue's base check runs the whole unit suite in the "Fast Quality Gates"
// job, where an untracked file of more than 512 MiB sat in a walked directory and the old
// walk-and-readFile audit died with "RangeError: Invalid string length" (run 44795004759).
// The fixture repository lives in the OS temp dir so that the 600 MB file can never be read
// by another test that walks this checkout while the suite runs.
test("the audit reads tracked files only and reports an oversized file by name", async (t) => {
if (!gitIsAvailable()) {
t.skip("git is not available: the tracked-file listing cannot be exercised");
return;
}
const repoRoot = mkdtempSync(join(tmpdir(), "provider-assets-audit-"));
const noGitRoot = mkdtempSync(join(tmpdir(), "provider-assets-audit-nogit-"));
try {
runGit(repoRoot, ["init", "--quiet"]);
mkdirSync(join(repoRoot, "tests"));
writeFileSync(join(repoRoot, "README.md"), "# fixture\n");
writeFileSync(join(repoRoot, "tests", "tracked.md"), "tracked fixture\n");
runGit(repoRoot, ["add", "README.md", "tests/tracked.md"]);
const untrackedHugeFile = join(repoRoot, "tests", "run-output.txt");
try {
createSparseFile(untrackedHugeFile, SPARSE_FIXTURE_BYTES);
} catch (error) {
t.skip(`cannot create a ${SPARSE_FIXTURE_BYTES}-byte sparse file in ${tmpdir()}: ${error}`);
return;
}
// The fixture is in scope: the walk reaches it, and the bounded read names it instead of
// throwing "Invalid string length".
const walked = walkAuditedReferenceFiles(repoRoot);
assert.ok(walked.includes(untrackedHugeFile), "the walk must reach the untracked fixture");
const walkedFindings = await auditReferenceFiles(walked, repoRoot);
assert.deepEqual(walkedFindings.oversized, [
`tests/run-output.txt (${SPARSE_FIXTURE_BYTES} bytes > ${MAX_AUDITED_FILE_BYTES} bytes)`,
]);
assert.deepEqual(walkedFindings.references, []);
assert.deepEqual(walkedFindings.unreadable, []);
const { source, files } = collectAuditedReferenceFiles(repoRoot);
const findings = await auditReferenceFiles(files, repoRoot);
assert.equal(source, "git");
assert.equal(files.includes(untrackedHugeFile), false, "untracked files must not be audited");
assert.deepEqual(files.map((file) => relative(repoRoot, file).split(sep).join("/")).sort(), [
"README.md",
"tests/tracked.md",
]);
assertCleanAudit(findings);
// A tracked file over the bound fails the audit with its name and size.
const tightFindings = await auditReferenceFiles(files, repoRoot, 12);
assert.deepEqual(tightFindings.oversized, ["tests/tracked.md (16 bytes > 12 bytes)"]);
// Without git metadata the audit falls back to the walk instead of auditing nothing.
mkdirSync(join(noGitRoot, "docs"));
writeFileSync(join(noGitRoot, "docs", "guide.md"), "see providers/cli-generic.svg\n");
const fallback = collectAuditedReferenceFiles(noGitRoot);
assert.equal(fallback.source, "walk");
assert.deepEqual(fallback.files, [join(noGitRoot, "docs", "guide.md")]);
} finally {
rmSync(repoRoot, { recursive: true, force: true });
rmSync(noGitRoot, { recursive: true, force: true });
}
});
test("the tracked-path scope matches the walk's scope rules", () => {
for (const [relativePath, expected] of [
["package.json", true],
["LICENSE", true],
["docs/guide.md", true],
["open-sse/services/combo.ts", true],
[".github/workflows/ci.yml", true],
["docs/image.png", false],
["public/providers/openai.svg", false],
["public/providers.json", true],
["_tasks/plan.md", false],
[".claude/notes.md", false],
[".git/config.json", false],
["node_modules/pkg/index.js", false],
["packages/ui-kit/dist/index.js", false],
["packages/ui-kit/node_modules/pkg/index.js", false],
["src/coverage/report.ts", false],
["src/_private/notes.md", true],
]) {
assert.equal(isAuditedTrackedPath(relativePath), expected, relativePath);
}
});

View File

@@ -0,0 +1,212 @@
// Same status contract as tests/unit/credits-signal-400-status-gate.test.ts, applied to
// the subscription/plan quota text signals ("usage limit reached", "plan limit",
// "weekly usage limit", ...). A 400 is how upstreams reject the caller's own input, and
// many of them quote that input back in error.message, so on 400 such a phrase counts
// only when the structured error code is a credit/quota code, or the provider is one
// whose documented 400 form is message-only (command-code, bai, openai-compatible-*).
// 429, 403 and every other status keep the plain text match.
import assert from "node:assert/strict";
import test from "node:test";
import { createChatPipelineHarness } from "../integration/_chatPipelineHarness.ts";
const h = await createChatPipelineHarness("subscription-quota-400-status-gate");
const providersDb = await import("../../src/lib/db/providers.ts");
const { checkFallbackError } = await import("../../open-sse/services/accountFallback.ts");
const { classifyProviderError, PROVIDER_ERROR_TYPES } =
await import("../../open-sse/services/errorClassifier.ts");
const { RateLimitReason } = await import("../../open-sse/config/constants.ts");
const { shouldCoolDownSearchConnection } =
await import("../../open-sse/handlers/search/searchProxy.ts");
const originalFetch = globalThis.fetch;
const ECHO_MARKER = "ECHO-MARKER-REQUEST";
// Typed invalid_request_error repeating a caller-chosen subscription-quota phrase.
const TYPED_ECHO_400 = {
error: {
message: "Unknown parameter: 'usage limit reached'.",
type: "invalid_request_error",
},
};
// Untyped 400 outside the param-validation patterns, same phrase family.
const UNTYPED_ECHO_400 = {
error: {
message: "Invalid value 'you have reached your usage limit' for model",
type: "api_error",
},
};
const ECHOED_PHRASES = [
"Unknown parameter: 'usage limit reached'.",
"Invalid value 'plan limit exceeded' for model",
"Unknown parameter: 'this request exceeds your plan'.",
"Unknown parameter: 'you have reached your weekly usage limit'.",
"Unknown parameter: 'session usage limit'.",
"Unknown parameter: 'usage limit reached, try again in 30 minutes'.",
];
test.afterEach(() => {
globalThis.fetch = originalFetch;
});
test.after(() => h.cleanup());
function stubUpstream(echoBody: unknown) {
const calls = { echo: 0, clean: 0 };
globalThis.fetch = (async (_url: unknown, init?: RequestInit) => {
const sent = typeof init?.body === "string" ? init.body : "";
if (sent.includes(ECHO_MARKER)) {
calls.echo++;
return new Response(JSON.stringify(echoBody), {
status: 400,
headers: { "content-type": "application/json" },
});
}
calls.clean++;
return h.buildOpenAIResponse("served");
}) as typeof fetch;
return calls;
}
function chatRequest(content: string) {
return h.buildRequest({
body: {
model: "openai/gpt-4o-mini",
stream: false,
messages: [{ role: "user", content }],
},
});
}
function isOnHold(conn: { rateLimitedUntil?: unknown; testStatus?: unknown } | null): boolean {
const until = conn?.rateLimitedUntil;
const untilMs = typeof until === "string" ? Date.parse(until) : Number(until ?? 0);
return conn?.testStatus === "unavailable" || (Number.isFinite(untilMs) && untilMs > Date.now());
}
for (const [label, echoBody] of [
["typed invalid_request_error", TYPED_ECHO_400],
["untyped 400 outside the param-validation patterns", UNTYPED_ECHO_400],
] as const) {
test(`${label}: a caller-echoed subscription-quota phrase never puts a shared openai connection on hold`, async () => {
await h.resetStorage();
const conns = [];
for (let i = 0; i < 3; i++) {
conns.push(await h.seedConnection("openai", { name: `shared-${i}` }));
}
const calls = stubUpstream(echoBody);
for (let i = 0; i < 3; i++) {
const res = await h.handleChat(chatRequest(`hello ${ECHO_MARKER} ${i}`));
await res.text();
}
assert.ok(calls.echo >= 3, `expected the echo requests to reach upstream, got ${calls.echo}`);
for (const conn of conns) {
const after = await providersDb.getProviderConnectionById(conn.id);
assert.equal(isOnHold(after), false, `connection ${after?.name} put on hold`);
assert.notEqual(after?.lastErrorType, "quota_exhausted", `${after?.name} quota_exhausted`);
}
const clean = await h.handleChat(chatRequest("a clean request"));
const body = await clean.text();
assert.equal(clean.status, 200, `clean request was not served: ${body}`);
assert.ok(calls.clean >= 1);
});
}
test("echoed 400 subscription-quota phrases are not QUOTA_EXHAUSTED for openai", () => {
for (const message of ECHOED_PHRASES) {
const text = JSON.stringify({ error: { message, type: "invalid_request_error" } });
assert.notEqual(
classifyProviderError(400, text, "openai"),
PROVIDER_ERROR_TYPES.QUOTA_EXHAUSTED,
text
);
const result = checkFallbackError(400, text, 0, "gpt-4o-mini", "openai");
assert.notEqual(result.reason, RateLimitReason.QUOTA_EXHAUSTED, text);
}
});
test("search: an echoed 400 subscription-quota phrase does not cool down the connection", () => {
assert.equal(
shouldCoolDownSearchConnection(400, "Invalid query: 'usage limit reached for this plan'"),
false
);
});
test("control: 429 with the same subscription-quota text stays QUOTA_EXHAUSTED", () => {
const text = JSON.stringify({ error: { message: "Usage limit reached for your plan." } });
// OAuth provider and provider-less callers keep the 429 quota semantics.
assert.equal(classifyProviderError(429, text, "claude"), PROVIDER_ERROR_TYPES.QUOTA_EXHAUSTED);
assert.equal(classifyProviderError(429, text), PROVIDER_ERROR_TYPES.QUOTA_EXHAUSTED);
const result = checkFallbackError(429, "Usage Limit Reached", 0, null, "claude");
assert.equal(result.reason, RateLimitReason.QUOTA_EXHAUSTED);
assert.equal(result.cooldownMs, 60 * 60 * 1000);
assert.equal(
checkFallbackError(429, "you have reached your weekly usage limit", 0, null, "ollama-cloud")
.reason,
RateLimitReason.QUOTA_EXHAUSTED
);
assert.equal(shouldCoolDownSearchConnection(429, "usage limit reached"), true);
});
test("control: 403 subscription-quota text stays QUOTA_EXHAUSTED", () => {
const text = JSON.stringify({
error: { message: "You've reached your usage limit for this billing cycle." },
});
assert.equal(
classifyProviderError(403, text, "kimi-coding"),
PROVIDER_ERROR_TYPES.QUOTA_EXHAUSTED
);
});
test("control: a 400 with a structured quota code still counts on openai", () => {
for (const code of ["insufficient_quota", "billing_hard_limit_reached"]) {
const body = JSON.stringify({ error: { message: "Usage limit reached for your plan.", code } });
assert.equal(
classifyProviderError(400, body, "openai"),
PROVIDER_ERROR_TYPES.QUOTA_EXHAUSTED,
code
);
// The structured code held apart from the text (executor-parsed) also counts.
const result = checkFallbackError(
400,
"Usage limit reached for your plan.",
0,
"gpt-4o-mini",
"openai",
null,
null,
{ code }
);
assert.equal(result.shouldFallback, true, code);
assert.equal(result.reason, RateLimitReason.QUOTA_EXHAUSTED, code);
assert.equal(result.cooldownMs, 60 * 60 * 1000, code);
}
assert.equal(
shouldCoolDownSearchConnection(
400,
JSON.stringify({ error: { message: "plan limit exceeded", code: "insufficient_quota" } })
),
true
);
});
test("control: a message-only 400 on an allow-listed provider still counts", () => {
for (const provider of ["command-code", "bai", "openai-compatible-my-gateway"]) {
const text = "Usage limit reached for your plan.";
assert.equal(
classifyProviderError(400, text, provider),
PROVIDER_ERROR_TYPES.QUOTA_EXHAUSTED,
provider
);
const result = checkFallbackError(400, text, 0, "m", provider);
assert.equal(result.reason, RateLimitReason.QUOTA_EXHAUSTED, provider);
}
});
test("the message-only allow-list is the id prefix, not a substring anywhere in the id", () => {
assert.notEqual(
classifyProviderError(400, "Usage limit reached", "my-openai-compatible-x"),
PROVIDER_ERROR_TYPES.QUOTA_EXHAUSTED
);
});

View File

@@ -0,0 +1,44 @@
// CodeQL #1392 (js/unvalidated-dynamic-method-call): applySyntxProviderRules indexed a plain
// object literal with the caller-chosen `aiName` (the text before "/" in the requested model), so
// names such as "constructor", "__proto__", "hasOwnProperty" or "valueOf" resolved to members
// inherited from Object.prototype and were invoked. Only the rules defined in the table may run;
// any other name takes the "no rule" path and leaves the settings untouched.
import { describe, it } from "node:test";
import assert from "node:assert/strict";
const { applySyntxProviderRules } = await import("../../open-sse/services/syntxMedia.ts");
const INHERITED_NAMES = ["constructor", "__proto__", "hasOwnProperty", "valueOf", "toString"];
describe("applySyntxProviderRules: only own rule entries run", () => {
for (const aiName of INHERITED_NAMES) {
it(`"${aiName}" takes the no-rule path without a TypeError`, () => {
const settings = { aspect_ratio: "1:1", resolution: "1K", style: "x" };
assert.doesNotThrow(() =>
applySyntxProviderRules(aiName, settings, { modelType: "m", fileCount: 0 })
);
assert.deepEqual(settings, { aspect_ratio: "1:1", resolution: "1K", style: "x" });
});
}
it("never invokes the inherited Object.prototype.constructor", () => {
const original = Object.prototype.constructor;
let calls = 0;
// Swap the inherited member for a spy; a plain-object lookup of "constructor" reaches it.
Object.prototype.constructor = function spy() {
calls += 1;
} as unknown as ObjectConstructor;
try {
applySyntxProviderRules("constructor", {}, { modelType: "m" });
} finally {
Object.prototype.constructor = original;
}
assert.equal(calls, 0);
});
it("an own rule still applies", () => {
const settings = { model_type: "seedream-4.5", resolution: "1K" };
applySyntxProviderRules("seedream", settings, { modelType: "seedream-4.5" });
assert.equal(settings.resolution, "2K");
});
});

View File

@@ -52,10 +52,19 @@ test("the OIDC callback validates `state` with the constant-time helper", () =>
);
});
test("the internal admission bypass compares its bearer in constant time", () => {
test("the internal admission bypass compares its process token in constant time", () => {
// The bypass is granted only on the per-process token, checked by isOwnListenerSelfHop.
const source = sourceOf("src/shared/middleware/chatAdmissionIdentity.ts");
assert.ok(
source.includes("timingSafeCompare"),
"isInternalAdmissionBypass gates a bypass on a shared secret — compare it in constant time"
assert.match(
source,
/isInternalAdmissionBypass\(request: Request\): boolean \{\s*return isOwnListenerSelfHop\(/,
"isInternalAdmissionBypass gates a bypass on a shared secret — it must go through isOwnListenerSelfHop"
);
const selfHop = sourceOf("open-sse/utils/selfHop.ts");
const check = selfHop.slice(selfHop.indexOf("export function isOwnListenerSelfHop"));
assert.match(
check.slice(0, check.indexOf("\n}\n")),
/timingSafeEqual\(got, expected\)/,
"isOwnListenerSelfHop must compare the token in constant time"
);
});

View File

@@ -20,6 +20,8 @@ const { checkBodySize, getBodySizeLimit } =
await import("../../src/shared/middleware/bodySizeGuard.ts");
const { admitChatRequest, ChatAdmissionController, resolveSelfLoopBearer } =
await import("../../src/shared/middleware/chatBodyAdmission.ts");
const { SELF_HOP_HEADER, ownListenerSelfHopToken } =
await import("../../open-sse/utils/selfHop.ts");
const paths = [
"/api/v1/chat/completions",
@@ -42,6 +44,7 @@ function request(pathname: string, bytes: number, declared?: number, internal =
if (internal) {
headers.set("x-omniroute-admission-bypass", "internal");
headers.set("authorization", `Bearer ${resolveSelfLoopBearer()}`);
headers.set(SELF_HOP_HEADER, ownListenerSelfHopToken());
}
const body = new ReadableStream<Uint8Array>(
{