settlekit/docs/CONFIGURATION.md
2026-06-17 02:09:36 +03:00

366 lines
20 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Configuration Reference
This is the authoritative reference for **every** environment variable read by
SettleKit. It is generated from the actual configuration loaders in the source
tree, not from documentation prose:
| Component | Config source |
| --- | --- |
| API (`apps/api`) | `apps/api/src/config/env.ts`, plus direct `process.env` reads in `src/context.ts`, `src/middleware/auth.ts`, `src/routes/auth.ts`, `src/routes/x402.ts`, `src/server.ts` |
| Worker (`apps/worker`) | `apps/worker/src/config.ts` |
| x402 Gateway (`services/x402-gateway`) | `config.go` |
| Arc Indexer (`services/arc-indexer`) | `src/config.rs` |
| License Gateway (`services/license-gateway`) | `src/config.rs` |
| Webhook Relay (`services/webhook-relay`) | `src/config.rs` |
| Node SDK (`packages/sdk`) | `src/index.ts` |
| Python SDK (`sdks/python`) | `settlekit/_transport.py`, `settlekit/x402.py` |
| Go CLI (`clis/agentpay`) | `internal/client/client.go` |
| Next.js apps (`apps/dashboard`, `checkout`, `marketplace`, `admin`, `docs`, `web`, `portal`) | `process.env.NEXT_PUBLIC_API_URL`, `PORT` |
## How configuration is loaded
### API — every integration is optional
The API loader (`loadConfig` in `apps/api/src/config/env.ts`) is designed so the
API **boots with zero integrations configured**. Each integration group is one
of three states:
- **Absent** — none of the group's keys are set → the in-memory client double in
`apps/api/src/clients/` is used instead of the real integration.
- **Present** — all of the group's required keys are set → the real client is
constructed and a `has*` flag flips to `true`.
- **Partial** — some but not all keys set → boot fails fast with a `ConfigError`
listing exactly which keys to set or unset. This prevents silent half-wired
integrations.
Persistence follows the same rule: set `DATABASE_URL` and the API/worker use
Postgres via `@settlekit/persistence`; leave it unset and they run against a
process-local in-memory store.
### Worker — integrations are required
Unlike the API, the worker (`apps/worker/src/config.ts`) **requires** Arc, email,
GitHub, Discord, file-delivery, license, and the webhook signing secret to be
present, because every background job depends on at least one of them. Missing
required values fail fast at boot with a precise message. `DATABASE_URL` remains
optional (in-memory fallback). Numeric job intervals are range-bounded so a bad
value cannot turn a sweep into a tight CPU loop.
### Services — fail-fast Rust/Go loaders
Each Rust/Go service validates its own environment at startup and refuses to
start on a missing required value or a malformed one (bad port, non-hex address,
zero timeout, etc.).
---
## API (`apps/api`) — port 8787
Built from `apps/api/src/config/env.ts` plus the direct `process.env` reads noted
above.
### Always-present settings (have defaults)
| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `PORT` | no | `8787` | TCP port the API binds to. Range 1–65535. Also read directly in `server.ts`. |
| `LICENSE_TOKEN_SECRET` | no | `settlekit-dev-license-secret` | HMAC secret used to sign license-key tokens. **Override in production.** |
| `WEBHOOK_SIGNING_SECRET` | no | `settlekit-dev-webhook-secret` | HMAC secret used to sign outbound webhook payloads so receivers can verify them. **Override in production.** |
| `AUTH_COOKIE_SECRET` | no | `settlekit-dev-auth-cookie-secret` | HMAC secret used to sign the `sk_session` auth cookie. **Override in production.** |
| `FILE_DOWNLOAD_BASE_URL` | no | `http://localhost:8787/v1/files/download` | Base URL embedded in signed file-download links. |
| `FILE_DOWNLOAD_SECRET` | no | `settlekit-dev-file-secret` | HMAC secret used to sign file-download URLs. **Override in production.** |
| `FILE_DOWNLOAD_EXPIRES_SEC` | no | `3600` | Default lifetime (seconds) of a signed download link. Range 60–2,592,000. |
| `FILE_DOWNLOAD_MAX_DOWNLOADS` | no | `3` | Default max downloads per signed link. Range 1–10,000. |
> Note: the API and worker use **different** env-var names for the file-delivery
> group (`FILE_DOWNLOAD_*` in the API vs `FILE_DELIVERY_*` in the worker). Set
> both if you run both processes.
### Authentication, merchant identity, runtime (direct `process.env`)
| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `API_BOOTSTRAP_KEY` | no | _(unset)_ | Static bootstrap Bearer key accepted by `authMiddleware` so the very first authenticated call can create real API keys. Read in `src/middleware/auth.ts`. Leave unset once real keys exist. |
| `NODE_ENV` | no | _(unset)_ | When `production`, the `sk_session` auth cookie is set `Secure`. Read in `src/routes/auth.ts`. |
| `MERCHANT_NAME` | no | `SettleKit Merchant` | Display name for the merchant identity used on invoices/receipts. Read in `src/context.ts`. |
| `MERCHANT_EMAIL` | no | _(unset)_ | Optional merchant contact email surfaced on invoices/receipts. |
| `MERCHANT_WEBSITE` | no | _(unset)_ | Optional merchant website surfaced on invoices/receipts. |
| `X402_PAY_TO` | no | `0x0000000000000000000000000000000000000000` | Destination USDC address advertised in the `/v1/paid/research` x402 challenge. Read in `src/routes/x402.ts`. Set to your real wallet to actually receive payment. |
### Database (optional group)
| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `DATABASE_URL` | no | _(unset → in-memory)_ | PostgreSQL connection string. When set, the API persists via `@settlekit/persistence` (drizzle, document-projection). When unset, an in-memory store is used. |
### Arc / USDC settlement (optional group — all-or-none)
| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `ARC_RPC_URL` | group | _(unset)_ | JSON-RPC endpoint for the Arc network used to read/verify USDC transfers. Required if any `ARC_*` is set. |
| `ARC_USDC_ADDRESS` | group | _(unset)_ | USDC ERC-20 contract address on Arc. Must be a `0x`-prefixed 20-byte address. Required if any `ARC_*` is set. |
| `ARC_CHAIN_ID` | group | _(unset)_ | Numeric chain id for the Arc network. Range 1–2,147,483,647. Required if any `ARC_*` is set. |
| `ARC_MIN_CONFIRMATIONS` | no | `3` | Confirmations required before a payment is treated as settled. Range 1–1000. |
Setting any one of `ARC_RPC_URL` / `ARC_USDC_ADDRESS` / `ARC_CHAIN_ID` without
the other two fails boot. Without the Arc group, x402 paid endpoints return an
honest rejection (`x402 settlement requires Arc (set ARC_RPC_URL)`).
### Circle (optional group)
| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `CIRCLE_API_KEY` | group | _(unset)_ | Circle API key for Gateway / x402 settlement rails. Presence enables the real Circle client. |
| `CIRCLE_BASE_URL` | no | _(SDK default)_ | Override Circle API base URL (e.g. for sandbox). Only meaningful when `CIRCLE_API_KEY` is set. |
### GitHub App (optional group — all-or-none)
| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `GITHUB_APP_ID` | group | _(unset)_ | Numeric GitHub App id. Range 1–2,147,483,647. |
| `GITHUB_APP_PRIVATE_KEY` | group | _(unset)_ | GitHub App private key (PEM). Use literal `\n` escapes or a single-line PEM. |
| `GITHUB_INSTALLATION_ID` | group | _(unset)_ | Default installation id the API/worker authenticate as. Range 1–2,147,483,647. |
| `GITHUB_WEBHOOK_SECRET` | no | _(unset)_ | Secret used to verify inbound GitHub webhook signatures. Optional within the group. |
Required group keys: `GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY`,
`GITHUB_INSTALLATION_ID`. Setting some but not all fails boot.
### Discord (optional group)
| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `DISCORD_BOT_TOKEN` | group | _(unset)_ | Bot token used to add/remove Discord roles on purchase. Presence enables the real Discord client. |
### Email / Resend (optional group — all-or-none)
| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `RESEND_API_KEY` | group | _(unset)_ | Resend API key for transactional delivery/receipt email. |
| `EMAIL_FROM` | group | _(unset)_ | From address for outbound transactional email. |
Setting one without the other fails boot.
### S3 / R2 object storage (optional group — all-or-none)
| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `S3_BUCKET` | group | _(unset)_ | Bucket holding sellable file assets. |
| `S3_REGION` | group | _(unset)_ | S3/R2 region. Use `auto` for Cloudflare R2. |
| `S3_ACCESS_KEY_ID` | group | _(unset)_ | S3/R2 access key id. |
| `S3_SECRET_ACCESS_KEY` | group | _(unset)_ | S3/R2 secret access key. |
| `S3_ENDPOINT` | no | _(native AWS S3)_ | S3/R2 endpoint URL. Required for R2; omit for native AWS S3. Optional within the group. |
Required group keys: `S3_BUCKET`, `S3_REGION`, `S3_ACCESS_KEY_ID`,
`S3_SECRET_ACCESS_KEY`.
---
## Worker (`apps/worker`)
Built from `apps/worker/src/config.ts`. The worker runs the recurring jobs
(delivery, payment confirmation, access sync, renewals, webhook retry, and the
email sweeps). Required variables fail boot if missing.
### Required integrations
| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `ARC_RPC_URL` | **yes** | — | JSON-RPC endpoint used to confirm on-chain USDC settlement. |
| `ARC_USDC_ADDRESS` | **yes** | — | USDC contract address (`0x` 20-byte). |
| `ARC_CHAIN_ID` | no | `1` | Arc chain id. Range 1–2,147,483,647. |
| `ARC_MIN_CONFIRMATIONS` | no | `3` | Confirmations before a payment is settled. Range 1–1000. |
| `RESEND_API_KEY` | **yes** | — | Resend API key for receipt/reminder/dunning/access emails. |
| `EMAIL_FROM` | no | `SettleKit <receipts@settlekit.dev>` | From address for worker-sent email. |
| `GITHUB_APP_ID` | no | `1` | GitHub App id used for access reconciliation. Range 1–2,147,483,647. |
| `GITHUB_APP_PRIVATE_KEY` | **yes** | — | GitHub App private key (PEM). |
| `GITHUB_INSTALLATION_ID` | no | `1` | Installation id the worker authenticates as. Range 1–2,147,483,647. |
| `DISCORD_BOT_TOKEN` | **yes** | — | Bot token used to revoke/grant Discord roles during access sync. |
| `FILE_DELIVERY_BASE_URL` | **yes** | — | Base URL embedded in worker-generated signed download links. |
| `FILE_DELIVERY_SECRET` | **yes** | — | HMAC secret used to sign worker-generated download URLs. |
| `FILE_DELIVERY_EXPIRES_SEC` | no | `3600` | Signed-link lifetime (seconds). Range 60–2,592,000. |
| `FILE_DELIVERY_MAX_DOWNLOADS` | no | `5` | Max downloads per signed link. Range 1–10,000. |
| `LICENSE_TOKEN_SECRET` | **yes** | — | HMAC secret used to sign license tokens (must match the API). |
| `WEBHOOK_SIGNING_SECRET` | **yes** | — | HMAC secret used to sign outbound webhooks dispatched by delivery actions (must match the API). |
### Subscription / dunning tuning
| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `SUBSCRIPTION_GRACE_DAYS` | no | `3` | Grace window (days) applied when a renewal is missed. Range 1–365. |
| `SUBSCRIPTION_RENEWAL_REMINDER_DAYS` | no | `7` | Send a renewal reminder when `currentPeriodEnd` is within this many days. Range 1–365. |
### Job intervals (milliseconds)
| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `WORKER_DELIVERY_INTERVAL_MS` | no | `5000` | How often pending delivery runs execute. Range 250–3,600,000. |
| `WORKER_PAYMENT_INTERVAL_MS` | no | `10000` | How often pending payments are polled for on-chain confirmation. Range 250–3,600,000. |
| `WORKER_ACCESS_SYNC_INTERVAL_MS` | no | `300000` | How often access is reconciled and expired grants revoked. Range 1,000–86,400,000. |
| `WORKER_RENEWAL_INTERVAL_MS` | no | `600000` | How often subscriptions are advanced/graced/expired. Range 1,000–86,400,000. |
| `WORKER_WEBHOOK_RETRY_INTERVAL_MS` | no | `30000` | How often failed webhooks are redelivered. Range 1,000–86,400,000. |
| `WORKER_RECEIPT_EMAIL_INTERVAL_MS` | no | `60000` | How often confirmed payments are swept for an unsent receipt email. Range 1,000–86,400,000. |
| `WORKER_RENEWAL_REMINDER_INTERVAL_MS` | no | `3600000` | How often upcoming renewals are swept for a reminder email. Range 1,000–86,400,000. |
| `WORKER_DUNNING_EMAIL_INTERVAL_MS` | no | `3600000` | How often grace/past-due subscriptions are swept for a dunning email. Range 1,000–86,400,000. |
| `WORKER_ACCESS_EMAIL_INTERVAL_MS` | no | `60000` | How often succeeded delivery runs are swept for an access-granted email. Range 1,000–86,400,000. |
### Persistence
| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `DATABASE_URL` | no | _(unset → in-memory)_ | Shared Postgres connection. When set, the worker reads/persists to the shared database; when unset it runs against a process-local in-memory store. |
---
## x402 Gateway (`services/x402-gateway`) — Go
Standalone reverse proxy that gates an upstream origin behind an x402 USDC
paywall. Built from `services/x402-gateway/config.go`. Fails fast on any missing
required var or malformed value.
| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `LISTEN_ADDR` | no | `:8402` | TCP address the HTTP server binds to. |
| `UPSTREAM_URL` | **yes** | — | Origin that paid requests are reverse-proxied to. Must be a valid URL. |
| `PRICE` | **yes** | — | Decimal major-unit price owed per call, e.g. `0.005`. Must be a non-negative decimal. |
| `CURRENCY` | no | `USDC` | Settlement asset. Only `USDC` is supported. |
| `NETWORK` | **yes** | — | Chain a payment must settle on. One of `arc`, `base`, `ethereum`. |
| `PAY_TO` | **yes** | — | Destination address payments must be sent to. |
| `PRODUCT_ID` | **yes** | — | Product id attributing the gated call for usage accounting. |
| `RESOURCE` | **yes** | — | Canonical identifier of the protected resource. |
| `VERIFY_URL` | no | _(local verify)_ | When set, a payment proof is POSTed here; the verifier must respond `{ "ok": true }`. Must be a valid URL. |
| `NONCE` | conditional | _(derived)_ | Stable nonce advertised in every challenge. If empty, an HMAC-derived nonce is used instead. |
| `X402_HMAC_SECRET` | conditional | — | Secret that signs derived nonces. **Either `NONCE` or `X402_HMAC_SECRET` must be set**, or boot fails. |
---
## Arc Indexer (`services/arc-indexer`) — Rust
Polls an Arc/EVM node for USDC `Transfer` events to a watched address and posts
confirmations to the SettleKit API. Built from `services/arc-indexer/src/config.rs`.
Addresses are normalized to lowercase `0x` + 40 hex; required vars fail fast.
| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `ARC_RPC_URL` | **yes** | — | JSON-RPC HTTP endpoint of the Arc/EVM node. |
| `ARC_USDC_ADDRESS` | **yes** | — | USDC ERC-20 contract address (20-byte hex, with or without `0x`). |
| `WATCH_ADDRESS` | **yes** | — | Payout address to watch as the `to` of relevant Transfer events. |
| `SETTLEKIT_API_URL` | **yes** | — | Base URL of the SettleKit API (trailing slash trimmed). |
| `SETTLEKIT_API_KEY` | **yes** | — | Bearer API key used to authenticate confirmation requests. |
| `POLL_INTERVAL_SECS` | no | `12` | Seconds between RPC polls. Must be greater than zero. |
| `CONFIRMATIONS` | no | `3` | Confirmations required before a transfer is posted to the API. |
| `START_BLOCK` | no | _(chain head)_ | Optional starting block. When unset, the indexer starts at the chain head. |
---
## License Gateway (`services/license-gateway`) — Rust, port 8090
Edge service that verifies license keys against the SettleKit API with a local
verification cache. Built from `services/license-gateway/src/config.rs`.
| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `SETTLEKIT_API_URL` | no | `http://localhost:8787` | Base URL of the upstream SettleKit API (trailing slash trimmed). |
| `SETTLEKIT_API_KEY` | **yes** | — | Bearer API key used to authenticate against the SettleKit API. |
| `PORT` | no | `8090` | TCP port the gateway binds to. Must be 1–65535. |
| `CACHE_TTL_SECS` | no | `30` | How long a cached verification result remains valid. |
| `REQUEST_TIMEOUT_SECS` | no | `10` | Timeout applied to each upstream HTTP request. Must be greater than zero. |
---
## Webhook Relay (`services/webhook-relay`) — Rust, port 8091
Standalone HMAC-signing webhook fan-out/redelivery service. Built from
`services/webhook-relay/src/config.rs`.
| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `PORT` | no | `8091` | TCP port the HTTP server binds to. |
| `SIGNING_SECRET` | **yes** | — | HMAC-SHA256 secret applied to every outbound delivery body. Must be at least 8 characters. |
| `MAX_RETRIES` | no | `5` | Max delivery attempts per subscriber before giving up. Must be greater than zero. |
| `RETRY_BASE_MS` | no | `500` | Base delay (ms) for the exponential backoff schedule. Must be greater than zero. |
---
## SDKs and CLIs
All first-party SDKs and the CLI resolve the API base URL and key from the same
two environment variables (constructor arguments take precedence).
| Variable | Required | Default | Read by | Purpose |
| --- | --- | --- | --- | --- |
| `SETTLEKIT_API_URL` | no | `http://localhost:8787` | Python SDK, Go CLI (`agentpay`), Arc Indexer, License Gateway; Node SDK by convention | Base URL of the SettleKit HTTP API. |
| `SETTLEKIT_API_KEY` | yes¹ | _(none)_ | Node SDK, Python SDK, Go CLI, Arc Indexer, License Gateway | Bearer token sent as `Authorization: Bearer <key>`. |
¹ Required for authenticated calls. The Python SDK raises if neither an argument
nor `SETTLEKIT_API_KEY` is provided. The Go CLI sends it only when set
(unauthenticated public endpoints work without it).
### Python SDK x402 example helpers (`sdks/python/examples`)
These are read only by the bundled paid-API example, not by the core SDK:
| Variable | Default | Purpose |
| --- | --- | --- |
| `SETTLEKIT_PAY_TO` | `0xYourMerchantWalletAddress` | Destination wallet advertised in the example's x402 challenge. |
| `SETTLEKIT_NETWORK` | `base` | Settlement network for the example. |
| `SETTLEKIT_VERIFY_MODE` | `accept` | Verifier mode; set to `api` to verify proofs against the API. |
---
## Next.js apps (dashboard 3001, marketplace 3002, checkout 3003, admin 3004, docs 3005)
| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `NEXT_PUBLIC_API_URL` | no | `http://localhost:8787` | Public base URL of the SettleKit API, read by the browser-facing Next apps. Must be `NEXT_PUBLIC_*` to be exposed to the client bundle. |
| `PORT` | no | per-app | Listen port when an app is started with `next dev/start -p $PORT`. Default ports: dashboard 3001, marketplace 3002, checkout 3003, admin 3004, docs 3005. |
---
## Quick start
### Minimal local development (in-memory, no integrations)
The API boots with **no** variables set — every integration falls back to its
in-memory double and persistence is in-memory:
```bash
pnpm --filter @settlekit/api dev
```
Optionally pin a port and a bootstrap key so you can create real API keys:
```bash
PORT=8787 API_BOOTSTRAP_KEY=dev_bootstrap_key pnpm --filter @settlekit/api dev
```
### With Postgres persistence
```bash
export DATABASE_URL="postgresql://settlekit:settlekit@localhost:5432/settlekit"
pnpm --filter @settlekit/database db:migrate # or: make db-migrate
pnpm --filter @settlekit/api dev
```
### Production secrets to override
These have insecure development defaults and **must** be set to strong, unique
values in production (and must match between the API and worker where noted):
- `LICENSE_TOKEN_SECRET` (API + worker — must match)
- `WEBHOOK_SIGNING_SECRET` (API + worker — must match)
- `AUTH_COOKIE_SECRET` (API)
- `FILE_DOWNLOAD_SECRET` (API) / `FILE_DELIVERY_SECRET` (worker)
- `SIGNING_SECRET` (webhook-relay, ≥ 8 chars)
- `X402_HMAC_SECRET` (x402-gateway)
- Unset `API_BOOTSTRAP_KEY` once real API keys exist.
### API envelope and auth recap
- Success responses: `{"data": T}`. Errors: `{"error": {"code", "message"}}`.
- Authenticated endpoints require `Authorization: Bearer <apiKey>`.
- x402 paid endpoints under `/v1/paid/*` are public and return HTTP 402 +
`PaymentRequirements` until a valid USDC payment proof is supplied; settlement
is verified on-chain via Arc when `ARC_*` is configured.
</content>
</invoke>