ARCHITECTURE

Q-Trust Plane — Quantum-Safe Zero-Trust Control Plane for Hybrid Web2/Web3 Infrastructure
Document: Architecture (Reduced but complete)
Version: v1.0
Scope: Core services, data flows, trust boundaries, persistence, security posture, multichain anchoring, agents.

0. Architecture at a Glance

Q-Trust Plane is a cryptographic governance control plane that issues ephemeral, single-use capability grants after deterministic policy evaluation, then captures cryptographic evidence and anchors integrity on-chain via Merkle roots.

High-level flow

1. Subject (CI/human/bot) presents identity + context + attestations
2. Policy engine evaluates QPL deterministically
3. Grant issuer returns short-lived, context-bound grant
4. Agent executes action, produces evidence
5. Evidence ledger chains + signs events
6. Merkle roots anchored on-chain via AuditAnchor contract
7. External auditors verify inclusion proofs independently

1. System Model (Control Plane vs Execution Plane)

1.1 Control Plane (Q-Trust Core)

Responsible for:

• identity and attestation verification
• deterministic policy evaluation
• grant issuance (hybrid signatures)
• evidence intake and validation
• evidence chaining
• Merkle batching and anchoring
• audit proof serving

1.2 Execution Plane (Agents / PEPs)

Responsible for:

• collecting execution context
• requesting authorization
• enforcing grant requirements
• executing target actions
• emitting evidence with required fields

2. Component Overview

flowchart TB
  subgraph CP[Control Plane]
    API[API Gateway]
    ID[Identity Verifier]
    AT[Attestation Verifier]
    PE[Policy Engine (QPL)]
    GI[Grant Issuer]
    EL[Evidence Ledger]
    MB[Merkle Batcher]
    AN[On-chain Anchorer]
    AP[Audit Proof API]
  end

  subgraph EP[Execution Plane]
    A1[CI Agent]
    A2[Terraform Agent]
    A3[K8s Admission Agent]
    A4[Web3 Agent]
    A5[Bridge/Oracle Operator Agent]
    A6[MLOps Agent]
  end

  subgraph EXT[External Systems]
    CI[GitHub/GitLab OIDC]
    REG[Artifact Registry]
    K8S[Kubernetes Clusters]
    TF[Terraform / State]
    CH[(EVM/Polkadot/Cosmos...)]
    AA[(AuditAnchor Contract)]
  end

  CI --> API
  API --> ID --> PE
  API --> AT --> PE
  PE --> GI
  GI --> API

  EP -->|Authz Request| API
  EP -->|Evidence Submit| API
  API --> EL --> MB --> AN --> AA

  AP -->|Proofs| EXT

3. Trust Boundaries and Security Posture

3.1 Trust boundaries

• Untrusted: agents running in CI runners, user workstations, cluster nodes
• Semi-trusted: enterprise identity providers (OIDC issuers), artifact registries
• Trusted: Q-Trust control plane, keys in vault/HSM/TEE, on-chain anchor contract (integrity only)

3.2 Security posture

• Fail-closed for critical actions: no grant → no execution
• Default deny at policy layer
• Deny-wins policy resolution
• Short TTL and one-time-use grants
• Context binding prevents token replay in different jobs/environments
• Evidence is hash-chained and hybrid-signed; integrity anchored on-chain.

4. Data Model (Canonical Objects)

4.1 Authorization Request (AuthzRequest)

Canonical request fields (conceptual):

• subject:

  • issuer, claims (repo, workflow, actor, job_id), roles
  • workload binding (runner id / agent id / cluster id)

• action: string

• resource: object (type, env, chain, identifiers)

• context: object (git metadata, pipeline metadata, time, runtime)

• attestations: object (SLSA, SBOM digests, approvals, signatures)

4.2 Grant (Capability Token)

A grant includes:

• grant_id (UUIDv7 + nonce)
• subject_fp (hash of canonical subject claims + binding)
• action, resource
• context_bindings (commit SHA, artifact digest, job id, agent id, chain id)
• policy_hash, policy_set_hash
• obligations + constraints
• nbf, exp
• signatures: classic + PQC

