@vrtmrz/livesync-commonlib 0.1.42 → 0.1.44

package/README.md

@@ -26,6 +26,7 @@ The package is ESM-only and declares Node 20 or later. Browser entry points are
 | -------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
 | `@vrtmrz/livesync-commonlib`                       | `DirectFileManipulator` for integrations which access CouchDB directly            | Deliberately small, but its high-level lifecycle and file-operation semantics are not final |
 | `@vrtmrz/livesync-commonlib/context`               | Instance-owned events, translation injection, and host-neutral standard-I/O types | Focused, package-tested pre-1.0 contract                                                    |
+| `@vrtmrz/livesync-commonlib/diagnostics` | Read-only Usage and integrity inspection, name projection, and reports | Focused pre-1.0 diagnostic contract |
 | `@vrtmrz/livesync-commonlib/hashing`               | Chunk ID calculation and exact file-content hashing                            | Focused, package-tested pre-1.0 contract                                                    |
 | `@vrtmrz/livesync-commonlib/browser`               | Rooted File System Access API storage                                             | Focused, package-tested pre-1.0 contract                                                    |
 | `@vrtmrz/livesync-commonlib/node`                  | Rooted Node storage, Node standard I/O, and selected Node capabilities            | Supported platform façade; keeps Node-only dependencies behind an explicit boundary         |
@@ -119,6 +120,45 @@ See [the settings lifecycle guide](docs/settings-lifecycle.md) before initialisi
 
 The focused Setup URI entry offers an Ephemeral mode bound to the current fixed seven-day window and a Persistent mode compatible with existing readers. Both use the same URI structure. See [the Setup URI sharing guide](docs/setup-uri.md) for the availability boundary, import behaviour, and compatibility limits.
 
