@tnid/filter 0.1.0

package/esm/internals.js

@@ -0,0 +1,61 @@
+/**
+ * Shared internals for filter functions.
+ * @internal Not part of the public API.
+ */
+// V0 data string character layout:
+// Chars 0-6: pure timestamp bits
+// Char 7: 1 timestamp bit + 2 variant bits + 3 random bits
+// Chars 8-16: pure random bits
+export const FIRST_CHAR_WITH_RANDOM = 7;
+export const V0_RANDOM_BITS = 57;
+export const V1_RANDOM_BITS = 100;
+/** Global last-known-safe timestamp to avoid re-discovering bad windows. */
+export let lastSafeTimestamp = 0n;
+export function recordSafeTimestamp(ts) {
+    if (ts > lastSafeTimestamp) {
+        lastSafeTimestamp = ts;
+    }
+}
+export function getStartingTimestamp() {
+    const current = BigInt(Date.now());
+    return current > lastSafeTimestamp ? current : lastSafeTimestamp;
+}
+/** Generate a random bigint with the specified number of bits. */
+export function randomBigInt(bits) {
+    const bytes = new Uint8Array(Math.ceil(bits / 8));
+    crypto.getRandomValues(bytes);
+    let result = 0n;
+    for (const b of bytes)
+        result = (result << 8n) | BigInt(b);
+    return result & ((1n << BigInt(bits)) - 1n);
+}
+/** Extract the 17-char data string from a TNID string. */
+export function dataString(tnid) {
+    return tnid.substring(tnid.indexOf(".") + 1);
+}
+/**
+ * Check if a match touches the random portion of V0 data string.
+ * If true, regenerating random bits may resolve the match.
+ * If false, the match is entirely in the timestamp portion and requires bumping.
+ */
+export function matchTouchesRandomPortion(start, length) {
+    return start + length > FIRST_CHAR_WITH_RANDOM;
+}
+/**
+ * Minimum timestamp bump (in ms) needed to change the character at position `pos`.
+ * Each character encodes 6 bits. Lower positions = more significant = larger bump.
+ */
+export function timestampBumpForChar(pos) {
+    return 1n << BigInt(42 - 6 * pos);
+}
+/**
+ * Handle a V0 blocklist match: bump timestamp if match is in timestamp portion.
+ * Returns the (possibly bumped) timestamp.
+ */
+export function handleV0Match(match, timestamp) {
+    if (!matchTouchesRandomPortion(match.start, match.length)) {
+        const rightmostChar = match.start + match.length - 1;
+        return timestamp + timestampBumpForChar(rightmostChar);
+    }
+    return timestamp;
+}

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@tnid/filter",
+  "version": "0.1.0",
+  "description": "Blocklist filtering for TNIDs - generate IDs that avoid specified substrings",
+  "keywords": [
+    "uuid",
+    "id",
+    "identifier",
+    "tnid",
+    "typed",
+    "type-safe"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mkeedlinger/tnid-typescript.git"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/mkeedlinger/tnid-typescript/issues"
+  },
+  "main": "./script/index.js",
+  "module": "./esm/index.js",
+  "exports": {
+    ".": {
+      "import": "./esm/index.js",
+      "require": "./script/index.js"
+    },
+    "./encryption": {
+      "import": "./esm/filter_encryption.js",
+      "require": "./script/filter_encryption.js"
+    }
+  },
+  "scripts": {},
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@tnid/core": "^0.1.0",
+    "@tnid/encryption": "^0.1.0"
+  },
+  "_generatedBy": "dnt@dev"
+}

