@sudobility/sider_lib 0.0.2

package/dist/tokenize.js

@@ -0,0 +1,199 @@
+// Tokenizer (browser-side, but PURE here — the caller supplies the secret
+// values it discovered in the user's own cookie jar / storage). Replaces secrets
+// in a raw observation with a readable placeholder "{{secret:<slotId>}}" and
+// emits SecretSlot proposals — so nothing with a real secret leaves the browser.
+//
+// Coverage (defense in depth, because storage cross-reference alone misses
+// secrets minted this session or carried in bodies / non-standard headers):
+//   1. Known values gathered from the user's own cookies/storage (exact match).
+//   2. Any request header whose NAME looks credential-bearing.
+//   3. Body fields whose KEY looks credential-bearing (e.g. access_token).
+//   4. JWT-shaped strings anywhere in a body.
+// Bias is conservative-for-privacy: over-mask rather than leak.
+export function samplePlaceholder(slotId) {
+    return `{{secret:${slotId}}}`;
+}
+// Header NAME looks credential-bearing (conservative-for-privacy: any "key",
+// "token", "auth", "secret", "session", etc. in the name).
+const SECRET_HEADER_RE = /authorization|cookie|token|key|secret|session|auth|xsrf|csrf|bearer/i;
+// Body property KEY looks credential-bearing.
+const SECRET_KEY_RE = /(^|[_-])(access_token|refresh_token|id_token|token|api[-_]?key|apikey|client_secret|secret|password|passwd|session_?(id|token)|jwt|bearer|credential|auth_?token)($|[_-])/i;
+// JWT-shaped string.
+const JWT_RE = /eyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{2,}/g;
+const MIN_MASK_LEN = 6;
+export function tokenizeObservation(raw, known) {
+    const origin = originOf(raw.url);
+    const host = hostOf(origin);
+    const slots = new Map();
+    let url = raw.url;
+    const headers = { ...raw.requestHeaders };
+    let requestBody = raw.requestBody;
+    let responseBody = raw.responseBody;
+    const ensure = (slotId, kind, role, loc, hint) => {
+        if (slots.has(slotId))
+            return;
+        slots.set(slotId, {
+            id: slotId,
+            kind,
+            role,
+            injectionLocation: loc,
+            allowedDestination: origin,
+            resolverHints: hint ? [hint] : [],
+            confidence: 0.6,
+        });
+    };
+    // 1. Known values (exact substring match everywhere).
+    for (const s of known) {
+        if (!s.value)
+            continue;
+        const loc = locate(raw, s.value) ?? { at: "header", name: "authorization" };
+        const ph = samplePlaceholder(s.slotId);
+        url = url.split(s.value).join(ph);
+        for (const k of Object.keys(headers))
+            headers[k] = headers[k].split(s.value).join(ph);
+        requestBody = replaceInJson(requestBody, s.value, ph);
+        responseBody = replaceInJson(responseBody, s.value, ph);
+        ensure(s.slotId, s.kind, s.role, loc, s.resolverHint);
+    }
+    // 2. Credential-bearing headers (by name), even when the value wasn't in storage.
+    for (const name of Object.keys(headers)) {
+        const val = headers[name];
+        if (typeof val !== "string" || !val || val.startsWith("{{secret:"))
+            continue;
+        if (!SECRET_HEADER_RE.test(name))
+            continue;
+        const lname = name.toLowerCase();
+        const slotId = `slot:${host}:${normalize(name)}`;
+        headers[name] = samplePlaceholder(slotId);
+        ensure(slotId, guessKind(name), lname === "cookie" ? "auto_cookie" : "active_inject", lname === "cookie" ? { at: "cookie", name } : { at: "header", name });
+    }
+    // 3 + 4. Body fields by key + JWTs anywhere.
+    requestBody = maskBody(requestBody, host, origin, slots, ensure, "");
+    responseBody = maskBody(responseBody, host, origin, slots, ensure, "");
+    return {
+        observation: {
+            method: raw.method,
+            url,
+            requestHeaders: headers,
+            requestBody,
+            status: raw.status,
+            responseBody,
+            timingMs: raw.timingMs,
+            context: raw.context,
+        },
+        slots: [...slots.values()],
+    };
+}
+function maskBody(node, host, origin, slots, ensure, path, key) {
+    if (node === undefined || node === null)
+        return node;
+    if (typeof node === "string") {
+        if (key && node.length >= MIN_MASK_LEN && SECRET_KEY_RE.test(key)) {
+            const slotId = `slot:${host}:${normalize(key)}`;
+            ensure(slotId, guessKind(key), "active_inject", { at: "body", jsonPath: path });
+            return samplePlaceholder(slotId);
+        }
+        if (JWT_RE.test(node)) {
+            JWT_RE.lastIndex = 0;
+            const slotId = `slot:${host}:jwt`;
+            ensure(slotId, "bearer", "active_inject", { at: "body", jsonPath: path });
+            return node.replace(JWT_RE, samplePlaceholder(slotId));
+        }
+        return node;
+    }
+    if (Array.isArray(node))
+        return node.map((n, i) => maskBody(n, host, origin, slots, ensure, `${path}[${i}]`, key));
+    if (typeof node === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(node))
+            out[k] = maskBody(v, host, origin, slots, ensure, path ? `${path}.${k}` : k, k);
+        return out;
+    }
+    return node;
+}
+// --- helpers ---------------------------------------------------------------
+function guessKind(name) {
+    const n = name.toLowerCase();
+    if (n.includes("csrf") || n.includes("xsrf"))
+        return "csrf";
+    if (n.includes("cookie") || n.includes("session"))
+        return "session";
+    if (n.includes("auth") || n.includes("bearer") || n.includes("token") || n.includes("jwt"))
+        return "bearer";
+    if (n.includes("api") && n.includes("key"))
+        return "api_key";
+    return "unknown";
+}
+function locate(raw, value) {
+    for (const [name, v] of Object.entries(raw.requestHeaders)) {
+        if (typeof v === "string" && v.includes(value))
+            return { at: "header", name };
+    }
+    try {
+        const u = new URL(raw.url, "http://sider.local");
+        for (const [param, v] of u.searchParams)
+            if (v.includes(value))
+                return { at: "query", param };
+    }
+    catch {
+        /* ignore */
+    }
+    const bodyPath = findInJson(raw.requestBody, value);
+    if (bodyPath)
+        return { at: "body", jsonPath: bodyPath };
+    return null;
+}
+function findInJson(node, value, prefix = "") {
+    if (typeof node === "string")
+        return node.includes(value) ? prefix.replace(/^\./, "") : null;
+    if (Array.isArray(node)) {
+        for (let i = 0; i < node.length; i++) {
+            const p = findInJson(node[i], value, `${prefix}[${i}]`);
+            if (p)
+                return p;
+        }
+        return null;
+    }
+    if (node && typeof node === "object") {
+        for (const [k, v] of Object.entries(node)) {
+            const p = findInJson(v, value, `${prefix}.${k}`);
+            if (p)
+                return p;
+        }
+    }
+    return null;
+}
+function replaceInJson(node, value, ph) {
+    if (node === undefined)
+        return node;
+    if (typeof node === "string")
+        return node.split(value).join(ph);
+    if (Array.isArray(node))
+        return node.map((n) => replaceInJson(n, value, ph));
+    if (node && typeof node === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(node))
+            out[k] = replaceInJson(v, value, ph);
+        return out;
+    }
+    return node;
+}
+function originOf(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return url;
+    }
+}
+function hostOf(origin) {
+    try {
+        return new URL(origin).host;
+    }
+    catch {
+        return origin;
+    }
+}
+function normalize(s) {
+    return s.toLowerCase().replace(/[^a-z0-9]+/g, "_");
+}

