stack/agents/darkwing/work/queue-d/helper.md

# Raw per-seat token files in `scripts/gitea-api.sh` (row 12, #1508)

Darkwing, 2026-09-27, after round 2 (lead decision 38). Lead decision 37 approved this patch. It ships next
to the Piece D candidate but is a separate patch, and Rocko reviews it
because it handles a credential. Filbert reviews D. Sage commits both.
Nothing is committed, staged or pushed.

`helper.patch` (sha256 `48edd46b93c54908e9d59737aab78a33e007ddfafa1e6ad4d34333015bb75430`)
changes `scripts/gitea-api.sh` and adds
`packages/ledger/tests/gitea-helper-raw.test.mjs`. It applies to HEAD
8efc0ff3 by itself. With only this patch applied, `node --test
packages/ledger/tests/` passes 58/58. D does not depend on it, and it does
not depend on D.

## Why

Each seat's Gitea token is at
`~/.mosaic/fleet/agents/<seat>/secrets/gitea-mosaicstack-<seat>.token`.
These files hold the bare token, not the JSON `mosaic.gitea.json` shape
that the helper reads today. Without this change the helper refuses them,
so D's live round can't post as the seat.

## What changed

Both old node snippets, the one that printed the base URL and the one that
wrote the curl config, are now one script, `CRED_JS`, run in two modes:
`base` and `cfg`. Each mode runs every check before it prints anything.

1. `lstat`: a regular file, not a symlink, no group or other bits.
   Unchanged.
2. Read the file. A read error exits 3. It used to be caught by the JSON
   parse's catch, with the same result.
3. `JSON.parse`. If the text parses, the JSON path runs unchanged: `url`
   must be `https://git.mosaicstack.dev` (trailing slashes stripped), and
   `api_token` must be a nonempty string. A non-`SyntaxError`, such as
   `null.mosaicstack`, exits 3.
4. The raw path runs only on a `SyntaxError`. It accepts the file only if
   all of these hold:
   - `stat` size is 40 or 41;
   - the byte length of the text equals the `stat` size;
   - the text matches `^[0-9a-f]{40}\n?$`.

   Then the base URL is the fixed string `https://git.mosaicstack.dev`,
   and the token is the first 40 characters. Anything else exits 3
   before any request.
5. The second read runs, and must succeed, before curl starts. Round 1
   ran it inside `curl -K <(…)`, where bash drops its exit status, so a
   refusal gave curl an empty config and the request still went out.
   Now `CFG="$(node -e "$CRED_JS" cfg)" || exit 3` and `[ -n "$CFG" ] ||
   exit 3` run first, and curl reads `-K <(printf '%s\n' "$CFG")`.
   `printf` is a builtin, so the token is in no argv. Both curl branches,
   with and without a body, use it.
6. `export -n CFG` runs right after the checked assignment, before any
   child starts. A `CFG` inherited from the caller's environment keeps its
   export attribute when assigned, and `SHELLOPTS=allexport` in the
   environment exports every assignment. Either way the config would reach
   curl's environment, and the body file's `mktemp` and `chmod` too.

## Decision 37, condition by condition

1. **The JSON path is unchanged.** The last test runs a good JSON file,
   four refused ones, and content that parses as JSON but would pass the
   raw pattern: 40 decimal digits, with and without a newline. Those take
   the JSON path and refuse.
2. **One line of token characters.** The format is 40 lowercase hex
   characters. I checked by `stat` that the real files are 40 bytes (jarvis)
   or 41 (the others), all mode 600. I then ran the patched `CRED_JS` in
   `base` mode against my own file only. It printed
   `https://git.mosaicstack.dev` and exited 0, so darkwing's file matches
   the pattern. Nothing printed the token, and I read no other seat's file.
   The other seats' files are unconfirmed beyond size and mode. If one
   doesn't match, the helper exits 3 before any request. The test refuses
   16 bad contents before curl runs: empty, 39 characters, 41 characters,
   upper case, CRLF, a trailing CR, a trailing space, a trailing tab, two
   newlines, a leading space, a trailing space at 40, a second line, a
   quote, non-hex, non-ASCII, and 80 characters.
3. **Fixed base URL.** The raw path assigns the literal. The test sets
   `MOSAIC_GITEA_URL`, `GITEA_URL` and `MOSAIC_GITEA_BASE_URL` to another
   host, and curl still gets `https://git.mosaicstack.dev/api/v1/user`.
4. **File checks and the config stream.** Modes 640, 604, 660, 644, 000
   and 200, a symlink, a missing file and a directory all refuse before
   curl runs. 000 and 200 pass the group and other check, and the read
   refuses them. The stub curl records its argv and its `-K` stream. The
   token is in the stream only, never in argv, stdout or stderr. Every
   token in the test is a dummy that the test writes.
