Skip to main content
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.
Never log provider-token responses, vault-value responses, authorization headers, callback codes, or encryption keys.