# Credentials: the management pattern

How `.credentials/` works in this ecology. This doc is **genome**: the same pattern travels in every hubler-net image. Which hosts you actually hold credentials for is **instance data**: it lives on your machine (and in your net's `bindings.json` context), never in a shared image or repo. **Secrets never travel in a container/net image, full stop.**

Authored 2026-07-09 through the bead-orchestrator standardization pass, distilling rules already in force (sources: [remote-access.md](remote-access.md), the `.credentials/` conventions, [conventions.md](conventions.md) "Creating New Sites"). Provenance: [bead-containers/hubler-nets `8df2d1bc`](https://redfish.acequia.io/guerin/.agents/8df2d1bc-e00f-4d0b-91a1-ebcf8f4753a2/2026-07-09/notes/01-first-container-bead-bootstrap.md).

## Layout

`.credentials/` sits at the workspace root, next to your site folders:

```
.credentials/
├── README.md                     # this pattern, in brief
├── refresh.ps1                   # regenerates the manifest below
├── manifest (generated)          # what exists, so agents can discover without reading secrets
├── <site.domain>.json            # one JSON per basic-auth host
├── <site>-token.txt / -jwt.txt   # one file per bearer token
└── .gitignore                    # ignores everything but README/refresh
```

- **Basic-auth host** → `<site.domain>.json`: `{"name", "protocol", "webdav", "host", "port", "user", "pass"}`.
- **Bearer token** → `<site>-token.txt` or `<site>-jwt.txt`, the bare token string only.
- **`_netrc`** (in `$HOME`) for netrc-speaking tools; it matches on **hostname only**, so one entry per hostname and no port/path discrimination. When a JSON file and `_netrc` disagree, treat the JSON as possibly stale and verify before use.
- After adding or changing a credential file, run `powershell .credentials/refresh.ps1` to regenerate the manifest.

## Safety rules (each is a live house rule)

1. **Read the credential file before firing.** Verify host, port, route, and protocol match your target before sending any auth. A JSON's port (e.g. `:2078` WebDAV) and the public HTTPS port serve different stacks.
2. **ONE failed auth, then stop.** Surface the failure to the human; do not retry with variations (fail2ban lockouts hit the human, not you).
3. **Never reuse credentials across machines or domains.** A redfish token never goes to another host; credentials do not migrate between machines. If the credential you need is not in `.credentials/`, ask; never guess or borrow.
4. **Never commit secrets.** `.credentials/`, `.env`, `webdav.json`, API keys: all git-ignored, always. The scaffold's `.gitignore` enforces this; do not weaken it.
5. **Confirm before writing new secrets to disk.** When a human hands you a credential, confirm storage location and form before writing (per [conventions.md](conventions.md) "Creating New Sites").
6. **Genome vs instance.** Docs, scaffolds, and this pattern are shareable. Actual tokens, keys, passwords, and the map of which hosts you can reach are instance data: local to the machine and parciante. An image or repo containing a secret is a leak, even briefly (external caches and indexes keep copies; see conventions.md "External Publication").

## The zero-credential window

A freshly instantiated net has this doc and an **empty** scaffold. Until a human adds the first credential, the agent can read anonymously served resources only; auth-gated `requires` links (for example the served `skills/` tree) will 302. That window is by design: capability arrives with the credential, from the parciante, after instantiation. Do not attempt to close the window by copying credentials from another context (rule 3).

## Forward pointer

At-rest encryption of `.credentials/` (vault namespace, seal/unseal gates, minted short-TTL sub-tokens) is the [key-manager design seed `6a4d9aa5`](https://redfish.acequia.io/guerin/.agents/6a4d9aa5-e939-495f-b4e9-9a47abcd2e93/about.md), dormant as of 2026-07-09 and out of scope here. Today `.credentials/` is plaintext on local disk; the rules above are the whole defense, so hold them.