@anizoptera/uuid-slug 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (163) hide show
  1. package/LICENSE +54 -31
  2. package/README.md +1175 -30
  3. package/dist/alphabet.d.ts +9 -0
  4. package/dist/alphabet.d.ts.map +1 -0
  5. package/dist/alphabet.js +166 -0
  6. package/dist/alphabet.js.map +1 -0
  7. package/dist/base64url-name.d.ts +7 -0
  8. package/dist/base64url-name.d.ts.map +1 -0
  9. package/dist/base64url-name.js +8 -0
  10. package/dist/base64url-name.js.map +1 -0
  11. package/dist/errors.d.ts +57 -0
  12. package/dist/errors.d.ts.map +1 -0
  13. package/dist/errors.js +162 -0
  14. package/dist/errors.js.map +1 -0
  15. package/dist/feistel.js +39 -0
  16. package/dist/feistel.js.map +1 -0
  17. package/dist/generation-options.js +20 -0
  18. package/dist/generation-options.js.map +1 -0
  19. package/dist/index.d.ts +23 -168
  20. package/dist/index.js +22 -649
  21. package/dist/instant.js +83 -0
  22. package/dist/instant.js.map +1 -0
  23. package/dist/mask-handle.d.ts +16 -0
  24. package/dist/mask-handle.d.ts.map +1 -0
  25. package/dist/mask-handle.js +60 -0
  26. package/dist/mask-handle.js.map +1 -0
  27. package/dist/mask.d.ts +27 -0
  28. package/dist/mask.d.ts.map +1 -0
  29. package/dist/mask.js +164 -0
  30. package/dist/mask.js.map +1 -0
  31. package/dist/masking-codec-protocol.js +23 -0
  32. package/dist/masking-codec-protocol.js.map +1 -0
  33. package/dist/masking-codec-types.d.ts +245 -0
  34. package/dist/masking-codec-types.d.ts.map +1 -0
  35. package/dist/masking-codec.d.ts +19 -0
  36. package/dist/masking-codec.d.ts.map +1 -0
  37. package/dist/masking-codec.js +391 -0
  38. package/dist/masking-codec.js.map +1 -0
  39. package/dist/migration.js +129 -0
  40. package/dist/migration.js.map +1 -0
  41. package/dist/node/runtime.js +39 -0
  42. package/dist/node/runtime.js.map +1 -0
  43. package/dist/payload.d.ts +7 -0
  44. package/dist/payload.d.ts.map +1 -0
  45. package/dist/payload.js +118 -0
  46. package/dist/payload.js.map +1 -0
  47. package/dist/runtime/pool.js +30 -0
  48. package/dist/runtime/pool.js.map +1 -0
  49. package/dist/runtime/portable.js +27 -0
  50. package/dist/runtime/portable.js.map +1 -0
  51. package/dist/sentinel.js +10 -0
  52. package/dist/sentinel.js.map +1 -0
  53. package/dist/siphash.js +29 -0
  54. package/dist/siphash.js.map +1 -0
  55. package/dist/slug.d.ts +169 -0
  56. package/dist/slug.d.ts.map +1 -0
  57. package/dist/slug.js +268 -0
  58. package/dist/slug.js.map +1 -0
  59. package/dist/timestamp.d.ts +19 -0
  60. package/dist/timestamp.d.ts.map +1 -0
  61. package/dist/timestamp.js +44 -0
  62. package/dist/timestamp.js.map +1 -0
  63. package/dist/types.d.ts +535 -0
  64. package/dist/types.d.ts.map +1 -0
  65. package/dist/types.js +8 -0
  66. package/dist/types.js.map +1 -0
  67. package/dist/uuid-value-protocol.js +46 -0
  68. package/dist/uuid-value-protocol.js.map +1 -0
  69. package/dist/uuid-value.d.ts +17 -0
  70. package/dist/uuid-value.d.ts.map +1 -0
  71. package/dist/uuid-value.js +127 -0
  72. package/dist/uuid-value.js.map +1 -0
  73. package/dist/uuid.d.ts +65 -0
  74. package/dist/uuid.d.ts.map +1 -0
  75. package/dist/uuid.js +232 -0
  76. package/dist/uuid.js.map +1 -0
  77. package/dist/v4-slug.d.ts +16 -0
  78. package/dist/v4-slug.d.ts.map +1 -0
  79. package/dist/v4-slug.js +16 -0
  80. package/dist/v4-slug.js.map +1 -0
  81. package/dist/v4.d.ts +42 -0
  82. package/dist/v4.d.ts.map +1 -0
  83. package/dist/v4.js +85 -0
  84. package/dist/v4.js.map +1 -0
  85. package/dist/v7-bounds.d.ts +36 -0
  86. package/dist/v7-bounds.d.ts.map +1 -0
  87. package/dist/v7-bounds.js +49 -0
  88. package/dist/v7-bounds.js.map +1 -0
  89. package/dist/v7-generator-input.js +75 -0
  90. package/dist/v7-generator-input.js.map +1 -0
  91. package/dist/v7-generator.d.ts +43 -0
  92. package/dist/v7-generator.d.ts.map +1 -0
  93. package/dist/v7-generator.js +105 -0
  94. package/dist/v7-generator.js.map +1 -0
  95. package/dist/v7-keyless.d.ts +46 -0
  96. package/dist/v7-keyless.d.ts.map +1 -0
  97. package/dist/v7-keyless.js +106 -0
  98. package/dist/v7-keyless.js.map +1 -0
  99. package/dist/v7-payload.js +54 -0
  100. package/dist/v7-payload.js.map +1 -0
  101. package/dist/v7-slug.d.ts +46 -0
  102. package/dist/v7-slug.d.ts.map +1 -0
  103. package/dist/v7-slug.js +127 -0
  104. package/dist/v7-slug.js.map +1 -0
  105. package/dist/v7-timestamp.js +9 -0
  106. package/dist/v7-timestamp.js.map +1 -0
  107. package/dist/v7-value-options.js +28 -0
  108. package/dist/v7-value-options.js.map +1 -0
  109. package/dist/v7-value.d.ts +23 -0
  110. package/dist/v7-value.d.ts.map +1 -0
  111. package/dist/v7-value.js +31 -0
  112. package/dist/v7-value.js.map +1 -0
  113. package/dist/v7.js +143 -0
  114. package/dist/v7.js.map +1 -0
  115. package/package.json +18 -17
  116. package/src/alphabet.ts +616 -0
  117. package/src/base64url-name.ts +5 -0
  118. package/src/errors.ts +423 -13
  119. package/src/feistel.ts +141 -0
  120. package/src/generation-options.ts +48 -0
  121. package/src/index.ts +137 -57
  122. package/src/instant.ts +196 -0
  123. package/src/keyless.ts +9 -0
  124. package/src/mask-handle.ts +141 -0
  125. package/src/mask.ts +377 -90
  126. package/src/masking-codec-protocol.ts +29 -0
  127. package/src/masking-codec-types.ts +380 -0
  128. package/src/masking-codec.ts +923 -0
  129. package/src/migration.ts +257 -0
  130. package/src/payload.ts +321 -0
  131. package/src/runtime/bun.ts +31 -25
  132. package/src/runtime/node.ts +55 -18
  133. package/src/runtime/pool.ts +90 -0
  134. package/src/runtime/portable.ts +68 -0
  135. package/src/runtime/types.ts +30 -5
  136. package/src/sentinel.ts +13 -0
  137. package/src/siphash.ts +128 -0
  138. package/src/slug.ts +884 -0
  139. package/src/timestamp.ts +122 -0
  140. package/src/types.ts +799 -61
  141. package/src/uuid-value-protocol.ts +77 -0
  142. package/src/uuid-value.ts +341 -0
  143. package/src/uuid.ts +527 -108
  144. package/src/v4-slug.ts +27 -0
  145. package/src/v4.ts +234 -0
  146. package/src/v7-bounds.ts +171 -0
  147. package/src/v7-generator-input.ts +169 -0
  148. package/src/v7-generator.ts +245 -0
  149. package/src/v7-keyless.ts +354 -0
  150. package/src/v7-payload.ts +121 -0
  151. package/src/v7-slug.ts +293 -0
  152. package/src/v7-timestamp.ts +21 -0
  153. package/src/v7-value-options.ts +62 -0
  154. package/src/v7-value.ts +54 -0
  155. package/src/v7.ts +433 -84
  156. package/dist/index.d.ts.map +0 -1
  157. package/dist/index.js.map +0 -1
  158. package/dist/node/index.js +0 -647
  159. package/dist/web/index.js +0 -648
  160. package/src/base64url.ts +0 -76
  161. package/src/codec.ts +0 -218
  162. package/src/runtime/web.ts +0 -20
  163. package/src/schema.ts +0 -123
