@declaw/sdk 1.1.12 → 1.2.0

package/dist/index.d.ts

@@ -234,10 +234,9 @@ declare function networkPolicyToOpts(policy: NetworkPolicy): SandboxNetworkOpts;
 /**
  * Toggle for per-sandbox audit logging.
  *
- * Declaw records a fixed set of lifecycle + security events (vm_created,
- * vm_killed, snapshot_*, egress_blocked, …). Set `enabled: false` to opt
- * the sandbox out entirely; events for that sandbox are not shipped to
- * the collector and nothing is persisted.
+ * When enabled, Declaw records lifecycle, network, command, filesystem,
+ * snapshot, and security events. Set `enabled: false` to suppress all
+ * gated categories; only lifecycle and admin events are still recorded.
  *
  * Retention is a platform-wide setting (global 7-day default), not a
  * per-sandbox knob. Body logging is not user-configurable today.
@@ -343,6 +342,62 @@ declare function parseInvisibleTextConfig(data: Record<string, unknown>): Invisi
 /** Serialize an InvisibleTextConfig to a JSON-friendly object. */
 declare function invisibleTextConfigToJSON(config: InvisibleTextConfig): Record<string, unknown>;
 
+/**
+ * Custom OPA policy configuration for per-sandbox policy overrides.
+ */
+interface CustomPolicyConfig {
+    /** Enable custom policy evaluation for this sandbox. */
+    enabled: boolean;
+    /**
+     * Customer-supplied Rego code appended to platform defaults.
+     *
+     * Example:
+     *   deny_command contains msg if {
+     *     input.action.command in {"rm", "dd"}
+     *     msg := "dangerous command blocked"
+     *   }
+     */
+    inlineRego?: string;
+    /**
+     * Additional independent Rego modules, each with its own `package` declaration.
+     *
+     * Use when your policy spans multiple packages (e.g. a `cmd` package and a
+     * `network` package) that need to cross-reference each other. Each entry is
+     * compiled as a separate OPA module alongside `inlineRego`.
+     */
+    inlineModules?: string[];
+    /** Future: reference to a bundled policy (URL, policy ID, version hash). */
+    policyRef?: string;
+    /**
+     * When the evaluator is unreachable, deny (true) or allow (false).
+     *
+     * Fail-closed (defaultDeny=true) is safer for security gates.
+     * Fail-open (defaultDeny=false) is acceptable for advisory scanners.
+     */
+    defaultDeny?: boolean;
+}
+
+/** Configuration for the content.scan OPA gate (model/endpoint allowlist).
+ *
+ * Opts a sandbox into content-gate enforcement without requiring an ML
+ * scanner.  {@link enabled} defaults to false (gate off).  {@link domains}
+ * is an optional list of hosts to intercept; omit or leave undefined to
+ * intercept none.
+ */
+interface ContentGateConfig {
+    enabled: boolean;
+    /** Optional list of hosts to intercept. Undefined = none. */
+    domains?: string[];
+}
+/**
+ * Create a ContentGateConfig with defaults.
+ */
+declare function createContentGateConfig(opts?: Partial<ContentGateConfig>): ContentGateConfig;
+/** Parse raw JSON data into ContentGateConfig. */
+declare function parseContentGateConfig(data: Record<string, unknown>): ContentGateConfig;
+/** Serialize a ContentGateConfig to a JSON-friendly object. */
+declare function contentGateConfigToJSON(config: ContentGateConfig): Record<string, unknown>;
+
 /** The top-level security policy for a sandbox. */
 interface SecurityPolicy {
     pii: PIIConfig;
@@ -354,6 +409,8 @@ interface SecurityPolicy {
     toxicity?: ToxicityConfig;
     codeSecurity?: CodeSecurityConfig;
     invisibleText?: InvisibleTextConfig;
+    contentGate?: ContentGateConfig;
+    customPolicy?: CustomPolicyConfig;
 }
 /**
  * Create a SecurityPolicy with defaults.
@@ -992,10 +1049,24 @@ declare class Stdio {
     start(cmd: string, opts?: StdioStartOpts): Promise<StdioProcess>;
 }
 
+/** Live-mount / copy mode for a volume attachment on Sandbox.create. */
+type VolumeAttachMode = 'copy' | 'mount' | 'mount-ro';
 /** Request-side shape of a volume attachment on Sandbox.create. */
 interface VolumeAttachment {
     volumeId: string;
     mountPath: string;
+    /**
+     * Attach mode. `copy` (default) hydrates the volume into the sandbox
+     * filesystem at boot. `mount` is a read-write live NFS mount; `mount-ro`
+     * is a read-only live mount. Omitted from the wire when unset (server
+     * defaults to copy).
+     */
+    mode?: VolumeAttachMode;
+    /**
+     * Relative path within the volume to mount. LIVE-MOUNT ONLY — the server
+     * rejects a subpath on a copy-mode attachment.
+     */
+    subpath?: string;
 }
 /** Server-side metadata for a single volume. */
 interface VolumeInfo {
@@ -1007,9 +1078,48 @@ interface VolumeInfo {
     contentType: string;
     metadata: Record<string, string>;
     createdAt: string;
+    /** Storage backend ("tarball" or a file-granular backend). */
+    backend: string;
+    /** Per-volume quota in bytes (0 = unset/unlimited). */
+    quotaBytes: number;
+    /** Last-modified timestamp (ISO 8601). */
+    updatedAt: string;
+}
+/** A single directory entry inside a file-granular volume (volumefs.Entry). */
+interface FileEntry {
+    name: string;
+    path: string;
+    isDir: boolean;
+    size: number;
+    modTime: string;
+    mode: number;
+}
+/** A file entry plus the CAS token returned by `info`/`stat`. */
+interface FileInfo extends FileEntry {
+    /** CAS token to round-trip into a conditional write's `ifVersion`. */
+    version: string;
+}
+/** Result of acquiring or renewing a lock. */
+interface LockLease {
+    token: string;
+    ttlSeconds: number;
+    expiresAt: string;
+}
+/** Result of querying lock status. */
+interface LockStatus {
+    held: boolean;
+    expiresInMs: number;
 }
 /** Convert a wire-format volume row into a VolumeInfo. */
 declare function parseVolumeInfo(data: Record<string, unknown>): VolumeInfo;
+/** Convert a wire-format file entry into a FileEntry. */
+declare function parseFileEntry(data: Record<string, unknown>): FileEntry;
+/** Convert a wire-format stat response into a FileInfo (FileEntry + version). */
+declare function parseFileInfo(data: Record<string, unknown>): FileInfo;
+/** Convert a wire-format lock lease into a LockLease. */
+declare function parseLockLease(data: Record<string, unknown>): LockLease;
+/** Convert a wire-format lock status into a LockStatus. */
+declare function parseLockStatus(data: Record<string, unknown>): LockStatus;
 /** Render a VolumeAttachment in wire (snake_case) form. */
 declare function volumeAttachmentToJSON(att: VolumeAttachment): Record<string, string>;
 
@@ -1375,6 +1485,20 @@ declare class NotEnoughSpaceError extends SandboxError {
         sandboxId?: string;
     });
 }
