@rubriclab/rubrot-api 0.1.0

package/README.md

@@ -0,0 +1,39 @@
+# @rubriclab/rubrot-api
+
+The fleet's API contract layer, folded together from the metal `/api/v1` `_lib` (structured errors, zod parsing, pagination — its error shape is THE standard) and vault's `api-handler` (fail-closed authenticated wrappers, generalized to an injected authenticator). Ships as TypeScript source; peer dep is `zod` only. No framework imports — handlers take a plain `Request`, so Next 16 route files export them directly.
+
+## The contract
+
+Every failure body is `{ error: { code, message } }` with a stable `ApiErrorCode` (`AUTH_MISSING`, `AUTH_INVALID`, `SCOPE_MISSING`, `BAD_REQUEST`, `INVALID_JSON`, `NOT_FOUND`, `UPSTREAM_CONTRACT`, `UPSTREAM_ERROR`, `INTERNAL`). Every response built here — success or failure — carries `cache-control: no-store`.
+
+```
+jsonError(code, message, status)       structured failure
+apiJson(data, status?)                 non-cached JSON success
+apiText(body, status?)                 non-cached text/plain (dotenv projections)
+parseRequestJson(request, contract)    JSON + zod in one step → data | ready 400
+zodMessage(error)                      first issue, offending field named
+parsePagination(request)               ?limit=&offset= via strict contract → data | ready 400
+pageItems / pageLimitOnlyItems         { items, pagination } envelope (exact / count-free total)
+limitForOffset(query)                  SQL LIMIT with the next-page sentinel row
+```
+
+## Authenticated routes
+
+`withAuth(authenticate, handler)` collapses what every route must get right — the auth gate, `no-store`, and fail-closed errors (a thrown handler logs and returns a clean structured 500, never a leak) — into one place. The authenticator is injected: header in, `{ ok, identity } | { ok: false, status, error, code? }` out. On failure, `code` defaults by status (403 → `SCOPE_MISSING`, else `AUTH_INVALID`).
+
+```ts
+// lib/api.ts — bind once per app
+import { createApiAuth } from "@rubriclab/rubrot-api";
+export const api = createApiAuth({
+  read: (authorization) => authenticateBearer(/* app's engine */),
+  write: (authorization) => authenticateBearer(/* required: "write"/"operate" */),
+});
+
+// app/api/v1/machines/[id]/route.ts
+export const GET = api.withRead<{ id: string }>(async (request, identity, ctx) => {
+  const { id } = await ctx.params;
+  return apiJson(await getMachine(id));
+});
+```
+
+What "read" vs "write" means (ranked floor, orthogonal capability) is the authenticator's business — pair with `@rubriclab/rubrot-tokens`.

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@rubriclab/rubrot-api",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "The fleet's API contract layer: structured errors, zod request parsing, pagination, and fail-closed authenticated route wrappers",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/RubricLab/Rubrot.git",
+    "directory": "packages/api"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  }
+}

package/src/handler.ts