5. **Only the acting seat's file.** That is D's job, not the helper's. D
   refuses unless `MOSAIC_GITEA_CREDENTIAL_FILE` resolves to
   `…/agents/<login>/secrets/gitea-mosaicstack-<login>.token` for the
   acting seat, or jarvis when Sage acts, and before posting it checks that
   `GET user` returns that login. See `review.mjs` `credCheck` and
   `checkUser` in the D candidate.
6. This review.

## Round 1 and what changed for round 2

Rocko's round 1 (`agents/rocko/work/gitea-helper-raw-r1-review-2026-09-27.md`)
found one blocker: a second read that refused still let curl run with an
empty config, and a 2xx then exited 0. My round 1 notes called that a 401,
which the server doesn't guarantee. Sage agreed it belongs in this patch.
Step 5 above is the fix.

The new test, "a file that changes between the two reads refuses before
curl runs", uses the git stub, which runs between the two reads, to
change a valid dummy file to invalid text, to `{}`, to mode 644, to a
symlink, and to missing. It runs each change for `GET user` and for a POST
with a dummy body. Every case exits 3 with no curl call and nothing on
stdout. It also changes a valid JSON file to invalid text. As a control,
both calls reach curl with the right config when nothing changes. The
first test now also checks that the token is not in the environment curl
gets.

Rocko's round 2 (`agents/rocko/work/gitea-helper-raw-r2-review-2026-09-27.md`)
closed that blocker and found another: the inherited export attribute in
step 6. Lead decision 38 took the fix, `export -n CFG`, with no round 3;
Sage checks it with Rocko's reproducer. The test "the token reaches no
child environment, even with an inherited CFG or SHELLOPTS=allexport" runs
raw and JSON dummy files, GET and POST, with an exported harmless `CFG`,
with `SHELLOPTS=allexport`, and with both. Each call must exit 0 with the
token in curl's config stream and not in its environment, argv, stdout or
stderr. I found the `SHELLOPTS` route while checking the fix; `export -n`
covers it too, so I added no second line for it.

Not in this patch: the predictable response path
`/tmp/gitea-api-response.$$`. Sage has it on DEFERRED as "Gitea helper
response-file hardening".

## What I'd like you to look at

- **The second read now re-validates.** Before, `gen_curl_cfg` parsed the
  file again without the `lstat` checks. Now both reads run every check.
  So a file swapped for a symlink or a wider mode between the two reads
  refuses. On the JSON path this is a tightening.
- **The token now sits in a shell variable** for the rest of the script.
  `export -n` keeps it out of every child's environment, and nothing
  prints it. Before, it existed only in the pipe.
- **`lstat` then `readFile` is still not atomic.** A swap between those two
  calls inside one read is the pre-existing race Rocko noted. This patch
  doesn't claim to close it.
- **`text.slice(0, 40)`** relies on the pattern having matched. The only
  accepted texts are the token alone or the token plus `\n`.

## Mutations

25 mutants, each run alone against `gitea-helper-raw.test.mjs`: 19 of
`CRED_JS` and 6 of the gate and the export. 15 are killed:

- uppercase allowed, any trailing whitespace allowed, the `^` anchor
  dropped;
- a raw file refused outright (the old behaviour);
- an env override of the raw base URL;
- the token taken with its newline;
- the mode check dropped;
- the JSON path's host check or token check dropped, or its `|| {}`;
- `cfg` output in `base` mode;
- the read's own `try` dropped (killed by the 000 and 200 modes; I added
  those after this mutant first survived);
- both gate checks dropped, and the round 1 code (no gate, curl reading
  `<(node … cfg)`), killed by the between-reads test;
- `export -n CFG` dropped, killed by the inherited-environment test.

Ten survive, and each is equivalent while the other checks stay:

- `\n*$` for `\n?$`: the size check caps the file at 41 bytes;
- the size check dropped: the pattern caps the length;
- the byte-length check dropped: the pattern is ASCII, so a match means
  bytes equal characters; the check differs only if the file changes
  between `lstat` and the read;
- the `SyntaxError` test dropped: the only non-`SyntaxError` is JSON
  `null`, which then fails the raw pattern;
- `text.trim()` for `text.slice(0, 40)`: same result on every accepted
  text;
- the `isSymbolicLink` test dropped: `lstat` of a symlink is never
  `isFile`;
- `!== "base"` for `=== "cfg"`: the script calls only these two modes;
- `|| true` for `|| exit 3` on the `CFG` line: node prints nothing when it
  refuses, so `[ -n "$CFG" ]` refuses;
- `[ -n "$CFG" ]` dropped: `|| exit 3` refuses first. Dropping
  `|| exit 3` outright is the same, since `set -e` exits on the failed
  assignment;
- `export CFG=…` for `CFG=…`: `export -n` on the next line clears it. In
  round 2 this one was killed; the fix makes it equivalent.

I kept the size, byte-length and symlink checks anyway. Decision 37 asks
for size plus pattern, and the other two cost nothing.