@dreamforgestudiollc/emet 0.0.0-stage → 0.2.6

package/src/owner-approvals.js

@@ -0,0 +1,281 @@
+/**
+ * Owner page for pending sub-key requests.
+ *
+ * Mounted only when EMET_SUBKEYS=1. The passphrase is the one the OAuth
+ * consent page already checks (MongoOAuthProvider.checkPassphrase against
+ * EMET_OAUTH_PASSPHRASE), and a wrong guess shares that form's per-address
+ * lockout. A correct passphrase opens a session that lasts 15 minutes.
+ * Approve and Deny post that session's CSRF token and call
+ * decideSubkeyIfPending for the posted key_id. The history event records
+ * the real owner id and via owner_page. emet_client_approve is unchanged.
+ */
+
+import crypto from 'node:crypto';
+import express from 'express';
+import { timingSafeEqualStr } from './oauth-provider.js';
+import { decideSubkeyIfPending, loadSubkeyRecords } from './subkeys.js';
+
+const COOKIE_NAME = 'emet_owner';
+export const SESSION_MS = 15 * 60 * 1000;
+const SESSION_MAX = 200;
+const REASON_MAX = 500;
+const STORE_MESSAGE = 'The sub-key store is unavailable.';
+const NOT_PENDING = 'That sub-key is not awaiting approval. Nothing was changed.';
+
+function esc(s) {
+  return String(s ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+}
+
+function readCookie(req, name) {
+  const raw = req.headers.cookie;
+  if (!raw || typeof raw !== 'string') return null;
+  for (const part of raw.split(';')) {
+    const i = part.indexOf('=');
+    if (i < 0) continue;
+    if (part.slice(0, i).trim() !== name) continue;
+    return part.slice(i + 1).trim();
+  }
+  return null;
+}
+
+function ownerActor(personId) {
+  return {
+    transport: 'http',
+    authenticated: true,
+    personId,
+    ownerId: personId,
+    sourceTag: 'owner',
+    sourceBasis: 'login',
+    clientId: null,
+    grantId: null
+  };
+}
+
+function page(body) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>EMET owner approvals</title>
+<style>
+  body { font-family: system-ui, sans-serif; background: #12141a; color: #e8e6e0; margin: 0; padding: 24px; }
+  button { font: inherit; margin-right: 8px; }
+</style>
+</head>
+<body>
+${body}
+</body>
+</html>`;
+}
+
+function sendHtml(res, status, body) {
+  res.status(status);
+  res.setHeader('Content-Type', 'text/html; charset=utf-8');
+  res.setHeader('Cache-Control', 'no-store');
+  res.setHeader('Content-Security-Policy', "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; base-uri 'none'; frame-ancestors 'none'");
+  res.send(page(body));
+}
+
+function pendingRows(data) {
+  return Object.values((data && data.keys) || {})
+    .filter((k) => k && k.status === 'pending' && k.key_id && k.tag)
+    .sort((a, b) => String(a.requested_at || '').localeCompare(String(b.requested_at || '')) || String(a.key_id).localeCompare(String(b.key_id)));
+}
+
+function listHtml(rows, csrf, note) {
+  const noteHtml = note ? `<p>${esc(note)}</p>` : '';
+  if (!rows.length) return `${noteHtml}<h1>Pending sub-keys</h1><p>No pending sub-key requests.</p>`;
+  const body = rows.map((row) => {
+    const prefix = esc(String(row.key_id).slice(0, 8));
+    return `<tr><td>${esc(row.tag)}</td><td>${prefix}</td><td>${esc(row.requested_at || '')}</td><td>
+<form method="post" action="/owner/approvals/decide">
+<input type="hidden" name="csrf" value="${esc(csrf)}">
+<input type="hidden" name="key_id" value="${esc(row.key_id)}">
+<input type="text" name="reason" maxlength="${REASON_MAX}" placeholder="Reason (optional)">
+<button type="submit" name="decision" value="approve">Approve</button>
+<button type="submit" name="decision" value="deny">Deny</button>
+</form>
+</td></tr>`;
+  }).join('\n');
+  return `${noteHtml}<h1>Pending sub-keys</h1>
+<table>
+<thead><tr><th>Tag</th><th>Key</th><th>Requested</th><th></th></tr></thead>
+<tbody>
+${body}
+</tbody>
+</table>`;
+}
+
+function notPending(res) {
+  res.locals.reason = 'not_pending';
+  sendHtml(res, 400, `<p>${NOT_PENDING}</p>`);
+}
+
+/**
+ * @param {import('express').Express} app
+ * @param {{ checkPassphrase: (input: string) => boolean, throttle: { check: Function, recordFailure: Function, recordSuccess: Function }, deps: object | Function, ownerId: string | Function, now?: () => number }} options
+ */
+export function mountOwnerApprovals(app, options = {}) {
+  const checkPassphrase = options.checkPassphrase;
+  const throttle = options.throttle;
+  const now = options.now || Date.now;
+  const sessions = new Map();
+  const parseBody = express.urlencoded({ extended: false });
+  const depsOf = () => (typeof options.deps === 'function' ? options.deps() : options.deps);
+
+  async function resolveOwner() {
+    try { const id = await (typeof options.ownerId === 'function' ? options.ownerId() : options.ownerId); return (typeof id === 'string' && id.trim()) || null; }
+    catch { return null; }
+  }
+
+  function sweep() {
+    const t = now();
+    for (const [id, row] of sessions) if (!row || row.expires <= t) sessions.delete(id);
+    while (sessions.size > SESSION_MAX) sessions.delete(sessions.keys().next().value);
+  }
+
+  function sessionOf(req) {
+    sweep();
+    const raw = readCookie(req, COOKIE_NAME);
+    if (!raw || !/^[0-9a-f]{64}$/.test(raw)) return null;
+    return sessions.get(raw) || null;
+  }
+
+  async function renderList(req, res, note) {
+    const session = sessionOf(req);
+    if (!session) {
+      sendHtml(res, 200, `<h1>Owner approvals</h1>
+<p>Enter the owner passphrase.</p>
+<form method="post" action="/owner/approvals/login">
+<label>Passphrase <input type="password" name="passphrase" autocomplete="current-password"></label>
+<button type="submit">Continue</button>
+</form>`);
+      return;
+    }
+    let rows = [];
+    try {
+      rows = pendingRows(await loadSubkeyRecords(depsOf()));
+    } catch {
+      res.locals.reason = 'subkey_store';
+      sendHtml(res, 503, `<p>${STORE_MESSAGE}</p>`);
+      return;
+    }
+    sendHtml(res, 200, listHtml(rows, session.csrf, note));
+  }
+
+  app.get('/owner/approvals', (req, res) => {
+    renderList(req, res).catch((e) => {
+      console.error('[emet] owner approvals', e && e.message ? e.message : e);
+      if (!res.headersSent) {
+        res.locals.reason = 'owner_approvals_error';
+        sendHtml(res, 500, '<p>Something went wrong.</p>');
+      }
+    });
+  });
+
+  app.post('/owner/approvals/login', parseBody, (req, res) => {
+    const limit = throttle.check(req.ip);
+    if (!limit.allowed) {
+      res.locals.reason = 'throttled';
+      res.setHeader('Retry-After', String(limit.retryAfterS));
+      sendHtml(res, 429, '<p>Too many attempts. Try again later.</p>');
+      return;
+    }
+    const passphrase = (req.body && req.body.passphrase) || '';
+    let ok = false;
+    try { ok = checkPassphrase(passphrase) === true; }
+    catch (e) {
+      console.error('[emet] owner passphrase check', e && e.message ? e.message : e);
+      res.locals.reason = 'passphrase_check_error';
+      sendHtml(res, 500, '<p>Something went wrong.</p>');
+      return;
+    }
+    if (!ok) {
+      throttle.recordFailure(req.ip);
+      res.locals.reason = 'bad_passphrase';
+      sendHtml(res, 401, '<p>Incorrect passphrase.</p>');
+      return;
+    }
+    throttle.recordSuccess(req.ip);
+    sweep();
+    const id = crypto.randomBytes(32).toString('hex');
+    const csrf = crypto.randomBytes(32).toString('hex');
+    sessions.set(id, { csrf, expires: now() + SESSION_MS });
+    res.cookie(COOKIE_NAME, id, {
+      httpOnly: true,
+      sameSite: 'strict',
+      path: '/owner',
+      maxAge: SESSION_MS,
+      secure: req.secure === true
+    });
+    res.locals.reason = 'owner_session';
+    res.redirect(303, '/owner/approvals');
+  });
+
+  app.post('/owner/approvals/decide', parseBody, (req, res) => {
+    const session = sessionOf(req);
+    if (!session) {
+      res.locals.reason = 'no_owner_session';
+      sendHtml(res, 401, '<p>Sign in again.</p>');
+      return;
+    }
+    const posted = (req.body && req.body.csrf) || '';
+    if (!timingSafeEqualStr(posted, session.csrf)) {
+      res.locals.reason = 'bad_csrf';
+      sendHtml(res, 403, '<p>The form expired. Reload the page and try again.</p>');
+      return;
+    }
+    const decision = req.body && req.body.decision;
+    const keyId = typeof (req.body && req.body.key_id) === 'string' ? req.body.key_id.trim() : '';
+    const reason = typeof (req.body && req.body.reason) === 'string' ? req.body.reason.trim() : '';
+    if (decision !== 'approve' && decision !== 'deny') {
+      res.locals.reason = 'bad_decision';
+      sendHtml(res, 400, '<p>Decision must be approve or deny. Nothing was changed.</p>');
+      return;
+    }
+    if (reason.length > REASON_MAX) {
+      res.locals.reason = 'reason_too_long';
+      sendHtml(res, 400, '<p>The reason is too long. Nothing was changed.</p>');
+      return;
+    }
+    finishDecide(req, res, keyId, decision, reason).catch((e) => {
+      console.error('[emet] owner decide', e && e.message ? e.message : e);
+      if (!res.headersSent) {
+        res.locals.reason = 'owner_decide_error';
+        sendHtml(res, 500, '<p>Something went wrong. Nothing was changed.</p>');
+      }
+    });
+  });
+
+  async function finishDecide(req, res, keyId, decision, reason) {
+    const personId = await resolveOwner();
+    if (!personId) {
+      res.locals.reason = 'owner_unavailable';
+      sendHtml(res, 400, '<p>The owner id is unavailable. Nothing was changed.</p>');
+      return;
+    }
+    let result = null;
+    try {
+      result = await decideSubkeyIfPending(depsOf(), ownerActor(personId), personId, {
+        key_id: keyId, decision, reason, via: 'owner_page'
+      }, new Date(now()));
+    } catch (e) {
+      if (e && e.attributionRefusal && !/sub-key store/.test(String(e.message))) {
+        res.locals.reason = 'decide_refused';
+        sendHtml(res, 400, `<p>${esc(e.message)}</p>`);
+        return;
+      }
+      res.locals.reason = 'subkey_store';
+      sendHtml(res, 503, `<p>${STORE_MESSAGE}</p>`);
+      return;
+    }
+    if (!result) {
+      notPending(res);
+      return;
+    }
+    res.locals.reason = decision === 'approve' ? 'subkey_approved' : 'subkey_denied';
+    const verb = decision === 'approve' ? 'Approved' : 'Denied';
+    await renderList(req, res, `${verb} ${result.tag}.`);
+  }
+}

package/src/persons.js

@@ -0,0 +1,136 @@
+/**
+ * EMET - persons
+ *
+ * A person is who logged in. A host-tag is which door they used.
+ * Tokens used to carry subject: "owner" for every connection. That cannot
+ * scale to a second human. This module is the first cut: one owner person
+ * in a `persons` collection, and a subject resolver the token issuer calls.
+ *
+ * Invitation, membership, and scopes on dispatch are later cuts.
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+const COLLECTION = 'persons';
+/** Stdio has no login. Every local write is stamped with this one subject. */
+export const LOCAL_SUBJECT = 'local';
+export const actorStore = new AsyncLocalStorage();
+export function currentActor() {
+  const s = actorStore.getStore();
+  if (typeof s === 'string' && s.trim()) return { personId: s.trim(), scopes: [] };
+  if (s && typeof s === 'object') {
+    return {
+      personId: s.personId || null,
+      clientId: s.clientId || null,
+      scopes: Array.isArray(s.scopes) ? s.scopes : [],
+      transport: s.transport || null,
+      authenticated: s.authenticated === true
+    };
+  }
+  return { personId: null, clientId: null, scopes: [], transport: null, authenticated: false };
+}
+export function currentPersonId() {
+  return currentActor().personId;
+}
+export function currentClientId() {
+  const s = actorStore.getStore();
+  if (!s || typeof s === 'string') return 'stdio';
+  return s.clientId === undefined ? 'stdio' : s.clientId;
+}
+
+/** Server stamp only. A caller value is never read. Stdio is one fixed local subject. */
+export function writerStamp() {
+  const s = actorStore.getStore();
+  if (!s || typeof s === 'string') {
+    const id = typeof s === 'string' && s.trim() ? s.trim() : LOCAL_SUBJECT;
+    return { person_id: id, client_id: 'stdio' };
+  }
+  if (s.transport === 'http') {
+    return { person_id: s.personId || null, client_id: s.clientId === undefined ? null : s.clientId };
+  }
+  return { person_id: s.personId || LOCAL_SUBJECT, client_id: s.clientId === undefined ? 'stdio' : s.clientId };
+}
+
+/**
+ * HTTP binds a source tag at approval. Returns that tag (or null when none
+ * was bound). Returns undefined on stdio, where the caller tag is checked
+ * against EMET_SOURCE_TAGS instead.
+ */
+export function boundSourceTag() {
+  const s = actorStore.getStore();
+  if (!s || typeof s !== 'object' || s.transport !== 'http') return undefined;
+  const tag = typeof s.sourceTag === 'string' ? s.sourceTag.trim() : '';
+  return tag || null;
+}
+
+/** The raw per-request actor (HTTP object), or null. Read only. */
+export function rawActor() {
+  const s = actorStore.getStore();
+  return s && typeof s === 'object' ? s : null;
+}
+
+/** Per-request attribution set by attribution.preflight (HTTP only). */
+export function declaredAttribution() {
+  const s = actorStore.getStore();
+  if (!s || typeof s !== 'object' || s.transport !== 'http') return null;
+  const login = typeof s.sourceTag === 'string' && s.sourceTag.trim() ? s.sourceTag.trim() : null;
+  return {
+    declared: s.declaredTag || null, basis: s.sourceBasis || null, login,
+    effective: s.effectiveTag || null, clientId: s.clientId || null,
+    approval: s.approvalState || null,
+    rememberedTags: Array.isArray(s.rememberedTags) ? s.rememberedTags : [],
+    ...(s.subkeyId ? { keyId: s.subkeyId } : {})
+  };
+}
+
+export function displayNameFromUserDoc(text) {
+  const heading = String(text || '').match(/^#\s+User Profile\s+[\u2014\u2013-]\s+(.+)$/im);
+  if (heading) return heading[1].trim();
+  return null;
+}
+
+export function slugPersonId(name) {
+  const s = String(name || '')
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40);
+  return s || 'owner';
+}
+
+export async function ensureOwnerPerson(db, { display_name } = {}) {
+  const col = db.collection(COLLECTION);
+  const existing = await col.findOne({ role: 'owner' });
+  if (existing) return existing;
+  const person_id = slugPersonId(display_name);
+  const row = {
+    person_id,
+    display_name: String(display_name || person_id).trim() || person_id,
+    role: 'owner',
+    created_at: new Date()
+  };
+  await col.insertOne(row);
+  return row;
+}
+
+/** Subject stamped on new tokens. Falls back to "owner" if the table is empty. */
+export async function resolveTokenSubject(db) {
+  if (!db) return 'owner';
+  const owner = await db.collection(COLLECTION).findOne({ role: 'owner' });
+  return owner?.person_id || 'owner';
+}
+
+/** Person on this request, from the bearer token. Host-tags stay separate. */
+export function personFromAuth(extra) {
+  const info = extra && extra.authInfo;
+  const s = (info && info.extra && info.extra.subject) || (info && info.subject);
+  if (typeof s === 'string' && s.trim()) return s.trim();
+  return null;
+}
+
+export async function getPerson(db, person_id) {
+  if (!db || !person_id) return null;
+  return db.collection(COLLECTION).findOne({ person_id });
+}

package/src/provenance.js

@@ -0,0 +1,257 @@
+/**
+ * EMET - Enduring Memory & Epistemic Tiers
+ * Copyright (c) 2026 Dreamforge Studio LLC
+ *
+ * Licensed under the MIT License - see LICENSE
+ *
+ * Provenance: how a tier-1 entry reaches the tier-2 record that justifies it.
+ *
+ * "Epistemic Tiers" names the pairing of a claim with its evidence. A layer
+ * entry that asserts something, with no reachable source, is a claim the system
+ * merely happens to hold - so the link between the tiers is not a convenience,
+ * it is the half of the name that makes the other half worth anything.
+ *
+ * TWO MECHANISMS, DELIBERATELY, AND THEY ARE NOT REDUNDANT COPIES.
+ *
+ *   POINTER   - the entry records the transcript span it came from: a session id
+ *               and a range of exchange indices. Exact. Conditional: absent on
+ *               everything written before pointers existed, and legitimately
+ *               absent on entries consolidated from other entries rather than
+ *               from a conversation.
+ *
+ *   TIMESTAMP - every entry has one, unconditionally, so a window around it can
+ *               always be searched. Universal. Approximate: it depends on
+ *               choosing the window, it degrades when sessions overlap or run
+ *               long, and when it is wrong it returns the NEIGHBOURING span
+ *               rather than failing. A silent wrong answer is the worst possible
+ *               failure shape for a provenance mechanism.
+ *
+ * PRECEDENCE IS WHAT KEEPS THEM FROM CONFLICTING. The pointer wins whenever it
+ * is present; the timestamp is the fallback when it is null. They are never
+ * averaged, never combined, and the timestamp is never preferred merely because
+ * it returned something. Without a stated precedence two links are ambiguity;
+ * with one they are a primary and a fallback.
+ *
+ * AND KEEPING BOTH BUYS SOMETHING NEITHER GIVES ALONE: they can check each
+ * other. If an entry's pointer names a session whose span sits nowhere near that
+ * entry's own timestamp, something is wrong - a mis-written pointer, a field
+ * copied from another entry, an entry attributed to the wrong session. Two
+ * independently derived answers that can disagree is redundancy in the
+ * engineering sense. A single link that can only be trusted is not.
+ *
+ * WHY THESE ARE TOP-LEVEL FIELDS. They sit beside the entry, not inside the
+ * metadata JSON string, for the same reason `superseded_by`, `valid_until` and
+ * `is_live` were promoted: the store cannot filter into a JSON string, so a
+ * pointer buried there could be written but never queried - and the reverse
+ * question, "what did we take from this session?", is exactly a query.
+ *
+ * NO BACKFILL. An entry written before pointers existed cannot be given a true
+ * one; the only way to invent it is to infer the span from the timestamp, which
+ * is precisely the weaker method the pointer exists to replace. Historical
+ * entries keep a null pointer and resolve by timestamp, and that remains correct
+ * for them - superseded, not wrong. Old records are not rewritten to look like
+ * new ones; the method that applies to them is written down instead.
+ */
+
+import { ValidationError } from './validation.js';
+
+/** Default half-width of the timestamp fallback window, in seconds. */
+export const FALLBACK_WINDOW_SECONDS = 3600;
+
+/** How far a pointer's session may sit from an entry's timestamp before the
+ *  cross-check calls it suspicious. Generous: long sessions are normal, and a
+ *  false alarm here trains its reader to ignore the check. */
+const CROSS_CHECK_TOLERANCE_SECONDS = 24 * 3600;
+
+function isPositiveInt(v) {
+  return Number.isInteger(v) && v > 0;
+}
+
+/**
+ * Validate a caller-supplied provenance object.
+ *
+ * Accepts either shape, and only one of them:
+ *   { session_id, exchange_start, exchange_end }  - derived from a conversation
+ *   { entries: [id, ...] }                        - consolidated from other entries
+ *
+ * The second shape exists because a required field with no honest value invites
+ * fabrication. An entry consolidated from three others has no transcript span,
+ * and must be able to say so explicitly rather than carry a nearest-timestamp
+ * guess dressed as a citation.
+ */
+export function validateProvenance(input) {
+  if (input === null || input === undefined) return null;
+  if (typeof input !== 'object' || Array.isArray(input)) {
+    throw new ValidationError('derived_from', 'must be an object');
+  }
+
+  const hasSpan = input.session_id !== undefined;
+  const hasEntries = input.entries !== undefined;
+
+  if (hasSpan && hasEntries) {
+    throw new ValidationError(
+      'derived_from',
+      'give a transcript span or a list of source entries, not both - an entry has one origin'
+    );
+  }
+  if (!hasSpan && !hasEntries) {
+    throw new ValidationError(
+      'derived_from',
+      'needs either session_id (with optional exchange_start/exchange_end) or entries'
+    );
+  }
+
+  if (hasEntries) {
+    if (!Array.isArray(input.entries) || input.entries.length === 0) {
+      throw new ValidationError('derived_from.entries', 'must be a non-empty array of entry ids');
+    }
+    if (!input.entries.every(isPositiveInt)) {
+      throw new ValidationError('derived_from.entries', 'entry ids must be positive integers');
+    }
+    return { entries: [...input.entries] };
+  }
+
+  if (typeof input.session_id !== 'string' || input.session_id.length === 0) {
+    throw new ValidationError('derived_from.session_id', 'must be a non-empty string');
+  }
+  const start = input.exchange_start;
+  const end = input.exchange_end;
+  if (start !== undefined && !isPositiveInt(start)) {
+    throw new ValidationError('derived_from.exchange_start', 'must be a positive integer');
+  }
+  if (end !== undefined && !isPositiveInt(end)) {
+    throw new ValidationError('derived_from.exchange_end', 'must be a positive integer');
+  }
+  if (isPositiveInt(start) && isPositiveInt(end) && end < start) {
+    throw new ValidationError('derived_from.exchange_end', 'must not be before exchange_start');
+  }
+
+  return {
+    session_id: input.session_id,
+    exchange_start: isPositiveInt(start) ? start : null,
+    exchange_end: isPositiveInt(end) ? end : (isPositiveInt(start) ? start : null)
+  };
+}
+
+/**
+ * The top-level columns to store for a validated provenance object.
+ * Always returns every key, so an entry without provenance stores explicit nulls
+ * rather than absent fields - absence and "no pointer" must not be the same
+ * shape as "this field was never part of the schema".
+ */
+export function provenanceColumns(provenance) {
+  if (!provenance) {
+    return { source_session_id: null, source_exchange_start: null, source_exchange_end: null, derived_from_ids: null };
+  }
+  if (provenance.entries) {
+    return { source_session_id: null, source_exchange_start: null, source_exchange_end: null, derived_from_ids: provenance.entries };
+  }
+  return {
+    source_session_id: provenance.session_id,
+    source_exchange_start: provenance.exchange_start,
+    source_exchange_end: provenance.exchange_end,
+    derived_from_ids: null
+  };
+}
+
+/**
+ * Resolve how to reach the evidence for an entry.
+ *
+ * This is the precedence rule, in one place, so no caller has to decide it.
+ */
+export function resolveProvenance(entry, windowSeconds = FALLBACK_WINDOW_SECONDS) {
+  if (!entry) throw new ValidationError('entry', 'is required');
+
+  if (entry.source_session_id) {
+    return {
+      method: 'pointer',
+      exact: true,
+      session_id: entry.source_session_id,
+      exchange_start: entry.source_exchange_start ?? null,
+      exchange_end: entry.source_exchange_end ?? null,
+      how: 'Read this session\'s transcript and take the named exchange range.'
+    };
+  }
+
+  if (Array.isArray(entry.derived_from_ids) && entry.derived_from_ids.length > 0) {
+    return {
+      method: 'entries',
+      exact: true,
+      entries: entry.derived_from_ids,
+      how: 'This entry was consolidated from other entries. Read those; they carry their own provenance.'
+    };
+  }
+
+  const timestamp = typeof entry.timestamp === 'number' ? entry.timestamp : null;
+  if (timestamp === null) {
+    return {
+      method: 'none',
+      exact: false,
+      how: 'No pointer and no timestamp. The source of this entry cannot be reached; treat the claim as unsourced.'
+    };
+  }
+
+  return {
+    method: 'timestamp',
+    exact: false,
+    timestamp_start: timestamp - windowSeconds,
+    timestamp_end: timestamp + windowSeconds,
+    how:
+      'No pointer on this entry, so fall back to searching transcripts over a window around its ' +
+      'timestamp. This is approximate: it can return a neighbouring span rather than the real ' +
+      'one, and an empty result is not proof that nothing was recorded. Do not cite a window ' +
+      'result with the confidence of a pointer.'
+  };
+}
+
+/**
+ * Cross-check a pointer against the entry's own timestamp.
+ *
+ * The reason to keep both mechanisms rather than replacing one with the other:
+ * two independently derived answers can disagree, and a disagreement is
+ * information. Returns a finding; it never throws and never blocks a write,
+ * because a suspicious pointer is a thing to look at, not a thing to refuse.
+ */
+export function crossCheckProvenance(entry, transcript, toleranceSeconds = CROSS_CHECK_TOLERANCE_SECONDS) {
+  if (!entry || !entry.source_session_id) return { checked: false, reason: 'no pointer to check' };
+  if (!transcript) {
+    return {
+      checked: true,
+      agrees: false,
+      finding: `Entry points at session "${entry.source_session_id}", which does not exist in the transcript store.`
+    };
+  }
+
+  const toSeconds = (v) => {
+    if (v instanceof Date) return v.getTime() / 1000;
+    if (typeof v === 'number') return v > 1e11 ? v / 1000 : v;
+    return null;
+  };
+  const start = toSeconds(transcript.session_start);
+  const end = toSeconds(transcript.session_end) ?? start;
+  const at = typeof entry.timestamp === 'number' ? entry.timestamp : null;
+
+  if (at === null || start === null) return { checked: false, reason: 'not enough timing information to compare' };
+
+  const distance = at < start ? start - at : (at > end ? at - end : 0);
+  if (distance <= toleranceSeconds) return { checked: true, agrees: true, distance_seconds: Math.round(distance) };
+
+  return {
+    checked: true,
+    agrees: false,
+    distance_seconds: Math.round(distance),
+    finding:
+      `Entry timestamp sits ${Math.round(distance / 3600)}h outside the session its pointer names. ` +
+      `The pointer and the timestamp disagree about where this entry came from - likely a field ` +
+      `copied from another entry, or an entry attributed to the wrong session. Report it; do not ` +
+      `silently prefer either one.`
+  };
+}
+
+export default {
+  validateProvenance,
+  provenanceColumns,
+  resolveProvenance,
+  crossCheckProvenance,
+  FALLBACK_WINDOW_SECONDS
+};