@nahisaho/katashiro-sandbox 0.4.0

package/README.md

@@ -0,0 +1,213 @@
+# @nahisaho/katashiro-sandbox
+
+コード実行サンドボックスパッケージ。Docker/ローカル環境でbash, Python, JavaScript/TypeScriptを安全に実行します。
+
+## 概要
+
+KATASHIRO v0.4.0で追加された、コード実行のための隔離環境を提供するパッケージです。
+
+### 主な機能
+
+- **Docker実行**: Dockerコンテナ内での安全なコード実行
+- **ローカル実行**: 開発/テスト用のローカル環境実行
+- **複数言語サポート**: bash, Python, JavaScript, TypeScript
+- **リソース制限**: メモリ、CPU、タイムアウト制限
+- **セキュリティポリシー**: システムコール制限、ケーパビリティ削除
+
+## インストール
+
+```bash
+npm install @nahisaho/katashiro-sandbox
+```
+
+## 基本的な使い方
+
+### 簡易関数
+
+```typescript
+import { executePython, executeBash, executeJavaScript } from '@nahisaho/katashiro-sandbox';
+
+// Pythonコード実行
+const result = await executePython('print("Hello, World!")');
+if (result.isOk()) {
+  console.log(result.value.stdout); // "Hello, World!\n"
+}
+
+// Bashスクリプト実行
+const bashResult = await executeBash('echo "Hello from bash"');
+
+// JavaScript実行
+const jsResult = await executeJavaScript('console.log(1 + 2)');
+```
+
+### SandboxFactoryを使用
+
+```typescript
+import { SandboxFactory } from '@nahisaho/katashiro-sandbox';
+
+// Dockerサンドボックスを作成
+const sandbox = SandboxFactory.create({ timeout: 60 }, 'docker');
+
+// コード実行
+const result = await sandbox.execute('print(sum(range(100)))', 'python');
+
+// イベントリスナー
+sandbox.on('execution:start', (event) => {
+  console.log(`開始: ${event.requestId}`);
+});
+
+sandbox.on('execution:complete', (event) => {
+  console.log(`完了: ${event.requestId}`);
+});
+
+// クリーンアップ
+await sandbox.cleanup();
+```
+
+### 自動ランタイム検出
+
+```typescript
+import { SandboxFactory } from '@nahisaho/katashiro-sandbox';
+
+// Dockerが利用可能ならDocker、そうでなければローカル実行
+const sandbox = await SandboxFactory.createAuto({ timeout: 30 });
+```
+
+## 設定
+
+### SandboxConfig
+
+```typescript
+interface SandboxConfig {
+  runtime: 'docker' | 'local' | 'wasm';  // ランタイム
+  timeout: number;           // タイムアウト（秒）
+  memoryLimit: number;       // メモリ制限（バイト）
+  cpuLimit: number;          // CPU制限（0.0-1.0）
+  workingDir: string;        // 作業ディレクトリ
+  networkEnabled: boolean;   // ネットワークアクセス
+  tmpfsSize: number;         // 一時ファイルシステムサイズ
+}
+```
+
+### デフォルト設定
+
+```typescript
+const DEFAULT_SANDBOX_CONFIG = {
+  runtime: 'docker',
+  timeout: 30,
+  memoryLimit: 512 * 1024 * 1024,  // 512MB
+  cpuLimit: 0.5,
+  workingDir: '/workspace',
+  networkEnabled: false,
+  tmpfsSize: 64 * 1024 * 1024,  // 64MB
+};
+```
+
+## Docker Executor
+
+### 特徴
+
+- **完全な隔離**: コンテナ内でコードを実行
+- **リソース制限**: メモリ・CPU制限を強制
+- **セキュリティ**: ケーパビリティ削除、seccompプロファイル
+- **自動クリーンアップ**: 実行後にコンテナを自動削除
+
+### 使用するDockerイメージ
+
+| 言語 | デフォルトイメージ |
+|------|-------------------|
+| bash | alpine:3.19 |
+| python | python:3.12-slim |
+| javascript | node:22-slim |
+| typescript | node:22-slim |
+
+### カスタムイメージの使用
+
+```typescript
+import { DockerExecutor } from '@nahisaho/katashiro-sandbox';
+
+const executor = new DockerExecutor(
+  { timeout: 60 },
+  {
+    images: {
+      bash: 'ubuntu:22.04',
+      python: 'python:3.11-alpine',
+      javascript: 'node:20-alpine',
+      typescript: 'node:20-alpine',
+    }
+  }
+);
+```
+
+## Local Executor
+
+### 注意
+
+Local Executorはホストシステムで直接コードを実行するため、**本番環境では使用しないでください**。開発とテスト目的専用です。
+
+```typescript
+import { LocalExecutor } from '@nahisaho/katashiro-sandbox';
+
+const executor = new LocalExecutor({ timeout: 10 });
+const result = await executor.execute('console.log("test")', 'javascript');
+```
+
+## セキュリティポリシー
+
+```typescript
+interface SecurityPolicy {
+  blockedSyscalls: string[];    // ブロックするシステムコール
+  readOnlyPaths: string[];      // 読み取り専用パス
+  writablePaths: string[];      // 書き込み可能パス
+  maxProcesses: number;         // 最大プロセス数
+  maxOpenFiles: number;         // 最大ファイルディスクリプタ数
+}
+```
+
+### デフォルトポリシー
+
+```typescript
+const DEFAULT_SECURITY_POLICY = {
+  blockedSyscalls: ['ptrace', 'mount', 'umount', 'reboot', 'swapon', 'swapoff'],
+  readOnlyPaths: ['/etc', '/usr', '/bin', '/lib'],
+  writablePaths: ['/workspace', '/tmp'],
+  maxProcesses: 10,
+  maxOpenFiles: 100,
+};
+```
+
+## イベント
+
+```typescript
+sandbox.on('execution:start', (event) => { ... });
+sandbox.on('execution:output', (event) => { ... });
+sandbox.on('execution:complete', (event) => { ... });
+sandbox.on('execution:error', (event) => { ... });
+sandbox.on('execution:timeout', (event) => { ... });
+sandbox.on('container:create', (event) => { ... });
+sandbox.on('container:start', (event) => { ... });
+sandbox.on('container:stop', (event) => { ... });
+sandbox.on('security:violation', (event) => { ... });
+```
+
+## ExecutionResult
+
+```typescript
+interface ExecutionResult {
+  requestId: string;         // リクエストID
+  status: ExecutionStatus;   // 'completed' | 'failed' | 'timeout' | ...
+  exitCode: number;          // 終了コード
+  stdout: string;            // 標準出力
+  stderr: string;            // 標準エラー出力
+  duration: number;          // 実行時間（ミリ秒）
+  files: FileOutput[];       // 出力ファイル
+  memoryUsed?: number;       // メモリ使用量
+  cpuTime?: number;          // CPU使用時間
+  error?: ExecutionError;    // エラー詳細
+  completedAt: string;       // 完了日時
+}
+```
+
+## ライセンス
+
+MIT

