@vrtmrz/livesync-commonlib 0.1.42 → 0.1.43

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,27 @@ 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 CouchDB. See [Database diagnostics](docs/database-diagnostics.md) for coverage, cancellation, and privacy boundaries.
+
+```typescript
+import {
+    analyseDatabaseUsage,
+    createDiagnosticNameMapper,
+    createLocalDiagnosticSource,
+    formatUsageTSV,
+    projectUsageReport,
+} from '@vrtmrz/livesync-commonlib/diagnostics';
+
+const result = await analyseDatabaseUsage({ source: createLocalDiagnosticSource(localPouchDB) });
+const report = projectUsageReport(result, createDiagnosticNameMapper('pseudonym'));
+if (report.status === 'complete') {
+    const tsv = formatUsageTSV(report);
+    // Present the report through the host's own UI or output stream.
+}
+```
+
 ## 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,129 @@
+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";
+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 readJSON = async (path, parameters = {}) => {
+    checkCancelled();
+    const requestURL = new URL(`${root}${path}`);
+    for (const [key, value] of Object.entries(parameters)) requestURL.searchParams.set(key, value);
+    headers.set("authorization", await auth.getAuthorizationHeader(credentials));
+    checkCancelled();
+    const response = await fetch(requestURL.toString(), {
+      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;
+  return {
+    async info() {
+      const info = await readJSON("");
+      return { update_seq: info.update_seq };
+    },
+    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";
+      const raw = await readJSON(`/${encodeURIComponent(id)}`, parameters);
+      if (raw._id !== id || typeof raw._rev !== "string") {
+        throw new DiagnosticReadError("document-unreadable");
+      }
+      const decoded = await decompressDoc(await decrypt(raw));
+      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;
+    },
+    close() {
+      signal?.removeEventListener("abort", abort);
+      controller.abort();
+      return Promise.resolve();
+    }
+  };
+}
+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, 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, DiagnosticDatabaseSource, DiagnosticError, DiagnosticContent, DiagnosticCoverage, DiagnosticObservation, DiagnosticIdentitySettings, DatabaseIntegrityResult, DatabaseIntegrityOptions, } from "./types.js";

package/dist/diagnostics/index.js

@@ -0,0 +1,26 @@
+import { analyseDatabaseUsage } from "./usage.js";
+import { analyseDatabaseIntegrity } from "./integrity.js";
+import { createLocalDiagnosticSource } from "./local.js";
+import { createCouchDBDiagnosticSource } from "./couchdb.js";
+import {
+  createDiagnosticNameMapper,
+  projectIntegrityReport,
+  projectUsageReport,
+  formatDiagnosticJSON,
+  formatIntegrityMarkdown,
+  formatUsageTSV
+} from "./reports.js";
+import { DiagnosticReadError } from "./types.js";
+export {
+  DiagnosticReadError,
+  analyseDatabaseIntegrity,
+  analyseDatabaseUsage,
+  createCouchDBDiagnosticSource,
+  createDiagnosticNameMapper,
+  createLocalDiagnosticSource,
+  formatDiagnosticJSON,
+  formatIntegrityMarkdown,
+  formatUsageTSV,
+  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>;