wendkeep 0.86.0 → 0.88.0

package/packages/observer/src/policy.mjs

@@ -0,0 +1,305 @@
+import { createHash } from 'node:crypto';
+import { redactObserverValue } from './redaction.mjs';
+
+const CAPTURE = {
+  document: new Set(['none', 'metadata', 'selected', 'full']),
+  transcript: new Set(['none', 'metadata', 'messages', 'full']),
+  prompt: new Set(['none', 'redacted', 'full']),
+  response: new Set(['none', 'redacted', 'full']),
+  usage: new Set(['none', 'aggregate', 'calls']),
+};
+
+const DEFAULTS = Object.freeze({
+  document_capture: 'metadata',
+  transcript_capture: 'metadata',
+  prompt_capture: 'redacted',
+  response_capture: 'redacted',
+  usage_capture: 'aggregate',
+  require_loopback_auth: false,
+  encryption_required: false,
+});
+
+const SESSION_FIELDS = [
+  'session_id', 'sessionId', 'provider', 'status', 'change_slug', 'changeSlug',
+];
+const SESSION_TIMESTAMPS = ['started_at', 'startedAt', 'ended_at', 'endedAt'];
+const AGENT_FIELDS = [
+  ...SESSION_FIELDS, 'agent_id', 'agentId', 'parent_agent_id', 'parentAgentId',
+  'role', 'agent_type', 'agentType', 'workflow', 'model', 'effort',
+];
+
+function structuralFields(strings, integers = [], timestamps = []) {
+  return Object.freeze({
+    strings: Object.freeze(strings),
+    integers: Object.freeze(integers),
+    timestamps: Object.freeze(timestamps),
+  });
+}
+
+export const OBSERVER_EVENT_STRUCTURAL_CONTRACT = Object.freeze({
+  envelope: structuralFields(['event_id', 'kind', 'project_id'], ['schema_version'], ['occurred_at']),
+  payload: Object.freeze({
+    'document.upsert': structuralFields([
+      'document_id', 'documentId', 'logical_path', 'logicalPath', 'entity_type', 'entityType',
+      'source_session_id', 'sourceSessionId', 'source_turn_id', 'sourceTurnId',
+      'operation', 'op',
+    ], ['revision'], ['captured_at', 'capturedAt']),
+    'document.delete': structuralFields([
+      'logical_path', 'logicalPath', 'entity_type', 'entityType',
+      'source_session_id', 'sourceSessionId', 'source_turn_id', 'sourceTurnId',
+      'operation', 'op',
+    ], ['revision']),
+    'session.upsert': structuralFields([...SESSION_FIELDS], [], [...SESSION_TIMESTAMPS]),
+    'agent.upsert': structuralFields([...AGENT_FIELDS], [], [...SESSION_TIMESTAMPS]),
+    'usage.rollup': structuralFields([
+      ...AGENT_FIELDS, 'rollup_key', 'rollupKey', 'model_provider', 'modelProvider',
+      'cost_status', 'costStatus', 'pricing_source', 'pricingSource', 'pricing_version', 'pricingVersion',
+    ], ['revision'], [...SESSION_TIMESTAMPS]),
+    llm_call: structuralFields([
+      ...AGENT_FIELDS, 'call_id', 'callId', 'model_provider', 'modelProvider',
+      'cost_status', 'costStatus', 'transcript_id', 'transcriptId',
+    ], ['sequence'], [...SESSION_TIMESTAMPS, 'occurred_at']),
+    'transcript.upsert': structuralFields([
+      ...AGENT_FIELDS, 'transcript_id', 'transcriptId', 'coverage', 'source',
+    ], [], [...SESSION_TIMESTAMPS]),
+  }),
+});
+
+function policyError(message) {
+  return Object.assign(new Error(message), { code: 'observer_policy_invalid' });
+}
+
+function assertObject(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw policyError(`${label} inválido.`);
+}
+
+function assertKnownKeys(value, allowed, label) {
+  const unknown = Object.keys(value).find((key) => !allowed.has(key));
+  if (unknown) throw policyError(`${label} contém campo desconhecido: ${unknown}`);
+}
+
+function captureFor(policy, dataClass) {
+  return policy[`${dataClass}_capture`];
+}
+
+function globMatches(pattern, value) {
+  if (!pattern) return true;
+  const escaped = String(pattern).replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replaceAll('**', '\u0000').replaceAll('*', '[^/]*').replaceAll('\u0000', '.*');
+  return new RegExp(`^${escaped}$`, 'u').test(String(value || '').replaceAll('\\', '/'));
+}
+
+function ruleMatches(rule, context) {
+  return (!rule.project_id || rule.project_id === context.projectId)
+    && (!rule.data_class || rule.data_class === context.dataClass)
+    && (!rule.entity_type || rule.entity_type === context.entityType)
+    && globMatches(rule.path, context.path);
+}
+
+export function createObserverPolicy(input = {}) {
+  assertObject(input, 'policy');
+  assertKnownKeys(input, new Set([
+    'document_capture', 'transcript_capture', 'prompt_capture', 'response_capture', 'usage_capture',
+    'require_loopback_auth', 'encryption_required', 'rules', 'redaction', 'retention',
+  ]), 'policy');
+  for (const field of ['require_loopback_auth', 'encryption_required']) {
+    if (Object.hasOwn(input, field) && typeof input[field] !== 'boolean') throw policyError(`${field} deve ser boolean.`);
+  }
+  if (Object.hasOwn(input, 'rules') && !Array.isArray(input.rules)) throw policyError('rules deve ser array.');
+  if (Object.hasOwn(input, 'redaction')) {
+    assertObject(input.redaction, 'redaction');
+    assertKnownKeys(input.redaction, new Set(['rules']), 'redaction');
+    if (Object.hasOwn(input.redaction, 'rules') && !Array.isArray(input.redaction.rules)) throw policyError('redaction.rules deve ser array.');
+  }
+  if (Object.hasOwn(input, 'retention')) {
+    assertObject(input.retention, 'retention');
+    assertKnownKeys(input.retention, new Set(['document', 'transcript', 'prompt', 'response', 'usage', 'documents', 'calls', 'transcripts']), 'retention');
+    if (Object.values(input.retention).some((value) => !Number.isInteger(value) || value < 0)) throw policyError('retention deve usar inteiros não negativos.');
+  }
+  const policy = {
+    ...DEFAULTS,
+    ...input,
+    rules: Array.isArray(input.rules) ? input.rules.map((rule) => ({ ...rule })) : [],
+    redaction: input.redaction && typeof input.redaction === 'object' ? structuredClone(input.redaction) : {},
+    retention: input.retention && typeof input.retention === 'object' ? structuredClone(input.retention) : {},
+  };
+  for (const rule of policy.rules) {
+    assertObject(rule, 'rule');
+    assertKnownKeys(rule, new Set(['project_id', 'data_class', 'path', 'entity_type', 'capture']), 'rule');
+  }
+  for (const rule of policy.redaction.rules || []) {
+    assertObject(rule, 'redaction rule');
+    assertKnownKeys(rule, new Set(['pattern', 'replacement']), 'redaction rule');
+    if (String(rule.replacement || '').length > 160) throw policyError('replacement de redaction excede o limite.');
+  }
+  for (const rule of policy.redaction.rules || []) {
+    const pattern = String(rule?.pattern || '');
+    if (!pattern || pattern.length > 512 || /\\[1-9]/.test(pattern)
+      || /\((?:[^()\\]|\\.)*[+*](?:[^()\\]|\\.)*\)\s*(?:[+*]|\{\d*,?\d*\})/.test(pattern)) {
+      throw policyError('regra de redaction insegura ou inválida.');
+    }
+    try { new RegExp(pattern, 'giu'); }
+    catch { throw policyError('regra de redaction insegura ou inválida.'); }
+  }
+  for (const dataClass of Object.keys(CAPTURE)) {
+    const capture = captureFor(policy, dataClass);
+    if (!CAPTURE[dataClass].has(capture)) throw policyError(`capture inválido para ${dataClass}: ${capture}`);
+  }
+  for (const rule of policy.rules) {
+    if (!CAPTURE[rule.data_class]?.has(rule.capture)) {
+      throw policyError(`regra de capture inválida para ${rule.data_class || 'classe ausente'}`);
+    }
+  }
+  return policy;
+}
+
+export function saveObserverPolicy(db, projectId, policyInput, { updatedAt = new Date().toISOString() } = {}) {
+  const policy = createObserverPolicy(policyInput);
+  db.prepare(`INSERT INTO observer_retention_policies(project_id, policy_json, updated_at)
+    VALUES (?, ?, ?) ON CONFLICT(project_id) DO UPDATE SET policy_json = excluded.policy_json, updated_at = excluded.updated_at`)
+    .run(projectId, JSON.stringify(policy), new Date(updatedAt).toISOString());
+  return policy;
+}
+
+export function readObserverPolicy(db, projectId) {
+  const row = db.prepare('SELECT policy_json FROM observer_retention_policies WHERE project_id = ?').get(projectId);
+  return row ? createObserverPolicy(JSON.parse(row.policy_json)) : createObserverPolicy();
+}
+
+export function evaluateObserverPolicy(policyInput, context = {}) {
+  const policy = policyInput?.rules ? policyInput : createObserverPolicy(policyInput);
+  const dataClass = String(context.dataClass || 'document');
+  if (!CAPTURE[dataClass]) throw policyError(`classe de dado desconhecida: ${dataClass}`);
+  let capture = captureFor(policy, dataClass);
+  for (const rule of policy.rules) {
+    if (ruleMatches(rule, { ...context, dataClass })) capture = rule.capture;
+  }
+  return {
+    data_class: dataClass,
+    capture,
+    encryption_required: Boolean(policy.encryption_required),
+    retention_days: Number(policy.retention?.[dataClass] ?? 0) || 0,
+  };
+}
+
+function metadataOnly(payload, capture) {
+  return {
+    ...payload,
+    content: '',
+    coverage: payload.coverage ? 'summary_only' : payload.coverage,
+    capture,
+  };
+}
+
+function protectText(value, capture, redaction) {
+  if (capture === 'none') return '';
+  if (capture === 'redacted') return redactObserverValue(value, redaction);
+  return String(value ?? '');
+}
+
+function preserveStructuralFields(original, protectedValue, contract) {
+  for (const key of contract?.strings || []) {
+    if (!Object.hasOwn(original, key)) continue;
+    const value = original[key];
+    if (value !== null && typeof value !== 'string') throw policyError(`${key} estrutural deve ser string ou null.`);
+    protectedValue[key] = value;
+  }
+  for (const key of contract?.integers || []) {
+    if (!Object.hasOwn(original, key)) continue;
+    const value = original[key];
+    if (!Number.isInteger(value) || value < 0) throw policyError(`${key} estrutural deve ser inteiro não negativo.`);
+    protectedValue[key] = value;
+  }
+  for (const key of contract?.timestamps || []) {
+    if (!Object.hasOwn(original, key)) continue;
+    const value = original[key];
+    if (value !== null && (typeof value !== 'string' || Number.isNaN(Date.parse(value)))) {
+      throw policyError(`${key} estrutural deve ser date-time ou null.`);
+    }
+    protectedValue[key] = value;
+  }
+  return protectedValue;
+}
+
+function protectedContentHash(value) {
+  return createHash('sha256').update(String(value ?? '')).digest('hex');
+}
+
+function transcriptMessagesOnly(value) {
+  const source = String(value || '');
+  const sanitizeMessage = (item) => {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) return null;
+    const role = String(item.role || '');
+    if (!['user', 'assistant', 'system'].includes(role) || typeof item.content !== 'string') return null;
+    return { role, content: item.content };
+  };
+  const sanitizeMessages = (items) => items.map(sanitizeMessage).filter(Boolean);
+  try {
+    const parsed = JSON.parse(source);
+    if (Array.isArray(parsed)) return JSON.stringify(sanitizeMessages(parsed));
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed) && Array.isArray(parsed.messages)) {
+      return JSON.stringify({ messages: sanitizeMessages(parsed.messages) });
+    }
+    return '';
+  } catch {
+    const lines = source.split(/\r?\n/u).filter(Boolean);
+    const items = lines.map((line) => {
+      try { return JSON.parse(line); } catch { return null; }
+    });
+    if (!lines.length || items.some((item) => item === null)) return '';
+    return sanitizeMessages(items).map(JSON.stringify).join('\n');
+  }
+}
+
+export function protectObserverEvent(event, { policy: policyInput = {} } = {}) {
+  const policy = policyInput?.rules ? policyInput : createObserverPolicy(policyInput);
+  const payload = structuredClone(event?.payload || {});
+  const context = {
+    projectId: String(event?.project_id || ''),
+    path: String(payload.logical_path || ''),
+    entityType: String(payload.entity_type || ''),
+  };
+  let protectedPayload = preserveStructuralFields(
+    payload,
+    redactObserverValue(payload, policy.redaction),
+    OBSERVER_EVENT_STRUCTURAL_CONTRACT.payload[event?.kind],
+  );
+  if (event?.kind === 'document.delete') {
+    delete protectedPayload.content;
+    delete protectedPayload.content_hash;
+    delete protectedPayload.contentHash;
+  } else if (event?.kind?.startsWith('document.')) {
+    const decision = evaluateObserverPolicy(policy, { ...context, dataClass: 'document' });
+    if (decision.capture === 'none') return null;
+    if (decision.capture === 'metadata' || decision.capture === 'selected') protectedPayload = metadataOnly(protectedPayload, decision.capture);
+    else protectedPayload.capture = decision.capture;
+  } else if (event?.kind === 'transcript.upsert') {
+    const decision = evaluateObserverPolicy(policy, { ...context, dataClass: 'transcript' });
+    if (decision.capture === 'none') return null;
+    if (decision.capture === 'metadata') protectedPayload = metadataOnly(protectedPayload, decision.capture);
+    else if (decision.capture === 'messages') {
+      protectedPayload.content = transcriptMessagesOnly(protectedPayload.content);
+      protectedPayload.capture = decision.capture;
+    }
+    else protectedPayload.capture = decision.capture;
+  } else if (event?.kind === 'usage.rollup') {
+    const usageDecision = evaluateObserverPolicy(policy, { ...context, dataClass: 'usage' });
+    if (usageDecision.capture === 'none') return null;
+    protectedPayload.capture = usageDecision.capture;
+  } else if (event?.kind === 'llm_call') {
+    const usageDecision = evaluateObserverPolicy(policy, { ...context, dataClass: 'usage' });
+    if (usageDecision.capture !== 'calls') return null;
+    const promptDecision = evaluateObserverPolicy(policy, { ...context, dataClass: 'prompt' });
+    const responseDecision = evaluateObserverPolicy(policy, { ...context, dataClass: 'response' });
+    protectedPayload.prompt_text = protectText(payload.prompt_text ?? payload.prompt, promptDecision.capture, policy.redaction);
+    protectedPayload.response_text = protectText(payload.response_text ?? payload.response, responseDecision.capture, policy.redaction);
+    delete protectedPayload.prompt;
+    delete protectedPayload.response;
+    protectedPayload.capture = usageDecision.capture;
+  }
+  if (event?.kind === 'document.upsert' || event?.kind === 'transcript.upsert') {
+    protectedPayload.content_hash = protectedContentHash(protectedPayload.content);
+    delete protectedPayload.contentHash;
+  }
+  return { ...event, payload: protectedPayload };
+}

