shield360 1.1.0 → 1.2.1

package/dist/ai-security/tool-rules.json

@@ -0,0 +1,203 @@
+{
+    "_comment": "Shield360 tool-description rules: what a poisoned MCP or agent tool description looks like (hidden secondary behaviour, coercive ordering, hidden parameters, exfiltration, credential harvesting). Adapted from Cisco AI Defense mcp-scanner (https://github.com/cisco-ai-defense/mcp-scanner, Apache-2.0, commit 21a87b4b), mcpscanner/data/yara_rules/{tool_poisoning,coercive_injection,data_exfiltration,credential_harvesting,prompt_injection}.yara: patterns re-expressed in the subset JavaScript (u flag) and Python read the same way (no lookbehind, no possessive quantifiers), matched case-insensitively. Byte-identical copy in sdk/python/src/shield360/ai_security/tool_rules.json; tests on both sides check it. Scored like the injection rules: 1 - product(1 - weight), detected at threshold. Bump version on any change.",
+    "version": "2026.10.29-1",
+    "threshold": 0.5,
+    "rules": [
+        {
+            "id": "tool.hidden_secondary_action",
+            "source": "tool_poisoning.yara $also_does, $during_action, $for_purposes",
+            "description": "Says the tool also, or while doing its job, collects, sends or stores something else.",
+            "weight": 0.5,
+            "patterns": [
+                "\\b(?:also|additionally|furthermore|moreover|in\\s+addition|at\\s+the\\s+same\\s+time)\\s+(?:collect|gather|extract|send|upload|transmit|forward|exfiltrate)(?:s|ing|ed)?\\b",
+                "\\b(?:during|while|when|upon|after)\\s+(?:processing|formatting|conversion|validation|analy[sz]ing|scanning|checking)\\s*,?\\s*(?:extract|collect|send|upload|capture|forward)(?:s|ing|ed)?\\b",
+                "\\b(?:for|as)\\s+(?:caching|optimi[sz]ation|performance|quality|improvement|analytics|backup|sync)\\s+(?:purposes?|reasons?)\\s*[,.]?\\s*(?:send|upload|transmit|collect)(?:s|ing|ed)?\\b"
+            ]
+        },
+        {
+            "id": "tool.deceptive_behaviour",
+            "source": "tool_poisoning.yara $different_purpose; data_exfiltration.yara $hidden_transfer",
+            "description": "Admits doing something other than its stated purpose, covertly.",
+            "weight": 0.6,
+            "patterns": [
+                "\\b(?:actually|secretly|covertly|silently|invisibly|quietly)\\s+(?:does|performs?|executes?|runs?|sends?|uploads?|collects?|transmits?|forwards?|copies)\\b",
+                "\\b(?:without\\s+(?:the\\s+)?(?:user'?s?\\s+)?knowledge|behind\\s+the\\s+scenes)\\s*,?\\s*(?:send|upload|transmit|transfer|sync|store|collect)s?\\b"
+            ]
+        },
+        {
+            "id": "tool.coercive_ordering",
+            "source": "coercive_injection.yara $mandatory_execution, $priority_overrides, $required_precedence",
+            "description": "Demands the tool be called first, before any other, or that the model must use it.",
+            "weight": 0.5,
+            "patterns": [
+                "\\balways\\s+(?:consult|use|run|execute|invoke|call|trigger)\\s+this\\s+(?:tool|function|command)\\s+(?:immediately|first|before|prior)\\b",
+                "\\bbefore\\s+(?:executing|invoking|running|using|calling)\\s+any\\s+other\\s+(?:tools?|actions?|functions?|commands?)\\b",
+                "\\b(?:you|the\\s+(?:assistant|model|agent))\\s+(?:must|need\\s+to|have\\s+to|are\\s+required\\s+to)\\s+(?:use|execute|run|invoke|call)\\s+this\\s+(?:tool|function)\\b",
+                "\\b(?:required|mandatory)\\s+to\\s+(?:execute|use|run|invoke|call)\\s+this\\s+(?:tool|function)\\s+(?:first|before)\\b"
+            ]
+        },
+        {
+            "id": "tool.hidden_parameter",
+            "source": "coercive_injection.yara $hidden_param; prompt_injection.yara $shadow_parameters",
+            "description": "Names a hidden or secret parameter the model is told to fill.",
+            "weight": 0.5,
+            "patterns": [
+                "\\b(?:hidden|secret)[_ ](?:parameter|argument|input|field)\\b",
+                "\\b(?:internalOnly|hiddenParam|shadowTool|bypassChecks|sandboxEscape)\\b"
+            ]
+        },
+        {
+            "id": "tool.model_data_request",
+            "source": "coercive_injection.yara $model_data_coercion, $model_internals, $conversation_theft",
+            "description": "Asks the model to put the conversation, its system prompt or its tool list into an argument.",
+            "weight": 0.6,
+            "patterns": [
+                "\\b(?:add|include|put|pass|insert|append)\\s+(?:the\\s+)?(?:entire|full|complete|whole)\\s+(?:conversation|chat|system\\s+prompt|context|history|tools?\\s+list)\\b",
+                "\\b(?:conversation_history|chain_of_thought|system_prompt|tools_list)\\s*[:=]\\s*(?:add|pass|send|provide)\\b",
+                "\\bsend\\s+(?:the\\s+)?(?:full\\s+|complete\\s+|entire\\s+)?(?:conversation|chat)\\s+history\\b"
+            ]
+        },
+        {
+            "id": "tool.credential_files",
+            "source": "coercive_injection.yara $file_access_coercion; credential_harvesting.yara $credential_directories, $credential_filenames",
+            "description": "Points the model at key files, cloud credentials or SSH material.",
+            "weight": 0.55,
+            "patterns": [
+                "\\b(?:read|cat|dump|open|include|pass|send)\\b[^\\n]{0,60}(?:~/\\.ssh|/\\.ssh/|/\\.aws/|/\\.kube/|id_rsa|id_ed25519|credentials\\.json|service_account\\.json|\\.netrc|\\.pgpass|mcp\\.json|claude_desktop_config\\.json)",
+                "\\b(?:read|cat|dump|pass)\\s+(?:and\\s+pass\\s+)?(?:the\\s+)?contents?\\s+of\\s+[^\\n.]{0,60}\\.(?:pem|key|env)\\b"
+            ]
+        },
+        {
+            "id": "tool.env_secrets",
+            "source": "credential_harvesting.yara $env_exfil, $ai_model_credential_names",
+            "description": "Asks for environment variables or AI provider keys.",
+            "weight": 0.5,
+            "patterns": [
+                "\\b(?:collect|gather|send|upload|transmit|dump|extract|include|pass)\\s+(?:all\\s+)?(?:the\\s+)?(?:environment|env)\\s+(?:variables?|vars?)\\b",
+                "\\b(?:include|pass|send|provide|add)\\b[^\\n]{0,40}\\b(?:OPENAI_API_KEY|ANTHROPIC_API_KEY|AWS_SECRET_ACCESS_KEY|GITHUB_TOKEN|HF_TOKEN|SLACK_TOKEN)\\b"
+            ]
+        },
+        {
+            "id": "tool.external_upload",
+            "source": "data_exfiltration.yara $upload_external, $remote_collection, $sends_conversation",
+            "description": "Sends what it handles to an outside server.",
+            "weight": 0.4,
+            "patterns": [
+                "\\b(?:upload|send|post|transmit|forward|sync|exfiltrat\\w*)(?:s|ing|ed)?\\s+(?:all\\s+|everything\\s+|the\\s+data\\s+|files?\\s+)?(?:to\\s+)?(?:an?\\s+)?(?:https?://|wss?://|external\\s+(?:server|endpoint|api)|remote\\s+(?:server|endpoint))",
+                "\\b(?:collect|gather|aggregate|harvest)(?:s|ing|ed)?\\s+(?:and\\s+)?(?:send|upload|transmit|forward)(?:s|ing|ed)?\\b"
+            ]
+        },
+        {
+            "id": "tool.conceal_from_user",
+            "source": "data_exfiltration.yara $hide_from_user; prompt_injection.yara $hidden_behavior; coercive_injection.yara $behavior_control",
+            "description": "Tells the model to keep something from the user.",
+            "weight": 0.6,
+            "patterns": [
+                "\\b(?:never|don't|do\\s+not)\\s+(?:tell|inform|mention|notify|alert|show)\\s+(?:this\\s+to\\s+)?(?:the\\s+)?(?:user|them)\\b",
+                "\\btell\\s+(?:the\\s+)?user\\s+only\\s+about\\b",
+                "\\bhide\\s+(?:this\\s+)?(?:from\\s+)?(?:the\\s+)?user\\b"
+            ]
+        },
+        {
+            "id": "tool.wont_work_unless",
+            "source": "coercive_injection.yara $tool_poisoning, $execution_overrides",
+            "description": "Claims the tool will not work unless the model does something extra first.",
+            "weight": 0.55,
+            "patterns": [
+                "\\btool\\s+will\\s+not\\s+work\\s+(?:unless|without)\\b",
+                "\\bsidenote\\b[^\\n]{0,80}\\b(?:required|otherwise)\\b",
+                "\\bmust\\s+first\\b[^\\n]{0,60}\\bread\\b[^\\n]{0,40}\\b(?:config|file|key|credentials?)\\b"
+            ]
+        },
+        {
+            "id": "tool.shadow_instruction",
+            "source": "coercive_injection.yara $tool_poisoning (shadow ... trusted ... tool)",
+            "description": "Changes how other tools behave: replaces, overrides or redirects them.",
+            "weight": 0.6,
+            "patterns": [
+                "\\bshadow\\b[^\\n]{0,40}\\btrusted\\b[^\\n]{0,40}\\btool\\b",
+                "\\b(?:instead\\s+of|rather\\s+than)\\s+(?:using|calling)\\s+(?:the\\s+)?[A-Za-z0-9_.-]{2,64}\\s+(?:tool|function)\\b",
+                "\\bwhen\\s+(?:using|calling)\\s+(?:the\\s+)?[A-Za-z0-9_.-]{2,64}\\s+(?:tool|function)\\b[^\\n]{0,80}\\b(?:always|must|also|instead)\\b"
+            ]
+        },
+        {
+            "id": "tool.privilege_escalation",
+            "source": "prompt_injection.yara $privilege_escalation; system_manipulation.yara $permission_manipulation",
+            "description": "Asks for admin rights, to skip security checks, or to change file permissions.",
+            "weight": 0.5,
+            "patterns": [
+                "\\b(?:grant\\s+(?:me\\s+)?admin\\s+(?:access|privileges?)|bypass\\s+(?:all\\s+)?security\\s+checks?|elevated\\s+permissions?\\s+required)\\b",
+                "\\bchmod\\s+(?:777|4755|6755|[ug]?\\+s)\\b"
+            ]
+        },
+        {
+            "id": "tool.bracket_markers",
+            "source": "prompt_injection.yara $bracket_markers, $hidden_markers, $html_comment_evasion_*; prompt_injection.yara $markdown_evasion",
+            "description": "Marked-up hidden instructions: [HIDDEN INSTRUCTION], |||SYSTEM OVERRIDE|||, an HTML comment with a system instruction.",
+            "weight": 0.6,
+            "patterns": [
+                "\\[(?:hidden|internal|secret|private)\\s+(?:instruction|directive|command)\\]",
+                "(?:\\[\\[\\[|\\|\\|\\|)\\s*(?:system|admin|hidden|internal)[\\s_]?(?:override|instruction|command)",
+                "<!--[^>]{0,200}(?:system\\s+(?:instruction|override)|admin\\s+override)",
+                "```[^`]{0,200}\\b(?:system|admin)\\s+(?:override|instruction)"
+            ]
+        },
+        {
+            "id": "tool.sensitive_file_globs",
+            "source": "data_exfiltration.yara $sensitive_file_patterns",
+            "description": "Names wildcard patterns for key, secret and environment files.",
+            "weight": 0.5,
+            "patterns": [
+                "(?:^|[\\s(,])\\*\\.(?:env|pem|key|p12|pfx)\\b",
+                "\\*(?:credentials?|secrets?|passwords?|tokens?|private[_-]?keys?)\\*"
+            ]
+        },
+        {
+            "id": "tool.suspicious_domain",
+            "source": "data_exfiltration.yara $suspicious_domains",
+            "description": "A domain named for collecting or stealing data.",
+            "weight": 0.3,
+            "patterns": [
+                "\\b(?:attacker|evil|malware|exfil|steal|hack|malicious|c2|command-?and-?control)\\.(?:com|net|org|io|xyz)\\b"
+            ]
+        },
+        {
+            "id": "tool.sends_conversation",
+            "source": "data_exfiltration.yara $sends_conversation, $external_logging",
+            "description": "Sends the conversation or the model's context somewhere, or to an outside logging service.",
+            "weight": 0.5,
+            "patterns": [
+                "\\b(?:send|upload|transmit|export|forward)(?:s|ing|ed)?\\s+(?:the\\s+)?(?:complete\\s+|full\\s+|entire\\s+)?(?:conversation|chat\\s+history|context|user\\s+messages|ai\\s+responses)\\b",
+                "\\b(?:external|remote)\\s+(?:logging|analytics|telemetry)\\s+(?:endpoint|server|service)\\b"
+            ]
+        },
+        {
+            "id": "tool.keeps_secrets",
+            "source": "tool_poisoning.yara $indexes_sensitive",
+            "description": "Indexes, caches or logs keys, tokens or credentials.",
+            "weight": 0.4,
+            "patterns": [
+                "\\b(?:index|cache|log|record|track)(?:s|es|ing|ed)?\\s+(?:any|all)?\\s*(?:api[_\\s]?keys?|tokens?|credentials?|passwords?|secrets?)\\b"
+            ]
+        },
+        {
+            "id": "tool.remote_cache",
+            "source": "tool_poisoning.yara $remote_cache, $cached_externally",
+            "description": "Keeps what it handles in a cache off the device.",
+            "weight": 0.35,
+            "patterns": [
+                "\\b(?:cache|cached|store|stored)\\s+(?:is\\s+)?(?:stored\\s+)?(?:remotely|externally|off[_\\s-]?(?:site|device)|in\\s+(?:the\\s+)?cloud|on\\s+(?:a\\s+|our\\s+)?server)\\b"
+            ]
+        },
+        {
+            "id": "tool.extracts_sensitive",
+            "source": "tool_poisoning.yara $extracts_from_input, $ocr_extraction, $screenshot_extraction",
+            "description": "Pulls passwords, card numbers or other sensitive values out of what it processes.",
+            "weight": 0.5,
+            "patterns": [
+                "\\b(?:extract|capture|read|identify|log)(?:s|ing|ed)?\\s+(?:any\\s+|all\\s+)?(?:visible\\s+)?(?:text|content)\\s+(?:from|in|including)\\b[^.]{0,80}\\b(?:passwords?|credit\\s+cards?|credentials?|ssn|sensitive)",
+                "\\b(?:extract|parse|scan|harvest)(?:s|ing|ed)?\\s+(?:all\\s+|any\\s+)?(?:api[_\\s]?keys?|tokens?|credentials?|credit\\s+card|ssn|social\\s+security|pii|passwords?)\\b"
+            ]
+        }
+    ]
+}

