Crypto.ts

Crypto.ts overview

Defines a platform-independent service for cryptographic operations.

Runtime packages provide concrete implementations backed by the host platform’s cryptography APIs. This module defines the service interface and a constructor from random-byte and digest primitives. The service provides secure random bytes and numbers, UUIDv4 and UUIDv7 generation, shuffling, and SHA message digests.

Since v4.0.0

---

Exports Grouped by Category

• constructors
  • make
• models
  • Crypto (interface)
  • DigestAlgorithm (type alias)
• services
  • Crypto

---

constructors

make

Creates a Crypto service from the primitive implementation, deriving the random generator helpers and UUID generation from those primitives.

When to use

Use to build a Crypto service for a platform integration, test layer, or custom runtime from primitive random-byte and digest operations.

Details

The constructor derives random numbers, booleans, integer ranges, shuffling, and UUID generation from impl.randomBytes. Digest operations delegate to impl.digest.

Gotchas

impl.randomBytes must return cryptographically secure bytes of the requested length. UUID formatting mutates the byte array returned for UUID generation, so the implementation should return a fresh array for each call.

Example (Creating a Crypto service)

import { Crypto, Effect, Layer } from "effect"

const TestCrypto = Layer.succeed(
  Crypto.Crypto,
  Crypto.make({
    randomBytes: (size) => new Uint8Array(size),
    digest: (_algorithm, data) => Effect.succeed(data)
  })
)

Signature

declare const make: (impl: {
  readonly randomBytes: (size: number) => Uint8Array
  readonly digest: (
    algorithm: DigestAlgorithm,
    data: Uint8Array
  ) => Effect.Effect<Uint8Array, PlatformError.PlatformError>
}) => Crypto

Source

Since v4.0.0

models

Crypto (interface)

Platform-agnostic cryptographic operations.

Details

Crypto implementations must use cryptographically secure platform APIs. The random generator helpers are derived by the make constructor from the random methods on this service.

Example (Using cryptographic operations)

import { Crypto, Effect, Layer } from "effect"

const TestCrypto = Layer.succeed(
  Crypto.Crypto,
  Crypto.make({
    randomBytes: (size) => new Uint8Array(size),
    digest: (_algorithm, data) => Effect.succeed(data)
  })
)

const program = Effect.gen(function* () {
  const crypto = yield* Crypto.Crypto
  const bytes = yield* crypto.randomBytes(16)
  const uuidv4 = yield* crypto.randomUUIDv4
  const uuidv7 = yield* crypto.randomUUIDv7
  const hash = yield* crypto.digest("SHA-256", bytes)
  return { uuidv4, uuidv7, hash }
})

Effect.runPromise(Effect.provide(program, TestCrypto))

Signature

export interface Crypto {
  readonly [TypeId]: typeof TypeId

  /**
   * Generates a random integer in the range Number.MIN_SAFE_INTEGER to
   * Number.MAX_SAFE_INTEGER (both inclusive).
   */
  nextIntUnsafe(): number

  /**
   * Generates a random number in the range 0 (inclusive) to 1 (exclusive).
   */
  nextDoubleUnsafe(): number

  /**
   * Generates cryptographically secure random bytes.
   */
  randomBytes(size: number): Effect.Effect<Uint8Array, PlatformError.PlatformError>

  /**
   * Computes a cryptographic digest for the supplied data.
   */
  digest(algorithm: DigestAlgorithm, data: Uint8Array): Effect.Effect<Uint8Array, PlatformError.PlatformError>

  /**
   * Generates a cryptographically secure random number between 0 (inclusive)
   * and 1 (exclusive).
   */
  readonly random: Effect.Effect<number>

  /**
   * Generates a cryptographically secure random boolean.
   */
  readonly randomBoolean: Effect.Effect<boolean>

  /**
   * Generates a cryptographically secure random integer between
   * `Number.MIN_SAFE_INTEGER` and `Number.MAX_SAFE_INTEGER` (both inclusive).
   */
  readonly randomInt: Effect.Effect<number>

  /**
   * Generates a cryptographically secure random number between `min`
   * (inclusive) and `max` (exclusive).
   */
  randomBetween(min: number, max: number): Effect.Effect<number>

  /**
   * Generates a cryptographically secure random integer between `min` and `max`.
   *
   * **Details**
   *
   * The lower bound is rounded up with `Math.ceil` and the upper bound is
   * rounded down with `Math.floor`. By default the range is inclusive; set
   * `options.halfOpen: true` to exclude the upper bound.
   */
  randomIntBetween(
    min: number,
    max: number,
    options?: {
      readonly halfOpen?: boolean | undefined
    }
  ): Effect.Effect<number>

  /**
   * Uses the cryptographically secure random generator to shuffle the supplied
   * iterable.
   */
  randomShuffle<A>(elements: Iterable<A>): Effect.Effect<Array<A>>

  /**
   * Generates a cryptographically secure UUIDv4 string.
   */
  readonly randomUUIDv4: Effect.Effect<string, PlatformError.PlatformError>

  /**
   * Generates a cryptographically secure UUIDv7 string.
   */
  readonly randomUUIDv7: Effect.Effect<string, PlatformError.PlatformError>
}

Source

Since v4.0.0

DigestAlgorithm (type alias)

Digest algorithms supported by the platform Crypto service.

Gotchas

SHA-1 is included for interoperability with existing protocols. Do not use SHA-1 for new security-sensitive designs.

Example (Using a digest algorithm)

import { Crypto } from "effect"

const algorithm: Crypto.DigestAlgorithm = "SHA-256"

Signature

type DigestAlgorithm = "SHA-1" | "SHA-256" | "SHA-384" | "SHA-512"

Source

Since v4.0.0

services

Crypto

Service tag for platform cryptography.

When to use

Use when you need to provide or retrieve the full platform cryptography service from an effect’s context.

Details

Providing this service supplies platform-agnostic cryptographic operations such as hashing, UUID generation, and secure random values.

See

• make for constructing a Crypto service from primitive operations

Signature

declare const Crypto: Context.Service<Crypto, Crypto>

Source

Since v4.0.0