Skip to main content
Hookfish encrypts stored credentials and enforces broker scopes. Your host application still owns identity-provider configuration, key custody, backups, and operator access.

​
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 /api/connections/callback/{providerId} for fixed OAuth providers.
  • Leave rawApiOrigins empty unless a server-to-server deployment explicitly requires cross-origin raw API access.
  • Configure auth before exposing /api/client.
  • Verify current tenant membership inside every application auth provider.
  • Give services scoped, expiring broker tokens instead of the root key.
  • Export lifecycle events with subject and tenantId to an audit system.
  • Back up the database and encryption key through separate controlled systems.
  • Test restoration, scoped-token revocation, tenant isolation, and provider reauthorization.

​
Credential boundaries

Hookfish uses three distinct credentials: No browser-facing response contains a provider access token, refresh token, stored API key, OAuth client secret, or broker credential.

​
Tenant isolation

The application auth provider returns a verified subject and tenantId. Hookfish converts the tenant into an internal resource namespace. Browser paths remain relative to that namespace. For each request, Hookfish signs a short-lived capability scoped to the tenant subtree. The raw API independently verifies and enforces that scope. A tenant cannot list, read, authorize, modify, or disconnect another tenant’s paths. OAuth state stores the internal connection namespace and is claimed once before code exchange. The callback remains public because the OAuth provider must reach it, but the one-time state binds the callback to the authorization that created it.

​
Network boundary

The raw /api/* API emits no CORS headers by default. Requests without an Origin, such as trusted server-to-server calls, continue to work with a valid broker credential. rawApiOrigins is a separate exact-origin allowlist. It rejects "*" and is not derived from OAuth redirect trust. CORS is not authentication; every raw operation still requires a valid broker credential. The authenticated /api/client API accepts same-origin calls by default. State-changing requests require an exact trusted Origin. Configure additional origins with clientOrigins only when your application needs them.

​
Operator dashboard

hookfish serve reads the broker credential in the server process, binds to loopback, and issues an ephemeral HttpOnly, SameSite=Strict operator cookie. Its BFF exposes only safe connection-management operations. It does not proxy the raw API or provider-token retrieval. Use application authentication or SSO for remotely hosted operator tools.

​
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. Keep tested, access-controlled copies of both inputs.
Never log connection-access responses, authorization headers, callback codes, application capabilities, or encryption keys.