API reference

createSecurityLayer()

Creates and returns a SecurityLayer instance. This is the main entry point for the SDK.

import { createSecurityLayer } from "@securitylayerai/sdk";

const sl = await createSecurityLayer(options?: SecurityLayerOptions);

Options

Option	Type	Default	Description
`configDir`	`string`	`~/.securitylayer`	Path to Security Layer configuration directory
`sessionId`	`string`	Auto-generated UUID	Default session ID for checks
`config`	`LoadedConfig`	—	Pre-loaded config object (skips file loading, useful for testing)
`eventBus`	`EventBus`	Auto-created	Injected event bus (useful for testing or sharing events)

Throws: ConfigError if config files can't be loaded, InitializationError if the security pipeline fails to initialize.

SecurityLayer

The object returned by createSecurityLayer(). Provides all security checking, taint tracking, and event handling methods.

check()

Evaluate an action through the security pipeline before execution.

const result = await sl.check(
  tool: string,
  params: Record<string, unknown>,
  context?: ExecutionContext,
): Promise<CheckResult>;

Parameters:

Parameter	Type	Description
`tool`	`string`	The capability being used: `"exec"`, `"file.read"`, `"file.write"`, `"web_fetch"`, etc.
`params`	`object`	Tool-specific parameters. For exec, the command is extracted from `command`, `cmd`, or `input` properties.
`context`	`ExecutionContext`	Optional context overrides for this check

Returns: Promise<CheckResult>

waitForApproval()

Block until a human approves or denies a REQUIRE_APPROVAL decision.

const approved = await sl.waitForApproval(
  approvalId: string,
  options?: ApprovalOptions,
): Promise<boolean>;

Parameters:

Parameter	Type	Description
`approvalId`	`string`	The approval ID from a `REQUIRE_APPROVAL` check result
`options.timeout`	`number`	Timeout in milliseconds (default: 300000 / 5 minutes)

Returns: true if approved, false if denied, timed out, or approvalId is unknown.

ingestContent()

Update the taint tracker when external content enters the session.

sl.ingestContent(
  content: string,
  metadata: ContentMetadata,
): void;

Parameters:

Parameter	Type	Description
`content`	`string`	The content that was read or fetched
`metadata.source`	`"web" \| "file" \| "channel" \| "skill" \| "memory"`	Where the content came from
`metadata.path`	`string?`	File path, skill name, or channel identifier
`metadata.url`	`string?`	URL (for web sources)

Source-to-taint mapping:

Source	Taint Level
`web`	WEB
`file`	UNTRUSTED
`channel`	UNTRUSTED
`skill`	SKILL
`memory`	MEMORY

scanEgress()

Scan outbound content for leaked secrets, PII, and sensitive data before sending.

const result = sl.scanEgress(content: string): EgressScanResult;

Returns: EgressScanResult with clean: boolean and findings: EgressFinding[].

getSessionTaint()

Get the current session's effective taint level.

const taint = sl.getSessionTaint(): string;

Returns: One of "owner", "trusted", "untrusted", "web", "skill", "memory".

on()

Subscribe to security events from the internal event bus.

const unsubscribe = sl.on(type: string, handler: (event) => void): () => void;

Parameters:

Parameter	Type	Description
`type`	`string`	Event type to listen for (e.g., `"action.evaluated"`, `"taint.elevated"`, `"approval.requested"`)
`handler`	`function`	Callback invoked when the event fires

Returns: An unsubscribe function. Call it to stop receiving events.

destroy()

Clean up resources. Resolves all pending approval requests as timed-out and clears all event handlers.

sl.destroy(): void;

Always call destroy() when you're done with the SecurityLayer instance.

withSecurityLayer()

Middleware wrapper that adds security checks to any function. Intercepts calls transparently — the wrapped function has the same signature as the original.

import { createSecurityLayer, withSecurityLayer } from "@securitylayerai/sdk";

const sl = await createSecurityLayer();

const protectedExec = withSecurityLayer(sl, originalExecFn, "exec");
const protectedRead = withSecurityLayer(sl, originalReadFn, "file.read");

Signature:

function withSecurityLayer<TArgs extends unknown[], TReturn>(
  sl: SecurityLayer,
  fn: (...args: TArgs) => TReturn | Promise<TReturn>,
  tool: string,
  options?: {
    extractParams?: (...args: unknown[]) => Record<string, unknown>;
  },
): (...args: TArgs) => Promise<TReturn>;

Behavior:

ALLOW → calls the original function and returns its result
DENY → throws SecurityLayerError without calling the function
REQUIRE_APPROVAL → waits for approval, throws if denied

Default parameter extraction: If the first argument is a string, it's mapped to { command: arg }. If it's an object, it's used directly as params.

Error classes

All SDK errors extend SecurityLayerError, which extends Error.

import {
  SecurityLayerError,
  ConfigError,
  InitializationError,
  CheckError,
  ApprovalTimeoutError,
} from "@securitylayerai/sdk";

Error	Properties	Thrown when
`SecurityLayerError`	`message`	Base class; also thrown by `withSecurityLayer()` on DENY
`ConfigError`	`configPath?: string`	Config files can't be loaded or parsed
`InitializationError`	`cause?: unknown`	Security pipeline fails to initialize
`CheckError`	`tool?: string`	Action evaluation fails unexpectedly
`ApprovalTimeoutError`	`approvalId: string`	Approval request times out

Types

CheckResult

interface CheckResult {
  decision: "ALLOW" | "DENY" | "REQUIRE_APPROVAL";
  reason: string;
  approvalId?: string;
  layers: LayerResults;
  degraded: boolean;
  timing: {
    total: number;
    capability?: number;
    rules?: number;
    llm?: number;
  };
}

LayerResults

interface LayerResults {
  capability: {
    allowed: boolean;
    reason?: string;
  };
  rules?: {
    decision: string;
    reason?: string;
  };
  llm?: {
    decision: string;
    confidence: number;
    reasoning?: string;
  };
}

EgressScanResult

interface EgressScanResult {
  clean: boolean;
  findings: EgressFinding[];
}

interface EgressFinding {
  type:
    | "api_key"
    | "pem_block"
    | "private_key"
    | "password"
    | "high_entropy"
    | "pii"
    | "credential_pattern";
  confidence: number;
  location: { start: number; end: number };
  redacted: string;
}

ExecutionContext

interface ExecutionContext {
  sessionId?: string;
  skillId?: string;
  channelId?: string;
}

ContentMetadata

interface ContentMetadata {
  source: "web" | "file" | "channel" | "skill" | "memory";
  path?: string;
  url?: string;
}

SecurityLayerOptions

interface SecurityLayerOptions {
  configDir?: string;
  sessionId?: string;
  config?: LoadedConfig;
  eventBus?: EventBus;
}

ApprovalOptions

interface ApprovalOptions {
  timeout?: number; // milliseconds, default 300000 (5 min)
}

API reference

createSecurityLayer()

Options

SecurityLayer

check()

waitForApproval()

ingestContent()

scanEgress()

getSessionTaint()

on()

destroy()

withSecurityLayer()

Error classes

Types

CheckResult

LayerResults

EgressScanResult

ExecutionContext

ContentMetadata

SecurityLayerOptions

ApprovalOptions

See also

On this page