docs(security): document the S11 kill-switch refusal codes and operator recovery
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 70/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Active
- Domain
- cli, documentation, security
Research direction
Start with §10.2 (Kill switch) in docs/security/agent-principals.md, then read the code merged in PR #9220 (commit 2373ec835) to confirm the PERSIST_UNCONFIRMED and TOO_MANY_LABELS refusal paths and the boot read of principals-disabled.json. Compare the chroxy agent help text with the doc. Done when §10.2 names both codes with their operator actions, states the 256-label bound, and describes the fail-closed boot read and the chroxy agent enable --all recovery, and the help text agrees.
Written by the indexing model from the issue text.
Description
Context
Identified during review of PR #9220 (S11 of #9112, merged as 2373ec835).
Location: docs/security/agent-principals.md §10.2 (Kill switch)
Description
The kill switch that PR #9220 added returns two refusal codes the operator contract does not name yet. The doc also does not describe how to recover from a bad flag file found at boot.
PERSIST_UNCONFIRMED(fromprincipal_admin_enable/chroxy agent enable): the enable was written, but the write was not confirmed durable (for example, the directory fsync failed).- The daemon stays disabled.
- Because the flag file may already read "enabled", a restart could apply it.
- Operator action: run
enableagain once the disk is healthy, or rundisableto make the disabled state durable.
TOO_MANY_LABELS(fromprincipal_admin_disable --label): the label set would exceed the 256-label bound that the writer and the boot reader share. Nothing is written.- Operator action: use
--all.
- Operator action: use
- Boot recovery: an unreadable, corrupt, untrusted (mode, owner or symlink) or oversized
principals-disabled.jsonfails closed to "disabled for all".- The documented recovery is
chroxy agent enable --all.
- The documented recovery is
Acceptance Criteria
- §10.2 names
PERSIST_UNCONFIRMEDandTOO_MANY_LABELS, each with its operator action. - §10.2 states the 256-label bound.
- §10.2 describes the fail-closed boot read and the
chroxy agent enable --allrecovery path. - The
chroxy agenthelp text and the doc agree. - Docs only, with no behaviour change.
- Dominant language
- JavaScript
- Stars
- 7
- Forks
- 1
- Avg merge
- 2h 19m
- Merged PRs (30d)
- 263
Getting set up
- Ships a Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from blamechris/chroxy
-
priority: low server testing
Difficulty 1/5 Under an hour Newbie friendliness 88/100
blamechris/chroxy#9277 ·
Maintainers usually reply within 1 day
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
blamechris/chroxy#9272 ·
Maintainers usually reply within 1 day
-
complexity: low dashboard enhancement from-review
Difficulty 2/5 1-3 hours Newbie friendliness 60/100
blamechris/chroxy#9271 ·
Maintainers usually reply within 1 day
-
bug server
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
blamechris/chroxy#9248 ·
Maintainers usually reply within 1 day
-
enhancement from-review
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
blamechris/chroxy#9232 ·
Maintainers usually reply within 1 day
All issues in blamechris/chroxy
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
cytoscape/cytoscape.js#3597 ·
Maintainers usually reply within 5 days
-
Difficulty 1/5 Under an hour Newbie friendliness 72/100
sunososobro-hub/cloudball#191 ·
Maintainers usually reply within 1 day
-
[MCP]: page snapshots in .playwright-mcp/ are not git-ignored (.playwright-cli/ is, since #42318)Open
Difficulty 2/5 1-3 hours Newbie friendliness 62/100
microsoft/playwright#44289 ·
Maintainers usually reply within 1 day
-
Wire ISO post: has() accepts text values such as an empty string, true or 0x1A for wire numbersOpenarea:post effort:low enhancement P7 source:agent
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
Maintainers usually reply within 1 day
-
marketing
Difficulty 2/5 Half a day Newbie friendliness 78/100
Maintainers usually reply within 1 day