amduat-api/notes/What SOPS is good at.md

Short answer: yes, you can use SOPS offline — and yes, it actually fits your model well — but only in a very specific role. It should be a transport + hygiene container, not a trust anchor or semantic authority.

Below is the precise guidance, aligned with your architecture.

---

1. What SOPS is good at (in your system)

SOPS excels at:

• Encrypting small structured payloads (YAML / JSON / binary blobs)
• Using offline keys (age, PGP)
• Providing tamper-evidence during transport
• Being human-operable on an air-gapped Debian machine

That maps nicely to:

“Move sensitive authority material safely from the offline signer to the online ASL domain.”

---

2. What SOPS must not be used for

SOPS must not be used as:

• A trust model
• A certification system
• An authority definition
• A replacement for DAM / certificates
• A verifier of correctness

In your system:

• Signatures establish truth
• SOPS only protects envelopes

This distinction is critical.

---

3. Correct placement of SOPS in the stack

Think of SOPS as living outside ASL semantics:

[ Offline Debian ORA ]
    |
    |  (SOPS-encrypted container)
    v
[ Transport medium: USB / SCP / email ]
    |
    v
[ Online ASL node ]
    |
    |  (decrypt)
    v
[ ASL artifact import + signature verification ]

Once decrypted:

• SOPS is discarded
• Only hashes + signatures matter

---

4. What should go inside SOPS containers

Good candidates ✅

• AuthorityCertificate artifacts (binary or canonical form)
• DAM source manifests (pre-hash)
• Policy documents (pre-hash)
• Key material temporarily (if absolutely required)
• Signing requests awaiting approval

Bad candidates ❌

• ASL blocks
• Snapshots
• PERs
• TGK edges
• Anything whose meaning depends on encryption

---

5. Recommended SOPS payload structure

Use SOPS as a sealed courier envelope:

kind: asl-authority-envelope
version: 1

payload:
  type: authority-certificate
  domain_id: example.org/build
  policy_hash: sha256:...
  artifact_bytes: |
    BASE64(AuthorityCertificate canonical bytes)    

metadata:
  issued_by: offline-root
  comment: "Initial domain bootstrap"

• Encrypt with age (simplest, modern, offline-friendly)
• No need for KMS
• No need for cloud hooks

---

6. Canonical rule (important)

The SOPS container is never hashed, never signed, and never referenced by ASL.

Only the decrypted payload bytes are:

• Hashed
• Signed
• Stored as artifacts
• Snapshot-pinned
• Federated

This preserves determinism.

---

7. Offline Debian workflow (clean and safe)

On offline machine

1. Generate or review authority material
2. Produce canonical bytes
3. Sign with root key
4. Place result in SOPS envelope
5. Encrypt with age recipients
6. Export file

On online machine

1. Decrypt SOPS envelope
2. Verify signature
3. Hash payload
4. Import as ASL artifact
5. Reference from DAM / snapshot
6. Forget SOPS ever existed

---

8. Why SOPS is a good fit here

Requirement	SOPS
Offline	✔
Human-auditable	✔
Minimal tooling	✔
Deterministic payloads	✔ (after decrypt)
Transport security	✔
Authority semantics	✘ (by design)

That last line is a feature, not a bug.

---

9. Alternative (why you probably don’t need more)

You don’t need:

• Vault
• HSM integration
• X.509
• TPM attestation
• Live secret management

Because your authority is historical and snapshot-bound, not session-based.

---

10. Final recommendation (clear and direct)

✔ Yes, use SOPS offline ✔ Use it as a sealed delivery container ✔ Keep all meaning outside SOPS ✘ Do not let SOPS define trust ✘ Do not hash or sign SOPS files

---

One-sentence takeaway

SOPS is an excellent armored courier for authority artifacts — but the moment it defines meaning or trust, it’s being misused.

If you want next, we can:

• Define an exact age key strategy for ORA
• Specify how many offline roots to trust
• Model temporary rescue-node authority via SOPS
• Show a bootstrap-from-zero ceremony

Just say where to go next.