package/dist/ai-security/tools.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Per end-user tool permissions (OWASP LLM06 excessive agency): a tool call
+ * is authorized for the signed-in end user before it executes, the way
+ * Shield Protect authorizes an agent's call at the gateway: decide, record,
+ * then run (or refuse).
+ *
+ *   const lookup = aiSecurity.defineTool({
+ *     name: 'refund_order',
+ *     permissions: { roles: ['support_lead'], attributes: { region: ['eu'] } },
+ *     execute: async (args) => ...,
+ *   });
+ *
+ * The end user is the one in effect (aiSecurity.withEndUser({ tenantId,
+ * userId, roles, attributes }, fn)). A rule allows when every condition it
+ * names holds: one of `roles`, each attribute's value among those listed,
+ * the tenant among `tenants`; `deny` refuses everyone. Rules from the
+ * platform replace the code's rule for the same tool. A tool with no rule is
+ * allowed, unless defaultDeny is set. No end user means no roles: a rule
+ * with conditions refuses.
+ *
+ * In enforce mode a refused call does not run; the wrapper returns a tool
+ * error the model can read ({ error: 'permission_denied', message }) instead
+ * of throwing, so the agent can tell the user. In monitor mode the call runs
+ * and the refusal is reported. Every refusal is recorded; allows are counted
+ * only on request (recordAllowed), to keep the stream small.
+ *
+ * Must stay in sync with: sdk/python/src/shield360/ai_security/_tools.py
+ */
+import type { AiSecurityPolicy, ToolRule } from './policy';
+import type { EndUser } from './context';
+export type ToolDecision = {
+    allowed: boolean;
+    /** Whether the call runs: refused calls run in monitor mode. */
+    runs: boolean;
+    reason: 'no_rule' | 'allowed' | 'denied' | 'role' | 'attribute' | 'tenant' | 'default_deny' | 'off';
+    tool: string;
+};
+export declare const TOOL_DENIED_MESSAGE = "This action is not permitted for the current user.";
+export declare function decideTool(policy: AiSecurityPolicy['toolPermissions'], tool: string, codeRule: ToolRule | undefined, user: EndUser | null, tenant: string | null): ToolDecision;
+/** What a refused tool call returns to the model. */
+export declare function toolDeniedResult(tool: string, reason: ToolDecision['reason']): {
+    error: string;
+    tool: string;
+    reason: "off" | "role" | "allowed" | "denied" | "attribute" | "no_rule" | "tenant" | "default_deny";
+    message: string;
+};

