@medusasec/sensitive-spans 0.1.0

package/README.md

@@ -0,0 +1,67 @@
+# @medusasec/sensitive-spans
+
+The browser-side primitives from the [Medusa](https://github.com/joshmaster2165/medusa-agent)
+extension, as one dependency-free ESM package. Runs in browsers, Node 20+, Deno
+and Workers. Nothing phones home.
+
+```
+npm i @medusasec/sensitive-spans
+```
+
+## What's inside
+
+| Module | What it gives you |
+|---|---|
+| `detect(text, {policy, settings, extraSpans})` | Sensitive spans (secrets, PII, financial, health, insurance, code, prompt injection) from the deterministic layer — vendor key prefixes, checksummed identifiers (Luhn, IBAN mod-97, ABA), 30+ injection families — then the **measured precision guards** and a policy decision: `{spans, action, requireJustification, disallowOverride, disallowApproval}`. |
+| `classifyLocal`, `applyAllowlist`, `mergeSpans` | The pieces behind `detect`, if you want to run your own model and merge. |
+| `decide`, `filterSpans`, `hasSecretSignal`, `isProsePii`, … | The guard library: each guard is traceable to a quantified false-positive reduction on a 12k-row corpus of real prose. |
+| `detectSpansTier0` | The zero-shot Tier-0 engine (entropy scoring, base64 deobfuscation, dummy-value rejection). |
+| `attributeActor`, `scoreSignals` | Who is driving the browser: `human \| agent \| automation \| unknown` from debugger attachment + an input fingerprint (pointer pressure, trail, unkeyed text insertion, injected-script frames). |
+| `decideAgentAction` | Actor-aware policy: `{default, rules:[{agent, sites, actions, action}]}` → `allow \| log \| approve \| deny`. Humans are never gated. |
+| `assignPlaceholders`, `pseudonymizeText`, `rehydrateText` | Consistent, reversible placeholders (`[PII-1]`) for detected values. |
+| `makeReceipt`, `verifyReceipts`, `makeSigner`, `makeVerifier` | Hash-chained, ECDSA P-256 signed receipts with WebCrypto; verification works from any runtime with the public JWK. |
+| `actorHeaderValue`, `headerRule` | The `Sec-Agent-Actor` attribution header and its per-tab declarativeNetRequest rule. |
+| `mergeTools`, `toolsFingerprint` | WebMCP tool inventory helpers. |
+
+## Quick start
+
+```js
+import { detect, decideAgentAction, attributeActor } from "@medusasec/sensitive-spans";
+
+const r = detect("rotate AKIAIOSFODNN7EXAMPLE before Friday", {
+  policy: { category_actions: { secret: "block" }, disallow_override: ["secret"] },
+});
+// r.action === "block", r.spans[0].category === "secret"
+
+const actor = attributeActor({ attached: true, candidates: [{ id: "fcoe…", known: "claude-in-chrome", label: "Claude in Chrome", kind: "agent", enabled: true, canDrive: true }] });
+decideAgentAction({ default: "log", rules: [{ agent: "claude-in-chrome", sites: ["*.internal.example"], action: "approve" }] }, actor, "hr.internal.example");
+// → { action: "approve", rule: 0, source: "rule" }
+```
+
+## The model
+
+The extension also runs a 28.8 MB int8 BERT token classifier on-device. It is
+not bundled here; pass its spans as `extraSpans` and `detect` merges them
+before the guards run. A loader package is planned.
+
+## Publishing
+
+The scope is `@medusasec`; create the `medusasec` organization on npmjs.com (or
+rename the package to your user scope) before the first publish. Then:
+
+```
+npm login
+cd packages/sensitive-spans
+npm publish
+```
+
+`prepublishOnly` rebuilds `dist/` from the extension source and runs the tests,
+and `publishConfig.access` is `public`, so no flags are needed.
+
+## Build
+
+`dist/` is assembled from `../../medusa-browser-extension/src` by `build.mjs`
+so the package can never drift from the extension. `npm test` builds and runs
+the tests.
+
+Apache-2.0.

package/dist/actor.js

@@ -0,0 +1,106 @@
+// Actor attribution — who is driving this tab: a person, or an agent?
+//
+// Two independent evidence sources, combined here (pure; unit-tested):
+//
+//   1. Debugger attachment. chrome.debugger.getTargets() reports `attached`
+//      for a tab whenever ANY extension or external DevTools-protocol client
+//      holds it — verified in the week-1 spikes against a mimic of Claude in
+//      Chrome and against Playwright over --remote-debugging-port. Combined
+//      with the inventory of installed driver-capable extensions this names
+//      the agent, or flags an external CDP client when none is installed.
+//
+//   2. Page-level input fingerprint (see driver-signals.js). Agents that never
+//      attach a debugger (a browser's own native agent, an isolated-world
+//      automation script) still produce inputs a person cannot: pointer
+//      presses with zero pressure and no movement trail, text that appears
+//      without keystrokes, DOM calls from anonymous injected scripts.
+//
+// Output shape is stable — it is stored on every telemetry event as
+// metadata.actor and rendered by the dashboard.
+
+export const ACTOR_HUMAN = "human";
+export const ACTOR_AGENT = "agent";
+export const ACTOR_AUTOMATION = "automation";
+export const ACTOR_UNKNOWN = "unknown";
+
+/** Score a driver-signals snapshot. Returns the evidence list that fired. */
+export function scoreSignals(sig) {
+  const evidence = [];
+  if (!sig || typeof sig !== "object") return { score: 0, evidence };
+  const downs = Number(sig.pointerdowns) || 0;
+  const zero = Number(sig.zeroPressureDowns) || 0;
+  const noTrail = Number(sig.downsWithoutTrail) || 0;
+  const inputs = Number(sig.inputs) || 0;
+  const unkeyed = Number(sig.inputsWithoutKeydown) || 0;
+  const foreign = Number(sig.foreignFrames) || 0;
+  if (downs > 0 && zero / downs >= 0.8) evidence.push("pointer_pressure_zero");
+  if (downs > 0 && noTrail / downs >= 0.8) evidence.push("no_pointer_trail");
+  if (inputs > 0 && unkeyed >= Math.max(1, Math.ceil(inputs * 0.5))) evidence.push("text_inserted_without_keys");
+  if (foreign > 0) evidence.push("injected_script_frames");
+  return { score: evidence.length, evidence };
+}
+
+/**
+ * Attribute the actor for one action.
+ * @param {object} p
+ * @param {boolean} p.attached        debugger attached to the tab right now
+ * @param {Array}   p.candidates      enabled driver-capable extensions (assessExtension shape)
+ * @param {object}  p.signals         driver-signals snapshot (may be null)
+ */
+export function attributeActor({ attached, candidates, signals } = {}) {
+  const cands = Array.isArray(candidates) ? candidates : [];
+  const sig = scoreSignals(signals);
+
+  if (attached) {
+    if (cands.length === 1) {
+      const c = cands[0];
+      return {
+        kind: c.kind === "automation" ? ACTOR_AUTOMATION : ACTOR_AGENT,
+        agent: { id: c.id, key: c.known || null, label: c.label },
+        confidence: "high",
+        evidence: ["debugger_attached", "single_driver_capable_extension", ...sig.evidence],
+      };
+    }
+    if (cands.length > 1) {
+      return {
+        kind: ACTOR_AGENT,
+        agent: null,
+        candidates: cands.map((c) => ({ id: c.id, key: c.known || null, label: c.label })),
+        confidence: "medium",
+        evidence: ["debugger_attached", "multiple_driver_capable_extensions", ...sig.evidence],
+      };
+    }
+    return {
+      kind: ACTOR_AUTOMATION,
+      agent: null,
+      confidence: "high",
+      evidence: ["debugger_attached", "no_driver_capable_extension", ...sig.evidence],
+    };
+  }
+
+  if (sig.score >= 2) {
+    return {
+      kind: ACTOR_AGENT,
+      agent: null,
+      confidence: sig.score >= 3 ? "medium" : "low",
+      evidence: sig.evidence,
+    };
+  }
+  const observed = (Number(signals?.pointerdowns) || 0) + (Number(signals?.keydowns) || 0);
+  if (observed > 0) {
+    return { kind: ACTOR_HUMAN, confidence: sig.score === 0 ? "high" : "medium", evidence: ["human_input_pattern", ...sig.evidence] };
+  }
+  // A submission with no observed input at all in the window: programmatic
+  // send or a driver we cannot see. Never call that a person.
+  return { kind: ACTOR_UNKNOWN, confidence: "low", evidence: ["no_input_observed", ...sig.evidence] };
+}
+
+/** Short human label for UI/receipts. */
+export function actorLabel(actor) {
+  if (!actor) return "Unknown";
+  if (actor.kind === ACTOR_HUMAN) return "Human";
+  if (actor.agent && actor.agent.label) return actor.agent.label;
+  if (actor.kind === ACTOR_AUTOMATION) return "External automation (CDP client)";
+  if (actor.kind === ACTOR_AGENT) return "Unidentified agent";
+  return "Unknown";
+}

package/dist/agent-policy.js

@@ -0,0 +1,109 @@
+// Actor-aware policy: what may an AGENT do on this site?
+//
+// The org policy's `extension.agents` block:
+//   {
+//     default: "allow" | "log" | "approve" | "deny",   // no rule matched
+//     rules: [{
+//       agent:   "*" | "<known key, e.g. claude-in-chrome>" | "<extension id>"
+//                | "automation" (external CDP client) | "unidentified" (agent, unnamed),
+//       sites:   ["*", "chatgpt.com", "*.example.com"],
+//       actions: ["*", "prompt_submit", "file_upload"],
+//       action:  "allow" | "log" | "approve" | "deny",
+//     }],
+//   }
+//
+// Semantics (content DLP policy still applies on top in every case):
+//   allow   — agent actions are treated like a person's.
+//   log     — every agent-driven submission is recorded (even a clean one) and
+//             receipted; nothing is blocked.
+//   approve — the submission is HELD until an admin approves it (existing
+//             approvals flow, TTL-bounded), whatever its content.
+//   deny    — agent-driven submissions on this site are refused outright. A
+//             person taking the keyboard back can still send.
+//
+// Human actors are never gated here. First matching rule wins. Pure module,
+// unit-tested; the service worker and the propagation test both import it.
+
+export const AGENT_ACTIONS = ["allow", "log", "approve", "deny"];
+export const DEFAULT_AGENTS_POLICY = Object.freeze({ default: "allow", rules: [] });
+
+const RANK = { allow: 0, log: 1, approve: 2, deny: 3 };
+
+function normalizeAction(a, fallback = "allow") {
+  const s = String(a || "").toLowerCase();
+  return AGENT_ACTIONS.includes(s) ? s : fallback;
+}
+
+/** The agent selector keys an actor answers to, most specific first. */
+export function actorKeys(actor) {
+  if (!actor || actor.kind === "human") return [];
+  const keys = [];
+  if (actor.agent) {
+    if (actor.agent.key) keys.push(String(actor.agent.key).toLowerCase());
+    if (actor.agent.id) keys.push(String(actor.agent.id).toLowerCase());
+  }
+  if (actor.kind === "automation") keys.push("automation");
+  if (actor.kind === "agent" && !actor.agent) keys.push("unidentified");
+  if (actor.kind === "unknown") keys.push("unknown");
+  keys.push("*");
+  return keys;
+}
+
+export function siteMatches(pattern, host) {
+  const p = String(pattern || "").trim().toLowerCase();
+  const h = String(host || "").trim().toLowerCase();
+  if (!p) return false;
+  if (p === "*") return true;
+  if (!h) return false;
+  if (p.startsWith("*.")) {
+    const base = p.slice(2);
+    return h === base || h.endsWith("." + base);
+  }
+  return h === p;
+}
+
+export function ruleMatches(rule, actor, host, actionKind) {
+  if (!rule || typeof rule !== "object") return false;
+  const keys = actorKeys(actor);
+  if (!keys.length) return false;
+  const agentSel = String(rule.agent || "*").toLowerCase();
+  if (!keys.includes(agentSel)) return false;
+  const sites = Array.isArray(rule.sites) && rule.sites.length ? rule.sites : ["*"];
+  if (!sites.some((s) => siteMatches(s, host))) return false;
+  const actions = Array.isArray(rule.actions) && rule.actions.length ? rule.actions : ["*"];
+  const kind = String(actionKind || "prompt_submit").toLowerCase();
+  return actions.some((a) => a === "*" || String(a).toLowerCase() === kind);
+}
+
+/**
+ * Decide the gate for one action.
+ * @returns {{action:"allow"|"log"|"approve"|"deny", rule:number|null, source:"rule"|"default"|"human"|"none"}}
+ */
+export function decideAgentAction(agentsPolicy, actor, host, actionKind = "prompt_submit") {
+  if (!actor || actor.kind === "human") return { action: "allow", rule: null, source: "human" };
+  // `unknown` (no input observed at all) is gated only by rules that name it
+  // explicitly — never by "*" or the default, so a quiet programmatic send is
+  // not mistaken for an agent.
+  const pol = agentsPolicy && typeof agentsPolicy === "object" ? agentsPolicy : DEFAULT_AGENTS_POLICY;
+  const rules = Array.isArray(pol.rules) ? pol.rules : [];
+  for (let i = 0; i < rules.length; i++) {
+    const r = rules[i];
+    if (actor.kind === "unknown" && String(r?.agent || "*").toLowerCase() !== "unknown") continue;
+    if (ruleMatches(r, actor, host, actionKind)) {
+      return { action: normalizeAction(r.action), rule: i, source: "rule" };
+    }
+  }
+  if (actor.kind === "unknown") return { action: "allow", rule: null, source: "none" };
+  return { action: normalizeAction(pol.default), rule: null, source: "default" };
+}
+
+/** Strictest of two gates (used to aggregate a multi-file upload). */
+export function strictestGate(a, b) {
+  if (!a) return b || null;
+  if (!b) return a;
+  return (RANK[b.action] || 0) > (RANK[a.action] || 0) ? b : a;
+}
+
+export function isGated(gate) {
+  return !!gate && (gate.action === "approve" || gate.action === "deny");
+}

package/dist/attribution.js

@@ -0,0 +1,52 @@
+// Agent attribution header — lets the org's own sites, WAF and SaaS tell
+// agent-driven traffic from a person's, per tab, in real time.
+//
+// When a tab is agent-driven and the org policy enables
+// `agents.attribution_header`, the service worker installs a
+// declarativeNetRequest SESSION rule scoped to that tab that sets
+//   Sec-Agent-Actor: <agent-key>; kind=<kind>; confidence=<c>; endpoint=<id>
+// on every request the tab makes to a site Medusa has host access to. The rule
+// is removed when the agent detaches or the tab closes. Verified in the week-1
+// spikes (fetch + top-level navigation; other tabs untouched).
+//
+// Pure helpers here; the chrome.declarativeNetRequest calls live in
+// agent-governance.js.
+
+export const ACTOR_HEADER = "Sec-Agent-Actor";
+const RULE_BASE = 1_000_000;
+
+// Header values are restricted to RFC 9110 token-ish characters.
+function tok(s, max = 64) {
+  return String(s == null ? "" : s).replace(/[^A-Za-z0-9._:-]/g, "-").slice(0, max) || "unknown";
+}
+
+export function actorHeaderValue(actor, endpoint) {
+  const key = actor?.agent?.key || actor?.agent?.id || (actor?.kind === "automation" ? "automation" : actor?.kind === "agent" ? "unidentified" : "unknown");
+  const parts = [
+    tok(key),
+    `kind=${tok(actor?.kind || "unknown", 16)}`,
+    `confidence=${tok(actor?.confidence || "low", 8)}`,
+    `endpoint=${tok(endpoint || "unenrolled", 80)}`,
+  ];
+  return parts.join("; ");
+}
+
+export function headerRuleId(tabId) {
+  const n = Number(tabId) || 0;
+  return RULE_BASE + (n % 1_000_000_000);
+}
+
+export function headerRule(tabId, value) {
+  return {
+    id: headerRuleId(tabId),
+    priority: 1,
+    action: {
+      type: "modifyHeaders",
+      requestHeaders: [{ header: ACTOR_HEADER, operation: "set", value }],
+    },
+    condition: {
+      tabIds: [Number(tabId)],
+      resourceTypes: ["main_frame", "sub_frame", "xmlhttprequest", "ping", "other", "script", "image", "stylesheet", "font", "media", "websocket"],
+    },
+  };
+}

package/dist/index.js

@@ -0,0 +1,45 @@
+// @medusasec/sensitive-spans — assembled by build.mjs from the Medusa extension.
+export { classifyLocal, applyAllowlist } from "./local-classifier.js";
+export {
+  decide, filterSpans, actionForSpans, cleanSpanText,
+  hasGenuineIdentifier, hasSecretSignal, hasCodeSignal, hasHealthSignal,
+  hasFinancialSignal, hasInsuranceSignal, isProsePii, isDegenerateSpan,
+  isNoisyPii, isNoisyOcrText, isObserveMode, isFailClosed, unscannableAction,
+} from "./policy-decision.js";
+export { mergeSpans } from "./merge-spans.js";
+export { detectSpans as detectSpansTier0, DEFAULT_POLICY as TIER0_DEFAULT_POLICY, PRODUCTION_CATEGORIES as TIER0_CATEGORIES } from "./medusa-engine.js";
+export * from "./actor.js";
+export * from "./agent-policy.js";
+export * from "./receipts.js";
+export * from "./pseudonymize.js";
+export * from "./attribution.js";
+export * from "./webmcp-inventory.js";
+
+import { classifyLocal as _classifyLocal, applyAllowlist as _applyAllowlist } from "./local-classifier.js";
+import { decide as _decide } from "./policy-decision.js";
+
+/** Every category on, no confidence floor — the enrolled-endpoint posture. */
+export const ALL_CATEGORIES_ON = Object.freeze({
+  SECRET: true, PII: true, FINANCIAL: true, HEALTH: true, INSURANCE: true, CODE: true, INJECTION: true,
+  LEGAL: true, HR: true, BUSINESS: true,
+});
+
+/**
+ * Detect sensitive spans in `text` with the deterministic layer (vendor key
+ * patterns, checksummed PII/financial identifiers, prompt-injection families,
+ * your custom patterns) and run the measured precision guards + policy over
+ * them. Returns { spans, action, requireJustification, disallowOverride,
+ * disallowApproval } exactly as the extension decides it.
+ *
+ * Plug a model in by passing `extraSpans` (e.g. from your own token
+ * classifier); they are merged before the guards run.
+ */
+export function detect(text, { policy = {}, settings, extraSpans = [] } = {}) {
+  const s = settings || { enabledCategories: ALL_CATEGORIES_ON, confidenceThreshold: 0, minTextLength: 1 };
+  const local = _classifyLocal(String(text ?? ""), {
+    customPatterns: policy.custom_dlp_patterns,
+    disabledDetectors: policy.disabled_detectors,
+  });
+  const merged = _applyAllowlist([...(extraSpans || []), ...local], policy.dlp_allowlist);
+  return _decide(merged, s, policy, String(text ?? ""));
+}