@haverstack/server 0.8.0

package/src/routes/changes.ts

@@ -0,0 +1,279 @@
+import { Hono } from 'hono';
+import type { Context } from 'hono';
+import { streamSSE } from 'hono/streaming';
+import type { AppEnv } from '../types.js';
+import type { StackContext } from '../stack.js';
+import type { Config } from '../config.js';
+import type { ScopedStack, TokenSession, RecordChange } from '@haverstack/core';
+import { StackQueryError, StackPermissionError } from '@haverstack/core';
+import { parseChangeParams } from '@haverstack/core/wire';
+import { serializeChange, isValidSeq } from '@haverstack/wire-types';
+import type { ChangeResetReason } from '@haverstack/wire-types';
+import type { Logger } from 'pino';
+import { safeCompare, isOwnerActingAlone } from '../middleware/auth.js';
+import { FrameGate } from '../lib/frameGate.js';
+import { decodeCursor } from '../lib/resumeCursor.js';
+import { ResumeBufferRegistry, resumeBufferKey, type ResumeEntry } from '../lib/resumeBuffer.js';
+
+// Keepalive cadence, and how often an authenticated session is re-checked
+// against the token store — a stream's authority is fixed at connect, so
+// without the re-check a revoked token keeps delivering for as long as the
+// connection lives. Neither value reaches a client, so neither is an env var.
+const DEFAULT_KEEPALIVE_MS = 15_000;
+const DEFAULT_SESSION_CHECK_MS = 30_000;
+// A client whose in-flight frame count crosses this is closed rather than
+// left to queue: one that can't tell it missed a frame can't repair it
+// either, so dropping silently is worse than disconnecting.
+const DEFAULT_MAX_PENDING_FRAMES = 1000;
+// Per-buffer ring depth and how long a buffer keeps being fed after its
+// last connection disconnects — see src/lib/resumeBuffer.ts. Not part of
+// the wire contract either: a client never learns these numbers, only
+// their consequence (`overflow` or `cursor_expired`).
+const DEFAULT_RESUME_BUFFER_DEPTH = 1000;
+const DEFAULT_RESUME_RETENTION_MS = 5 * 60 * 1000;
+
+export type ChangeRouteOptions = {
+  keepaliveMs?: number;
+  sessionCheckMs?: number;
+  maxPendingFrames?: number;
+  /**
+   * Whether a presented cursor is honored at all. Default true and never
+   * false in production, since discovery advertises resume unconditionally.
+   * It exists because `resume: false` is real, spec-defined behavior
+   * (`ready` with no `seq`, then `reset` with reason `not_supported`) that
+   * a conformance fixture needs a way to reach.
+   */
+  resume?: boolean;
+  resumeBufferDepth?: number;
+  resumeRetentionMs?: number;
+};
+
+/**
+ * Raw cursor text presented on this connection, if any — `Last-Event-ID`
+ * takes priority over `?since=` (a browser EventSource-style reconnect
+ * sends the header; `?since=` exists for a client whose transport can't
+ * set one). Not yet validated or decoded — see isValidSeq()/decodeCursor().
+ */
+function presentedCursorRaw(c: Context<AppEnv>, url: URL): string | undefined {
+  return c.req.header('Last-Event-ID') ?? url.searchParams.get('since') ?? undefined;
+}
+
+export function changeRoutes(
+  ctx: StackContext,
+  config: Config,
+  logger: Logger,
+  opts: ChangeRouteOptions = {},
+): Hono<AppEnv> {
+  const app = new Hono<AppEnv>();
+  const keepaliveMs = opts.keepaliveMs ?? DEFAULT_KEEPALIVE_MS;
+  const sessionCheckMs = opts.sessionCheckMs ?? DEFAULT_SESSION_CHECK_MS;
+  const maxPendingFrames = opts.maxPendingFrames ?? DEFAULT_MAX_PENDING_FRAMES;
+  const resumeEnabled = opts.resume ?? true;
+  const resumeBuffers = new ResumeBufferRegistry({
+    depth: opts.resumeBufferDepth ?? DEFAULT_RESUME_BUFFER_DEPTH,
+    retentionMs: opts.resumeRetentionMs ?? DEFAULT_RESUME_RETENTION_MS,
+  });
+
+  /** Scope to a session if authenticated, else the anonymous (public-only) view. */
+  function scopeFor(auth: TokenSession | null): ScopedStack {
+    return auth ? ctx.stack.forSession(auth) : ctx.stack.asEntity(null);
+  }
+
+  // Single-process only: events exist only in the process owning the
+  // stack's storage (docs/spec/wire-format.md § Feed implementation
+  // checklist), and query workers only read. A second process subscribing
+  // to its own Stack over the same storage would see nothing and look fine
+  // in testing — worth knowing before scaling this horizontally.
+  app.get('/', async (c) => {
+    const url = new URL(c.req.url);
+    const auth = c.get('auth');
+    const { filter, includeRecords, includeUnlisted } = parseChangeParams(url);
+    const presentedRaw = presentedCursorRaw(c, url);
+
+    // Refused before the stream opens: a throw from subscribe() after
+    // streaming starts is caught below and merely closes the connection,
+    // silently, having already answered 200. includeUnlisted owes a real
+    // 403, the same one GET /records answers with.
+    if (includeUnlisted && !isOwnerActingAlone(auth, ctx.stack.ownerEntityId)) {
+      throw new StackPermissionError('includeUnlisted is owner-only');
+    }
+
+    // A charset-invalid cursor is refused rather than treated as a cache
+    // miss: no conformant server could have minted it, so there is nothing
+    // to reconcile. isValidSeq() is the rule minted cursors meet on the way
+    // out, applied here on the way in.
+    if (resumeEnabled && presentedRaw !== undefined && !isValidSeq(presentedRaw)) {
+      throw new StackQueryError(`Invalid cursor: "${presentedRaw}"`);
+    }
+
+    // Never accepted: a bearer token is read only from the Authorization
+    // header (authMiddleware), never from a query param — the feed is
+    // consumed via fetch with a streaming body precisely so a client never
+    // needs to put a credential somewhere a browser might log or cache it.
+    const bearerToken = c.req.header('Authorization')?.slice('Bearer '.length);
+
+    return streamSSE(c, async (stream) => {
+      let resolveDone!: () => void;
+      const done = new Promise<void>((resolve) => {
+        resolveDone = resolve;
+      });
+      stream.onAbort(() => resolveDone());
+      const unregister = ctx.changeStreams.add(() => resolveDone());
+
+      const gate = new FrameGate(maxPendingFrames, () => resolveDone());
+      /** Returns false once the gate has tripped — this connection is closing. */
+      function send(event: string, data: unknown, id?: string): boolean {
+        return gate.send(() =>
+          stream.writeSSE({ event, data: JSON.stringify(data), ...(id !== undefined && { id }) }),
+        );
+      }
+
+      // Assigned inside the try below; torn down in the finally whether the
+      // connection ended by abort, by a revoked session, or by a throw. A
+      // throw is caught rather than left to hono, which would answer it by
+      // writing the raw error message to the client as an `error` frame.
+      let unsubscribe: (() => void) | undefined;
+      let keepalive: NodeJS.Timeout | undefined;
+      let sessionCheck: NodeJS.Timeout | undefined;
+
+      try {
+        if (!resumeEnabled) {
+          // `resume: false` — a discovery-conformant server that mints no
+          // cursors at all, reachable only through WellknownRouteOptions'
+          // matching test toggle.
+          send('ready', {});
+          if (presentedRaw !== undefined) {
+            const reason: ChangeResetReason = 'not_supported';
+            send('reset', { reason });
+          }
+          unsubscribe = await scopeFor(auth).subscribe(
+            (change: RecordChange) => {
+              send('record', serializeChange(change));
+            },
+            { filter, includeRecords, includeUnlisted },
+          );
+        } else {
+          const key = resumeBufferKey({
+            principalId: auth?.principalId ?? null,
+            subjectId: auth?.subjectId ?? null,
+            filter,
+            includeRecords,
+            includeUnlisted,
+          });
+          const scoped = scopeFor(auth);
+          const buffer = await resumeBuffers.acquire(key, (onChange) =>
+            scoped.subscribe(onChange, { filter, includeRecords, includeUnlisted }),
+          );
+
+          // Attached before anything below awaits, so there is no gap
+          // between what the backlog snapshot covers and what the live
+          // buffer reports. `replaying` holds live arrivals until the
+          // permission-rechecking replay finishes, so a change appended
+          // mid-replay can't overtake an older, still-pending backlog frame.
+          let replaying = true;
+          const queued: ResumeEntry[] = [];
+          const detachLive = buffer.subscribeLive((entry) => {
+            if (replaying) queued.push(entry);
+            else send('record', entry.frame, entry.frame.seq);
+          });
+          // Registered before the first `await` below, so a subscription
+          // opened above is always released — including when that await
+          // throws. Everything after this point runs under the finally.
+          unsubscribe = () => {
+            detachLive();
+            resumeBuffers.release(key);
+          };
+
+          let resetReason: ChangeResetReason | undefined;
+          let backlog: ResumeEntry[] = [];
+          if (presentedRaw !== undefined) {
+            const decoded = decodeCursor(presentedRaw);
+            if (!decoded || decoded.bufferId !== buffer.id) {
+              // Unrecognized outright, or names a buffer instance that isn't
+              // this key's current one (evicted past its retention window,
+              // or minted for a filter this cursor doesn't actually match).
+              resetReason = 'cursor_expired';
+            } else {
+              const outcome = buffer.entriesAfter(decoded.n);
+              if (outcome.status === 'ok') backlog = outcome.entries;
+              else resetReason = outcome.status;
+            }
+          }
+
+          send('ready', { seq: buffer.headCursor() });
+
+          if (resetReason) {
+            send('reset', { reason: resetReason });
+          } else {
+            for (const entry of backlog) {
+              // A purge frame isn't re-checkable: the mutation-time
+              // decision is the only one there will ever be
+              // (docs/spec/events.md). Everything else still has its record
+              // ID, so a grant revoked during the gap is caught here.
+              if (!entry.isPurge) {
+                const stillReadable = await scoped.get(entry.recordId);
+                if (!stillReadable) continue;
+              }
+              // Once the gate trips this connection is closing, so the
+              // remaining entries are permission checks nobody will read.
+              if (!send('record', entry.frame, entry.frame.seq)) break;
+            }
+          }
+
+          replaying = false;
+          for (const entry of queued) {
+            if (!send('record', entry.frame, entry.frame.seq)) break;
+          }
+        }
+
+        // Through the gate like any other write: a client not draining its
+        // keepalives isn't draining anything, and counting them is what
+        // keeps "in-flight frames are bounded" true of the whole stream
+        // rather than of `record` frames alone.
+        keepalive = setInterval(() => {
+          gate.send(() => stream.write(': keepalive\n\n'));
+        }, keepaliveMs);
+
+        // A revoked or expired token must stop delivering. The owner's
+        // static bearer token never expires (authMiddleware compares it
+        // directly, not via the token store), so only a minted session needs
+        // re-checking; an anonymous connection has no token to revoke.
+        const isOwnerToken =
+          bearerToken !== undefined && safeCompare(bearerToken, config.ownerToken);
+        sessionCheck =
+          auth && !isOwnerToken && bearerToken
+            ? setInterval(() => {
+                void ctx.tokens.lookupToken(bearerToken).then(
+                  (session) => {
+                    if (!session) resolveDone();
+                  },
+                  // The token store is unreachable. Closing is the honest
+                  // answer — the client reconnects and re-authenticates
+                  // through the path that already handles a 401 — and it
+                  // keeps a rejection here from going unhandled.
+                  () => resolveDone(),
+                );
+              }, sessionCheckMs)
+            : undefined;
+
+        await done;
+      } catch (err) {
+        // Hono answers an uncaught throw here by writing the raw error
+        // message to the client as an `error` frame. Catching keeps internal
+        // detail off a stream any anonymous caller can open, and a closed
+        // connection is a repair the client already knows how to make.
+        logger.error(
+          { err, requestId: c.get('requestId') },
+          'Change feed connection ended with an error',
+        );
+      } finally {
+        if (keepalive) clearInterval(keepalive);
+        if (sessionCheck) clearInterval(sessionCheck);
+        unsubscribe?.();
+        unregister();
+      }
+    });
+  });
+
+  return app;
+}

