defmodule Pkcs11ex do
  @moduledoc """
  Hardware-backed digital signatures for Elixir, via PKCS#11.

  This module hosts the **Layer 2** signing primitives — format-agnostic
  `sign_bytes`, `verify_bytes`, `digest`, and `digest_stream`. Format adapters
  (`SignCore.JWS`, `SignCore.PDF`, `SignCore.XML`) build on top.

  See `docs/specs/specs.md` for architecture and `docs/specs/api.md` for the
  full public API specification.

  ## Surface

  Two paths into a sign:

    * **Signer-ref (`:signer`, recommended)** — `signer: {slot_ref, key_ref}`
      resolves through the running `Pkcs11ex.Slot.Server` for that slot,
      which holds the persistent session, applies the configured
      `pin_callback`, and routes through the single-session-pinned model
      from `specs.md` §5.2. Atom shorthand: `signer: :key_ref` resolves
      against `default_slot` from `Pkcs11ex.Application.config/0`.

    * **Explicit (legacy / one-shot)** — pass `module:`, `slot_id:`,
      `key_label:`, and (for token slots) `pin:` directly. Opens a fresh
      session per call. Useful for scripts and tests; production should
      prefer `:signer`.
  """

  alias SignCore.Algorithm
  alias Pkcs11ex.Native

  @type sign_opts :: [
          module: Native.module_resource(),
          slot_id: non_neg_integer(),
          pin: binary() | nil,
          key_label: String.t(),
          alg: atom(),
          encoding_context: :jose | :der
        ]

  @type verify_opts :: [
          module: Native.module_resource(),
          slot_id: non_neg_integer(),
          key_label: String.t(),
          alg: atom(),
          encoding_context: :jose | :der
        ]

  @doc """
  Sign `data` with a hardware-backed key.

  ## Required options
    * `:module` — a `Pkcs11ex.Native` module resource (from `Native.module_load/1`).
    * `:slot_id` — `CK_SLOT_ID` (non-negative integer).
    * `:key_label` — `CKA_LABEL` of the private key on the slot.
    * `:alg` — algorithm atom (e.g., `:PS256`). Must be in the configured
      `:allowed_algs` allowlist; any value outside the allowlist is rejected
      before the NIF is called.

  ## Optional options
    * `:pin` — User PIN for token slots; omit for cloud HSMs that don't require login.
    * `:encoding_context` — `:jose` or `:der`; defaults to `:der`. Controls the
      wire-format encoding of the returned signature for algorithms whose
      encoding differs by context (e.g., ES256 — irrelevant for PS256).
  """
  @spec sign_bytes(iodata(), sign_opts()) :: {:ok, binary()} | {:error, term()}
  def sign_bytes(data, opts) when is_list(opts) do
    with {:ok, alg} <- fetch_alg(opts),
         :ok <- check_alg_allowed(alg),
         {:ok, adapter} <- Algorithm.lookup(alg),
         {:ok, mechanism} <- mechanism_string(adapter, :sign),
         {:ok, raw} <- dispatch_sign(opts, adapter, mechanism, IO.iodata_to_binary(data)),
         ctx <- Keyword.get(opts, :encoding_context, :der),
         {:ok, encoded} <- adapter.encode_signature(raw, ctx) do
      {:ok, encoded}
    end
  end

  @doc """
  Verify a `signature` over `data` using a hardware-backed public key.

  Required options: `:module`, `:slot_id`, `:key_label`, `:alg`.
  Optional: `:encoding_context` (default `:der`).
  """
  @spec verify_bytes(iodata(), binary(), verify_opts()) :: :ok | {:error, term()}
  def verify_bytes(data, signature, opts) when is_binary(signature) and is_list(opts) do
    with {:ok, alg} <- fetch_alg(opts),
         :ok <- check_alg_allowed(alg),
         {:ok, adapter} <- Algorithm.lookup(alg),
         {:ok, mechanism} <- mechanism_string(adapter, :verify),
         ctx <- Keyword.get(opts, :encoding_context, :der),
         {:ok, raw} <- adapter.decode_signature(signature, ctx),
         {:ok, true} <- run_verify(opts, mechanism, IO.iodata_to_binary(data), raw) do
      :ok
    else
      {:error, _} = err -> err
    end
  end

  @doc """
  Returns the version reported by the native bridge.

  Smoke test for the Rustler NIF wiring; returns the `Cargo.toml` package
  version of `pkcs11ex_nif`.
  """
  @spec native_version() :: String.t()
  def native_version, do: Native.version()

  # ---------- Internals ----------

  defp fetch_alg(opts) do
    case Keyword.fetch(opts, :alg) do
      {:ok, alg} when is_atom(alg) -> {:ok, alg}
      _ -> {:error, :missing_alg}
    end
  end

  defp check_alg_allowed(alg) do
    allowed = Application.get_env(:pkcs11ex, :allowed_algs, [:PS256])

    cond do
      alg == :none -> {:error, :disallowed_alg}
      alg in allowed -> :ok
      true -> {:error, :disallowed_alg}
    end
  end

  defp mechanism_string(adapter, :sign), do: {:ok, Atom.to_string(adapter.signing_mechanism())}
  defp mechanism_string(adapter, :verify), do: {:ok, Atom.to_string(adapter.verifying_mechanism())}

  # Choose between the persistent-session signer-ref path (preferred) and the
  # legacy explicit-opts path (per-call session). Signer-ref wins when present.
  defp dispatch_sign(opts, adapter, mechanism, data) do
    cond do
      Keyword.has_key?(opts, :signer) ->
        sign_via_signer(opts, adapter, data)

      Keyword.has_key?(opts, :module) ->
        run_sign(opts, mechanism, data)

      true ->
        {:error, :no_signer_specified}
    end
  end

  defp sign_via_signer(opts, adapter, data) do
    with {:ok, %{slot_ref: slot_ref, key_label: key_label}} <- resolve_signer(opts) do
      sign_opts = Keyword.take(opts, [:pin])

      Pkcs11ex.Slot.sign(slot_ref, key_label, adapter.signing_mechanism(), data, sign_opts)
    end
  end

  defp resolve_signer(opts) do
    case Keyword.fetch!(opts, :signer) do
      {slot_ref, key_ref} when is_atom(slot_ref) and is_atom(key_ref) ->
        resolve_signer_pair(slot_ref, key_ref)

      key_ref when is_atom(key_ref) ->
        case default_slot() do
          nil -> {:error, :no_default_slot}
          slot_ref -> resolve_signer_pair(slot_ref, key_ref)
        end

      other ->
        {:error, {:invalid_signer, other}}
    end
  end

  defp resolve_signer_pair(slot_ref, key_ref) do
    with {:ok, slot_config} <- Pkcs11ex.Slot.Server.get_config(slot_ref),
         keys = slot_config[:keys] || [],
         {:ok, key_entry} <- fetch_key(keys, key_ref),
         {:ok, key_label} <- key_label_from_entry(key_entry) do
      {:ok, %{slot_ref: slot_ref, key_ref: key_ref, key_label: key_label}}
    end
  end

  defp fetch_key(keys, key_ref) do
    case Keyword.fetch(keys, key_ref) do
      {:ok, entry} -> {:ok, entry}
      :error -> {:error, {:key_not_found, key_ref}}
    end
  end

  defp key_label_from_entry(entry) do
    case {entry[:label], entry[:id]} do
      {label, _} when is_binary(label) -> {:ok, label}
      {_, id} when is_binary(id) -> {:ok, id}
      _ -> {:error, :key_has_no_label_or_id}
    end
  end

  defp default_slot do
    Pkcs11ex.Application.config().default_slot
  rescue
    # Application not started — for example in plain-script use of the
    # legacy path without the supervisor. Atom-shorthand :signer requires
    # config; tuple form does not.
    _ -> nil
  end

  defp run_sign(opts, mechanism, data) do
    module = Keyword.fetch!(opts, :module)
    slot_id = Keyword.fetch!(opts, :slot_id)
    pin = Keyword.get(opts, :pin, "") || ""
    key_label = Keyword.fetch!(opts, :key_label)

    # NIF returns `Result<Vec<u8>, Error>`; Rustler 0.37 encodes Vec<u8>
    # as an Erlang list, hence the IO.iodata_to_binary normalisation here.
    case Native.sign(module, slot_id, pin, mechanism, key_label, data) do
      {:ok, sig} -> {:ok, IO.iodata_to_binary(sig)}
      {:error, _} = err -> err
    end
  end

  defp run_verify(opts, mechanism, data, signature) do
    module = Keyword.fetch!(opts, :module)
    slot_id = Keyword.fetch!(opts, :slot_id)
    key_label = Keyword.fetch!(opts, :key_label)

    case Native.verify(module, slot_id, mechanism, key_label, data, signature) do
      {:ok, true} -> {:ok, true}
      {:error, _} = err -> err
    end
  end
end