> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Crypto Module

> Hashing, HMAC, base64 and secure random for automations

The **crypto** module provides cryptographic helpers built on Node's `crypto`, with no external dependencies. Typical uses: **OAuth PKCE**, **webhook signature verification** (HMAC), and content fingerprints.

## sha256 / sha512 / md5

Compute a cryptographic digest of a string.

```yaml theme={null}
- run:
    module: crypto
    function: sha256
    parameters:
      data: "{{code_verifier}}"
      encoding: base64url
    output: challenge
# challenge → base64url SHA-256 (an OAuth PKCE code_challenge)
```

| Parameter | Type   | Required | Default | Description                                            |
| --------- | ------ | -------- | ------- | ------------------------------------------------------ |
| data      | string | yes      |         | Data to hash (non-strings are JSON-stringified first). |
| encoding  | string | no       | hex     | Output encoding: `hex`, `base64`, or `base64url`.      |

Returns the digest as a string. `sha512` and `md5` take the same parameters (`md5` for legacy/etag use only).

## hmac

Compute a keyed HMAC signature — used to sign or verify webhooks.

```yaml theme={null}
- run:
    module: crypto
    function: hmac
    parameters:
      data: "{{request.rawBody}}"
      key: "{{secret.webhook_signing_key}}"
      algorithm: sha256
      encoding: hex
    output: signature
- conditions:
    '{{signature}} = {{request.headers.x-signature}}':
      - comment: signature valid
```

| Parameter | Type   | Required | Default | Description                           |
| --------- | ------ | -------- | ------- | ------------------------------------- |
| data      | string | yes      |         | Data to sign.                         |
| key       | string | yes      |         | Secret key.                           |
| algorithm | string | no       | sha256  | `sha256`, `sha512`, `sha1`, or `md5`. |
| encoding  | string | no       | hex     | `hex`, `base64`, or `base64url`.      |

Returns the signature as a string.

## base64Encode / base64Decode

Encode or decode base64, with an optional URL-safe variant.

```yaml theme={null}
- run:
    module: crypto
    function: base64Encode
    parameters:
      data: "{{payload}}"
      urlSafe: true
    output: encoded
```

| Parameter | Type    | Required | Default | Description                                    |
| --------- | ------- | -------- | ------- | ---------------------------------------------- |
| data      | string  | yes      |         | Data to encode / decode.                       |
| urlSafe   | boolean | no       | false   | Use URL-safe base64 (`-` and `_`, no padding). |

`base64Encode` returns the encoded string; `base64Decode` returns the decoded UTF-8 string.

## randomBytes

Generate cryptographically-secure random bytes — e.g. a PKCE `code_verifier` or a token.

```yaml theme={null}
- run:
    module: crypto
    function: randomBytes
    parameters:
      length: 32
      encoding: base64url
    output: code_verifier
```

| Parameter | Type   | Required | Default   | Description                      |
| --------- | ------ | -------- | --------- | -------------------------------- |
| length    | number | no       | 32        | Number of random bytes.          |
| encoding  | string | no       | base64url | `hex`, `base64`, or `base64url`. |

Returns the random value as a string.

## randomUUID

Generate a canonical random UUID v4 (with dashes).

```yaml theme={null}
- run:
    module: crypto
    function: randomUUID
    output: id
# id → "550e8400-e29b-41d4-a716-446655440000"
```

Takes no parameters. For a dash-free UUID inline in an expression, the `uuid()` helper is also available.

## OAuth PKCE example

The two crypto primitives PKCE needs, end to end:

```yaml theme={null}
# 1. Generate the verifier (secure random, url-safe)
- run:
    module: crypto
    function: randomBytes
    parameters: { length: 32, encoding: base64url }
    output: code_verifier

# 2. Derive the challenge = base64url(sha256(verifier))
- run:
    module: crypto
    function: sha256
    parameters: { data: "{{code_verifier}}", encoding: base64url }
    output: code_challenge
# Send code_challenge (+ method S256) on /authorize;
# send code_verifier on /token.
```