switchroom 0.5.0

package/telegram-plugin/secret-detect/pipeline.ts

@@ -0,0 +1,144 @@
+/**
+ * High-level orchestrator: take an inbound user text, run the detector,
+ * decide per-detection whether to auto-store or stage as ambiguous, rewrite
+ * the prompt so Claude never sees raw bytes, and emit audit events.
+ *
+ * Pure of side effects *except* the injected vault-write function — keeping
+ * the real child-process spawn out of the hot path keeps this unit-testable
+ * and lets us stub it from server.ts.
+ *
+ * The vault passphrase must already be resolved by the caller (via the
+ * plugin's existing `vaultPassphraseCache`). If the cache is empty, this
+ * returns early with `needs_passphrase=true` — the caller prompts the user
+ * and re-invokes.
+ */
+import { detectSecrets, type Detection } from './index.js'
+import { rewritePrompt, type RewriteTarget } from './rewrite.js'
+import { deriveSlug } from './slug.js'
+import { emitAudit } from './audit.js'
+import { maskToken } from './mask.js'
+import type { VaultWriteFn, VaultListFn } from './vault-write.js'
+
+export interface PipelineInputs {
+  chat_id: string
+  message_id: number | null
+  text: string
+  passphrase: string
+  vaultWrite: VaultWriteFn
+  vaultList: VaultListFn
+}
+
+export interface ConfirmedStore {
+  detection: Detection
+  actual_slug: string
+  masked: string
+}
+
+export interface PipelineResult {
+  /** The rewritten text — this is what Claude sees. Equals input when no confirmed hits. */
+  rewritten_text: string
+  /** Confirmed stores (high-confidence, not suppressed) that were written to the vault. */
+  stored: ConfirmedStore[]
+  /** Ambiguous hits (entropy-only, or suppressed) requiring user confirmation. */
+  ambiguous: Detection[]
+  /** Failed stores — detection found but vault write failed. Caller should surface. */
+  failed: Array<{ detection: Detection; error: string }>
+}
+
+export function runPipeline(inputs: PipelineInputs): PipelineResult {
+  const { chat_id, message_id, text, passphrase, vaultWrite, vaultList } = inputs
+
+  const detections = detectSecrets(text)
+  if (detections.length === 0) {
+    return { rewritten_text: text, stored: [], ambiguous: [], failed: [] }
+  }
+
+  // Separate confirmed (high + !suppressed) from ambiguous.
+  const confirmed: Detection[] = []
+  const ambiguous: Detection[] = []
+  for (const d of detections) {
+    if (d.confidence === 'high' && !d.suppressed) {
+      confirmed.push(d)
+    } else {
+      ambiguous.push(d)
+    }
+  }
+
+  if (confirmed.length === 0) {
+    // All ambiguous — log them and return; caller stages.
+    for (const d of ambiguous) {
+      emitAudit({
+        chat_id,
+        message_id,
+        rule_id: d.rule_id,
+        slug: d.suggested_slug,
+        action: 'ambiguous',
+        delete_ok: false,
+      })
+    }
+    return { rewritten_text: text, stored: [], ambiguous, failed: [] }
+  }
+
+  // Read the current vault key set ONCE so we can resolve collisions
+  // across multiple hits in the same message.
+  const listResult = vaultList(passphrase)
+  const existing = new Set(listResult.ok ? listResult.keys : [])
+
+  const stored: ConfirmedStore[] = []
+  const failed: Array<{ detection: Detection; error: string }> = []
+
+  for (const d of confirmed) {
+    const actual_slug = deriveSlug(
+      { key_name: d.key_name, rule_id: d.rule_id },
+      existing,
+    )
+    const writeResult = vaultWrite(actual_slug, d.matched_text, passphrase)
+    if (!writeResult.ok) {
+      failed.push({ detection: d, error: writeResult.output })
+      emitAudit({
+        chat_id,
+        message_id,
+        rule_id: d.rule_id,
+        slug: actual_slug,
+        action: 'failed',
+        delete_ok: false,
+        detail: writeResult.output.slice(0, 200),
+      })
+      continue
+    }
+    existing.add(actual_slug)
+    stored.push({
+      detection: d,
+      actual_slug,
+      masked: maskToken(d.matched_text),
+    })
+    emitAudit({
+      chat_id,
+      message_id,
+      rule_id: d.rule_id,
+      slug: actual_slug,
+      action: 'stored',
+      delete_ok: false, // caller updates after Telegram deleteMessage
+    })
+  }
+
+  // Also log ambiguous entries that co-occurred with confirmed ones.
+  for (const d of ambiguous) {
+    emitAudit({
+      chat_id,
+      message_id,
+      rule_id: d.rule_id,
+      slug: d.suggested_slug,
+      action: d.suppressed ? 'suppressed' : 'ambiguous',
+      delete_ok: false,
+    })
+  }
+
+  const targets: RewriteTarget[] = stored.map((s) => ({
+    detection: s.detection,
+    actual_slug: s.actual_slug,
+  }))
+  const rewritten_text = rewritePrompt(text, targets)
+
+  return { rewritten_text, stored, ambiguous, failed }
+}

