AshHooks.Custody behaviour (AshHooks v3.3.0)

Copy Markdown View Source

Custody of opaque webhook keys. Secret bytes never return to ash_hooks after AshHooks.Custody.store/4.

Material and kinds

material is decoded cryptographic material only: raw HMAC key bytes or an Ed25519 seed. The caller decodes whsec_, whsk_, base64, hex, and provider encodings. Custody never parses wire prefixes or encodings.

  • {:standard_webhooks, :v1}: HMAC-SHA256, 24 to 64 bytes, sign and verify.
  • {:standard_webhooks, :v1a}: Ed25519, exactly a 32-byte seed, sign and verify; its public half may be disclosed.
  • {:sender_hmac, digest}: :sha1, :sha256, :sha384, or :sha512, 1 to 16,384 decoded bytes as issued, verify only. Signing returns {:error, :not_signable}.
  • {:legacy_hmac, :sha256}: at least one byte as issued, with no ceiling, sign and verify. Even prefix-shaped material is stored byte for byte.

Import bounds are not generation policy. Package-generated spec and legacy keys use 32 cryptographically random bytes; sender keys are never generated or admitted to an endpoint slot.

The kind is fixed at store. Every expected_kind is an assertion and must be checked before computing. A mismatch returns {:error, :kind_mismatch}. Verification compares the full decoded MAC in constant time and refuses truncated MACs with {:error, :invalid_signature}.

:unavailable means custody could not answer and is retryable. Every other error is final for that attempt. ash_hooks classifies backend errors without exposing their terms. A callback that raises, exits or throws becomes a contents-free AshHooks.Errors.Unknown.UnknownError, an outage rather than a signature verdict.

References, tenant binding, and destruction

ashhooks chooses `"ahk" <> UUIDv7references, one per slot occupancy; references are never shared. Store is idempotent for the exact reference, material, kind, and tenant. Other reuse of a live reference returns the:ref_exists` error.

A reference is bound globally and atomically to the canonical tenant of its first store or destroy. Reference uniqueness is global, never per tenant. For another tenant, sign, verify, public-key disclosure, and fingerprint return {:error, :unknown_ref} without computing or revealing existence. Store returns :ref_exists for a live reference and :ref_destroyed for a tombstoned reference. Destroy returns {:error, :tenant_mismatch} and changes nothing, leaving the original tenant's key working.

Destroy is idempotent under the bound tenant, succeeds for a never-stored reference, and leaves a permanent tombstone for the life of the custody store. Every later store returns {:error, :ref_destroyed}. Store and destroy of a reference must be linearizable: the second operation sees the first, including a delayed store arriving after destruction. A destroy under A then store under B, or destroy under B of an absent reference then store under A, both refuse store with :ref_destroyed. Store under A then destroy under B refuses destroy with :tenant_mismatch.

Canonical tenants come from canonical_tenant/3, using the owner resource's create-path conversion. Non-multitenant owners use nil. Attribute tenancy supports UUID, UUIDv7, integer, string, and case-insensitive string. For any other type the host supplies custody_tenant_key: {module, function, args}. It receives the cast value followed by args and must return the same UTF-8 binary for values the database treats as equal. This equality contract belongs to the host. tenant_type_supported?/2 lets resource verifiers check coverage at compile time. Context tenancy is unsupported.

Fingerprints

For v1 and v1a, fingerprint/3 returns the first 16 bytes of SHA-256("ash_hooks key fingerprint v1\0" <> kind_label <> "\0" <> key_bytes). The labels are standard_webhooks.v1 and standard_webhooks.v1a. key_bytes is the exact stored HMAC material for v1, and the Ed25519 public key derived from the seed for v1a. Custody returns the digest only; ash_hooks formats "SHA256:" <> unpadded_base64url(digest).

Sender and legacy kinds return {:error, :no_fingerprint}. An unkeyed fingerprint of an as-issued secret could enable offline guessing. Display fingerprints are 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 the correlation-only AshHooks.Telemetry.fingerprint/1.

