Grey.ooo/agent-standards
Watch
2
0
Fork
You've already forked agent-standards
 0
Code Issues 2 Pull requests Projects Releases Packages Wiki Activity Actions

Narrow the altcha no-bypass rule to the unit and functional suites #26

Merged
geusebio merged 1 commit from docs/altcha-browser-automation-exception into main 2026-08-15 19:56:39 +00:00
Conversation 0 Commits 1 Files changed 1 +39 -5
geusebio commented 2026-08-15 19:54:21 +00:00
Owner
Copy link

docs/Topics/Auth-Hardening.md § 6 told the reader flatly not to add a kill switch for
the proof-of-work check, and the adoption checklist asked for "no bypass flag".
someones.computer now ships exactly such a flag, deliberately and with the repo owner's
decision behind it: ALTCHA_ENABLED, defaulting to 1 in .env and set to 0 only in
compose.ci.yaml for the Playwright stack
(Grey.ooo/Someones.Computer#662,
commit 3ff859f). A standard the reference implementation openly violates stops being read
as a rule, so this narrows the rule to what it was actually protecting.

What changed

Was Now
"Do not add a kill switch to skip it in tests." "No kill switch the unit or functional suite can reach" — same argument, same remedy (turn the work factor down and solve honestly)
— A new paragraph naming the one exception: a browser-automation stack, with the three reasons it is different, and a table of four guardrails it has to carry
Checklist: "Proof of work on anonymous forms, single-use, with no bypass flag" Split in two — one box for the suites solving honestly, one for the exception being default-on, opted out in a single stack's config, and read in one place
"As built" pointers Adds config/packages/altcha.yaml, .env and compose.ci.yaml, where the argument lives

Why the blanket ban was wrong rather than merely inconvenient

  • The check has nothing to catch there. Proof of work stops scripts that POST without
    executing JavaScript; a browser-automation suite executes it.
  • It loses a race rather than costing time. The driver fills a form and clicks submit in
    well under a second while the widget dynamic-imports ~110KB, fetches a challenge and solves
    it — so the doc's own remedy, turning maxNumber down, does not fix it and only makes the
    flake rarer and harder to read.
  • when@test cannot reach it. An E2E stack runs the built image at APP_ENV=prod on
    purpose, so an env var read at runtime is the only mechanism that gets to a compiled prod
    container.

What the rule protects still holds and is stated as such: the PHPUnit suite goes on solving
challenges honestly at a work factor of 100, so the control stays exercised end to end. The
new text also says plainly that this does not generalise past proof of work — it is the one
control whose value against a real browser is zero, and anything else asking for the same
treatment is asking to stop testing something.

Verification

Prose only — docs/Topics/Auth-Hardening.md, 39 insertions, 5 deletions, no other file. This
repo ships no CI and no markdownlint config; line lengths were checked by hand against the
file's existing wrap (no new non-table line over 100 columns, matching the rest of the doc).
Every claim about the implementation was read out of 3ff859f rather than recalled —
AltchaChallenges::verify(), config/packages/altcha.yaml, config/services.yaml, .env
and compose.ci.yaml.

Not in scope, and following separately: the submodule pointer bump in
Grey.ooo/Someones.Computer, which is a gitlink and therefore code, not docs.

