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

Generated from HELIX docs. Source: docs/helix/02-design/adrs/ADR-003-issuer-url-and-web-of-trust.md. Edit the source, not this file or site/ HTML.

ddx:
  id: aibadge.adr.003
  type: adr
  links:
    - target: aibadge.adr.001
      kind: informed_by
    - target: aibadge.design.claim-system
      kind: informed_by
    - target: aibadge.design.attestation-prior-art
      kind: informed_by
    - target: aibadge.contract.001
      kind: informs
    - target: aibadge.prd
      kind: informed_by
status: accepted
activity: 02-design
created: 2026-07-24

ADR-003: Issuer URL binding and web of trust

Context

Threats this ADR addresses

Decision

D1 — Full issuer URL in every signature

1. Every signed claim payload MUST include issuer.key_url as an absolute URL with scheme https: (production) or http: only for loopback/test.
2. Relative paths, bare hostnames, and missing key_url are invalid for signed claims.
3. Because the claim payload is what ADR-001 signs (JCS → SHA-256 → Ed25519), key_url is covered by the signature. A verifier that checks the signature has integrity over the discovery URL the signer asserted at seal time.
4. issuer.id remains a non-unique display slug. Cryptographic identity is issuer.key_id. Discovery channel is issuer.key_url.

D2 — How verifiers load keys

1. Default discovery: fetch the issuer document from the signed issuer.key_url.
2. Match issuer.key_id to a non-revoked key in that document; issuer_id in the document SHOULD equal issuer.id (warn if not; do not treat slug alone as trust).
3. Implementations MAY accept a local file only when it is a pin of a previously observed document for that key_url / key_id, or for offline tests.
4. Implementations MUST NOT silently substitute an unrelated keys file without recording that policy override.

D3 — Issuer document at key_url

The resource at key_url is an issuer document (evolved from minimal keys.json):

Backward compatibility: Documents that only set innsigle_keys: "1" (pre-ADR-003) remain valid as a keys-only issuer document with empty endorsements. New producers SHOULD emit innsigle_issuer: "1".

D4 — Key-endorsement attestations (web of trust edges)

An issuer may publish key-endorsement claims: signed statements that this key trusts another Innsigle key for identity / seal recognition, not for content truth.

1. Type URI: https://innsigle.dev/claim/key-endorsement/v1
2. Signed payload MUST include the endorser’s full issuer object (including absolute key_url), same as colophon claims.
3. Subject of endorsement MUST include the endorsee’s absolute key_url and key_id (and MAY include issuer_id as display only).
4. Each endorsement is a normal Innsigle attestation envelope (ADR-001 crypto).
5. The endorser’s issuer document lists endorsements in endorsements[] with at least:

- attestation_url — absolute URL of the endorsement attestation JSON - subject_key_id - subject_key_url — absolute - issued_at (optional cache hint; the attestation is authoritative)

D5 — Transitive web of trust (verifier policy)

Trust is a policy graph, not a crypto boolean alone.

Normative verifier algorithm (WoT path check):

1. Verify the content attestation (colophon claim) under sealer key_id / keys from sealer’s signed key_url.
2. If sealer key_id is in the verifier’s pin set → identity accepted (for policy).
3. Else, BFS/DFS from pin set over endorsement edges:

- Load endorser’s issuer document from the endorsement attestation’s signed issuer.key_url. - Verify endorsement attestation signature. - Confirm endorsement subject matches next hop key_id + key_url. - Enforce max_depth (default 3), reject cycles, optional level policy (e.g. only full).

1. If a path exists → transitively recognized; else → crypto may still be VALID but issuer not recognized.

Non-goals of the WoT:

• Does not validate colophon honesty or content truth.
• Does not replace offline private-key custody.
• Does not make issuer.id globally unique.
• Does not require a global keyserver (each issuer publishes their own edge list).

D6 — Host compromise (design honesty)

Publishing keys at a URL is DKIM-class discovery, not a CA. ADR-003 makes the asserted discovery URL immutable inside the seal and adds signed peer edges for transitive recognition.

D7 — Social and profile discovery (no webserver required)

Problem: Requiring every maker to run or configure a webserver excludes UC-human-social and casual house signers.

Decision: Self-hosted HTTP is not required. What is required is a durable absolute HTTPS URL for the issuer document (the signed key_url). That URL MAY be hosted by any operator the issuer trusts enough to publish public material, including free platforms. Social profiles carry corroborating embeds of issuer metadata so humans can bootstrap without knowing DNS or servers.

D7.1 — Hosting the issuer document (key_url targets)

Any stable HTTPS origin that serves raw JSON (or HTML with a linked JSON) is valid, including but not limited to:

Private keys MUST NOT be uploaded to these hosts. Only the issuer document (public keys + endorsement index) and public attestations.

D7.2 — Social / profile embeds (bootstrap, not substitute for key_url)

Platforms that strip file metadata still allow profile fields and posts. Issuers SHOULD embed a compact issuer card so viewers can find keys without already knowing key_url.

Issuer card (profile-safe text):

Innsigle · {short_name}
key {key_id}
keys {absolute_key_url}

Rules:

1. key_id is mandatory in the card when space allows (cryptographic handle).
2. keys {url} MUST be the same absolute URL used as signed issuer.key_url on claims (or a short redirect that 302/200 resolves to that document).
3. Optional one-liner: how https://…/use/marks/ or house meaning page.
4. Card text is unsigned marketing/discovery. Crypto trust still comes from verifying seals + pin/WoT.
5. Platforms that allow a single link field: put key_url (or shortlink to it) as the profile URL; put fingerprint in bio text.

D7.3 — Recommended profile placements

D7.4 — Relationship to signed claims

A profile that shows fingerprint F but seals that use a different key_id is a mismatch warning for humans and tools—not automatic invalid crypto.

D7.5 — Multiple discovery URLs

• Exactly one key_url is signed per claim (D1).
• Issuers MAY publish the same issuer document bytes (or identical keys) at multiple HTTPS locations.
• Optional later: mirrors[] on the issuer document; not required for v1.
• Shortlinks allowed only if they resolve to the absolute document URL used in seals (document the final URL in seals when practical).

D7.6 — Platform risk (honesty)

Non-goal: Innsigle does not require partnership with social platforms or in-app key APIs for v1.

Alternatives

Consequences

Risks

Validation

Supersession

• Supersedes: None (extends ADR-001 envelope usage; does not change algorithms)
• Superseded by: None
• Amends guidance in: claim-system.md (TOFU/WoT); CONTRACT-001 (issuer URL + endorsements)

Concern Impact

• Strengthens key-custody, issuer discovery, and future area:crypto trust policy.
• WoT is opt-in policy for verifiers; unsigned seals and keys-only issuers remain valid.

Normative summary (implementers)

1. Sign: payload.issuer.key_url = absolute URL; covered by ADR-001 signature.
2. Publish: issuer document at that URL with keys; optional endorsements index — any durable HTTPS host, not only self-hosted servers (D7).
3. Embed: put issuer card (fingerprint + keys URL) on social/profiles for human discovery (D7).
4. Endorse: sign key-endorsement attestations; list them on your issuer document.
5. Verify content: crypto under sealer key from signed key_url.
6. Verify identity (optional): pin roots + walk endorsement edges with depth limits.

References

• ADR-001 Signing and canonicalization
• CONTRACT-001 Claim and CLI
• docs/helix/02-design/claim-system.md
• docs/helix/02-design/attestation-prior-art.md (PGP WoT, DKIM)
• RFC 8785 JCS
• PRD FR-9–12