Flywheel Connector Protocol (FCP)

Specification note: FCPSpecificationV3.md is the current architectural and conformance target. FCPSpecificationV2.md is retained as historical / legacy-interoperability context. When descriptions conflict, trust V3 for intended semantics and the code for current behavior.

A secure connector protocol and Rust platform for AI agent operations across zones, hosts, and personal device meshes. The workspace ships 42 platform crates under crates/, 177 connector crates under connectors/ (176 production connectors plus one adversarial conformance test crate, connectors/_adversarial/), and a single agent-first CLI (fwc) that classifies every answer by truth source and refuses to fabricate runtime state.

TL;DR

The Problem

AI agents need to act on the real world (read mail, file PRs, send messages, query databases, control hardware), but the prevailing toolchains do this with a shared-memory plugin model, an "API key in a .env file" trust model, and a "prompt told the model not to do that" security model. None of those survive a hostile input from Discord, a compromised laptop, or a misconfigured deploy.

The Solution

FCP is a connector platform where:

• Every connector is a separately-signed sandboxed binary with an embedded manifest declaring its capabilities, sandbox limits, and network constraints.
• Every operation is gated by a capability token with type-state-enforced binding, so an UnboundVerified token does not compile against a function that requires BoundVerified.
• Every request is bound to exactly one zone (a cryptographic namespace with its own symmetric key); cross-zone access requires explicit policy and proof.
• Every connector's outbound network traffic flows through an egress proxy with CIDR deny defaults, SNI enforcement, and secretless credential injection, so the connector binary never sees raw API keys.
• Every operation produces a signed receipt and is recorded on a hash-linked audit chain with monotonic sequence numbers and Hybrid Logical Clock causality, plus an OpenTelemetry OTLP parity exporter.
• Sensitive zones support post-quantum cryptography (X-Wing KEM hybrid HPKE + ML-DSA-65 signatures) and threshold owner keys (FROST) so no single device holds the complete signing material.

Truth Hierarchy

fwc classifies every answer by its source (mesh-backed > host-backed > node-local > offline) rather than collapsing everything into a single fake "live" state.

• Current operational path (V1, host-first): fwc → fcp-host → connector subprocesses over supervised stdio/JSON-RPC. This is what runs in production today.
• Target steady state (V2, mesh-native): personal-device sovereignty, mesh durability, capability-gated execution across your own infrastructure. The mesh infrastructure (gossip, IBLT, XOR filters, symbol-first object distribution, LiveTruthResolver, KnowledgeState taxonomy) is built and tested; the cutover gates are documented in docs/FCP3TransitionScorecard.md.

Three Foundational Axioms

| Axiom | Principle | |-------|-----------| | Universal Fungibility | All durable mesh objects are symbol-addressable: any K' RaptorQ symbols reconstruct the canonical object bytes. Control-plane messages may travel over FCPC streams, but the canonical representation is a content-addressed mesh object. | | Authenticated Mesh | Tailscale is the transport AND the identity layer. Every node has unforgeable WireGuard keys. Zones map to Tailscale ACL tags. | | Explicit Authority | No ambient authority. All capabilities flow from the owner key through cryptographic chains and short-lived, instance-bound capability tokens. |

Why Use FCP?

Status legend:

• PROVEN: backed by direct repository evidence (tests, harnesses, golden vectors).
• LIMITED: functional at the stated scope but narrower than the mature target (e.g. threshold-gated rather than adaptive).
• STEADY-STATE TARGET: architectural target with built infrastructure but not yet operational by default.