package/src/routes/entity.ts

@@ -0,0 +1,33 @@
+import { Hono } from 'hono';
+import type { AppEnv } from '../types.js';
+import type { StackContext } from '../stack.js';
+import { requireAuth, requireOwner } from '../middleware/auth.js';
+import { readJson } from '../lib/json.js';
+import { serializeRecord } from '@haverstack/wire-types';
+import { StackNotFoundError } from '@haverstack/core';
+
+export function entityRoutes(ctx: StackContext): Hono<AppEnv> {
+  const app = new Hono<AppEnv>();
+  const { stack } = ctx;
+  const ownerEntityId = stack.ownerEntityId;
+
+  app.get('/', requireAuth(), async (c) => {
+    const auth = c.get('auth')!;
+    const record = await stack.forSession(auth).getOwnerEntity();
+    if (!record) throw new StackNotFoundError('Entity record not found');
+    return c.json(serializeRecord(record));
+  });
+
+  app.patch('/', requireOwner(ownerEntityId), async (c) => {
+    const auth = c.get('auth')!;
+    const record = await stack.forSession(auth).getOwnerEntity();
+    if (!record) throw new StackNotFoundError('Entity record not found');
+    const body = await readJson<Record<string, unknown>>(c);
+    const updated = await stack
+      .forSession(auth)
+      .patchContent(record.id, (body.content ?? {}) as Record<string, unknown>);
+    return c.json(serializeRecord(updated));
+  });
+
+  return app;
+}