+/**
+ * Thrown on an HTTP 409 conflict.
+ *
+ * For volume file writes this signals a CAS (compare-and-swap) version
+ * mismatch — the file changed since the `if_version` token was read. For
+ * volume locks it signals the lock is already held by another holder (on
+ * acquire) or that the caller is not the current holder (on release/renew).
+ * Catch this to re-read and retry.
+ */
+declare class ConflictError extends SandboxError {
+    constructor(message: string, opts?: {
+        sandboxId?: string;
+    });
+}
 /** Thrown for template-related errors. */
 declare class TemplateError extends SandboxError {
     constructor(message: string, opts?: {
@@ -1591,35 +1715,226 @@ declare class Template {
     static getBuildStatus(buildId: string, opts?: GetBuildStatusOpts): Promise<TemplateBuildStatus>;
 }
 
-/** Shared per-call options. */
+/** Shared per-call options for volume operations. */
 interface VolumeRequestOpts {
     apiKey?: string;
     domain?: string;
     apiUrl?: string;
     requestTimeout?: number;
 }
-/** Options for Volumes.create. */
+
+/** Options for VolumeFiles.write. */
+interface VolumeWriteOpts extends VolumeRequestOpts {
+    /**
+     * CAS token from `info(path).version`. When set, the server rejects the
+     * write with a ConflictError (409) if the file changed since the token was
+     * read. Omit for an unconditional write.
+     */
+    ifVersion?: string;
+}
+/** Options for VolumeFiles.remove. */
+interface VolumeRemoveOpts extends VolumeRequestOpts {
+    /** Recursively remove a directory and its contents. */
+    recursive?: boolean;
+}
+/**
+ * File-granular operations on a single volume.
+ *
+ * Only valid for file-granular (non-tarball) volumes — the server returns
+ * a ConflictError (409) for a tarball-backed volume and a 503 when no
+ * file-granular accessor is configured. Obtain an instance via
+ * `Volumes.files(volumeId)`.
+ */
+declare class VolumeFiles {
+    private readonly volumeId;
+    private readonly opts?;
+    constructor(volumeId: string, opts?: VolumeRequestOpts);
+    private client;
+    private timeout;
+    /** Write raw bytes to `path`. Optionally conditional on `ifVersion` (CAS). */
+    write(path: string, data: Uint8Array | ArrayBuffer, opts?: VolumeWriteOpts): Promise<string>;
+    /** Read raw bytes from `path`. */
+    read(path: string): Promise<Uint8Array>;
+    /** List directory entries under `path`. */
+    list(path: string): Promise<FileEntry[]>;
+    /** Stat `path`, returning the entry plus the CAS `version` token. */
+    info(path: string): Promise<FileInfo>;
+    /** Return whether `path` exists. */
+    exists(path: string): Promise<boolean>;
+    /** Remove `path`. Pass `{ recursive: true }` to remove a directory tree. */
+    remove(path: string, opts?: VolumeRemoveOpts): Promise<void>;
+    /** Rename `oldPath` to `newPath`. */
+    rename(oldPath: string, newPath: string): Promise<{
+        oldPath: string;
+        newPath: string;
+    }>;
+    /** Create a directory at `path`. */
+    mkdir(path: string): Promise<string>;
+}
+
+/**
+ * Advisory locks (leases) over a (volume, path) pair.
+ *
+ * Acquire returns a token; renew/release require it. A ConflictError (409)
+ * is raised on acquire when the path is already locked, and on renew/release
+ * when the caller is not the current holder. Obtain an instance via
+ * `Volumes.locks(volumeId)`.
+ */
+declare class VolumeLocks {
+    private readonly volumeId;
+    private readonly opts?;
+    constructor(volumeId: string, opts?: VolumeRequestOpts);
+    private client;
+    private timeout;
+    /** Acquire a lock on `path`. Throws ConflictError (409) if already held. */
+    acquire(path: string, ttlSeconds?: number): Promise<LockLease>;
+    /** Release a lock on `path` held under `token`. Throws ConflictError (409) if not the holder. */
+    release(path: string, token: string): Promise<boolean>;
+    /** Renew a lock on `path` held under `token`. Throws ConflictError (409) if not the holder. */
+    renew(path: string, token: string, ttlSeconds?: number): Promise<LockLease>;
+    /** Query whether `path` is currently locked. */
+    status(path: string): Promise<LockStatus>;
+}
+
+/** Options for Volumes.create / ingest. */
 interface VolumeCreateOpts extends VolumeRequestOpts {
     /** Override the Content-Type header. Defaults to application/gzip. */
     contentType?: string;
 }
 /**
- * Volumes: upload a tarball once and attach it to one or many sandboxes.
+ * Volumes: upload a tarball once and attach it to one or many sandboxes,
+ * or create file-granular volumes that support per-file read/write,
+ * compare-and-swap (CAS), and advisory locks.
  *
- * Phase 1: the body must be a gzip-compressed tar archive; the server
- * materializes regular-file entries inside the sandbox filesystem under
- * the attachment's mount_path. Symlinks, hardlinks, and device nodes
+ * Phase 1 (tarball backend): the body must be a gzip-compressed tar archive;
+ * the server materializes regular-file entries inside the sandbox filesystem
+ * under the attachment's mount_path. Symlinks, hardlinks, and device nodes
  * are dropped on the server for safety.
  */
 declare class Volumes {
-    /** Create a volume by streaming a tarball to the server. */
+    /** Create a volume by streaming a tarball (gzip tar.gz) to the server. */
     static create(name: string, data: Uint8Array | ArrayBuffer, opts?: VolumeCreateOpts): Promise<VolumeInfo>;
+    /**
+     * Capture the attached volume's mount path in `sandboxId` into a NEW volume.
+     *
+     * The source volume is left unchanged. If `name` is omitted the server names
+     * the new volume "<source-name>-commit". Returns the new VolumeInfo.
+     */
+    static commit(sandboxId: string, volumeId: string, name?: string, opts?: VolumeRequestOpts): Promise<VolumeInfo>;
+    /**
+     * Snapshot an arbitrary absolute in-sandbox `path` into a NEW volume.
+     *
+     * Unlike `commit` (which captures an already-attached volume's mount path),
+     * `snapshot` captures any path in the running sandbox. `name` defaults to
+     * "snapshot" on the server. Synthetic paths (/proc, /sys, /dev) are rejected.
+     */
+    static snapshot(sandboxId: string, path: string, name?: string, opts?: VolumeRequestOpts): Promise<VolumeInfo>;
+    /**
+     * Create an empty file-granular volume. Requires a file-granular backend
+     * (503 if not configured). Returns the new VolumeInfo.
+     */
+    static empty(name: string, opts?: VolumeRequestOpts): Promise<VolumeInfo>;
+    /**
+     * Ingest a gzip tar.gz archive into a NEW file-granular volume. Requires a
+     * file-granular backend (503 if not configured). 413 on quota exceeded.
+     */
+    static ingest(name: string, data: Uint8Array | ArrayBuffer, opts?: VolumeCreateOpts): Promise<VolumeInfo>;
     /** Fetch metadata for a single volume. */
     static get(volumeId: string, opts?: VolumeRequestOpts): Promise<VolumeInfo>;
     /** List all volumes owned by the caller, newest first. */
     static list(opts?: VolumeRequestOpts): Promise<VolumeInfo[]>;
+    /** Download the volume's contents as raw bytes (the stored archive/blob). */
+    static download(volumeId: string, opts?: VolumeRequestOpts): Promise<Uint8Array>;
     /** Delete a volume and its blob. Idempotent on the wire. */
     static delete(volumeId: string, opts?: VolumeRequestOpts): Promise<void>;
+    /**
+     * File-granular operations (read/write/list/info/exists/remove/rename/mkdir,
+     * plus CAS via `write(..., { ifVersion })`) on `volumeId`. File-granular
+     * volumes only.
+     */
+    static files(volumeId: string, opts?: VolumeRequestOpts): VolumeFiles;
+    /** Advisory locks (acquire/release/renew/status) over a (volume, path). */
+    static locks(volumeId: string, opts?: VolumeRequestOpts): VolumeLocks;
+}
+
+/** A single enforced control within a governance pack gate. */
+interface GovernanceControl {
+    /** Control identifier, e.g. "OWASP-LLM06-ExcessiveAgency". */
+    control: string;
+    /** Gate that enforces this control: "cmd", "network", or "content". */
+    gate: string;
+    /** Human-readable rule description. */
+    rule: string;
+    /** Remediation playbook / guidance. */
+    playbook: string;
+}
+/** An advisory (non-enforced) item within a governance pack. */
+interface GovernanceAdvisory {
+    /** Control identifier this advisory references. */
+    control: string;
+    /** Explanation of why this control is advisory rather than enforced. */
+    reason: string;
+}
+/** A governance pack returned by GET /governance/packs or GET /governance/packs/:name. */
+interface GovernancePack {
+    /** Pack name / slug, e.g. "owasp-llm-top10". */
+    name: string;
+    /** Pack version string, e.g. "v1". */
+    version: string;
+    /** Full framework name, e.g. "OWASP Top 10 for LLM Applications (2025)". */
+    framework: string;
+    /** Human-readable description of what this pack enforces. */
+    description: string;
+    /** Gates activated by this pack, e.g. ["cmd","network","content"]. */
+    gates: string[];
+    /** Enforced controls within this pack. */
+    enforces: GovernanceControl[];
+    /** Advisory (non-enforced) controls within this pack. */
+    advisory: GovernanceAdvisory[];
+    /**
+     * Canonical policy reference string, e.g. "owasp-llm-top10@v1".
+     * Mapped from wire field `policy_ref`.
+     */
+    policyRef: string;
+    /** Whether this pack was seeded (built-in) vs. user-created. */
+    seeded: boolean;
+}
+/** Parse a raw wire-format pack row into a GovernancePack. */
+declare function parseGovernancePack(data: Record<string, unknown>): GovernancePack;
+
+/** Shared per-call options for Governance methods. */
+interface GovernanceRequestOpts {
+    /** API key override. */
+    apiKey?: string;
+    /** Domain override. */
+    domain?: string;
+    /** Full API URL override. */
+    apiUrl?: string;
+    /** Per-request timeout in milliseconds. */
+    requestTimeout?: number;
+}
+/**
+ * Governance pack discovery.
+ *
+ * Lists and retrieves governance packs exposed by the Declaw control plane.
+ * The /governance/packs endpoint is public — no auth is required — but the
+ * SDK's normal Authorization header is still sent when an API key is
+ * configured (harmless and consistent with other list methods).
+ */
+declare class Governance {
+    /**
+     * List all available governance packs.
+     *
+     * Sends GET /governance/packs and returns the `packs` array.
+     */
+    static listPacks(opts?: GovernanceRequestOpts): Promise<GovernancePack[]>;
+    /**
+     * Fetch a single governance pack by name.
+     *
+     * Sends GET /governance/packs/:name and returns the pack object.
+     * Throws InvalidArgumentError if the name contains unsafe characters.
+     */
+    static getPack(name: string, opts?: GovernanceRequestOpts): Promise<GovernancePack>;
 }
 
-export { ALL_TRAFFIC, ApiClient, type AuditConfig, type AuditEntry, AuthenticationError, BuildError, type BuildInfo, type CodeSecurityConfig, CommandExitError, CommandHandle, type CommandResult, type CommandWaitOpts, Commands, ConnectionConfig, type ConnectionConfigOptions, type CopyItem, DEFAULT_MASK_PATTERNS, type EntryInfo, type EnvSecurityConfig, FileType, FileUploadError, Filesystem, type FilesystemEvent, FilesystemEventType, type GetBuildStatusOpts, GitAuthError, GitUpstreamError, InjectionAction, type InjectionDefenseConfig, InjectionSensitivity, InvalidArgumentError, type InvisibleTextConfig, type NetworkPolicy, NotEnoughSpaceError, NotFoundError, type PIIConfig, PIIType, type ProcessInfo, Pty, type PtyConnectOpts, type PtyCreateOpts, PtyHandle, type PtyOutput, type PtyResult, type PtySize, RedactionAction, type RequestOpts, type RunOpts, type RunStreamOpts, Sandbox, SandboxError, type SandboxInfo, type SandboxLifecycle, type SandboxMetrics, type SandboxNetworkOpts, type SandboxOpts, SandboxPaginator, type SandboxQuery, SandboxState, type SecureEnvVar, type SecurityPolicy, type Snapshot, type SnapshotInfo, SnapshotPaginator, type SnapshotSource, type Stderr, Stdio, StdioProcess, type StdioResult, type StdioStartOpts, type Stdout, Template, TemplateBase, type TemplateBuildOpts, type TemplateBuildStatus, TemplateError, TimeoutError, type ToxicityConfig, TransformDirection, type TransformationRule, type VolumeAttachment, type VolumeCreateOpts, type VolumeInfo, type VolumeRequestOpts, Volumes, WatchHandle, type WriteEntry, type WriteInfo, applyTransformation, codeSecurityConfigToJSON, createAuditConfig, createCodeSecurityConfig, createEnvSecurityConfig, createInjectionDefenseConfig, createInvisibleTextConfig, createNetworkPolicy, createPIIConfig, createSecurityPolicy, createToxicityConfig, createTransformationRule, domainMatches, getSharedClient, invisibleTextConfigToJSON, isSensitive, networkPolicyToOpts, parseAuditConfig, parseAuditEntry, parseBuildInfo, parseCodeSecurityConfig, parseCommandResult, parseEntryInfo, parseEnvSecurityConfig, parseFilesystemEvent, parseInjectionDefenseConfig, parseInvisibleTextConfig, parseNetworkPolicy, parsePIIConfig, parseProcessInfo, parseSandboxInfo, parseSandboxLifecycle, parseSandboxMetrics, parseSecurityPolicy, parseSnapshot, parseSnapshotInfo, parseTemplateBuildStatus, parseToxicityConfig, parseVolumeInfo, parseWriteInfo, requiresTlsInterception, resetSharedClients, securityPolicyToJSON, toxicityConfigToJSON, validateNetworkEntry, volumeAttachmentToJSON };
+export { ALL_TRAFFIC, ApiClient, type AuditConfig, type AuditEntry, AuthenticationError, BuildError, type BuildInfo, type CodeSecurityConfig, CommandExitError, CommandHandle, type CommandResult, type CommandWaitOpts, Commands, ConflictError, ConnectionConfig, type ConnectionConfigOptions, type ContentGateConfig, type CopyItem, DEFAULT_MASK_PATTERNS, type EntryInfo, type EnvSecurityConfig, type FileEntry, type FileInfo, FileType, FileUploadError, Filesystem, type FilesystemEvent, FilesystemEventType, type GetBuildStatusOpts, GitAuthError, GitUpstreamError, Governance, type GovernanceAdvisory, type GovernanceControl, type GovernancePack, type GovernanceRequestOpts, InjectionAction, type InjectionDefenseConfig, InjectionSensitivity, InvalidArgumentError, type InvisibleTextConfig, type LockLease, type LockStatus, type NetworkPolicy, NotEnoughSpaceError, NotFoundError, type PIIConfig, PIIType, type ProcessInfo, Pty, type PtyConnectOpts, type PtyCreateOpts, PtyHandle, type PtyOutput, type PtyResult, type PtySize, RedactionAction, type RequestOpts, type RunOpts, type RunStreamOpts, Sandbox, SandboxError, type SandboxInfo, type SandboxLifecycle, type SandboxMetrics, type SandboxNetworkOpts, type SandboxOpts, SandboxPaginator, type SandboxQuery, SandboxState, type SecureEnvVar, type SecurityPolicy, type Snapshot, type SnapshotInfo, SnapshotPaginator, type SnapshotSource, type Stderr, Stdio, StdioProcess, type StdioResult, type StdioStartOpts, type Stdout, Template, TemplateBase, type TemplateBuildOpts, type TemplateBuildStatus, TemplateError, TimeoutError, type ToxicityConfig, TransformDirection, type TransformationRule, type VolumeAttachMode, type VolumeAttachment, type VolumeCreateOpts, VolumeFiles, type VolumeInfo, VolumeLocks, type VolumeRemoveOpts, type VolumeRequestOpts, type VolumeWriteOpts, Volumes, WatchHandle, type WriteEntry, type WriteInfo, applyTransformation, codeSecurityConfigToJSON, contentGateConfigToJSON, createAuditConfig, createCodeSecurityConfig, createContentGateConfig, createEnvSecurityConfig, createInjectionDefenseConfig, createInvisibleTextConfig, createNetworkPolicy, createPIIConfig, createSecurityPolicy, createToxicityConfig, createTransformationRule, domainMatches, getSharedClient, invisibleTextConfigToJSON, isSensitive, networkPolicyToOpts, parseAuditConfig, parseAuditEntry, parseBuildInfo, parseCodeSecurityConfig, parseCommandResult, parseContentGateConfig, parseEntryInfo, parseEnvSecurityConfig, parseFileEntry, parseFileInfo, parseFilesystemEvent, parseGovernancePack, parseInjectionDefenseConfig, parseInvisibleTextConfig, parseLockLease, parseLockStatus, parseNetworkPolicy, parsePIIConfig, parseProcessInfo, parseSandboxInfo, parseSandboxLifecycle, parseSandboxMetrics, parseSecurityPolicy, parseSnapshot, parseSnapshotInfo, parseTemplateBuildStatus, parseToxicityConfig, parseVolumeInfo, parseWriteInfo, requiresTlsInterception, resetSharedClients, securityPolicyToJSON, toxicityConfigToJSON, validateNetworkEntry, volumeAttachmentToJSON };