Planck.Agent.Secrets behaviour (Planck.Agent v0.1.11)

Copy Markdown View Source

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.

Summary

Types

service()

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

t()

A map of secret key → value pairs.

Callbacks

delete(key)

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

delete_service(host)

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

fetch(key)

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

fetch_all()

Fetch all secrets as a map.

list()

List all stored secret keys.

list_services()

List all configured service rules.

store(key, value)

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

store_service(host, auth_type, credential_key, opts)

Upsert a service rule for the given host.

Types

service()

@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()

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

A map of secret key → value pairs.

Callbacks

delete(key)

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

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

delete_service(host)

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

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

fetch(key)

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

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

fetch_all()

@callback fetch_all() :: t()

Fetch all secrets as a map.

list()

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

List all stored secret keys.

list_services()

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

List all configured service rules.

store(key, value)

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

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

store_service(host, auth_type, credential_key, opts)

@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".