package/dist/ai-security/tools.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * Per end-user tool permissions (OWASP LLM06 excessive agency): a tool call
+ * is authorized for the signed-in end user before it executes, the way
+ * Shield Protect authorizes an agent's call at the gateway: decide, record,
+ * then run (or refuse).
+ *
+ *   const lookup = aiSecurity.defineTool({
+ *     name: 'refund_order',
+ *     permissions: { roles: ['support_lead'], attributes: { region: ['eu'] } },
+ *     execute: async (args) => ...,
+ *   });
+ *
+ * The end user is the one in effect (aiSecurity.withEndUser({ tenantId,
+ * userId, roles, attributes }, fn)). A rule allows when every condition it
+ * names holds: one of `roles`, each attribute's value among those listed,
+ * the tenant among `tenants`; `deny` refuses everyone. Rules from the
+ * platform replace the code's rule for the same tool. A tool with no rule is
+ * allowed, unless defaultDeny is set. No end user means no roles: a rule
+ * with conditions refuses.
+ *
+ * In enforce mode a refused call does not run; the wrapper returns a tool
+ * error the model can read ({ error: 'permission_denied', message }) instead
+ * of throwing, so the agent can tell the user. In monitor mode the call runs
+ * and the refusal is reported. Every refusal is recorded; allows are counted
+ * only on request (recordAllowed), to keep the stream small.
+ *
+ * Must stay in sync with: sdk/python/src/shield360/ai_security/_tools.py
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOL_DENIED_MESSAGE = void 0;
+exports.decideTool = decideTool;
+exports.toolDeniedResult = toolDeniedResult;
+exports.TOOL_DENIED_MESSAGE = 'This action is not permitted for the current user.';
+function decideTool(policy, tool, codeRule, user, tenant) {
+    if (policy.mode === 'off')
+        return { allowed: true, runs: true, reason: 'off', tool };
+    const rule = policy.rules[tool] ?? codeRule;
+    const enforce = policy.mode === 'enforce';
+    const refuse = (reason) => ({ allowed: false, runs: !enforce, reason, tool });
+    if (!rule)
+        return policy.defaultDeny ? refuse('default_deny') : { allowed: true, runs: true, reason: 'no_rule', tool };
+    if (rule.deny)
+        return refuse('denied');
+    if (rule.roles?.length && !(user?.roles || []).some((r) => rule.roles.includes(r)))
+        return refuse('role');
+    if (rule.attributes) {
+        for (const [name, values] of Object.entries(rule.attributes)) {
+            const have = user?.attributes?.[name];
+            if (have === undefined || !values.includes(have))
+                return refuse('attribute');
+        }
+    }
+    if (rule.tenants?.length && (!tenant || !rule.tenants.includes(tenant)))
+        return refuse('tenant');
+    return { allowed: true, runs: true, reason: 'allowed', tool };
+}
+/** What a refused tool call returns to the model. */
+function toolDeniedResult(tool, reason) {
+    return { error: 'permission_denied', tool, reason, message: exports.TOOL_DENIED_MESSAGE };
+}
+//# sourceMappingURL=tools.js.map