package/dist/tokenize.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tokenize.test.js

@@ -0,0 +1,42 @@
+import { test, expect } from "bun:test";
+import { tokenizeObservation } from "./tokenize";
+function raw(overrides = {}) {
+    return {
+        method: "GET",
+        url: "https://resale.fifa.com/api/seats",
+        requestHeaders: {},
+        requestBody: undefined,
+        status: 200,
+        responseBody: undefined,
+        timingMs: 10,
+        context: { route: "/seats" },
+        ...overrides,
+    };
+}
+test("masks a credential-named request header", () => {
+    const { observation, slots } = tokenizeObservation(raw({ requestHeaders: { authorization: "Bearer abc.def.ghi" } }), []);
+    expect(JSON.stringify(observation.requestHeaders)).not.toContain("abc.def.ghi");
+    expect(slots.length).toBeGreaterThan(0);
+});
+test("masks a known cookie/storage value wherever it appears in a body", () => {
+    const known = [
+        {
+            value: "SUPERSECRETVALUE123",
+            slotId: "slot:resale.fifa.com:session",
+            kind: "session",
+            role: "active_inject",
+            resolverHint: { from: "cookie", name: "sid" },
+        },
+    ];
+    const { observation } = tokenizeObservation(raw({ responseBody: { echoed: "SUPERSECRETVALUE123", ok: true } }), known);
+    expect(JSON.stringify(observation.responseBody)).not.toContain("SUPERSECRETVALUE123");
+});
+test("masks a JWT-shaped string in a body", () => {
+    const jwt = "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0In0.abc123signature";
+    const { observation } = tokenizeObservation(raw({ responseBody: { token: jwt } }), []);
+    expect(JSON.stringify(observation.responseBody)).not.toContain(jwt);
+});
+test("leaves non-secret data untouched", () => {
+    const { observation } = tokenizeObservation(raw({ responseBody: { price: 400, section: "A1" } }), []);
+    expect(observation.responseBody).toEqual({ price: 400, section: "A1" });
+});

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@sudobility/sider_lib",
+  "version": "0.0.2",
+  "description": "Sider business logic — recipe compiler, egress gates, tokenizer, clustering. Pure, no Chrome/DOM/server.",
+  "license": "BUSL-1.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@sudobility/sider_types": "^0.0.2"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "typescript": "^5.9.3"
+  }
+}

