effect 4.0.6 → 4.1.0

package/dist/crypto/Mac.js

@@ -0,0 +1,288 @@
+/**
+ * Message authentication codes: HMAC with SHA-1, SHA-256, SHA-384, or
+ * SHA-512.
+ *
+ * The {@link Mac} service generates keys, signs data, and verifies tags. The
+ * top-level {@link key}, {@link fromCryptoKey}, and {@link toBytes} functions
+ * build and export keys without a service, and {@link timingSafeEqual}
+ * compares byte arrays in constant time.
+ *
+ * Keys are opaque. They hold either key bytes or a `CryptoKey`, display only
+ * their algorithm, and compare by reference.
+ *
+ * @stability unstable
+ * @since 4.0.0
+ */
+import * as Context from "../Context.js";
+import * as Effect from "../Effect.js";
+import * as Layer from "../Layer.js";
+import * as Predicate from "../Predicate.js";
+import * as Digest from "./Digest.js";
+import * as KeyModel from "./internal/key.js";
+import * as internal from "./internal/webCrypto.js";
+import * as SecureRandom from "./SecureRandom.js";
+import { WebCrypto } from "./WebCrypto.js";
+const TypeId = "~effect/crypto/Mac/Key";
+/**
+ * HMAC with SHA-1, with a 20-byte tag.
+ *
+ * **Gotchas**
+ *
+ * HMAC-SHA-1 is still secure as a MAC, but use it only for interoperability
+ * with existing protocols.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const hmacSha1 = {
+  name: "hmacSha1",
+  hash: Digest.sha1
+};
+/**
+ * HMAC with SHA-256, with a 32-byte tag.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const hmacSha256 = {
+  name: "hmacSha256",
+  hash: Digest.sha256
+};
+/**
+ * HMAC with SHA-384, with a 48-byte tag.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const hmacSha384 = {
+  name: "hmacSha384",
+  hash: Digest.sha384
+};
+/**
+ * HMAC with SHA-512, with a 64-byte tag.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const hmacSha512 = {
+  name: "hmacSha512",
+  hash: Digest.sha512
+};
+const KeyProto = /*#__PURE__*/KeyModel.redactedProto(TypeId, "Mac.Key");
+/**
+ * Checks whether a value is a {@link Key}.
+ *
+ * @stability unstable
+ * @category guards
+ * @since 4.0.0
+ */
+export const isKey = u => Predicate.hasProperty(u, TypeId);
+// Generated keys have the hash's block size, as Web Crypto generates them.
+const blockSizes = {
+  "MD5": 64,
+  "SHA-1": 64,
+  "SHA-256": 64,
+  "SHA-384": 128,
+  "SHA-512": 128
+};
+/**
+ * Service that generates HMAC keys, signs data, and verifies tags.
+ *
+ * **Example** (Signing and verifying a message)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, Layer } from "effect"
+ * import { Mac, SecureRandom } from "effect/crypto"
+ *
+ * const program = Effect.gen(function*() {
+ *   const mac = yield* Mac.Mac
+ *   const key = yield* mac.generateKey(Mac.hmacSha256)
+ *   const data = new TextEncoder().encode("message")
+ *   const tag = yield* mac.sign(key, data)
+ *   return yield* mac.verify(key, tag, data)
+ * })
+ *
+ * const layer = Mac.layerWebCrypto.pipe(Layer.provide(SecureRandom.layerWebCrypto))
+ * const valid = await Effect.runPromise(program.pipe(Effect.provide(layer)))
+ * valid // => true
+ * ```
+ *
+ * @stability unstable
+ * @category services
+ * @since 4.0.0
+ */
+export class Mac extends /*#__PURE__*/Context.Service()("effect/crypto/Mac") {}
+const importParams = algorithm => ({
+  name: "HMAC",
+  hash: algorithm.hash.name
+});
+/**
+ * Builds a `Mac` layer on the `WebCrypto` reference that can sign and verify
+ * byte-backed keys with a synchronous HMAC primitive.
+ *
+ * **When to use**
+ *
+ * Use to run HMAC on a runtime's native code, as `NodeCrypto.layerMac` does
+ * with `createHmac` from `node:crypto`.
+ *
+ * **Details**
+ *
+ * `hmac` receives the hash name, the key bytes, and the data, and returns the
+ * tag. It runs only for byte-backed keys. `CryptoKey`-backed keys run on
+ * `crypto.subtle`, and generated keys come from `SecureRandom`, as in
+ * {@link layerWebCrypto}. `verify` computes the tag with `hmac` and compares
+ * it with {@link timingSafeEqual}. Without `hmac`, the layer is
+ * {@link layerWebCrypto}.
+ *
+ * **Gotchas**
+ *
+ * `hmac` receives the key's own bytes, not a copy, so it must not modify or
+ * keep them.
+ *
+ * **Example** (Signing with a native HMAC)
+ *
+ * ```ts
+ * import { Layer } from "effect"
+ * import { Mac, SecureRandom } from "effect/crypto"
+ *
+ * declare const nativeHmac: (hash: string, key: Uint8Array, data: Uint8Array) => Uint8Array
+ *
+ * const layer = Mac.layerWebCryptoWith({ hmac: nativeHmac }).pipe(
+ *   Layer.provide(SecureRandom.layerWebCrypto)
+ * )
+ * ```
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.0.0
+ */
+export const layerWebCryptoWith = options => Layer.effect(Mac, Effect.gen(function* () {
+  const random = yield* SecureRandom.SecureRandom;
+  const crypto = yield* WebCrypto;
+  const cryptoKeyFor = KeyModel.makeCache((subtle, bytes, algorithm) => subtle.importKey("raw", bytes, importParams(algorithm), false, ["sign", "verify"]));
+  const hmac = options.hmac;
+  // Computes a byte-backed key's tags with `hmac`, or `undefined` to use WebCrypto.
+  const hmacTag = key => {
+    if (hmac === undefined) return undefined;
+    const stored = KeyModel.material(key);
+    return stored._tag === "Bytes" ? data => hmac(key.algorithm.hash.name, stored.bytes, data) : undefined;
+  };
+  return Mac.of({
+    generateKey: algorithm => Effect.map(random.randomBytes(blockSizes[algorithm.hash.name]), bytes => KeyModel.makeBytes(KeyProto, algorithm, bytes)),
+    sign: (key, data) => {
+      const tagOf = hmacTag(key);
+      return tagOf !== undefined ? Effect.sync(() => tagOf(data)) : internal.run("Mac", "sign", key.algorithm.name, crypto, async subtle => new Uint8Array(await subtle.sign("HMAC", await cryptoKeyFor(subtle, key), data)));
+    },
+    // Both paths compare tags in constant time and reject other lengths.
+    verify: (key, tag, data) => {
+      const tagOf = hmacTag(key);
+      return tagOf !== undefined ? Effect.sync(() => timingSafeEqual(tagOf(data), tag)) : internal.run("Mac", "verify", key.algorithm.name, crypto, async subtle => subtle.verify("HMAC", await cryptoKeyFor(subtle, key), tag, data));
+    }
+  });
+}));
+/**
+ * Layer that provides `Mac` on the `WebCrypto` reference.
+ *
+ * **Details**
+ *
+ * Signing and verification run on `crypto.subtle`. The layer imports a
+ * byte-backed key on first use and caches the `CryptoKey`. Generated keys come
+ * from `SecureRandom`, so a seeded `SecureRandom` gives reproducible keys.
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.0.0
+ */
+export const layerWebCrypto = /*#__PURE__*/layerWebCryptoWith({});
+/**
+ * Builds a key from raw key bytes.
+ *
+ * **Details**
+ *
+ * The bytes are copied into a new `Uint8Array`, so later changes to the input,
+ * including a Node.js `Buffer`, do not reach the key. Any non-empty length is
+ * accepted; RFC 2104 recommends at least the hash's output length. An empty key
+ * fails with an `InvalidKey` reason.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export const key = (algorithm, bytes) => KeyModel.fromBytes("Mac", "key", KeyProto, algorithm, bytes, bytes => bytes.length === 0 ? "An HMAC key cannot be empty" : undefined);
+/**
+ * Builds a key from an existing `CryptoKey`, such as a non-extractable one.
+ *
+ * **Details**
+ *
+ * The `CryptoKey` must be a secret HMAC key with the algorithm's hash and both
+ * the `sign` and `verify` usages, since a key reaches both operations.
+ * Otherwise the constructor fails with an `InvalidKey` reason. It must come
+ * from the `Crypto` object of the `WebCrypto` reference.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export const fromCryptoKey = (algorithm, cryptoKey) => KeyModel.fromCryptoKey("Mac", "fromCryptoKey", KeyProto, algorithm, cryptoKey, {
+  type: "secret",
+  name: "HMAC",
+  usages: ["sign", "verify"],
+  usagePolicy: "all",
+  check: keyAlgorithm => {
+    const hash = keyAlgorithm.hash?.name;
+    return hash === algorithm.hash.name ? undefined : `Expected an HMAC key for ${algorithm.hash.name}, not ${hash}`;
+  }
+});
+/**
+ * Exports a key's bytes.
+ *
+ * **Details**
+ *
+ * Returns a fresh `Uint8Array` that shares no memory with the key. A
+ * `CryptoKey`-backed key is exported on the `WebCrypto` reference, and fails
+ * with a `NotExtractable` reason when the `CryptoKey` is not extractable.
+ *
+ * @stability unstable
+ * @category converting
+ * @since 4.0.0
+ */
+export const toBytes = key => KeyModel.toBytes("Mac", key, KeyModel.exportRaw);
+/**
+ * Compares two byte arrays in constant time.
+ *
+ * **When to use**
+ *
+ * Use to compare secrets of a fixed, known length, such as tags computed
+ * outside {@link Mac}. To check an HMAC tag, use `Mac.verify`.
+ *
+ * **Gotchas**
+ *
+ * Arrays of different lengths return `false` immediately, revealing their
+ * lengths. Equal-length arrays are compared with an XOR-accumulate loop;
+ * JavaScript runtimes do not guarantee constant-time execution.
+ *
+ * **Example** (Comparing fixed-length secrets)
+ *
+ * ```ts import.meta.vitest
+ * import { Mac } from "effect/crypto"
+ *
+ * const expected = new Uint8Array([1, 2, 3])
+ * const received = new Uint8Array([1, 2, 3])
+ * Mac.timingSafeEqual(expected, received) // => true
+ * ```
+ *
+ * @stability unstable
+ * @category utils
+ * @since 4.0.0
+ */
+export const timingSafeEqual = (a, b) => {
+  if (a.length !== b.length) return false;
+  let difference = 0;
+  for (let i = 0; i < a.length; i++) difference |= a[i] ^ b[i];
+  return difference === 0;
+};
+//# sourceMappingURL=Mac.js.map

