@kedge/server 0.0.0-stage → 0.10.0

package/src/meta-routes.ts

@@ -0,0 +1,277 @@
+// What the admin is built from (docs/proposals/p0.9-admin-shell.md §4.4, §5):
+// who the caller is and what they may do, and one metadata contract for core
+// resources and plugin entities. Definitions and grants only, never row values.
+import { createRoute, type OpenAPIHono } from "@hono/zod-openapi";
+import {
+  type AccessContext,
+  type EntityDefinition,
+  FRESH_MS,
+  holds,
+  ORDER,
+  ORDER_LINE,
+  permissionsOf,
+  type Resource,
+} from "@kedge/core";
+import type { Context } from "hono";
+import type { AdminPermissions, KedgeEnv } from "./access";
+import { authzFingerprint } from "./admin-shell";
+import { ok } from "./http";
+import type { AuthDeps, EntityAdmin } from "./types";
+
+const iso = (ms: number | null) => (ms === null ? null : new Date(ms).toISOString());
+const STRONG = "password+totp";
+
+/** The admin's request codec for a list (§5.1): how it encodes filters, sort and the cursor. */
+type Codec = "entity" | "order" | "audit";
+
+export interface AdminMetaDeps {
+  auth: AuthDeps;
+  entities?: {
+    store: EntityAdmin;
+    declared: readonly { plugin: string; entity: string; def: EntityDefinition }[];
+  };
+  /** Plugin tracks whose target is a core resource, in `trackMetadata`'s shape (§5.1). */
+  tracksOn?: (ctx: AccessContext, on: "order" | "order_line") => unknown[];
+  /** Whether the store has the routes a core resource's endpoints name. */
+  orders: boolean;
+  auditLog: boolean;
+}
+
+const classes = (ctx: AccessContext) =>
+  new Set(["public", ...(["pii", "financial"] as const).filter((c) => holds(ctx.grants, `field:${c}`))]);
+
+/** A core registration's fields, as the admin shows them to this caller. */
+function coreFields(r: Resource, ctx: AccessContext) {
+  const held = classes(ctx);
+  return Object.entries(r.fields)
+    .filter(([, f]) => f.admin)
+    .map(([name, f]) => ({
+      name,
+      type: f.admin?.type,
+      ...(f.admin?.wire ? { wire: f.admin.wire } : {}),
+      class: f.class,
+      label: f.admin?.label,
+      required: false,
+      filter: f.filter ?? [],
+      sort: Boolean(f.sort),
+      search: Boolean(f.search),
+      scope: null,
+      readable: held.has(f.class),
+      writable: false,
+    }));
+}
+
+/**
+ * A create the caller can actually use (§5.1): every required field writable,
+ * the row able to fall inside the caller's write scope, and an order to attach
+ * to when the entity needs one. A prediction of the create route's own checks,
+ * so no form is offered that always rolls back.
+ */
+export function createUsable(
+  ctx: AccessContext,
+  def: EntityDefinition,
+  write: string,
+  fields: readonly { name: string; required: boolean; writable: boolean; scope: string | null }[],
+): boolean {
+  return createFill(ctx, def, write, fields) !== false;
+}
+
+/**
+ * Which scope column a scoped writer's form must fill with the caller (§5.1):
+ * null for an unscoped writer, the column's scope for a scoped one, false when
+ * no create can succeed.
+ */
+export function createFill(
+  ctx: AccessContext,
+  def: EntityDefinition,
+  write: string,
+  fields: readonly { name: string; required: boolean; writable: boolean; scope: string | null }[],
+): "assignee" | "location" | null | false {
+  const scopes = ctx.grants.get(write);
+  if (!scopes || scopes.size === 0) return false;
+  if (fields.some((f) => f.required && !f.writable)) return false;
+  if (def.order === "required" && !holds(ctx.grants, "order:read")) return false;
+  if (scopes.has("all")) return null;
+  const field = (scope: string) => fields.find((f) => f.scope === scope);
+  if (scopes.has("self") && field("assignee")?.writable) return "assignee";
+  if (scopes.has("location") && field("location")?.writable && ctx.locations.length > 0) return "location";
+  return false;
+}
+
+export function metaRoutes(app: OpenAPIHono<KedgeEnv>, perms: AdminPermissions, deps: AdminMetaDeps): void {
+  const { auth } = deps;
+
+  app.openapi(
+    perms.declare(
+      // Any signed-in staff member or key: it answers only about the caller.
+      { permission: "meta:read", store: true },
+      createRoute({ method: "get", path: "/admin/meta/me", responses: ok("Who the caller is and what they may do") }),
+    ),
+    async (c: Context<KedgeEnv>) => {
+      const a = c.var.access;
+      const ctx = a.ctx;
+      const s = a.session;
+      const permissions = [...ctx.grants.entries()]
+        .map(([code, scopes]) => ({ code, scopes: [...scopes].sort() }))
+        .sort((x, y) => (x.code < y.code ? -1 : x.code > y.code ? 1 : 0));
+      const authz = await authzFingerprint(ctx, s?.method ?? null, auth.accessContract ?? "");
+      const locations = [...ctx.locations].sort();
+      if (ctx.principal.kind === "staff" && s) {
+        const profile = await auth.ceremonies.staffProfile(ctx.principal.id);
+        const strong = s.method === STRONG;
+        return c.json(
+          {
+            principal: { kind: "staff", id: ctx.principal.id, email: profile?.email ?? null },
+            session: {
+              id: s.id,
+              method: s.method,
+              strong,
+              expires_at: iso(s.expiresAt),
+              authenticated_at: iso(s.authenticatedAt),
+              // A factor or password change needs a strong session this fresh (p0.5 §2.6).
+              fresh_until: strong ? iso(s.authenticatedAt + FRESH_MS) : null,
+            },
+            roles: (profile?.roles ?? []).map((r) => ({ ...r, counted: !r.strong || strong })),
+            permissions,
+            locations,
+            authz,
+          },
+          200,
+        );
+      }
+      return c.json(
+        {
+          principal: { kind: ctx.principal.kind, id: "id" in ctx.principal ? ctx.principal.id : null },
+          permissions,
+          locations,
+          authz,
+        },
+        200,
+      );
+    },
+  );
+
+  app.openapi(
+    perms.declare(
+      { permission: "meta:read", store: true },
+      createRoute({
+        method: "get",
+        path: "/admin/meta/resources",
+        responses: ok("Every resource the caller may read, core and plugin, as definitions"),
+      }),
+    ),
+    async (c: Context<KedgeEnv>) => {
+      const ctx = c.var.access.ctx;
+      const resources: Record<string, unknown>[] = [];
+      if (deps.orders && holds(ctx.grants, ORDER.permission)) {
+        const line = {
+          id: "core.order_line",
+          kind: "core",
+          label: ORDER_LINE.admin?.label,
+          title: ORDER_LINE.admin?.title ?? null,
+          list: ORDER_LINE.admin?.list ?? [],
+          fields: coreFields(ORDER_LINE, ctx),
+          actions: { create: false, update: false, archive: false, assign: false },
+          tracks: deps.tracksOn?.(ctx, "order_line") ?? [],
+        };
+        resources.push({
+          id: "core.order",
+          kind: "core",
+          label: ORDER.admin?.label,
+          nav: { section: "orders", order: 10 },
+          endpoints: {
+            list: { path: "/admin/orders", page: "cursor", codec: "order" satisfies Codec },
+            search: "/admin/orders/search",
+            read: "/admin/orders/{id}",
+          },
+          title: ORDER.admin?.title ?? null,
+          list: ORDER.admin?.list ?? [],
+          fields: coreFields(ORDER, ctx),
+          nested: [{ name: "lines", resource: line }],
+          actions: { create: false, update: false, archive: false, assign: false },
+          tracks: deps.tracksOn?.(ctx, "order") ?? [],
+        });
+      }
+      if (deps.auditLog && holds(ctx.grants, "audit:read")) {
+        const pii = holds(ctx.grants, "field:pii");
+        const f = (name: string, label: string, type: string, extra: Record<string, unknown> = {}) => ({
+          name,
+          type,
+          class: "public",
+          label,
+          required: false,
+          filter: [],
+          sort: false,
+          search: false,
+          scope: null,
+          readable: true,
+          writable: false,
+          ...extra,
+        });
+        resources.push({
+          id: "core.audit_log",
+          kind: "core",
+          label: "Audit log",
+          nav: { section: "system", order: 30 },
+          endpoints: { list: { path: "/admin/audit-log", page: "before", codec: "audit" satisfies Codec } },
+          title: "action",
+          list: ["created_at", "actor", "action", "entity_type", "entity_id"],
+          // As the route answers (p0.5 §7.2): `ip` and `user_agent` are null without
+          // field:pii, and `changes` is projected, financial values only with field:financial.
+          fields: [
+            f("created_at", "When", "datetime", { wire: "iso" }),
+            f("actor", "Actor", "string", { filter: ["eq"] }),
+            f("action", "Action", "string"),
+            f("entity_type", "Entity", "string", { filter: ["eq"] }),
+            f("entity_id", "Entity id", "string", { filter: ["eq"] }),
+            f("changes", "Changes", "json", { projected: true }),
+            f("ip", "IP", "string", { class: "pii", readable: pii }),
+            f("user_agent", "User agent", "string", { class: "pii", readable: pii }),
+          ],
+          actions: { create: false, update: false, archive: false, assign: false },
+          tracks: [],
+        });
+      }
+      if (deps.entities) {
+        const meta = deps.entities.store.metadata(ctx) as { entities: Record<string, unknown>[] };
+        for (const e of meta.entities) {
+          const plugin = e.plugin as string;
+          const entity = e.entity as string;
+          const declared = deps.entities.declared.find((d) => d.plugin === plugin && d.entity === entity);
+          if (!declared) continue;
+          const p = permissionsOf(plugin, entity, declared.def);
+          const fields = (e.fields as Record<string, unknown>[]).map((x) =>
+            x.type === "datetime" ? { ...x, wire: "ms" } : x,
+          ) as { name: string; required: boolean; writable: boolean; scope: string | null }[];
+          const actions = e.actions as { create: boolean; update: boolean; archive: boolean; assign: boolean };
+          const base = `/admin/plugins/${plugin}/${entity}`;
+          resources.push({
+            id: `plugin.${plugin}.${entity}`,
+            kind: "entity",
+            plugin,
+            entity,
+            label: e.label,
+            nav: { section: `plugin.${plugin}`, order: 10 },
+            endpoints: {
+              list: { path: base, page: "cursor", codec: "entity" satisfies Codec },
+              search: `${base}/search`,
+              read: `${base}/{id}`,
+              ...(actions.update ? { update: `${base}/{id}` } : {}),
+              ...(actions.archive ? { archive: `${base}/{id}/archive` } : {}),
+              create: base,
+            },
+            order: e.order,
+            title: e.title,
+            list: e.list,
+            fields,
+            actions: { ...actions, create: createUsable(ctx, declared.def, p.write, fields) },
+            // The scope column a scoped writer's create fills with the caller, if any (§5.1).
+            create_fill: createFill(ctx, declared.def, p.write, fields) || null,
+            tracks: e.tracks,
+          });
+        }
+      }
+      return c.json({ version: 1, resources }, 200);
+    },
+  );
+}