package/src/composite.ts

@@ -0,0 +1,86 @@
+// Composite/fan-out tool execution. A ToolSpec whose recipe has `compose` steps
+// chains or fans out over other tools — e.g. "list sections → for each, fetch
+// seats". This is PURE orchestration: the caller injects `run` (which applies
+// the three gates + issues the actual request for one tool), and this threads
+// prior outputs, resolves bindings, and parallelizes fan-out.
+
+import type { ComposeStep, ParamBinding, ToolSpec } from "@sudobility/sider_types";
+import { getByPath } from "./recipe";
+
+export interface RunStepResult {
+  ok: boolean;
+  status?: number;
+  body?: unknown;
+  error?: string;
+  gate?: string;
+}
+
+/** Runs ONE tool by id with resolved args. The caller applies gates + fetch. */
+export type StepRunner = (toolId: string, args: Record<string, unknown>) => Promise<RunStepResult>;
+
+/** Reference, in a priorOutput binding, to the current element during a fan-out. */
+const ITEM_REF = "$item";
+
+export async function executeComposite(
+  tool: ToolSpec,
+  ctx: { args?: Record<string, unknown> },
+  run: StepRunner,
+): Promise<RunStepResult> {
+  const steps = tool.recipe.compose ?? [];
+  if (steps.length === 0) return run(tool.id, ctx.args ?? {});
+
+  const priorOutputs: Record<string, unknown> = {};
+  let last: RunStepResult | undefined;
+
+  for (const step of steps) {
+    if (step.forEachJsonPath) {
+      // Fan out: run the step once per element of the referenced array (parallel).
+      const arr = getByPath(priorOutputs, step.forEachJsonPath);
+      const items = Array.isArray(arr) ? arr : [];
+      const results = await Promise.all(
+        items.map((item) => run(step.toolId, resolveArgs(step.argBindings, ctx, priorOutputs, item))),
+      );
+      priorOutputs[step.ref] = results.map((r) => r.body);
+      last = { ok: results.every((r) => r.ok), body: results.map((r) => r.body) };
+      if (!last.ok) break; // don't thread a failed fan-out into later steps
+    } else {
+      const r = await run(step.toolId, resolveArgs(step.argBindings, ctx, priorOutputs, undefined));
+      priorOutputs[step.ref] = r.body;
+      last = r;
+      if (!r.ok) break; // stop the chain on the first failure
+    }
+  }
+
+  return last ?? { ok: false, error: "empty compose" };
+}
+
+function resolveArgs(
+  bindings: Record<string, ParamBinding>,
+  ctx: { args?: Record<string, unknown> },
+  priorOutputs: Record<string, unknown>,
+  item: unknown,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, b] of Object.entries(bindings)) {
+    switch (b.kind) {
+      case "literal":
+        out[key] = b.value;
+        break;
+      case "arg":
+        out[key] = ctx.args?.[b.argName];
+        break;
+      case "priorOutput":
+        out[key] =
+          b.stepRef === ITEM_REF ? getByPath(item, b.jsonPath) : getByPath(priorOutputs[b.stepRef], b.jsonPath);
+        break;
+      case "secret":
+        // Secrets belong to the sub-tool's own recipe (resolved at egress by
+        // the runner), never to compose-level args.
+        break;
+    }
+  }
+  return out;
+}
+
+// keep the fan-out sentinel discoverable to callers/authors of recipes.
+export { ITEM_REF };