@@ -0,0 +1,103 @@
+import { type ApiErrorCode, jsonError } from "./json";
+
+/**
+ * The shared handler harness — vault's `withRead`/`withWrite` pattern with the
+ * auth check INJECTED, so each app supplies its own authenticator (a service
+ * token gate, a session cookie, an HMAC check) and keeps the three things
+ * every route must get right in one audited place:
+ *
+ *   1. Authentication for the RIGHT capability — the structural gate.
+ *   2. `no-store` on every path — a vended secret is never cached en route.
+ *   3. FAIL-CLOSED error handling — a handler that throws never leaks an
+ *      internal error or a non-JSON body; it logs and returns a clean
+ *      structured 500.
+ *
+ * The payoff: a consumer always gets parseable `{ error: { code, message } }`
+ * JSON on every failure path, the auth gate is impossible to forget on a new
+ * route, and a new endpoint is a few lines of real logic.
+ */
+
+/** The context Next.js passes a dynamic route — params resolve lazily. */
+export type RouteContext<P = Record<string, string | string[]>> = {
+  params: Promise<P>;
+};
+
+/** An authentication failure; `code` defaults by status when omitted. */
+export type AuthFailure = {
+  ok: false;
+  status: number;
+  error: string;
+  code?: ApiErrorCode;
+};
+
+export type AuthResult<Identity> =
+  | { ok: true; identity: Identity }
+  | AuthFailure;
+
+/**
+ * The injected auth check: raw `Authorization` header in, verdict out. Apps
+ * bind this to their own token engine (e.g. rubrot-tokens' authenticateBearer)
+ * — the wrapper never sees credentials, only the verdict.
+ */
+export type Authenticator<Identity> = (
+  authorization: string | null,
+) => Promise<AuthResult<Identity>>;
+
+export type AuthedHandler<Identity, P = Record<string, string | string[]>> = (
+  request: Request,
+  identity: Identity,
+  context: RouteContext<P>,
+) => Promise<Response>;
+
+function failureCode(failure: AuthFailure): ApiErrorCode {
+  if (failure.code) return failure.code;
+  return failure.status === 403 ? "SCOPE_MISSING" : "AUTH_INVALID";
+}
+
+/**
+ * The core wrapper: authenticate with `authenticate`, then run the handler
+ * under a fail-closed catch. An auth failure and a thrown handler both resolve
+ * to the canonical structured error — never an unstructured 500.
+ */
+export function withAuth<Identity, P = Record<string, string | string[]>>(
+  authenticate: Authenticator<Identity>,
+  handler: AuthedHandler<Identity, P>,
+): (request: Request, context: RouteContext<P>) => Promise<Response> {
+  return async (request, context) => {
+    const auth = await authenticate(request.headers.get("authorization"));
+    if (!auth.ok) return jsonError(failureCode(auth), auth.error, auth.status);
+    try {
+      return await handler(request, auth.identity, context);
+    } catch (error) {
+      console.error("[api] handler error", error);
+      return jsonError("INTERNAL", "internal error", 500);
+    }
+  };
+}
+
+export type ApiAuth<Identity> = {
+  /** Wrap a READ endpoint — every list/view/projection path. */
+  withRead: <P = Record<string, string | string[]>>(
+    handler: AuthedHandler<Identity, P>,
+  ) => (request: Request, context: RouteContext<P>) => Promise<Response>;
+  /** Wrap a WRITE endpoint — the provision/mutate path. */
+  withWrite: <P = Record<string, string | string[]>>(
+    handler: AuthedHandler<Identity, P>,
+  ) => (request: Request, context: RouteContext<P>) => Promise<Response>;
+};
+
+/**
+ * Bind read/write authenticators once (per app, in one lib file) and get the
+ * vault-style `withRead`/`withWrite` conveniences back. What "read" and
+ * "write" mean — ranked capability floor, orthogonal capability, anything —
+ * is entirely the authenticators' business.
+ */
+export function createApiAuth<Identity>(authenticators: {
+  read: Authenticator<Identity>;
+  write: Authenticator<Identity>;
+}): ApiAuth<Identity> {
+  return {
+    withRead: (handler) => withAuth(authenticators.read, handler),
+    withWrite: (handler) => withAuth(authenticators.write, handler),
+  };
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+export {
+  type ApiAuth,
+  type AuthedHandler,
+  type Authenticator,
+  type AuthFailure,
+  type AuthResult,
+  createApiAuth,
+  type RouteContext,
+  withAuth,
+} from "./handler";
+export {
+  type ApiErrorBody,
+  type ApiErrorCode,
+  apiJson,
+  apiText,
+  jsonError,
+  type ParsedRequestJson,
+  parseRequestJson,
+  zodMessage,
+} from "./json";
+export {
+  limitForOffset,
+  type Pagination,
+  type PaginationQuery,
+  type ParsedPagination,
+  pageItems,
+  pageLimitOnlyItems,
+  paginationQueryContract,
+  parsePagination,
+} from "./pagination";

package/src/json.ts

@@ -0,0 +1,100 @@
+import type { ZodError, z } from "zod";
+
+/**
+ * The fleet's structured API error contract — metal's `/api/v1` shape, adopted
+ * as the standard: every failure body is `{ error: { code, message } }` where
+ * `code` is a stable machine-readable enum and `message` is for humans. A
+ * consumer switches on `code`, never on message text.
+ *
+ * Every response built here carries `cache-control: no-store` (vault's rule):
+ * these surfaces vend credentials and live state, and a forgotten header on
+ * one route is exactly the kind of bug this package exists to delete.
+ */
+
+export type ApiErrorCode =
+  | "AUTH_INVALID"
+  | "AUTH_MISSING"
+  | "BAD_REQUEST"
+  | "INTERNAL"
+  | "INVALID_JSON"
+  | "NOT_FOUND"
+  | "SCOPE_MISSING"
+  | "UPSTREAM_CONTRACT"
+  | "UPSTREAM_ERROR";
+
+export type ApiErrorBody = {
+  error: {
+    code: ApiErrorCode;
+    message: string;
+  };
+};
+
+const noStore = { "cache-control": "no-store" } as const;
+
+/** A non-cached JSON response — the canonical success shape. */
+export function apiJson(data: unknown, status = 200): Response {
+  return Response.json(data, { status, headers: noStore });
+}
+
+/** A non-cached `text/plain` response — e.g. a dotenv projection. */
+export function apiText(body: string, status = 200): Response {
+  return new Response(body, {
+    status,
+    headers: { "content-type": "text/plain; charset=utf-8", ...noStore },
+  });
+}
+
+/** The canonical structured failure: `{ error: { code, message } }`. */
+export function jsonError(
+  code: ApiErrorCode,
+  message: string,
+  status: number,
+): Response {
+  return Response.json({ error: { code, message } } satisfies ApiErrorBody, {
+    status,
+    headers: noStore,
+  });
+}
+
+export type ParsedRequestJson<ParsedBody> =
+  | { success: true; data: ParsedBody }
+  | { success: false; response: Response };
+
+/**
+ * Parse and validate a JSON request body against a zod contract. Failures come
+ * back as a ready-to-return Response: non-JSON is `INVALID_JSON`, a contract
+ * miss is `BAD_REQUEST` with the offending field named.
+ */
+export async function parseRequestJson<ParsedBody>(
+  request: Request,
+  contract: z.ZodType<ParsedBody>,
+): Promise<ParsedRequestJson<ParsedBody>> {
+  let body: unknown;
+  try {
+    body = await request.json();
+  } catch {
+    return {
+      success: false,
+      response: jsonError("INVALID_JSON", "request body must be JSON", 400),
+    };
+  }
+
+  const parsedBody = contract.safeParse(body);
+  if (!parsedBody.success) {
+    return {
+      success: false,
+      response: jsonError("BAD_REQUEST", zodMessage(parsedBody.error), 400),
+    };
+  }
+
+  return { success: true, data: parsedBody.data };
+}
+
+export function zodMessage(error: ZodError): string {
+  const issue = error.issues[0];
+  if (!issue) return "invalid request";
+  // Name the offending field: a bare "expected string, received undefined"
+  // leaves the caller (and the dashboard) guessing which input was wrong.
+  const field = issue.path.join(".");
+  return field ? `${field}: ${issue.message}` : issue.message;
+}

package/src/pagination.ts

@@ -0,0 +1,92 @@
+import { z } from "zod";
+import { jsonError, zodMessage } from "./json";
+
+/**
+ * Offset pagination for list endpoints — metal's `/api/v1` helpers. Query
+ * params parse through a strict contract with clamped bounds; the response
+ * envelope is `{ items, pagination: { limit, offset, total, nextOffset } }`
+ * where `nextOffset: null` means the caller has everything.
+ */
+
+export const paginationQueryContract = z.strictObject({
+  limit: z.coerce.number().int().min(1).max(500).default(30),
+  offset: z.coerce.number().int().min(0).max(10_000).default(0),
+});
+
+export type PaginationQuery = z.infer<typeof paginationQueryContract>;
+
+export type Pagination = {
+  limit: number;
+  offset: number;
+  total: number;
+  nextOffset: number | null;
+};
+
+export type ParsedPagination =
+  | { success: true; data: PaginationQuery }
+  | { success: false; response: Response };
+
+/** Parse `?limit=&offset=` from a request URL; out-of-bounds is a 400. */
+export function parsePagination(request: Request): ParsedPagination {
+  const searchParams = new URL(request.url).searchParams;
+  const parsedQuery = paginationQueryContract.safeParse({
+    limit: searchParams.get("limit") ?? undefined,
+    offset: searchParams.get("offset") ?? undefined,
+  });
+  if (!parsedQuery.success) {
+    return {
+      success: false,
+      response: jsonError("BAD_REQUEST", zodMessage(parsedQuery.error), 400),
+    };
+  }
+  return { success: true, data: parsedQuery.data };
+}
+
+/** Page a fully-materialized list; `total` is exact. */
+export function pageItems<Item>(
+  items: readonly Item[],
+  query: PaginationQuery,
+): { items: Item[]; pagination: Pagination } {
+  const total = items.length;
+  const nextOffset =
+    query.offset + query.limit < total ? query.offset + query.limit : null;
+
+  return {
+    items: items.slice(query.offset, query.offset + query.limit),
+    pagination: {
+      limit: query.limit,
+      offset: query.offset,
+      total,
+      nextOffset,
+    },
+  };
+}
+
+/**
+ * Page a list fetched with `limitForOffset` (one sentinel row past the page):
+ * `total` is a floor, not an exact count — it says "at least this many" when
+ * a next page exists, avoiding a COUNT(*) on hot paths.
+ */
+export function pageLimitOnlyItems<Item>(
+  items: readonly Item[],
+  query: PaginationQuery,
+): { items: Item[]; pagination: Pagination } {
+  const page = items.slice(query.offset, query.offset + query.limit);
+  const hasNext = items.length > query.offset + query.limit;
+  const total = hasNext ? query.offset + query.limit + 1 : items.length;
+
+  return {
+    items: page,
+    pagination: {
+      limit: query.limit,
+      offset: query.offset,
+      total,
+      nextOffset: hasNext ? query.offset + query.limit : null,
+    },
+  };
+}
+
+/** The SQL LIMIT that lets `pageLimitOnlyItems` detect a next page. */
+export function limitForOffset(query: PaginationQuery): number {
+  return query.limit + query.offset + 1;
+}