package/dist/docker-executor.d.ts

@@ -0,0 +1,117 @@
+/**
+ * KATASHIRO Sandbox - Docker Executor Implementation
+ *
+ * @fileoverview REQ-007: Dockerベースのコード実行サンドボックス
+ * @module @nahisaho/katashiro-sandbox
+ * @since 0.4.0
+ */
+import { EventEmitter } from 'events';
+import { type Result } from '@nahisaho/katashiro-core';
+import type { SandboxConfig, DockerConfig, ExecutionRequest, ExecutionResult, SupportedLanguage, SecurityPolicy, SandboxEventType, SandboxEventListener, ContainerInfo, ResourceStats } from './types';
+/**
+ * サンドボックスエラー
+ */
+export declare class SandboxError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, details?: Record<string, unknown> | undefined);
+}
+/**
+ * Docker Executor
+ *
+ * EARS Requirements:
+ * - Ubiquitous: The Sandbox shall execute code in an isolated Docker/VM environment
+ * - Ubiquitous: The Sandbox shall support bash, Python, and JavaScript/TypeScript execution
+ * - Event-Driven: When execution time exceeds timeout, the Sandbox shall terminate
+ * - State-Driven: While code is executing, the Sandbox shall enforce CPU and memory limits
+ * - Unwanted: If code attempts to access host system, the Sandbox shall block the access
+ */
+export declare class DockerExecutor extends EventEmitter {
+    private readonly docker;
+    private readonly config;
+    private readonly dockerConfig;
+    private readonly securityPolicy;
+    private readonly activeContainers;
+    constructor(config?: Partial<SandboxConfig>, dockerConfig?: Partial<DockerConfig>, securityPolicy?: Partial<SecurityPolicy>);
+    /**
+     * 型安全なイベントリスナー登録
+     */
+    on(event: SandboxEventType, listener: SandboxEventListener): this;
+    /**
+     * イベント発火
+     */
+    private emitEvent;
+    /**
+     * コードを実行
+     *
+     * @param code 実行するコード
+     * @param language プログラミング言語
+     * @param options 追加オプション
+     */
+    execute(code: string, language: SupportedLanguage, options?: Partial<Pick<ExecutionRequest, 'stdin' | 'env' | 'timeout'>>): Promise<Result<ExecutionResult, SandboxError>>;
+    /**
+     * コンテナを作成
+     */
+    private createContainer;
+    /**
+     * 実行コマンドを構築
+     */
+    private buildCommand;
+    /**
+     * 言語に対応するファイル名を取得
+     */
+    private getCodeFileName;
+    /**
+     * 環境変数を構築
+     */
+    private buildEnv;
+    /**
+     * コードをコンテナにコピー
+     */
+    private copyCodeToContainer;
+    /**
+     * tarアーカイブを作成（簡易版）
+     */
+    private createTarArchive;
+    /**
+     * コンテナの完了を待機
+     */
+    private waitForCompletion;
+    /**
+     * Dockerログをパース
+     */
+    private parseLogs;
+    /**
+     * 出力ファイルを抽出
+     */
+    private extractOutputFiles;
+    /**
+     * コンテナをクリーンアップ
+     */
+    private cleanupContainer;
+    /**
+     * エラーをパース
+     */
+    private parseError;
+    /**
+     * アクティブなコンテナ数を取得
+     */
+    getActiveContainerCount(): number;
+    /**
+     * 指定した実行をキャンセル
+     */
+    cancel(requestId: string): Promise<boolean>;
+    /**
+     * 全アクティブコンテナをクリーンアップ
+     */
+    cleanup(): Promise<void>;
+    /**
+     * コンテナ情報を取得
+     */
+    getContainerInfo(requestId: string): Promise<ContainerInfo | null>;
+    /**
+     * リソース使用量を取得
+     */
+    getResourceStats(requestId: string): Promise<ResourceStats | null>;
+}
+//# sourceMappingURL=docker-executor.d.ts.map

