coreci/orca
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 91 Wiki Activity

docs(P11): doc drift round 2 — README, cli.md, CHANGELOG, verify-reqs (REQ-160)

Browse Source 
- README: status banner v0.12+v0.13, latest tag v0.12.10, subcommand
  table expanded (auth/nft/peer-setup/secrets rotate-master), "mTLS by
  default" corrected to "SSH-push canonical", docs table updated
- docs/cli.md: complete rewrite (521->1465 lines), all ~40 subcommands
- CHANGELOG: regenerated from git log (v0.11.29..HEAD)
- help text: job run HCL->markdown, job stop daemon->SSH-push
- docs/security-runbook.md: expanded to match P05 reality (seal/unseal,
  doctor audit/modes/oidc, incident response)
- docs/webauthn.md: added auth register (P06)
- docs/namespace.md: added inherit + set-constraint
- internal/proxmox/bootstrap.go: comments password->key auth
- internal/cli/status.go: deprecation warning
- scripts/verify-docs.sh + make verify-docs: cli.md <-> orca --help
- cmd/verify-reqs/main.go: fix bold-format regex (was bypassing v0.12)
  + case-insensitive status matching
- .ciagent/REQUIREMENTS.md: v0.12 REQs marked complete
- .ciagent/ROADMAP.md: v0.12 bolded COMPLETE

---ci---
project: orca
phase: 11
milestone: v0.13
status: complete
requirements:
  covered: [160]
