Composition: Foxbook ↔ Concordia ↔ Sanctuary typed-reference schema

[cloakmaster]

Composition: Foxbook ↔ Concordia ↔ Sanctuary typed-reference schema

Context

A2A Discussion #1803 opened a three-layer framing that's now concrete enough to spec a cross-implementation surface against:

1. Handle verification — Foxbook (RFC 9162-shaped public transparency log)
2. Evidence composition — Concordia v0.4.0 (#1734-shape attestation envelopes)
3. Verdict policy — Sanctuary Castle Architecture v1.2 (receiving-gateway policy enforcement)

@eriknewton proposed the natural integration surface: a Concordia attestation envelope carries a typed reference to a Foxbook leaf as supporting evidence, so a Sanctuary-wrapped agent can cryptographically anchor "caller identity was Foxbook-verified at leaf N" inside the negotiation receipt.

This thread is the open spec venue for that typed reference. Public so it's reviewable, archival, and other identity-layer / evidence-layer / verdict-layer implementations can compose against the same shape.

Strawman: typed-reference schema v1.0

{
  "tl_url": "https://transparency.foxbook.dev",
  "leaf_index": 42,
  "tl_leaf_canonical_hash": "<64-char lowercase hex SHA-256>",
  "verified_signing_key_hex": "<64-char lowercase hex Ed25519 public key>",

  "sth_at_verify_time": {
    "tree_size": 100,
    "root_hash": "<64-char lowercase hex>",
    "timestamp": "<ISO-8601>"
  },
  "sth_signature": "<compact-JWS EdDSA, three base64url segments>"
}

Field-by-field

Field	Type	Required	Purpose
tl_url	URL	yes	Base URL of the transparency log this leaf lives in. Verifier resolves ${tl_url}/inclusion/${leaf_index} and ${tl_url}/root to re-verify.
leaf_index	integer ≥ 0	yes	Position of the leaf in the log. Combined with tl_url, uniquely identifies the leaf.
tl_leaf_canonical_hash	64-char hex	yes	SHA-256 of canonical-bytes of the leaf (per Foxbook's ADR 0005, canonicalization via canonical.ts on the raw object). Lets the verifier detect log forks: recompute hash from live leaf, compare.
verified_signing_key_hex	64-char hex	yes	Agent's Ed25519 signing key that was active at verify-time. Surfaced by Foxbook SDK v0.2.0's verifyAgentCard on the verified branch (@foxbook/sdk-claim). The key the verdict-layer uses to verify the AgentCard's JWS signature.
sth_at_verify_time	object	no	The Signed Tree Head the verifier saw at verify-time: {tree_size, root_hash, timestamp}. Anchors temporal context.
sth_signature	compact-JWS	no	EdDSA signature over the canonical bytes of sth_at_verify_time (or equivalent serialization), signed by the log's signing key (public key at ${tl_url}/.well-known/foxbook.json). Lets the verdict-layer authenticate the STH offline without trusting the integrator to have not falsified it.

The optional fields exist for verdict-layer threat models that need offline verification or temporal anchoring. Verdict layers that always re-fetch from the live log can ignore them.

Versioning

Schema version 1.0. Evolution rules mirror Foxbook's ADR 0004:

• Additive within v1.x: new optional fields are OK, no schema-version bump.
• Breaking changes (remove field, rename field, tighten existing constraint): require 2.0 with a migration window.
• The version number lives in the typed-reference's containing context (e.g., the Concordia envelope's schema version), not as a separate version field inside the typed reference itself — keeps the wire shape minimal.

(Open question 4 below revisits this.)

Negative-path scenarios

The interesting edge cases happen between assert-time (when Foxbook returned verified and Concordia embedded the typed reference) and consume-time (when Sanctuary processes the receipt). Three concrete scenarios:

1. Leaf revoked between assert-time and consume-time

• T1: Foxbook verifies; returns verified at leaf N, key K.
• T2 (later): the agent's recovery key is used to revoke the claim. A revocation leaf is appended at index M > N. Per Foxbook's ADR 0004 addendum-1, revocation is atomic: claim row deleted, leaf appended in the same transaction.
• T3: Sanctuary processes the receipt.

What's "correct" depends on Sanctuary's policy:

• Strict freshness policy: Sanctuary re-fetches ${tl_url}/api/v1/claim/by-handle/... at T3. If revoked, reject — even though the receipt was valid at T1.
• Point-in-time anchor policy: Sanctuary accepts T1 verification as historical fact. Useful for audit-trail use cases where "what did we know when" matters more than "what's true now."
• Hybrid policy (the typical case): Sanctuary checks both. Recent receipts (T3 - T1 < threshold) accepted as fresh-enough; older receipts trigger re-verification.

The typed-reference should be rich enough to support all three policies. sth_at_verify_time enables temporal-anchor checks. tl_url + leaf_index enable live re-verification. Verdict-layer policy is out of scope for the typed-reference itself.

2. Signing-key rotation between assert-time and consume-time

Symmetric to revocation: a signing-key-registration leaf (per Foxbook's tl-leaf v1.2 / ADR 0004 addendum-3) is appended between T1 and T3. The receipt's verified_signing_key_hex is now superseded.

Same three policy options apply. The typed-reference's role is to be honest about what was true at T1, not to make policy decisions.

3. Log fork

A malicious or buggy log serves different bytes for the same leaf_index at different times. Concordia embedded the typed reference based on bytes seen at T1; Sanctuary fetches the live leaf at T3 and gets different bytes.

tl_leaf_canonical_hash is the load-bearing field here. Sanctuary recomputes the hash from the live leaf's canonical bytes; if it doesn't match, the log has forked (or the integrator falsified the typed reference). Either way, reject.

This is the case where the typed reference's integrity guarantees are stronger than re-fetching alone — a verifier with the typed reference can detect a fork class that a re-fetch-only verifier can't.

Open questions for the thread

1. Container shape: should the typed reference live inside the CTEF envelope (reusing Concordia's existing schema) or as a peer field at the envelope's top level? Both are viable; CTEF-inside is the more composable shape.

2. Promote optional fields? sth_at_verify_time + sth_signature are optional in this strawman because they add receipt size + verifier complexity. Should they be promoted to required for stronger default semantics? If yes, optional becomes "deprecated optional" for v1.0 backward compat then required in v2.0.

3. verified_signing_key_hex semantics: does the typed reference assert "the AgentCard was JWS-signed with this key" or only "this key is the active signing key per Foxbook at verify-time"? The latter is weaker and more honest — it shifts AgentCard-signature verification to Sanctuary. The former is stronger but requires Concordia to actually verify the AgentCard's JWS at verify-time.

4. In-band version field? The strawman puts version in the containing envelope's context. An alternative is "_version": "1.0" inside the typed reference itself. Wire-size cost: ~14 bytes per receipt. Forward-compat benefit: future Concordia/Sanctuary impls that don't share envelope context still know how to parse.

5. Multi-log federation: the schema works for a single tl_url per typed reference. If the future is multi-vendor federated logs, do we need a way to express "verified against these N logs that all agreed"? Probably not for v1.0; can be additive later.

What this is NOT

• Not a feature change to Foxbook. Foxbook's SDK v0.2.0 + tl-leaf v1.2 already expose everything needed; this is a composition spec, not a Foxbook protocol change. Per ADR 0008, Foxbook is in stable mode; this thread documents how the existing surface composes.
• Not a Concordia or Sanctuary feature change in advance of consensus. Anyone implementing this strawman as-is should consider it a draft.
• Not a closed spec. The thread is open; reviewers from any identity-layer, evidence-layer, or verdict-layer implementation are welcome to weigh in.

Next steps

• This thread reaches consensus on the typed-reference shape (v1.0).
• Foxbook lands an ADR (0009) ratifying the agreed shape on the Foxbook side. ADR 0009 is purely descriptive — it documents how Foxbook's existing surface composes; it does not lift the feature freeze in ADR 0008.
• Concordia v0.5.0 (or wherever eriknewton wants it) ships envelope support for the typed reference.
• Sanctuary Castle Architecture v1.3 (similar) adds verdict-policy hooks for typed-reference validation.

Cross-implementation references in any of these directions are welcome and improve the strength of the cross-impl reference cycle. Foxbook's harness aggregator entry lists claim_type_layer: identity for any future implementor wanting to add the same shape.

Engagement

• Threaded comments here are the primary venue.
• hello@foxbook.dev for substantive offline conversations.
• GitHub issues in cloakmaster/foxbook for bugs in Foxbook's existing surface.
• Foxbook is in stable / maintenance mode per ADR 0008; review timing on substantive engagement is days-to-weeks, not minutes.

cc @eriknewton — the thread is yours to shape too.

[eriknewton]

The three-layer framing is the right composition shape. I'll walk through your five open questions one at a time.

Q1, container shape (CTEF-inside vs peer field):

CTEF-inside is the right call. Concordia v0.4.0 already ships the generalized references[] field on the attestation envelope specifically to carry typed references to external evidence (Foxbook leaves, mandate references, others). Nesting the typed reference inside the attestation's references[] entry preserves that composability and makes the receipt shape self-contained, with no external context required to understand what the attestation is anchored to.

Q2, promote sth_at_verify_time + sth_signature to required:

Keep optional in v1.0 and require in v2.0. Letting early integrators ship without the STH-anchor burden lowers the activation energy for v1.0 adoption. Once implementations exist and we have real-world data on the wire-cost vs policy-clarity tradeoff, ratchet to required in v2.0. The optional-deprecated phase you described is the right structural shape.

Q3, verified_signing_key_hex semantics:

Weaker semantic is right. The typed reference carries "this key is the active signing key per Foxbook at verify-time," which is a fact about Foxbook's log state, not a claim about any specific AgentCard signature. Downstream consumers (Concordia, Sanctuary, others) choose whether to re-verify the AgentCard JWS against that key per their own policy. The typed reference stays a clean fact about Foxbook; verification policy stays in the verdict layer where it belongs.

Q4, in-band version field:

In-band wins. Fourteen bytes is negligible at receipt scale, and the forward-compat benefit is real. Future implementations that don't share envelope context, or that read archived receipts from older Concordia versions, need to know which typed-reference schema they're parsing. Recommend _version or typed_reference_version as the field name to signal "this is the outer shape, not an inner protocol version."

Q5, multi-log federation:

Defer to v2.0. The single-tl_url shape is correct for v1.0. When multi-vendor federation becomes real, the typed reference can gain an optional federated_logs field listing the N logs that reached consensus. Additive, doesn't affect v1.0 parsing.

Integration surfaces confirmed:

Concordia v0.4.0 carries the typed reference inside references[] on the attestation envelope. Sanctuary's verdict-policy gate (Castle Layer 3 in v1.2 cooperative MCP; Castle Layer 1 OS-level egress filtering once Phase 1 ships) consumes the typed reference as one input to the operator's policy decision. The shape Concordia carries is the integration surface; Sanctuary consumes downstream.

Composition posture:

Concordia and Sanctuary compose with Foxbook independently. Neither depends on the other, and the composition partnership introduces no new cross-substrate dependencies. Cleanest for future implementors too.

Ready to drill on any of the five. The strawman is solid ground to work from.

[cloakmaster]

@eriknewton — solid pass. Walking through your answers in the same order. Net: I agree with all five positions. Three small refinements + one clarifying question.

Q1 — Container shape: CTEF-inside Concordia's references[]

Agreed. Concordia v0.4.0's existing references[] is the right home — the typed reference becomes a typed entry alongside other external-evidence references the envelope already carries.

Clarifying Q: what's the entry shape inside references[]? My working assumption is something like {type: "foxbook_leaf", value: {tl_url, leaf_index, tl_leaf_canonical_hash, ...}} — a discriminated type tag plus a payload object. If Concordia's existing references[] entries already follow a consistent discriminator pattern, the Foxbook typed reference should fit that pattern verbatim rather than introduce its own. Could you point me at the v0.4.0 envelope schema or paste the references[] entry shape so we lock the wire form before either side commits?

Q2 — Optional v1.0 → required v2.0

Agreed. Optional-deprecated phase in v1.0 + required in v2.0 is the right ratchet.

Refinement: I'd propose v1.0 spec text adds a non-binding "consumer-policy guidance" note — verdict layers wanting offline-verifiable receipts SHOULD prefer typed references with both sth_at_verify_time + sth_signature populated. Soft nudge, not a MUST; signals direction without gating adoption.

Q3 — verified_signing_key_hex semantics: weaker / fact-about-log-state

Agreed, completely.

Refinement: the spec text should make this explicit so future implementors don't drift toward the stronger reading. Proposed phrasing for the field's spec definition:

verified_signing_key_hex is a fact about Foxbook's log state at the moment foxbookVerify returned — specifically, the active signing key registered for this DID. It is not a claim that any specific AgentCard JWS was verified against this key. AgentCard signature verification is the verdict layer's responsibility; the typed reference provides the key bytes the verdict layer needs to do that verification, nothing more.

That phrasing pushes the policy boundary cleanly: typed reference = facts about Foxbook log state; verdict policy = decisions about what those facts mean for a specific receipt.

Q4 — In-band version field

Agreed on in-band. typed_reference_version over _version — when someone debugs a receipt and sees _version: "1.0", they have to know "version of what." typed_reference_version: "1.0" is unambiguous and self-documenting. Wire-cost delta is ~10 bytes vs _version; trivial.

Q5 — Multi-log federation: defer to v2.0

Agreed. Single tl_url for v1.0. When multi-vendor federation becomes a real shape (currently no second canonical Foxbook deployment exists), v2.0 adds optional federated_logs: [{tl_url, leaf_index, tl_leaf_canonical_hash, sth_at_verify_time?, sth_signature?}, ...] — array of typed-ref-like sub-objects. Single-log v1.0 receipts stay parseable in v2.0 readers; v2.0 receipts that use federated_logs are not parseable in v1.0 readers, which is fine because they're a strict superset.

Integration surfaces + composition posture

Confirmed on both. Concordia v0.4.0 references[] carries; Sanctuary Castle Layer 3 (v1.2 cooperative MCP) and Layer 1 (Phase 1 OS-level egress) consume independently. Foxbook stays the canonical-bytes substrate; neither downstream introduces new cross-substrate dependencies. Cleanest shape for future implementors.

Worked example

https://gist.github.com/cloakmaster/0e07c1aed0c7cae61484a01762e6ed9b

Real fixture from leaf #6 of the live Foxbook log + ~80-line reference verifier that depends only on @noble/curves + @noble/hashes — no @foxbook/sdk-claim, no canonicalization library. Protocol-portable to any language with SHA-256 + Ed25519. Negative-path tests included (tamper canonical hash → MISMATCH; tamper tree_size → both merkle_root and sth_signature diverge; omit optional STH fields → graceful skip with explanatory note).

Documents the Q3 weaker-semantic rule explicitly in code: signing-key match is "Foxbook says this is the active key," NOT "AgentCard JWS verified." Verdict-layer composition stays where it belongs.

Ground for the v1.0 shape above. If references[] entry-shape lands different than the {type, value} assumption, the gist updates in-place — the verifier logic is shape-agnostic; only the fixture changes.

Where this leaves the strawman

With your five answers + the three refinements above, the v1.0 schema is concrete enough to ratify on the Foxbook side. Proposed next step:

1. You answer the clarifying Q on references[] entry shape (so we lock the wire form).
2. Either of us drafts the v1.0 schema in final form (single comment, copy-pasteable JSON, with the field-level spec text). I'm happy to do this in this thread.
3. One pass of nits from anyone watching (you, anyone else in identity-layer / evidence-layer / verdict-layer who wants to weigh in).
4. Foxbook ratifies ADR 0009 in-place — strawman replaced with the agreed schema, status under-public-discussion → accepted, Discussion Composition: Foxbook ↔ Concordia ↔ Sanctuary typed-reference schema #73 link cited as the consensus venue.
5. Concordia v0.5+ and Sanctuary Castle v1.3+ ship the typed reference at whatever cadence works on your side; INTEGRATIONS.md Status flips Proposed → Live when each lands.

Three small refinements above are the only outstanding shape decisions on the Foxbook side. Once references[] shape is confirmed, the v1.0 schema is locked.

[eriknewton]

@cloakmaster substrate-mode posture is structurally correct. The trade you're naming (no per-call SLA, weeks-not-days review timing, frozen surface, compounding cross-impl reference cycle) is the right shape for an evidence-layer primitive. We're at the same tempo on our side post-v1.2.

Acknowledging the three commitments shipped:
The tl-leaf v1.2 signing-key-registration shape (recovery-key-signed, same DID, new ed25519 signing key) cleanly resolves the rotation transition window question.

verified_signing_key_hex on the verified branch of verifyAgentCard is the right surface for downstream consumers. One call returning tier plus did plus leafIndex plus signing key removes the second-lookup dance.

Structured reason_code on the unverified branch with key-not-yet-logged as the rotation discriminator is a clean enforcement gate for any consumer that wants to retry after rotation propagates.

On the typed-reference schema, our five answers from earlier in this thread still hold: CTEF-inside (Concordia's references[] is the canonical container for cross-vendor evidence references), optional in v1.0 then require in v2.0 (lower adoption barrier wins), weaker semantic on verification (downstream consumers choose JWS verification per their own policy), in-band version field, defer multi-log federation to v2.0.

What we're queuing to consume the v1.0 strawman after thread consensus lands per ADR 0009:
Concordia: a references[] extension that consumes the typed-reference shape, queued against the v0.5 milestone alongside the existing envelope-level vs attestation-level reconciliation work. Lands as a small spec PR once the schema firms up.

Sanctuary: a Foxbook-by-handle verifier surfaced as a Cooperative MCP capability for compliant agents that want AgentCard claims verified at runtime. Operator policy decides whether to require Foxbook verification or leave it informational; verification semantics stay Foxbook's per the Q3 answer above. Queued as a v1.3+ candidate.

Symmetric integration entry on our side at docs/COMPOSE-WITH-SANCTUARY.md so any third party reaching for the three-layer composition can find both directions of the same story.

Substrate tempo on our side too. Other identity-layer, evidence-layer, and verdict-layer participants are welcome to weigh in here; the cross-impl reference cycle compounds with each one that lands.

Erik

[cloakmaster]

@eriknewton — appreciate the substantive close on the v0.2.0 commitments + the reciprocal substrate-mode positioning. Same tempo on our side too; the cross-impl reference cycle compounding is exactly what ADR 0006 §4 named as the load-bearing structural mechanism, and Concordia + Sanctuary's queue (v0.5 references[] extension; v1.3+ Sanctuary Foxbook-by-handle verifier as Cooperative MCP capability; symmetric docs/COMPOSE-WITH-SANCTUARY.md) is a clean instance of it.

Reading your re-confirmation of the five answers + your concrete forward queue, the typed-reference v1.0 schema is converged from both sides. Calling consensus.

Typed-reference v1.0 — final form

{
  "typed_reference_version": "1.0",
  "tl_url": "https://transparency.foxbook.dev",
  "leaf_index": 42,
  "tl_leaf_canonical_hash": "<64-char lowercase hex>",
  "verified_signing_key_hex": "<64-char lowercase hex>",
  "sth_at_verify_time": {
    "tree_size": 100,
    "root_hash": "<64-char lowercase hex>",
    "timestamp": "<ISO-8601>"
  },
  "sth_signature": "<compact-JWS, 3 base64url segments>"
}

Field spec

• typed_reference_version (string, required). Schema version of this typed reference. Currently "1.0". Evolution per ADR 0004 precedent: additive within v1.x (new optional fields OK, no version bump); breaking changes (remove field, rename field, tighten constraint) require 2.0.

• tl_url (URL, required). Base URL of the transparency log carrying the leaf. Verifiers resolve ${tl_url}/inclusion/${leaf_index} and ${tl_url}/leaf/${leaf_index} against this base.

• leaf_index (integer ≥ 0, required). Position of the leaf in the log. Combined with tl_url, uniquely identifies the leaf.

• tl_leaf_canonical_hash (64-char lowercase hex, required). RFC 9162 leaf hash of the leaf at leaf_index. Lets verifiers detect log forks by recomputing from the live leaf and comparing — a mismatch is a log-integrity violation or a falsified typed reference. Either way: reject.

• verified_signing_key_hex (64-char lowercase hex, required). A fact about Foxbook's log state at the moment foxbookVerify returned — specifically, the active signing key registered for this DID. It is NOT a claim that any specific AgentCard JWS was verified against this key. AgentCard signature verification is the verdict layer's responsibility; the typed reference provides the key bytes the verdict layer needs to do that verification, nothing more. This phrasing is load-bearing: it pins the policy boundary where it belongs (typed reference = facts about Foxbook log state; verdict policy = decisions about what those facts mean for a specific receipt).

• sth_at_verify_time (object, optional). Shape: {tree_size, root_hash, timestamp}. The Signed Tree Head observed at verify-time. Anchors temporal context + enables Merkle-root reconstruction without re-fetching the live /root.

• sth_signature (compact-JWS, optional). EdDSA signature over the STH content. Lets verdict layers authenticate the STH offline without trusting the integrator to have not falsified it. Cross-checks against sth_at_verify_time catch typed-reference falsification at two independent points.

Versioning + optionality rules

• v1.0: sth_at_verify_time + sth_signature are optional. Verdict layers wanting offline-verifiable receipts SHOULD prefer typed references with both populated. Soft directional signal — not a MUST; doesn't gate adoption.
• v2.0: both fields become required. The optional-deprecated phase in v1.0 is the migration path.
• Multi-log federation (multiple tl_urls with consensus): deferred to v2.0 with an additive federated_logs field. v1.0 stays single-log.

Container is Concordia's call

How the typed reference embeds inside Concordia's envelope (references[] entry shape, type-discriminator field name, version-of-version handling at the envelope vs typed-ref layer) is Concordia's spec to define. ADR 0009 ratifies the typed reference itself, container-agnostic. That separation keeps the typed-reference v1.0 portable to any future evidence-layer envelope shape that wants to compose Foxbook-verified identity, not just Concordia v0.5+.

Path to ratification

The Foxbook side ratifies via in-place update of ADR 0009: strawman replaced with the schema above, status under-public-discussion → accepted, this thread cited as the consensus venue. Proposed window: 72h from this comment, unless another identity-layer / evidence-layer / verdict-layer participant weighs in with substantive nits — in which case we work them in, then ratify.

After ratification:

• docs/INTEGRATIONS.md Concordia + Sanctuary entry status flips Proposed → Spec'd
• docs/COMPOSE-WITH-FOXBOOK.md adds a forward link to docs/COMPOSE-WITH-SANCTUARY.md once it's published on your side; happy to do the symmetric link from our side first if that helps unblock the cross-link
• INTEGRATIONS status flips Spec'd → Live when Concordia v0.5 + Sanctuary v1.3 actually ship

If anyone wants the typed reference as a formal JSON Schema artifact (separate from the markdown spec above), happy to add schemas/typed-reference.v1.json to the Foxbook repo as part of the ratification PR. Useful for envelope-side validation; optional for ratification.

Open invitation preserved

The thread stays open. Other identity-layer, evidence-layer, and verdict-layer participants are welcome to weigh in — substantive nits in the 72h window land in the ratified schema; out-of-window comments land as v1.x additions or v2.0 candidates per the evolution rules above.

— Benjamin