+## Database diagnostics
+
+The focused `/diagnostics` entry provides read-only Usage and integrity reports, with original names or temporary pseudonyms selected by the host for each run. Integrity inspection covers normal-file Metadata, current conflict branches, and content comparisons for suspect groups in the local database and, by default, CouchDB; the host can exclude the remote source for one run. See [Database diagnostics](docs/database-diagnostics.md) for coverage, progress, cancellation, pseudonym lookup, and privacy boundaries.
+
+Integrity Markdown places a compact state summary and review index before all findings, while retaining each observation and its follow-up references. This formatting does not change the projected JSON data or schema; see [the Markdown field guide](docs/database-diagnostics.md#compact-integrity-markdown-report) for the meaning and limits of its review index.
+
+```typescript
+import {
+    analyseDatabaseUsage,
+    createDiagnosticNameMapper,
+    createLocalDiagnosticSource,
+    formatUsageTSV,
+    parseDiagnosticPathToken,
+    projectUsageReport,
+} from '@vrtmrz/livesync-commonlib/diagnostics';
+
+const result = await analyseDatabaseUsage({ source: createLocalDiagnosticSource(localPouchDB) });
+const mapper = createDiagnosticNameMapper('pseudonym');
+const report = projectUsageReport(result, mapper);
+if (report.status === 'complete') {
+    const tsv = formatUsageTSV(report);
+    // Present the report through the host's own UI or output stream.
+}
+```
+
+Path pseudonyms include the report salt. A consumer can parse that token and supply its salt to a new mapper for a targeted follow-up against exact local Metadata paths:
+
+```typescript
+const pathToken = report.rows[0]?.path;
+const parsed = pathToken === undefined ? undefined : parseDiagnosticPathToken(pathToken);
+if (parsed) {
+    const followUpMapper = createDiagnosticNameMapper('pseudonym', parsed.salt);
+    const candidateToken = followUpMapper.path(storedVaultRelativePath);
+    // Compare this token with the path pseudonym on this device.
+}
+```
+
+The parser accepts only complete path tokens; it does not reverse them to recover a path. The salt is public, so a guessed path can be checked. Older ordinal pseudonyms have no corresponding lookup.
+
 ## Chunk ID calculation
 
 The `/hashing` entry exports `HashManager` and its `HashManagerCoreOptions` type. It uses the same implementation as database writes, including legacy algorithms and independent ID keys. Hosts supply their settings service and await `initialise()` before calling `computeHash(piece)`.

package/dist/common/pathIdentity.d.ts

@@ -2,9 +2,18 @@ import type { EntryHasPath, FilePathWithPrefix } from "./types.js";
 import type { IPathService } from "../services/base/IService.js";
 /** Check the complete source listing before an operation can discard either database. */
 export declare function assertUniqueStoragePathIdentities(paths: Iterable<FilePathWithPrefix>, pathService: Pick<IPathService, "path2id">): Promise<void>;
-/** Distinct Metadata documents must not be merged by a change of path identity. */
+/**
+ * Distinct Metadata documents must not be merged by a change of path identity.
+ * Callers must enumerate entries with `conflicts: true` so unresolved revisions remain visible.
+ * `requireMatchingIds: false` is reserved for preflight checks before replacing the local database;
+ * only that mode excludes conflict-free logical deletions from collision checks.
+ */
 export declare function assertMetadataPathIdentities(entries: AsyncIterable<EntryHasPath & {
     _id: string;
+    deleted?: boolean;
+    _conflicts?: string[];
 }> | Iterable<EntryHasPath & {
     _id: string;
+    deleted?: boolean;
+    _conflicts?: string[];
 }>, pathService: Pick<IPathService, "path2id">, requireMatchingIds: boolean): Promise<void>;

package/dist/common/pathIdentity.js

@@ -16,6 +16,7 @@ async function assertUniqueStoragePathIdentities(paths, pathService) {
 async function assertMetadataPathIdentities(entries, pathService, requireMatchingIds) {
   const identities = /* @__PURE__ */ new Map();
   for await (const entry of entries) {
+    if (!requireMatchingIds && entry.deleted === true && !entry._conflicts?.length) continue;
     const path = id2path_base(entry._id, entry);
     const id = await pathService.path2id(path);
     const previous = identities.get(id);

package/dist/diagnostics/couchdb.d.ts

@@ -0,0 +1,15 @@
+import { type RemoteDBSettings } from "../common/types.js";
+import { type DiagnosticDatabaseSource } from "./types.js";
+export interface CouchDBDiagnosticSourceOptions {
+    settings: RemoteDBSettings;
+    fetch(request: string, options: RequestInit): Promise<Response>;
+    signal?: AbortSignal;
+}
+/**
+ * Open an operation-owned HTTP reader. All requests are GETs, including the
+ * Security Seed lookup; the replication connection and its setup paths are
+ * deliberately absent from this boundary.
+ */
+export declare function createCouchDBDiagnosticSource({ settings: originalSettings, fetch, signal, }: CouchDBDiagnosticSourceOptions): DiagnosticDatabaseSource & {
+    close(): Promise<void>;
+};

package/dist/diagnostics/couchdb.js

@@ -0,0 +1,202 @@
+import { DOCID_SYNC_PARAMETERS } from "../common/types.js";
+import { isObfuscatedEntry, parseHeaderValues } from "../common/utils.js";
+import { getConfiguredFunctionsForEncryption, isEncryptedMeta } from "../pouchdb/encryption.js";
+import { isPathProbablyObfuscated } from "octagonal-wheels/encryption/encryption";
+import { decompressDoc } from "../pouchdb/compress.js";
+import { AuthorizationHeaderGenerator, generateCredentialObject } from "../replication/httplib.js";
+import { base64ToArrayBuffer } from "../string_and_binary/convert.js";
+import { DiagnosticReadError } from "./types.js";
+const MAX_BULK_DOCUMENTS = 64;
+const MAX_BULK_URL_LENGTH = 6e3;
+function createCouchDBDiagnosticSource({
+  settings: originalSettings,
+  fetch,
+  signal
+}) {
+  const settings = { ...originalSettings };
+  const root = `${settings.couchDB_URI.replace(/\/+$/, "")}/${encodeURIComponent(settings.couchDB_DBNAME)}`;
+  const url = new URL(root);
+  if (!settings.couchDB_DBNAME || !["https:", "http:"].includes(url.protocol) || url.search || url.hash) {
+    throw new DiagnosticReadError("source-unavailable");
+  }
+  if (settings.encrypt && !settings.passphrase && !settings.permitEmptyPassphrase) {
+    throw new DiagnosticReadError("source-unavailable");
+  }
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  if (signal?.aborted) abort();
+  else signal?.addEventListener("abort", abort, { once: true });
+  const auth = new AuthorizationHeaderGenerator();
+  const credentials = generateCredentialObject(settings);
+  const headers = new Headers(parseHeaderValues(settings.couchDB_CustomHeaders));
+  const checkCancelled = () => {
+    if (controller.signal.aborted) throw new DOMException("Diagnostic cancelled", "AbortError");
+  };
+  const requestURL = (path, parameters = {}) => {
+    const requestURL2 = new URL(`${root}${path}`);
+    for (const [key, value] of Object.entries(parameters)) requestURL2.searchParams.set(key, value);
+    return requestURL2.toString();
+  };
+  const readJSON = async (path, parameters = {}) => {
+    checkCancelled();
+    headers.set("authorization", await auth.getAuthorizationHeader(credentials));
+    checkCancelled();
+    const response = await fetch(requestURL(path, parameters), {
+      method: "GET",
+      headers,
+      cache: "no-store",
+      signal: controller.signal
+    });
+    checkCancelled();
+    if (!response.ok) throw new DiagnosticReadError("document-unreadable", response.status === 404);
+    const result = await response.json();
+    checkCancelled();
+    return result;
+  };
+  let salt;
+  const readSalt = () => salt ??= (async () => {
+    try {
+      const parameters = await readJSON(`/${DOCID_SYNC_PARAMETERS}`);
+      if (typeof parameters.pbkdf2salt !== "string" || !parameters.pbkdf2salt) {
+        throw new DiagnosticReadError("security-seed-unavailable");
+      }
+      const bytes = new Uint8Array(base64ToArrayBuffer(parameters.pbkdf2salt));
+      if (!bytes.length) throw new DiagnosticReadError("security-seed-unavailable");
+      return bytes;
+    } catch {
+      checkCancelled();
+      throw new DiagnosticReadError("security-seed-unavailable");
+    }
+  })();
+  const decrypt = settings.encrypt ? getConfiguredFunctionsForEncryption(
+    settings.passphrase,
+    settings.useDynamicIterationCount,
+    false,
+    readSalt,
+    settings.E2EEAlgorithm,
+    false,
+    () => {
+    }
+  ).outgoing : async (doc) => doc;
+  const decode = async (id, value) => {
+    if (!value || typeof value !== "object" || !("_id" in value) || value._id !== id || !("_rev" in value) || typeof value._rev !== "string") {
+      throw new DiagnosticReadError("document-unreadable");
+    }
+    const decoded = await decompressDoc(await decrypt(value));
+    if ("e_" in decoded && decoded.e_ === true || "path" in decoded && typeof decoded.path === "string" && (isEncryptedMeta(decoded) || isObfuscatedEntry(decoded) && isPathProbablyObfuscated(decoded.path)))
+      throw new DiagnosticReadError("document-unreadable");
+    checkCancelled();
+    return decoded;
+  };
+  const source = {
+    async info() {
+      const info = await readJSON("");
+      return { update_seq: info.update_seq, doc_count: info.doc_count };
+    },
+    async *enumerateIds() {
+      let previous;
+      while (true) {
+        const parameters = { limit: "256" };
+        if (previous !== void 0) {
+          parameters.startkey = JSON.stringify(previous);
+          parameters.skip = "1";
+        }
+        const page = await readJSON("/_all_docs", parameters);
+        if (!Array.isArray(page.rows)) throw new DiagnosticReadError("source-unavailable");
+        if (page.rows.length === 0) return;
+        for (const row of page.rows) {
+          checkCancelled();
+          if (typeof row.id !== "string") throw new DiagnosticReadError("source-unavailable");
+          if (!row.value?.deleted) yield row.id;
+        }
+        const last = page.rows.at(-1).id;
+        if (last === previous) throw new DiagnosticReadError("source-unavailable");
+        previous = last;
+        if (page.rows.length < 256) return;
+      }
+    },
+    async get(id, options = {}) {
+      const parameters = {};
+      if (options.rev !== void 0) parameters.rev = options.rev;
+      if (options.conflicts) parameters.conflicts = "true";
+      if (options.revs) parameters.revs = "true";
+      if (options.revs_info) parameters.revs_info = "true";
+      return await decode(id, await readJSON(`/${encodeURIComponent(id)}`, parameters));
+    },
+    async getMany(ids, options = {}) {
+      const result = [];
+      const parameters = (keys) => ({
+        keys: JSON.stringify(keys),
+        include_docs: "true",
+        ...options.conflicts ? { conflicts: "true" } : {}
+      });
+      const readBatch = async (keys) => {
+        if (!keys.length) return;
+        let rows;
+        try {
+          const page = await readJSON("/_all_docs", parameters(keys));
+          if (!Array.isArray(page.rows)) throw new DiagnosticReadError("document-unreadable");
+          rows = page.rows;
+        } catch {
+          checkCancelled();
+          result.push(...keys.map((id) => ({ id, error: new DiagnosticReadError("document-unreadable") })));
+          return;
+        }
+        for (let offset = 0; offset < keys.length; offset += 4) {
+          checkCancelled();
+          const decoded = await Promise.allSettled(
+            keys.slice(offset, offset + 4).map(async (id, index) => {
+              try {
+                const row = rows[offset + index];
+                if (!row || row.key !== id) throw new DiagnosticReadError("document-unreadable");
+                if (row.error === "not_found" || row.value?.deleted)
+                  throw new DiagnosticReadError("document-unreadable", true);
+                if (row.error || row.id !== id) throw new DiagnosticReadError("document-unreadable");
+                return { id, document: await decode(id, row.doc) };
+              } catch (error) {
+                checkCancelled();
+                return {
+                  id,
+                  error: error instanceof DiagnosticReadError ? error : new DiagnosticReadError("document-unreadable")
+                };
+              }
+            })
+          );
+          checkCancelled();
+          for (const outcome of decoded) {
+            if (outcome.status === "rejected") throw outcome.reason;
+            result.push(outcome.value);
+          }
+        }
+      };
+      let pending = [];
+      for (const id of ids) {
+        checkCancelled();
+        if (pending.length >= MAX_BULK_DOCUMENTS || requestURL("/_all_docs", parameters([...pending, id])).length > MAX_BULK_URL_LENGTH) {
+          await readBatch(pending);
+          pending = [];
+        }
+        if (requestURL("/_all_docs", parameters([id])).length > MAX_BULK_URL_LENGTH) {
+          try {
+            result.push({ id, document: await source.get(id, options) });
+          } catch (error) {
+            checkCancelled();
+            result.push({ id, error });
+          }
+        } else pending.push(id);
+      }
+      await readBatch(pending);
+      checkCancelled();
+      return result;
+    },
+    close() {
+      signal?.removeEventListener("abort", abort);
+      controller.abort();
+      return Promise.resolve();
+    }
+  };
+  return source;
+}
+export {
+  createCouchDBDiagnosticSource
+};

package/dist/diagnostics/index.d.ts

@@ -0,0 +1,10 @@
+export { analyseDatabaseUsage } from "./usage.js";
+export type { DatabaseUsageSource, DatabaseUsageResult, DatabaseUsageRow, DatabaseUsageProgress, DatabaseUsageError, } from "./usage.js";
+export { analyseDatabaseIntegrity } from "./integrity.js";
+export { createLocalDiagnosticSource } from "./local.js";
+export { createCouchDBDiagnosticSource } from "./couchdb.js";
+export type { CouchDBDiagnosticSourceOptions } from "./couchdb.js";
+export { createDiagnosticNameMapper, parseDiagnosticPathToken, projectIntegrityReport, projectUsageReport, formatDiagnosticJSON, formatIntegrityMarkdown, formatUsageTSV, } from "./reports.js";
+export type { DiagnosticNameMapper, DiagnosticReportVersions, ProjectedDiagnosticReport, ProjectedDatabaseIntegrityReport, ProjectedDatabaseUsageReport, } from "./reports.js";
+export { DiagnosticReadError } from "./types.js";
+export type { DiagnosticStatus, DiagnosticNameMode, DiagnosticSourceName, DiagnosticReason, DiagnosticReadOptions, DiagnosticDocumentReadResult, DiagnosticDatabaseSource, DiagnosticError, DiagnosticContent, DiagnosticCoverage, DiagnosticObservation, DiagnosticPathEquivalenceGroup, DiagnosticIdentitySettings, DatabaseIntegrityResult, DatabaseIntegrityOptions, DatabaseIntegrityProgress, DatabaseIntegrityLog, } from "./types.js";

package/dist/diagnostics/index.js

@@ -0,0 +1,28 @@
+import { analyseDatabaseUsage } from "./usage.js";
+import { analyseDatabaseIntegrity } from "./integrity.js";
+import { createLocalDiagnosticSource } from "./local.js";
+import { createCouchDBDiagnosticSource } from "./couchdb.js";
+import {
+  createDiagnosticNameMapper,
+  parseDiagnosticPathToken,
+  projectIntegrityReport,
+  projectUsageReport,
+  formatDiagnosticJSON,
+  formatIntegrityMarkdown,
+  formatUsageTSV
+} from "./reports.js";
+import { DiagnosticReadError } from "./types.js";
+export {
+  DiagnosticReadError,
+  analyseDatabaseIntegrity,
+  analyseDatabaseUsage,
+  createCouchDBDiagnosticSource,
+  createDiagnosticNameMapper,
+  createLocalDiagnosticSource,
+  formatDiagnosticJSON,
+  formatIntegrityMarkdown,
+  formatUsageTSV,
+  parseDiagnosticPathToken,
+  projectIntegrityReport,
+  projectUsageReport
+};

package/dist/diagnostics/integrity.d.ts

@@ -0,0 +1,5 @@
+import type { DatabaseIntegrityOptions, DatabaseIntegrityResult } from "./types.js";
+/**
+ * Inspect current normal-file Metadata and content evidence without changing a source.
+ */
+export declare function analyseDatabaseIntegrity(options: DatabaseIntegrityOptions): Promise<DatabaseIntegrityResult>;