package/src/execute.ts

@@ -0,0 +1,89 @@
+// Detokenization (the last mile, browser-side) + the single prepareRequest
+// entry point. Detokenization runs ONLY after the gates pass; it reads each
+// secret's current value from the caller's resolver (backed by the browser
+// TokenMap) and substitutes it into the sentinel positions the gates already
+// proved are confined to the declared location.
+
+import type { CompiledRequest, SecretSlot } from "@sudobility/sider_types";
+import { compileRecipe, secretSentinel } from "./recipe";
+import { evaluateGates } from "./gates";
+import type { ToolSpec } from "@sudobility/sider_types";
+import type { CompileContext } from "./recipe";
+import type { GateContext } from "./gates";
+
+export interface ResolvedRequest {
+  method: CompiledRequest["method"];
+  url: string;
+  headers: Record<string, string>;
+  body?: unknown;
+  credentials: "include";
+}
+
+/** Resolve a slot's current value from the caller's live session (never stored). */
+export type SecretResolver = (slotId: string) => string | undefined;
+
+export function detokenizeRequest(
+  req: CompiledRequest,
+  resolve: SecretResolver,
+  slotsById: Record<string, SecretSlot>,
+): ResolvedRequest {
+  let url = req.url;
+  const headers: Record<string, string> = { ...req.headers };
+  let bodyStr = req.body !== undefined ? JSON.stringify(req.body) : undefined;
+
+  for (const slotId of req.referencedSlotIds) {
+    const slot = slotsById[slotId];
+    // auto_cookie secrets are attached by the browser; never substituted.
+    if (slot && (slot.role === "auto_cookie" || slot.injectionLocation.at === "cookie")) continue;
+
+    const value = resolve(slotId);
+    if (value === undefined) throw new Error(`Unresolved secret slot at egress: ${slotId}`);
+
+    const sen = secretSentinel(slotId);
+    url = url.split(sen).join(value);
+    for (const k of Object.keys(headers)) headers[k] = headers[k]!.split(sen).join(value);
+    if (bodyStr !== undefined) {
+      const innerEscaped = JSON.stringify(value).slice(1, -1); // JSON-string-safe
+      bodyStr = bodyStr.split(sen).join(innerEscaped);
+    }
+  }
+
+  return {
+    method: req.method,
+    url,
+    headers,
+    body: bodyStr !== undefined ? JSON.parse(bodyStr) : undefined,
+    credentials: "include",
+  };
+}
+
+export type PrepareResult =
+  | { ok: true; request: ResolvedRequest }
+  | { ok: false; gate: "compile" | "same_origin" | "injection_location" | "safety"; reason: string };
+
+/**
+ * compile → gate → detokenize, in one call. The browser executor should issue
+ * `result.request` only when `result.ok`.
+ */
+export function prepareRequest(
+  tool: ToolSpec,
+  compileCtx: CompileContext,
+  gateCtx: GateContext,
+  resolve: SecretResolver,
+): PrepareResult {
+  let compiled: CompiledRequest;
+  try {
+    compiled = compileRecipe(tool, compileCtx);
+  } catch (e) {
+    return { ok: false, gate: "compile", reason: (e as Error).message };
+  }
+
+  const gate = evaluateGates(compiled, gateCtx);
+  if (!gate.ok) return gate;
+
+  try {
+    return { ok: true, request: detokenizeRequest(compiled, resolve, gateCtx.slotsById) };
+  } catch (e) {
+    return { ok: false, gate: "injection_location", reason: (e as Error).message };
+  }
+}

