niklas/amduat-api
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
amduat-api/ops/legacy/ENC-ASL-AUTH-HOST.md
Carl Niklas Rydberg 74efedf62c Rework ops specs
2026-01-17 09:21:47 +01:00

4.9 KiB
Raw Blame History

Perfect! Here’s a draft specification for ENC-ASL-AUTH-HOST v0.1, the on-disk layout and encoding for the authority host. This complements ASL-AUTH-HOST by formalizing how artifacts, blocks, logs, snapshots, and certificates are stored.

ENC-ASL-AUTH-HOST v0.1 — On-Disk Layout

1. Purpose

Defines the physical and logical layout of an ASL authority host’s storage. Ensures:

  • Deterministic artifact placement
  • Snapshot-aware storage
  • Offline-first operation
  • Compatibility with ASL-HOST, PERs, and SOPS bundles

2. Root Layout

/asl-auth-host/
├─ /domains/
│   ├─ <domain-id>/
│   │   ├─ /store/
│   │   ├─ /log/
│   │   ├─ /snapshots/
│   │   ├─ /certs/
│   │   ├─ /policies/
│   │   └─ /dam/
├─ /tools/
│   └─ <binary-tools>   # deterministic, versioned rescue/auth tools
├─ /env-claims/
│   └─ <snapshot-hash>.claim
└─ /sops-bundles/
    └─ <bundle-id>.sops

3. Domains Directory

/domains/<domain-id>/ contains all domain-specific storage and authority artifacts.

3.1 Store

/domains/<domain-id>/store/
├─ blocks/
│   ├─ <block-id>.bin    # raw artifact bytes
│   └─ <block-id>.meta   # metadata: size, type_tag, sealed_flag
├─ indices/
│   ├─ segment-<n>.idx   # ASL-STORE index segments
│   └─ bloom-<n>.bf      # optional bloom filters
  • Each block is immutable once sealed
  • Segment indices point to block IDs and offsets
  • Encoding follows ASL-STORE-INDEX + ENC-ASL-STORE(-INDEX) rules

3.2 Log

/domains/<domain-id>/log/
├─ log-<seq>.aol   # append-only log files

  • Each log record contains:

    • Artifact additions
    • DAM signatures
    • Snapshot seals
    • Tombstone records

  • Deterministic replay reconstructs CURRENT state

3.3 Snapshots

/domains/<domain-id>/snapshots/
├─ snapshot-<id>.meta
├─ snapshot-<id>.blocks  # optional reference map

  • Snapshot metadata includes:

    • Logseq boundary
    • Sealed segments
    • Block references
    • Environment claim artifact reference

  • Snapshots are immutable

3.4 Certificates

/domains/<domain-id>/certs/
├─ root.pub           # root public key
├─ root.priv.enc      # encrypted private key
├─ dam-signer.pub     # optional signing key for DAMs
├─ dam-signer.priv.enc
  • All private keys are encrypted and never leave offline host
  • Public keys are referenced in DAM artifacts

3.5 Policies

/domains/<domain-id>/policies/
├─ policy-<hash>.json

  • Policy hash stored as artifact

  • Policies include:

    • Domain admission rules
    • Courtesy leases
    • GC / retention rules

3.6 Domain Admission Manifests (DAM)

/domains/<domain-id>/dam/
├─ dam-<seq>.json.sig  # signed DAM artifact

  • Each DAM artifact contains:

    • Domain ID
    • Root key fingerprint
    • Policy hash
    • Courtesy lease info (optional)

  • Signed by root key

4. Tools

/tools/
├─ asl-auth-host       # main authority binary
├─ asl-rescue          # SystemRescue patched tools
└─ sops                # for offline bundle creation
  • Versioned, deterministic, immutable binaries
  • Executables stored as ASL artifacts if desired

5. Environment Claims

/env-claims/
├─ <snapshot-id>.claim

  • Contains:

    • OS image hash
    • Boot environment info
    • Installed tool hashes
    • ASL-HOST store checksum at snapshot

  • Stored as artifact and optionally signed by root key

6. SOPS Bundles

/sops-bundles/
├─ <bundle-id>.sops
  • Encrypted container for DAMs, PER receipts, and optionally policies
  • Can be delivered to new nodes for admission or rescue
  • Includes checksums for integrity

7. Encoding Conventions

  1. Blocks: <block-id>.bin (raw bytes), accompanied by <block-id>.meta

  2. Indices: segment-based index; segment files immutable after seal

  3. Log: append-only, each entry:

    • logseq | artifact_key | block_ref | type_tag | operation | signature

  4. Snapshots: snapshot ID derived from hash of CURRENT log + block refs

  5. Certificates: PEM or ASL-artifact wrapped keys

  6. SOPS Bundles: standard encrypted JSON/YAML with embedded checksums

8. Security Notes

  • Private keys must never be exposed or included in SOPS bundles unencrypted
  • Blocks in store may be encrypted with per-domain keys
  • Environment claims ensure proof of offline execution
  • DAMs must be signed to be trusted

This layout allows the authority host to:

  • Bootstrap personal or group domains
  • Accept rescued artifacts
  • Produce deterministic PERs and snapshots
  • Create SOPS bundles for new nodes
  • Operate fully offline

If you want, I can draw a full diagram showing the ENC-ASL-AUTH-HOST tree, block-flow, snapshot integration, and PER generation, so it’s easier to visualize the data flow during rescue or admission.

Do you want me to make that diagram next?