feat(jans-lock-server): Lock Server TRACE Records Creation

## 1. Summary

This design extends Jans Lock Server to collect and verify evidence from Cedarling, Jans Auth Server, and the Attestation Token Service and construct TRACE v0.2 Trust Records.

Lock Server is the system of record and correlation point. It does not invent workload-local facts and does not replace the TEE-bound TRACE signature. It assembles the record, requests a signature from the originating Cedarling sidecar, verifies the result, persists the immutable artifact, and optionally anchors it to a SCITT-compatible transparency service.

## 2. Responsibilities

Lock Server will:

- Ingest signed Cedarling evidence envelopes.
- Ingest Jans Auth Server identity and lifecycle events.
- Validate Attestation Tokens and appraisal references.
- Resolve model and build-provenance metadata.
- Correlate evidence into one execution execution.
- Detect missing, duplicated, conflicting, or stale evidence.
- Construct a schema-valid TRACE v0.2 record.
- Coordinate TEE-bound final-record signing.
- Verify signatures, freshness, revocation, and evidence bindings.
- Store immutable records and supporting artifacts.
- Optionally submit records for transparency anchoring.
- Expose verification, search, export, and audit APIs.

## 3. Non-responsibilities

Lock Server will not:

- Claim direct observation of tool execution.
- Rewrite signed Cedarling evidence.
- Hold the workload's TRACE private key.
- Treat an Auth Server token event as runtime execution proof.
- Treat an Attestation Token alone as a complete TRACE record.
- Treat a registry URL as proof of transparency inclusion.
- Declare regulatory compliance solely from TRACE conformance.

## 4. Architecture

```mermaid
flowchart TD
CS["Cedarling evidence"] --> ING["TRACE ingestion"]
AS["Auth Server events"] --> ING
ATS["ATS appraisal"] --> ING
BUILD["SLSA / model registries"] --> CORR["Evidence correlator"]
ING --> CORR
CORR --> RB["TRACE record builder"]
RB -->|canonical draft| CS
CS -->|TEE signature| RB
RB --> STORE["Immutable evidence store"]
RB --> SCITT["Transparency service"]
STORE --> API["Audit and verification API"]
```

## 5. Evidence inputs

### 5.1 Cedarling evidence

Required:

- Signed evidence envelope.
- Execution, subject, and producer identifiers.
- Policy bundle digest and enforcement mode.
- Transcript hash, count, completeness, and chain tip.
- Data classification.
- Runtime appraisal reference.
- TRACE signing public key and attestation binding.
- Model descriptor hash.

### 5.2 Auth Server evidence

Auth Server publishes signed events for:

- Agent registration and assigned SPIFFE identity.
- Enclave-key enrollment and binding.
- JWT-SVID issuance, audience, expiration, and `cnf.jkt`.
- Client disablement and key revocation.
- Token introspection/status when required.

Example:

```json
{
"event_type": "jwt_svid_issued",
"subject": "spiffe://example.org/agent/3f9c",
"client_id": "3f9c",
"jti": "svid_72a",
"aud": "https://payments.example.com",
"cnf_jkt": "9XKt...",
"iat": 1788887900,
"exp": 1788888500
}
```

### 5.3 ATS evidence

Lock verifies:

- Attestation Token signature and issuer.
- Subject, audience, `cnf`, `iat`, `exp`, and `jti`.
- Platform and measurement claims.
- Verifier identity, appraisal status, policy reference, and timestamp.
- Binding to the TRACE signing key.
- Evidence or appraisal reference required by the selected hardware profile.

### 5.4 Model and build evidence

Lock resolves:

- Signed agent/model manifest.
- Model provider, ID, version, weights digest, and AIBOM URI.
- Application and Cedarling image digests.
- SLSA provenance, builder identity, level, and provenance URI.
- Composite workload digest when the measured unit contains several containers.

Unverified declarations remain labeled as declarations and cannot be upgraded merely because they appear in a signed Cedarling envelope.

## 6. Ingestion API

```http
POST /jans-lock/trace/v1/evidence
Content-Type: application/jose+json
Authorization: DPoP
Idempotency-Key: ev_91d2
```

Successful response:

```json
{
"evidence_id": "ev_91d2",
"evidence_digest": "sha256:...",
"status": "accepted",
"missing_inputs": ["build_provenance"]
}
```

The endpoint enforces size limits, authenticates the producer, verifies the envelope signature, validates schema, and stores the original bytes before extracting indexed fields.

Other ingestion endpoints or topics accept Auth Server and ATS events. All messages use stable event IDs and idempotent processing.

## 7. Identifier and correlation model

Lock Server does not equate an Auth Server session with a TRACE execution. `trace_execution_id` is registered by the first valid signed Cedarling evidence envelope and identifies the evidence boundary for one Trust Record.

Primary correlation keys:

