@metalabel/dfos-protocol 0.0.1

package/examples/identity-rotation.json

@@ -0,0 +1,19 @@
+{
+  "description": "Identity chain: genesis + key rotation",
+  "type": "identity",
+  "chain": [
+    "eyJhbGciOiJFZERTQSIsInR5cCI6ImRpZDpkZm9zOmlkZW50aXR5LW9wIiwia2lkIjoia2V5X3I5ZXYzNGZ2YzIzejk5OXZlYWFmdDgiLCJjaWQiOiJiYWZ5cmVpYmFuanBnY3FmZmNmaHI0c3B0empmdGhoNXN6b2hoYm81dGpmdWxlbWt3N3VoZGVuNXVxeSJ9.eyJ2ZXJzaW9uIjoxLCJ0eXBlIjoiY3JlYXRlIiwiYXV0aEtleXMiOlt7ImlkIjoia2V5X3I5ZXYzNGZ2YzIzejk5OXZlYWFmdDgiLCJ0eXBlIjoiTXVsdGlrZXkiLCJwdWJsaWNLZXlNdWx0aWJhc2UiOiJ6Nk1rcnpMTU53b0pTVjRQM1ljY1djYnRrOHZkOUx0Z01LbkxlYURMVXFMdUFTamIifV0sImFzc2VydEtleXMiOlt7ImlkIjoia2V5X3I5ZXYzNGZ2YzIzejk5OXZlYWFmdDgiLCJ0eXBlIjoiTXVsdGlrZXkiLCJwdWJsaWNLZXlNdWx0aWJhc2UiOiJ6Nk1rcnpMTU53b0pTVjRQM1ljY1djYnRrOHZkOUx0Z01LbkxlYURMVXFMdUFTamIifV0sImNvbnRyb2xsZXJLZXlzIjpbeyJpZCI6ImtleV9yOWV2MzRmdmMyM3o5OTl2ZWFhZnQ4IiwidHlwZSI6Ik11bHRpa2V5IiwicHVibGljS2V5TXVsdGliYXNlIjoiejZNa3J6TE1Od29KU1Y0UDNZY2NXY2J0azh2ZDlMdGdNS25MZWFETFVxTHVBU2piIn1dLCJjcmVhdGVkQXQiOiIyMDI2LTAzLTA3VDAwOjAwOjAwLjAwMFoifQ.EDryDK1uvtix-17cHun9t6MacFIx2rMmMF1QLzfD5TFlSsOvMcue97pCgGn3CXeLVFtVxgpCoh0kGSXioKKzAw",
+    "eyJhbGciOiJFZERTQSIsInR5cCI6ImRpZDpkZm9zOmlkZW50aXR5LW9wIiwia2lkIjoiZGlkOmRmb3M6ZTN2dnRjazQyZDRlYWNkbnp2dHJuNiNrZXlfcjlldjM0ZnZjMjN6OTk5dmVhYWZ0OCIsImNpZCI6ImJhZnlyZWljeW00Y3lpZWRubGQ3M3NtYngzMnN6YWVpN3hkdWxxbjRnM3N0ZTVlMncydWxhanIzb3FtIn0.eyJ2ZXJzaW9uIjoxLCJ0eXBlIjoidXBkYXRlIiwicHJldmlvdXNPcGVyYXRpb25DSUQiOiJiYWZ5cmVpYmFuanBnY3FmZmNmaHI0c3B0empmdGhoNXN6b2hoYm81dGpmdWxlbWt3N3VoZGVuNXVxeSIsImF1dGhLZXlzIjpbeyJpZCI6ImtleV9lejlhODc0dGNrcjNkdjkzM2QzY2tkIiwidHlwZSI6Ik11bHRpa2V5IiwicHVibGljS2V5TXVsdGliYXNlIjoiejZNa2ZVZDY1SnJBaGZkZ0Z1TUNjY1U5VGhRdmpCMmZKQU1VSGt1dWFqRjk5MmdLIn1dLCJhc3NlcnRLZXlzIjpbeyJpZCI6ImtleV9lejlhODc0dGNrcjNkdjkzM2QzY2tkIiwidHlwZSI6Ik11bHRpa2V5IiwicHVibGljS2V5TXVsdGliYXNlIjoiejZNa2ZVZDY1SnJBaGZkZ0Z1TUNjY1U5VGhRdmpCMmZKQU1VSGt1dWFqRjk5MmdLIn1dLCJjb250cm9sbGVyS2V5cyI6W3siaWQiOiJrZXlfZXo5YTg3NHRja3IzZHY5MzNkM2NrZCIsInR5cGUiOiJNdWx0aWtleSIsInB1YmxpY0tleU11bHRpYmFzZSI6Ino2TWtmVWQ2NUpyQWhmZGdGdU1DY2NVOVRoUXZqQjJmSkFNVUhrdXVhakY5OTJnSyJ9XSwiY3JlYXRlZEF0IjoiMjAyNi0wMy0wN1QwMDowMTowMC4wMDBaIn0.MScuoBlgOK3j5QX9tFcw1ou0o4LgJziGJEsZ5pvqiBr1SagAyAv5h-wajQhtg8IP7dLlM0U4leW2iRra945cDg"
+  ],
+  "expected": {
+    "did": "did:dfos:e3vvtck42d4eacdnzvtrn6",
+    "isDeleted": false,
+    "controllerKeys": [
+      {
+        "id": "key_ez9a874tckr3dv933d3ckd",
+        "type": "Multikey",
+        "publicKeyMultibase": "z6MkfUd65JrAhfdgFuMCccU9ThQvjB2fJAMUHkuuajF992gK"
+      }
+    ]
+  }
+}

