Innsigle Reference ADR-004: Human key, build key, and derived pages

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

Generated from HELIX docs. Source: docs/helix/02-design/adrs/ADR-004-human-and-build-keys.md. Edit the source, not this file or site/ HTML.
Source frontmatter
ddx:
  id: innsigle.adr.004
  type: adr
  links:
    - target: innsigle.adr.003
      kind: informed_by
    - target: innsigle.contract.001
      kind: informs
status: accepted
activity: 02-design
created: 2026-09-16

ADR-004: Human key, build key, and derived pages

DateStatusDecidersRelatedConfidence
2026-09-16AcceptedOperatorADR-003 D4–D5; Helix microsite sealsHigh

Context

HELIX (and this microsite) seal documentation with Innsigle. One house key was signing curated mixed/human pages and generated reference pages. That collapses key provenance: a GitHub Actions secret that can seal model-primary output can also seal a page that claims to be mixed. PGP-style web of trust already exists in ADR-003 (key-endorsement) but was unused.

Rendered HTML is a deterministic function of sealed markdown. Signing the HTML with the human key would put that key in CI and go stale on every layout tweak. The HTML must carry the source signature, not replace it.

Decision

D1 — Two roles, one issuer document

RoleCustodySeals
humanOperator (1Password / local PEM, never GitHub)human-authored and mixed sources in git
buildCI (INNSIGLE_BUILD_KEY) or a gitignored local PEMmodel-primary / generated: true sources; optional later derivation receipts

Both public keys live in the same issuer document (keys.json). Identity is still key_id + key_url (ADR-003). Optional role on a key object is display only.

D2 — Human key endorses the build key

The human key publishes a key-endorsement (ADR-003 D4) over the build key_id / key_url, purpose build-signing. Verifiers who pin the human key recognize build-key seals transitively (D5, depth 1 is enough here).

The build key MUST NOT endorse the human key. CI compromise must not mint human-role seals.

D3 — Seal policy (innsigle seal --all)

  • --role human — only mixed / human-authored; requires the human private key
  • --role build — only model-primary; requires INNSIGLE_BUILD_KEY or

keys.build.signing_key

  • --all with no role — each file uses the matching key; skip (do not fail)

when that key is absent

A digest match does not skip if the existing claim was signed by the wrong role (migration).

D4 — Derived pages quote the source seal

The published HTML is not the subject of the human signature. The colophon embeds the source attestation (bytes + application/innsigle+json) and MUST say the signature covers the markdown source, not the HTML bytes.

A viewer who verifies that attestation against the source file (or a byte-identical checkout) has the same guarantee Helix wanted from a page seal, without putting the human key in GitHub.

Consequences

  • Curated claims are committed; they change only when a human reseals.
  • Generated claims may be committed (local build key) or refreshed in CI

with INNSIGLE_BUILD_KEY.

  • innsigle verify --all still checks crypto-VALID. Recognition

(human pin → build via endorsement) is extra chrome, not a new VALID meaning.

  • Signing HTML with the human key remains a non-goal.

Update (ADR-005)

D4's "derived pages quote the source seal" is generalized: a build-signed derivation claim now carries the human review of the source across the build, and the human-endorses-build relationship (D2) is what a verifier checks before trusting it. See ADR-005.

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-004-human-and-build-keys.md
Signed
2026-11-10T13:38:16Z
Content digest
sha256:e6fb7993…29bbdc4a

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-11-10T13:38:16Z",
    "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-004-human-and-build-keys/",
        "digest": {
          "alg": "sha256",
          "value": "e6fb7993ed832cf7214fb7c5774e539cee3ac2fe5c1710dad22fb43d29bbdc4a"
        }
      }
    ],
    "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": "_BHKc-x4rSLMyW4fskQCG1sv99S9kapQ9P08wNE4wcqzzVWKTbR7sMPhK2B0Y7hsIdmCF8mdWEzBSenKkmpuCQ",
      "signed_at": "2026-11-10T13:38:16Z"
    }
  ]
}