dacument 1.0.1 → 1.2.0

package/README.md

@@ -19,10 +19,16 @@ yarn add dacument
 
 ```ts
 import { generateNonce } from "bytecodec";
+import { generateSignPair } from "zeyra";
 import { Dacument } from "dacument";
 
 const actorId = generateNonce(); // 256-bit base64url id
-Dacument.setActorId(actorId);
+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 }),
@@ -93,9 +99,11 @@ doc.acl.setRole("user-viewer", "viewer");
 await doc.flush();
 ```
 
-Before any schema/load/create, call `Dacument.setActorId()` once per process.
-The actor id must be a 256-bit base64url string (e.g. `bytecodec.generateNonce()`).
-Subsequent calls are ignored.
+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` libarys `generateNonce()`), and the actor key pair must be ES256 (P-256).
+Subsequent calls are ignored. On first merge, Dacument auto-attaches the
+actor's `publicKeyJwk` to its own ACL entry (if missing).
 
 Each actor signs with the role key they were given (owner/manager/editor). Load
 with the highest role key you have; viewers load without a key.
@@ -123,7 +131,12 @@ without snapshotting.
 To add a new replica, share a snapshot and load it:
 
 ```ts
-Dacument.setActorId(bobId);
+const bobKeys = await generateSignPair();
+await Dacument.setActorInfo({
+  id: bobId,
+  privateKeyJwk: bobKeys.signingJwk,
+  publicKeyJwk: bobKeys.verificationJwk,
+});
 const bob = await Dacument.load({
   schema,
   roleKey: bobKey.privateKey,
@@ -139,10 +152,42 @@ Snapshots do not include schema or schema ids; callers must supply the schema on
 - `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
+doc id 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: <id>`. 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

package/dist/Dacument/acl.d.ts

@@ -11,6 +11,7 @@ export declare class AclLog {
     roleAt(actorId: string, stamp: AclAssignment["stamp"]): Role;
     currentRole(actorId: string): Role;
     currentEntry(actorId: string): AclAssignment | null;
+    publicKeyAt(actorId: string, stamp: AclAssignment["stamp"]): JsonWebKey | null;
     knownActors(): string[];
     private insert;
 }

package/dist/Dacument/acl.js

@@ -55,6 +55,19 @@ export class AclLog {
     currentEntry(actorId) {
         return this.currentByActor.get(actorId) ?? null;
     }
+    publicKeyAt(actorId, stamp) {
+        const list = this.nodesByActor.get(actorId);
+        if (!list || list.length === 0)
+            return null;
+        for (let index = list.length - 1; index >= 0; index--) {
+            const entry = list[index];
+            if (compareHLC(entry.stamp, stamp) > 0)
+                continue;
+            if (entry.publicKeyJwk)
+                return entry.publicKeyJwk;
+        }
+        return null;
+    }
     knownActors() {
         return [...this.currentByActor.keys()];
     }

package/dist/Dacument/class.d.ts

@@ -1,9 +1,21 @@
-import { type AclAssignment, type DacumentEventMap, type DocFieldAccess, type DocSnapshot, type RoleKeys, type RolePublicKeys, type SchemaDefinition, type SchemaId, type SignedOp, type Role, array, map, record, register, set, text } from "./types.js";
+import { type AclAssignment, type ActorInfo, type DacumentEventMap, type DocFieldAccess, type DocSnapshot, type RoleKeys, type RolePublicKeys, type SchemaDefinition, type SchemaId, type SignedOp, type VerificationResult, type VerifyActorIntegrityOptions, type Role, array, map, record, register, set, text } from "./types.js";
+type ResetStateInfo = {
+    ts: AclAssignment["stamp"];
+    by: string;
+    newDocId: string;
+    reason?: string;
+};
 export declare class Dacument<S extends SchemaDefinition> {
-    private static actorId?;
-    static setActorId(actorId: string): void;
-    private static requireActorId;
+    private static actorInfo?;
+    private static actorSigner?;
+    static setActorInfo(info: ActorInfo): Promise<void>;
+    private static requireActorInfo;
+    private static requireActorSigner;
+    private static signActorToken;
     private static isValidActorId;
+    private static assertActorKeyJwk;
+    private static assertActorPrivateKey;
+    private static assertActorPublicKey;
     static schema: <Schema extends SchemaDefinition>(schema: Schema) => Schema;
     static register: typeof register;
     static text: typeof text;
@@ -38,8 +50,11 @@ export declare class Dacument<S extends SchemaDefinition> {
     private readonly opLog;
     private readonly opTokens;
     private readonly verifiedOps;
+    private readonly opIndexByToken;
+    private readonly actorSigByToken;
     private readonly appliedTokens;
     private currentRole;
+    private resetState;
     private readonly revokedCrdtByField;
     private readonly deleteStampsByField;
     private readonly tombstoneStampsByField;
@@ -49,8 +64,14 @@ export declare class Dacument<S extends SchemaDefinition> {
     private readonly ackByActor;
     private suppressMerge;
     private ackScheduled;
+    private actorKeyPublishPending;
     private lastGcBarrier;
     private snapshotFieldValues;
+    private resetError;
+    private assertNotReset;
+    private currentRoleFor;
+    private roleAt;
+    private recordActorSig;
     readonly acl: {
         setRole: (actorId: string, role: Role) => void;
         getRole: (actorId: string) => Role;
@@ -68,11 +89,23 @@ export declare class Dacument<S extends SchemaDefinition> {
     removeEventListener<K extends keyof DacumentEventMap>(type: K, listener: (event: DacumentEventMap[K]) => void): void;
     flush(): Promise<void>;
     snapshot(): DocSnapshot;
+    getResetState(): ResetStateInfo | null;
+    selfRevoke(): void;
+    accessReset(options?: {
+        reason?: string;
+    }): Promise<{
+        newDoc: DacumentDoc<S>;
+        oldDocOps: SignedOp[];
+        newDocSnapshot: DocSnapshot;
+        roleKeys: RoleKeys;
+    }>;
+    verifyActorIntegrity(options?: VerifyActorIntegrityOptions): Promise<VerificationResult>;
     merge(input: SignedOp | SignedOp[] | string | string[]): Promise<{
         accepted: SignedOp[];
         rejected: number;
     }>;
     private rebuildFromVerified;
+    private maybePublishActorKey;
     private ack;
     private scheduleAck;
     private computeGcBarrier;
@@ -102,6 +135,8 @@ export declare class Dacument<S extends SchemaDefinition> {
     private commitRecordMutation;
     private capturePatches;
     private queueLocalOp;
+    private queueActorOp;
+    private applyResetPayload;
     private applyRemotePayload;
     private applyAclPayload;
     private applyRegisterPayload;
@@ -125,9 +160,11 @@ export declare class Dacument<S extends SchemaDefinition> {
     private recordValue;
     private mapValue;
     private fieldValue;
+    private materializeSchema;
     private emitEvent;
     private emitMerge;
     private emitRevoked;
+    private emitReset;
     private emitError;
     private canWriteField;
     private canWriteAcl;
@@ -140,3 +177,4 @@ export declare class Dacument<S extends SchemaDefinition> {
     private assertSchemaKeys;
 }
 export type DacumentDoc<S extends SchemaDefinition> = Dacument<S> & DocFieldAccess<S>;
+export {};