@tnid/encryption 0.0.4 → 0.0.5

package/README.md

@@ -1,6 +1,6 @@
 # @tnid/encryption
 
-Format-preserving encryption for TNIDs - hide timestamp information by encrypting V0 TNIDs to V1.
+Encrypt V0 TNIDs to V1 to hide timestamp information.
 
 ## Why Encrypt TNIDs?
 
@@ -62,13 +62,7 @@ const decrypted = await decryptV1ToV0(v1, key);
 
 ## How It Works
 
-The encryption uses Format-Preserving Encryption (FPE) with AES-128 in FF1 mode (NIST SP 800-38G). This encrypts the 100 Payload bits while preserving:
-
-- The TNID name (unchanged)
-- The UUID version/variant bits (valid UUIDv8)
-- The overall 128-bit structure
-
-The TNID variant changes from V0 to V1, making the encrypted ID indistinguishable from a randomly generated V1 TNID.
+The encryption converts the 100 payload bits while preserving the TNID structure. The result is a valid V1 TNID that is indistinguishable from a randomly generated one.
 
 ## API Reference
 
@@ -94,26 +88,27 @@ const bytes: Uint8Array = key.asBytes();
 Encrypts a V0 TNID to V1, hiding timestamp information.
 
 ```typescript
-const v1 = await encryptV0ToV1("user.Br2flcNDfF6LYICnT", key);
+const v0: UserId = UserId.new_v0();
+const v1: UserId = await encryptV0ToV1(v0, key); // Type preserved!
 ```
 
-- **Input**: V0 TNID string
-- **Output**: V1 TNID string (same name, encrypted payload)
+- **Input**: V0 TNID (any typed TNID or `DynamicTnid`)
+- **Output**: V1 TNID (same type as input)
 - **Idempotent**: If input is already V1, returns it unchanged
-- **Throws**: `EncryptionError` if input is invalid or unsupported variant
+- **Throws**: `EncryptionError` if variant is unsupported (v2/v3)
 
 ### `decryptV1ToV0(tnid, key)`
 
 Decrypts a V1 TNID back to V0, recovering timestamp information.
 
 ```typescript
-const v0 = await decryptV1ToV0("user.X3Wxwp0wOy4OZp_rP", key);
+const decrypted: UserId = await decryptV1ToV0(v1, key); // Type preserved!
 ```
 
-- **Input**: V1 TNID string (encrypted)
-- **Output**: V0 TNID string (original with timestamp)
+- **Input**: V1 TNID (any typed TNID or `DynamicTnid`)
+- **Output**: V0 TNID (same type as input)
 - **Idempotent**: If input is already V0, returns it unchanged
-- **Throws**: `EncryptionError` if input is invalid or unsupported variant
+- **Throws**: `EncryptionError` if variant is unsupported (v2/v3)
 
 ### Error Classes
 
@@ -128,17 +123,12 @@ try {
     console.log("Invalid key:", e.message);
   }
 }