package/openapi.yaml

@@ -0,0 +1,408 @@
+openapi: 3.1.0
+info:
+  title: DFOS Protocol Registry
+  version: 0.1.0
+  description: |
+    Minimal registry API for the DFOS Protocol. Provides chain submission,
+    resolution, and paginated operation history for identity chains and content
+    chains. Linear chain enforcement — accepts same or longer chains, rejects forks.
+
+    This spec defines the interoperability surface. Any implementation serving
+    these endpoints with these semantics is a compatible DFOS registry.
+
+servers:
+  - url: /
+    description: Registry root
+
+# ---------------------------------------------------------------------------
+
+paths:
+  /identities:
+    post:
+      operationId: submitIdentityChain
+      summary: Submit or extend an identity chain
+      description: |
+        Verifies the chain, derives the DID from the genesis CID, and stores it.
+        - 201: chain accepted (new or extended)
+        - 200: chain already stored (noop)
+        - 400: invalid chain (verification failed)
+        - 409: chain conflicts with stored chain (fork)
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SubmitChainRequest'
+      responses:
+        '201':
+          description: Chain accepted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IdentityState'
+        '200':
+          description: Chain already stored (noop)
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IdentityState'
+        '400':
+          description: Invalid chain
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '409':
+          description: Fork conflict
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
+  /identities/{did}:
+    get:
+      operationId: resolveIdentity
+      summary: Resolve current identity state
+      parameters:
+        - $ref: '#/components/parameters/did'
+      responses:
+        '200':
+          description: Verified identity state
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IdentityState'
+        '404':
+          description: Identity not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
+  /identities/{did}/operations:
+    get:
+      operationId: listIdentityOperations
+      summary: List identity chain operations (newest-first, paginated)
+      parameters:
+        - $ref: '#/components/parameters/did'
+        - $ref: '#/components/parameters/cursor'
+        - $ref: '#/components/parameters/limit'
+      responses:
+        '200':
+          description: Paginated operation list
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PaginatedOperations'
+        '404':
+          description: Identity not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
+  /entities:
+    post:
+      operationId: submitContentChain
+      summary: Submit or extend a content chain
+      description: |
+        Verifies the chain (resolving signing keys from stored identity chains),
+        derives the entity ID from the genesis CID, and stores it.
+        Same status code semantics as identity submission.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SubmitChainRequest'
+      responses:
+        '201':
+          description: Chain accepted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EntityState'
+        '200':
+          description: Chain already stored (noop)
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EntityState'
+        '400':
+          description: Invalid chain
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '409':
+          description: Fork conflict
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
+  /entities/{entityId}:
+    get:
+      operationId: resolveEntity
+      summary: Resolve current entity state
+      parameters:
+        - $ref: '#/components/parameters/entityId'
+      responses:
+        '200':
+          description: Entity state
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EntityState'
+        '404':
+          description: Entity not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
+  /entities/{entityId}/operations:
+    get:
+      operationId: listEntityOperations
+      summary: List content chain operations (newest-first, paginated)
+      parameters:
+        - $ref: '#/components/parameters/entityId'
+        - $ref: '#/components/parameters/cursor'
+        - $ref: '#/components/parameters/limit'
+      responses:
+        '200':
+          description: Paginated operation list
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PaginatedOperations'
+        '404':
+          description: Entity not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
+  /operations/{cid}:
+    get:
+      operationId: resolveOperation
+      summary: Resolve a single operation by CID
+      parameters:
+        - $ref: '#/components/parameters/cid'
+      responses:
+        '200':
+          description: Operation found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Operation'
+        '404':
+          description: Operation not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
+  /documents/{cid}:
+    get:
+      operationId: resolveDocument
+      summary: Resolve a document by CID
+      description: |
+        This is the only endpoint that touches actual content.
+        All other endpoints deal purely in chain mechanics.
+      parameters:
+        - $ref: '#/components/parameters/cid'
+      responses:
+        '200':
+          description: Document found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Document'
+        '404':
+          description: Document not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
+# ---------------------------------------------------------------------------
+
+components:
+  parameters:
+    did:
+      name: did
+      in: path
+      required: true
+      schema:
+        type: string
+        pattern: '^did:dfos:[2346789acdefhknrtvz]{22}$'
+      example: 'did:dfos:e3vvtck42d4eacdnzvtrn6'
+
+    entityId:
+      name: entityId
+      in: path
+      required: true
+      schema:
+        type: string
+        pattern: '^[2346789acdefhknrtvz]{22}$'
+      example: '67t27rzc83v7c22n9t6z7c'
+
+    cid:
+      name: cid
+      in: path
+      required: true
+      schema:
+        type: string
+      example: 'bafyreieseogefhfjajtkzqq6ssq63nnt7bslwca7d5wbrfbdlhld5jos6i'
+
+    cursor:
+      name: cursor
+      in: query
+      required: false
+      description: Opaque pagination cursor (CID of last item on previous page)
+      schema:
+        type: string
+
+    limit:
+      name: limit
+      in: query
+      required: false
+      description: Page size (1-100, default 25)
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 100
+        default: 25
+
+  schemas:
+    SubmitChainRequest:
+      type: object
+      required: [chain]
+      properties:
+        chain:
+          type: array
+          minItems: 1
+          items:
+            type: string
+            description: JWS compact token
+          description: |
+            Ordered array of JWS compact tokens, genesis-first.
+            The registry verifies the chain and either accepts (same or longer
+            than stored) or rejects (fork or invalid).
+
+    MultikeyPublicKey:
+      type: object
+      required: [id, type, publicKeyMultibase]
+      properties:
+        id:
+          type: string
+          example: 'key_ref_controller_01'
+        type:
+          type: string
+          enum: [Multikey]
+        publicKeyMultibase:
+          type: string
+          description: W3C Multikey encoded Ed25519 public key (z6Mk... prefix)
+          example: 'z6MkveUvhr2oyjZGmP4kHgsPSSa6t9mG9pWuPsYoGn2CzQ6o'
+
+    IdentityState:
+      type: object
+      required: [did, isDeleted, authKeys, assertKeys, controllerKeys]
+      properties:
+        did:
+          type: string
+          example: 'did:dfos:e3vvtck42d4eacdnzvtrn6'
+        isDeleted:
+          type: boolean
+        authKeys:
+          type: array
+          items:
+            $ref: '#/components/schemas/MultikeyPublicKey'
+        assertKeys:
+          type: array
+          items:
+            $ref: '#/components/schemas/MultikeyPublicKey'
+        controllerKeys:
+          type: array
+          items:
+            $ref: '#/components/schemas/MultikeyPublicKey'
+
+    EntityState:
+      type: object
+      required: [entityId, isDeleted, currentDocumentCID, genesisCID, headCID]
+      properties:
+        entityId:
+          type: string
+          example: '67t27rzc83v7c22n9t6z7c'
+        isDeleted:
+          type: boolean
+        currentDocumentCID:
+          type: string
+          nullable: true
+          description: CID of current document (null if cleared or deleted)
+        genesisCID:
+          type: string
+          description: CID of the genesis operation
+        headCID:
+          type: string
+          description: CID of the most recent operation
+
+    OperationEntry:
+      type: object
+      required: [cid, jwsToken, createdAt]
+      properties:
+        cid:
+          type: string
+          description: dag-cbor CID of the operation payload
+        jwsToken:
+          type: string
+          description: JWS compact token (the signed operation)
+        createdAt:
+          type: string
+          format: date-time
+          description: ISO 8601 timestamp from the operation payload
+
+    PaginatedOperations:
+      type: object
+      required: [operations, nextCursor]
+      properties:
+        operations:
+          type: array
+          items:
+            $ref: '#/components/schemas/OperationEntry'
+          description: Operations ordered newest-first
+        nextCursor:
+          type: string
+          nullable: true
+          description: |
+            Opaque cursor for the next page. Null when there are no more pages.
+            Pass as ?cursor=xxx on the next request.
+
+    Operation:
+      type: object
+      required: [cid, jwsToken]
+      properties:
+        cid:
+          type: string
+        jwsToken:
+          type: string
+
+    Document:
+      type: object
+      required: [cid, content]
+      properties:
+        cid:
+          type: string
+        content:
+          description: Opaque document content (application-defined)
+
+    Error:
+      type: object
+      required: [error, message]
+      properties:
+        error:
+          type: string
+          enum: [BAD_REQUEST, NOT_FOUND, CONFLICT]
+        message:
+          type: string

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@metalabel/dfos-protocol",
+  "version": "0.0.1",
+  "description": "DFOS Protocol — Ed25519 signed chain primitives, registry, and verification",
+  "license": "MIT",
+  "author": "Metalabel <hello@metalabel.com> (https://metalabel.com)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/metalabel/metalabel-dfos.git",
+    "directory": "packages/dfos-protocol"
+  },
+  "homepage": "https://github.com/metalabel/metalabel-dfos/tree/main/packages/dfos-protocol",
+  "keywords": [
+    "dfos",
+    "protocol",
+    "ed25519",
+    "jws",
+    "did",
+    "verifiable",
+    "identity",
+    "content-addressing",
+    "dag-cbor",
+    "cid",
+    "metalabel"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./crypto": {
+      "import": "./dist/crypto/index.js",
+      "types": "./dist/crypto/index.d.ts"
+    },
+    "./chain": {
+      "import": "./dist/chain/index.js",
+      "types": "./dist/chain/index.d.ts"
+    },
+    "./registry": {
+      "import": "./dist/registry/index.js",
+      "types": "./dist/registry/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "examples",
+    "PROTOCOL.md",
+    "openapi.yaml",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@ipld/dag-cbor": "^9.2.5",
+    "@noble/curves": "^2.0.1",
+    "@noble/hashes": "^2.0.1",
+    "hono": "^4.12.3",
+    "multiformats": "^13.4.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.4",
+    "ajv": "^8.18.0",
+    "ajv-formats": "^3.0.1",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "generate-examples": "vitest run --config vitest.scripts.config.ts",
+    "build": "tsup"
+  }
+}

