@spec decrypt_fields(map()) :: map()

Decrypt sensitive fields in an integration data map after reading.

Only values with the enc:v1: prefix are decrypted. Non-encrypted values are returned as-is for backwards compatibility.

@spec decrypt_fields_with_failures(map()) :: {map(), [String.t()]}

Same as decrypt_fields/1, but also returns the names of any fields that looked encrypted (carried the enc:v1: prefix) yet failed to decrypt under the currently active key.

decrypt_fields/1 drops an undecryptable field entirely — correct for every caller that treats the result as a live credential to use or display, since a caller must never mistake stale ciphertext for a real value. But PhoenixKit.Integrations.resolve_uuid/2 also hands this same map to write paths that merge new attributes onto it and save the result wholesale: for THOSE callers, "absent because it failed to decrypt" and "absent because nothing was ever there" are not the same thing — the first must not be permanently erased by an unrelated write. The returned field-name list lets a write path restore an untouched field's original ciphertext from storage (see PhoenixKit.Integrations.save_setup/4, refresh_access_token/1, exchange_code/4, record_validation/3) without ever exposing that ciphertext as if it were usable.

@spec decrypt_value(String.t() | nil) :: {:ok, String.t() | nil} | {:error, term()}

Decrypt a value produced by encrypt_value/1.

Returns {:ok, plaintext}. A value without the enc:v1: prefix is returned as {:ok, value} unchanged — backwards compatibility with data written before encryption was applied. {:error, :encryption_unavailable} when the value IS prefixed but no encryption key is available (no secret_key_base) — unlike the nil-key path in encrypt_value/1, there is no plaintext to fall back to here, only ciphertext nobody can read right now. {:error, reason} for any other decrypt failure (wrong/rotated key, corrupted ciphertext).

@spec enabled?() :: boolean()

Check if encryption is available and enabled.

True for both the :dedicated and :legacy_secret_key_base tiers — this answers "will values be encrypted at all", not "how well". Use status/0 to distinguish the two.

@spec encrypt_fields(map()) :: map()

Encrypt sensitive fields in an integration data map before saving.

Non-sensitive fields and nil/empty values are left unchanged. Already-encrypted values (with enc:v1: prefix) are not re-encrypted.

@spec encrypt_fields_with_secret(map(), String.t()) :: map()

Encrypts sensitive fields using an EXPLICIT secret, bypassing the configured-key resolution entirely — the rotation primitive.

secret is derived the same way a configured key would be (derive_key/1); this does not read :integrations_encryption_key or secret_key_base. Used by PhoenixKit.Integrations.KeyRotation to write values under a NEW secret before that secret becomes the active configured key — which is the whole point of rotation: the new key must be usable to encrypt before it's the one encryption_key/0 resolves to.

@spec encrypt_value(String.t() | nil) :: String.t() | nil

Encrypt a single value, for callers with a bare field to protect rather than a full encrypt_fields/1-shaped map (e.g. an Ecto schema field like PhoenixKit.Modules.Storage.Bucket.secret_access_key).

Same cipher, key derivation and enc:v1: prefix as encrypt_fields/1. Nil/empty and already-encrypted values (see encrypted?/1) pass through unchanged. When encryption is unavailable (no secret_key_base), the value is stored as plaintext — same as encrypt_fields/1 — but this path logs a warning, since a caller that reaches for single-value encryption is usually protecting something as sensitive as the fields encrypt_fields/1 already covers, and a schema field silently staying plaintext is exactly the gap this API exists to close.

@spec encrypt_value_with_secret(String.t() | nil, String.t()) :: String.t() | nil