package/packages/observer/src/purge.mjs

@@ -0,0 +1,100 @@
+import { createHash } from 'node:crypto';
+
+const TABLES = {
+  documents: { table: 'documents', time: 'captured_at', id: 'document_id' },
+  calls: { table: 'llm_calls', time: 'occurred_at', id: 'call_pk' },
+  transcripts: { table: 'transcripts', time: 'occurred_at', id: 'transcript_pk' },
+};
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])]));
+  return value;
+}
+
+function digest(value) {
+  return `sha256:${createHash('sha256').update(JSON.stringify(canonical(value))).digest('hex')}`;
+}
+
+export function verifyObserverPurgeReceipt(receipt = {}) {
+  const candidate = { ...receipt };
+  const expected = String(candidate.receipt_hash || '');
+  delete candidate.receipt_hash;
+  delete candidate.idempotent;
+  return Boolean(expected) && digest(candidate) === expected;
+}
+
+export function purgeObserverData(db, {
+  projectId, before, classes = Object.keys(TABLES), now = new Date().toISOString(), dryRun = false,
+  operationId = '', beforeCommit, receiptSink,
+} = {}) {
+  const normalizedClasses = [...new Set(classes)].sort();
+  if (!normalizedClasses.length || normalizedClasses.some((item) => !TABLES[item])) {
+    throw Object.assign(new Error('classes de purge inválidas.'), { code: 'observer_purge_invalid' });
+  }
+  const cutoff = new Date(before).toISOString();
+  const requestHash = digest({ project_id: projectId, before: cutoff, classes: normalizedClasses });
+  db.exec('BEGIN IMMEDIATE');
+  let transactionOpen = true;
+  try {
+    const requestedReceiptId = operationId
+      ? digest({ request_hash: requestHash, operation_id: String(operationId) }).slice(7, 39)
+      : '';
+    const candidates = Object.fromEntries(normalizedClasses.map((dataClass) => {
+      const spec = TABLES[dataClass];
+      const rows = db.prepare(`SELECT ${spec.id} AS id FROM ${spec.table} WHERE project_id = ? AND ${spec.time} < ? ORDER BY ${spec.id}`).all(projectId, cutoff);
+      return [dataClass, rows.map((row) => row.id)];
+    }));
+    const counts = Object.fromEntries(normalizedClasses.map((dataClass) => [dataClass, candidates[dataClass].length]));
+    if (dryRun) {
+      db.exec('COMMIT');
+      transactionOpen = false;
+      return { dry_run: true, project_id: projectId, before: cutoff, classes: normalizedClasses, counts };
+    }
+    const noCandidates = Object.values(counts).every((count) => count === 0);
+    if (noCandidates) {
+      const previous = requestedReceiptId
+        ? db.prepare('SELECT receipt_json FROM observer_purge_receipts WHERE receipt_id = ?').get(requestedReceiptId)
+        : db.prepare('SELECT receipt_json FROM observer_purge_receipts WHERE project_id = ? AND request_hash = ? ORDER BY purged_at DESC LIMIT 1').get(projectId, requestHash);
+      if (previous) {
+        db.exec('COMMIT');
+        transactionOpen = false;
+        const replay = { ...JSON.parse(previous.receipt_json), idempotent: true };
+        receiptSink?.(replay);
+        return replay;
+      }
+    }
+    const operationExists = requestedReceiptId && db.prepare('SELECT receipt_id FROM observer_purge_receipts WHERE receipt_id = ?').get(requestedReceiptId);
+    const receiptId = operationExists
+      ? digest({ request_hash: requestHash, operation_id: String(operationId), candidates }).slice(7, 39)
+      : requestedReceiptId || digest({ request_hash: requestHash, candidates }).slice(7, 39);
+    const receipt = {
+      schema_version: 1, receipt_id: receiptId, project_id: projectId, before: cutoff,
+      classes: normalizedClasses, counts, purged_at: new Date(now).toISOString(),
+    };
+    receipt.receipt_hash = digest(receipt);
+    for (const dataClass of normalizedClasses) {
+      const spec = TABLES[dataClass];
+      if (dataClass === 'documents' && db.prepare("SELECT COUNT(*) AS count FROM sqlite_master WHERE type = 'table' AND name = 'evidence_chunks_fts'").get().count) {
+        db.prepare('DELETE FROM evidence_chunks_fts WHERE project_id = ? AND logical_path IN (SELECT logical_path FROM documents WHERE project_id = ? AND captured_at < ?)').run(projectId, projectId, cutoff);
+      }
+      db.prepare(`DELETE FROM ${spec.table} WHERE project_id = ? AND ${spec.time} < ?`).run(projectId, cutoff);
+      const kind = dataClass === 'documents' ? 'document.%' : dataClass === 'calls' ? 'llm_call' : 'transcript.upsert';
+      const comparator = dataClass === 'documents' ? 'LIKE' : '=';
+      db.prepare(`DELETE FROM ingest_events WHERE project_id = ? AND kind ${comparator} ? AND occurred_at < ?`).run(projectId, kind, cutoff);
+    }
+    beforeCommit?.(receipt);
+    db.prepare(`INSERT INTO observer_purge_receipts(receipt_id, project_id, request_hash, cutoff_at, classes_json, counts_json, purged_at, receipt_hash, receipt_json)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(
+      receipt.receipt_id, projectId, requestHash, cutoff, JSON.stringify(normalizedClasses), JSON.stringify(counts),
+      receipt.purged_at, receipt.receipt_hash, JSON.stringify(receipt),
+    );
+    db.exec('COMMIT');
+    transactionOpen = false;
+    receiptSink?.(receipt);
+    return { ...receipt, idempotent: false };
+  } catch (error) {
+    if (transactionOpen) db.exec('ROLLBACK');
+    throw error;
+  }
+}

package/packages/observer/src/redaction.mjs

@@ -0,0 +1,54 @@
+import { basename } from 'node:path';
+
+const SENSITIVE_KEY = /(?:authorization|password|passwd|secret|api[_-]?key|connection[_-]?string|cookie)|^(?:token|access[_-]?token|refresh[_-]?token|auth[_-]?token|bearer[_-]?token)$/i;
+const PATH_KEY = /^(?:transcript_path|agent_transcript_path|transcriptPath|agentTranscriptPath)$/i;
+const BUILT_INS = [
+  [/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, 'Bearer [REDACTED]'],
+  [/\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis):\/\/([^\s/:@]+):([^\s/@]+)@/gi, (_all, user) => `postgres://${user}:[REDACTED]@`],
+  [/\b(https?:\/\/)([^\s/:@]+):([^\s/@]+)@/gi, '$1$2:[REDACTED]@'],
+  [/\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi, '[EMAIL]'],
+  [/(?:\+?\d{1,3}[\s.-]?)?(?:\(?\d{2}\)?[\s.-]?)?\d{4,5}[\s.-]?\d{4}\b/g, '[PHONE]'],
+  [/\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g, '[ACCESS_KEY]'],
+];
+
+function sourceLabel(value) {
+  return basename(String(value || '').replaceAll('\\', '/'));
+}
+
+function customRules(config = {}) {
+  return (Array.isArray(config.rules) ? config.rules : []).flatMap((rule) => {
+    try {
+      if (!rule?.pattern) return [];
+      return [[new RegExp(String(rule.pattern), 'giu'), String(rule.replacement || '[REDACTED]')]];
+    } catch {
+      return [];
+    }
+  });
+}
+
+export function redactObserverText(value, config = {}) {
+  let result = String(value ?? '');
+  for (const [pattern, replacement] of [...BUILT_INS, ...customRules(config)]) {
+    result = result.replace(pattern, replacement);
+  }
+  return result;
+}
+
+export function redactObserverValue(value, config = {}, key = '') {
+  if (PATH_KEY.test(key)) return sourceLabel(value);
+  if (SENSITIVE_KEY.test(key)) return value ? '[REDACTED]' : value;
+  if (typeof value === 'string') return redactObserverText(value, config);
+  if (Array.isArray(value)) return value.map((item) => redactObserverValue(item, config));
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.entries(value).map(([childKey, item]) => [
+    childKey,
+    redactObserverValue(item, config, childKey),
+  ]));
+}
+
+export function sanitizeObserverAuditMetadata(metadata = {}, config = {}) {
+  const allowed = new Set(['route', 'method', 'remote_address', 'user_agent', 'reason', 'resource_id']);
+  return Object.fromEntries(Object.entries(metadata || {})
+    .filter(([key]) => allowed.has(key))
+    .map(([key, value]) => [key, redactObserverValue(value, config, key)]));
+}

package/packages/observer/src/retention.mjs

@@ -0,0 +1,39 @@
+import { purgeObserverData } from './purge.mjs';
+
+const CLASSES = ['documents', 'calls', 'transcripts'];
+
+export function observerRetentionCutoffs(policy = {}, now = new Date()) {
+  const timestamp = new Date(now);
+  if (Number.isNaN(timestamp.getTime())) throw Object.assign(new Error('retention clock inválido.'), { code: 'observer_retention_invalid' });
+  return Object.fromEntries(CLASSES.flatMap((dataClass) => {
+    const days = Number(policy[dataClass] ?? 0);
+    if (!Number.isInteger(days) || days < 0) throw Object.assign(new Error(`retention inválida para ${dataClass}.`), { code: 'observer_retention_invalid' });
+    return days === 0 ? [] : [[dataClass, new Date(timestamp.getTime() - days * 86_400_000).toISOString()]];
+  }));
+}
+
+export function runObserverRetention(db, {
+  projectId, policy = {}, clock = () => new Date(), dryRun = false, operationId = '', receiptSink,
+} = {}) {
+  const observedAt = clock();
+  const cutoffs = observerRetentionCutoffs(policy, observedAt);
+  const receipts = [];
+  for (const [dataClass, before] of Object.entries(cutoffs)) {
+    receipts.push(purgeObserverData(db, {
+      projectId,
+      before,
+      classes: [dataClass],
+      dryRun,
+      operationId: operationId ? `${operationId}:${dataClass}` : '',
+      now: observedAt,
+      receiptSink,
+    }));
+  }
+  return {
+    schema_version: 1,
+    project_id: projectId,
+    observed_at: new Date(observedAt).toISOString(),
+    cutoffs,
+    receipts,
+  };
+}

package/packages/observer/src/token-registry.mjs

@@ -0,0 +1,122 @@
+import { createHash, randomBytes } from 'node:crypto';
+
+const ROLES = new Set(['viewer', 'auditor', 'publisher', 'admin']);
+
+export function hashObserverToken(token) {
+  const value = String(token || '');
+  if (!value) throw Object.assign(new Error('token vazio.'), { code: 'observer_token_invalid' });
+  return `sha256:${createHash('sha256').update(value, 'utf8').digest('hex')}`;
+}
+
+function json(value) { return JSON.stringify(value); }
+function parse(value) { try { return JSON.parse(value || '[]'); } catch { return []; } }
+function validTime(value, field) {
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) throw Object.assign(new Error(`${field} inválido.`), { code: 'observer_token_invalid' });
+  return parsed.toISOString();
+}
+
+export function registerObserverToken(db, {
+  tokenId = randomBytes(12).toString('hex'), token, role, projectIds = [], scopes = [],
+  createdAt = new Date().toISOString(), expiresAt, rotatedFrom = null,
+} = {}) {
+  if (!ROLES.has(role)) throw Object.assign(new Error('role inválida.'), { code: 'observer_role_invalid' });
+  if (!Array.isArray(projectIds) || projectIds.length === 0) throw Object.assign(new Error('projectIds é obrigatório.'), { code: 'observer_projects_invalid' });
+  if (!Array.isArray(scopes) || scopes.length === 0) throw Object.assign(new Error('scopes é obrigatório.'), { code: 'observer_scopes_invalid' });
+  const row = {
+    token_id: String(tokenId), token_hash: hashObserverToken(token), role,
+    project_ids_json: json([...new Set(projectIds.map(String))].sort()),
+    scopes_json: json([...new Set(scopes.map(String))].sort()),
+    created_at: validTime(createdAt, 'createdAt'), expires_at: validTime(expiresAt, 'expiresAt'),
+    revoked_at: null, rotated_from: rotatedFrom ? String(rotatedFrom) : null,
+  };
+  db.prepare(`INSERT INTO observer_tokens(token_id, token_hash, role, project_ids_json, scopes_json, created_at, expires_at, revoked_at, rotated_from)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(...Object.values(row));
+  return { token_id: row.token_id, role, project_ids: parse(row.project_ids_json), scopes: parse(row.scopes_json), expires_at: row.expires_at, rotated_from: row.rotated_from };
+}
+
+export function resolveObserverPrincipal(db, token, { now = new Date().toISOString() } = {}) {
+  let tokenHash;
+  try { tokenHash = hashObserverToken(token); } catch { return { ok: false, code: 'observer_token_missing' }; }
+  const row = db.prepare('SELECT * FROM observer_tokens WHERE token_hash = ?').get(tokenHash);
+  if (!row) return { ok: false, code: 'observer_token_invalid' };
+  const timestamp = new Date(now).getTime();
+  if (row.revoked_at && new Date(row.revoked_at).getTime() <= timestamp) return { ok: false, code: 'observer_token_revoked', token_id: row.token_id };
+  if (new Date(row.expires_at).getTime() <= timestamp) return { ok: false, code: 'observer_token_expired', token_id: row.token_id };
+  return {
+    ok: true, token_id: row.token_id, role: row.role,
+    project_ids: parse(row.project_ids_json), scopes: parse(row.scopes_json), expires_at: row.expires_at,
+  };
+}
+
+export function ensureObserverBootstrapToken(db, {
+  token, tokenId = '', role, projectIds = [], scopes = [], expiresAt, createdAt = new Date().toISOString(), now = createdAt,
+} = {}) {
+  const tokenHash = hashObserverToken(token);
+  const existing = db.prepare('SELECT * FROM observer_tokens WHERE token_hash = ?').get(tokenHash);
+  if (existing) {
+    const expired = new Date(existing.expires_at).getTime() <= new Date(validTime(now, 'now')).getTime();
+    return {
+      created: false,
+      token_id: existing.token_id,
+      role: existing.role,
+      project_ids: parse(existing.project_ids_json),
+      scopes: parse(existing.scopes_json),
+      expires_at: existing.expires_at,
+      revoked: Boolean(existing.revoked_at),
+      expired,
+    };
+  }
+  if (!Array.isArray(projectIds) || projectIds.length === 0 || projectIds.includes('*')) {
+    throw Object.assign(new Error('bootstrap exige projectIds explícitos e não aceita wildcard.'), { code: 'observer_bootstrap_projects_invalid' });
+  }
+  const normalizedExpiry = validTime(expiresAt, 'expiresAt');
+  if (new Date(normalizedExpiry).getTime() <= new Date(validTime(now, 'now')).getTime()) {
+    throw Object.assign(new Error('bootstrap exige expiração futura.'), { code: 'observer_bootstrap_expired' });
+  }
+  const id = String(tokenId || `bootstrap-${tokenHash.slice(-24)}`);
+  if (db.prepare('SELECT token_id FROM observer_tokens WHERE token_id = ?').get(id)) {
+    throw Object.assign(new Error('tokenId de bootstrap já pertence a outra credencial.'), { code: 'observer_bootstrap_token_id_conflict' });
+  }
+  return {
+    created: true,
+    ...registerObserverToken(db, {
+      tokenId: id,
+      token,
+      role,
+      projectIds,
+      scopes,
+      createdAt,
+      expiresAt: normalizedExpiry,
+    }),
+    revoked: false,
+    expired: false,
+  };
+}
+
+export function revokeObserverToken(db, { tokenId, revokedAt = new Date().toISOString() } = {}) {
+  const result = db.prepare('UPDATE observer_tokens SET revoked_at = ? WHERE token_id = ? AND revoked_at IS NULL')
+    .run(validTime(revokedAt, 'revokedAt'), String(tokenId || ''));
+  return { token_id: String(tokenId || ''), revoked: Number(result.changes) > 0 };
+}
+
+export function rotateObserverToken(db, {
+  tokenId, newTokenId, newToken, rotatedAt = new Date().toISOString(), expiresAt,
+} = {}) {
+  const current = db.prepare('SELECT * FROM observer_tokens WHERE token_id = ?').get(String(tokenId || ''));
+  if (!current || current.revoked_at) throw Object.assign(new Error('token não pode ser rotacionado.'), { code: 'observer_token_rotation_invalid' });
+  db.exec('BEGIN IMMEDIATE');
+  try {
+    revokeObserverToken(db, { tokenId, revokedAt: rotatedAt });
+    const created = registerObserverToken(db, {
+      tokenId: newTokenId, token: newToken, role: current.role,
+      projectIds: parse(current.project_ids_json), scopes: parse(current.scopes_json),
+      createdAt: rotatedAt, expiresAt, rotatedFrom: tokenId,
+    });
+    db.exec('COMMIT');
+    return created;
+  } catch (error) {
+    db.exec('ROLLBACK');
+    throw error;
+  }
+}