Headless Admin CLI and Break-glass Access

1. The problem: losing the GUI must not create a backdoor

Assume the tray and desktop window fail after a bad configuration update while the worker service is still running. Operations needs a headless path for diagnosis and a narrowly bounded recovery action. The dangerous shortcut is a flag such as --force-admin that disables every control. This lesson builds a recovery CLI that remains constrained even during an emergency.

2. Owned boundary: what this lesson controls

LOC-005 owns only the local headless control plane: command identity, effect class, command scope, normal authorization, bounded break-glass state, expiry/revocation, confirmation, and audit. Base device identity, native capability/CSP policy, tray behavior, and OS-service lifecycle remain in adjacent lessons and are not redefined here.

3. Classify a command before authorizing it

Every command needs a stable name and an explicit effect class. A practical minimum is DIAGNOSTIC_READ_ONLY, RECOVERY_STATE_CHANGE, and DESTRUCTIVE_OR_HIGH_RISK. Classification happens before authorization so emergency mode cannot hide the true risk of a destructive operation.

4. Read-only and state-changing commands do not share one gate

Health inspection or configuration validation can use a lower-risk normal local path when authentication, authorization, and scope are valid. Rollback, rotation, or other state changes need stronger evidence, explicit confirmation, and complete audit binding. Being exposed through a CLI grants no additional authority.

5. Prefer the normal path whenever it is usable

If the normal admin path is available and valid, use it. Break-glass is not a permanent substitute for ordinary login or authorization. A broken UI does not necessarily prevent valid local authentication for diagnostic commands, so emergency state should not be activated for every operational inconvenience.

6. Break-glass is a bounded record, not a superuser switch

The emergency record identifies the actor, reason, approval reference, permitted scopes, activation time, and expiry. An active record creates an alternate authorization path only. Each requested command still has to be break-glass eligible and inside the approved scope.

7. Keep local authentication separate from local authorization

A central identity-provider outage does not make a local username trustworthy by default. local_authn_state establishes who presented the local credential, while local_authz_state establishes whether that actor holds the required role. STALE, UNKNOWN, and DENIED evidence remain non-success states.

8. Expiry and revocation are runtime checks

Old approval is not enough. At execution time, compare the current time with expires_at and check revocation. An expired or revoked emergency record stops the action with a typed EXPIRED or REVOKED result and requires a fresh authorization record.

9. Emergency scope must be narrower than local administrator authority

A useful break-glass record may permit only a controlled configuration rollback or rotation of one damaged local credential. An unrelated request such as data purge, log deletion, or broad policy modification remains DENIED even while emergency mode is active.

10. Confirmation protects sensitive effects from operator error

Before a state-changing effect, show the exact target, scope, and consequence and record explicit confirmation. Confirmation is not authentication or authorization; it is an additional gate that reduces accidental execution of an otherwise authorized action.

11. Audit must bind pre-effect intent to post-effect outcome

Each admin command needs a stable audit_event_id tying together actor, command, scope, authority path, reason, approval, timestamps, and result. If an action cannot be linked to its audit record, the result remains UNBOUND rather than being presented as a clean success.

12. Post-event review is how break-glass actually ends

When the normal identity service returns, revoke emergency authority and record what ran, why it ran, which evidence supported it, and what follow-up remains. Closing the incident without this review turns emergency access into an untracked exception.

13. Fail closed by preserving typed weak states

DENIED, DEFER, DEGRADED, EXPIRED, REVOKED, and UNBOUND are operational states, not generic errors. Stale authentication, missing approval, scope mismatch, or a missing audit binding must not be collapsed into a Boolean success value.

14. Lab: Headless Admin CLI & Break-glass Control Record v1

Eight synthetic fixtures ask you to derive authority path, scope state, time state, audit state, break-glass state, action state, and the bounded decision. Expected labels are not present in the learner package. No real credential, privileged OS change, external target, or network access is required.

15. Transfer and chapter exit: close emergency access instead of normalizing it

For transfer, assume the normal identity service returns after recovery. Subsequent commands go back through the normal path, emergency authority is revoked, and post-event review is recorded. C01 exits only when recovery works without the GUI while no permanent “always-admin” path remains.