package/src/routes/health.ts

@@ -0,0 +1,8 @@
+import { Hono } from 'hono';
+import type { AppEnv } from '../types.js';
+
+export function healthRoutes(): Hono<AppEnv> {
+  const app = new Hono<AppEnv>();
+  app.get('/', (c) => c.json({ status: 'ok', timestamp: new Date().toISOString() }));
+  return app;
+}

package/src/routes/records.ts

@@ -0,0 +1,259 @@
+import { Hono } from 'hono';
+import type { AppEnv } from '../types.js';
+import type { StackContext } from '../stack.js';
+import type { ScopedStack, TokenSession } from '@haverstack/core';
+import { requireAuth, requireOwner } from '../middleware/auth.js';
+import { readJson } from '../lib/json.js';
+import {
+  parseQueryBody,
+  parseQueryParams,
+  parsePositiveInt,
+  parseIfMatch,
+  createOptionsFromWireRecord,
+  changesFromWireBody,
+} from '@haverstack/core/wire';
+import { clampLimit } from '../lib/queryLimit.js';
+import { serializeRecord, serializeVersion } from '@haverstack/wire-types';
+import type { WireQueryResponse } from '@haverstack/wire-types';
+import { StackValidationError, StackQueryError, StackNotFoundError } from '@haverstack/core';
+import type { Association, TypeId } from '@haverstack/core';
+
+// ---------------------------------------------------------------------------
+// Route factory
+// ---------------------------------------------------------------------------
+
+// Only the routes that can search a large index (POST /query, GET /) run
+// on the query worker pool with a deadline; everything else calls the main
+// thread's ScopedStack directly, being index-bound already. Virtualizing
+// the whole ScopedStack API across the worker boundary would buy no bound
+// the unbounded-cost case needs. See src/lib/queryWorker/pool.ts and
+// docs/spec/wire-format.md § Bounding query cost.
+export function recordRoutes(ctx: StackContext, queryTimeoutMs: number): Hono<AppEnv> {
+  const app = new Hono<AppEnv>();
+  const { stack, queryWorker } = ctx;
+  const ownerEntityId = stack.ownerEntityId;
+
+  /** Scope to a session if authenticated, else the anonymous view. */
+  function scopeFor(auth: TokenSession | null): ScopedStack {
+    return auth ? stack.forSession(auth) : stack.asEntity(null);
+  }
+
+  // POST /records/query — full query with content-field filters. Optional
+  // auth, like GET /records: a superset of the same query surface, so an
+  // anonymous caller gets the same public-record subset either way.
+  // Registered ahead of the /:id patterns, which would otherwise capture
+  // the literal "query" segment.
+  app.post('/query', async (c) => {
+    const auth = c.get('auth');
+    const query = clampLimit(parseQueryBody(await readJson(c)));
+    const result = await queryWorker.query(auth, query, queryTimeoutMs);
+    const body: WireQueryResponse = {
+      records: result.records.map(serializeRecord),
+      cursor: result.cursor,
+    };
+    return c.json(body);
+  });
+
+  // GET /records — query by native fields via URL params
+  app.get('/', async (c) => {
+    const auth = c.get('auth');
+    const query = clampLimit(parseQueryParams(new URL(c.req.url)));
+    const result = await queryWorker.query(auth, query, queryTimeoutMs);
+    const body: WireQueryResponse = {
+      records: result.records.map(serializeRecord),
+      cursor: result.cursor,
+    };
+    return c.json(body);
+  });
+
+  // POST /records — a full record body, but version, entityId and
+  // principalId are stamped here and never trusted from it. Everything else
+  // a wire record body can carry — which fields are forwarded as-is, which
+  // are owner-acting-alone-only, and which reduce to a boolean rather than
+  // their literal value — is `createOptionsFromWireRecord()`'s disposition
+  // to make, not this route's: see `@haverstack/core/wire` and
+  // docs/spec/wire-format.md § Records.
+  app.post('/', requireAuth(), async (c) => {
+    const auth = c.get('auth')!;
+    const body = await readJson(c);
+    const { typeId, content, options } = createOptionsFromWireRecord(body, auth, ownerEntityId);
+    const created = await stack.forSession(auth).create(typeId, content, options);
+    return c.json(serializeRecord(created), 200);
+  });
+
+  // GET /records/:id
+  app.get('/:id', async (c) => {
+    const id = c.req.param('id');
+    const auth = c.get('auth');
+    const record = await scopeFor(auth).get(id);
+    if (!record) throw new StackNotFoundError('Record not found');
+    return c.json(serializeRecord(record));
+  });
+
+  // PATCH /records/:id — the body is a change set: an envelope naming any
+  // combination of `contentPatch`, `parentId`, `permissions`, `associations`
+  // and `unlisted`, applied as one atomic write that produces exactly one
+  // version. A conforming client sends { "contentPatch": { "title": "New" } },
+  // never the bare patch — content is one aspect among five here, so the
+  // envelope is what tells a `parentId` naming a container from a content
+  // field of that name. One If-Match fences the whole multi-aspect edit.
+  //
+  // `changesFromWireBody()` owns the entire read of that envelope: which
+  // keys it may carry, the 400 an unrecognized or wholly absent key earns,
+  // and the 422 a malformed value earns. Content keys stay Stack's to judge,
+  // so nothing here inspects the patch. See docs/spec/wire-format.md § Records.
+  //
+  // No route-level guard belongs here: ScopedStack owns the _attachment@1
+  // immutable-field and _grant@1 owner-only rules (docs/spec/attachments.md,
+  // docs/spec/access-control.md) and resolves each change-set key against its
+  // own gate, so a denial round-trips as the core error it is rather than a
+  // guess made before the permission check ran.
+  app.patch('/:id', requireAuth(), async (c) => {
+    const id = c.req.param('id');
+    const auth = c.get('auth')!;
+    const changes = changesFromWireBody(await readJson(c));
+
+    const updated = await stack
+      .forSession(auth)
+      .mutate(id, changes, { ifVersion: parseIfMatch(c.req.header('If-Match')) });
+    return c.json(serializeRecord(updated));
+  });
+
+  // DELETE /records/:id  (?hard=true for permanent). A soft delete bumps
+  // the version like any other mutation, so it answers with the record it
+  // produced (carrying deletedAt); a hard delete leaves nothing to answer
+  // with, so that one stays 204.
+  app.delete('/:id', requireAuth(), async (c) => {
+    const id = c.req.param('id');
+    const auth = c.get('auth')!;
+    const hard = new URL(c.req.url).searchParams.get('hard') === 'true';
+    const session = stack.forSession(auth);
+
+    await session.delete(id, { hard, ifVersion: parseIfMatch(c.req.header('If-Match')) });
+    if (hard) return c.body(null, 204);
+    return c.json(serializeRecord((await session.get(id))!));
+  });
+
+  // POST /records/:id/undelete — reverses a soft delete; idempotent
+  app.post('/:id/undelete', requireAuth(), async (c) => {
+    const id = c.req.param('id');
+    const auth = c.get('auth')!;
+    const restored = await stack
+      .forSession(auth)
+      .undelete(id, { ifVersion: parseIfMatch(c.req.header('If-Match')) });
+    return c.json(serializeRecord(restored));
+  });
+
+  // ------------------------------------------------------------------
+  // Permissions
+  // ------------------------------------------------------------------
+
+  app.get('/:id/permissions', async (c) => {
+    const id = c.req.param('id');
+    const auth = c.get('auth');
+    const record = await scopeFor(auth).get(id);
+    if (!record) throw new StackNotFoundError('Record not found');
+    return c.json({ permissions: record.permissions ?? [] });
+  });
+
+  // ------------------------------------------------------------------
+  // Associations
+  // ------------------------------------------------------------------
+
+  app.get('/:id/associations', async (c) => {
+    const id = c.req.param('id');
+    const auth = c.get('auth');
+    const record = await scopeFor(auth).get(id);
+    if (!record) throw new StackNotFoundError('Record not found');
+    let assocs = record.associations ?? [];
+    const kind = c.req.query('kind');
+    if (kind) assocs = assocs.filter((a) => a.kind === kind);
+    const label = c.req.query('label');
+    if (label) assocs = assocs.filter((a) => a.label === label);
+    return c.json({ associations: assocs });
+  });
+
+  app.post('/:id/associations', requireAuth(), async (c) => {
+    const id = c.req.param('id');
+    const auth = c.get('auth')!;
+    const body = await readJson<Association>(c);
+    if (!body.kind || !body.label) throw new StackQueryError('kind and label are required');
+    const updated = await stack
+      .forSession(auth)
+      .associate(id, body, { ifVersion: parseIfMatch(c.req.header('If-Match')) });
+    return c.json(serializeRecord(updated));
+  });
+
+  // POST, not DELETE — a DELETE request body has no defined semantics
+  // (RFC 9110 §9.3.5) and is a portability landmine for proxies/gateways
+  // that drop or reject it.
+  app.post('/:id/associations/delete', requireAuth(), async (c) => {
+    const id = c.req.param('id');
+    const auth = c.get('auth')!;
+    const body = await readJson<Association>(c);
+    const updated = await stack
+      .forSession(auth)
+      .dissociate(id, body, { ifVersion: parseIfMatch(c.req.header('If-Match')) });
+    return c.json(serializeRecord(updated));
+  });
+
+  // ------------------------------------------------------------------
+  // Versions
+  // ------------------------------------------------------------------
+
+  app.get('/:id/versions', async (c) => {
+    const id = c.req.param('id');
+    const auth = c.get('auth');
+    const versions = await scopeFor(auth).getVersions(id);
+    return c.json(versions.map(serializeVersion));
+  });
+
+  app.get('/:id/versions/:version', async (c) => {
+    const id = c.req.param('id');
+    const vNum = parsePositiveInt(c.req.param('version'), 'version number');
+    const auth = c.get('auth');
+    const version = await scopeFor(auth).getVersion(id, vNum);
+    if (!version) throw new StackNotFoundError('Version not found');
+    return c.json(serializeVersion(version));
+  });
+
+  // POST /records/:id/restore/:version — creates new version, does not rewrite history
+  app.post('/:id/restore/:version', requireAuth(), async (c) => {
+    const id = c.req.param('id');
+    const vNum = parsePositiveInt(c.req.param('version'), 'version number');
+    const auth = c.get('auth')!;
+    const restored = await stack
+      .forSession(auth)
+      .restoreVersion(id, vNum, { ifVersion: parseIfMatch(c.req.header('If-Match')) });
+    return c.json(serializeRecord(restored));
+  });
+
+  // POST /records/:id/migrate — the only way typeId changes after creation.
+  // The body carries the full post-migration content, computed client-side
+  // by the type's owning app and validated against toTypeId's schema by
+  // ScopedStack.commitMigration(). Owner acting alone only: replacing
+  // content and typeId wholesale would have to re-derive every gate
+  // create() and update() apply at both ends.
+  app.post('/:id/migrate', requireOwner(ownerEntityId), async (c) => {
+    const id = c.req.param('id');
+    const auth = c.get('auth')!;
+    const body = await readJson<Record<string, unknown>>(c);
+    if (!body.toTypeId || typeof body.toTypeId !== 'string')
+      throw new StackQueryError('toTypeId is required');
+    if (!body.content || typeof body.content !== 'object')
+      throw new StackQueryError('content is required');
+    if (!(await stack.getType(body.toTypeId as TypeId)))
+      throw new StackValidationError([
+        { path: 'toTypeId', message: `Unknown type: "${body.toTypeId}"` },
+      ]);
+
+    const migrated = await stack
+      .forSession(auth)
+      .commitMigration(id, body.toTypeId as TypeId, body.content as Record<string, unknown>, {
+        ifVersion: parseIfMatch(c.req.header('If-Match')),
+      });
+    return c.json(serializeRecord(migrated));
+  });
+
+  return app;
+}