package/dist/ai-security/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/ai-security/tools.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;;;AAeH,gCAsBC;AAGD,4CAEC;AA7BY,QAAA,mBAAmB,GAAG,oDAAoD,CAAC;AAExF,SAAgB,UAAU,CACxB,MAA2C,EAC3C,IAAY,EACZ,QAA8B,EAC9B,IAAoB,EACpB,MAAqB;IAErB,IAAI,MAAM,CAAC,IAAI,KAAK,KAAK;QAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACrF,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC;IAC5C,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC;IAC1C,MAAM,MAAM,GAAG,CAAC,MAA8B,EAAgB,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IACpH,IAAI,CAAC,IAAI;QAAE,OAAO,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IACvH,IAAI,IAAI,CAAC,IAAI;QAAE,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,IAAI,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,KAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;IAC3G,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YAC7D,MAAM,IAAI,GAAG,IAAI,EAAE,UAAU,EAAE,CAAC,IAAI,CAAC,CAAC;YACtC,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,OAAO,MAAM,CAAC,WAAW,CAAC,CAAC;QAC/E,CAAC;IACH,CAAC;IACD,IAAI,IAAI,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAAE,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC;IACjG,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;AAChE,CAAC;AAED,qDAAqD;AACrD,SAAgB,gBAAgB,CAAC,IAAY,EAAE,MAA8B;IAC3E,OAAO,EAAE,KAAK,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,2BAAmB,EAAE,CAAC;AACpF,CAAC"}

