path: root/docs/FOG-COMPOSER.md

# FOG Composer

Status: Draft 0.1

Date: 2026-08-08

## 1. Purpose

This document defines `FOG-COMPOSER`, the networkless endpoint, local-state,
transfer, recovery, and update-verification contract for FOG native services.

It fixes the common Composer security boundary, MicroVM and Portable
deployment profiles, process separation, authenticated encrypted vault,
transaction and rollback rules, hostile import handling, committed export
bundles, identity-safe recovery, update verification, local rendering,
resource limits, and conformance gates.

It records four non-active implementation candidates:

- `FOG-COMPOSER-CANDIDATE-LINUX-VAULT-1` for a Linux read-only system image,
  LUKS2 defense-in-depth volume encryption, a transactional embedded
  database, and object-level authenticated encryption;
- `FOG-COMPOSER-CANDIDATE-MICROVM-QUBES-1` for a Qubes-style networkless VM
  with narrowly allowlisted qrexec transfer services;
- `FOG-COMPOSER-CANDIDATE-PORTABLE-LINUX-1` for a signed read-only Linux image
  on dedicated physically offline hardware;
- `FOG-COMPOSER-CANDIDATE-UPDATE-TUF-1` for offline update metadata derived
  from The Update Framework.

Separately, `FOG-COMPOSER-FIXTURE-EPHEMERAL-CONTAINER-1` records a
functional-only rootless, networkless, read-only container whose bounded
runtime state exists only in tmpfs for one-shot drops and explicitly
non-resumable sessions. It is not a conforming deployment profile.

These candidates have no active numeric profile IDs, do not select final
libraries or cryptographic parameters, are not authorized for public release,
and do not establish deployed endpoint-security claims.

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, and MAY describe
normative requirements in the sense of BCP 14 when they appear in uppercase.

## 2. Scope

`FOG-COMPOSER` owns:

- the networkless Composer runtime and its local privilege boundaries;
- common, MicroVM, Portable, and lower-assurance transfer profiles;
- booted-image verification requirements visible to the Composer;
- encrypted mutable state, key wrapping, object protection, and state
  migration;
- local atomic transactions spanning messaging, storage, PKI, imports,
  exports, recovery, and application state;
- local state commitments and optional external monotonic anchors;
- fixed Composer bundle framing and direction-specific record allowlists;
- import quarantine, complete validation, deduplication, and state release;
- transactional export creation and duplicate-export behavior;
- identity recovery packages and non-resumable restored sessions;
- offline release and update verification on Composer systems;
- safe local rendering and native application module boundaries;
- local retention, deletion, diagnostic, and resource-limit behavior;
- Composer-specific conformance and fault-injection evidence.

This document does not own:

- message handshake, ratchet, envelope, acknowledgment, or fragmentation
  cryptography;
- storage capabilities, replica envelopes, receipts, retention, or polling;
- KEMSphinx packet or SURB construction;
- adjacent online Noise links or blind-relay queue behavior;
- FOG-PKI consensus production, authority recovery, or transparency proofs;
- FOG-SX framing, FEC, physical signaling, or optical hardware;
- entry capsule and return-rendezvous constructions;
- release-repository production, signing ceremonies, or build provenance;
- a native multi-device protocol or automatic account recovery service.

Those contracts belong to `FOG-MESSAGING`, `FOG-STORAGE`,
`FOG-SPHINX-PROFILES`, `FOG-WIRE`, `FOG-PKI`, `FOG-SX`, the entry and return
specifications, a future `FOG-UPDATE` release contract, and future
multi-device work.

## 3. Security Boundary and Threats

### 3.1 Assets

The Composer holds the highest-value user assets in FOG:

- message plaintext, drafts, permitted attachments, and rendered history;
- pairwise identity roots, handshake identities, prekeys, ratchets, and
  skipped-message keys;
- storage read and write capabilities, recovery tombstones, and outboxes;
- contacts, private labels, verification decisions, and conversation state;
- PKI trust anchors, accepted epochs, checkpoints, manifests, and
  equivocation evidence;
- KEMSphinx routes, ephemeral secrets, SURBs, reply tokens, and pending
  network work;
- vault, object, transfer-pairing, backup, recovery, and local anchor keys;
- installed release state, trusted release roots, and rollback floors.

Compromise of an unlocked Composer can expose or alter all local assets. No
storage, boot, VM, or transfer mechanism can preserve confidentiality against
an attacker that controls the code currently using the plaintext and keys.

### 3.2 Adversaries

The contract considers:

- theft or forensic copying of powered-off storage;
- malicious, malformed, replayed, truncated, reordered, or oversized import;
- a compromised blind relay, transfer receiver, removable medium, QR reader,
  FOG-SX decoder, or update distributor;
- partial database corruption, torn writes, power failure, disk-full faults,
  and stale filesystem snapshots;
- rollback or cloning of a complete internally consistent Composer vault;
- a hostile MicroVM host, hypervisor, firmware, peripheral, DMA device, boot
  chain, or system update;
- malicious contacts and authenticated but adversarial message content;
- physical observation, evil-maid access, side channels, and secret remnants;
- dependency, compiler, build, release-key, or update-metadata compromise.

### 3.3 Trust distinctions

Object-level authenticated encryption protects stored object confidentiality
and integrity under its exact key assumptions. It does not prove freshness.

A hash-chained local journal detects missing, reordered, partially restored,
or corrupted state relative to the latest state still available locally. It
cannot detect replacement of the complete vault, journal, and keys by an older
coherent copy.

Complete rollback detection requires a monotonic anchor outside the rollback
domain. A virtual TPM controlled by the same hostile VM host is not independent
of that host. A counter alone also does not automatically bind the intended
state commitment unless the selected anchor protocol proves that binding.

Networklessness prevents direct network access by the guest or portable
runtime. It does not prevent a hostile host, firmware, peripheral, or human
from observing or modifying the endpoint.

## 4. Protocol Invariants

### COMPOSER-INV-01: No network interface

A conforming Composer has no network adapter, route, network namespace access,
socket activation, proxy, update proxy, loopback service, HTTP server, RPC
server, or plugin listener. A convenience mode with networking is not a FOG
Composer profile.

### COMPOSER-INV-02: One active mutable instance

One Composer identity vault has exactly one active mutable instance. Copying a
vault, VM private volume, database, USB state partition, or live backup does
not create a second device. Any suspected clone freezes affected ratchets,
capabilities, prekeys, outboxes, and monotonic state.

### COMPOSER-INV-03: Random data keys, human unlock

Bulk state is encrypted under random vault and object keys. A passphrase or
recovery phrase is processed only by the profile's reviewed memory-hard KDF to
unlock or rewrap random key material. It is never used directly as an AEAD
key, identity key, ratchet seed, storage capability, or backup key.

### COMPOSER-INV-04: Every sensitive object is authenticated

Identity, contact, draft, message, ratchet, capability, outbox, inbox,
deduplication, PKI monotonic, recovery, and update state has object-level
authenticated encryption or an equally reviewed authenticated container.
Whole-volume encryption is defense in depth and is not accepted as the sole
object-integrity control.

### COMPOSER-INV-05: Persist and anchor before effect

A security-critical transition is not externally exportable and its plaintext
is not renderable until the complete local transaction is durable. Where the
profile claims full rollback detection, the corresponding external monotonic
anchor transition must also be durable before export or rendering.

### COMPOSER-INV-06: Local chain is not full anti-rollback

Documentation and UI MUST distinguish local consistency verification from
independent monotonic anchoring. A self-contained vault without an external
anchor MUST NOT claim detection of a complete coherent rollback.

### COMPOSER-INV-07: Every import is hostile

Filename, label, QR presentation, media filesystem, MIME type, transport
checksum, FEC result, relay origin, and operator statement confer no
authenticity. Complete bounded parsing and the owning inner cryptographic
verification occur before state transition or rendering.

### COMPOSER-INV-08: Export contains committed opaque work only

An export bundle contains only already committed public objects or opaque
protocol work. It never contains message plaintext, drafts, identity private
keys, contact labels, ratchet state, capability roots, database keys, backup
keys, crash diagnostics, or a long-term Composer signature visible to the
relay.

### COMPOSER-INV-09: Transfer signatures do not create a public identity

FOG does not sign relay-facing bundles with a long-term user or Composer key.
Each inner object supplies its owning authentication. A local transfer-pairing
authenticator MAY reject random injection but does not replace inner
verification and does not become a remote network identity.

### COMPOSER-INV-10: Recovery never silently resumes live state

An identity recovery package can preserve explicitly allowed long-term
identity and contact verification material. Restored live ratchets,
capability streams, prekeys, reply tokens, outboxes, and deduplication windows
remain frozen. They are replaced through authenticated recovery transitions,
not resumed from a stale snapshot.

### COMPOSER-INV-11: Update verification is offline and monotonic