package/src/routes/tokens.ts

@@ -0,0 +1,85 @@
+import { Hono } from 'hono';
+import type { AppEnv } from '../types.js';
+import type { StackContext } from '../stack.js';
+import { requireOwner } from '../middleware/auth.js';
+import { readJson } from '../lib/json.js';
+import { parseDate } from '@haverstack/wire-types';
+import { StackValidationError } from '@haverstack/core';
+import { isValidDid } from '@haverstack/core/did';
+import type { TokenInfo } from '@haverstack/core/wire';
+
+export function tokenRoutes(ctx: StackContext): Hono<AppEnv> {
+  const app = new Hono<AppEnv>();
+  const { tokens, stack } = ctx;
+  const ownerEntityId = stack.ownerEntityId;
+
+  // POST /tokens — issue a new token (owner only). `onBehalfOf` asserts a
+  // delegation out of band: the owner names the subject the issued
+  // principal acts for, per docs/spec/wire-format.md § The session a
+  // token names.
+  app.post('/', requireOwner(ownerEntityId), async (c) => {
+    const body = await readJson<{
+      entityId?: string;
+      onBehalfOf?: string;
+      label?: string;
+      expiresAt?: string;
+    }>(c);
+    if (body.entityId !== undefined && !isValidDid(body.entityId))
+      throw new StackValidationError([{ path: 'entityId', message: 'Must be a DID' }]);
+    if (body.onBehalfOf !== undefined && !isValidDid(body.onBehalfOf))
+      throw new StackValidationError([{ path: 'onBehalfOf', message: 'Must be a DID' }]);
+
+    const principalId = body.entityId ?? ownerEntityId;
+    const expiresAt = body.expiresAt ? parseDate(body.expiresAt) : undefined;
+    if (body.expiresAt && !expiresAt)
+      throw new StackValidationError([{ path: 'expiresAt', message: 'Invalid date' }]);
+
+    const { id, token } = await tokens.createToken(principalId, {
+      onBehalfOf: body.onBehalfOf,
+      label: body.label,
+      expiresAt,
+    });
+
+    // Read the row back rather than fabricating createdAt here — the store
+    // is the source of truth, and GET /tokens must report the same value.
+    const stored = (await tokens.listTokens()).find((t) => t.id === id)!;
+
+    return c.json(
+      {
+        id,
+        token,
+        principalId,
+        subjectId: body.onBehalfOf ?? principalId,
+        label: stored.label ?? null,
+        createdAt: stored.createdAt.toISOString(),
+        expiresAt: stored.expiresAt?.toISOString() ?? null,
+      },
+      201,
+    );
+  });
+
+  // GET /tokens — list all DB-managed tokens; never returns token values
+  app.get('/', requireOwner(ownerEntityId), async (c) => {
+    const list = await tokens.listTokens();
+    return c.json({ tokens: list.map(serializeToken) });
+  });
+
+  // DELETE /tokens/:id — revoke a token by its ID
+  app.delete('/:id', requireOwner(ownerEntityId), async (c) => {
+    await tokens.revokeToken(c.req.param('id'));
+    return c.body(null, 204);
+  });
+
+  return app;
+}
+
+function serializeToken(t: TokenInfo) {
+  return {
+    id: t.id,
+    principalId: t.principalId,
+    subjectId: t.subjectId,
+    label: t.label ?? null,
+    createdAt: t.createdAt.toISOString(),
+    expiresAt: t.expiresAt?.toISOString() ?? null,
+  };
+}