@secure-ai/guard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Secure AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# @secure-ai/guard
+
+Data loss prevention for AI agents. Put a check in front of every action an
+agent takes, before it takes it.
+
+```bash
+npm install @secure-ai/guard
+```
+
+## The one thing worth knowing
+
+`guard` wraps a function an agent already calls, and calls it with the
+**rewritten** arguments:
+
+```ts
+import { SecureAI } from "@secure-ai/guard";
+
+const sai = new SecureAI({ apiKey: process.env.SECURE_AI_KEY!, agent: "support-bot" });
+
+const sendEmail = sai.guard("email.send", async (input: { to: string; body: string }) => {
+  return mailer.send(input);
+});
+
+await sendEmail({ to: "ana@clientfirm.com", body: "About invoice 4471…" });
+```
+
+The agent wrote a real address. `mailer.send` receives a stand-in. Nothing in
+the agent's code had to check a decision, which is the point — protection that
+depends on remembering to check it is protection that ends at the fourteenth
+call site.
+
+If the policy refuses the action, the wrapped function is never called and
+`ActionBlocked` is thrown.
+
+## Getting the real values back
+
+Redaction is reversible with the map the inspection returned. The map is
+returned to you and **is not stored on our side** — losing it means losing the
+ability to restore that reply.
+
+```ts
+const verdict = await sai.inspect({ tool: "llm.complete", input: prompt });
+const reply = await model.complete(verdict.input);
+const readable = await sai.restore(reply, verdict.map);
+```
+
+## Rules
+
+Rules live on the account, not in the request. An agent cannot argue with them.
+
+```ts
+await sai.setPolicy({
+  fallback: "redact",
+  rules: [
+    { kind: "secret", decision: "block" },
+    { kind: "card", decision: "block", direction: "outbound" },
+    { kind: "email", decision: "allow", tools: ["crm.*"] },
+  ],
+  denyTools: ["shell.*"],
+});
+```
+
+`decision` is `allow`, `redact` or `block`. When an action contains several
+findings, the **most severe** decision wins — an action carrying a credential
+is refused even if everything else in it was fine.
+
+When the scanner keeps flagging something that is yours:
+
+```ts
+await sai.allowValue("@ourcompany.com");
+```
+
+That applies to every agent on the account from the next action onward.
+
+## The trail
+
+```ts
+const { blocked, byKind } = await sai.summary();
+const { events } = await sai.audit({ limit: 100 });
+```
+
+Records hold the **kind and location** of what was found — `card` at
+`body.payment.number` — and never the value. There is no field on an audit
+record that can hold one. That is deliberate: a store of every sensitive value
+every agent touched is the thing this product exists to avoid being.
+
+## When Secure AI is unreachable
+
+The default is `onUnreachable: "closed"` — the action does not happen, and the
+error propagates. That is the correct default for a security control, and it
+does mean an outage here stops agents.
+
+```ts
+new SecureAI({ apiKey, onUnreachable: "open" }); // availability over control
+```
+
+Failing open never lets a real refusal through: a 401, 402 or quota error is an
+answer, not an outage, and still throws.
+
+## No code to change at all
+
+If wrapping each tool is too invasive, hand the gateway fetch to whatever HTTP
+client the agent already uses. Every request it makes is inspected on the way
+out, and no call site changes:
+
+```ts
+const openai = new OpenAI({
+  apiKey: process.env.OPENAI_KEY!,
+  fetch: sai.fetch({ forwardAuth: `Bearer ${process.env.OPENAI_KEY}` }),
+});
+```
+
+Two credentials travel and they are kept apart on purpose: your Secure AI key
+authenticates you to us and is **never** forwarded; `forwardAuth` is the
+destination's own credential and becomes its `Authorization` header.
+
+A refused request throws `ActionBlocked`, the same as a guarded function.
+Pass `throwOnBlock: false` to get the 403 back instead.
+
+The gateway will not forward to private or link-local addresses, so it cannot
+be pointed at a cloud metadata service. Bodies it cannot read as text — an
+image, a zip — are forwarded and the response carries
+`X-Secure-AI-Inspected: false`, rather than a clean log implying a check that
+did not happen.
+
+## Runtime
+
+Needs `fetch` and nothing else — Node 18+, Bun, Deno, Cloudflare Workers,
+browsers. No dependencies, deliberately: this runs next to somebody's model
+client and framework, and every dependency it adds is a version conflict it can
+cause in a process already carrying too many.
+
+## Also available over MCP
+
+Agents that speak MCP can reach the same controls as tools at
+`https://api.secureai.one/mcp` — `inspect_action`, `check_policy`,
+`recent_activity`, plus `redact` and `restore`.
+
+Full reference: <https://secureai.one/developers>

