@metalabel/dfos-protocol 0.15.0 → 0.17.0

package/dist/chunk-XF7T45EQ.js

@@ -0,0 +1,65 @@
+// src/fold/linearize.ts
+var byteCompare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+var compareHeadPreference = (a, b) => {
+  if (a.createdAt !== b.createdAt) return byteCompare(b.createdAt, a.createdAt);
+  return byteCompare(b.cid, a.cid);
+};
+var compareLinear = (a, b) => {
+  if (a.createdAt !== b.createdAt) return byteCompare(a.createdAt, b.createdAt);
+  return byteCompare(a.cid, b.cid);
+};
+var linearize = (ops) => [...ops].sort(compareLinear);
+
+// src/fold/lww-map.ts
+var foldLwwMap = (deltas) => {
+  const map = /* @__PURE__ */ new Map();
+  for (const delta of deltas) {
+    if (delta.op === "set") map.set(delta.key, delta.value);
+    else map.delete(delta.key);
+  }
+  return map;
+};
+
+// src/fold/index-v1.ts
+var INDEX_V1_SCHEMA = "https://schemas.dfos.com/index/v1";
+var isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var parseIndexDelta = (raw) => {
+  if (!isRecord(raw)) return null;
+  const { op, key } = raw;
+  if (typeof key !== "string") return null;
+  if (op === "remove") return { op: "remove", key };
+  if (op === "set") {
+    const value = raw["value"];
+    if (value === void 0) return { op: "set", key };
+    if (!isRecord(value)) return null;
+    return { op: "set", key, value };
+  }
+  return null;
+};
+var indexDeltaStream = (ops) => {
+  const stream = [];
+  for (const op of linearize(ops)) {
+    const doc = op.document;
+    if (!isRecord(doc) || doc["$schema"] !== INDEX_V1_SCHEMA) continue;
+    const deltas = doc["deltas"];
+    if (!Array.isArray(deltas)) continue;
+    for (const raw of deltas) {
+      const delta = parseIndexDelta(raw);
+      if (!delta) continue;
+      if (delta.op === "remove") stream.push({ op: "remove", key: delta.key });
+      else stream.push({ op: "set", key: delta.key, value: delta.value ?? {} });
+    }
+  }
+  return stream;
+};
+var foldIndexV1 = (ops) => foldLwwMap(indexDeltaStream(ops));
+
+export {
+  byteCompare,
+  compareHeadPreference,
+  compareLinear,
+  linearize,
+  foldLwwMap,
+  INDEX_V1_SCHEMA,
+  foldIndexV1
+};