package/dist/docker-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docker-executor.d.ts","sourceRoot":"","sources":["../src/docker-executor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAEtC,OAAO,EAAW,KAAK,MAAM,EAAc,MAAM,0BAA0B,CAAC;AAC5E,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,eAAe,EAGf,iBAAiB,EACjB,cAAc,EAEd,gBAAgB,EAChB,oBAAoB,EACpB,aAAa,EACb,aAAa,EACd,MAAM,SAAS,CAAC;AAWjB;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;aAGnB,IAAI,EAAE,MAAM;aACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAFjD,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;CAKpD;AAMD;;;;;;;;;GASG;AACH,qBAAa,cAAe,SAAQ,YAAY;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAChD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAuC;gBAGtE,MAAM,GAAE,OAAO,CAAC,aAAa,CAAM,EACnC,YAAY,GAAE,OAAO,CAAC,YAAY,CAAM,EACxC,cAAc,GAAE,OAAO,CAAC,cAAc,CAAM;IAc9C;;OAEG;IACH,EAAE,CAAC,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,oBAAoB,GAAG,IAAI;IAIjE;;OAEG;IACH,OAAO,CAAC,SAAS;IAYjB;;;;;;OAMG;IACG,OAAO,CACX,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,GAAE,OAAO,CAAC,IAAI,CAAC,gBAAgB,EAAE,OAAO,GAAG,KAAK,GAAG,SAAS,CAAC,CAAM,GACzE,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,YAAY,CAAC,CAAC;IAqGjD;;OAEG;YACW,eAAe;IAwD7B;;OAEG;IACH,OAAO,CAAC,YAAY;IA+BpB;;OAEG;IACH,OAAO,CAAC,eAAe;IAUvB;;OAEG;IACH,OAAO,CAAC,QAAQ;IAUhB;;OAEG;YACW,mBAAmB;IAajC;;OAEG;YACW,gBAAgB;IA0D9B;;OAEG;YACW,iBAAiB;IAmC/B;;OAEG;IACH,OAAO,CAAC,SAAS;IAoCjB;;OAEG;YACW,kBAAkB;IAQhC;;OAEG;YACW,gBAAgB;IAuB9B;;OAEG;IACH,OAAO,CAAC,UAAU;IAsBlB;;OAEG;IACH,uBAAuB,IAAI,MAAM;IAIjC;;OAEG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAcjD;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAW9B;;OAEG;IACG,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAoBxE;;OAEG;IACG,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;CAkEzE"}