Sigra Auth Integration

Copy Markdown View Source

This guide is the canonical adoption path for composing Chimeway with Sigra authentication notifications — the end-to-end path from dependency to verification for magic link and confirmation code auth flows. For the focused copy-paste notifier and seam recipe, see the Sigra auth blueprint; this guide owns the full integration path while the blueprint owns the recipe.

Responsibility split (SEED-003)

Chimeway orchestrates the when and why: durable notification lifecycle, suppression and preference gates, idempotency, and operator traces you can search at /admin/chimeway.

Sigra owns auth state: token generation, hashed persistence, rate limits, and magic link / confirmation code TTL. Sigra emits auth events; Chimeway does not mutate Sigra records.

This integration is not a Chimeway.Adapter delivery seam — it is a Sigra auth event → Chimeway.trigger/3 bridge only.

1. Dependencies

Add Chimeway and Sigra to your host mix.exs:

def deps do
  [
    {:chimeway, "~> 1.0"},
    sigra_dep()
  ]
end

defp sigra_dep do
  case System.get_env("SIGRA_PATH") do
    nil -> {:sigra, "~> 0.3", optional: true, runtime: false}
    path -> {:sigra, path: path, optional: true, runtime: false}
  end
end

For local development and integration proof, check out the Sigra repo as a sibling and point SIGRA_PATH at it:

SIGRA_PATH=../sigra mix deps.get

Production adopters use {:sigra, "~> 0.3", optional: true, runtime: false} from Hex. Local proof and CI use a sibling checkout pinned to the integration ref documented in MAINTAINING.md.

2. Integration seam

Sigra.Integrations.Chimeway is the cross-repo seam: it lives in the Sigra package, is conditionally compiled when Chimeway is loaded, and bridges Sigra auth events into the Chimeway trigger spine. Hosts activate it through runtime config — no host callback glue is required:

config :sigra,
  chimeway: [enabled: true]

Chimeway orchestrates the when and why of each auth notification: durable attempts, suppression and preference gates, idempotency, and explainable operator traces. Sigra owns auth state — token generation, hashed persistence, rate limits, and magic link / confirmation code TTL. When an auth event fires, Sigra.Integrations.Chimeway resolves the recipient from Sigra domain models and calls Chimeway.trigger/3; Chimeway never mutates Sigra records.

3. Notifier reference

The integration declares two stable notification keys — string identities, not module names:

  • sigra.auth.magic_link — passwordless magic link sign-in
  • sigra.auth.confirmation_code — email confirmation code dispatch

The notifier build/2 callback resolves the magic link URL and the confirmation code at dispatch time, reading from the Sigra repo and host-supplied closures. Sensitive values are reconstructed only at render time — they are never carried in the Chimeway event payload and never persisted to chimeway_events.payload.

4. Auth event triggers

Sigra auth events drive the triggers. On a successful Sigra.Auth.request_magic_link/3 (existing user, not rate-limited), the integration calls Chimeway.trigger/3; the same happens when a confirmation code is generated. Each call passes a stable idempotency_key (so retried auth events deduplicate) and tenant_id (the user id, for tenant-scoped operator search):

Chimeway.trigger(Sigra.Integrations.Chimeway.MagicLinkNotifier, %{user_id: user_id, email: email},
  idempotency_key: "sigra.magic_link:#{user_id}:#{token_inserted_at}",
  tenant_id: user_id,
  correlation_id: correlation_id
)

Do not pass raw_token, magic_link_url, or confirmation_code to Chimeway.trigger/3. Pass identifier-only params (user_id, email, opaque ref). Sensitive data resolves inside notifier build/2 at dispatch time and is never written to chimeway_events.payload.

The trigger params carry only identifiers. The notifier reconstructs the raw token, the magic link URL, and the confirmation code from the Sigra repo at dispatch time, so they never enter Chimeway's durable trace, telemetry meta, or operator surfaces.

5. Verification

Seed the demo host Sigra auth scenario to exercise both flows end-to-end:

DemoHost.Seeds.seed_sigra_auth()

Then run the named proof command:

SIGRA_PATH=../sigra mix verify.sigra

This exercises the Chimeway-root auth lifecycle proof (including the payload-redaction assertions) and the demo host Sigra proof. After seeding, search /admin/chimeway for the auth notification's operator trace and confirm no raw token, magic link URL path segment, or confirmation code appears in the event payload.