# `Image.Components.Signing`
[🔗](https://github.com/elixir-image/image_components/blob/v0.1.1/lib/image/components/signing.ex#L1)

Client-side HMAC signing for URLs emitted by `Image.Components.URL`.

Functionally equivalent to `Image.Plug.Signing` on the back-end:
HMAC-SHA256 over the path-and-query (with the `sig` parameter
removed), hex-encoded, appended as `?sig=<hex>`. Sign-only — the
back-end verifies. Use this when your `Image.Plug` deployment is
configured with `:signing` and you need the component to emit
authentic URLs.

Self-contained — does not depend on `image_plug`. Both packages
share the wire format, not the code.

### Examples

    iex> path = "/cdn-cgi/image/width=200/photo.jpg"
    iex> signed = Image.Components.Signing.sign(path, ["secret"])
    iex> String.starts_with?(signed, path <> "?sig=")
    true

# `sign`

```elixir
@spec sign(String.t(), [String.t(), ...], keyword()) :: String.t()
```

Signs `path` with the first key in `keys`.

### Arguments

* `path` is the request path (with or without an existing query
  string).

* `keys` is a non-empty list of secret-key strings. The first
  key is used.

### Options

* `:expires_at` — `DateTime` or unix-seconds integer. When set,
  appends `?exp=<unix-seconds>` and signs the result.

### Returns

* The path with `?sig=<hex>` (and optional `?exp=…`) appended.

### Examples

    iex> Image.Components.Signing.sign("/foo.jpg", ["secret"])
    ...> |> String.starts_with?("/foo.jpg?sig=")
    true

    iex> Image.Components.Signing.sign("/foo.jpg?other=1", ["secret"])
    ...> =~ "?other=1&sig="
    true

---

*Consult [api-reference.md](api-reference.md) for complete listing*