package/dist/fold/index.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Byte-wise (code-point) string comparison returning -1 | 0 | 1.
+ *
+ * NOT `localeCompare` — ICU collation is locale/engine dependent with no
+ * determinism contract. For base32lower CIDs and ASCII ISO-8601 timestamps,
+ * JS `<`/`>` (UTF-16 code-unit order) equals byte-wise order, and equals the
+ * Go relay twin's `<`/`>` on the same strings. This is the single comparison
+ * primitive both head selection and the canonical fold are built on.
+ */
+declare const byteCompare: (a: string, b: string) => number;
+/** The minimum an operation must expose to be ordered: its CID and `createdAt`. */
+interface OrderKey {
+    /** Operation CID — multibase (base32lower) string from the JWS `cid` header. */
+    cid: string;
+    /** ISO-8601 `createdAt` from the operation payload. */
+    createdAt: string;
+}
+/**
+ * Head-preference comparator — the web relay's `selectDeterministicHead` tip
+ * ordering, exported so head selection and the canonical fold cannot drift.
+ *
+ * Sorts the MORE head-preferred operation FIRST: highest `createdAt`, then
+ * highest CID (both byte-wise). `array.sort(compareHeadPreference)[0]` is the
+ * head among a set of tips.
+ */
+declare const compareHeadPreference: (a: OrderKey, b: OrderKey) => number;
+/**
+ * Canonical linearization comparator — the exact reverse of
+ * `compareHeadPreference`. Sorts ascending (lowest `createdAt` first, then
+ * lowest CID), so the head-preferred operation sorts LAST and, under the LWW
+ * fold, is applied last (last-applied wins).
+ */
+declare const compareLinear: (a: OrderKey, b: OrderKey) => number;
+/**
+ * Order a set of operations into the canonical total order — createdAt
+ * ascending, CID ascending tiebreak, branch-inclusive.
+ *
+ * Deterministic regardless of input order: CIDs are unique per operation, so
+ * the order is a strict total order and any permutation of the same operation
+ * set linearizes identically (this is what makes concurrent forks converge).
+ * Returns a new array; the input is not mutated.
+ */
+declare const linearize: <T extends OrderKey>(ops: readonly T[]) => T[];
+
+/** A single LWW-Map delta over key `key`. */
+type LwwDelta<V = unknown> = {
+    readonly op: 'set';
+    readonly key: string;
+    readonly value: V;
+} | {
+    readonly op: 'remove';
+    readonly key: string;
+};
+/**
+ * Fold an ordered sequence of deltas into a Map. Deltas are applied in the
+ * order given — the caller linearizes first. Insertion order of the returned
+ * Map reflects last-set position, but equality is by (key → value) content, so
+ * two ingest orders that linearize identically produce equal maps.
+ */
+declare const foldLwwMap: <V = unknown>(deltas: Iterable<LwwDelta<V>>) => Map<string, V>;
+
+/** Canonical `$schema` URI for index documents. */
+declare const INDEX_V1_SCHEMA = "https://schemas.dfos.com/index/v1";
+/**
+ * An index entry's metadata value. `label` and `order` are the standard hints;
+ * unknown keys are preserved (forward compat). The degenerate set-membership
+ * case is the empty object `{}`.
+ */
+interface IndexEntry {
+    /** Optional display label for the entry. */
+    label?: string;
+    /** Optional ordering hint (integer, per the content number-encoding rule). */
+    order?: number;
+    [k: string]: unknown;
+}
+/** A single index/v1 delta. */
+type IndexDelta = {
+    op: 'set';
+    key: string;
+    value?: IndexEntry;
+} | {
+    op: 'remove';
+    key: string;
+};
+/** An index/v1 document — the content committed by one operation. */
+interface IndexDocument {
+    $schema: string;
+    deltas: IndexDelta[];
+}
+/**
+ * An operation reduced to what the fold needs: its ordering keys plus the
+ * resolved content document. `document` is whatever the operation committed by
+ * CID (an `IndexDocument` for index chains; anything else is skipped).
+ */
+interface FoldOperation extends OrderKey {
+    /** The resolved content document this operation committed (null for delete/clear). */
+    document: unknown;
+}
+/**
+ * Fold a set of index/v1 operations into the resolved index map.
+ *
+ * The fold is branch-INCLUSIVE — pass every operation in the chain's log, not
+ * just the selected-head branch. Concurrent forks converge: any permutation of
+ * the same operation set folds to an equal map.
+ *
+ * Precondition: the chain is not delete-terminal. If the selected head branch
+ * is a `delete`, the chain is deleted and the fold is moot — the caller checks
+ * `isDeleted` (from `verifyContentChain`) and does not fold a deleted chain.
+ */
+declare const foldIndexV1: (ops: readonly FoldOperation[]) => Map<string, IndexEntry>;
+
+export { type FoldOperation, INDEX_V1_SCHEMA, type IndexDelta, type IndexDocument, type IndexEntry, type LwwDelta, type OrderKey, byteCompare, compareHeadPreference, compareLinear, foldIndexV1, foldLwwMap, linearize };

package/dist/fold/index.js

