@nahisaho/katashiro-sandbox 0.4.0

package/dist/types.d.ts

@@ -0,0 +1,228 @@
+/**
+ * KATASHIRO Sandbox - Type Definitions
+ *
+ * @fileoverview REQ-007: コード実行サンドボックスの型定義
+ * @module @nahisaho/katashiro-sandbox
+ * @since 0.4.0
+ */
+import type { ID, Timestamp } from '@nahisaho/katashiro-core';
+/**
+ * サンドボックスランタイム
+ */
+export type SandboxRuntime = 'docker' | 'local' | 'wasm';
+/**
+ * サポートされるプログラミング言語
+ */
+export type SupportedLanguage = 'bash' | 'python' | 'javascript' | 'typescript';
+/**
+ * 実行状態
+ */
+export type ExecutionStatus = 'pending' | 'running' | 'completed' | 'failed' | 'timeout' | 'cancelled';
+/**
+ * サンドボックス設定
+ * EARS: The Sandbox shall execute code in an isolated Docker/VM environment
+ */
+export interface SandboxConfig {
+    /** ランタイム種別 */
+    readonly runtime: SandboxRuntime;
+    /** タイムアウト（秒） */
+    readonly timeout: number;
+    /** メモリ制限（バイト） */
+    readonly memoryLimit: number;
+    /** CPU制限（0.0-1.0 = 100%） */
+    readonly cpuLimit: number;
+    /** 作業ディレクトリ */
+    readonly workingDir: string;
+    /** ネットワークアクセス許可 */
+    readonly networkEnabled: boolean;
+    /** 一時ファイルシステムサイズ（バイト） */
+    readonly tmpfsSize: number;
+}
+/**
+ * デフォルトサンドボックス設定
+ */
+export declare const DEFAULT_SANDBOX_CONFIG: SandboxConfig;
+/**
+ * Docker固有の設定
+ */
+export interface DockerConfig {
+    /** Dockerデーモンソケットパス */
+    readonly socketPath?: string;
+    /** Dockerホスト（TCP接続時） */
+    readonly host?: string;
+    /** 使用するイメージ（言語別） */
+    readonly images: Record<SupportedLanguage, string>;
+    /** コンテナ自動削除 */
+    readonly autoRemove: boolean;
+    /** コンテナ名プレフィックス */
+    readonly containerPrefix: string;
+}
+/**
+ * デフォルトDockerイメージ
+ */
+export declare const DEFAULT_DOCKER_IMAGES: Record<SupportedLanguage, string>;
+/**
+ * デフォルトDocker設定
+ */
+export declare const DEFAULT_DOCKER_CONFIG: DockerConfig;
+/**
+ * コード実行リクエスト
+ */
+export interface ExecutionRequest {
+    /** リクエストID */
+    readonly id: ID;
+    /** 実行するコード */
+    readonly code: string;
+    /** 言語 */
+    readonly language: SupportedLanguage;
+    /** 入力データ（stdin） */
+    readonly stdin?: string;
+    /** 環境変数 */
+    readonly env?: Record<string, string>;
+    /** タイムアウト上書き（秒） */
+    readonly timeout?: number;
+    /** リクエスト日時 */
+    readonly createdAt: Timestamp;
+}
+/**
+ * ファイル出力
+ */
+export interface FileOutput {
+    /** ファイルパス（コンテナ内） */
+    readonly path: string;
+    /** ファイル内容 */
+    readonly content: string | Buffer;
+    /** ファイルサイズ（バイト） */
+    readonly size: number;
+    /** MIMEタイプ */
+    readonly mimeType?: string;
+}
+/**
+ * 実行結果
+ * EARS: The Sandbox shall provide a temporary file system for code execution
+ */
+export interface ExecutionResult {
+    /** リクエストID */
+    readonly requestId: ID;
+    /** 実行ステータス */
+    readonly status: ExecutionStatus;
+    /** 終了コード */
+    readonly exitCode: number;
+    /** 標準出力 */
+    readonly stdout: string;
+    /** 標準エラー出力 */
+    readonly stderr: string;
+    /** 実行時間（ミリ秒） */
+    readonly duration: number;
+    /** 出力ファイル */
+    readonly files: readonly FileOutput[];
+    /** メモリ使用量（バイト） */
+    readonly memoryUsed?: number;
+    /** CPU使用時間（ミリ秒） */
+    readonly cpuTime?: number;
+    /** エラー詳細（失敗時） */
+    readonly error?: ExecutionError;
+    /** 完了日時 */
+    readonly completedAt: Timestamp;
+}
+/**
+ * 実行エラー
+ */
+export interface ExecutionError {
+    /** エラーコード */
+    readonly code: string;
+    /** エラーメッセージ */
+    readonly message: string;
+    /** 行番号（コンパイルエラー時） */
+    readonly line?: number;
+    /** 列番号（コンパイルエラー時） */
+    readonly column?: number;
+    /** スタックトレース */
+    readonly stack?: string;
+}
+/**
+ * セキュリティポリシー
+ * EARS: If code attempts to access the host system, then the Sandbox shall block the access
+ */
+export interface SecurityPolicy {
+    /** 許可するシステムコール */
+    readonly allowedSyscalls?: readonly string[];
+    /** ブロックするシステムコール */
+    readonly blockedSyscalls?: readonly string[];
+    /** 許可するネットワークポート */
+    readonly allowedPorts?: readonly number[];
+    /** 読み取り専用パス */
+    readonly readOnlyPaths?: readonly string[];
+    /** 書き込み可能パス */
+    readonly writablePaths?: readonly string[];
+    /** 最大プロセス数 */
+    readonly maxProcesses: number;
+    /** 最大ファイルディスクリプタ数 */
+    readonly maxOpenFiles: number;
+}
+/**
+ * デフォルトセキュリティポリシー
+ */
+export declare const DEFAULT_SECURITY_POLICY: SecurityPolicy;
+/**
+ * サンドボックスイベントタイプ
+ */
+export type SandboxEventType = 'execution:start' | 'execution:output' | 'execution:complete' | 'execution:error' | 'execution:timeout' | 'container:create' | 'container:start' | 'container:stop' | 'security:violation';
+/**
+ * サンドボックスイベント
+ */
+export interface SandboxEvent {
+    /** イベントタイプ */
+    readonly type: SandboxEventType;
+    /** リクエストID */
+    readonly requestId?: ID;
+    /** コンテナID */
+    readonly containerId?: string;
+    /** イベントデータ */
+    readonly data?: unknown;
+    /** タイムスタンプ */
+    readonly timestamp: Timestamp;
+}
+/**
+ * サンドボックスイベントリスナー
+ */
+export type SandboxEventListener = (event: SandboxEvent) => void;
+/**
+ * コンテナ情報
+ */
+export interface ContainerInfo {
+    /** コンテナID */
+    readonly id: string;
+    /** コンテナ名 */
+    readonly name: string;
+    /** イメージ */
+    readonly image: string;
+    /** 状態 */
+    readonly status: 'created' | 'running' | 'paused' | 'exited' | 'dead';
+    /** 作成日時 */
+    readonly createdAt: Timestamp;
+    /** 開始日時 */
+    readonly startedAt?: Timestamp;
+    /** 終了日時 */
+    readonly finishedAt?: Timestamp;
+}
+/**
+ * リソース使用量統計
+ */
+export interface ResourceStats {
+    /** メモリ使用量（バイト） */
+    readonly memoryUsage: number;
+    /** メモリ上限（バイト） */
+    readonly memoryLimit: number;
+    /** CPU使用率（0-100） */
+    readonly cpuPercent: number;
+    /** ネットワーク送信バイト */
+    readonly networkTx: number;
+    /** ネットワーク受信バイト */
+    readonly networkRx: number;
+    /** ディスクIO読み取りバイト */
+    readonly diskRead: number;
+    /** ディスクIO書き込みバイト */
+    readonly diskWrite: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * KATASHIRO Sandbox - Type Definitions
+ *
+ * @fileoverview REQ-007: コード実行サンドボックスの型定義
+ * @module @nahisaho/katashiro-sandbox
+ * @since 0.4.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SECURITY_POLICY = exports.DEFAULT_DOCKER_CONFIG = exports.DEFAULT_DOCKER_IMAGES = exports.DEFAULT_SANDBOX_CONFIG = void 0;
+/**
+ * デフォルトサンドボックス設定
+ */
+exports.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イメージ
+ */
+exports.DEFAULT_DOCKER_IMAGES = {
+    bash: 'alpine:3.19',
+    python: 'python:3.12-slim',
+    javascript: 'node:22-slim',
+    typescript: 'node:22-slim',
+};
+/**
+ * デフォルトDocker設定
+ */
+exports.DEFAULT_DOCKER_CONFIG = {
+    socketPath: '/var/run/docker.sock',
+    images: exports.DEFAULT_DOCKER_IMAGES,
+    autoRemove: true,
+    containerPrefix: 'katashiro-sandbox-',
+};
+/**
+ * デフォルトセキュリティポリシー
+ */
+exports.DEFAULT_SECURITY_POLICY = {
+    blockedSyscalls: ['ptrace', 'mount', 'umount', 'reboot', 'swapon', 'swapoff'],
+    readOnlyPaths: ['/etc', '/usr', '/bin', '/lib'],
+    writablePaths: ['/workspace', '/tmp'],
+    maxProcesses: 10,
+    maxOpenFiles: 100,
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAsDH;;GAEG;AACU,QAAA,sBAAsB,GAAkB;IACnD,OAAO,EAAE,QAAQ;IACjB,OAAO,EAAE,EAAE;IACX,WAAW,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI,EAAE,QAAQ;IACxC,QAAQ,EAAE,GAAG;IACb,UAAU,EAAE,YAAY;IACxB,cAAc,EAAE,KAAK;IACrB,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI,EAAE,OAAO;CACrC,CAAC;AAsBF;;GAEG;AACU,QAAA,qBAAqB,GAAsC;IACtE,IAAI,EAAE,aAAa;IACnB,MAAM,EAAE,kBAAkB;IAC1B,UAAU,EAAE,cAAc;IAC1B,UAAU,EAAE,cAAc;CAC3B,CAAC;AAEF;;GAEG;AACU,QAAA,qBAAqB,GAAiB;IACjD,UAAU,EAAE,sBAAsB;IAClC,MAAM,EAAE,6BAAqB;IAC7B,UAAU,EAAE,IAAI;IAChB,eAAe,EAAE,oBAAoB;CACtC,CAAC;AA8GF;;GAEG;AACU,QAAA,uBAAuB,GAAmB;IACrD,eAAe,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC;IAC7E,aAAa,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;IAC/C,aAAa,EAAE,CAAC,YAAY,EAAE,MAAM,CAAC;IACrC,YAAY,EAAE,EAAE;IAChB,YAAY,EAAE,GAAG;CAClB,CAAC"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@nahisaho/katashiro-sandbox",
+  "version": "0.4.0",
+  "description": "Code execution sandbox for KATASHIRO with Docker/VM isolation",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rimraf dist",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "lint": "eslint src --ext .ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "katashiro",
+    "sandbox",
+    "docker",
+    "code-execution",
+    "isolation"
+  ],
+  "author": "nahisaho",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nahisaho/katashiro.git",
+    "directory": "packages/sandbox"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@nahisaho/katashiro-core": "*",
+    "dockerode": "^4.0.2"
+  },
+  "devDependencies": {
+    "@types/dockerode": "^3.3.31",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.3.3",
+    "vitest": "^1.6.0"
+  },
+  "peerDependencies": {
+    "@nahisaho/katashiro-core": ">=0.3.0"
+  }
+}