shield360 1.0.1 → 1.1.0

package/dist/protect/mode.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Shield Protect -- the enforcement mode of this process.
+ *
+ *   observe   every check runs and its finding is recorded (span event,
+ *             decision report); nothing is refused. For seeing what enforced
+ *             mode would stop before turning it on.
+ *   warn      as observe, and the finding is logged as a warning.
+ *   enforced  a finding refuses the call; a guard that throws refuses the
+ *             call (fail closed, whatever guardFailOpen says); a provider
+ *             named in `required` that could not be wrapped stops startup;
+ *             a streamed completion that postflight guards cannot inspect
+ *             is refused; input past the scan bound is refused rather than
+ *             scanned in part.
+ *
+ * The mode set in code is a floor: SHIELD360_PROTECT_MODE can raise it and
+ * never lower it, so an environment variable in a shell or a container
+ * cannot weaken what the application was deployed with. With no mode set
+ * anywhere, guards behave as they always have (each guard's own action,
+ * guardFailOpen as given): that is `legacy`, and nothing changes for an
+ * application that never asked for Protect.
+ *
+ * What this layer can and cannot claim: it runs inside the application's
+ * process. Code that can disable the SDK, import a provider the SDK does
+ * not wrap, or reach a network directly is not stopped by it. The
+ * mandatory boundary is the Shield360 gateway; this layer is monitored or
+ * partially protected, and its readiness report says so.
+ *
+ * Must stay in sync with: sdk/python/src/shield360/protect/_mode.py
+ */
+export type ProtectMode = 'observe' | 'warn' | 'enforced';
+export declare const PROTECT_MODES: readonly ProtectMode[];
+export declare const PROTECT_MODE_ENV = "SHIELD360_PROTECT_MODE";
+export declare const PROTECT_REQUIRED_ENV = "SHIELD360_PROTECT_REQUIRED";
+export declare function isProtectMode(value: unknown): value is ProtectMode;
+/** The stricter of two modes; undefined counts as nothing. */
+export declare function strictestMode(a?: ProtectMode, b?: ProtectMode): ProtectMode | undefined;
+/**
+ * The mode this process runs under: what the code set, raised by the
+ * environment when the environment asks for more. An environment value
+ * that is not a mode is ignored, never a downgrade.
+ */
+export declare function resolveProtectMode(fromCode?: ProtectMode, env?: NodeJS.ProcessEnv): ProtectMode | undefined;
+/** Providers that must be wrapped: the code's list plus the environment's. */
+export declare function resolveRequired(fromCode?: string[], env?: NodeJS.ProcessEnv): string[];
+export type ProtectConfig = {
+    mode?: ProtectMode;
+    /** npm package names whose provider methods must be wrapped, or startup fails in enforced mode: "openai", "@anthropic-ai/sdk". */
+    required?: string[];
+};
+export type ResolvedProtect = {
+    mode?: ProtectMode;
+    required: string[];
+};
+export declare function resolveProtect(config: ProtectConfig | undefined, env?: NodeJS.ProcessEnv): ResolvedProtect;
+export declare const refuses: (mode: ProtectMode | undefined) => boolean;
+export declare class ProtectError extends Error {
+    constructor(message?: string);
+}
+/** A call refused by Protect for a reason that is not a guard finding: oversized input, uninspectable streaming, a failed check. */
+export declare class ProtectDeniedError extends ProtectError {
+    readonly code: 'oversized' | 'streaming' | 'guard_failed' | 'not_authorized' | 'authorize_failed';
+    constructor(code: ProtectDeniedError['code'], message: string);
+}
+/** Enforced mode could not be set up: a required provider is not wrapped, or guards are missing. Thrown from init. */
+export declare class ProtectReadinessError extends ProtectError {
+    readonly missing: string[];
+    constructor(missing: string[], message: string);
+}
+export type ProtectReadiness = {
+    mode: ProtectMode | 'legacy';
+    /** Provider packages whose methods were wrapped. */
+    wrapped: string[];
+    /** Provider packages named as required that were not wrapped. */
+    missing: string[];
+    /** monitored: in-process checks that code in the same process can bypass. Never "enforced": that is the gateway's claim. */
+    level: 'monitored' | 'partially_protected';
+    note: string;
+};
+/** @internal */
+export declare function setProtectState(next: {
+    mode?: ProtectMode;
+    wrapped: string[];
+    missing: string[];
+}): void;
+/** @internal */
+export declare function currentProtectMode(): ProtectMode | undefined;
+export declare function protectReadiness(): ProtectReadiness;
+/** @internal for tests */
+export declare function resetProtectState(): void;

