erun-blueprint-api

Build a multi-tenant API service

Produce a Go HTTP API service following ERun's blueprint — the same shape erun-backend-api captures: OIDC bearer authentication, tenant resolution from the token iss claim, layered internal/model → internal/repository → internal/service → internal/routes structure, transaction-scoped PostgreSQL security context (SET LOCAL ROLE erun_tenant / SET LOCAL erun.tenant_id), bounded identity-resolution cache, and audit logging on successfully authorized requests.

This skill packages ERun's accumulated best practices for multi-tenant HTTP APIs. Do not freelance the patterns; the conventions encoded here are the contract.

When to use

Trigger on user phrasings such as:

• "build a multi-tenant http api" / "build a multi-tenant backend api"
• "create an erun-backend-api-shaped service"
• "I need a multi-tenant Go api with oidc auth and tenant rls"
• "I need an HTTP API that talks to my erun-backend-db-shaped database"

Prerequisite

This skill assumes the database side already exists or is being built in parallel via the erun-blueprint-rls-db skill. The API expects:

• A PostgreSQL database with erun_tenant and erun_operations roles.
• An erun_current_tenant_id() function backed by session setting erun.tenant_id.
• The bootstrap tables: tenants, tenant_issuers, users, user_external_ids.
• An audit_events table for API/MCP/CLI audit (add via the db skill if missing).

If the database side is not present, run erun-blueprint-rls-db first or confirm with the user that they have an equivalent.

Inputs to collect

1. Module name (e.g. acme-api). Used as the Go module name and directory name.
2. Go module path (e.g. github.com/acme/acme-api). Used in go.mod and import paths.
3. Target directory (default: current working directory).
4. OIDC issuers to accept initially — list of issuer URLs. The first authenticated identity from any of them bootstraps the OPERATIONS tenant on an empty database; subsequent unknown issuers are rejected.
5. Initial domain entities — list of tenant-owned entities (e.g. invoices, customers). For each: route prefix (e.g. /v1/invoices), minimal columns. Empty list is fine — the produced module still has a working whoami endpoint.

Ask once, then proceed.

What gets produced

<module-name>/
├── AGENTS.md
├── go.mod
├── cmd/
│   └── <module-name>/
│       └── main.go                          # process entrypoint
├── server.go                                # HandlerOptions + NewHandler composition
├── auth.go                                  # AuthMiddleware
├── oidc.go                                  # OIDC TokenVerifier (issuer + JWKS)
├── identity_cache.go                        # Identity resolution cache
├── audit.go                                 # AuditLogger interface
├── api_path.go                              # canonical API path helpers
└── internal/
    ├── model/
    │   ├── user.go
    │   └── <user-supplied entities>.go
    ├── repository/
    │   ├── tx.go                            # TxManager — security context wiring
    │   ├── identity.go                      # IdentityRepository — issuer/subject resolution + bootstrap
    │   ├── user.go                          # UserRepository — non-bootstrap user CRUD
    │   ├── audit_event.go                   # AuditEventRepository
    │   ├── permission_authorizer.go         # role_permissions matcher
    │   └── <user-supplied entities>.go
    ├── service/
    │   └── (add a file only when a workflow has real logic)
    └── routes/
        ├── protected.go                     # ProtectedRouteRegistrar type
        ├── whoami.go                        # /v1/whoami
        └── <user-supplied entities>.go

Reference files for the canonical blueprint ship alongside this SKILL.md under templates/. Substitute placeholders, then expand for the user's domain entities.

Conventions (binding)

These come from erun-backend/erun-backend-api/AGENTS.md. Apply every one.

Layer layout

• internal/model/ — DB-mapped entity structs. Used as the shared entity language across all layers. No DTOs, no service entities, no route response types that mirror the same fields.
• internal/repository/ — SQL persistence via Bun. CRUD only. No workflows. Create/Get/List/Update; add Delete only when the product hard-deletes.
• internal/service/ — workflow orchestration only when a workflow has real logic beyond calling one repository method. Do not create the directory until a real service exists.
• internal/routes/ — HTTP adaptation: path values, query parsing, body decoding, status codes, JSON responses.
• server.go is the composition boundary — constructs repos, optional services, routes, middleware, wires them.
• Import direction: routes → (services or repositories) → model. model must not import anything from the API layers.

