fix(auth): bind defensive delete state in v2 signatures

Author: Marcus Pousette

.changeset/authored-at-op-auth-claims.md

@@ -5,4 +5,7 @@
 '@treecrdt/sync-postgres': minor
 ---
 
-Add signed `authoredAtMs` claims to op auth and persist them through sync proof material stores.
+Add opt-in signed `authoredAtMs` claims to op auth and persist them through sync proof material
+stores. Version 2 signatures also bind the operation's defensive-delete `knownState`; the auth
+layer refuses to sign or accept `knownState` under legacy v1 signatures because v1 does not cover
+those causally meaningful bytes.

docs/sync/v0/auth.md

@@ -60,6 +60,7 @@ Each op may carry:
 - `sig`: Ed25519 signature bytes (64 bytes)
 - `proof_ref` (optional but RECOMMENDED): 16-byte reference to the capability token used
   to authorize this op
+- `claims.authored_at_ms` (optional): author-claimed wall-clock time covered by a v2 signature
 
 Rationale:
 
@@ -177,8 +178,10 @@ Ops are signed with the doc-scoped Ed25519 key. The signature covers:
 - `doc_id`
 - `op_id` (`replica_id` + `counter`)
 - `lamport`
+- defensive-delete `known_state` in signature v2
 - op kind + fields
 - payload bytes (ciphertext bytes if payloads are encrypted)
+- v2 auth claims
 
 ### Canonical signing bytes
 
@@ -213,6 +216,26 @@ Kind tags and fields:
   - value_tag(u8): 0=clear, 1=payload
   - if value_tag=1: u32_be(len(payload)) || payload_bytes
 
+Signature v1 predates defensive deletion and does **not** cover `known_state`. It remains supported
+for operations without `known_state`, but MUST NOT be used for a causally aware delete or tombstone.
+
+Signature v2 changes the domain to `"treecrdt/op-sig/v2"` and appends these fields after the v1 op
+fields (without the v1 domain):
+
+```
+known_state = absent:  u8(0)
+              present: u8(1) || u32_be(len(bytes)) || bytes
+
+authored_at = absent:  u8(0)
+              present: u8(1) || u64_be(authored_at_ms)
+```
+
+The reference COSE+CWT auth layer uses the presence of signed claims to distinguish v2 auth. New
+signers therefore keep v1 as the default for rolling-upgrade compatibility. Set
+`includeAuthoredAt: true` only after all verifiers that may receive those operations support v2.
+Until then, signing or verifying an operation with `known_state` fails closed; accepting it as v1
+would allow an untrusted relay to change deletion causality without invalidating the signature.
+
 ## Subtree scope enforcement and `pending_context`
 
 Subtree ACLs require the verifier to answer: “is the node touched by this op within the granted subtree?”

examples/playground/src/playground/hooks/usePlaygroundAuthSession.ts

@@ -128,6 +128,8 @@ export function usePlaygroundAuthSession(
           },
           revokedCapabilityTokenIds: hardRevokedTokenIdBytes,
           requireProofRef: true,
+          // Playground peers ship verifier and signer together, so v2 can be enabled immediately.
+          includeAuthoredAt: true,
           identity: {
             onPeer: onPeerIdentityChain,
             local: getLocalIdentityChain,

packages/treecrdt-auth/src/internal/cose-cwt-auth.ts

@@ -93,7 +93,13 @@ export type TreecrdtCoseCwtAuthOptions = {
   ) => boolean | Promise<boolean>;
   allowUnsigned?: boolean;
   requireProofRef?: boolean;
-  /** Include a signed `claims.authoredAtMs` value on locally authored ops. Defaults to true. */
+  /**
+   * Opt into v2 op signatures and include a signed `claims.authoredAtMs` value.
+   *
+   * Defaults to false so a signer upgrade does not make its operations unreadable to v1-only
+   * verifiers. Upgrade verifiers before enabling this option. Operations with `meta.knownState`
+   * require v2 and fail closed while this option is disabled.
+   */
   includeAuthoredAt?: boolean;
   now?: () => number;
   /** Wall-clock source for authoredAtMs claims. */
@@ -121,7 +127,7 @@ export function createTreecrdtCoseCwtAuth(opts: TreecrdtCoseCwtAuthOptions): Syn
   const nowMs = opts.nowMs ?? (() => Date.now());
   const allowUnsigned = opts.allowUnsigned ?? false;
   const requireProofRef = opts.requireProofRef ?? false;
-  const includeAuthoredAt = opts.includeAuthoredAt ?? true;
+  const includeAuthoredAt = opts.includeAuthoredAt ?? false;
 
   const localTokens = opts.localCapabilityTokens ?? [];
   const localTokenIds = localTokens.map((t) => deriveTokenIdV1(t));
@@ -661,6 +667,11 @@ export function createTreecrdtCoseCwtAuth(opts: TreecrdtCoseCwtAuthOptions): Syn
           });
           proofRef = selected.tokenId;
         }
