@bluelamp/secret-exec 0.2.1 → 0.3.1

package/README.md

@@ -67,3 +67,13 @@ bluelamp-secret put my-db --file ./db-url.txt --url https://db.example.com
 | 1 | 未ログイン・金庫に無い・権限なし・ポータルに届かない（子は起こさない） |
 | 2 | 引数の形が違う |
 | 127 | コマンドを起動できなかった |
+
+## `@bluelamp/secret-exec/handoff`（0.3.0〜・箱 n=2946）
+
+口座の鍵を、起こす子の `CLAUDE_CODE_OAUTH_TOKEN` にだけ渡すコマンドの**組み立て**。monster-orchestrator（配車の席）と scheduler（予約の席）が同じ式で使う。
+
+- `buildCredentialHandoff(command, vaultName, bins)` … `command` を「金庫 `vaultName` の鍵を `CLAUDE_CODE_OAUTH_TOKEN` に入れてから exec する」sh の 1 行に包む。値は `bluelamp-secret exec` が子の env に入れ、コマンド置換で受けて仮の名を unset してから exec する＝argv・ディスク・ログに出ない。取り出せなければ exit 97（子は起きない）
+- `probeCredential(vaultName, bins)` … 取り出せるかだけを `{ ok, exitCode }` で返す（何も出力しない）
+- `resolveHandoffBins(overrideEnvNames)` … node と bluelamp-secret の実体の絶対パス（launchd の貧しい PATH に依らない）。見つからなければ null
+
+⛔ 値を返す口は無い（テスト P10 が export の一覧を縛る）。外側の `env -u CLAUDE_CODE_OAUTH_TOKEN`（親の継承を切る）は呼び手が付ける。

package/dist/handoff.d.ts

@@ -0,0 +1,51 @@
+/** 子の env に金庫の値を入れる仮の名（exec 前に unset する）。 */
+export declare const CRED_ENV_NAME = "MO_ACCOUNT_CRED";
+/**
+ * 金庫の値から accessToken を取り出して stdout に出す（`node -e` に渡す本文）。
+ * 🔐 本文に値は無い（値は env から読む）。stdout はコマンド置換（pipe）で受けるのでディスクに落ちない。
+ */
+export declare const EXTRACT_TOKEN_JS: string;
+/** 取り出せるかだけを終了コードで返す本文（0＝取り出せる・97＝形が違う／空）。⛔ 何も出力しない */
+export declare const PROBE_TOKEN_JS: string;
+/**
+ * 値を受けて exec する sh の本文（`$1`=node・`$2`=取り出す本文・`$3`=元の command）。
+ * 値は `$(…)` で変数に受けるだけ＝argv に出ない。仮の名は exec 前に unset。
+ */
+export declare const HANDOFF_SH: string;
+/** 金庫の名前に許す文字（シェルの 1 語にそのまま載るので狭く取る） */
+export declare const VAULT_NAME_RE: RegExp;
+/** POSIX sh の 1 語にクォートする（純関数） */
+export declare function shellQuote(s: string): string;
+export interface HandoffBins {
+    /** node の絶対パス（launchd の貧しい PATH に依らない） */
+    node: string;
+    /** bluelamp-secret の実体（.mjs）の絶対パス。shebang の `env node` に依らないよう node で直接起こす */
+    secretExec: string;
+}
+/**
+ * `command` を「金庫 `vaultName` の鍵を `CLAUDE_CODE_OAUTH_TOKEN` に入れてから exec する」sh の 1 行に包む（純関数）。
+ * 外側の `env -u CLAUDE_CODE_OAUTH_TOKEN`（親の継承を切る多重防御）は呼び手が付ける。
+ */
+export declare function buildCredentialHandoff(command: string, vaultName: string, bins: HandoffBins): string;
+/** 取り出せるかだけを確かめる argv（純関数・シェルを通さず spawn する）。 */
+export declare function buildCredentialProbeArgv(vaultName: string, bins: HandoffBins): string[];
+/** 金庫の鍵を取り出せるか（I/O）。⛔ stdout／stderr は捨てる（値は出ないが、bluelamp-secret の案内も呼び手に返さない） */
+export declare function probeCredential(vaultName: string, bins: HandoffBins, timeoutMs?: number): {
+    ok: boolean;
+    exitCode: number | null;
+};
+export declare const SECRET_EXEC_NAME = "bluelamp-secret";
+/**
+ * bluelamp-secret を探す先（純関数・箱 n=2730）。順は
+ * 呼び手の上書き（env の値・先頭から）→ /opt/homebrew/bin → /usr/local/bin → PATH の各段 → node と同じ bin（npm の既定 prefix）。
+ * Mac の 2 か所を PATH より前に置く＝launchd の貧しい PATH でも、Mac で選ばれる実体は変わらない。
+ */
+export declare function secretExecCandidates(env: NodeJS.ProcessEnv, execPath: string, overrideEnvNames?: readonly string[]): string[];
+export interface HandoffBinsDeps {
+    env: NodeJS.ProcessEnv;
+    execPath: string;
+    realpath: (p: string) => string;
+    npmGlobal: () => string | null;
+}
+/** node / bluelamp-secret の絶対パスを決める。見つからなければ null（呼び手が自分の言葉でエラーにする）。 */
+export declare function resolveHandoffBins(overrideEnvNames?: readonly string[], deps?: Partial<HandoffBinsDeps>): HandoffBins | null;

