lib/forge/hash.ex

defmodule Forge.Hash do
  @moduledoc """
  Hash - SHA-256 hashing utilities for provenance and integrity.
  
  This module provides cryptographic hashing for all artifacts in the
  Forge tournament system. Every artifact receives a SHA-256 hash to
  ensure provenance and detect tampering.
  
  ## Usage
  
      # Hash a string
      {:ok, hash} = Forge.Hash.sha256("source code")
      
      # Hash a file
      {:ok, hash} = Forge.Hash.file("path/to/file.ex")
      
      # Create a hash chain
      chain = Forge.Hash.chain("artifact1", hash1)
      chain = Forge.Hash.chain(chain, hash2)
  """

  @type hash :: binary()
  @type hash_hex :: String.t()

  @doc """
  Computes SHA-256 hash of a binary string.
  
  ## Parameters
    - data: The binary data to hash
    
  ## Returns
    - {:ok, hash} where hash is a 32-byte binary
    - {:error, reason} on failure
  """
  @spec sha256(binary()) :: {:ok, hash()} | {:error, String.t()}
  def sha256(data) when is_binary(data) do
    try do
      hash = :crypto.hash(:sha256, data)
      {:ok, hash}
    rescue
      e -> {:error, "Hash computation failed: #{inspect(e)}"}
    end
  end

  @doc """
  Computes SHA-256 hash of a string (converts to binary first).
  """
  @spec sha256(String.t()) :: {:ok, hash()} | {:error, String.t()}
  def sha256(string) when is_binary(string) or is_list(string) do
    sha256(to_string(string))
  end

  @doc """
  Computes SHA-256 hash of a file.
  
  ## Parameters
    - path: Path to the file
    
  ## Returns
    - {:ok, hash, size} where size is file size in bytes
    - {:error, reason} on failure
  """
  @spec file(String.t()) :: {:ok, hash(), integer()} | {:error, String.t()}
  def file(path) do
    case File.read(path) do
      {:ok, data} ->
        hash = sha256(data)
        size = byte_size(data)
        case hash do
          {:ok, h} -> {:ok, h, size}
          {:error, reason} -> {:error, reason}
        end
      {:error, reason} -> {:error, "File read failed: #{reason}"}
    end
  end

  @doc """
  Creates a hash chain by combining two hashes.
  
  The chain is computed as SHA-256(prev_hash ++ new_hash).
  This creates a tamper-evident chain of artifacts.
  
  ## Parameters
    - prev: Previous hash in the chain (binary or hex string)
    - current: Current hash to add to the chain
    
  ## Returns
    - {:ok, chain_hash} where chain_hash is the new chain hash
  """
  @spec chain(hash() | String.t(), hash() | String.t()) :: {:ok, hash()}
  def chain(prev, current) do
    prev_bin = normalize_hash(prev)
    current_bin = normalize_hash(current)
    sha256(prev_bin ++ current_bin)
  end

  @doc """
  Normalizes a hash to binary format.
  
  Accepts either binary (32 bytes) or hex string (64 characters).
  """
  @spec normalize_hash(hash() | String.t()) :: hash()
  defp normalize_hash(hash) when is_binary(hash) and byte_size(hash) == 32, do: hash
  defp normalize_hash(hash) when is_binary(hash), do: hash
  defp normalize_hash(hash) when is_list(hash), do: list_to_binary(hash)
  defp normalize_hash(hash) when is_binary(hash) do
    cond do
      byte_size(hash) == 32 -> hash
      String.length(hash) == 64 -> Base.decode16!(hash)
      true -> :erlang.hash(:sha256, hash)
    end
  end

  @doc """
  Converts a hash to hexadecimal string representation.
  """
  @spec to_hex(hash()) :: String.t()
  def to_hex(hash) when is_binary(hash), do: Base.encode16(hash)

  @doc """
  Generates a unique artifact ID based on hash and timestamp.
  
  Format: hash_prefix-timestamp-random
  """
  @spec artifact_id(hash() | String.t()) :: String.t()
  def artifact_id(hash) do
    hash_bin = normalize_hash(hash)
    hash_hex = to_hex(hash_bin)
    prefix = String.slice(hash_hex, 0, 8)
    timestamp = DateTime.utc_now() |> DateTime.to_iso8601()
    random = :rand.uniform(1_000_000) |> Integer.to_string(16)
    "#{prefix}-#{timestamp}-#{random}"
  end

  @doc """
  Verifies a hash chain.
  
  Given a chain hash and the previous chain hash, verifies that
  the current hash was properly chained.
  """
  @spec verify_chain(hash(), hash(), hash()) :: boolean()
  def verify_chain(prev_chain, prev_hash, current_hash) do
    expected = chain(prev_hash, current_hash)
    case expected do
      {:ok, expected_hash} -> expected_hash == prev_chain
      {:error, _} -> false
    end
  end
end