110 lines
4.7 KiB
TypeScript
110 lines
4.7 KiB
TypeScript
/**
|
|
* The sandbox POLICY home (`ctx.sandboxPolicy`): the single owner of the
|
|
* deployment's sandbox fallbacks plus per-session resolution: the file-effect
|
|
* {@link SandboxMode}, the `workspace-write` root, and the override kit (the
|
|
* `sandbox/mode` event, its fold, and its write path, from `./session-mode.ts`).
|
|
*
|
|
* Both enforcing capability families read the SAME policy here: the sandboxed
|
|
* bash executor (`@deepseek-ai/dsh-bash-sandbox`) and the sandboxed filesystem
|
|
* provider (`@deepseek-ai/dsh-fs-sandbox`) consume the SAME resolved per-call
|
|
* policy, so bash and fs can never confine to different roots — the split
|
|
* world the sandbox RFC warns about. The service reads session state once at
|
|
* the tool boundary; executors and providers remain session-free.
|
|
*
|
|
* @module @deepseek-ai/dsh-sandbox-policy
|
|
*/
|
|
|
|
import { resolve as resolvePath } from 'node:path'
|
|
import { Context, Service } from 'cordis'
|
|
import z from 'schemastery'
|
|
import { canonicalPath, type SandboxExecutionPolicy, type SandboxMode } from '@deepseek-ai/dsh-sandbox'
|
|
import type { Session } from '@deepseek-ai/dsh-session'
|
|
import { effectiveSandboxMode } from './session-mode.ts'
|
|
|
|
export { SANDBOX_MODES, effectiveSandboxMode, setSandboxMode } from './session-mode.ts'
|
|
|
|
/** Resolve filesystem identity before lexical normalization can erase symlink-sensitive components. */
|
|
function resolveWorkspaceRoot(path: string): string {
|
|
return resolvePath(canonicalPath(path))
|
|
}
|
|
|
|
declare module 'cordis' {
|
|
interface Context {
|
|
sandboxPolicy: SandboxPolicyService
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Plugin config: the deployment's sandbox default. All optional — `Config`
|
|
* supplies the defaults (`mode: 'read-only'` is the fail-safe default; a
|
|
* deployment that wants a workspace-writable agent opts in explicitly). The
|
|
* runner choice is NOT here (it is the `ctx.sandbox` provider's config), nor
|
|
* is any per-family knob: this is the one shared policy home.
|
|
*/
|
|
export interface Config {
|
|
/** File-sandbox mode a session starts from (default: `read-only`). */
|
|
mode?: SandboxMode
|
|
/**
|
|
* Fallback root for agentless calls and sessions without a cwd (default:
|
|
* `process.cwd()`). Normal agent calls use their session cwd instead.
|
|
*/
|
|
workspaceRoot?: string
|
|
}
|
|
|
|
/** Inputs that select the sandbox policy for one capability call. */
|
|
export interface SandboxPolicyRequest {
|
|
/** Calling session; its immutable cwd becomes the workspace boundary. */
|
|
session?: Session
|
|
/** Explicit approved mode override, which outranks session policy. */
|
|
mode?: SandboxMode
|
|
}
|
|
|
|
/**
|
|
* The sandbox-policy service (`ctx.sandboxPolicy`). Owns the deployment
|
|
* default mode and fallback workspace root. Tool layers call {@link resolve}
|
|
* for each execution so a session's mode log and immutable cwd travel together
|
|
* to every enforcing capability.
|
|
*/
|
|
export class SandboxPolicyService extends Service {
|
|
// Inline schema call: the config catalog walks `static Config` statically.
|
|
static Config: z<Config> = z.object({
|
|
mode: z.union(['read-only', 'workspace-write', 'danger-full-access'] as const).default('read-only'),
|
|
// No schema default: process.cwd() is resolved in the constructor so the
|
|
// stored root is always absolute regardless of how it was supplied.
|
|
workspaceRoot: z.string(),
|
|
})
|
|
|
|
/** The deployment default mode — the fallback beneath a session override. */
|
|
readonly defaultMode: SandboxMode
|
|
/** The absolute `workspace-write` fallback root for calls without a session cwd. */
|
|
readonly workspaceRoot: string
|
|
|
|
constructor(ctx: Context, config: Config) {
|
|
super(ctx, 'sandboxPolicy')
|
|
// schemastery (static Config) already filled `mode`; the cast records that
|
|
// runtime fact. `workspaceRoot` has NO schema default, so its fallback to
|
|
// the process cwd is real branching, resolved absolute either way.
|
|
this.defaultMode = config.mode as SandboxMode
|
|
this.workspaceRoot = resolveWorkspaceRoot(config.workspaceRoot ?? process.cwd())
|
|
}
|
|
|
|
/**
|
|
* Resolve the complete policy for one capability call. An approved explicit
|
|
* mode outranks the session's last `sandbox/mode` event, which outranks the
|
|
* deployment default. A session cwd is its workspace-write boundary; the
|
|
* configured root is the fallback for agentless calls and sessions without a
|
|
* cwd.
|
|
* @param request - optional session and approved mode override.
|
|
* @returns the fully resolved per-call mode and absolute workspace root.
|
|
*/
|
|
resolve(request: SandboxPolicyRequest = {}): SandboxExecutionPolicy {
|
|
const { session } = request
|
|
return {
|
|
mode: request.mode ?? (session === undefined ? undefined : effectiveSandboxMode(session.events)) ?? this.defaultMode,
|
|
workspaceRoot: resolveWorkspaceRoot(session?.header.cwd ?? this.workspaceRoot),
|
|
}
|
|
}
|
|
}
|
|
|
|
export default SandboxPolicyService
|