Authentication

• OIDC bearer token required on every protected route. cmd/<name>/main.go wires the TokenVerifier (JWKS-backed, multi-issuer).
• Authentication middleware: verify token → look up tenant from iss → look up user from (iss, sub) → populate request-scoped security context → call next.
• An unknown issuer is unauthorized — it cannot be mapped to a tenant.
• An unknown (iss, sub) on an empty database may bootstrap the OPERATIONS tenant and first user with ReadAll + WriteAll. Once any tenant exists, unknown identities are rejected, no implicit user creation.
• Treat missing security context inside repository transaction setup as an internal wiring error, not a user-facing 401.

Tenant transaction wiring

Repositories never accept tenant_id as an argument. Instead, TxManager opens a transaction and sets the PostgreSQL security context from the authenticated context:

// Sketch — see templates/repository/tx.go.tmpl for the full version.
func (tm *TxManager) WithTx(ctx context.Context, fn func(*bun.Tx) error) error {
    sec, err := SecurityFromContext(ctx)
    if err != nil {
        return fmt.Errorf("backend: missing security context: %w", err)
    }
    return tm.db.RunInTx(ctx, nil, func(ctx context.Context, tx bun.Tx) error {
        role := "erun_tenant"
        if sec.IsOperations {
            role = "erun_operations"
        }
        if _, err := tx.ExecContext(ctx, "SET LOCAL ROLE "+role); err != nil {
            return err
        }
        if _, err := tx.ExecContext(ctx, "SELECT set_config('erun.tenant_id', ?, true)", sec.TenantID.String()); err != nil {
            return err
        }
        if sec.UserID != uuid.Nil {
            if _, err := tx.ExecContext(ctx, "SELECT set_config('erun.user_id', ?, true)", sec.UserID.String()); err != nil {
                return err
            }
        }
        return fn(&tx)
    })
}

Use Bun ? placeholders inside set_config(...). Do not use $1 PostgreSQL placeholders in Bun-managed queries.

Authorization

• Permissions live in role_permissions as exact (method, path) pairs or regex (method_pattern, path_pattern) patterns.
• Authorization middleware computes the user's effective permissions as the distinct union across all assigned roles, then matches the canonical route template (e.g. /v1/invoices/{invoice_id}) — not the concrete request URL.
• The ReadAll predefined role grants all read-style methods across all paths; WriteAll grants all write-style methods. Route handlers never check role names directly.

Identity resolution cache

• Bounded TTL, positive and negative entries.
• Key by (issuer, external_subject). Never by subject alone.
• Never key by raw bearer token.
• Identity cache decisions never bypass token verification — verify first, then look up cached resolution.
• Cache instance passed through API construction; no package-level mutable globals.

Audit logging

• Audit middleware writes events after token verification, tenant resolution, user resolution, and authorization all succeed.
• Routes never hand-write routine audit events. They are middleware-owned.
• Required fields: tenant_id, erun_user_id, external_user_id, external_issuer_id, type = 'API', api_method, api_path (canonical template, not concrete URL), created_at.
• Audit failures on a non-audit-durability endpoint should log and continue; the audit failure should not surface as a route 500.

Canonical API paths

• Use the route template (/v1/invoices/{invoice_id}) for permission matching and audit logging — never the concrete request URL.
• api_path.go wires the canonical path into request context at registration time, so authentication/authorization/audit middleware can read it.

IDs

• All externally visible IDs are UUIDv7. Generation lives in database defaults (uuidv7()), not application code. Create routes and create repository methods must not accept or generate IDs.

Step-by-step

Step 1 — confirm inputs

Read back: module name, Go module path, target dir, OIDC issuers, initial entities. Ask before producing if anything is unclear.

Step 2 — create directory tree

mkdir -p "${target_dir}/${module}"/{cmd/${module},internal/model,internal/repository,internal/routes}

Skip internal/service/ until a real service exists.

Step 3 — write boilerplate

Copy the reference files verbatim, substituting __MODULE__ (e.g. acme-api) and __MODULE_PATH__ (e.g. github.com/acme/acme-api):

