SigilGuard.Backend behaviour (SigilGuard v0.2.0)

View Source

Behaviour for SigilGuard processing backends.

All backends must implement this behaviour to be used interchangeably by the SigilGuard API. This enables swapping between different processing strategies:

  • :elixir - Pure Elixir using OTP :crypto (default, safe)
  • :nif - Rust NIF reimplementing SIGIL protocol operations (fastest)

Configuration

config :sigil_guard,
  backend: :elixir  # :elixir | :nif

Example

# Get the configured backend module
backend = SigilGuard.Backend.impl()

# Scan text
{:ok, "safe"} = backend.scan("safe", [])

Summary

Types

backend_module()

Backend module types

backend_type()

Backend configuration atoms

Callbacks

audit_sign_event(event, key, prev_hmac)

Sign an audit event, linking it to the previous event in the chain.

audit_verify_chain(events, key)

Verify the integrity of an audit event chain.

canonical_bytes(identity, verdict, timestamp, nonce_hex)

Produce canonical byte representation for signing.

classify_risk(action, opts)

Classify the risk level of an action.

envelope_sign(identity, verdict, opts)

Sign an envelope.

envelope_verify(envelope, public_key_b64u)

Verify an envelope's signature.

evaluate_policy(action, trust_level, opts)

Evaluate an action against a trust level.

redact(text, hits, opts)

Replace matched regions with replacement hints.

scan(text, opts)

Scan text for sensitive content.

scan_and_redact(text, opts)

Scan and redact in a single pass.

Functions

available?(atom)

Checks if a backend is available on this system.

available_backends()

Returns a list of all available backends on this system.

impl()

Returns the backend implementation module based on configuration.

Types

backend_module()

@type backend_module() :: SigilGuard.Backend.Elixir | SigilGuard.Backend.NIF

Backend module types

backend_type()

@type backend_type() :: :elixir | :nif

Backend configuration atoms

Callbacks

audit_sign_event(event, key, prev_hmac)

@callback audit_sign_event(
  event :: SigilGuard.Audit.t(),
  key :: binary(),
  prev_hmac :: String.t() | nil
) ::
  SigilGuard.Audit.t()

Sign an audit event, linking it to the previous event in the chain.

audit_verify_chain(events, key)

@callback audit_verify_chain(events :: [SigilGuard.Audit.t()], key :: binary()) ::
  :ok | {:broken, non_neg_integer()}

Verify the integrity of an audit event chain.

canonical_bytes(identity, verdict, timestamp, nonce_hex)

@callback canonical_bytes(
  identity :: String.t(),
  verdict :: SigilGuard.Envelope.verdict(),
  timestamp :: String.t(),
  nonce_hex :: String.t()
) :: binary()

Produce canonical byte representation for signing.

classify_risk(action, opts)

@callback classify_risk(action :: String.t(), opts :: keyword()) ::
  SigilGuard.Policy.risk_level()

Classify the risk level of an action.

envelope_sign(identity, verdict, opts)

@callback envelope_sign(
  identity :: String.t(),
  verdict :: SigilGuard.Envelope.verdict(),
  opts :: keyword()
) :: SigilGuard.Envelope.t()

Sign an envelope.

envelope_verify(envelope, public_key_b64u)

@callback envelope_verify(
  envelope :: SigilGuard.Envelope.t(),
  public_key_b64u :: String.t()
) ::
  :ok | {:error, term()}

Verify an envelope's signature.

evaluate_policy(action, trust_level, opts)

@callback evaluate_policy(
  action :: String.t(),
  trust_level :: SigilGuard.Identity.trust_level(),
  opts :: keyword()
) :: SigilGuard.Policy.verdict()

Evaluate an action against a trust level.

redact(text, hits, opts)

@callback redact(
  text :: String.t(),
  hits :: [SigilGuard.Patterns.scan_hit()],
  opts :: keyword()
) ::
  String.t()

Replace matched regions with replacement hints.

scan(text, opts)

@callback scan(text :: String.t(), opts :: keyword()) ::
  {:ok, String.t()} | {:hit, [SigilGuard.Patterns.scan_hit()]}

Scan text for sensitive content.

scan_and_redact(text, opts)

@callback scan_and_redact(text :: String.t(), opts :: keyword()) :: String.t()

Scan and redact in a single pass.

Functions

available?(atom)

@spec available?(backend_type()) :: boolean()

Checks if a backend is available on this system.

Examples

iex> SigilGuard.Backend.available?(:elixir)
true

available_backends()

@spec available_backends() :: [backend_type()]

Returns a list of all available backends on this system.

impl()

@spec impl() :: backend_module()

Returns the backend implementation module based on configuration.

Accepts :elixir, :nif, or a custom module implementing this behaviour. Any other value raises ArgumentError immediately, rather than failing later with UndefinedFunctionError mid-operation.

Examples

iex> SigilGuard.Backend.impl()
SigilGuard.Backend.Elixir