@skwid138/opencode-command-normalizer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hunter Hodnett
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# opencode-command-normalizer
+
+[![npm version](https://img.shields.io/npm/v/@skwid138/opencode-command-normalizer.svg)](https://www.npmjs.com/package/@skwid138/opencode-command-normalizer)
+[![CI](https://github.com/skwid138/opencode-command-normalizer/actions/workflows/ci.yml/badge.svg)](https://github.com/skwid138/opencode-command-normalizer/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Command normalization plugin for opencode permission matching.
+
+## Why
+
+opencode expands configured permission patterns such as `~/tool.sh` to absolute
+home paths when it loads configuration, but bash commands are matched against the
+raw command text. That means a command typed with a home-form `argv0` can miss an
+otherwise anchored allow rule unless the config falls back to broad wildcard
+patterns.
+
+This plugin rewrites only command-node `argv0` home forms to the equivalent
+absolute path before opencode's permission matcher sees the command. It is meant
+to let anchored absolute permission rules work without unsafe leading wildcards.
+
+## Install
+
+```sh
+npm install @skwid138/opencode-command-normalizer
+```
+
+Register it in opencode using the singular `plugin` config key in tuple form:
+
+```jsonc
+{
+  "plugin": [
+    [
+      "@skwid138/opencode-command-normalizer",
+      {
+        "roots": ["~/workspace/tools"],
+        "expandBraceHome": false
+      }
+    ]
+  ]
+}
+```
+
+Install the bare package name. The package also exposes `./server` for loaders
+that resolve that subpath, but user installation should use
+`@skwid138/opencode-command-normalizer`.
+
+## Configuration
+
+Options:
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `roots` | `string[]` | unset | Optional blast-radius limiter. Expanded `argv0` values outside configured roots are left unchanged. |
+| `expandBraceHome` | `boolean` | `false` | Enables `${HOME}` and `${HOME}/...` expansion at command-node starts. |
+| `homedir` | `string` | OS home directory | Test/advanced override for home expansion. |
+| `auditLogPath` | `string` | data-home audit log | Absolute path override for the NDJSON audit log. Relative paths are ignored. |
+| `debugLogPath` | `string` | data-home debug log | Absolute path override for debug messages. Relative paths are ignored. |
+
+Default logs resolve lazily at plugin startup. If `XDG_DATA_HOME` is set to a
+truthy absolute path, logs live below that directory; otherwise they live below
+`$HOME/.local/share`. The subfolder intentionally keeps the historical name
+`opencode/permission-audit-plugin` for continuity, even though the package is now
+named command-normalizer.
+
+`auditLogPath` and `debugLogPath` overrides must be absolute paths. Relative
+override values are ignored and the defaults are used instead, preserving the
+plugin's fail-open posture for malformed configuration.
+
+## How it works
+
+The plugin hooks `tool.execute.before` for bash tool executions and mutates
+`output.args.command` before opencode permission matching. It expands only home
+forms in `argv0` position at command-node starts:
+
+- `~`
+- `~/...`
+- `$HOME`
+- `$HOME/...`
+- optionally `${HOME}` and `${HOME}/...` when `expandBraceHome: true`
+
+Command nodes are split at shell separators such as `&&`, `||`, pipes,
+semicolons, ampersands, and newlines while respecting quotes. The plugin returns
+the original command unchanged for uncertain shell shapes such as heredocs,
+command substitution, arithmetic expansion, process substitution, unbalanced
+quotes, leading environment assignments, grouped commands, quoted `argv0`, and
+dot-dot `argv0` values when roots are configured.
+
+## Development
+
+```sh
+npm install
+npm test
+npm run build
+```
+
+`npm run build` emits declarations and verifies the public TypeScript surface.
+
+## Security
+
+This package is a normalization aid, not a policy engine. It should only rewrite
+to the path the shell would produce for home expansion, and it intentionally
+bails out instead of guessing on ambiguous shell syntax. See [SECURITY.md](SECURITY.md)
+for the command-rewrite scope and fail-open philosophy.
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,31 @@
+# Security
+
+`@skwid138/opencode-command-normalizer` rewrites bash command text before
+opencode's permission matcher sees it. Its scope is intentionally narrow:
+
+- It handles bash tool executions only.
+- It rewrites command-node `argv0` home forms only.
+- It rewrites to the same absolute path the shell would use for home expansion.
+- It never expands home forms in argument position.
+
+## Bail philosophy
+
+The plugin should prefer leaving a command unchanged over guessing. It bails out
+on uncertain shell shapes such as heredocs, command substitution, arithmetic
+expansion, process substitution, unbalanced quotes, grouped commands, leading
+environment assignments, quoted `argv0`, and dot-dot `argv0` values when roots
+are configured.
+
+Leaving the command unchanged means opencode's normal permission rules still
+decide whether to allow, deny, or ask.
+
+## Fail-open intent
+
+Malformed plugin options disable rewriting instead of blocking command execution.
+Audit and debug logging failures are swallowed or logged best-effort, so logging
+cannot change command execution. Relative audit/debug log overrides are ignored
+and replaced with default absolute paths.
+
+The plugin must not become a second policy engine. Policy remains in opencode's
+configured permissions; this package only normalizes command spelling so anchored
+rules can match consistently.

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import type { Plugin } from "@opencode-ai/plugin";
+export type CanonicalizeOptions = {
+    roots?: string[];
+    expandBraceHome?: boolean;
+    homedir?: string;
+};
+export type AuditRecord = {
+    ts: string;
+    sessionID: string;
+    agent: string | null;
+    callID: string;
+    command_node_text: string;
+};
+export type AuditContext = {
+    sessionID: string;
+    agent: string | null;
+    callID: string;
+    appendRecord: (record: AuditRecord) => Promise<void>;
+    debug: (message: string) => Promise<void>;
+};
+export declare function resolveDefaultLogPaths(env: Record<string, string | undefined>, homedir?: string): {
+    audit: string;
+    debug: string;
+};
+export declare function splitCommandNodes(command: string): string[];
+export declare function canonicalize(command: string, opts?: CanonicalizeOptions): string;
+export declare function canonicalizeAndAudit(command: string, opts: CanonicalizeOptions, context: AuditContext): Promise<string>;
+export declare const PermissionCanonicalizerPlugin: Plugin;
+declare const _default: {
+    server: Plugin;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,283 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import { homedir as osHomedir } from "node:os";
+import { dirname, isAbsolute, join } from "node:path";
+export function resolveDefaultLogPaths(env, homedir = osHomedir()) {
+    const xdg = env.XDG_DATA_HOME;
+    const base = xdg && isAbsolute(xdg) ? xdg : join(homedir, ".local", "share");
+    const dir = join(base, "opencode", "permission-audit-plugin");
+    return { audit: join(dir, "audit.log"), debug: join(dir, "debug.log") };
+}
+function hasUnbalancedQuotes(command) {
+    let quote = null;
+    let escaped = false;
+    for (const char of command) {
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (quote === '"' && char === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (quote) {
+            if (char === quote)
+                quote = null;
+            continue;
+        }
+        if (char === "'" || char === '"')
+            quote = char;
+    }
+    return quote !== null || escaped;
+}
+function hasGlobalBailShape(command) {
+    return (hasUnbalancedQuotes(command) ||
+        command.includes("<<") ||
+        command.includes("$((") ||
+        command.includes("$(") ||
+        command.includes("`") ||
+        command.includes("<(") ||
+        command.includes(">("));
+}
+function separatorLength(command, index) {
+    const two = command.slice(index, index + 2);
+    if (two === "&&" || two === "||" || two === "|&")
+        return 2;
+    const one = command[index];
+    if (one === "|" || one === ";" || one === "&" || one === "\n")
+        return 1;
+    return 0;
+}
+function commandSegments(command) {
+    const segments = [];
+    let quote = null;
+    let escaped = false;
+    let start = 0;
+    for (let index = 0; index < command.length; index += 1) {
+        const char = command[index];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (quote === '"' && char === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (quote) {
+            if (char === quote)
+                quote = null;
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            quote = char;
+            continue;
+        }
+        const length = separatorLength(command, index);
+        if (length > 0) {
+            segments.push({ text: command.slice(start, index), start, end: index });
+            index += length - 1;
+            start = index + 1;
+        }
+    }
+    if (quote !== null || escaped)
+        return null;
+    segments.push({ text: command.slice(start), start, end: command.length });
+    return segments;
+}
+export function splitCommandNodes(command) {
+    return (commandSegments(command) ?? [{ text: command, start: 0, end: command.length }])
+        .map((segment) => segment.text.trim())
+        .filter(Boolean);
+}
+function expandHomeForm(argv0, home, expandBraceHome) {
+    if (argv0 === "~")
+        return home;
+    if (argv0.startsWith("~/"))
+        return `${home}${argv0.slice(1)}`;
+    if (argv0 === "$HOME")
+        return home;
+    if (argv0.startsWith("$HOME/"))
+        return `${home}${argv0.slice("$HOME".length)}`;
+    if (expandBraceHome && argv0 === "${HOME}")
+        return home;
+    if (expandBraceHome && argv0.startsWith("${HOME}/"))
+        return `${home}${argv0.slice("${HOME}".length)}`;
+    return null;
+}
+function normalizeRoot(root, home, expandBraceHome) {
+    const expanded = expandHomeForm(root, home, expandBraceHome) ?? root;
+    if (!expanded.startsWith("/") || expanded.split("/").includes(".."))
+        return null;
+    return expanded.replace(/\/+$/, "");
+}
+function isUnderRoot(path, root) {
+    return path === root || path.startsWith(`${root}/`);
+}
+function rewriteSegment(segment, options) {
+    const leading = segment.match(/^\s*/)?.[0] ?? "";
+    const rest = segment.slice(leading.length);
+    if (!rest)
+        return segment;
+    if (rest.startsWith("(") || rest.startsWith("{"))
+        return null;
+    if (rest.startsWith("'") || rest.startsWith('"'))
+        return null;
+    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(rest))
+        return null;
+    const argv0Match = rest.match(/^\S+/);
+    if (!argv0Match)
+        return segment;
+    const argv0 = argv0Match[0];
+    if (argv0.includes("'") || argv0.includes('"'))
+        return null;
+    if (options.normalizedRoots && argv0.includes(".."))
+        return null;
+    const expanded = expandHomeForm(argv0, options.homedir, options.expandBraceHome);
+    if (!expanded)
+        return segment;
+    if (options.normalizedRoots && !options.normalizedRoots.some((root) => isUnderRoot(expanded, root))) {
+        return segment;
+    }
+    return `${leading}${expanded}${rest.slice(argv0.length)}`;
+}
+export function canonicalize(command, opts = {}) {
+    if (hasGlobalBailShape(command))
+        return command;
+    const home = opts.homedir ?? osHomedir();
+    const expandBraceHome = opts.expandBraceHome ?? false;
+    const normalizedRoots = opts.roots
+        ? opts.roots.map((root) => normalizeRoot(root, home, expandBraceHome))
+        : null;
+    if (normalizedRoots?.some((root) => root === null))
+        return command;
+    const segments = commandSegments(command);
+    if (!segments)
+        return command;
+    const settings = {
+        homedir: home,
+        expandBraceHome,
+        roots: opts.roots ?? [],
+        normalizedRoots: normalizedRoots,
+    };
+    let rewritten = "";
+    let cursor = 0;
+    for (const segment of segments) {
+        const replacement = rewriteSegment(segment.text, settings);
+        if (replacement === null)
+            return command;
+        rewritten += command.slice(cursor, segment.start) + replacement;
+        cursor = segment.end;
+    }
+    rewritten += command.slice(cursor);
+    return rewritten;
+}
+export async function canonicalizeAndAudit(command, opts, context) {
+    const canonical = canonicalize(command, opts);
+    const auditNodes = canonical === command && hasGlobalBailShape(command) ? [command] : splitCommandNodes(canonical);
+    const records = auditNodes.map((node) => ({
+        ts: new Date().toISOString(),
+        sessionID: context.sessionID,
+        agent: context.agent,
+        callID: context.callID,
+        // Keep the exact node text the plugin saw. The Python join intentionally
+        // does not strip trailing redirections from this field because opencode's
+        // AST-to-permission-pattern behavior is not specified tightly enough to do
+        // that without risking a wrong-agent attribution.
+        command_node_text: node,
+    }));
+    for (const record of records) {
+        try {
+            await context.appendRecord(record);
+        }
+        catch (error) {
+            await context.debug(`permission audit append failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return canonical;
+}
+function parseOptions(options) {
+    const defaults = resolveDefaultLogPaths(process.env);
+    if (options === undefined) {
+        return { enabled: true, canonicalizeOptions: {}, auditLogPath: defaults.audit, debugLogPath: defaults.debug };
+    }
+    if (typeof options !== "object" || options === null || Array.isArray(options)) {
+        return { enabled: false, canonicalizeOptions: {}, auditLogPath: defaults.audit, debugLogPath: defaults.debug };
+    }
+    const raw = options;
+    if (raw.roots !== undefined && (!Array.isArray(raw.roots) || !raw.roots.every((root) => typeof root === "string"))) {
+        return { enabled: false, canonicalizeOptions: {}, auditLogPath: defaults.audit, debugLogPath: defaults.debug };
+    }
+    if (raw.expandBraceHome !== undefined && typeof raw.expandBraceHome !== "boolean") {
+        return { enabled: false, canonicalizeOptions: {}, auditLogPath: defaults.audit, debugLogPath: defaults.debug };
+    }
+    const home = typeof raw.homedir === "string" ? raw.homedir : osHomedir();
+    const expandBraceHome = raw.expandBraceHome ?? false;
+    if (raw.roots?.some((root) => normalizeRoot(root, home, expandBraceHome) === null)) {
+        return { enabled: false, canonicalizeOptions: {}, auditLogPath: defaults.audit, debugLogPath: defaults.debug };
+    }
+    return {
+        enabled: true,
+        canonicalizeOptions: {
+            roots: raw.roots,
+            expandBraceHome: raw.expandBraceHome,
+            homedir: raw.homedir,
+        },
+        auditLogPath: typeof raw.auditLogPath === "string" && isAbsolute(raw.auditLogPath) ? raw.auditLogPath : defaults.audit,
+        debugLogPath: typeof raw.debugLogPath === "string" && isAbsolute(raw.debugLogPath) ? raw.debugLogPath : defaults.debug,
+    };
+}
+export const PermissionCanonicalizerPlugin = async (_ctx, options) => {
+    const parsed = parseOptions(options);
+    const sessionAgents = new Map();
+    async function debug(message) {
+        try {
+            await mkdir(dirname(parsed.debugLogPath), { recursive: true });
+            await appendFile(parsed.debugLogPath, `${new Date().toISOString()} ${message}\n`, "utf8");
+        }
+        catch {
+            // Debug logging must never affect command execution.
+        }
+    }
+    if (!parsed.enabled) {
+        await debug("permission canonicalizer disabled due to malformed config");
+        return {};
+    }
+    await mkdir(dirname(parsed.auditLogPath), { recursive: true }).catch((error) => debug(`audit directory init failed: ${error}`));
+    await mkdir(dirname(parsed.debugLogPath), { recursive: true }).catch(() => undefined);
+    function rememberAgent(input) {
+        if (typeof input !== "object" || input === null)
+            return;
+        const record = input;
+        if (typeof record.sessionID === "string" && typeof record.agent === "string") {
+            sessionAgents.set(record.sessionID, record.agent);
+        }
+    }
+    return {
+        "chat.params": async (input) => {
+            rememberAgent(input);
+        },
+        "chat.message": async (input) => {
+            rememberAgent(input);
+        },
+        "tool.execute.before": async (input, output) => {
+            const toolInput = input;
+            const toolOutput = output;
+            if (toolInput.tool !== "bash" || typeof toolOutput.args?.command !== "string")
+                return;
+            const original = toolOutput.args.command;
+            const sessionID = typeof toolInput.sessionID === "string" ? toolInput.sessionID : "";
+            const callID = typeof toolInput.callID === "string" ? toolInput.callID : "";
+            const canonical = await canonicalizeAndAudit(original, parsed.canonicalizeOptions, {
+                sessionID,
+                callID,
+                agent: sessionAgents.get(sessionID) ?? null,
+                appendRecord: async (record) => {
+                    await appendFile(parsed.auditLogPath, `${JSON.stringify(record)}\n`, "utf8");
+                },
+                debug,
+            });
+            toolOutput.args.command = canonical;
+            await debug(canonical === original ? `pass-through: ${original}` : `rewrite: ${original} -> ${canonical}`);
+        },
+    };
+};
+export default { server: PermissionCanonicalizerPlugin };

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@skwid138/opencode-command-normalizer",
+  "version": "0.1.0",
+  "description": "Command normalization plugin for opencode permission matching",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./server": {
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "SECURITY.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build",
+    "prepare": "husky || true"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "^1.15.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^21.0.2",
+    "@commitlint/config-conventional": "^21.0.2",
+    "@opencode-ai/plugin": "^1.15.0",
+    "@opencode-ai/sdk": "^1.15.0",
+    "@types/node": "^22.0.0",
+    "husky": "^9.1.7",
+    "semantic-release": "^25.0.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/skwid138/opencode-command-normalizer.git"
+  },
+  "homepage": "https://github.com/skwid138/opencode-command-normalizer",
+  "bugs": {
+    "url": "https://github.com/skwid138/opencode-command-normalizer/issues"
+  },
+  "license": "MIT",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "plugin",
+    "permission",
+    "bash",
+    "canonicalize",
+    "security"
+  ]
+}