@git-stunts/git-warp 10.3.2 → 10.7.0

package/src/domain/services/SyncAuthService.js

@@ -0,0 +1,396 @@
+/**
+ * HMAC-SHA256 request signing and verification for the sync protocol.
+ *
+ * Provides:
+ * - Canonical payload construction
+ * - Request signing (client side)
+ * - Request verification with replay protection (server side)
+ *
+ * @module domain/services/SyncAuthService
+ */
+
+import LRUCache from '../utils/LRUCache.js';
+import defaultCrypto from '../utils/defaultCrypto.js';
+import nullLogger from '../utils/nullLogger.js';
+
+const SIG_VERSION = '1';
+const SIG_PREFIX = 'warp-v1';
+const HMAC_ALGO = 'sha256';
+const MAX_CLOCK_SKEW_MS = 5 * 60 * 1000;
+const DEFAULT_NONCE_CAPACITY = 100_000;
+const NONCE_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const SIG_HEX_LENGTH = 64;
+const HEX_PATTERN = /^[0-9a-f]+$/;
+const MAX_TIMESTAMP_DIGITS = 16;
+
+/**
+ * Canonicalizes a URL path for signature computation.
+ *
+ * @param {string} url - URL or path to canonicalize
+ * @returns {string} Canonical path (pathname + search, no fragment)
+ */
+export function canonicalizePath(url) {
+  const parsed = new URL(url, 'http://localhost');
+  return parsed.pathname + (parsed.search || '');
+}
+
+/**
+ * Builds the canonical string that gets signed.
+ *
+ * @param {Object} params
+ * @param {string} params.keyId - Key identifier
+ * @param {string} params.method - HTTP method (uppercased by caller)
+ * @param {string} params.path - Canonical path
+ * @param {string} params.timestamp - Epoch milliseconds as string
+ * @param {string} params.nonce - UUIDv4 nonce
+ * @param {string} params.contentType - Content-Type header value
+ * @param {string} params.bodySha256 - Hex SHA-256 of request body
+ * @returns {string} Pipe-delimited canonical payload
+ */
+export function buildCanonicalPayload({ keyId, method, path, timestamp, nonce, contentType, bodySha256 }) {
+  return `${SIG_PREFIX}|${keyId}|${method}|${path}|${timestamp}|${nonce}|${contentType}|${bodySha256}`;
+}
+
+/**
+ * Signs an outgoing sync request.
+ *
+ * @param {Object} params
+ * @param {string} params.method - HTTP method
+ * @param {string} params.path - Canonical path
+ * @param {string} params.contentType - Content-Type header value
+ * @param {Buffer|Uint8Array} params.body - Raw request body
+ * @param {string} params.secret - Shared secret
+ * @param {string} params.keyId - Key identifier
+ * @param {Object} deps
+ * @param {import('../../ports/CryptoPort.js').default} [deps.crypto] - Crypto port
+ * @returns {Promise<Record<string, string>>} Auth headers
+ */
+export async function signSyncRequest({ method, path, contentType, body, secret, keyId }, { crypto } = {}) {
+  const c = crypto || defaultCrypto;
+  const timestamp = String(Date.now());
+  const nonce = globalThis.crypto.randomUUID();
+
+  const bodySha256 = await c.hash('sha256', body);
+  const canonical = buildCanonicalPayload({
+    keyId,
+    method: method.toUpperCase(),
+    path,
+    timestamp,
+    nonce,
+    contentType,
+    bodySha256,
+  });
+
+  const hmacBuf = await c.hmac(HMAC_ALGO, secret, canonical);
+  const signature = Buffer.from(hmacBuf).toString('hex');
+
+  return {
+    'x-warp-sig-version': SIG_VERSION,
+    'x-warp-key-id': keyId,
+    'x-warp-timestamp': timestamp,
+    'x-warp-nonce': nonce,
+    'x-warp-signature': signature,
+  };
+}
+
+/**
+ * @param {string} reason
+ * @param {number} status
+ * @returns {{ ok: false, reason: string, status: number }}
+ */
+function fail(reason, status) {
+  return { ok: false, reason, status };
+}
+
+/**
+ * @returns {{ authFailCount: number, replayRejectCount: number, nonceEvictions: number, clockSkewRejects: number, malformedRejects: number, logOnlyPassthroughs: number }}
+ */
+function _freshMetrics() {
+  return {
+    authFailCount: 0,
+    replayRejectCount: 0,
+    nonceEvictions: 0,
+    clockSkewRejects: 0,
+    malformedRejects: 0,
+    logOnlyPassthroughs: 0,
+  };
+}
+
+/**
+ * Validates format of individual auth header values.
+ *
+ * @param {string} timestamp
+ * @param {string} nonce
+ * @param {string} signature
+ * @returns {{ ok: false, reason: string, status: number } | { ok: true }}
+ */
+function _checkHeaderFormats(timestamp, nonce, signature) {
+  if (!/^\d+$/.test(timestamp) || timestamp.length > MAX_TIMESTAMP_DIGITS) {
+    return fail('MALFORMED_TIMESTAMP', 400);
+  }
+
+  if (!NONCE_PATTERN.test(nonce)) {
+    return fail('MALFORMED_NONCE', 400);
+  }
+
+  if (signature.length !== SIG_HEX_LENGTH || !HEX_PATTERN.test(signature)) {
+    return fail('MALFORMED_SIGNATURE', 400);
+  }
+
+  return { ok: true };
+}
+
+/**
+ * @param {Record<string, string>|undefined} keys
+ */
+function _validateKeys(keys) {
+  if (!keys || typeof keys !== 'object' || Object.keys(keys).length === 0) {
+    throw new Error('SyncAuthService requires a non-empty keys map');
+  }
+}
+
+export default class SyncAuthService {
+  /**
+   * @param {Object} options
+   * @param {Record<string, string>} options.keys - Key-id to secret mapping
+   * @param {'enforce'|'log-only'} [options.mode='enforce'] - Auth enforcement mode
+   * @param {number} [options.nonceCapacity] - Nonce LRU capacity
+   * @param {number} [options.maxClockSkewMs] - Max clock skew tolerance
+   * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - Crypto port
+   * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger port
+   * @param {() => number} [options.wallClockMs] - Wall clock function
+   */
+  constructor({ keys, mode = 'enforce', nonceCapacity, maxClockSkewMs, crypto, logger, wallClockMs } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+    _validateKeys(keys);
+    this._keys = keys;
+    this._mode = mode;
+    this._crypto = crypto || defaultCrypto;
+    this._logger = logger || nullLogger;
+    this._wallClockMs = wallClockMs || (() => Date.now());
+    this._maxClockSkewMs = typeof maxClockSkewMs === 'number' ? maxClockSkewMs : MAX_CLOCK_SKEW_MS;
+    this._nonceCache = new LRUCache(nonceCapacity || DEFAULT_NONCE_CAPACITY);
+    this._metrics = _freshMetrics();
+  }
+
+  /** @returns {'enforce'|'log-only'} */
+  get mode() {
+    return this._mode;
+  }
+
+  /**
+   * Validates auth header presence and format.
+   *
+   * @param {Record<string, string>} headers
+   * @returns {{ ok: false, reason: string, status: number } | { ok: true, sigVersion: string, signature: string, timestamp: string, nonce: string, keyId: string }}
+   * @private
+   */
+  _validateHeaders(headers) {
+    const sigVersion = headers['x-warp-sig-version'];
+    if (sigVersion !== SIG_VERSION) {
+      return fail('INVALID_VERSION', 400);
+    }
+
+    const keyId = headers['x-warp-key-id'];
+    const signature = headers['x-warp-signature'];
+    const timestamp = headers['x-warp-timestamp'];
+    const nonce = headers['x-warp-nonce'];
+
+    if (!keyId || !signature || !timestamp || !nonce) {
+      return fail('MISSING_AUTH', 401);
+    }
+
+    const formatCheck = _checkHeaderFormats(timestamp, nonce, signature);
+    if (!formatCheck.ok) {
+      return formatCheck;
+    }
+
+    return { ok: true, sigVersion, signature, timestamp, nonce, keyId };
+  }
+
+  /**
+   * Checks that the timestamp is within the allowed clock skew.
+   *
+   * @param {string} timestamp - Epoch ms as string
+   * @returns {{ ok: false, reason: string, status: number } | { ok: true }}
+   * @private
+   */
+  _validateFreshness(timestamp) {
+    const ts = Number(timestamp);
+    const now = this._wallClockMs();
+    if (Math.abs(now - ts) > this._maxClockSkewMs) {
+      this._metrics.clockSkewRejects += 1;
+      return fail('EXPIRED', 403);
+    }
+    return { ok: true };
+  }
+
+  /**
+   * Atomically reserves a nonce. Returns replay failure if already seen.
+   *
+   * @param {string} nonce
+   * @returns {{ ok: false, reason: string, status: number } | { ok: true }}
+   * @private
+   */
+  _reserveNonce(nonce) {
+    if (this._nonceCache.has(nonce)) {
+      this._metrics.replayRejectCount += 1;
+      return fail('REPLAY', 403);
+    }
+
+    const sizeBefore = this._nonceCache.size;
+    this._nonceCache.set(nonce, true);
+    if (this._nonceCache.size <= sizeBefore && sizeBefore >= this._nonceCache.maxSize) {
+      this._metrics.nonceEvictions += 1;
+    }
+
+    return { ok: true };
+  }
+
+  /**
+   * Resolves the shared secret for a key-id.
+   *
+   * @param {string} keyId
+   * @returns {{ ok: false, reason: string, status: number } | { ok: true, secret: string }}
+   * @private
+   */
+  _resolveKey(keyId) {
+    const secret = this._keys[keyId];
+    if (!secret) {
+      return fail('UNKNOWN_KEY_ID', 401);
+    }
+    return { ok: true, secret };
+  }
+
+  /**
+   * Verifies the HMAC signature against the canonical payload.
+   *
+   * @param {Object} params
+   * @param {{ method: string, url: string, headers: Record<string, string>, body?: Buffer|Uint8Array }} params.request
+   * @param {string} params.secret
+   * @param {string} params.keyId
+   * @param {string} params.timestamp
+   * @param {string} params.nonce
+   * @returns {Promise<{ ok: false, reason: string, status: number } | { ok: true }>}
+   * @private
+   */
+  async _verifySignature({ request, secret, keyId, timestamp, nonce }) {
+    const body = request.body || new Uint8Array(0);
+    const bodySha256 = await this._crypto.hash('sha256', body);
+    const contentType = request.headers['content-type'] || '';
+    const path = canonicalizePath(request.url || '/');
+
+    const canonical = buildCanonicalPayload({
+      keyId,
+      method: (request.method || 'POST').toUpperCase(),
+      path,
+      timestamp,
+      nonce,
+      contentType,
+      bodySha256,
+    });
+
+    const expectedBuf = await this._crypto.hmac(HMAC_ALGO, secret, canonical);
+    const receivedHex = request.headers['x-warp-signature'];
+
+    let receivedBuf;
+    try {
+      receivedBuf = Buffer.from(receivedHex, 'hex');
+    } catch {
+      return fail('INVALID_SIGNATURE', 401);
+    }
+
+    if (receivedBuf.length !== expectedBuf.length) {
+      return fail('INVALID_SIGNATURE', 401);
+    }
+
+    let equal;
+    try {
+      equal = this._crypto.timingSafeEqual(
+        Buffer.from(expectedBuf),
+        receivedBuf,
+      );
+    } catch {
+      return fail('INVALID_SIGNATURE', 401);
+    }
+
+    if (!equal) {
+      return fail('INVALID_SIGNATURE', 401);
+    }
+
+    return { ok: true };
+  }
+
+  /**
+   * Verifies an incoming sync request.
+   *
+   * @param {{ method: string, url: string, headers: Record<string, string>, body?: Buffer|Uint8Array }} request
+   * @returns {Promise<{ ok: true } | { ok: false, reason: string, status: number }>}
+   */
+  async verify(request) {
+    const headers = request.headers || {};
+
+    const headerResult = this._validateHeaders(headers);
+    if (!headerResult.ok) {
+      this._metrics.malformedRejects += 1;
+      return this._fail('header validation failed', { reason: headerResult.reason }, headerResult);
+    }
+
+    const { timestamp, nonce, keyId } = headerResult;
+
+    const freshnessResult = this._validateFreshness(timestamp);
+    if (!freshnessResult.ok) {
+      return this._fail('clock skew rejected', { keyId, timestamp }, freshnessResult);
+    }
+
+    const keyResult = this._resolveKey(keyId);
+    if (!keyResult.ok) {
+      return this._fail('unknown key-id', { keyId }, keyResult);
+    }
+
+    const sigResult = await this._verifySignature({
+      request, secret: keyResult.secret, keyId, timestamp, nonce,
+    });
+    if (!sigResult.ok) {
+      return this._fail('signature mismatch', { keyId }, sigResult);
+    }
+
+    // Reserve nonce only after signature verification succeeds to avoid
+    // consuming nonces for requests with invalid signatures.
+    const nonceResult = this._reserveNonce(nonce);
+    if (!nonceResult.ok) {
+      return this._fail('replay detected', { keyId, nonce }, nonceResult);
+    }
+
+    return { ok: true };
+  }
+
+  /**
+   * Records an auth failure and returns the result.
+   * @param {string} message
+   * @param {Record<string, *>} context
+   * @param {{ ok: false, reason: string, status: number }} result
+   * @returns {{ ok: false, reason: string, status: number }}
+   * @private
+   */
+  _fail(message, context, result) {
+    this._metrics.authFailCount += 1;
+    this._logger.warn(`sync auth: ${message}`, context);
+    return result;
+  }
+
+  /**
+   * Increments the log-only passthrough counter.
+   */
+  recordLogOnlyPassthrough() {
+    this._metrics.logOnlyPassthroughs += 1;
+  }
+
+  /**
+   * Returns a snapshot of auth metrics.
+   *
+   * @returns {{ authFailCount: number, replayRejectCount: number, nonceEvictions: number, clockSkewRejects: number, malformedRejects: number, logOnlyPassthroughs: number }}
+   */
+  getMetrics() {
+    return { ...this._metrics };
+  }
+}

