@metalabel/dfos-protocol 0.0.2 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (24) hide show
  1. package/CONTENT-MODEL.md +64 -23
  2. package/DID-METHOD.md +7 -8
  3. package/PROTOCOL.md +194 -123
  4. package/README.md +9 -11
  5. package/dist/chain/index.d.ts +97 -5
  6. package/dist/chain/index.js +15 -3
  7. package/dist/{chunk-LWC4PWGZ.js → chunk-ASGEXSVT.js} +177 -7
  8. package/dist/chunk-E5CFQG2B.js +99 -0
  9. package/dist/index.d.ts +2 -4
  10. package/dist/index.js +28 -34
  11. package/dist/merkle/index.d.ts +45 -0
  12. package/dist/merkle/index.js +14 -0
  13. package/examples/content-delete.json +5 -4
  14. package/examples/content-lifecycle.json +9 -7
  15. package/package.json +6 -9
  16. package/schemas/manifest.v1.json +29 -0
  17. package/schemas/post.v1.json +5 -0
  18. package/schemas/profile.v1.json +5 -0
  19. package/REGISTRY-API.md +0 -242
  20. package/dist/chunk-4MMWM2PC.js +0 -311
  21. package/dist/registry/index.d.ts +0 -143
  22. package/dist/registry/index.js +0 -34
  23. package/openapi.yaml +0 -376
  24. package/schemas/document-envelope.v1.json +0 -37
package/CONTENT-MODEL.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # DFOS Content Model
2
2
 
3
- Standard content schemas for documents committed to DFOS content chains. JSON Schema (draft 2020-12) definitions for what goes inside the document envelope's `content` field.
3
+ Standard content schemas for documents committed to DFOS content chains. JSON Schema (draft 2020-12) definitions for content objects committed directly by CID.
4
4
 
5
- These schemas are conventions, not protocol requirements. The DFOS Protocol commits to documents by CID without inspecting their contents — any valid JSON object with a `$schema` field can be committed. The content model defines the vocabulary that DFOS uses internally, provided as a starting point for applications built on the protocol.
5
+ These schemas are conventions, not protocol requirements. The DFOS Protocol commits to content objects by CID without inspecting their contents — any valid JSON object with a `$schema` field can be committed. The content model defines the vocabulary that DFOS uses internally, provided as a starting point for applications built on the protocol.
6
6
 
