Engine API
@samabaasi/engine is the backend: a schema‑validated, multi‑tenant app.json API with auth, RBAC, versioning/rollback, an encrypted credential vault, and (optionally) the NL configurator. It runs over a pluggable store/vault (in‑memory now, Postgres at deploy — see Deployment).
Authentication
Every /api/* request must authenticate. An Authenticator resolves the request to a Principal { tenantId, userId, roles }; the engine scopes all storage to tenantId.
Authorization: Bearer <token> # or:
X-Api-Key: <token>Dev uses an ApiKeyAuthenticator (static key → Principal); production swaps a JWT verifier behind the same interface.
RBAC
| Role | Permissions |
|---|---|
viewer | read app.json, read credential metadata |
editor | + write app.json, generate config |
admin | + write/delete credentials |
Unauthenticated → 401; authenticated but lacking the permission → 403.
Endpoints
| Method | Path | Perm | Description |
|---|---|---|---|
GET | /health | — | Liveness. |
GET | /api/app-json | app-json:read | The tenant's current app.json (404 if none). |
PUT | /api/app-json | app-json:write | Validate (@samabaasi/core) + append a new version. 400 + Zod issues on invalid. |
GET | /api/app-json/versions | app-json:read | Version metadata (no bodies). |
GET | /api/app-json/versions/:v | app-json:read | A specific version. |
POST | /api/app-json/rollback/:v | app-json:write | Append a new version copying v. |
GET | /api/credentials | credentials:read | Credential metadata only — never secret values. |
PUT | /api/credentials/:ref | credentials:write | Store/replace a secret (encrypted at rest). |
DELETE | /api/credentials/:ref | credentials:write | Remove a credential. |
POST | /api/config/natural | config:generate | NL → proposed app.json (dry run; see AI). 501 if no LLM. |
Tenant isolation
Every read/write is filtered by the authenticated tenantId; a second tenant gets a clean 404/empty list, never another tenant's data. At deploy this is reinforced by Postgres Row‑Level Security — defense‑in‑depth on top of the explicit filters.
Validation on write
PUT /api/app-json parses the body with @samabaasi/core. Invalid input returns 400 with the exact Zod issues — the same schema that guards the renderer and the AI generator. The engine never stores an app.json it can't validate.
Versioning & rollback
Each PUT appends an immutable version (createdBy/comment optional). rollback/:v creates a new version copying an old one (history is append‑only — nothing is destroyed). The frontend can show history and revert.
Run it
npx @samabaasi/engine app-json-server # :4000
# with NL config enabled:
ANTHROPIC_API_KEY=sk-ant-... npx @samabaasi/engine app-json-server