package/src/plugin-routes.ts

@@ -0,0 +1,40 @@
+// P0.7's lifecycle routes (docs/proposals/p0.7-tracks-entities.md §5.1),
+// under /admin/system so no plugin route or entity name can collide with
+// them. Each change is one audited batch under the route's scope.
+import { createRoute, type OpenAPIHono, z } from "@hono/zod-openapi";
+import type { AdminPermissions, KedgeEnv } from "./access";
+import { ok } from "./http";
+import type { PluginAdmin } from "./types";
+
+const Name = z.string().regex(/^[a-z][a-z0-9_]{0,30}$/);
+
+export function pluginRoutes(app: OpenAPIHono<KedgeEnv>, perms: AdminPermissions, plugins: PluginAdmin): void {
+  app.openapi(
+    perms.declare(
+      "plugin:read",
+      createRoute({
+        method: "get",
+        path: "/admin/system/plugins",
+        responses: ok("Each installed plugin, its state and what it declares"),
+      }),
+    ),
+    async (c) => c.json({ plugins: await plugins.list() }, 200),
+  );
+  for (const [action, to] of [
+    ["disable", "disabled"],
+    ["enable", "active"],
+  ] as const) {
+    app.openapi(
+      perms.declare(
+        { permission: "plugin:write", action: `plugin.${action}` },
+        createRoute({
+          method: "post",
+          path: `/admin/system/plugins/{name}/${action}`,
+          request: { params: z.object({ name: Name }) },
+          responses: ok(action === "disable" ? "The plugin, disabled: no new use" : "The plugin, active again"),
+        }),
+      ),
+      async (c) => c.json(await plugins.set(c.req.valid("param").name, to), 200),
+    );
+  }
+}