| Key | Purpose |
| --- | --- |
| `trace_execution_id` | Binds one governed execution and its candidate TRACE record. |
| Auth Server `sid` | Optional authentication/SSO correlation; never defines the TRACE boundary. |
| `subject` | Binds workload identity. |
| JWT-SVID `jti` | Connects Auth Server issuance to Cedarling evidence. |
| Attestation Token `jti` | Connects runtime appraisal. |
| `cnf.jkt` | Connects identity and proof key. |
| TRACE signing-key thumbprint | Connects appraisal to record signature. |
| `policy.bundle_hash` | Connects decisions to exact policy. |
| `decision_id` | Connects Cedarling evaluation to transcript event. |
| `call_id` | Connects authorization, execution, and receipt. |
| `tx_id` | Connects distributed business transaction evidence. |

Lock rejects, quarantines, or marks incomplete any execution with conflicting immutable correlation values. It must not merge two `trace_execution_id` values merely because they share an Auth Server `sid`, client ID, JWT-SVID, or business transaction.

## 8. Evidence state machine

```mermaid
stateDiagram-v2
[*] --> Collecting
Collecting --> Ready: required evidence present
Collecting --> Incomplete: deadline reached
Ready --> Signing: draft created
Signing --> Final: TEE signature valid
Signing --> Rejected: signature or binding fails
Final --> Anchored: receipt verified
```

Records are not silently constructed from partial evidence. Operators configure whether incomplete executions are retained as non-TRACE evidence packages or rejected.

## 9. TRACE record mapping

Lock constructs the current TRACE v0.2 schema using:

| TRACE field | Authoritative source |
| --- | --- |
| `eat_profile` | Lock constant: `tag:agentrust-io.com,2026:trace-v0.2` |
| `iat` | Finalization/signing time |
| `subject` | Auth Server identity corroborated by Cedarling |
| `model` | Trusted manifest/model registry |
| `runtime` | ATS appraisal and evidence reference |
| `policy` | Cedarling policy artifact evidence |
| `data_class` | Cedarling execution aggregation |
| `tool_transcript` | Cedarling transcript commitment |
| `delegation` | Verified delegation credential and parent record |
| `origin` | Set when Lock assembles imported or third-party evidence |
| `build_provenance` | SLSA resolver |
| `appraisal` | ATS/verifier result |
| `transparency` | SCITT workflow; absent below Level 2 |
| `cnf` | TEE-bound TRACE record-signing JWK |
| `signature` | Returned by originating sidecar over canonical record |

## 10. Record-building algorithm

1. Load original immutable evidence bytes.
2. Verify every producer signature before parsing claims as trusted.
3. Validate freshness and current revocation status.
4. Resolve Auth Server identity and key binding.
5. Validate ATS appraisal and TRACE-key binding.
6. Validate policy digest consistency across decisions.
7. Validate transcript hash, call count, order, and completeness.
8. Resolve model and build-provenance evidence.
9. Apply record acceptance policy and required conformance level.
10. Construct the TRACE object without `signature`.
11. Validate against the TRACE v0.2 schema.
12. RFC 8785-canonicalize the object.
13. Send canonical bytes and digest to the originating Cedarling sidecar.
14. Receive and verify the TEE-key signature.
15. Add `signature` and revalidate the final object.
16. Persist the exact signed bytes as immutable.
17. Optionally begin transparency anchoring.

Ordinary sorted JSON is not acceptable in place of RFC 8785.

## 11. Signing request protocol

```http
POST /cedarling/trace/executions/{trace_execution_id}/sign
Content-Type: application/json
```

```json
{
"record_digest": "sha256:...",
"canonical_record": "",
"expires_at": 1788888060,
"nonce": "lock-challenge-..."
}
```

Cedarling verifies all fields it originated and signs only if the execution is finalized and unsigned. Lock then verifies the signature against `cnf.jwk` and confirms that the key is bound by the accepted appraisal.

The endpoint must prevent arbitrary signing: one signature per record version, strict schema/profile checks, short request lifetime, Lock identity allowlist, nonce replay protection, and complete field comparison.

## 12. Verification service

Lock exposes:

```http
POST /jans-lock/trace/v1/verify
GET /jans-lock/trace/v1/records/{record_id}
GET /jans-lock/trace/v1/records/{record_id}/verification
```

Verification covers:

- TRACE schema and profile.
- Workload signature.
- Freshness and challenge nonce where required.
- Issuer and workload-key revocation.
- Silicon/vendor trust and appraisal evidence.
- Runtime measurement and RIM acceptance.
- Policy digest and enforcement mode.
- Transcript commitment and completeness.
- SLSA provenance at configured depth.
- Delegation-chain integrity.
- Transparency receipt and checkpoint for Level 2.

The response distinguishes `valid`, `invalid`, `unverified`, `unavailable`, and `incomplete`. Absence of evidence must not be reported as success.

## 13. Storage model

Store separately:

- Original evidence envelopes.
- Auth Server lifecycle events.
- Attestation Tokens and appraisal references.
- Tool transcripts or encrypted transcript references.
- SLSA and model evidence.
- Canonical unsigned record bytes.
- Final signed TRACE record.
- Transparency receipt and inclusion proof.
- Verification Outcome Statements.

