Crypto Module

Runtime modules are the built-in capabilities you call from automations on the foundation, and the crypto module is one of them. It provides cryptographic helpers built on Node’s crypto, with no external dependencies. Typical uses: OAuth PKCE, webhook signature verification (HMAC), signed JWT client assertions, and content fingerprints.

sha256 / sha512 / md5

Compute a cryptographic digest of a string.

- 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.

- run:
    module: crypto
    function: hmac
    parameters:
      data: "{{request.rawBody}}"
      # index.yml: config.value.webhookSigningKey: '{{secret.webhook_signing_key}}'
      key: "{{config.webhookSigningKey}}"
      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.

- 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.

- 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).

- 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.

signJwt

Sign a JWT with a private key you supply, for example an OAuth client_assertion (RFC 7523) for certificate-based client authentication.

- run:
    module: crypto
    function: signJwt
    parameters:
      payload:
        aud: "https://login.example.com/oauth2/token"
        iss: "{{config.clientId}}"
        sub: "{{config.clientId}}"
        jti: "{{jti}}"
      key: "{{privateKey}}"
      algorithm: PS256
      expiresIn: 300
    output: signed
- conditions:
    '{{signed.error}}':
      - break:
          scope: automation
          payload:
            error: "{{signed.error}}"
# signed.jwt → "eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCIsIng1dCNTMjU2Ijoi..."

Parameter	Type	Required	Default	Description
payload	object	yes		Claims, signed as given. Serialized size at most 16 KB.
key	string	yes		Private key in PEM (PKCS#8, PKCS#1 or SEC1), or the base64 of that PEM. May be bundled with certificates. At most 64 KB. Encrypted keys are not supported.
algorithm	string	yes		`RS256`, `PS256` (RSA-PSS) or `ES256` (P-256). Nothing else is accepted.
expiresIn	number	no		Lifetime in seconds (positive integer). Sets `iat` and `nbf` to now and `exp` to now + `expiresIn`, overriding the same claims in `payload`.
header	object	no		Extra header fields such as `kid`. `alg` and `typ` cannot be overridden. At most 4 KB.
requireCertificate	boolean	no	`false`	Fail with `missing_certificate` when `key` holds no certificate, so a returned JWT always carries `x5t#S256`.

RSA keys must be 2048 to 4096 bits. When key also contains certificates (in any order, a CA certificate included), the one whose public key matches the private key is used: it must be within its validity period, and its SHA-256 thumbprint is added to the header as x5t#S256. Certificates are only parsed — no chain or trust verification. Returns { jwt } on success. On any input problem it returns { error } instead of failing the instruction, with one of these codes:

Error	Meaning
`invalid_payload`	`payload` is not an object, or `expiresIn` is not a positive integer.
`payload_too_large`	Serialized payload exceeds 16 KB.
`invalid_header`	`header` is not an object, or exceeds 4 KB.
`unsupported_algorithm`	`algorithm` is not `RS256`, `PS256` or `ES256`.
`invalid_key`	No usable private key, an encrypted key, or a key that does not fit the algorithm (RSA for `RS256`/`PS256`, P-256 for `ES256`).
`key_too_large`	Key input exceeds 64 KB, or the RSA key is larger than 4096 bits.
`key_too_small`	RSA key smaller than 2048 bits.
`missing_certificate`	`requireCertificate` is set and `key` holds no certificate.
`certificate_mismatch`	Certificates are present but none matches the private key.
`certificate_expired`	The matching certificate is past its validity period.
`certificate_not_yet_valid`	The matching certificate is not valid yet.

Pass the private key into the calling automation through an argument declared with secret: true, so its value is masked in runtime events (see Protecting sensitive fields). The result never contains the key.

OAuth PKCE example

The two crypto primitives PKCE needs, end to end:

# 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.

Overview

Chat

Agent Creator

Knowledges

Collections

Builder

Governe

Engage

Insights

sha256 / sha512 / md5

hmac

base64Encode / base64Decode

randomBytes

randomUUID

signJwt

OAuth PKCE example

​sha256 / sha512 / md5

​hmac

​base64Encode / base64Decode

​randomBytes

​randomUUID

​signJwt

​OAuth PKCE example

sha256 / sha512 / md5

hmac

base64Encode / base64Decode

randomBytes

randomUUID

signJwt

OAuth PKCE example