@metalabel/dfos-protocol

Ed25519 signed chain primitives for cryptographic identity and verifiable content. Self-certifying DIDs, content-addressed CIDs, offline verification. The protocol operates on keys and document hashes — application semantics are a separate concern, free to evolve without protocol changes.

Install

npm install @metalabel/dfos-protocol zod

zod is a peer dependency. The package exports Zod schema objects directly (IdentityOperation, ContentOperation, MultikeyPublicKey, …) so you can compose them into your own schemas — which only works if your app and this package share one Zod install.

Usage

// Chain verification
import { verifyContentChain, verifyIdentityChain } from '@metalabel/dfos-protocol/chain';
// Credentials (DFOS credentials) and the API-AUTH proof envelope
import { createDFOSCredential, signApiIdentityRequest } from '@metalabel/dfos-protocol/credentials';
// Crypto primitives
import { createJws, dagCborCanonicalEncode, verifyJws } from '@metalabel/dfos-protocol/crypto';
// KEY-PROOF — the challenge-bound proof that a candidate key is held
import { signKeyProof, verifyKeyProof } from '@metalabel/dfos-protocol/key-proof';

Subpath Exports

| Export | Description | | -------------------------------------- | ------------------------------------------------------------------------------------------------------- | | @metalabel/dfos-protocol/chain | Identity & content chains, services, artifacts, countersigns, revocations, credit claims, sign requests | | @metalabel/dfos-protocol/credentials | DFOS credentials for authorization, and the API-AUTH request-proof / identity-proof envelopes | | @metalabel/dfos-protocol/crypto | Ed25519, JWS, JWT, dag-cbor, base64url, ID generation | | @metalabel/dfos-protocol/key-proof | KEY-PROOF envelopes — compose/sign and verify a challenge-bound proof that a candidate key is held | | @metalabel/dfos-protocol/fold | Canonical linearization and LWW-map folds for index documents |

api: resources and the jti member

An api: resource takes one of two forms: api:<host>, the whole API surface, and api:<host>/spaces/<id>, one space on it. A bare host is the ancestor of every space at that host, so a grant naming the host covers a space-addressed request while a space-scoped grant covers only its own space. parseApiResource and apiResourceCovers are that rule on its own; isAttenuated and matchesResource apply it. Every other resource type is exact byte equality, and a malformed api: id covers nothing — itself included.

jti is the envelope's one registered additive member: a per-request unique string of at most MAX_JTI_BYTES UTF-8 bytes, emitted after the canonical members. Pass it typed to signApiRequest or signApiIdentityRequest (generateJti() mints one), set requireJti on a verifier to refuse a proof without it, and read the verified value back off the envelope to key a replay cache. A proof carrying none has the bytes it always had.

Specifications

| Document | Description | | ------------------------------------------------ | ------------------------------------------------------------------------------- | | PROTOCOL.md | Core protocol — chains, signatures, key possession, verification, test vectors | | DID-METHOD.md | W3C DID method specification for did:dfos | | CONTENT-MODEL.md | Standard content schemas (post, profile) and verifiable attribution | | CREDENTIALS.md | UCAN-style authorization credentials for the DFOS protocol | | RELAY.md | The relay HTTP surface, including the sign-request envelope and signing mailbox | | INTEGRATIONS.md | Sign in, API authentication, origin binding, and key ceremonies |

Release history lives at https://github.com/metalabel/dfos/releases.

Examples

The examples/ directory contains deterministic reference fixtures that can be independently verified by any Ed25519 + dag-cbor implementation:

• identity-genesis.json — single create operation
• identity-rotation.json — genesis + key rotation
• identity-delete.json — genesis + delete (terminal)
• content-lifecycle.json — create + update (with both documents)
• content-delete.json — create + delete
• content-delegated.json — creator genesis + delegated update with DFOS write credential
• credential-write.json — DFOS write credential (broad + content-narrowed)
• credential-read.json — DFOS read credential
• identity-services.json — genesis publishing a services set (relay locator + content/artifact anchors)
• api-resource-coverage.json — the api: hierarchy's parse, coverage, attenuation, and matching rows, read by the TypeScript and Go suites alike

License

MIT