package/src/gates.test.ts

@@ -0,0 +1,98 @@
+import { test, expect } from "bun:test";
+import { evaluateGates } from "./gates";
+import { secretSentinel } from "./recipe";
+import type { CompiledRequest, SecretSlot } from "@sudobility/sider_types";
+
+const ORIGIN = "https://resale.fifa.com";
+
+function slot(overrides: Partial<SecretSlot> = {}): SecretSlot {
+  return {
+    id: "slot:resale.fifa.com:auth_bearer",
+    siteId: "site1",
+    kind: "bearer",
+    role: "active_inject",
+    injectionLocation: { at: "header", name: "authorization" },
+    allowedDestination: ORIGIN,
+    resolverHints: [],
+    confidence: 1,
+    createdAt: "2026-01-01T00:00:00.000Z",
+    updatedAt: "2026-01-01T00:00:00.000Z",
+    ...overrides,
+  };
+}
+
+function req(overrides: Partial<CompiledRequest> = {}): CompiledRequest {
+  const sen = secretSentinel("slot:resale.fifa.com:auth_bearer");
+  return {
+    method: "GET",
+    url: `${ORIGIN}/api/seats`,
+    headers: { authorization: `Bearer ${sen}` },
+    body: undefined,
+    credentials: "include",
+    referencedSlotIds: ["slot:resale.fifa.com:auth_bearer"],
+    safetyClass: "read",
+    ...overrides,
+  };
+}
+
+const ctx = (extra: Partial<Parameters<typeof evaluateGates>[1]> = {}) => ({
+  siteOrigin: ORIGIN,
+  slotsById: { "slot:resale.fifa.com:auth_bearer": slot() },
+  ...extra,
+});
+
+test("Gate A: passes a same-origin read with a confined header secret", () => {
+  expect(evaluateGates(req(), ctx())).toEqual({ ok: true });
+});
+
+test("Gate A: refuses a cross-origin destination", () => {
+  const out = evaluateGates(req({ url: "https://evil.com/api/seats" }), ctx());
+  expect(out.ok).toBe(false);
+  if (!out.ok) expect(out.gate).toBe("same_origin");
+});
+
+test("Gate A: refuses when the slot's allowedDestination differs", () => {
+  const s = slot({ allowedDestination: "https://other.com" });
+  const out = evaluateGates(req(), ctx({ slotsById: { [s.id]: s } }));
+  expect(out.ok).toBe(false);
+  if (!out.ok) expect(out.gate).toBe("same_origin");
+});
+
+test("Gate B: refuses a sentinel relocated into the URL", () => {
+  const sen = secretSentinel("slot:resale.fifa.com:auth_bearer");
+  const out = evaluateGates(
+    req({ url: `${ORIGIN}/api/seats?t=${sen}`, headers: { authorization: `Bearer ${sen}` } }),
+    ctx(),
+  );
+  expect(out.ok).toBe(false);
+  if (!out.ok) expect(out.gate).toBe("injection_location");
+});
+
+test("Gate B: refuses when the sentinel is absent from its declared location", () => {
+  const out = evaluateGates(req({ headers: { authorization: "Bearer plain" } }), ctx());
+  expect(out.ok).toBe(false);
+  if (!out.ok) expect(out.gate).toBe("injection_location");
+});
+
+test("Gate C: a POST (method-bound) requires confirmation even if labeled read", () => {
+  const out = evaluateGates(req({ method: "POST", safetyClass: "read" }), ctx());
+  expect(out.ok).toBe(false);
+  if (!out.ok) expect(out.gate).toBe("safety");
+});
+
+test("Gate C: a confirmed POST passes", () => {
+  expect(evaluateGates(req({ method: "POST" }), ctx({ confirmed: true }))).toEqual({ ok: true });
+});
+
+test("Gate C: allowMutations=false blocks a mutation outright", () => {
+  const out = evaluateGates(req({ method: "POST" }), ctx({ confirmed: true, allowMutations: false }));
+  expect(out.ok).toBe(false);
+  if (!out.ok) expect(out.gate).toBe("safety");
+});
+
+test("cookie-borne slot is refused (must be auto-attached, never injected)", () => {
+  const s = slot({ role: "auto_cookie", injectionLocation: { at: "cookie", name: "sid" } });
+  const out = evaluateGates(req(), ctx({ slotsById: { [s.id]: s } }));
+  expect(out.ok).toBe(false);
+  if (!out.ok) expect(out.gate).toBe("injection_location");
+});