package/src/relay-routes.ts

@@ -0,0 +1,192 @@
+// P0.6a's staff routes (p0.6a §2.8, §4.9): the deliveries staff act on, the
+// relay's health, and the unresolved effects with their decisions. Every
+// mutation runs inside the admin gate's batch scope, so its one batch carries
+// the audit row and re-proves the permission at commit (p0.5 §7.1). Nothing
+// here re-sends an effect: a decision is recorded, and its own delivery
+// applies it on the effect's shard.
+import { createRoute, type OpenAPIHono, z } from "@hono/zod-openapi";
+import { actorOf, KedgeError, RELAY_LIMITS, readableWebhookTypes } from "@kedge/core";
+import type { AdminPermissions, KedgeEnv } from "./access";
+import { jsonBody, ok } from "./http";
+import type { DeliveryAdmin } from "./types";
+
+const Cursor = z.string().min(1).max(RELAY_LIMITS.STAFF_CURSOR_MAX).optional();
+const Limit = z.coerce.number().int().min(1).max(100).default(50);
+const DeliveryParam = z.object({ kind: z.enum(["sub", "rel", "res", "whk"]), seq: z.coerce.number().int().min(1) });
+// `printedKey`'s form (core): the home shard in two hex digits, then the logical key.
+const EffectKey = z.string().regex(/^efk_[0-9a-f]{2}_[0-9a-f]{64}$/);
+
+export function relayRoutes(app: OpenAPIHono<KedgeEnv>, deliveries: DeliveryAdmin, perms: AdminPermissions): void {
+  app.openapi(
+    perms.declare(
+      "delivery:read",
+      createRoute({
+        method: "get",
+        path: "/admin/deliveries",
+        request: {
+          query: z.object({
+            state: z.enum(["failed", "blocked", "orphaned"]),
+            plugin: z.string().min(1).max(64).optional(),
+            cursor: Cursor,
+            limit: Limit,
+          }),
+        },
+        responses: ok("Failed, blocked or orphaned deliveries, paged by kind and seq"),
+      }),
+    ),
+    async (c) => {
+      const q = c.req.valid("query");
+      return c.json(
+        await deliveries.problems({
+          state: q.state,
+          ...(q.plugin ? { plugin: q.plugin } : {}),
+          // A webhook delivery shows only for a type the reader may read unscoped (p0.6b §2.9, codex r2).
+          webhookTypes: readableWebhookTypes(c.var.access.ctx.grants),
+          cursor: q.cursor ?? null,
+          limit: q.limit,
+        }),
+        200,
+      );
+    },
+  );
+
+  app.openapi(
+    perms.declare(
+      "delivery:read",
+      createRoute({
+        method: "get",
+        path: "/admin/deliveries/health",
+        responses: ok("How far behind the relay is: the oldest due timer and delivery, counts, and each shard"),
+      }),
+    ),
+    async (c) => c.json((await deliveries.health()) as Record<string, unknown>, 200),
+  );
+
+  // A retry or discard of a delivery that isn't `failed` changes nothing and
+  // says so: two staff acting at once see one of them win (§2.8).
+  for (const [action, permission] of [
+    ["retry", "delivery:retry"],
+    ["discard", "delivery:discard"],
+  ] as const) {
+    app.openapi(
+      perms.declare(
+        permission,
+        createRoute({
+          method: "post",
+          path: `/admin/deliveries/{kind}/{seq}/${action}`,
+          request: {
+            params: DeliveryParam,
+            // The row's `updated_at` as the caller saw it (codex code r11): only that failure is acted
+            // on, so a repeat arriving after the delivery failed again changes nothing.
+            query: z.object({ expected_updated_at: z.coerce.number().int().min(0).optional() }),
+          },
+          responses: ok(action === "retry" ? "The delivery, due now" : "The delivery, given up on"),
+        }),
+      ),
+      async (c) => {
+        const { kind, seq } = c.req.valid("param");
+        const expected = c.req.valid("query").expected_updated_at ?? null;
+        if (kind === "whk") {
+          // Named one at a time, a webhook delivery still needs its type's read permission (p0.6b §2.9).
+          const type = await deliveries.webhookEventType(seq);
+          if (type === null || !readableWebhookTypes(c.var.access.ctx.grants).includes(type))
+            throw new KedgeError("NOT_FOUND", "Not found");
+          if (action === "retry")
+            throw new KedgeError("DELIVERY_KIND_REPLAY", "A webhook delivery is sent again by replay", {
+              route: "POST /admin/webhooks/deliveries/{id}/replay",
+            });
+        }
+        const done =
+          action === "retry"
+            ? await deliveries.retry(kind, seq, expected)
+            : await deliveries.discard(kind, seq, expected);
+        if (!done) throw new KedgeError("DELIVERY_STATE", "Only a failed delivery can be retried or discarded");
+        return c.json({ kind, seq, [action === "retry" ? "retried" : "discarded"]: true }, 200);
+      },
+    );
+  }
+
+  app.openapi(
+    perms.declare(
+      "effect:read",
+      createRoute({
+        method: "get",
+        path: "/admin/effects",
+        request: {
+          query: z.object({ state: z.enum(["unresolved", "conflict", "divergence"]), cursor: Cursor, limit: Limit }),
+        },
+        responses: ok("Unresolved effects or divergences across the journal's shards, or key conflicts"),
+      }),
+    ),
+    async (c) => {
+      const q = c.req.valid("query");
+      return c.json(
+        await deliveries.effects({
+          state: q.state,
+          cursor: q.cursor ?? null,
+          limit: q.limit,
+          webhookTypes: readableWebhookTypes(c.var.access.ctx.grants),
+        }),
+        200,
+      );
+    },
+  );
+
+  app.openapi(
+    perms.declare(
+      // Its own envelope (code r17): a replay must answer the resolution id it created.
+      { permission: "effect:resolve", own: true },
+      createRoute({
+        method: "post",
+        path: "/admin/effects/{key}/resolve",
+        request: {
+          params: z.object({ key: EffectKey }),
+          ...jsonBody(
+            z.object({
+              expected_revision: z.number().int().min(0),
+              form: z.enum(["observe", "succeeded", "failed_final"]),
+              result: z.record(z.string(), z.unknown()).optional(),
+              code: z.string().min(1).max(64).optional(),
+            }),
+          ),
+        },
+        responses: ok(
+          "The resolution's id; its own delivery applies it. Needs an Idempotency-Key, whose retry answers the same id",
+        ),
+      }),
+    ),
+    async (c) => {
+      const b = c.req.valid("json");
+      const out = await deliveries.resolve({
+        key: c.req.valid("param").key,
+        expectedRevision: b.expected_revision,
+        form: b.form,
+        ...(b.result ? { result: b.result } : {}),
+        ...(b.code ? { code: b.code } : {}),
+        staffId: actorOf(c.var.access.ctx.principal),
+        idempotencyKey: c.req.header("idempotency-key") ?? null,
+      });
+      return c.json(
+        { resolution_id: out.resolutionId, state: "pending", ...(out.replayed ? { replayed: true } : {}) },
+        200,
+      );
+    },
+  );
+
+  app.openapi(
+    perms.declare(
+      "effect:read",
+      createRoute({
+        method: "get",
+        path: "/admin/effects/resolutions/{id}",
+        request: { params: z.object({ id: z.string().min(1).max(64) }) },
+        responses: ok("A resolution's delivery: pending, then applied, conflict, canceled or discarded"),
+      }),
+    ),
+    async (c) => {
+      const r = await deliveries.resolution(c.req.valid("param").id);
+      if (!r) throw new KedgeError("NOT_FOUND", "No such resolution");
+      return c.json(r as Record<string, unknown>, 200);
+    },
+  );
+}

