leora
df1ed31bdb
Add requirements.txt (cryptography>=43.0.0,<45) and docs/PROD_RUNBOOK.md requiring SIGIL_SEAL_PASS and SIGIL_ANCHOR on separate storage. Document info findings R9/R12/R13 in DESIGN; leave R10 domain separation as a versioned follow-up (not backward-safe).
34 lines
2.1 KiB
Markdown
34 lines
2.1 KiB
Markdown
# Sigil production runbook
|
|
|
|
Short checklist before Sigil guards anything real. Library-only today — do **not**
|
|
enable platform glue until an integration review covers session minting.
|
|
|
|
## Required environment
|
|
|
|
| Variable | Purpose | Notes |
|
|
|----------|---------|--------|
|
|
| `SIGIL_DB` | Path to the store file | Prefer a dedicated volume; backups are sensitive (roster + audit). |
|
|
| `SIGIL_SEAL_PASS` | AES-256-GCM seal passphrase | **Required in prod.** ≥12 chars. Without it the DB file is cleartext on disk. Seal-on still uses a plaintext `0600` working copy while the process is open — not SQLCipher. |
|
|
| `SIGIL_ANCHOR` | Off-box signed tip path | **Required in prod.** Must be on storage **separate** from `SIGIL_DB` (different volume/host). Every checkpoint publishes here; `verify_external_anchors` / `verify-chain` must alert on failure. |
|
|
|
|
Optional: agent private keys stay **off** the platform host whenever possible; checkpoint signer key preferably offline.
|
|
|
|
## Ops loop
|
|
|
|
1. Open with seal + anchor configured (CLI respects the env vars above).
|
|
2. Periodically run chain verify **and** external-anchor verify; page on failure.
|
|
3. After permanent revoke (compromise): bootstrap + `enrol_rekey`, then `reinstate`. Reinstate alone does not restore a wiped key.
|
|
4. Single writer process until a shared rate-limit store exists (in-process quotas multiply across processes).
|
|
|
|
## Integration sharp edges (do not ignore)
|
|
|
|
- Never mint `issue_agent_session` from a client-supplied name or header. Only after a verified challenge-response. Prefer keeping that helper internal to verified paths.
|
|
- Human view codes are ~40 bits; keep TTL short; never log raw codes (already hashed in audit).
|
|
- Challenge signatures today sign the raw nonce (no domain separation). Changing the signed payload needs a coordinated version bump — tracked as a follow-up, not a silent break.
|
|
|
|
## Deferred
|
|
|
|
- SQLCipher / page-level encryption for multi-tenant co-resident hosts.
|
|
- Domain-separated challenge payloads (`sigil-challenge-v1` prefix) — backward-incompatible without a protocol version.
|
|
- Shared cross-process rate limiter.
|