`docs/Topics/Auth-Hardening.md` § 6 told the reader flatly **not** to add a kill switch for the proof-of-work check, and the adoption checklist asked for "no bypass flag". someones.computer now ships exactly such a flag, deliberately and with the repo owner's decision behind it: `ALTCHA_ENABLED`, defaulting to `1` in `.env` and set to `0` only in `compose.ci.yaml` for the Playwright stack ([Grey.ooo/Someones.Computer#662](https://git.grey.ooo/Grey.ooo/Someones.Computer/pulls/662), commit `3ff859f`). A standard the reference implementation openly violates stops being read as a rule, so this narrows the rule to what it was actually protecting. ## What changed | Was | Now | |---|---| | "Do not add a kill switch to skip it in tests." | "No kill switch the unit or functional suite can reach" — same argument, same remedy (turn the work factor down and solve honestly) | | — | A new paragraph naming the one exception: a browser-automation stack, with the three reasons it is different, and a table of four guardrails it has to carry | | Checklist: "Proof of work on anonymous forms, single-use, with no bypass flag" | Split in two — one box for the suites solving honestly, one for the exception being default-on, opted out in a single stack's config, and read in one place | | "As built" pointers | Adds `config/packages/altcha.yaml`, `.env` and `compose.ci.yaml`, where the argument lives | ## Why the blanket ban was wrong rather than merely inconvenient - **The check has nothing to catch there.** Proof of work stops scripts that POST without executing JavaScript; a browser-automation suite executes it. - **It loses a race rather than costing time.** The driver fills a form and clicks submit in well under a second while the widget dynamic-imports ~110KB, fetches a challenge and solves it — so the doc's own remedy, turning `maxNumber` down, does not fix it and only makes the flake rarer and harder to read. - **`when@test` cannot reach it.** An E2E stack runs the built image at `APP_ENV=prod` on purpose, so an env var read at runtime is the only mechanism that gets to a compiled prod container. What the rule protects still holds and is stated as such: the PHPUnit suite goes on solving challenges honestly at a work factor of 100, so the control stays exercised end to end. The new text also says plainly that this does not generalise past proof of work — it is the one control whose value against a real browser is zero, and anything else asking for the same treatment is asking to stop testing something. ## Verification Prose only — `docs/Topics/Auth-Hardening.md`, 39 insertions, 5 deletions, no other file. This repo ships no CI and no markdownlint config; line lengths were checked by hand against the file's existing wrap (no new non-table line over 100 columns, matching the rest of the doc). Every claim about the implementation was read out of `3ff859f` rather than recalled — `AltchaChallenges::verify()`, `config/packages/altcha.yaml`, `config/services.yaml`, `.env` and `compose.ci.yaml`. Not in scope, and following separately: the submodule pointer bump in `Grey.ooo/Someones.Computer`, which is a gitlink and therefore code, not docs.
Auth-Hardening.md told the reader flatly not to add a kill switch for the
proof-of-work check, and the adoption checklist asked for "no bypass flag".
someones.computer now ships exactly such a flag, deliberately: ALTCHA_ENABLED,
defaulting to 1 in .env and set to 0 only in compose.ci.yaml for the Playwright
stack (Grey.ooo/Someones.Computer#662, 3ff859f). A standard the reference
implementation openly violates stops being read as a rule.

The blanket ban was wrong rather than merely inconvenient, for three reasons the
doc now states:

  * Proof of work stops scripts that POST without executing JavaScript. A
    browser-automation suite executes it, so there was never anything for the
    check to catch there.
  * It loses a race rather than costing time. The driver fills a form and clicks
    submit in well under a second while the widget dynamic-imports ~110KB,
    fetches a challenge and solves it — so the doc's own remedy, turning the
    work factor down, does not fix it and only makes the flake rarer.
  * `when@test` cannot reach it. An E2E stack runs the built image at
    APP_ENV=prod on purpose, so an env var read at runtime is the only mechanism
    that gets to a compiled prod container.

What the rule was protecting still holds and stays: the unit and functional
suites solve challenges honestly at a low work factor, so the control is
exercised end to end somewhere. The exception carries four guardrails in a table
— default on in the committed .env, read in exactly one place, unset in the test
env, and the rate limiters left on in the same stack — plus a line saying it does
not generalise to any other control.

Also adds config/packages/altcha.yaml, .env and compose.ci.yaml to the "As built"
pointers, since that is where the argument lives, and splits the checklist item
in two so the exception has its own box to tick.
geusebio added spent time 2026-08-15 19:54:37 +00:00
25 minutes
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Total time spent: 25 minutes
geusebio
25 minutes
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
Grey.ooo/agent-standards!26
No description provided.