amduat-api/notes/USB REQUEST-RESPONSE SCHEMAS.md

Excellent. Below is a tight, normative draft set that you can treat as v0.1 specs. I’ll keep this aligned with your philosophy: PEL early, receipts primary, ASL as the riverbed, no premature coupling.

I’ll structure this into five sections, exactly as requested.

---

1. USB REQUEST / RESPONSE SCHEMAS (Normative)

1.1 USB REQUEST Schema (v0.1)

/usb/REQUEST/
├── manifest.yaml          # REQUIRED
├── pel-program.yaml       # REQUIRED
├── input-artifacts/       # OPTIONAL (directory of files or blocks)
├── policy.hash            # REQUIRED
├── request.sig            # REQUIRED
└── meta/                  # OPTIONAL
    ├── requester-domain.txt
    └── notes.txt

manifest.yaml

version: 1
request_id: <uuid>
request_type: rescue | admission | authority-op
created_at: <iso8601>
requested_outputs:
  - artifacts
  - receipt
  - dam            # optional
policy_hash: <sha256>
pel_program_hash: <sha256>
input_artifact_hashes:
  - <sha256>
signing:
  algorithm: ed25519
  signer_hint: <string>

Invariant:

The manifest is the canonical object. All hashes are computed over canonical encodings.

---

1.2 USB RESPONSE Schema (v0.1)

/usb/RESPONSE/
├── receipt.per            # REQUIRED
├── published/
│   ├── blocks/
│   ├── index/
│   └── snapshots/
├── dam/                   # OPTIONAL
│   └── domain.dam
├── response.sig           # REQUIRED
└── meta.yaml              # OPTIONAL

Invariant:

RESPONSE is append-only and must be reconstructible as ASL input elsewhere.

---

2. PEL SUBSET ALLOWED ON AUTH HOST

2.1 Allowed PEL Operations

Only pure, deterministic, side-effect-free operators:

Category	Allowed
Ingest	✔
Hash	✔
Encrypt	✔
Chunk / Pack	✔
Seal	✔
Index	✔
Snapshot	✔
Sign	✔
Network	✖
Clock access	✖
Randomness	✖
External exec	✖

---

2.2 PEL Program Constraints

pel_version: 0.1
operators:
  - ingest
  - encrypt
  - seal
  - index
  - snapshot
outputs:
  - receipt
  - published_artifacts

Invariant:

The PEL program hash is part of the receipt and MUST uniquely determine execution.

---

3. EXECUTION RECEIPT (PER) SIGNATURE LAYOUT

3.1 Receipt Structure

receipt_version: 1
receipt_id: <uuid>
domain_id: <uuid>
snapshot_id: <uuid>
pel_program_hash: <sha256>
inputs:
  - artifact_hash
outputs:
  artifacts:
    - artifact_key
    - block_id
receipt_hash: <sha256>
authority_signature:
  algorithm: ed25519
  key_id: <fingerprint>
  signature: <bytes>

---

3.2 Receipt Invariants

1. Receipt uniquely identifies:

   • Inputs
   • Program
   • Snapshot

2. Receipt hash is computed before signing

3. Receipt verification requires no ASL store access

A receipt is portable truth.

---

4. PUBLISHED ARTIFACT SELECTION RULES

4.1 Default Rule

Only artifacts explicitly declared in the PEL program as publish: true may exit the host.

outputs:
  - name: encrypted_archive
    publish: true
  - name: intermediate_chunks
    publish: false

---

4.2 Enforcement

• Unpublished artifacts:

  • May exist internally
  • MUST NOT be written to USB

• Published artifacts:

  • MUST be sealed
  • MUST be indexed
  • MUST be referenced in receipt

---

4.3 Domain Binding

Published artifacts are bound to:

(domain_id, snapshot_id)

This binding is immutable.

---

5. WRITE-ONCE USB HARDENING RULES

These are operational invariants, not filesystem tricks.

5.1 Mount Discipline

Phase	Mount mode
Intake	read-only
Execution	unmounted
Output write	read-write
Final	unmounted

---

5.2 Structural Rules

• AUTH host never deletes from USB
• AUTH host only writes under /RESPONSE
• AUTH host never modifies REQUEST

---

5.3 Tamper Evidence

• RESPONSE includes:

  • response.sig
  • hash of REQUEST manifest

• Any post-write modification invalidates signature

---

6. How this fits your philosophy (explicitly)

You said:

“All we should do is place artifacts, certificates, program specification and intent, then crank.”

That is now formally true.

• Intent → manifest
• Program → PEL
• Data → artifacts
• Authority → signature
• Outcome → receipt

Nothing else matters.

---

7. What you can implement immediately

Even without ASL-CORE or PEL-TRACE:

• Canonical hashing
• Manifest validation
• Receipt generation
• USB discipline
• Domain bootstrapping
• Offline signing

This is real progress, not paper.

---

If you want next, I recommend (in this order):

1. PEL canonical encoding rules
2. Receipt hash canonicalization
3. DAM schema finalization
4. Minimal reference CLI (asl-auth-host verify/run/seal)
5. Threat model write-up

Just say where to go.