Custodians can run AshHooks.Custody.Conformance in their test suite against a fresh real store to exercise these contracts.

Summary

Functions

Derives canonical custody text from a tenant and its owner resource.

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

Whether an owner's tenant type has a canonical custody representation.

Types

kind()

@type kind() ::
  {:standard_webhooks, :v1}
  | {:standard_webhooks, :v1a}
  | {:sender_hmac, :sha1 | :sha256 | :sha384 | :sha512}
  | {:legacy_hmac, :sha256}

ref()

@type ref() :: String.t()

tenant()

@type tenant() :: String.t() | nil

Callbacks

destroy(ref, tenant)

@callback destroy(ref(), tenant()) ::
  :ok | {:error, :tenant_mismatch | :unavailable | term()}

fingerprint(ref, tenant, expected_kind)

@callback fingerprint(ref(), tenant(), expected_kind :: kind()) ::
  {:ok, <<_::128>>}
  | {:error,
     :kind_mismatch | :no_fingerprint | :unknown_ref | :unavailable | term()}

public_key(ref, tenant, expected_kind)

@callback public_key(ref(), tenant(), expected_kind :: kind()) ::
  {:ok, binary()}
  | {:error,
     :kind_mismatch | :no_public_half | :unknown_ref | :unavailable | term()}

sign(ref, tenant, expected_kind, input)

@callback sign(ref(), tenant(), expected_kind :: kind(), input :: binary()) ::
  {:ok, binary()}
  | {:error,
     :kind_mismatch | :not_signable | :unknown_ref | :unavailable | term()}

store(ref, material, tenant, kind)

@callback store(ref(), material :: binary(), tenant(), kind()) ::
  :ok
  | {:error,
     :ref_exists | :ref_destroyed | :invalid_material | :unavailable | term()}

verify(ref, tenant, expected_kind, input, mac)

@callback verify(
  ref(),
  tenant(),
  expected_kind :: kind(),
  input :: binary(),
  mac :: binary()
) ::
  :ok
  | {:error,
     :invalid_signature | :kind_mismatch | :unknown_ref | :unavailable | term()}

Functions

canonical_tenant(tenant, owner_resource, opts \\ [])

@spec canonical_tenant(term(), module(), keyword()) ::
  {:ok, tenant()} | {:error, :invalid_tenant | :unsupported_tenant_type}

Derives canonical custody text from a tenant and its owner resource.

Applies Ash.ToTenant.to_tenant/2, the multitenancy parse_attribute, and Ash.Type.cast_input/3 with the tenant attribute's constraints, in that order. UUIDs are lowercase hyphenated text, integers are decimal, strings are exact valid UTF-8, and ci_strings are downcased. Other types require the :custody_tenant_key MFA option described in the module contract.

Returns {:error, :invalid_tenant} for rejected inputs and invalid hook results, or {:error, :unsupported_tenant_type} for uncovered tenant types or unsupported tenancy declarations. Non-multitenant resources return {:ok, nil} without interpreting the supplied tenant. Exceptions raised by application code in Ash.ToTenant, parse_attribute, or custody_tenant_key propagate. Inside an Ash action, such an exception rolls the action back.

display_fingerprint(key)

@spec display_fingerprint(AshHooks.Custody.Key.t()) ::
  {:ok, String.t()} | {:error, struct() | :no_fingerprint}

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

v1 and v1a ask the custodian for the 16-byte digest defined in the module contract. Sender and legacy kinds return {:error, :no_fingerprint} without calling custody. Custody errors become classified package errors, including AshHooks.Errors.Invalid.KeyKindMismatch for a kind mismatch.

Safe to show for securely generated keys. This hash does not protect a weak or predictable secret against offline guessing.

tenant_type_supported?(owner_resource, opts \\ [])

@spec tenant_type_supported?(module() | map(), keyword()) :: boolean()

Whether an owner's tenant type has a canonical custody representation.

Accepts a resource module or the DSL state available to a compile-time verifier. No tenant value or custody call is needed. Other types are covered only with a :custody_tenant_key MFA option. This function checks coverage; it does not install a verifier on a resource.