package/src/gates.ts

@@ -0,0 +1,124 @@
+// The three egress gates. This is the security core: tokenization is only safe
+// BECAUSE a secret cannot leave for the wrong destination (Gate A), cannot be
+// relocated out of its declared slot (Gate B), and cannot ride a mutation
+// without confirmation (Gate C). Run on a CompiledRequest whose secrets are
+// still sentinels — never on values.
+
+import type { CompiledRequest, GateOutcome, SecretSlot } from "@sudobility/sider_types";
+import { getByPath, secretSentinel } from "./recipe";
+
+export interface GateContext {
+  /** The site's origin. The request destination MUST equal this. */
+  siteOrigin: string;
+  /** Every secret slot the request may reference, keyed by slot id (placeholder). */
+  slotsById: Record<string, SecretSlot>;
+  /** True once the user has confirmed a write/financial step. */
+  confirmed?: boolean;
+  /** Site policy: whether mutations are permitted here at all. */
+  allowMutations?: boolean;
+}
+
+export function evaluateGates(req: CompiledRequest, ctx: GateContext): GateOutcome {
+  // --- Gate A: same-origin destination ------------------------------------
+  let originHost: string;
+  try {
+    originHost = new URL(req.url).origin;
+  } catch {
+    return { ok: false, gate: "same_origin", reason: `invalid url: ${req.url}` };
+  }
+  if (originHost !== ctx.siteOrigin) {
+    return {
+      ok: false,
+      gate: "same_origin",
+      reason: `destination ${originHost} != site ${ctx.siteOrigin}`,
+    };
+  }
+
+  for (const slotId of req.referencedSlotIds) {
+    const slot = ctx.slotsById[slotId];
+    if (!slot) {
+      return { ok: false, gate: "injection_location", reason: `unknown secret slot ${slotId}` };
+    }
+    if (slot.allowedDestination !== originHost) {
+      return {
+        ok: false,
+        gate: "same_origin",
+        reason: `slot ${slotId} allows ${slot.allowedDestination}, not ${originHost}`,
+      };
+    }
+    if (slot.role === "auto_cookie" || slot.injectionLocation.at === "cookie") {
+      return {
+        ok: false,
+        gate: "injection_location",
+        reason: `slot ${slotId} is cookie-borne (auto-attached); it must not be injected`,
+      };
+    }
+
+    // --- Gate B: sentinel appears ONLY in its declared location ------------
+    const b = injectionCheck(req, slot);
+    if (!b.ok) return b;
+  }
+
+  // --- Gate C: mutations require confirmation -----------------------------
+  // Bind to the HTTP method, not just the server-declared (and therefore
+  // untrusted) safetyClass — a recipe labeled "read" with a POST/PUT/PATCH/
+  // DELETE still mutates and must not run unconfirmed.
+  const idempotent = req.method === "GET" || req.method === "HEAD" || req.method === "OPTIONS";
+  if (req.safetyClass !== "read" || !idempotent) {
+    if (ctx.allowMutations === false) {
+      return { ok: false, gate: "safety", reason: `mutations disabled for ${ctx.siteOrigin}` };
+    }
+    if (!ctx.confirmed) {
+      return { ok: false, gate: "safety", reason: `mutating request requires confirmation` };
+    }
+  }
+
+  return { ok: true };
+}
+
+function injectionCheck(req: CompiledRequest, slot: SecretSlot): GateOutcome {
+  const sen = secretSentinel(slot.id);
+  const bodyStr = req.body !== undefined ? JSON.stringify(req.body) : "";
+
+  const total =
+    count(req.url, sen) +
+    Object.values(req.headers).reduce((n, v) => n + count(v, sen), 0) +
+    count(bodyStr, sen);
+
+  let allowed = 0;
+  const loc = slot.injectionLocation;
+  if (loc.at === "header") {
+    allowed = count(req.headers[loc.name] ?? "", sen);
+  } else if (loc.at === "query") {
+    let qv = "";
+    try {
+      qv = new URL(req.url).searchParams.get(loc.param) ?? "";
+    } catch {
+      /* invalid url already caught in Gate A */
+    }
+    allowed = count(qv, sen);
+  } else if (loc.at === "body") {
+    allowed = count(String(getByPath(req.body, loc.jsonPath) ?? ""), sen);
+  }
+
+  if (allowed < 1) {
+    return {
+      ok: false,
+      gate: "injection_location",
+      reason: `slot ${slot.id} absent from its declared ${loc.at} location`,
+    };
+  }
+  if (total !== allowed) {
+    return {
+      ok: false,
+      gate: "injection_location",
+      reason: `slot ${slot.id} appears outside its declared ${loc.at} location`,
+    };
+  }
+  return { ok: true };
+}
+
+function count(hay: string, needle: string): number {
+  if (!needle) return 0;
+  return hay.split(needle).length - 1;
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+// @sudobility/sider_lib — pure Sider business logic.
+//
+//   templating  — cluster raw observations into endpoint templates
+//   tokenize    — replace known secret values with placeholders (browser-side)
+//   recipe      — compile a ToolSpec + args into a CompiledRequest (secrets = sentinels)
+//   gates       — the three egress gates (same-origin / injection-location / safety)
+//   execute     — detokenize after gates pass; prepareRequest = compile→gate→detokenize
+//
+// No Chrome/DOM/server dependencies — safe to import from sider_api,
+// sider_extension, and sider_app alike.
+
+export * from "./templating";
+export * from "./tokenize";
+export * from "./recipe";
+export * from "./gates";
+export * from "./execute";
+export * from "./composite";