@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.
- package/LICENSE +54 -31
- package/README.md +1175 -30
- package/dist/alphabet.d.ts +9 -0
- package/dist/alphabet.d.ts.map +1 -0
- package/dist/alphabet.js +166 -0
- package/dist/alphabet.js.map +1 -0
- package/dist/base64url-name.d.ts +7 -0
- package/dist/base64url-name.d.ts.map +1 -0
- package/dist/base64url-name.js +8 -0
- package/dist/base64url-name.js.map +1 -0
- package/dist/errors.d.ts +57 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +162 -0
- package/dist/errors.js.map +1 -0
- package/dist/feistel.js +39 -0
- package/dist/feistel.js.map +1 -0
- package/dist/generation-options.js +20 -0
- package/dist/generation-options.js.map +1 -0
- package/dist/index.d.ts +23 -168
- package/dist/index.js +22 -649
- package/dist/instant.js +83 -0
- package/dist/instant.js.map +1 -0
- package/dist/mask-handle.d.ts +16 -0
- package/dist/mask-handle.d.ts.map +1 -0
- package/dist/mask-handle.js +60 -0
- package/dist/mask-handle.js.map +1 -0
- package/dist/mask.d.ts +27 -0
- package/dist/mask.d.ts.map +1 -0
- package/dist/mask.js +164 -0
- package/dist/mask.js.map +1 -0
- package/dist/masking-codec-protocol.js +23 -0
- package/dist/masking-codec-protocol.js.map +1 -0
- package/dist/masking-codec-types.d.ts +245 -0
- package/dist/masking-codec-types.d.ts.map +1 -0
- package/dist/masking-codec.d.ts +19 -0
- package/dist/masking-codec.d.ts.map +1 -0
- package/dist/masking-codec.js +391 -0
- package/dist/masking-codec.js.map +1 -0
- package/dist/migration.js +129 -0
- package/dist/migration.js.map +1 -0
- package/dist/node/runtime.js +39 -0
- package/dist/node/runtime.js.map +1 -0
- package/dist/payload.d.ts +7 -0
- package/dist/payload.d.ts.map +1 -0
- package/dist/payload.js +118 -0
- package/dist/payload.js.map +1 -0
- package/dist/runtime/pool.js +30 -0
- package/dist/runtime/pool.js.map +1 -0
- package/dist/runtime/portable.js +27 -0
- package/dist/runtime/portable.js.map +1 -0
- package/dist/sentinel.js +10 -0
- package/dist/sentinel.js.map +1 -0
- package/dist/siphash.js +29 -0
- package/dist/siphash.js.map +1 -0
- package/dist/slug.d.ts +169 -0
- package/dist/slug.d.ts.map +1 -0
- package/dist/slug.js +268 -0
- package/dist/slug.js.map +1 -0
- package/dist/timestamp.d.ts +19 -0
- package/dist/timestamp.d.ts.map +1 -0
- package/dist/timestamp.js +44 -0
- package/dist/timestamp.js.map +1 -0
- package/dist/types.d.ts +535 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +8 -0
- package/dist/types.js.map +1 -0
- package/dist/uuid-value-protocol.js +46 -0
- package/dist/uuid-value-protocol.js.map +1 -0
- package/dist/uuid-value.d.ts +17 -0
- package/dist/uuid-value.d.ts.map +1 -0
- package/dist/uuid-value.js +127 -0
- package/dist/uuid-value.js.map +1 -0
- package/dist/uuid.d.ts +65 -0
- package/dist/uuid.d.ts.map +1 -0
- package/dist/uuid.js +232 -0
- package/dist/uuid.js.map +1 -0
- package/dist/v4-slug.d.ts +16 -0
- package/dist/v4-slug.d.ts.map +1 -0
- package/dist/v4-slug.js +16 -0
- package/dist/v4-slug.js.map +1 -0
- package/dist/v4.d.ts +42 -0
- package/dist/v4.d.ts.map +1 -0
- package/dist/v4.js +85 -0
- package/dist/v4.js.map +1 -0
- package/dist/v7-bounds.d.ts +36 -0
- package/dist/v7-bounds.d.ts.map +1 -0
- package/dist/v7-bounds.js +49 -0
- package/dist/v7-bounds.js.map +1 -0
- package/dist/v7-generator-input.js +75 -0
- package/dist/v7-generator-input.js.map +1 -0
- package/dist/v7-generator.d.ts +43 -0
- package/dist/v7-generator.d.ts.map +1 -0
- package/dist/v7-generator.js +105 -0
- package/dist/v7-generator.js.map +1 -0
- package/dist/v7-keyless.d.ts +46 -0
- package/dist/v7-keyless.d.ts.map +1 -0
- package/dist/v7-keyless.js +106 -0
- package/dist/v7-keyless.js.map +1 -0
- package/dist/v7-payload.js +54 -0
- package/dist/v7-payload.js.map +1 -0
- package/dist/v7-slug.d.ts +46 -0
- package/dist/v7-slug.d.ts.map +1 -0
- package/dist/v7-slug.js +127 -0
- package/dist/v7-slug.js.map +1 -0
- package/dist/v7-timestamp.js +9 -0
- package/dist/v7-timestamp.js.map +1 -0
- package/dist/v7-value-options.js +28 -0
- package/dist/v7-value-options.js.map +1 -0
- package/dist/v7-value.d.ts +23 -0
- package/dist/v7-value.d.ts.map +1 -0
- package/dist/v7-value.js +31 -0
- package/dist/v7-value.js.map +1 -0
- package/dist/v7.js +143 -0
- package/dist/v7.js.map +1 -0
- package/package.json +18 -17
- package/src/alphabet.ts +616 -0
- package/src/base64url-name.ts +5 -0
- package/src/errors.ts +423 -13
- package/src/feistel.ts +141 -0
- package/src/generation-options.ts +48 -0
- package/src/index.ts +137 -57
- package/src/instant.ts +196 -0
- package/src/keyless.ts +9 -0
- package/src/mask-handle.ts +141 -0
- package/src/mask.ts +377 -90
- package/src/masking-codec-protocol.ts +29 -0
- package/src/masking-codec-types.ts +380 -0
- package/src/masking-codec.ts +923 -0
- package/src/migration.ts +257 -0
- package/src/payload.ts +321 -0
- package/src/runtime/bun.ts +31 -25
- package/src/runtime/node.ts +55 -18
- package/src/runtime/pool.ts +90 -0
- package/src/runtime/portable.ts +68 -0
- package/src/runtime/types.ts +30 -5
- package/src/sentinel.ts +13 -0
- package/src/siphash.ts +128 -0
- package/src/slug.ts +884 -0
- package/src/timestamp.ts +122 -0
- package/src/types.ts +799 -61
- package/src/uuid-value-protocol.ts +77 -0
- package/src/uuid-value.ts +341 -0
- package/src/uuid.ts +527 -108
- package/src/v4-slug.ts +27 -0
- package/src/v4.ts +234 -0
- package/src/v7-bounds.ts +171 -0
- package/src/v7-generator-input.ts +169 -0
- package/src/v7-generator.ts +245 -0
- package/src/v7-keyless.ts +354 -0
- package/src/v7-payload.ts +121 -0
- package/src/v7-slug.ts +293 -0
- package/src/v7-timestamp.ts +21 -0
- package/src/v7-value-options.ts +62 -0
- package/src/v7-value.ts +54 -0
- package/src/v7.ts +433 -84
- package/dist/index.d.ts.map +0 -1
- package/dist/index.js.map +0 -1
- package/dist/node/index.js +0 -647
- package/dist/web/index.js +0 -648
- package/src/base64url.ts +0 -76
- package/src/codec.ts +0 -218
- package/src/runtime/web.ts +0 -20
- package/src/schema.ts +0 -123
package/src/errors.ts
CHANGED
|
@@ -1,26 +1,436 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
|
|
3
|
+
/** The operation was cancelled through its `AbortSignal`. */
|
|
4
|
+
export const ABORTED = "aborted";
|
|
5
|
+
/** The input is not a canonical base32hex UUID slug. */
|
|
6
|
+
export const INVALID_BASE32HEX = "invalid_base32hex";
|
|
7
|
+
/** The input is not a canonical base64url UUID slug. */
|
|
8
|
+
export const INVALID_BASE64URL = "invalid_base64url";
|
|
9
|
+
/** A byte buffer or offset cannot satisfy the requested operation. */
|
|
10
|
+
export const INVALID_BUFFER = "invalid_buffer";
|
|
11
|
+
/** A mask is missing, malformed, or failed its reversible transform. */
|
|
12
|
+
export const INVALID_MASK = "invalid_mask";
|
|
13
|
+
/** An options object or one of its values is invalid. */
|
|
14
|
+
export const INVALID_OPTIONS = "invalid_options";
|
|
15
|
+
/** A sentinel definition is invalid or conflicts with another sentinel. */
|
|
16
|
+
export const INVALID_SENTINEL = "invalid_sentinel";
|
|
17
|
+
/** A timestamp is invalid or outside the selected operation's range. */
|
|
18
|
+
export const INVALID_TIMESTAMP = "invalid_timestamp";
|
|
19
|
+
/** The input is not valid UUID text or a valid UUID byte payload. */
|
|
20
|
+
export const INVALID_UUID = "invalid_uuid";
|
|
21
|
+
/** The input is not a canonical plain or codec-owned UUID slug. */
|
|
22
|
+
export const INVALID_UUID_SLUG = "invalid_uuid_slug";
|
|
23
|
+
/** The UUID version does not satisfy the requested operation. */
|
|
24
|
+
export const INVALID_UUID_VERSION = "invalid_uuid_version";
|
|
25
|
+
/** The runtime could not provide cryptographically secure random bytes. */
|
|
26
|
+
export const RNG_UNAVAILABLE = "rng_unavailable";
|
|
27
|
+
/** The UUIDv7 timestamp falls outside the caller's validation window. */
|
|
28
|
+
export const TIMESTAMP_OUTSIDE_WINDOW = "timestamp_outside_window";
|
|
29
|
+
|
|
30
|
+
/** One stable `UuidSlugError.code`; branch on this value and use `message` for diagnostics. */
|
|
1
31
|
export type UuidSlugErrorCode =
|
|
2
|
-
|
|
|
3
|
-
|
|
|
4
|
-
|
|
|
5
|
-
|
|
|
6
|
-
|
|
|
7
|
-
|
|
|
8
|
-
|
|
|
9
|
-
|
|
|
32
|
+
| typeof ABORTED
|
|
33
|
+
| typeof INVALID_BASE32HEX
|
|
34
|
+
| typeof INVALID_BASE64URL
|
|
35
|
+
| typeof INVALID_BUFFER
|
|
36
|
+
| typeof INVALID_MASK
|
|
37
|
+
| typeof INVALID_OPTIONS
|
|
38
|
+
| typeof INVALID_SENTINEL
|
|
39
|
+
| typeof INVALID_TIMESTAMP
|
|
40
|
+
| typeof INVALID_UUID
|
|
41
|
+
| typeof INVALID_UUID_SLUG
|
|
42
|
+
| typeof INVALID_UUID_VERSION
|
|
43
|
+
| typeof RNG_UNAVAILABLE
|
|
44
|
+
| typeof TIMESTAMP_OUTSIDE_WINDOW;
|
|
45
|
+
|
|
46
|
+
export const ERROR_CODES: readonly UuidSlugErrorCode[] = /*#__PURE__*/ Object.freeze([
|
|
47
|
+
ABORTED,
|
|
48
|
+
INVALID_BASE32HEX,
|
|
49
|
+
INVALID_BASE64URL,
|
|
50
|
+
INVALID_BUFFER,
|
|
51
|
+
INVALID_MASK,
|
|
52
|
+
INVALID_OPTIONS,
|
|
53
|
+
INVALID_SENTINEL,
|
|
54
|
+
INVALID_TIMESTAMP,
|
|
55
|
+
INVALID_UUID,
|
|
56
|
+
INVALID_UUID_SLUG,
|
|
57
|
+
INVALID_UUID_VERSION,
|
|
58
|
+
RNG_UNAVAILABLE,
|
|
59
|
+
TIMESTAMP_OUTSIDE_WINDOW,
|
|
60
|
+
]);
|
|
61
|
+
|
|
62
|
+
const ERROR_CODE_SET: ReadonlySet<unknown> = /*#__PURE__*/ new Set(ERROR_CODES);
|
|
63
|
+
const ERROR_NAME = "UuidSlugError";
|
|
64
|
+
// Internal consumers share the protocol key without exporting it from the package root.
|
|
65
|
+
export const ERROR_MARKER = "__failure";
|
|
66
|
+
const OBJECT_TYPE = "object";
|
|
67
|
+
const ERROR_TAG = "[object Error]";
|
|
68
|
+
const ARRAY_BUFFER_TAG = "[object ArrayBuffer]";
|
|
69
|
+
const DATA_VIEW_TAG = "[object DataView]";
|
|
70
|
+
const BYTE_LENGTH_PROPERTY = "byteLength";
|
|
71
|
+
const BUFFER_TYPE_MESSAGE = "Buffer must be a Uint8Array.";
|
|
72
|
+
const RANDOM_FAILURE_MESSAGE = "Random byte generation failed.";
|
|
73
|
+
const nativeIsError = (Error as { isError?: (value: unknown) => boolean }).isError;
|
|
10
74
|
|
|
75
|
+
const typedArrayTagDescriptor = /*#__PURE__*/ Object.getOwnPropertyDescriptor(
|
|
76
|
+
Object.getPrototypeOf(Uint8Array.prototype) as object,
|
|
77
|
+
Symbol.toStringTag,
|
|
78
|
+
);
|
|
79
|
+
const dataViewByteLengthDescriptor = /*#__PURE__*/ Object.getOwnPropertyDescriptor(
|
|
80
|
+
DataView.prototype,
|
|
81
|
+
BYTE_LENGTH_PROPERTY,
|
|
82
|
+
);
|
|
83
|
+
const dataViewByteOffsetDescriptor = /*#__PURE__*/ Object.getOwnPropertyDescriptor(
|
|
84
|
+
DataView.prototype,
|
|
85
|
+
"byteOffset",
|
|
86
|
+
);
|
|
87
|
+
const dataViewBufferDescriptor = /*#__PURE__*/ Object.getOwnPropertyDescriptor(
|
|
88
|
+
DataView.prototype,
|
|
89
|
+
"buffer",
|
|
90
|
+
);
|
|
91
|
+
const arrayBufferByteLengthDescriptor = /*#__PURE__*/ Object.getOwnPropertyDescriptor(
|
|
92
|
+
ArrayBuffer.prototype,
|
|
93
|
+
BYTE_LENGTH_PROPERTY,
|
|
94
|
+
);
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* An expected failure returned by package operations. Branch on `code`; `message` explains the
|
|
98
|
+
* failed input or operation, and `cause` retains an underlying runtime or callback failure.
|
|
99
|
+
*/
|
|
11
100
|
export class UuidSlugError extends Error {
|
|
101
|
+
/** Stable cross-realm marker used by `isUuidSlugError` and composable package operations. */
|
|
102
|
+
declare readonly __failure: true;
|
|
103
|
+
/** Stable recovery category; use `message` and `cause` for diagnostics. */
|
|
12
104
|
readonly code: UuidSlugErrorCode;
|
|
13
105
|
|
|
106
|
+
/**
|
|
107
|
+
* Create an expected package error.
|
|
108
|
+
*
|
|
109
|
+
* @param code - Stable recovery category.
|
|
110
|
+
* @param message - Input- or operation-specific diagnostic.
|
|
111
|
+
* @param options - Standard error options; use `cause` to retain the underlying failure.
|
|
112
|
+
*/
|
|
14
113
|
constructor(code: UuidSlugErrorCode, message: string, options?: ErrorOptions) {
|
|
15
114
|
super(message, options);
|
|
16
|
-
this.name =
|
|
115
|
+
this.name = ERROR_NAME;
|
|
17
116
|
this.code = code;
|
|
18
117
|
}
|
|
19
118
|
}
|
|
20
119
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
120
|
+
// One immutable prototype property avoids adding storage to every error while preserving the same
|
|
121
|
+
// marker across realms and duplicate package copies. Remeasure if supported engines change their
|
|
122
|
+
// prototype-property access or Error layout; benchmark evidence belongs in bench/PERFORMANCE.md.
|
|
123
|
+
Object.defineProperty(UuidSlugError.prototype, ERROR_MARKER, { value: true });
|
|
124
|
+
|
|
125
|
+
// Keep local identity before the costlier cross-realm capability, but isolate the probes: a proxy
|
|
126
|
+
// that blocks one operation must not suppress a later independent one. Remeasure if Error branding
|
|
127
|
+
// or inlining changes in a supported engine; results and statistical limits live in PERFORMANCE.md.
|
|
128
|
+
/*#__NO_SIDE_EFFECTS__*/
|
|
129
|
+
function hasErrorBrand(candidate: object): boolean {
|
|
130
|
+
try {
|
|
131
|
+
if (candidate instanceof Error) return true;
|
|
132
|
+
} catch {
|
|
133
|
+
// A proxy may block local identity while a native cross-realm check can still recognize it.
|
|
134
|
+
}
|
|
135
|
+
try {
|
|
136
|
+
return nativeIsError
|
|
137
|
+
? nativeIsError(candidate)
|
|
138
|
+
: Object.prototype.toString.call(candidate) === ERROR_TAG;
|
|
139
|
+
} catch {
|
|
140
|
+
return false;
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/**
|
|
145
|
+
* Narrow a returned value to `UuidSlugError`, including errors from another realm or package copy.
|
|
146
|
+
* The package marker is the primary protocol. Existing unmarked package errors use local Error
|
|
147
|
+
* identity before native or portable cross-realm recognition. This does not authenticate data.
|
|
148
|
+
*/
|
|
149
|
+
/*#__NO_SIDE_EFFECTS__*/
|
|
150
|
+
export function isUuidSlugError(value: unknown): value is UuidSlugError {
|
|
151
|
+
if (typeof value !== OBJECT_TYPE || value === null) return false;
|
|
152
|
+
const candidate = value as object;
|
|
153
|
+
try {
|
|
154
|
+
if ((candidate as { readonly __failure?: unknown })[ERROR_MARKER] === true) return true;
|
|
155
|
+
} catch {
|
|
156
|
+
// A hostile marker does not suppress the independent Error-brand fallback.
|
|
157
|
+
}
|
|
158
|
+
if (!hasErrorBrand(candidate)) return false;
|
|
159
|
+
try {
|
|
160
|
+
return (
|
|
161
|
+
Reflect.get(candidate, "name") === ERROR_NAME &&
|
|
162
|
+
ERROR_CODE_SET.has(Reflect.get(candidate, "code"))
|
|
163
|
+
);
|
|
164
|
+
} catch {
|
|
165
|
+
return false;
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
/**
|
|
170
|
+
* Universal conversions otherwise recognize the same local bytes before and after dispatch. Keep
|
|
171
|
+
* this shortcut exact; views and cross-realm arrays need the general path. Remeasure if dispatch
|
|
172
|
+
* stops repeating byte recognition.
|
|
173
|
+
*/
|
|
174
|
+
/*#__NO_SIDE_EFFECTS__*/
|
|
175
|
+
export function exactLocalUuidBytes(value: unknown): Uint8Array | undefined {
|
|
176
|
+
try {
|
|
177
|
+
return value instanceof Uint8Array && value.length === 16 ? value : undefined;
|
|
178
|
+
} catch {
|
|
179
|
+
return undefined;
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
/** Recognize local Errors first, then use native or portable cross-realm recognition. */
|
|
184
|
+
/*#__NO_SIDE_EFFECTS__*/
|
|
185
|
+
export function isError(value: unknown): value is Error {
|
|
186
|
+
if (typeof value !== OBJECT_TYPE || value === null) return false;
|
|
187
|
+
return hasErrorBrand(value as object);
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
// A slot probe is the only proof of a genuine buffer, but calling one on anything else
|
|
191
|
+
// throws, and building that native TypeError costs three orders of magnitude more than the checks
|
|
192
|
+
// below (bench/PERFORMANCE.md). For buffers, local identity answers the common case without reading
|
|
193
|
+
// the tag at all; the tag then recognizes another realm's value. The tag is caller-visible, so a value
|
|
194
|
+
// carrying its own Symbol.toStringTag still reaches the probe and keeps its acceptance, and that
|
|
195
|
+
// own-property lookup runs only after the tag misses. Only a value whose realm re-tagged the
|
|
196
|
+
// prototype itself is lost, and a tag getter that throws lands in the catch the probe already
|
|
197
|
+
// needed. Every clause is ordered by measured cost; remeasure if a probe stops throwing.
|
|
198
|
+
/*#__NO_SIDE_EFFECTS__*/
|
|
199
|
+
function isTagged(value: unknown, tag: string): boolean {
|
|
200
|
+
return (
|
|
201
|
+
Object.prototype.toString.call(value) === tag ||
|
|
202
|
+
// The literal is required: TypeScript narrows from `typeof x === "object"`, not from a constant.
|
|
203
|
+
(typeof value === "object" && value !== null && Object.hasOwn(value, Symbol.toStringTag))
|
|
204
|
+
);
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/** Read primitive or genuine boxed text without invoking caller-defined coercion hooks. */
|
|
208
|
+
/*#__NO_SIDE_EFFECTS__*/
|
|
209
|
+
export function stringInput(value: unknown): string | undefined {
|
|
210
|
+
if (typeof value === "string") return value;
|
|
211
|
+
if (typeof value !== "object" || value === null) return undefined;
|
|
212
|
+
try {
|
|
213
|
+
// The intrinsic checks the string slot across realms. A tag or prototype precheck can invoke
|
|
214
|
+
// caller getters, reject retagged wrappers, or reenter a conversion using shared scratch.
|
|
215
|
+
return String.prototype.valueOf.call(value);
|
|
216
|
+
} catch {
|
|
217
|
+
return undefined;
|
|
218
|
+
}
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
/** Normalize UUID string input while preserving a preceding package failure. */
|
|
222
|
+
export function normalizeUuidStringInput(value: unknown): string | UuidSlugError {
|
|
223
|
+
if (typeof value === "string") return value;
|
|
224
|
+
return stringInput(value) ?? invalidUuidStringInput(value);
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
/** Normalize slug input while preserving a preceding package failure. */
|
|
228
|
+
export function normalizeUuidSlugInput(value: unknown): string | UuidSlugError {
|
|
229
|
+
if (typeof value === "string") return value;
|
|
230
|
+
return stringInput(value) ?? invalidUuidSlugInput(value);
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
/** Describe rejected values without executing object coercion or inspecting caller properties. */
|
|
234
|
+
export function diagnosticValue(value: unknown): string {
|
|
235
|
+
if (typeof value === "string") return value;
|
|
236
|
+
if (
|
|
237
|
+
typeof value === "number" ||
|
|
238
|
+
typeof value === "bigint" ||
|
|
239
|
+
typeof value === "boolean" ||
|
|
240
|
+
typeof value === "symbol"
|
|
241
|
+
)
|
|
242
|
+
return String(value);
|
|
243
|
+
return value === null ? "null" : typeof value;
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
/** Accept cross-realm and null-prototype records; callers contain proxy failures at their boundary. */
|
|
247
|
+
export function isPlainRecord(value: object): boolean {
|
|
248
|
+
if (Array.isArray(value)) return false;
|
|
249
|
+
const prototype = Object.getPrototypeOf(value);
|
|
250
|
+
return prototype === null || Object.getPrototypeOf(prototype) === null;
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
/** Use fast local identity, then an unspoofable intrinsic brand for cross-realm Uint8Array values. */
|
|
254
|
+
/*#__NO_SIDE_EFFECTS__*/
|
|
255
|
+
export function isUint8Array(value: unknown): value is Uint8Array {
|
|
256
|
+
return (
|
|
257
|
+
ArrayBuffer.isView(value) &&
|
|
258
|
+
(value instanceof Uint8Array || typedArrayTagDescriptor?.get?.call(value) === "Uint8Array")
|
|
259
|
+
);
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
// A validated draw returns Uint8Array or a recognized failure, so a view check is sufficient:
|
|
263
|
+
// unmarked Errors cannot be views, and marked views remain failures. Rechecking the element brand
|
|
264
|
+
// adds work without narrowing this union. Arbitrary public input still needs its owning validator.
|
|
265
|
+
export function isSuccessfulUuidBytes(value: Uint8Array | UuidSlugError): value is Uint8Array {
|
|
266
|
+
if (!ArrayBuffer.isView(value)) return false;
|
|
267
|
+
try {
|
|
268
|
+
return (value as Uint8Array & { readonly __failure?: unknown })[ERROR_MARKER] !== true;
|
|
269
|
+
} catch {
|
|
270
|
+
// A validated view cannot be an unmarked native Error when its marker is inaccessible.
|
|
271
|
+
return true;
|
|
272
|
+
}
|
|
273
|
+
}
|
|
274
|
+
|
|
275
|
+
/** Borrow bytes from supported local or cross-realm input without copying or accepting other views. */
|
|
276
|
+
export function uuidByteView(value: unknown): Uint8Array | undefined {
|
|
277
|
+
if (isUint8Array(value)) return value;
|
|
278
|
+
try {
|
|
279
|
+
if (
|
|
280
|
+
ArrayBuffer.isView(value) &&
|
|
281
|
+
(value instanceof DataView || isTagged(value, DATA_VIEW_TAG)) &&
|
|
282
|
+
dataViewByteLengthDescriptor?.get?.call(value) !== undefined
|
|
283
|
+
) {
|
|
284
|
+
return new Uint8Array(
|
|
285
|
+
dataViewBufferDescriptor?.get?.call(value) as ArrayBuffer,
|
|
286
|
+
dataViewByteOffsetDescriptor?.get?.call(value) as number,
|
|
287
|
+
dataViewByteLengthDescriptor.get.call(value) as number,
|
|
288
|
+
);
|
|
289
|
+
}
|
|
290
|
+
if (
|
|
291
|
+
(value instanceof ArrayBuffer || isTagged(value, ARRAY_BUFFER_TAG)) &&
|
|
292
|
+
arrayBufferByteLengthDescriptor?.get?.call(value) !== undefined
|
|
293
|
+
)
|
|
294
|
+
return new Uint8Array(value as ArrayBuffer);
|
|
295
|
+
} catch {
|
|
296
|
+
// Detached buffers and hostile objects are invalid byte inputs.
|
|
297
|
+
}
|
|
298
|
+
return undefined;
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
/** Return the first unsupported enumerable own string key in a package-owned options object. */
|
|
302
|
+
/*#__NO_SIDE_EFFECTS__*/
|
|
303
|
+
export function findUnknownOption(
|
|
304
|
+
options: object,
|
|
305
|
+
accepted: Readonly<Record<string, true>>,
|
|
306
|
+
): string | undefined {
|
|
307
|
+
for (const option of Object.keys(options)) if (!Object.hasOwn(accepted, option)) return option;
|
|
308
|
+
return undefined;
|
|
309
|
+
}
|
|
310
|
+
|
|
311
|
+
/**
|
|
312
|
+
* The one range check for every entry point that reads or writes a caller's buffer at an offset.
|
|
313
|
+
*
|
|
314
|
+
* `Number.isInteger` is the load-bearing half and the reason this is shared rather than repeated.
|
|
315
|
+
* The obvious spelling — `offset < 0 || offset + need > capacity` — passes a fractional or
|
|
316
|
+
* NaN offset, because both of its comparisons are false for NaN and neither notices `0.5`. What
|
|
317
|
+
* follows is worse than a wrong answer: `bytes[0.5] = x` is not a store, so the write SILENTLY does
|
|
318
|
+
* nothing while the guard reports success, and an id can come back half-written with the caller's
|
|
319
|
+
* stale bytes in the rest of it. A string offset defeats the same test from the other side, by
|
|
320
|
+
* concatenation: `"4" + 16` is `"416"`, which is not greater than any plausible length.
|
|
321
|
+
*
|
|
322
|
+
* Seven near-identical copies of that test existed across this package and not one checked
|
|
323
|
+
* integrality — the copying is why. One copy is what stops the class returning.
|
|
324
|
+
*/
|
|
325
|
+
/*#__NO_SIDE_EFFECTS__*/
|
|
326
|
+
export function checkRange(
|
|
327
|
+
capacity: number,
|
|
328
|
+
offset: number,
|
|
329
|
+
need: number,
|
|
330
|
+
): undefined | UuidSlugError {
|
|
331
|
+
if (!Number.isInteger(offset))
|
|
332
|
+
return new UuidSlugError(
|
|
333
|
+
INVALID_BUFFER,
|
|
334
|
+
`Buffer offset must be a whole number, got ${typeof offset} ${diagnosticValue(offset)}.`,
|
|
335
|
+
);
|
|
336
|
+
if (offset < 0 || offset + need > capacity)
|
|
337
|
+
return new UuidSlugError(
|
|
338
|
+
INVALID_BUFFER,
|
|
339
|
+
`Buffer needs ${need} bytes at offset ${offset}, but holds ${capacity}.`,
|
|
340
|
+
);
|
|
341
|
+
return undefined;
|
|
342
|
+
}
|
|
343
|
+
|
|
344
|
+
/** Reject alien views and objects before range checks can mistake them for byte storage. */
|
|
345
|
+
/*#__NO_SIDE_EFFECTS__*/
|
|
346
|
+
export function checkByteRange(
|
|
347
|
+
bytes: unknown,
|
|
348
|
+
offset: number,
|
|
349
|
+
need: number,
|
|
350
|
+
): undefined | UuidSlugError {
|
|
351
|
+
if (!isUint8Array(bytes)) {
|
|
352
|
+
if (isUuidSlugError(bytes)) return bytes;
|
|
353
|
+
return new UuidSlugError(INVALID_BUFFER, BUFFER_TYPE_MESSAGE);
|
|
354
|
+
}
|
|
355
|
+
return checkRange(bytes.length, offset, need);
|
|
356
|
+
}
|
|
357
|
+
|
|
358
|
+
/** Preserve a preceding failure or reject an untyped value that is not UUID text. */
|
|
359
|
+
/*#__NO_SIDE_EFFECTS__*/
|
|
360
|
+
export function invalidUuidStringInput(value: unknown): UuidSlugError {
|
|
361
|
+
return isUuidSlugError(value) ? value : new UuidSlugError(INVALID_UUID, "UUID must be text.");
|
|
362
|
+
}
|
|
363
|
+
|
|
364
|
+
/** Preserve a preceding failure or reject an untyped value that is not a UUID slug. */
|
|
365
|
+
/*#__NO_SIDE_EFFECTS__*/
|
|
366
|
+
export function invalidUuidSlugInput(value: unknown): UuidSlugError {
|
|
367
|
+
return isUuidSlugError(value)
|
|
368
|
+
? value
|
|
369
|
+
: new UuidSlugError(INVALID_UUID_SLUG, "UUID slug must be a string.");
|
|
370
|
+
}
|
|
371
|
+
|
|
372
|
+
/** Preserve failures from an injected or platform entropy source without changing successful draws. */
|
|
373
|
+
export const randomFailure = /* @__NO_SIDE_EFFECTS__ */ (
|
|
374
|
+
value: unknown,
|
|
375
|
+
): undefined | UuidSlugError => {
|
|
376
|
+
if (value === undefined) return undefined;
|
|
377
|
+
if (isUuidSlugError(value)) return value;
|
|
378
|
+
return isError(value)
|
|
379
|
+
? new UuidSlugError(RNG_UNAVAILABLE, RANDOM_FAILURE_MESSAGE, { cause: value })
|
|
380
|
+
: undefined;
|
|
381
|
+
};
|
|
382
|
+
|
|
383
|
+
export function fillRandomBytes(
|
|
384
|
+
fill: (bytes: Uint8Array<ArrayBuffer>) => unknown,
|
|
385
|
+
bytes: Uint8Array<ArrayBuffer>,
|
|
386
|
+
): undefined | UuidSlugError {
|
|
387
|
+
try {
|
|
388
|
+
return randomFailure(fill(bytes));
|
|
389
|
+
} catch (cause) {
|
|
390
|
+
return new UuidSlugError(RNG_UNAVAILABLE, RANDOM_FAILURE_MESSAGE, { cause });
|
|
391
|
+
}
|
|
392
|
+
}
|
|
393
|
+
|
|
394
|
+
/**
|
|
395
|
+
* Generation whose typed inputs cannot fail declares no error union, so a failure reaching this
|
|
396
|
+
* point is an environment defect such as a missing secure random source and is thrown. Callers
|
|
397
|
+
* with fallible input never route through here; they keep the error value.
|
|
398
|
+
*/
|
|
399
|
+
export function generatedOrThrow<Value>(result: Value | UuidSlugError): Value {
|
|
400
|
+
if (result instanceof Error) throw result;
|
|
401
|
+
return result;
|
|
402
|
+
}
|
|
403
|
+
|
|
404
|
+
/** Keep both failed implementations inspectable when an optional native shortcut also fails. */
|
|
405
|
+
/*#__NO_SIDE_EFFECTS__*/
|
|
406
|
+
export function failedFallback(
|
|
407
|
+
nativeCause: unknown,
|
|
408
|
+
fallback: UuidSlugError,
|
|
409
|
+
message: string,
|
|
410
|
+
): UuidSlugError {
|
|
411
|
+
return new UuidSlugError(fallback.code, fallback.message, {
|
|
412
|
+
cause: new AggregateError([nativeCause, fallback], message),
|
|
413
|
+
});
|
|
414
|
+
}
|
|
415
|
+
|
|
416
|
+
/** Run the portable generator once after native generation failed; dual failures keep both causes. */
|
|
417
|
+
export function portableAfterNative<FallbackArgument>(
|
|
418
|
+
nativeCause: unknown,
|
|
419
|
+
fallback: (argument: FallbackArgument) => string | UuidSlugError,
|
|
420
|
+
fallbackArgument: FallbackArgument,
|
|
421
|
+
operation: string,
|
|
422
|
+
): string | UuidSlugError {
|
|
423
|
+
const result = fallback(fallbackArgument);
|
|
424
|
+
return result instanceof Error
|
|
425
|
+
? failedFallback(nativeCause, result, `Native and portable ${operation} failed.`)
|
|
426
|
+
: result;
|
|
427
|
+
}
|
|
428
|
+
|
|
429
|
+
/** Read once so a failing clock keeps its original cause and successful clocks have one observation. */
|
|
430
|
+
export function readClock(clock: () => number): number | UuidSlugError {
|
|
431
|
+
try {
|
|
432
|
+
return clock();
|
|
433
|
+
} catch (cause) {
|
|
434
|
+
return new UuidSlugError(INVALID_TIMESTAMP, "Clock reading failed.", { cause });
|
|
25
435
|
}
|
|
26
436
|
}
|
package/src/feistel.ts
ADDED
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* A four-round Feistel network gives masking an exact inverse while spreading each UUID change
|
|
5
|
+
* across the block. HalfSipHash-2-4 supplies the keyed round function. This is reversible
|
|
6
|
+
* obfuscation, not authenticated encryption; `docs/design.md` defines the security boundary.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* Round count. Wire-format-bearing: changing it changes every masked slug this package has ever
|
|
11
|
+
* issued, so it moves only alongside a deliberate format change.
|
|
12
|
+
*/
|
|
13
|
+
const ROUNDS = 4;
|
|
14
|
+
|
|
15
|
+
/** Two 32-bit round keys per round, consumed as one flat array to keep the hot loop indexed. */
|
|
16
|
+
export const FEISTEL_KEY_WORDS = ROUNDS * 2;
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* The `lowbias32` finalizer: an integer hash with near-ideal avalanche for its size. No longer the
|
|
20
|
+
* round function — see above — but still what `mask.ts` derives its check tag with, where the input
|
|
21
|
+
* is public and an unkeyed mixer is the right tool.
|
|
22
|
+
*/
|
|
23
|
+
/*#__NO_SIDE_EFFECTS__*/
|
|
24
|
+
export function mix32(value: number): number {
|
|
25
|
+
let x = (value ^ (value >>> 16)) >>> 0;
|
|
26
|
+
x = Math.imul(x, 0x7feb352d);
|
|
27
|
+
x = (x ^ (x >>> 15)) >>> 0;
|
|
28
|
+
x = Math.imul(x, 0x846ca68b);
|
|
29
|
+
return (x ^ (x >>> 16)) >>> 0;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** Big-endian on purpose: the wire format must not depend on the host's byte order. */
|
|
33
|
+
/*#__NO_SIDE_EFFECTS__*/
|
|
34
|
+
export function read32(bytes: Uint8Array, offset: number): number {
|
|
35
|
+
return (
|
|
36
|
+
((bytes[offset] as number) << 24) |
|
|
37
|
+
((bytes[offset + 1] as number) << 16) |
|
|
38
|
+
((bytes[offset + 2] as number) << 8) |
|
|
39
|
+
(bytes[offset + 3] as number) |
|
|
40
|
+
0
|
|
41
|
+
);
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
function write32(bytes: Uint8Array, offset: number, value: number) {
|
|
45
|
+
bytes[offset] = value >>> 24;
|
|
46
|
+
bytes[offset + 1] = (value >>> 16) & 0xff;
|
|
47
|
+
bytes[offset + 2] = (value >>> 8) & 0xff;
|
|
48
|
+
bytes[offset + 3] = value & 0xff;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* Transform 16 bytes from `input` into `output`, which may be the same array.
|
|
53
|
+
*
|
|
54
|
+
* Unmasking is the exact inverse: the rounds are identical and only the key order differs, which
|
|
55
|
+
* is why the final swap below is undone rather than performed.
|
|
56
|
+
*/
|
|
57
|
+
export function feistel16(
|
|
58
|
+
input: Uint8Array,
|
|
59
|
+
inputOffset: number,
|
|
60
|
+
keys: Int32Array,
|
|
61
|
+
direction: "mask" | "unmask",
|
|
62
|
+
output: Uint8Array,
|
|
63
|
+
outputOffset: number,
|
|
64
|
+
) {
|
|
65
|
+
let left0 = read32(input, inputOffset);
|
|
66
|
+
let left1 = read32(input, inputOffset + 4);
|
|
67
|
+
let right0 = read32(input, inputOffset + 8);
|
|
68
|
+
let right1 = read32(input, inputOffset + 12);
|
|
69
|
+
for (let round = 0; round < ROUNDS; round += 1) {
|
|
70
|
+
const key = (direction === "mask" ? round : ROUNDS - 1 - round) * 2;
|
|
71
|
+
// The round function is `halfSipHash(keys[key], keys[key + 1], [right0, right1], 8)`, written
|
|
72
|
+
// out for its fixed two-word message: the call through word arrays cost about a fifth more of
|
|
73
|
+
// the network on Node and Bun (bench/PERFORMANCE.md). The fixed vector in `feistel.test.ts`
|
|
74
|
+
// and the wire-format vectors hold it to issued slugs.
|
|
75
|
+
const key0 = keys[key] as number;
|
|
76
|
+
const key1 = keys[key + 1] as number;
|
|
77
|
+
let v0 = key0 | 0;
|
|
78
|
+
let v1 = (key1 ^ 0xee) | 0;
|
|
79
|
+
let v2 = (key0 ^ 0x6c796765) | 0;
|
|
80
|
+
let v3 = (key1 ^ 0x74656462) | 0;
|
|
81
|
+
// Absorb both message words, then the length block for 8 bytes, with two rounds each.
|
|
82
|
+
for (let block = 0; block < 3; block += 1) {
|
|
83
|
+
const m = block === 0 ? right0 : block === 1 ? right1 : 8 << 24;
|
|
84
|
+
v3 ^= m;
|
|
85
|
+
for (let sipRound = 0; sipRound < 2; sipRound += 1) {
|
|
86
|
+
v0 = (v0 + v1) | 0;
|
|
87
|
+
v1 = (v1 << 5) | (v1 >>> 27);
|
|
88
|
+
v1 ^= v0;
|
|
89
|
+
v0 = (v0 << 16) | (v0 >>> 16);
|
|
90
|
+
v2 = (v2 + v3) | 0;
|
|
91
|
+
v3 = (v3 << 8) | (v3 >>> 24);
|
|
92
|
+
v3 ^= v2;
|
|
93
|
+
v0 = (v0 + v3) | 0;
|
|
94
|
+
v3 = (v3 << 7) | (v3 >>> 25);
|
|
95
|
+
v3 ^= v0;
|
|
96
|
+
v2 = (v2 + v1) | 0;
|
|
97
|
+
v1 = (v1 << 13) | (v1 >>> 19);
|
|
98
|
+
v1 ^= v2;
|
|
99
|
+
v2 = (v2 << 16) | (v2 >>> 16);
|
|
100
|
+
}
|
|
101
|
+
v0 ^= m;
|
|
102
|
+
}
|
|
103
|
+
// Two four-round squeezes yield the two output words.
|
|
104
|
+
v2 ^= 0xee;
|
|
105
|
+
let hash0 = 0;
|
|
106
|
+
for (let half = 0; half < 2; half += 1) {
|
|
107
|
+
for (let sipRound = 0; sipRound < 4; sipRound += 1) {
|
|
108
|
+
v0 = (v0 + v1) | 0;
|
|
109
|
+
v1 = (v1 << 5) | (v1 >>> 27);
|
|
110
|
+
v1 ^= v0;
|
|
111
|
+
v0 = (v0 << 16) | (v0 >>> 16);
|
|
112
|
+
v2 = (v2 + v3) | 0;
|
|
113
|
+
v3 = (v3 << 8) | (v3 >>> 24);
|
|
114
|
+
v3 ^= v2;
|
|
115
|
+
v0 = (v0 + v3) | 0;
|
|
116
|
+
v3 = (v3 << 7) | (v3 >>> 25);
|
|
117
|
+
v3 ^= v0;
|
|
118
|
+
v2 = (v2 + v1) | 0;
|
|
119
|
+
v1 = (v1 << 13) | (v1 >>> 19);
|
|
120
|
+
v1 ^= v2;
|
|
121
|
+
v2 = (v2 << 16) | (v2 >>> 16);
|
|
122
|
+
}
|
|
123
|
+
if (half === 0) {
|
|
124
|
+
hash0 = v1 ^ v3;
|
|
125
|
+
v1 ^= 0xdd;
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
const next0 = left0 ^ hash0;
|
|
129
|
+
const next1 = left1 ^ v1 ^ v3;
|
|
130
|
+
left0 = right0;
|
|
131
|
+
left1 = right1;
|
|
132
|
+
right0 = next0;
|
|
133
|
+
right1 = next1;
|
|
134
|
+
}
|
|
135
|
+
// Undoing the last round's swap is what collapses encode and decode into one routine. Perform
|
|
136
|
+
// it, and decoding would need its own mirrored loop that can silently disagree with this one.
|
|
137
|
+
write32(output, outputOffset, right0);
|
|
138
|
+
write32(output, outputOffset + 4, right1);
|
|
139
|
+
write32(output, outputOffset + 8, left0);
|
|
140
|
+
write32(output, outputOffset + 12, left1);
|
|
141
|
+
}
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
|
|
3
|
+
import { findUnknownOption, INVALID_OPTIONS, isPlainRecord, UuidSlugError } from "./errors.ts";
|
|
4
|
+
|
|
5
|
+
export interface GenerationOptionValues {
|
|
6
|
+
readonly alphabet?: unknown;
|
|
7
|
+
readonly at?: unknown;
|
|
8
|
+
readonly generator?: unknown;
|
|
9
|
+
readonly maskingCodec?: unknown;
|
|
10
|
+
readonly output?: unknown;
|
|
11
|
+
readonly outputOffset?: unknown;
|
|
12
|
+
readonly textCase?: unknown;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
/** Read selected generation options once and reject every unsupported key. */
|
|
16
|
+
export function readGenerationOptions(
|
|
17
|
+
options: unknown,
|
|
18
|
+
accepted: Readonly<Partial<Record<keyof GenerationOptionValues, true>>>,
|
|
19
|
+
operation: string,
|
|
20
|
+
): GenerationOptionValues | UuidSlugError {
|
|
21
|
+
if (options === null || typeof options !== "object")
|
|
22
|
+
return new UuidSlugError(INVALID_OPTIONS, `${operation} options must be a plain object.`);
|
|
23
|
+
try {
|
|
24
|
+
if (!isPlainRecord(options))
|
|
25
|
+
return new UuidSlugError(INVALID_OPTIONS, `${operation} options must be a plain object.`);
|
|
26
|
+
const unknown = findUnknownOption(options, accepted);
|
|
27
|
+
if (unknown !== undefined)
|
|
28
|
+
return new UuidSlugError(INVALID_OPTIONS, `Unknown ${operation} option: ${unknown}.`);
|
|
29
|
+
const source = options as GenerationOptionValues;
|
|
30
|
+
// Direct assignments build one object; a conditional spread per option allocated a temporary
|
|
31
|
+
// object for each (bench/PERFORMANCE.md). Each accepted own property is read once, in this
|
|
32
|
+
// order. Callers resolve `alphabet` and `textCase`, which also unwraps `String` objects.
|
|
33
|
+
const values: { -readonly [Key in keyof GenerationOptionValues]: unknown } = {};
|
|
34
|
+
if (accepted.alphabet && Object.hasOwn(source, "alphabet")) values.alphabet = source.alphabet;
|
|
35
|
+
if (accepted.at && Object.hasOwn(source, "at")) values.at = source.at;
|
|
36
|
+
if (accepted.generator && Object.hasOwn(source, "generator"))
|
|
37
|
+
values.generator = source.generator;
|
|
38
|
+
if (accepted.maskingCodec && Object.hasOwn(source, "maskingCodec"))
|
|
39
|
+
values.maskingCodec = source.maskingCodec;
|
|
40
|
+
if (accepted.output && Object.hasOwn(source, "output")) values.output = source.output;
|
|
41
|
+
if (accepted.outputOffset && Object.hasOwn(source, "outputOffset"))
|
|
42
|
+
values.outputOffset = source.outputOffset;
|
|
43
|
+
if (accepted.textCase && Object.hasOwn(source, "textCase")) values.textCase = source.textCase;
|
|
44
|
+
return values;
|
|
45
|
+
} catch (cause) {
|
|
46
|
+
return new UuidSlugError(INVALID_OPTIONS, `Reading ${operation} options failed.`, { cause });
|
|
47
|
+
}
|
|
48
|
+
}
|