Sanitization

Sanitization is off by default. When enabled, Keyv strips dangerous patterns from keys and namespaces before they reach the store. Harmless characters such as quotes, slashes, and dollar signs in the middle of a string pass through.

Results are cached in an LRU (10,000 entries) so repeated keys are cheap.

Table of Contents

• Enable it
• Pattern categories
• Targets
• Granular control
• Change at runtime

Enable it

const keyv = new Keyv({
	sanitize: { keys: true, namespace: true },
});

await keyv.set("test; DROP TABLE", "value");
// stored as "test DROP TABLE"

await keyv.set("user's-data", "value");
// unchanged

Omitting sanitize, or setting both targets to false, leaves keys and namespaces untouched.

Pattern categories

Stripping repeats until nothing matches, so the characters left around a removed pattern can't form a new one. For example, ..././etc becomes etc, not ../etc, and $$where becomes where.

Targets

Methods that sanitize keys: get, set, delete, has, getMany, setMany, deleteMany, hasMany, getRaw, getManyRaw, setRaw, setManyRaw.

Empty keys after sanitization cause set / delete / has / get to no-op (false / undefined). The batch methods skip them the same way: an empty key never reaches the store, and its position in the result holds undefined or false.

A namespace that is empty after sanitization, such as $$ or ;, becomes keyv-sanitized. An empty namespace would turn namespacing off, mixing the instance's keys with unrelated ones and letting clear() remove them.

Granular control

const keyv = new Keyv({
	sanitize: {
		keys: { sql: true, mongo: false },
		namespace: { path: true, sql: false },
	},
});

Disable namespace sanitization only:

const keyv = new Keyv({
	sanitize: { keys: true, namespace: false },
});

Change at runtime

import { KeyvSanitize } from "keyv";

keyv.sanitize.updateOptions({ keys: true, namespace: true });
keyv.sanitize.updateOptions({ keys: { sql: true, mongo: false } });
keyv.sanitize = new KeyvSanitize({ keys: true, namespace: true });

keyv.sanitize.enabled is true when any category is on for keys or namespace.

Sanitization is not a substitute for parameterized queries or adapter-level escaping. It is a Defense-in-Depth filter for untrusted key material. See SECURITY.md in the repository.