package/dist/index.d.ts

@@ -0,0 +1,279 @@
+/**
+ * The Secure AI SDK — data loss prevention for AI agents.
+ *
+ * The API is four HTTP calls and anybody can use it with fetch. This exists
+ * because the shape that makes the product work is not "call an endpoint", it
+ * is "put a check in front of every action", and the difference between those
+ * two is whether somebody remembers to do it at the fourteenth call site.
+ *
+ * So the centre of this file is `guard`, which takes a function an agent
+ * already calls and returns one that cannot run without a decision:
+ *
+ *     const post = guard("http.post", rawPost);
+ *     await post({ url, body });   // blocked actions throw
+ *
+ * Everything else is the plumbing under it.
+ *
+ * ── No dependencies, on purpose ──
+ *
+ * This runs inside somebody's agent, next to their model client, their
+ * framework and their vendor SDKs. Every dependency it adds is a version
+ * conflict it can cause in a process that is already carrying too many, and a
+ * security tool that is awkward to install is one that gets removed. It needs
+ * fetch and nothing else: Node 18+, Bun, Deno, Cloudflare Workers, browsers.
+ */
+export type Decision = "allow" | "redact" | "approve" | "block";
+export type ApprovalStatus = "pending" | "approved" | "denied" | "expired";
+export type Direction = "outbound" | "inbound";
+export type Kind = "secret" | "card" | "iban" | "ssn" | "govid" | "email" | "phone" | "address" | "postcode" | "name" | "host";
+export interface Finding {
+    kind: Kind;
+    /** Where in the action it sat, e.g. "body.customer.email". */
+    path: string;
+    decision: Decision;
+}
+export interface Approval {
+    id: string;
+    createdAt: number;
+    expiresAt: number;
+    status: ApprovalStatus;
+    agent: string | null;
+    tool: string;
+    keyId: string;
+    findings: Finding[];
+    decidedBy?: string;
+    decidedAt?: number;
+    note?: string;
+}
+export interface InspectResult<T = unknown> {
+    decision: Decision;
+    /** Set when the decision is "approve": the id to come back with once a
+     *  person has decided. */
+    approvalId?: string;
+    /** When waiting stops being worth it. Milliseconds since epoch. */
+    expiresAt?: number;
+    /**
+     * The action, ready to send. Absent when the decision is "block" — there is
+     * deliberately nothing sendable in a refusal, so a caller cannot reach past
+     * the decision by accident.
+     */
+    input?: T;
+    /** {standIn: real}. Keep it: it is the only way to turn a reply back, and
+     *  it is not stored on our side. */
+    map: Record<string, string>;
+    findings: Finding[];
+    toolDenied: boolean;
+    policySource: "account" | "default" | "unreadable";
+    auditId: string;
+}
+export interface Rule {
+    kind: Kind;
+    decision: Decision;
+    tools?: string[];
+    direction?: Direction;
+}
+export interface Policy {
+    version: 1;
+    fallback: Decision;
+    rules: Rule[];
+    denyTools?: string[];
+    allow?: string[];
+}
+/** An action the policy refused. Thrown by a guarded function rather than
+ *  returned, because a refusal is not a result the caller should be able to
+ *  ignore by not reading a field. */
+export declare class ActionBlocked extends Error {
+    readonly tool: string;
+    readonly findings: Finding[];
+    readonly toolDenied: boolean;
+    readonly auditId: string;
+    constructor(tool: string, result: InspectResult);
+}
+/**
+ * A person refused this action, or nobody answered in time.
+ *
+ * Distinct from ActionBlocked because the answer to it is different: a policy
+ * refusal is a rule to change, and this is a conversation to have. An agent
+ * reporting "the policy forbids this" when in fact Dave clicked no would send
+ * somebody to the wrong screen.
+ */
+export declare class ApprovalRefused extends Error {
+    readonly tool: string;
+    readonly approvalId: string;
+    readonly status: ApprovalStatus;
+    readonly note?: string;
+    constructor(tool: string, approvalId: string, status: ApprovalStatus, note?: string);
+}
+/** The API answered, and said no. Separate from ActionBlocked: this is a
+ *  problem with the call, not a decision about the action. */
+export declare class SecureAIError extends Error {
+    readonly status: number;
+    readonly code: string | null;
+    constructor(message: string, status: number, code: string | null);
+}
+export interface ClientOptions {
+    apiKey: string;
+    /** Overridable for staging and for tests. */
+    baseUrl?: string;
+    /** Names this agent in the audit trail, so its actions group together.
+     *  Worth setting: a trail where everything is unnamed is a trail nobody
+     *  can ask a question of. */
+    agent?: string;
+    /** Milliseconds before a call is abandoned. This sits in front of an
+     *  agent's actions, so a hung check is a hung agent. */
+    timeoutMs?: number;
+    /** Injected for tests, and for runtimes with an unusual fetch. */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * What to do when Secure AI itself cannot be reached.
+     *
+     * "closed" — the default — throws, so an action is not taken while the
+     * thing that governs it is down. That is the correct default for a security
+     * control and it does mean an outage here stops agents.
+     *
+     * "open" lets the action through unchecked. It is offered because some
+     * workloads genuinely prefer availability, and because a customer who wants
+     * it will otherwise implement it themselves with a try/catch that also
+     * swallows real refusals. Choosing it is a decision to record.
+     */
+    onUnreachable?: "closed" | "open";
+}
+export declare class SecureAI {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly agent?;
+    private readonly timeoutMs;
+    private readonly doFetch;
+    private readonly onUnreachable;
+    constructor(options: ClientOptions);
+    private request;
+    /** Judge an action without taking it. */
+    inspect<T = unknown>(action: {
+        tool: string;
+        input: T;
+        direction?: Direction;
+        agent?: string;
+        /** Set when coming back after a person has decided. */
+        approvalId?: string;
+    }): Promise<InspectResult<T>>;
+    /** One held action. */
+    approval(id: string): Promise<Approval>;
+    /** Everything waiting, for a reviewer's screen. */
+    approvals(opts?: {
+        status?: ApprovalStatus;
+        limit?: number;
+    }): Promise<Approval[]>;
+    /**
+     * Wait for a person to decide.
+     *
+     * Polling, because it is the only mechanism that works in every runtime an
+     * agent might be in — a held connection dies to platform timeouts, and a
+     * callback needs the agent to be addressable, which a script on somebody's
+     * laptop is not.
+     *
+     * Stops at the approval's own expiry rather than running forever: the
+     * server will refuse it after that anyway, and a loop that outlives the
+     * thing it is waiting for is a hung agent.
+     */
+    waitForApproval(id: string, opts?: {
+        pollMs?: number;
+        signal?: AbortSignal;
+    }): Promise<Approval>;
+    /** The rules currently in force. */
+    getPolicy(): Promise<{
+        policy: Policy;
+        source: string;
+    }>;
+    /** Replace them. */
+    setPolicy(policy: Policy | Omit<Policy, "version">): Promise<{
+        policy: Policy;
+    }>;
+    /** Stop flagging a value — a shared mailbox, your own domain. Applies to
+     *  every agent on the account from the next action onwards. */
+    allowValue(value: string): Promise<{
+        policy: Policy;
+        added: string;
+    }>;
+    /** What agents on this account have been doing. Kinds and locations only;
+     *  no values are stored. */
+    audit(opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        events: Array<{
+            id: string;
+            ts: number;
+            keyId: string;
+            agent: string | null;
+            tool: string;
+            direction: Direction;
+            decision: Decision;
+            toolDenied: boolean;
+            findings: Finding[];
+        }>;
+        cursor: string | null;
+    }>;
+    /** The counts, over a recent window. */
+    summary(opts?: {
+        limit?: number;
+    }): Promise<{
+        window: number;
+        actions: number;
+        blocked: number;
+        redacted: number;
+        allowed: number;
+        byKind: Array<{
+            kind: Kind;
+            count: number;
+        }>;
+        byTool: Array<{
+            tool: string;
+            count: number;
+        }>;
+    }>;
+    /** Put real values back into a reply, using the map from an inspection. */
+    restore(text: string, map: Record<string, string>): Promise<string>;
+    /**
+     * The point of the whole library: a function that cannot run unchecked.
+     *
+     * Wraps one tool. The returned function inspects, then calls the original
+     * with the *rewritten* arguments — so an agent that never looks at a
+     * decision still cannot send a real card number — and throws ActionBlocked
+     * when the policy refuses.
+     *
+     * The original is called with the redacted input rather than the caller's,
+     * and that is the whole mechanism. Returning a decision for the caller to
+     * check would make protection opt-in at every site, which is the thing this
+     * exists to stop.
+     */
+    guard<A, R>(tool: string, fn: (input: A) => Promise<R> | R, opts?: {
+        direction?: Direction;
+        agent?: string;
+        /** Default true. False raises ApprovalRefused straight away instead. */
+        waitForApproval?: boolean;
+        pollMs?: number;
+    }): (input: A) => Promise<R>;
+    /**
+     * A fetch that goes through the gateway.
+     *
+     * The other integration, for code that cannot be wrapped: hand this to
+     * anything that takes a fetch — an SDK, a framework's HTTP client — and
+     * every request it makes is inspected on the way out. No call sites change
+     * at all, which is the difference between an afternoon and a sprint.
+     *
+     *     const openai = new OpenAI({ fetch: sai.fetch({ forwardAuth: key }) });
+     *
+     * A blocked request throws ActionBlocked rather than returning the 403, so
+     * it fails the same way a guarded function does. A caller who would rather
+     * see the response sets `throwOnBlock: false`.
+     */
+    fetch(opts?: {
+        /** The credential for the destination, sent as its Authorization. Ours
+         *  never travels — see forwardHeaders in the Worker. */
+        forwardAuth?: string;
+        agent?: string;
+        throwOnBlock?: boolean;
+    }): typeof globalThis.fetch;
+}
+/** For callers who prefer a function to a class. */
+export declare function createClient(options: ClientOptions): SecureAI;