An update installs only after threshold signature, metadata chain, target
hash, target length, platform, compatibility, expiry, version, and rollback
floor validation. No online fetch, local administrator override, unsigned
emergency image, or boot failure authorizes a downgrade.

### COMPOSER-INV-12: Immutable runtime image

The booted operating-system and Composer image are read-only and verified by a
root authenticated outside that mutable image. Writable application state,
temporary data, logs, and update staging cannot replace executable content.

### COMPOSER-INV-13: No active imported content

Initial native applications render bounded plain text and fixed local UI
objects only. HTML, scripts, macros, fonts, office files, PDFs, media codecs,
shell commands, desktop launchers, and automatic external resource loading are
not valid message content.

### COMPOSER-INV-14: High-assurance paths are physically directional

The high-assurance export and import paths use separate transmit-only and
receive-only mechanisms. A removable device alternated between online and
offline systems is a named lower-assurance profile, never an invisible
fallback.

### COMPOSER-INV-15: No secret-bearing diagnostics

Logs, metrics, crash dumps, support bundles, command arguments, environment
variables, shell history, swap, hibernation, thumbnails, previews, clipboard,
and generic desktop indexes contain no Composer secrets or plaintext.

### COMPOSER-INV-16: No runtime extension mechanism

The Composer loads no third-party plugin, interpreted script, external
renderer, generic parser, dynamic protocol module, or operator-selected crypto
provider. New functionality requires a reviewed release and an authenticated
profile transition.

## 5. Deployment Profiles

### 5.1 Common profile

Every Composer profile MUST:

- boot an authenticated read-only software image;
- omit or disable all network and radio devices and drivers;
- use one dedicated mutable vault with object-level authenticated encryption;
- strongly recommend whole-volume encryption as defense in depth and disclose
  the powered-off metadata exposure when it is omitted;
- separate import quarantine and export spool from active vault state;
- disable swap, hibernation, core dumps, automatic crash reporting, previews,
  indexing, and host clipboard integration;
- mount no internal disk or general removable filesystem automatically;
- expose only the minimum display, human input, import, export, state, and
  optional monotonic-anchor devices;
- enforce the exact bundle profiles, limits, and direction allowlists;
- require explicit human unlock and explicit update or recovery ceremonies;
- show the current assurance profile and lost assumptions locally.

### 5.2 MicroVM profile

The MicroVM definition contains no virtual NIC. Network absence is enforced at
the hypervisor configuration, guest kernel configuration, process sandbox,
and conformance-test levels.

Host integration is limited to:

- a minimal display path;
- explicit keyboard and pointing input;
- one bounded import data channel;
- one separately authorized bounded export data channel;
- one dedicated mutable state block device;
- an optional external monotonic-anchor interface.

Shared directories, host filesystem mounts, arbitrary qrexec, drag-and-drop,
clipboard, audio, camera, USB passthrough, generic guest agents, shell
services, and bidirectional device forwarding are forbidden.

The host and hypervisor remain inside the endpoint trust assumption. A
MicroVM profile can reduce accidental network exposure and contain some
application failures, but cannot protect unlocked memory or execution from a
host that can inspect or replace the guest.

The Qubes candidate uses a dedicated no-NetVM qube and two exact qrexec
services with fixed direction and byte bounds. General qrexec command
execution, file-copy services, URL opening, clipboard, and update proxy access
remain denied. Qubes is an integration candidate, not a runtime dependency or
an automatic security claim.

### 5.3 Portable profile

The Portable profile boots signed immutable media on a physically offline
computer. Its kernel and initramfs omit network, Bluetooth, cellular, NFC,
Thunderbolt networking, and unnecessary radio drivers. Firmware setup and
physical switches disable available radios where supported.

It MUST:

- verify the bootloader, kernel, initramfs, command line, root-image digest,
  and Composer release identity before vault unlock;
- use a read-only verified root image and a separate mutable state partition
  with mandatory object-level authenticated encryption;
- strongly recommend whole-volume encryption for that state partition;
- refuse automatic internal-disk, network-share, and foreign-filesystem
  mounting;
- use dedicated receive-only and transmit-only transfer devices in its
  high-assurance form;
- keep Composer state media away from online machines;
- warn locally when Secure Boot, measured boot, immutable-root verification,
  external anchoring, or physical directionality is absent.

Portable means the signed system and encrypted state can be carried. It does
not mean the same active state may be cloned or used concurrently. A profile
that binds rollback protection to one machine TPM is machine-bound even if its
boot media is removable.

### 5.4 Portable shuttle profile

`PORTABLE_SHUTTLE` permits one explicitly labeled removable transfer medium to
move opaque bundles between online and offline systems. It is lower assurance
because the online system can attack the medium controller, filesystem, and
subsequent offline parser and because the medium provides a physical return
channel.

This profile still requires the fixed Composer bundle parser, separate import
quarantine, no automatic execution, no general file browsing, and complete
inner authentication. It MUST NOT inherit the high-assurance simplex or
peripheral-compromise claim.

### 5.5 Claim matrix

| Property | MicroVM | Portable high assurance | Portable shuttle |
| --- | --- | --- | --- |
| Composer process has no network | required | required | required |
| Host compromise protection | not claimed | not applicable while dedicated offline hardware is honest | not claimed for online transfer host |
| Read-only verified system image | required | required | required |
| Separate directional transfer hardware | profile-dependent | required | absent by definition |
| Complete rollback detection | only with an anchor outside the hostile host | only with independent anchor | only with independent anchor |
| Physical peripheral isolation | host-dependent | required and measured | weakened |
| Endpoint compromise protection while unlocked | not claimed | not claimed | not claimed |

### 5.6 Ephemeral container fixture

`FOG-COMPOSER-FIXTURE-EPHEMERAL-CONTAINER-1` is a functional and
lower-assurance direction, not a substitute for the MicroVM or Portable
profiles. It uses a rootless container with no configured network interface,
a read-only container root, bounded tmpfs mounts for runtime state, no
persistent vault or application log, no host clipboard, and no generic shared
directory.

The Ephemeral Composer is limited to one-shot `fog-drop` operations and
sessions whose identity, keys, capabilities, pending work, and reply ability
are intentionally abandoned at shutdown. It MUST NOT create or resume a
continuing mailbox, ratchet, voucher, deduplication window, acknowledgment
stream, or capability sequence after its runtime state is lost.

Container shutdown is only logical best-effort disposal. It does not prove
erasure from host swap, hibernation, kernel caches, residual RAM, logs,
display capture, input infrastructure, crash artifacts, or a compromised host.
The container shares the host kernel, and a hostile host can inspect or alter
its unlocked plaintext, keys, execution, devices, and transfer channels.

## 6. Process and Module Architecture

### 6.1 Security domains

The Composer image contains these local domains:

1. `fog-compose`: the only process that unlocks vault keys, performs protocol
   state transitions, and renders authenticated plaintext;
2. import decoder: an unprivileged sandbox that reads one raw transfer stream,
   validates only outer framing and limits, and writes one quarantine object;
3. export encoder: an unprivileged sandbox that reads one already sealed
   opaque export and drives one transmit-only backend;
4. update verifier: a maintenance environment that has release roots and
   inactive image access but no unlocked Composer vault;
5. optional anchor adapter: a minimal process or device interface that exposes
   only the profile's monotonic prepare, advance, and read operations.

The import decoder does not receive vault keys, identity state, contact state,
message plaintext, network configuration, a shell, or writable executable
paths. Its output remains untrusted when `fog-compose` opens it.

The export encoder cannot query the vault or create new protocol work. It can
read only one immutable export spool item selected by `fog-compose` and cannot
write to import quarantine.

### 6.2 Internal modules

Inside the `fog-compose` trust domain, responsibilities remain explicit:

```text
ui
  -> native applications
     -> messaging and storage coordinators
        -> transaction service
           -> encrypted vault

import coordinator -> protocol verifiers -> transaction service
export coordinator -> committed protocol outbox -> export spool
PKI verifier -------^                         |
anchor coordinator ---------------------------^
```

The initial implementation SHOULD use modules named by responsibility:

- `composer/vault`: key hierarchy, encrypted objects, schema, transactions;
- `composer/anchor`: state commitments and monotonic-anchor protocol;
- `composer/import`: bundle validation, quarantine, deduplication, dispatch;
- `composer/export`: committed selection, sealing, spool lifecycle;
- `composer/update`: trusted metadata and installed-version state;
- `composer/recovery`: recovery package creation and restore freeze;
- `composer/ui`: safe presentation and explicit user decisions;
- `apps/drop`, `apps/mailbox`, and `apps/im`: native state machines only.

Protocol modules do not import UI, filesystem, database, qrexec, removable
media, or platform code. Platform adapters do not implement messaging,
storage, PKI, or cryptographic state transitions.

### 6.3 What not to split

The initial implementation does not create:

- separate network services for native applications;
- one database per application;
- a generic plugin host or IPC bus;
- a background indexing or search service with plaintext access;
- a universal crypto, filesystem, archive, or document adapter;
- concurrent writable Composer processes.

