backend

Imported from bex-co/bex (lego/backend/AGENTS.md). Install upstream with npx skills add bex-co/bex --skill backend. Copyright stays with the author.

backend/AGENTS.md

The backend module (github.com/bex-co/bex/lego/backend) is the business-logic layer. It builds bex-api (cmd/api) — Render-compatible REST/GraphQL/MCP + OpenFGA + API keys + metrics — and the isolated SSH gateway (cmd/ssh-gateway). It imports types/ and never operator/ — it patches App CR intent, the operator converges it. Build/test from here (go build/test ./...); make targets + config/ live in ../operator.

Layout — by feature, not layer

One package per feature: service (business logic) + models + REST/GraphQL/MCP fragments.

• cmd/api/ — bex-api entrypoint (api mcp-stdio / BEX_MCP_STDIO=1 → MCP over stdio)
• cmd/ssh-gateway/ — isolated public-key SSH entrypoint; only Deployment with pods/exec
• internal/core/ — leaf kernel: Base + Identity + sentinels + Authorize gates + TTLCache + Poll workers. Imports CRD types only.
• internal/hmacticket/ — one HMAC envelope for shellticket/sandboxexec/sandboxfiles/agentsessionticket; each flavor owns only Claims. Leaf.
• internal/id/ — typed ids <prefix>-<xid> (id.New(kind), id.WellFormed). Leaf. ADR020
• internal/<feature>/ — apps, logs, metrics, apikeys, sshkeys, postgres, secrets, deploys, events (read VIEW over deploys+audit_events). Each service.go + rest.go/graphql.go/mcp.go.
  • sshgateway — protocol→exec boundary; shared Executor/SessionLimiter/NonceGuard/TargetResolver + nativessh/webshell/sandboxsse/sandboxfiles/agentattach/agentcred; one limiter/guard across transports.
  • authz (OpenFGA core.Checker), gqlutil helper.
• internal/store/ — control-plane Postgres + App-CR projector, opt-in via BEX_CP_DB_URI (ADR003)
• internal/billing/ — Stripe Billing (opt-in BEX_STRIPE_SECRET_KEY), sealed usage_hourly → Customers/Subscriptions, invoices, webhooks.
• internal/api/ — composition root: one auth gate (auth.go) + one REST router / one GraphQL schema / one MCP registry. See internal/api/AGENTS.md.

Rules

• Never import operator/. Cross via types/ + App CR only.
• Ids via internal/id only (id.New(kind)), hyphen-separated; depguard forbids xid elsewhere. ADR020
• One service per feature, three thin fragments, Render-consistent. Verbs live in service.go; fragments map wire formats onto single roots (one schema/router/registry). See internal/api/AGENTS.md.
• Authz seam: single-resource verbs start a, err := s.AuthorizeApp(ctx, core.Rel…, name) (or Database/KeyValue) — fetches + authorizes against resource's OWN LabelTenant. Bare s.Authorize only for List/create. Swept by TestAuthzGuardsEveryVerb + TestFetchByNameUsesTheVerbsOwnRelation. Never split into two gates.
• Target always recorded (ServiceTarget/DatabaseTarget/KeyValueTarget) for events feed; write relations always emit, read only on denial. TestEveryTargetedVerbIsNamedOrExcused enforces vocabulary.
• Workspace from request context (REST ownerId, GraphQL ownerId, MCP workspaceId). Empty → default workspace; non-member → ErrForbidden.
• Store opt-in BEX_CP_DB_URI; unset → bex-api alone.

Environment variables — compact reference

Full meanings + defaults + ADR pointers live in the long descriptions below; this table is the quick lookup (operator/SSR vars → sibling ../operator/AGENTS.md, dashboard/AGENTS.md). Unset ⇒ feature 503/disabled unless noted.

Detailed semantics, ADRs, and startup-fail-closed conditions: see the original per-variable paragraphs in git history or the referenced docs/ADR*.md.