@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/runtime/node.ts
CHANGED
|
@@ -1,23 +1,60 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
|
|
1
3
|
import crypto from "node:crypto";
|
|
2
|
-
import {
|
|
3
|
-
import
|
|
4
|
+
import { Buffer } from "node:buffer";
|
|
5
|
+
import { pooledFill } from "./pool.ts";
|
|
6
|
+
import type { Runtime } from "./types.ts";
|
|
4
7
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
+
const JITLESS_FLAG = "--jitless";
|
|
9
|
+
const JIT_ENABLED_FLAG = "--no-jitless";
|
|
10
|
+
let jitless: boolean | undefined;
|
|
11
|
+
// NODE_OPTIONS is applied before command-line flags; the final explicit setting wins. Keep this
|
|
12
|
+
// startup-only so bounds and generation share the selection without probing each identifier.
|
|
13
|
+
// Quoted option words remain whole: a filename containing a flag is not a flag.
|
|
14
|
+
for (let index = process.execArgv.length - 1; index >= 0; index -= 1) {
|
|
15
|
+
const flag = process.execArgv[index];
|
|
16
|
+
if (flag === JITLESS_FLAG || flag === JIT_ENABLED_FLAG) {
|
|
17
|
+
jitless = flag === JITLESS_FLAG;
|
|
18
|
+
break;
|
|
19
|
+
}
|
|
20
|
+
}
|
|
8
21
|
|
|
9
|
-
|
|
22
|
+
// CLI overrides settle the answer without parsing the environment. Ordinary imports allocate no
|
|
23
|
+
// token array; quoted environment words need tokenization only when a mode flag could be present.
|
|
24
|
+
const nodeOptions = jitless === undefined ? process.env.NODE_OPTIONS : undefined;
|
|
25
|
+
if (nodeOptions?.includes("jitless")) {
|
|
26
|
+
const words = nodeOptions.match(/(?:[^\s"\\]|\\.|"(?:[^"\\]|\\.)*")+/g);
|
|
27
|
+
for (let index = (words?.length ?? 0) - 1; index >= 0; index -= 1) {
|
|
28
|
+
const flag = words?.[index]?.replace(/"|\\(?=.)/g, "");
|
|
29
|
+
if (flag === JITLESS_FLAG || flag === JIT_ENABLED_FLAG) {
|
|
30
|
+
jitless = flag === JITLESS_FLAG;
|
|
31
|
+
break;
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
}
|
|
10
35
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
36
|
+
/**
|
|
37
|
+
* Node's native UTF-8 encoder materially reduces string-seed construction; the portable adapter
|
|
38
|
+
* remains the compatibility boundary. bench/PERFORMANCE.md owns the measured runtime scope.
|
|
39
|
+
*/
|
|
40
|
+
export const encodeUtf8 = /* @__NO_SIDE_EFFECTS__ */ (text: string): Uint8Array =>
|
|
41
|
+
Buffer.from(text, "utf8");
|
|
42
|
+
|
|
43
|
+
const nodeRuntime: Runtime = {
|
|
44
|
+
/**
|
|
45
|
+
* `randomFillSync` writes into the buffer it is given. `randomBytes` would allocate a fresh
|
|
46
|
+
* `Buffer` per call and copy out of it, leaving a second, unzeroed copy of the random
|
|
47
|
+
* material on the heap for the collector to get to whenever it does. Pooled because the
|
|
48
|
+
* per-call cost dominates at 16 bytes; see `pool.ts`.
|
|
49
|
+
*/
|
|
50
|
+
fillRandom: /*#__PURE__*/ pooledFill((into) => {
|
|
51
|
+
crypto.randomFillSync(into);
|
|
52
|
+
return undefined;
|
|
53
|
+
}),
|
|
54
|
+
// Pooled formatting wins with the JIT; native text wins without it. Missing native capability
|
|
55
|
+
// stays undefined so the generator uses its tested portable fallback. Remeasure both modes
|
|
56
|
+
// after Node changes; bench/PERFORMANCE.md owns the compared calls and resource limits.
|
|
57
|
+
...(jitless ? { jitless: true, uuidV4: crypto.randomUUID } : {}),
|
|
23
58
|
};
|
|
59
|
+
|
|
60
|
+
export const runtime = nodeRuntime;
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
|
|
3
|
+
import { randomFailure } from "../errors.ts";
|
|
4
|
+
import type { UuidSlugError } from "../errors.ts";
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* Draws cryptographic randomness a page at a time instead of per id.
|
|
8
|
+
*
|
|
9
|
+
* Randomness calls cost more than copying the 16 bytes an identifier needs. The bounded pool
|
|
10
|
+
* amortizes that call without retaining more unissued material than needed.
|
|
11
|
+
*
|
|
12
|
+
* The source is unchanged — this batches the same CSPRNG, it does not replace or stretch it.
|
|
13
|
+
*/
|
|
14
|
+
export const POOL_BYTES = 8192;
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* Wraps a direct random-fill primitive in a pool.
|
|
18
|
+
*
|
|
19
|
+
* Consumed bytes are zeroed as they are handed out. Batching is what creates the need: without
|
|
20
|
+
* a pool, material for an id is gone once used, whereas a live 8 KiB buffer would otherwise
|
|
21
|
+
* retain the random half of up to 512 already-issued ids, so a heap dump would expose ids the
|
|
22
|
+
* process had already handed out. Zeroing restores the property batching would remove; the cost
|
|
23
|
+
* is one write per byte already being copied.
|
|
24
|
+
*
|
|
25
|
+
* Each module instance owns its pool, so worker threads never share one. This is safe under
|
|
26
|
+
* Node's process model because a new process gets a fresh heap; it would NOT be safe under a
|
|
27
|
+
* POSIX `fork` that copies the heap, where parent and child would issue identical bytes.
|
|
28
|
+
*/
|
|
29
|
+
/*#__NO_SIDE_EFFECTS__*/
|
|
30
|
+
export function pooledFill(
|
|
31
|
+
fill: (into: Uint8Array<ArrayBuffer>) => unknown,
|
|
32
|
+
): (bytes: Uint8Array<ArrayBuffer>) => undefined | UuidSlugError {
|
|
33
|
+
let pool: Uint8Array<ArrayBuffer> | undefined;
|
|
34
|
+
// STARTS EMPTY, and must. Pre-filling here would move the first call's syscall off the hot path,
|
|
35
|
+
// which looks like a free win and is the one change that breaks heap-snapshot safety: a snapshot
|
|
36
|
+
// taken at import time (V8 or JavaScriptCore startup snapshots, and the serverless platforms
|
|
37
|
+
// built on them) would capture drawn randomness, and every process restored from it would issue
|
|
38
|
+
// the SAME identifiers. Nothing else would notice — the bytes stay perfectly random within any
|
|
39
|
+
// one process, so every other case in this suite passes. `__test__/entropy.test.ts` gates it by
|
|
40
|
+
// importing the package under the instrument and requiring that no source was touched.
|
|
41
|
+
let offset = POOL_BYTES;
|
|
42
|
+
return (bytes) => {
|
|
43
|
+
const { length } = bytes;
|
|
44
|
+
// A request larger than the pool would refill for a single use; serve it directly instead.
|
|
45
|
+
if (length > POOL_BYTES) {
|
|
46
|
+
return randomFailure(fill(bytes));
|
|
47
|
+
}
|
|
48
|
+
if (pool === undefined || offset + length > POOL_BYTES) {
|
|
49
|
+
pool ??= new Uint8Array(POOL_BYTES);
|
|
50
|
+
const failed = randomFailure(fill(pool));
|
|
51
|
+
if (failed) return failed;
|
|
52
|
+
offset = 0;
|
|
53
|
+
}
|
|
54
|
+
// Copy and erase in one pass; `subarray` plus `set` would allocate a view per call.
|
|
55
|
+
// Continuation draws need four bytes. Fixed stores avoid their loop without another view
|
|
56
|
+
// or retained buffer. Owned draws use four-byte blocks, reusing each source offset rather
|
|
57
|
+
// than repeating its arithmetic. Blocks keep the body smaller than fully expanded stores;
|
|
58
|
+
// other lengths keep the indexed loop. Complete-call comparisons in bench/PERFORMANCE.md
|
|
59
|
+
// decide this shape, not copy-only timing. Remeasure if draw widths
|
|
60
|
+
// or the runtime's typed-array handling change.
|
|
61
|
+
if (length === 4) {
|
|
62
|
+
bytes[0] = pool[offset + 0] as number;
|
|
63
|
+
pool[offset + 0] = 0;
|
|
64
|
+
bytes[1] = pool[offset + 1] as number;
|
|
65
|
+
pool[offset + 1] = 0;
|
|
66
|
+
bytes[2] = pool[offset + 2] as number;
|
|
67
|
+
pool[offset + 2] = 0;
|
|
68
|
+
bytes[3] = pool[offset + 3] as number;
|
|
69
|
+
pool[offset + 3] = 0;
|
|
70
|
+
} else if (length === 16) {
|
|
71
|
+
for (let i = 0; i < 16; i += 4) {
|
|
72
|
+
const sourceOffset = offset + i;
|
|
73
|
+
bytes[i] = pool[sourceOffset] as number;
|
|
74
|
+
pool[sourceOffset] = 0;
|
|
75
|
+
bytes[i + 1] = pool[sourceOffset + 1] as number;
|
|
76
|
+
pool[sourceOffset + 1] = 0;
|
|
77
|
+
bytes[i + 2] = pool[sourceOffset + 2] as number;
|
|
78
|
+
pool[sourceOffset + 2] = 0;
|
|
79
|
+
bytes[i + 3] = pool[sourceOffset + 3] as number;
|
|
80
|
+
pool[sourceOffset + 3] = 0;
|
|
81
|
+
}
|
|
82
|
+
} else
|
|
83
|
+
for (let i = 0; i < length; i += 1) {
|
|
84
|
+
bytes[i] = pool[offset + i] as number;
|
|
85
|
+
pool[offset + i] = 0;
|
|
86
|
+
}
|
|
87
|
+
offset += length;
|
|
88
|
+
return undefined;
|
|
89
|
+
};
|
|
90
|
+
}
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
|
|
3
|
+
import { RNG_UNAVAILABLE, UuidSlugError } from "../errors.ts";
|
|
4
|
+
import { pooledFill } from "./pool.ts";
|
|
5
|
+
import type { Latin1Scratch, Runtime } from "./types.ts";
|
|
6
|
+
|
|
7
|
+
let utf8Encoder: TextEncoder | undefined;
|
|
8
|
+
const nativeToHex = (Uint8Array.prototype as { toHex?: () => string }).toHex;
|
|
9
|
+
|
|
10
|
+
/** Create the shared encoder only when mask construction needs it; generation imports this adapter too. */
|
|
11
|
+
export const encodeUtf8 = (text: string): Uint8Array =>
|
|
12
|
+
(utf8Encoder ??= new TextEncoder()).encode(text);
|
|
13
|
+
|
|
14
|
+
const runtimeCapabilities: Runtime = {
|
|
15
|
+
/**
|
|
16
|
+
* Pooled for the same reason as Node's: `getRandomValues` costs far more per call than per
|
|
17
|
+
* byte, and a v7 id needs 16. Bun draws this path too, where pooling measured 16x.
|
|
18
|
+
*/
|
|
19
|
+
fillRandom: /*#__PURE__*/ pooledFill((into) => {
|
|
20
|
+
// Resolve per draw so instrumentation installed after import observes the source.
|
|
21
|
+
const crypto = globalThis.crypto;
|
|
22
|
+
if (!crypto?.getRandomValues)
|
|
23
|
+
return new UuidSlugError(RNG_UNAVAILABLE, "Web Crypto getRandomValues is unavailable.");
|
|
24
|
+
crypto.getRandomValues(into);
|
|
25
|
+
return undefined;
|
|
26
|
+
}),
|
|
27
|
+
};
|
|
28
|
+
|
|
29
|
+
// WebKit's fixed formatter slowed unrelated successful calls in mixed comparisons. Native hex
|
|
30
|
+
// did not reproduce a repeated loss while other engines retain their fixed writers. This identity
|
|
31
|
+
// selects cost only; absent hex support still uses the portable writer. Remeasure after browser
|
|
32
|
+
// changes (bench/PERFORMANCE.md); the shared ASCII decoder also slowed slug output.
|
|
33
|
+
if (
|
|
34
|
+
typeof navigator !== "undefined" &&
|
|
35
|
+
navigator.vendor === "Apple Computer, Inc." &&
|
|
36
|
+
typeof nativeToHex === "function"
|
|
37
|
+
)
|
|
38
|
+
runtimeCapabilities.uuidHex = (bytes) => nativeToHex.call(bytes);
|
|
39
|
+
|
|
40
|
+
type Latin1Buffer = Uint8Array & {
|
|
41
|
+
toString(encoding: "latin1", start: number, end: number): string;
|
|
42
|
+
};
|
|
43
|
+
type HostBuffer = { alloc(size: number): Latin1Buffer } | undefined;
|
|
44
|
+
|
|
45
|
+
/** Build scratch text through a Node-compatible `Buffer` constructor. */
|
|
46
|
+
export function bufferLatin1Scratch(hostBuffer: NonNullable<HostBuffer>) {
|
|
47
|
+
return (length: number): Latin1Scratch => {
|
|
48
|
+
const bytes = hostBuffer.alloc(length);
|
|
49
|
+
return { bytes, text: () => bytes.toString("latin1", 0, length) };
|
|
50
|
+
};
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
// Deno's Web Crypto UUID method is faster than the portable formatter; Chromium's is slower.
|
|
54
|
+
// Runtime identity decides only this measured performance split—the entropy and UUID contracts
|
|
55
|
+
// are the same, and both paths remain covered by the shared runtime corpus.
|
|
56
|
+
if (typeof (globalThis as { Deno?: unknown }).Deno !== "undefined") {
|
|
57
|
+
if (globalThis.crypto?.randomUUID)
|
|
58
|
+
runtimeCapabilities.uuidV4 = globalThis.crypto.randomUUID.bind(globalThis.crypto);
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* Browser `randomUUID` is intentionally not selected. Chromium measured it about five times
|
|
63
|
+
* slower than this package's pooled byte generator and formatter, while insecure contexts can
|
|
64
|
+
* expose `getRandomValues` without `randomUUID`. Leaving the shortcut absent gives every browser
|
|
65
|
+
* context the faster common path. Reconsider when another browser engine or Chromium release
|
|
66
|
+
* overturns the complete public-route measurement.
|
|
67
|
+
*/
|
|
68
|
+
export const runtime: Runtime = runtimeCapabilities;
|
package/src/runtime/types.ts
CHANGED
|
@@ -1,12 +1,37 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
|
|
3
|
+
import type { UuidSlugError } from "../errors.ts";
|
|
4
|
+
|
|
1
5
|
export interface Runtime {
|
|
6
|
+
/** Node has disabled executable JavaScript code generation for this process. */
|
|
7
|
+
readonly jitless?: true;
|
|
2
8
|
/**
|
|
3
9
|
* The buffer is pinned to a plain `ArrayBuffer` because Web Crypto's `getRandomValues`
|
|
4
10
|
* rejects a `SharedArrayBuffer` view at runtime, and the unparameterised `Uint8Array`
|
|
5
11
|
* admits one. Narrowing here makes that refusal unrepresentable instead of a throw.
|
|
6
12
|
*/
|
|
7
|
-
fillRandom(bytes: Uint8Array<ArrayBuffer>):
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
13
|
+
fillRandom(this: void, bytes: Uint8Array<ArrayBuffer>): undefined | UuidSlugError;
|
|
14
|
+
/**
|
|
15
|
+
* Hooks are detached from the adapter, so `this: void` rejects implementations that depend on
|
|
16
|
+
* method binding.
|
|
17
|
+
*/
|
|
18
|
+
/** Native UUIDv4 text; default calls trust the proper native generator's result directly. */
|
|
19
|
+
uuidV4?(this: void): string;
|
|
20
|
+
/** Native current-time UUIDv7 text; configured clocks and sequence state stay on generators. */
|
|
21
|
+
uuidV7?(this: void): string;
|
|
22
|
+
/** Native current-time UUIDv7 as one canonical unpadded base64url plain slug. */
|
|
23
|
+
uuidV7Slug?(this: void): string;
|
|
24
|
+
/** Optional native hex conversion for the runtime's selected UUID text writer. */
|
|
25
|
+
uuidHex?(this: void, bytes: Uint8Array): string;
|
|
26
|
+
/**
|
|
27
|
+
* Create a reusable buffer whose bytes a native call turns into a flat Latin-1 string. Adapters
|
|
28
|
+
* provide it only where that call beats building text from JavaScript strings.
|
|
29
|
+
*/
|
|
30
|
+
latin1Scratch?(this: void, length: number): Latin1Scratch;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
export interface Latin1Scratch {
|
|
34
|
+
readonly bytes: Uint8Array;
|
|
35
|
+
/** Return every byte of `bytes` as one Latin-1 string. */
|
|
36
|
+
text(this: void): string;
|
|
12
37
|
}
|
package/src/sentinel.ts
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
|
|
3
|
+
// Only the 26-character plain spelling is case-insensitive. Normalizing a base64url key would
|
|
4
|
+
// merge distinct UUIDs; exact hits and codecs without sentinels require no normalization.
|
|
5
|
+
export function findSentinel<Value>(
|
|
6
|
+
sentinels: ReadonlyMap<string, Value>,
|
|
7
|
+
slug: string,
|
|
8
|
+
): Value | undefined {
|
|
9
|
+
return (
|
|
10
|
+
sentinels.get(slug) ??
|
|
11
|
+
(slug.length === 26 && sentinels.size !== 0 ? sentinels.get(slug.toLowerCase()) : undefined)
|
|
12
|
+
);
|
|
13
|
+
}
|
package/src/siphash.ts
ADDED
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* HalfSipHash-2-4 with 64-bit output — the 32-bit-word member of the SipHash family (Aumasson and
|
|
5
|
+
* Bernstein), transcribed from the reference implementation. It is a KEYED pseudorandom function:
|
|
6
|
+
* without the key its output on a chosen input is not computable, which is exactly what `mix32` — a
|
|
7
|
+
* fixed, public, unkeyed bijection — could never be, and the reason it replaced it.
|
|
8
|
+
*
|
|
9
|
+
* Key derivation (`mask.ts`) calls this function. The Feistel round (`feistel.ts`) writes the same
|
|
10
|
+
* function out for its fixed two-word message because the call cost measurably more per masked slug;
|
|
11
|
+
* the published vectors grade this transcription, and the Feistel and wire-format vectors grade that one.
|
|
12
|
+
*
|
|
13
|
+
* Chosen over full SipHash-2-4 because that is defined over 64-bit words, which JavaScript has only
|
|
14
|
+
* as `BigInt` or as hand-emulated 32-bit pairs — the first far too slow for a hot path, the second a
|
|
15
|
+
* re-implementation whose errors nothing would catch. HalfSipHash is 32-bit BY SPECIFICATION, so
|
|
16
|
+
* this is a transcription, and `__test__/siphash.test.ts` holds it to all 64 published vectors. That
|
|
17
|
+
* external check is the whole reason a standard primitive beat anything tuned here: nothing in this
|
|
18
|
+
* repository can grade a mixing function (see `feistel.ts` — every instrument here passes a
|
|
19
|
+
* two-round network), so agreement with a specification somebody else wrote is the only evidence
|
|
20
|
+
* available that can actually fail.
|
|
21
|
+
*
|
|
22
|
+
* Its key is 64 bits. `mask.ts` runs two independently keyed instances and XORs them, the standard
|
|
23
|
+
* cascade for widening a PRF's key; see there.
|
|
24
|
+
*/
|
|
25
|
+
|
|
26
|
+
/** Message-absorption rounds per block — the `2` of HalfSipHash-**2**-4. */
|
|
27
|
+
const C_ROUNDS = 2;
|
|
28
|
+
/** Finalisation rounds per output word — the `4` of HalfSipHash-2-**4**. */
|
|
29
|
+
const D_ROUNDS = 4;
|
|
30
|
+
|
|
31
|
+
/** Private continuation: resume only with the same message, keys, byte length and output. */
|
|
32
|
+
export interface HashContinuation {
|
|
33
|
+
readonly block: number;
|
|
34
|
+
readonly v0: number;
|
|
35
|
+
readonly v1: number;
|
|
36
|
+
readonly v2: number;
|
|
37
|
+
readonly v3: number;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* HalfSipHash-2-4 over a message supplied as 32-bit LITTLE-ENDIAN words, writing the two output
|
|
42
|
+
* words into `out`.
|
|
43
|
+
*
|
|
44
|
+
* Words rather than bytes because both callers already hold words, and the specification absorbs the
|
|
45
|
+
* message in 32-bit little-endian blocks regardless — so this is the same function with the byte
|
|
46
|
+
* reassembly left to whoever actually has bytes. Taking a `Uint8Array` would make the hot path pack
|
|
47
|
+
* bytes it had just unpacked.
|
|
48
|
+
*
|
|
49
|
+
* `byteLength` is the message length the specification hashes and stamps into the final block.
|
|
50
|
+
* `words` must therefore hold `ceil(byteLength / 4)` entries, with any trailing 1-3 bytes packed
|
|
51
|
+
* little-endian into the low bytes of the last one. Internal cooperative callers may pass a
|
|
52
|
+
* positive block limit and resume the returned continuation with exactly the same inputs.
|
|
53
|
+
*/
|
|
54
|
+
export function halfSipHash(
|
|
55
|
+
key0: number,
|
|
56
|
+
key1: number,
|
|
57
|
+
words: Int32Array,
|
|
58
|
+
byteLength: number,
|
|
59
|
+
out: Int32Array,
|
|
60
|
+
continuation?: HashContinuation,
|
|
61
|
+
blockLimit = Infinity,
|
|
62
|
+
): HashContinuation | undefined {
|
|
63
|
+
let v0 = key0 | 0;
|
|
64
|
+
let v1 = (key1 ^ 0xee) | 0;
|
|
65
|
+
let v2 = (key0 ^ 0x6c796765) | 0;
|
|
66
|
+
let v3 = (key1 ^ 0x74656462) | 0;
|
|
67
|
+
if (continuation) ({ v0, v1, v2, v3 } = continuation);
|
|
68
|
+
|
|
69
|
+
// The length-stamped final block is absorbed exactly like a message block, so it rides the same
|
|
70
|
+
// loop rather than a second copy of it. Seeds may end mid-word; mask blocks use whole words.
|
|
71
|
+
// The reference vectors exercise every tail length, including an empty message.
|
|
72
|
+
const fullWords = byteLength >>> 2;
|
|
73
|
+
const spare = byteLength & 3;
|
|
74
|
+
const tail = spare === 0 ? 0 : (words[fullWords] as number) & ((1 << (spare * 8)) - 1);
|
|
75
|
+
const lengthBlock = (byteLength << 24) | tail | 0;
|
|
76
|
+
const start = continuation?.block ?? 0;
|
|
77
|
+
const end = blockLimit === Infinity ? fullWords : Math.min(fullWords, start + blockLimit - 1);
|
|
78
|
+
for (let block = start; block <= end; block += 1) {
|
|
79
|
+
const m = block === fullWords ? lengthBlock : (words[block] as number);
|
|
80
|
+
v3 ^= m;
|
|
81
|
+
for (let round = 0; round < C_ROUNDS; round += 1) {
|
|
82
|
+
v0 = (v0 + v1) | 0;
|
|
83
|
+
v1 = (v1 << 5) | (v1 >>> 27);
|
|
84
|
+
v1 ^= v0;
|
|
85
|
+
v0 = (v0 << 16) | (v0 >>> 16);
|
|
86
|
+
v2 = (v2 + v3) | 0;
|
|
87
|
+
v3 = (v3 << 8) | (v3 >>> 24);
|
|
88
|
+
v3 ^= v2;
|
|
89
|
+
v0 = (v0 + v3) | 0;
|
|
90
|
+
v3 = (v3 << 7) | (v3 >>> 25);
|
|
91
|
+
v3 ^= v0;
|
|
92
|
+
v2 = (v2 + v1) | 0;
|
|
93
|
+
v1 = (v1 << 13) | (v1 >>> 19);
|
|
94
|
+
v1 ^= v2;
|
|
95
|
+
v2 = (v2 << 16) | (v2 >>> 16);
|
|
96
|
+
}
|
|
97
|
+
v0 ^= m;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
// No output is published until absorption and finalisation are complete. The synchronous
|
|
101
|
+
// hot path has an unlimited block budget and never allocates a continuation.
|
|
102
|
+
if (end < fullWords) return { block: end + 1, v0, v1, v2, v3 };
|
|
103
|
+
|
|
104
|
+
// Two squeezes, and the `0xdd` between them is what makes the second output word something other
|
|
105
|
+
// than a rerun of the first.
|
|
106
|
+
v2 ^= 0xee;
|
|
107
|
+
for (let half = 0; half < 2; half += 1) {
|
|
108
|
+
for (let round = 0; round < D_ROUNDS; round += 1) {
|
|
109
|
+
v0 = (v0 + v1) | 0;
|
|
110
|
+
v1 = (v1 << 5) | (v1 >>> 27);
|
|
111
|
+
v1 ^= v0;
|
|
112
|
+
v0 = (v0 << 16) | (v0 >>> 16);
|
|
113
|
+
v2 = (v2 + v3) | 0;
|
|
114
|
+
v3 = (v3 << 8) | (v3 >>> 24);
|
|
115
|
+
v3 ^= v2;
|
|
116
|
+
v0 = (v0 + v3) | 0;
|
|
117
|
+
v3 = (v3 << 7) | (v3 >>> 25);
|
|
118
|
+
v3 ^= v0;
|
|
119
|
+
v2 = (v2 + v1) | 0;
|
|
120
|
+
v1 = (v1 << 13) | (v1 >>> 19);
|
|
121
|
+
v1 ^= v2;
|
|
122
|
+
v2 = (v2 << 16) | (v2 >>> 16);
|
|
123
|
+
}
|
|
124
|
+
out[half] = v1 ^ v3;
|
|
125
|
+
v1 ^= 0xdd;
|
|
126
|
+
}
|
|
127
|
+
return undefined;
|
|
128
|
+
}
|