> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zap.wzrd.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets and connections

> Secrets are write-only references, usable only through declared HTTPS connections with allowlisted origins, methods, and path prefixes.

## Write-only secrets

`useSecret("NAME")` produces an opaque reference — never a value. Values are injected only into declared connections after origin, method, path-prefix, agent, and environment checks. They never appear in prompts, logs, templates, snapshots, bundles, manifests, rendered instructions, events, session transcripts, `--json` output, API responses, or env dumps.

```bash theme={null}
zap secret set WEBHOOK_TOKEN --agent transcode --env production --stdin
zap secret list          # names, scopes, last4 only
zap secret remove WEBHOOK_TOKEN --agent transcode --env production
```

Values are encrypted at rest, resolved just-in-time immediately before a request, attached only to that request, and discarded.

## Connections

`defineConnection` allowlists an HTTPS origin, an allowed method list, and a path prefix:

```ts theme={null}
import { bearer, defineConnection, useSecret } from "@wzrdtech/zap-agent";

export const api = defineConnection({
  id: "api",
  origin: "https://api.example.com",
  methods: ["GET", "POST"],
  pathPrefix: "/v1/",
  headers: { Authorization: bearer(useSecret("API_TOKEN")) },
});
```

At request time:

* `fetch` takes relative paths only; absolute URLs fail closed (`CONNECTION_ABSOLUTE_URL`).
* Methods outside the allowlist fail (`CONNECTION_METHOD_DENIED`); paths outside the prefix fail (`CONNECTION_PATH_DENIED`).
* Hard-coding sensitive headers (`Authorization`, `Cookie`, `X-API-Key`) as literals is a build error (`ZAP_BUILD_SECRET_LITERAL`).

Outbound HTTP without a declared connection is denied with `SECRET_SCOPE_DENIED`.

## Redaction

Every resolved key registers with the redaction layer, so any occurrence in logs, run events, or `--json` output is replaced with `[redacted]`:

```ts theme={null}
import { registerSecret, redactingLogger } from "@wzrdtech/zap-runtime";

registerSecret(apiKey);
const log = redactingLogger((line) => process.stdout.write(`${line}\n`));
```