feat: add Federation & Cross-Provider epic issue mapping

specs/EPIC-Federation-Cross-Provider-Issues.md

@@ -0,0 +1,192 @@
+# Epic: Federation & Cross-Provider Context Interoperability
+## Repository: Protocol
+## Epic Mapping Document
+
+This document outlines the detailed issues to be created in the issue trackers of the four repositories of the Memact family: `Protocol`, `Contracts`, `Access` (Identity Provider), and `SDK`.
+
+The Federation & Cross-Provider epic introduces the mechanisms required for users to hold context across multiple independent Identity Providers and for those providers to interoperate trustlessly. It defines provider discovery, cross-provider proof portability, federated trust anchoring, and multi-provider context aggregation — all built on top of the ZKP primitives established in RFC-004 and RFC-005.
+
+---
+
+## 1. Protocol Repository (`Protocol`)
+
+### Issue PROTOCOL-301: Draft RFC-006: Federation & Cross-Provider Context Interoperability
+* **Type**: Feature / Specification
+* **Priority**: High
+* **Description**:
+  Create the formal protocol specification (RFC-006) defining how multiple independent Identity Providers (IdPs) discover, authenticate, and interoperate within the Memact federated context ecosystem. The RFC must specify:
+  - **Provider Discovery Protocol**: A well-known endpoint (`/.well-known/memact-federation.json`) that advertises a provider's supported protocol families (CAP, CCP, CRP), ZK circuit registry, verification key URIs, consensus participation status, and federation trust anchors.
+  - **Cross-Provider Proof Portability**: How a ZKP assertion generated by Provider A can be verified and accepted by a Client whose trust root is anchored to Provider B, using a federated verification key resolution chain.
+  - **Federated Trust Anchor Model**: A decentralized trust registry where providers register their signing keys and circuit verification keys, enabling mutual authentication without a centralized certificate authority.
+  - **Multi-Provider Context Aggregation**: How a Client SDK can request assertions spanning claims managed by different providers (e.g., age from Provider A, residency from Provider B) and receive a composite proof bundle.
+  - **Cross-Provider State Root Synchronization**: How consensus blocks from independent provider SMTs are reconciled into a shared federated state commitment using recursive ZK proof composition.
+* **Acceptance Criteria**:
+  * RFC-006 markdown document is merged in `specs/`.
+  * Fully specifies the provider discovery document schema and well-known endpoint semantics.
+  * Describes the federated verification key resolution chain with cryptographic binding.
+  * Covers cross-provider conflict resolution when claims from different IdPs contradict.
+  * Includes sequence diagrams for multi-provider authorization flows.
+
+### Issue PROTOCOL-302: Define JSON Schema for Provider Federation Manifest
+* **Type**: Feature / Schema Definition
+* **Priority**: High
+* **Description**:
+  Author the JSON schema `federation-manifest.schema.json` for the provider discovery document served at `/.well-known/memact-federation.json`. The schema must validate the structure advertising a provider's identity, supported protocols, circuit capabilities, verification key endpoints, federation peers, and trust anchor commitments.
+* **Acceptance Criteria**:
+  * JSON schema file created in `schemas/federation-manifest.schema.json`.
+  * Required fields include `provider_id`, `provider_name`, `supported_protocols` (array of CAP/CCP/CRP entries), `circuit_registry` (mapping circuit IDs to verification key URIs), `federation_trust_anchor` (public key and signature), `consensus_endpoint`, and `peers` (list of known federated provider URIs).
+  * Pattern-matched hex fields for trust anchor public keys and signatures.
+  * Strict `additionalProperties: false` enforcement.
+
+### Issue PROTOCOL-303: Define JSON Schema for Cross-Provider Proof Bundle
+* **Type**: Feature / Schema Definition
+* **Priority**: High
+* **Description**:
+  Author the JSON schema `cross-provider-proof-bundle.schema.json` defining the structure for aggregated proof bundles returned when a client requests assertions spanning multiple providers. The bundle must contain individual provider assertions, a composite binding proof, and the federation chain metadata linking each provider's verification keys.
+* **Acceptance Criteria**:
+  * JSON schema file created in `schemas/cross-provider-proof-bundle.schema.json`.
+  * Required fields include `bundle_id`, `timestamp`, `assertions` (array of provider-scoped `cap_zkp_assertion` objects each tagged with `provider_id` and `provider_trust_anchor`), `binding_proof` (a Groth16 proof binding all individual assertions to a single nonce), and `federation_chain` (ordered list of trust anchor references).
+  * Each assertion entry must conform to the structure defined in `zkp-response.schema.json` with additional federation metadata fields.
+
+### Issue PROTOCOL-304: Define Conformance Checklist for Federated CAP Providers
+* **Type**: Task / Conformance
+* **Priority**: Medium
+* **Description**:
+  Create a conformance checklist document `conformance/cap-federation.md` defining the requirements that an Identity Provider must satisfy to participate in the Memact federation network. This extends the existing `cap-zkp.md` checklist with federation-specific requirements.
+* **Acceptance Criteria**:
+  * Conformance markdown file created in `conformance/cap-federation.md`.
+  * Covers: discovery endpoint availability, federation manifest schema compliance, trust anchor key rotation procedures, cross-provider proof acceptance rules, peer synchronization obligations, and circuit compatibility requirements.
+  * Each requirement is expressed as a checkable item with MUST/SHOULD/MAY RFC 2119 language.
+
+---
+
+## 2. Contracts Repository (`Contracts`)
+
+### Issue CONTRACTS-401: Implement Cross-Provider Proof Binding Circuit
+* **Type**: Feature
+* **Priority**: Critical (Blocker for multi-provider verification)
+* **Description**:
+  Write a ZK circuit (Circom or Halo2) that accepts $N$ individual Groth16 proof verification results (from potentially different providers using different circuits) and produces a single composite binding proof. The circuit must verify that:
+  1. All individual proofs share the same client `nonce` (preventing mix-and-match replay).
+  2. Each proof's `verification_key_hash` is linked to a registered trust anchor in the federation registry.
+  3. The composite output commits to the ordered set of assertion results.
+* **Acceptance Criteria**:
+  * Recursive or aggregation circuit compiles and generates valid proofs for $N \leq 8$ individual assertions.
+  * Unit tests verify rejection when nonces differ across assertions.
+  * Unit tests verify rejection when an unregistered verification key is supplied.
+
+### Issue CONTRACTS-402: Implement Federation Trust Anchor Verification Library
+* **Type**: Feature
+* **Priority**: High
+* **Description**:
+  Implement a verification utility module that validates a provider's federation trust anchor. Given a provider's manifest document, the library must verify the self-signed trust anchor signature, validate the provider's circuit registry entries against known verification keys, and confirm the provider's public key is registered in the federated trust root (an on-chain or off-chain Merkle commitment).
+* **Acceptance Criteria**:
+  * Provide functions: `verifyTrustAnchor(manifest, federationRoot): Promise<boolean>`.
+  * Provide functions: `resolveFederatedVerificationKey(circuitId, providerId, federationRoot): Promise<VerificationKey>`.
+  * Add unit tests covering valid anchors, expired anchors, and tampered manifests.
+
+### Issue CONTRACTS-403: Implement Federated State Root Reconciliation Circuit
+* **Type**: Feature
+* **Priority**: High
+* **Description**:
+  Write a ZK circuit that reconciles state roots from multiple independent provider SMTs into a unified federated state commitment. The circuit accepts $M$ provider state roots (each backed by a valid consensus block proof from their respective chains) and computes a Poseidon hash commitment over the ordered set of roots, producing a single `federated_state_root` with a proof of correct aggregation.
+* **Acceptance Criteria**:
+  * Circuit compiles for $M \leq 16$ provider roots.
+  * Includes verification that each input state root is backed by a valid batch proof from the corresponding provider's consensus engine.
+  * Unit tests verify that modifying any single provider root invalidates the federated commitment proof.
+
+---
+
+## 3. Access Repository (Reference IdP / Federation Node: `Access`)
+
+### Issue ACCESS-501: Implement Federation Discovery Endpoint
+* **Type**: Feature
+* **Priority**: High
+* **Description**:
+  Add a `/.well-known/memact-federation.json` endpoint to the IdP that serves the provider's federation manifest. The manifest must be dynamically generated from the provider's current configuration, reflecting the active circuit registry, verification key URIs, federation peers, and the provider's trust anchor signature.
+* **Acceptance Criteria**:
+  * Endpoint returns a valid JSON document conforming to `federation-manifest.schema.json`.
+  * Response includes correct `Content-Type: application/json` and CORS headers (`Access-Control-Allow-Origin: *`).
+  * Trust anchor signature is regenerated when the provider's signing key rotates.
+  * Integration test verifies schema validation of the served document.
+
+### Issue ACCESS-502: Implement Federated Peer Registry & Synchronization
+* **Type**: Feature
+* **Priority**: High
+* **Description**:
+  Build a peer management subsystem that discovers, registers, and maintains connections to other federated IdP nodes. The system must periodically fetch peer manifests, verify their trust anchors against the federation root, cache peer verification keys, and detect stale or revoked peers.
+* **Acceptance Criteria**:
+  * Peer registry stores and updates federation manifests for all known peers.
+  * Background synchronization job runs on a configurable interval (default: 5 minutes).
+  * Peers with invalid or expired trust anchors are flagged and excluded from cross-provider operations.
+  * API endpoint `/federation/peers` returns the current peer list with health status.
+
+### Issue ACCESS-503: Implement Cross-Provider Proof Acceptance Pipeline
+* **Type**: Feature
+* **Priority**: High
+* **Description**:
+  Extend the IdP's token verification pipeline to accept and validate ZKP assertions originating from federated peer providers. When a client presents a `cap_zkp_assertion` whose `verification_key_uri` points to a peer provider, the system must resolve the peer's verification key through the federation trust chain, verify the proof, and accept it as a valid assertion if the peer is a trusted federation member.
+* **Acceptance Criteria**:
+  * Cross-provider proofs are verified using the peer's cached verification key.
+  * Verification falls back to live fetching from `verification_key_uri` if the key is not cached.
+  * Proofs from unregistered or revoked peers are rejected with error `untrusted_federation_provider`.
+  * Audit log records cross-provider verification events including the originating `provider_id`.
+
+### Issue ACCESS-504: Implement Multi-Provider Aggregation Coordinator
+* **Type**: Feature
+* **Priority**: Medium
+* **Description**:
+  Build a coordination service that handles client requests requiring assertions from multiple providers. The coordinator must fan out authorization requests to the appropriate peer IdPs, collect individual ZKP assertions, invoke the cross-provider proof binding circuit (CONTRACTS-401) to generate the composite binding proof, and return the aggregated proof bundle to the client.
+* **Acceptance Criteria**:
+  * Coordinator exposes endpoint `/authorize/federated` accepting multi-provider `zkp_request` payloads with a `providers` array.
+  * Individual peer authorization requests are dispatched in parallel with timeout handling.
+  * The response contains a valid `cross-provider-proof-bundle` conforming to the schema.
+  * Partial failures (e.g., one provider is unreachable) are reported with per-provider error details.
+
+---
+
+## 4. Client SDK Repository (`SDK`)
+
+### Issue SDK-601: Implement Federation Provider Discovery Client
+* **Type**: Feature
+* **Priority**: High
+* **Description**:
+  Add SDK utilities to discover and cache federated provider capabilities. The client must fetch the `/.well-known/memact-federation.json` manifest from a given provider URI, validate it against the schema, verify the trust anchor signature, and cache the provider's circuit registry and verification key URIs for subsequent proof verification operations.
+* **Acceptance Criteria**:
+  * Expose function `discoverProvider(providerUri): Promise<FederationManifest>`.
+  * Expose function `listProviderCircuits(providerUri): Promise<CircuitEntry[]>`.
+  * Manifest is cached locally with configurable TTL (default: 15 minutes).
+  * Invalid or tampered manifests throw `InvalidFederationManifestError`.
+
+### Issue SDK-602: Implement Multi-Provider Authorization Request Builder
+* **Type**: Feature
+* **Priority**: High
+* **Description**:
+  Extend the CAP SDK Authorization Request builder to support multi-provider assertion requests. The builder must accept assertion constraints tagged with target provider identifiers, generate a shared cryptographic `nonce` bound across all providers, and serialize the request into the federated authorization format dispatched to the aggregation coordinator.
+* **Acceptance Criteria**:
+  * Add builder functions like `.addProviderAssertion(providerId, claim, operator, value)` for chaining multiple provider-specific constraints.
+  * A single high-entropy `nonce` is generated and bound to all assertions in the request.
+  * The builder serializes into a valid `/authorize/federated` request payload.
+  * Session storage records the nonce and the expected provider list for verification.
+
+### Issue SDK-603: Implement Cross-Provider Proof Bundle Verifier
+* **Type**: Feature
+* **Priority**: High
+* **Description**:
+  Implement client-side verification of cross-provider proof bundles. The verifier must validate the composite binding proof, individually verify each provider's assertion proof using the appropriate federated verification key, confirm all assertions share the expected session nonce, and verify the federation chain linking each provider to a trusted root.
+* **Acceptance Criteria**:
+  * Expose function `verifyProofBundle(bundle, sessionNonce, trustedRoots): Promise<BundleVerificationResult>`.
+  * The result includes per-assertion verification status (`valid`, `invalid`, `provider_untrusted`).
+  * Verification fails if the binding proof is invalid, any individual proof fails, or the nonce does not match.
+  * Federation chain validation ensures each provider's trust anchor is present in the client's `trustedRoots` set.
+
+### Issue SDK-604: Implement Provider Trust Root Manager
+* **Type**: Feature
+* **Priority**: Medium
+* **Description**:
+  Build a local trust root manager in the SDK that maintains the set of federation trust anchors the client application considers authoritative. The manager must support adding, removing, and rotating trust roots, and provide the trust root set to the proof bundle verifier for federation chain validation.
+* **Acceptance Criteria**:
+  * Expose functions `addTrustRoot(anchor)`, `removeTrustRoot(anchorId)`, and `getTrustRoots(): TrustAnchor[]`.
+  * Trust roots are persisted in client-side storage (localStorage / secure storage).
+  * Rotation support: when a provider's trust anchor key changes, the manager accepts the new key only if the rotation is signed by the previous key (key continuity).
+  * Default initialization includes the Memact reference provider trust anchor.