package/dist/handoff.js

@@ -0,0 +1,125 @@
+/**
+ * 口座の鍵を、起こす子の `CLAUDE_CODE_OAUTH_TOKEN` にだけ渡す組み立て（箱 n=2946・`@bluelamp/secret-exec/handoff`）。
+ *
+ * 出所: monster-orchestrator の account-pool.ts（箱 n=2079・n=2696・n=2730）から移した。orchestrator（配車の席）と
+ *       scheduler（予約の席）が同じ式で渡す＝二つ目の実装を作らない。
+ *
+ * ■ 秘密の扱い（⛔ 1 つも破らない）
+ *   - ここに値は来ない。組み立てるのは「`bluelamp-secret exec <仮の名>=<金庫の名前> -- …` をどう撃つか」だけ。
+ *   - 値は bluelamp-secret が子の env（仮の名）に入れ、取り出す口（sh ＋ node -e）がコマンド置換で受けて
+ *     `CLAUDE_CODE_OAUTH_TOKEN` に入れ、仮の名を unset してから exec する＝argv・ディスク・ログに出ない。
+ *   - ⛔ 値を返す関数を足さない（このパッケージの約束・index.ts の冒頭）。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { spawnSync } from "node:child_process";
+/** 子の env に金庫の値を入れる仮の名（exec 前に unset する）。 */
+export const CRED_ENV_NAME = "MO_ACCOUNT_CRED";
+/** 金庫の値の形を読んで accessToken を `t` に置く本文（JSON `{accessToken}`／JSON の文字列／生の token）。 */
+const READ_TOKEN_JS = `const r=(process.env.${CRED_ENV_NAME}||"").trim();let t;` +
+    `try{const o=JSON.parse(r);t=typeof o==="string"?o:o&&typeof o==="object"?o.accessToken:undefined}catch{t=/^[^\\s{}"]+$/.test(r)?r:undefined}`;
+/**
+ * 金庫の値から accessToken を取り出して stdout に出す（`node -e` に渡す本文）。
+ * 🔐 本文に値は無い（値は env から読む）。stdout はコマンド置換（pipe）で受けるのでディスクに落ちない。
+ */
+export const EXTRACT_TOKEN_JS = READ_TOKEN_JS +
+    `if(typeof t!=="string"||t.length===0){process.stderr.write("bluelamp: 口座の資格を取り出せない\\n");process.exit(97)}` +
+    `process.stdout.write(t)`;
+/** 取り出せるかだけを終了コードで返す本文（0＝取り出せる・97＝形が違う／空）。⛔ 何も出力しない */
+export const PROBE_TOKEN_JS = READ_TOKEN_JS + `process.exit(typeof t==="string"&&t.length>0?0:97)`;
+/**
+ * 値を受けて exec する sh の本文（`$1`=node・`$2`=取り出す本文・`$3`=元の command）。
+ * 値は `$(…)` で変数に受けるだけ＝argv に出ない。仮の名は exec 前に unset。
+ */
+export const HANDOFF_SH = `T=$("$1" -e "$2") || exit 97; unset ${CRED_ENV_NAME}; ` +
+    `CLAUDE_CODE_OAUTH_TOKEN=$T; export CLAUDE_CODE_OAUTH_TOKEN; unset T; exec /bin/sh -c "$3"`;
+/** 金庫の名前に許す文字（シェルの 1 語にそのまま載るので狭く取る） */
+export const VAULT_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+/** POSIX sh の 1 語にクォートする（純関数） */
+export function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * `command` を「金庫 `vaultName` の鍵を `CLAUDE_CODE_OAUTH_TOKEN` に入れてから exec する」sh の 1 行に包む（純関数）。
+ * 外側の `env -u CLAUDE_CODE_OAUTH_TOKEN`（親の継承を切る多重防御）は呼び手が付ける。
+ */
+export function buildCredentialHandoff(command, vaultName, bins) {
+    if (!VAULT_NAME_RE.test(vaultName))
+        throw new Error(`金庫の名前の形が不正: ${JSON.stringify(vaultName)}`);
+    return [
+        shellQuote(bins.node),
+        shellQuote(bins.secretExec),
+        "exec",
+        `${CRED_ENV_NAME}=${vaultName}`,
+        "--",
+        "/bin/sh",
+        "-c",
+        shellQuote(HANDOFF_SH),
+        "mo-account",
+        shellQuote(bins.node),
+        shellQuote(EXTRACT_TOKEN_JS),
+        shellQuote(command),
+    ].join(" ");
+}
+/** 取り出せるかだけを確かめる argv（純関数・シェルを通さず spawn する）。 */
+export function buildCredentialProbeArgv(vaultName, bins) {
+    if (!VAULT_NAME_RE.test(vaultName))
+        throw new Error(`金庫の名前の形が不正: ${JSON.stringify(vaultName)}`);
+    return [bins.secretExec, "exec", `${CRED_ENV_NAME}=${vaultName}`, "--", bins.node, "-e", PROBE_TOKEN_JS];
+}
+/** 金庫の鍵を取り出せるか（I/O）。⛔ stdout／stderr は捨てる（値は出ないが、bluelamp-secret の案内も呼び手に返さない） */
+export function probeCredential(vaultName, bins, timeoutMs = 15_000) {
+    // bluelamp-secret（.mjs）は shebang の `env node` に依らず node で直接起こす
+    const r = spawnSync(bins.node, buildCredentialProbeArgv(vaultName, bins), { stdio: "ignore", timeout: timeoutMs });
+    return { ok: r.status === 0, exitCode: r.status };
+}
+/* ============================== bluelamp-secret の置き場 ============================== */
+export const SECRET_EXEC_NAME = "bluelamp-secret";
+/**
+ * bluelamp-secret を探す先（純関数・箱 n=2730）。順は
+ * 呼び手の上書き（env の値・先頭から）→ /opt/homebrew/bin → /usr/local/bin → PATH の各段 → node と同じ bin（npm の既定 prefix）。
+ * Mac の 2 か所を PATH より前に置く＝launchd の貧しい PATH でも、Mac で選ばれる実体は変わらない。
+ */
+export function secretExecCandidates(env, execPath, overrideEnvNames = []) {
+    const dirs = (env.PATH ?? "").split(path.delimiter).filter((d) => path.isAbsolute(d));
+    const list = [
+        // 上書きは絶対パスだけ（相対は cwd で解決され、起こした場所で別の実体を掴む・CTO H-5 指摘②）
+        ...overrideEnvNames.map((n) => env[n]).filter((p) => typeof p === "string" && path.isAbsolute(p)),
+        `/opt/homebrew/bin/${SECRET_EXEC_NAME}`,
+        `/usr/local/bin/${SECRET_EXEC_NAME}`,
+        ...dirs.map((d) => path.join(d, SECRET_EXEC_NAME)),
+        path.join(path.dirname(execPath), SECRET_EXEC_NAME),
+    ].filter((p) => typeof p === "string" && p.length > 0);
+    return [...new Set(list)];
+}
+/** `npm prefix -g`/bin の bluelamp-secret（npm の prefix を ~/.npmrc で変えた機体向け）。npm が無い・遅いときは null。 */
+function npmGlobalSecretExec() {
+    const r = spawnSync("npm", ["prefix", "-g"], { encoding: "utf8", timeout: 5_000 });
+    const prefix = r.status === 0 ? r.stdout.trim() : "";
+    return path.isAbsolute(prefix) ? path.join(prefix, "bin", SECRET_EXEC_NAME) : null;
+}
+/** node / bluelamp-secret の絶対パスを決める。見つからなければ null（呼び手が自分の言葉でエラーにする）。 */
+export function resolveHandoffBins(overrideEnvNames = [], deps) {
+    const d = {
+        env: process.env,
+        execPath: process.execPath,
+        realpath: fs.realpathSync,
+        npmGlobal: npmGlobalSecretExec,
+        ...deps,
+    };
+    const tryOne = (c) => {
+        try {
+            return { node: d.execPath, secretExec: d.realpath(c) };
+        }
+        catch {
+            return null;
+        }
+    };
+    for (const c of secretExecCandidates(d.env, d.execPath, overrideEnvNames)) {
+        const b = tryOne(c);
+        if (b)
+            return b;
+    }
+    const g = d.npmGlobal();
+    return g ? tryOne(g) : null;
+}

