@doubling/compound-sync 1.14.0 → 1.15.0

package/files.js

@@ -28,6 +28,7 @@ import { doc, getDoc, getDocs, setDoc, updateDoc, deleteDoc, query, where, } fro
 import { ref as storageRef, uploadBytes, deleteObject, getBytes, } from 'firebase/storage';
 import { storagePathFor, extFromPath, contentByteSize, computeContentHash, folderDocId, fileDocId, toBytes, } from './storage-helpers.js';
 import { planFolderChain, splitPath, } from './folder-chain.js';
+import { logOperation } from './operation-log.js';
 // Re-export pure helpers so callers (and existing tests) can import
 // either from here or directly from storage-helpers.js.
 export { storagePathFor, extFromPath, contentByteSize, computeContentHash, isTextMimeType, mimeTypeFromExt, } from './storage-helpers.js';
@@ -173,11 +174,49 @@ export async function pushFolderToCloud({ filesRef, scope, teamId, userId, docPa
     if (scope === 'shared-with-me' || scope === 'shared-by-me') {
         return { action: 'skipped', reason: 'shared-scope' };
     }
+    // Validate userId BEFORE any writes so an audit-only failure
+    // never leaves committed folder docs behind. Firestore rules
+    // require actor.id == request.auth.uid on operationLog creates;
+    // an empty actor id would land as permission-denied AFTER the
+    // folder chain was already created.
+    if (!userId) {
+        throw new Error('pushFolderToCloud: userId is required for audit logging');
+    }
     const folderId = await ensureFolderChainInCloud({
         filesRef, scope, teamId, userId, docPath, now,
     });
+    // Log FolderCreate on any 'ensured' outcome. This is an over-log:
+    // ensureFolderChainInCloud is idempotent, so a call that only
+    // reuses existing folder docs still emits an entry. Introducing a
+    // "was-actually-created" signal requires plumbing through
+    // planFolderChain results; deferred to a follow-up because the
+    // extra rows are small and BQ dedup on op + subject is trivial.
+    if (folderId) {
+        // filesRef points at orgs/{orgId}/files; the parent doc is orgs/{orgId}.
+        const orgId = orgIdFromFilesRef(filesRef);
+        await logOperation({
+            db: filesRef.firestore,
+            orgId,
+            actor: { type: 'user', id: userId },
+            subject: { type: 'folder', id: folderId },
+            opType: 'FolderCreate',
+            path: docPath,
+            outcome: 'success',
+        });
+    }
     return { action: 'ensured', folderId };
 }
+// Derive orgId from a files collection ref. filesRef always points
+// at orgs/{orgId}/files; its parent doc is orgs/{orgId}. Extracted
+// so pushFolderToCloud and deleteFolderFromCloud share a single
+// well-named accessor rather than an inline IIFE.
+function orgIdFromFilesRef(filesRef) {
+    const parent = filesRef.parent;
+    if (!parent) {
+        throw new Error('filesRef has no parent (expected orgs/{orgId}/files)');
+    }
+    return parent.id;
+}
 /**
  * Delete the folder doc at `docPath` AND every descendant (files and
  * sub-folders) in the same scope. Cascade is authoritative: it does
@@ -205,6 +244,15 @@ export async function deleteFolderFromCloud({ filesRef, storage, orgId, scope, t
     if (scope === 'shared-with-me' || scope === 'shared-by-me') {
         return { action: 'skipped', reason: 'shared-scope' };
     }
+    // Validate userId BEFORE any deletes so an audit-only failure
+    // never leaves the cascade committed with no audit trail behind
+    // it. Firestore rules require actor.id == request.auth.uid on
+    // operationLog creates; without the up-front check the descendants
+    // could be deleted and only then would the log emit hit
+    // permission-denied.
+    if (!userId) {
+        throw new Error('deleteFolderFromCloud: userId is required for audit logging');
+    }
     // Pull every doc in this scope; cheap because vaults are small
     // (hundreds of docs at most). Filtering in memory avoids the
     // Firestore composite-index requirement for a path-prefix range
@@ -277,9 +325,44 @@ export async function deleteFolderFromCloud({ filesRef, storage, orgId, scope, t
     if (folderDocSnap) {
         await deleteDoc(folderDocSnap.ref);
     }
+    const deletedFolderId = folderDocSnap ? folderDocSnap.id : null;
+    // Emit a single FolderDelete for the top-level folder OR for the
+    // orphan-cleanup case where descendants existed without a
+    // top-level folder doc (folderDocSnap null but descendants.length
+    // > 0). Both are real mutations and must appear in the audit
+    // trail. When folderDocSnap is null we compute the deterministic
+    // folderDocId as the subject so downstream analytics can still
+    // join on subject.id.
+    //
+    // Cascaded child deletes are NOT logged individually in this
+    // pass; the childCount conveys the cascade blast radius. Per-
+    // child auditing (one FileDelete entry per cascaded file) is
+    // tracked in a follow-up ticket alongside FolderMove.
+    const subjectFolderId = deletedFolderId
+        ?? folderDocId({
+            scope,
+            teamId: scope === 'team' ? (teamId ?? null) : null,
+            ownerId: scope === 'private' ? userId : null,
+            path: docPath,
+        });
+    // userId already validated at the top of the function so no
+    // inner guard needed. orgId is derived from filesRef.parent
+    // instead of the input param so callers that pass a partial
+    // input (older tests without orgId, e.g. delete-empty-folder
+    // cases) still produce valid audit writes; filesRef.parent.id
+    // IS orgId by definition.
+    await logOperation({
+        db: filesRef.firestore,
+        orgId: orgIdFromFilesRef(filesRef),
+        actor: { type: 'user', id: userId },
+        subject: { type: 'folder', id: subjectFolderId },
+        opType: 'FolderDelete',
+        path: docPath,
+        outcome: 'success',
+    });
     return {
         action: 'deleted',
-        folderId: folderDocSnap ? folderDocSnap.id : null,
+        folderId: deletedFolderId,
         childCount: descendants.length,
     };
 }
@@ -385,6 +468,29 @@ export async function pushFileToCloud({ filesRef, storage, orgId, userId, scope,
         catch (err) {
             storageError = err;
         }
+        // Emit-after-mutation (fail-loud): a broken audit emit fails the
+        // surrounding pushFileToCloud call. See DOU-271 §5.1.
+        //
+        // When uploadBlob fails, the Firestore doc is written but the
+        // blob is missing; sync/push-outcome.ts treats this as a partial
+        // failure ("synced with warnings"), so the audit entry mirrors
+        // that: outcome=io_error + captured error object.
+        await logOperation({
+            db: filesRef.firestore,
+            orgId,
+            actor: { type: 'user', id: userId },
+            subject: { type: 'file', id: fileId },
+            opType: 'FileWrite',
+            path: docPath,
+            preContentHash: null,
+            postContentHash: contentHash,
+            sizeBytes: size,
+            outcome: storageError == null ? 'success' : 'io_error',
+            error: storageError == null ? null : {
+                code: storageError?.code ?? 'storage-upload-failed',
+                message: String(storageError),
+            },
+        });
         return { action: 'created', fileId, fileData, storageError };
     }
     const docSnap = snapshot.docs[0];
@@ -413,6 +519,7 @@ export async function pushFileToCloud({ filesRef, storage, orgId, userId, scope,
     }
     const existingMime = typeof existing['mimeType'] === 'string' ? existing['mimeType'] : undefined;
     const resolvedMime = mimeType || existingMime || 'text/markdown';
+    const existingContentHash = typeof existing['contentHash'] === 'string' ? existing['contentHash'] : null;
     await updateDoc(docSnap.ref, {
         type: 'file',
         name: fileName,
@@ -430,6 +537,26 @@ export async function pushFileToCloud({ filesRef, storage, orgId, userId, scope,
     catch (err) {
         storageError = err;
     }
+    // See the 'created' branch above for the storage-error mapping
+    // rationale: partial failures land as outcome=io_error so the
+    // audit trail reflects the sync/push-outcome.ts "synced with
+    // warnings" state instead of a false 'success'.
+    await logOperation({
+        db: filesRef.firestore,
+        orgId,
+        actor: { type: 'user', id: userId },
+        subject: { type: 'file', id: docSnap.id },
+        opType: 'FileWrite',
+        path: docPath,
+        preContentHash: existingContentHash,
+        postContentHash: contentHash,
+        sizeBytes: size,
+        outcome: storageError == null ? 'success' : 'io_error',
+        error: storageError == null ? null : {
+            code: storageError?.code ?? 'storage-upload-failed',
+            message: String(storageError),
+        },
+    });
     return { action: 'updated', fileId: docSnap.id, storageError };
 }
 /**
@@ -506,6 +633,15 @@ export async function deleteFileFromCloud({ filesRef, storage, orgId, userId, sc
     // throws "Null value error" → SDK surfaces permission-denied. The
     // desired end state (no doc) is already achieved, so treat as
     // already-deleted instead of propagating.
+    // Read the pre-delete content hash from `preRecheck` rather than
+    // the initial query snapshot: preRecheck was fetched immediately
+    // before the blob delete, so it reflects any concurrent update in
+    // the narrow window between the query and here. Also avoids the
+    // duplicate `docSnap.data()` calls the previous version made.
+    const preRecheckData = preRecheck.data();
+    const existingContentHash = typeof preRecheckData?.['contentHash'] === 'string'
+        ? preRecheckData['contentHash']
+        : null;
     try {
         await deleteDoc(docSnap.ref);
     }
@@ -519,6 +655,17 @@ export async function deleteFileFromCloud({ filesRef, storage, orgId, userId, sc
         }
         throw err;
     }
+    await logOperation({
+        db: filesRef.firestore,
+        orgId,
+        actor: { type: 'user', id: userId },
+        subject: { type: 'file', id: fileId },
+        opType: 'FileDelete',
+        path: docPath,
+        preContentHash: existingContentHash,
+        postContentHash: null,
+        outcome: 'success',
+    });
     return { action: 'deleted', fileId };
 }
 //# sourceMappingURL=files.js.map

package/operation-log.d.ts

@@ -0,0 +1,52 @@
+import { type Firestore } from 'firebase/firestore';
+export type OpType = 'FileWrite' | 'FileDelete' | 'FolderCreate' | 'FolderDelete' | 'FolderMove';
+export type ActorType = 'user' | 'agent';
+export type SubjectType = 'file' | 'folder';
+export type Outcome = 'success' | 'integrity_error' | 'io_error' | 'permission_denied';
+export interface OperationLogActor {
+    type: ActorType;
+    id: string;
+}
+export interface OperationLogSubject {
+    type: SubjectType;
+    id: string;
+}
+export interface OperationLogError {
+    code: string;
+    message: string;
+}
+export interface OperationLogEntryInput {
+    orgId: string;
+    actor: OperationLogActor;
+    subject: OperationLogSubject;
+    opType: OpType;
+    path: string;
+    outcome: Outcome;
+    preContentHash?: string | null;
+    postContentHash?: string | null;
+    sizeBytes?: number | null;
+    error?: OperationLogError | null;
+    agentVersion?: string;
+}
+export interface LogOperationInput extends OperationLogEntryInput {
+    db: Firestore;
+}
+export declare const DAEMON_AGENT_VERSION = "1.14.1";
+export interface OperationLogDoc {
+    id: string;
+    timestamp: string;
+    actor: OperationLogActor;
+    subject: OperationLogSubject;
+    op_type: OpType;
+    path: string;
+    pre_content_hash: string | null;
+    post_content_hash: string | null;
+    size_bytes: number | null;
+    outcome: Outcome;
+    error: OperationLogError | null;
+    agent_version: string;
+    org_id: string;
+}
+export declare function buildOperationLogDoc(input: OperationLogEntryInput, now?: string, id?: string): OperationLogDoc;
+export declare function logOperation(input: LogOperationInput): Promise<void>;
+//# sourceMappingURL=operation-log.d.ts.map

package/operation-log.js

@@ -0,0 +1,44 @@
+// Daemon-side operation-log emitter. Writes an append-only doc at
+// orgs/{orgId}/operationLog/{ulid} per DOU-271 §5.1's Firestore-
+// intermediary transport. The emitOperationLog Cloud Function (see
+// DOU-298) reads via Admin SDK and forwards to Cloud Logging.
+//
+// The helper is intentionally minimal: caller supplies the operation
+// details, the helper fills in id (ULID), timestamp, and
+// agent_version, and setDoc's throw propagates. A broken audit emit
+// fails the surrounding mutation (fail-loud, per DOU-271 rationale
+// in §5.1: audit + file-doc writes share the same hard-failure
+// surface, so silencing audit failures would hide the class of bug
+// the log exists to expose).
+import { doc, setDoc } from 'firebase/firestore';
+import { ulid } from 'ulid';
+// Sync-daemon version stamped onto every emitted entry. Kept in
+// step with sync/package.json version by hand; a follow-up can
+// inject at build time if drift becomes a concern.
+export const DAEMON_AGENT_VERSION = '1.14.1';
+// Pure envelope builder. Split out for unit testability without a
+// Firestore instance; logOperation composes it with setDoc. Takes
+// `OperationLogEntryInput` (no `db` field) so tests don't need to
+// synthesize a Firestore stub for a function that never uses it.
+export function buildOperationLogDoc(input, now = new Date().toISOString(), id = ulid()) {
+    return {
+        id,
+        timestamp: now,
+        actor: input.actor,
+        subject: input.subject,
+        op_type: input.opType,
+        path: input.path,
+        pre_content_hash: input.preContentHash ?? null,
+        post_content_hash: input.postContentHash ?? null,
+        size_bytes: input.sizeBytes ?? null,
+        outcome: input.outcome,
+        error: input.error ?? null,
+        agent_version: input.agentVersion ?? DAEMON_AGENT_VERSION,
+        org_id: input.orgId,
+    };
+}
+export async function logOperation(input) {
+    const entry = buildOperationLogDoc(input);
+    await setDoc(doc(input.db, 'orgs', input.orgId, 'operationLog', entry.id), entry);
+}
+//# sourceMappingURL=operation-log.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doubling/compound-sync",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "Bidirectional sync between Compound and local markdown files",
   "type": "module",
   "bin": {
@@ -43,6 +43,8 @@
     "yjs-file-binding.d.ts",
     "yjs-binding-state.js",
     "yjs-binding-state.d.ts",
+    "operation-log.js",
+    "operation-log.d.ts",
     "README.md"
   ],
   "scripts": {
@@ -50,8 +52,8 @@
     "build": "tsc",
     "typecheck": "tsc --noEmit",
     "prepack": "npm run build",
-    "test:unit": "node --import tsx --test config.test.ts paths.test.ts storage-helpers.test.ts folder-chain.test.ts team-registry.test.ts auth-persistence.test.ts pre-mint-app-check.test.ts setup-auth-with-pre-mint.test.ts sync-state.test.ts manifest.test.ts push-outcome.test.ts yjs-file-binding.test.ts yjs-binding-state.test.ts files-helpers.test.ts",
-    "test:integration": "node --import tsx --test --test-timeout=180000 files-push-create-private.test.ts files-push-create-team.test.ts files-push-update-private.test.ts files-push-binary.test.ts files-push-staleness.test.ts files-push-storage-fail.test.ts files-push-no-content.test.ts files-push-stamps.test.ts files-push-folder.test.ts files-delete.test.ts files-delete-folder.test.ts files-read-blob.test.ts org-sync-local-edit.test.ts org-sync-file-ops.test.ts org-sync-mtime.test.ts org-sync-rename.test.ts org-sync-yjs-pull.test.ts org-sync-yjs-push.test.ts org-sync-cold-start.test.ts org-sync-startup-ordering.test.ts org-sync-manifest-reconcile.test.ts org-sync-team-membership-filter.test.ts org-sync-special-chars.test.ts org-sync-copy.test.ts two-user-happy-paths.test.ts two-user-yjs-convergence.test.ts files-concurrency-folder-create.test.ts files-concurrency-file-create.test.ts files-concurrency-file-create-sandbox.test.ts files-concurrency-file-delete.test.ts files-concurrency-folder-delete.test.ts",
+    "test:unit": "node --import tsx --test config.test.ts paths.test.ts storage-helpers.test.ts folder-chain.test.ts team-registry.test.ts auth-persistence.test.ts pre-mint-app-check.test.ts setup-auth-with-pre-mint.test.ts sync-state.test.ts manifest.test.ts push-outcome.test.ts yjs-file-binding.test.ts yjs-binding-state.test.ts files-helpers.test.ts operation-log.test.ts",
+    "test:integration": "node --import tsx --test --test-timeout=180000 files-push-create-private.test.ts files-push-create-team.test.ts files-push-update-private.test.ts files-push-binary.test.ts files-push-staleness.test.ts files-push-storage-fail.test.ts files-push-no-content.test.ts files-push-stamps.test.ts files-push-folder.test.ts files-delete.test.ts files-delete-folder.test.ts files-read-blob.test.ts operation-log-emit.test.ts org-sync-local-edit.test.ts org-sync-file-ops.test.ts org-sync-mtime.test.ts org-sync-rename.test.ts org-sync-yjs-pull.test.ts org-sync-yjs-push.test.ts org-sync-cold-start.test.ts org-sync-startup-ordering.test.ts org-sync-manifest-reconcile.test.ts org-sync-team-membership-filter.test.ts org-sync-special-chars.test.ts org-sync-copy.test.ts two-user-happy-paths.test.ts two-user-yjs-convergence.test.ts files-concurrency-folder-create.test.ts files-concurrency-file-create.test.ts files-concurrency-file-create-sandbox.test.ts files-concurrency-file-delete.test.ts files-concurrency-folder-delete.test.ts",
     "test:integration:emulator": "USE_EMULATOR=true firebase emulators:exec --only firestore,storage,auth 'npm run test:integration'",
     "test": "npm run test:unit && npm run test:integration"
   },
@@ -59,14 +61,15 @@
     "@doubling/types": "*",
     "chokidar": "^5.0.0",
     "fast-diff": "^1.3.0",
-    "firebase": "^12.14.0",
+    "firebase": "^12.15.0",
+    "ulid": "^3.0.2",
     "yjs": "^13.6.31"
   },
   "devDependencies": {
     "@firebase/rules-unit-testing": "^5.0.1",
-    "@types/node": "^26.0.0",
-    "firebase-tools": "^15.20.0",
-    "tsx": "^4.22.4",
+    "@types/node": "22.20.0",
+    "firebase-tools": "^15.22.4",
+    "tsx": "^4.23.0",
     "typescript": "^5.9.3"
   },
   "publishConfig": {