magnetar/TEE-INTEGRATION.md

Magnetar --- TEE integration specification

This document is the canonical design + integration story for Magnetar's TEE-attested production surface. It is the load-bearing prose for the strict-PQ chain profile at deployment time.

Decomplecting discipline. The TEE integration is the SIBLING package at luxfi/threshold/protocols/slhdsa-tee --- NOT a new field on the magnetar primitive. Magnetar stays the hash-tree arithmetic; slhdsa-tee composes the trust root + attestation + HSM + approval flow. The two compose by function composition, not by inheritance.

---

1. Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Caller (RPC / EVM precompile)         │
└──────────────┬──────────────────────────────────┬───────────┘
               │ Sign / Sign_Ctx                  │ Sign_TEE / Combine_TEE
               │ (legacy-compat)                  │ (strict-PQ)
               ▼                                  ▼
   ┌───────────────────────┐         ┌──────────────────────────────────┐
   │ magnetar.ValidatorSign│         │ slhdsa-tee.Signer.Sign           │
   │  (per-validator)      │         │  • approval.ApproveIntent         │
   └───────────────────────┘         │  • gate.Issue (nonce+epoch)       │
                                      │  • gate.Release (attest+RIM)     │
   ┌───────────────────────┐         │  • hsm.Provider.GetKey            │
   │ magnetar.Combine      │         │  • magnetar.Sign (inside TEE)    │
   │  (strict-atom Combine)│         │  • zeroize on return              │
   │  (THBS-SE public)     │         └──────────────────────────────────┘
   └───────────────────────┘                       │
                                                   ▼
                                      ┌──────────────────────────────────┐
                                      │ slhdsa-tee.CombinerPool.Combine  │
                                      │  • snapshot members under RLock  │
                                      │  • freshness gate (RotationWindow)│
                                      │  • drive each member's Sign      │
                                      │  • byte-equality across quorum   │
                                      │  • refuse divergence             │
                                      └──────────────────────────────────┘
                                                   │
                                                   ▼
                                      ┌──────────────────────────────────┐
                                      │ cc/attest/{sev,tdx,nras}.go      │
                                      │  • SEV-SNP: PRODUCTION           │
                                      │  • TDX:     STUB (#222 stage 2)  │
                                      │  • NRAS:    STUB (#222 stage 3)  │
                                      └──────────────────────────────────┘

---

2. Component contracts

2.1 Magnetar (this repo)

• Lane: FIPS 205 hash-tree arithmetic (FORS, WOTS+, XMSS, hypertree). Pure functions.
• Inputs (sign path): Params, *PrivateKey, msg, ctx, randomized, rng.
• Output: Signature (FIPS 205 wire bytes).
• No knowledge of: TEE, HSM, approval, gate, attestation. Pure crypto.

2.2 slhdsa-tee.Signer (sibling, luxfi/threshold/protocols/slhdsa-tee)

• Lane: institutional-custody composition. The full attested-release flow that ends in a magnetar.Sign call.
• Inputs: Envelope (attestation, RIM, hardware, TEEPub), jobID, msg, signCtx.
• Output: (wireBytes, *SignReceipt, error).
• Composes: kms.ReleaseGate + hsm.Provider + approval.ApprovalProvider + Config.
• Does NOT compose magnetar itself --- the Signer holds an hsm.Provider reference and unwraps the master seed inside the TEE, then calls magnetar.KeyFromSeed + magnetar.Sign on the unwrapped seed.

2.3 slhdsa-tee.CombinerPool (sibling)

• Lane: t-of-n attested-combiner agreement. The strict-PQ Sign surface.
• Inputs: map[memberName]*Envelope, jobID, msg, signCtx.
• Output: (wireBytes, []*SignReceipt, error) --- one consolidated wire signature byte-equal across the quorum, plus per-member audit signatures.
• Composes: N *slhdsa-tee.Signer instances (one per attested host) + freshness state (LastIssuedAt per member).
• Refusal sentinels: ErrMagnetarNoTEEAttestation, ErrMagnetarStaleAttestation, ErrMagnetarInsufficientQuorum, ErrMagnetarSignatureDivergence.

2.4 cc/attest (sibling, luxfi/mpc/cc/attest)

• Lane: vendor evidence chain validation. Maps from vendor-framed quote bytes to VerifiedReport (Vendor + IssuedAt + ReportData).
• Status: SEV-SNP PRODUCTION; TDX + NRAS STUB.

2.5 hsm.Provider (sibling, luxfi/mpc/pkg/hsm)

• Lane: at-rest seed wrap. Implementations include file (dev), AWS KMS, Azure Key Vault, GCP Cloud KMS.
• Inputs: keyID, ctx.
• Output: wrapped (or AEAD-sealed) bytes.

2.6 kms.ReleaseGate (sibling, luxfi/mpc/pkg/kms)

• Lane: fresh-nonce + policy-bound release decision.
• Issue: returns (nonce, epoch) for a job; must be presented in the subsequent Release call.
• Release: takes ReleaseRequest{JobID, Epoch, Nonce, Attestation, Ctx} and returns a SealedSessionKey if policy + attestation pass.

2.7 approval.ApprovalProvider (sibling, luxfi/mpc/pkg/approval)

• Lane: out-of-band human / programmatic approval of a sign intent. Used when Config.ApprovalRequired = true.
• Inputs: SignIntent (jobID, msg, env-bound).
• Output: ApprovalSignature.

---

3. Profile gate (one function, one place)

The profile gate is the only decomplecting point between the permissionless and strict-PQ paths. The function is magnetarRefuseUnderStrictPQ at luxfi/threshold/pkg/thresholdd/magnetar.go:242. It mirrors:

• RefuseUnderStrictPQ at luxfi/precompile/contract/strict_pq.go (precompile-side gate consulted at the top of every classical precompile's Run).
• RefuseUnderStrictPQ at luxfi/threshold/pkg/thresholdd/ profile.go (per-request chain-ID resolver gate for HTTP 503 mapping).

Discipline

1. ONE function. No duplication across schemes (every PQ primitive that has a strict-PQ-only path consults its own gate function with this exact shape).
2. ONE place. Called at the top of Sign and Sign_Ctx --- the permissionless paths. Never called from Sign_TEE / Combine_TEE (which are the strict-PQ-permitted paths).
3. ONE canonical refusal sentinel. slhdsatee.ErrMagnetarNoTEEAttestation with wire identifier ERR_MAGNETAR_NO_TEE_ATTESTATION.

Cascade on chain profile flip

Operators rotating a chain into strict-PQ MUST follow:

1. Flip the chain profile in luxfi/node ChainConfig.
2. Flip the magnetar dispatcher's profile via magnetarScheme.SetChainSecurityProfile(ProfileStrictPQ).
3. Wire a CombinerPool via SetCombinerPool with at least Threshold attested members already provisioned.

Until all three steps complete, the dispatcher fail-closes: Sign / Sign_Ctx refuse; Combine_TEE refuses with errMagnetarPoolUnwired. No silent fallback.

---

4. Production deployment matrix

Chain profile	Sign primitive	TEE substrate	KnownIssuers map
legacy-compat (default)	per-validator standalone	none	---
legacy-compat (THBS-SE)	public combiner	none	---
legacy-compat (custody opt-in)	Combine_TEE (1-of-1)	SEV-SNP	{"amd.sev.snp": {}}
strict-PQ (production today)	Combine_TEE (t-of-n)	SEV-SNP	{"amd.sev.snp": {}}
strict-PQ (post-#222 stage 2)	Combine_TEE (t-of-n)	SEV-SNP + TDX	{"amd.sev.snp": {}, "intel.tdx": {}}
strict-PQ (post-#222 stage 3)	Combine_TEE (t-of-n)	+ NVIDIA NRAS	{"amd.sev.snp": {}, "intel.tdx": {}, "nvidia.nras.v1": {}}

4.1 NVIDIA Confidential Computing (H100 / H200 / B200) integration

When luxfi/mpc/cc/attest/nras.go ships its production chain validator (NVIDIA Remote Attestation Service, nvtrust SDK integration), the operator's CombinerPool config adds "nvidia.nras.v1": {} to KnownIssuers. Each attested member's slhdsa-tee.Signer runs inside a NVIDIA Confidential Compute VM on H100/H200/B200. The CC VM's measurement (firmware + UEFI + VBS + TEE workload) is chain-validated against NRAS's JWKS. No magnetar-side code change.

For the deployment-time Apple SE / Apple Silicon story, see the v1.4 work item MAGNETAR-APPLE-SE-HSM-V14 --- the Apple SE is layered BELOW the attestation as the hsm.Provider, not as a substitute for the attestation chain.

---

5. Wire compatibility

The TEE integration is completely opaque to verifiers. Any party holding the canonical MAGG-framed group public key validates a TEE-emitted signature via stock magnetar.VerifyBytes(gkBytes, msg, sigBytes) --- no special casing, no TEE-aware verifier, no extra round-trips.

This is the load-bearing property: the TEE substrate provides custody discipline, NOT verification discipline. The on-chain verifier (the EVM precompile at slot 0x012207) does NOT know or care whether the signature came from:

• a per-validator standalone keypair on a commodity host,
• a public combiner on a commodity host running THBS-SE,
• a 1-of-1 attested-host TEE,
• a t-of-n attested-combiner pool spanning SEV-SNP + TDX + NRAS.

All four paths emit byte-identical FIPS 205 wire bytes.

---

6. Stub Go integration code (operator-side reference)

The following is a minimal operator-side reference for wiring a strict-PQ chain into the magnetar dispatcher with NVIDIA Confidential Compute. It is NOT in this repo (the TEE primitives live at luxfi/threshold/protocols/slhdsa-tee); reproduced here for the spec's completeness.

package main

import (
    "context"
    "time"

    "github.com/luxfi/mpc/cc/attest"
    "github.com/luxfi/mpc/pkg/approval"
    "github.com/luxfi/mpc/pkg/hsm"
    "github.com/luxfi/mpc/pkg/kms"
    magnetar "github.com/luxfi/magnetar/ref/go/pkg/magnetar"
    slhdsatee "github.com/luxfi/threshold/protocols/slhdsa-tee"
    "github.com/luxfi/threshold/pkg/thresholdd"
)

// configureMagnetarStrictPQ wires a strict-PQ Magnetar dispatcher
// with a 2-of-3 attested-combiner pool across AMD SEV-SNP +
// NVIDIA NRAS. Called once at operator boot.
func configureMagnetarStrictPQ(
    ctx context.Context,
    dispatcher *thresholdd.MagnetarScheme,
    gate kms.ReleaseGate,
    hsmP hsm.Provider,
    approver approval.ApprovalProvider,
) error {
    // 1. Flip the dispatcher into strict-PQ. From this point on,
    //    Sign / Sign_Ctx refuse with ErrMagnetarNoTEEAttestation.
    //    Only Sign_TEE / Combine_TEE can produce signatures.
    dispatcher.SetChainSecurityProfile(slhdsatee.ProfileStrictPQ)

    // 2. Build the attested-combiner pool. KnownIssuers includes
    //    both AMD SEV-SNP (production today) AND NVIDIA NRAS
    //    (post-#222 stage 3).
    pool, err := slhdsatee.NewCombinerPool(slhdsatee.CombinerPoolConfig{
        Threshold:      2,                  // 2-of-3, no single-host quorum
        RotationWindow: 60 * time.Second,   // 60 blocks of slack
        KnownIssuers: map[string]struct{}{
            "amd.sev.snp":     {},
            "nvidia.nras.v1": {},   // assumes cc/attest/nras.go has shipped
        },
    })
    if err != nil {
        return err
    }

    // 3. Register the three attested signers. Each signer has its
    //    own wrapped seed in its own HSM key slot; the pool drives
    //    each member's full slhdsa-tee.Signer.Sign machinery.
    for _, m := range []struct {
        name  string
        keyID string
        mode  magnetar.Mode
    }{
        {name: "us-east-1a-snp-01", keyID: "magnetar/east/snp01", mode: magnetar.ModeM192s},
        {name: "us-west-2b-snp-02", keyID: "magnetar/west/snp02", mode: magnetar.ModeM192s},
        {name: "eu-central-1a-nras-01", keyID: "magnetar/eu/nras01", mode: magnetar.ModeM192s},
    } {
        signer, err := slhdsatee.New(gate, hsmP, approver, slhdsatee.Config{
            Mode:               m.mode,
            WrappedSeedKeyID:   m.keyID,
            ApprovalRequired:   true,    // require human sign-off per call
            ApproverID:         "operator@example.com",
            RequireSEV:         false,   // accept any KnownIssuer
            RequireTDX:         false,
            RequireNRAS:        false,
        })
        if err != nil {
            return err
        }
        if _, err := pool.AddMember(m.name, signer); err != nil {
            return err
        }
    }

    // 4. Wire the pool into the dispatcher. From this point on,
    //    Combine_TEE drives the pool; Sign_TEE drives a single
    //    attested host.
    dispatcher.SetCombinerPool(pool)

    // 5. Initial attestation tick. Production deployments would
    //    re-attest every block (~1s); the 60s RotationWindow
    //    absorbs ~60 blocks of control-plane latency before any
    //    sign would refuse.
    for _, name := range []string{
        "us-east-1a-snp-01",
        "us-west-2b-snp-02",
        "eu-central-1a-nras-01",
    } {
        // The operator's control-plane captures fresh attestation
        // evidence from the named TEE and submits it.
        env := captureFreshAttestation(name)  // operator-side hook
        if err := pool.Attest(ctx, name, env); err != nil {
            return err
        }
    }
    return nil
}

// captureFreshAttestation is the operator's control-plane hook.
// For SEV-SNP: capture SNP_GUEST_REQUEST quote via the in-VM agent.
// For TDX:     capture TDREPORT via the in-VM agent.
// For NRAS:    capture NRAS-JWT via nvidia-attest agent + NRAS API.
// Each returns an *slhdsatee.Envelope wrapping the vendor quote.
func captureFreshAttestation(name string) *slhdsatee.Envelope {
    // ... vendor-specific quote capture ...
    return &slhdsatee.Envelope{
        Kind: attest.Kind{
            Vendor:   "amd.sev.snp", // or "nvidia.nras.v1"
            Format:   "snp.v1",      // or "nras.jwt.v1"
        },
        EvidenceBytes: nil, // populate from quote
        RIM:           [32]byte{},   // operator-asserted RIM digest
        Hardware:      [32]byte{},   // hardware fingerprint
        TEEPub:        [32]byte{},   // X25519 TEE pubkey
    }
}

The above is the operator-side wiring; the magnetar reference package itself stays pure.

---

7. Verification end-to-end

Pinned by magnetar_tee_gate_test.go in luxfi/threshold/pkg/thresholdd/:

• TestMagnetarCombine_StrictPQProfile_RequiresTEE --- strict-PQ refuses Sign and Sign_Ctx; permits Combine_TEE only when pool is wired; profile flip is reversible + idempotent.
• TestMagnetarCombine_AttestationVerified_AllowsSign --- end-to-end pool drive against committed AMD Milan SEV-SNP fixture; output verifies under magnetar.VerifyBytes (no caller awareness of the pool's existence).
• TestMagnetarCombine_StaleAttestation_RejectsSign --- members outside rotation window refused; partial re-attestation recovers.
• TestMagnetarCombine_TwoOfThreeAttestedCombiners_MatchSig --- 2-of-3 quorum surfaces signature; 1-of-3 stops.
• TestMagnetarCombine_SignatureDivergence_HardRefusal --- pool refuses byte-divergent quorum output (no silent winner-picking).

All five tests pass under -race against the committed Milan SEV-SNP fixture (pkg/thresholdd/testdata/sev_snp_attestation_milan.bin, sev_snp_vcek_milan.cer) replayed via dispatchKDSReplay().

---

Document metadata

• Name: TEE-INTEGRATION.md
• Date: 2026-06-03
• Pin: Magnetar v1.2 + slhdsa-tee at commit b1c0..f8d