@@ -0,0 +1,18 @@
+import {
+  INDEX_V1_SCHEMA,
+  byteCompare,
+  compareHeadPreference,
+  compareLinear,
+  foldIndexV1,
+  foldLwwMap,
+  linearize
+} from "../chunk-XF7T45EQ.js";
+export {
+  INDEX_V1_SCHEMA,
+  byteCompare,
+  compareHeadPreference,
+  compareLinear,
+  foldIndexV1,
+  foldLwwMap,
+  linearize
+};

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { JwsHeader, JwsVerificationError, JwtClaims, JwtCreateOptions, JwtHeader
 export { A as ARTIFACT_CID_ANCHOR_RE, a as ArtifactPayload, C as CONTENT_ID_ANCHOR_RE, b as ContentOperation, c as CountersignPayload, I as IdentityOperation, M as MAX_ARTIFACT_PAYLOAD_SIZE, d as MAX_OPERATION_SIZE, e as MAX_SERVICES_ENTRIES, f as MAX_SERVICES_PAYLOAD_SIZE, g as MultikeyPublicKey, R as RevocationPayload, S as ServiceEntry, h as ServicesArray, i as Signer, V as VerifiedIdentity } from './schemas-BXye25k7.js';
 export { AnchorKind, ED25519_PRIV_MULTICODEC, ED25519_PUB_MULTICODEC, RECOGNIZED_SERVICE_TYPES, VerifiedArtifact, VerifiedContentChain, VerifiedCountersignature, VerifiedRevocation, anchorsByLabel, assertServicesWithinCap, classifyAnchor, decodeMultikey, deriveChainIdentifier, deriveContentId, encodeEd25519Multikey, isRecognizedServiceType, relayEndpoints, signArtifact, signContentOperation, signCountersignature, signIdentityOperation, signRevocation, verifyArtifact, verifyContentChain, verifyContentExtensionFromTrustedState, verifyCountersignature, verifyIdentityChain, verifyIdentityExtensionFromTrustedState, verifyRevocation } from './chain/index.js';
 export { Attenuation, AuthTokenClaims, AuthTokenCreateOptions, AuthTokenVerificationError, AuthTokenVerifyOptions, CredentialVerificationError, DFOSCredentialPayload, MAX_CREDENTIAL_SIZE, VerifiedAuthToken, VerifiedDFOSCredential, VerifiedDelegationChain, createAuthToken, createDFOSCredential, decodeDFOSCredentialUnsafe, isAttenuated, matchesResource, verifyAuthToken, verifyDFOSCredential, verifyDelegationChain } from './credentials/index.js';
+export { FoldOperation, INDEX_V1_SCHEMA, IndexDelta, IndexDocument, IndexEntry, LwwDelta, OrderKey, byteCompare, compareHeadPreference, compareLinear, foldIndexV1, foldLwwMap, linearize } from './fold/index.js';
 import 'multiformats';
 import 'multiformats/cid';
 import 'zod';

package/dist/index.js

@@ -79,6 +79,15 @@ import {
   verifyJws,
   verifyJwt
 } from "./chunk-4QQ5HK5M.js";
+import {
+  INDEX_V1_SCHEMA,
+  byteCompare,
+  compareHeadPreference,
+  compareLinear,
+  foldIndexV1,
+  foldLwwMap,
+  linearize
+} from "./chunk-XF7T45EQ.js";
 export {
   ARTIFACT_CID_ANCHOR_RE,
   ArtifactPayload,
@@ -92,6 +101,7 @@ export {
   DFOSCredentialPayload,
   ED25519_PRIV_MULTICODEC,
   ED25519_PUB_MULTICODEC,
+  INDEX_V1_SCHEMA,
   IdentityOperation,
   JwsVerificationError,
   JwtVerificationError,
@@ -111,7 +121,10 @@ export {
   assertServicesWithinCap,
   base64urlDecode,
   base64urlEncode,
+  byteCompare,
   classifyAnchor,
+  compareHeadPreference,
+  compareLinear,
   createAuthToken,
   createDFOSCredential,
   createJws,
@@ -125,6 +138,8 @@ export {
   deriveChainIdentifier,
   deriveContentId,
   encodeEd25519Multikey,
+  foldIndexV1,
+  foldLwwMap,
   generateId,
   generateIdNoPrefix,
   importEd25519Keypair,
@@ -133,6 +148,7 @@ export {
   isRecognizedServiceType,
   isValidEd25519Signature,
   isValidId,
+  linearize,
   matchesResource,
   normalizedId,
   parseDagCborCID,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metalabel/dfos-protocol",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "type": "module",
   "description": "DFOS Protocol — Ed25519 signed chain primitives, services, credentials, and verification",
   "license": "MIT",
@@ -40,6 +40,10 @@
     "./credentials": {
       "import": "./dist/credentials/index.js",
       "types": "./dist/credentials/index.d.ts"
+    },
+    "./fold": {
+      "import": "./dist/fold/index.js",
+      "types": "./dist/fold/index.d.ts"
     }
   },
   "files": [

package/schemas/index.v1.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.dfos.com/index/v1",
+  "title": "Index",
+  "description": "An index chain document — an LWW-Map folded via the canonical fold. Each operation's document carries an array of set/remove deltas over content-ref keys. The resolved index is the fold over ALL operations (every branch) in canonical order; the last delta touching a key wins.",
+  "type": "object",
+  "required": ["$schema", "deltas"],
+  "properties": {
+    "$schema": {
+      "const": "https://schemas.dfos.com/index/v1"
+    },
+    "deltas": {
+      "type": "array",
+      "description": "Ordered deltas contributed by this operation. Applied in array order within the document, then across documents in canonical fold order.",
+      "items": {
+        "type": "object",
+        "required": ["op"],
+        "properties": {
+          "op": {
+            "type": "string",
+            "description": "Delta operation. 'set' and 'remove' are the v1 vocabulary; deltas with other ops are valid and are skipped deterministically by readers (forward compat). Validators MUST NOT reject documents carrying additional delta shapes."
+          }
+        },
+        "allOf": [
+          {
+            "if": { "properties": { "op": { "const": "set" } } },
+            "then": {
+              "required": ["key"],
+              "properties": {
+                "key": {
+                  "type": "string",
+                  "description": "Content ref — a 31-char content chain id or a CID."
+                },
+                "value": { "$ref": "#/$defs/entry" }
+              }
+            }
+          },
+          {
+            "if": { "properties": { "op": { "const": "remove" } } },
+            "then": {
+              "required": ["key"],
+              "properties": {
+                "key": {
+                  "type": "string",
+                  "description": "Content ref to drop from the index."
+                }
+              }
+            }
+          }
+        ]
+      }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "entry": {
+      "type": "object",
+      "description": "Optional entry metadata for a set delta. A pure set-membership index uses the degenerate empty object {}. Unknown fields are preserved (forward compat).",
+      "properties": {
+        "label": {
+          "type": "string",
+          "description": "Optional display label."
+        },
+        "order": {
+          "type": "integer",
+          "description": "Optional ordering hint (integer per the content number-encoding rule)."
+        }
+      }
+    }
+  }
+}

package/schemas/profile.v1.json

@@ -17,6 +17,10 @@
       "type": "string",
       "description": "Short bio or description."
     },
+    "avatar": {
+      "$ref": "#/$defs/media",
+      "description": "Optional avatar image as a Media object."
+    },
     "links": {
       "type": "array",
       "maxItems": 20,
@@ -43,5 +47,29 @@
       }
     }
   },
-  "additionalProperties": false
+  "additionalProperties": false,
+  "$defs": {
+    "media": {
+      "type": "object",
+      "required": ["uri"],
+      "properties": {
+        "uri": {
+          "type": "string",
+          "format": "uri",
+          "description": "Canonical reference to the media — an attachment://<id> ref (opaque, host-scoped) or any other URI. Always present."
+        },
+        "cid": {
+          "type": "string",
+          "pattern": "^bafkrei[a-z2-7]{52}$",
+          "description": "Optional content commitment — CIDv1, raw codec (0x55), sha2-256, base32 lowercase, computed over the media bytes exactly as stored/served. May be absent when no cid has been computed for the media."
+        },
+        "href": {
+          "type": "string",
+          "format": "uri",
+          "description": "Optional resolution hint — a plain URL where the bytes may currently be fetched. Implementation-dependent and non-normative; carries no integrity promise."
+        }
+      },
+      "additionalProperties": false
+    }
+  }
 }