One transaction owner and one encrypted database simplify the required
cross-layer atomic commits. Process separation is used only where it removes
raw transfer or update parsing from the vault-bearing process.

## 7. Boot and Runtime Hardening

### 7.1 Verified immutable image

The profile authenticates the complete boot path and one immutable root-image
digest. The Linux candidate uses a signed boot artifact and `dm-verity` for
read-only block verification. The authenticated root digest must be inside the
signed boot chain, not supplied by mutable kernel arguments or the state
volume.

Verification failure stops before vault unlock. An integrity error after boot
locks the vault, produces no export, and enters recovery. Ignore-corruption and
continue-on-verification-failure modes are forbidden.

### 7.2 Writable mounts

The runtime permits only:

- the dedicated mutable state volume, with whole-volume encryption strongly
  recommended;
- a bounded encrypted or memory-backed import quarantine;
- a bounded export spool containing opaque committed bundles;
- bounded memory-backed temporary directories;
- explicit update staging only in maintenance mode.

Executable, setuid, device, and interpreter behavior is disabled on mutable
mounts where the platform supports it. Imported filenames never become local
paths. The Composer does not traverse a foreign filesystem supplied by a
transfer medium.

### 7.3 Runtime controls

The active Composer profile requires:

- no swap or hibernation;
- disabled core dumps and process-memory crash capture;
- locked-down debugging, tracing, performance counters, and ptrace;
- no shell or package manager in the user session;
- no automatic login or vault unlock;
- strict process, file-descriptor, memory, CPU, and disk quotas;
- default-deny device and syscall policy, including network socket creation;
- memory-backed plaintext staging with bounded lifetime;
- explicit lock on suspend, display loss, anchor loss, or integrity fault.

Memory locking and explicit zeroization are best-effort implementation
controls. They do not prove that compilers, kernels, caches, firmware, DMA,
hibernation remnants, or physical memory retained no copy.

## 8. Vault and Key Hierarchy

### 8.1 Vault layers

The Composer always uses:

1. object-level authenticated encryption for every sensitive logical record.

The Composer strongly recommends, but does not universally require:

2. full-volume encryption to hide filesystem metadata, database pages,
   journals, temporary files, and free space while powered off.

A profile that omits layer 2 MUST disclose that loss of defense in depth and
MUST NOT weaken layer 1, key separation, transaction integrity, or message
end-to-end encryption.

The Linux candidate evaluates LUKS2 for layer 2. It does not rely on ordinary
sector encryption to authenticate logical records. Any LUKS2 integrity mode
requires separate maturity, performance, recovery, and power-failure review.

### 8.2 Key hierarchy

The minimum hierarchy is:

```text
human unlock secret
  -> profile-fixed memory-hard KDF
     -> unlock KEK
        -> unwrap random vault key
           -> profile-fixed KDF/exporter
              -> identity-object key epoch
              -> contact-object key epoch
              -> messaging-state key epoch
              -> storage-state key epoch
              -> PKI-state key epoch
              -> draft/content key epoch
              -> outbox/import/export key epoch
              -> local-state-authentication key epoch
```

The backup or recovery key hierarchy is generated independently. It never
derives from the live vault key, a contact root, message ratchet, storage
capability, transfer-pairing key, release key, or monotonic-anchor key.

The unlock KDF stores its algorithm identifier, salt, memory cost, time cost,
parallelism, and output length in authenticated keyslot metadata. Parameters
are benchmarked per supported hardware class and may be raised through a
versioned rewrap without reencrypting all logical objects.

The deployment profile states whether volume unlock and object-vault unlock
use one human secret or separate factors. If one human secret is used, each
layer has independent salts, context, KDF output, and wrapping key. Raw keys
are never reused between the LUKS2 and object-vault layers.

### 8.3 Keyslot rules

A keyslot wraps only random vault or recovery key material. Adding, removing,
or changing a passphrase is an authenticated transaction. The previous slot
remains in the live header only until the new slot and replacement header
backup are durably verified.

A memory-hard KDF raises guessing cost but does not turn a weak passphrase into
a high-entropy secret. The UI requires a profile-appropriate secret and states
the offline-guessing risk.

Removing a LUKS2 keyslot does not revoke an old passphrase against an attacker
who retained an earlier header backup containing that slot and the same volume
key. True revocation against copied old headers requires a reviewed full
volume-key and vault-key rotation, reencrypted data, retirement of old object
keys, and controlled destruction of obsolete headers and media.

Unlock secrets are accepted only through the trusted local UI or a narrowly
specified hardware-token protocol. They never appear in command arguments,
environment variables, files in the export bundle, logs, clipboard, or shell
input history.

Failed unlock attempts have bounded memory and CPU cost. The local UI may
apply a coarse delay, but denial-of-service resistance cannot depend on an
attacker-writable on-disk failure counter.

### 8.4 Object envelope

Every encrypted logical object has a canonical profile-fixed header containing
at least:

```text
[
  vault_format_version,
  vault_profile_id,
  network_id,
  composer_instance_id,
  object_type,
  object_id,
  object_generation,
  transaction_generation,
  key_epoch,
  plaintext_length,
  padded_length,
  nonce,
  ciphertext
]
```

All fields preceding `ciphertext` are authenticated associated data. The
profile fixes lengths, encoding, nonce construction, padding classes, AEAD,
KDF, maximum plaintext, and key epoch. Unknown fields, alternate encodings,
nonce reuse, invalid padding, counter wrap, or authentication failure reject
the object.

`composer_instance_id` is a random local domain separator. It is never placed
in relay-facing bundles, contact cards, messages, PKI, storage records, public
logs, or release metadata.

### 8.5 Object classes

The vault separates at least these object classes and key purposes:

| Class | Examples | Restore rule |
| --- | --- | --- |
| Identity | contact roots, handshake identities | only through identity recovery policy |
| Contact | public roots, fingerprints, local labels, verification decisions | public and local metadata may be recovered |
| Messaging live state | ratchets, prekeys, skipped keys, ACK and dedup windows | stale copy never resumes |
| Storage live state | capabilities, indexes, tombstones, receipts, retry generations | stale copy never resumes |
| Content | drafts, inbox, sent plaintext, reassembly | optional local retention, not required for identity recovery |
| Protocol outbox | immutable envelopes, boxes, packets, reply material | exact live instance only |
| PKI state | genesis root, highest consensus, log checkpoint, manifests | monotonic verification required |
| Release state | trusted roots, metadata versions, installed target, rollback floor | monotonic verification required |
| Local control | transaction journal, state commitment, anchor receipt | never exported or identity-recovered as live state |

### 8.6 Candidate primitives

`FOG-COMPOSER-CANDIDATE-LINUX-VAULT-1` evaluates Argon2id for unlock key
derivation and XChaCha20-Poly1305 for object protection through maintained
reviewed libraries. The candidate uses random nonces from the OS CSPRNG and
purpose-separated KDF outputs.

No primitive, parameter, library, ABI, database, or vault profile becomes
active merely because it appears here. Activation requires exact versions,
byte-level vectors, nonce analysis, crash tests, benchmarks, dependency
review, and independent security review.

## 9. Transactional State Model

### 9.1 One transaction owner

Exactly one `fog-compose` process opens the mutable vault for writing. It uses
one transaction engine capable of atomic durable commit across every logical
object participating in a protocol transition.

Messaging ratchet state, storage capability state, outbox objects, PKI
monotonic state, application queue state, import deduplication, and export
eligibility MUST NOT be committed through independent databases or eventually
consistent workers.

### 9.2 State commitment

Every security-critical transaction produces a canonical `StateCommitment`:

```text
[
  commitment_format_version,
  vault_profile_id,
  network_id,
  composer_instance_id,
  transaction_generation,
  previous_commitment,
  encrypted_catalog_root,
  highest_consensus_epoch,
  consensus_hash,
  transparency_tree_size,
  transparency_root_hash,
  release_root_version,
  installed_release_version,
  import_generation,
  export_generation,
  transaction_class
]
```

The commitment uses a profile-fixed authenticated hash or MAC construction.
It contains no plaintext, contact identifier, message identifier, capability,
box ID, or application type. It remains local except for a private external
anchor that is explicitly part of the same Composer trust domain.

### 9.3 Unanchored commit

An unanchored profile:

1. stages all new encrypted objects and the next catalog separately;
2. validates cross-object invariants and resource bounds;
3. writes and syncs the transaction journal;
4. atomically selects the new catalog and state commitment;
5. syncs the database and containing filesystem metadata;
6. only then releases export eligibility or authenticated plaintext.

This detects ordinary partial writes and local history discontinuity. A
complete older vault copy containing its matching keys and journal can still
pass.

### 9.4 Externally anchored commit

An anchored profile uses a prepared generation so the external effect never
precedes the anchor:

1. retain generation `N` as the active catalog;
2. stage generation `N+1`, its encrypted objects, undo information, and exact
   commitment in a durable `PREPARED` namespace;