• templates/go.mod.tmpl → ${module}/go.mod
• templates/cmd_main.go.tmpl → ${module}/cmd/${module}/main.go
• templates/server.go.tmpl → ${module}/server.go
• templates/auth.go.tmpl → ${module}/auth.go
• templates/oidc.go.tmpl → ${module}/oidc.go
• templates/identity_cache.go.tmpl → ${module}/identity_cache.go
• templates/audit.go.tmpl → ${module}/audit.go
• templates/api_path.go.tmpl → ${module}/api_path.go
• templates/repository_tx.go.tmpl → ${module}/internal/repository/tx.go
• templates/repository_identity.go.tmpl → ${module}/internal/repository/identity.go
• templates/repository_user.go.tmpl → ${module}/internal/repository/user.go
• templates/repository_audit_event.go.tmpl → ${module}/internal/repository/audit_event.go
• templates/repository_permission_authorizer.go.tmpl → ${module}/internal/repository/permission_authorizer.go
• templates/routes_protected.go.tmpl → ${module}/internal/routes/protected.go
• templates/routes_whoami.go.tmpl → ${module}/internal/routes/whoami.go
• templates/model_user.go.tmpl → ${module}/internal/model/user.go
• templates/AGENTS.md.tmpl → ${module}/AGENTS.md

Step 4 — produce user-supplied entities

For each entity E the user supplied (e.g. invoice, plural invoices, route prefix /v1/invoices):

• internal/model/<entity>.go — Bun-tagged struct with read-only EntityID, TenantID, CreatedAt, UpdatedAt, plus the user's domain columns. Use templates/model_entity.go.tmpl as the shape.
• internal/repository/<entity>.go — Create/Get/List/Update methods using Bun via TxManager.WithTx. Use templates/repository_entity.go.tmpl.
• internal/routes/<entity>.go — RegisterEntityRoutes that wires GET /v1/<entity-plural>, POST /v1/<entity-plural>, GET /v1/<entity-plural>/{<entity>_id}, PATCH /v1/<entity-plural>/{<entity>_id} through the ProtectedRouteRegistrar. Use templates/routes_entity.go.tmpl.

Only add internal/service/<entity>.go when a workflow exists beyond single-repository CRUD.

Step 5 — wire entity routes in server.go

Edit the produced server.go NewHandler to construct the entity repository and register its routes — follow the pattern of RegisterWhoamiRoute already present.

Step 6 — validate

cd "${target_dir}/${module}"
go mod tidy
go build ./...
go test ./...

Run a smoke test against a local PostgreSQL instance configured with the matching erun-backend-db-shaped schema. Confirm:

• GET /healthz returns 204 without a token.
• GET /v1/whoami with no token returns 401.
• GET /v1/whoami with a valid OIDC token returns the resolved user.
• A second valid request from a different (iss, sub) on a freshly bootstrapped database is rejected (no implicit user creation).

Error behaviour

Failure mode	Recovery
Target dir already contains a go.mod	Stop. Offer --force (rewrite) or a new module name. Do not silently overwrite.
User-supplied entity name is singular plural-form ambiguous	Ask for both singular (invoice) and plural (invoices) explicitly. Do not guess.
User-supplied route prefix doesn't start with /v1/	Surface the convention and ask the user to confirm or change.
OIDC issuer list is empty	Stop. Ask for at least one issuer; no point producing an unauthenticated API.
go build fails after generation	Surface the compiler output. Most common cause is module path mismatch — confirm __MODULE_PATH__ substitution.
The matching database doesn't have the bootstrap tables	Surface the missing tables and offer to run erun-blueprint-rls-db first.

Important

• Do not let CLI/MCP modules import this API directly. Shared contracts go in a separate transport-neutral library, not in the API module.
• Do not put workflow names on repositories (UpdateStatus, AdvanceMergeQueue). Repository = CRUD; service = workflow.
• Do not check role names in route handlers. Authorization middleware computes effective permissions from role_permissions.
• Do not generate or accept externally visible IDs in application code. Database defaults own them.
• Do not write audit events from individual route handlers. Middleware owns routine audit.
• Do not bypass TxManager.WithTx. Direct db.Exec calls skip the security context setup and break RLS.
• This skill encodes ERun's accumulated best practices for multi-tenant HTTP APIs; do not negotiate them away to match a user's existing preferences. If the user's existing project conflicts with the blueprint, surface the conflict; do not silently relax the convention.