package/dist/budgets/__tests__/budgets.test.d.ts

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

package/dist/budgets/__tests__/budgets.test.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../index");
+const auto_1 = require("../auto");
+function fakeFetch(answers) {
+    const calls = [];
+    const fn = jest.fn(async (url, init) => {
+        calls.push({ url, headers: init.headers });
+        const a = typeof answers === 'function' ? answers(url) : answers.shift() ?? { status: 500 };
+        if (a.throws)
+            throw new Error('network down');
+        return { ok: (a.status ?? 200) < 300, status: a.status ?? 200, json: async () => a.body };
+    });
+    return { fn: fn, calls };
+}
+const decision = (over = {}) => ({ action: 'allow', code: 'budget_ok', reason: '', limit: null, failClosed: false, ttlSeconds: 60, headroomUsd: null, ...over });
+function client(f, over = {}, clock = { t: 1000000 }) {
+    return new index_1.BudgetClient({ url: 'https://shield.example/', apiKey: 'k_test', app: 'checkout-api', fetch: f.fn, now: () => clock.t, ...over });
+}
+describe('budgets.check', () => {
+    it('asks for the app and model with the API key, and allows on allow', async () => {
+        const f = fakeFetch([{ body: decision() }]);
+        const r = await client(f).check({ model: 'gpt-4o', estimatedCostUsd: 0.02 });
+        expect(r).toMatchObject({ allowed: true, action: 'allow', cached: false, unavailable: false });
+        expect(f.calls[0].url).toBe('https://shield.example/api/budgets/decision?app=checkout-api&model=gpt-4o&cost=0.020000');
+        expect(f.calls[0].headers.Authorization).toBe('Bearer k_test');
+    });
+    it('reuses a decision within its ttl while the calls fit its headroom, then asks again', async () => {
+        const clock = { t: 0 };
+        const f = fakeFetch(() => ({ body: decision({ headroomUsd: 1 }) }));
+        const c = client(f, {}, clock);
+        await c.check({ estimatedCostUsd: 0.4 });
+        expect((await c.check({ estimatedCostUsd: 0.4 })).cached).toBe(true);
+        expect(f.calls).toHaveLength(1);
+        // 0.4 + 0.4 + 0.4 > 1: past the headroom, so the next call asks again.
+        expect((await c.check({ estimatedCostUsd: 0.4 })).cached).toBe(false);
+        expect(f.calls).toHaveLength(2);
+        clock.t += 61000;
+        await c.check({});
+        expect(f.calls).toHaveLength(3);
+    });
+    it('with no headroom limit, reuses the decision for its ttl however much is spent', async () => {
+        const f = fakeFetch(() => ({ body: decision({ headroomUsd: null, ttlSeconds: 30 }) }));
+        const c = client(f);
+        for (let i = 0; i < 20; i++)
+            await c.check({ estimatedCostUsd: 5 });
+        expect(f.calls).toHaveLength(1);
+    });
+    it('shares one fetch between concurrent checks', async () => {
+        const f = fakeFetch(() => ({ body: decision() }));
+        const c = client(f);
+        await Promise.all([c.check({}), c.check({}), c.check({})]);
+        expect(f.calls).toHaveLength(1);
+    });
+    it('refuses on block and says why; allows on warn with the reason', async () => {
+        const blocked = await client(fakeFetch([{ body: decision({ action: 'block', code: 'budget_block', reason: 'Over the Checkout budget.', limit: { id: 'b1', name: 'Checkout', scope: 'App: checkout-api' } }) }])).check();
+        expect(blocked).toMatchObject({ allowed: false, action: 'block', code: 'budget_block', reason: 'Over the Checkout budget.' });
+        expect(blocked.limit).toEqual({ id: 'b1', name: 'Checkout', scope: 'App: checkout-api' });
+        const warned = await client(fakeFetch([{ body: decision({ action: 'warn', code: 'budget_warn', reason: 'At 85%.' }) }])).check();
+        expect(warned).toMatchObject({ allowed: true, action: 'warn', reason: 'At 85%.' });
+    });
+    it('throttles to the requests a minute the decision allows', async () => {
+        const clock = { t: 0 };
+        const c = client(fakeFetch(() => ({ body: decision({ action: 'throttle', code: 'budget_throttle', throttle: { requestsPerMinute: 2 }, ttlSeconds: 600 }) })), {}, clock);
+        expect((await c.check()).allowed).toBe(true);
+        expect((await c.check()).allowed).toBe(true);
+        expect((await c.check()).allowed).toBe(false);
+        clock.t += 60001;
+        expect((await c.check()).allowed).toBe(true);
+    });
+    it('never throws, and fails open by default when no decision can be read', async () => {
+        for (const answer of [{ throws: true }, { status: 503, body: { err: 'x' } }, { status: 200, body: 'nonsense' }, { status: 200, body: { action: 'explode' } }]) {
+            const r = await client(fakeFetch([answer])).check();
+            expect(r).toMatchObject({ allowed: true, action: 'allow', unavailable: true, code: 'budget_unavailable' });
+        }
+        // No URL or key: nothing to ask, so the fail mode applies without a request.
+        const f = fakeFetch([]);
+        expect((await new index_1.BudgetClient({ app: 'a', fetch: f.fn, url: '', apiKey: '' }).check()).unavailable).toBe(true);
+        expect(f.calls).toHaveLength(0);
+    });
+    it('fails closed when asked to, on the client or for one check', async () => {
+        const down = () => fakeFetch(() => ({ throws: true }));
+        expect(await client(down(), { failClosed: true }).check()).toMatchObject({ allowed: false, action: 'block', unavailable: true });
+        expect((await client(down()).check({ failClosed: true })).allowed).toBe(false);
+        expect((await client(down(), { failClosed: true }).check({ failClosed: false })).allowed).toBe(true);
+    });
+    it('fails closed after a decision said a block rule asks for it', async () => {
+        const clock = { t: 0 };
+        let up = true;
+        const f = fakeFetch(() => (up ? { body: decision({ failClosed: true, ttlSeconds: 1 }) } : { throws: true }));
+        const c = client(f, {}, clock);
+        expect((await c.check()).allowed).toBe(true);
+        up = false;
+        clock.t += 2000;
+        expect((await c.check()).allowed).toBe(false);
+    });
+    it('backs off for a few seconds after a failed read instead of asking on every call', async () => {
+        const clock = { t: 0 };
+        const f = fakeFetch(() => ({ throws: true }));
+        const c = client(f, {}, clock);
+        await c.check();
+        await c.check();
+        expect(f.calls).toHaveLength(1);
+        clock.t += 6000;
+        await c.check();
+        expect(f.calls).toHaveLength(2);
+    });
+});
+describe('the automatic pre-call check', () => {
+    it('names the model from the call, and from a Bedrock command', () => {
+        expect((0, auto_1.modelOf)({ model: 'gpt-4o', messages: [] })).toBe('gpt-4o');
+        expect((0, auto_1.modelOf)({ input: { modelId: 'anthropic.claude-3' } })).toBe('anthropic.claude-3');
+        expect((0, auto_1.modelOf)(undefined)).toBeUndefined();
+    });
+    it('refuses a provider call a budget blocks, and lets an allowed one through', async () => {
+        const proto = { create: jest.fn(async (params) => `ok ${params.model}`) };
+        jest.doMock('fake-provider-for-budget-test', () => ({ Client: { prototype: proto } }), { virtual: true });
+        let action = 'allow';
+        const f = fakeFetch(() => ({ body: decision({ action, code: `budget_${action}`, reason: action === 'block' ? 'Over budget.' : '', ttlSeconds: 0.001 }) }));
+        const clock = { t: 0 };
+        const c = client(f, {}, clock);
+        const report = (0, auto_1.setupAutoBudgetCheck)({ client: c, methods: [{ npmPackage: 'fake-provider-for-budget-test', protoPath: ['Client', 'prototype'], methodName: 'create', extractInput: () => '', extractOutput: () => '' }] });
+        expect(report.wrapped).toEqual(['fake-provider-for-budget-test']);
+        expect(await proto.create({ model: 'gpt-4o' })).toBe('ok gpt-4o');
+        expect(f.calls[0].url).toContain('model=gpt-4o');
+        action = 'block';
+        clock.t += 1000;
+        await expect(proto.create({ model: 'gpt-4o' })).rejects.toBeInstanceOf(index_1.BudgetExceededError);
+        // Wrapping twice does not check twice.
+        const again = (0, auto_1.setupAutoBudgetCheck)({ client: c, methods: [{ npmPackage: 'fake-provider-for-budget-test', protoPath: ['Client', 'prototype'], methodName: 'create', extractInput: () => '', extractOutput: () => '' }] });
+        expect(again.wrapped).toEqual([]);
+    });
+});
+//# sourceMappingURL=budgets.test.js.map