package/script/blocklist.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Blocklist for matching substrings in TNID data strings.
+ *
+ * Uses a single compiled RegExp with alternation for efficient matching.
+ */
+/**
+ * A compiled blocklist for efficient case-insensitive substring matching.
+ *
+ * Patterns may only contain characters from the TNID data string alphabet
+ * (`-0-9A-Z_a-z`). Patterns with other characters can never match and
+ * will be rejected.
+ *
+ * @example
+ * ```typescript
+ * const blocklist = new Blocklist(["TACO", "FOO", "BAZZ"]);
+ *
+ * blocklist.containsMatch("xyzTACOxyz"); // true
+ * blocklist.containsMatch("xyztacoxyz"); // true (case-insensitive)
+ * blocklist.containsMatch("xyzHELLOxyz"); // false
+ * ```
+ */
+export declare class Blocklist {
+    private pattern;
+    /**
+     * Creates a new blocklist from the given patterns.
+     *
+     * @throws {Error} If any pattern contains characters outside the TNID data alphabet.
+     */
+    constructor(patterns: string[]);
+    /** Returns `true` if the text contains any blocklisted word. */
+    containsMatch(text: string): boolean;
+    /**
+     * Finds the first blocklist match in the text.
+     * Returns the start index and length, or `null` if no match.
+     */
+    findFirstMatch(text: string): {
+        start: number;
+        length: number;
+    } | null;
+}
+//# sourceMappingURL=blocklist.d.ts.map

package/script/blocklist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocklist.d.ts","sourceRoot":"","sources":["../src/blocklist.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,OAAO,CAAgB;IAE/B;;;;OAIG;gBACS,QAAQ,EAAE,MAAM,EAAE;IAgB9B,gEAAgE;IAChE,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAKpC;;;OAGG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;CAMvE"}