+        if (op.meta.knownState !== undefined && !includeAuthoredAt) {
+          throw new Error(
+            'refusing to sign meta.knownState with legacy op signature v1; enable includeAuthoredAt only after upgrading verifiers to v2',
+          );
+        }
         const claims = includeAuthoredAt ? { authoredAtMs: nowMs() } : undefined;
         const sig = claims
           ? await signTreecrdtOpV2({
@@ -778,6 +789,10 @@ export function createTreecrdtCoseCwtAuth(opts: TreecrdtCoseCwtAuthOptions): Syn
         });
         if (scopeRes === 'deny') throw new Error('capability does not allow op');
 
+        if (!a.claims && op.meta.knownState !== undefined) {
+          throw new Error('legacy op signature v1 does not authenticate meta.knownState');
+        }
+
         const ok = a.claims
           ? await verifyTreecrdtOpV2({
               docId: ctx.docId,

packages/treecrdt-auth/src/internal/op-sig.ts

@@ -109,6 +109,12 @@ function encodeTreecrdtOpAuthClaimsV1(claims: TreecrdtOpAuthClaimsV1): Uint8Arra
   return concatBytes(...parts);
 }
 
+function encodeTreecrdtOpKnownStateV2(op: Operation): Uint8Array {
+  const knownState = op.meta.knownState;
+  if (knownState === undefined) return u8(0);
+  return concatBytes(u8(1), u32be(knownState.length), knownState);
+}
+
 export function encodeTreecrdtOpSigInputV1(opts: { docId: string; op: Operation }): Uint8Array {
   return concatBytes(OP_SIG_V1_DOMAIN, u8(0), encodeTreecrdtOpFields(opts));
 }
@@ -122,6 +128,7 @@ export function encodeTreecrdtOpSigInputV2(opts: {
     OP_SIG_V2_DOMAIN,
     u8(0),
     encodeTreecrdtOpFields(opts),
+    encodeTreecrdtOpKnownStateV2(opts.op),
     encodeTreecrdtOpAuthClaimsV1(opts.claims),
   );
 }

packages/treecrdt-auth/tests/auth.test.ts

@@ -24,6 +24,7 @@ import {
   issueTreecrdtCapabilityTokenV1,
   issueTreecrdtDelegatedCapabilityTokenV1,
   issueTreecrdtRevocationRecordV1,
+  signTreecrdtOpV1,
   verifyTreecrdtRevocationRecordV1,
 } from '../dist/treecrdt-auth.js';
 import type { Capability, Filter, OpRef, SyncBackend } from '@treecrdt/sync-protocol';
@@ -320,6 +321,8 @@ test('auth: signOps selects proof_ref per op when multiple tokens exist', async
   expect(auth?.length).toBe(2);
   expect(auth?.[0]?.proofRef).toBeTruthy();
   expect(auth?.[1]?.proofRef).toBeTruthy();
+  expect(auth?.[0]?.claims).toBeUndefined();
+  expect(auth?.[1]?.claims).toBeUndefined();
 
   const tokenStructureId = deriveTokenIdV1(tokenStructure);
   const tokenDeleteId = deriveTokenIdV1(tokenDelete);
@@ -335,9 +338,8 @@ test('auth: signOps selects proof_ref per op when multiple tokens exist', async
   );
 });
 