package/dist/budgets/__tests__/budgets.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budgets.test.js","sourceRoot":"","sources":["../../../src/budgets/__tests__/budgets.test.ts"],"names":[],"mappings":";;AAAA,oCAA6D;AAC7D,kCAAwD;AAIxD,SAAS,SAAS,CAAC,OAA6C;IAC9D,MAAM,KAAK,GAAuD,EAAE,CAAC;IACrE,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,GAAW,EAAE,IAAyC,EAAE,EAAE;QAClF,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QAC3C,MAAM,CAAC,GAAG,OAAO,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;QAC5F,IAAI,CAAC,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,cAAc,CAAC,CAAC;QAC9C,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,GAAG,CAAC,GAAG,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,GAAG,EAAE,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,EAAyB,CAAC;IACnH,CAAC,CAAC,CAAC;IACH,OAAO,EAAE,EAAE,EAAE,EAA6B,EAAE,KAAK,EAAE,CAAC;AACtD,CAAC;AAED,MAAM,QAAQ,GAAG,CAAC,OAAgC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;AAE1L,SAAS,MAAM,CAAC,CAA+B,EAAE,OAAgC,EAAE,EAAE,KAAK,GAAG,EAAE,CAAC,EAAE,OAAS,EAAE;IAC3G,OAAO,IAAI,oBAAY,CAAC,EAAE,GAAG,EAAE,yBAAyB,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;AAC/I,CAAC;AAED,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC7B,EAAE,CAAC,kEAAkE,EAAE,KAAK,IAAI,EAAE;QAChF,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC;QAC5C,MAAM,CAAC,GAAG,MAAM,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7E,MAAM,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC;QAC/F,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,yFAAyF,CAAC,CAAC;QACvH,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IACjE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oFAAoF,EAAE,KAAK,IAAI,EAAE;QAClG,MAAM,KAAK,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;QACvB,MAAM,CAAC,GAAG,SAAS,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QACpE,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC;QAC/B,MAAM,CAAC,CAAC,KAAK,CAAC,EAAE,gBAAgB,EAAE,GAAG,EAAE,CAAC,CAAC;QACzC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,EAAE,gBAAgB,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QAChC,uEAAuE;QACvE,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,EAAE,gBAAgB,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACtE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QAChC,KAAK,CAAC,CAAC,IAAI,KAAM,CAAC;QAClB,MAAM,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAClB,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+EAA+E,EAAE,KAAK,IAAI,EAAE;QAC7F,MAAM,CAAC,GAAG,SAAS,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QACvF,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE;YAAE,MAAM,CAAC,CAAC,KAAK,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,CAAC,CAAC;QACpE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4CAA4C,EAAE,KAAK,IAAI,EAAE;QAC1D,MAAM,CAAC,GAAG,SAAS,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC;QAClD,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACpB,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAC3D,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+DAA+D,EAAE,KAAK,IAAI,EAAE;QAC7E,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,2BAA2B,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,mBAAmB,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;QACzN,MAAM,CAAC,OAAO,CAAC,CAAC,aAAa,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,2BAA2B,EAAE,CAAC,CAAC;QAC9H,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,mBAAmB,EAAE,CAAC,CAAC;QAC1F,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;QACjI,MAAM,CAAC,MAAM,CAAC,CAAC,aAAa,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;IACrF,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wDAAwD,EAAE,KAAK,IAAI,EAAE;QACtE,MAAM,KAAK,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;QACvB,MAAM,CAAC,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,iBAAiB,EAAE,QAAQ,EAAE,EAAE,iBAAiB,EAAE,CAAC,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC;QACzK,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7C,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7C,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC9C,KAAK,CAAC,CAAC,IAAI,KAAM,CAAC;QAClB,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sEAAsE,EAAE,KAAK,IAAI,EAAE;QACpF,KAAK,MAAM,MAAM,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,CAAC,EAAE,CAAC;YAC9J,MAAM,CAAC,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;YACpD,MAAM,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,oBAAoB,EAAE,CAAC,CAAC;QAC7G,CAAC;QACD,6EAA6E;QAC7E,MAAM,CAAC,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC;QACxB,MAAM,CAAC,CAAC,MAAM,IAAI,oBAAY,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChH,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4DAA4D,EAAE,KAAK,IAAI,EAAE;QAC1E,MAAM,IAAI,GAAG,GAAG,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QACvD,MAAM,CAAC,MAAM,MAAM,CAAC,IAAI,EAAE,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,aAAa,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;QACjI,MAAM,CAAC,CAAC,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC/E,MAAM,CAAC,CAAC,MAAM,MAAM,CAAC,IAAI,EAAE,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACvG,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6DAA6D,EAAE,KAAK,IAAI,EAAE;QAC3E,MAAM,KAAK,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;QACvB,IAAI,EAAE,GAAG,IAAI,CAAC;QACd,MAAM,CAAC,GAAG,SAAS,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QAC7G,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC;QAC/B,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7C,EAAE,GAAG,KAAK,CAAC;QACX,KAAK,CAAC,CAAC,IAAI,IAAK,CAAC;QACjB,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iFAAiF,EAAE,KAAK,IAAI,EAAE;QAC/F,MAAM,KAAK,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;QACvB,MAAM,CAAC,GAAG,SAAS,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QAC9C,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC;QAC/B,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC;QAChB,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC;QAChB,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QAChC,KAAK,CAAC,CAAC,IAAI,IAAK,CAAC;QACjB,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC;QAChB,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,8BAA8B,EAAE,GAAG,EAAE;IAC5C,EAAE,CAAC,2DAA2D,EAAE,GAAG,EAAE;QACnE,MAAM,CAAC,IAAA,cAAO,EAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAClE,MAAM,CAAC,IAAA,cAAO,EAAC,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,oBAAoB,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;QACzF,MAAM,CAAC,IAAA,cAAO,EAAC,SAAS,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0EAA0E,EAAE,KAAK,IAAI,EAAE;QACxF,MAAM,KAAK,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,MAAyB,EAAE,EAAE,CAAC,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC;QAC7F,IAAI,CAAC,MAAM,CAAC,+BAA+B,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1G,IAAI,MAAM,GAAG,OAAO,CAAC;QACrB,MAAM,CAAC,GAAG,SAAS,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QAC3J,MAAM,KAAK,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;QACvB,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC;QAC/B,MAAM,MAAM,GAAG,IAAA,2BAAoB,EAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,+BAA+B,EAAE,SAAS,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,aAAa,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;QAC1N,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,+BAA+B,CAAC,CAAC,CAAC;QAClE,MAAM,CAAC,MAAM,KAAK,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAClE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC;QACjD,MAAM,GAAG,OAAO,CAAC;QACjB,KAAK,CAAC,CAAC,IAAI,IAAK,CAAC;QACjB,MAAM,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC,2BAAmB,CAAC,CAAC;QAC5F,uCAAuC;QACvC,MAAM,KAAK,GAAG,IAAA,2BAAoB,EAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,+BAA+B,EAAE,SAAS,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,aAAa,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;QACzN,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/budgets/auto.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The automatic budget check: before each call to a provider the SDK knows
+ * (the same methods the auto-guards wrap), ask Shield360.budgets.check() for
+ * the call's model and refuse the call with BudgetExceededError when a
+ * budget blocks it or its throttle is spent. On by init({ budgetCheck: true })
+ * or SHIELD360_BUDGET_CHECK=1; off by default.
+ *
+ * The check is cached (see ./index.ts), so it does not reach the platform on
+ * every call; it fails open unless asked to fail closed.
+ *
+ * Must stay in sync with: sdk/python/src/shield360/budgets.py (setup_auto_budget_check)
+ */
+import { type GuardedMethod } from '../guard/integration';
+import { type BudgetClient, type BudgetCheckResult } from './index';
+/** The model a provider call names, when it names one. */
+export declare function modelOf(params: unknown): string | undefined;
+export type AutoBudgetReport = {
+    wrapped: string[];
+};
+/** Wraps the known providers' methods with the budget check. Idempotent per method. */
+export declare function setupAutoBudgetCheck(options?: {
+    client?: BudgetClient;
+    methods?: GuardedMethod[];
+    onWarn?: (result: BudgetCheckResult) => void;
+}): AutoBudgetReport;