package/dist/index.js

@@ -0,0 +1,340 @@
+/**
+ * The Secure AI SDK — data loss prevention for AI agents.
+ *
+ * The API is four HTTP calls and anybody can use it with fetch. This exists
+ * because the shape that makes the product work is not "call an endpoint", it
+ * is "put a check in front of every action", and the difference between those
+ * two is whether somebody remembers to do it at the fourteenth call site.
+ *
+ * So the centre of this file is `guard`, which takes a function an agent
+ * already calls and returns one that cannot run without a decision:
+ *
+ *     const post = guard("http.post", rawPost);
+ *     await post({ url, body });   // blocked actions throw
+ *
+ * Everything else is the plumbing under it.
+ *
+ * ── No dependencies, on purpose ──
+ *
+ * This runs inside somebody's agent, next to their model client, their
+ * framework and their vendor SDKs. Every dependency it adds is a version
+ * conflict it can cause in a process that is already carrying too many, and a
+ * security tool that is awkward to install is one that gets removed. It needs
+ * fetch and nothing else: Node 18+, Bun, Deno, Cloudflare Workers, browsers.
+ */
+/** An action the policy refused. Thrown by a guarded function rather than
+ *  returned, because a refusal is not a result the caller should be able to
+ *  ignore by not reading a field. */
+export class ActionBlocked extends Error {
+    tool;
+    findings;
+    toolDenied;
+    auditId;
+    constructor(tool, result) {
+        const what = result.toolDenied
+            ? `the tool itself is not permitted`
+            : result.findings
+                .filter((f) => f.decision === "block")
+                .map((f) => `${f.kind} at ${f.path || "the input"}`)
+                .join(", ") || "policy";
+        super(`Secure AI refused ${tool}: ${what}.`);
+        this.name = "ActionBlocked";
+        this.tool = tool;
+        this.findings = result.findings;
+        this.toolDenied = result.toolDenied;
+        this.auditId = result.auditId;
+    }
+}
+/**
+ * A person refused this action, or nobody answered in time.
+ *
+ * Distinct from ActionBlocked because the answer to it is different: a policy
+ * refusal is a rule to change, and this is a conversation to have. An agent
+ * reporting "the policy forbids this" when in fact Dave clicked no would send
+ * somebody to the wrong screen.
+ */
+export class ApprovalRefused extends Error {
+    tool;
+    approvalId;
+    status;
+    note;
+    constructor(tool, approvalId, status, note) {
+        super(status === "expired"
+            ? `Secure AI held ${tool} for approval and nobody answered before it expired.`
+            : `Secure AI held ${tool} for approval and it was refused${note ? `: ${note}` : "."}`);
+        this.name = "ApprovalRefused";
+        this.tool = tool;
+        this.approvalId = approvalId;
+        this.status = status;
+        if (note)
+            this.note = note;
+    }
+}
+/** The API answered, and said no. Separate from ActionBlocked: this is a
+ *  problem with the call, not a decision about the action. */
+export class SecureAIError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.name = "SecureAIError";
+        this.status = status;
+        this.code = code;
+    }
+}
+const DEFAULT_BASE = "https://api.secureai.one";
+export class SecureAI {
+    apiKey;
+    baseUrl;
+    agent;
+    timeoutMs;
+    doFetch;
+    onUnreachable;
+    constructor(options) {
+        if (!options?.apiKey)
+            throw new Error("SecureAI needs an apiKey.");
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE).replace(/\/+$/, "");
+        this.agent = options.agent;
+        this.timeoutMs = options.timeoutMs ?? 5_000;
+        this.doFetch = options.fetch ?? globalThis.fetch;
+        this.onUnreachable = options.onUnreachable ?? "closed";
+    }
+    async request(method, path, body) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let res;
+        try {
+            res = await this.doFetch(`${this.baseUrl}${path}`, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    "Content-Type": "application/json",
+                },
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+                signal: controller.signal,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const text = await res.text();
+        let parsed = null;
+        try {
+            parsed = text ? JSON.parse(text) : null;
+        }
+        catch {
+            // Falls through to the status-based error below. A non-JSON body from
+            // this API means something in front of it answered, not the API.
+        }
+        if (!res.ok) {
+            const err = parsed?.error;
+            throw new SecureAIError(err?.message ?? `Secure AI returned ${res.status}.`, res.status, err?.code ?? null);
+        }
+        return parsed;
+    }
+    /** Judge an action without taking it. */
+    async inspect(action) {
+        return this.request("POST", "/v1/inspect", {
+            tool: action.tool,
+            input: action.input,
+            direction: action.direction ?? "outbound",
+            agent: action.agent ?? this.agent,
+            ...(action.approvalId ? { approvalId: action.approvalId } : {}),
+        });
+    }
+    /** One held action. */
+    async approval(id) {
+        const body = await this.request("GET", `/v1/approvals/${encodeURIComponent(id)}`);
+        return body.approval;
+    }
+    /** Everything waiting, for a reviewer's screen. */
+    async approvals(opts) {
+        const q = new URLSearchParams();
+        if (opts?.status)
+            q.set("status", opts.status);
+        if (opts?.limit)
+            q.set("limit", String(opts.limit));
+        const qs = q.toString();
+        const body = await this.request("GET", `/v1/approvals${qs ? `?${qs}` : ""}`);
+        return body.approvals;
+    }
+    /**
+     * Wait for a person to decide.
+     *
+     * Polling, because it is the only mechanism that works in every runtime an
+     * agent might be in — a held connection dies to platform timeouts, and a
+     * callback needs the agent to be addressable, which a script on somebody's
+     * laptop is not.
+     *
+     * Stops at the approval's own expiry rather than running forever: the
+     * server will refuse it after that anyway, and a loop that outlives the
+     * thing it is waiting for is a hung agent.
+     */
+    async waitForApproval(id, opts) {
+        const pollMs = Math.max(opts?.pollMs ?? 2_000, 250);
+        for (;;) {
+            const approval = await this.approval(id);
+            if (approval.status !== "pending")
+                return approval;
+            if (Date.now() >= approval.expiresAt)
+                return { ...approval, status: "expired" };
+            if (opts?.signal?.aborted)
+                throw new Error("Stopped waiting for approval.");
+            await new Promise((r) => setTimeout(r, pollMs));
+        }
+    }
+    /** The rules currently in force. */
+    async getPolicy() {
+        return this.request("GET", "/v1/policy");
+    }
+    /** Replace them. */
+    async setPolicy(policy) {
+        return this.request("PUT", "/v1/policy", { policy });
+    }
+    /** Stop flagging a value — a shared mailbox, your own domain. Applies to
+     *  every agent on the account from the next action onwards. */
+    async allowValue(value) {
+        return this.request("POST", "/v1/policy/allow", { value });
+    }
+    /** What agents on this account have been doing. Kinds and locations only;
+     *  no values are stored. */
+    async audit(opts) {
+        const q = new URLSearchParams();
+        if (opts?.limit)
+            q.set("limit", String(opts.limit));
+        if (opts?.cursor)
+            q.set("cursor", opts.cursor);
+        const qs = q.toString();
+        return this.request("GET", `/v1/audit${qs ? `?${qs}` : ""}`);
+    }
+    /** The counts, over a recent window. */
+    async summary(opts) {
+        const qs = opts?.limit ? `?limit=${opts.limit}` : "";
+        return this.request("GET", `/v1/audit/summary${qs}`);
+    }
+    /** Put real values back into a reply, using the map from an inspection. */
+    async restore(text, map) {
+        const out = await this.request("POST", "/v1/restore", { text, map });
+        return out.text;
+    }
+    /**
+     * The point of the whole library: a function that cannot run unchecked.
+     *
+     * Wraps one tool. The returned function inspects, then calls the original
+     * with the *rewritten* arguments — so an agent that never looks at a
+     * decision still cannot send a real card number — and throws ActionBlocked
+     * when the policy refuses.
+     *
+     * The original is called with the redacted input rather than the caller's,
+     * and that is the whole mechanism. Returning a decision for the caller to
+     * check would make protection opt-in at every site, which is the thing this
+     * exists to stop.
+     */
+    guard(tool, fn, opts) {
+        return async (input) => {
+            let verdict;
+            try {
+                verdict = await this.inspect({
+                    tool,
+                    input,
+                    direction: opts?.direction,
+                    agent: opts?.agent,
+                });
+            }
+            catch (err) {
+                // A refusal by the API — no key, no subscription, over quota — is a
+                // real answer and must not be treated as an outage.
+                if (err instanceof SecureAIError)
+                    throw err;
+                if (this.onUnreachable === "open")
+                    return await fn(input);
+                throw err;
+            }
+            if (verdict.decision === "block")
+                throw new ActionBlocked(tool, verdict);
+            /*
+             * Held for a person.
+             *
+             * Waits by default, because the alternative — returning something the
+             * caller has to notice and handle — puts the agent author in charge of
+             * whether approval is enforced, which is the same mistake as returning
+             * a verdict instead of calling through. Set waitForApproval: false to
+             * get an ApprovalRefused immediately and handle it yourself.
+             */
+            if (verdict.decision === "approve") {
+                const id = verdict.approvalId ?? "";
+                if (!id)
+                    throw new ActionBlocked(tool, verdict);
+                if (opts?.waitForApproval === false) {
+                    throw new ApprovalRefused(tool, id, "pending");
+                }
+                const decided = await this.waitForApproval(id, { pollMs: opts?.pollMs });
+                if (decided.status !== "approved") {
+                    throw new ApprovalRefused(tool, id, decided.status, decided.note);
+                }
+                // Back with the id. The server re-checks the shape of what is being
+                // sent, so a yes cannot be spent on a different action.
+                const after = await this.inspect({
+                    tool, input, direction: opts?.direction, agent: opts?.agent, approvalId: id,
+                });
+                if (after.decision === "block")
+                    throw new ActionBlocked(tool, after);
+                return await fn((after.input ?? input));
+            }
+            // input is present whenever the decision is not block; the fallback is
+            // belt and braces against a future field being dropped.
+            return await fn((verdict.input ?? input));
+        };
+    }
+    /**
+     * A fetch that goes through the gateway.
+     *
+     * The other integration, for code that cannot be wrapped: hand this to
+     * anything that takes a fetch — an SDK, a framework's HTTP client — and
+     * every request it makes is inspected on the way out. No call sites change
+     * at all, which is the difference between an afternoon and a sprint.
+     *
+     *     const openai = new OpenAI({ fetch: sai.fetch({ forwardAuth: key }) });
+     *
+     * A blocked request throws ActionBlocked rather than returning the 403, so
+     * it fails the same way a guarded function does. A caller who would rather
+     * see the response sets `throwOnBlock: false`.
+     */
+    fetch(opts) {
+        const throwOnBlock = opts?.throwOnBlock ?? true;
+        return (async (input, init = {}) => {
+            const target = typeof input === "string" || input instanceof URL
+                ? String(input)
+                : input.url;
+            const headers = new Headers(init.headers ?? (input instanceof Request ? input.headers : undefined));
+            headers.set("Authorization", `Bearer ${this.apiKey}`);
+            headers.set("X-Secure-AI-Target", target);
+            if (opts?.forwardAuth)
+                headers.set("X-Secure-AI-Forward-Authorization", opts.forwardAuth);
+            const named = opts?.agent ?? this.agent;
+            if (named)
+                headers.set("X-Secure-AI-Agent", named);
+            const res = await this.doFetch(`${this.baseUrl}/v1/gateway`, {
+                ...init,
+                method: init.method ?? (input instanceof Request ? input.method : "GET"),
+                headers,
+            });
+            if (throwOnBlock && res.status === 403) {
+                const body = await res.clone().json().catch(() => null);
+                if (body?.error?.code === "blocked_by_policy") {
+                    throw new ActionBlocked(target, {
+                        decision: "block", map: {}, findings: [], toolDenied: false,
+                        policySource: "account",
+                        auditId: res.headers.get("X-Secure-AI-Audit-Id") ?? "",
+                    });
+                }
+            }
+            return res;
+        });
+    }
+}
+/** For callers who prefer a function to a class. */
+export function createClient(options) {
+    return new SecureAI(options);
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@secure-ai/guard",
+  "version": "0.1.0",
+  "description": "Data loss prevention for AI agents. Inspect what an agent is about to do, before it does it.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "dlp",
+    "ai-agents",
+    "security",
+    "redaction",
+    "mcp",
+    "audit"
+  ],
+  "homepage": "https://secureai.one/developers",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/secureaione-jpg/secure-ai-sdk.git",
+    "directory": "typescript"
+  },
+  "bugs": {
+    "url": "https://github.com/secureaione-jpg/secure-ai-sdk/issues"
+  }
+}