@veridjs/core 1.0.0

package/LICENSE

@@ -0,0 +1 @@
+MIT License

package/README.md

@@ -0,0 +1,86 @@
+# VID — Verifiable Identifier
+
+VID is a cryptographically verifiable, globally unique identifier designed for distributed systems.
+
+Unlike UUIDv4 or UUIDv7, VID includes built-in authenticity verification using HMAC signatures.
+
+This prevents forged IDs and enables trustless validation.
+
+---
+
+## Features
+
+• Globally unique  
+• Cryptographically verifiable  
+• Database efficient (18 bytes binary)  
+• Supports MongoDB, PostgreSQL, Redis  
+• Time-sortable  
+• Zero dependencies  
+• High performance  
+
+---
+
+## Installation
+
+```bash
+npm install @kishan/vid
+Quick Start
+import { VID } from "@kishan/vid"
+
+const vid = VID.initialize({
+  secret: "your-secret-key",
+  keyVersion: 1
+})
+
+const id = vid.generate()
+
+console.log(id.toString())
+
+console.log(
+  vid.verify(id.toString())
+)
+Storage Options
+String storage (recommended default):
+
+id.toString()
+Binary storage (optimized):
+
+id.toBinary()
+MongoDB Example
+collection.insertOne({
+  _id: id.toBinary()
+})
+
+vid.verify(doc._id)
+PostgreSQL Example
+CREATE TABLE users (
+  id BYTEA PRIMARY KEY
+);
+await db.query(
+  "INSERT INTO users (id) VALUES ($1)",
+  [id.toBinary()]
+)
+Verification
+vid.verify(id)
+Returns true if valid.
+
+False if tampered or forged.
+
+Parsing
+const metadata = vid.parse(id)
+
+console.log(metadata.timestamp)
+console.log(metadata.nodeId)
+Security
+VID uses HMAC-SHA256 signature truncated to 56 bits.
+
+Verification uses constant-time comparison to prevent timing attacks.
+
+Secret key never exposed.
+
+Performance
+Binary size: 18 bytes
+String size: 26 chars
+
+Index size smaller than UUIDv7.
+

package/dist/adapters/mongo/VIDMongoAdapter.d.ts

@@ -0,0 +1,22 @@
+/**
+ * MongoDB adapter for VID.
+ *
+ * Converts between VID binary format and MongoDB BSON Binary type.
+ *
+ * Does NOT require VIDValue instance.
+ * Works with Uint8Array directly.
+ */
+export declare class VIDMongoAdapter {
+    /**
+     * Convert VID binary to MongoDB Binary.
+     *
+     * Accepts Uint8Array (from id.toBinary())
+     */
+    static toDatabase(binary: Uint8Array): Buffer;
+    /**
+     * Convert MongoDB Binary to Uint8Array.
+     *
+     * Output can be passed directly to vid.verify()
+     */
+    static fromDatabase(value: Buffer): Uint8Array;
+}

package/dist/adapters/mongo/VIDMongoAdapter.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VIDMongoAdapter = void 0;
+/**
+ * MongoDB adapter for VID.
+ *
+ * Converts between VID binary format and MongoDB BSON Binary type.
+ *
+ * Does NOT require VIDValue instance.
+ * Works with Uint8Array directly.
+ */
+class VIDMongoAdapter {
+    /**
+     * Convert VID binary to MongoDB Binary.
+     *
+     * Accepts Uint8Array (from id.toBinary())
+     */
+    static toDatabase(binary) {
+        if (!(binary instanceof Uint8Array)) {
+            throw new Error("Expected Uint8Array");
+        }
+        return Buffer.from(binary);
+    }
+    /**
+     * Convert MongoDB Binary to Uint8Array.
+     *
+     * Output can be passed directly to vid.verify()
+     */
+    static fromDatabase(value) {
+        if (!(value instanceof Buffer)) {
+            throw new Error("Expected MongoDB Binary");
+        }
+        return new Uint8Array(value);
+    }
+}
+exports.VIDMongoAdapter = VIDMongoAdapter;

package/dist/adapters/postgres/VIDPostgresAdapter.d.ts

@@ -0,0 +1,35 @@
+/**
+ * PostgreSQL adapter for VID.
+ *
+ * Converts between VID binary format and PostgreSQL BYTEA format.
+ *
+ * PostgreSQL BYTEA maps to Node.js Buffer.
+ *
+ * This adapter does NOT depend on VIDValue.
+ * Works only with Uint8Array and Buffer.
+ */
+export declare class VIDPostgresAdapter {
+    /**
+     * Convert VID binary (Uint8Array) to PostgreSQL Buffer.
+     *
+     * Usage:
+     *
+     * await db.query(
+     *   "INSERT INTO users (id) VALUES ($1)",
+     *   [VIDPostgresAdapter.toDatabase(id.toBinary())]
+     * )
+     */
+    static toDatabase(binary: Uint8Array): Buffer;
+    /**
+     * Convert PostgreSQL BYTEA (Buffer) to Uint8Array.
+     *
+     * Usage:
+     *
+     * const result = await db.query(...)
+     *
+     * vid.verify(
+     *   VIDPostgresAdapter.fromDatabase(result.rows[0].id)
+     * )
+     */
+    static fromDatabase(buffer: Buffer): Uint8Array;
+}

package/dist/adapters/postgres/VIDPostgresAdapter.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VIDPostgresAdapter = void 0;
+/**
+ * PostgreSQL adapter for VID.
+ *
+ * Converts between VID binary format and PostgreSQL BYTEA format.
+ *
+ * PostgreSQL BYTEA maps to Node.js Buffer.
+ *
+ * This adapter does NOT depend on VIDValue.
+ * Works only with Uint8Array and Buffer.
+ */
+class VIDPostgresAdapter {
+    /**
+     * Convert VID binary (Uint8Array) to PostgreSQL Buffer.
+     *
+     * Usage:
+     *
+     * await db.query(
+     *   "INSERT INTO users (id) VALUES ($1)",
+     *   [VIDPostgresAdapter.toDatabase(id.toBinary())]
+     * )
+     */
+    static toDatabase(binary) {
+        if (!(binary instanceof Uint8Array)) {
+            throw new Error("VIDPostgresAdapter.toDatabase: expected Uint8Array");
+        }
+        return Buffer.from(binary);
+    }
+    /**
+     * Convert PostgreSQL BYTEA (Buffer) to Uint8Array.
+     *
+     * Usage:
+     *
+     * const result = await db.query(...)
+     *
+     * vid.verify(
+     *   VIDPostgresAdapter.fromDatabase(result.rows[0].id)
+     * )
+     */
+    static fromDatabase(buffer) {
+        if (!Buffer.isBuffer(buffer)) {
+            throw new Error("VIDPostgresAdapter.fromDatabase: expected Buffer");
+        }
+        return new Uint8Array(buffer);
+    }
+}
+exports.VIDPostgresAdapter = VIDPostgresAdapter;

package/dist/core/VID.d.ts

@@ -0,0 +1,103 @@
+import { VIDOptions } from "../types";
+import { VIDValue } from "./VIDValue";
+/**
+ * VID — Verifiable Identifier Engine
+ *
+ * This class is the main entry point for generating, verifying,
+ * and parsing VIDs.
+ *
+ * It encapsulates all configuration required for identifier generation,
+ * including cryptographic secret, key version, and node identity.
+ *
+ * This class is stateless beyond its configuration and safe to use
+ * in distributed environments.
+ *
+ * Example usage:
+ *
+ * ```ts
+ * const vid = VID.initialize({
+ *   secret: process.env.VID_SECRET!,
+ *   keyVersion: 1,
+ *   nodeId: 42
+ * })
+ *
+ * const id = vid.generate()
+ *
+ * console.log(id.toString())
+ *
+ * const valid = vid.verify(id)
+ *
+ * const metadata = vid.parse(id)
+ * ```
+ *
+ * Configuration must be initialized once per service instance.
+ */
+export declare class VID {
+    /**
+     * Cryptographic secret used for HMAC signing.
+     *
+     * Stored internally as byte array for deterministic cryptographic behavior.
+     */
+    private readonly secret;
+    /**
+     * Secret version identifier.
+     *
+     * Embedded in VID binary structure.
+     * Enables secret rotation.
+     */
+    private readonly keyVersion;
+    /**
+     * Unique identifier for this node.
+     *
+     * Prevents collisions in distributed systems.
+     */
+    private readonly nodeId;
+    /**
+     * Private constructor.
+     *
+     * Use VID.initialize() instead.
+     */
+    private constructor();
+    /**
+     * Initializes VID engine instance.
+     *
+     * This must be called before generating identifiers.
+     *
+     * @param options.secret Cryptographic secret string (required)
+     * @param options.keyVersion Secret version number (required)
+     * @param options.nodeId Optional node identifier
+     *
+     * @returns VID instance
+     *
+     * Throws error if configuration invalid.
+     */
+    static initialize(options: VIDOptions): VID;
+    /**
+     * Generates a new VID.
+     *
+     * @returns VIDValue object
+     *
+     * Thread-safe within Node.js event loop.
+     */
+    generate(): VIDValue;
+    /**
+     * Verifies VID authenticity.
+     *
+     * Ensures identifier was generated using correct secret.
+     *
+     * @param id VIDValue instance
+     *
+     * @returns true if valid, false otherwise
+     */
+    verify(input: string | Uint8Array | Buffer | ArrayBuffer): boolean;
+    /**
+     * Parses VID metadata.
+     *
+     * Extracts timestamp, nodeId, sequence, and keyVersion.
+     *
+     * @param id VIDValue instance
+     *
+     * @returns VIDMetadata
+     */
+    parse(input: string | Uint8Array | Buffer | ArrayBuffer): import("../types").VIDMetadata;
+}

package/dist/core/VID.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VID = void 0;
+const VIDGenerator_1 = require("./VIDGenerator");
+const VIDVerifier_1 = require("./VIDVerifier");
+const VIDParser_1 = require("./VIDParser");
+/**
+ * VID — Verifiable Identifier Engine
+ *
+ * This class is the main entry point for generating, verifying,
+ * and parsing VIDs.
+ *
+ * It encapsulates all configuration required for identifier generation,
+ * including cryptographic secret, key version, and node identity.
+ *
+ * This class is stateless beyond its configuration and safe to use
+ * in distributed environments.
+ *
+ * Example usage:
+ *
+ * ```ts
+ * const vid = VID.initialize({
+ *   secret: process.env.VID_SECRET!,
+ *   keyVersion: 1,
+ *   nodeId: 42
+ * })
+ *
+ * const id = vid.generate()
+ *
+ * console.log(id.toString())
+ *
+ * const valid = vid.verify(id)
+ *
+ * const metadata = vid.parse(id)
+ * ```
+ *
+ * Configuration must be initialized once per service instance.
+ */
+class VID {
+    /**
+     * Private constructor.
+     *
+     * Use VID.initialize() instead.
+     */
+    constructor(options) {
+        // Validate options object
+        if (!options) {
+            throw new Error("VID initialization failed: options object is required");
+        }
+        /**
+         * Validate secret presence
+         */
+        if (options.secret === undefined || options.secret === null) {
+            throw new Error("VID initialization failed: secret is required");
+        }
+        /**
+         * Validate secret type
+         */
+        if (typeof options.secret !== "string") {
+            throw new Error("VID initialization failed: secret must be a string");
+        }
+        /**
+         * Validate secret length
+         */
+        if (options.secret.trim().length === 0) {
+            throw new Error("VID initialization failed: secret must not be empty");
+        }
+        if (options.secret.length < 8) {
+            throw new Error("VID initialization failed: secret must be at least 8 characters");
+        }
+        /**
+         * Validate keyVersion presence
+         */
+        if (options.keyVersion === undefined || options.keyVersion === null) {
+            throw new Error("VID initialization failed: keyVersion is required");
+        }
+        /**
+         * Validate keyVersion type
+         */
+        if (!Number.isInteger(options.keyVersion)) {
+            throw new Error("VID initialization failed: keyVersion must be an integer");
+        }
+        /**
+         * Validate keyVersion range
+         */
+        if (options.keyVersion < 0 || options.keyVersion > 255) {
+            throw new Error("VID initialization failed: keyVersion must be between 0 and 255");
+        }
+        /**
+         * Validate nodeId if provided
+         */
+        if (options.nodeId !== undefined) {
+            if (!Number.isInteger(options.nodeId)) {
+                throw new Error("VID initialization failed: nodeId must be an integer");
+            }
+            if (options.nodeId < 0 || options.nodeId > 65535) {
+                throw new Error("VID initialization failed: nodeId must be between 0 and 65535");
+            }
+            this.nodeId = options.nodeId;
+        }
+        else {
+            /**
+             * Auto-generate nodeId safely
+             *
+             * Uses process and time entropy to reduce collision risk.
+             */
+            this.nodeId = ((process.pid ^ Date.now()) & 0xffff);
+        }
+        /**
+         * Convert secret string to byte array
+         */
+        this.secret =
+            new TextEncoder().encode(options.secret);
+        this.keyVersion = options.keyVersion;
+    }
+    /**
+     * Initializes VID engine instance.
+     *
+     * This must be called before generating identifiers.
+     *
+     * @param options.secret Cryptographic secret string (required)
+     * @param options.keyVersion Secret version number (required)
+     * @param options.nodeId Optional node identifier
+     *
+     * @returns VID instance
+     *
+     * Throws error if configuration invalid.
+     */
+    static initialize(options) {
+        return new VID(options);
+    }
+    /**
+     * Generates a new VID.
+     *
+     * @returns VIDValue object
+     *
+     * Thread-safe within Node.js event loop.
+     */
+    generate() {
+        return VIDGenerator_1.VIDGenerator.generate({
+            secret: this.secret,
+            keyVersion: this.keyVersion,
+            nodeId: this.nodeId
+        });
+    }
+    /**
+     * Verifies VID authenticity.
+     *
+     * Ensures identifier was generated using correct secret.
+     *
+     * @param id VIDValue instance
+     *
+     * @returns true if valid, false otherwise
+     */
+    verify(input) {
+        return VIDVerifier_1.VIDVerifier.verify(input, this.secret);
+    }
+    /**
+     * Parses VID metadata.
+     *
+     * Extracts timestamp, nodeId, sequence, and keyVersion.
+     *
+     * @param id VIDValue instance
+     *
+     * @returns VIDMetadata
+     */
+    parse(input) {
+        return VIDParser_1.VIDParser.parse(input);
+    }
+}
+exports.VID = VID;

package/dist/core/VIDGenerator.d.ts

@@ -0,0 +1,53 @@
+import { VIDValue } from "./VIDValue";
+/**
+ * VIDGenerator is responsible for constructing VID binary identifiers.
+ *
+ * This class is INTERNAL and should never be used directly by library consumers.
+ *
+ * It assumes all inputs have already been validated by the VID class.
+ *
+ * Responsibilities:
+ *
+ * - Construct VID payload
+ * - Ensure per-millisecond uniqueness using sequence counter
+ * - Generate cryptographic signature
+ * - Combine payload and signature into final VID binary
+ *
+ * VID binary layout (18 bytes total):
+ *
+ * Byte 0       → keyVersion    (1 byte)
+ *
+ * Bytes 1–6    → timestamp     (6 bytes, milliseconds)
+ *
+ * Bytes 7–8    → nodeId        (2 bytes)
+ *
+ * Bytes 9–10   → sequence      (2 bytes)
+ *
+ * Bytes 11–17  → signature     (7 bytes, HMAC truncated)
+ */
+export declare class VIDGenerator {
+    /**
+     * Generates a new VIDValue instance.
+     *
+     * This method is called internally by VID.generate().
+     *
+     * @param config.secret Secret key (Uint8Array)
+     * @param config.keyVersion Secret version identifier
+     * @param config.nodeId Unique node identifier
+     *
+     * @returns VIDValue instance containing binary identifier
+     *
+     * Internal assumptions:
+     *
+     * - secret is valid Uint8Array
+     * - keyVersion is valid uint8
+     * - nodeId is valid uint16
+     *
+     * These guarantees are enforced by VID.initialize().
+     */
+    static generate(config: {
+        secret: Uint8Array;
+        keyVersion: number;
+        nodeId: number;
+    }): VIDValue;
+}

package/dist/core/VIDGenerator.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VIDGenerator = void 0;
+const ByteUtils_1 = require("../utils/ByteUtils");
+const HMACSigner_1 = require("../crypto/HMACSigner");
+const VIDValue_1 = require("./VIDValue");
+/**
+ * Internal timestamp tracker.
+ *
+ * Used to detect multiple ID generation events within the same millisecond.
+ *
+ * Ensures monotonic uniqueness when generating high volumes of IDs.
+ */
+let lastTimestamp = 0;
+/**
+ * Per-millisecond sequence counter.
+ *
+ * Prevents collisions when multiple identifiers are generated within the same millisecond.
+ *
+ * Range: 0–65535 (uint16)
+ */
+let sequence = 0;
+/**
+ * VIDGenerator is responsible for constructing VID binary identifiers.
+ *
+ * This class is INTERNAL and should never be used directly by library consumers.
+ *
+ * It assumes all inputs have already been validated by the VID class.
+ *
+ * Responsibilities:
+ *
+ * - Construct VID payload
+ * - Ensure per-millisecond uniqueness using sequence counter
+ * - Generate cryptographic signature
+ * - Combine payload and signature into final VID binary
+ *
+ * VID binary layout (18 bytes total):
+ *
+ * Byte 0       → keyVersion    (1 byte)
+ *
+ * Bytes 1–6    → timestamp     (6 bytes, milliseconds)
+ *
+ * Bytes 7–8    → nodeId        (2 bytes)
+ *
+ * Bytes 9–10   → sequence      (2 bytes)
+ *
+ * Bytes 11–17  → signature     (7 bytes, HMAC truncated)
+ */
+class VIDGenerator {
+    /**
+     * Generates a new VIDValue instance.
+     *
+     * This method is called internally by VID.generate().
+     *
+     * @param config.secret Secret key (Uint8Array)
+     * @param config.keyVersion Secret version identifier
+     * @param config.nodeId Unique node identifier
+     *
+     * @returns VIDValue instance containing binary identifier
+     *
+     * Internal assumptions:
+     *
+     * - secret is valid Uint8Array
+     * - keyVersion is valid uint8
+     * - nodeId is valid uint16
+     *
+     * These guarantees are enforced by VID.initialize().
+     */
+    static generate(config) {
+        /**
+         * Get current timestamp in milliseconds.
+         */
+        let timestamp = Date.now();
+        /**
+         * Handle same-millisecond generation.
+         *
+         * If generating multiple IDs within same millisecond,
+         * increment sequence counter.
+         */
+        if (timestamp === lastTimestamp) {
+            sequence++;
+            /**
+             * Prevent uint16 overflow.
+             *
+             * More than 65,536 IDs per millisecond is extremely unlikely.
+             */
+            if (sequence > 65535) {
+                throw new Error("VID generation overflow: too many IDs generated in same millisecond");
+            }
+        }
+        else {
+            sequence = 0;
+            lastTimestamp = timestamp;
+        }
+        /**
+         * Construct payload buffer (11 bytes).
+         *
+         * Payload contains core identifier data excluding signature.
+         */
+        const payload = new Uint8Array(11);
+        const view = new DataView(payload.buffer);
+        /**
+         * Byte 0 → keyVersion
+         */
+        view.setUint8(0, config.keyVersion);
+        /**
+         * Bytes 1–6 → timestamp (48-bit)
+         *
+         * Split into:
+         *
+         * high 32 bits → bytes 1–4
+         * low 16 bits  → bytes 5–6
+         */
+        view.setUint32(1, Math.floor(timestamp / 65536));
+        view.setUint16(5, timestamp % 65536);
+        /**
+         * Bytes 7–8 → nodeId
+         */
+        view.setUint16(7, config.nodeId);
+        /**
+         * Bytes 9–10 → sequence
+         */
+        view.setUint16(9, sequence);
+        /**
+         * Generate cryptographic signature.
+         *
+         * Signature ensures identifier authenticity.
+         */
+        const signature = HMACSigner_1.HMACSigner.sign(payload, config.secret);
+        /**
+         * Combine payload and signature into final binary identifier.
+         */
+        const binary = ByteUtils_1.ByteUtils.concat(payload, signature);
+        /**
+         * Return VIDValue instance.
+         */
+        return new VIDValue_1.VIDValue(binary);
+    }
+}
+exports.VIDGenerator = VIDGenerator;

package/dist/core/VIDParser.d.ts

@@ -0,0 +1,49 @@
+import { VIDMetadata } from "../types";
+/**
+ * VIDParser
+ *
+ * Responsible for extracting metadata from a VID identifier.
+ *
+ * This class does NOT perform cryptographic verification.
+ * It only decodes structural fields embedded in the VID.
+ *
+ * Supported input formats:
+ *
+ * - Base32 string
+ * - Uint8Array
+ * - Buffer (Node.js)
+ * - ArrayBuffer
+ *
+ * VID binary layout (18 bytes total):
+ *
+ * Byte 0       → keyVersion  (1 byte)
+ * Bytes 1–6    → timestamp   (6 bytes, 48-bit)
+ * Bytes 7–8    → nodeId      (2 bytes)
+ * Bytes 9–10   → sequence    (2 bytes)
+ * Bytes 11–17  → signature   (7 bytes)
+ *
+ * Returned metadata does NOT include signature.
+ */
+export declare class VIDParser {
+    /**
+     * Parses VID and extracts metadata fields.
+     *
+     * @param input VID in string or binary format
+     *
+     * @returns VIDMetadata object containing:
+     *
+     * - keyVersion → secret version used
+     * - timestamp → creation timestamp (ms)
+     * - nodeId → generator node identifier
+     * - sequence → per-ms sequence counter
+     *
+     * Throws error for invalid input structure.
+     */
+    static parse(input: string | Uint8Array | Buffer | ArrayBuffer): VIDMetadata;
+    /**
+     * Normalizes input into canonical Uint8Array.
+     *
+     * Accepts string, Buffer, Uint8Array, ArrayBuffer.
+     */
+    private static normalizeToBinary;
+}

package/dist/core/VIDParser.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VIDParser = void 0;
+const Base32Decoder_1 = require("../encoding/Base32Decoder");
+/**
+ * VIDParser
+ *
+ * Responsible for extracting metadata from a VID identifier.
+ *
+ * This class does NOT perform cryptographic verification.
+ * It only decodes structural fields embedded in the VID.
+ *
+ * Supported input formats:
+ *
+ * - Base32 string
+ * - Uint8Array
+ * - Buffer (Node.js)
+ * - ArrayBuffer
+ *
+ * VID binary layout (18 bytes total):
+ *
+ * Byte 0       → keyVersion  (1 byte)
+ * Bytes 1–6    → timestamp   (6 bytes, 48-bit)
+ * Bytes 7–8    → nodeId      (2 bytes)
+ * Bytes 9–10   → sequence    (2 bytes)
+ * Bytes 11–17  → signature   (7 bytes)
+ *
+ * Returned metadata does NOT include signature.
+ */
+class VIDParser {
+    /**
+     * Parses VID and extracts metadata fields.
+     *
+     * @param input VID in string or binary format
+     *
+     * @returns VIDMetadata object containing:
+     *
+     * - keyVersion → secret version used
+     * - timestamp → creation timestamp (ms)
+     * - nodeId → generator node identifier
+     * - sequence → per-ms sequence counter
+     *
+     * Throws error for invalid input structure.
+     */
+    static parse(input) {
+        const binary = this.normalizeToBinary(input);
+        if (binary.length !== 18) {
+            throw new Error("VID parse failed: invalid VID length");
+        }
+        const view = new DataView(binary.buffer, binary.byteOffset, binary.byteLength);
+        /**
+         * Extract keyVersion (1 byte)
+         */
+        const keyVersion = view.getUint8(0);
+        /**
+         * Extract timestamp (48-bit)
+         *
+         * Recombine:
+         *
+         * high 32 bits → bytes 1–4
+         * low 16 bits → bytes 5–6
+         */
+        const timestamp = view.getUint32(1) * 65536 +
+            view.getUint16(5);
+        /**
+         * Extract nodeId (2 bytes)
+         */
+        const nodeId = view.getUint16(7);
+        /**
+         * Extract sequence (2 bytes)
+         */
+        const sequence = view.getUint16(9);
+        /**
+         * Optional derived fields for usability
+         */
+        const date = new Date(timestamp);
+        const iso = date.toISOString();
+        return {
+            keyVersion,
+            timestamp,
+            nodeId,
+            sequence,
+            /**
+             * Helpful derived values
+             */
+            date,
+            iso
+        };
+    }
+    /**
+     * Normalizes input into canonical Uint8Array.
+     *
+     * Accepts string, Buffer, Uint8Array, ArrayBuffer.
+     */
+    static normalizeToBinary(input) {
+        if (input === null || input === undefined) {
+            throw new Error("VID parse failed: input is required");
+        }
+        /**
+         * Handle Base32 string
+         */
+        if (typeof input === "string") {
+            const trimmed = input.trim();
+            if (trimmed.length === 0) {
+                throw new Error("VID parse failed: empty string");
+            }
+            try {
+                return Base32Decoder_1.Base32Decoder.decode(trimmed);
+            }
+            catch {
+                throw new Error("VID parse failed: invalid string encoding");
+            }
+        }
+        /**
+         * Handle Uint8Array
+         */
+        if (input instanceof Uint8Array) {
+            return input;
+        }
+        /**
+         * Handle Node.js Buffer
+         */
+        if (typeof Buffer !== "undefined" &&
+            Buffer.isBuffer(input)) {
+            return new Uint8Array(input);
+        }
+        /**
+         * Handle ArrayBuffer
+         */
+        if (input instanceof ArrayBuffer) {
+            return new Uint8Array(input);
+        }
+        throw new Error("VID parse failed: unsupported input type");
+    }
+}
+exports.VIDParser = VIDParser;

package/dist/core/VIDValue.d.ts

@@ -0,0 +1,25 @@
+export declare class VIDValue {
+    private readonly binary;
+    constructor(binary: Uint8Array);
+    /**
+     * Returns Base32 string representation.
+     *
+     * Recommended for:
+     * - APIs
+     * - logging
+     * - debugging
+     * - external communication
+     */
+    toString(): string;
+    /**
+     * Returns binary representation.
+     *
+     * Recommended for:
+     * - MongoDB Binary
+     * - PostgreSQL BYTEA
+     * - Redis
+     *
+     * Saves database space and improves index performance.
+     */
+    toBinary(): Uint8Array;
+}

package/dist/core/VIDValue.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VIDValue = void 0;
+const Base32Encoder_1 = require("../encoding/Base32Encoder");
+class VIDValue {
+    constructor(binary) {
+        if (!binary || binary.length !== 18) {
+            throw new Error("Invalid VID binary");
+        }
+        this.binary = binary;
+    }
+    /**
+     * Returns Base32 string representation.
+     *
+     * Recommended for:
+     * - APIs
+     * - logging
+     * - debugging
+     * - external communication
+     */
+    toString() {
+        return Base32Encoder_1.Base32Encoder.encode(this.binary);
+    }
+    /**
+     * Returns binary representation.
+     *
+     * Recommended for:
+     * - MongoDB Binary
+     * - PostgreSQL BYTEA
+     * - Redis
+     *
+     * Saves database space and improves index performance.
+     */
+    toBinary() {
+        return this.binary;
+    }
+}
+exports.VIDValue = VIDValue;

package/dist/core/VIDVerifier.d.ts

@@ -0,0 +1,44 @@
+/**
+ * VIDVerifier
+ *
+ * Central verification engine for VID identifiers.
+ *
+ * Responsibilities:
+ *
+ * - Accept user input in multiple formats
+ * - Normalize input into canonical binary form
+ * - Validate VID structure
+ * - Verify cryptographic authenticity
+ *
+ * Supported input formats:
+ *
+ * - Base32 string
+ * - Uint8Array
+ * - Node.js Buffer
+ * - ArrayBuffer
+ *
+ * VID binary layout (18 bytes):
+ *
+ * Bytes 0–10  → payload
+ * Bytes 11–17 → signature
+ */
+export declare class VIDVerifier {
+    /**
+     * Public verification method.
+     *
+     * Accepts flexible input formats and verifies VID authenticity.
+     *
+     * @param input VID in string or binary format
+     * @param secret secret key used for signing
+     *
+     * @returns true if valid
+     * @returns false if invalid or tampered
+     */
+    static verify(input: string | Uint8Array | Buffer | ArrayBuffer, secret: Uint8Array): boolean;
+    /**
+     * Converts user input into Uint8Array.
+     *
+     * Handles all supported transport formats.
+     */
+    private static normalizeToBinary;
+}

package/dist/core/VIDVerifier.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VIDVerifier = void 0;
+const HMACSigner_1 = require("../crypto/HMACSigner");
+const Base32Decoder_1 = require("../encoding/Base32Decoder");
+/**
+ * VIDVerifier
+ *
+ * Central verification engine for VID identifiers.
+ *
+ * Responsibilities:
+ *
+ * - Accept user input in multiple formats
+ * - Normalize input into canonical binary form
+ * - Validate VID structure
+ * - Verify cryptographic authenticity
+ *
+ * Supported input formats:
+ *
+ * - Base32 string
+ * - Uint8Array
+ * - Node.js Buffer
+ * - ArrayBuffer
+ *
+ * VID binary layout (18 bytes):
+ *
+ * Bytes 0–10  → payload
+ * Bytes 11–17 → signature
+ */
+class VIDVerifier {
+    /**
+     * Public verification method.
+     *
+     * Accepts flexible input formats and verifies VID authenticity.
+     *
+     * @param input VID in string or binary format
+     * @param secret secret key used for signing
+     *
+     * @returns true if valid
+     * @returns false if invalid or tampered
+     */
+    static verify(input, secret) {
+        if (!secret || !(secret instanceof Uint8Array)) {
+            throw new Error("VID verification failed: valid secret is required");
+        }
+        const binary = this.normalizeToBinary(input);
+        if (binary.length !== 18) {
+            return false;
+        }
+        const payload = binary.slice(0, 11);
+        const signature = binary.slice(11, 18);
+        return HMACSigner_1.HMACSigner.verify(payload, signature, secret);
+    }
+    /**
+     * Converts user input into Uint8Array.
+     *
+     * Handles all supported transport formats.
+     */
+    static normalizeToBinary(input) {
+        if (input === null || input === undefined) {
+            throw new Error("VID verification failed: input is required");
+        }
+        /**
+         * String input (Base32)
+         */
+        if (typeof input === "string") {
+            const trimmed = input.trim();
+            if (trimmed.length === 0) {
+                throw new Error("VID verification failed: empty string");
+            }
+            try {
+                return Base32Decoder_1.Base32Decoder.decode(trimmed);
+            }
+            catch {
+                throw new Error("VID verification failed: invalid string encoding");
+            }
+        }
+        /**
+         * Uint8Array input
+         */
+        if (input instanceof Uint8Array) {
+            return input;
+        }
+        /**
+         * Buffer input
+         */
+        if (typeof Buffer !== "undefined" && Buffer.isBuffer(input)) {
+            return new Uint8Array(input);
+        }
+        /**
+         * ArrayBuffer input
+         */
+        if (input instanceof ArrayBuffer) {
+            return new Uint8Array(input);
+        }
+        throw new Error("VID verification failed: unsupported input type");
+    }
+}
+exports.VIDVerifier = VIDVerifier;

package/dist/crypto/HMACSigner.d.ts

@@ -0,0 +1,5 @@
+export declare class HMACSigner {
+    private static SIGNATURE_LENGTH;
+    static sign(payload: Uint8Array, secret: Uint8Array): Uint8Array;
+    static verify(payload: Uint8Array, signature: Uint8Array, secret: Uint8Array): boolean;
+}

package/dist/crypto/HMACSigner.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HMACSigner = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+class HMACSigner {
+    static sign(payload, secret) {
+        const hmac = crypto_1.default.createHmac("sha256", secret);
+        hmac.update(payload);
+        const fullSignature = hmac.digest();
+        return new Uint8Array(fullSignature.slice(0, this.SIGNATURE_LENGTH));
+    }
+    static verify(payload, signature, secret) {
+        if (!payload ||
+            !signature ||
+            !secret) {
+            return false;
+        }
+        if (signature.length !== this.SIGNATURE_LENGTH) {
+            return false;
+        }
+        const expected = this.sign(payload, secret);
+        const expectedBuffer = Buffer.from(expected);
+        const signatureBuffer = Buffer.from(signature);
+        if (expectedBuffer.length !== signatureBuffer.length) {
+            return false;
+        }
+        return crypto_1.default.timingSafeEqual(expectedBuffer, signatureBuffer);
+    }
+}
+exports.HMACSigner = HMACSigner;
+HMACSigner.SIGNATURE_LENGTH = 7;

package/dist/encoding/Base32Decoder.d.ts

@@ -0,0 +1,3 @@
+export declare class Base32Decoder {
+    static decode(str: string): Uint8Array;
+}

package/dist/encoding/Base32Decoder.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Base32Decoder = void 0;
+const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+class Base32Decoder {
+    static decode(str) {
+        let bits = 0;
+        let value = 0;
+        const out = [];
+        for (const c of str) {
+            const idx = alphabet.indexOf(c);
+            if (idx === -1)
+                throw new Error("Invalid Base32");
+            value = (value << 5) | idx;
+            bits += 5;
+            if (bits >= 8) {
+                out.push((value >>> (bits - 8)) & 255);
+                bits -= 8;
+            }
+        }
+        return new Uint8Array(out);
+    }
+}
+exports.Base32Decoder = Base32Decoder;

package/dist/encoding/Base32Encoder.d.ts

@@ -0,0 +1,3 @@
+export declare class Base32Encoder {
+    static encode(data: Uint8Array): string;
+}

package/dist/encoding/Base32Encoder.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Base32Encoder = void 0;
+const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+class Base32Encoder {
+    static encode(data) {
+        let bits = 0;
+        let value = 0;
+        let output = "";
+        for (const byte of data) {
+            value = (value << 8) | byte;
+            bits += 8;
+            while (bits >= 5) {
+                output += alphabet[(value >>> (bits - 5)) & 31];
+                bits -= 5;
+            }
+        }
+        if (bits > 0) {
+            output += alphabet[(value << (5 - bits)) & 31];
+        }
+        return output;
+    }
+}
+exports.Base32Encoder = Base32Encoder;

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { VID } from "./core/VID";

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VID = void 0;
+var VID_1 = require("./core/VID");
+Object.defineProperty(exports, "VID", { enumerable: true, get: function () { return VID_1.VID; } });

package/dist/types/index.d.ts

@@ -0,0 +1,13 @@
+export interface VIDOptions {
+    secret: string;
+    keyVersion: number;
+    nodeId?: number;
+}
+export interface VIDMetadata {
+    keyVersion: number;
+    timestamp: number;
+    date: Date;
+    nodeId: number;
+    sequence: number;
+    iso: string;
+}

package/dist/types/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils/ByteUtils.d.ts

@@ -0,0 +1,3 @@
+export declare class ByteUtils {
+    static concat(a: Uint8Array, b: Uint8Array): Uint8Array;
+}

package/dist/utils/ByteUtils.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ByteUtils = void 0;
+class ByteUtils {
+    static concat(a, b) {
+        const out = new Uint8Array(a.length + b.length);
+        out.set(a, 0);
+        out.set(b, a.length);
+        return out;
+    }
+}
+exports.ByteUtils = ByteUtils;

package/dist/utils/TimeUtils.d.ts

@@ -0,0 +1,3 @@
+export declare class TimeUtils {
+    static now(): number;
+}

package/dist/utils/TimeUtils.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimeUtils = void 0;
+class TimeUtils {
+    static now() {
+        return Date.now();
+    }
+}
+exports.TimeUtils = TimeUtils;

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@veridjs/core",
+  "version": "1.0.0",
+  "description": "Verifiable Identifier for distributed systems",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./postgres": "./dist/adapters/VIDPostgresAdapter.js",
+    "./mongo": "./dist/adapters/VIDMongoAdapter.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "keywords": [
+    "identifier",
+    "uuid",
+    "vid",
+    "distributed"
+  ],
+  "author": "Kishan Kumar",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "@types/pg": "^8.16.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {}
+}