Add local auth signer materialization

Author: marcus-pousette

.changeset/local-auth-signer.md

@@ -0,0 +1,6 @@
+---
+'@treecrdt/interface': minor
+'@treecrdt/wa-sqlite': minor
+---
+
+Allow local write auth sessions to annotate materialization events with signer public keys.

packages/treecrdt-sqlite-node/tests/conformance.test.ts

@@ -7,6 +7,7 @@ import {
   runTreecrdtEngineConformanceScenario,
   treecrdtEngineConformanceScenarios,
 } from '@treecrdt/engine-conformance';
+import type { MaterializationEvent } from '@treecrdt/interface/engine';
 import {
   createTreecrdtClient,
   defaultExtensionPath,
@@ -68,9 +69,11 @@ test('sqlite auth-aware local write rolls back on auth failure', async () => {
 
 test('sqlite auth-aware local write emits materialization after auth succeeds', async () => {
   const client = await createNodeEngine({ docId: 'sqlite-auth-local-success' });
-  const events: unknown[] = [];
+  const events: MaterializationEvent[] = [];
   const unsubscribe = client.onMaterialized((event) => events.push(event));
+  const signerPublicKey = Uint8Array.from({ length: 32 }, (_, i) => i + 1);
   const authSession = {
+    signer: { publicKey: signerPublicKey },
     authorizeLocalOps: vi.fn(async () => {
       expect(events).toHaveLength(0);
     }),
@@ -85,6 +88,7 @@ test('sqlite auth-aware local write emits materialization after auth succeeds',
     expect(op.kind.type).toBe('insert');
     expect(authSession.authorizeLocalOps).toHaveBeenCalledTimes(1);
     expect(events).toHaveLength(1);
+    expect(events[0]!.changes[0]!.source?.signer?.publicKey).toEqual(signerPublicKey);
     expect(await client.tree.exists(node)).toBe(true);
     expect(await client.ops.all()).toHaveLength(1);
   } finally {

packages/treecrdt-ts/src/engine.ts

@@ -1,6 +1,10 @@
 import type { Operation, ReplicaId } from './index.js';
 import type { SqliteTreeChildRow, SqliteTreeRow, TreecrdtSqlitePlacement } from './sqlite.js';
 
+export type MaterializationSigner = {
+  publicKey: Uint8Array;
+};
+
 export type MaterializationSource = {
   /**
    * Operation that caused the visible change.
@@ -15,10 +19,8 @@ export type MaterializationSource = {
     /** Lamport timestamp assigned to the operation. */
     lamport: number;
   };
-  /** Future auth metadata for the operation signer, when available. */
-  signer?: {
-    publicKey: Uint8Array;
-  };
+  /** Auth signer metadata for the operation, when available. */
+  signer?: MaterializationSigner;
 };
 
 type ChangeSource = {
@@ -115,7 +117,14 @@ export type WriteOptions = {
 };
 
 export type LocalWriteAuthSession = {
+  /**
+   * Authorizes local ops before they are exposed as committed.
+   *
+   * If the session has signer metadata available, expose it on `signer` so SQLite writers can
+   * annotate materialization events.
+   */
   authorizeLocalOps: (ops: readonly Operation[]) => Promise<unknown>;
+  signer?: MaterializationSigner;
 };
 
 export type LocalWriteOptions = {

packages/treecrdt-ts/src/sqlite.ts

@@ -4,6 +4,7 @@ import type {
   LocalWriteOptions,
   MaterializationEvent,
   MaterializationOutcome,
+  MaterializationSigner,
   MaterializationSource,
 } from './engine.js';
 import {
@@ -85,6 +86,58 @@ function emitLocalOutcome(
     emit?.({ ...outcome, ...(writeId ? { writeIds: [writeId] } : {}) });
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function decodeMaterializationSigner(raw: unknown): MaterializationSigner | undefined {
+  if (!isRecord(raw)) return undefined;
+  const publicKey = raw.publicKey;
+  if (publicKey instanceof Uint8Array) return { publicKey: Uint8Array.from(publicKey) };
+  if (Array.isArray(publicKey)) return { publicKey: Uint8Array.from(publicKey) };
+  return undefined;
+}
+
+function localWriteAuthSigner(
+  authSession: NonNullable<LocalWriteOptions['authSession']>,
+): MaterializationSigner | undefined {
+  return decodeMaterializationSigner(authSession.signer);
+}
+
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i += 1) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
+function annotateOutcomeSigner(
+  outcome: MaterializationOutcome,
+  op: Operation,
+  signer?: MaterializationSigner,
+): MaterializationOutcome {
+  if (!signer) return outcome;
+  const opReplica = replicaIdToBytes(op.meta.id.replica);
+  const opCounter = op.meta.id.counter;
+  return {
+    ...outcome,
+    changes: outcome.changes.map((change) => {
+      const source = change.source;
+      if (!source) return change;
+      if (source.operation.id.counter !== opCounter) return change;
+      if (!bytesEqual(source.operation.id.replica, opReplica)) return change;
+      return {
+        ...change,
+        source: {
+          ...source,
+          signer,
+        },
+      };
+    }),
+  };
+}
+
 const ROOT_NODE_BYTES = nodeIdToBytes16(ROOT_NODE_ID_HEX);
 
 function buildAppendOp(
@@ -639,7 +692,11 @@ export function createTreecrdtSqliteWriter(
       await authSession.authorizeLocalOps([op]);
       await sqliteExec(runner, `RELEASE ${savepoint}`);
       released = true;
-      emitLocalOutcome(outcome, opts.onMaterialized, writeOpts?.writeId);
+      emitLocalOutcome(
+        annotateOutcomeSigner(outcome, op, localWriteAuthSigner(authSession)),
+        opts.onMaterialized,
+        writeOpts?.writeId,
+      );
       return op;
     } catch (err) {
       if (!released) {