package/dist/protect/mode.js

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * Shield Protect -- the enforcement mode of this process.
+ *
+ *   observe   every check runs and its finding is recorded (span event,
+ *             decision report); nothing is refused. For seeing what enforced
+ *             mode would stop before turning it on.
+ *   warn      as observe, and the finding is logged as a warning.
+ *   enforced  a finding refuses the call; a guard that throws refuses the
+ *             call (fail closed, whatever guardFailOpen says); a provider
+ *             named in `required` that could not be wrapped stops startup;
+ *             a streamed completion that postflight guards cannot inspect
+ *             is refused; input past the scan bound is refused rather than
+ *             scanned in part.
+ *
+ * The mode set in code is a floor: SHIELD360_PROTECT_MODE can raise it and
+ * never lower it, so an environment variable in a shell or a container
+ * cannot weaken what the application was deployed with. With no mode set
+ * anywhere, guards behave as they always have (each guard's own action,
+ * guardFailOpen as given): that is `legacy`, and nothing changes for an
+ * application that never asked for Protect.
+ *
+ * What this layer can and cannot claim: it runs inside the application's
+ * process. Code that can disable the SDK, import a provider the SDK does
+ * not wrap, or reach a network directly is not stopped by it. The
+ * mandatory boundary is the Shield360 gateway; this layer is monitored or
+ * partially protected, and its readiness report says so.
+ *
+ * Must stay in sync with: sdk/python/src/shield360/protect/_mode.py
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProtectReadinessError = exports.ProtectDeniedError = exports.ProtectError = exports.refuses = exports.PROTECT_REQUIRED_ENV = exports.PROTECT_MODE_ENV = exports.PROTECT_MODES = void 0;
+exports.isProtectMode = isProtectMode;
+exports.strictestMode = strictestMode;
+exports.resolveProtectMode = resolveProtectMode;
+exports.resolveRequired = resolveRequired;
+exports.resolveProtect = resolveProtect;
+exports.setProtectState = setProtectState;
+exports.currentProtectMode = currentProtectMode;
+exports.protectReadiness = protectReadiness;
+exports.resetProtectState = resetProtectState;
+exports.PROTECT_MODES = ['observe', 'warn', 'enforced'];
+const RANK = { observe: 0, warn: 1, enforced: 2 };
+exports.PROTECT_MODE_ENV = 'SHIELD360_PROTECT_MODE';
+exports.PROTECT_REQUIRED_ENV = 'SHIELD360_PROTECT_REQUIRED';
+function isProtectMode(value) {
+    return typeof value === 'string' && exports.PROTECT_MODES.includes(value);
+}
+/** The stricter of two modes; undefined counts as nothing. */
+function strictestMode(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    return RANK[a] >= RANK[b] ? a : b;
+}
+/**
+ * The mode this process runs under: what the code set, raised by the
+ * environment when the environment asks for more. An environment value
+ * that is not a mode is ignored, never a downgrade.
+ */
+function resolveProtectMode(fromCode, env = process.env) {
+    const raw = (env[exports.PROTECT_MODE_ENV] || '').trim().toLowerCase();
+    const fromEnv = isProtectMode(raw) ? raw : undefined;
+    return strictestMode(fromCode, fromEnv);
+}
+/** Providers that must be wrapped: the code's list plus the environment's. */
+function resolveRequired(fromCode = [], env = process.env) {
+    const fromEnv = (env[exports.PROTECT_REQUIRED_ENV] || '')
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    return Array.from(new Set([...fromCode, ...fromEnv]));
+}
+function resolveProtect(config, env = process.env) {
+    return { mode: resolveProtectMode(config?.mode, env), required: resolveRequired(config?.required, env) };
+}
+const refuses = (mode) => mode === 'enforced';
+exports.refuses = refuses;
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+class ProtectError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ProtectError';
+    }
+}
+exports.ProtectError = ProtectError;
+/** A call refused by Protect for a reason that is not a guard finding: oversized input, uninspectable streaming, a failed check. */
+class ProtectDeniedError extends ProtectError {
+    constructor(code, message) {
+        super(message);
+        this.name = 'ProtectDeniedError';
+        this.code = code;
+    }
+}
+exports.ProtectDeniedError = ProtectDeniedError;
+/** Enforced mode could not be set up: a required provider is not wrapped, or guards are missing. Thrown from init. */
+class ProtectReadinessError extends ProtectError {
+    constructor(missing, message) {
+        super(message);
+        this.name = 'ProtectReadinessError';
+        this.missing = missing;
+    }
+}
+exports.ProtectReadinessError = ProtectReadinessError;
+let state = { wrapped: [], missing: [] };
+/** @internal */
+function setProtectState(next) {
+    state = { mode: next.mode, wrapped: [...next.wrapped], missing: [...next.missing] };
+}
+/** @internal */
+function currentProtectMode() {
+    return state.mode;
+}
+function protectReadiness() {
+    const mode = state.mode ?? 'legacy';
+    const partial = mode === 'enforced' && state.missing.length === 0 && state.wrapped.length > 0;
+    return {
+        mode,
+        wrapped: [...state.wrapped],
+        missing: [...state.missing],
+        level: partial ? 'partially_protected' : 'monitored',
+        note: partial
+            ? 'Supported provider calls in this process are refused before they leave when a guard finds a violation, and fail closed. Code in this process that bypasses the SDK is not covered; the mandatory boundary is the Shield360 gateway.'
+            : 'Findings are recorded; calls are not refused by this layer. The mandatory boundary is the Shield360 gateway.',
+    };
+}
+/** @internal for tests */
+function resetProtectState() {
+    state = { wrapped: [], missing: [] };
+}
+//# sourceMappingURL=mode.js.map

