ex_credstash

# Copyright 2026 Relay, Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

defmodule ExCredstash.Config do
  @moduledoc """
  Configuration handling for ExCredstash.

  This module manages configuration options for the credential store,
  including AWS settings, table names, and encryption contexts.

  ## Configuration Priority

  Configuration values are resolved in the following order (highest to lowest priority):
  1. Options passed directly to functions
  2. Application environment (`config.exs`)
  3. Environment variables
  4. Default values

  ## Application Environment

      config :ex_credstash,
        table: "credential-store",
        kms_key: "alias/credstash",
        region: "us-east-1"

  ## Environment Variables

  - `CREDSTASH_DEFAULT_TABLE` - DynamoDB table name
  - `CREDSTASH_KEY_ID` - KMS key ID or alias
  - `AWS_DEFAULT_REGION` or `AWS_REGION` - AWS region

  """

  @default_table "credential-store"
  @default_kms_key "alias/credstash"
  @default_digest :sha256

  @doc """
  Get a configuration value, checking options first, then app config, then env vars.

  Priority: opts > app config > env vars > default

  ## Parameters

    * `opts` - Keyword list of options
    * `key` - Configuration key to look up
    * `default` - Default value if not found (default: nil)

  ## Examples

      iex> ExCredstash.Config.get([table: "my-table"], :table)
      "my-table"

      iex> ExCredstash.Config.get([], :table, "credential-store")
      "credential-store"

  """
  @spec get(keyword(), atom(), term()) :: term()
  def get(opts, key, default \\ nil) do
    case Keyword.get(opts, key) do
      nil ->
        case Application.get_env(:ex_credstash, key) do
          nil -> env_var_for_key(key) || default
          value -> value
        end

      value ->
        value
    end
  end

  @doc """
  Gets the AWS region from configuration.

  Checks in order: opts[:region] > app config > AWS_DEFAULT_REGION > AWS_REGION

  ## Parameters

    * `opts` - Keyword list of options

  ## Returns

  The region string or nil if not configured.

  ## Examples

      iex> ExCredstash.Config.region(region: "eu-west-1")
      "eu-west-1"

  """
  @spec region(keyword()) :: String.t() | nil
  def region(opts \\ []) do
    opts[:region] ||
      Application.get_env(:ex_credstash, :region) ||
      System.get_env("AWS_DEFAULT_REGION") ||
      System.get_env("AWS_REGION")
  end

  @doc """
  Gets the DynamoDB table name from configuration.

  ## Parameters

    * `opts` - Keyword list of options

  ## Returns

  The table name (defaults to "credential-store").

  ## Examples

      iex> ExCredstash.Config.table()
      "credential-store"

      iex> ExCredstash.Config.table(table: "my-creds")
      "my-creds"

  """
  @spec table(keyword()) :: String.t()
  def table(opts \\ []) do
    opts[:table] ||
      Application.get_env(:ex_credstash, :table) ||
      System.get_env("CREDSTASH_DEFAULT_TABLE") ||
      @default_table
  end

  @doc """
  Gets the KMS key ID from configuration.

  ## Parameters

    * `opts` - Keyword list of options

  ## Returns

  The KMS key ID or alias (defaults to "alias/credstash").

  ## Examples

      iex> ExCredstash.Config.kms_key()
      "alias/credstash"

      iex> ExCredstash.Config.kms_key(kms_key: "alias/my-key")
      "alias/my-key"

  """
  @spec kms_key(keyword()) :: String.t()
  def kms_key(opts \\ []) do
    opts[:kms_key] || opts[:key_id] ||
      Application.get_env(:ex_credstash, :kms_key) ||
      Application.get_env(:ex_credstash, :key_id) ||
      System.get_env("CREDSTASH_KEY_ID") ||
      @default_kms_key
  end

  @doc """
  Gets the encryption context from configuration.

  ## Parameters

    * `opts` - Keyword list of options

  ## Returns

  The encryption context map (defaults to empty map).

  ## Examples

      iex> ExCredstash.Config.context()
      %{}

      iex> ExCredstash.Config.context(context: %{"env" => "prod"})
      %{"env" => "prod"}

  """
  @spec context(keyword()) :: map()
  def context(opts \\ []) do
    opts[:context] ||
      Application.get_env(:ex_credstash, :context) ||
      %{}
  end

  @doc """
  Gets the digest algorithm from configuration.

  ## Parameters

    * `opts` - Keyword list of options

  ## Returns

  The digest algorithm atom (defaults to :sha256).

  ## Examples

      iex> ExCredstash.Config.digest()
      :sha256

      iex> ExCredstash.Config.digest(digest: :sha512)
      :sha512

  """
  @spec digest(keyword()) :: atom()
  def digest(opts \\ []) do
    opts[:digest] ||
      Application.get_env(:ex_credstash, :digest) ||
      @default_digest
  end

  @doc """
  Returns the default table name constant.
  """
  @spec default_table() :: String.t()
  def default_table, do: @default_table

  @doc """
  Returns the default KMS key constant.
  """
  @spec default_kms_key() :: String.t()
  def default_kms_key, do: @default_kms_key

  @doc """
  Returns the default digest algorithm constant.
  """
  @spec default_digest() :: atom()
  def default_digest, do: @default_digest

  # Private helpers

  defp env_var_for_key(:table), do: System.get_env("CREDSTASH_DEFAULT_TABLE")
  defp env_var_for_key(:kms_key), do: System.get_env("CREDSTASH_KEY_ID")
  defp env_var_for_key(:key_id), do: System.get_env("CREDSTASH_KEY_ID")

  defp env_var_for_key(:region) do
    System.get_env("AWS_DEFAULT_REGION") || System.get_env("AWS_REGION")
  end

  defp env_var_for_key(_key), do: nil
end