3. sync the complete prepared namespace without exposing its work;
4. ask the independent anchor to advance from the exact accepted generation
   and commitment to `N+1` and the new commitment;
5. receive and verify one anchor receipt bound to the instance, generations,
   old commitment, and new commitment;
6. atomically select `N+1` as active and persist the receipt;
7. sync the active selector and journal;
8. only then export work or render newly accepted plaintext.

The anchor operation is compare-and-advance, not an unchecked write. It must
reject a wrong old generation, wrong old commitment, repeated alternate next
commitment, counter wrap, unauthorized reset, or another instance.
An exact retry of an already completed compare-and-advance is idempotent and
returns the same authenticated successor state without another increment.

### 9.5 Crash reconciliation

At startup:

- anchor equals latest finalized local commitment: open normally;
- anchor equals the one exact durable prepared successor: finalize it before
  any other operation;
- anchor remains at the finalized predecessor and no external effect was
  released: discard the prepared successor using its durable staging state;
- anchor is ahead without the exact prepared successor: enter
  `RECOVERY_REQUIRED`;
- anchor has the same generation but another commitment: enter
  `CLONE_OR_TAMPER_DETECTED`;
- local state is ahead of, behind, or unrelated to the anchor outside the
  permitted one-step reconciliation: enter `RECOVERY_REQUIRED`.

No user confirmation, clock change, file rename, or import bundle overrides a
mismatch.

### 9.6 Anchor assurance levels

The registry defines:

- `LOCAL_CHAIN`: no external anchor and no complete-rollback claim;
- `HOST_BOUND_ANCHOR`: useful against accidental snapshot restore but not a
  hostile MicroVM host controlling the anchor;
- `INDEPENDENT_ANCHOR`: a separate hardware or physically controlled state
  that is outside the vault and host rollback domain.

A TPM 2.0 NV counter is only a candidate building block. The active anchor
profile must prove reset authorization, endurance, atomic crash behavior,
binding between generation and commitment, device replacement, backup,
recovery, and denial-of-service behavior. A bare increment command is not by
itself the FOG anchor protocol.

The anchor has no network interface and receives only its private local
instance handle, generation numbers, and opaque fixed-length commitments. It
does not receive the commitment body, object catalog, contact, message,
capability, application type, plaintext, or vault key. It necessarily observes
local anchor-operation count and timing, which remains an endpoint metadata
risk.

### 9.7 Database candidate

The Linux candidate evaluates one SQLite database with one writer and an exact
durability profile. The selected journal mode, synchronization level,
filesystem, block device, locking behavior, power-loss assumptions, and backup
API become immutable profile inputs.

Copying an SQLite main file while a transaction or hot journal exists is not a
backup. The implementation uses the reviewed backup API or a fully quiescent
profile-specific snapshot and preserves every required journal and metadata
file. Database integrity checks do not replace object authentication or an
external monotonic anchor.

## 10. Composer Transfer Bundle

### 10.1 Fixed outer header

Every Composer bundle starts with this exact 128-byte header:

```text
offset  length  field
0       8       magic
8       2       bundle_format_version
10      1       bundle_kind
11      1       flags
12      4       bundle_profile_id
16      32      network_id
48      32      bundle_nonce
80      8       payload_length
88      4       record_count
92      4       record_table_length
96      32      payload_digest
```

`magic`, version, kind, flags, profile, counts, and lengths have one canonical
encoding. `bundle_nonce` contains 256 CSPRNG bits and is unique to the bundle;
it is not an identity or protocol replay token. `payload_digest` provides
bounded corruption detection and canonical deduplication only. It does not
authenticate the producer.

### 10.2 Fixed record header

Each record starts with this exact 48-byte header:

```text
offset  length  field
0       2       record_type
2       2       record_version
4       4       flags
8       8       actual_length
16      8       padded_length
24      16      record_id
40      8       reserved
```

The body contains `actual_length` bytes followed by zero padding to
`padded_length`. The record table lists exact ordered offsets and types before
any body is dispatched. `record_id` is random and bundle-local. Reserved bits,
duplicate IDs, overlap, gaps outside canonical padding, non-zero padding,
integer overflow, inconsistent lengths, and trailing data reject the complete
bundle.

Bundles contain no nested bundle, archive, directory, symlink, device node,
filesystem image, filename, URI, MIME type, compression stream, or executable
metadata.

### 10.3 Bundle kinds

The registry defines separate allowlists for:

- `RELAY_EXPORT`: committed KEMSphinx submissions and bounded public relay
  scheduling hints already authorized by the Composer;
- `RELAY_IMPORT`: complete signed PKI objects, opaque KEMSphinx replies,
  conflict evidence, and bounded public relay state;
- `CONTACT_EXPORT` and `CONTACT_IMPORT`: one bounded contact card, voucher, or
  authenticated contact transition;
- `RECOVERY_EXPORT` and `RECOVERY_IMPORT`: one encrypted recovery package and
  its public format metadata;
- `UPDATE_IMPORT`: signed release metadata and exact target artifacts handled
  only by the maintenance environment.

Wrong-direction records reject the bundle. `UPDATE_IMPORT` is never parsed by
the unlocked ordinary Composer process, and ordinary relay or contact bundles
cannot contain an executable target.

### 10.4 Absolute version-1 limits

These are parser ceilings, not recommended operational batch sizes:

| Item | Absolute limit |
| --- | --- |
| Outer header | exactly 128 bytes |
| Record header | exactly 48 bytes |
| Nesting | forbidden |
| Relay bundle | 64 MiB |
| Relay records | 2048 |
| One relay record | 256 KiB |
| Contact bundle | 1 MiB |
| Contact records | 64 |
| Recovery bundle | 64 MiB |
| Recovery records | 256 |
| Update metadata | 64 MiB |
| Complete update bundle | 16 GiB, streamed only |
| Update records | 4096 |
| Unknown record type or flag | reject complete bundle |

FOG-SX and deployment profiles set lower transport and memory limits. An
update target is streamed to an inactive verified image and never allocated as
one memory buffer.

### 10.5 Authentication ownership

The outer bundle is a transport container. Authentication remains owned by
each embedded protocol:

- PKI objects use authority signatures and monotonic consensus rules;
- KEMSphinx replies use their packet, SURB, token, storage, and message
  authentication;
- contact objects use the exact contact-root or voucher signature rules;
- recovery objects use the recovery envelope and separately held key;
- updates use the release metadata threshold and target hashes.

A Composer-relay pairing key MAY authenticate a local bundle envelope to
reduce random injection and accidental cross-user delivery. The relay is
still untrusted, a pairing MAC is never accepted as message or PKI
authenticity, and the pairing handle is not exported into the FOG network.

## 11. Import Processing

### 11.1 Quarantine

Raw input first enters a new size-limited quarantine object created with an
unpredictable local name and exclusive creation. The decoder streams the
input, enforces the outer limit, calculates the digest, syncs the completed
object, and closes the input before `fog-compose` can open it.

The decoder never extracts files or follows a path supplied by input. Partial,
oversized, timed-out, or multiply opened inputs are deleted without entering
the vault.

### 11.2 Validation order

The Composer:

1. opens the quarantine object read-only without following links;
2. validates exact total size and the 128-byte header;
3. validates bundle direction, network, profile, kind, count, and limits;
4. validates the complete record table and non-overlap before allocation;
5. streams every record through its owning strict parser into staged state;
6. verifies every inner signature, AEAD, hash, token, generation, expiry, and
   monotonic rule required by that record type;
7. compares conflicting complete PKI views and preserves evidence rather than
   merging them;
8. computes all cross-record and cross-protocol state transitions;
9. commits import digest, deduplication, new protocol state, inbox, and any
   resulting outbox through Section 9;
10. only after final commit and required anchor advance, releases plaintext or
    marks resulting work exportable;
11. destroys staged plaintext and expires the quarantine object.

One invalid critical record rejects the complete bundle. The parser does not
continue in order to collect attacker-selected diagnostic detail.

### 11.3 Duplicate and replay handling

The Composer stores a keyed local import identifier derived from the complete
bundle digest and profile. An exact duplicate is idempotent and does not repeat
rendering, ratchet advancement, capability advancement, voucher consumption,
update installation, or recovery.

The bundle identifier is only an outer deduplication aid. Each embedded
protocol still performs its own replay and generation checks. Repacking the
same records into another bundle cannot bypass those checks.

### 11.4 Failure privacy

Detailed failure remains local and bounded. The Composer does not
automatically export a parse error, invalid-contact error, decryption error,
missing-message error, stale-state error, or update-verification oracle.

The UI maps failures to coarse classes such as `INVALID_IMPORT`,
`AUTHENTICATION_FAILED`, `STALE_OR_ROLLED_BACK`, `RESOURCE_LIMIT`,
`RECOVERY_REQUIRED`, and `UNSUPPORTED_PROFILE`. Secret values and attacker
bytes are not copied into diagnostics.

## 12. Export Processing

### 12.1 Export transaction