| Feature | Status | What It Does | Evidence | |---------|--------|--------------|----------| | Host-First Control Plane | PROVEN | fwc + fcp-host is the proven provisioning boundary. Operators use this path today while mesh-backed truth converges to steady state. | crates/fcp-host/src/{supervisor,enforcement,health}.rs, crates/fcp-conformance/tests/hostinvokeloopconformance.rs, crates/fcp-e2e/tests/capabilityenforcementconcurrente2e.rs | | Truthful Runtime Resolution | PROVEN | fwc resolves runtime mode explicitly and classifies answers as mesh-backed, host-backed, node-local, or offline instead of fabricating "live". | crates/fwc/src/{truth,catalog,readiness}.rs, crates/fwc/tests/{cualintegration,readmestatus_pinning}.rs | | Capability Token Typestate | PROVEN | CapabilityToken<Unverified → UnboundVerified → BoundVerified → ConstraintsEnforced> is compiler-enforced across every connector boundary. LEGACYVERIFYALLOWLIST.len() == 0; forward-only ratchet enforced by conformance test. | crates/fcp-conformance/tests/capabilitytypestateconnectorboundarydja9u.rs, crates/fcp-core/tests/typestatecompilefail.rs | | Capability Tokens (CWT/COSE) | PROVEN | COSE/CWT signing, canonical CBOR, constraints, instance binding, predicate matrix all covered. | crates/fcp-crypto/src/cose.rs, crates/fcp-core/src/capability.rs, crates/fcp-host/tests/capabilitytokentypestate_runtime.rs | | Post-Quantum Zone Keys | PROVEN | ZoneKeyManifest V4 schema with hybrid HPKE-X25519 + X-Wing KEM wrap lists, RustCrypto X-Wing (draft-06) + IETF KAT, ML-DSA-65 FIPS 204 signatures with KAT, hybrid verifier, length-invariant Deserialize, constant-time Eq. | crates/fcp-crypto-pq/, crates/fcp-core/src/zone_keys.rs, mixed V3/V4 mesh migration harness | | Zone Isolation | LIMITED | Core cryptographic namespaces proven; Lean zone-flow lattice proof source pinned; host-side connector RPC requires explicit allowedzones before invoke/introspect/health. | crates/fcp-core/src/{zonekeys,pcs,policy}.rs, lean/Fcp/Zone/Lattice.lean, crates/fcp-host/tests/allowedzonesrequired.rs, crates/fcp-e2e/tests/zoneisolationfull_e2e.rs | | Tamper-Evident Audit + HLC | PROVEN | Hash-linked audit chain with monotonic sequence numbers, quorum-signed checkpoints, Hybrid Logical Clocks, Hierarchical Version Vectors for revocation freshness, and an OTLP parity exporter. | crates/fcp-audit/src/hlc.rs, crates/fcp-mesh/src/revocation/hiervv.rs, crates/fcp-conformance/tests/{hlchiervvconformance,auditotlphlccontract}.rs | | Revocation | PROVEN | First-class revocation objects, exact-membership lookup (no XOR filter in the revocation path), RevocationSeal for check-use atomicity, priority gossip push, zone-wide freshness SLA. | crates/fcp-core/src/revocation.rs, crates/fcp-conformance/tests/revocationtiming.rs, crates/fcp-e2e/tests/revocationcascade_e2e.rs | | Egress Proxy | PROVEN | Connector network access routed through manifest-aware guardrails with CIDR deny defaults and denial audit evidence. | crates/fcp-sandbox/src/egress.rs, crates/fcp-e2e/tests/egressproxye2e.rs | | Secretless Connectors | PROVEN | Egress proxy injects credentials per request through SecretFetchHook; connector binaries pass credentialid references rather than raw bearer material. | crates/fcp-crypto/src/secretfetch.rs, crates/fcp-e2e/tests/secretless{github,slack,gmail}e2e.rs | | Multi-Method Provider Auth | PROVEN | fcp-provider-auth consolidates API key, AWS SigV4 request signing, JWT refresh, OAuth device-code, authorization-code with PKCE, refresh-token, and setup-token; AuthProfile flows through the credential pool layer. | crates/fcp-provider-auth/, host/fwc profile-admin and OAuth login surfaces | | Credential Pooling | PROVEN | Multi-credential per-provider pools with priority, strategy, exhaustion-cooldown, active-lease tracking, LRU, sticky restick, max-use, and a redaction-safe connector-boundary E2E. | crates/fcp-host/src/credentials.rs, crates/fcp-e2e/tests/credentialpoole2e.rs, host admin API routes, audit log | | Multi-Host Singleton Writers (HRW) | PROVEN | Quorum-signed durable leases gossip across nodes; rendezvous hashing picks the holder deterministically; binary launch/flush/invoke fencing prevents split-writer windows; multi-node failover replay harness lands as closeout. | crates/fcp-core/src/lease.rs, crates/fcp-mesh/src/{authority,coordinator,planner}.rs, multi-node failover replay harness | | Threshold Owner Key | PROVEN | FROST ceremony and signing support exist in fcp-bootstrap; not yet the universal operational default. | crates/fcp-bootstrap/src/ceremony.rs, crates/fcp-e2e/tests/thresholdownerkey_e2e.rs | | Threshold Secrets (Shamir) | PROVEN | Shamir secret sharing for device-distributed recovery so raw secret material never lives on one machine. | crates/fcp-core/src/secret.rs, crates/fcp-e2e/tests/thresholdsecretse2e.rs | | Supply Chain Attestations | PROVEN | Registry-side attestation schemas, TUF/cosign verification adapters, host gate proof. Release-distribution proof remains outside this repo. | crates/fcp-registry/src/lib.rs, crates/fcp-e2e/tests/supplychainattestation_e2e.rs | | Offline Access | PROVEN | ObjectPlacementPolicy, repair controllers, cache-while-offline, queued writes, drain-on-restore. | crates/fcp-store/src/offline.rs, crates/fcp-e2e/tests/{offlineaccess,offlinerepair}_e2e.rs | | Mesh-Stored Policy Objects | PROVEN | Zone definitions and policy bundles exist as owner-signed objects with mesh gossip, verification, evaluation, and revocation proof. | crates/fcp-core/src/policy.rs, crates/fcp-e2e/tests/meshpolicyobject_e2e.rs | | Symbol-First Protocol | PROVEN | RaptorQ object-symbol framing, reconstruction, repair machinery, multipath aggregation, offline resilience. | crates/fcp-raptorq/, crates/fcp-e2e/tests/symbolfirstprotocol_e2e.rs, golden vectors | | Browser Real-CDP Control Plane | PROVEN | Rust-owned CDP control-worker, supervised target/session manager, cookie ownership boundary, native launcher/proxy worker, direct-CDP routing, real-browser operation-matrix closeout — mirrors OpenClaw semantics. | connectors/browser/, host browser CDP manager proof | | Voice-Call Multi-Provider Parity | PROVEN | Shared CallAuthToken, SessionStore, replay-cache crate (fcp-voice-call); Twilio, Telnyx, Plivo all flow through the same architectural shape with no-live-credential loopback evidence. | crates/fcp-voice-call/, connectors/{twilio,telnyx,plivo}/, scripts/e2e/voicecallmultiproviderverification.sh | | Manifest Operations Conformance | PROVEN | Every connector with declared operations exposes them via typed [provides.operations.] in manifest.toml; runtime const drift is caught by a conformance scanner. | crates/fcp-conformance/tests/manifestoperations.rs | | Computation Migration | PROVEN | Migrate-and-resume reference proof: CRIU-format checkpoint handoff, lease transfer, replay, byte-equivalent completion. | crates/fcp-kernel/src/computationmigration.rs, crates/fcp-e2e/tests/computationmigration_reference.rs | | Mesh-Native Architecture | STEADY-STATE TARGET | Gossip, IBLT, XOR filters, masked IBLT anti-entropy, and LiveTruthResolver are built and tested. The production fwc → fcp-host → connector subprocess invoke path remains host-first today. Pinned by crates/fwc/tests/readmestatuspinning.rs. | crates/fcp-mesh/, crates/fwc/src/truth.rs |