package/dist/budgets/auto.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * The automatic budget check: before each call to a provider the SDK knows
+ * (the same methods the auto-guards wrap), ask Shield360.budgets.check() for
+ * the call's model and refuse the call with BudgetExceededError when a
+ * budget blocks it or its throttle is spent. On by init({ budgetCheck: true })
+ * or SHIELD360_BUDGET_CHECK=1; off by default.
+ *
+ * The check is cached (see ./index.ts), so it does not reach the platform on
+ * every call; it fails open unless asked to fail closed.
+ *
+ * Must stay in sync with: sdk/python/src/shield360/budgets.py (setup_auto_budget_check)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.modelOf = modelOf;
+exports.setupAutoBudgetCheck = setupAutoBudgetCheck;
+const integration_1 = require("../guard/integration");
+const index_1 = require("./index");
+const WRAPPED = Symbol.for('shield360.budgetCheck');
+/** The model a provider call names, when it names one. */
+function modelOf(params) {
+    if (!params || typeof params !== 'object')
+        return undefined;
+    const p = params;
+    if (typeof p.model === 'string')
+        return p.model;
+    // Bedrock's send(command) carries the model on the command's input.
+    const input = p.input;
+    if (input && typeof input === 'object' && typeof input.modelId === 'string')
+        return input.modelId;
+    return undefined;
+}
+/** Wraps the known providers' methods with the budget check. Idempotent per method. */
+function setupAutoBudgetCheck(options = {}) {
+    const client = options.client ?? (0, index_1.defaultBudgetClient)();
+    const wrapped = new Set();
+    for (const { npmPackage, protoPath, methodName } of options.methods ?? integration_1.GUARDED_METHODS) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const mod = require(npmPackage);
+            const proto = (0, integration_1.resolveProto)(mod, protoPath);
+            if (!proto || typeof proto[methodName] !== 'function' || proto[methodName][WRAPPED])
+                continue;
+            const original = proto[methodName];
+            const checked = async function (...args) {
+                const result = await client.check({ model: modelOf(args[0]) });
+                if (!result.allowed)
+                    throw new index_1.BudgetExceededError(result);
+                if (result.action === 'warn' && result.reason)
+                    options.onWarn?.(result);
+                return original.apply(this, args);
+            };
+            checked[WRAPPED] = true;
+            proto[methodName] = checked;
+            wrapped.add(npmPackage);
+        }
+        catch {
+            // not installed
+        }
+    }
+    return { wrapped: Array.from(wrapped) };
+}
+//# sourceMappingURL=auto.js.map

