Dacument

Dacument is a schema-driven CRDT document that signs every operation and
enforces role-based ACLs at merge time. Local writes emit signed ops; state
advances only when ops are merged. It gives you a JS object-like API for
register fields and safe CRDT views for all other field types.

Install

``sh
npm install dacument

or

pnpm add dacument

or

yarn add dacument
`

Quick start

`ts
import { generateNonce } from "bytecodec";
import { generateSignPair } from "zeyra";
import { Dacument } from "dacument";

const actorId = generateNonce(); // 256-bit base64url id
const actorKeys = await generateSignPair();
await Dacument.setActorInfo({
id: actorId,
privateKeyJwk: actorKeys.signingJwk,
publicKeyJwk: actorKeys.verificationJwk,
});

const schema = Dacument.schema({
title: Dacument.register({ jsType: "string", regex: /^[a-z ]+$/i }),
body: Dacument.text(),
items: Dacument.array({ jsType: "string" }),
tags: Dacument.set({ jsType: "string" }),
meta: Dacument.record({ jsType: "string" }),
});

const { docId, snapshot, roleKeys } = await Dacument.create({ schema });

const doc = await Dacument.load({
schema,
roleKey: roleKeys.owner.privateKey,
snapshot,
});

doc.title = "Hello world";
doc.body.insertAt(0, "H");
doc.tags.add("draft");
doc.items.push("milk");

// Wire ops to your transport.
doc.addEventListener("delta", (event) => channel.send(event.ops));
channel.onmessage = (ops) => doc.merge(ops);

doc.addEventListener("merge", ({ actor, target, method, data }) => {
// Update UI from a single merge stream.
});
`

create() returns roleKeys for owner/manager/editor; store them securely and
distribute the highest role key each actor should hold.

Schema and fields

- register fields behave like normal properties: doc.title = "hi".
- Other fields return safe CRDT views: doc.items.push("x").
- Unknown fields or schema bypasses throw.
- UI updates should listen to merge events.

Supported CRDT field types:

- register - last writer wins register.
- text - text RGA.
- array - array RGA.
- set - OR-Set.
- map - OR-Map.
- record - OR-Record.

Map keys must be JSON-compatible values (string, number, boolean, null,
arrays, or objects). For string-keyed data, prefer record. For non-JSON or
identity-based keys, use CRMap with a stable key function.

Roles and ACL

Roles are evaluated at the op stamp time (HLC).

- Owner: full control (including ownership transfer).
- Manager: can grant editor/viewer/revoked roles (cannot change owner).
- Editor: can write non-ACL fields.
- Viewer: read-only.
- Revoked: reads are masked to initial values; writes are rejected.

Grant roles via doc.acl (viewer/revoked have no key):

`ts
const bobId = generateNonce();
doc.acl.setRole(bobId, "editor");
doc.acl.setRole("user-viewer", "viewer");
await doc.flush();
`

Before any schema/load/create, call await Dacument.setActorInfo(...) once per
process. The actor id must be a 256-bit base64url string (e.g.
bytecodec library's generateNonce()), and the actor key pair must be ES256 (P-256).
Updating actor info requires providing the current keys. On first merge, Dacument
auto-attaches the actor's publicKeyJwk to its own ACL entry (if missing) and
pins it for actor-signature verification. To rotate actor keys in-process, call
Dacument.setActorInfo again with the new keys plus
currentPrivateKeyJwk/currentPublicKeyJwk.

Write ops are role-signed; acks are actor-signed with the per-actor key set via
setActorInfo. Load with the highest role key you have; viewers load without a
key. Role keys are generated once at create(); role public keys are embedded
in the snapshot and never rotated.

Networking and sync

Use delta events to relay signed ops, and merge to apply them:

`ts
doc.addEventListener("delta", (event) => send(event.ops));