4.3 Evidence Event

Includes:

• request_digest, grant_digest, policy_hash
• execution outputs (tx hash, bytecode hash, plan digest, etc.)
• prev_event_hash (hash chain)
• signatures (classic + PQC)
• merkle leaf hash commitment
• epoch metadata (for anchoring)

5. End-to-End Flows

5.1 Authorization flow (Agent → Core)

sequenceDiagram
  participant Agent
  participant API as Q-Trust API
  participant ID as Identity Verifier
  participant AT as Attestation Verifier
  participant PE as Policy Engine
  participant GI as Grant Issuer

  Agent->>API: POST /authorize (OIDC token + context + attestations)
  API->>ID: verify identity + produce Subject FP
  API->>AT: verify attestations (SBOM/SLSA/approvals/signatures)
  API->>PE: evaluate QPL (deny-wins)
  PE-->>API: decision + obligations + ttl
  API->>GI: issue grant (nonce, TTL, bindings)
  GI-->>API: signed grant (classic + PQC)
  API-->>Agent: allow + grant OR deny + reasons

5.2 Execution + Evidence + Anchoring

sequenceDiagram
  participant Agent
  participant API as Q-Trust API
  participant EL as Evidence Ledger
  participant MB as Merkle Batcher
  participant AN as Anchorer
  participant CH as Chain
  participant AA as AuditAnchor

  Agent->>Agent: execute action (requires grant)
  Agent->>API: POST /evidence (grant_id + outputs + required fields)
  API->>EL: validate obligations + append evidence (hash-chained)
  EL-->>API: evidence_id + leaf_hash
  API->>MB: add leaf to current epoch batch
  MB->>AN: publish epoch root when ready
  AN->>CH: submit tx publishRoot(epoch, root, metaHash)
  CH->>AA: store root
  AN-->>API: txHash + epoch root
  API-->>Agent: ack + anchor receipt (epoch, root, txHash)

6. Core Service Decomposition (Modules)

6.1 API Gateway

Responsibilities:

• endpoint routing (/authorize, /evidence, /audit/proof)
• request normalization (canonicalization)
• rate limiting, tenant isolation
• input validation and size limits (DoS defense)

Key properties:

• no policy logic
• strict schema validation
• structured audit logs (operational)

6.2 Identity Verifier

Responsibilities:

• validate OIDC (issuer allowlist, audience, expiry)

• fetch & cache JWKS

• compute canonical Subject Fingerprint

• enforce anti-replay controls:

  • nonce checks (when provided)
  • token age threshold
  • jti replay store (optional, enterprise)

Outputs:

• verified subject claims
• subject fingerprint (subject_fp)
• binding hints for policies

6.3 Attestation Verifier

Responsibilities:

• verify SLSA provenance metadata is present and trusted
• verify SBOM digest exists and matches artifact(s)
• verify artifact signatures (cosign/PGP/sigstore)
• verify approvals bundle (signed approvals, group membership)

Outputs:

• normalized attestations object with:

  • present flags
  • digest fields
  • verified booleans
  • issuer metadata

6.4 Policy Engine (QPL)

Responsibilities:

• parse QPL into AST

• type-check + validate references

• canonicalize policy objects

• compute policy hashes

• deterministic evaluation:

  • match → when → deny-wins resolution

• output obligations + constraints + TTL bounds

Deterministic requirements:

• stable ordering for policy evaluation
• stable ordering for sets/maps
• explicit undefined semantics

6.5 Grant Issuer

Responsibilities:

• build canonical grant payload

• inject strict bindings:

  • job id / run id
  • commit sha / tag
  • artifact digest
  • agent identity / runner identity
  • chain id / env

• enforce TTL policy

• enforce single-use constraints

• sign grants (hybrid):

  • classic: Ed25519 or secp256k1
  • PQC: Dilithium/Falcon (implementation-dependent)