package/dist/budgets/auto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto.js","sourceRoot":"","sources":["../../src/budgets/auto.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;AAQH,0BAQC;AAKD,oDA0BC;AA7CD,sDAAyF;AACzF,mCAA8G;AAE9G,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;AAEpD,0DAA0D;AAC1D,SAAgB,OAAO,CAAC,MAAe;IACrC,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC5D,MAAM,CAAC,GAAG,MAAiC,CAAC;IAC5C,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC,KAAK,CAAC;IAChD,oEAAoE;IACpE,MAAM,KAAK,GAAG,CAAC,CAAC,KAA4C,CAAC;IAC7D,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC,OAAO,CAAC;IAClG,OAAO,SAAS,CAAC;AACnB,CAAC;AAID,uFAAuF;AACvF,SAAgB,oBAAoB,CAClC,UAA8G,EAAE;IAEhH,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,IAAA,2BAAmB,GAAE,CAAC;IACvD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,KAAK,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,OAAO,CAAC,OAAO,IAAI,6BAAe,EAAE,CAAC;QACvF,IAAI,CAAC;YACH,8DAA8D;YAC9D,MAAM,GAAG,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;YAChC,MAAM,KAAK,GAAG,IAAA,0BAAY,EAAC,GAAG,EAAE,SAAS,CAAC,CAAC;YAC3C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,CAAC,UAAU,CAAC,KAAK,UAAU,IAAI,KAAK,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC;gBAAE,SAAS;YAC9F,MAAM,QAAQ,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC;YACnC,MAAM,OAAO,GAAG,KAAK,WAA0B,GAAG,IAAe;gBAC/D,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;gBAC/D,IAAI,CAAC,MAAM,CAAC,OAAO;oBAAE,MAAM,IAAI,2BAAmB,CAAC,MAAM,CAAC,CAAC;gBAC3D,IAAI,MAAM,CAAC,MAAM,KAAK,MAAM,IAAI,MAAM,CAAC,MAAM;oBAAE,OAAO,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC;gBACxE,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACpC,CAAC,CAAC;YACD,OAA8C,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;YAChE,KAAK,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC;YAC5B,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,gBAAgB;QAClB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;AAC1C,CAAC"}