Crypto unstable

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 Since v4.0.0 Source

Constructors

make

unstable

Since v4.0.0

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

Example Creating a Crypto service

import { Crypto, Effect } from "effect"

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

await Effect.runPromise(testCrypto.randomBytes(4)) // => new Uint8Array([0, 0, 0, 0])

Models

DigestAlgorithm

type unstable

Since v4.0.0

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"

Example Using a digest algorithm

import { Crypto } from "effect"

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

Services

Crypto

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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/Crypto": "~effect/Crypto";
  readonly random: Effect<number>;
  readonly randomBoolean: Effect<boolean>;
  readonly randomInt: Effect<number>;
  readonly randomULID: 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>>;
  randomUUIDv4(options?: {
    readonly format?: "hex";
  }): Effect<string, PlatformError>;
  randomUUIDv4<Format extends "bytes" | "hex">(options: {
    readonly format: Format;
  }): Effect<Format extends "bytes" ? Uint8Array<ArrayBufferLike> : string, PlatformError>;
  randomUUIDv4(options?: {
    readonly format?: "bytes" | "hex";
  }): Effect<string | Uint8Array<ArrayBufferLike>, PlatformError>;
  randomUUIDv7(options?: {
    readonly format?: "hex";
  }): Effect<string, PlatformError>;
  randomUUIDv7<Format extends "bytes" | "hex">(options: {
    readonly format: Format;
  }): Effect<Format extends "bytes" ? Uint8Array<ArrayBufferLike> : string, PlatformError>;
  randomUUIDv7(options?: {
    readonly format?: "bytes" | "hex";
  }): Effect<string | Uint8Array<ArrayBufferLike>, PlatformError>;
}

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 hash = yield* crypto.digest("SHA-256", bytes)
  return [bytes.length, uuidv4.length, hash.length]
})

await Effect.runPromise(Effect.provide(program, TestCrypto)) // => [16, 36, 16]