package/src/domain/services/SyncProtocol.js

@@ -56,18 +56,16 @@ import { vvDeserialize } from '../crdt/VersionVector.js';
  * **Mutation**: This function mutates the input patch object for efficiency.
  * The original object reference is returned.
  *
- * @param {Object} patch - The raw decoded patch from CBOR
- * @param {Object|Map} [patch.context] - The causal context (version vector).
- *   If present as a plain object, will be converted to a Map.
- * @param {Array} patch.ops - The patch operations (not modified)
- * @returns {Object} The same patch object with context converted to Map
+ * @param {{ context?: Object | Map<any, any>, ops: any[] }} patch - The raw decoded patch from CBOR.
+ *   If context is present as a plain object, it will be converted to a Map.
+ * @returns {{ context?: Object | Map<any, any>, ops: any[] }} The same patch object with context converted to Map
  * @private
  */
 function normalizePatch(patch) {
   // Convert context from plain object to Map (VersionVector)
   // CBOR deserialization returns plain objects, but join() expects a Map
   if (patch.context && !(patch.context instanceof Map)) {
-    patch.context = vvDeserialize(patch.context);
+    patch.context = vvDeserialize(/** @type {{ [x: string]: number }} */ (patch.context));
   }
   return patch;
 }
@@ -85,12 +83,12 @@ function normalizePatch(patch) {
  * **Commit message format**: The message is encoded using WarpMessageCodec
  * and contains metadata (schema version, writer info) plus the patch OID.
  *
- * @param {import('../../ports/GraphPersistencePort.js').default} persistence - Git persistence layer
+ * @param {import('../../ports/GraphPersistencePort.js').default & import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default} persistence - Git persistence layer
  *   (uses CommitPort.showNode() + BlobPort.readBlob() methods)
  * @param {string} sha - The 40-character commit SHA to load the patch from
  * @param {Object} [options]
  * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
- * @returns {Promise<Object>} The decoded and normalized patch object containing:
+ * @returns {Promise<{ context?: Object | Map<any, any>, ops: any[] }>} The decoded and normalized patch object containing:
  *   - `ops`: Array of patch operations
  *   - `context`: VersionVector (Map) of causal dependencies
  *   - `writerId`: The writer who created this patch
@@ -101,7 +99,7 @@ function normalizePatch(patch) {
  * @throws {Error} If the patch blob cannot be CBOR-decoded (corrupted data)
  * @private
  */
-async function loadPatchFromCommit(persistence, sha, { codec: codecOpt } = {}) {
+async function loadPatchFromCommit(persistence, sha, { codec: codecOpt } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
   const codec = codecOpt || defaultCodec;
   // Read commit message to extract patch OID
   const message = await persistence.showNode(sha);
@@ -109,7 +107,7 @@ async function loadPatchFromCommit(persistence, sha, { codec: codecOpt } = {}) {
 
   // Read and decode the patch blob
   const patchBuffer = await persistence.readBlob(decoded.patchOid);
-  const patch = codec.decode(patchBuffer);
+  const patch = /** @type {{ context?: Object | Map<any, any>, ops: any[] }} */ (codec.decode(patchBuffer));
 
   // Normalize the patch (convert context from object to Map)
   return normalizePatch(patch);
@@ -129,7 +127,7 @@ async function loadPatchFromCommit(persistence, sha, { codec: codecOpt } = {}) {
  * **Performance**: O(N) where N is the number of commits between fromSha and toSha.
  * Each commit requires two reads: commit info (for parent) and patch blob.
  *
- * @param {import('../../ports/GraphPersistencePort.js').default} persistence - Git persistence layer
+ * @param {import('../../ports/GraphPersistencePort.js').default & import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default} persistence - Git persistence layer
  *   (uses CommitPort.getNodeInfo()/showNode() + BlobPort.readBlob() methods)
  * @param {string} graphName - Graph name (used in error messages, not for lookups)
  * @param {string} writerId - Writer ID (used in error messages, not for lookups)
@@ -154,7 +152,7 @@ async function loadPatchFromCommit(persistence, sha, { codec: codecOpt } = {}) {
  * // Load ALL patches for a new writer
  * const patches = await loadPatchRange(persistence, 'events', 'new-writer', null, tipSha);
  */
-export async function loadPatchRange(persistence, graphName, writerId, fromSha, toSha, { codec } = {}) {
+export async function loadPatchRange(persistence, graphName, writerId, fromSha, toSha, { codec } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
   const patches = [];
   let cur = toSha;
 
@@ -172,9 +170,9 @@ export async function loadPatchRange(persistence, graphName, writerId, fromSha,
 
   // If fromSha was specified but we didn't reach it, we have divergence
   if (fromSha && cur === null) {
-    const err = new Error(
+    const err = /** @type {Error & { code: string }} */ (new Error(
       `Divergence detected: ${toSha} does not descend from ${fromSha} for writer ${writerId}`
-    );
+    ));
     err.code = 'E_SYNC_DIVERGENCE';
     throw err;
   }
@@ -214,11 +212,7 @@ export async function loadPatchRange(persistence, graphName, writerId, fromSha,
  *   Maps writerId to the SHA of their latest patch commit.
  * @param {Map<string, string>} remoteFrontier - Remote writer heads.
  *   Maps writerId to the SHA of their latest patch commit.
- * @returns {Object} Sync delta containing:
- *   - `needFromRemote`: Map<writerId, {from: string|null, to: string}> - Patches local needs
- *   - `needFromLocal`: Map<writerId, {from: string|null, to: string}> - Patches remote needs
- *   - `newWritersForLocal`: string[] - Writers that local has never seen
- *   - `newWritersForRemote`: string[] - Writers that remote has never seen
+ * @returns {{ needFromRemote: Map<string, {from: string|null, to: string}>, needFromLocal: Map<string, {from: string|null, to: string}>, newWritersForLocal: string[], newWritersForRemote: string[] }} Sync delta
  *
  * @example
  * const local = new Map([['w1', 'sha-a'], ['w2', 'sha-b']]);
@@ -333,13 +327,14 @@ export function computeSyncDelta(localFrontier, remoteFrontier) {
  */
 export function createSyncRequest(frontier) {
   // Convert Map to plain object for serialization
+  /** @type {{ [x: string]: string }} */
   const frontierObj = {};
   for (const [writerId, sha] of frontier) {
     frontierObj[writerId] = sha;
   }
 
   return {
-    type: 'sync-request',
+    type: /** @type {'sync-request'} */ ('sync-request'),
     frontier: frontierObj,
   };
 }
@@ -363,7 +358,7 @@ export function createSyncRequest(frontier) {
  *
  * @param {SyncRequest} request - Incoming sync request containing the requester's frontier
  * @param {Map<string, string>} localFrontier - Local frontier (what this node has)
- * @param {import('../../ports/GraphPersistencePort.js').default} persistence - Git persistence
+ * @param {import('../../ports/GraphPersistencePort.js').default & import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default} persistence - Git persistence
  *   layer for loading patches (uses CommitPort + BlobPort methods)
  * @param {string} graphName - Graph name for error messages and logging
  * @returns {Promise<SyncResponse>} Response containing local frontier and patches.
@@ -379,7 +374,7 @@ export function createSyncRequest(frontier) {
  *   res.json(response);
  * });
  */
-export async function processSyncRequest(request, localFrontier, persistence, graphName, { codec } = {}) {
+export async function processSyncRequest(request, localFrontier, persistence, graphName, { codec } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
   // Convert incoming frontier from object to Map
   const remoteFrontier = new Map(Object.entries(request.frontier));
 
@@ -406,7 +401,7 @@ export async function processSyncRequest(request, localFrontier, persistence, gr
     } catch (err) {
       // If we detect divergence, skip this writer
       // The requester may need to handle this separately
-      if (err.code === 'E_SYNC_DIVERGENCE' || err.message.includes('Divergence detected')) {
+      if (/** @type {any} */ (err).code === 'E_SYNC_DIVERGENCE' || /** @type {any} */ (err).message?.includes('Divergence detected')) { // TODO(ts-cleanup): type error
         continue;
       }
       throw err;
@@ -414,13 +409,14 @@ export async function processSyncRequest(request, localFrontier, persistence, gr
   }
 
   // Convert local frontier to plain object
+  /** @type {{ [x: string]: string }} */
   const frontierObj = {};
   for (const [writerId, sha] of localFrontier) {
     frontierObj[writerId] = sha;
   }
 
   return {
-    type: 'sync-response',
+    type: /** @type {'sync-response'} */ ('sync-response'),
     frontier: frontierObj,
     patches,
   };
@@ -495,7 +491,7 @@ export function applySyncResponse(response, state, frontier) {
       // will prevent silent data loss until the reader is upgraded.
       assertOpsCompatible(normalizedPatch.ops, SCHEMA_V3);
       // Apply patch to state
-      join(newState, normalizedPatch, sha);
+      join(newState, /** @type {*} */ (normalizedPatch), sha); // TODO(ts-cleanup): type patch array
       applied++;
     }
 
@@ -580,13 +576,14 @@ export function syncNeeded(localFrontier, remoteFrontier) {
  * }
  */
 export function createEmptySyncResponse(frontier) {
+  /** @type {{ [x: string]: string }} */
   const frontierObj = {};
   for (const [writerId, sha] of frontier) {
     frontierObj[writerId] = sha;
   }
 
   return {
-    type: 'sync-response',
+    type: /** @type {'sync-response'} */ ('sync-response'),
     frontier: frontierObj,
     patches: [],
   };

package/src/domain/services/TemporalQuery.js

@@ -60,10 +60,11 @@ function unwrapValue(value) {
  *
  * @param {import('./JoinReducer.js').WarpStateV5} state - Current state
  * @param {string} nodeId - Node ID to extract
- * @returns {{ id: string, exists: boolean, props: Object<string, *> }}
+ * @returns {{ id: string, exists: boolean, props: Record<string, *> }}
  */
 function extractNodeSnapshot(state, nodeId) {
   const exists = orsetContains(state.nodeAlive, nodeId);
+  /** @type {Record<string, *>} */
   const props = {};
 
   if (exists) {
@@ -108,7 +109,7 @@ export class TemporalQuery {
    * @param {string} nodeId - The node ID to evaluate
    * @param {Function} predicate - Predicate receiving node snapshot
    *   `{ id, exists, props }`. Should return boolean.
-   * @param {{ since?: number }} [options={}] - Options
+   * @param {Object} [options={}] - Options
    * @param {number} [options.since=0] - Minimum Lamport tick (inclusive).
    *   Only patches with lamport >= since are considered.
    * @returns {Promise<boolean>} True if predicate held at every tick
@@ -161,7 +162,7 @@ export class TemporalQuery {
    * @param {string} nodeId - The node ID to evaluate
    * @param {Function} predicate - Predicate receiving node snapshot
    *   `{ id, exists, props }`. Should return boolean.
-   * @param {{ since?: number }} [options={}] - Options
+   * @param {Object} [options={}] - Options
    * @param {number} [options.since=0] - Minimum Lamport tick (inclusive).
    *   Only patches with lamport >= since are considered.
    * @returns {Promise<boolean>} True if predicate held at any tick

package/src/domain/services/TranslationCost.js

@@ -94,8 +94,8 @@ function zeroCost() {
 /**
  * Counts how many items in `source` are absent from `targetSet`.
  *
- * @param {Array|Set} source - Source collection
- * @param {Set} targetSet - Target set to test against
+ * @param {Array<string>|Set<string>} source - Source collection
+ * @param {Set<string>} targetSet - Target set to test against
  * @returns {number}
  */
 function countMissing(source, targetSet) {
@@ -141,7 +141,7 @@ function computeEdgeLoss(state, nodesASet, nodesBSet) {
  * Counts lost properties for a single node between two observer configs.
  *
  * @param {Map<string, boolean>} nodeProps - Property keys for the node
- * @param {{ configA: Object, configB: Object, nodeInB: boolean }} opts
+ * @param {{ configA: {expose?: string[], redact?: string[]}, configB: {expose?: string[], redact?: string[]}, nodeInB: boolean }} opts
  * @returns {{ propsInA: number, lostProps: number }}
  */
 function countNodePropLoss(nodeProps, { configA, configB, nodeInB }) {
@@ -157,7 +157,7 @@ function countNodePropLoss(nodeProps, { configA, configB, nodeInB }) {
  * Computes property loss across all A-visible nodes.
  *
  * @param {*} state - WarpStateV5
- * @param {{ nodesA: string[], nodesBSet: Set<string>, configA: Object, configB: Object }} opts
+ * @param {{ nodesA: string[], nodesBSet: Set<string>, configA: {expose?: string[], redact?: string[]}, configB: {expose?: string[], redact?: string[]} }} opts
  * @returns {number} propLoss fraction
  */
 function computePropLoss(state, { nodesA, nodesBSet, configA, configB }) {