7
7
  [Protocol Specification](https://protocol.dfos.com/spec) · [schemas.dfos.com](https://schemas.dfos.com) · [Source](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol/schemas)
8
8
 
@@ -10,7 +10,13 @@ These schemas are conventions, not protocol requirements. The DFOS Protocol comm
10
10
 
11
11
  ## Schema Convention
12
12
 
13
- Every document committed to a content chain is wrapped in a [document envelope](https://protocol.dfos.com/spec#document-envelope). The envelope's `content` field holds the application-defined payload. The protocol requires one thing of this payload: it must include a `$schema` property identifying its content type.
13
+ Content objects are committed directly to a content chain by CID. The CID is derived from the canonical dag-cbor encoding of the content object itself:
14
+
15
+ ```
16
+ documentCID = CID(dagCborCanonicalEncode(contentObject))
17
+ ```
18
+
19
+ The protocol requires one thing of the content object: it must include a `$schema` property identifying its content type.
14
20
 
15
21
  ```json
16
22
  {
@@ -20,7 +26,7 @@ Every document committed to a content chain is wrapped in a [document envelope](
20
26
  }
21
27
  ```
22
28
 
23
- Because `$schema` is part of the document, it is behind the `documentCID` — cryptographically committed in the content chain. Any verifier can resolve the document, read `$schema`, and validate against the schema. Documents are self-describing.
29
+ Because `$schema` is part of the content object, it is behind the `documentCID` — cryptographically committed in the content chain. Any verifier can resolve the document, read `$schema`, and validate against the schema. Documents are self-describing.
24
30
 
25
31
  ---
26
32
 
@@ -42,28 +48,63 @@ Schema files live in [`schemas/`](https://github.com/metalabel/dfos/tree/main/pa
42
48
 
43
49
  The primary content type. Covers short posts, long-form posts, comments, and replies via the `format` discriminator.
44
50
 
45
- | Field | Type | Required | Description |
46
- | ------------- | -------- | -------- | ---------------------------------------------------------------------------------- |
47
- | `$schema` | string | yes | `"https://schemas.dfos.com/post/v1"` |
48
- | `format` | enum | yes | `"short-post"`, `"long-post"`, `"comment"`, `"reply"` — immutable, set at creation |
49
- | `title` | string | no | Post title (typically for long-post format) |
50
- | `body` | string | no | Post body content |
51
- | `cover` | media | no | Cover image |
52
- | `attachments` | media[] | no | Attached media objects |
53
- | `topics` | string[] | no | Topic names (stored as names for portability) |
51
+ | Field | Type | Required | Description |
52
+ | -------------- | -------- | -------- | ---------------------------------------------------------------------------------- |
53
+ | `$schema` | string | yes | `"https://schemas.dfos.com/post/v1"` |
54
+ | `format` | enum | yes | `"short-post"`, `"long-post"`, `"comment"`, `"reply"` — immutable, set at creation |
55
+ | `title` | string | no | Post title (typically for long-post format) |
56
+ | `body` | string | no | Post body content |
57
+ | `cover` | media | no | Cover image |
58
+ | `attachments` | media[] | no | Attached media objects |
59
+ | `topics` | string[] | no | Topic names (stored as names for portability) |
60
+ | `createdByDID` | string | no | DID of the content author — distinct from the chain operation signer |
61
+
62
+ `createdByDID` answers "who authored this content", which may differ from the signer of the chain operation (the `kid` DID). For example, an agent acting on behalf of a user commits the operation, but `createdByDID` records the human author.
54
63
 
55
64
  ### Profile (`https://schemas.dfos.com/profile/v1`)
56
65
 
57
66
  The displayable identity for any agent, person, group, or space.
58
67
 
59
- | Field | Type | Required | Description |
60
- | ------------- | ------ | -------- | --------------------------------------- |
61
- | `$schema` | string | yes | `"https://schemas.dfos.com/profile/v1"` |
62
- | `name` | string | no | Display name |
63
- | `description` | string | no | Short bio or description |
64
- | `avatar` | media | no | Avatar image |
65
- | `banner` | media | no | Banner image |
66
- | `background` | media | no | Background image |
68
+ | Field | Type | Required | Description |
69
+ | -------------- | ------ | -------- | --------------------------------------- |
70
+ | `$schema` | string | yes | `"https://schemas.dfos.com/profile/v1"` |
71
+ | `name` | string | no | Display name |
72
+ | `description` | string | no | Short bio or description |
73
+ | `avatar` | media | no | Avatar image |
74
+ | `banner` | media | no | Banner image |
75
+ | `background` | media | no | Background image |
76
+ | `createdByDID` | string | no | DID of the identity subject |
77
+
78
+ ### Manifest (`https://schemas.dfos.com/manifest/v1`)
79
+
80
+ A semantic index mapping path-like labels to protocol object references. The navigation layer for a DID's content.
81
+
82
+ | Field | Type | Required | Description |
83
+ | --------- | ------ | -------- | --------------------------------------------------- |
84
+ | `$schema` | string | yes | `"https://schemas.dfos.com/manifest/v1"` |
85
+ | `entries` | object | yes | Map of path-like keys to protocol object references |
86
+
87
+ Entry keys: lowercase alphanumeric with dots, underscores, hyphens, forward slashes. 2–128 chars. Must start and end with alphanumeric. Examples: `profile`, `posts`, `drafts/post-1`, `v1.0/release-notes`.
88
+
89
+ Entry values are protocol object references, self-describing by format:
90
+
91
+ - **contentId** (22-char bare hash) — references a living content chain
92
+ - **DID** (`did:dfos:...`) — references an identity
93
+ - **CID** (`bafyrei...`) — references a specific immutable document snapshot
94
+
95
+ ```json
96
+ {
97
+ "$schema": "https://schemas.dfos.com/manifest/v1",
98
+ "entries": {
99
+ "profile": "67t27rzc83v7c22n9t6z7c",
100
+ "posts": "a4b8c2d3e5f6g7h8i9j0k1",
101
+ "dark-publisher": "did:dfos:e3vvtck42d4eacdnzvtrn6",
102
+ "pinned-charter": "bafyreibanjpgcqffcfhr4sptzjfthh5szohhbo5tjfulemkw7uhden5uqy"
103
+ }
104
+ }
105
+ ```
106
+
107
+ Manifests are content chains — same signing, same verification, same CIDs. A manifest's contentId appears in the DID's content set like any other chain. The semantic index (the document) is dark forest content — requires authorization to read. The operation chain (proof substrate) is public.
67
108
 
68
109
  ### Media Object
69
110
 
@@ -86,9 +127,9 @@ A content chain is a signed append-only log. The protocol enforces ordering, aut
86
127
 
87
128
  ### Living Document
88
129
 
89
- The chain represents a single evolving thing — a profile, a post, a policy document. Each operation is a **revision**. The resolved state is the latest `documentCID`. History is audit trail. The entity _is_ the current version.
130
+ The chain represents a single evolving thing — a profile, a post, a policy document. Each operation is a **revision**. The resolved state is the latest `documentCID`. History is audit trail. The content _is_ the current version.
90
131
 
91
- This is the default interpretation for the standard schemas. The document envelope's `baseDocumentCID` field supports edit lineage — each new document version can point back to the one it replaced.
132
+ This is the default interpretation for the standard schemas. Edit lineage is tracked via `baseDocumentCID` on the content operation payload — each new operation can reference the document CID it replaced.
92
133
 
93
134
  ### Stream
94
135
 
package/DID-METHOD.md CHANGED
@@ -201,7 +201,7 @@ The critical property of `did:dfos` resolution: **the DID is verified against th
201
201
 
202
202
  The `did:dfos` method is transport-agnostic. Any system that can deliver an ordered sequence of JWS tokens (the identity chain) is a valid transport. Examples include:
203
203
 
204
- - **HTTP API** — The DFOS Registry API ([OpenAPI spec](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/openapi.yaml)) provides a REST interface for chain storage and retrieval.
204
+ - **HTTP API** — Any HTTP service that stores and retrieves ordered JWS logs can serve as a transport binding.
205
205
  - **Peer-to-peer exchange** — Chains can be exchanged directly between parties.
206
206
  - **Local storage** — Chains can be stored in local files, databases, or key-value stores.
207
207
  - **Bundle export** — Applications can export chains as portable bundles (e.g., JSON arrays of JWS tokens).
@@ -317,10 +317,9 @@ A complete reference implementation is available as the `@metalabel/dfos-protoco
317
317
 
318
318
  ### 9.2 Informative References
319
319
 
320
- | Reference | URI |
321
- | ----------------------- | ------------------------------------------------------------------------------- |
322
- | W3C DID Spec Registries | https://w3c.github.io/did-spec-registries/ |
323
- | Multicodec Table | https://github.com/multiformats/multicodec |
324
- | CIDv1 Specification | https://github.com/multiformats/cid |
325
- | dag-cbor Codec | https://ipld.io/specs/codecs/dag-cbor/spec/ |
326
- | DFOS Registry OpenAPI | https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/openapi.yaml |
320
+ | Reference | URI |
321
+ | ----------------------- | ------------------------------------------- |
322
+ | W3C DID Spec Registries | https://w3c.github.io/did-spec-registries/ |
323
+ | Multicodec Table | https://github.com/multiformats/multicodec |
324
+ | CIDv1 Specification | https://github.com/multiformats/cid |
325
+ | dag-cbor Codec | https://ipld.io/specs/codecs/dag-cbor/spec/ |