Docs
Security
Threat model and review checklist for implementers.
Who you are defending against
| Adversary | Capability | Primary defence |
|---|---|---|
| A legitimate member | Valid credential | Reciprocity budgets, logging, the rulebook |
| A stolen credential | Everything the member could do | Request signing, short freshness window, revocation |
| A crafted payload | Feeds a QR code or deeplink to a reader | Anchored parsing |
| A network operator | Sees searches; holds the index | Declared retention, audit, contract |
| A compromised resolver | Answers with the wrong destination | Signatures, plus a commitment published independently of the answer — see its limits |
| A passive observer | Watches traffic | TLS |
The realistic directory attacker is an authenticated participant, or someone holding their key — not an anonymous outsider.
Rules that matter
1. Parse the whole input
Match the complete string, at both ends. See the reading algorithm.
2. Asymmetric signatures on public statements
Ed25519 over canonical JSON for every statement that leaves the operator. A shared secret does not let a third party verify who produced a value.
3. Canonical serialisation
RFC 8785. Test against vectors from an independent implementation.
4. A lookup returns a routing answer
Which member, what they accept, applicable limits. Not a profile, a name, or a KYC tier.
5. Indistinguishable negatives
An unknown key and a key that is not visible to the caller produce the same response.
6. Credentials stay on the server
Directory calls go from a server. The application talks to its own backend.
7. Check authorisation when the operation runs
Revocation is evaluated at execution, not at issuance.
8. Bound delegation
A token names amount, currency and a commitment over the destination, and exposes its counters.
Key management
One signing key per operator, published under a kid. Rotation is publish-then-switch: the new
key appears alongside the old, then new envelopes carry the new kid, and old envelopes stay
verifiable.
An unknown kid is not a bad signature. Report it distinctly and refetch the issuer's document.
Fetch keys from the issuer's own discovery document. Never from whoever served the envelope.
Identifier hashing
The network holds the hashing secret. Members do not. The directory stores a reference and a version, not the secret. Lookups are hashed by the network — that is not zero knowledge. See Privacy.
Request signing
- 01Path-Key-IdThe key id.
- 02Path-TimestampRFC 3339, inside the freshness window.
- 03Path-SignatureEd25519 over METHOD \n PATH \n TIMESTAMP \n SHA256(body).
A five-minute window by default. The signature includes a digest of the body.
Clock skew is the usual reason a request fails verification.
What to review first
- Input that is not a complete PATH link is rejected.
- Unknown and hidden keys return the same answer.
- A signature produced by another implementation verifies.
- Clear identifiers do not appear in storage or logs.
- A revoked credential fails the next operation.
- A lookup returns routing information only.
- The hashing secret is not in the database.
Reporting
Security issues in the specification or the reference implementation: security@pathprotocol.dev.
Issues in a specific operator's deployment go to that operator — its contact is in its discovery document.