• persist consumed grant index

6.6 Evidence Ledger

Responsibilities:

• receive evidence submissions

• validate obligations:

  • required fields
  • evidence formats
  • cross-check with grant bindings

• append to an evidence log with:

  • prev_event_hash chaining
  • domain-separated leaf hashing

• sign evidence records (hybrid)

• emit leaf hashes to batcher

6.7 Merkle Batcher

Responsibilities:

• maintain epoch windows (e.g., 60 seconds)

• build Merkle trees with deterministic rules:

  • fixed hash functions
  • explicit left/right ordering by index

• produce root and proofs

• persist proofs for evidence ids

6.8 On-Chain Anchorer

Responsibilities:

• submit root to chain via AuditAnchor.publishRoot

• manage transaction nonces & retries safely (idempotent design)

• track tx receipts and confirmations

• record anchor receipts per epoch:

  • chain id, tx hash, root, metaHash

6.9 Audit Proof API

Responsibilities:

• serve external verifiers:

  • leaf hash + proof path + root + epoch + tx hash + chain id

• provide minimal disclosure:

  • never leak sensitive context; only commitments/proofs

• support independent verification workflows

7. Persistence & Storage

7.1 Required state

• Policy Store

  • QPL sources
  • canonical forms (CPR)
  • policy hashes and versions
  • signatures of policy bundles

• Grant Store

  • issued grants (optional cache)
  • consumed grants index (mandatory)
  • revocation list / quarantine flags (enterprise)

• Evidence Store

  • evidence records
  • hash chain pointers
  • leaf hashes
  • proof data (Merkle paths)
  • anchor receipts (epoch → tx hash)

7.2 Recommended databases

• Evidence: append-optimized store (Postgres + partitioning, or event store)
• Grants: fast key-value store for consumed nonce index (Redis + persistence or RocksDB)
• Policies: Postgres (versioned) + object store for bundles

8. Cryptography (Concrete Choices)

8.1 Hashing (Domain-separated)

• policy_hash = SHA256("QTRUST:POLICY:" || canonical_policy_bytes)
• request_digest = SHA256("QTRUST:REQUEST:" || canonical_request_bytes)
• grant_digest = SHA256("QTRUST:GRANT:" || canonical_grant_bytes)
• evidence_leaf = SHA256("QTRUST:EVIDENCE:" || canonical_evidence_bytes)

8.2 Merkle internal node hashing

Must be fixed and documented. Options:

• EVM-friendly: Keccak256 for internal nodes
• Cross-platform: SHA256 everywhere

Rule: Off-chain builder must match on-chain verifier rules exactly.

8.3 Signatures (Hybrid)

• Classic:

  • Ed25519 (preferred for control plane)
  • secp256k1 (for interoperability)

• PQC:

  • Dilithium or Falcon as co-signature

• Bundles include both signatures, enabling migration.

9. Multi-Chain Architecture

9.1 Chain adapters

Each chain adapter provides:

• chain id normalization
• tx receipt parsing
• contract deployment address extraction
• bytecode/runtime hash extraction
• proxy upgrade event extraction (if applicable)
• bridge/oracle event extraction

9.2 Web3 Agent model

The Web3 Agent:

• requests grants for deploy, upgrade, rotate_signers, etc.

• executes via controlled signer interface (vault signing)

• reports evidence:

  • tx hash
  • addresses
  • bytecode hashes
  • parameter hashes
  • chain id

9.3 Evidence fields for Web3 actions

• tx_hash
• chain_id
• contract_address or proxy_address
• bytecode_hash / runtime_code_hash
• old_impl_hash, new_impl_hash (upgrade)
• params_hash (governance changes)
• pipeline_run_url
• change_ticket (enterprise)

10. Agents (Enforcement Points) Architecture

