effect 4.0.7 → 4.1.1

package/dist/crypto/SecureRandom.js

@@ -0,0 +1,257 @@
+/**
+ * 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.js";
+import * as Effect from "../Effect.js";
+import * as Ulid from "../internal/ulid.js";
+import * as Uuid from "../internal/uuid.js";
+import * as Layer from "../Layer.js";
+import { WebCrypto } from "./WebCrypto.js";
+/**
+ * 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 class SecureRandom extends /*#__PURE__*/Context.Service()("effect/crypto/SecureRandom") {}
+const checkSize = size => {
+  if (!Number.isSafeInteger(size) || size < 0) {
+    throw new RangeError("size must be a non-negative safe integer");
+  }
+};
+const readUint53 = bytes => (bytes[0] & 0x1f) * 2 ** 48 + bytes[1] * 2 ** 40 + bytes[2] * 2 ** 32 + bytes[3] * 2 ** 24 + bytes[4] * 2 ** 16 + bytes[5] * 2 ** 8 + bytes[6];
+// Draws an integer by rejection sampling over 53-bit (or, for ranges wider than
+// 2^53, 54-bit) draws, so every integer in the range has the same probability.
+const intBetweenUnsafe = (min, max, halfOpen, draw) => {
+  const minInt = Math.ceil(min);
+  const maxInt = Math.floor(max);
+  if (!Number.isSafeInteger(minInt) || !Number.isSafeInteger(maxInt)) {
+    throw new RangeError("bounds must round to safe integers");
+  }
+  if (maxInt - minInt < Number.MAX_SAFE_INTEGER) {
+    // Every intermediate stays below 2^53, and `%` is exact, so the divisions
+    // below are exact without BigInt.
+    const count = maxInt - minInt + (halfOpen ? 0 : 1);
+    if (count <= 0) {
+      throw new RangeError("range must contain at least one integer");
+    }
+    // `+ 0` turns `Math.ceil` of a value in (-1, 0) into 0 instead of -0.
+    if (count === 1) return minInt + 0;
+    const bucketSize = (2 ** 53 - 2 ** 53 % count) / count;
+    const limit = bucketSize * count;
+    while (true) {
+      const value = readUint53(draw());
+      if (value < limit) return minInt + (value - value % bucketSize) / bucketSize;
+    }
+  }
+  // BigInt keeps every integer distinct when the range is wider than 2^53.
+  const lower = BigInt(minInt);
+  const count = BigInt(maxInt) - lower + (halfOpen ? BigInt(0) : BigInt(1));
+  const wide = count > BigInt(1) << BigInt(53);
+  const bucketSize = (wide ? BigInt(1) << BigInt(54) : BigInt(1) << BigInt(53)) / count;
+  const limit = bucketSize * count;
+  while (true) {
+    const bytes = draw();
+    const value = BigInt(readUint53(bytes)) + (wide && (bytes[0] & 0x20) !== 0 ? BigInt(1) << BigInt(53) : BigInt(0));
+    if (value < limit) return Number(lower + value / bucketSize);
+  }
+};
+const makeUuid = (bytes, randomBytes, format) => {
+  const uuid = bytes(randomBytes(16));
+  return format === "bytes" ? uuid : Uuid.stringify(uuid);
+};
+/**
+ * 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 const make = randomBytes => {
+  const randomBytesChecked = size => {
+    checkSize(size);
+    return randomBytes(size);
+  };
+  const draw = () => randomBytes(7);
+  const uuidV7 = Uuid.makeV7Monotonic();
+  const ulid = Ulid.makeMonotonic();
+  const ulidRandomBytes = () => randomBytes(10);
+  return {
+    randomBytes: size => Effect.sync(() => randomBytesChecked(size)),
+    intBetween: (min, max, options) => Effect.sync(() => intBetweenUnsafe(min, max, options?.halfOpen ?? false, draw)),
+    shuffle: elements => Effect.sync(() => {
+      const buffer = Array.from(elements);
+      for (let i = buffer.length - 1; i >= 1; i--) {
+        const index = intBetweenUnsafe(0, i, false, draw);
+        const value = buffer[i];
+        buffer[i] = buffer[index];
+        buffer[index] = value;
+      }
+      return buffer;
+    }),
+    uuidV4: options => Effect.sync(() => makeUuid(Uuid.v4Bytes, randomBytes, options?.format)),
+    uuidV7: options => Effect.clockWith(clock => Effect.sync(() => makeUuid(bytes => uuidV7(clock.currentTimeMillisUnsafe(), bytes), randomBytes, options?.format))),
+    ulid: Effect.clockWith(clock => Effect.sync(() => ulid(clock.currentTimeMillisUnsafe(), ulidRandomBytes)))
+  };
+};
+// `getRandomValues` throws a `QuotaExceededError` above 65,536 bytes.
+const fillRandom = (crypto, size) => {
+  const bytes = new Uint8Array(size);
+  for (let offset = 0; offset < size; offset += 65_536) {
+    crypto.getRandomValues(bytes.subarray(offset, offset + 65_536));
+  }
+  return bytes;
+};
+/**
+ * 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 const layerWebCrypto = /*#__PURE__*/Layer.effect(SecureRandom, /*#__PURE__*/WebCrypto.use(crypto => Effect.succeed(make(size => fillRandom(crypto, size)))));
+/**
+ * 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 const randomBytesUnsafe = size => {
+  checkSize(size);
+  return fillRandom(globalThis.crypto, size);
+};
+/**
+ * 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 const uuidV4Unsafe = options => makeUuid(Uuid.v4Bytes, randomBytesUnsafe, options?.format);
+/**
+ * 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 const uuidV7Unsafe = options => makeUuid(bytes => Uuid.v7Monotonic(Date.now(), bytes), randomBytesUnsafe, options?.format);
+/**
+ * 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 const ulidUnsafe = () => Ulid.monotonic(Date.now(), ulidRandomBytesUnsafe);
+const ulidRandomBytesUnsafe = () => randomBytesUnsafe(10);
+//# sourceMappingURL=SecureRandom.js.map

package/dist/crypto/SecureRandom.js.map

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