.env.example

# arkaik services (M4) — environment variables
#
# ALL variables here are server-only. None are NEXT_PUBLIC_, so none reach the
# browser bundle. The local-first app boots and serves every existing surface
# with all of these UNSET — services simply degrade to absent, they never break
# the client-only app (docs/spec/services.md § Backend — Decision Record).
#
# To enable services locally, copy this file to `.env.local` and fill in values.

# --- Storage (Publik & Synk) --------------------------------------------------
# Postgres connection string. Required by `npm run db:migrate` and every service
# route handler. Neon via Vercel in production; any Postgres for self-hosting
# (Inkognito). Example: postgres://user:password@host:5432/arkaik
DATABASE_URL=

# --- Auth (Synk accounts) -----------------------------------------------------
# Auth.js (NextAuth v5) with GitHub OAuth (docs/spec/services.md § Synk → Auth).
# The sign-in UI stays hidden and every auth route degrades to absent until ALL
# three are set. Auth.js infers AUTH_GITHUB_ID / AUTH_GITHUB_SECRET as the GitHub
# provider's clientId/secret, and signs the session JWT with AUTH_SECRET.
#
# AUTH_SECRET: a random 32+ byte secret. Generate with `npx auth secret` or
#   `openssl rand -base64 33`.
# AUTH_GITHUB_ID / AUTH_GITHUB_SECRET: from a GitHub OAuth App
#   (https://github.com/settings/developers). Set its Authorization callback URL
#   to `<origin>/api/auth/callback/github` — e.g.
#   https://arkaik.app/api/auth/callback/github in production, or
#   http://localhost:3000/api/auth/callback/github for local dev.
AUTH_SECRET=
AUTH_GITHUB_ID=
AUTH_GITHUB_SECRET=

# --- GitHub App (PR-driven acceptance transitions) ----------------------------
# Optional. Without these, /api/github/webhook refuses every delivery and the
# rest of the app is unaffected — PR automation simply does not run.
#
# GITHUB_WEBHOOK_SECRET is the shared secret configured on the GitHub App. Every
# delivery is HMAC-verified against it; a deployment that leaves it unset
# rejects webhooks rather than accepting unauthenticated writes.
# GITHUB_APP_ID / GITHUB_APP_PRIVATE_KEY identify the App when arkaik calls the
# GitHub API back. That happens for exactly ONE reason: a PATH-SCOPED repository
# link (a monorepo, where `apps/ios` is the iOS app and `apps/webapp` is the web
# one) has to read which files a pull request changed to know which link it
# belongs to. Every other repository link resolves from the delivery payload
# alone, so a deployment with no monorepo can leave both of these unset and
# nothing degrades. Where they ARE needed and are missing, the delivery reports
# that in its response instead of guessing a platform.
#
# The App needs no permission beyond the "Pull requests: Read" it already asks
# for — the files endpoint is a pull-request sub-resource — so adding the key
# needs no reinstall.
#
# GITHUB_APP_PRIVATE_KEY is the .pem file's contents, verbatim, including the
# "-----BEGIN" and "-----END" lines. Both formats GitHub and the usual tutorials
# produce (PKCS#1 and PKCS#8) work as-is; do not convert. If your host can only
# store single-line values, literal `\n` escapes are accepted and converted —
# but a base64-encoded copy of the file is not, and is refused with a message
# saying so rather than a crypto stack trace.
GITHUB_WEBHOOK_SECRET=
GITHUB_APP_ID=
GITHUB_APP_PRIVATE_KEY=

# --- Rate limiting ------------------------------------------------------------
# Optional. Keys the HMAC used to hash client IPs for Publik rate limiting
# (lib/services/publik.ts). Falls back to AUTH_SECRET, then a constant — the
# stored value is never a raw address either way.
RATE_LIMIT_SALT=

# Optional. Set to 1 ONLY when arkaik sits behind a reverse proxy that
# overwrites `X-Forwarded-For` / `X-Real-IP` (nginx with `proxy_set_header
# X-Forwarded-For $remote_addr`, Caddy, a cloud load balancer). It tells the
# Publik rate limiter that the first forwarded hop can be believed.
#
# Leave it unset on Vercel: the platform sets its own VERCEL variable, which
# no request can forge, and arkaik trusts the header there automatically.
#
# Leave it unset when arkaik is reachable directly, too. Those headers are then
# written by the caller, who can rotate a random value per request and hand
# itself a fresh rate-limit bucket every time — turning the throttle on the
# UNAUTHENTICATED POST /api/publik into a no-op. Untrusted, every request shares
# one bucket instead: strict, but a self-hosted instance is usually one person
# anyway, and a shared limit beats a limit anyone can walk past.
#
# Setting it while NOT behind such a proxy re-opens exactly that hole, so only
# set it once the proxy is actually in front.
ARKAIK_TRUSTED_PROXY=