For every export generation, the Composer:

1. selects only committed eligible outbox objects under the active schedule;
2. validates their protocol profile, lifetime, retry, geometry, and state;
3. generates any fresh KEMSphinx, SURB, route, entry, rendezvous, and reply
   material required for this network transmission;
4. stages the exact immutable bundle, random bundle nonce, record table,
   digest, export generation, and outbox transitions;
5. commits all state and advances the required external anchor;
6. creates a new export spool object with exclusive creation;
7. writes, syncs, seals read-only, and reopens the spool object to verify its
   exact bytes and digest;
8. only then authorizes the export encoder to transmit that one object.

A crash before step 5 creates no exportable bytes. A crash after step 5
recovers the exact committed bundle. A crash during spool creation rebuilds
only those same committed bytes and does not advance a ratchet, capability, or
packet generation again.

### 12.2 Duplicate physical export

Copying or replaying one already sealed bundle can cause duplicate relay
submission. Bundle, packet, courier, storage, and message deduplication remain
required. The Composer never assumes physical transfer occurred merely
because it authorized the encoder.

If the outcome is unknown, later retry creates the fresh outer packet material
required by the owning packet and storage profiles from already committed
inner state. It does not reconstruct an end-to-end message envelope or reuse a
single-use reply secret contrary to those profiles.

### 12.3 Export contents

Relay-facing export MUST NOT contain:

- plaintext, local UI strings, application names, contact labels, drafts, or
  message history;
- long-term user signatures over the bundle, stable Composer instance IDs, or
  vault generations;
- message, session, capability, box, or receipt identifiers outside their
  required opaque cryptographic layer;
- private PKI, release, recovery, backup, state, or transfer keys;
- filesystem paths, usernames, hostnames, locale, timezone, device model, or
  software diagnostics.

Export size class and timing remain observable to the physical transfer path
and blind relay. Cover and scheduling profiles, not the bundle container
alone, govern those metadata claims.

### 12.4 Spool retention

An opaque export spool item remains until one of:

- an explicitly lower-assurance local transfer profile returns an
  authenticated acceptance permitted by that profile;
- a bounded re-export window ends;
- the owning protocol produces authenticated terminal evidence;
- the operation is explicitly cancelled before a forbidden state transition;
- recovery freezes the entire instance.

The high-assurance simplex profile has no automatic receiver acceptance path.
Its Composer therefore relies on bounded spool retention and later owning-
protocol evidence, not an FOG-SX acknowledgment.

Deletion of a spool item never rewinds its protocol state. Sensitive reply
material and ephemeral packet keys follow their shorter owning lifetimes.

## 13. Backup and Recovery

### 13.1 Recovery goals

Composer recovery is designed to preserve the minimum long-term authority
needed to reestablish an identity and verify known contacts. It is not a
transparent snapshot restore and does not promise recovery of undelivered
messages, forward-secret message keys, live storage positions, consumed
prekeys, pending acknowledgments, or current network work.

The default `IdentityRecoveryPackage` MAY contain:

- the FOG network ID and genesis trust-anchor material;
- the long-term pairwise or accountless identity roots explicitly selected
  for recovery;
- contact public roots, verified fingerprints, and verification status;
- encrypted local contact labels when the user includes them;
- release trust roots and minimum accepted release version;
- the latest public PKI checkpoint and consistency metadata as a recovery
  starting point, never as permission to roll backward;
- identity-generation and recovery-package sequence metadata;
- a declaration that every messaging session and storage stream must be
  replaced before use.

The default package MUST NOT contain live ratchets, chain keys, message keys,
skipped keys, one-time prekeys, active storage read or write capabilities,
outbox ciphertexts, SURBs, reply tokens, pending packets, deduplication
windows, transfer-pairing keys, local anchor credentials, or an active
Composer instance ID.

### 13.2 Recovery envelope

The recovery plaintext is one canonical bounded object with an explicit
format version, network, identity set, package sequence, creation release,
key profile, content allowlist, and restore policy. It is padded and
authenticated under a random recovery data key.

That random key is wrapped by a distinct recovery key hierarchy. Recovery key
material is stored separately from the recovery ciphertext. A recovery
passphrase, if supported, uses its own profile-fixed memory-hard KDF, salt, and
parameters and does not reuse the live-vault keyslot or passphrase verifier.

Recovery filenames, QR labels, media labels, and transport checksums are not
authenticated metadata. Every field that affects identity, version, content,
or restore behavior is inside the authenticated envelope.

### 13.3 Recovery export

Recovery creation requires explicit local user confirmation and a dedicated
ceremony outside normal message export. The Composer:

1. validates that the selected identities and contact metadata are eligible;
2. generates a fresh recovery package ID and random data key;
3. constructs and encrypts the exact canonical package;
4. atomically records the package sequence and digest in live state;
5. advances the external anchor when required by the active profile;
6. exports ciphertext and recovery key material through distinct controlled
   paths;
7. verifies one complete test decryption before reporting success;
8. erases transient recovery plaintext and wrapping material.

Normal relay export, contact exchange, and FOG-SX network work MUST NOT carry a
recovery package or recovery key.

### 13.4 Restore

Restore occurs into a fresh verified Composer image and a newly initialized
vault with a new random `composer_instance_id`, vault key, object key epochs,
transfer-pairing keys, and local anchor state.

After verifying and decrypting the package, the new Composer:

- imports the allowed identity roots and contact verification history;
- refuses any recovered PKI, release, or rollback state lower than the trusted
  state embedded in the verified recovery image or independent anchor;
- marks every historical messaging session and storage stream
  `RECOVERY_REQUIRED` or `CLOSED`;
- creates no message, packet, prekey, voucher, read, write, or ACK from restored
  mutable protocol bytes;
- obtains a current PKI view through the full long-offline consistency path;
- verifies the current release chain and rollback floor;
- uses the recovered identity authority to authenticate fresh contact-session
  and storage-stream transitions;
- warns that contacts may need independent fingerprint confirmation when
  compromise, identity change, or ambiguous recovery is suspected.

The old instance is not automatically revoked merely because a new vault was
created. If the old device may still operate, identity compromise and clone
procedures apply and contacts require an authenticated identity transition.

### 13.5 Full-state archives

A routine full copy of a live Composer vault is forbidden as a resumable
backup. A profile MAY create a separately encrypted forensic archive for
disaster analysis, but it is marked `NON_RESUMABLE`, contains no unlock or
anchor key beside its ciphertext, and cannot be opened as an active vault.

Copying a VM private volume, SQLite file, LUKS device, portable state
partition, or suspended memory image is not recovery. Such a copy is clone
evidence and freezes all live state if discovered.

### 13.6 Deletion limits

Deleting an object key or recovery key can make surviving ciphertext
inaccessible under the stated assumptions. It does not prove removal from
RAM, flash translation layers, snapshots, filesystem journals, controller
caches, old media, recipient devices, or adversarial copies.

The UI describes deletion as local best effort with explicit retained-copy
limits. It never reports cryptographic erasure as physical proof.

## 14. Offline Update Verification

### 14.1 Separation of authority

Release authority is separate from user identity, FOG-PKI authority, node,
relay, storage, backup, recovery, and Composer state authority. Runtime images
contain only public release roots and current trusted metadata, never a
release signing key.

An update distributor, relay, mirror, removable medium, QR label, or package
manager is an untrusted transport. It cannot authorize code.

### 14.2 Update candidate

`FOG-COMPOSER-CANDIDATE-UPDATE-TUF-1` evaluates an exact future TUF revision
and maintained client implementation. The candidate uses distinct threshold
roles for root, targets, snapshot, and timestamp metadata, consistent target
hashes and lengths, version monotonicity, expiry, and sequential root
rotation.

The selected release profile MUST pin:

- exact TUF specification and implementation revisions;
- root, targets, snapshot, timestamp, and delegated-role thresholds;
- key algorithms, key IDs, role separation, and offline-key requirements;
- canonical metadata encoding and absolute size limits;
- trusted-time and maximum-clock-uncertainty behavior;
- target naming, architecture, deployment profile, and compatibility fields;
- installed-version, minimum-version, revocation, and rollback-floor rules;
- root rotation, repository recovery, and emergency response ceremonies.

TUF metadata transport security is not release authenticity. A valid older
but unexpired view is still subject to the Composer's highest accepted
versions, rollback floor, and freeze policy.

### 14.3 Update bundle validation

The maintenance environment:

1. verifies the fixed Composer `UPDATE_IMPORT` framing and streaming limits;
2. starts from the currently trusted release root stored in monotonic state;
3. applies every intermediate root version sequentially with the required old
   and new thresholds;
4. verifies timestamp, snapshot, targets, delegations, versions, expiry,
   hashes, lengths, and consistent-snapshot rules;
5. rejects metadata below any locally trusted version or rollback floor;
6. verifies target architecture, deployment profile, state-schema range,
   boot profile, and hardware requirements;
