Credential rules

Use rules to turn a secret binding into a scoped HTTP credential capability. Each rule defines an effect (allow or deny), hosts, methods, and paths.

Rules constrain credential injection only. They do not widen ordinary HTTP(S) connectivity; configure that separately with egress_hosts.

Rule evaluation

Rules are unordered. Matching allow rules are additive, while a matching deny always wins. If a binding has any rules, it is default-deny until an allow rule matches.

For a request carrying a secret placeholder, Stashbase evaluates:

1. deny_hosts; a match denies the destination.
2. Configured egress_hosts.
3. The binding's legacy hosts list when it has no rules, or its rules when it does.
4. Credential injection only after all applicable checks allow the request.

Methods are normalized to uppercase. Query strings are ignored, paths are normalized before matching, and * matches any sequence of path characters. Redirects are independently evaluated, so a credential is never forwarded to a redirect destination without a fresh policy check.

Example: GitHub issue access

egress_hosts = ["api.github.com"]

[secrets.GITHUB_TOKEN]
from = "GITHUB_TOKEN"

[[secrets.GITHUB_TOKEN.rules]]
effect = "allow"
hosts = ["api.github.com"]
methods = ["GET"]
paths = ["/user", "/repos/*/*"]

[[secrets.GITHUB_TOKEN.rules]]
effect = "allow"
hosts = ["api.github.com"]
methods = ["POST", "PATCH"]
paths = ["/repos/*/*/issues", "/repos/*/*/pulls"]

[[secrets.GITHUB_TOKEN.rules]]
effect = "deny"
hosts = ["api.github.com"]
methods = ["DELETE"]
paths = ["*"]

The two allows form a union. For this binding, a GET /user or PATCH /repos/acme/widget/issues request is eligible for injection, while a DELETE request is denied even if another rule could allow it.

Explain a decision

Inspect a proposed request without loading a secret, opening a connection, or starting a proxy:

stashbase agent explain --verbose --profile github \
  --host api.github.com --method GET --path /repos/acme/widget/../widget/issues

--verbose reports the normalized path and matching-rule diagnostics. Use --json for automation.

Legacy host bindings

Existing bindings that set hosts and no rules retain their host-only behavior:

[secrets.GITHUB_TOKEN]
hosts = ["api.github.com"]

Add rules when the credential needs method- or path-level restrictions. See profile configuration for secret sources, headers, and ordinary egress.