05/api

CLI Bayrakları & Programatik API Referansı

unpeek CLI ikili dosyası, Node.js programatik fonksiyonları ve packages/unpeek/src/types.ts içinden dışa aktarılan TypeScript arayüzlerinin tam referansı.

CLI Komutları & Savunma Kademeleri (Tier 1 / Tier 2 / Tier 3)

`unpeek` komut satırı aracı `init`, `protect`, `check` ve `symbolicate` komutlarını üç savunma kademesiyle sunar:

Tier 1 (`--profile minimal`): `coldFlow: false`, `mangler.minLength: 1`, sıcak yol muafiyeti ve sıra-bağımsız `globalThis` kalkanıyla hızlı temel koruma (<%2 CPU, <%15 Gzip).

Tier 2 (`--profile recommended` / Varsayılan): 92-karakter kaçışsız metin kasası, `>=4`-değişkenli yarı-lineer MBA + derece-3 Rivest QNR koruması ve yerinde `Uint8Array` shader kasası ekler.

Tier 3 (`--profile strict` / `--aggressive`): `@unpeek-critical` kalelerini ve `critical.include` desenlerini 43-komutlu Micro-VM v2, paylaşımlı `<1.2 KB` konak-bağlı WASM KDF, 64-bit çağrı-noktası tuzlu kasa ve CWE-540 yol temizliğiyle korur.

CLI Referansı
  ▛▀▀▜  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

Programatik Node.js API & TypeScript Tipleri

Özel derleme hatları oluşturmak için `protectProject`, `transformJavaScript`, `checkProject`, `symbolicateStackTrace`, `PRESETS`, `isUnpeekError` veya bundler eklentilerini doğrudan `unpeek` paketinden içe aktarabilirsiniz.

TypeScript: Programatik Kullanım & Arayüzler
import {
  PRESETS,
  protectProject,
  transformJavaScript,
  checkProject,
  symbolicateStackTrace,
  isUnpeekError,
  type ProtectOptions,
  type ProtectSummary,
  type TransformOptions,
  type TransformResult,
  type UnpeekDiagnostic,
  type UnpeekProfile,
} from "unpeek";

// 1. Tek bir JavaScript modülünü bellek içinde dönüştürme
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. Tüm framework çıktı dizinini koruma
const summary: ProtectSummary = await protectProject({
  cwd: process.cwd(),
  profile: "recommended",
  keepPrivateMaps: true,
  privateMapsDir: ".unpeek-maps",
  deterrentMode: "passive",
  aggressive: false,
});

Yapılandırma Şeması & Seçenekleri (UnpeekConfig)

`UnpeekConfig` arayüzü; sıcak yol (hot-path) sezgileri, metin kasası (string vault) sınırları, sembol karmaşıklaştırma (mangler) kuralları ve kaynak haritası (source map) depolamasını yönetir. Ayarlar hiyerarşik öncelik sırasına göre çözümlenir: CLI bayrakları > programatik seçenekler > keşfedilen yapılandırma dosyası > hazır profil (`PRESETS`).

Yapılandırma dosyaları `unpeek.config.js`, `unpeek.config.mjs`, `unpeek.config.cjs` ve `unpeek.config.json` (veya TypeScript yükleyicileriyle `unpeek.config.ts`) isimleriyle proje kökünde otomatik olarak aranır.

  • `hotPath`: Geçişken muafiyet için `customAnimationCalls` (ör. `['requestAnimationFrame', 'useFrame']`), `customHooks` (ör. `['useSpring', 'useGesture']`), `arrayHofMethods`, `hocWrappers` ve `maxPipelineCallers` (varsayılan `2`) seçeneklerini belirler.
  • `vault`: `minStringLength` (varsayılan `4`), `cssFramework` (`'tailwind'` | `'unocss'` | `'none'`), `customDirectives`, `reservedProps`, `semanticAnchors`, `polymorphicDecoys` (varsayılan `true`) ve `fragmented` / `fragmentCount` kurallarını yapılandırır.
  • `critical` / `tier` / `coldFlow`: `'Tier 1' | 'Tier 2' | 'Tier 3'` katmanını seçer, `coldFlow` geçişini ayarlar ve `@unpeek-critical` veya `critical.include` desenlerini hedefler (`maxFunctionsPerChunk` varsayılan: `12`).
  • `mangler`: `minLength` (tüm hazır profillerde varsayılan `1`) ile `reservedIdentifiers`, `excludePrefixes` ve `excludePatterns` (RegExp dizisi) kurallarını tanımlar.
  • `scrubPaths`: Yerel dosya sistemi yollarını (`rootDir`, `[project]/`, `webpack://`, Windows `C:\`) ve artık geliştirme meta verilerini temizler (CWE-540).
  • `next` / `vite`: Özel Next.js çıktı dizinleri için `next.distDir`, özel Vite dağıtımları için `vite.outDir` / `vite.assetsDir` geçersiz kılmalarını tanımlar.
unpeek.config.ts: Eksiksiz Şema Örneği
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",
  },
});