7. streams each target to inactive storage while hashing and enforcing its
   exact declared length;
8. verifies the complete inactive image and its signed boot and root digest;
9. records a signed-metadata-bound prepared boot transition without opening
   the Composer vault;
10. activates the new boot slot for one bounded trial;
11. lets only the verified target image, after explicit user unlock, validate
    the prepared transition, migrate state if required, commit the installed
    release and rollback floor through Section 9, and mark boot success.

No target is executed, mounted writable, or parsed by its own code before its
owning metadata, hash, and length have been verified.

### 14.4 Trusted time and freeze

Update expiry requires a trusted update-start time with a stated uncertainty.
File modification times, removable-media clocks, relay timestamps, target
timestamps, HTTP headers, and unauthenticated user input are not trusted time.

If time uncertainty prevents expiry validation, the Composer stops update
installation and invokes a separately authenticated time-recovery ceremony.
It does not disable expiry. Highest accepted metadata versions reduce rollback
risk but do not independently prove that a distributor has supplied the
latest release.

### 14.5 A/B image and boot failure

The Portable candidate uses inactive-image installation and a bounded boot
trial. Automatic fallback is permitted only to an image still above the
authenticated rollback floor and not explicitly revoked.

If the new image and the prior image are both unauthorized or incompatible,
the system enters signed recovery media rather than booting an older vulnerable
release. A boot-success marker is not trusted if it can be rolled back without
the profile's monotonic control.

### 14.6 State migration

A release declares the exact source and target vault schema range. Migration:

- runs in a dedicated mode of the verified target image after explicit user
  unlock; the maintenance update verifier never receives vault keys;
- runs offline with network and ordinary import/export disabled;
- opens the old state through the old reviewed reader and writes a separately
  staged new catalog;
- authenticates and validates every source object before transformation;
- rejects unknown-critical object types and counter or size overflow;
- preserves no old live-state copy as a resumable second Composer;
- commits the new schema and release version through Section 9;
- cannot be reversed after external effect or anchored finalization.

If migration fails before finalization, the old still-authorized image and
state remain active. If the anchor or state has advanced but reconciliation
cannot prove the exact prepared migration, recovery is required.

### 14.7 Emergency response

Emergency metadata may revoke a target or raise the minimum release version,
but uses the normal authenticated root and delegated authority rules. There is
no unsigned rescue build, universal operator password, hidden update URL,
network bypass, or local force-install flag.

## 15. PKI, Time, and Monotonic Consumer State

### 15.1 PKI import

The Composer persists the complete trusted PKI consumer state required by
`FOG-PKI` in the same security-critical transaction as any route, profile,
message, or storage work that first depends on it.

It accepts a newer view only after validating:

- network and trust-anchor identity;
- canonical full consensus and independent authority quorum;
- sequential authority-set transitions;
- epoch, validity, freshness, and clock uncertainty;
- archive inclusion and append-only consistency from the stored checkpoint;
- active packet, wire, messaging, storage, entry, cover, and Composer profiles;
- complete current storage manifests and key windows;
- split-view, equivocation, and conflict evidence.

A bundle containing multiple valid conflicting views freezes affected work and
preserves evidence. It does not select the numerically highest view or merge
descriptors.

### 15.2 Offline time

The Composer maintains separate notions of:

- monotonic process time for one boot session;
- authenticated protocol epoch and version progression;
- profile-approved civil time with explicit uncertainty;
- release-metadata update-start time.

An RTC can be a candidate input but is not trusted merely because it is
battery-backed. Clock rollback, implausible jump, uncertainty overflow, or
disagreement with authenticated epoch bounds stops new time-sensitive work.

The UI permits a user to report the clock problem, not to declare an arbitrary
time valid. Exact offline time recovery remains a profile activation gate.

## 16. Native Applications and Safe Rendering

### 16.1 Common application boundary

`fog-drop`, `fog-mailbox`, and `fog-im` are modules inside the Composer trust
domain. They receive authenticated bounded application frames only after
messaging, storage, import, and state commit. They do not parse raw transfer,
KEMSphinx, storage, or ratchet bytes.

Applications cannot select packet geometry, route length, storage replica
count, retry timing, cover class, cryptographic primitive, update channel, or
external renderer.

### 16.2 Initial content profile

The initial content profile supports bounded UTF-8 plain text with canonical
normalization rules and a small fixed set of non-active local presentation
attributes. It rejects invalid UTF-8, control-character abuse, bidirectional
text policy violations, oversized grapheme sequences, unknown critical
fields, and active content.

No content triggers:

- network or filesystem access;
- contact creation or verification change;
- command execution, URL opening, media decoding, font installation, or
  external process launch;
- automatic reply, read receipt, typing indicator, preview, or notification
  containing plaintext outside the unlocked Composer;
- import, update, recovery, profile, or key transition.

### 16.3 Local UI status

The UI distinguishes at least:

- locally queued but not exported;
- exported with unknown relay outcome;
- courier accepted, replica quorum committed, and degraded storage;
- authenticated recipient Composer commit acknowledgment;
- expired or uncertain delivery;
- contact fingerprint verified, unverified, changed, or recovery pending;
- PKI fresh, stale but valid, expired, split, or recovery required;
- vault locally consistent, externally anchored, unanchored, or mismatched;
- installed release verified, update available, revoked, or time-blocked.

It never labels courier acceptance as delivery, replica commit as human read,
encryption as anonymity, networklessness as host integrity, or local hash-chain
verification as complete anti-rollback.

### 16.4 Plaintext lifetime

Plaintext is decrypted only for the active operation or visible bounded view.
Search indexes, caches, undo history, previews, clipboard, recent-file lists,
accessibility bridges, screenshots, and notifications are disabled unless a
later profile explicitly bounds and protects them.

Lock, suspend, inactivity timeout, display detachment, update mode, integrity
failure, anchor failure, or fatal parser fault closes views and erases active
keys and staging memory on a best-effort basis.

## 17. State and Key Lifecycle

| Material | Owner | Persistence | Transition or destruction |
| --- | --- | --- | --- |
| Human unlock secret | user | never stored as plaintext | replace through authenticated keyslot rewrap |
| Unlock KDF output or KEK | Composer unlock transaction | memory only | erase after vault key unwrap or lock |
| Random vault key | one Composer instance | wrapped keyslot plus unlocked memory | rotate by profile; never export or identity-recover |
| Object key epoch | Composer vault | wrapped or derived encrypted state | rotate by object class; retain only for live objects |
| Local state-authentication key | Composer vault | one instance | erase on instance retirement; never use for backup |
| Composer instance ID | Composer vault | lifetime of one active instance | replace on restore or reinitialization; never export |
| State commitment chain | Composer vault | permanent for one instance | preserve until explicit retirement |
| External anchor key or handle | independent anchor domain | profile-specific monotonic lifetime | controlled replacement requires recovery ceremony |
| Import quarantine bytes | sandbox and Composer | one bounded import | delete after commit or rejection |
| Import dedup identifier | Composer vault | maximum bundle replay window | expire by authenticated profile, not input time |
| Export spool ciphertext | export encoder and Composer | bounded transfer or retry window | delete without rewinding protocol state |
| Transfer-pairing key | Composer and local blind relay boundary | local pairing generation | rotate on pairing compromise; never authenticate messages |
| Recovery data key | recovery transaction | package creation or restore only | erase after verified wrap or unwrap |
| Recovery wrapping key | user recovery domain | separate from package ciphertext | rotate by creating and testing a new package |
| Identity root in recovery | encrypted recovery package | explicit identity lifetime | revoke or replace through identity protocol after compromise |
| Live ratchet and capability state | current Composer instance only | encrypted mutable state | freeze on restore, clone, rollback, or compromise |
| Release trust roots | Composer maintenance state | sequential root lifetime | rotate only through authenticated old and new thresholds |
| Installed-release floor | Composer and external anchor where claimed | monotonic installation lifetime | only increase through authenticated metadata |
| Temporary plaintext and message keys | Composer process | one transaction or view | best-effort erase immediately after owning commit or close |

Purpose-separated keys MUST NOT be converted, copied, or relabeled to satisfy a
different row.

## 18. Failure and Recovery States

### 18.1 Minimum vault states

The Composer state machine includes:

- `UNINITIALIZED`: no identity or mutable vault exists;
- `LOCKED`: image verified, vault keys absent from active memory;
- `UNLOCKING`: bounded keyslot and state verification in progress;
- `READY_UNANCHORED`: locally consistent, no complete-rollback claim;
- `READY_ANCHORED`: local and independent anchor state match;
- `IMPORT_STAGED`: one bounded import is parsed but has no effect;
- `EXPORT_PREPARED`: exact export state is durable but not yet released;
- `UPDATE_STAGED`: inactive release verified but not activated;
- `RECOVERY_REQUIRED`: ordinary protocol actions forbidden;
- `CLONE_OR_TAMPER_DETECTED`: local and anchor history conflict;
- `LOCKDOWN`: integrity, runtime, or secret-lifetime policy failed;
- `RETIRED`: no further use of instance keys or live protocol state.

