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

# Production security

> Review Hookfish credential boundaries, deployment controls, and production readiness.

Hookfish encrypts stored credentials and enforces broker scopes, but the host
application still owns identity, network exposure, key custody, backups, and
tenant authorization.

## Production checklist

* Generate independent high-entropy `OAUTH_ENCRYPTION_KEY` and
  `HOOKFISH_API_KEY` values.
* Store every secret in the runtime's secret manager.
* Set `OAUTH_REDIRECT_BASE_URL` to the public HTTPS broker origin.
* Register callback URLs returned by `/api/oauth/providers`.
* Keep authenticated raw `/api/*` operations behind a trusted service
  boundary while leaving the provider callback publicly reachable.
* Authenticate users on your application API before calling Hookfish.
* Select a scoped broker token for the current user or tenant in server code.
* Give services scoped, expiring broker tokens instead of the root key.
* Keep provider-token retrieval and vault-value operations server-only.
* Export lifecycle events to an audit or telemetry system.
* Back up the database and encryption key through separate controlled systems.
* Test restoration, scoped-token revocation, and provider reauthorization.

## Stored credentials

Provider access tokens, refresh tokens, dynamic-provider client secrets, and
vault values are encrypted with AES-GCM before database storage. Provider and
connection metadata exclude access tokens, refresh tokens, ID tokens, and
client secrets.

OAuth state is stored only as a SHA-256 hash and expires after ten minutes. A
state record is claimed before code exchange so a completed callback cannot be
replayed concurrently.

## Broker credentials

Scoped tokens are HMAC-signed with `HOOKFISH_API_KEY`. Hookfish stores only a
SHA-256 hash of each token's random identifier and checks the authoritative
database record on every request. This enables immediate revocation and scope
narrowing.

The root key remains a high-impact credential. Keep it out of browser code,
operator screenshots, logs, and shared shell history.

## Application boundary

The browser should call your authenticated application API. After checking the
session and permissions, your server calls Hookfish with the tenant's scoped
broker token. Do not forward that token, provider tokens, or vault values to
the browser.

The optional `/api/client` facade has a restricted route allowlist, but its
application authorizer does not select tenant-specific broker credentials.
Prefer app-owned routes for user-facing, multi-tenant access.

## Database and key recovery

Database backups without `OAUTH_ENCRYPTION_KEY` cannot restore encrypted
credentials. An encryption-key change without re-encrypting existing rows makes
those rows unreadable. Document recovery ownership and keep tested, access-
controlled copies of both inputs.

On Cloudflare Workers, use PostgreSQL through Hyperdrive for production. The
SQLite Durable Objects adapter is experimental.

<Warning>
  Never log provider-token responses, vault-value responses, authorization
  headers, callback codes, or encryption keys.
</Warning>