AshHooks.Signing (AshHooks v3.3.0)

Copy Markdown View Source

Standard Webhooks signing and verification for v1 (HMAC-SHA256) and v1a (ed25519), over msg_id.timestamp.payload.

Pass the exact payload bytes. headers/4 assembles the webhook ID, timestamp, and signatures; verify/4 validates those headers against the received bytes and enforces a timestamp tolerance by default.

Secret formats:

  • symmetric: whsec_ + base64 of 24 to 64 random bytes (prefix optional, matching the references). sign/4 enforces the 24 to 64 byte band (the emitter's length bound); verification accepts nonempty decoded symmetric secrets, including shorter keys, and rejects malformed base64.
  • asymmetric: whsk_ + base64 of the 32-byte ed25519 seed (signing), whpk_ + base64 of the 32-byte public key (verification). Prefixes are required; they are what verify/4 dispatches on.

headers_for_mode/5 emits :standard, :dual (Standard Webhooks and legacy), or :legacy headers for the delivery runtime. Rotation options include the previous key's signature alongside the current signature.

Signing and header builders also accept AshHooks.Custody.Key values. Their kind selects v1 or v1a independently for each slot. Custody failures return {:error, classified_error}; sender-only kinds return {:error, :kind_not_allowed} before custody is called. Byte clauses retain their existing values and exceptions.

Summary

Functions

Displays a spec key's fingerprint as SHA256: plus unpadded base64url.

A fresh msg_-prefixed webhook id (URL-safe, never contains .).

A fresh whsec_-prefixed secret (24 to 64 decoded bytes, spec band).

A fresh ed25519 keypair as {whsk, whpk}.

The three Standard Webhooks headers. :whsec and/or :whsk select the signature schemes; :previous_whsec / :previous_whsk append the rotated-out key's signature (space-delimited, per the spec's zero-downtime rotation, symmetric and asymmetric alike).

The headers produced for each signing mode

Signs the canonical string with HMAC-SHA256 under a decoded byte secret, returning "v1," <> base64(mac). A custody key selects v1 HMAC or v1a Ed25519 from its kind and returns the corresponding signature string. Custody failures return classified package errors; sender-only kinds return {:error, :kind_not_allowed}.

Signs the canonical string with ed25519 under the seed decoded from a whsk_ byte secret, returning "v1a," <> base64(signature). Invalid byte inputs raise ArgumentError. Custody keys delegate to sign/4: their kind selects v1 or v1a, and failures return its classified errors or {:error, :kind_not_allowed}.

Verifies a webhook's webhook-id / webhook-timestamp / webhook-signature headers against the raw payload.

Types

verify_reason()

@type verify_reason() ::
  :missing_header
  | :invalid_timestamp
  | :timestamp_out_of_tolerance
  | :invalid_signature
  | :invalid_secret

Functions

display_fingerprint(key)

@spec display_fingerprint(term()) :: {:ok, String.t()} | {:error, :not_a_spec_key}

Displays a spec key's fingerprint as SHA256: plus unpadded base64url.

The digest is the first 16 bytes of SHA-256("ash_hooks key fingerprint v1\0" <> kind_label <> "\0" <> key_bytes). whsec_ uses the label standard_webhooks.v1 and its 24 to 64 decoded HMAC bytes. whsk_ and whpk_ use standard_webhooks.v1a and the Ed25519 public key, deriving it first for a 32-byte seed. Both halves of a pair therefore display the same fingerprint. Other inputs return {:error, :not_a_spec_key}.

Safe to show for securely generated keys. This truncated, domain-separated hash does not protect weak or predictable secrets from offline guessing. It is distinct from AshHooks.Telemetry.fingerprint/1, which is for correlation only. Opaque custody keys use AshHooks.Custody.display_fingerprint/1.

generate_msg_id()

@spec generate_msg_id() :: String.t()

A fresh msg_-prefixed webhook id (URL-safe, never contains .).

generate_secret(bytes \\ 32)