package/src/track-routes.ts

@@ -0,0 +1,102 @@
+// P0.7's track routes (docs/proposals/p0.7-tracks-entities.md §3.3, §3.4,
+// §3.8). A transition's permission depends on the transition named in the
+// body, and a row-scoped grant is compiled into the batch, so the store
+// authorizes and audits each command itself (`store: true`): the gate only
+// authenticates and checks CSRF.
+import { createRoute, type OpenAPIHono, z } from "@hono/zod-openapi";
+import { TRACK_LIMITS } from "@kedge/core";
+import type { Context } from "hono";
+import { type AdminPermissions, clientOf, type KedgeEnv } from "./access";
+import { jsonBody, ok } from "./http";
+import type { TrackAdmin } from "./types";
+
+const Name = z.string().regex(/^[a-z][a-z0-9_]{0,40}$/);
+const Params = z.object({ plugin: Name, track: Name, aggregate_id: z.string().min(3).max(200) });
+const Token = z.object({ recovery_id: z.string().min(1).max(64), version: z.number().int().min(1) });
+
+export function trackRoutes(app: OpenAPIHono<KedgeEnv>, perms: AdminPermissions, tracks: TrackAdmin): void {
+  const command = (c: Context<KedgeEnv>, p: z.infer<typeof Params>) => {
+    const client = clientOf(c);
+    return {
+      plugin: p.plugin,
+      track: p.track,
+      aggregateId: p.aggregate_id,
+      idempotencyKey: c.req.header("idempotency-key") ?? null,
+      ip: client.ip,
+      userAgent: client.userAgent,
+    };
+  };
+
+  app.openapi(
+    perms.declare(
+      { permission: "track:read", store: true },
+      createRoute({
+        method: "get",
+        path: "/admin/plugins/{plugin}/tracks/{track}/{aggregate_id}",
+        request: { params: Params, query: z.object({ history_after: z.coerce.number().int().min(0).optional() }) },
+        responses: ok("The track: its state, token, transitions and a page of history"),
+      }),
+    ),
+    async (c) => {
+      const p = c.req.valid("param");
+      return c.json(
+        (await tracks.read(
+          c.var.access.ctx,
+          p.plugin,
+          p.track,
+          p.aggregate_id,
+          c.req.valid("query").history_after,
+        )) as object,
+        200,
+      );
+    },
+  );
+
+  app.openapi(
+    perms.declare(
+      { permission: "track:start", store: true },
+      createRoute({
+        method: "post",
+        path: "/admin/plugins/{plugin}/tracks/{track}/{aggregate_id}/start",
+        request: { params: Params },
+        responses: ok("The started track, or a receipt when the caller can't read it"),
+      }),
+    ),
+    async (c) => c.json((await tracks.start(c.var.access.ctx, command(c, c.req.valid("param")))) as object, 200),
+  );
+
+  app.openapi(
+    perms.declare(
+      { permission: "track:transition", store: true },
+      createRoute({
+        method: "post",
+        path: "/admin/plugins/{plugin}/tracks/{track}/{aggregate_id}/transitions",
+        request: {
+          params: Params,
+          ...jsonBody(
+            z.object({
+              transition: Name,
+              expected: Token,
+              input: z.record(z.string(), z.unknown()).optional(),
+              comment: z.string().min(1).max(TRACK_LIMITS.COMMENT_MAX).nullable().optional(),
+            }),
+          ),
+        },
+        responses: ok("The moved track, or a receipt when the caller can't read it"),
+      }),
+    ),
+    async (c) => {
+      const b = c.req.valid("json");
+      return c.json(
+        (await tracks.transition(c.var.access.ctx, {
+          ...command(c, c.req.valid("param")),
+          transition: b.transition,
+          expected: b.expected,
+          ...(b.input !== undefined ? { input: b.input } : {}),
+          comment: b.comment ?? null,
+        })) as object,
+        200,
+      );
+    },
+  );
+}