How the resolver works

The resolver is the piece of infrastructure that turns OLPN claims into verified answers. The reference implementation is hosted at olpn.org and its source lives alongside this repo. Anyone can run their own resolver; the protocol does not require you to trust the hosted one.

Input

A resolver takes one input: an OLPN network ID in any of the forms below.

• §:entity:example.com (canonical)
• entity:example.com (prefix dropped, still recognized)
• example.com (domain only, the resolver infers the prefix)

The reference resolver also accepts a small set of aliases ("Nick Carroll" resolves to §:entity:nickcarroll.com) via a local founders.json file. This is a UX convenience for the hosted resolver, not part of the protocol.

Steps

1. Normalize input. Strip known prefixes. Validate the domain shape.
2. Fetch the entity document. Try https://{domain}/olpn.json first. On failure, fetch https://{domain}/ and extract <script id="olpn-hub">.
3. Parse. Must have a non-empty network_id. Everything else is optional.
4. Verify each property. For each entry in properties[], fetch the property document at that property's domain and check ownership[] for the entity's network ID. See Two-way back-link check.
5. Verify each credential. For each entry in credentials[], parse the credential ID, fetch the credential document at {issuer}/{user}/olpn-credential.json, and check that olpn_entity_id matches the entity. See Issuer-side back-link check.
6. Render. Emit a results page with verified properties and credentials, schema.org JSON-LD, and a verification trace so users can see what the resolver checked.

Output

The reference resolver's output is an HTML page: profile, verified properties, verified credentials, and a collapsible "Show Details" section with a step-by-step trace.

A custom resolver might output JSON, produce signed attestations, stream events, or do something else entirely. The protocol only specifies the inputs and the verification rules, not the output format.

Failure is silent by default

If a property or credential fails to verify (document missing, back-link missing, parse error), the reference resolver drops it from the verified list. It still logs the failure to the trace, so users can see why, but the verified output shows only what passed.

This is deliberate. Showing unverified claims alongside verified ones on the default results page would encourage consumers to treat "claimed" as "trusted". Implementers who want to surface unverified claims with a different visual treatment are free to do so in their own resolvers.

Timeouts

Every external fetch has a 10-second timeout. Slow or unreachable hosts are treated as failures. Credential and property documents are fetched sequentially; a resolver can reasonably verify an entity with dozens of credentials in under a minute, assuming each issuer responds promptly.

Caching

The reference resolver does not cache document fetches. Every search re-fetches everything. This is simple and predictable but puts steady load on popular hosts. Future resolvers may cache with standard HTTP cache headers; the protocol does not mandate a caching policy.

No identity assertion

A resolver does not assert that the person behind the domain is who they claim to be. It only checks that two documents published at two domains agree with each other. If the wrong person controls both sides, the resolver will happily verify the lie. The protocol relies on the fact that controlling a domain is a costly, auditable signal, not on any separate attestation of identity.