package/dist/protect/mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode.js","sourceRoot":"","sources":["../../src/protect/mode.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -2,6 +2,7 @@ import { Resource } from '@opentelemetry/resources';
 import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
 import { metrics } from '@opentelemetry/api';
 import type { Guard } from './guard/base';
+import type { ProtectConfig, ResolvedProtect } from './protect/mode';
 export type InstrumentationType = 'openai' | 'anthropic' | 'cohere' | 'groq' | 'mistral' | 'google-ai' | 'vertexai' | 'together' | 'ollama' | 'vllm' | 'vercel-ai' | 'langchain' | 'langgraph' | 'pinecone' | 'bedrock' | 'llamaindex' | 'huggingface' | 'replicate' | 'chroma' | 'qdrant' | 'milvus' | 'astra' | 'azure-ai-inference' | 'openai-agents' | 'strands' | 'google-adk' | 'claude-agent-sdk' | 'cursor-sdk' | 'ai21' | 'gradient' | 'browser-use' | 'mcp' | 'mem0' | 'elevenlabs' | 'assemblyai' | 'transformers' | 'pg' | 'firecrawl' | 'letta';
 export type Shield360Instrumentations = Partial<Record<InstrumentationType, any>>;
 export type PricingObject = Record<string, Record<string, unknown>>;
@@ -41,6 +42,9 @@ export interface Shield360ConfigInterface {
  *   Python: max_content_length   → JS: maxContentLength
  *   Python: custom_span_attributes → JS: customSpanAttributes
  *   Python: collect_gpu_stats     → JS: collectGpuStats
+ *   Python: capture_code_location → JS: captureCodeLocation
+ *   Python: code_root             → JS: codeRoot
+ *   Python: service_version       → JS: serviceVersion
  */
 export type Shield360Options = {
     environment?: string;
@@ -61,7 +65,21 @@ export type Shield360Options = {
     shield360Url?: string;
     guards?: Guard[];
     guardFailOpen?: boolean;
+    /**
+     * Shield Protect: the enforcement mode (observe | warn | enforced; env
+     * SHIELD360_PROTECT_MODE can raise it, never lower it) and the provider
+     * packages that must be wrapped for protected startup (env
+     * SHIELD360_PROTECT_REQUIRED adds to the list). In enforced mode, init()
+     * throws ProtectReadinessError instead of starting unguarded.
+     */
+    protect?: ProtectConfig;
     collectGpuStats?: boolean;
+    /** Add code.* call-site attributes to GenAI spans (default true; env SHIELD360_CAPTURE_CODE_LOCATION). */
+    captureCodeLocation?: boolean;
+    /** Root stripped from code.file.path (env SHIELD360_CODE_ROOT). */
+    codeRoot?: string;
+    /** service.version resource attribute (env SHIELD360_SERVICE_VERSION). */
+    serviceVersion?: string;
 };
 /**
  * Resolved options used internally after merging args, env vars, and defaults.
@@ -85,7 +103,11 @@ export interface ResolvedOptions {
     shield360Url?: string;
     guards?: Guard[];
     guardFailOpen: boolean;
+    protect: ResolvedProtect;
     collectGpuStats: boolean;
+    captureCodeLocation: boolean;
+    codeRoot?: string;
+    serviceVersion?: string;
 }
 export type SetupTracerOptions = ResolvedOptions & {
     resource: Resource;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shield360",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "homepage": "https://github.com/ThinkfleetAI/shield360-js#readme",
   "bugs": {
     "url": "https://github.com/ThinkfleetAI/shield360-js/issues",