# `Planck.Agent.Secrets`
[🔗](https://github.com/alexdesousa/planck/blob/v0.2.2/lib/planck/agent/secrets.ex#L1)

Behaviour for secret storage and service rule management in Planck.

Declare the implementation module in `config.json`:

    { "secrets_hook": "Sidecar.Secrets.AgentVault" }

When not set, `Planck.Headless.Secrets.EnvFile` is used — reads and writes
`.planck/.env` and `~/.planck/.env`.

Both `planck_headless` and the sidecar depend on `planck_agent`, so
implementations in either package can reference this behaviour at compile time.

## Service rules

Service rules tell the credential proxy which credentials to inject for
outbound requests to a given host. The proxy injects unconditionally —
the agent makes plain HTTP calls with no credential knowledge required.

Rules are stored alongside credentials: `EnvFile` uses `# planck-service:`
comment lines in `.env`; `AgentVault` uses the vault service rules API.

# `service`

```elixir
@type service() :: %{
  host: String.t(),
  auth_type: String.t(),
  credential_key: String.t(),
  header: String.t() | nil
}
```

A service rule that tells the credential proxy to inject a credential for
all requests to the given host.

- `auth_type` — `"bearer"` (Authorization header) or `"api-key"` (custom header)
- `header` — the header name for `api-key` type (e.g. `"x-api-key"`); `nil` for bearer

# `t`

```elixir
@type t() :: %{optional(String.t()) => String.t()}
```

A map of secret key → value pairs.

# `delete`

```elixir
@callback delete(key :: String.t()) :: :ok | {:error, term()}
```

Delete a secret by key. No-op if not found.

# `delete_service`

```elixir
@callback delete_service(host :: String.t()) :: :ok | {:error, term()}
```

Delete the service rule for the given host. No-op if not found.

# `fetch`

```elixir
@callback fetch(key :: String.t()) :: {:ok, String.t()} | :not_found | {:error, term()}
```

Fetch a secret by key. Returns `:not_found` when absent.

# `fetch_all`

```elixir
@callback fetch_all() :: t()
```

Fetch all secrets as a map.

# `list`

```elixir
@callback list() :: {:ok, [String.t()]} | {:error, term()}
```

List all stored secret keys.

# `list_services`

```elixir
@callback list_services() :: {:ok, [service()]} | {:error, term()}
```

List all configured service rules.

# `store`

```elixir
@callback store(key :: String.t(), value :: String.t()) :: :ok | {:error, term()}
```

Store a secret. Overwrites any existing value for the same key.

# `store_service`

```elixir
@callback store_service(
  host :: String.t(),
  auth_type :: String.t(),
  credential_key :: String.t(),
  opts :: keyword()
) :: :ok | {:error, term()}
```

Upsert a service rule for the given host.

`opts` may include `header: String.t()` when `auth_type` is `"api-key"`.

---

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