-test('auth: signOps signs authoredAt claims', async () => {
+test('auth: v2 signs authoredAt and defensive-delete knownState', async () => {
   const docId = 'doc-auth-authored-at';
-  const root = '0'.repeat(32);
   const authoredAtMs = 1_700_000_000_123;
 
   const issuerSk = ed25519Utils.randomSecretKey();
@@ -351,7 +353,7 @@ test('auth: signOps signs authoredAt claims', async () => {
     issuerPrivateKey: issuerSk,
     subjectPublicKey: writerPk,
     docId,
-    actions: ['write_structure'],
+    actions: ['delete'],
   });
 
   const authWriter = createTreecrdtCoseCwtAuth({
@@ -360,6 +362,7 @@ test('auth: signOps signs authoredAt claims', async () => {
     localPublicKey: writerPk,
     localCapabilityTokens: [token],
     requireProofRef: true,
+    includeAuthoredAt: true,
     nowMs: () => authoredAtMs,
   });
 
@@ -376,19 +379,54 @@ test('auth: signOps signs authoredAt claims', async () => {
     { docId },
   );
 
-  const op = makeOp(writerPk, 1, 1, {
-    type: 'insert',
-    parent: root,
-    node: nodeIdFromInt(1),
-    orderKey: orderKeyFromPosition(0),
+  const op: Operation = {
+    meta: {
+      id: { replica: writerPk, counter: 1 },
+      lamport: 1,
+      knownState: new Uint8Array([0x01, 0x02, 0x03]),
+    },
+    kind: { type: 'delete', node: nodeIdFromInt(1) },
+  };
+
+  const legacyWriter = createTreecrdtCoseCwtAuth({
+    issuerPublicKeys: [issuerPk],
+    localPrivateKey: writerSk,
+    localPublicKey: writerPk,
+    localCapabilityTokens: [token],
+    requireProofRef: true,
   });
 
   const ctx = { docId, purpose: 'reconcile' as const, filterId: 'all' };
+  await expect(legacyWriter.signOps?.([op], ctx)).rejects.toThrow(
+    /refusing to sign meta\.knownState.*v1/i,
+  );
+
+  const legacySig = await signTreecrdtOpV1({ docId, op, privateKey: writerSk });
+  await expect(
+    authVerifier.verifyOps?.([op], [{ sig: legacySig, proofRef: deriveTokenIdV1(token) }], ctx),
+  ).rejects.toThrow(/v1 does not authenticate meta\.knownState/i);
+
   const auth = await authWriter.signOps?.([op], ctx);
   expect(auth?.[0]?.claims).toEqual({ authoredAtMs });
 
   await expect(authVerifier.verifyOps?.([op], auth, ctx)).resolves.toBeUndefined();
 
+  const mutatedKnownState: Operation = {
+    ...op,
+    meta: { ...op.meta, knownState: new Uint8Array([0x01, 0x02, 0x04]) },
+  };
+  await expect(authVerifier.verifyOps?.([mutatedKnownState], auth, ctx)).rejects.toThrow(
+    /invalid op signature/i,
+  );
+
+  const omittedKnownState: Operation = {
+    ...op,
+    meta: { id: op.meta.id, lamport: op.meta.lamport },
+  };
+  await expect(authVerifier.verifyOps?.([omittedKnownState], auth, ctx)).rejects.toThrow(
+    /invalid op signature/i,
+  );
+
   await expect(
     authVerifier.verifyOps?.(
       [op],
@@ -408,7 +446,7 @@ test('auth: signOps signs authoredAt claims', async () => {
       ],
       ctx,
     ),
-  ).rejects.toThrow(/invalid op signature/i);
+  ).rejects.toThrow(/v1 does not authenticate meta\.knownState/i);
 });
 
 test('auth ignores foreign peer capability tokens during hello and still verifies known authors', async () => {

packages/treecrdt-auth/tests/op-sig.test.ts

@@ -0,0 +1,34 @@
+import { expect, test } from 'vitest';
+
+import type { Operation } from '@treecrdt/interface';
+import { encodeTreecrdtOpSigInputV1, encodeTreecrdtOpSigInputV2 } from '../dist/treecrdt-auth.js';
+
+const DOC_ID = 'doc-vector';
+const CLAIMS = { authoredAtMs: 1_700_000_000_123 };
+
+function hex(value: Uint8Array): string {
+  return Buffer.from(value).toString('hex');
+}
+
+function deleteOp(knownState: Uint8Array | undefined): Operation {
+  const replica = Uint8Array.from({ length: 32 }, (_, index) => index);
+  return {
+    meta: {
+      id: { replica, counter: 9 },
+      lamport: 17,
+      ...(knownState === undefined ? {} : { knownState }),
+    },
+    kind: { type: 'delete', node: '00112233445566778899aabbccddeeff' },
+  };
+}
+
+test('op signature inputs have stable v1 and v2 vectors', () => {
+  const op = deleteOp(new TextEncoder().encode('{"a":1}'));
+
+  expect(hex(encodeTreecrdtOpSigInputV1({ docId: DOC_ID, op }))).toBe(
+    '74726565637264742f6f702d7369672f7631000000000a646f632d766563746f7200000020000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f000000000000000900000000000000110300112233445566778899aabbccddeeff',
+  );
+  expect(hex(encodeTreecrdtOpSigInputV2({ docId: DOC_ID, op, claims: CLAIMS }))).toBe(
+    '74726565637264742f6f702d7369672f7632000000000a646f632d766563746f7200000020000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f000000000000000900000000000000110300112233445566778899aabbccddeeff01000000077b2261223a317d010000018bcfe5687b',
+  );
+});