package/telegram-plugin/secret-detect/rewrite.ts

@@ -0,0 +1,26 @@
+/**
+ * Apply a list of detections to the original text, replacing each secret
+ * with `[secret stored as vault:${slug}]`. The slug map tells us which
+ * slug each detection was actually stored under (the detector's
+ * `suggested_slug` may have been bumped on collision).
+ *
+ * Replacements are applied right-to-left so earlier byte offsets stay
+ * valid as we mutate the string.
+ */
+import type { Detection } from './index.js'
+
+export interface RewriteTarget {
+  detection: Detection
+  actual_slug: string
+}
+
+export function rewritePrompt(text: string, targets: RewriteTarget[]): string {
+  if (targets.length === 0) return text
+  const sorted = [...targets].sort((a, b) => b.detection.start - a.detection.start)
+  let out = text
+  for (const t of sorted) {
+    const { start, end } = t.detection
+    out = out.slice(0, start) + `[secret stored as vault:${t.actual_slug}]` + out.slice(end)
+  }
+  return out
+}

package/telegram-plugin/secret-detect/secretlint-source.ts

@@ -0,0 +1,95 @@
+/**
+ * Secretlint wrapper — adapts `@secretlint/core` + the recommend preset into
+ * our `Detection` shape so it can merge with the vendored pattern engine.
+ *
+ * Secretlint is async (it loads rules, applies preset config, walks the
+ * source). This module exposes `detectViaSecretlint(text)` returning a
+ * Promise. The synchronous `detectSecrets()` path in `index.ts` stays the
+ * fast default; callers that want the full engine use `detectSecretsAsync()`
+ * which fans out both and merges.
+ *
+ * Slug derivation: Secretlint rules don't give us a clean LHS (KEY=value),
+ * so we derive from the rule id (e.g. `@secretlint/secretlint-rule-slack`
+ * becomes the slug `@secretlint-rule-slack_YYYYMMDD` via `deriveSlug`'s
+ * rule_id + date fallback path).
+ *
+ * Confidence tier: Secretlint is a curated engine with checksum-validated
+ * rules for most providers, so every hit is `high`.
+ */
+
+import { lintSource } from '@secretlint/core'
+import { creator as presetRecommendCreator } from '@secretlint/secretlint-rule-preset-recommend'
+import type { Detection } from './index.js'
+import { deriveSlug } from './slug.js'
+import { isSuppressed } from './suppressor.js'
+
+/**
+ * Map a single Secretlint rule id to a short rule slug used as the
+ * `Detection.rule_id`. The full `@secretlint/secretlint-rule-foo` names are
+ * long; we strip the scope/prefix to keep rule_ids readable in logs.
+ */
+function normalizeRuleId(secretlintRuleId: string): string {
+  // "@secretlint/secretlint-rule-slack" → "secretlint_slack"
+  // "secretlint-rule-custom-thing"       → "secretlint_custom_thing"
+  const stripped = secretlintRuleId
+    .replace(/^@secretlint\//, '')
+    .replace(/^secretlint-rule-/, '')
+    .replace(/[^A-Za-z0-9]+/g, '_')
+    .replace(/_+/g, '_')
+    .replace(/^_+|_+$/g, '')
+  return `secretlint_${stripped || 'unknown'}`
+}
+
+export async function detectViaSecretlint(text: string): Promise<Detection[]> {
+  if (!text || text.length === 0) return []
+
+  let result
+  try {
+    result = await lintSource({
+      source: {
+        content: text,
+        filePath: 'message.txt',
+        ext: '.txt',
+        contentType: 'text',
+      },
+      options: {
+        config: {
+          rules: [
+            {
+              id: '@secretlint/secretlint-rule-preset-recommend',
+              rule: presetRecommendCreator,
+            },
+          ],
+        },
+        noPhysicFilePath: true,
+      },
+    })
+  } catch {
+    // Fail-open: Secretlint crashes must never break the detector path.
+    return []
+  }
+
+  const existing = new Set<string>()
+  const out: Detection[] = []
+  for (const msg of result.messages) {
+    const [start, end] = msg.range
+    if (typeof start !== 'number' || typeof end !== 'number' || end <= start) continue
+    const matched_text = text.slice(start, end)
+    if (!matched_text) continue
+    const rule_id = normalizeRuleId(msg.ruleId)
+    const suggested_slug = deriveSlug({ rule_id }, existing)
+    existing.add(suggested_slug)
+    out.push({
+      rule_id,
+      matched_text,
+      start,
+      end,
+      confidence: 'high',
+      suppressed: isSuppressed(text, start, end),
+      suggested_slug,
+    })
+  }
+  return out
+}
+
+export { normalizeRuleId as __normalizeRuleId }

package/telegram-plugin/secret-detect/slug.ts

@@ -0,0 +1,44 @@
+/**
+ * Vault slug derivation for a detected secret.
+ *
+ * Preference order:
+ *   1. If the detection knows the LHS of `KEY=value`, sanitize it to
+ *      `[A-Z0-9_]+` (uppercase, underscores for separators, strip other chars).
+ *   2. Otherwise use `${rule_name}_${YYYYMMDD}`.
+ *
+ * Collision handling: if `slug` already exists in `existing`, append
+ * `_2`, `_3`, ... until free.
+ */
+
+export function sanitizeKeyName(raw: string): string {
+  // Upper, replace non-[A-Z0-9_] with `_`, collapse runs, trim leading/trailing `_`.
+  const up = raw.toUpperCase()
+  const cleaned = up.replace(/[^A-Z0-9_]+/g, '_').replace(/_+/g, '_').replace(/^_+|_+$/g, '')
+  return cleaned.length > 0 ? cleaned : 'SECRET'
+}
+
+export function datePart(now: Date = new Date()): string {
+  const y = now.getUTCFullYear()
+  const m = String(now.getUTCMonth() + 1).padStart(2, '0')
+  const d = String(now.getUTCDate()).padStart(2, '0')
+  return `${y}${m}${d}`
+}
+
+export interface SlugInputs {
+  key_name?: string
+  rule_id: string
+  now?: Date
+}
+
+export function deriveSlug(inputs: SlugInputs, existing: Set<string>): string {
+  let base: string
+  if (inputs.key_name && inputs.key_name.trim().length > 0) {
+    base = sanitizeKeyName(inputs.key_name)
+  } else {
+    base = `${inputs.rule_id}_${datePart(inputs.now)}`
+  }
+  if (!existing.has(base)) return base
+  let n = 2
+  while (existing.has(`${base}_${n}`)) n++
+  return `${base}_${n}`
+}

package/telegram-plugin/secret-detect/staging.ts

@@ -0,0 +1,85 @@
+/**
+ * In-memory staging map for ambiguous secret hits.
+ *
+ * When the detector returns an ambiguous detection (entropy-only, or a
+ * confirmed hit near suppressor markers), we don't auto-store or auto-delete.
+ * We park the detection in this map keyed by `(chat_id, message_id)` with a
+ * 5-minute TTL. Follow-up inbound commands — `stash NAME`, `ignore`, `rename
+ * X`, `forget` — look up the entry by chat and act on it.
+ *
+ * Keeping this as a plain Map (not SQLite) is intentional: the data is
+ * ephemeral, and a restart discarding in-flight ambiguous captures is
+ * the correct behavior (the user can re-paste if they still want it).
+ */
+
+import type { Detection } from './index.js'
+
+export interface StagedSecret {
+  chat_id: string
+  message_id: number
+  detection: Detection
+  staged_at: number
+}
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000
+
+export class StagingMap {
+  private readonly map = new Map<string, StagedSecret>()
+  constructor(private readonly ttlMs: number = DEFAULT_TTL_MS) {}
+
+  private key(chat_id: string, message_id: number): string {
+    return `${chat_id}:${message_id}`
+  }
+
+  set(entry: StagedSecret): void {
+    this.map.set(this.key(entry.chat_id, entry.message_id), entry)
+  }
+
+  get(chat_id: string, message_id: number): StagedSecret | undefined {
+    const k = this.key(chat_id, message_id)
+    const entry = this.map.get(k)
+    if (!entry) return undefined
+    if (Date.now() - entry.staged_at > this.ttlMs) {
+      this.map.delete(k)
+      return undefined
+    }
+    return entry
+  }
+
+  /**
+   * Return the most recent non-expired entry for a chat, regardless of
+   * message_id. Used to resolve `stash NAME` / `ignore` follow-ups where
+   * the user's reply message isn't the same as the original inbound.
+   */
+  latestForChat(chat_id: string): StagedSecret | undefined {
+    const now = Date.now()
+    let best: StagedSecret | undefined
+    for (const [k, v] of this.map) {
+      if (v.chat_id !== chat_id) continue
+      if (now - v.staged_at > this.ttlMs) {
+        this.map.delete(k)
+        continue
+      }
+      if (!best || v.staged_at > best.staged_at) best = v
+    }
+    return best
+  }
+
+  delete(chat_id: string, message_id: number): boolean {
+    return this.map.delete(this.key(chat_id, message_id))
+  }
+
+  /** Evict all expired entries. Idempotent. */
+  sweep(): void {
+    const now = Date.now()
+    for (const [k, v] of this.map) {
+      if (now - v.staged_at > this.ttlMs) {
+        this.map.delete(k)
+      }
+    }
+  }
+
+  size(): number {
+    return this.map.size
+  }
+}

package/telegram-plugin/secret-detect/suppressor.ts

@@ -0,0 +1,34 @@
+/**
+ * Context-based suppressor — downgrades hits that look like examples,
+ * fixtures, or test data based on nearby keywords.
+ *
+ * Spec: if any of `test`, `mock`, `example`, `fixture`, `dummy` appears as a
+ * whole word within 40 characters of the matched secret, mark the hit as
+ * `suppressed: true`.
+ *
+ * IMPORTANT — suppressed does NOT mean "silent-allow":
+ *   The pipeline routes `confidence: 'high' && suppressed: true` hits into
+ *   the AMBIGUOUS tier (see pipeline.ts), so the user is explicitly asked
+ *   `stash NAME` / `ignore` / `forget` / `rename`. We never silently pass
+ *   a structured-pattern match just because the word "test" is nearby.
+ *
+ *   Asymmetric risk: a false-negative leaks a real credential into the
+ *   agent's session log forever; a false-positive briefly redacts a fake
+ *   one and the user dismisses it with a single word. We bias toward the
+ *   user being the final arbiter on every structured-pattern hit.
+ *
+ *   See secret-detect-suppressor-no-silent-allow.test.ts for the
+ *   regression contract.
+ */
+const MARKERS = ['test', 'mock', 'example', 'fixture', 'dummy']
+const WINDOW = 40
+
+// Pre-compile a single regex for all markers as whole words.
+const MARKER_RE = new RegExp(`\\b(?:${MARKERS.join('|')})\\b`, 'i')
+
+export function isSuppressed(text: string, start: number, end: number): boolean {
+  const left = Math.max(0, start - WINDOW)
+  const right = Math.min(text.length, end + WINDOW)
+  const context = text.slice(left, start) + text.slice(end, right)
+  return MARKER_RE.test(context)
+}

package/telegram-plugin/secret-detect/url-redact.ts

@@ -0,0 +1,60 @@
+/**
+ * URL redactor — strip credentials and mask sensitive query params in place.
+ *
+ * Port of the openclaw `redact-sensitive-url` pattern. The goal isn't to
+ * *detect* a secret (that's what patterns.ts does) but to scrub URLs embedded
+ * in chat text before they're logged, echoed to the model, or stored in
+ * history. If a user pastes
+ *     https://u:p@api.example.com/x?api_key=abc123&trace=42
+ * the rewritten text becomes
+ *     https://***@api.example.com/x?api_key=***&trace=42
+ *
+ * Only string-level transformation — no network, no parsing beyond WHATWG URL.
+ */
+const SENSITIVE_PARAMS = new Set([
+  'token',
+  'key',
+  'api_key',
+  'apikey',
+  'secret',
+  'access_token',
+  'password',
+  'pass',
+  'auth',
+  'client_secret',
+  'refresh_token',
+  'signature',
+])
+
+// Loose URL regex — covers http(s)/ws(s)/ftp schemes. Intentionally permissive
+// on the tail; WHATWG URL parsing is what actually rejects garbage.
+const URL_RE = /\b(?:https?|wss?|ftp):\/\/[^\s<>"']+/gi
+
+export function redactUrls(text: string): string {
+  return text.replace(URL_RE, (m) => {
+    const redacted = redactOne(m)
+    return redacted ?? m
+  })
+}
+
+function redactOne(raw: string): string | null {
+  let u: URL
+  try {
+    u = new URL(raw)
+  } catch {
+    return null
+  }
+  let changed = false
+  if (u.username || u.password) {
+    u.username = '***'
+    u.password = ''
+    changed = true
+  }
+  for (const [key] of u.searchParams) {
+    if (SENSITIVE_PARAMS.has(key.toLowerCase())) {
+      u.searchParams.set(key, '***')
+      changed = true
+    }
+  }
+  return changed ? u.toString() : null
+}

package/telegram-plugin/secret-detect/vault-write.ts

@@ -0,0 +1,56 @@
+/**
+ * Programmatic vault write from the Telegram plugin path.
+ *
+ * Reuses the existing `runVaultCli`-style approach (spawn `switchroom vault
+ * set` with SWITCHROOM_VAULT_PASSPHRASE in env and the secret piped on
+ * stdin) so we don't have to import and open the vault directly from this
+ * subprocess.
+ *
+ * Exposed as a pure function for testability: callers inject the spawn
+ * helper in tests to avoid needing a real vault on disk.
+ */
+import { execFileSync } from 'node:child_process'
+
+export interface VaultWriteResult {
+  ok: boolean
+  output: string
+}
+
+export type VaultWriteFn = (
+  slug: string,
+  value: string,
+  passphrase: string,
+) => VaultWriteResult
+
+export type VaultListFn = (passphrase: string) => { ok: boolean; keys: string[] }
+
+export const defaultVaultWrite: VaultWriteFn = (slug, value, passphrase) => {
+  const env = { ...process.env, SWITCHROOM_VAULT_PASSPHRASE: passphrase }
+  try {
+    const result = execFileSync(
+      process.env.SWITCHROOM_CLI_PATH ?? 'switchroom',
+      ['vault', 'set', slug],
+      { input: value, encoding: 'utf8', env, timeout: 10000 },
+    )
+    return { ok: true, output: result.trim() }
+  } catch (err: unknown) {
+    const e = err as { stdout?: string; stderr?: string; message?: string }
+    const detail = [e.stdout, e.stderr, e.message].filter(Boolean).join('\n').trim()
+    return { ok: false, output: detail }
+  }
+}
+
+export const defaultVaultList: VaultListFn = (passphrase) => {
+  const env = { ...process.env, SWITCHROOM_VAULT_PASSPHRASE: passphrase }
+  try {
+    const result = execFileSync(
+      process.env.SWITCHROOM_CLI_PATH ?? 'switchroom',
+      ['vault', 'list'],
+      { encoding: 'utf8', env, timeout: 10000 },
+    )
+    const keys = result.split('\n').map((l) => l.trim()).filter(Boolean)
+    return { ok: true, keys }
+  } catch {
+    return { ok: false, keys: [] }
+  }
+}