@te-river/opencode-team-mode 1.5.0 → 1.5.2

package/dist/envprotect.d.ts

@@ -0,0 +1,234 @@
+/**
+ * R6 — code-level environment-variable read protection for Team mode.
+ *
+ * HUMAN-approved feature: in Team mode, EVERY path the model can use to
+ * read environment variables / env files is intercepted in code, before
+ * the tool runs, independent of prompt compliance. This hook throws inside
+ * `tool.execute.before`, which opencode (verified live on 1.18.29) turns
+ * into a failed tool call whose error text is returned to the model — so
+ * the block is hard, not advisory.
+ *
+ * Surfaces covered (bash + PowerShell dialects, matched against the bash
+ * tool's `args.command`, and against path-class args of the read / grep /
+ * glob / list tools):
+ *   1. explicit env commands: `env` — a dump whenever no outside command
+ *      word follows: flags/assignments only (`env -0`, `env -u HOME`,
+ *      `env FOO=bar`) or a command word that is itself `env`/`printenv`
+ *      (`env printenv`); a real launcher (`env node app.js`, `env -i node
+ *      app.js`) passes — `printenv`, bare `set` (sh context only —
+ *      PowerShell `Set-*` cmdlets are never matched), `declare -p` and
+ *      its dump synonyms `typeset -p` / `export -p` / `local -p` (flags
+ *      may be split: `declare -x -p FOO`), and the PowerShell `env:`
+ *      drive via Get-ChildItem / gci / dir / ls / Get-Item / gi /
+ *      Get-Content / gc / cat / type (flags and optional quotes allowed
+ *      between cmdlet and drive: `Get-Content 'env:HOME'`).  The same
+  *      statement heads are caught behind statement noise: subshells and
+  *      groups (`(env)`, `{ env; }`), escaped commands (`\env`), the `time`
+  *      keyword prefix, command substitution (`$(printenv)`, backticks), the
+  *      program-path twins of the dump heads (bare `/usr/bin/env` = full
+  *      dump, `/usr/bin/printenv …`), and the Windows launcher head
+  *      (`cmd /c set` = cmd.exe's own caseless full dump; `/k` and quoted
+  *      inners included).
+ *   2. `$env:` / `${env:...}` expansion (PowerShell);
+ *   3. strict mode only: `${VAR}` and `$ALLCAPS_VAR` expansion;
+ *   4. env-file paths: `.env`, `.env.*`, `*.env`, `.bashrc`,
+ *      `.bash_profile`, `.profile`, `.zshrc`, `.zprofile`, `.zshenv`
+ *      (checked-in template copies like `.env.example` are exempt, and
+ *      code identifiers like `process.env` are not files).
+ *
+ * TeamMode's own tm_* tools (tm_read / tm_grep / tm_bash) are aliased onto
+ * read/grep/bash in `inspectToolCall`, so this interception covers them
+ * identically — the plugin tools can never serve as an R6 bypass.
+ *
+ * Known limitation (accepted, documented): interpreter execution paths —
+ * `bash -c "env"`, `node -e 'process.env'`, `python -c "import os; ..."` —
+ * are NOT intercepted; the pattern surface stops at the command line
+ * itself.  One decode pass covers URL-encoded names (`/%2Eenv`); a double
+ * encoding (`/%252Eenv`) and a quoted dump head behind `env`
+ * (`env 'printenv'`) stay ahead of the matcher by design.
+ *
+ * Configuration (read by the PLUGIN at startup — this is program-level
+ * configuration of the tool itself, the same category as the ttlDays
+ * option below; it is NOT what R6 defends against, which is the MODEL
+ * reading environment variables through tool calls at runtime):
+ *   - `TM_ENV_PROTECT`       = "strict" (default) | "standard" | "off";
+ *     unknown values fail closed into strict.
+ *   - `TM_ENV_PROTECT_EXTRA_DENY` = semicolon-separated user regexes,
+ *     applied to every scanned string in any non-off mode.
+ *
+ * Audit red line (HUMAN privacy constraint): every interception is logged
+ * via `client.app.log()` (level "warn", service "team-mode-env-protect")
+ * recording ONLY the tool name and the pattern category. Command text,
+ * paths, variable names and values are NEVER logged — the audit trail must
+ * answer "what class of read was blocked", and must not become a place
+ * where secrets accumulate.
+ */
+/** Audit log service identifier (also the query key for "what was blocked"). */
+export declare const ENV_PROTECT_SERVICE = "team-mode-env-protect";
+/**
+ * Fixed structured message returned to the model on every block.  The
+ * category is appended as a machine-readable suffix; tests pin both.
+ */
+export declare const ENV_PROTECT_MESSAGE = "TeamMode R6 env protection: \u73AF\u5883\u53D8\u91CF\u8BFB\u53D6\u5DF2\u88AB\u62E6\u622A\u3002\u9700\u8981\u53D8\u91CF\u503C\u8BF7\u5411 HUMAN \u7533\u8BF7\u3002";
+/** Pattern categories surfaced in the block message and the audit log. */
+export declare const CATEGORY_BASH_ENV_COMMAND = "bash-env-command";
+export declare const CATEGORY_BASH_ENV_EXPANSION = "bash-env-expansion";
+export declare const CATEGORY_ENV_FILE_PATH = "env-file-path";
+export declare const CATEGORY_EXTRA_DENY = "extra-deny";
+/**
+ * Two faces are routed to the OpenCode official confirmation dialog by
+ * declaring them `ask` in each agent's bash permission object.  The host
+ * pops a dialog for any command matching one of these patterns and SUSPENDS
+ * it: a human reply ("once"/"always") runs the command, a "reject" or NO
+ * REPLY is handled by the approval timer (Layer 2, see approval-gate.ts)
+ * which auto-REJECTS after TM_ASK_TIMEOUT_MIN.  The plugin NEVER self-allows.
+ *
+ * These are the shapes a wildcard CAN express (head-anchored globs, matching
+ * the probe-verified grammar: `printenv*`, `rm *`, `Get-ChildItem env:*`).
+ * Wildcards CANNOT express (embedded `${VAR}` / `$ALLCAPS` / `$env:` inside
+ * another command, command substitution `$(printenv)`, subshell/escaped/
+ * `time`-prefixed heads, `VAR=… env` assignment prefixes, split `declare -xp`,
+ * env-file paths at arbitrary positions) stay the classifier's HARD THROW —
+ * that is the `isAskGatedEnvCommand` boundary, kept in lockstep with the
+ * classifier so a form we stop throwing on is exactly a form the dialog shows.
+ */
+/** R6 env face — the wildcard-expressible environment-variable reads. */
+export declare const R6_ENV_BASH_ASK: Readonly<Record<string, "ask">>;
+/** R2 danger face — destructive / publishing / network / install / process /
+ *  privilege commands.  Independent of TM_ENV_PROTECT (R2 is its own red
+ *  line); the built-in bash tool stays `allow` for everything else, so the
+ *  normal verification stack (npm test, tsc, git status/diff) never pops. */
+export declare const R2_DANGER_BASH_ASK: Readonly<Record<string, "ask">>;
+/** Ordered key lists (frozen) — single source for the matcher + the gate. */
+export declare const R6_ENV_BASH_ASK_PATTERNS: readonly string[];
+export declare const R2_DANGER_BASH_ASK_PATTERNS: readonly string[];
+/**
+ * The bash permission object injected into the four execution-role agents
+ * (team / implementer / reviewer / tester).  Default stays `allow`
+ * (`"*": "allow"`, preserving the T2.1 matrix semantics — bash is granted,
+ * not removed); only the listed shapes escalate to the host dialog.  The R6
+ * env face is dropped when `mode === "off"` (the R6 kill switch) AND when
+ * `envFace` is false — index.ts passes false while the approval gate cannot
+ * arm: the R6 hook then hard-throws every env read BEFORE its dialog could
+ * ever satisfy it, so injecting the env asks would only create dead popups
+ * a human can answer yet never make runnable.  The R2 face is always
+ * present (its dialog is the whole gate — no code-level throw is involved).
+ */
+export declare function bashAskPatterns(mode: EnvProtectMode, envFace?: boolean): Record<string, string>;
+export type EnvProtectMode = "strict" | "standard" | "off";
+/**
+ * Resolve the protection mode.  Only exact "standard" / "off" switch those
+ * modes on; everything else (unset, typos, wrong case) fails CLOSED into
+ * strict — a mistyped opt-out must never disable the red line.
+ */
+export declare function resolveEnvProtectMode(raw: unknown): EnvProtectMode;
+/**
+ * Parse `TM_ENV_PROTECT_EXTRA_DENY` (semicolon-separated regex bodies).
+ * Invalid regexes are skipped rather than crashing plugin startup; the
+ * remaining rules still apply.  Empty/absent input yields no extra rules.
+ */
+export declare function parseExtraDeny(raw: unknown): RegExp[];
+/** The block error handed back to the model (fixed text + category tag). */
+export declare function envProtectError(category: string): Error;
+/**
+ * True when the value points at an env file.  Matches on the BASENAME with
+ * both separators handled; URL query/fragment tails are cut first so
+ * `https://x/.env?raw=1` matches the same basename as a plain path, and
+ * asterisks are stripped so glob patterns like "*.env" or a recursive deep
+ * form of ".env.local" are caught by the same matcher as real paths.
+ * (Note: glob spellings are written without backticks here — a double-star
+ * + slash inside JSDoc would close the comment block early.)
+ */
+export declare function isEnvFilePath(raw: string): boolean;
+/**
+ * Classify a bash/PowerShell command string.  Returns the pattern category
+ * when the command must be blocked, null when it may pass.  `off` is
+ * handled by the caller; user extra-deny rules take precedence.
+ */
+export declare function classifyBashCommand(command: string, mode: EnvProtectMode, extra?: RegExp[]): string | null;
+/** True when `text` matches ANY of the given ask globs (LOOSE, host-style). */
+export declare function commandMatchesAnyAskPattern(text: unknown, patterns: readonly string[]): boolean;
+/**
+ * True when a built-in-bash command is an environment read in a form the
+ * host is configured to ASK about (and therefore the dialog governs it).
+ * The hook then lets it proceed WITHOUT throwing, so a human approval is
+ * meaningful.  Kept deliberately narrower than classifyBashCommand: every
+ * form it accepts is a head-anchored single statement that matches one of
+ * R6_ENV_BASH_ASK BYTE-EXACTLY (so the dialog WILL fire under any host
+ * grammar at least as greedy as ours — no case/trim leniency, see
+ * commandMatchesAnyAskPatternExact), and every hazard that breaks that
+ * alignment (compound statements, substitutions, `${…}`, `$ALLCAPS`,
+ * assignment prefixes, `time`/subshell/escaped heads, user extra-deny, path
+ * heads like `/usr/bin/env`, `cmd /c …`, and the PowerShell env-drive forms
+ * with intervening flags or quotes that the globs miss) returns false → the
+ * classifier keeps hard-throwing.  tm_* channels are hard-blocked separately
+ * (the dialog never opens for them).
+ */
+export declare function isAskGatedEnvCommand(command: string, mode: EnvProtectMode, extra?: RegExp[]): boolean;
+/**
+ * Coarse category for a host permission-event payload, used ONLY to gate the
+ * timer, to register the deferral session, and to tag the audit (never the
+ * pattern text itself).  Returns null for anything that is not one of OUR
+ * injected bash asks, so the gate leaves other tools' dialogs (edit,
+ * webfetch, host-native rules) alone.
+ *
+ * Real 1.18.29 `permission.asked` props carry NO `type` field: the tool name
+ * rides in `permission` and the concrete command segments in `patterns[]`
+ * (plus `metadata.command` with the raw line).  Inference order, defensive
+ * across builds:
+ *   1. explicit tool field (`type` || `permission`) — non-bash is a hard no;
+ *   2. absent tool field → bash evidence = `metadata.command` present, or a
+ *      candidate that is COMMAND-SHAPED (contains whitespace: our command
+ *      globs all need an embedded space except bare keys, and bare-key
+ *      patterns like a file named `set` cannot prove bash without the
+ *      command metadata beside them).
+ * Matching here is the LOOSE glob (case-insensitive): over-matching can only
+ * arm a timer for a dialog the host already opened, never run a command —
+ * the deferral side keeps the byte-exact matcher (isAskGatedEnvCommand).
+ */
+export declare function categorizePermission(props: {
+    type?: string;
+    permission?: string;
+    pattern?: string | string[];
+    patterns?: string | string[];
+    title?: string;
+    metadata?: Record<string, unknown>;
+} | null | undefined): "env" | "danger" | null;
+/**
+ * Classify the path-class arguments of a file tool.  Returns the pattern
+ * category when the call must be blocked, null when it may pass.
+ */
+export declare function classifyPathFields(args: Record<string, unknown> | undefined, mode: EnvProtectMode, extra?: RegExp[]): string | null;
+/**
+ * Top routing: tool name + tool args -> category to block, or null to pass.
+ * `off` always passes (the hook stays installed but is a no-op).
+ */
+export declare function inspectToolCall(tool: string, args: Record<string, unknown> | undefined, mode: EnvProtectMode, extra?: RegExp[]): string | null;
+/**
+ * Build the `tool.execute.before` hook.  The hook is installed in every
+ * mode; with mode "off" it returns immediately and everything passes.
+ * When a block triggers, the audit entry is written first, then the fixed
+ * structured error is thrown so opencode surfaces it to the model as the
+ * failed tool result.
+ *
+ * `options.deferToApproval` (the unified approval gate) — called with the
+ * tool call's `input.sessionID`; when it reports `true`, a built-in-bash
+ * environment read in an EXACT ask-glob form is passed through WITHOUT
+ * throwing, because the official confirmation dialog is the live gate for
+ * it (approve → runs, reject or timeout → the host blocks it).  The signal
+ * is SESSION-SCOPED on purpose: the gate registers only sessions carrying
+ * our injected bash ask set (exec-role chat.message, or an R6-env-classified
+ * `permission.asked`), so a stock build/plan session — where no dialog would
+ * ever open for `printenv` — keeps the hard throw instead of slipping the
+ * read through a global arm flag.  Reaching the deferral point at all
+ * additionally requires the command to match the config globs byte-exactly,
+ * so the dialog is GUARANTEED to fire wherever deferral happens.  A failed
+ * auto-reject flips the gate back to `false` everywhere, restoring the hard
+ * throw (fail-closed).  tm_* channels are never deferred (no dialog opens
+ * for them).
+ */
+export declare function createEnvProtectHook(client: unknown, mode: EnvProtectMode, extra?: RegExp[], options?: {
+    deferToApproval?: (sessionID?: string) => boolean;
+    envApproved?: (sessionID?: string) => boolean;
+}): (input: unknown, output: unknown) => Promise<void>;
+//# sourceMappingURL=envprotect.d.ts.map

