Crypto

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.

4 exports Added in v4.0.0 Source

Constructors

make

Added in v4.0.0 Source

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.

Signature

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

Models

DigestAlgorithm type

Added in v4.0.0 Source

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.

Signature

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

Services

Crypto

Added in v4.0.0 Source

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: Service<Crypto, Crypto>;

Crypto interface

Added in v4.0.0 Source

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.

Signature

interface Crypto {
  readonly "~effect/platform/Crypto": "~effect/platform/Crypto";
  readonly random: Effect<number>;
  readonly randomBoolean: Effect<boolean>;
  readonly randomInt: Effect<number>;
  readonly randomUUIDv4: Effect<string, PlatformError>;
  readonly randomUUIDv7: Effect<string, PlatformError>;
  digest(
    algorithm: DigestAlgorithm,
    data: Uint8Array,
  ): Effect<Uint8Array<ArrayBufferLike>, PlatformError>;
  nextDoubleUnsafe(): number;
  nextIntUnsafe(): number;
  randomBetween(min: number, max: number): Effect<number>;
  randomBytes(size: number): Effect<Uint8Array<ArrayBufferLike>, PlatformError>;
  randomIntBetween(
    min: number,
    max: number,
    options?: {
      readonly halfOpen?: boolean;
    },
  ): Effect<number>;
  randomShuffle<A>(elements: Iterable<A>): Effect<Array<A>>;
}