05/api

CLI Flags & Programmatic API Reference

Complete specification for the unpeek CLI binary, Node.js programmatic functions, and TypeScript interfaces exported from packages/unpeek/src/types.ts.

CLI Commands & Defense Tiers (Tier 1 / Tier 2 / Tier 3)

The `unpeek` binary supports `init`, `protect`, `check`, and `symbolicate` commands across three defense tiers:

Tier 1 (`--profile minimal`): Fast baseline with `coldFlow: false`, `mangler.minLength: 1`, hot-path exemption, and order-independent `globalThis` shield (<2% CPU, <15% Gzip).

Tier 2 (`--profile recommended` / Default): Adds 92-char zero-escape string vaulting, `>=4`-var semi-linear MBA + degree-3 Rivest QNR cold-flow guards, and in-place `Uint8Array` shader vaulting.

Tier 3 (`--profile strict` / `--aggressive`): Targets `@unpeek-critical` enclaves and `critical.include` functions with the 43-opcode Micro-VM v2, shared `<1.2 KB` host-coupled WASM KDF, 64-bit call-site salted decoders, and CWE-540 path scrubbing.

CLI Reference
  ▛▀▀▜  unpeek 3.0.0
  ▙▄▄▟  client bundle protection

  Usage:
    unpeek init [--dry-run] [--profile <name>]   wire postbuild and the .unpeek-maps/ vault
    unpeek protect [options]                     protect client bundles in place (Tier 1 default: <2% CPU, <15% Gzip)
    unpeek check [options]                       read-only CI gate for leaks, ignores, budget, and CSP
    unpeek symbolicate [options]                 resolve stack traces locally using .unpeek-maps/

  Options (protect):
    --profile <name>               preset profile: minimal | recommended | strict
    --dry-run                      compute transform & Gzip delta in memory without writing files
    --max-gzip-delta <num>         fail if Gzip delta exceeds percentage
    --out-dir <dir>                explicit client output directory
    --seed <number>                deterministic polymorphic seed
    --passive                      passive deterrent mode (default: marks tamper, keeps console)
    --gradual                      gradual deterrent mode (silences console on tamper)
    --detect-headless              treat navigator.webdriver / HeadlessChrome as tamper
    --no-maps                      delete .map files instead of vaulting them
    --min-string-length <num>      minimum string length for the vault (default: 4)
    --private-maps-dir <dir>       vault directory (default: .unpeek-maps)
    --no-shield                    skip the runtime anti-tamper shield
    --aggressive                   enable Tier 2 aggressive protection (Micro-VM & WASM KDF)
    -h, --help                     show help
    -v, --version                  show version

  Tiers:
    Tier 1 (default)               call-graph hot-path exemption (<2% CPU, <15% Gzip)
    Tier 2 (--aggressive)          zero plaintext exposure via Micro-VM & WASM KDF

Programmatic Node.js API & TypeScript Types

Import `protectProject`, `transformJavaScript`, `checkProject`, `symbolicateStackTrace`, `PRESETS`, `isUnpeekError`, or bundler plugins directly from `unpeek` to build custom compilation pipelines.

TypeScript: Programmatic Usage & Exported Interfaces
import {
  PRESETS,
  protectProject,
  transformJavaScript,
  checkProject,
  symbolicateStackTrace,
  isUnpeekError,
  type ProtectOptions,
  type ProtectSummary,
  type TransformOptions,
  type TransformResult,
  type UnpeekDiagnostic,
  type UnpeekProfile,
} from "unpeek";

// 1. Transform a single JavaScript module in memory
const result: TransformResult = transformJavaScript(sourceCode, {
  seed: 0x10b981,
  minStringLength: 4,
  injectRuntimeShield: true,
  deterrentMode: "passive",
  aggressive: true,
  scrubPaths: true,
});

console.log(result.hotPathReport.hotFunctionsSkipped);
console.log(result.encryptedStringsCount, result.virtualizedFunctionsCount);

// 2. Protect an entire framework build directory
const summary: ProtectSummary = await protectProject({
  cwd: process.cwd(),
  profile: "recommended",
  keepPrivateMaps: true,
  privateMapsDir: ".unpeek-maps",
  deterrentMode: "passive",
  aggressive: false,
});

Configuration Schema & Options (UnpeekConfig)

The `UnpeekConfig` interface governs build heuristics, string encryption boundaries, symbol mangling rules, and source map storage. Configurations are resolved in hierarchical precedence: CLI flags > programmatic options > discovered config file > preset profile (`PRESETS`).

Config files are automatically discovered across `unpeek.config.js`, `unpeek.config.mjs`, `unpeek.config.cjs`, and `unpeek.config.json` (or `unpeek.config.ts` with TypeScript loaders).

  • `hotPath`: Configure `customAnimationCalls` (e.g. `['requestAnimationFrame', 'useFrame']`), `customHooks` (e.g. `['useSpring', 'useGesture']`), `arrayHofMethods`, `hocWrappers`, and `maxPipelineCallers` (default `2`) for transitive exemption.
  • `vault`: Configure `minStringLength` (default `4`), `cssFramework` (`'tailwind'` | `'unocss'` | `'none'`), `customDirectives`, `reservedProps`, `semanticAnchors`, `polymorphicDecoys` (default `true`), and `fragmented` / `fragmentCount`.
  • `critical` / `tier` / `coldFlow`: Select `'Tier 1' | 'Tier 2' | 'Tier 3'`, toggle `coldFlow`, and target `@unpeek-critical` annotations or `critical.include` patterns (up to `maxFunctionsPerChunk`, default `12`).
  • `mangler`: Set `minLength` (default `1` across presets) plus `reservedIdentifiers`, `excludePrefixes`, and `excludePatterns` (RegExp array) to protect critical runtime globals.
  • `scrubPaths`: Strip local filesystem paths (`rootDir`, `[project]/`, `webpack://`, Windows `C:\`) and residual dev metadata (CWE-540).
  • `next` / `vite`: Specify `next.distDir` for custom Next.js output directories, or `vite.outDir` / `vite.assetsDir` for custom Vite distributions.
unpeek.config.ts: Complete Schema Example
import { defineConfig, type UnpeekConfig } from "unpeek";

export default defineConfig({
  target: "browser",
  filter: {
    exclude: ["node_modules/**", "**/*.test.*", "**/*.spec.*"],
  },
  hotPath: {
    customAnimationCalls: ["requestAnimationFrame", "useFrame"],
    customHooks: ["useSpring", "useGesture"],
    arrayHofMethods: ["map", "filter", "forEach", "reduce"],
    maxPipelineCallers: 2,
  },
  vault: {
    minStringLength: 4,
    cssFramework: "tailwind",
    semanticAnchors: {
      excludeUiClasses: true,
    },
    polymorphicDecoys: true,
  },
  mangler: {
    reservedIdentifiers: ["__NEXT_DATA__", "process"],
    excludePrefixes: ["$$"],
  },
  sourcemaps: {
    keepPrivate: true,
    vaultDir: ".unpeek-maps",
    stripComments: true,
  },
  next: {
    distDir: ".next",
  },
});