package/dist/envprotect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envprotect.d.ts","sourceRoot":"","sources":["../src/envprotect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH,gFAAgF;AAChF,eAAO,MAAM,mBAAmB,0BAA0B,CAAA;AAE1D;;;GAGG;AACH,eAAO,MAAM,mBAAmB,sKAC4B,CAAA;AAE5D,0EAA0E;AAC1E,eAAO,MAAM,yBAAyB,qBAAqB,CAAA;AAC3D,eAAO,MAAM,2BAA2B,uBAAuB,CAAA;AAC/D,eAAO,MAAM,sBAAsB,kBAAkB,CAAA;AACrD,eAAO,MAAM,mBAAmB,eAAe,CAAA;AAK/C;;;;;;;;;;;;;;;;GAgBG;AAEH,yEAAyE;AACzE,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAyB1D,CAAA;AAEF;;;6EAG6E;AAC7E,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CA6C7D,CAAA;AAEF,6EAA6E;AAC7E,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAErD,CAAA;AACD,eAAO,MAAM,2BAA2B,EAAE,SAAS,MAAM,EAExD,CAAA;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,UAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAO5F;AAED,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,UAAU,GAAG,KAAK,CAAA;AAE1D;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAIlE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,EAAE,CAarD;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,CAEvD;AAyBD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAiClD;AAuKD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,cAAc,EACpB,KAAK,GAAE,MAAM,EAAO,GACnB,MAAM,GAAG,IAAI,CA2Cf;AAwCD,+EAA+E;AAC/E,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAK/F;AAYD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,cAAc,EACpB,KAAK,GAAE,MAAM,EAAO,GACnB,OAAO,CAyBT;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAC3B,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,IAAI,CA2B7C;AAaD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACzC,IAAI,EAAE,cAAc,EACpB,KAAK,GAAE,MAAM,EAAO,GACnB,MAAM,GAAG,IAAI,CAWf;AAoBD;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACzC,IAAI,EAAE,cAAc,EACpB,KAAK,GAAE,MAAM,EAAO,GACnB,MAAM,GAAG,IAAI,CAYf;AA0CD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,cAAc,EACpB,KAAK,GAAE,MAAM,EAAO,EACpB,OAAO,GAAE;IAAE,eAAe,CAAC,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAA;CAAO,GACjH,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAqBpD"}