fix: add OpenPGP payload diagnostics (#130)

tnunamak · web-flow · commit 4dc329ce6cfb · 2026-06-08T19:19:06.000-05:00
Adds safe sync diagnostics for OpenPGP parse/decrypt failures so
browser-only repros can identify whether storage returned OpenPGP, HTML,
JSON, empty, binary, or unknown bytes and how many bytes were
downloaded.\n\nValidation:\n- npx vitest run
packages/core/src/sync/workers/download.test.ts\n- npm run build\n- npm
run format:check\n- npm run lint:eslint\n- npm test
diff --git a/packages/core/src/sync/workers/download.test.ts b/packages/core/src/sync/workers/download.test.ts
@@ -156,6 +156,47 @@ describe("download worker", () => {
       expect(deps.storageAdapter.download).not.toHaveBeenCalled();
     });
 
+    it("records downloaded payload metadata when OpenPGP parsing fails", async () => {
+      const deps = makeMockDeps();
+      const htmlPayload = new TextEncoder().encode("<html>not pgp</html>");
+      (
+        deps.storageAdapter.download as ReturnType<typeof vi.fn>
+      ).mockResolvedValue(htmlPayload);
+      (decryptWithPassword as ReturnType<typeof vi.fn>).mockRejectedValue(
+        new Error("Armored OpenPGP message could not be parsed"),
+      );
+      deps.diagnostics = {
+        onDownloadStart: vi.fn(),
+        onDownloadEnd: vi.fn(),
+        onDownloadError: vi.fn(),
+        onDecryptStart: vi.fn(),
+        onDecryptEnd: vi.fn(),
+        onDecryptError: vi.fn(),
+        onIndexStart: vi.fn(),
+        onIndexEnd: vi.fn(),
+        onIndexError: vi.fn(),
+        onManifestBuildStart: vi.fn(),
+        onManifestBuildEnd: vi.fn(),
+        onManifestBuildError: vi.fn(),
+        onRepair: vi.fn(),
+      };
+
+      await expect(downloadOne(deps, makeFileRecord())).rejects.toThrow(
+        "Armored OpenPGP message could not be parsed",
+      );
+
+      expect(deps.diagnostics.onDecryptError).toHaveBeenCalledWith(
+        FILE_ID,
+        SCOPE,
+        expect.stringContaining("payloadKind=html"),
+      );
+      expect(deps.diagnostics.onDecryptError).toHaveBeenCalledWith(
+        FILE_ID,
+        SCOPE,
+        expect.stringContaining(`encryptedSizeBytes=${htmlPayload.byteLength}`),
+      );
+    });
+
     it("backfills missing block sidecars when fileId is already indexed", async () => {
       const deps = makeMockDeps();
       const existingEntry: IndexEntry = {
@@ -665,7 +706,10 @@ describe("download worker", () => {
         expect.objectContaining({
           fileId: "file-002",
           schemaId: SCHEMA_ID,
+          scope: SCOPE,
           stage: "decrypt",
+          payloadKind: "unknown",
+          encryptedSizeBytes: 2,
           errorClass: "Error",
           message: "Encrypted payload could not be decrypted",
         }),
diff --git a/packages/core/src/sync/workers/download.ts b/packages/core/src/sync/workers/download.ts
@@ -10,7 +10,12 @@ import type { SyncCursor } from "../cursor.js";
 import type { Logger } from "../../logger/index.js";
 import type { DataStoragePort } from "../../ports/index.js";
 import { buildDataBlocks } from "../../storage/blocks/build.js";
-import { classifySyncFailure } from "../issues.js";
+import {
+  classifySyncFailure,
+  inferPayloadKind,
+  type SyncFailureStage,
+  type SyncPayloadKind,
+} from "../issues.js";
 
 /** Minimal diagnostics hook — keeps core free of lite-specific imports. */
 export interface DownloadDiagnosticsHook {
@@ -48,6 +53,13 @@ export interface DownloadResult {
   path: string;
 }
 
+interface SyncFailureMetadata {
+  stage?: SyncFailureStage;
+  scope?: string;
+  payloadKind?: SyncPayloadKind;
+  encryptedSizeBytes?: number;
+}
+
 /**
  * Download and process a single file record from the storage backend:
  * 1. Check dedup: skip if fileId already in local index
@@ -121,9 +133,19 @@ export async function downloadOne(
   try {
     plaintext = await decryptWithPassword(encrypted, scopeKeyHex);
   } catch (err) {
-    const detail = (err as Error).message;
+    const payloadKind = inferPayloadKind(encrypted);
+    const encryptedSizeBytes = encrypted.byteLength;
+    const detail = [
+      (err as Error).message,
+      `payloadKind=${payloadKind}`,
+      `encryptedSizeBytes=${encryptedSizeBytes}`,
+    ].join("; ");
     diagnostics?.onDecryptError(record.fileId, schema.scope, detail);
-    throw err;
+    throw withSyncFailureMetadata(err, {
+      scope: schema.scope,
+      payloadKind,
+      encryptedSizeBytes,
+    });
   }
 
   // 6. Parse as DataFileEnvelope (validate)
@@ -267,18 +289,26 @@ export async function downloadAll(
         results.push(result);
       }
     } catch (err) {
+      const metadata = getSyncFailureMetadata(err);
       const classified = classifySyncFailure({
         error: err,
         fileId: file.fileId,
         schemaId: file.schemaId,
         syncRunId,
+        stage: metadata.stage,
+        scope: metadata.scope,
+        payloadKind: metadata.payloadKind,
+        encryptedSizeBytes: metadata.encryptedSizeBytes,
       });
       if (!classified.issue.retryable) {
         logger.warn(
           {
             fileId: file.fileId,
             schemaId: file.schemaId,
+            scope: classified.issue.scope,
             stage: classified.issue.stage,
+            payloadKind: classified.issue.payloadKind,
+            encryptedSizeBytes: classified.issue.encryptedSizeBytes,
             errorClass: classified.issue.errorClass,
             message: classified.issue.message,
           },
@@ -372,6 +402,25 @@ function uint8ToHex(bytes: Uint8Array): string {
   );
 }
 
+function withSyncFailureMetadata(
+  error: unknown,
+  metadata: SyncFailureMetadata,
+): unknown {
+  if (error instanceof Error) {
+    Object.assign(error, { syncFailureMetadata: metadata });
+    return error;
+  }
+  return { error, syncFailureMetadata: metadata };
+}
+
+function getSyncFailureMetadata(error: unknown): SyncFailureMetadata {
+  if (typeof error !== "object" || error === null) return {};
+  const metadata = (error as { syncFailureMetadata?: unknown })
+    .syncFailureMetadata;
+  if (typeof metadata !== "object" || metadata === null) return {};
+  return metadata as SyncFailureMetadata;
+}
+
 async function writeBlockSidecars(
   storage: DataStoragePort,
   envelope: {
