@anizoptera/uuid-slug 0.2.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.
- package/LICENSE +181 -0
- package/README.md +65 -0
- package/dist/index.d.ts +168 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +649 -0
- package/dist/index.js.map +1 -0
- package/dist/node/index.js +647 -0
- package/dist/web/index.js +648 -0
- package/package.json +68 -0
- package/src/base64url.ts +76 -0
- package/src/codec.ts +218 -0
- package/src/errors.ts +26 -0
- package/src/index.ts +74 -0
- package/src/mask.ts +95 -0
- package/src/runtime/bun.ts +33 -0
- package/src/runtime/node.ts +23 -0
- package/src/runtime/types.ts +12 -0
- package/src/runtime/web.ts +20 -0
- package/src/schema.ts +123 -0
- package/src/types.ts +89 -0
- package/src/uuid.ts +158 -0
- package/src/v7.ts +106 -0
package/package.json
ADDED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@anizoptera/uuid-slug",
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "Zero-dependency UUID v4/v7 generation, direct base64url slugs, and configurable masked UUID slugs.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"base64url",
|
|
7
|
+
"browser",
|
|
8
|
+
"bun",
|
|
9
|
+
"deno",
|
|
10
|
+
"node",
|
|
11
|
+
"slug",
|
|
12
|
+
"uuid",
|
|
13
|
+
"uuidv7",
|
|
14
|
+
"zero-dependencies"
|
|
15
|
+
],
|
|
16
|
+
"homepage": "https://github.com/Anizoptera/uuid-slug#readme",
|
|
17
|
+
"bugs": {
|
|
18
|
+
"url": "https://github.com/Anizoptera/uuid-slug/issues"
|
|
19
|
+
},
|
|
20
|
+
"license": "Apache-2.0",
|
|
21
|
+
"author": "Anizoptera",
|
|
22
|
+
"contributors": [
|
|
23
|
+
"Art Shendrik"
|
|
24
|
+
],
|
|
25
|
+
"repository": {
|
|
26
|
+
"type": "git",
|
|
27
|
+
"url": "git+https://github.com/Anizoptera/uuid-slug.git"
|
|
28
|
+
},
|
|
29
|
+
"files": [
|
|
30
|
+
"dist",
|
|
31
|
+
"src",
|
|
32
|
+
"README.md",
|
|
33
|
+
"LICENSE"
|
|
34
|
+
],
|
|
35
|
+
"type": "module",
|
|
36
|
+
"sideEffects": false,
|
|
37
|
+
"main": "./dist/index.js",
|
|
38
|
+
"module": "./dist/index.js",
|
|
39
|
+
"types": "./dist/index.d.ts",
|
|
40
|
+
"imports": {
|
|
41
|
+
"#runtime": {
|
|
42
|
+
"bun": "./src/runtime/bun.ts",
|
|
43
|
+
"deno": "./src/runtime/web.ts",
|
|
44
|
+
"browser": "./src/runtime/web.ts",
|
|
45
|
+
"node": "./src/runtime/node.ts",
|
|
46
|
+
"default": "./src/runtime/web.ts"
|
|
47
|
+
}
|
|
48
|
+
},
|
|
49
|
+
"exports": {
|
|
50
|
+
".": {
|
|
51
|
+
"types": "./dist/index.d.ts",
|
|
52
|
+
"bun": "./src/index.ts",
|
|
53
|
+
"deno": "./dist/web/index.js",
|
|
54
|
+
"browser": "./dist/web/index.js",
|
|
55
|
+
"node": "./dist/node/index.js",
|
|
56
|
+
"default": "./dist/web/index.js"
|
|
57
|
+
},
|
|
58
|
+
"./package.json": "./package.json"
|
|
59
|
+
},
|
|
60
|
+
"publishConfig": {
|
|
61
|
+
"access": "public",
|
|
62
|
+
"provenance": true
|
|
63
|
+
},
|
|
64
|
+
"dependencies": {},
|
|
65
|
+
"engines": {
|
|
66
|
+
"node": ">=20"
|
|
67
|
+
}
|
|
68
|
+
}
|
package/src/base64url.ts
ADDED
|
@@ -0,0 +1,76 @@
|
|
|
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
ADDED
|
@@ -0,0 +1,218 @@
|
|
|
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 };
|
package/src/errors.ts
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
export type UuidSlugErrorCode =
|
|
2
|
+
| "invalid_base64url"
|
|
3
|
+
| "invalid_buffer"
|
|
4
|
+
| "invalid_mask_schema"
|
|
5
|
+
| "invalid_uuid"
|
|
6
|
+
| "invalid_uuid_slug"
|
|
7
|
+
| "invalid_uuid_version"
|
|
8
|
+
| "rng_unavailable"
|
|
9
|
+
| "stale_uuid";
|
|
10
|
+
|
|
11
|
+
export class UuidSlugError extends Error {
|
|
12
|
+
readonly code: UuidSlugErrorCode;
|
|
13
|
+
|
|
14
|
+
constructor(code: UuidSlugErrorCode, message: string, options?: ErrorOptions) {
|
|
15
|
+
super(message, options);
|
|
16
|
+
this.name = "UuidSlugError";
|
|
17
|
+
this.code = code;
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
export class UuidRuntimeError extends UuidSlugError {
|
|
22
|
+
constructor(message: string, options?: ErrorOptions) {
|
|
23
|
+
super("rng_unavailable", message, options);
|
|
24
|
+
this.name = "UuidRuntimeError";
|
|
25
|
+
}
|
|
26
|
+
}
|
package/src/index.ts
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
export { decodeBase64Url, encodeBase64Url, isBase64Url } from "./base64url";
|
|
2
|
+
export {
|
|
3
|
+
UUID_V7_SENTINEL_DEFINITIONS,
|
|
4
|
+
createUuidSlugCodec,
|
|
5
|
+
defaultCodec,
|
|
6
|
+
validateMaskedUuidV7SlugFresh,
|
|
7
|
+
validateUuidV7Fresh,
|
|
8
|
+
validateUuidV7SlugFresh,
|
|
9
|
+
} from "./codec";
|
|
10
|
+
export { UuidRuntimeError, UuidSlugError } from "./errors";
|
|
11
|
+
export {
|
|
12
|
+
DEFAULT_MASK_SCHEMA,
|
|
13
|
+
LEGACY_MASK_SCHEMA_V1,
|
|
14
|
+
createMaskSchema,
|
|
15
|
+
defineMaskSchema,
|
|
16
|
+
} from "./schema";
|
|
17
|
+
export type {
|
|
18
|
+
Base64UrlString,
|
|
19
|
+
ExplicitMaskSchema,
|
|
20
|
+
FreshValidationOptions,
|
|
21
|
+
MaskSchema,
|
|
22
|
+
MaskSchemaOptions,
|
|
23
|
+
MaskedUuidSlug,
|
|
24
|
+
MaskedUuidV7Slug,
|
|
25
|
+
PublicUuidV7Slug,
|
|
26
|
+
SentinelUuidV7Slug,
|
|
27
|
+
UuidBytes,
|
|
28
|
+
UuidSlug,
|
|
29
|
+
UuidSlugCodec,
|
|
30
|
+
UuidSlugCodecOptions,
|
|
31
|
+
UuidString,
|
|
32
|
+
UuidV4Slug,
|
|
33
|
+
UuidV4String,
|
|
34
|
+
UuidV7Generator,
|
|
35
|
+
UuidV7Sentinel,
|
|
36
|
+
UuidV7SentinelDefinition,
|
|
37
|
+
UuidV7Slug,
|
|
38
|
+
UuidV7String,
|
|
39
|
+
} from "./types";
|
|
40
|
+
export {
|
|
41
|
+
extractUuidV7Timestamp,
|
|
42
|
+
formatUuid,
|
|
43
|
+
formatUuidSlug,
|
|
44
|
+
hasUuidV7Entropy,
|
|
45
|
+
isUuidSlug,
|
|
46
|
+
isUuidV4Slug,
|
|
47
|
+
isUuidV4String,
|
|
48
|
+
isUuidV7Bytes,
|
|
49
|
+
isUuidV7Slug,
|
|
50
|
+
isUuidV7String,
|
|
51
|
+
isUuidString,
|
|
52
|
+
parseUuid,
|
|
53
|
+
parseUuidSlug,
|
|
54
|
+
slugToUuid,
|
|
55
|
+
slugToUuidBytes,
|
|
56
|
+
uuidBytesToSlug,
|
|
57
|
+
uuidToSlug,
|
|
58
|
+
} from "./uuid";
|
|
59
|
+
export { createRuntimeGenerator, createUuidV7Generator } from "./v7";
|
|
60
|
+
|
|
61
|
+
import { defaultCodec } from "./codec";
|
|
62
|
+
|
|
63
|
+
export const uuidV4 = defaultCodec.uuidV4;
|
|
64
|
+
export const uuidV7 = defaultCodec.uuidV7;
|
|
65
|
+
export const uuidV4Bytes = defaultCodec.uuidV4Bytes;
|
|
66
|
+
export const uuidV7Bytes = defaultCodec.uuidV7Bytes;
|
|
67
|
+
export const uuidV4Slug = defaultCodec.uuidV4Slug;
|
|
68
|
+
export const uuidV7Slug = defaultCodec.uuidV7Slug;
|
|
69
|
+
export const uuidV7MaskedSlug = defaultCodec.uuidV7MaskedSlug;
|
|
70
|
+
export const uuidToMaskedSlug = defaultCodec.uuidToMaskedSlug;
|
|
71
|
+
export const maskedSlugToUuid = defaultCodec.maskedSlugToUuid;
|
|
72
|
+
export const uuidV7ToMaskedSlug = defaultCodec.uuidV7ToMaskedSlug;
|
|
73
|
+
export const maskedSlugToUuidV7 = defaultCodec.maskedSlugToUuidV7;
|
|
74
|
+
export const UUID_V7_SENTINELS = defaultCodec.sentinels;
|
package/src/mask.ts
ADDED
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
import { UuidSlugError } from "./errors";
|
|
2
|
+
import {
|
|
3
|
+
formatUuid,
|
|
4
|
+
isRfcVariant,
|
|
5
|
+
parseUuid,
|
|
6
|
+
slugToUuidBytes,
|
|
7
|
+
uuidBytesToSlug,
|
|
8
|
+
uuidVersion,
|
|
9
|
+
} from "./uuid";
|
|
10
|
+
import type {
|
|
11
|
+
MaskSchema,
|
|
12
|
+
MaskedUuidSlug,
|
|
13
|
+
MaskedUuidV7Slug,
|
|
14
|
+
UuidString,
|
|
15
|
+
UuidV7String,
|
|
16
|
+
} from "./types";
|
|
17
|
+
|
|
18
|
+
function checksum4(bytes: Uint8Array): number {
|
|
19
|
+
let acc = 0;
|
|
20
|
+
for (const byte of bytes) acc ^= byte;
|
|
21
|
+
return (acc >>> 4) ^ (acc & 0x0f);
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
function checksum6(bytes: Uint8Array): number {
|
|
25
|
+
let acc = 0;
|
|
26
|
+
for (let i = 0; i < bytes.length; i += 1) acc = (acc + (bytes[i] ?? 0) * (i + 17)) & 0xff;
|
|
27
|
+
return ((acc >>> 2) ^ acc) & 0x3f;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
function tagFor(bytes: Uint8Array, tagBits: 4 | 6) {
|
|
31
|
+
return tagBits === 4 ? checksum4(bytes) : checksum6(bytes);
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
function injectTag(bytes: Uint8Array, tag: number, tagBits: 4 | 6) {
|
|
35
|
+
bytes[6] = ((tag & 0x0f) << 4) | ((bytes[6] ?? 0) & 0x0f);
|
|
36
|
+
if (tagBits === 6) bytes[8] = ((tag & 0x30) << 2) | ((bytes[8] ?? 0) & 0x3f);
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
function extractTag(bytes: Uint8Array, tagBits: 4 | 6) {
|
|
40
|
+
const versionBits = (bytes[6] ?? 0) >>> 4;
|
|
41
|
+
if (tagBits === 4) return versionBits;
|
|
42
|
+
return versionBits | (((bytes[8] ?? 0) >>> 6) << 4);
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
function restoreV7(bytes: Uint8Array, tagBits: 4 | 6) {
|
|
46
|
+
bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x70;
|
|
47
|
+
if (tagBits === 6) bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
export function uuidToMaskedSlugWithSchema(
|
|
51
|
+
uuid: string,
|
|
52
|
+
schema: MaskSchema,
|
|
53
|
+
): Error | MaskedUuidSlug {
|
|
54
|
+
const raw = parseUuid(uuid);
|
|
55
|
+
if (raw instanceof Error) return raw;
|
|
56
|
+
if (uuidVersion(raw) !== 7 || !isRfcVariant(raw))
|
|
57
|
+
return new UuidSlugError("invalid_uuid_version", "Masked UUID slugs currently require UUIDv7.");
|
|
58
|
+
return uuidV7BytesToMaskedSlug(raw, schema);
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
export function uuidV7BytesToMaskedSlug(
|
|
62
|
+
raw: Uint8Array,
|
|
63
|
+
schema: MaskSchema,
|
|
64
|
+
): Error | MaskedUuidV7Slug {
|
|
65
|
+
const tagged = new Uint8Array(raw);
|
|
66
|
+
injectTag(tagged, tagFor(raw, schema.tagBits), schema.tagBits);
|
|
67
|
+
const mixed = new Uint8Array(16);
|
|
68
|
+
for (let i = 0; i < 16; i += 1)
|
|
69
|
+
mixed[i] = (tagged[schema.permute[i] ?? 0] ?? 0) ^ (schema.xor[i] ?? 0);
|
|
70
|
+
const slug = uuidBytesToSlug(mixed);
|
|
71
|
+
return slug instanceof Error ? slug : (slug as MaskedUuidV7Slug);
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
export function maskedSlugToUuidWithSchema(slug: string, schema: MaskSchema): Error | UuidString {
|
|
75
|
+
const mixed = slugToUuidBytes(slug);
|
|
76
|
+
if (mixed instanceof Error) return mixed;
|
|
77
|
+
const unmixed = new Uint8Array(16);
|
|
78
|
+
for (let i = 0; i < 16; i += 1) {
|
|
79
|
+
const source = schema.inverse[i] ?? 0;
|
|
80
|
+
unmixed[i] = (mixed[source] ?? 0) ^ (schema.xor[source] ?? 0);
|
|
81
|
+
}
|
|
82
|
+
const foundTag = extractTag(unmixed, schema.tagBits);
|
|
83
|
+
restoreV7(unmixed, schema.tagBits);
|
|
84
|
+
if (tagFor(unmixed, schema.tagBits) !== foundTag)
|
|
85
|
+
return new UuidSlugError("invalid_uuid_slug", "Masked UUID slug failed schema validation.");
|
|
86
|
+
return formatUuid(unmixed);
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
export function maskedSlugToUuidV7WithSchema(
|
|
90
|
+
slug: string,
|
|
91
|
+
schema: MaskSchema,
|
|
92
|
+
): Error | UuidV7String {
|
|
93
|
+
const uuid = maskedSlugToUuidWithSchema(slug, schema);
|
|
94
|
+
return uuid instanceof Error ? uuid : (uuid as UuidV7String);
|
|
95
|
+
}
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import { UuidRuntimeError } from "../errors";
|
|
2
|
+
import { runtime as webRuntime } from "./web";
|
|
3
|
+
import type { Runtime } from "./types";
|
|
4
|
+
|
|
5
|
+
type BunUuid = {
|
|
6
|
+
randomUUIDv7(format?: "base64url" | "buffer" | "hex"): string | Uint8Array;
|
|
7
|
+
};
|
|
8
|
+
|
|
9
|
+
function bunObject(): BunUuid {
|
|
10
|
+
const candidate = globalThis as typeof globalThis & { Bun?: BunUuid };
|
|
11
|
+
if (!candidate.Bun?.randomUUIDv7) throw new UuidRuntimeError("Bun.randomUUIDv7 is unavailable.");
|
|
12
|
+
return candidate.Bun;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
const bunRuntime: Runtime = {
|
|
16
|
+
fillRandom: webRuntime.fillRandom,
|
|
17
|
+
uuidV7() {
|
|
18
|
+
return bunObject().randomUUIDv7("hex") as string;
|
|
19
|
+
},
|
|
20
|
+
uuidV7Bytes(out?: Uint8Array, offset = 0) {
|
|
21
|
+
const bytes = bunObject().randomUUIDv7("buffer") as Uint8Array;
|
|
22
|
+
if (!out) return bytes;
|
|
23
|
+
out.set(bytes, offset);
|
|
24
|
+
return out;
|
|
25
|
+
},
|
|
26
|
+
uuidV7Slug() {
|
|
27
|
+
return bunObject().randomUUIDv7("base64url") as string;
|
|
28
|
+
},
|
|
29
|
+
};
|
|
30
|
+
|
|
31
|
+
if (webRuntime.uuidV4) bunRuntime.uuidV4 = webRuntime.uuidV4;
|
|
32
|
+
|
|
33
|
+
export const runtime = bunRuntime;
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import crypto from "node:crypto";
|
|
2
|
+
import { UuidRuntimeError } from "../errors";
|
|
3
|
+
import type { Runtime } from "./types";
|
|
4
|
+
|
|
5
|
+
type NodeCryptoWithV7 = {
|
|
6
|
+
randomUUIDv7?: () => string;
|
|
7
|
+
};
|
|
8
|
+
|
|
9
|
+
const cryptoWithV7 = crypto as typeof crypto & NodeCryptoWithV7;
|
|
10
|
+
|
|
11
|
+
export const runtime: Runtime = {
|
|
12
|
+
fillRandom(bytes) {
|
|
13
|
+
bytes.set(crypto.randomBytes(bytes.length));
|
|
14
|
+
},
|
|
15
|
+
uuidV4() {
|
|
16
|
+
return crypto.randomUUID();
|
|
17
|
+
},
|
|
18
|
+
uuidV7() {
|
|
19
|
+
if (!cryptoWithV7.randomUUIDv7)
|
|
20
|
+
throw new UuidRuntimeError("Node crypto.randomUUIDv7 is unavailable.");
|
|
21
|
+
return cryptoWithV7.randomUUIDv7();
|
|
22
|
+
},
|
|
23
|
+
};
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
export interface Runtime {
|
|
2
|
+
/**
|
|
3
|
+
* The buffer is pinned to a plain `ArrayBuffer` because Web Crypto's `getRandomValues`
|
|
4
|
+
* rejects a `SharedArrayBuffer` view at runtime, and the unparameterised `Uint8Array`
|
|
5
|
+
* admits one. Narrowing here makes that refusal unrepresentable instead of a throw.
|
|
6
|
+
*/
|
|
7
|
+
fillRandom(bytes: Uint8Array<ArrayBuffer>): void;
|
|
8
|
+
uuidV4?(): string;
|
|
9
|
+
uuidV7?(): string;
|
|
10
|
+
uuidV7Bytes?(out?: Uint8Array, offset?: number): Uint8Array;
|
|
11
|
+
uuidV7Slug?(): string;
|
|
12
|
+
}
|
|
@@ -0,0 +1,20 @@
|
|
|
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
|
+
};
|