Encrypts a single value using an EXPLICIT secret — the single-value counterpart to encrypt_fields_with_secret/2, for the same rotation use case (PhoenixKit.Integrations.KeyRotation re-encrypting PhoenixKit.Settings' restricted setting values, which are stored as a bare value string rather than a value_json map of sensitive fields).

Nil/empty pass through unchanged, same as encrypt_value/1. Unlike encrypt_value/1, does NOT skip already-encrypted input — rotation always calls this with a value it just decrypted under the OLD key, so by the time it reaches here it is plaintext, never still enc:v1:-prefixed.

@spec encrypted?(term()) :: boolean()

Whether value looks like an already-encrypted field value (carries the current enc:v1: prefix).

Used to keep encrypt_value/1 idempotent (never double-encrypt) and to let callers tell an already-migrated field apart from legacy plaintext. Also public so callers outside this module — PhoenixKit.Integrations.KeyRotation detecting which fields were encrypted before a rotation — don't hardcode the prefix literal themselves. A future enc:v2: format only needs to update this one place.

@spec key_diagnosis() :: key_diagnosis()

The active tier and the reason for it. See key_diagnosis/0.

The reasons are ordered by what must be acted on first: an unreadable key store outranks "no dedicated key", because repairing the store may restore the very key the data is encrypted under, while rotating would abandon it.

@spec key_fingerprint() :: {:ok, String.t()} | :none

A short, non-reversible fingerprint of the key currently in use, or :none.

Exists so that key reuse between sites is visible. derive_key/1 is a plain SHA-256 over the secret, so two installs that share a secret_key_base — copied from a template, cloned from a sibling environment, inherited with a config/dev.exs — derive a byte-identical integration key and neither has any way to notice. One compromise then exposes every site that shares it.

Two installs showing the same fingerprint are using the same key.

Comparing two numbers only means something like-for-like

Three things make one site show a fingerprint that is not "its" key, and none of them are visible in the number itself, so always read the tier printed next to it:

• an unreadable key store, so the fallback key is being fingerprinted;
• a dedicated key rejected as too short, same effect;
• encryption disabled, in which case there is no fingerprint at all.

There is also an environment trap. mix phoenix_kit.doctor resolves the key in the task's environment; a key delivered by an env var read in runtime.exs may differ from what the running server holds. A task and an admin page on the same site can therefore disagree. Compare admin page with admin page, or task with task.

What it gives away

Domain-separated from derive_key/1 and truncated, so it is not the key and cannot be turned back into one. It IS a verifier: anyone holding it can test candidate secrets offline.

There is no salt, and there cannot be one — a per-install salt would make two installs with the same key show different numbers, destroying the only thing this is for. What can be raised is the cost per guess, so the digest is iterated (PBKDF2-HMAC-SHA256, 100000 iterations) instead of the two plain hashes it used to be. The prefix is global to PhoenixKit, so a table over common secret_key_base values works against every install at once; iteration makes building that table that many times more expensive, and nothing more. The fingerprint is no stronger than the secret behind it — against a weak, guessable secret it is a verification oracle, which is exactly the situation this feature exists to surface.

Accordingly it is shown on the admin-only system page, and by mix phoenix_kit.doctor only when explicitly asked for: a task's output ends up in CI logs, whose readership is wider than the page's.

@spec key_report() :: key_report()

The complete report for the current state.

@spec key_report(key_signals()) :: key_report()

The verdict for a set of signals — total over the signal space.

Public because the acceptance criterion here is an enumeration: every combination rendered whole and read for self-contradiction. That needs a seam that takes the state rather than discovering it.

Ordered by the tier first, and deliberately

Three rounds ordered the clauses by fault — unreadable store, then short key, then tier — and each round found a state where the fault clause fired over a tier that was working, and announced a fallback that was not happening. The fix each time was to move one clause; the next round found the next one.

The tier is the ground truth: it is which key is protecting the data right now. A fault is a modifier on that, never a replacement for it. So the tier is matched first and the fault second, which has two consequences worth stating:

• no combination of signals can produce a report claiming a fallback while the signals say a dedicated key is in use — not because that combination is argued to be unreachable, but because no clause can say it;
• the verdict is total. Every point in the signal space renders, and the test walks all of them rather than filtering by a reachability rule. Reachability rules were themselves the defect twice: they were reasoned out by whoever reasoned out the code, and they excluded states the code could actually reach.

Within a tier, the faults are ordered by which one an operator must clear first. For the weaker tiers a rejected key outranks an unreadable store, because dedicated_candidate/2 never consults the store while config answers — so repairing the store cannot change anything until the short key is gone.

@spec key_report_message(key_report()) :: String.t()

The report rendered as one sentence, for a log line.

Never includes the fingerprint: a log's readership is wider than the admin page's, and the fingerprint is a verifier against candidate secrets.

@spec key_signals() :: key_signals()

Reads every signal the key verdict depends on, in one pass.

@spec min_dedicated_key_length() :: pos_integer()

Shortest secret accepted as a dedicated key.

Public so mix phoenix_kit.integrations.rotate_key can refuse a --new-key this module would later reject: without the check the rotation "succeeds", the data is re-encrypted, and the app silently drops to a weaker tier on the next restart.

@spec sensitive_fields() :: [String.t()]

Returns the list of field keys that are encrypted.

@spec status() :: key_status()

Reports which secret currently backs the encryption key. See key_status/0.

Never touches the database, and safe to call from a boot hook or a LiveView mount/3. It is no longer pure config introspection: when a key store is configured it may read from it (memoised after the first success). A host-supplied store cannot crash this call — PhoenixKit.Integrations.KeyStore turns a raising store into an error tuple.

@spec warn_if_insecure() :: :ok

Logs a one-time warning when integration credentials are not protected by a dedicated key — called once at boot by PhoenixKit.boot/1. Deliberately silent (no log line) for the healthy :dedicated case; the common, correctly-configured install must produce zero noise here.

An :integrations_encryption_key shorter than the minimum length gets its OWN message rather than being folded into the "no dedicated key" wording below — an operator who set one, just too short, needs different advice than one who never set it, and telling them "no dedicated key is configured" when they configured one is simply false.

Never raises — returns :ok unconditionally.