pentect 0.0.25

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EdamAme-x
+
+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,173 @@
+# Pentect
+
+Pentect is a local security boundary for AI coding tools. It replaces secrets
+and sensitive data with opaque handles before requests reach a model provider,
+then resolves those handles only at trusted client tool boundaries.
+
+Pentect currently supports Codex CLI, Claude Code, OpenCode, Pi, Codex App, and
+Claude Desktop. It also provides standalone masking commands and sandboxed
+WebAssembly plugins.
+
+> Pentect is pre-1.0 security software. Unknown provider formats are blocked by
+> default, but no filter can promise perfect detection. Keep provider and tool
+> permissions narrow and review the documented limitations before production
+> use.
+
+## Install
+
+Windows PowerShell:
+
+```powershell
+irm https://pentect.dev/install | iex
+```
+
+Linux and macOS:
+
+```sh
+curl -fsSL https://pentect.dev/install.sh | sh
+```
+
+The installers detect the platform, download a GitHub Release asset, and verify
+its SHA-256 checksum. Run `pentect doctor` after installation. Version-specific
+installation is supported with `-Version X.Y.Z` in PowerShell or
+`--version X.Y.Z` for `install.sh`.
+
+Package managers are also supported:
+
+```sh
+# Homebrew (macOS or Linux)
+brew install EdamAme-x/pentect/pentect
+
+# Nix
+nix profile install github:EdamAme-x/pentect
+
+# Nix, temporary shell
+nix shell github:EdamAme-x/pentect
+
+# Nix, pinned to a Pentect release
+nix profile install github:EdamAme-x/pentect/nix-vX.Y.Z
+
+# npm (downloads a checksummed release binary)
+npm install --global github:EdamAme-x/pentect
+
+# Cargo (builds from source)
+cargo install --git https://github.com/EdamAme-x/pentect --locked pentect-cli
+```
+
+Debian and Ubuntu users can configure the signed Pentect repository and install
+the package with one command:
+
+```sh
+curl -fsSL https://pentect.dev/install-apt.sh | sudo sh
+```
+
+When installed by Homebrew, Nix, or apt, use that package manager to update or
+remove Pentect. The CLI detects managed installations and will not overwrite
+package-owned files.
+
+## Use
+
+Launch a supported CLI through Pentect:
+
+```text
+pentect codex
+pentect claude
+pentect opencode --model openai/gpt-5
+pentect pi --model openai/gpt-5
+```
+
+Use a Responses- or Messages-compatible gateway without changing permanent
+client configuration:
+
+```text
+pentect codex --upstream http://127.0.0.1:8080/openai/v1
+pentect claude --upstream http://127.0.0.1:8080/anthropic
+pentect opencode --model anthropic/claude-sonnet --upstream http://127.0.0.1:8080/openai/v1
+pentect pi --model anthropic/claude-sonnet --upstream http://127.0.0.1:8080/openai/v1
+```
+
+Launch a desktop app only when explicitly requested:
+
+```text
+pentect codex app
+pentect claude app
+```
+
+These commands protect Codex mode and supported Claude Desktop Chat, Code, and
+attachment traffic; they do not claim coverage for every Chat, Work, Cowork,
+Voice, or future opaque route.
+
+Mask text from stdin while preserving opaque handles:
+
+```sh
+cat .env | pentect mask
+cat terraform.tfvars | pentect mask
+```
+
+PowerShell:
+
+```powershell
+Get-Content .env -Raw | pentect mask
+```
+
+Common maintenance commands:
+
+```text
+pentect doctor [--json | --fix [--yes]]
+pentect update [VERSION] [--check | --force]
+pentect uninstall
+pentect log [--json]
+```
+
+## What is protected
+
+- Prompts and local tool results sent through supported model gateways
+- Completed model tool-call arguments, resolved only for the local client tool
+- dotenv, Terraform, Kubernetes, kubeconfig, AWS, npm, PyPI, JSON, and other
+  recognized structured configuration
+- Inline images and documents that Pentect can inspect safely
+- Supported UTF-8 Files API uploads
+
+Binary uploads that Pentect cannot inspect or safely rewrite are blocked. File
+IDs and remote URLs are accepted only when Pentect can establish safe coverage;
+otherwise the configured unscanned-content policy applies.
+
+Unknown provider endpoints, content blocks, and malformed provider JSON are
+blocked by default. A user may explicitly select compatibility mode in the
+global configuration, but project configuration cannot weaken this policy.
+
+See [compatibility](COMPATIBILITY.md) for the release-tested client matrix.
+
+## Plugins
+
+Plugins are either declarative regex rules or portable WebAssembly middleware.
+Wasm plugins run without WASI, filesystem, environment, process, or raw socket
+access. Network destinations and payload-changing permissions require explicit
+approval.
+
+```text
+pentect plugins new NAME
+pentect plugins dev PATH
+pentect plugins publish PATH
+pentect plugins add github:@owner/repository/path
+pentect plugins list
+pentect plugins inspect NAME
+pentect plugins test NAME
+pentect plugins update NAME
+```
+
+See [PLUGINS.md](PLUGINS.md) for plugin authoring and security details.
+The Rust SDK is published as
+[`pentect-plugin`](https://crates.io/crates/pentect-plugin).
+The first-party catalog includes a one-file regex example and an optional
+[OpenAI Privacy Filter adapter](https://pentect.dev/plugins/official/).
+
+## Security and development
+
+Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
+Contributions are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+Pentect is licensed under the [MIT License](LICENSE).
+Third-party notices, including the bundled OCR model attribution, are available
+in [`THIRD_PARTY_LICENSES.txt`](THIRD_PARTY_LICENSES.txt) and are attached to
+each GitHub Release.

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "pentect",
+  "version": "0.0.25",
+  "type": "module",
+  "description": "Local secret masking boundary for AI agents",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EdamAme-x/pentect.git"
+  },
+  "homepage": "https://pentect.dev",
+  "bugs": "https://github.com/EdamAme-x/pentect/issues",
+  "bin": {
+    "pentect": "packaging/npm/bin/pentect.js"
+  },
+  "files": [
+    "packaging/npm/bin/pentect.js",
+    "packaging/npm/install.js",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node packaging/npm/install.js",
+    "test": "node --test packaging/npm/*.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/packaging/npm/bin/pentect.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const executable = fileURLToPath(new URL(`../vendor/${process.platform === 'win32' ? 'pentect.exe' : 'pentect'}`, import.meta.url));
+const result = spawnSync(executable, process.argv.slice(2), { stdio: 'inherit' });
+if (result.error) {
+  console.error(`pentect: ${result.error.message}`);
+  process.exitCode = 1;
+} else if (result.signal) {
+  process.kill(process.pid, result.signal);
+} else {
+  process.exitCode = result.status ?? 1;
+}

package/packaging/npm/install.js

@@ -0,0 +1,88 @@
+import { createHash } from 'node:crypto';
+import { chmod, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { gunzipSync } from 'node:zlib';
+
+const repository = 'EdamAme-x/pentect';
+const packageRoot = fileURLToPath(new URL('../..', import.meta.url));
+const destination = join(packageRoot, 'packaging', 'npm', 'vendor', process.platform === 'win32' ? 'pentect.exe' : 'pentect');
+
+export function releaseAsset(platform = process.platform, architecture = process.arch) {
+  const assets = {
+    'win32-x64': 'pentect-windows-x86_64.exe',
+    'linux-x64': 'pentect-linux-x86_64',
+    'linux-arm64': 'pentect-linux-aarch64',
+    'darwin-x64': 'pentect-macos-x86_64',
+    'darwin-arm64': 'pentect-macos-aarch64',
+  };
+  const asset = assets[`${platform}-${architecture}`];
+  if (!asset) throw new Error(`Pentect does not provide a binary for ${platform}/${architecture}`);
+  return asset;
+}
+
+export function expectedChecksum(text) {
+  const match = text.trim().match(/^([a-fA-F0-9]{64})(?:\s+\*?[^\s]+)?$/);
+  if (!match) throw new Error('The release checksum is invalid');
+  return match[1].toLowerCase();
+}
+
+async function download(url, signal) {
+  const response = await fetch(url, {
+    redirect: 'follow',
+    headers: { 'user-agent': 'pentect-npm-installer' },
+    signal,
+  });
+  if (!response.ok) throw new Error(`Download failed (${response.status} ${response.statusText})`);
+  return Buffer.from(await response.arrayBuffer());
+}
+
+async function downloadBinary(base, asset, signal) {
+  const compressed = await fetch(`${base}/${asset}.gz`, {
+    redirect: 'follow',
+    headers: { 'user-agent': 'pentect-npm-installer' },
+    signal,
+  });
+  if (compressed.ok) return gunzipSync(Buffer.from(await compressed.arrayBuffer()));
+  if (compressed.status !== 404) {
+    throw new Error(`Download failed (${compressed.status} ${compressed.statusText})`);
+  }
+  return download(`${base}/${asset}`, signal);
+}
+
+export async function install() {
+  const asset = releaseAsset();
+  const metadata = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8'));
+  const version = (process.env.PENTECT_VERSION || metadata.version)?.replace(/^v/, '');
+  const tag = version ? `v${version}` : 'latest';
+  const base = tag === 'latest'
+    ? `https://github.com/${repository}/releases/latest/download`
+    : `https://github.com/${repository}/releases/download/${tag}`;
+  const signal = AbortSignal.timeout(90_000);
+  const [binary, checksumFile] = await Promise.all([
+    downloadBinary(base, asset, signal),
+    download(`${base}/${asset}.sha256`, signal),
+  ]);
+  const expected = expectedChecksum(checksumFile.toString('utf8'));
+  const actual = createHash('sha256').update(binary).digest('hex');
+  if (actual !== expected) throw new Error('The release checksum does not match the downloaded binary');
+
+  await mkdir(dirname(destination), { recursive: true });
+  const temporary = `${destination}.${process.pid}.tmp`;
+  try {
+    await writeFile(temporary, binary, { mode: 0o755, flag: 'wx' });
+    await rm(destination, { force: true });
+    await rename(temporary, destination);
+    if (process.platform !== 'win32') await chmod(destination, 0o755);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}
+
+const invokedDirectly = process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1]);
+if (invokedDirectly) {
+  install().catch((error) => {
+    console.error(`pentect: ${error.message}`);
+    process.exitCode = 1;
+  });
+}