Release V0.3.0

Genkit Guard v0.3.0

This release improves Redis retention, configuration validation, and PII restoration across multi-turn conversations.

Fixes

• Prevent expired Redis fallback values from reappearing after subsequent writes.
• Protect existing PII placeholders from being masked again, fixing corrupted tokens and incomplete restoration in follow-up turns.
• Apply each Redis hash write and its TTL within one server-side script, preventing interruption between those operations.
• Reject invalid configuration before loading guard models or executing downstream work.

Validation and packaging

• Added Redis tests for expiry, concurrent writes, partial failures, and recovery.
• Added clean-consumer tests for packed-package installation, public imports, TypeScript declarations, and Genkit integration.
• Added independent integration tests using real MiniLM and privacy-filter models with live Redis.
• Verified masking at a controlled provider boundary, tool-input restoration, response restoration, reused conversation history, and preservation of thought signatures.
• Removed development test scripts from the published package.

Migration notes

• Redis TTL requires Redis 7+ and an eval(script, { keys, arguments }) client adapter. Node-redis provides this signature; custom clients may require a wrapper.
• Invalid configurations now fail earlier. Semantic thresholds must be finite and within [-1, 1]; model identifiers must be nonempty; callbacks and adapter methods must be callable.
• Restart conversations containing previously corrupted placeholders. This release prevents new corruption but does not repair historical strings.
• The public decision schema and infrastructure error codes remain unchanged.

Operational limits

Scope and token-index writes remain separate; failures do not imply rollback. Memory fallback is process-local and does not replay writes after Redis recovery. TTL refreshes on writes and is not a per-entry retention deadline.

Automated real-model integration tests use a controlled provider model; they do not establish live-provider compatibility or constitute a production soak.

Dependency review

The production-only audit reports zero findings for the library’s installed runtime graph. Genkit is a required peer dependency as well as a development dependency; consuming applications should audit their complete dependency graph. Keep Genkit within the supported 1.x range.

Release v0.2.0

v0.2.0

Scope: framework compatibility matrix, security hardening and operational error handling. This prepares the release; it does not publish it.

• Remove duplicated README sections and repair code examples. Setup guides use unpinned Genkit install commands.
• Replace the exact Genkit peer pin with a bounded compatible range and test minimum/latest targets across Node.js 22 and 24 in CI.
• Check injection patterns across all message parts, history and documents; semantic intent uses all content in the final message. Pattern detection still has false positives and false negatives, including possible matches in trusted history.
• Remove prompt copies and classifier output from guard-generated model metadata. Use cryptographic token namespaces and keep tokenizer state outside user-provided context fields.
• Mask longer PII values first, ignore empty matches, and cache tokens only after vault writes succeed.
• Sanitize guard model, audit delivery and tokenizer vault failures. Stop execution before downstream work when a required check fails; do not retry audit delivery or tools automatically.
• Update Transformers.js and compatible transitive dependencies, and track the root lockfile for reproducible CI installs.
• Restrict model-request checks, masking and response restoration to Genkit content fields. Preserve opaque provider metadata, including Gemini thought signatures, along with tool names and call references. Secret detection remains active inside text, structured data and tool payloads. Binary media and custom protocol payloads are not inspected.

Dependency audit

After compatible updates, npm audit --omit=dev reports zero findings in this repository's production-only graph. The full audit still reports 49 moderate and 7 high findings in the Genkit dependency graph, including OpenTelemetry and UUID dependencies. Because Genkit is a development dependency here and a required peer in consuming applications, the production-only result does not clear consumers of those findings. Audit the application's complete installed graph. The suggested forced remediation would downgrade Genkit incompatibly; no forced downgrade or unverified override is applied.

Validation

On Windows with Node.js 26, the full deterministic suite passes against the latest stable Genkit resolved from npm. Type checking, build and all 26 release regression tests also pass against the minimum peer target. The example type-check and all six README TypeScript examples pass syntax/type checks as applicable. The Node.js 22/24 CI matrix is configured but has not been run remotely as part of this local preparation. Live inference, provider calls and a real Redis server were not exercised.

PII default migration

PII now defaults to classifier with openai/privacy-filter during startup, model/tool requests and direct detection. Explicit pii: { mode: "ner" } retains BERT NER. A custom PII model without a mode now uses classifier mode, which requires compatible q4 weights; set the mode explicitly for existing NER models. This aligns defaults with the bundled model download script.

Error contract and migration

Failure	Public result
Model policy rejection	Hook returns finishReason: "blocked"; Genkit generation raises FAILED_PRECONDITION with that response in its details
Tool policy rejection	GuardToolError with its decision
Local guard model loading/inference	GuardModelError, MODEL_UNAVAILABLE, with or without a fallback
Audit store/callback delivery	GuardOperationalError, AUDIT_UNAVAILABLE
Vault access through tokenizer/middleware	GuardOperationalError, VAULT_UNAVAILABLE
Provider/tool implementation	Original downstream error

Applications should branch on class/code instead of underlying infrastructure messages. Guard-owned errors omit original messages and causes because they can contain PII. Direct calls to storage adapters retain their own errors. Configuration validation errors remain configuration errors.

Fallback runs once only when explicitly configured. Audit failure never triggers inference fallback. A persisted decision is not rolled back if its callback fails. Restoration and response checks may fail after downstream work has executed; automatic retries can duplicate side effects.

Vault scopes and tokens are not tenant authorization. Use isolated adapters/prefixes per trust boundary. Retention, encryption, request deadlines and durable approval remain application responsibilities.

Next release