Audit status: all status labels reconciled as of 2026-05-16. See docs/quarterly/2026-Q2-claims-vs-reality.md for the inaugural quarterly debiasing report.

Design Philosophy

Five principles drive every architectural decision in FCP.

1. Mechanical Enforcement, Not Prompted Compliance

Security is enforced by the type system, the binary boundary, the protocol, or cryptography. Never by a string in a prompt. Telling a model "don't read private email" is trivially bypassed by a hostile message; telling a Rust compiler that gmail.read does not exist in the z:public zone is not. Examples from the codebase:

• Capability-token typestate. CapabilityToken<UnboundVerified> and CapabilityToken<BoundVerified> are distinct types. An operation executor that requires full instance-binding declares fn execute(: CapabilityToken<BoundVerified>, ...). An UnboundVerified token (produced by the gateway, which does not yet know the connector's real InstanceId) does not compile against that signature. Enforced by trybuild tests in crates/fcp-core/tests/typestatecompile_fail.rs.
• Connector-boundary ratchet. crates/fcp-conformance/tests/capabilitytypestateconnectorboundarydja9u.rs checks LEGACYVERIFYALLOWLIST.len() == 0. New connectors must use the typestate path; enforced connectors cannot regress.
• Sealed FcpConnector trait. Third-party crates cannot accidentally subvert the lifecycle by implementing the trait themselves.

2. Default Deny With Explicit Allow

If a capability is not granted, it cannot be invoked. If a zone is not bound, the host refuses to start the subprocess. If allowedzones is empty, connector RPC fails closed before invoke, introspection, or health probes reach connector code. If cidrdeny is malformed, the sandbox rejects the manifest at runtime rather than silently degrading. If a webhook signing secret is empty or shorter than the threshold, the webhook layer refuses to verify. At every boundary, absence of explicit configuration is treated as denial, never as a permissive default.

3. Truthfulness Over Convenience

fwc classifies every answer by its source rather than collapsing runtime state into a fake "live" answer. If the host is unreachable and the operator did not pass --offline, fwc refuses rather than falling back to stale artifact data silently. Offline answers carry provenance markers and stale-data caveats. Placeholder runtime data, guessed simulate support, and local file-edit side channels are bugs, not convenience features.

This is the same reason every operator run produces a replayable evidence bundle (trace.jsonl, summary.json, environment.json, replay.sh): debugging starts from artifacts the system actually wrote, not from a story the operator reconstructed afterwards.

4. Symbol-First Data Model

Durable data is content-addressed and symbol-distributed. Any K' RaptorQ symbols reconstruct the canonical object bytes. There is no "primary copy"; there is only a placement policy and a repair controller that maintains it. This eliminates retransmit coordination, enables multipath aggregation, and turns offline resilience from "did I cache this file" into "do I have K' of the N symbols this object is encoded into."

5. Audit Everything That Has Side Effects

Every operation with external effects produces a signed receipt. Every receipt is appended to a hash-linked audit chain with monotonic sequence numbers and Hybrid Logical Clock attributes. Audit heads are quorum-signed across nodes. Receipts are the primary deduplication primitive: on retry with the same idempotency key, the mesh returns the prior receipt instead of re-executing. The OpenTelemetry OTLP parity exporter re-emits the audit chain as traces/metrics/logs, so external observability systems get the same causal model.

Quick Example

# Install fwc
cargo build -p fwc --bin fwc --release
cp target/release/fwc ~/.local/bin/
Start fcp-host in another terminal
./target/release/fcp-host
Talk to the host (current provisioning path, V1)
fwc --host http://127.0.0.1:8787 list
fwc --host http://127.0.0.1:8787 show github
fwc --host http://127.0.0.1:8787 status github
fwc --host http://127.0.0.1:8787 simulate github issues.create --file payload.json
fwc --host http://127.0.0.1:8787 invoke   github issues.create --file payload.json
See which truth source backs the answer
fwc --host http://127.0.0.1:8787 mesh explain-availability github
Offline mode: artifact-backed data without a running host
fwc list --offline
fwc search "send message" --offline
fwc show github --offline
fwc ops github --offline
fwc schema github issues.create --offline
Compile a natural-language intent into a concrete plan, then materialize it safely
fwc plan "search my Gmail for invoices from last week"
fwc explain
fwc do --approve
Expose connectors to MCP clients
fwc serve-mcp --host http://127.0.0.1:8787 github slack gmail
Audit + history
fwc history --connector github --limit 20
fwc audit tail --zone z:work
fwc supply-chain verify github

Architecture

Current Operator Path (V1, Host-First)

This is the provisioning boundary that runs in production today.

┌─────────────────────────────────────────────────────────────────────────────┐
│                          OPERATOR PATH (V1)                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   Operator / AI Agent                                                       │
│       │                                                                     │
│       ▼                                                                     │
│   ┌─────────────────────────────────────────────────────────────────────┐  │
│   │  fwc (CLI)                                                          │  │
│   │  --host http://127.0.0.1:8787                                       │  │
│   │  Classifies answers: host-backed | node-local | offline             │  │
│   └────────────────────────────┬────────────────────────────────────────┘  │
│                                │  HTTP Admin API                            │
│                                ▼                                            │
│   ┌─────────────────────────────────────────────────────────────────────┐  │
│   │  fcp-host (Supervisor)                                              │  │
│   │  1. Verify capability token (COSE)         8. Append audit + HLC    │  │
│   │  2. Check token expiry (CWT nbf/exp)       9. Emit OTLP span        │  │
│   │  3. Check revocation (O(1) freshness)     10. Issue HRW lease       │  │
│   │  4. Enforce zone policy (allowed_zones)   11. Credential pool lease │  │
│   │  5. Check rate limits (token bucket)      12. Receipt for retries   │  │
│   │  6. Connector lifecycle / health           13. Rollout / canary     │  │
│   │  7. Sandbox configuration                  14. Drift detection      │  │
│   └────────────────────────────┬────────────────────────────────────────┘  │
│                                │  stdio / JSON-RPC                          │
│                                ▼                                            │
│   ┌─────────────┐     ┌─────────────┐     ┌─────────────┐                  │
│   │  Connector  │     │  Connector  │     │  Connector  │                  │
│   │   Gmail     │     │   GitHub    │     │   Slack     │                  │
│   │ (sandboxed) │     │ (sandboxed) │     │ (sandboxed) │                  │
│   └──────┬──────┘     └──────┬──────┘     └──────┬──────┘                  │
│          │                   │                   │                          │
│          │ Egress proxy: CIDR deny + SNI + SPKI + credential injection      │
│          ▼                   ▼                   ▼                          │
│     Gmail API          GitHub API           Slack API                       │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Target Steady State (V2, Mesh-Native)

This is the intended steady-state architecture: every device is a peer in a personal mesh, with symbol-based data distribution and mesh-backed answers as the highest-confidence truth source. The mesh infrastructure is built and tested; the remaining work is production evidence and cutover gating.

┌─────────────────────────────────────────────────────────────────────────────┐
│                          PERSONAL MESH (V2)                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   ┌──────────┐      ┌──────────┐      ┌──────────┐                         │
│   │ Desktop  │◄────►│  Laptop  │◄────►│  Phone   │  ← Tailscale mesh      │
│   │ MeshNode │      │ MeshNode │      │ MeshNode │                         │
│   └────┬─────┘      └────┬─────┘      └────┬─────┘                         │
│        │                 │                 │                                │
│        ▼                 ▼                 ▼                                │
│   ┌─────────────────────────────────────────────────────────────────────┐  │
│   │              SYMBOL DISTRIBUTION (RaptorQ K-of-N)                   │  │
│   │  Object: gmail-inbox-2026-05      K=100 symbols                     │  │
│   │  Desktop: [1,5,12,23,...]  Laptop: [2,8,15,...]  Phone: [3,9,...]   │  │
│   │  Any 100 symbols → full reconstruction; no symbol is "important"    │  │
│   └─────────────────────────────────────────────────────────────────────┘  │
│                                                                             │
│   ┌─────────────────────────────────────────────────────────────────────┐  │
│   │  Gossip + IBLT + XOR-filter set reconciliation                      │  │
│   │  HLC + HierVV for causality and revocation freshness                │  │
│   │  HRW (rendezvous hashing) elects singleton writers                  │  │
│   │  Threshold owner key (FROST) and threshold secrets (Shamir)         │  │
│   │  Post-quantum zone keys (X-Wing KEM + ML-DSA-65, ZoneKeyManifest V4)│  │
│   └─────────────────────────────────────────────────────────────────────┘  │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Core Concepts

Terminology

| Term | Definition | |------|------------| | Symbol | A RaptorQ-encoded fragment; any K' symbols reconstruct the original | | Object | Content-addressed data with ObjectHeader (refs, retention, provenance) | | Zone | A cryptographic namespace with its own symmetric encryption key | | Epoch | A logical time unit; no ordering within, ordering between | | MeshNode | A device participating in the FCP mesh | | Capability | An authorized operation with cryptographic proof; grantobjectids enable mechanical verification | | Role | Named bundle of capabilities (RoleObject) for simplified policy administration | | ResourceObject | Zone-bound handle for external resources (files, repos, APIs) | | Resource Visibility | ResourceObjects carry public/private classification; the host enforces declassification when writing higher-confidentiality data to lower-confidentiality external resources | | Connector | A sandboxed binary that bridges an external service to FCP | | Receipt | Signed proof of operation execution for idempotency | | Revocation | First-class object that invalidates tokens, keys, or devices | | Lease | HRW-elected, quorum-signed authority to act as singleton writer for a connector instance | | HLC / HierVV | Hybrid Logical Clock / Hierarchical Version Vector for audit causality |

Cryptographic Key Hierarchy

FCP uses a structured key hierarchy to prevent cross-purpose key reuse. The hybrid classical + post-quantum stack lives in fcp-crypto (classical) and fcp-crypto-pq (X-Wing KEM, ML-DSA-65).

Owner Key (Ed25519, threshold via FROST)
    │
    ├── sign NodeKeyAttestation     (binds node_id → signing/encryption/issuance keys)
    ├── sign ZoneKeyManifest V3/V4  (distributes zone symmetric keys via HPKE-X25519
    │                                and X-Wing KEM hybrid wrap)
    ├── sign DeviceEnrollment       (admits new nodes)
    └── sign RevocationObject       (invalidates any of the above)
Per-Node Keys:     Node Signing Key     (Ed25519)   → signs frames, gossip, receipts, audit heads     Node Encryption Key  (X25519)    → receives HPKE-sealed zone keys     Node Issuance Key    (Ed25519)   → mints capability tokens (separately revocable)     Optional: Node ML-DSA-65 Key     → post-quantum signing (hybrid alongside Ed25519)
Per-Zone Keys:     Zone Encryption Key (ChaCha20-Poly1305)         │         ├── HKDF("FCP3-ZONE-KEY" ‖ zone_id) → zone subkey         ├── HKDF(zonekey ‖ senderinstance_id) → per-sender subkey (reboot-safe)         └── Per-symbol nonce: frame_seq ‖ ESI (deterministic, no coordination)
Per-Session Keys (from X25519 ECDH, optional X-Wing KEM hybrid):     Shared secret → HKDF with both nonces         ├── kmaci2r  (initiator → responder MAC key)         ├── kmacr2i  (responder → initiator MAC key)         └── k_ctx      (control-plane AEAD key)

Five distinct cryptographic roles:

| Key | Algorithm | Purpose | |-----|-----------|---------| | Owner Key | Ed25519 (FROST-thresholded) | Root trust; signs attestations, manifests, revocations | | Node Signing Key | Ed25519 | Per-device; signs frames, gossip, receipts | | Node Encryption Key | X25519 (+ optional X-Wing KEM) | Per-device; receives sealed zone keys and secret shares | | Node Issuance Key | Ed25519 | Per-device; mints capability tokens (separately revocable) | | Zone Encryption Key | ChaCha20-Poly1305 | Per-zone symmetric key; AEAD for zone data |

Each node has a NodeKeyAttestation signed by the owner, binding the Tailscale node ID to all three node key types plus their Key IDs (KIDs) for rotation. Issuance keys are separately revocable so token minting can be disabled without affecting other functions.

Security Invariants

These invariants are enforced mechanically:

• Single-Zone Binding. A connector instance binds to exactly one zone for its lifetime.
• Default Deny — if a capability is not explicitly granted to a zone, it cannot be invoked. The host now refuses to start a connector subprocess with an empty allowed_zones set.
• No Cross-Connector Calling — connectors do not call each other; all composition flows through the host.
• Threshold Secret Distribution — secrets use Shamir's Secret Sharing; never complete on any single device.
• Revocation Enforcement — tokens, keys, and operations check revocation before use. Revocation is wired into all 14 stages of the enforcement pipeline (Gemini Lane 3 closed the gap where freshness was checked but is_revoked() was not consulted).
• Auditable Everything — every operation produces a signed receipt and a hash-linked audit event with HLC + HierVV.
• Cryptographic Authority Chain — all authority flows from the owner key through verifiable signature chains.

Zone Architecture

Zones are cryptographic boundaries, not labels. Each zone has its own randomly generated symmetric key, distributed to eligible nodes via owner-signed ZoneKeyManifest (V3 = HPKE-X25519, V4 = hybrid HPKE-X25519 + X-Wing KEM).

z:owner        [Trust: 100]   Direct owner control, most privileged
    │                         Tailscale tag: tag:fcp-owner
    ▼
z:private      [Trust: 80]    Personal data, high sensitivity
    │                         Tailscale tag: tag:fcp-private
    ▼
z:work         [Trust: 60]    Professional context, medium sensitivity
    │                         Tailscale tag: tag:fcp-work
    ▼
z:community    [Trust: 40]    Trusted external (paired users)
    │                         Tailscale tag: tag:fcp-community
    ▼
z:public       [Trust: 20]    Public/anonymous inputs
                              Tailscale tag: tag:fcp-public
INVARIANTS:   Integrity:        Data flows DOWN freely. UP requires ApprovalToken (elevation).   Confidentiality:  Data flows UP freely. DOWN requires ApprovalToken (declassification).

Provenance and Taint

Every piece of data carries provenance:

| Field | Purpose | |-------|---------| | origin_zone | Where data originated | | current_zone | Updated on every zone crossing | | integrity_label | Numeric integrity level (higher = more trusted source) | | confidentiality_label | Numeric confidentiality level (higher = more sensitive) | | label_adjustments | Proof-carrying label changes (elevation/declassification) with ApprovalToken references | | taint | Compositional flags (PUBLICINPUT, EXTERNALINPUT, PROMPT_SURFACE, …) | | taint_reductions | Proof-carrying reductions via SanitizerReceipt references |

Merge rule: combining data from multiple sources yields MIN(integrity) and MAX(confidentiality). Compromised inputs cannot elevate trust; sensitive outputs cannot be inadvertently exposed.

Taint reduction: specific taints can be cleared when you have a verifiable SanitizerReceipt from a sanitizer capability (URL scanner, malware scanner, schema validator). The receipt is a first-class mesh object.

Defense-in-Depth

Layer 1: Tailscale ACLs       → Network-level isolation
Layer 2: Zone Encryption      → Cryptographic isolation (per-zone symmetric keys)
Layer 3: Policy Objects       → Authority isolation (owner-signed mesh objects)
Layer 4: Capability Signing   → Operation isolation (node-signed COSE/CWT tokens)
Layer 5: Revocation Check     → Continuous validity enforcement (HLC-fresh check)

Symbol Layer (RaptorQ)

All durable data in FCP is symbol-addressable. RaptorQ (RFC 6330) generates a stream of fungible symbols where any K' symbols reconstruct the original. This eliminates retransmit coordination, enables multipath aggregation, and provides natural offline resilience.

| Property | Benefit | |----------|---------| | Fungibility | Any K' symbols reconstruct; no coordination needed | | Multipath | Aggregate bandwidth across all network paths | | Resumable | No bookkeeping; just collect more symbols | | DoS Resistant | Attackers cannot target "important" symbols | | Offline Resilient | Partial availability = partial reconstruction | | Key Rotation Safe | zonekeyid in each symbol enables seamless rotation | | Chunked Objects | Large payloads split via ChunkedObjectManifest for partial retrieval and targeted repair |

Frame Format (FCPS)

┌──────────────────────────────────────────────────────────────────────────┐
│                    FCPS FRAME FORMAT (Symbol-Native)                      │
├──────────────────────────────────────────────────────────────────────────┤
│  Bytes 0-3:     Magic (0x46 0x43 0x50 0x53 = "FCPS")                     │
│  Bytes 4-5:     Version (u16 LE)                                          │
│  Bytes 6-7:     Flags (u16 LE)                                            │
│  Bytes 8-11:    Symbol Count (u32 LE)                                     │
│  Bytes 12-15:   Total Payload Length (u32 LE)                             │
│  Bytes 16-47:   Object ID (32 bytes)                                      │
│  Bytes 48-49:   Symbol Size (u16 LE, default 1024)                        │
│  Bytes 50-57:   Zone Key ID (8 bytes, for rotation)                       │
│  Bytes 58-89:   Zone ID hash (32 bytes, BLAKE3; fixed-size)               │
│  Bytes 90-97:   Epoch ID (u64 LE)                                         │
│  Bytes 98-105:  Sender Instance ID (u64 LE, reboot-safety)                │
│  Bytes 106-113: Frame Seq (u64 LE, per-sender monotonic counter)          │
│  Bytes 114+:    Symbol payloads (encrypted, concatenated)                 │
│                                                                           │
│  Fixed header: 114 bytes                                                  │
│  Integrity: per-symbol AEAD tags + per-frame session MAC                  │
│  Per-symbol nonce: derived as frameseq || esile (deterministic)         │
└──────────────────────────────────────────────────────────────────────────┘

Session Authentication

High-throughput symbol delivery uses per-session authentication, not per-frame signatures:

• Handshake: X25519 ECDH authenticated by attested node signing keys, with per-party nonces for replay protection and crypto-suite negotiation. Optional X-Wing KEM hybrid for post-quantum forward secrecy.
• Session keys: HKDF-derived directional MAC keys (kmaci2r, kmacr2i) from ECDH shared secret, bound to the selected suite and both handshake nonces.
• Per-sender subkeys: Each sender derives a unique subkey via HKDF including senderinstanceid, eliminating cross-sender and cross-reboot nonce collision.
• Per-frame MAC: HMAC-SHA256 or BLAKE3 (negotiated) with per-sender monotonic frame_seq for anti-replay.

┌──────────────────────────────────────────────────────────────────────────┐
│                                MESHNODE                                  │
├──────────────────────────────────────────────────────────────────────────┤
│  ┌────────────────────────────────────────────────────────────────────┐  │
│  │  Tailscale Identity                                                │  │
│  │  - Stable node ID (unforgeable WireGuard keys)                     │  │
│  │  - Signing/encryption/issuance keys with owner attestation         │  │
│  │  - ACL tags for zone mapping                                       │  │
│  │  - Optional PostureAttestation (TPM / Secure Enclave)              │  │
│  └────────────────────────────────────────────────────────────────────┘  │
│  ┌────────────────────────────────────────────────────────────────────┐  │
│  │  Symbol Store                                                      │  │
│  │  - Local symbol storage with retention classes                     │  │
│  │  - Quarantine store for unreferenced objects (bounded)             │  │
│  │  - XOR filters + IBLT + masked-IBLT anti-entropy for gossip        │  │
│  │  - Reachability-based garbage collection                           │  │
│  │  - ObjectPlacementPolicy enforcement for availability SLOs         │  │
│  └────────────────────────────────────────────────────────────────────┘  │
│  ┌────────────────────────────────────────────────────────────────────┐  │
│  │  Capability + Revocation Registry                                  │  │
│  │  - Zone keyrings (deterministic key selection by zonekeyid)      │  │
│  │  - Trust anchors (owner key, attested node keys)                   │  │
│  │  - Monotonic seq numbers for O(1) freshness                        │  │
│  │  - ZoneCheckpoint checkpoints for fast sync                        │  │
│  │  - RevocationPushMessage for priority gossip                       │  │
│  │  - HLC + HierVV freshness frontier (angoc.17.3)                    │  │
│  └────────────────────────────────────────────────────────────────────┘  │
│  ┌────────────────────────────────────────────────────────────────────┐  │
│  │  Connector State Manager                                           │  │
│  │  - Externalized connector state as mesh objects                    │  │
│  │  - Single-writer semantics via HRW + quorum-signed leases          │  │
│  │  - Fencing tokens prevent split-writer windows                     │  │
│  │  - Multi-writer CRDT support (LWW-Map, OR-Set, counters)           │  │
│  │  - Safe failover and migration for stateful connectors             │  │
│  └────────────────────────────────────────────────────────────────────┘  │
│  ┌────────────────────────────────────────────────────────────────────┐  │
│  │  Execution Planner                                                 │  │
│  │  - Device profiles (CPU, GPU, memory, battery)                     │  │
│  │  - Connector availability and version requirements                 │  │
│  │  - Secret reconstruction cost estimation                           │  │
│  │  - Symbol locality scoring, DERP penalty                           │  │
│  └────────────────────────────────────────────────────────────────────┘  │
│  ┌────────────────────────────────────────────────────────────────────┐  │
│  │  Repair Controller                                                 │  │
│  │  - Background symbol coverage evaluation                           │  │
│  │  - Automatic repair toward ObjectPlacementPolicy targets           │  │
│  │  - Rebalancing after device churn or offline periods               │  │
│  │  - Power-aware deferral (battery threshold)                        │  │
│  └────────────────────────────────────────────────────────────────────┘  │
│  ┌────────────────────────────────────────────────────────────────────┐  │
│  │  Egress Proxy                                                      │  │
│  │  - Connector network access via capability-gated IPC               │  │
│  │  - CIDR deny defaults (localhost, private, tailnet ranges)         │  │
│  │  - SNI enforcement, SPKI pinning                                   │  │
│  │  - Secretless credential injection (SecretFetchHook)               │  │
│  └────────────────────────────────────────────────────────────────────┘  │
│  ┌────────────────────────────────────────────────────────────────────┐  │
│  │  Audit Chain                                                       │  │
│  │  - Hash-linked audit events per zone with monotonic seq            │  │
│  │  - Hybrid Logical Clock attributes                                 │  │
│  │  - Quorum-signed audit heads for tamper evidence                   │  │
│  │  - Operation receipts for idempotency                              │  │
│  │  - OpenTelemetry OTLP parity exporter (traces, metrics, logs)      │  │
│  └────────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────────┘

Priority 1: Tailscale Direct (same LAN)
Priority 2: Tailscale Mesh (NAT traversal)
Priority 3: Tailscale DERP Relay         (policy-controlled per zone)
Priority 4: Tailscale Funnel (public)    (low-trust zones only by default)

┌──────────────────────────────────────────────────────────────┐
│                          FCP BINARY                          │
├──────────────────────────────────────────────────────────────┤
│  ┌────────────────────────────────────────────────────────┐  │
│  │  MANIFEST SECTION                                      │  │
│  │  ┌─────────────────┐  ┌─────────────────┐              │  │
│  │  │  Metadata       │  │  Capabilities   │              │  │
│  │  │  - Name         │  │  - Required     │              │  │
│  │  │  - Version      │  │  - Optional     │              │  │
│  │  │  - Author       │  │  - Forbidden    │              │  │
│  │  └─────────────────┘  └─────────────────┘              │  │
│  │  ┌─────────────────┐  ┌─────────────────┐              │  │
│  │  │  Zone Policy    │  │  Sandbox Config │              │  │
│  │  │  - Home zone    │  │  - Memory limit │              │  │
│  │  │  - Allowed      │  │  - CPU limit    │              │  │
│  │  │  - Forbidden    │  │  - FS access    │              │  │
│  │  │  - Tailscale tag│  │  - deny_exec    │              │  │
│  │  └─────────────────┘  └─────────────────┘              │  │
│  │  ┌─────────────────────────────────────────────────┐   │  │
│  │  │  [provides.operations.*]                         │   │  │
│  │  │  Typed input/output schemas per operation        │   │  │
│  │  │  Network constraints per operation               │   │  │
│  │  │  Risk / safety / idempotency classification      │   │  │
│  │  │  AI hints for agent-readable operation docs      │   │  │
│  │  └─────────────────────────────────────────────────┘   │  │
│  └────────────────────────────────────────────────────────┘  │
│  ┌────────────────────────────────────────────────────────┐  │
│  │  CODE SECTION                                          │  │
│  │  - FCP protocol implementation                         │  │
│  │  - Capability negotiation                              │  │
│  │  - External API client                                 │  │
│  │  - State management                                    │  │
│  └────────────────────────────────────────────────────────┘  │
│  ┌────────────────────────────────────────────────────────┐  │
│  │  SIGNATURE SECTION                                     │  │
│  │  - Ed25519 signature over manifest + code              │  │
│  │  - Reproducible build attestation                      │  │
│  │  - Registry provenance chain                           │  │
│  └────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘

ConnectorStateRoot {
  connector_id     → Which connector
  zone_id          → Which zone
  head             → Latest ConnectorStateObject
}
ConnectorStateObject {   prev             → Hash link to previous state   seq              → Monotonic sequence   state_cbor       → Canonical connector-specific state   signature        → Node signature }

Secret: API_KEY
Scheme: Shamir over GF(2^8), k=3, n=5
Distribution:   Desktop: share_1 (wrapped for Desktop's public key)   Laptop:  share_2 (wrapped for Laptop's public key)   Phone:   share_3 (wrapped for Phone's public key)   Tablet:  share_4 (wrapped for Tablet's public key)   Server:  share_5 (wrapped for Server's public key)
To use:   1. Obtain SecretAccessToken (signed by approver)   2. Collect any 3 wrapped shares   3. Unwrap and reconstruct using Shamir   4. Use in memory only   5. Zeroize immediately after use   6. Log audit event
No single device ever has the complete secret. A node cannot decrypt other nodes' shares.

OperationReceipt {
  requestobjectid    → What was requested
  idempotency_key      → For deduplication
  outcomeobjectids   → What was produced
  executed_at          → When
  executed_by          → Which node
  signature            → Node's signing key
}

AuditEvent1 → AuditEvent2 → AuditEvent_3 → ... → AuditHead
  seq=1          seq=2          seq=3              head_seq=N
  HLC=(t,c)      HLC=(t,c)      HLC=(t,c)
     ↑              ↑              ↑                   ↑
  signed         signed         signed         quorum-signed
ZoneCheckpoint {   revhead, revseq      → Revocation chain state   audithead, auditseq  → Audit chain state   hier_vv                → Hierarchical version vector }