flowchart LR
  subgraph Agents
    CIa[CI Agent]
    TFa[Terraform Agent]
    K8a[K8s Admission Agent]
    W3a[Web3 Agent]
    MLa[MLOps Agent]
  end

  CP[Q-Trust Control Plane]
  Targets[Targets: CI, IaC, K8s, Chains, ML Deploy]

  CIa <--> CP
  TFa <--> CP
  K8a <--> CP
  W3a <--> CP
  MLa <--> CP

  CIa --> Targets
  TFa --> Targets
  K8a --> Targets
  W3a --> Targets
  MLa --> Targets

10.1 Enforcement invariants

• Agents must verify:

  • grant signature(s)
  • grant TTL
  • nonce consumption state
  • required bindings (job id, artifact digest, chain id)

• Agents must refuse execution if:

  • grant is missing/expired/mismatched
  • obligations cannot be satisfied
  • evidence cannot be emitted

11. Failure Modes and Safe Behavior

11.1 Control plane outage

• critical action classes → fail-closed (deny)
• low-risk classes → allowed only if explicitly configured (rare)

11.2 Anchor service outage

• evidence is still chained locally
• grants may be withheld if anchoring cannot proceed (strict mode)
• queue anchoring but mark actions as “unfinalized” until on-chain root is published

11.3 Agent compromise assumptions

Agents are considered potentially compromised:

• the core mitigates via:

  • strict context binding
  • short TTL
  • attestation requirements
  • minimal privileges at targets

12. Policy Distribution & Integrity

12.1 Policy bundles

Policies are shipped as signed bundles:

• canonical policy set
• policy set hash
• signatures (classic + PQC)
• metadata

12.2 Deterministic resolution rules

• deny-wins

• stable ordering:

  • evaluate all matching policies
  • collect matching denies and allows
  • if any deny → deny
  • else allow if any allow
  • else deny

13. Auditability & External Verification

13.1 Proof retrieval

Auditors can request:

• evidence leaf hash
• Merkle proof
• anchored root
• epoch + tx hash
• chain id
• metaHash (tenant/policy set commitments)

13.2 What an auditor can prove

• This evidence event existed at time epoch T
• It was included in the on-chain anchored Merkle root
• The root cannot be altered without chain consensus
• Policy hashes used at that time are immutable commitments

14. Implementation Notes (Rust-first)

14.1 Suggested crates/modules

• qtrust_api (tonic/axum)
• qtrust_identity (OIDC/JWKS validation)
• qtrust_attest (SLSA/SBOM/approvals)
• qtrust_qpl (lexer/parser/AST/type-check)
• qtrust_canon (canonicalization + encoding)
• qtrust_crypto (hashing, signatures, PQC abstraction)
• qtrust_grants (grant issuance + consumption store)
• qtrust_evidence (ledger + leaf hashing)
• qtrust_merkle (tree builder + proofs)
• qtrust_anchor (chain tx manager)
• qtrust_agents_* (agent implementations)

14.2 Canonical encoding

Prefer CBOR for canonical bytes (strict rules), but JSON canonicalization is acceptable if rules are explicit and tested.

15. Minimal “Vertical Slice” (First Milestone)

A production-grade vertical slice includes:

• CI agent authorization for a single action (e.g., web3.contract.deploy)
• QPL policy evaluation
• grant issuance + one-time store
• evidence submission validation
• Merkle root anchoring to AuditAnchor
• audit proof retrieval endpoint

This produces a complete end-to-end proof chain from identity → policy → grant → execution → on-chain anchor.

16. Appendix: Merkle Construction Rules (Required Consistency)

16.1 Leaf hash

leaf = SHA256("QTRUST:EVIDENCE:" || canonical_evidence_bytes)

16.2 Node hash (EVM-friendly default)

node = keccak256(left || right)

16.3 Ordering

• leaves have explicit index order (0..n-1)
• for proof verification, ordering is determined by index bits

Important: the off-chain builder and on-chain verifier MUST match these exact rules.

17. Appendix: AuditAnchor Contract Reference

See contracts/AuditAnchor.sol for:

• epoch root publishing
• optional inclusion verification

Authorization should not be trusted. It should be proven.