// on remote
await peer.merge(ops);
`

Local writes do not update state until merged. If you want a single UI update
path, broadcast ops (even back to yourself) and drive UI from merge events.

merge events mirror the confirmed operation parameters (e.g. insertAt,
deleteAt, push, pop, set, add) so UIs can apply minimal updates
without snapshotting.

To add a new replica, share a snapshot and load it:

`ts
const bobKeys = await generateSignPair();
await Dacument.setActorInfo({
id: bobId,
privateKeyJwk: bobKeys.signingJwk,
publicKeyJwk: bobKeys.verificationJwk,
});
const bob = await Dacument.load({
schema,
roleKey: bobKey.privateKey,
snapshot,
});
`

Snapshots do not include the schema or schema ids; callers must supply the schema on load.

Events and values

- doc.addEventListener("delta", handler) emits ops for network sync
(writer ops are role-signed; acks are actor-signed by non-revoked actors and
verified against ACL-pinned actor public keys).
- doc.addEventListener("merge", handler) emits { actor, target, method, data }.
- doc.addEventListener("error", handler) emits signing/verification errors.
- doc.addEventListener("revoked", handler) fires when the current actor is revoked.
- doc.addEventListener("reset", handler) emits { oldDocId, newDocId, ts, by, reason }.
- doc.selfRevoke() emits a signed ACL op that revokes the current actor.
- await doc.accessReset({ reason }) creates a new Dacument with fresh keys and emits a reset op.
- doc.getResetState() returns reset metadata (or null).
- await doc.flush() waits for pending signatures so all local ops are emitted.
- doc.snapshot() returns a loadable op log ({ docId, roleKeys, ops }).
- await doc.verifyActorIntegrity(...) verifies per-actor signatures on demand.
- Revoked actors cannot snapshot; reads are masked to initial values.

Access reset (key compromise response)

If an owner suspects role key compromise, call accessReset() to fork to a new
docId and revoke the old one:

`ts
const { newDoc, oldDocOps, newDocSnapshot, roleKeys } =
await doc.accessReset({ reason: "suspected compromise" });
`

accessReset() materializes the current state into a new Dacument with fresh
role keys, emits a signed reset op for the old doc, and returns the new
snapshot + keys. The reset is stored as a CRDT op so all replicas converge. Once
reset, the old doc rejects any ops after the reset stamp and throws on writes:
Dacument is reset/deprecated. Use newDocId: . Snapshots and verification
still work so you can archive/inspect history.
If an attacker already has the owner key, they can also reset; this is a
response tool for suspected compromise, not a prevention mechanism.

Actor identity (cold path)

Every op may include an actorSig (detached ES256 signature over the op token).
Merges ignore actorSig by default to keep the hot path fast. When you need
attribution or forensic checks, call verifyActorIntegrity() with a token,
ops list, or snapshot. It verifies actorSig against the actor's publicKeyJwk
from the ACL at the op stamp and returns a summary plus failures.

Garbage collection

Dacument tracks per-actor ack ops and compacts tombstones once all non-revoked
actors (including viewers) have acknowledged a given HLC. Acks are emitted
automatically after merges that apply new non-ack ops. Acks are ES256 actor-signed
by non-revoked actors and verified against ACL-pinned actor public keys.
If any non-revoked actor is offline and never acks, tombstones are kept.

Guarantees

- Schema enforcement is strict; unknown fields are rejected.
- Ops are accepted only if the CRDT patch is valid and the role signature
verifies; acks require a valid actor signature.
- Role checks are applied at the op stamp time (HLC).
- IDs are base64url nonces from bytecodec library's generateNonce() (32 random bytes).
- Private keys are returned by create() and never stored by Dacument.
- Snapshots may include ops that are rejected; invalid ops are ignored on load.

Eventual consistency is achieved when all signed ops are delivered to all
replicas. Dacument does not provide transport; use delta events to wire it up.

Possible threats and how to handle

- Role key compromise: role keys cannot be rotated; use accessReset or
snapshot into a new Dacument with fresh keys. Actor keys can be rotated by
providing the current keys.
- Shared role keys: attribution is role-level, not per-user; treat roles as
trust groups and log merge events if you need auditing.
- Insider DoS/flooding: rate-limit ops, cap payload sizes, and monitor merge
errors at the application layer.
- Withholding/delivery delays: eventual consistency depends on ops arriving;
use reliable transport and resync via snapshot when needed.
- No built-in encryption: use TLS or E2E encryption and treat snapshots as
sensitive data.

Compatibility

- ESM only (type: module).
- Requires WebCrypto (node >= 18 or modern browsers).

Scripts

- npm test runs the test suite (build included).
- npm run test:types runs compile-time inference checks.
- npm run test:playwright runs browser/unit/integration/e2e coverage via Playwright.
- npm run bench runs all CRDT micro-benchmarks (build included).
- npm run sim runs a worker-thread stress simulation.
- npm run verify runs tests (including type + Playwright), benchmarks, and the simulation in one go.

Benchmarks

npm run bench prints CRDT timings alongside native structure baselines
(Array/Set/Map/string). Use environment variables like RUNS, SIZE, READS,
WRITES, and MERGE_SIZE to tune scale. Compare the CRDT lines to the native
lines in the output to estimate overhead on your machine. CRDT ops retain
causal metadata and tombstones, so write-heavy paths will be slower than native
structures; the baselines show the relative cost.

Advanced exports

CRArray, CRMap, CRRecord, CRRegister, CRSet, and CRText` are exported
from the package for building custom CRDT workflows.