### 18.2 Failure table

| Condition | Required response |
| --- | --- |
| Boot signature or root-image verification failure | stop before vault unlock |
| Vault keyslot authentication failure | generic local failure, no object parsing |
| Object AEAD or canonical encoding failure | quarantine object or vault, no partial use |
| Database integrity or durability uncertainty | lock and enter authenticated recovery |
| Local commitment-chain break | freeze all mutable protocol state |
| External anchor mismatch | `RECOVERY_REQUIRED` or `CLONE_OR_TAMPER_DETECTED` |
| Missing anchor in an anchor-required profile | no export, render, or state advancement |
| Malformed or oversized import | reject complete bundle and delete quarantine |
| One invalid critical bundle record | reject complete bundle |
| Duplicate valid import | idempotent success without repeated effect |
| Export spool partial write | rebuild exact committed bytes or discard partial file |
| PKI split or consistency failure | freeze new network work and preserve evidence |
| Clock uncertainty outside profile | stop time-sensitive PKI and update acceptance |
| Update signature, expiry, hash, length, or version failure | retain verified non-revoked version or stop |
| Migration failure before finalization | keep old still-authorized state and image |
| Migration or anchor ambiguity after advance | recovery required, no downgrade |
| Recovery package failure | no identity import and no detailed oracle |
| Lock, suspend, display loss, or runtime policy failure | erase active keys best effort and stop |

User-visible diagnostics remain local, coarse, and free of attacker-controlled
secret bytes. A failure never opens networking, mounts an internal disk,
enables a general shell, skips verification, accepts an older profile, or
exports an automatic error.

## 19. Resource Limits and Abuse Resistance

Every active Composer profile defines lower limits within the absolute bundle
ceilings for:

- vault objects, object bytes, transaction objects, and staged generations;
- identities, contacts, sessions, prekeys, skipped keys, capabilities, and
  storage streams;
- drafts, messages, fragments, reassembly groups, history, and attachments;
- protocol outbox, inbox, deduplication, ACK, receipt, retry, and tombstone
  state;
- quarantine items, bundle bytes, record count, parser depth, and parse time;
- export spool items, bytes, re-export attempts, and retention;
- PKI objects, consensus views, proof nodes, manifests, conflicts, and history;
- update metadata, targets, stream bytes, staging space, and migration work;
- recovery identities, contacts, labels, package bytes, and attempts;
- Argon2 memory, CPU, lanes, attempts, and concurrent KDF calls;
- UI text bytes, graphemes, lines, rendering time, and notification queue;
- anchor operations, prepared generations, reconciliation attempts, and
  device timeouts;
- memory, file descriptors, processes, threads, temporary files, and disk
  reserve.

Limits are enforced before allocation or expensive cryptography where the
owning format permits. Authenticated contacts remain untrusted for resource
purposes. A valid signature or ciphertext does not authorize unbounded local
storage, rendering, KDF work, or notifications.

Disk-full handling preserves the latest finalized catalog and anchor state.
The Composer does not evict security-critical replay, ratchet, capability,
commitment, or rollback state according to least-recently-used behavior. It
stops new work or applies an authenticated retention policy.

## 20. Logging and Local Observability

The default release logs only coarse boot, lock, integrity, capacity, and
failure-class counters needed to operate the local device. Logs are bounded,
stored inside the encrypted vault or volatile memory, and deleted by a fixed
policy.

The Composer MUST NOT log or export:

- plaintext, drafts, rendered content, contact labels, or fingerprints;
- private keys, unlock material, recovery keys, capabilities, or ratchets;
- message, session, box, receipt, packet, SURB, reply, voucher, or bundle
  identifiers;
- routes, replica selection, entry sets, import timing histories, or per-
  contact activity;
- object ciphertext samples, failed attacker input, decrypted fragments, or
  detailed cryptographic errors;
- filesystem paths containing user identity, hostnames, locale, timezone, or
  device serial numbers;
- state commitments or anchor receipts in a generic support bundle.

There is no automatic telemetry, update check, crash upload, or remote
diagnostic channel. A manually exported diagnostic report uses an explicit
reviewed schema, contains only coarse redacted status selected by the user,
and never includes a raw log or vault object.

## 21. Candidate Implementation Profiles

### 21.1 Linux vault candidate

`FOG-COMPOSER-CANDIDATE-LINUX-VAULT-1` combines:

- an authenticated boot artifact and read-only `dm-verity` root image;
- a dedicated LUKS2 mutable volume with Argon2id keyslots;
- object-level XChaCha20-Poly1305 authenticated encryption;
- one transactional SQLite database with one writer;
- immutable import quarantine and export spool files;
- disabled network stack, swap, hibernation, core dumps, and active-content
  desktop services.

This combination is a review target, not a composed security proof. LUKS2,
dm-verity, AEAD, SQLite, boot firmware, filesystem, storage hardware, and the
Composer transaction protocol have different failure and trust assumptions.

### 21.2 Qubes MicroVM candidate

`FOG-COMPOSER-CANDIDATE-MICROVM-QUBES-1` evaluates:

- a dedicated persistent Composer qube with no NetVM;
- an immutable reviewed template or standalone image measurement;
- one private encrypted state volume unlocked inside the guest;
- exact qrexec policies for bounded import and export services only;
- separate untrusted transfer qubes where physical device support requires
  them;
- explicit denial of file copy, clipboard, URL opening, general command,
  update proxy, audio, camera, block, USB, and arbitrary qrexec services.

qrexec is a host-mediated data channel and the Qubes host remains trusted for
guest confidentiality and integrity. A host-controlled vTPM is not an
independent anchor against that host.

### 21.3 Portable Linux candidate

`FOG-COMPOSER-CANDIDATE-PORTABLE-LINUX-1` reuses the Linux vault profile but
boots a signed read-only image on dedicated offline hardware. It requires
driver removal, internal-disk automount denial, separate RX/TX devices,
physical inspection, and a profile-selected independent monotonic anchor for
any complete-rollback claim.

Secure Boot without a narrowly controlled FOG release root, root-image
verification without an authenticated root digest, or a TPM without a reviewed
state-binding protocol does not satisfy the complete candidate.

### 21.4 Ephemeral container fixture

`FOG-COMPOSER-FIXTURE-EPHEMERAL-CONTAINER-1` evaluates:

- rootless Podman with `network=none` and no published port;
- a read-only container root and bounded tmpfs mounts for `/run`, `/tmp`, and
  runtime state;
- no persistent volume, host filesystem, generic bind mount, application log,
  swap-dependent security claim, or secret-bearing standard output;
- capability removal, no-new-privileges, resource ceilings, core-dump denial,
  and one bounded import and export interface;
- fresh one-shot identity and protocol state that cannot be resumed after
  shutdown.

This candidate can demonstrate functional network absence and ordinary
storage minimization. It cannot demonstrate secure memory erasure, host
protection, physical isolation, durable mailbox behavior, or production
endpoint security.

### 21.5 Activation gates

Before any candidate receives an active numeric profile, FOG MUST freeze and
verify:

1. exact operating system, kernel, bootloader, firmware assumptions, image
   format, and immutable-root construction;
2. exact AEAD, KDF, hash, database, filesystem, and library revisions and
   parameters, plus exact LUKS2 parameters when whole-volume encryption is
   selected;
3. byte-exact vault object, commitment, bundle, record, recovery, and update
   serialization;
4. nonce uniqueness, key-purpose separation, wrapping, rotation, and deletion;
5. database atomicity, sync, power-loss, disk-full, corruption, and backup
   behavior on supported hardware;
6. external-anchor state binding, crash protocol, endurance, reset, clone,
   replacement, and recovery;
7. exact MicroVM device model and qrexec or equivalent policy;
8. exact Portable driver set, mounts, Secure Boot ownership, dm-verity chain,
   and physical transfer direction;
9. exact TUF revision, client, metadata encoding, thresholds, trusted time,
   root rotation, rollback floor, revocation, and offline repository workflow;
10. parser fuzzing, UI rendering, import/export duplication, hostile media,
    migration, recovery, and update fault injection;
11. reproducible or independently verifiable builds, dependency provenance,
    release ceremony, and rollback rehearsal;
12. independent endpoint, cryptographic integration, and implementation
    review before public claims.

## 22. Conformance and Adversarial Tests

Before the local PoC, FOG-COMPOSER requires deterministic positive and
negative tests for:

- image signature, boot argument, root digest, read-only root, and failure
  before vault unlock;
- absence of NICs, network drivers, network syscalls, listeners, proxies, and
  undeclared devices;
- MicroVM clipboard, shared directory, qrexec, device, and guest-agent denial;
- Portable radio, internal-disk mount, foreign-filesystem, and directional
  device denial;
- Ephemeral container network, writable-layer, persistent-volume, bind-mount,
  log, core-dump, restart, and tmpfs-boundary denial;
