Vord

Architecture Decision Record

0003. Credential and token formats (spec-first)

Date: design phase Status: Accepted

Context

Tokens and credentials are the artifacts Vord's whole scaling thesis rests on. The constitution (ADR-0001 rule 1) requires the common path to be stateless cryptographic verification of these artifacts at the edge, never a core read. They are also the one place "data outlives software" applies to Vord exactly as it does to Wyrd's on-disk format: a relying party or a non-Vord verifier must read a token or credential long after it was issued, and must not depend on Vord's implementation to do so.

This is therefore Vord's one spec-first, normative, versioned artifact — the same posture Wyrd takes for its on-disk format (Wyrd ADR-0002) — and the format choices below are the most expensive in the project to change. Two properties are structural and must be chosen now because they cannot be added later without breaking verifiers: the external token's standard conformance, and whether an internal token supports holder-side attenuation (the macaroon / biscuit property — deriving a weaker token without an issuer round-trip).

Decision

  1. External tokens (the ID / access tokens relying parties consume): JOSE / JWT, OIDC-conformant, signed with EdDSA (Ed25519) as the primary suite and ES256 offered for interop. This is not a free choice — relying parties speak OIDC, so the external surface conforms rather than innovates.

  2. The Troth credential / attestation format: SD-JWT VC (SD-JWT with selective disclosure), the IETF-tracked shape, so a holder presents a signed, offline-verifiable pledge and discloses only the claims a verifier needs.

  3. Attenuable capability tokens for the internal authorization path: the biscuit shape — holder-attenuable, offline-verifiable — is reserved as a specified-but-optional token, not built for v1. Because attenuation is structural, the seat is reserved now (the reserved-seat pattern of Wyrd ADR-0007); adding it later only strengthens locality and never breaks a verifier.

  4. Signing-key custody is a trait from day one. A KeyCustody abstraction backs all signing keys — KMS / HSM in production, an embedded software keystore for the dev profile (the dual-backend pattern of Wyrd ADR-0008). Keys are never inline in config or code. This is foundational in importance even though most of its surface is filled in later.

  5. Versioning. Every token and credential carries its format version; a verifier rejects a version it does not understand rather than guess (the rule of Wyrd's chunk-format spec). A version increment is a strict ecosystem event with updated conformance vectors.

The normative format and its conformance vectors live in Vord's specs/ and are verified in CI, exactly as Wyrd's chunk-format is.

Consequences

  • The external surface is interoperable by construction: any OIDC relying party verifies a Vord token with standard libraries and Vord's JWKS, with no core read — satisfying constitution rule 1 directly.
  • Selective disclosure (SD-JWT VC) means a verifier learns only what it needs — a privacy property that also reduces what edge nodes must carry.
  • Reserving biscuit-attenuation keeps the capability-style authorization future open at zero v1 cost; declining to build it now keeps v1 small.
  • Key custody as a trait keeps the single most security-critical dependency swappable and out of the codebase. Done badly here, nothing else matters, so it is fixed as an abstraction from the first commit.
  • This artifact carries the project's strictest change process. The format is stamped stable only once a second, non-reference verifier or a sustained conformance run validates it — the same bar Wyrd sets before stamping its format v1.