sealbridge 0.0.1 → 0.1.0

package/dist/packages/sandbox/dist/index.js

@@ -0,0 +1,179 @@
+// SPDX-License-Identifier: Apache-2.0
+import { mkdtemp, realpath, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { resolveNodePermissionArgs } from './permission.js';
+export { OCI_CONTAINER_BOUNDARY, detectNodePermissionFlag, prefersStableNodePermissionFlag, resolveNodePermissionArgs, subprocessSandboxBoundary, } from './permission.js';
+// The parent process is the only one that holds owner keys and tool handlers.
+// Task values cross that process boundary as JSON. Inside the child, `node:vm`
+// evaluates task source in a null-prototype context. Node.js documents that
+// `node:vm` is not a security mechanism: code that escapes the context runs as
+// this child. `--permission` / `--experimental-permission` can deny filesystem,
+// child-process, worker, and addon access. They do not deny network syscalls
+// (`fetch`, `node:net`, `node:http`, `node:https`, `node:dns`, `node:dgram`).
+// Deleting the Web globals below only hides those names in the wrapper.
+export const sandboxWrapper = String.raw `
+const vm = require('node:vm');
+const fs = require('node:fs');
+try { delete globalThis.fetch; } catch { /* name may be non-configurable */ }
+try { delete globalThis.WebSocket; } catch { /* name may be non-configurable */ }
+const config = JSON.parse(fs.readFileSync('task.json', 'utf8'));
+const context = vm.createContext(Object.create(null), { codeGeneration: { strings: false, wasm: false }, microtaskMode: 'afterEvaluate' });
+const bootstrap = 'globalThis.queue=[]; globalThis.waiters=new Map(); globalThis.serial=0; globalThis.finished=false; globalThis.callTool=(name,args)=>new Promise((resolve,reject)=>{const id=++serial;waiters.set(id,{resolve,reject});queue.push({id,name,args});}); globalThis.reportUsage=(inputTokens,outputTokens)=>callTool("$usage",{inputTokens,outputTokens}); globalThis.input=JSON.parse(' + JSON.stringify(JSON.stringify(config.input)) + ');';
+vm.runInContext(bootstrap, context, { timeout: 100 });
+new vm.Script('(async()=>{'+config.code+'})().then(value=>{globalThis.result=JSON.stringify({value:value===undefined?null:value});globalThis.finished=true;},error=>{globalThis.result=JSON.stringify({error:String(error)});globalThis.finished=true;});').runInContext(context, { timeout: config.timeoutMs });
+const timer = setInterval(()=>{
+ try {
+   const queued=JSON.parse(vm.runInContext('JSON.stringify(queue.splice(0))',context,{timeout:100}));
+   for(const req of queued)process.send({type:'tool',...req});
+   if(vm.runInContext('finished',context,{timeout:100})){clearInterval(timer);process.send({type:'done',...JSON.parse(vm.runInContext('result',context,{timeout:100}))});process.disconnect();}
+ } catch(e){process.send({type:'done',error:String(e)});process.exit(1);}
+},5);
+process.on('message',msg=>{
+ try { const data=JSON.stringify(msg); vm.runInContext('{const r=JSON.parse('+JSON.stringify(data)+');const w=waiters.get(r.id);if(w){waiters.delete(r.id);r.error?w.reject(new Error(r.error)):w.resolve(r.value);}}',context,{timeout:100}); }
+ catch(e){process.send({type:'done',error:String(e)});process.exit(1);}
+});
+`;
+export function sanitizedEnvironment(directory) {
+    // Build an allowlist from scratch: NODE_OPTIONS, proxy auth, cloud credentials,
+    // provider keys, SSH sockets and inherited PATH never enter the worker.
+    return { LANG: 'C.UTF-8', TZ: 'UTC', HOME: directory, TMPDIR: directory };
+}
+/**
+ * Argv after `process.execPath` for a `subprocess_restricted` child.
+ * Permission-model flags come from `resolveNodePermissionArgs`. `--no-addons`
+ * stays even when this Node binary supports neither permission flag.
+ */
+export function buildRestrictedSubprocessArgv(directory, entry, probe) {
+    return [
+        ...resolveNodePermissionArgs(directory, probe).args,
+        '--no-addons',
+        '--disable-proto=throw',
+        '--max-old-space-size=64',
+        entry,
+    ];
+}
+/** SIGTERM, then SIGKILL if the child is still alive. `killed` is true after either signal. */
+export function terminateSubprocess(subprocess) {
+    if (subprocess.exitCode !== null)
+        return;
+    subprocess.kill('SIGTERM');
+    const timer = setTimeout(() => {
+        if (subprocess.exitCode === null)
+            subprocess.kill('SIGKILL');
+    }, 40);
+    timer.unref?.();
+}
+/**
+ * `subprocess_restricted` runner. Separate OS process, sanitized environment,
+ * scratch directory, timeout then SIGKILL, and an output byte cap. Node's
+ * permission model is applied when `detectNodePermissionFlag` finds a flag.
+ * `node:vm` inside the child is not a security mechanism, and the permission
+ * model does not block network syscalls. Untrusted code needs `oci_container`.
+ */
+export async function runSandbox(options) {
+    if (!Number.isSafeInteger(options.timeoutMs) ||
+        options.timeoutMs < 1 ||
+        options.timeoutMs > 604800000)
+        throw new Error('INVALID_TIMEOUT');
+    // macOS tmpdir() is /var/folders/..., a symlink to /private/var/folders/...
+    // Node's permission model realpath's the entry script and then stats '/var'
+    // unless --allow-fs-read already names the physical directory.
+    const directory = await realpath(await mkdtemp(join(tmpdir(), 'acp-task-')));
+    let child;
+    let exited = Promise.resolve();
+    try {
+        await writeFile(join(directory, 'runner.cjs'), sandboxWrapper, { mode: 0o600 });
+        await writeFile(join(directory, 'task.json'), JSON.stringify({
+            code: options.code,
+            input: options.input ?? null,
+            timeoutMs: options.timeoutMs,
+        }), { mode: 0o600 });
+        return await new Promise((resolve, reject) => {
+            const subprocess = spawn(process.execPath, buildRestrictedSubprocessArgv(directory, join(directory, 'runner.cjs')), {
+                cwd: directory,
+                env: sanitizedEnvironment(directory),
+                stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
+            });
+            child = subprocess;
+            // `close` means stdio and the process handle are gone, so Windows can release cwd.
+            exited = new Promise((resolveExit) => {
+                const finished = () => resolveExit();
+                subprocess.once('exit', finished);
+                subprocess.once('close', finished);
+            });
+            let done = false, requests = 0, stderr = '';
+            const finish = (error, result) => {
+                if (done)
+                    return;
+                done = true;
+                clearTimeout(timer);
+                options.signal?.removeEventListener('abort', abort);
+                terminateSubprocess(subprocess);
+                error ? reject(error) : resolve(result ?? null);
+            };
+            const abort = () => finish(new Error('SANDBOX_HALTED: ' + String(options.signal?.reason)));
+            const timer = setTimeout(() => finish(new Error('SANDBOX_TIMEOUT')), options.timeoutMs);
+            options.signal?.addEventListener('abort', abort, { once: true });
+            if (options.signal?.aborted)
+                abort();
+            subprocess.stderr?.on('data', (b) => {
+                stderr = (stderr + b.toString()).slice(-4096);
+            });
+            // Requests arrive from another OS process. The child has no tool handlers,
+            // capability counters, private keys or credentials, and cannot skip CapGuard.
+            let serial = Promise.resolve();
+            subprocess.on('message', (message) => {
+                serial = serial
+                    .then(async () => {
+                    if (done)
+                        return;
+                    const m = message;
+                    // Output byte cap for one IPC message from the child.
+                    if (JSON.stringify(m).length > 1048576)
+                        return finish(new Error('SANDBOX_MESSAGE_LIMIT'));
+                    if (m.type === 'done')
+                        return finish(m.error ? new Error(m.error) : undefined, m.value);
+                    if (m.type !== 'tool' || ++requests > 10000)
+                        return finish(new Error('SANDBOX_PROTOCOL'));
+                    try {
+                        let value = null;
+                        if (m.name === '$usage') {
+                            if (!options.onUsage)
+                                throw new Error('USAGE_ADAPTER_REQUIRED');
+                            options.onUsage(m.args.inputTokens, m.args.outputTokens);
+                        }
+                        else
+                            value = await options.onTool(m.name, m.args);
+                        if (!done && subprocess.connected)
+                            subprocess.send({ id: m.id, value });
+                    }
+                    catch (error) {
+                        finish(error instanceof Error ? error : new Error(String(error)));
+                    }
+                })
+                    .catch((e) => finish(e));
+            });
+            subprocess.on('error', (e) => finish(e));
+            subprocess.on('exit', (code) => {
+                if (!done)
+                    finish(new Error('SANDBOX_EXIT: ' + code + ' ' + stderr));
+            });
+        });
+    }
+    finally {
+        try {
+            if (child)
+                terminateSubprocess(child);
+            // Wait until the child has actually exited, then give Windows a short retry window.
+            await Promise.race([exited, new Promise((resolve) => setTimeout(resolve, 250))]);
+            await rm(directory, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
+        }
+        catch {
+            // EBUSY, EPERM, and EACCES while deleting the temp dir must not replace the result.
+        }
+    }
+}
+export * from './container.js';
+//# sourceMappingURL=index.js.map

package/dist/packages/sandbox/dist/index.js.map

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

package/dist/packages/sandbox/dist/permission.d.ts

@@ -0,0 +1,58 @@
+/**
+ * CLI spelling of Node's permission model.
+ * `--permission` is the stable flag on Node.js >= 22.13 and on Node.js 23+.
+ * Earlier Node.js 20 and 22 releases accept `--experimental-permission`.
+ * `--allow-fs-read` / `--allow-fs-write` are valid only together with one of these.
+ */
+export declare const NODE_PERMISSION_FLAGS: readonly ["--permission", "--experimental-permission"];
+export type NodePermissionFlag = (typeof NODE_PERMISSION_FLAGS)[number];
+/**
+ * What a sandbox run can honestly claim about Node's permission model.
+ * `kernelNetworkIsolated` is true only for `oci_container` (`--network none`).
+ * The permission model does not deny `fetch`, `node:net`, `node:http`,
+ * `node:https`, `node:dns`, or `node:dgram`.
+ * `permissionModelActive` means a permission flag was passed. It is false for
+ * `oci_container`, which uses the container runtime instead of that flag.
+ */
+export interface SandboxBoundaryMetadata {
+    nodePermissionFlag: NodePermissionFlag | null;
+    permissionModelActive: boolean;
+    kernelNetworkIsolated: boolean;
+}
+export interface NodePermissionProbe {
+    /** Flags the binary advertises. Defaults to `process.allowedNodeEnvironmentFlags`. */
+    flags?: Iterable<string>;
+    /** `process.versions.node`, with or without a leading `v`. */
+    nodeVersion?: string;
+}
+export interface ResolvedNodePermission {
+    flag: NodePermissionFlag | null;
+    /** Empty when neither permission flag is supported. Never contains `--allow-fs-*` alone. */
+    args: string[];
+    boundary: SandboxBoundaryMetadata;
+}
+/** Boundary recorded for Podman/Docker `--network none` runs. */
+export declare const OCI_CONTAINER_BOUNDARY: SandboxBoundaryMetadata;
+export declare function parseNodeVersion(version: string): {
+    major: number;
+    minor: number;
+    patch: number;
+};
+/** True when the documented stable spelling is `--permission` (Node.js >= 22.13, or >= 23). */
+export declare function prefersStableNodePermissionFlag(nodeVersion: string): boolean;
+/**
+ * Chooses `--permission` or `--experimental-permission` for `process.execPath`.
+ * Returns null when `allowedNodeEnvironmentFlags` lists neither, so callers can
+ * start the child without `--allow-fs-*` and record `permissionModelActive: false`.
+ * Version selects the spelling when both flags are advertised. A binary that
+ * lists only one spelling uses that spelling.
+ */
+export declare function detectNodePermissionFlag(probe?: NodePermissionProbe): NodePermissionFlag | null;
+/** Subprocess claim. `kernelNetworkIsolated` stays false even when the flag is active. */
+export declare function subprocessSandboxBoundary(probe?: NodePermissionProbe): SandboxBoundaryMetadata;
+/**
+ * Permission-model argv for one scratch directory.
+ * `--allow-fs-read` and `--allow-fs-write` are omitted when no permission flag exists,
+ * because Node rejects them unless `--permission` or `--experimental-permission` is active.
+ */
+export declare function resolveNodePermissionArgs(directory: string, probe?: NodePermissionProbe): ResolvedNodePermission;

package/dist/packages/sandbox/dist/permission.js

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CLI spelling of Node's permission model.
+ * `--permission` is the stable flag on Node.js >= 22.13 and on Node.js 23+.
+ * Earlier Node.js 20 and 22 releases accept `--experimental-permission`.
+ * `--allow-fs-read` / `--allow-fs-write` are valid only together with one of these.
+ */
+export const NODE_PERMISSION_FLAGS = ['--permission', '--experimental-permission'];
+/** Boundary recorded for Podman/Docker `--network none` runs. */
+export const OCI_CONTAINER_BOUNDARY = {
+    nodePermissionFlag: null,
+    permissionModelActive: false,
+    kernelNetworkIsolated: true,
+};
+export function parseNodeVersion(version) {
+    const match = /^v?(\d+)\.(\d+)(?:\.(\d+))?/.exec(version.trim());
+    if (!match)
+        return { major: 0, minor: 0, patch: 0 };
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: match[3] ? Number(match[3]) : 0,
+    };
+}
+/** True when the documented stable spelling is `--permission` (Node.js >= 22.13, or >= 23). */
+export function prefersStableNodePermissionFlag(nodeVersion) {
+    const { major, minor } = parseNodeVersion(nodeVersion);
+    return major > 22 || (major === 22 && minor >= 13);
+}
+function advertisedFlags(probe) {
+    return new Set(probe?.flags ?? process.allowedNodeEnvironmentFlags);
+}
+/**
+ * Chooses `--permission` or `--experimental-permission` for `process.execPath`.
+ * Returns null when `allowedNodeEnvironmentFlags` lists neither, so callers can
+ * start the child without `--allow-fs-*` and record `permissionModelActive: false`.
+ * Version selects the spelling when both flags are advertised. A binary that
+ * lists only one spelling uses that spelling.
+ */
+export function detectNodePermissionFlag(probe) {
+    const flags = advertisedFlags(probe);
+    const version = probe?.nodeVersion ?? process.versions.node;
+    const hasStable = flags.has('--permission');
+    const hasExperimental = flags.has('--experimental-permission');
+    if (prefersStableNodePermissionFlag(version) && hasStable)
+        return '--permission';
+    if (hasExperimental)
+        return '--experimental-permission';
+    if (hasStable)
+        return '--permission';
+    return null;
+}
+/** Subprocess claim. `kernelNetworkIsolated` stays false even when the flag is active. */
+export function subprocessSandboxBoundary(probe) {
+    const flag = detectNodePermissionFlag(probe);
+    return {
+        nodePermissionFlag: flag,
+        permissionModelActive: flag !== null,
+        kernelNetworkIsolated: false,
+    };
+}
+function assertScratchDirectory(directory) {
+    // A comma is a permission-model path separator, so it would widen the allowlist.
+    if (directory.length === 0 ||
+        directory === '/' ||
+        directory.includes(',') ||
+        directory.includes('\0'))
+        throw new Error('INVALID_SANDBOX_DIRECTORY');
+}
+/**
+ * Permission-model argv for one scratch directory.
+ * `--allow-fs-read` and `--allow-fs-write` are omitted when no permission flag exists,
+ * because Node rejects them unless `--permission` or `--experimental-permission` is active.
+ */
+export function resolveNodePermissionArgs(directory, probe) {
+    const boundary = subprocessSandboxBoundary(probe);
+    if (!boundary.nodePermissionFlag)
+        return { flag: null, args: [], boundary };
+    assertScratchDirectory(directory);
+    return {
+        flag: boundary.nodePermissionFlag,
+        args: [
+            boundary.nodePermissionFlag,
+            '--allow-fs-read=' + directory,
+            '--allow-fs-write=' + directory,
+        ],
+        boundary,
+    };
+}
+//# sourceMappingURL=permission.js.map

package/dist/packages/sandbox/dist/permission.js.map

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

package/dist/spec/README.ja.md

@@ -0,0 +1,76 @@
+# Sealbridge Protocol Specification (`spec/`)
+
+[English (README.md)](./README.md) | **日本語**
+
+**結論**: 本ディレクトリはプログラミング言語に依存しないプロトコル仕様と JSON Schema (Draft 2020-12) の正本（Single Source of Truth）を定義する。すべてのプロトコルオブジェクトは **RFC 8785 (JCS: JSON Canonicalization Scheme)** で正規化されたバイト列に対して **SHA-256 ダイジェスト** と **Ed25519 署名** を計算する。
+
+---
+
+## 1. 共通暗号・シリアライズ規則
+
+1. **エンコーディング**: UTF-8 JSON（I-JSON サブセット準拠、浮動小数点の誤差を避けるため金額・トークン数・秒数はすべて整数 `integer` で表現する）。
+2. **正規化（Canonicalization）**: 署名およびハッシュ計算の対象となるJSONオブジェクトは、[RFC 8785 (JCS)](https://www.rfc-editor.org/info/rfc8785/) に従ってキーを辞書順ソートし空白を除去した決定論的バイト列に変換する。
+3. **識別子（Principal ID）**: オーナーおよびエージェントの識別子は W3C `did:key` 形式（Ed25519公開鍵のMultibase base58btcエンコード、例: `did:key:z6Mk...`）を使用する。
+4. **ダイジェスト表記**: `"sha256:<64文字の16進小文字>"`（例: `"sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"`）。
+5. **署名表記**: `"ed25519:<base64urlまたは128文字の16進小文字>"`。署名計算時は対象オブジェクトから `signature` / `signatures` フィールドを除いた状態でJCS正規化を行う。
+
+---
+
+## 2. コアスキーマ一覧
+
+| ファイル名                                                 | ステータス              | 役割                                                                                                                                                                            |
+| :--------------------------------------------------------- | :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [`task-manifest.schema.json`](./task-manifest.schema.json) | **Draft v0.1 (検証済)** | 依頼側（Requester）が提示するタスク仕様・入出力JSON Schema・受入基準・検証方法・予算上限・付与Capability・隔離要件の定義                                                        |
+| `capability-token.schema.json`                             | Planned (M0)            | UCAN/Biscuit風の減衰可能スコープトークン定義（`issuer`, `audience`, `taskId`, `resources`, `allowedTools`, `argConstraints`, `maxInvocations`, `maxDelegationDepth`, `proofs`） |
+| `envelope.schema.json`                                     | Planned (M0)            | Relay通過用の署名付きメッセージエンベロープ（`envelopeId`, `taskId`, `seq`, `eventType`, `senderDid`, `recipientDid`, `payload`, `signature`）および受領確認 `AckReceipt`       |
+| `audit-entry.schema.json`                                  | Planned (M0)            | 双方向署名ハッシュチェーン台帳エントリおよび `UsageReceipt` / `ApprovalReceipt`                                                                                                 |
+
+---
+
+## 3. スキーマ検証コマンド
+
+```bash
+npx --yes -p ajv-cli@5 -p ajv-formats@3 ajv validate \
+  --spec=draft2020 \
+  -c ajv-formats \
+  -s spec/task-manifest.schema.json \
+  -d spec/examples/sample-task-manifest.json
+```
+
+## M0–M1 実行可能なワイヤプロファイル
+
+新しい `capability-token`、`usage-receipt`、`approval-receipt`、`ack-receipt`、`envelope`、`audit-entry` のスキーマは実装済みです。`pnpm validate:schemas` を実行すると、Ajv Draft 2020-12 で全スキーマをコンパイルし、すべてのサンプルを検証します。元の TaskManifest スキーマとサンプルは変更していません。
+
+署名付きプロトコルオブジェクトは `{ "payload": <object>, "signature": <block> }` です。`D = "sha256:" + hex(SHA256(UTF8(JCS(payload))))` とします。ブロックには `signerDid`、`canonicalization: "RFC8785-JCS"`、`payloadDigest: D`、`signedAt`、パディング無しの `signature: "ed25519:" + base64url(64-byte-signature)` が入ります。Ed25519 署名の正確なプレイメージは次のとおりです。
+
+```text
+UTF8(JCS({payload, signerDid, canonicalization, payloadDigest, signedAt}))
+```
+
+これはペイロードと署名メタデータを覆い、署名バイトそのものは署名しません。上の草案にある一般規則を、この形に精密化しています。JCS の入力は、有効な Unicode を持つ有限の JSON データでなければなりません。`undefined`、循環、疎な配列、非有限数、独自のオブジェクトインスタンス、孤立サロゲートは拒否します。JSON 成果物のコンテンツアドレスは `SHA256(UTF8(JCS(data)))` です。バイナリそのものには `digestBytes` を使います。did:key は Ed25519 公開鍵を、マルチコーデックのバイト `ed 01` と base58btc マルチベース `z` で符号化します。
+
+Capability の証明は、根から葉へ並んだ署名付きトークンの配列です。各子は、完全に署名された親の SHA-256 ダイジェストへ `parentHash` を束縛し、発行者を親の audience に変え、タスク束縛を保ち、リソース・ツール・引数スキーマを狭め、maxCalls と期限を上げず、notBefore を過去へ戻さず、maxDepth を少なくとも 1 減らします。深さが 0 なら、さらに子を作れません。ワイヤ上の `maxCalls` / `maxDepth` は、マニフェストの付与である `maxInvocations` / `maxDelegationDepth` に対応します。引数スキーマはツール名をキーにします。同一スキーマか、直接の `allOf` 継承だけを受理します。対応するスコープとスキーマ構文はセキュリティモデルを見てください。
+
+承認レシートのゲート名は、マニフェストのゲート名へ次のように対応します。
+
+| レシートのゲート     | マニフェストのゲート      |
+| -------------------- | ------------------------- |
+| contract_acceptance  | GATE_CONTRACT_ACCEPT      |
+| external_side_effect | GATE_EXTERNAL_SIDE_EFFECT |
+| budget_increase      | GATE_BUDGET_OVERRUN       |
+| redelegation         | GATE_SUB_DELEGATION       |
+| final_verification   | GATE_DELIVERY_ACCEPT      |
+
+オーナー署名の承認レシートは、タスク、ゲート、対象ダイジェストそのもの、APPROVED / REJECTED の決定を束縛します。ゲートのインスタンスはレシートの再生を拒否します。署名付き遷移は、契約ダイジェスト、タスク、直前の状態、0 始まりのシーケンスを束縛します。M1 の遷移プロファイルは PROPOSED、ACCEPTED、IN_PROGRESS、DELIVERED、VERIFY_ACCEPT、VERIFY_REJECT、SETTLED、CANCELLED、DISPUTED です。網羅表は `conformance/state-transitions.json` にあります。PROPOSE が PROPOSED を確立します。アーキテクチャにある交渉、再試行、タイムアウト専用の状態は、後の拡張です。
+
+監査本体のフィールドは `taskId`、0 始まりの `seq`、`prevEntryHash`（起源では null）、`actorDid`、`receiverDid`、`eventType`、`payload` です。`entryHash = digest(body)` です。`actorSignature` は本体に署名し、`counterSignature` はそのハッシュ、タスク、双方を束縛する署名付き AckReceipt です。最終の署名付きチェックポイントは件数、head、行為者を固定し、相手がもう一度署名します。JSONL は `{"entry": ...}` レコードのあとに、1件の `{"checkpoint": ...}` レコードが続きます。バンドルは `{entries, checkpoint}` です。オフライン検証にはチェックポイントが必要です。より古い有効なバンドルへの巻き戻しを検出するには、独立して入手した最新の head が必要です。
+
+妥当な `reportProgress` は途中の `metrics` を含められます。その使用量は、進捗フレームをキューへ入れる前にセッションのクォータへ計上されます。不正な `reportProgress` ペイロード（`INVALID_PROGRESS`）は、その `metrics` を適用しません。返された Promise は直ちに拒否され、セッションは粘着的な失敗を記録するため、その後の成果物で `SETTLED` にはなりません。アダプタが Promise 拒否を catch しても、依頼者は `PEER_REJECTED: {"code":"INVALID"}` を観測し、ワーカーは `INVALID_PROGRESS` で失敗します。
+
+A2A の AgentCard、Task、Message、Artifact は SDK のワイヤ形を保ち、署名付き Sealbridge エンベロープの中に載ります。ブリッジは、インストール済みの A2A SDK 0.3 のワイヤプロファイルを使います。Sealbridge の契約とレシートは、A2A を書き換えるのではなく、オーバーレイのペイロードです。MCP の `tools/call` の要求と結果は公式 SDK を使い、サンドボックスの外で物理的にプロキシされます。未知のツールと、メタデータの無い迂回は拒否します。
+
+## M2/M3 追加のディスカバリとセッションプロファイル
+
+M0/M1 の JSON スキーマとサンプルは変更していません。署名付き AgentCard と招待は、同じ `Signed<T>` のプレイメージを使います。`AgentCard` には ownerDid、agentDid、relayEndpoint、skills（任意の JSON 入出力スキーマを含む）、costModes、name、description、version が入ります。カードに署名するのはオーナーです。`AgentInvite` は、完全に署名されたカードを、同じ ownerDid / agentDid と relayUrl、および issuedAt / expiresAt に束縛します。パーサは、無効な署名、一致しない識別子や経路、未来の発行時刻、期限切れを拒否します。URI の符号化は `acp-invite:<base64url(JSON(Signed<AgentInvite>))>` または `acp://invite?token=<same-base64url>` です。
+
+セッションのエンベロープは、送信者ごとに単調なシーケンス番号を持ちます。各アプリケーションイベントのあとに、署名付き監査本体を運ぶ `AUDIT_ENTRY` エンベロープが続き、受信者は署名付き AckReceipt を運ぶ `AUDIT_ACK` を返します。双方が同一の AuditEntry を追記します。`CHECKPOINT` と `CHECKPOINT_ACK` は、最終の署名付きチェックポイントと副署を交換します。DELIVER には成果物、利用量、実行証明、およびその署名付き遷移が含まれます。証明は `effectiveIsolationLevel` と `sandboxBoundary`（`nodePermissionFlag`、`permissionModelActive`、`kernelNetworkIsolated`）を追加できます。`node:vm` はセキュリティ機構ではないです。Node の `--permission` / `--experimental-permission` は `fetch`、`node:net`、`node:http`、`node:https`、`node:dns`、`node:dgram` を止めません。`kernelNetworkIsolated` が真になるのは `oci_container`（`isolationLevel: 'oci_container'`）だけで、その経路はカーネルのネットワーク境界です（`--network none`、`--read-only`、`--cap-drop ALL`、`no-new-privileges`）。`subprocess_restricted` は権限フラグと `--allow-fs-read`、`--allow-fs-write` を組にすることがあります。元の M1 証明も有効なままです。

package/dist/spec/README.md

@@ -0,0 +1,135 @@
+# Sealbridge Protocol Specification (`spec/`)
+
+**English** | [日本語 (README.ja.md)](./README.ja.md)
+
+**Conclusion**: This directory is the language-independent source of truth for the protocol specification and the JSON Schema (Draft 2020-12). Every protocol object computes a **SHA-256 digest** and an **Ed25519 signature** over bytes canonicalized with **RFC 8785 (JCS: JSON Canonicalization Scheme)**.
+
+---
+
+## 1. Shared cryptographic and serialization rules
+
+1. **Encoding**: UTF-8 JSON (the I-JSON subset). Amounts, token counts, and durations are integers, so floating-point error does not enter the signed bytes.
+2. **Canonicalization**: A JSON object that will be signed or hashed is converted to a deterministic byte string with keys sorted lexicographically and whitespace removed, following [RFC 8785 (JCS)](https://www.rfc-editor.org/info/rfc8785/).
+3. **Principal ID**: Owner and agent identifiers use W3C `did:key` (the Ed25519 public key in multibase base58btc, for example `did:key:z6Mk...`).
+4. **Digest form**: `"sha256:<64 lowercase hex characters>"` (for example `"sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"`).
+5. **Signature form**: `"ed25519:<base64url or 128 lowercase hex characters>"`. Before signing, remove the `signature` / `signatures` fields from the object and then apply JCS.
+
+---
+
+## 2. Core schemas
+
+| File                                                       | Status                     | Role                                                                                                                                                                                      |
+| :--------------------------------------------------------- | :------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`task-manifest.schema.json`](./task-manifest.schema.json) | **Draft v0.1 (validated)** | The task specification the requester presents: input and output JSON Schema, acceptance criteria, verification method, budget cap, granted Capabilities, and isolation requirements       |
+| `capability-token.schema.json`                             | Planned (M0)               | A UCAN/Biscuit-style attenuating scope token (`issuer`, `audience`, `taskId`, `resources`, `allowedTools`, `argConstraints`, `maxInvocations`, `maxDelegationDepth`, `proofs`)            |
+| `envelope.schema.json`                                     | Planned (M0)               | The signed message envelope that crosses the Relay (`envelopeId`, `taskId`, `seq`, `eventType`, `senderDid`, `recipientDid`, `payload`, `signature`) and the acknowledgement `AckReceipt` |
+| `audit-entry.schema.json`                                  | Planned (M0)               | A bilateral signed hash-chain ledger entry, plus `UsageReceipt` / `ApprovalReceipt`                                                                                                       |
+
+---
+
+## 3. Schema validation command
+
+```bash
+npx --yes -p ajv-cli@5 -p ajv-formats@3 ajv validate \
+  --spec=draft2020 \
+  -c ajv-formats \
+  -s spec/task-manifest.schema.json \
+  -d spec/examples/sample-task-manifest.json
+```
+
+## M0–M1 executable wire profile
+
+The new `capability-token`, `usage-receipt`, `approval-receipt`, `ack-receipt`,
+`envelope` and `audit-entry` schemas are implemented. Run `pnpm validate:schemas`
+to compile all schemas and validate every example using Ajv Draft 2020-12.
+The original TaskManifest schema and example remain unchanged.
+
+Signed protocol objects use `{ "payload": <object>, "signature": <block> }`.
+Let `D = "sha256:" + hex(SHA256(UTF8(JCS(payload))))`. The block contains
+`signerDid`, `canonicalization: "RFC8785-JCS"`, `payloadDigest: D`, `signedAt`, and
+`signature: "ed25519:" + base64url(64-byte-signature)` without padding.
+The exact Ed25519 signature preimage is:
+
+```text
+UTF8(JCS({payload, signerDid, canonicalization, payloadDigest, signedAt}))
+```
+
+This covers the payload and signature metadata, and does not sign the signature
+bytes themselves. It refines the draft's general rule above. JCS inputs must be
+finite JSON data with valid Unicode; undefined, cycles, sparse arrays, nonfinite
+numbers, custom object instances and lone surrogates are rejected. Content
+addresses for JSON artifacts use `SHA256(UTF8(JCS(data)))`; `digestBytes` is
+available for exact binary content. did:key encodes the Ed25519 public key with
+multicodec bytes `ed 01` and base58btc multibase `z`.
+
+Capability proofs are an ordered root-to-leaf array of signed tokens. Each child
+binds `parentHash` to the SHA-256 digest of its complete signed parent, changes
+issuer to the parent's audience, retains task binding, narrows the resource,
+tools and argument schemas, never raises maxCalls or expiry, never backdates
+notBefore, and decreases maxDepth by at least one. A zero depth forbids another
+child. Wire token `maxCalls`/`maxDepth` correspond to manifest grant
+`maxInvocations`/`maxDelegationDepth`. Argument schemas are indexed by tool name.
+Only identical schemas or direct `allOf` inheritance are accepted. See the
+security model for supported scope and schema syntax.
+
+Approval receipt gate names map to the manifest's names:
+
+| Receipt gate         | Manifest gate             |
+| -------------------- | ------------------------- |
+| contract_acceptance  | GATE_CONTRACT_ACCEPT      |
+| external_side_effect | GATE_EXTERNAL_SIDE_EFFECT |
+| budget_increase      | GATE_BUDGET_OVERRUN       |
+| redelegation         | GATE_SUB_DELEGATION       |
+| final_verification   | GATE_DELIVERY_ACCEPT      |
+
+Owner-signed approval receipts bind the task, gate, exact target digest and
+APPROVED/REJECTED decision. Gate instances reject receipt replay. Signed
+transitions bind contract digest, task, prior state and zero-based sequence. The
+M1 transition profile uses PROPOSED, ACCEPTED, IN_PROGRESS, DELIVERED,
+VERIFY_ACCEPT, VERIFY_REJECT, SETTLED, CANCELLED and DISPUTED; the exhaustive table
+is in `conformance/state-transitions.json`. PROPOSE establishes PROPOSED. Negotiation,
+retry and timeout-specific states in the architecture remain later extensions.
+
+Audit body fields are `taskId`, zero-based `seq`, `prevEntryHash` (null at genesis),
+`actorDid`, `receiverDid`, `eventType`, `payload`. `entryHash = digest(body)`;
+`actorSignature` signs the body and `counterSignature` is a signed AckReceipt
+binding that hash, task and both parties. The final signed checkpoint fixes the
+count, head and actors and is signed again by the other party. JSONL contains
+`{"entry": ...}` records followed by one `{"checkpoint": ...}` record. Bundles
+contain `{entries, checkpoint}`. The checkpoint is required for offline verification.
+An independent latest head is required to detect rollback to an older valid bundle.
+
+A valid `reportProgress` may include intermediate `metrics`, and those metrics are charged to the session quota before the progress frame is queued. An invalid `reportProgress` payload (`INVALID_PROGRESS`) does not apply its `metrics`. The returned promise rejects immediately, and the session records a sticky failure, so a later deliverable cannot settle. The requester observes `PEER_REJECTED: {"code":"INVALID"}` and the worker fails with `INVALID_PROGRESS`, even if the adapter catches the promise.
+
+A2A AgentCard, Task, Message and Artifact retain SDK wire shapes, carried inside
+signed Sealbridge envelopes. The bridge uses the installed A2A SDK 0.3 wire profile;
+Sealbridge contract/receipt objects are overlay payloads rather than changes to A2A.
+MCP `tools/call` requests and results use the official SDK and are physically
+proxied outside the sandbox. Unknown tools and metadata-free bypasses are denied.
+
+## M2/M3 additive discovery and session profile
+
+The M0/M1 JSON schemas and examples remain unchanged. Signed AgentCards and
+invites use the same `Signed<T>` preimage. `AgentCard` contains ownerDid,
+agentDid, relayEndpoint, skills (including optional JSON input/output schemas),
+costModes, name, description and version. The owner signs the card.
+`AgentInvite` binds the complete signed card to the same ownerDid/agentDid and
+relayUrl, plus issuedAt/expiresAt. Parsers reject invalid signatures, mismatched
+identities/routes, future issuance and expiry. URI encoding is either
+`acp-invite:<base64url(JSON(Signed<AgentInvite>))>` or
+`acp://invite?token=<same-base64url>`.
+
+Session envelopes have monotonic sequence numbers per sender. Each application
+event is followed by an `AUDIT_ENTRY` envelope carrying a signed audit body;
+the receiver returns `AUDIT_ACK` carrying its signed AckReceipt. Both sides
+append the identical AuditEntry. `CHECKPOINT` and `CHECKPOINT_ACK` exchange the
+final signed checkpoint and countersignature. DELIVER includes artifact, usage,
+attestation and its signed transition. Attestations may add
+`effectiveIsolationLevel` and `sandboxBoundary` (`nodePermissionFlag`,
+`permissionModelActive`, `kernelNetworkIsolated`). `node:vm` is not a security mechanism,
+and Node's `--permission` / `--experimental-permission` model does not block
+`fetch`, `node:net`, `node:http`, `node:https`, `node:dns`, or `node:dgram`.
+`kernelNetworkIsolated` is true only for `oci_container` (`isolationLevel: 'oci_container'`),
+which is the kernel network boundary: `--network none`, `--read-only`, `--cap-drop ALL`, and `no-new-privileges`.
+`subprocess_restricted` may add `--allow-fs-read` and `--allow-fs-write` with the
+permission flag. Original M1 attestations remain valid.

package/dist/spec/ack-receipt.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://acp-spec.local/schemas/v0.1/ack-receipt.schema.json",
+  "title": "ack-receipt",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "payload",
+    "signature"
+  ],
+  "properties": {
+    "payload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "type",
+        "taskId",
+        "entryHash",
+        "actorDid",
+        "receiverDid"
+      ],
+      "properties": {
+        "type": {
+          "const": "AckReceipt"
+        },
+        "taskId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "entryHash": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$"
+        },
+        "actorDid": {
+          "type": "string",
+          "pattern": "^did:key:z[1-9A-HJ-NP-Za-km-z]{32,128}$"
+        },
+        "receiverDid": {
+          "type": "string",
+          "pattern": "^did:key:z[1-9A-HJ-NP-Za-km-z]{32,128}$"
+        }
+      }
+    },
+    "signature": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "signerDid",
+        "canonicalization",
+        "payloadDigest",
+        "signedAt",
+        "signature"
+      ],
+      "properties": {
+        "signerDid": {
+          "type": "string",
+          "pattern": "^did:key:z[1-9A-HJ-NP-Za-km-z]{32,128}$"
+        },
+        "canonicalization": {
+          "const": "RFC8785-JCS"
+        },
+        "payloadDigest": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$"
+        },
+        "signedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "signature": {
+          "type": "string",
+          "pattern": "^ed25519:[A-Za-z0-9_-]{86}$"
+        }
+      }
+    }
+  }
+}