CLAUDE.md@crates/orbit-auth git:20261026.7154cd6A

Immutable. This exact content never changes and is served at /api/v1/blob/166ae86490f9c937.

# orbit-auth

Orbit's credential code, so one crate carries the security review. Today that is the lease listener's bearer **lease tokens** ([path-leases design §7](../../docs/design/path-leases/2_design.md#7-authority-and-authentication)).

- **Owns:** the token format (`orbl_` + 256 random bits from `getrandom`), generation, SHA-256 hashing and constant-time comparison (`token`); principals, classes, verbs, workspace scope, priority ceilings, `hard` permission and the allow-or-deny decision with typed refusals (`scope`); the listener user's own SQLite store `lease-tokens.db`, its schema, forward-only migrations and audit rows (`store`); and the execution-environment check every listener-user command and the listener run first (`environment`).
- Any Rust code that creates, hashes, checks or stores a lease token lives here. Surfaces wrap this crate (`orbit-cli` exposes `orbit lease token`); none reimplements it.
- Internal dependencies are `orbit-common` and `orbit-types` only: no HTTP framework, runtime handle or Orbit store. The token store is a separate file opened through `orbit_common::storage::sqlite`, never a table in Orbit's main store.
- The store is never created here. Root provisions it in the listener user's `0700` Orbit home; a user without one is refused with how to run as the listener user. Opening refuses a store or home other users can access or own.
- STD-05: a secret appears once, in the mint result. Never put it, or its hash, in an error, log, audit row or `Debug` output; `LeaseTokenSecret` has no `Display` and a redacting `Debug`. The `orbl_` pattern in `orbit_common::security::redaction` is the backstop, not the control.
- Schema changes append to `store::schema::MIGRATIONS`; never edit a shipped entry.