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
| Date | Status | Deciders | Related | Confidence |
| 2026-07-22 | Accepted | Operator | PRD FR-9–12; claim-system.md | High |
Context
| Aspect | Description |
| Problem | Claim attestations need a frozen crypto suite and deterministic bytes to sign so independent verifiers agree |
| Current State | claim-system.md proposed Ed25519 + SHA-256 + simple JSON envelope without a decision record |
| Requirements | Offline verify; local long-lived house keys; no mandatory Sigstore/OIDC in v1 |
| Decision Drivers | Simplicity 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
| Option | Pros | Cons | Evaluation |
| OpenPGP packets + cleartext/detached sig | WoT tooling exists | Heavy UX; variable implementations | Rejected for v1 |
| Sigstore keyless only | No long-lived keys | OIDC dependency; not house craft default | Rejected as sole path; optional later |
| ECDSA P-256 | Common in web PKI | Larger; no advantage for us | Rejected |
| Ed25519 + SHA-256 + JCS | Small keys; deterministic; simple | Need careful JSON rules | Selected |
| Embed C2PA as only format | Industry media path | Social strip; media-first | Rejected as sole path |
Consequences
| Type | Impact |
| Positive | Implementable with sodium/WebCrypto/libsodium; clear verify steps; no CA required |
| Negative | Not natively cosign-compatible until export path; must document JCS carefully |
| Neutral | Type URI host can change without changing crypto |
Risks
| Risk | Prob | Impact | Mitigation |
| Canonicalization bugs cause false invalid | M | H | Golden test vectors in repo; Contract examples |
| HTML page hashing ambiguity | M | H | Contract: hash exact file bytes operator passes; no silent HTML rewrite in v1 |
Validation
| Success Metric | Review Trigger |
| Independent verify of golden attestation succeeds on two runtimes | Any change to alg or canonicalization |
| Mutated content fails closed | Softening 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"
}
]
}
attestation file · issuer keys