Discovery Mechanisms

Status and BCP 14 terminology are defined in Status of This Document.

This document defines how verifiers find attestations and issuer metadata. OSAP v0.1 defines five discovery mechanisms. Conforming issuers MUST support at least one attestation discovery mechanism, but no individual mechanism is required for every issuer (see conformance.md).

1. Overview

#	Mechanism	Discovers	Initiated by
1	Sidecar file	Attestations for a specific asset URL	Verifier, given asset URL
2	Well-known issuer metadata	Issuer keys and endpoints	Verifier, given issuer identifier
3	HTTP Link header	Attestations for a fetched resource	Server response
4	HTML <link> element	Attestations for an HTML page or its assets	Page author
5	Hash lookup API	Attestations for a fingerprint	Verifier, given asset bytes

Relays, federation, IPFS transport, and Nostr-like distribution are not specified in v0.1; see index.md § 9.

2. Sidecar File

For an asset published at a URL, the attestation MAY be published at the same URL with .osap.json appended:

https://publisher.example/images/photo.jpg
https://publisher.example/images/photo.jpg.osap.json

• The sidecar file MUST contain either a single attestation envelope or a JSON array of envelopes, each validating against osap-envelope.schema.json.
• The sidecar SHOULD be served with Content-Type: application/json.
• Verifiers supporting sidecar discovery MUST, given an asset URL, attempt GET <asset-url>.osap.json.

Note (informative): A sidecar can be deployed as a static file adjacent to the asset and is the recommended starting point for issuers.

3. Well-Known Issuer Metadata

Issuer metadata lives at https://<domain>/.well-known/osap.json as defined in identity.md. It discovers keys and endpoints (revocations_url, outbox_url, lookup_url), not attestations directly. Verifiers MUST support this mechanism, since it is required for signature verification.

Example: ../examples/well-known-osap.json.

4. HTTP Link Header

A server MAY advertise an attestation for a resource in the HTTP response:

Link: <https://publisher.example/images/photo.jpg.osap.json>; rel="osap-attestation"

• The link relation string is osap-attestation (not yet IANA-registered; registration is an open issue, see index.md § 11).
• The target MUST resolve to a sidecar-format document (§ 2).
• Multiple Link headers (or a comma-separated list) MAY advertise multiple attestation documents.

5. HTML link Element

An HTML page MAY advertise attestations for itself or embedded assets:

<link rel="osap-attestation" href="https://publisher.example/articles/story.osap.json">

• The href MUST resolve to a sidecar-format document (§ 2).
• A page MAY carry multiple such elements, e.g. one for the page and one per embedded image.
• Verifiers match discovered attestations to assets by fingerprint, never by proximity in markup: an attestation only applies to bytes whose SHA-256 matches one of its asset_hashes.

6. Hash Lookup API

An issuer (or any other party) MAY operate a lookup endpoint, advertised via lookup_url in issuer metadata:

GET <lookup_url>?sha256=<lowercase-hex-digest>

• The response MUST be a JSON array of attestation envelopes whose subject.asset_hashes include an exact-bytes SHA-256 entry equal to the query value. The array MAY be empty.
• The endpoint SHOULD respond with HTTP 200 and an empty array, rather than 404, when no attestations are known.
• Privacy (normative): querying a lookup API reveals to its operator which content the user is examining. Verifier implementations MUST make hash lookup opt-in and MUST NOT perform lookups silently by default. See privacy.md and threat-model.md (hash lookup surveillance).

7. Precedence and Failure Handling

• Discovery mechanisms yield candidate attestations. The discovery mechanism does not affect verification; the same attestation is evaluated identically whether found through a sidecar or lookup (verification.md).
• When multiple mechanisms yield attestations for the same asset, verifiers MUST deduplicate by (issuer.id, id) and verify each distinct attestation independently.
• Verifiers SHOULD attempt mechanisms in the order: local/offline sources (already-cached attestations, sidecar files delivered with the asset), then in-band advertisement (Link header, HTML <link>), then sidecar probing, then — only with user opt-in — hash lookup.
• A failed mechanism (network error, 404, invalid JSON, schema failure) MUST NOT abort discovery; the verifier proceeds to the next mechanism. Documents that fail schema validation MUST be discarded and MAY be reported diagnostically.
• Verifiers MUST NOT label unattested content negatively. An attacker can strip attestations when redistributing content; see threat-model.md (downgrade attacks).