package/src/base64url.ts DELETED
@@ -1,76 +0,0 @@
1
- import { UuidSlugError } from "./errors";
2
- import type { Base64UrlString } from "./types";
3
-
4
- const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
5
- const DECODE = new Int16Array(128).fill(-1);
6
- for (let i = 0; i < ALPHABET.length; i += 1) DECODE[ALPHABET.charCodeAt(i)] = i;
7
-
8
- function byteAt(bytes: Uint8Array, index: number) {
9
- return bytes[index] ?? 0;
10
- }
11
-
12
- export function encodeBase64Url(bytes: Uint8Array): Base64UrlString {
13
- let out = "";
14
- let i = 0;
15
- for (; i + 2 < bytes.length; i += 3) {
16
- const value = (byteAt(bytes, i) << 16) | (byteAt(bytes, i + 1) << 8) | byteAt(bytes, i + 2);
17
- out += ALPHABET[(value >>> 18) & 63];
18
- out += ALPHABET[(value >>> 12) & 63];
19
- out += ALPHABET[(value >>> 6) & 63];
20
- out += ALPHABET[value & 63];
21
- }
22
- const remaining = bytes.length - i;
23
- if (remaining === 1) {
24
- const value = byteAt(bytes, i) << 16;
25
- out += ALPHABET[(value >>> 18) & 63];
26
- out += ALPHABET[(value >>> 12) & 63];
27
- }
28
- if (remaining === 2) {
29
- const value = (byteAt(bytes, i) << 16) | (byteAt(bytes, i + 1) << 8);
30
- out += ALPHABET[(value >>> 18) & 63];
31
- out += ALPHABET[(value >>> 12) & 63];
32
- out += ALPHABET[(value >>> 6) & 63];
33
- }
34
- return out as Base64UrlString;
35
- }
36
-
37
- export function decodeBase64Url(value: string, out?: Uint8Array, offset = 0): Error | Uint8Array {
38
- if (value.includes("="))
39
- return new UuidSlugError("invalid_base64url", "Base64url value must be unpadded.");
40
- if (value.length % 4 === 1)
41
- return new UuidSlugError("invalid_base64url", "Base64url length is impossible.");
42
-
43
- const byteLength = Math.floor((value.length * 6) / 8);
44
- const target = out ?? new Uint8Array(byteLength);
45
- if (offset < 0 || offset + byteLength > target.length)
46
- return new UuidSlugError("invalid_buffer", "Output buffer is too small.");
47
-
48
- let buffer = 0;
49
- let bits = 0;
50
- let written = 0;
51
- for (let i = 0; i < value.length; i += 1) {
52
- const code = value.charCodeAt(i);
53
- const decoded = code < DECODE.length ? (DECODE[code] ?? -1) : -1;
54
- if (decoded < 0)
55
- return new UuidSlugError("invalid_base64url", `Invalid base64url character at offset ${i}.`);
56
- buffer = (buffer << 6) | decoded;
57
- bits += 6;
58
- if (bits >= 8) {
59
- bits -= 8;
60
- target[offset + written] = (buffer >>> bits) & 0xff;
61
- written += 1;
62
- }
63
- }
64
- if (bits > 0 && (buffer & ((1 << bits) - 1)) !== 0) {
65
- return new UuidSlugError(
66
- "invalid_base64url",
67
- "Base64url value has non-canonical trailing bits.",
68
- );
69
- }
70
- return out ? target : target.subarray(0, byteLength);
71
- }
72
-
73
- export function isBase64Url(value: null | string | undefined): value is Base64UrlString {
74
- if (!value || value.includes("=") || value.length % 4 === 1) return false;
75
- return decodeBase64Url(value) instanceof Error ? false : true;
76
- }
package/src/codec.ts DELETED
@@ -1,218 +0,0 @@
1
- import { runtime } from "#runtime";
2
- import { UuidSlugError } from "./errors";
3
- import {
4
- uuidToMaskedSlugWithSchema,
5
- uuidV7BytesToMaskedSlug,
6
- maskedSlugToUuidWithSchema,
7
- } from "./mask";
8
- import { createMaskSchema, DEFAULT_MASK_SCHEMA } from "./schema";
9
- import type {
10
- MaskSchema,
11
- MaskedUuidSlug,
12
- MaskedUuidV7Slug,
13
- PublicUuidV7Slug,
14
- SentinelUuidV7Slug,
15
- UuidSlug,
16
- UuidSlugCodec,
17
- UuidSlugCodecOptions,
18
- UuidString,
19
- UuidV4Slug,
20
- UuidV4String,
21
- UuidV7Sentinel,
22
- UuidV7String,
23
- UuidV7Slug,
24
- } from "./types";
25
- import { createRuntimeGenerator } from "./v7";
26
- import {
27
- formatUuid,
28
- formatUuidSlug,
29
- hasUuidV7Entropy,
30
- isUuidSlug,
31
- isUuidV4Slug,
32
- isUuidV4String,
33
- isUuidV7Slug,
34
- isUuidV7String,
35
- isUuidString,
36
- parseUuid,
37
- parseUuidSlug,
38
- slugToUuid,
39
- uuidBytesToSlug,
40
- uuidToSlug,
41
- extractUuidV7Timestamp,
42
- } from "./uuid";
43
- import type { FreshValidationOptions, UuidV7SentinelDefinition } from "./types";
44
-
45
- export const UUID_V7_SENTINEL_DEFINITIONS: readonly UuidV7SentinelDefinition[] = [
46
- {
47
- name: "nil",
48
- uuid: "00000000-0000-7000-8000-000000000000" as UuidV7String,
49
- },
50
- {
51
- name: "anonymousUser",
52
- uuid: "00000000-0001-7000-8000-000000000000" as UuidV7String,
53
- },
54
- {
55
- name: "unknownUser",
56
- uuid: "00000000-0002-7000-8000-000000000000" as UuidV7String,
57
- },
58
- ];
59
-
60
- function schemaFromOption(mask: UuidSlugCodecOptions["mask"]): Error | MaskSchema {
61
- if (!mask) return DEFAULT_MASK_SCHEMA;
62
- if ("xor" in mask && "permute" in mask && "inverse" in mask) return mask;
63
- return createMaskSchema(mask);
64
- }
65
-
66
- function createSentinels(definitions: readonly UuidV7SentinelDefinition[]) {
67
- const sentinels: UuidV7Sentinel[] = [];
68
- const byUuid = new Map<string, SentinelUuidV7Slug>();
69
- const bySlug = new Map<string, UuidV7String>();
70
- for (const definition of definitions) {
71
- const slug = uuidToSlug(definition.uuid);
72
- if (slug instanceof Error) throw slug;
73
- const sentinel = {
74
- name: definition.name,
75
- slug: slug as SentinelUuidV7Slug,
76
- uuid: definition.uuid,
77
- };
78
- sentinels.push(sentinel);
79
- byUuid.set(definition.uuid, sentinel.slug);
80
- bySlug.set(sentinel.slug, definition.uuid);
81
- }
82
- return { bySlug, byUuid, sentinels };
83
- }
84
-
85
- /**
86
- * Randomness is drawn into a private buffer and copied out instead of filled through a view
87
- * of the caller's array. `fillRandom` requires a plain `ArrayBuffer` because Web Crypto
88
- * rejects a `SharedArrayBuffer` view, and a caller-supplied `out` carries no such guarantee.
89
- * Reused rather than allocated per call, matching the v7 generator, so the cost is one
90
- * 16-byte copy.
91
- */
92
- const v4Random = new Uint8Array(16);
93
-
94
- function generateUuidV4Bytes(out?: Uint8Array, offset = 0): Error | Uint8Array {
95
- const target = out ?? new Uint8Array(16);
96
- if (offset < 0 || offset + 16 > target.length)
97
- return new UuidSlugError("invalid_buffer", "Output buffer is too small.");
98
- runtime.fillRandom(v4Random);
99
- target.set(v4Random, offset);
100
- target[offset + 6] = ((target[offset + 6] ?? 0) & 0x0f) | 0x40;
101
- target[offset + 8] = ((target[offset + 8] ?? 0) & 0x3f) | 0x80;
102
- return target;
103
- }
104
-
105
- function errorOrThrow<T>(value: Error | T): T {
106
- if (value instanceof Error) throw value;
107
- return value;
108
- }
109
-
110
- export function createUuidSlugCodec(options: UuidSlugCodecOptions = {}): UuidSlugCodec {
111
- const schema = errorOrThrow(schemaFromOption(options.mask));
112
- const legacyMasks = options.legacy?.masks ?? [];
113
- const generator = options.generator ?? createRuntimeGenerator(runtime);
114
- const sentinelState = createSentinels(options.sentinels ?? UUID_V7_SENTINEL_DEFINITIONS);
115
-
116
- function decodeMasked(slug: string): Error | UuidString {
117
- const sentinel = sentinelState.bySlug.get(slug);
118
- if (sentinel) return sentinel;
119
- const primary = maskedSlugToUuidWithSchema(slug, schema);
120
- if (!(primary instanceof Error)) return primary;
121
- for (const legacy of legacyMasks) {
122
- const decoded = maskedSlugToUuidWithSchema(slug, legacy);
123
- if (!(decoded instanceof Error)) return decoded;
124
- }
125
- if (options.legacy?.directDecode === true) return slugToUuid(slug);
126
- return primary;
127
- }
128
-
129
- function uuidV7ToMaskedSlug(uuid: string): Error | PublicUuidV7Slug {
130
- const sentinel = sentinelState.byUuid.get(uuid);
131
- if (sentinel) return sentinel;
132
- return uuidToMaskedSlugWithSchema(uuid, schema) as Error | PublicUuidV7Slug;
133
- }
134
-
135
- return {
136
- sentinels: sentinelState.sentinels,
137
- uuidV4() {
138
- const native = runtime.uuidV4?.();
139
- if (native) return native as UuidV4String;
140
- return errorOrThrow(formatUuid(errorOrThrow(generateUuidV4Bytes()))) as UuidV4String;
141
- },
142
- uuidV7() {
143
- return generator.uuidV7();
144
- },
145
- uuidV4Bytes: generateUuidV4Bytes,
146
- uuidV7Bytes: generator.uuidV7Bytes,
147
- uuidV4Slug() {
148
- return errorOrThrow(uuidBytesToSlug(errorOrThrow(generateUuidV4Bytes()))) as UuidV4Slug;
149
- },
150
- uuidV7Slug() {
151
- if (runtime.uuidV7Slug) return runtime.uuidV7Slug() as UuidV7Slug;
152
- return errorOrThrow(uuidBytesToSlug(errorOrThrow(generator.uuidV7Bytes()))) as UuidV7Slug;
153
- },
154
- uuidV7MaskedSlug() {
155
- return errorOrThrow(uuidV7BytesToMaskedSlug(errorOrThrow(generator.uuidV7Bytes()), schema));
156
- },
157
- uuidToSlug,
158
- slugToUuid,
159
- uuidToMaskedSlug(uuid) {
160
- return uuidV7ToMaskedSlug(uuid) as Error | MaskedUuidSlug;
161
- },
162
- maskedSlugToUuid: decodeMasked,
163
- uuidV7ToMaskedSlug,
164
- maskedSlugToUuidV7(slug) {
165
- const decoded = decodeMasked(slug);
166
- if (decoded instanceof Error) return decoded;
167
- return isUuidV7String(decoded)
168
- ? decoded
169
- : new UuidSlugError("invalid_uuid_version", "Decoded UUID is not UUIDv7.");
170
- },
171
- parseUuid,
172
- formatUuid,
173
- parseUuidSlug,
174
- formatUuidSlug,
175
- };
176
- }
177
-
178
- export const defaultCodec = createUuidSlugCodec();
179
-
180
- export function validateUuidV7Fresh(
181
- uuid: string,
182
- options: FreshValidationOptions = {},
183
- ): Error | UuidV7String {
184
- if (!isUuidV7String(uuid))
185
- return new UuidSlugError("invalid_uuid", "Expected canonical UUIDv7 string.");
186
- const bytes = parseUuid(uuid);
187
- if (bytes instanceof Error) return bytes;
188
- const windowMs = options.windowMs ?? 86_400_000;
189
- const now = options.now?.() ?? Date.now();
190
- const timestamp = extractUuidV7Timestamp(bytes);
191
- if (timestamp < now - windowMs || timestamp > now + windowMs)
192
- return new UuidSlugError("stale_uuid", "UUIDv7 timestamp is outside the accepted window.");
193
- if (!hasUuidV7Entropy(bytes))
194
- return new UuidSlugError("invalid_uuid", "UUIDv7 random payload is degenerate.");
195
- return uuid;
196
- }
197
-
198
- export function validateUuidV7SlugFresh(
199
- slug: string,
200
- options?: FreshValidationOptions,
201
- ): Error | UuidV7Slug {
202
- const uuid = slugToUuid(slug);
203
- if (uuid instanceof Error) return uuid;
204
- const valid = validateUuidV7Fresh(uuid, options);
205
- return valid instanceof Error ? valid : (slug as UuidV7Slug);
206
- }
207
-
208
- export function validateMaskedUuidV7SlugFresh(
209
- slug: string,
210
- options?: FreshValidationOptions,
211
- ): Error | MaskedUuidV7Slug {
212
- const uuid = defaultCodec.maskedSlugToUuidV7(slug);
213
- if (uuid instanceof Error) return uuid;
214
- const valid = validateUuidV7Fresh(uuid, options);
215
- return valid instanceof Error ? valid : (slug as MaskedUuidV7Slug);
216
- }
217
-
218
- export { isUuidSlug, isUuidString, isUuidV4Slug, isUuidV4String, isUuidV7Slug, isUuidV7String };
@@ -1,20 +0,0 @@
1
- import { UuidRuntimeError } from "../errors";
2
- import type { Runtime } from "./types";
3
-
4
- function cryptoObject(): Crypto {
5
- const value = globalThis.crypto;
6
- if (!value?.getRandomValues)
7
- throw new UuidRuntimeError("Web Crypto getRandomValues is unavailable.");
8
- return value;
9
- }
10
-
11
- export const runtime: Runtime = {
12
- fillRandom(bytes) {
13
- cryptoObject().getRandomValues(bytes);
14
- },
15
- uuidV4() {
16
- const crypto = cryptoObject();
17
- if (!crypto.randomUUID) throw new UuidRuntimeError("Web Crypto randomUUID is unavailable.");
18
- return crypto.randomUUID();
19
- },
20
- };
package/src/schema.ts DELETED
@@ -1,123 +0,0 @@
1
- import { UuidSlugError } from "./errors";
2
- import type { ExplicitMaskSchema, MaskSchema, MaskSchemaOptions } from "./types";
3
-
4
- const LEGACY_PERMUTE = Uint8Array.from([9, 13, 3, 8, 14, 0, 11, 7, 6, 1, 15, 4, 2, 5, 10, 12]);
5
- const LEGACY_XOR = Uint8Array.from([
6
- 0xa2, 0x70, 0x32, 0x7f, 0x98, 0xb8, 0x9b, 0x5e, 0x1b, 0x26, 0xb6, 0x16, 0x96, 0xf9, 0xea, 0x3e,
7
- ]);
8
-
9
- function clone16(bytes: Uint8Array, name: string): Error | Uint8Array {
10
- if (bytes.length !== 16)
11
- return new UuidSlugError("invalid_mask_schema", `${name} must contain exactly 16 bytes.`);
12
- return new Uint8Array(bytes);
13
- }
14
-
15
- function inversePermutation(permute: Uint8Array): Error | Uint8Array {
16
- if (permute.length !== 16)
17
- return new UuidSlugError("invalid_mask_schema", "Permutation must contain exactly 16 bytes.");
18
- const seen = new Uint8Array(16);
19
- const inverse = new Uint8Array(16);
20
- for (let i = 0; i < 16; i += 1) {
21
- const value = permute[i] ?? 255;
22
- if (value > 15 || seen[value] === 1)
23
- return new UuidSlugError(
24
- "invalid_mask_schema",
25
- "Permutation must be a bijection over 0..15.",
26
- );
27
- seen[value] = 1;
28
- inverse[value] = i;
29
- }
30
- return inverse;
31
- }
32
-
33
- function fnv1a64(data: Uint8Array) {
34
- let hash = 0xcbf29ce484222325n;
35
- for (const byte of data) {
36
- hash ^= BigInt(byte);
37
- hash = BigInt.asUintN(64, hash * 0x100000001b3n);
38
- }
39
- return hash;
40
- }
41
-
42
- function seedBytes(seed: string | Uint8Array) {
43
- if (typeof seed !== "string") return new Uint8Array(seed);
44
- return new TextEncoder().encode(seed);
45
- }
46
-
47
- function next64(state: { value: bigint }) {
48
- state.value ^= state.value << 13n;
49
- state.value ^= state.value >> 7n;
50
- state.value ^= state.value << 17n;
51
- state.value = BigInt.asUintN(64, state.value);
52
- return state.value;
53
- }
54
-
55
- function derivedBytes(seed: Uint8Array, purpose: number, length: number) {
56
- const state = {
57
- value: fnv1a64(Uint8Array.from([...seed, purpose])) || 0x9e3779b97f4a7c15n,
58
- };
59
- const out = new Uint8Array(length);
60
- for (let i = 0; i < length; i += 1)
61
- out[i] = Number((next64(state) >> BigInt((i % 8) * 8)) & 0xffn);
62
- return out;
63
- }
64
-
65
- function derivedPermutation(seed: Uint8Array) {
66
- const random = derivedBytes(seed, 2, 64);
67
- const permute = Uint8Array.from({ length: 16 }, (_, i) => i);
68
- let cursor = 0;
69
- for (let i = 15; i > 0; i -= 1) {
70
- const j = (random[cursor] ?? 0) % (i + 1);
71
- cursor += 1;
72
- const tmp = permute[i] ?? 0;
73
- permute[i] = permute[j] ?? 0;
74
- permute[j] = tmp;
75
- }
76
- return permute;
77
- }
78
-
79
- function completeSchema(
80
- id: string,
81
- xorInput: Uint8Array,
82
- permuteInput: Uint8Array,
83
- tagBits: 4 | 6,
84
- ): Error | MaskSchema {
85
- const xor = clone16(xorInput, "XOR mask");
86
- if (xor instanceof Error) return xor;
87
- const permute = clone16(permuteInput, "Permutation");
88
- if (permute instanceof Error) return permute;
89
- const inverse = inversePermutation(permute);
90
- if (inverse instanceof Error) return inverse;
91
- return { id, inverse, permute, tagBits, xor };
92
- }
93
-
94
- export const LEGACY_MASK_SCHEMA_V1: MaskSchema = completeSchema(
95
- "legacy-mask-v1",
96
- LEGACY_XOR,
97
- LEGACY_PERMUTE,
98
- 4,
99
- ) as MaskSchema;
100
-
101
- export function defineMaskSchema(schema: ExplicitMaskSchema): Error | MaskSchema {
102
- return completeSchema(schema.id ?? "explicit", schema.xor, schema.permute, schema.tagBits);
103
- }
104
-
105
- export function createMaskSchema(options: MaskSchemaOptions): Error | MaskSchema {
106
- const seed = seedBytes(options.seed);
107
- if (seed.length === 0)
108
- return new UuidSlugError("invalid_mask_schema", "Mask seed must not be empty.");
109
- const tagBits = options.tagBits ?? 6;
110
- if (tagBits !== 4 && tagBits !== 6)
111
- return new UuidSlugError("invalid_mask_schema", "Mask tagBits must be 4 or 6.");
112
- return completeSchema(
113
- options.id ?? "seeded",
114
- derivedBytes(seed, 1, 16),
115
- derivedPermutation(seed),
116
- tagBits,
117
- );
118
- }
119
-
120
- export const DEFAULT_MASK_SCHEMA: MaskSchema = createMaskSchema({
121
- id: "default",
122
- seed: "anizoptera.uuid-slug.default-mask.v1",
123
- }) as MaskSchema;