@metalabel/dfos-protocol 0.4.0 → 0.5.0

package/PROTOCOL.md

@@ -20,15 +20,16 @@ The protocol is not coupled to the DFOS platform. Any system implementing the sa
 
 ## Protocol Overview
 
-The DFOS protocol has five components:
+The DFOS protocol has six components:
 
-| Component             | Concern                                                                      |
-| --------------------- | ---------------------------------------------------------------------------- |
-| **Crypto core**       | Identity chains + content chains — Ed25519 signatures, JWS tokens, CID links |
-| **Credentials**       | Auth tokens (DID-signed JWT) and VC-JWT credentials for authorization        |
-| **Beacons**           | Signed merkle root announcements — periodic commitment over content sets     |
-| **Countersignatures** | Witness attestation — third-party signatures over existing chain operations  |
-| **Merkle trees**      | SHA-256 binary trees over content IDs — inclusion proofs for beacon roots    |
+| Component             | Concern                                                                         |
+| --------------------- | ------------------------------------------------------------------------------- |
+| **Crypto core**       | Identity chains + content chains — Ed25519 signatures, JWS tokens, CID links    |
+| **Credentials**       | Auth tokens (DID-signed JWT) and VC-JWT credentials for authorization           |
+| **Beacons**           | Signed merkle root announcements — periodic commitment over content sets        |
+| **Artifacts**         | Standalone signed inline documents — immutable, CID-addressable structured data |
+| **Countersignatures** | Standalone witness attestation — signed references to any CID-addressable op    |
+| **Merkle trees**      | SHA-256 binary trees over content IDs — inclusion proofs for beacon roots       |
 
 The crypto core is the trust boundary — everything below it is cryptographically verified. Documents are flat content objects, content-addressed directly: `documentCID = CID(dagCborCanonicalEncode(contentObject))`. What goes inside the content object is application-defined — see the [DFOS Content Model](https://protocol.dfos.com/content-model) for the standard schema library.
 
@@ -126,6 +127,8 @@ The JWS `typ` header uses protocol-specific values (not IANA media types):
 | `did:dfos:identity-op` | Identity chain operations                     |
 | `did:dfos:content-op`  | Content chain operations                      |
 | `did:dfos:beacon`      | Beacon announcements                          |
+| `did:dfos:artifact`    | Standalone signed inline documents            |
+| `did:dfos:countersign` | Standalone witness attestations               |
 | `JWT`                  | Auth tokens (DID-signed relay authentication) |
 | `vc+jwt`               | VC-JWT credentials (W3C VC Data Model v2)     |
 
@@ -584,15 +587,9 @@ typ:          did:dfos:beacon
 cid:          bafyreihholuui7s7ns74iem6ahfxsb472hwogbqd32yrrp5fztc3kxa5qu
 ```
 
-**Witness countersignature** (key 2 signs the same payload — same CID, different kid):
+**Witness countersignature** (a separate identity countersigns the beacon by CID):
 
-```
-kid:          did:dfos:e3vvtck42d4eacdnzvtrn6#key_ez9a874tckr3dv933d3ckd
-typ:          did:dfos:beacon
-cid:          bafyreihholuui7s7ns74iem6ahfxsb472hwogbqd32yrrp5fztc3kxa5qu
-```
-
-Both JWS tokens commit to identical bytes (same CID). The controller/witness distinction is determined at verification time by comparing the `kid` DID to the payload `did`.
+A countersignature is a standalone operation with its own CID and `typ: did:dfos:countersign`. See the [Countersignatures](#countersignatures) section below.
 
 Full JWS tokens are in [`examples/beacon.json`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/examples/beacon.json).
 
@@ -700,22 +697,78 @@ Proof path (from [`examples/merkle-tree.json`](https://github.com/metalabel/dfos
 
 ---
 
+## Artifacts
+
+Artifacts are standalone signed inline documents — immutable, CID-addressable proof plane primitives. Unlike chain operations which extend a sequence, an artifact is a single signed statement with no predecessor or successor.
+
+### Payload
+
+```json
+{
+  "version": 1,
+  "type": "artifact",
+  "did": "did:dfos:...",
+  "content": {
+    "$schema": "https://schemas.dfos.com/profile/v1",
+    "name": "Example"
+  },
+  "createdAt": "2026-03-25T00:00:00.000Z"
+}
+```
+
+The `content` object MUST include a `$schema` string that identifies the artifact's schema. The schema acts as a discriminator — consumers use it to determine how to interpret the artifact's content. Schema names are free-form strings (no protocol-level registry).
+
+### Constraints
+
+- **JWS `typ` header**: `did:dfos:artifact`
+- **Max payload size**: 16384 bytes CBOR-encoded. Protocol constant — not configurable
+- **Immutability**: Once published, an artifact is never updated or replaced
+- **CID-addressable**: Each artifact is addressed by the CID of its CBOR-encoded payload
+
+### Verification
+
+1. JWS signature verification against the signing DID's current key state
+2. CID integrity — `header.cid` matches the CID computed from dag-cbor canonical encoding the raw payload
+3. Payload schema validation — `version`, `type: "artifact"`, `did`, `content` with `$schema`, `createdAt`
+4. Size limit — CBOR-encoded payload does not exceed 16384 bytes
+
+---
+
 ## Countersignatures
 
-A countersignature is a witness attestation — a third-party identity signing the same CID-committed bytes as an existing chain operation. Countersignatures use the same JWS format and `typ` (`did:dfos:content-op`) as the original operation.
+A countersignature is a standalone witness attestation — a signed statement that references a target operation by CID. Each countersignature has its own `typ` header (`did:dfos:countersign`), its own payload, and its own CID distinct from the target.
+
+### Payload
+
+```json
+{
+  "version": 1,
+  "type": "countersign",
+  "did": "did:dfos:witness...",
+  "targetCID": "bafy...",
+  "createdAt": "2026-03-25T00:00:00.000Z"
+}
+```
 
-### Discrimination Rule
+The `did` field is the witness identity — the DID signing the attestation. The `targetCID` references the operation being attested to.
 
-The protocol distinguishes author operations from countersignatures by comparing the `kid` DID in the JWS header to the `did` field in the operation payload:
+### Properties
 
-- **`kid` DID === payload `did`** → author operation (chain operation)
-- **`kid` DID !== payload `did`** → witness countersignature
+- **JWS `typ` header**: `did:dfos:countersign`
+- **Own CID**: Each countersignature has its own CID derived from its own payload, distinct from the target. This avoids the ambiguity of multiple JWS tokens sharing the same CID
+- **Stateless verification**: Signature + CID integrity + payload schema. No chain state required to verify the cryptographic validity of a countersignature
+- **Composable**: The `targetCID` can reference any CID-addressable operation — content ops, beacons, artifacts, identity ops, even other countersignatures
+- **Immutable**: Once published, a countersignature is permanent
 
-### Semantics
+### Verification
 
-A countersignature proves that a witness identity has seen and attested to a specific operation. The witness signs the exact same payload (same CID), but with their own key. The countersignature's JWS header will contain the witness's `kid` (their DID URL), while the payload's `did` field remains the original author's DID.
+1. Decode JWS, verify `typ` is `did:dfos:countersign`
+2. Parse and validate countersign payload (`version`, `type: "countersign"`, `did`, `targetCID`, `createdAt`)
+3. Verify the `kid` DID matches the payload `did` (the witness must sign with their own key)
+4. CID integrity — `header.cid` matches the CID computed from dag-cbor canonical encoding the raw payload
+5. Verify EdDSA JWS signature against the witness's public key
 
-Countersignatures are not part of the chain — they do not have `previousOperationCID` links and do not affect chain state. They are auxiliary attestations stored alongside chain operations.
+Relay-level semantic checks (target exists, witness ≠ author, deduplication) are enforcement concerns, not protocol verification.
 
 ---
 
@@ -741,7 +794,7 @@ Countersignatures are not part of the chain — they do not have `previousOperat
 2. First op must be `type: "create"` — the signer is the chain creator
 3. For each subsequent op: verify `previousOperationCID` matches, verify `createdAt` increasing
 4. Derive the operation CID via dag-cbor canonical encoding. Verify `header.cid` matches the derived CID.
-5. Verify the `kid` DID matches the payload `did` field (mismatches indicate a countersignature, not a chain operation)
+5. Verify the `kid` DID matches the payload `did` field
 6. Resolve `kid` via external key resolver (caller provides)
 7. Verify EdDSA JWS signature
 8. If `enforceAuthorization` is enabled and the signer DID differs from the chain creator: verify the `authorization` field contains a valid `DFOSContentWrite` VC-JWT issued by the creator DID, with `sub` matching the signer, not expired at `op.createdAt`, and `contentId` (if present) matching this chain
@@ -1077,7 +1130,7 @@ Given the artifacts above, verify:
 
 ## Source and Verification
 
-All source lives in [`packages/dfos-protocol/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol) — self-contained, zero monorepo dependencies. 293 checks across 5 languages.
+All source lives in [`packages/dfos-protocol/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol) — self-contained, zero monorepo dependencies. 266 checks across 5 languages.
 
 - [`crypto/ed25519`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/crypto/ed25519.ts) — `createNewEd25519Keypair`, `importEd25519Keypair`, `signPayloadEd25519`, `isValidEd25519Signature`
 - [`crypto/jws`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/crypto/jws.ts) — `createJws`, `verifyJws`, `decodeJwsUnsafe`
@@ -1086,11 +1139,12 @@ All source lives in [`packages/dfos-protocol/`](https://github.com/metalabel/dfo
 - [`crypto/multiformats`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/crypto/multiformats.ts) — `dagCborCanonicalEncode`, `dagCborCanonicalEqual`
 - [`crypto/id`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/crypto/id.ts) — `generateId`, `generateIdNoPrefix`, `isValidId`
 - [`chain/multikey`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/chain/multikey.ts) — `encodeEd25519Multikey`, `decodeMultikey`
-- [`chain/schemas`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/chain/schemas.ts) — `IdentityOperation`, `ContentOperation`, `MultikeyPublicKey`, `VerifiedIdentity`
-- [`chain/identity-chain`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/chain/identity-chain.ts) — `signIdentityOperation`, `verifyIdentityChain`
-- [`chain/content-chain`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/chain/content-chain.ts) — `signContentOperation`, `verifyContentChain`
+- [`chain/schemas`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/chain/schemas.ts) — `IdentityOperation`, `ContentOperation`, `ArtifactPayload`, `CountersignPayload`, `MultikeyPublicKey`, `VerifiedIdentity`
+- [`chain/identity-chain`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/chain/identity-chain.ts) — `signIdentityOperation`, `verifyIdentityChain`, `verifyIdentityExtensionFromTrustedState`
+- [`chain/content-chain`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/chain/content-chain.ts) — `signContentOperation`, `verifyContentChain`, `verifyContentExtensionFromTrustedState`
 - [`chain/derivation`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/chain/derivation.ts) — `deriveChainIdentifier`, `deriveContentId`
 - [`chain/beacon`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/chain/beacon.ts) — `signBeacon`, `verifyBeacon`
+- [`chain/artifact`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/chain/artifact.ts) — `signArtifact`, `verifyArtifact`
 - [`chain/countersign`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/chain/countersign.ts) — `signCountersignature`, `verifyCountersignature`
 - [`credentials/auth-token`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/credentials/auth-token.ts) — `createAuthToken`, `verifyAuthToken`
 - [`credentials/credential`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/credentials/credential.ts) — `createCredential`, `verifyCredential`, `decodeCredentialUnsafe`
@@ -1102,16 +1156,17 @@ All source lives in [`packages/dfos-protocol/`](https://github.com/metalabel/dfo
 
 - [DID Method: `did:dfos`](https://protocol.dfos.com/did-method) — W3C DID method specification for identity chains
 - [Content Model](https://protocol.dfos.com/content-model) — Standard content schemas (post, profile) for document content objects
+- [Web Relay](https://protocol.dfos.com/web-relay) — HTTP relay specification for ingestion, state, and content plane
 
 ### Cross-Language Verification
 
 | Language   | Tests | Source                                                                                               |
 | ---------- | ----- | ---------------------------------------------------------------------------------------------------- |
-| TypeScript | 190   | [`tests/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol/tests)                 |
-| Python     | 59    | [`verify/python/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol/verify/python) |
-| Go         | 15    | [`verify/go/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol/verify/go)         |
-| Rust       | 15    | [`verify/rust/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol/verify/rust)     |
-| Swift      | 14    | [`verify/swift/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol/verify/swift)   |
+| TypeScript | 224   | [`tests/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol/tests)                 |
+| Go         | 18    | [`verify/go/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol/verify/go)         |
+| Rust       | 18    | [`verify/rust/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol/verify/rust)     |
+| Python     | 3     | [`verify/python/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol/verify/python) |
+| Swift      | 3     | [`verify/swift/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol/verify/swift)   |
 
 ---
 

package/README.md

@@ -53,6 +53,19 @@ The `examples/` directory contains deterministic reference fixtures that can be
 - `merkle-tree.json` — 5 content IDs → sorted tree → root, with inclusion proof
 - `beacon.json` — signed merkle root announcement with witness countersignature
 
+## Cross-Language Verification
+
+The `verify/` directory contains independent verification suites that re-derive CIDs and verify signatures from the reference fixtures — proving protocol correctness across implementations:
+
+| Language | Path             | Status  |
+| -------- | ---------------- | ------- |
+| Go       | `verify/go/`     | Passing |
+| Python   | `verify/python/` | Passing |
+| Rust     | `verify/rust/`   | Passing |
+| Swift    | `verify/swift/`  | Passing |
+
+Each suite uses only its language's native Ed25519, dag-cbor, and multihash implementations — no shared code with the TypeScript reference.
+
 ## License
 
 MIT

package/dist/chain/index.d.ts

@@ -113,6 +113,28 @@ declare const BeaconPayload: z.ZodObject<{
     createdAt: z.ZodISODateTime;
 }, z.core.$strict>;
 type BeaconPayload = z.infer<typeof BeaconPayload>;
+/** Max CBOR-encoded payload size for artifacts (bytes) — protocol constant */
+declare const MAX_ARTIFACT_PAYLOAD_SIZE = 16384;
+/** Artifact: standalone signed inline document, immutable, CID-addressable */
+declare const ArtifactPayload: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"artifact">;
+    did: z.ZodString;
+    content: z.ZodObject<{
+        $schema: z.ZodString;
+    }, z.core.$catchall<z.ZodUnknown>>;
+    createdAt: z.ZodISODateTime;
+}, z.core.$strict>;
+type ArtifactPayload = z.infer<typeof ArtifactPayload>;
+/** Countersign: standalone witness attestation referencing a target operation by CID */
+declare const CountersignPayload: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"countersign">;
+    did: z.ZodString;
+    targetCID: z.ZodString;
+    createdAt: z.ZodISODateTime;
+}, z.core.$strict>;
+type CountersignPayload = z.infer<typeof CountersignPayload>;
 
 /** Ed25519 public key multicodec value */
 declare const ED25519_PUB_MULTICODEC = 237;
@@ -172,6 +194,33 @@ declare const verifyIdentityChain: (input: {
     didPrefix: string;
     log: string[];
 }) => Promise<VerifiedIdentity>;
+/**
+ * Verify a single new operation against already-verified identity state
+ *
+ * The caller guarantees that `currentState` was produced by a correct prior
+ * verification (full chain replay or a chain of trusted extensions from a
+ * verified genesis). This function performs one signature verification and one
+ * state transition — constant time regardless of chain length.
+ *
+ * Note: key-ID consistency across the full chain history is NOT checked here.
+ * That invariant is established during genesis verification and maintained by
+ * the protocol's key consistency rules. Periodic full re-verification can
+ * audit this property.
+ */
+declare const verifyIdentityExtensionFromTrustedState: (input: {
+    /** Previously verified identity state */
+    currentState: VerifiedIdentity;
+    /** CID of the most recent operation in the chain */
+    headCID: string;
+    /** createdAt timestamp of the most recent operation */
+    lastCreatedAt: string;
+    /** The new JWS operation to verify */
+    newOp: string;
+}) => Promise<{
+    state: VerifiedIdentity;
+    operationCID: string;
+    createdAt: string;
+}>;
 
 interface VerifiedContentChain {
     /** Content identifier — bare 22-char hash derived from genesis CID */
@@ -227,6 +276,29 @@ declare const verifyContentChain: (input: {
      */
     enforceAuthorization?: boolean;
 }) => Promise<VerifiedContentChain>;
+/**
+ * Verify a single new content operation against already-verified chain state
+ *
+ * Same trust model as verifyIdentityExtensionFromTrustedState — the caller
+ * guarantees `currentState` was correctly verified. One signature verification,
+ * one key resolution, one state transition.
+ */
+declare const verifyContentExtensionFromTrustedState: (input: {
+    /** Previously verified content chain state */
+    currentState: VerifiedContentChain;
+    /** createdAt timestamp of the most recent operation */
+    lastCreatedAt: string;
+    /** The new JWS operation to verify */
+    newOp: string;
+    /** Resolve a kid (DID URL) to the raw Ed25519 public key bytes */
+    resolveKey: (kid: string) => Promise<Uint8Array>;
+    /** Enforce creator-sovereignty authorization (see verifyContentChain) */
+    enforceAuthorization?: boolean;
+}) => Promise<{
+    state: VerifiedContentChain;
+    operationCID: string;
+    createdAt: string;
+}>;
 
 /**
  * Sign a beacon announcement as a JWS
@@ -253,57 +325,60 @@ declare const verifyBeacon: (input: {
     now?: number;
 }) => Promise<VerifiedBeacon>;
 
+interface VerifiedCountersignature {
+    /** CID of this countersign operation (distinct from the target) */
+    countersignCID: string;
+    /** The witness DID (payload.did — the DID that signed this attestation) */
+    witnessDID: string;
+    /** The CID being attested to */
+    targetCID: string;
+}
 /**
- * Sign an existing content operation as a countersignature (witness JWS)
- *
- * The witness signs the same payload as the author, producing a different
- * JWS token with their own kid. The CID is identical because the payload
- * is identical.
+ * Sign a countersignature attesting to a target operation by CID
  */
 declare const signCountersignature: (input: {
-    /** The original operation payload (must include did of the author) */
-    operationPayload: ContentOperation;
-    /** Witness signer */
+    payload: CountersignPayload;
     signer: Signer;
-    /** Witness kid — DID URL of the witness (must differ from payload.did) */
     kid: string;
 }) => Promise<{
     jwsToken: string;
-    operationCID: string;
+    countersignCID: string;
 }>;
-interface VerifiedCountersignature {
-    operationCID: string;
-    /** The DID that authored the operation (payload.did) */
-    authorDID: string;
-    /** The DID that witnessed the operation (kid DID) */
-    witnessDID: string;
-}
 /**
- * Verify a countersignature JWS against an expected operation CID
+ * Verify a countersignature JWS — stateless verification
  *
- * Checks: valid signature, CID matches, kid DID differs from payload did
+ * Checks: valid signature, CID integrity, payload schema. Does NOT check
+ * whether the target exists or whether the witness differs from the target
+ * author — those are relay-level semantic checks.
  */
 declare const verifyCountersignature: (input: {
     jwsToken: string;
-    expectedCID: string;
     resolveKey: (kid: string) => Promise<Uint8Array>;
 }) => Promise<VerifiedCountersignature>;
-interface VerifiedBeaconCountersignature {
-    beaconCID: string;
-    /** The DID that controls the beacon (payload.did) */
-    controllerDID: string;
-    /** The DID that witnessed the beacon (kid DID) */
-    witnessDID: string;
+
+interface VerifiedArtifact {
+    payload: ArtifactPayload;
+    artifactCID: string;
 }
 /**
- * Verify a beacon countersignature JWS against an expected beacon CID
+ * Sign an artifact as a JWS
  *
- * Checks: valid signature, CID matches, kid DID differs from payload did
+ * Enforces the protocol size limit on the CBOR-encoded payload.
+ */
+declare const signArtifact: (input: {
+    payload: ArtifactPayload;
+    signer: Signer;
+    kid: string;
+}) => Promise<{
+    jwsToken: string;
+    artifactCID: string;
+}>;
+/**
+ * Verify an artifact JWS — signature, CID, payload schema, size limit
  */
-declare const verifyBeaconCountersignature: (input: {
+declare const verifyArtifact: (input: {
     jwsToken: string;
-    expectedCID: string;
     resolveKey: (kid: string) => Promise<Uint8Array>;
-}) => Promise<VerifiedBeaconCountersignature>;
+}) => Promise<VerifiedArtifact>;
 
-export { BeaconPayload, ContentOperation, ED25519_PRIV_MULTICODEC, ED25519_PUB_MULTICODEC, IdentityOperation, MultikeyPublicKey, type Signer, type VerifiedBeacon, type VerifiedBeaconCountersignature, type VerifiedContentChain, type VerifiedCountersignature, VerifiedIdentity, decodeMultikey, deriveChainIdentifier, deriveContentId, encodeEd25519Multikey, signBeacon, signContentOperation, signCountersignature, signIdentityOperation, verifyBeacon, verifyBeaconCountersignature, verifyContentChain, verifyCountersignature, verifyIdentityChain };
+export { ArtifactPayload, BeaconPayload, ContentOperation, CountersignPayload, ED25519_PRIV_MULTICODEC, ED25519_PUB_MULTICODEC, IdentityOperation, MAX_ARTIFACT_PAYLOAD_SIZE, MultikeyPublicKey, type Signer, type VerifiedArtifact, type VerifiedBeacon, type VerifiedContentChain, type VerifiedCountersignature, VerifiedIdentity, decodeMultikey, deriveChainIdentifier, deriveContentId, encodeEd25519Multikey, signArtifact, signBeacon, signContentOperation, signCountersignature, signIdentityOperation, verifyArtifact, verifyBeacon, verifyContentChain, verifyContentExtensionFromTrustedState, verifyCountersignature, verifyIdentityChain, verifyIdentityExtensionFromTrustedState };

package/dist/chain/index.js

@@ -1,46 +1,58 @@
 import {
+  ArtifactPayload,
   BeaconPayload,
   ContentOperation,
+  CountersignPayload,
   ED25519_PRIV_MULTICODEC,
   ED25519_PUB_MULTICODEC,
   IdentityOperation,
+  MAX_ARTIFACT_PAYLOAD_SIZE,
   MultikeyPublicKey,
   VerifiedIdentity,
   decodeMultikey,
   deriveChainIdentifier,
   deriveContentId,
   encodeEd25519Multikey,
+  signArtifact,
   signBeacon,
   signContentOperation,
   signCountersignature,
   signIdentityOperation,
+  verifyArtifact,
   verifyBeacon,
-  verifyBeaconCountersignature,
   verifyContentChain,
+  verifyContentExtensionFromTrustedState,
   verifyCountersignature,
-  verifyIdentityChain
-} from "../chunk-GEVJ3SEV.js";
+  verifyIdentityChain,
+  verifyIdentityExtensionFromTrustedState
+} from "../chunk-QKHP7UVL.js";
 import "../chunk-CZSEEZLL.js";
 import "../chunk-ZXXP5W5N.js";
 export {
+  ArtifactPayload,
   BeaconPayload,
   ContentOperation,
+  CountersignPayload,
   ED25519_PRIV_MULTICODEC,
   ED25519_PUB_MULTICODEC,
   IdentityOperation,
+  MAX_ARTIFACT_PAYLOAD_SIZE,
   MultikeyPublicKey,
   VerifiedIdentity,
   decodeMultikey,
   deriveChainIdentifier,
   deriveContentId,
   encodeEd25519Multikey,
+  signArtifact,
   signBeacon,
   signContentOperation,
   signCountersignature,
   signIdentityOperation,
+  verifyArtifact,
   verifyBeacon,
-  verifyBeaconCountersignature,
   verifyContentChain,
+  verifyContentExtensionFromTrustedState,
   verifyCountersignature,
-  verifyIdentityChain
+  verifyIdentityChain,
+  verifyIdentityExtensionFromTrustedState
 };

package/dist/{chunk-GEVJ3SEV.js → chunk-QKHP7UVL.js}

@@ -104,6 +104,23 @@ var BeaconPayload = z.strictObject({
   merkleRoot: z.string().regex(/^[0-9a-f]{64}$/),
   createdAt: Iso8601
 });
+var MAX_SCHEMA = 256;
+var MAX_ARTIFACT_PAYLOAD_SIZE = 16384;
+var ArtifactContent = z.object({ $schema: z.string().max(MAX_SCHEMA) }).catchall(z.unknown());
+var ArtifactPayload = z.strictObject({
+  version: z.literal(1),
+  type: z.literal("artifact"),
+  did: z.string().max(MAX_DID),
+  content: ArtifactContent,
+  createdAt: Iso8601
+});
+var CountersignPayload = z.strictObject({
+  version: z.literal(1),
+  type: z.literal("countersign"),
+  did: z.string().max(MAX_DID),
+  targetCID: CIDString,
+  createdAt: Iso8601
+});
 
 // src/chain/multikey.ts
 import { base58btc } from "multiformats/bases/base58";
@@ -299,6 +316,78 @@ var verifyIdentityChain = async (input) => {
     controllerKeys: state.controllerKeys
   };
 };
+var verifyIdentityExtensionFromTrustedState = async (input) => {
+  const { currentState, headCID, lastCreatedAt, newOp } = input;
+  if (currentState.isDeleted) {
+    throw new Error("cannot extend a deleted identity");
+  }
+  const decoded = decodeJwsUnsafe(newOp);
+  if (!decoded) throw new Error("failed to decode JWS");
+  const result = IdentityOperation.safeParse(decoded.payload);
+  if (!result.success) {
+    const messages = result.error.issues.map((e) => e.message).join(", ");
+    throw new Error(messages);
+  }
+  const op = result.data;
+  if (decoded.header.typ !== "did:dfos:identity-op") {
+    throw new Error(`invalid typ: ${decoded.header.typ}`);
+  }
+  if (op.type === "create") {
+    throw new Error("extension cannot be a create operation");
+  }
+  if (op.previousOperationCID !== headCID) {
+    throw new Error("previousCID is incorrect");
+  }
+  if (op.createdAt <= lastCreatedAt) {
+    throw new Error("createdAt must be after last op");
+  }
+  const encoded = await dagCborCanonicalEncode(op);
+  const operationCID = encoded.cid.toString();
+  if (!decoded.header.cid) throw new Error("missing cid in protected header");
+  if (decoded.header.cid !== operationCID) throw new Error("cid mismatch in protected header");
+  const kid = decoded.header.kid;
+  if (!kid.includes("#")) {
+    throw new Error("non-genesis op kid must be DID URL, got bare key ID");
+  }
+  const hashIdx = kid.indexOf("#");
+  const signingKeyId = kid.substring(hashIdx + 1);
+  const kidDid = kid.substring(0, hashIdx);
+  if (kidDid !== currentState.did) {
+    throw new Error("kid DID does not match identity DID");
+  }
+  const signingKey = currentState.controllerKeys.find((k) => k.id === signingKeyId);
+  if (!signingKey) {
+    throw new Error(`kid references unknown key: ${signingKeyId}`);
+  }
+  const { keyBytes } = decodeMultikey(signingKey.publicKeyMultibase);
+  try {
+    verifyJws({ token: newOp, publicKey: keyBytes });
+  } catch {
+    throw new Error("invalid signature");
+  }
+  if (op.type === "update") {
+    [op.authKeys, op.assertKeys, op.controllerKeys].forEach((keys) => {
+      const set = new Set(keys.map((k) => k.id));
+      if (set.size !== keys.length) {
+        throw new Error("cannot repeat key ids in same usage");
+      }
+    });
+  }
+  const newState = op.type === "update" ? {
+    did: currentState.did,
+    isDeleted: false,
+    authKeys: op.authKeys,
+    assertKeys: op.assertKeys,
+    controllerKeys: op.controllerKeys
+  } : {
+    did: currentState.did,
+    isDeleted: true,
+    authKeys: currentState.authKeys,
+    assertKeys: currentState.assertKeys,
+    controllerKeys: currentState.controllerKeys
+  };
+  return { state: newState, operationCID, createdAt: op.createdAt };
+};
 
 // src/chain/content-chain.ts
 var signContentOperation = async (input) => {
@@ -447,6 +536,98 @@ var verifyContentChain = async (input) => {
     creatorDID: state.creatorDID
   };
 };
+var verifyContentExtensionFromTrustedState = async (input) => {
+  const { currentState, lastCreatedAt, newOp, resolveKey } = input;
+  if (currentState.isDeleted) {
+    throw new Error("cannot extend a deleted chain");
+  }
+  const decoded = decodeJwsUnsafe(newOp);
+  if (!decoded) throw new Error("failed to decode JWS");
+  const result = ContentOperation.safeParse(decoded.payload);
+  if (!result.success) {
+    const messages = result.error.issues.map((e) => e.message).join(", ");
+    throw new Error(messages);
+  }
+  const op = result.data;
+  if (decoded.header.typ !== "did:dfos:content-op") {
+    throw new Error(`invalid typ: ${decoded.header.typ}`);
+  }
+  if (op.type === "create") {
+    throw new Error("extension cannot be a create operation");
+  }
+  if (op.previousOperationCID !== currentState.headCID) {
+    throw new Error("previousOperationCID is incorrect");
+  }
+  if (op.createdAt <= lastCreatedAt) {
+    throw new Error("createdAt must be after last op");
+  }
+  const kid = decoded.header.kid;
+  const hashIdx = kid.indexOf("#");
+  if (hashIdx < 0) throw new Error("kid must be a DID URL");
+  const kidDid = kid.substring(0, hashIdx);
+  if (kidDid !== op.did) {
+    throw new Error("kid DID does not match operation did");
+  }
+  const publicKey = await resolveKey(kid);
+  try {
+    verifyJws({ token: newOp, publicKey });
+  } catch {
+    throw new Error("invalid signature");
+  }
+  if (op.did !== currentState.creatorDID && input.enforceAuthorization) {
+    const authorization = op.authorization;
+    if (!authorization) {
+      throw new Error(`signer ${op.did} is not the chain creator \u2014 authorization VC required`);
+    }
+    const vcDecoded = decodeCredentialUnsafe(authorization);
+    if (!vcDecoded) throw new Error("failed to decode authorization VC");
+    const vcKid = vcDecoded.header.kid;
+    if (!vcKid || !vcKid.includes("#")) {
+      throw new Error("authorization VC kid must be a DID URL");
+    }
+    let creatorPublicKey;
+    try {
+      creatorPublicKey = await resolveKey(vcKid);
+    } catch {
+      throw new Error("cannot resolve creator key for authorization verification");
+    }
+    const opCreatedAtUnix = Math.floor(new Date(op.createdAt).getTime() / 1e3);
+    try {
+      const credential = verifyCredential({
+        token: authorization,
+        publicKey: creatorPublicKey,
+        subject: op.did,
+        expectedType: VC_TYPE_CONTENT_WRITE,
+        currentTime: opCreatedAtUnix
+      });
+      if (credential.iss !== currentState.creatorDID) {
+        throw new Error("VC issuer is not the chain creator");
+      }
+      if (credential.contentId && credential.contentId !== currentState.contentId) {
+        throw new Error(
+          `VC contentId ${credential.contentId} does not match chain ${currentState.contentId}`
+        );
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "unknown error";
+      throw new Error(`authorization verification failed: ${message}`);
+    }
+  }
+  const encoded = await dagCborCanonicalEncode(op);
+  const operationCID = encoded.cid.toString();
+  if (!decoded.header.cid) throw new Error("missing cid in protected header");
+  if (decoded.header.cid !== operationCID) throw new Error("cid mismatch in protected header");
+  const newState = {
+    contentId: currentState.contentId,
+    genesisCID: currentState.genesisCID,
+    headCID: operationCID,
+    isDeleted: op.type === "delete",
+    currentDocumentCID: op.type === "update" ? op.documentCID : null,
+    length: currentState.length + 1,
+    creatorDID: currentState.creatorDID
+  };
+  return { state: newState, operationCID, createdAt: op.createdAt };
+};
 
 // src/chain/beacon.ts
 var signBeacon = async (input) => {
@@ -499,92 +680,102 @@ var verifyBeacon = async (input) => {
 
 // src/chain/countersign.ts
 var signCountersignature = async (input) => {
-  const encoded = await dagCborCanonicalEncode(input.operationPayload);
-  const operationCID = encoded.cid.toString();
+  const encoded = await dagCborCanonicalEncode(input.payload);
+  const countersignCID = encoded.cid.toString();
   const jwsToken = await createJws({
-    header: { alg: "EdDSA", typ: "did:dfos:content-op", kid: input.kid, cid: operationCID },
-    payload: input.operationPayload,
+    header: { alg: "EdDSA", typ: "did:dfos:countersign", kid: input.kid, cid: countersignCID },
+    payload: input.payload,
     sign: input.signer
   });
-  return { jwsToken, operationCID };
+  return { jwsToken, countersignCID };
 };
 var verifyCountersignature = async (input) => {
   const decoded = decodeJwsUnsafe(input.jwsToken);
   if (!decoded) throw new Error("failed to decode countersignature JWS");
-  if (decoded.header.typ !== "did:dfos:content-op") {
+  if (decoded.header.typ !== "did:dfos:countersign") {
     throw new Error(`invalid countersignature typ: ${decoded.header.typ}`);
   }
-  const result = ContentOperation.safeParse(decoded.payload);
+  const result = CountersignPayload.safeParse(decoded.payload);
   if (!result.success) {
     const messages = result.error.issues.map((e) => e.message).join(", ");
-    throw new Error(`invalid operation payload: ${messages}`);
-  }
-  const op = result.data;
-  const encoded = await dagCborCanonicalEncode(op);
-  const operationCID = encoded.cid.toString();
-  if (operationCID !== input.expectedCID) {
-    throw new Error("countersignature CID does not match expected CID");
-  }
-  if (decoded.header.cid !== operationCID) {
-    throw new Error("countersignature header cid mismatch");
+    throw new Error(`invalid countersignature payload: ${messages}`);
   }
+  const payload = result.data;
   const kid = decoded.header.kid;
+  const hashIdx = kid.indexOf("#");
+  if (hashIdx < 0) throw new Error("countersignature kid must be a DID URL");
+  const kidDid = kid.substring(0, hashIdx);
+  if (kidDid !== payload.did) {
+    throw new Error("countersignature kid DID does not match payload did");
+  }
   const publicKey = await input.resolveKey(kid);
   try {
     verifyJws({ token: input.jwsToken, publicKey });
   } catch {
-    throw new Error("invalid countersignature");
-  }
-  const hashIdx = kid.indexOf("#");
-  if (hashIdx < 0) throw new Error("countersignature kid must be a DID URL");
-  const witnessDID = kid.substring(0, hashIdx);
-  if (witnessDID === op.did) {
-    throw new Error("countersignature kid DID must differ from operation did (not a witness)");
+    throw new Error("invalid countersignature signature");
   }
+  const encoded = await dagCborCanonicalEncode(decoded.payload);
+  const countersignCID = encoded.cid.toString();
+  if (!decoded.header.cid) throw new Error("missing cid in countersignature header");
+  if (decoded.header.cid !== countersignCID) throw new Error("countersignature cid mismatch");
   return {
-    operationCID,
-    authorDID: op.did,
-    witnessDID
+    countersignCID,
+    witnessDID: payload.did,
+    targetCID: payload.targetCID
   };
 };
-var verifyBeaconCountersignature = async (input) => {
-  const decoded = decodeJwsUnsafe(input.jwsToken);
-  if (!decoded) throw new Error("failed to decode beacon countersignature JWS");
-  if (decoded.header.typ !== "did:dfos:beacon") {
-    throw new Error(`invalid beacon countersignature typ: ${decoded.header.typ}`);
+
+// src/chain/artifact.ts
+var signArtifact = async (input) => {
+  const encoded = await dagCborCanonicalEncode(input.payload);
+  const artifactCID = encoded.cid.toString();
+  if (encoded.bytes.length > MAX_ARTIFACT_PAYLOAD_SIZE) {
+    throw new Error(
+      `artifact payload exceeds max size: ${encoded.bytes.length} > ${MAX_ARTIFACT_PAYLOAD_SIZE}`
+    );
   }
-  const result = BeaconPayload.safeParse(decoded.payload);
+  const jwsToken = await createJws({
+    header: { alg: "EdDSA", typ: "did:dfos:artifact", kid: input.kid, cid: artifactCID },
+    payload: input.payload,
+    sign: input.signer
+  });
+  return { jwsToken, artifactCID };
+};
+var verifyArtifact = async (input) => {
+  const decoded = decodeJwsUnsafe(input.jwsToken);
+  if (!decoded) throw new Error("failed to decode artifact JWS");
+  const result = ArtifactPayload.safeParse(decoded.payload);
   if (!result.success) {
     const messages = result.error.issues.map((e) => e.message).join(", ");
-    throw new Error(`invalid beacon payload: ${messages}`);
+    throw new Error(`invalid artifact payload: ${messages}`);
   }
-  const beacon = result.data;
-  const encoded = await dagCborCanonicalEncode(beacon);
-  const beaconCID = encoded.cid.toString();
-  if (beaconCID !== input.expectedCID) {
-    throw new Error("beacon countersignature CID does not match expected CID");
-  }
-  if (decoded.header.cid !== beaconCID) {
-    throw new Error("beacon countersignature header cid mismatch");
+  const payload = result.data;
+  if (decoded.header.typ !== "did:dfos:artifact") {
+    throw new Error(`invalid artifact typ: ${decoded.header.typ}`);
   }
   const kid = decoded.header.kid;
+  const hashIdx = kid.indexOf("#");
+  if (hashIdx < 0) throw new Error("artifact kid must be a DID URL");
+  const kidDid = kid.substring(0, hashIdx);
+  if (kidDid !== payload.did) {
+    throw new Error("artifact kid DID does not match payload did");
+  }
   const publicKey = await input.resolveKey(kid);
   try {
     verifyJws({ token: input.jwsToken, publicKey });
   } catch {
-    throw new Error("invalid beacon countersignature");
+    throw new Error("invalid artifact signature");
   }
-  const hashIdx = kid.indexOf("#");
-  if (hashIdx < 0) throw new Error("beacon countersignature kid must be a DID URL");
-  const witnessDID = kid.substring(0, hashIdx);
-  if (witnessDID === beacon.did) {
-    throw new Error("beacon countersignature kid DID must differ from beacon did (not a witness)");
+  const encoded = await dagCborCanonicalEncode(decoded.payload);
+  const artifactCID = encoded.cid.toString();
+  if (!decoded.header.cid) throw new Error("missing cid in artifact header");
+  if (decoded.header.cid !== artifactCID) throw new Error("artifact cid mismatch");
+  if (encoded.bytes.length > MAX_ARTIFACT_PAYLOAD_SIZE) {
+    throw new Error(
+      `artifact payload exceeds max size: ${encoded.bytes.length} > ${MAX_ARTIFACT_PAYLOAD_SIZE}`
+    );
   }
-  return {
-    beaconCID,
-    controllerDID: beacon.did,
-    witnessDID
-  };
+  return { payload, artifactCID };
 };
 
 export {
@@ -593,6 +784,9 @@ export {
   VerifiedIdentity,
   ContentOperation,
   BeaconPayload,
+  MAX_ARTIFACT_PAYLOAD_SIZE,
+  ArtifactPayload,
+  CountersignPayload,
   ED25519_PUB_MULTICODEC,
   ED25519_PRIV_MULTICODEC,
   encodeEd25519Multikey,
@@ -601,11 +795,14 @@ export {
   deriveContentId,
   signIdentityOperation,
   verifyIdentityChain,
+  verifyIdentityExtensionFromTrustedState,
   signContentOperation,
   verifyContentChain,
+  verifyContentExtensionFromTrustedState,
   signBeacon,
   verifyBeacon,
   signCountersignature,
   verifyCountersignature,
-  verifyBeaconCountersignature
+  signArtifact,
+  verifyArtifact
 };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { JwsHeader, JwsVerificationError, JwtClaims, JwtCreateOptions, JwtHeader, JwtVerificationError, JwtVerifyOptions, PrefixedID, base64urlDecode, base64urlEncode, createJws, createJwt, createNewEd25519Keypair, dagCborCanonicalEncode, decodeJwsUnsafe, decodeJwtUnsafe, generateId, generateIdNoPrefix, importEd25519Keypair, isCanonicallyEqual, isValidEd25519Signature, isValidId, normalizedId, parseDagCborCID, signPayloadEd25519, verifyJws, verifyJwt } from './crypto/index.js';
-export { BeaconPayload, ContentOperation, ED25519_PRIV_MULTICODEC, ED25519_PUB_MULTICODEC, IdentityOperation, MultikeyPublicKey, Signer, VerifiedBeacon, VerifiedBeaconCountersignature, VerifiedContentChain, VerifiedCountersignature, VerifiedIdentity, decodeMultikey, deriveChainIdentifier, deriveContentId, encodeEd25519Multikey, signBeacon, signContentOperation, signCountersignature, signIdentityOperation, verifyBeacon, verifyBeaconCountersignature, verifyContentChain, verifyCountersignature, verifyIdentityChain } from './chain/index.js';
+export { ArtifactPayload, BeaconPayload, ContentOperation, CountersignPayload, ED25519_PRIV_MULTICODEC, ED25519_PUB_MULTICODEC, IdentityOperation, MAX_ARTIFACT_PAYLOAD_SIZE, MultikeyPublicKey, Signer, VerifiedArtifact, VerifiedBeacon, VerifiedContentChain, VerifiedCountersignature, VerifiedIdentity, decodeMultikey, deriveChainIdentifier, deriveContentId, encodeEd25519Multikey, signArtifact, signBeacon, signContentOperation, signCountersignature, signIdentityOperation, verifyArtifact, verifyBeacon, verifyContentChain, verifyContentExtensionFromTrustedState, verifyCountersignature, verifyIdentityChain, verifyIdentityExtensionFromTrustedState } from './chain/index.js';
 export { MerkleProof, buildMerkleTree, generateMerkleProof, hashLeaf, hexToBytes, verifyMerkleProof } from './merkle/index.js';
 export { AuthTokenClaims, AuthTokenCreateOptions, AuthTokenVerificationError, AuthTokenVerifyOptions, ContentReadSubject, ContentWriteSubject, CredentialClaims, CredentialCreateOptions, CredentialVerificationError, CredentialVerifyOptions, DFOSCredentialType, VCClaim, VC_TYPE_CONTENT_READ, VC_TYPE_CONTENT_WRITE, VerifiedAuthToken, VerifiedCredential, createAuthToken, createCredential, decodeCredentialUnsafe, verifyAuthToken, verifyCredential } from './credentials/index.js';
 import 'multiformats';

package/dist/index.js

@@ -1,25 +1,31 @@
 import {
+  ArtifactPayload,
   BeaconPayload,
   ContentOperation,
+  CountersignPayload,
   ED25519_PRIV_MULTICODEC,
   ED25519_PUB_MULTICODEC,
   IdentityOperation,
+  MAX_ARTIFACT_PAYLOAD_SIZE,
   MultikeyPublicKey,
   VerifiedIdentity,
   decodeMultikey,
   deriveChainIdentifier,
   deriveContentId,
   encodeEd25519Multikey,
+  signArtifact,
   signBeacon,
   signContentOperation,
   signCountersignature,
   signIdentityOperation,
+  verifyArtifact,
   verifyBeacon,
-  verifyBeaconCountersignature,
   verifyContentChain,
+  verifyContentExtensionFromTrustedState,
   verifyCountersignature,
-  verifyIdentityChain
-} from "./chunk-GEVJ3SEV.js";
+  verifyIdentityChain,
+  verifyIdentityExtensionFromTrustedState
+} from "./chunk-QKHP7UVL.js";
 import {
   buildMerkleTree,
   generateMerkleProof,
@@ -68,12 +74,14 @@ import {
   verifyJwt
 } from "./chunk-ZXXP5W5N.js";
 export {
+  ArtifactPayload,
   AuthTokenClaims,
   AuthTokenVerificationError,
   BeaconPayload,
   ContentOperation,
   ContentReadSubject,
   ContentWriteSubject,
+  CountersignPayload,
   CredentialClaims,
   CredentialVerificationError,
   DFOSCredentialType,
@@ -82,6 +90,7 @@ export {
   IdentityOperation,
   JwsVerificationError,
   JwtVerificationError,
+  MAX_ARTIFACT_PAYLOAD_SIZE,
   MultikeyPublicKey,
   VCClaim,
   VC_TYPE_CONTENT_READ,
@@ -114,18 +123,21 @@ export {
   isValidId,
   normalizedId,
   parseDagCborCID,
+  signArtifact,
   signBeacon,
   signContentOperation,
   signCountersignature,
   signIdentityOperation,
   signPayloadEd25519,
+  verifyArtifact,
   verifyAuthToken,
   verifyBeacon,
-  verifyBeaconCountersignature,
   verifyContentChain,
+  verifyContentExtensionFromTrustedState,
   verifyCountersignature,
   verifyCredential,
   verifyIdentityChain,
+  verifyIdentityExtensionFromTrustedState,
   verifyJws,
   verifyJwt,
   verifyMerkleProof

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metalabel/dfos-protocol",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "DFOS Protocol — Ed25519 signed chain primitives, beacons, merkle trees, and verification",
   "license": "MIT",
@@ -69,7 +69,7 @@
     "ajv-formats": "^3.0.1",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.0"
   },
   "scripts": {
     "build": "tsup",