v1.0.0-rc.1 is the next planned release candidate and the public API freeze. Freeze exports, configuration, decision schema and error codes at that candidate. Subsequent candidates focus on fixes and compatibility validation; API changes require explicit review before stable v1. SQLite vault and memory compaction are deferred.

Release v0.1.0

v0.1.0 - Release 2

Historical scope: persistent decision logging and opt-in guard-model fallback. Current wiki documentation is maintained in docs/wiki; see docs/release-3.md for subsequent behavior changes.

Acceptance criteria:

• Persist GuardDecision v1 records through a custom append adapter or the built-in JSONL store.
• Await store delivery before callback/downstream execution and propagate delivery failures.
• Read records after reopening, serialize concurrent in-process appends, validate input and reject incomplete tails.
• Try one explicitly configured fallback after an intent/PII model loading or inference error.
• Use fallback-specific PII mode and labels; retain regex detection.
• Never use fallback to override policy rejection, audit failure or downstream failure.
• Stop when both models fail; no regex-only bypass.
• Keep no-fallback defaults and error behavior, existing tool policies and vault APIs.
• Cover native Genkit execution, persistence, concurrency, startup and runtime in tests.

Out of scope: generative-model fallback, replacing privacy-filter, AU fine-tuning, SQLite PII vault (Release 3), compaction, audit retention/rotation/encryption, timeout/circuit-breaker policies and durable multi-worker file coordination.

The package version is prepared as 0.1.0. Nothing is published by this implementation. Wiki preview: npm run wiki:publish. Publish only when ready: npm run wiki:publish -- --publish.

Release v0.0.14

v0.0.14 release notes:

• Explicit exact-name tool policy with allow, block, redact and approval-required actions.
• Default allow preserves prior behavior; default block supports allowlists.
• No execution for blocked, pending, denied or failed approval decisions.
• Irreversible redaction of detected PII in nested string arguments.
• Versioned content-free GuardDecision events shared by prompt and tool checks.
• Awaited audit callback and deterministic reason codes.
• Tests for Genkit generate integration, policy behavior, logging privacy and a local-remote wiki publisher.
• Example and wiki documentation.

Release v0.0.13

This version updates the following changes over 0.0.12

• Correct Privacy Filter pipeline selection.
• Conversion of detected model spans into masking matches.
• Cross-turn response unmasking.
• Recovery when Genkit provides a fresh tool context.
• Redis initialization corrections in the example.
• Focused regression tests.

Release v0.0.12

ttlSeconds now requires a positive integer and verifies Redis supports expire.
TTL applies to both scoped vault hashes and the token index.
Added opt-in fallbackToMemory: true.
Memory fallback is continuously warmed, so values written before a Redis outage remain available.
Fallback supports get, getByToken, set, and entries.
In-memory fallback follows the configured TTL.
Default behavior remains fail-fast when fallback is disabled.
Added tests covering TTL, Redis outages, warm fallback, writes during outages, invalid TTL, and strict failure behavior.

Release v0.0.11

• fixed the TypeScript issue and added a cleaner Redis path
• The error came from GuardConfig
• users also dont need to pass the class now
• Updated readme with the change in approach for using redis vault.
• Update example folder with the changed approach
• Updated test scripts for testing concurrency and pii storage checks

Release v0.0.10

• PII mask and unmask for Tool Calls so that PII retreived from tools are never leaked to the model.
• Adds a pluggable vault storage interface for Redis, DB, KV, secret stores, etc.
• Lets apps provide pii.vault.scopeId, so isolation can be per request/session/user/tenant.
• Adds npm run test:concurrency.

0.0.9-alpha.1 - Tool Calling Middleware PII Masking

This release shifts genkit-guard from an input-only security utility into a fully bidirectional, stateful data compliance firewall for agentic workflows. By intercepting Genkit's native tool-calling lifecycle, it completely solves the paradox of wanting tools to execute with real customer data while keeping the upstream LLM completely zero-trust and PII-free.

🌟 Key Features & Improvements
Just-In-Time (JIT) Tool Payload Hydration:
The middleware isolates an ephemeral token ledger per execution turn. When the LLM decides to call a tool using masked placeholders (e.g., [private_email_0]), the middleware intercepts the payload right before execution and swaps the raw data back in so your database or CRM gets valid data natively.

Automated Egress Sanitization:
If an internal tool retrieves a database record or customer profile containing fresh, unmasked PII, the middleware intercepts the return object and scrubs it before appending it to the LLM's chat history context, preventing downstream token leakage.

Runtime Fixes (TypeError Resolved):
Fixed a critical runtime crash (TypeError: Cannot assign to read only property 'name') caused by JavaScript's native restriction on modifying function names when wrapping Genkit action middlewares.

Zero-Touch Developer Experience:
Retains 100% backward compatibility with your existing configurations (intent.semantic, pii.reversible). No manual tool-wrapping or refactoring is required—it hooks directly into your ai.generate plugin lifecycle automatically.

Release v0.0.9

Middleware-first Architecture

Genkit Guard now follows the official Genkit middleware approach, making it easier to integrate directly into Genkit applications.

Enhanced PII Detection

Added support for OpenAI's privacy-filter model, providing an alternative to traditional NER-based PII detection.

Configurable Initialization

initGuard() now accepts configuration options, allowing developers to customize:

Extractor models
PII models
Detection modes

Dependency Updates
Updated Genkit compatibility.
Upgraded Transformers.js dependency.
Updated TypeScript and supporting packages.

Migration Notes

Existing users should review initialization code and update model download steps to use the new privacy-filter model where appropriate.