OpenCode Redactor

A lightweight, native TypeScript plugin for OpenCode. It masks sensitive information (API keys, PII, credentials) and high-entropy strings before text is sent to an LLM provider.

Features

• Zero Dependencies: Built using native TypeScript and Bun, ensuring fast startup and minimal footprint.
• Hybrid Detection Engine:
  • Regex Matching: Instantly identifies known patterns for AWS, GitHub, GitLab, Slack, Stripe, private keys, and emails.
  • Entropy Analysis: Uses Shannon entropy calculation to detect potential secrets that don't match specific regex patterns (e.g., random hex strings, passwords).
• Smart Masking: Replaces secrets with descriptive placeholders like <SECRET: AWSKeyDetector> or <SECRET: Base64HighEntropyString>, preserving context while hiding the original value.
• Pre-Send Hook Coverage: Masks both user chat text and tool output text via OpenCode hooks.
• Metadata-Only Audit Logs: Writes JSONL records without storing raw secret values.

Installation

This plugin is designed for the OpenCode environment.

1. Local Project Installation

Copy the plugin into your project's .opencode/plugins/ directory:

mkdir -p .opencode/plugins
cp opencode-redactor.ts .opencode/plugins/opencode-redactor.ts

Tip: during development, symlink instead of copying to avoid drift:

mkdir -p .opencode/plugins
ln -sf "$PWD/opencode-redactor.ts" .opencode/plugins/opencode-redactor.ts

2. Global Installation

To make the plugin available across all your OpenCode projects:

mkdir -p ~/.config/opencode/plugins
cp opencode-redactor.ts ~/.config/opencode/plugins/opencode-redactor.ts

3. Install via npm (recommended)

If you publish/install this plugin from npm, add it to your OpenCode config:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-redactor@0.1.1"]
}

OpenCode will install/load the package and run the plugin's default export.

Note: OpenCode currently imports npm plugins via a directory path. This package includes a root index.js entrypoint for compatibility.

Usage

Once installed, OpenCode loads the plugin automatically at startup.

This avoids “opportunistic tool calling” (where the model decides whether to call a tool after seeing your raw text).

Auto-Mask Before LLM (Plugin)

This repo is an OpenCode plugin. The source file is:

• opencode-redactor.ts (copy/symlink into .opencode/plugins/opencode-redactor.ts)

If you paste a secret into chat, it should be replaced with <SECRET: ...> placeholders before any upstream request is made.

To also protect secrets introduced by tools (file reads, command output, etc.), the plugin hooks:

• tool.execute.after

This masks tool outputs at the source so they are never printed/stored/sent unmasked in subsequent model turns.

Testing (Local)

1) Unit tests (masking behavior)

Run the bun tests in this repo:

bun test

2) Manual end-to-end test (OpenCode plugin)

1. Ensure the plugin files are in either:

   • Project: .opencode/plugins/
   • Global: ~/.config/opencode/plugins/

2. Restart OpenCode so it reloads plugins.

3. Test it out by sending a message with a fake secret:

export OPENCODE_REDACTOR_AUDIT_ENABLED=1
export OPENCODE_REDACTOR_AUDIT_PATH="$PWD/opencode-redactor.audit.jsonl"
rm -f "$OPENCODE_REDACTOR_AUDIT_PATH"

# In another terminal, watch the audit log:
# tail -f "$OPENCODE_REDACTOR_AUDIT_PATH"

echo "AKIAIOSFODNN7EXAMPLE" > secret-test.txt
opencode run "Read secret-test.txt and tell me what it contains"

# Then verify audit output:
cat "$OPENCODE_REDACTOR_AUDIT_PATH"

Configuration

You can tune entropy sensitivity by editing the constants near the top of opencode-redactor.ts:

const BASE64_ENTROPY_LIMIT = 4.5;
const HEX_ENTROPY_LIMIT = 3.0;
const MIN_LENGTH_FOR_ENTROPY = 16;

Local Audit Log

By default, when masking changes output text, the plugin appends a single JSON line (JSONL) to a local audit file so you can track usage and which detectors fired.

• Default path: ~/.config/opencode/opencode-redactor.audit.jsonl
• Disable logging: set OPENCODE_REDACTOR_AUDIT_ENABLED=0
• Override paths: OPENCODE_REDACTOR_AUDIT_DIR or OPENCODE_REDACTOR_AUDIT_PATH

Each audit line includes additional performance metadata:

• hook: chat.message or tool.execute.after
• durationMs: time spent masking for that hook invocation
• bytesIn / bytesOut: UTF-8 byte size before/after masking
• parts / partsChanged: part-level metrics for chat.message
• toolName: tool name for tool.execute.after when available

Supported Patterns

This plugin is deliberately conservative: it prefers high-confidence regex matches and only applies entropy masking in limited contexts.

Regex Detectors

When a match is found, the value is replaced with a placeholder like <SECRET: AWSKeyDetector>.

Content-Aware Detectors

These are not simple regex replacements across all text; they apply only in constrained contexts.