package/script/blocklist.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * Blocklist for matching substrings in TNID data strings.
+ *
+ * Uses a single compiled RegExp with alternation for efficient matching.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Blocklist = void 0;
+/** TNID data string alphabet: `-0-9A-Z_a-z` */
+const VALID_PATTERN = /^[-0-9A-Za-z_]+$/;
+/**
+ * A compiled blocklist for efficient case-insensitive substring matching.
+ *
+ * Patterns may only contain characters from the TNID data string alphabet
+ * (`-0-9A-Z_a-z`). Patterns with other characters can never match and
+ * will be rejected.
+ *
+ * @example
+ * ```typescript
+ * const blocklist = new Blocklist(["TACO", "FOO", "BAZZ"]);
+ *
+ * blocklist.containsMatch("xyzTACOxyz"); // true
+ * blocklist.containsMatch("xyztacoxyz"); // true (case-insensitive)
+ * blocklist.containsMatch("xyzHELLOxyz"); // false
+ * ```
+ */
+class Blocklist {
+    /**
+     * Creates a new blocklist from the given patterns.
+     *
+     * @throws {Error} If any pattern contains characters outside the TNID data alphabet.
+     */
+    constructor(patterns) {
+        Object.defineProperty(this, "pattern", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        const nonEmpty = patterns.filter((p) => p.length > 0);
+        for (const p of nonEmpty) {
+            if (!VALID_PATTERN.test(p)) {
+                throw new Error(`invalid blocklist pattern "${p}": only TNID data characters are allowed (-0-9A-Za-z_)`);
+            }
+        }
+        if (nonEmpty.length === 0) {
+            this.pattern = null;
+        }
+        else {
+            this.pattern = new RegExp(nonEmpty.join("|"), "i");
+        }
+    }
+    /** Returns `true` if the text contains any blocklisted word. */
+    containsMatch(text) {
+        if (this.pattern === null)
+            return false;
+        return this.pattern.test(text);
+    }
+    /**
+     * Finds the first blocklist match in the text.
+     * Returns the start index and length, or `null` if no match.
+     */
+    findFirstMatch(text) {
+        if (this.pattern === null)
+            return null;
+        const m = this.pattern.exec(text);
+        if (m === null)
+            return null;
+        return { start: m.index, length: m[0].length };
+    }
+}
+exports.Blocklist = Blocklist;

package/script/filter.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Filtered TNID generation functions.
+ *
+ * Generate TNIDs guaranteed not to contain blocklisted substrings
+ * in their data string representation.
+ */
+import type { NamedTnid, TnidValue } from "@tnid/core";
+import type { Blocklist } from "./blocklist.js";
+/** Error thrown when filtered generation exceeds the iteration limit. */
+export declare class FilterError extends Error {
+    readonly iterations: number;
+    constructor(iterations: number);
+}
+/**
+ * Generate a V0 TNID whose data string contains no blocklisted words.
+ *
+ * Uses smart timestamp bumping when a match is in the timestamp portion,
+ * and random regeneration when a match touches the random portion.
+ *
+ * @throws {FilterError} If maximum iterations exceeded.
+ *
+ * @example
+ * ```typescript
+ * import { Tnid } from "@tnid/core";
+ * import { Blocklist, newV0Filtered } from "@tnid/filter";
+ *
+ * const UserId = Tnid("user");
+ * const blocklist = new Blocklist(["TACO", "FOO"]);
+ * const id = newV0Filtered(UserId, blocklist);
+ * ```
+ */
+export declare function newV0Filtered<Name extends string>(factory: NamedTnid<Name>, blocklist: Blocklist): TnidValue<Name>;
+/**
+ * Generate a V1 TNID whose data string contains no blocklisted words.
+ *
+ * Since all V1 bits are random, simply regenerates until clean.
+ *
+ * @throws {FilterError} If maximum iterations exceeded.
+ *
+ * @example
+ * ```typescript
+ * import { Tnid } from "@tnid/core";
+ * import { Blocklist, newV1Filtered } from "@tnid/filter";
+ *
+ * const UserId = Tnid("user");
+ * const blocklist = new Blocklist(["TACO", "FOO"]);
+ * const id = newV1Filtered(UserId, blocklist);
+ * ```
+ */
+export declare function newV1Filtered<Name extends string>(factory: NamedTnid<Name>, blocklist: Blocklist): TnidValue<Name>;
+//# sourceMappingURL=filter.d.ts.map

package/script/filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../src/filter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAchD,yEAAyE;AACzE,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,UAAU,EAAE,MAAM;CAO/B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,IAAI,SAAS,MAAM,EAC/C,OAAO,EAAE,SAAS,CAAC,IAAI,CAAC,EACxB,SAAS,EAAE,SAAS,GACnB,SAAS,CAAC,IAAI,CAAC,CAkBjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,IAAI,SAAS,MAAM,EAC/C,OAAO,EAAE,SAAS,CAAC,IAAI,CAAC,EACxB,SAAS,EAAE,SAAS,GACnB,SAAS,CAAC,IAAI,CAAC,CAYjB"}

package/script/filter.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * Filtered TNID generation functions.
+ *
+ * Generate TNIDs guaranteed not to contain blocklisted substrings
+ * in their data string representation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FilterError = void 0;
+exports.newV0Filtered = newV0Filtered;
+exports.newV1Filtered = newV1Filtered;
+const internals_js_1 = require("./internals.js");
+const MAX_V0_ITERATIONS = 1_000;
+const MAX_V1_ITERATIONS = 100;
+/** Error thrown when filtered generation exceeds the iteration limit. */
+class FilterError extends Error {
+    constructor(iterations) {
+        super(`failed to generate clean ID after ${iterations} iterations; blocklist may be too restrictive`);
+        Object.defineProperty(this, "iterations", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = "FilterError";
+        this.iterations = iterations;
+    }
+}
+exports.FilterError = FilterError;
+/**
+ * Generate a V0 TNID whose data string contains no blocklisted words.
+ *
+ * Uses smart timestamp bumping when a match is in the timestamp portion,
+ * and random regeneration when a match touches the random portion.
+ *
+ * @throws {FilterError} If maximum iterations exceeded.
+ *
+ * @example
+ * ```typescript
+ * import { Tnid } from "@tnid/core";
+ * import { Blocklist, newV0Filtered } from "@tnid/filter";
+ *
+ * const UserId = Tnid("user");
+ * const blocklist = new Blocklist(["TACO", "FOO"]);
+ * const id = newV0Filtered(UserId, blocklist);
+ * ```
+ */
+function newV0Filtered(factory, blocklist) {
+    let timestamp = (0, internals_js_1.getStartingTimestamp)();
+    for (let i = 0; i < MAX_V0_ITERATIONS; i++) {
+        const random = (0, internals_js_1.randomBigInt)(internals_js_1.V0_RANDOM_BITS);
+        const id = factory.v0_from_parts(timestamp, random);
+        const data = (0, internals_js_1.dataString)(id);
+        const match = blocklist.findFirstMatch(data);
+        if (match === null) {
+            (0, internals_js_1.recordSafeTimestamp)(timestamp);
+            return id;
+        }
+        timestamp = (0, internals_js_1.handleV0Match)(match, timestamp);
+    }
+    throw new FilterError(MAX_V0_ITERATIONS);
+}
+/**
+ * Generate a V1 TNID whose data string contains no blocklisted words.
+ *
+ * Since all V1 bits are random, simply regenerates until clean.
+ *
+ * @throws {FilterError} If maximum iterations exceeded.
+ *
+ * @example
+ * ```typescript
+ * import { Tnid } from "@tnid/core";
+ * import { Blocklist, newV1Filtered } from "@tnid/filter";
+ *
+ * const UserId = Tnid("user");
+ * const blocklist = new Blocklist(["TACO", "FOO"]);
+ * const id = newV1Filtered(UserId, blocklist);
+ * ```
+ */
+function newV1Filtered(factory, blocklist) {
+    for (let i = 0; i < MAX_V1_ITERATIONS; i++) {
+        const random = (0, internals_js_1.randomBigInt)(internals_js_1.V1_RANDOM_BITS);
+        const id = factory.v1_from_parts(random);
+        const data = (0, internals_js_1.dataString)(id);
+        if (!blocklist.containsMatch(data)) {
+            return id;
+        }
+    }
+    throw new FilterError(MAX_V1_ITERATIONS);
+}

package/script/filter_encryption.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @tnid/filter/encryption - Encryption-aware blocklist filtering
+ *
+ * Generate V0 TNIDs where both the V0 and its encrypted V1 form
+ * contain no blocklisted words.
+ *
+ * @example
+ * ```typescript
+ * import { Tnid } from "@tnid/core";
+ * import { EncryptionKey } from "@tnid/encryption";
+ * import { Blocklist } from "@tnid/filter";
+ * import { newV0FilteredForEncryption } from "@tnid/filter/encryption";
+ *
+ * const UserId = Tnid("user");
+ * const blocklist = new Blocklist(["TACO", "FOO"]);
+ * const key = EncryptionKey.fromHex("0102030405060708090a0b0c0d0e0f10");
+ *
+ * const id = await newV0FilteredForEncryption(UserId, blocklist, key);
+ * ```
+ *
+ * @module
+ */
+import type { NamedTnid, TnidValue } from "@tnid/core";
+import { type EncryptionKey } from "@tnid/encryption";
+import type { Blocklist } from "./blocklist.js";
+import { FilterError } from "./filter.js";
+export { Blocklist } from "./blocklist.js";
+export { FilterError };
+/**
+ * Generate a V0 TNID where both the V0 and its encrypted V1 form
+ * contain no blocklisted words.
+ *
+ * Requires the V0/V1 Encryption extension.
+ *
+ * @throws {FilterError} If maximum iterations exceeded.
+ *
+ * @example
+ * ```typescript
+ * import { Tnid } from "@tnid/core";
+ * import { EncryptionKey } from "@tnid/encryption";
+ * import { Blocklist } from "@tnid/filter";
+ * import { newV0FilteredForEncryption } from "@tnid/filter/encryption";
+ *
+ * const UserId = Tnid("user");
+ * const blocklist = new Blocklist(["TACO", "FOO"]);
+ * const key = EncryptionKey.fromHex("0102030405060708090a0b0c0d0e0f10");
+ *
+ * const id = await newV0FilteredForEncryption(UserId, blocklist, key);
+ * ```
+ */
+export declare function newV0FilteredForEncryption<Name extends string>(factory: NamedTnid<Name>, blocklist: Blocklist, key: EncryptionKey): Promise<TnidValue<Name>>;
+//# sourceMappingURL=filter_encryption.d.ts.map

package/script/filter_encryption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter_encryption.d.ts","sourceRoot":"","sources":["../src/filter_encryption.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,KAAK,aAAa,EAAiB,MAAM,kBAAkB,CAAC;AACrE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAW1C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,CAAC;AAIvB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,0BAA0B,CAAC,IAAI,SAAS,MAAM,EAClE,OAAO,EAAE,SAAS,CAAC,IAAI,CAAC,EACxB,SAAS,EAAE,SAAS,EACpB,GAAG,EAAE,aAAa,GACjB,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CA2B1B"}

package/script/filter_encryption.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * @tnid/filter/encryption - Encryption-aware blocklist filtering
+ *
+ * Generate V0 TNIDs where both the V0 and its encrypted V1 form
+ * contain no blocklisted words.
+ *
+ * @example
+ * ```typescript
+ * import { Tnid } from "@tnid/core";
+ * import { EncryptionKey } from "@tnid/encryption";
+ * import { Blocklist } from "@tnid/filter";
+ * import { newV0FilteredForEncryption } from "@tnid/filter/encryption";
+ *
+ * const UserId = Tnid("user");
+ * const blocklist = new Blocklist(["TACO", "FOO"]);
+ * const key = EncryptionKey.fromHex("0102030405060708090a0b0c0d0e0f10");
+ *
+ * const id = await newV0FilteredForEncryption(UserId, blocklist, key);
+ * ```
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FilterError = exports.Blocklist = void 0;
+exports.newV0FilteredForEncryption = newV0FilteredForEncryption;
+const encryption_1 = require("@tnid/encryption");
+const filter_js_1 = require("./filter.js");
+Object.defineProperty(exports, "FilterError", { enumerable: true, get: function () { return filter_js_1.FilterError; } });
+const internals_js_1 = require("./internals.js");
+// Re-export Blocklist and FilterError for convenience
+var blocklist_js_1 = require("./blocklist.js");
+Object.defineProperty(exports, "Blocklist", { enumerable: true, get: function () { return blocklist_js_1.Blocklist; } });
+const MAX_ENCRYPTION_ITERATIONS = 1_000;
+/**
+ * Generate a V0 TNID where both the V0 and its encrypted V1 form
+ * contain no blocklisted words.
+ *
+ * Requires the V0/V1 Encryption extension.
+ *
+ * @throws {FilterError} If maximum iterations exceeded.
+ *
+ * @example
+ * ```typescript
+ * import { Tnid } from "@tnid/core";
+ * import { EncryptionKey } from "@tnid/encryption";
+ * import { Blocklist } from "@tnid/filter";
+ * import { newV0FilteredForEncryption } from "@tnid/filter/encryption";
+ *
+ * const UserId = Tnid("user");
+ * const blocklist = new Blocklist(["TACO", "FOO"]);
+ * const key = EncryptionKey.fromHex("0102030405060708090a0b0c0d0e0f10");
+ *
+ * const id = await newV0FilteredForEncryption(UserId, blocklist, key);
+ * ```
+ */
+async function newV0FilteredForEncryption(factory, blocklist, key) {
+    let timestamp = (0, internals_js_1.getStartingTimestamp)();
+    for (let i = 0; i < MAX_ENCRYPTION_ITERATIONS; i++) {
+        const random = (0, internals_js_1.randomBigInt)(internals_js_1.V0_RANDOM_BITS);
+        const v0 = factory.v0_from_parts(timestamp, random);
+        const v0Data = (0, internals_js_1.dataString)(v0);
+        // Check V0 first
+        const v0Match = blocklist.findFirstMatch(v0Data);
+        if (v0Match !== null) {
+            timestamp = (0, internals_js_1.handleV0Match)(v0Match, timestamp);
+            continue;
+        }
+        // V0 is clean, now check encrypted V1
+        const v1 = await (0, encryption_1.encryptV0ToV1)(v0, key);
+        const v1Data = (0, internals_js_1.dataString)(v1);
+        if (!blocklist.containsMatch(v1Data)) {
+            (0, internals_js_1.recordSafeTimestamp)(timestamp);
+            return v0;
+        }
+        // V1 had a match - regenerate (loop continues with new random)
+    }
+    throw new filter_js_1.FilterError(MAX_ENCRYPTION_ITERATIONS);
+}

package/script/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @tnid/filter - Blocklist filtering for TNID generation
+ *
+ * Generate TNIDs guaranteed not to contain specified substrings
+ * (e.g., profanity) in their string representation.
+ *
+ * @example
+ * ```typescript
+ * import { Tnid } from "@tnid/core";
+ * import { Blocklist, newV0Filtered, newV1Filtered } from "@tnid/filter";
+ *
+ * const UserId = Tnid("user");
+ * const blocklist = new Blocklist(["TACO", "FOO"]);
+ *
+ * const v0 = newV0Filtered(UserId, blocklist);
+ * const v1 = newV1Filtered(UserId, blocklist);
+ * ```
+ *
+ * For encryption-aware filtering, use the `@tnid/filter/encryption` entry point.
+ *
+ * @module
+ */
+export { Blocklist } from "./blocklist.js";
+export { FilterError, newV0Filtered, newV1Filtered } from "./filter.js";
+//# sourceMappingURL=index.d.ts.map

package/script/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/script/index.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * @tnid/filter - Blocklist filtering for TNID generation
+ *
+ * Generate TNIDs guaranteed not to contain specified substrings
+ * (e.g., profanity) in their string representation.
+ *
+ * @example
+ * ```typescript
+ * import { Tnid } from "@tnid/core";
+ * import { Blocklist, newV0Filtered, newV1Filtered } from "@tnid/filter";
+ *
+ * const UserId = Tnid("user");
+ * const blocklist = new Blocklist(["TACO", "FOO"]);
+ *
+ * const v0 = newV0Filtered(UserId, blocklist);
+ * const v1 = newV1Filtered(UserId, blocklist);
+ * ```
+ *
+ * For encryption-aware filtering, use the `@tnid/filter/encryption` entry point.
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newV1Filtered = exports.newV0Filtered = exports.FilterError = exports.Blocklist = void 0;
+var blocklist_js_1 = require("./blocklist.js");
+Object.defineProperty(exports, "Blocklist", { enumerable: true, get: function () { return blocklist_js_1.Blocklist; } });
+var filter_js_1 = require("./filter.js");
+Object.defineProperty(exports, "FilterError", { enumerable: true, get: function () { return filter_js_1.FilterError; } });
+Object.defineProperty(exports, "newV0Filtered", { enumerable: true, get: function () { return filter_js_1.newV0Filtered; } });
+Object.defineProperty(exports, "newV1Filtered", { enumerable: true, get: function () { return filter_js_1.newV1Filtered; } });

package/script/internals.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared internals for filter functions.
+ * @internal Not part of the public API.
+ */
+export declare const FIRST_CHAR_WITH_RANDOM = 7;
+export declare const V0_RANDOM_BITS = 57;
+export declare const V1_RANDOM_BITS = 100;
+/** Global last-known-safe timestamp to avoid re-discovering bad windows. */
+export declare let lastSafeTimestamp: bigint;
+export declare function recordSafeTimestamp(ts: bigint): void;
+export declare function getStartingTimestamp(): bigint;
+/** Generate a random bigint with the specified number of bits. */
+export declare function randomBigInt(bits: number): bigint;
+/** Extract the 17-char data string from a TNID string. */
+export declare function dataString(tnid: string): string;
+/**
+ * Check if a match touches the random portion of V0 data string.
+ * If true, regenerating random bits may resolve the match.
+ * If false, the match is entirely in the timestamp portion and requires bumping.
+ */
+export declare function matchTouchesRandomPortion(start: number, length: number): boolean;
+/**
+ * Minimum timestamp bump (in ms) needed to change the character at position `pos`.
+ * Each character encodes 6 bits. Lower positions = more significant = larger bump.
+ */
+export declare function timestampBumpForChar(pos: number): bigint;
+/**
+ * Handle a V0 blocklist match: bump timestamp if match is in timestamp portion.
+ * Returns the (possibly bumped) timestamp.
+ */
+export declare function handleV0Match(match: {
+    start: number;
+    length: number;
+}, timestamp: bigint): bigint;
+//# sourceMappingURL=internals.d.ts.map

package/script/internals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internals.d.ts","sourceRoot":"","sources":["../src/internals.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,eAAO,MAAM,cAAc,KAAK,CAAC;AACjC,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC,4EAA4E;AAC5E,eAAO,IAAI,iBAAiB,QAAK,CAAC;AAElC,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAIpD;AAED,wBAAgB,oBAAoB,IAAI,MAAM,CAG7C;AAED,kEAAkE;AAClE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMjD;AAED,0DAA0D;AAC1D,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAEhF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EACxC,SAAS,EAAE,MAAM,GAChB,MAAM,CAMR"}