@spec generate_secret(pos_integer()) :: String.t()

A fresh whsec_-prefixed secret (24 to 64 decoded bytes, spec band).

generate_signing_keypair()

@spec generate_signing_keypair() :: {String.t(), String.t()}

A fresh ed25519 keypair as {whsk, whpk}.

headers(msg_id, unix_ts, payload, opts \\ [])

@spec headers(String.t(), integer(), binary(), keyword() | AshHooks.Custody.Key.t()) ::
  %{required(String.t()) => String.t()} | {:error, struct() | :kind_not_allowed}

The three Standard Webhooks headers. :whsec and/or :whsk select the signature schemes; :previous_whsec / :previous_whsk append the rotated-out key's signature (space-delimited, per the spec's zero-downtime rotation, symmetric and asymmetric alike).

headers_for_mode(mode, msg_id, unix_ts, body, opts)

@spec headers_for_mode(
  :legacy | :dual | :standard,
  String.t(),
  integer(),
  binary(),
  keyword()
) ::
  %{required(String.t()) => String.t()} | {:error, struct() | :kind_not_allowed}

The headers produced for each signing mode:

  • :standard: the three SW headers.
  • :dual: SW headers PLUS the byte-identical legacy envelope (x-webhook-signature, via AshHooks.Legacy); requires :legacy_secret (dual MEANS both envelopes).
  • :legacy: the legacy envelope only.

Legacy options: :legacy_secret, :legacy_previous_secret. SW options: :whsec, :whsk, :previous_whsec, and :previous_whsk.

sign(msg_id, unix_ts, payload, key)

@spec sign(String.t(), integer(), binary(), String.t() | AshHooks.Custody.Key.t()) ::
  String.t() | {:error, struct() | :kind_not_allowed}

Signs the canonical string with HMAC-SHA256 under a decoded byte secret, returning "v1," <> base64(mac). A custody key selects v1 HMAC or v1a Ed25519 from its kind and returns the corresponding signature string. Custody failures return classified package errors; sender-only kinds return {:error, :kind_not_allowed}.

Raises ArgumentError on invalid inputs; the send path fails loud on config or programming errors.

sign_ed25519(msg_id, unix_ts, payload, key)

@spec sign_ed25519(
  String.t(),
  integer(),
  binary(),
  String.t() | AshHooks.Custody.Key.t()
) ::
  String.t() | {:error, struct() | :kind_not_allowed}

Signs the canonical string with ed25519 under the seed decoded from a whsk_ byte secret, returning "v1a," <> base64(signature). Invalid byte inputs raise ArgumentError. Custody keys delegate to sign/4: their kind selects v1 or v1a, and failures return its classified errors or {:error, :kind_not_allowed}.

verify(payload, headers, secret, opts \\ [])

@spec verify(binary(), map(), String.t(), keyword()) ::
  {:ok, %{id: String.t(), timestamp: integer()}} | {:error, verify_reason()}

Verifies a webhook's webhook-id / webhook-timestamp / webhook-signature headers against the raw payload.

Dispatches on the secret's prefix: whpk_ verifies v1a (ed25519) entries; anything else verifies v1 (HMAC) entries and skips all other version identifiers.

headers is a map with lowercased header names as string keys and single binary values ("webhook-id", "webhook-timestamp", "webhook-signature"), the shape Plug and the inbound seam supply after normalization. Mixed-case keys or multi-value header lists are {:error, :missing_header} (fail closed); callers normalize before this boundary.

Options:

  • :now: integer unix seconds (default System.system_time(:second)).
  • :tolerance: allowed |now - timestamp| in seconds (default 300).
  • :ignore_timestamp: skip the tolerance check (dead-letter re-drives, offline verification); the timestamp must still parse.

Signature verification precedes the timestamp window check in both schemes. A bad signature returns :invalid_signature even when the timestamp is stale.

Returns {:ok, %{id: id, timestamp: ts}} or {:error, reason}. Never raises on hostile input.