docs(security): document the S11 kill-switch refusal codes and operator recovery

Open Beginner friendly
#9,237 0 comments 0 reactions 0 assignees View on GitHub

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

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

documentation from-review

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 (from principal_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 enable again once the disk is healthy, or run disable to make the disabled state durable.
  • TOO_MANY_LABELS (from principal_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.
  • Boot recovery: an unreadable, corrupt, untrusted (mode, owner or symlink) or oversized principals-disabled.json fails closed to "disabled for all".
    • The documented recovery is chroxy agent enable --all.

Acceptance Criteria

  • §10.2 names PERSIST_UNCONFIRMED and TOO_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 --all recovery path.
  • The chroxy agent help 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

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from blamechris/chroxy

All issues in blamechris/chroxy

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.