Innsigle Reference ADR-001: Signing algorithm and payload canonicalization

Generated reference: edit sources under docs/helix/, then npm run site:build.

Generated from HELIX docs. Source: docs/helix/02-design/adrs/ADR-001-signing-and-canonicalization.md. Edit the source, not this file or site/ HTML.
Source frontmatter
ddx:
  id: innsigle.adr.001
  type: adr
  links:
    - target: innsigle.design.claim-system
      kind: informed_by
    - target: innsigle.design.attestation-prior-art
      kind: informed_by
    - target: innsigle.prd
      kind: informed_by
status: accepted
activity: 02-design
created: 2026-07-22

ADR-001: Signing algorithm and payload canonicalization

DateStatusDecidersRelatedConfidence
2026-07-22AcceptedOperatorPRD FR-9–12; claim-system.mdHigh

Context

AspectDescription
ProblemClaim attestations need a frozen crypto suite and deterministic bytes to sign so independent verifiers agree
Current Stateclaim-system.md proposed Ed25519 + SHA-256 + simple JSON envelope without a decision record
RequirementsOffline verify; local long-lived house keys; no mandatory Sigstore/OIDC in v1
Decision DriversSimplicity for craft makers; wide library support; alignment with in-toto/DSSE later without blocking v1

Decision

We will use Ed25519 signatures over the SHA-256 digest of a canonical JSON claim payload, carried in a simple Innsigle attestation envelope. Content subjects use SHA-256 digests of the bytes the operator designates as canonical for that subject.

Key Points: Ed25519 for issuer keys | SHA-256 for content and payload digests | RFC 8785-style JCS canonicalization for JSON payloads | OpenPGP packets and DSSE/in-toto export deferred

Alternatives

OptionProsConsEvaluation
OpenPGP packets + cleartext/detached sigWoT tooling existsHeavy UX; variable implementationsRejected for v1
Sigstore keyless onlyNo long-lived keysOIDC dependency; not house craft defaultRejected as sole path; optional later
ECDSA P-256Common in web PKILarger; no advantage for usRejected
Ed25519 + SHA-256 + JCSSmall keys; deterministic; simpleNeed careful JSON rulesSelected
Embed C2PA as only formatIndustry media pathSocial strip; media-firstRejected as sole path

Consequences

TypeImpact
PositiveImplementable with sodium/WebCrypto/libsodium; clear verify steps; no CA required
NegativeNot natively cosign-compatible until export path; must document JCS carefully
NeutralType URI host can change without changing crypto

Risks

RiskProbImpactMitigation
Canonicalization bugs cause false invalidMHGolden test vectors in repo; Contract examples
HTML page hashing ambiguityMHContract: hash exact file bytes operator passes; no silent HTML rewrite in v1

Validation

Success MetricReview Trigger
Independent verify of golden attestation succeeds on two runtimesAny change to alg or canonicalization
Mutated content fails closedSoftening of fail-closed behavior

Supersession

  • Supersedes: None
  • Superseded by: None

Concern Impact

  • Practice: Strengthens key-custody and crypto testing practices; no slot change.
  • Update concerns overrides only if key storage path is standardized later.

References

  • docs/helix/02-design/claim-system.md
  • docs/helix/02-design/attestation-prior-art.md
  • RFC 8785 JSON Canonicalization Scheme (JCS)
  • PRD FR-9–12
Innsigle seal: model-primary by Innsigle (build key)

Signature covers the markdown source of this page, not these HTML bytes. This render quotes that seal.

Composition
model-primary
Issuer
Innsigle innsigle
Signing key
ed25519:050bf4d0361a96aa3b6baa3fc2ffd0cb (build key)
Signed source
docs/website/content/generated/artifacts/adrs/adr-001-signing-and-canonicalization.md
Signed
2026-09-30T20:48:46Z
Content digest
sha256:6f5de99c…2d5eec50

Endorsed by the human key for seal recognition (ADR-003).

Raw attestation JSON
{
  "payload": {
    "innsigle": "1",
    "type": "https://innsigle.dev/claim/colophon/v1",
    "issued_at": "2026-09-30T20:48:46Z",
    "issuer": {
      "id": "innsigle",
      "name": "Innsigle",
      "key_id": "ed25519:050bf4d0361a96aa3b6baa3fc2ffd0cb",
      "key_url": "https://documentdrivendx.github.io/innsigle/.well-known/innsigle/keys.json"
    },
    "subjects": [
      {
        "uri": "https://documentdrivendx.github.io/innsigle/reference/artifacts/adrs/adr-001-signing-and-canonicalization/",
        "digest": {
          "alg": "sha256",
          "value": "6f5de99ca95be7648cc061f9b5556816bf6a3c39fccb6ac06a6dd2fd2d5eec50"
        }
      }
    ],
    "colophon": {
      "schema_version": "1",
      "composition": "model-primary",
      "ingredients": [
        {
          "kind": "model",
          "name": "Claude",
          "role": "draft"
        },
        {
          "kind": "tool",
          "name": "sloptimizer",
          "role": "rewrite"
        },
        {
          "kind": "human",
          "name": "operator",
          "role": "structure-edit"
        }
      ],
      "notes": null
    }
  },
  "payload_encoding": "json",
  "signatures": [
    {
      "key_id": "ed25519:050bf4d0361a96aa3b6baa3fc2ffd0cb",
      "alg": "ed25519",
      "sig": "SkTpDRmN_22deiYNLWlciQEdoUGb92sDHIvSIn3k0FdI7kHPZiHHfjRPHvnCSmjSbnZe9oYyKGef0eXgcRDFDw",
      "signed_at": "2026-09-30T20:48:46Z"
    }
  ]
}