[PUBLISHED ON NPMJS] @takk/mcpcustoms@1.0.0

STATUS: PUBLISHED ON NPMJS. This version was published to the npm registry on 2026-06-18T10:42:18Z with provenance attestation. View on npm: https://www.npmjs.com/package/@takk/mcpcustoms/v/1.0.0

[1.0.0] - 2026-06-18T03:34:14Z

Initial stable release. Universal, zero-runtime-dependency NPM library and CLI: a runtime customs and semantic firewall that inspects every Massive Intelligence (IM) agent tool call before execution and reaches an allow, block, or ask verdict, fail-closed by default.

Added

Core engine

• createCustoms(options) factory returning the Customs engine: inspect, inspectManifest, preview, registerDetector, setPolicy, auditTrail, verifyAuditChain, stats, prune, flush, snapshot, on.
• Deterministic, side-effect-free inspection: never executes the tool, performs no network I/O, and reads time only through an injectable clock.
• Verdict shape: decision (allow / block / ask), a riskScore in [0, 100], the collected findings, the tool, the instant, and the audit sequence.

Detectors (default suite)

• metadata.tool-poisoning (critical): hidden instructions in the tool's own description.
• parameter.command-injection (critical): shell metacharacters, command substitution, chained destructive commands.
• parameter.path-traversal (high): ../ sequences and sensitive absolute paths.
• parameter.sql-injection (high): tautologies, UNION SELECT, stacked queries.
• parameter.secret-exfiltration (high): credential-store references and known key shapes.
• parameter.prompt-injection (medium): instruction-override phrasing.
• capability.side-effect-overreach (high): inferred side effects exceeding the declared ones.
• Pure-function Detector contract, stringLeaves argument flattening, and registerDetector for custom detectors. A throwing detector is isolated to one info finding.
• Normalization pre-pass (normalizeVariants): detectors run over percent-decoded, embedded-base64-decoded, Unicode NFKC-folded, and zero-width-stripped views of each argument and the description, so payloads obfuscated by common encodings are still matched. Bounded by depth, count, and length; a match on a decoded view is marked (after decoding).

Reputation

• Pluggable ReputationSource hook consulted on every inspection: a flagged tool or publisher contributes a finding, a trusted one an info signal. staticReputation builds a source from in-memory allow and deny sets. The on-ramp for an external reputation database without coupling the core to a service.

Policy

• DEFAULT_POLICY (fail-closed: block critical/high, ask medium) and STRICT_POLICY (block down to medium, ask low).
• decide, dominantSeverity, and a monotonic riskScore.

Publisher verification

• Ed25519 version-locked manifest signing and verification against a pinned trust anchor: signManifest, verifyPublisherClaim, manifestMessage, generatePublisherKeyPair.
• nodeSigner (node:crypto) and webSigner (Web Crypto) producing byte-identical keys; the core engine carries no platform crypto import, the entries inject the signer.

Audit trail

• FNV-1a hash-chained, append-only, frozen audit events with verifyAuditChain, prune (re-seals the surviving chain), maxAudit retention cap, and redactEvidence for non-reversible evidence redaction.

State backends

• memoryState (default), fileState({ path }) (atomic JSON snapshot, corrupt-file quarantine, Node only), and kvState(kv, key?) (any structural key-value store, edge-friendly).

Entry points and adapters

• Eight subpath exports: ., ./publisher, ./integrations, ./vercel, ./mcp, ./store, ./web, ./edge.
• Framework-agnostic guard (createGuard, guardTool, enforceVerdict); Vercel AI SDK adapter (guardVercelTool, guardVercelTools); MCP adapter (guardMcpCall, inspectMcpCall, mcpToToolCall) that maps readOnlyHint / openWorldHint annotations to declared side effects.
• The web and edge bundles are verified free of any node: reference.

CLI

• Binary mcpcustoms exposed via package.json#bin.
• Subcommands inspect, verify, keygen, sign, help, version. Exit codes follow the verdict (0 allow, 1 block, 2 ask, 64 usage error). The CLI logic is pure over an injected CliIO.

Distribution

• Dual ESM + CJS bundles built with tsup 8, target es2022.
• Separate .d.ts and .d.cts type files per entry point; exports map with split import / require conditions.
• Zero required runtime dependencies. Sibling @takk/* packages are optional peers.

Quality

• 158 tests across 19 suites passing under Vitest 4 on Node 20, 22, and 24.
• Coverage: lines 95.7%, statements 95.3%, functions 98.6%, branches 89.1%.
• Labeled evasion benchmark in CI: each payload class is asserted blocked in its raw form and after base64, percent, zero-width, Unicode, and double encoding, the regression guard for the normalization pre-pass.
• Lint clean under Biome 2, typecheck clean under TypeScript 6 in maximum strict mode.
• publint clean, attw green on all eight entry points (CJS, ESM, bundler), size-limit budgets met (core 6.46 kB brotli ESM).

Security

• Published with --provenance (SLSA attestation by GitHub Actions). Verify via npm view @takk/mcpcustoms --json | jq .dist.attestations.
• Fail-closed default policy; publisher verification requires a pinned trust anchor and an injected signer.
• Defense-in-depth, not a sole control: the detectors are heuristic pattern matchers over a normalization pre-pass, not a complete static analyzer. See SECURITY.md for the threat model.

Licensing

• Licensed under the Apache License, Version 2.0. NOTICE ships in the tarball alongside LICENSE.

Engines

• Node >=20.0.0. Tested on Node 20, 22, and 24.