The signed record is immutable. Enrichment, verification results, revocation state, and receipts are versioned related objects rather than mutations to the signed artifact.

Suggested indexed fields include subject, execution, record digest, time, platform, policy digest, data class, model ID, builder, appraisal status, conformance level, capability ID, and transaction ID.

## 14. Transparency anchoring

Level 2 requires more than a registry URI. Lock must:

- Submit the correct committed bytes to a SCITT-compatible service.
- Retain the signed receipt and inclusion proof.
- Validate the proof against an independently trusted checkpoint.
- Associate receipt, log ID, tree size, and checkpoint with the record.
- Reverify inclusion periodically where policy requires it.

Because the TRACE anchor workflow is evolving, Level 2 should be delivered only after Lock implements the published anchor profile and passes its conformance suite.

## 15. Record acceptance policy

Lock needs an operator policy defining:

- Required TRACE level by capability or risk tier.
- Trusted Cedarling producers and Auth Server issuers.
- Trusted ATS issuers and verifier identities.
- Accepted TEE platforms and measurements.
- Maximum evidence and record age.
- Accepted signing algorithms.
- Required transcript completeness.
- Minimum SLSA level and provenance depth.
- Accepted data-classification vocabulary.
- Required transparency logs.
- Revocation and dependency-unavailability behavior.

This policy is separate from the Cedar authorization policy recorded inside TRACE.

## 16. Failure and conflict behavior

| Condition | Result |
| --- | --- |
| Duplicate evidence ID, identical digest | Idempotent success. |
| Duplicate evidence ID, different digest | Reject and alert. |
| Subject or key mismatch | Quarantine execution. |
| Policy digest changes mid-execution | Require execution split or reject. |
| Transcript gap | Mark incomplete; do not claim completeness. |
| Attestation expired before signing | Re-attest or reject Level 1 construction. |
| Signing sidecar unavailable | Keep draft pending until deadline. |
| Workload signature invalid | Reject. |
| Revocation service unavailable | Fail closed when current status is required. |
| Transparency service unavailable | Retain Level 1 record; do not claim Level 2. |

## 17. Security requirements

- Preserve original signed evidence bytes.
- Authenticate every producer and enforce tenant isolation.
- Verify signatures before trusting extracted indexes.
- Prevent cross-execution and cross-tenant correlation attacks.
- Apply URL allowlists and size limits when resolving external artifacts.
- Never trust a public key merely because it appears inside the record.
- Require independent issuer, verifier, builder, and log trust configuration.
- Keep record construction deterministic and reproducible.
- Prevent Lock from substituting fields in a sidecar signing request.
- Encrypt sensitive transcripts and apply retention controls.
- Audit all evidence rejection, override, reprocessing, and export operations.

## 18. Observability

- `lock_trace_evidence_ingested_total{type,result}`
- `lock_trace_sessions_total{state}`
- `lock_trace_correlation_conflicts_total{field}`
- `lock_trace_records_built_total{level,result}`
- `lock_trace_signing_latency_seconds`
- `lock_trace_verification_total{outcome}`
- `lock_trace_anchor_total{log,result}`
- `lock_trace_incomplete_sessions`
- `lock_trace_oldest_pending_seconds`

All services propagate `trace_execution_id`, `evidence_id`, `record_id`, `decision_id`, `call_id`, and `tx_id` through OpenTelemetry baggage or explicitly protected fields.

## 19. Implementation phases

### Phase 1: Evidence collection and Level 0 records

- Cedarling/Auth Server ingestion.
- Envelope and schema validation.
- Correlation engine.
- Model/build declaration storage.
- TRACE record construction and software-evidence verification.
- Immutable record storage and audit API.

### Phase 2: Level 1 hardware evidence

- ATS ingestion and appraisal validation.
- TEE-key binding verification.
- Two-phase sidecar signing.
- Revocation and RIM checks.
- Hardware conformance tests.

### Phase 3: Level 2 and advanced correlation

- SCITT submission and inclusion verification.
- Verification Outcome Statements.
- Delegation DAGs and cross-agent correlation.
- External execution receipts.
- Auditor exports and compliance reporting.

## 20. Acceptance criteria

- Lock ingests each evidence type idempotently and preserves original bytes.
- Correlation rejects conflicting identities, keys, policies, and executions.
- Constructed records validate against TRACE v0.2 schema.
- RFC 8785 canonical bytes are reproducible across implementations.
- Final signature verifies against a TEE-bound key.
- Lock cannot alter Cedarling-originated fields without signing failure.
- Incomplete or unavailable evidence is reported honestly.
- Records, receipts, and verification results have independent version histories.
- Level claims are made only after the corresponding conformance suite passes.

## 21. Key design decision

Lock Server creates the TRACE record, but the measured Cedarling workload signs it. This preserves centralized correlation and lifecycle management without allowing a central collector to fabricate workload-local execution evidence.