-
-// EncryptionError - encryption/decryption failed
-try {
-  await encryptV0ToV1("invalid-tnid", key);
-} catch (e) {
-  if (e instanceof EncryptionError) {
-    console.log("Encryption failed:", e.message);
-  }
-}
 ```
 
+## Implementation Details
+
+Uses FF1 format-preserving encryption (NIST SP 800-38G) with AES-128, which allows encrypting the 100 payload bits while maintaining the exact same bit length. This implementation is bit-compatible with the Rust TNID library.
+
 ## Note
 
 The encryption functionality is not part of the TNID specification. Encrypted TNIDs are standard V1 TNIDs and remain fully compatible with any TNID implementation.

package/esm/bits.js

@@ -4,7 +4,7 @@
  * These functions extract and expand the 100 Payload bits that are
  * encrypted/decrypted, matching the Rust implementation exactly.
  */
-// Mask for the right-most Payload bits section (bits 0-51, 52 bits)
+// Mask for the right-most Payload bits section (bits 0-59, 60 bits)
 export const RIGHT_SECRET_DATA_SECTION_MASK = 0x00000000000000000fffffffffffffffn;
 // Mask for the middle Payload bits section (bits 64-75, 12 bits)
 export const MIDDLE_SECRET_DATA_SECTION_MASK = 0x0000000000000fff0000000000000000n;

package/esm/encryption.d.ts

@@ -4,6 +4,7 @@
  * Provides functions to convert V0 (time-ordered) TNIDs to V1 (random-looking)
  * TNIDs and vice versa, hiding timestamp information while remaining reversible.
  */
+import { DynamicTnid } from "@tnid/core";
 /**
  * Error when creating an EncryptionKey.
  */
@@ -38,19 +39,19 @@ export declare class EncryptionKey {
 /**
  * Encrypts a V0 TNID to V1, hiding timestamp information.
  *
- * @param tnid The V0 TNID string to encrypt
+ * @param tnid The V0 TNID to encrypt
  * @param key The encryption key
- * @returns The encrypted V1 TNID string
+ * @returns The encrypted V1 TNID (same type as input)
  * @throws EncryptionError if the TNID is not V0 or is invalid
  */
-export declare function encryptV0ToV1(tnid: string, key: EncryptionKey): Promise<string>;
+export declare function encryptV0ToV1<T extends DynamicTnid>(tnid: T, key: EncryptionKey): Promise<T>;
 /**
  * Decrypts a V1 TNID back to V0, recovering timestamp information.
  *
- * @param tnid The V1 TNID string to decrypt
+ * @param tnid The V1 TNID to decrypt
  * @param key The encryption key (must match the one used for encryption)
- * @returns The decrypted V0 TNID string
+ * @returns The decrypted V0 TNID (same type as input)
  * @throws EncryptionError if the TNID is not V1 or is invalid
  */
-export declare function decryptV1ToV0(tnid: string, key: EncryptionKey): Promise<string>;
+export declare function decryptV1ToV0<T extends DynamicTnid>(tnid: T, key: EncryptionKey): Promise<T>;
 //# sourceMappingURL=encryption.d.ts.map

package/esm/encryption.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encryption.d.ts","sourceRoot":"","sources":["../src/encryption.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAmBH;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IAEnC,OAAO;IAIP;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,aAAa;IASlD;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa;IAsB1C;;OAEG;IACH,OAAO,IAAI,UAAU;CAGtB;AA6DD;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAmCrF;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAmCrF"}
+{"version":3,"file":"encryption.d.ts","sourceRoot":"","sources":["../src/encryption.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAiBzC;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IAEnC,OAAO;IAIP;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,aAAa;IASlD;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa;IAsB1C;;OAEG;IACH,OAAO,IAAI,UAAU;CAGtB;AA2DD;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,CAAC,SAAS,WAAW,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,CAAC,CAAC,CA8BlG;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,CAAC,SAAS,WAAW,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,CAAC,CAAC,CA8BlG"}

package/esm/encryption.js

@@ -74,16 +74,14 @@ export class EncryptionKey {
     }
 }
 /**
- * Convert TNID string to 128-bit value.
+ * Convert TNID to 128-bit value.
  */
 function tnidToValue(tnid) {
-    // Use @tnid/core to convert to UUID, then parse UUID to value
-    const parsed = DynamicTnid.parse(tnid);
-    const uuid = DynamicTnid.toUuidString(parsed);
+    const uuid = DynamicTnid.toUuidString(tnid);
     return parseUuidStringToValue(uuid);
 }
 /**
- * Convert 128-bit value back to TNID string.
+ * Convert 128-bit value back to TNID.
  */
 function valueToTnid(value) {
     return valueToTnidString(value);
@@ -123,19 +121,13 @@ async function decryptPayload(payload, key) {
 /**
  * Encrypts a V0 TNID to V1, hiding timestamp information.
  *
- * @param tnid The V0 TNID string to encrypt
+ * @param tnid The V0 TNID to encrypt
  * @param key The encryption key
- * @returns The encrypted V1 TNID string
+ * @returns The encrypted V1 TNID (same type as input)
  * @throws EncryptionError if the TNID is not V0 or is invalid
  */
 export async function encryptV0ToV1(tnid, key) {
-    let value;
-    try {
-        value = tnidToValue(tnid);
-    }
-    catch (e) {
-        throw new EncryptionError(`Invalid TNID: ${e.message}`);
-    }
+    const value = tnidToValue(tnid);
     const variant = extractVariantFromValue(value);
     if (variant === "v1") {
         // Already V1, return unchanged
@@ -159,19 +151,13 @@ export async function encryptV0ToV1(tnid, key) {
 /**
  * Decrypts a V1 TNID back to V0, recovering timestamp information.
  *
- * @param tnid The V1 TNID string to decrypt
+ * @param tnid The V1 TNID to decrypt
  * @param key The encryption key (must match the one used for encryption)
- * @returns The decrypted V0 TNID string
+ * @returns The decrypted V0 TNID (same type as input)
  * @throws EncryptionError if the TNID is not V1 or is invalid
  */
 export async function decryptV1ToV0(tnid, key) {
-    let value;
-    try {
-        value = tnidToValue(tnid);
-    }
-    catch (e) {
-        throw new EncryptionError(`Invalid TNID: ${e.message}`);
-    }
+    const value = tnidToValue(tnid);
     const variant = extractVariantFromValue(value);
     if (variant === "v0") {
         // Already V0, return unchanged

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tnid/encryption",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Format-preserving encryption for TNIDs - convert time-ordered IDs to random-looking IDs",
   "keywords": [
     "uuid",
@@ -34,7 +34,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@tnid/core": "^0.0.4"
+    "@tnid/core": "^0.0.5"
   },
   "_generatedBy": "dnt@dev"
 }

package/script/bits.js

@@ -13,7 +13,7 @@ exports.toHexDigits = toHexDigits;
 exports.fromHexDigits = fromHexDigits;
 exports.getVariant = getVariant;
 exports.setVariant = setVariant;
-// Mask for the right-most Payload bits section (bits 0-51, 52 bits)
+// Mask for the right-most Payload bits section (bits 0-59, 60 bits)
 exports.RIGHT_SECRET_DATA_SECTION_MASK = 0x00000000000000000fffffffffffffffn;
 // Mask for the middle Payload bits section (bits 64-75, 12 bits)
 exports.MIDDLE_SECRET_DATA_SECTION_MASK = 0x0000000000000fff0000000000000000n;

package/script/encryption.d.ts

@@ -4,6 +4,7 @@
  * Provides functions to convert V0 (time-ordered) TNIDs to V1 (random-looking)
  * TNIDs and vice versa, hiding timestamp information while remaining reversible.
  */
+import { DynamicTnid } from "@tnid/core";
 /**
  * Error when creating an EncryptionKey.
  */
@@ -38,19 +39,19 @@ export declare class EncryptionKey {
 /**
  * Encrypts a V0 TNID to V1, hiding timestamp information.
  *
- * @param tnid The V0 TNID string to encrypt
+ * @param tnid The V0 TNID to encrypt
  * @param key The encryption key
- * @returns The encrypted V1 TNID string
+ * @returns The encrypted V1 TNID (same type as input)
  * @throws EncryptionError if the TNID is not V0 or is invalid
  */
-export declare function encryptV0ToV1(tnid: string, key: EncryptionKey): Promise<string>;
+export declare function encryptV0ToV1<T extends DynamicTnid>(tnid: T, key: EncryptionKey): Promise<T>;
 /**
  * Decrypts a V1 TNID back to V0, recovering timestamp information.
  *
- * @param tnid The V1 TNID string to decrypt
+ * @param tnid The V1 TNID to decrypt
  * @param key The encryption key (must match the one used for encryption)
- * @returns The decrypted V0 TNID string
+ * @returns The decrypted V0 TNID (same type as input)
  * @throws EncryptionError if the TNID is not V1 or is invalid
  */
-export declare function decryptV1ToV0(tnid: string, key: EncryptionKey): Promise<string>;
+export declare function decryptV1ToV0<T extends DynamicTnid>(tnid: T, key: EncryptionKey): Promise<T>;
 //# sourceMappingURL=encryption.d.ts.map

package/script/encryption.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encryption.d.ts","sourceRoot":"","sources":["../src/encryption.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAmBH;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IAEnC,OAAO;IAIP;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,aAAa;IASlD;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa;IAsB1C;;OAEG;IACH,OAAO,IAAI,UAAU;CAGtB;AA6DD;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAmCrF;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAmCrF"}
+{"version":3,"file":"encryption.d.ts","sourceRoot":"","sources":["../src/encryption.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAiBzC;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IAEnC,OAAO;IAIP;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,aAAa;IASlD;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa;IAsB1C;;OAEG;IACH,OAAO,IAAI,UAAU;CAGtB;AA2DD;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,CAAC,SAAS,WAAW,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,CAAC,CAAC,CA8BlG;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,CAAC,SAAS,WAAW,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,CAAC,CAAC,CA8BlG"}

package/script/encryption.js

@@ -82,16 +82,14 @@ class EncryptionKey {
 }
 exports.EncryptionKey = EncryptionKey;
 /**
- * Convert TNID string to 128-bit value.
+ * Convert TNID to 128-bit value.
  */
 function tnidToValue(tnid) {
-    // Use @tnid/core to convert to UUID, then parse UUID to value
-    const parsed = core_1.DynamicTnid.parse(tnid);
-    const uuid = core_1.DynamicTnid.toUuidString(parsed);
+    const uuid = core_1.DynamicTnid.toUuidString(tnid);
     return (0, uuid_1.parseUuidStringToValue)(uuid);
 }
 /**
- * Convert 128-bit value back to TNID string.
+ * Convert 128-bit value back to TNID.
  */
 function valueToTnid(value) {
     return (0, uuid_1.valueToTnidString)(value);
@@ -131,19 +129,13 @@ async function decryptPayload(payload, key) {
 /**
  * Encrypts a V0 TNID to V1, hiding timestamp information.
  *
- * @param tnid The V0 TNID string to encrypt
+ * @param tnid The V0 TNID to encrypt
  * @param key The encryption key
- * @returns The encrypted V1 TNID string
+ * @returns The encrypted V1 TNID (same type as input)
  * @throws EncryptionError if the TNID is not V0 or is invalid
  */
 async function encryptV0ToV1(tnid, key) {
-    let value;
-    try {
-        value = tnidToValue(tnid);
-    }
-    catch (e) {
-        throw new EncryptionError(`Invalid TNID: ${e.message}`);
-    }
+    const value = tnidToValue(tnid);
     const variant = (0, uuid_1.extractVariantFromValue)(value);
     if (variant === "v1") {
         // Already V1, return unchanged
@@ -167,19 +159,13 @@ async function encryptV0ToV1(tnid, key) {
 /**
  * Decrypts a V1 TNID back to V0, recovering timestamp information.
  *
- * @param tnid The V1 TNID string to decrypt
+ * @param tnid The V1 TNID to decrypt
  * @param key The encryption key (must match the one used for encryption)
- * @returns The decrypted V0 TNID string
+ * @returns The decrypted V0 TNID (same type as input)
  * @throws EncryptionError if the TNID is not V1 or is invalid
  */
 async function decryptV1ToV0(tnid, key) {
-    let value;
-    try {
-        value = tnidToValue(tnid);
-    }
-    catch (e) {
-        throw new EncryptionError(`Invalid TNID: ${e.message}`);
-    }
+    const value = tnidToValue(tnid);
     const variant = (0, uuid_1.extractVariantFromValue)(value);
     if (variant === "v0") {
         // Already V0, return unchanged