package/dist/crypto/Mac.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Mac.js","names":[],"sources":["../../src/crypto/Mac.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/crypto/SecureRandom.d.ts

@@ -0,0 +1,340 @@
+/**
+ * Cryptographically secure randomness: random bytes, uniform integers,
+ * shuffles, UUIDv4, UUIDv7, and ULIDs.
+ *
+ * The {@link SecureRandom} service is built from one `randomBytes` primitive
+ * with {@link make}. {@link layerWebCrypto} draws from `getRandomValues` on
+ * the `WebCrypto` reference. The `*Unsafe` functions draw synchronously from
+ * `globalThis.crypto` for code that cannot use a service, such as constructors
+ * and model defaults.
+ *
+ * Every operation has a `never` error channel. A bad size or an empty range is
+ * a defect.
+ *
+ * **Gotchas**
+ *
+ * There are no float, boolean, or full-range integer helpers. Insecure random
+ * numbers belong to `effect/Random`, and a secure bit is `randomBytes(1)`.
+ *
+ * @stability unstable
+ * @since 4.0.0
+ */
+import * as Context from "../Context.ts";
+import * as Effect from "../Effect.ts";
+import * as Layer from "../Layer.ts";
+/**
+ * Generates a UUID as a lowercase, hyphenated string or, with
+ * `format: "bytes"`, the 16 UUID bytes.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface UuidGenerator {
+    (options?: {
+        readonly format?: "string" | undefined;
+    }): Effect.Effect<string>;
+    <Format extends "string" | "bytes">(options: {
+        readonly format: Format;
+    }): Effect.Effect<Format extends "bytes" ? Uint8Array : string>;
+}
+declare const SecureRandom_base: Context.ServiceClass<SecureRandom, "effect/crypto/SecureRandom", {
+    /**
+     * Generates `size` cryptographically secure random bytes.
+     *
+     * A negative or non-integer size dies with a `RangeError`.
+     */
+    readonly randomBytes: (size: number) => Effect.Effect<Uint8Array>;
+    /**
+     * Generates an integer between `min` and `max`, both inclusive unless
+     * `halfOpen` excludes `max`.
+     *
+     * **Details**
+     *
+     * The result is exactly uniform: draws that would bias it are rejected.
+     * `min` is rounded up and `max` down. An empty range, or bounds that do not
+     * round to safe integers, die with a `RangeError`.
+     */
+    readonly intBetween: (min: number, max: number, options?: {
+        readonly halfOpen?: boolean | undefined;
+    }) => Effect.Effect<number>;
+    /**
+     * Returns a uniformly shuffled copy of the elements, using Fisher-Yates over
+     * `intBetween`.
+     */
+    readonly shuffle: <A>(elements: Iterable<A>) => Effect.Effect<Array<A>>;
+    /**
+     * Generates a UUIDv4, as a lowercase hyphenated string or, with
+     * `format: "bytes"`, the 16 UUID bytes.
+     */
+    readonly uuidV4: UuidGenerator;
+    /**
+     * Generates a UUIDv7 from the `Clock` timestamp, as a lowercase hyphenated
+     * string or, with `format: "bytes"`, the 16 UUID bytes.
+     *
+     * Every UUIDv7 from this service sorts after the previous one, as a string
+     * and as bytes. Within a millisecond, a 42-bit counter seeded from random
+     * bytes orders them. If the `Clock` moves back, the last timestamp is kept,
+     * and if the counter overflows, the timestamp advances by 1 ms, so a
+     * timestamp can run slightly ahead of the `Clock`. The ordering ends at the
+     * maximum timestamp, 2^48 − 1 ms (in the year 10889), which overflow cannot
+     * advance. There is no ordering between separate services, processes or
+     * workers.
+     *
+     * Consecutive UUIDv7s reveal their generation order, so never use them as
+     * secrets. Uniqueness between generators is probabilistic: each UUID has 32
+     * fresh random bits, on top of a counter seeded from 41 random bits each
+     * millisecond.
+     */
+    readonly uuidV7: UuidGenerator;
+    /**
+     * Generates a ULID from the `Clock` timestamp: 26 uppercase Crockford
+     * base32 characters.
+     *
+     * Every ULID from this service sorts after the previous one, using the ULID
+     * spec's monotonic mode: within a millisecond, the 80-bit random part is
+     * incremented. If the `Clock` moves back, the last timestamp is kept, and if
+     * the random part overflows, the timestamp advances by 1 ms. The ordering
+     * ends at the maximum timestamp, 2^48 − 1 ms (in the year 10889), which
+     * overflow cannot advance. There is no ordering between separate services,
+     * processes or workers. Consecutive ULIDs reveal their generation order, so
+     * never use them as secrets.
+     */
+    readonly ulid: Effect.Effect<string>;
+}>;
+/**
+ * Service that generates cryptographically secure random values.
+ *
+ * **Details**
+ *
+ * Every operation is derived from `randomBytes`. See {@link make}.
+ *
+ * @stability unstable
+ * @category services
+ * @since 4.0.0
+ */
+export declare class SecureRandom extends SecureRandom_base {
+}
+/**
+ * Creates a `SecureRandom` service from a secure byte source.
+ *
+ * **When to use**
+ *
+ * Use to build the service for a platform integration, a custom runtime, or a
+ * seeded test double.
+ *
+ * **Details**
+ *
+ * Every operation is derived from `randomBytes`. Sizes are checked before it
+ * is called, and an exception it throws is a defect. Each service orders its
+ * own UUIDv7s and ULIDs, independently of other services and of the
+ * `*Unsafe` functions.
+ *
+ * **Gotchas**
+ *
+ * `randomBytes` must return a fresh array of exactly `size` secure random
+ * bytes. UUID formatting mutates the returned array.
+ *
+ * **Example** (Creating a SecureRandom service)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect } from "effect"
+ * import { SecureRandom } from "effect/crypto"
+ *
+ * const random = SecureRandom.make((size) => globalThis.crypto.getRandomValues(new Uint8Array(size)))
+ *
+ * const bytes = await Effect.runPromise(random.randomBytes(4))
+ * bytes.length // => 4
+ * ```
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const make: (randomBytes: (size: number) => Uint8Array) => SecureRandom["Service"];
+/**
+ * Layer that provides `SecureRandom` from `getRandomValues` on the `WebCrypto`
+ * reference.
+ *
+ * **Details**
+ *
+ * Requests above the 65,536-byte `getRandomValues` limit are filled in chunks.
+ * Only `getRandomValues` is needed, so the layer also works in insecure browser
+ * contexts, which have no `crypto.subtle`.
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.0.0
+ */
+export declare const layerWebCrypto: Layer.Layer<SecureRandom>;
+/**
+ * Synchronously generates `size` cryptographically secure random bytes from
+ * `globalThis.crypto`.
+ *
+ * **When to use**
+ *
+ * Use when a service cannot be read, as in constructors and model defaults.
+ * Elsewhere, use the `SecureRandom` service.
+ *
+ * **Gotchas**
+ *
+ * Reads `globalThis.crypto` directly, so neither the `WebCrypto` reference nor
+ * a mocked `SecureRandom` service affects it. A negative or non-integer size
+ * throws a `RangeError`.
+ *
+ * @stability unstable
+ * @category unsafe
+ * @since 4.0.0
+ */
+export declare const randomBytesUnsafe: (size: number) => Uint8Array;
+/**
+ * Synchronously generates a UUIDv4 from `globalThis.crypto`, as a lowercase
+ * hyphenated string or, with `format: "bytes"`, the 16 UUID bytes.
+ *
+ * **Gotchas**
+ *
+ * Reads `globalThis.crypto` directly, so neither the `WebCrypto` reference nor
+ * a mocked `SecureRandom` service affects it.
+ *
+ * @stability unstable
+ * @category unsafe
+ * @since 4.0.0
+ */
+export declare const uuidV4Unsafe: {
+    /**
+     * Synchronously generates a UUIDv4 from `globalThis.crypto`, as a lowercase
+     * hyphenated string or, with `format: "bytes"`, the 16 UUID bytes.
+     *
+     * **Gotchas**
+     *
+     * Reads `globalThis.crypto` directly, so neither the `WebCrypto` reference nor
+     * a mocked `SecureRandom` service affects it.
+     *
+     * @stability unstable
+     * @category unsafe
+     * @since 4.0.0
+     */
+    (options?: {
+        readonly format?: "string" | undefined;
+    }): string;
+    /**
+     * Synchronously generates a UUIDv4 from `globalThis.crypto`, as a lowercase
+     * hyphenated string or, with `format: "bytes"`, the 16 UUID bytes.
+     *
+     * **Gotchas**
+     *
+     * Reads `globalThis.crypto` directly, so neither the `WebCrypto` reference nor
+     * a mocked `SecureRandom` service affects it.
+     *
+     * @stability unstable
+     * @category unsafe
+     * @since 4.0.0
+     */
+    <Format extends "string" | "bytes">(options: {
+        readonly format: Format;
+    }): Format extends "bytes" ? Uint8Array : string;
+};
+/**
+ * Synchronously generates a UUIDv7 from `Date.now()` and `globalThis.crypto`,
+ * as a lowercase hyphenated string or, with `format: "bytes"`, the 16 UUID
+ * bytes.
+ *
+ * **Details**
+ *
+ * Below the maximum timestamp, every UUIDv7 generated in this JS realm
+ * (process or worker) sorts after the previous one, as a string and as bytes,
+ * using the counter described on the `SecureRandom` service's `uuidV7`. The
+ * ordering is shared with `Model.UuidV7WithGenerate`, and does not hold across
+ * processes or workers. Consecutive UUIDv7s reveal their
+ * generation order, so never use them as secrets.
+ *
+ * **Gotchas**
+ *
+ * Reads `Date.now()` rather than the `Clock`, and `globalThis.crypto` rather
+ * than the `WebCrypto` reference. A timestamp can run slightly ahead of
+ * `Date.now()` when the clock moves back or the counter overflows.
+ *
+ * @stability unstable
+ * @category unsafe
+ * @since 4.0.0
+ */
+export declare const uuidV7Unsafe: {
+    /**
+     * Synchronously generates a UUIDv7 from `Date.now()` and `globalThis.crypto`,
+     * as a lowercase hyphenated string or, with `format: "bytes"`, the 16 UUID
+     * bytes.
+     *
+     * **Details**
+     *
+     * Below the maximum timestamp, every UUIDv7 generated in this JS realm
+     * (process or worker) sorts after the previous one, as a string and as bytes,
+     * using the counter described on the `SecureRandom` service's `uuidV7`. The
+     * ordering is shared with `Model.UuidV7WithGenerate`, and does not hold across
+     * processes or workers. Consecutive UUIDv7s reveal their
+     * generation order, so never use them as secrets.
+     *
+     * **Gotchas**
+     *
+     * Reads `Date.now()` rather than the `Clock`, and `globalThis.crypto` rather
+     * than the `WebCrypto` reference. A timestamp can run slightly ahead of
+     * `Date.now()` when the clock moves back or the counter overflows.
+     *
+     * @stability unstable
+     * @category unsafe
+     * @since 4.0.0
+     */
+    (options?: {
+        readonly format?: "string" | undefined;
+    }): string;
+    /**
+     * Synchronously generates a UUIDv7 from `Date.now()` and `globalThis.crypto`,
+     * as a lowercase hyphenated string or, with `format: "bytes"`, the 16 UUID
+     * bytes.
+     *
+     * **Details**
+     *
+     * Below the maximum timestamp, every UUIDv7 generated in this JS realm
+     * (process or worker) sorts after the previous one, as a string and as bytes,
+     * using the counter described on the `SecureRandom` service's `uuidV7`. The
+     * ordering is shared with `Model.UuidV7WithGenerate`, and does not hold across
+     * processes or workers. Consecutive UUIDv7s reveal their
+     * generation order, so never use them as secrets.
+     *
+     * **Gotchas**
+     *
+     * Reads `Date.now()` rather than the `Clock`, and `globalThis.crypto` rather
+     * than the `WebCrypto` reference. A timestamp can run slightly ahead of
+     * `Date.now()` when the clock moves back or the counter overflows.
+     *
+     * @stability unstable
+     * @category unsafe
+     * @since 4.0.0
+     */
+    <Format extends "string" | "bytes">(options: {
+        readonly format: Format;
+    }): Format extends "bytes" ? Uint8Array : string;
+};
+/**
+ * Synchronously generates a ULID from `Date.now()` and `globalThis.crypto`.
+ *
+ * **Details**
+ *
+ * Below the maximum timestamp, every ULID generated in this JS realm (process
+ * or worker) sorts after the previous one, using the monotonic mode described
+ * on the `SecureRandom` service's `ulid`. The ordering does not hold across
+ * processes or workers. Consecutive ULIDs reveal their generation order, so
+ * never use them as secrets.
+ *
+ * **Gotchas**
+ *
+ * Reads `Date.now()` rather than the `Clock`, and `globalThis.crypto` rather
+ * than the `WebCrypto` reference. A timestamp can run slightly ahead of
+ * `Date.now()` when the clock moves back or the random part overflows.
+ *
+ * @stability unstable
+ * @category unsafe
+ * @since 4.0.0
+ */
+export declare const ulidUnsafe: () => string;
+export {};
+//# sourceMappingURL=SecureRandom.d.ts.map

package/dist/crypto/SecureRandom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SecureRandom.d.ts","sourceRoot":"","sources":["../../src/crypto/SecureRandom.ts"],"names":[],"mappings":"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"}