package/dist/index.d.ts

@@ -0,0 +1,138 @@
+/**
+ * @bluelamp/secret-exec — `bluelamp-secret exec`（箱 n=2018 設計④′）と `bluelamp-secret put`（箱 n=2498・下の put の節）
+ *
+ * 🔒 これは「値を返さない口」である（実装より先に書いた線・README の冒頭と同じ）。
+ *   取れるのは「金庫にその名前が在るか無いか」と「値を使えるか（子プロセスが env で受けて走れたか＝終了コード）」だけ。
+ *   ⛔ 値を標準出力・標準エラー・戻り値・ファイル・argv・ログ・エラーの文言に出す口を作らない。
+ *   ⛔ 値を返す関数を export しない（呼び手に値を渡す API を足したくなったら、それはこのパッケージの仕事ではない）。
+ */
+/**
+ * 🕳 塞いでいる穴: MCP の `get_secret` は値を返り値にしていたため、値が会話の転写に残った。
+ *   その口を閉じると、値を Bash で使っていた手順（21 日で 235 回）が壊れる。⇒ 値を「見せずに使う」口をここに置く。
+ *
+ * 🔑 値の通り道は「金庫の HTTP 応答 → 子の env」の 1 本だけ。
+ *   ⛔ HTTP の本文・fetch の例外をそのまま出さない（本文は値を、例外は要求を引用しうる）。
+ *      失敗は「どの ENV 名・どの金庫の名前が・なぜ」だけを返す。
+ * 🔑 パッケージの外へ出す API は無い（package.json の exports は package.json だけ）。
+ *   下の export は同じパッケージの bin と unit テストのためのもの。値を返す関数は export しない（`extractSecretValue` は非公開）。`runSecretExec` の戻り値は終了コードだけ。
+ * 🔑 使用の記録: `GET /vault/:service` は backend 側で監査 `get`（誰が・どの秘密を）を 1 行書く。
+ *
+ * 判定と組み立ては純粋関数（unit で直接撃つ）、網と子プロセスは `runSecretExec` の deps に寄せる。
+ */
+/** ENV 名として受ける形。⛔ これ以外（小文字・記号・先頭数字）は受けない */
+export declare const ENV_NAME_PATTERN: RegExp;
+/** 既定のポータル API（bluelamp CLI の portal-api-client・TokenManager と同じ値） */
+export declare const DEFAULT_PORTAL_API_BASE_URL = "https://api.motohi.jp/api/bluelamp";
+export declare const USAGE: string;
+export interface SecretBinding {
+    env: string;
+    name: string;
+}
+export type ParseResult = {
+    ok: true;
+    bindings: SecretBinding[];
+    command: string;
+    args: string[];
+} | {
+    ok: false;
+    help: boolean;
+    error: string;
+};
+/** 引数を解析する（`process.argv.slice(2)` を受ける）。値はここに来ない＝金庫の名前だけ */
+export declare function parseExecArgs(argv: readonly string[]): ParseResult;
+/** 基底 URL（BLUELAMP_PORTAL_API_BASE_URL > PORTAL_URL > 既定。portal-api-client.cjs と同じ順） */
+export declare function resolvePortalApiBaseUrl(env: Readonly<Record<string, string | undefined>>): string;
+/**
+ * 金庫の 1 件を引く URL。
+ * 🔑 vault の sub-app は内部で `/api/vault/...` に経路を切るが、bluelamp module ごと `/api/bluelamp` に
+ *    載っているので外から見える経路は `<base>/vault/...`（base は /api/bluelamp まで含む）。
+ *    🔬 実測（無認証）: `/api/bluelamp/api/vault/x` → 404／`/api/bluelamp/vault/x` → 401。
+ *    mcp-list/bluelamp/playwright/src/fillSecret.ts の VAULT_FILL_PATH と同じ結論。
+ */
+export declare function buildVaultUrl(baseUrl: string, name: string): string;
+/** 子の env を合成する（親を書き換えない） */
+export declare function composeChildEnv(parentEnv: Readonly<Record<string, string | undefined>>, values: Readonly<Record<string, string>>): Record<string, string>;
+/** HTTP の状態を理由の文言にする（⛔ 本文は使わない） */
+export declare function describeVaultStatus(status: number): string;
+/** 子の終わり方を終了コードにする（シグナルは 128+番号＝シェルと同じ） */
+export declare function exitCodeOf(code: number | null, signal: string | null, signalNumbers: Readonly<Record<string, number>>): number;
+interface FetchResponseLike {
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}
+type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}) => Promise<FetchResponseLike>;
+interface ChildLike {
+    on(event: 'exit', cb: (code: number | null, signal: string | null) => void): unknown;
+    on(event: 'error', cb: (err: {
+        code?: string;
+    }) => void): unknown;
+    kill(signal?: string): unknown;
+}
+export interface SecretExecDeps {
+    env: Readonly<Record<string, string | undefined>>;
+    loadToken: () => string | null;
+    fetch: FetchLike;
+    spawn: (command: string, args: string[], options: {
+        stdio: 'inherit';
+        shell: false;
+        env: Record<string, string>;
+    }) => ChildLike;
+    stderr: (text: string) => void;
+    signalNumbers: Readonly<Record<string, number>>;
+    /** 親が受けたシグナルを子へ回す口（無ければ回さない）。戻り値は解除関数 */
+    onParentSignal?: (forward: (signal: string) => void) => () => void;
+}
+/** 実行する。戻り値は終了コード */
+export declare function runSecretExec(argv: readonly string[], deps: SecretExecDeps): Promise<number>;
+/**
+ * 🔒 exec と対になる「値を会話に出さない書き込みの口」。
+ *   値の通り道は「標準入力（か --file のファイル）→ 金庫への POST 本文」の 1 本だけ。
+ *   ⛔ 値を引数で受けない（argv はプロセス一覧と転写に残る）。⛔ 値・HTTP の本文を出力に出さない。
+ * 🔑 金庫の POST は同じ名前を黙って上書きする（🔬 2026-10-05 本番で実測）。⇒ --force が無ければ
+ *    先に一覧（値を含まない）で「自分の金庫に同じ名前が在るか」を見て止める。共有されてきた同名は
+ *    自分の金庫には無いので止めない（書けば自分の側に別の 1 件ができ、exec は自分の側を先に引く）。
+ * 🔑 保存の後に読み戻して一致を確かめる（読み戻しは exec と同じ GET＝監査に get が 1 行残る）。
+ */
+export interface PutOptions {
+    name: string;
+    note?: string;
+    username?: string;
+    /** --url から導いた origin（scheme+host+port）。金庫の列は bound_origins */
+    origin?: string;
+    file?: string;
+    force: boolean;
+}
+export type PutParseResult = {
+    ok: true;
+    options: PutOptions;
+} | {
+    ok: false;
+    help: boolean;
+    error: string;
+};
+/** --url を origin に畳む（http/https だけ受ける）。畳めなければ null */
+export declare function deriveOrigin(raw: string): string | null;
+/**
+ * put の引数を解析する（`process.argv.slice(2)` を受ける）。
+ * ⛔ 失敗の文言に、知らない引数や余分な位置引数の中身を引用しない（値を引数に書き間違えた場合に値が出るため）。
+ */
+export declare function parsePutArgs(argv: readonly string[]): PutParseResult;
+export interface SecretPutDeps {
+    env: Readonly<Record<string, string | undefined>>;
+    loadToken: () => string | null;
+    fetch: FetchLike;
+    /** 標準入力が端末か */
+    stdinIsTTY: () => boolean;
+    /** 標準入力を最後まで読む（⛔ 失敗時の例外の文言は出さない） */
+    readStdin: () => Promise<string>;
+    readFile: (path: string) => Promise<string>;
+    stderr: (text: string) => void;
+}
+/** put を実行する。戻り値は終了コード（0 保存して一致／1 失敗／2 引数・入力の形／3 既に在る） */
+export declare function runSecretPut(argv: readonly string[], deps: SecretPutDeps): Promise<number>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluelamp/secret-exec",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "金庫の値を子プロセスの環境変数にだけ入れてコマンドを実行し（exec）、標準入力から金庫へ入れる（put）。値を画面・引数・ログに出さない口",
   "keywords": [
     "bluelamp",
@@ -11,7 +11,11 @@
   "author": "BlueLamp <dev@bluelamp.app>",
   "type": "module",
   "exports": {
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./handoff": {
+      "types": "./dist/handoff.d.ts",
+      "default": "./dist/handoff.js"
+    }
   },
   "bin": {
     "bluelamp-secret": "./bin/bluelamp-secret.mjs"