package/schemas/document-envelope.v1.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.dfos.com/document-envelope/v1",
+  "title": "Document Envelope",
+  "description": "Standard wrapper for content committed to by content chains. The documentCID in a content chain operation is CID(dagCborEncode(envelope)).",
+  "type": "object",
+  "required": ["content", "baseDocumentCID", "createdByDID", "createdAt"],
+  "properties": {
+    "content": {
+      "type": "object",
+      "required": ["$schema"],
+      "properties": {
+        "$schema": {
+          "type": "string",
+          "format": "uri",
+          "description": "URI identifying the JSON Schema that validates this content."
+        }
+      },
+      "description": "Application-defined content payload. Opaque to chains — validated by the schema identified in $schema."
+    },
+    "baseDocumentCID": {
+      "type": ["string", "null"],
+      "description": "CID of the previous document version (edit lineage), or null for the first version."
+    },
+    "createdByDID": {
+      "type": "string",
+      "pattern": "^did:",
+      "description": "DID of the identity that created this document version."
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of document creation."
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/post.v1.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.dfos.com/post/v1",
+  "title": "Post",
+  "description": "A post — the primary content type in DFOS. Covers short posts, long-form posts, comments, and replies via the format discriminator.",
+  "type": "object",
+  "required": ["$schema", "format"],
+  "properties": {
+    "$schema": {
+      "const": "https://schemas.dfos.com/post/v1"
+    },
+    "format": {
+      "type": "string",
+      "enum": ["short-post", "long-post", "comment", "reply"],
+      "description": "Immutable content format — set at creation, never changes. Determines rendering and interaction semantics."
+    },
+    "title": {
+      "type": "string",
+      "description": "Post title. Typically used for long-post format."
+    },
+    "body": {
+      "type": "string",
+      "description": "Post body content."
+    },
+    "cover": {
+      "$ref": "#/$defs/media",
+      "description": "Cover image for the post."
+    },
+    "attachments": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/media" },
+      "description": "Attached media objects."
+    },
+    "topics": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Topic names this post belongs to. Stored as names for portability."
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "media": {
+      "type": "object",
+      "required": ["id"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Opaque media object identifier."
+        },
+        "uri": {
+          "type": "string",
+          "format": "uri",
+          "description": "Optional URI for the media object."
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/profile.v1.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.dfos.com/profile/v1",
+  "title": "Profile",
+  "description": "A profile — the displayable identity for any agent, person, group, or space. Lowest common denominator of a presence in the system.",
+  "type": "object",
+  "required": ["$schema"],
+  "properties": {
+    "$schema": {
+      "const": "https://schemas.dfos.com/profile/v1"
+    },
+    "name": {
+      "type": "string",
+      "description": "Display name."
+    },
+    "description": {
+      "type": "string",
+      "description": "Short bio or description."
+    },
+    "avatar": {
+      "$ref": "#/$defs/media",
+      "description": "Avatar image."
+    },
+    "banner": {
+      "$ref": "#/$defs/media",
+      "description": "Banner image."
+    },
+    "background": {
+      "$ref": "#/$defs/media",
+      "description": "Background image."
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "media": {
+      "type": "object",
+      "required": ["id"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Opaque media object identifier."
+        },
+        "uri": {
+          "type": "string",
+          "format": "uri",
+          "description": "Optional URI for the media object."
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}