@remnic/core 9.3.624 → 9.3.625

package/src/wearables/redaction.ts

@@ -0,0 +1,156 @@
+/**
+ * Wearable transcript redaction — privacy guard applied before any
+ * transcript text is persisted or fed to extraction.
+ *
+ * Always-on recorders capture things nobody intended to store: card
+ * numbers read aloud, SSNs dictated to a pharmacy line. Built-in
+ * patterns cover the unambiguous, high-sensitivity cases; users can add
+ * their own regexes via `wearables.redactionPatterns` (validated at
+ * config parse — invalid patterns are rejected loudly, never ignored).
+ *
+ * All built-in patterns are simple linear scans (no nested quantifiers)
+ * to stay safely outside polynomial-ReDoS territory.
+ */
+
+import type { WearableConversation } from "./types.js";
+
+export const REDACTION_PLACEHOLDER = "[redacted]";
+
+/**
+ * Built-in patterns. Conservative by design — false positives erase
+ * real transcript content, so each pattern targets formats that are
+ * near-certain PII:
+ *  - US SSN with separators (123-45-6789). Bare 9-digit runs are NOT
+ *    matched (too many false positives: ids, tracking numbers).
+ *  - Payment-card-like runs: 13–19 digits in groups separated by
+ *    spaces/dashes (4111 1111 1111 1111) or contiguous 15–16 digits.
+ */
+const BUILT_IN_PATTERNS: RegExp[] = [
+  /\b\d{3}-\d{2}-\d{4}\b/g,
+  // Starts and ENDS on a digit so a trailing separator is never
+  // consumed (replacing it would glue the placeholder to the next word).
+  /\b\d(?:[ -]?\d){12,18}\b/g,
+];
+
+/** Minimum digit count before a digit-run is treated as a card number. */
+const CARD_MIN_DIGITS = 13;
+
+export interface RedactionResult {
+  text: string;
+  redactions: number;
+}
+
+export function redactText(
+  text: string,
+  userPatterns: RegExp[],
+): RedactionResult {
+  let redactions = 0;
+  let result = text;
+
+  // SSN pattern first (more specific than the digit-run pattern).
+  result = result.replace(BUILT_IN_PATTERNS[0], () => {
+    redactions += 1;
+    return REDACTION_PLACEHOLDER;
+  });
+
+  // Digit-run pattern with a post-match digit-count check so short
+  // grouped numbers ("call 555 0125 today") survive.
+  result = result.replace(BUILT_IN_PATTERNS[1], (match) => {
+    const digits = match.replace(/\D/g, "");
+    if (digits.length < CARD_MIN_DIGITS || digits.length > 19) {
+      return match;
+    }
+    redactions += 1;
+    return REDACTION_PLACEHOLDER;
+  });
+
+  for (const pattern of userPatterns) {
+    result = result.replace(pattern, () => {
+      redactions += 1;
+      return REDACTION_PLACEHOLDER;
+    });
+  }
+
+  return { text: result, redactions };
+}
+
+/**
+ * Compile user-supplied redaction patterns. Throws with a descriptive
+ * message on the first invalid pattern — config parsing surfaces this
+ * to the operator instead of silently skipping the rule.
+ */
+export function compileRedactionPatterns(patterns: string[]): RegExp[] {
+  return patterns.map((pattern, index) => {
+    if (typeof pattern !== "string" || pattern.trim().length === 0) {
+      throw new Error(
+        `wearables.redactionPatterns[${index}] must be a non-empty string`,
+      );
+    }
+    if (pattern.length > 256) {
+      throw new Error(
+        `wearables.redactionPatterns[${index}] exceeds 256 characters — redaction patterns must stay short`,
+      );
+    }
+    try {
+      // Operator-supplied regexes from the operator's own config —
+      // length-capped above; never request input.
+      return new RegExp(pattern, "gi");
+    } catch (err) {
+      throw new Error(
+        `wearables.redactionPatterns[${index}] is not a valid regular expression: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    }
+  });
+}
+
+const OFF_THE_RECORD = /\boff\s+the\s+record\b/i;
+const BACK_ON_THE_RECORD = /\b(?:back\s+)?on\s+the\s+record\b/i;
+
+export interface OffTheRecordResult {
+  conversation: WearableConversation;
+  droppedSegments: number;
+}
+
+/**
+ * Drop segments between a spoken "off the record" marker and the next
+ * "(back) on the record" marker (or conversation end). The marker
+ * segments themselves are kept, with the off-record span replaced by a
+ * visible placeholder so the transcript shows that content was elided
+ * by request rather than lost.
+ */
+export function applyOffTheRecord(
+  conversation: WearableConversation,
+): OffTheRecordResult {
+  let offRecord = false;
+  let droppedSegments = 0;
+  const segments = [];
+  for (const segment of conversation.segments) {
+    if (!offRecord && OFF_THE_RECORD.test(segment.text)) {
+      offRecord = true;
+      segments.push({
+        ...segment,
+        text: "[off the record — segment elided]",
+      });
+      continue;
+    }
+    if (offRecord) {
+      if (BACK_ON_THE_RECORD.test(segment.text)) {
+        offRecord = false;
+        segments.push({
+          ...segment,
+          text: "[back on the record]",
+        });
+      } else {
+        droppedSegments += 1;
+      }
+      continue;
+    }
+    segments.push(segment);
+  }
+  return {
+    conversation: { ...conversation, segments },
+    droppedSegments,
+  };
+}

package/src/wearables/registry.test.ts

@@ -0,0 +1,62 @@
+import assert from "node:assert/strict";
+import { afterEach, test } from "node:test";
+
+import {
+  clearWearableConnectors,
+  ensureBuiltInWearableConnectors,
+  getWearableConnector,
+  listWearableConnectors,
+  registerWearableConnector,
+} from "./registry.js";
+
+afterEach(() => {
+  clearWearableConnectors();
+});
+
+function registration(id = "testsource") {
+  return {
+    id,
+    displayName: "Test Source",
+    factory: () => ({
+      id,
+      displayName: "Test Source",
+      verifyAuth: async () => ({ ok: true }),
+      fetchConversations: async () => ({ conversations: [], nextCursor: null }),
+    }),
+  };
+}
+
+test("register + get + list round-trip", () => {
+  registerWearableConnector(registration());
+  assert.ok(getWearableConnector("testsource"));
+  assert.deepEqual(listWearableConnectors(), ["testsource"]);
+  assert.equal(getWearableConnector("missing"), undefined);
+  assert.equal(getWearableConnector(""), undefined);
+});
+
+test("duplicate registration throws; ids are trimmed", () => {
+  registerWearableConnector(registration());
+  assert.throws(() => registerWearableConnector(registration()), /already registered/);
+  registerWearableConnector(registration("  spaced  ") as never);
+  assert.ok(getWearableConnector("spaced"));
+});
+
+test("invalid registrations are rejected", () => {
+  assert.throws(
+    () => registerWearableConnector({ id: "", displayName: "x", factory: () => ({}) } as never),
+    /non-empty string/,
+  );
+  assert.throws(
+    () => registerWearableConnector({ id: "x", displayName: "x" } as never),
+    /factory function/,
+  );
+});
+
+test("ensureBuiltInWearableConnectors tolerates absent optional packages", async () => {
+  // In the core package's own test environment the connector packages
+  // may or may not be installed; the loader must succeed either way and
+  // never throw for a missing optional package.
+  await ensureBuiltInWearableConnectors();
+  await ensureBuiltInWearableConnectors();
+  assert.ok(Array.isArray(listWearableConnectors()));
+});

package/src/wearables/registry.ts

@@ -0,0 +1,133 @@
+/**
+ * Wearable connector registry.
+ *
+ * Concrete connectors live in optional à-la-carte packages and register
+ * a factory here (directly, or via the built-in loader below which
+ * dynamic-imports the known packages with computed specifiers so
+ * bundlers and the dts resolver never require them at build time).
+ */
+
+import { log } from "../logger.js";
+import type {
+  WearableSourceConnector,
+  WearableSourceSettings,
+} from "./types.js";
+
+export interface WearableConnectorFactoryOptions {
+  settings: WearableSourceSettings;
+  /** IANA timezone transcripts are bucketed in. */
+  timezone: string;
+}
+
+export type WearableConnectorFactory = (
+  options: WearableConnectorFactoryOptions,
+) => WearableSourceConnector;
+
+export interface WearableConnectorRegistration {
+  id: string;
+  displayName: string;
+  factory: WearableConnectorFactory;
+}
+
+const registrations = new Map<string, WearableConnectorRegistration>();
+
+export function registerWearableConnector(
+  registration: WearableConnectorRegistration,
+): void {
+  if (!registration || typeof registration !== "object") {
+    throw new Error("wearable connector registration must be an object");
+  }
+  if (
+    typeof registration.id !== "string" ||
+    registration.id.trim().length === 0
+  ) {
+    throw new Error("wearable connector id must be a non-empty string");
+  }
+  if (typeof registration.factory !== "function") {
+    throw new Error(
+      `wearable connector '${registration.id}' must provide a factory function`,
+    );
+  }
+  const key = registration.id.trim();
+  if (registrations.has(key)) {
+    throw new Error(`wearable connector '${key}' is already registered`);
+  }
+  registrations.set(key, { ...registration, id: key });
+}
+
+export function getWearableConnector(
+  id: string,
+): WearableConnectorRegistration | undefined {
+  if (typeof id !== "string") return undefined;
+  const key = id.trim();
+  if (key.length === 0) return undefined;
+  return registrations.get(key);
+}
+
+export function listWearableConnectors(): string[] {
+  return [...registrations.keys()];
+}
+
+/** Test-only: reset the registry between cases. */
+export function clearWearableConnectors(): void {
+  registrations.clear();
+}
+
+/**
+ * Built-in connector packages, tried in order. Each entry is loaded via
+ * a computed-specifier dynamic import (see optional-bench.ts in
+ * @remnic/cli for the canonical à-la-carte pattern); a missing package
+ * is silently skipped, any other load error is logged once and skipped
+ * so one broken connector never takes down the others.
+ */
+const BUILT_IN_CONNECTOR_PACKAGES: Array<{ id: string; suffix: string }> = [
+  { id: "limitless", suffix: "connector-limitless" },
+  { id: "bee", suffix: "connector-bee" },
+  { id: "omi", suffix: "connector-omi" },
+];
+
+const loadFailuresWarned = new Set<string>();
+
+export async function ensureBuiltInWearableConnectors(): Promise<void> {
+  for (const entry of BUILT_IN_CONNECTOR_PACKAGES) {
+    if (registrations.has(entry.id)) continue;
+    const specifier = "@remnic/" + entry.suffix;
+    let mod: { wearableConnectorRegistration?: WearableConnectorRegistration };
+    try {
+      mod = (await import(specifier)) as {
+        wearableConnectorRegistration?: WearableConnectorRegistration;
+      };
+    } catch (err) {
+      if (isModuleNotFound(err, specifier)) continue;
+      if (!loadFailuresWarned.has(specifier)) {
+        loadFailuresWarned.add(specifier);
+        log.warn(
+          `wearables: failed to load optional connector package ${specifier}: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
+      }
+      continue;
+    }
+    const registration = mod.wearableConnectorRegistration;
+    if (!registration) continue;
+    try {
+      registerWearableConnector(registration);
+    } catch {
+      // Already registered by a direct import — fine.
+    }
+  }
+}
+
+function isModuleNotFound(err: unknown, specifier: string): boolean {
+  if (!err || typeof err !== "object") return false;
+  const code = (err as { code?: unknown }).code;
+  if (code !== "ERR_MODULE_NOT_FOUND" && code !== "MODULE_NOT_FOUND") {
+    return false;
+  }
+  const message = (err as { message?: unknown }).message;
+  // Only treat the failure as "optional package absent" when the error
+  // names the specifier we asked for — a transitive resolution failure
+  // inside an installed connector is a broken install worth surfacing.
+  return typeof message === "string" && message.includes(specifier);
+}