---/ci---
This commit is contained in:
Jon Chery
2026-08-10 14:18:27 +00:00
parent ed91d68fbf
commit b6dd86fdf3
14 changed files with 1642 additions and 266 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/cli.md
+1069 -126
View File
File diff suppressed because it is too large Load Diff
docs/namespace.md
+62 -13
View File
@@ -8,8 +8,8 @@ directory holds cluster-wide artifacts shared across namespaces.
> **v0.9 layout (canonical)**: This document describes the v0.9
> multi-namespace layout. The v0.8 flat layout (`orca.db`, `ca.crt`,
> `server.crt` at the root) is deprecated and will be removed in
> v0.11. See [v0.8 flat layout](#deprecated-v08-flat-layout) below.
> `server.crt` at the root) is deprecated and removed in v0.12
> (REQ-138).
## Namespace root resolution
@@ -51,12 +51,16 @@ $ORCA_HOME/
├── cluster/ # cluster-wide (NOT a workload namespace)
│ ├── ca.crt, ca.key # step-ca root (R-006, D-101)
│ ├── master.key # AES-256-GCM root (R-011, mode 0600)
│ ├── master.key.sealed # sealed master key (REQ-147, mode 0600)
│ ├── config.md # Markdown frontmatter config (R-014)
│ ├── known_hosts # SSH known_hosts (D-035)
│ ├── orca_ssh_key # orca SSH private key (D-037)
│ ├── orca_ssh_key.pub # orca SSH public key
│ ├── peers/<host>/ # per-peer directory
│ ├── txns/ # cluster transaction log (R-016)
│ ├── acl.json # ACL state (mode 0600)
│ ├── oidc-client-secret # OIDC client secret (mode 0600, C-36)
│ ├── webauthn-credentials.db # WebAuthn public keys (mode 0600)
│ └── state/ # cluster state
├── _defaults/ # implicit root namespace (always exists)
│ ├── ns.md # namespace frontmatter (kind: Namespace)
@@ -80,14 +84,16 @@ $ORCA_HOME/
exists. Every namespace inherits from `_defaults` and cannot opt out
(D-185, D-187).
- **`cluster/`** is NOT a workload namespace — it holds cluster-wide
artifacts (CA, master key, SSH keys, known_hosts, peers, txns).
artifacts (CA, master key, SSH keys, known_hosts, peers, txns, ACL,
OIDC secrets, WebAuthn credentials).
- **Per-namespace DBs**: each namespace has its own
`db/orca.db` (R-002). No namespace column in SQLite.
- **Namespace inheritance**: child namespaces inherit env and
constraints from parents (via `ns.md` frontmatter `parents:` field).
`_defaults` is always appended last in the inheritance chain.
- **`orca ns` subcommands**: `list`, `create`, `delete`, `inspect`,
`validate` — see [docs/cli.md](cli.md#orca-ns).
`validate`, `inherit`, `set-constraint` — see below and
[docs/cli.md](cli.md#orca-ns).
### Path reference (`internal/paths/`)
@@ -134,6 +140,50 @@ orca ns validate prod
orca ns delete staging
```
### `orca ns inherit` — set parent namespace (R-002)
Set the parent namespace for a namespace. Updates `ns.md` frontmatter
(`parents` field) and validates the new chain has no cycles. The
implicit root `_defaults` is always appended last (D-185).
```bash
orca ns inherit <name> --parent <parent-namespace>
```
**Example**:
```bash
# Make staging inherit from prod (chain: staging -> prod -> _defaults)
orca ns inherit staging --parent prod
```
The child cannot inherit from itself transitively — the resolver
validates the chain before writing. If a cycle is detected, the
command exits 1 with an error.
### `orca ns set-constraint` — set a constraint (R-002)
Set a constraint on a namespace. Constraints are `key=value` strings
(e.g., `max-allocs=10`) stored in `ns.md` frontmatter and unioned
across the inheritance chain by the resolver.
```bash
orca ns set-constraint <name> <key>=<value>
```
**Example**:
```bash
# Limit prod to 10 concurrent allocations
orca ns set-constraint prod max-allocs=10
# Set a required node affinity
orca ns set-constraint prod require-label=ssd
```
Constraints are unioned (not overridden) across the inheritance chain:
if `_defaults` sets `max-allocs=50` and `prod` sets `max-allocs=10`,
the effective constraint is the most restrictive one (CEL evaluation
determines precedence per constraint key).
See [docs/cli.md](cli.md#orca-ns) for the full `orca ns` reference.
## `ORCA_DB` override
@@ -148,11 +198,10 @@ orca init # uses /tmp/test.db for the DB, ~/.orca/ for everything else
## Deprecated: v0.8 flat layout
> **Deprecated in v0.9**: The v0.8 flat layout (`orca.db`, `ca.crt`,
> `ca.key`, `server.crt`, `server.key` at the namespace root) is
> superseded by the v0.9 multi-namespace layout (R-002). The v0.8
> layout is supported during the dual-write window via
> `internal/certpaths` (a thin shim) and will be removed in v0.11.
> **Removed in v0.12** (REQ-138): The v0.8 flat layout (`orca.db`,
> `ca.crt`, `ca.key`, `server.crt`, `server.key` at the namespace root)
> is superseded by the v0.9 multi-namespace layout (R-002) and the
> dual-write window is closed.
The v0.8 flat layout stored all state at the namespace root:
@@ -166,12 +215,12 @@ The v0.8 flat layout stored all state at the namespace root:
The v0.9 re-architecture moved these to `cluster/` (CA, SSH keys) and
per-namespace `db/` (SQLite) to support multi-tenancy (R-002). The
`orca doctor --legacy-paths` command (v0.11-P14c) will detect v0.8
residue and recommend migration.
`internal/certpaths` shim that supported the dual-write window is
removed in v0.12.
## See also
- [Install Guide](install.md) — 1-liner install with `install.sh`.
- [Docker Guide](docker.md) — running orca in a container.
- [CLI Reference](cli.md) — `orca ns` subcommands.
- [Jobspec Reference](jobspec.md) — markdown frontmatter schema.
- [CLI Reference](cli.md#orca-ns) — `orca ns` subcommands.
- [Jobspec Reference](jobspec.md) — markdown frontmatter schema.
docs/security-runbook.md
+138 -21
View File
@@ -1,31 +1,148 @@
# Security Runbook (v0.12)
# Security Runbook (v0.13)
## Master Key Seal/Unseal
This runbook documents the operational security procedures for orca's
zero-trust identity model (R-021): human identity is exclusively
external (OIDC), machine identity is exclusively mTLS/SPIFFE, and no
passwords / Orca-issued tokens / CA-key passphrases exist anywhere in
the system. The v0.12 milestone shipped these capabilities; the v0.13
milestone wired them operationally (R-023).
- `orca cluster seal`: encrypts master key with OIDC-derived key;
prints 5 Shamir shards for offline recovery.
- `orca cluster unseal`: operator authenticates via OIDC; master key
unwrapped into memory; zeroed on shutdown.
- `orca cluster unseal --recovery`: if IdP lost, present 3 of 5 shards.
## Master Key Seal/Unseal (REQ-147, P05)
## Master Key Rotation
The cluster master key (`ClusterDir()/master.key`, mode 0600) encrypts
all namespace `.env.secrets` via per-namespace HKDF-SHA256 sub-keys
(AES-256-GCM). The master key can be **sealed** (encrypted at rest) and
**unsealed** (unwrapped into memory for use).
`orca secrets rotate-master [--dry-run]`: generates new master key,
re-encrypts all namespace secrets, re-seals. Atomic + automatic rollback.
### Seal
```bash
orca cluster seal
```
Encrypts the raw master key with a key derived from either:
- the OIDC ID token subject (if `orca auth login` has been run), or
- the cluster CA fingerprint (mTLS-only offline path, D-241).
The sealed blob is written to `ClusterDir()/master.key.sealed` (0600).
**Five Shamir shards (3-of-5 recovery)** are printed to stdout — store
them offline. The raw master key is then deleted from disk so the
cluster is sealed at rest.
### Unseal
```bash
orca cluster unseal
```
Reads the sealed blob and unwraps the master key using the OIDC ID
token subject or the cluster CA fingerprint. The unwrapped key is
written back to `ClusterDir()/master.key` (0600) and zeroed from
memory on process exit.
### Recovery (IdP lost)
```bash
orca cluster unseal --recovery
```
If the IdP is permanently lost, the operator is prompted for 3 of the
5 Shamir shards printed at seal time. With quorum, the master key is
reconstructed and written back to disk. If quorum is unavailable, the
cluster is unrecoverable by design (C-35: no backdoor).
## Master Key Rotation (REQ-129, C-30)
```bash
orca secrets rotate-master [--dry-run]
```
Generates a new master key, re-encrypts every namespace's
`.env.secrets` under the new key, and re-seals the master key to OIDC.
With `--dry-run`, reports affected namespaces without writing.
- **Atomic per-namespace**: each namespace is re-encrypted independently.
- **Automatic rollback**: on any namespace failure, the old sealed key
is restored (C-30).
- **No passphrase** (R-021): the master key is sealed to OIDC, not to a
human-typed passphrase.
## File-Mode Audit (REQ-033, REQ-130, F13)
```bash
orca doctor modes
```
Verifies file modes on security-sensitive files across `ORCA_HOME`:
- private keys / secrets: `0600`
- certs / public keys: `0644`
Exits 0 if all files have correct modes; exits 1 if any violation is
found. Missing files are not counted as violations.
Checks: SSH key, master key (sealed blob), server cert/key,
known_hosts, `acl.json`, OIDC client secret.
## Audit Log Tamper-Evidence (REQ-125, F2)
```bash
orca doctor audit
```
Verifies the audit log hash chain. Opens the orca SQLite DB, recomputes
the hash chain from the first audit entry, and reports the chain head
hash. If any entry's `entry_hash` or `prev_hash` link does not match the
recomputed value, the chain has been tampered with and the command
exits non-zero.
The audit log is append-only (SQLite trigger blocks
UPDATE/DELETE). Each entry's `actor` field carries the OIDC `sub` or
SPIFFE SVID. Run this after any suspected intrusion or as part of a
regular audit cadence.
## Sudoers Audit (REQ-134, F22)
```bash
orca doctor proxmox
```
Audits the `/etc/sudoers.d/orca` file against the expected allowlist:
- `pct` + `qm` with NOEXEC
- `apt-get` / `dpkg` excluded (or NOEXEC'd)
- `pvesh` EXCLUDED (AD-020: pvesh can bypass NOEXEC via the API execute
endpoint)
## nft Audit (REQ-133, F21)
```bash
orca doctor nft
```
Audits the live nftables ingress ruleset against the on-disk
`/etc/nftables.d/orca.nft` hash (recorded at the latest applied txn).
Reports drift if the live ruleset does not match. Also verifies:
- table exists
- DNAT `:443 → 127.0.0.1:8443` and `:80 → 127.0.0.1:8080` present
- rate-limit meter present
- `/etc/nftables.d/orca.nft` parses
## Incident Response
1. Revoke the compromised identity (OIDC user/group or SPIFFE SVID).
2. Rotate the master key (`orca secrets rotate-master`).
3. Review the audit log (`orca doctor audit` verifies the hash chain).
4. If the master key is compromised, all historical secrets are
compromised (no forward secrecy).
1. **Revoke the compromised identity** (OIDC user/group or SPIFFE SVID).
2. **Rotate the master key** (`orca secrets rotate-master`).
3. **Review the audit log** (`orca doctor audit` verifies the hash
chain; `orca audit list` shows entries).
4. **Check file modes** (`orca doctor modes` detects permission drift).
5. If the master key is compromised, **all historical secrets are
compromised** (no forward secrecy — documented residual risk).
6. **Re-seal** the master key after rotation (`orca cluster seal`).
## Sudoers Audit
## OIDC Provider Health (P06)
`orca doctor proxmox` audits the `/etc/sudoers.d/orca` file against the
expected allowlist (pct + qm with NOEXEC; apt-get/dpkg excluded).
```bash
orca doctor oidc
```
## nft Audit
`orca doctor nft` audits the live nftables ruleset against the emitted one.
Checks the bundled Dex OIDC provider health. Verifies the Dex systemd
unit is running and the `/.well-known/openid-configuration` endpoint
responds. Run after `orca auth init-idp` or after a Dex config change.
docs/webauthn.md
+84 -14
View File
@@ -1,27 +1,97 @@
# WebAuthn / Passkeys (v0.12)
# WebAuthn / Passkeys (v0.13)
## Overview
The bundled Dex uses a custom WebAuthn connector for password-free
authentication. Passkeys are public-key credentials — the private key
never leaves the authenticator (TPM/security key/phone Secure Enclave).
The bundled Dex uses a custom WebAuthn connector (`orca-webauthn-connector`,
REQ-148) for password-free authentication. Passkeys are public-key
credentials — the private key never leaves the authenticator (TPM /
security key / phone Secure Enclave). This directly satisfies R-021
(no Orca-issued credentials): the authenticator proves possession of
the private key without ever exposing it.
The WebAuthn connector ships as part of the v0.12 milestone (P05) and
is operationally wired in v0.13 (P04: registration requires auth; P06:
real Dex deployment).
## Registration
`orca auth register` opens the browser to the Dex WebAuthn endpoint.
After the ceremony (biometric/security key), Dex maps the credential
ID to an OIDC `sub`. Credentials stored at
`ClusterDir()/webauthn-credentials.db` (0600, public keys only).
```bash
orca auth register [--no-browser]
```
Opens the browser to the Dex WebAuthn registration page at
`https://<cluster>/orca/webauthn/register`. The operator authenticates
via an existing session or admin bootstrap token, then performs the
WebAuthn ceremony (biometric or security key). After the ceremony,
Dex maps the credential ID to an OIDC `sub`.
- **`--no-browser`**: print the registration URL instead of opening a
browser (useful for headless operators or remote SSH sessions — copy
the URL into a local browser).
Credentials are stored at `ClusterDir()/webauthn-credentials.db`
(mode 0600, public keys only — private keys never leave the
authenticator and are never stored by orca).
**Example**:
```bash
# Interactive (opens browser)
orca auth register
# Headless / remote SSH (print URL)
orca auth register --no-browser
# → https://orca.local/orca/webauthn/register
```
## RP ID
The relying-party ID is the cluster's Traefik-served domain
(`--rp-id` on `orca auth init-idp`). HTTPS secure context is provided
by Traefik (step-ca cert, R-017).
The relying-party ID is the cluster's Traefik-served domain, set via
`--rp-id` on `orca auth init-idp` (C-38). The RP ID **must** match the
cluster's Traefik domain — WebAuthn enforces that the RP ID is a
registrable domain suffix of the current origin.
HTTPS secure context is provided by Traefik (step-ca cert, R-017).
WebAuthn requires a secure context (HTTPS or localhost); the step-ca
cert behind Traefik satisfies this.
## Bootstrap Sequence
1. `orca init` bootstraps the cluster CA (step-ca, mTLS-only).
2. `orca auth init-idp` deploys Dex behind Traefik (step-ca cert).
3. First operator registers a passkey via the mTLS-authenticated session.
4. Subsequent operators use WebAuthn.
2. `orca auth init-idp --rp-id <cluster-domain>` deploys Dex behind
Traefik (step-ca cert) with the WebAuthn connector configured.
3. First operator authenticates via an existing session or admin
bootstrap token, then registers a passkey:
```bash
orca auth register
```
4. Subsequent operators use WebAuthn login (`orca auth login` opens
the browser to the Dex login page; the WebAuthn ceremony is one of
the available upstreams).
## Health Check
```bash
orca doctor oidc
```
Verifies the bundled Dex OIDC provider is running and the
`/.well-known/openid-configuration` endpoint responds. Run after
`orca auth init-idp` or after a Dex config change.
## Security properties
- **No passwords**: WebAuthn is password-free. No password is ever
sent to or stored by orca (R-021).
- **Phishing-resistant**: the WebAuthn protocol cryptographically binds
the ceremony to the RP ID, defeating credential phishing.
- **Private key never leaves the authenticator**: orca stores only
public keys.
- **Secure context required**: HTTPS via step-ca / Traefik (C-38).
## See also
- [docs/oidc.md](oidc.md) — OIDC configuration (Dex quickstart, BYO IdP)
- [docs/security-runbook.md](security-runbook.md) — security runbook
- [docs/cli.md](cli.md#orca-auth) — `orca auth` CLI reference