@zapiu/server

Backend contract 1 for Node.js 22+ and Fastify 5.

import { defineBackend, getZapiuContext } from "@zapiu/server";

export default defineBackend({
  register(app) {
    app.get("/api/notes", async (request) => {
      return getZapiuContext(request).services.database.list("notes");
    });
  },
});

The configured compiled entry must default-export an object with runtimeContractVersion: 1 and register(app, context). Wrappers and re-exports are supported. Optional initialize(context) runs once before registration; cleanup() runs on close and failed initialization. The entry must not listen. The platform loads it through @zapiu/server/launcher in a separate application container. @zapiu/server/local provides a credential-free local runtime.

Request context and supported services

getZapiuContext(request) exposes tenantId, appId, environment, userId, requestId, and request-scoped services. Database supports list(table, query) and insert(table, values). Storage supports read(key) and write(key, bytes, contentType) for objects up to 1 MiB. Database reads and storage are scoped to the authenticated owner as well as app and environment. Protected owner fields cannot be supplied on insert.

@zapiu/server/broker obtains identity from the platform over HTTPS using an opaque, five-minute Code App session. The platform issues that session only after its normal authentication and Code Apps permission checks. Each broker operation verifies the session independently, including write permission. Production writes require production permission when the session is issued. Source capability declarations cannot grant access.

Built-in routes

• GET /api/health: public runtime health.
• GET /api/zapiu/context: public application context; validates a bearer session when present and reports authentication errors instead of silently downgrading.
• GET /api/v1/me: authenticated current user, compatible with @zapiu/client.
• GET /api/v1/resources/:table: owner-scoped list with limit/cursor.
• POST /api/v1/resources/:table: schema-validated owner-scoped insert.

The current Code App adapter supports list/create operations. Page SDK record get/update and action APIs are separate contracts and are not supplied here. Reserve /api/ for backend routes. Initialization errors prevent startup. A separate platform transport serves the configured static frontend directory.

Platform setup and security

The control plane requires CODE_APP_BROKER_SECRET (at least 32 random bytes) and a private R2 source bucket for storage. The isolated launcher receives only nonsecret deployment context and the HTTPS broker origin. Signing keys, unrestricted database/storage credentials, and control-plane credentials must never enter an application container. Local runtime managed operations fail with an explicit connection error; they do not use production data.

SDK code is not a security or isolation boundary. The broker enforces scope when application code bypasses this package. Hosting must provide separate application/environment containers, restricted service identities, resource limits, and no shared host filesystem or privileged metadata credentials.