- keyslot creation, unlock, wrong secret, rewrap, rotation, and partial header
  update;
- object AEAD, associated data, nonce, padding, generation, key epoch, wrong
  instance, corruption, truncation, and unknown-critical fields;
- atomic messaging, storage, PKI, import, export, and application commits;
- every crash point before and after prepared state, anchor advance,
  finalization, export release, and plaintext rendering;
- local-chain rollback, complete coherent rollback, clone, split generation,
  anchor reset, missing anchor, same-generation conflict, and reconciliation;
- exact 128-byte bundle and 48-byte record headers;
- every bundle kind, record allowlist, direction, size, count, padding,
  overlap, gap, duplicate ID, integer overflow, and trailing byte;
- malformed QR, FOG-SX, removable-medium, contact, PKI, reply, recovery, and
  update inputs as data only;
- exact duplicate import and export, repacking, reordered records, replay,
  interrupted transfer, and stale result;
- recovery creation, separate-key handling, test decrypt, restore into a new
  instance, and refusal to resume live state;
- rejection of a copied VM volume, database, portable partition, or full-state
  archive as an active restore;
- TUF thresholds, sequential root rotation, expiry, freeze, rollback,
  fast-forward, mix-and-match, wrong target, hash, length, platform,
  compatibility, and revocation;
- update stream interruption, inactive-image verification, A/B trial,
  unauthorized fallback, migration failure, and recovery media;
- safe text rendering, Unicode edge cases, active content, external resource,
  notification, clipboard, and parser resource abuse;
- disk full, fake-capacity media, I/O error, fsync failure, hot journal,
  corrupted database, low memory, KDF exhaustion, and anchor timeout;
- lock, inactivity, suspend, display loss, update mode, and best-effort key
  erasure;
- absence of prohibited data from logs, crash artifacts, swap, hibernation,
  temporary files, export, and diagnostics.

Testing MUST include parser fuzzing, property tests, transaction fault
injection, simulated power loss, race detection, hostile peripheral fixtures,
resource exhaustion, cross-version migrations, restore exercises, dependency
audits, and byte-identical vectors across independent implementations.

Platform evidence MUST distinguish simulator, VM, dedicated offline hardware,
and production-profile results.

## 23. Threat and Architecture Traceability

| Requirement | Primary controls |
| --- | --- |
| `ARC-002` | no NIC, no socket service, bounded transfer only, conformance network tests |
| `ARC-004` | local vault, messaging, KEMSphinx, storage, and Noise keys remain separate |
| `ARC-005` | full PKI verification and monotonic consensus state before route construction |
| `ARC-006` | common opaque bundle and packet classes across native applications |
| `ARC-007` | explicit vault, object, transfer, backup, anchor, release, and protocol key ownership |
| `ARC-008` | exact headers, absolute parser ceilings, object and transaction bounds |
| `ARC-009` | fail closed on image, state, anchor, import, PKI, update, and recovery uncertainty |
| `IF-01` | committed opaque export only, sealed spool, no stable Composer signature |
| `IF-02` | hostile quarantine, complete parsing, owning inner authentication, atomic import |
| `IF-12` | threshold release metadata, target verification, inactive image, rollback floor |
| `TM-PKI-02` | persisted consensus and checkpoint monotonic state, split freeze, external anchor where claimed |
| `TM-ENDPOINT-01` | MicroVM and Portable profiles, immutable image, encrypted vault, no network or active content |
| `TM-ENDPOINT-02` | separate bounded binary directions, sandboxed decoder, no archive or filesystem import |
| `TM-ENDPOINT-03` | separate recovery hierarchy, identity-only default, no stale live-state resume or file-copy multi-device |
| `TM-APP-01` | authenticated commit before bounded plain-text rendering, no automatic actions |
| `TM-OPS-01` | no telemetry or secret-bearing log, crash, support, or export artifacts |
| `TM-SUPPLY-01` | separate release authority, TUF candidate, immutable verified images, provenance gates |
| `TM-CRYPTO-01` | random data keys, memory-hard unlock, purpose-separated object keys, lifecycle table |
| `TM-CRYPTO-02` | immutable profile registry, no runtime crypto selection or downgrade |
| `TM-AVAIL-01` | absolute limits, staged streaming, bounded KDF and parser work, disk reserve and safe stop |

## 24. Claims Deliberately Withheld

FOG-COMPOSER does not yet establish:

- protection of plaintext or keys from a compromised unlocked Composer;
- protection of a MicroVM from its malicious host or hypervisor;
- protection of an Ephemeral container from its host or shared kernel;
- detection of a complete coherent rollback without an independent anchor;
- safe binding or endurance of a concrete TPM, secure element, or token;
- secure deletion from every RAM, flash, snapshot, backup, or physical copy;
- a final operating system, database, AEAD, KDF, filesystem, or library;
- correctness of firmware, Secure Boot implementation, peripheral, DMA, or
  hardware randomness;
- that network driver removal eliminates every physical or side channel;
- that TUF alone proves the distributor supplied the latest update while the
  Composer is isolated;
- transparent recovery of forward-secret sessions, pending delivery, or live
  capability streams;
- safe multi-device state, cloud recovery, or server-held recovery secrets;
- production security from a Qubes fixture, portable USB prototype, or local
  fault test.

## 25. Open Dependencies

The structural Composer contract is fixed, but these dependencies remain open
before an active profile or implementation:

- exact supported Linux distribution, kernel, boot, immutable-image,
  filesystem, and hardware profiles;
- exact Argon2id, AEAD, KDF, database, and secure-memory selections, plus an
  exact LUKS2 selection for profiles that enable whole-volume encryption;
- exact rootless container runtime, no-network configuration, tmpfs limits,
  logging behavior, host swap and hibernation assumptions, and bounded
  import/export adapters for the Ephemeral candidate;
- byte-exact vault, state commitment, bundle records, recovery envelope, and
  update metadata integration;
- an independent monotonic-anchor construction with proven state binding,
  crash reconciliation, endurance, replacement, and recovery;
- a trusted offline-time and clock-uncertainty recovery ceremony;
- exact Qubes version, qube type, template lifecycle, qrexec services, and
  host policy for the MicroVM candidate;
- exact Secure Boot root ownership, firmware requirements, driver manifest,
  RX/TX devices, and media policy for Portable;
- the full `FOG-UPDATE` repository, signing, provenance, reproducible-build,
  revocation, and recovery contract;
- activation of one byte-exact numeric `FOG-SX` joint profile after its fixed
  structural frame, object, padding, parser, no-ACK, and physical-direction
  contract passes FEC, implementation, license and IPR, resource, vector,
  hardware, and independent review;
- entry capsule and return-rendezvous bundles needed for complete relay
  import/export;
- identity compromise, revocation, contact recovery UX, and fresh-session
  transition vectors;
- future native attachment, full-text search, group, and multi-device
  protocols.

No implementation convenience may silently resolve these dependencies.

## 26. Primary References

- FOG threat model: `FOG-THREAT-MODEL.md`
- FOG architecture: `FOG-ARCHITECTURE.md`
- FOG public key infrastructure: `FOG-PKI.md`
- FOG wire protocol: `FOG-WIRE.md`
- FOG Sphinx profile framework: `FOG-SPHINX-PROFILES.md`
- FOG messaging protocol: `FOG-MESSAGING.md`
- FOG storage protocol: `FOG-STORAGE.md`
- FOG simplex transfer protocol: `FOG-SX.md`
- Qubes OS qrexec architecture:
  <https://doc.qubes-os.org/en/r4.3/developer/services/qrexec.html>
- Qubes OS device handling:
  <https://doc.qubes-os.org/en/latest/user/how-to-guides/how-to-use-devices.html>
- Linux kernel `dm-verity` documentation:
  <https://docs.kernel.org/admin-guide/device-mapper/verity.html>
- cryptsetup and LUKS2 specification resources:
  <https://gitlab.com/cryptsetup/cryptsetup/-/wikis/Specification>
- RFC 9106, Argon2 Memory-Hard Function:
  <https://www.rfc-editor.org/rfc/rfc9106.html>
- libsodium XChaCha20-Poly1305 documentation:
  <https://doc.libsodium.org/secret-key_cryptography/aead/chacha20-poly1305/xchacha20-poly1305_construction>
- SQLite atomic commit documentation:
  <https://sqlite.org/atomiccommit.html>
- SQLite database-corruption and backup guidance:
  <https://sqlite.org/howtocorrupt.html>
- Trusted Computing Group TPM 2.0 Library specification:
  <https://trustedcomputinggroup.org/resource/tpm-library-specification/>
- The Update Framework specification and security model:
  <https://theupdateframework.io/spec/>
  <https://theupdateframework.io/docs/security/>

These references supply maintained formats, mechanisms, and failure lessons.
They do not make the combined FOG endpoint secure by inheritance. FOG still
requires exact profiles, integration analysis, hardware measurement, vectors,
fault testing, build provenance, update and recovery rehearsal, and
independent review.