@haverstack/server 0.8.0

package/src/lib/resumeCursor.ts

@@ -0,0 +1,48 @@
+/**
+ * Resume cursor codec. A cursor is opaque and base64url by wire contract
+ * (`isValidSeq()` in @haverstack/wire-types), but this server's own are
+ * self-describing: `base64url(bufferId + ":" + n)`. That makes a presented
+ * cursor's origin checkable — a reconnect naming a buffer this server
+ * doesn't hold (a different filter, a restart, a buffer past its retention
+ * window) is caught rather than resumed against the wrong stream.
+ *
+ * Real base64url encoding of the whole string is what satisfies the
+ * charset rule automatically — there's no separate escaping step for the
+ * ":" delimiter, since it never appears in the encoded output.
+ */
+import { base64urlEncode, base64urlDecode } from '@haverstack/core/wire';
+
+export type DecodedCursor = {
+  bufferId: string;
+  n: number;
+};
+
+/** Mint a cursor naming one buffer's identity and position. */
+export function encodeCursor(bufferId: string, n: number): string {
+  return base64urlEncode(new TextEncoder().encode(`${bufferId}:${n}`));
+}
+
+/**
+ * Decode a presented cursor. Returns null for anything that doesn't parse
+ * as `bufferId + ":" + a non-negative integer` — never throws. A
+ * charset-valid cursor naming garbage is the same "cannot be honored" case
+ * an unrecognized buffer id is: answered with a `reset` frame, not a 400.
+ * (A charset-*invalid* cursor is refused before this is ever called — see
+ * `src/routes/changes.ts`.)
+ */
+export function decodeCursor(seq: string): DecodedCursor | null {
+  let text: string;
+  try {
+    text = new TextDecoder('utf-8', { fatal: true }).decode(base64urlDecode(seq));
+  } catch {
+    return null;
+  }
+  const colonIndex = text.lastIndexOf(':');
+  if (colonIndex === -1) return null;
+  const bufferId = text.slice(0, colonIndex);
+  const nText = text.slice(colonIndex + 1);
+  if (!/^\d+$/.test(nText)) return null;
+  const n = Number(nText);
+  if (!Number.isSafeInteger(n)) return null;
+  return { bufferId, n };
+}

package/src/lib/tokenSweep.ts

@@ -0,0 +1,43 @@
+import type { Logger } from 'pino';
+import type { StackTokenStore } from '@haverstack/core/wire';
+
+// Once an hour at most. The sweep is O(n) in tokens ever issued — cheap
+// relative to that interval, and never on the hot path twice in a row.
+const SWEEP_INTERVAL_MS = 60 * 60 * 1000;
+
+/**
+ * Delete tokens past their `expiresAt`.
+ *
+ * `lookupToken()` already refuses an expired token, so this changes no
+ * authorization outcome — it reclaims rows, and nothing else does: the
+ * store deletes only on an explicit `revokeToken()`. Since `POST
+ * /auth/token` is unauthenticated, strangers drive the row count, and
+ * unbounded growth costs disk and slows every `listTokens()` caller.
+ *
+ * Returns a throttled sweep — call it freely; it runs at most once per
+ * interval and never rejects, since failing to reclaim rows must not fail
+ * the request that happened to trigger it.
+ */
+export function createExpiredTokenSweeper(
+  tokens: StackTokenStore,
+  logger: Logger,
+): () => Promise<void> {
+  let lastSweptAt = 0;
+  return async () => {
+    const now = Date.now();
+    if (now - lastSweptAt < SWEEP_INTERVAL_MS) return;
+    // Claimed before the await, so two concurrent requests can't both start
+    // a sweep and race each other's revokeToken() calls.
+    lastSweptAt = now;
+    try {
+      const all = await tokens.listTokens();
+      const expired = all.filter((t) => t.expiresAt !== undefined && t.expiresAt.getTime() <= now);
+      for (const t of expired) await tokens.revokeToken(t.id);
+      if (expired.length > 0) {
+        logger.info({ revoked: expired.length }, 'Swept expired tokens');
+      }
+    } catch (err) {
+      logger.warn({ err }, 'Expired-token sweep failed');
+    }
+  };
+}

package/src/middleware/auth.ts

@@ -0,0 +1,77 @@
+import { timingSafeEqual } from 'node:crypto';
+import type { MiddlewareHandler } from 'hono';
+import { StackPermissionError } from '@haverstack/core';
+import type { TokenSession } from '@haverstack/core';
+import type { AppEnv } from '../types.js';
+import type { StackContext } from '../stack.js';
+import { wireError } from '../wireError.js';
+
+/**
+ * Constant-time string equality, for comparing a presented credential
+ * against a configured secret. Exported so every comparison of the owner
+ * token uses the same one — `GET /changes` re-derives "is this the owner"
+ * to decide whether to arm its session re-check.
+ */
+export function safeCompare(a: string, b: string): boolean {
+  const ba = Buffer.from(a);
+  const bb = Buffer.from(b);
+  return ba.length === bb.length && timingSafeEqual(ba, bb);
+}
+
+export function authMiddleware(ownerToken: string, ctx: StackContext): MiddlewareHandler<AppEnv> {
+  const ownerEntityId = ctx.stack.ownerEntityId;
+
+  return async (c, next) => {
+    const header = c.req.header('Authorization');
+    if (header === undefined) {
+      c.set('auth', null);
+    } else if (!header.startsWith('Bearer ')) {
+      // A credential that isn't a bearer token (`Basic ...`, a missing
+      // space) is a 401, never a silent downgrade to anonymous.
+      return wireError(c, 401, 'unauthorized', 'Missing or invalid bearer token');
+    } else {
+      const token = header.slice(7);
+      if (safeCompare(token, ownerToken)) {
+        c.set('auth', { principalId: ownerEntityId, subjectId: ownerEntityId });
+      } else {
+        const session = await ctx.tokens.lookupToken(token);
+        // Unknown, expired, or revoked is distinct from "none offered",
+        // and must not read as anonymous on optional-auth routes.
+        if (!session) return wireError(c, 401, 'unauthorized', 'Missing or invalid bearer token');
+        c.set('auth', session);
+      }
+    }
+    await next();
+  };
+}
+
+export function requireAuth(): MiddlewareHandler<AppEnv> {
+  return async (c, next) => {
+    if (!c.get('auth')) return wireError(c, 401, 'unauthorized', 'Missing or invalid bearer token');
+    await next();
+  };
+}
+
+/**
+ * Whether a session is the stack owner acting alone: undelegated, and
+ * authenticated as the owner rather than merely delegated for it. Being the
+ * owner is never on its own sufficient under delegation — a delegated
+ * session with the owner as principal still fails this, matching
+ * `ScopedStack`'s own owner-only gates (e.g. hard delete). See
+ * docs/spec/access-control.md § Delegation.
+ */
+export function isOwnerActingAlone(auth: TokenSession | null, ownerEntityId: string): boolean {
+  return auth?.principalId === ownerEntityId && auth?.subjectId === ownerEntityId;
+}
+
+/** Gates a route to the owner acting alone; see `isOwnerActingAlone()`. */
+export function requireOwner(ownerEntityId: string): MiddlewareHandler<AppEnv> {
+  return async (c, next) => {
+    const auth = c.get('auth');
+    if (!auth) return wireError(c, 401, 'unauthorized', 'Missing or invalid bearer token');
+    if (!isOwnerActingAlone(auth, ownerEntityId)) {
+      throw new StackPermissionError('Owner access required');
+    }
+    await next();
+  };
+}

package/src/middleware/errors.ts

@@ -0,0 +1,73 @@
+import type { ErrorHandler } from 'hono';
+import type { ContentfulStatusCode } from 'hono/utils/http-status';
+import type { Logger } from 'pino';
+import { StackPermissionError, StackNotFoundError, type Stack } from '@haverstack/core';
+import type { AppEnv } from '../types.js';
+import { serializeError } from '@haverstack/wire-types';
+
+/**
+ * Central error handler. `serializeError()` covers every core `StackError`
+ * (thrown directly by routes or surfaced from `Stack`/`ScopedStack`) with
+ * the wire-format's typed `{ error: { code, message } }` body. Anything
+ * else is an unanticipated bug: log it and return a bodyless 500 rather
+ * than guessing at a taxonomy it doesn't belong to.
+ *
+ * `stack` is the unscoped root Stack, used only to probe existence for the
+ * refusal log below — never to read content or bypass a permission check
+ * for the response itself.
+ */
+export function errorMiddleware(logger: Logger, stack: Stack): ErrorHandler<AppEnv> {
+  return async (err, c) => {
+    const wire = serializeError(err);
+    if (wire) {
+      // A denial with a resolved auth is a verified DID that lacked the
+      // grant, which docs/spec/identity.md asks be logged. Anonymous
+      // denials are bodyless 401s from wireError() and never reach here.
+      const auth = c.get('auth');
+      if (err instanceof StackPermissionError && auth) {
+        logger.warn(
+          {
+            requestId: c.get('requestId'),
+            principalId: auth.principalId,
+            subjectId: auth.subjectId,
+          },
+          'Denied a verified requester',
+        );
+      }
+      // On the wire a refused record is indistinguishable from a missing
+      // one (docs/spec/wire-format.md § Server implementation checklist),
+      // but the operator is not the adversary: an unscoped probe, on a path
+      // already failing, recovers the distinction for the log alone. Debug
+      // rather than warn — this is the sharing graph, which the spec asks
+      // stay out of a general-purpose aggregator by default.
+      if (err instanceof StackNotFoundError && auth) {
+        const recordId = c.req.param('id');
+        if (recordId) {
+          const existing = await stack.get(recordId);
+          logger.debug(
+            {
+              requestId: c.get('requestId'),
+              principalId: auth.principalId,
+              subjectId: auth.subjectId,
+              recordId,
+              existed: existing !== null,
+              // Always 'read': ScopedStack collapses to StackNotFoundError
+              // exactly when canRead() is false, whatever verb was asked.
+              check: 'read',
+            },
+            'Refused a verified requester a 404',
+          );
+        }
+      }
+      // A 401 or 403 to an anonymous caller would confirm the record
+      // exists to someone who presented no credential, so a private record
+      // and a missing one answer alike. `Bearer` (RFC 6750 §3) — not the
+      // `did-challenge` exchange discovery advertises for obtaining a
+      // token — keeps the login prompt reachable without reopening that.
+      if (wire.status === 404 && !auth) c.header('WWW-Authenticate', 'Bearer');
+      return c.json(wire.body, wire.status as ContentfulStatusCode);
+    }
+    logger.error({ err, requestId: c.get('requestId') }, 'Unhandled request error');
+    return c.json({ error: { code: 'internal', message: 'Internal server error' } }, 500);
+  };
+}

package/src/routes/attachments.ts

@@ -0,0 +1,126 @@
+import { Hono } from 'hono';
+import { bodyLimit } from 'hono/body-limit';
+import { StackPermissionError, StackPayloadTooLargeError } from '@haverstack/core';
+import {
+  resolveAttachmentDownloadContentType,
+  firstRecordedAttachment,
+  parseUploadFilename,
+  NOSNIFF_HEADER_NAME,
+  NOSNIFF_HEADER_VALUE,
+} from '@haverstack/core/wire';
+import { serializeRecord } from '@haverstack/wire-types';
+import type { AppEnv } from '../types.js';
+import type { StackContext } from '../stack.js';
+import { requireAuth, requireOwner } from '../middleware/auth.js';
+
+export function attachmentRoutes(ctx: StackContext, maxAttachmentBytes: number): Hono<AppEnv> {
+  const app = new Hono<AppEnv>();
+  const { stack } = ctx;
+  const { ownerEntityId } = stack;
+
+  // Aborts while reading the body, the moment the byte count passes the
+  // limit — no full-body buffer for an oversized upload, chunked or not.
+  const attachmentBodyLimit = bodyLimit({
+    maxSize: maxAttachmentBytes,
+    onError: () => {
+      throw new StackPayloadTooLargeError(
+        `Attachment exceeds the ${maxAttachmentBytes}-byte limit`,
+      );
+    },
+  });
+
+  // POST /attachments — stores the bytes and creates the _attachment@1
+  // metadata record in the same request, returning that record. Routed
+  // through ScopedStack.putAttachment() so the create-grant check on
+  // _attachment@1 runs before a single byte is written: an authenticated
+  // requester with no grant is refused, not merely denied a metadata
+  // record afterward. See docs/spec/wire-format.md § Upload.
+  app.post('/', attachmentBodyLimit, requireAuth(), async (c) => {
+    const auth = c.get('auth')!;
+    const mimeType = c.req.header('Content-Type') || 'application/octet-stream';
+    const filename = parseUploadFilename(c.req.header('Content-Disposition'));
+    const appId = c.req.query('appId') || undefined;
+
+    const data = new Uint8Array(await c.req.arrayBuffer());
+    const record = await stack.forSession(auth).putAttachment(data, mimeType, filename, appId);
+    return c.json(serializeRecord(record), 200);
+  });
+
+  // GET /attachments/:fileId — download
+  app.get('/:fileId', async (c) => {
+    const fileId = c.req.param('fileId');
+    const auth = c.get('auth');
+
+    let data: Uint8Array;
+    try {
+      data = await (auth ? stack.forSession(auth) : stack.asEntity(null)).getAttachment(fileId);
+    } catch (e) {
+      // Anonymous and denied is a transport-auth failure, distinct from an
+      // authenticated requester lacking access; everything else belongs to
+      // errorMiddleware. ScopedStack.getAttachment() already throws alike
+      // for missing and forbidden, so this handler owes no anti-oracle
+      // logic of its own — only to leave that answer intact.
+      if (!auth && e instanceof StackPermissionError) {
+        return c.json({ error: 'Unauthorized' }, 401);
+      }
+      throw e;
+    }
+
+    const metaRecords = await stack.getAttachmentRecords(fileId);
+    const firstRecord = firstRecordedAttachment(metaRecords);
+    const ownRecord = auth
+      ? firstRecordedAttachment(metaRecords.filter((r) => r.entityId === auth.subjectId))
+      : undefined;
+
+    const contentTypeParam = c.req.query('contentType');
+    const filenameParam = c.req.query('filename');
+
+    const { contentType, forced } = resolveAttachmentDownloadContentType({
+      contentTypeParam,
+      filenameParam,
+      storedMimeType: firstRecord?.content.mimeType,
+    });
+    // When the dangerous-type policy overrides the candidate, the filename
+    // goes too: forcing Content-Type alone won't stop a browser sniffing
+    // the body back into the original type without both nosniff and a
+    // non-inline disposition.
+    const filename = forced
+      ? undefined
+      : (filenameParam ?? ownRecord?.content.filename ?? firstRecord?.content.filename);
+
+    const disposition = filename
+      ? `attachment; filename*=UTF-8''${encodeURIComponent(filename)}`
+      : 'attachment';
+
+    return c.newResponse(data as unknown as Uint8Array<ArrayBuffer>, 200, {
+      'Content-Type': contentType,
+      'Content-Length': String(data.byteLength),
+      'Content-Disposition': disposition,
+      [NOSNIFF_HEADER_NAME]: NOSNIFF_HEADER_VALUE,
+    });
+  });
+
+  // DELETE /attachments/:fileId
+  app.delete('/:fileId', requireOwner(ownerEntityId), async (c) => {
+    const fileId = c.req.param('fileId');
+    await stack.deleteAttachment(fileId);
+    return c.body(null, 204);
+  });
+
+  // POST /attachments/gc — sweep and delete orphaned attachment bytes.
+  // Owner-only, invoke-only (no built-in scheduling): dryRun makes a
+  // cron-from-outside workflow safe. Body is entirely optional — every
+  // field defaults inside ScopedStack.collectAttachmentGarbage().
+  app.post('/gc', requireOwner(ownerEntityId), async (c) => {
+    const auth = c.get('auth')!;
+    const raw = await c.req.text();
+    const body = raw ? (JSON.parse(raw) as { graceMs?: number; dryRun?: boolean }) : {};
+    const result = await stack.forSession(auth).collectAttachmentGarbage({
+      ...(typeof body.graceMs === 'number' && { graceMs: body.graceMs }),
+      ...(body.dryRun === true && { dryRun: true }),
+    });
+    return c.json(result, 200);
+  });
+
+  return app;
+}

package/src/routes/auth.ts

@@ -0,0 +1,137 @@
+import { Hono } from 'hono';
+import type { ContentfulStatusCode } from 'hono/utils/http-status';
+import { verifyAuthChallenge, base64urlDecode } from '@haverstack/core/wire';
+import { isValidDidKey } from '@haverstack/core/did';
+import { WIRE_AUTH_ERROR_STATUS } from '@haverstack/wire-types';
+import type {
+  AuthChallengeRequest,
+  AuthChallengeResponse,
+  AuthTokenRequest,
+  AuthTokenResponse,
+  WireAuthErrorCode,
+} from '@haverstack/wire-types';
+import type { Context } from 'hono';
+import type { Logger } from 'pino';
+import type { AppEnv } from '../types.js';
+import type { StackContext } from '../stack.js';
+import { readJson } from '../lib/json.js';
+import { createExpiredTokenSweeper } from '../lib/tokenSweep.js';
+
+// The handshake never issues a delegated token: proving key possession
+// proves the principal and nothing about whom it may act for. It gets a
+// default TTL rather than the owner's choice of one, because a token
+// anyone can mint for themselves owes a bounded lifetime.
+const AUTH_TOKEN_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+// Stamped on every handshake-issued token. GET /tokens is the owner's only
+// view of what exists, and without this a self-service token is
+// indistinguishable from one the owner minted deliberately — so "revoke
+// everything the handshake handed out" would be an unanswerable question.
+const AUTH_TOKEN_LABEL = 'did-challenge';
+
+/**
+ * `{ error: { code, message } }` for the four handshake-specific codes,
+ * deliberately outside WireErrorCode — no Stack operation has begun at
+ * this point, so none of these maps to a StackError. See
+ * docs/spec/wire-format.md § Authentication.
+ */
+function authError(c: Context<AppEnv>, code: WireAuthErrorCode, message: string): Response {
+  return c.json({ error: { code, message } }, WIRE_AUTH_ERROR_STATUS[code] as ContentfulStatusCode);
+}
+
+export function authRoutes(ctx: StackContext, authOrigin: string, logger: Logger): Hono<AppEnv> {
+  const app = new Hono<AppEnv>();
+  const sweepExpiredTokens = createExpiredTokenSweeper(ctx.tokens, logger);
+
+  // POST /auth/challenge — issues a nonce bound to the requested DID.
+  // Unauthenticated: this is how a token is earned in the first place.
+  app.post('/challenge', async (c) => {
+    const body = await readJson<Partial<AuthChallengeRequest>>(c);
+    if (typeof body.did !== 'string' || !isValidDidKey(body.did)) {
+      return authError(c, 'invalid_did', 'Not a valid did:key');
+    }
+    const { nonce, expiresAt } = ctx.nonces.issue(body.did);
+    const response: AuthChallengeResponse = { nonce, expiresAt: expiresAt.toISOString() };
+    return c.json(response);
+  });
+
+  // POST /auth/token — redeems a signed nonce for a bearer token.
+  // Unauthenticated for the same reason.
+  app.post('/token', async (c) => {
+    const body = await readJson<Partial<AuthTokenRequest>>(c);
+    if (typeof body.did !== 'string' || !isValidDidKey(body.did)) {
+      return authError(c, 'invalid_did', 'Not a valid did:key');
+    }
+    // Checked ahead of the signature so a nonce issued to a different DID
+    // is refused as unknown_nonce even when the caller's own signature over
+    // it is perfectly valid — the nonce belongs to the DID it was issued
+    // for, not to whoever can produce a valid signature.
+    if (typeof body.nonce !== 'string') {
+      return authError(c, 'unknown_nonce', 'Unknown or already-used nonce');
+    }
+    if (typeof body.signature !== 'string') {
+      return authError(c, 'invalid_signature', 'Signature does not verify');
+    }
+
+    // Spent on this call regardless of what happens next — single-use
+    // means a redemption attempt consumes the nonce, not merely a
+    // successful one.
+    const result = ctx.nonces.redeem(body.did, body.nonce);
+    if (result === 'unknown') return authError(c, 'unknown_nonce', 'Unknown or already-used nonce');
+    if (result === 'expired') return authError(c, 'expired_nonce', 'Challenge has expired');
+
+    let signatureBytes: Uint8Array;
+    try {
+      signatureBytes = base64urlDecode(body.signature);
+    } catch {
+      return authError(c, 'invalid_signature', 'Signature does not verify');
+    }
+
+    // Built from our own configured public origin (authOrigin), never from
+    // a request header — Host/X-Forwarded-Host are client-controlled, and
+    // deriving the signed origin from either would let a client choose
+    // which origin it signs for, silently reopening the relay attack the
+    // origin binding exists to prevent.
+    const verified = await verifyAuthChallenge(
+      { origin: authOrigin, did: body.did, nonce: body.nonce },
+      signatureBytes,
+    ).catch(() => false);
+    if (!verified) return authError(c, 'invalid_signature', 'Signature does not verify');
+
+    // Reclaim expired rows before adding one. Throttled internally, so this
+    // is a no-op on all but the first handshake of each interval.
+    await sweepExpiredTokens();
+
+    // Undelegated by construction: principalId and subjectId are both the
+    // proven DID. Never let a client name its own subject.
+    const expiresAt = new Date(Date.now() + AUTH_TOKEN_TTL_MS);
+    const { token } = await ctx.tokens.createToken(body.did, {
+      expiresAt,
+      label: AUTH_TOKEN_LABEL,
+    });
+
+    // Reported from the value just written rather than read back through
+    // listTokens(), an unpaginated scan of every token ever issued — on an
+    // unauthenticated route that makes each handshake cost more than the
+    // last. The store persists the Date unchanged, so a read-back could
+    // only return what is already here.
+    const response: AuthTokenResponse = {
+      token,
+      expiresAt: expiresAt.toISOString(),
+      principalId: body.did,
+      subjectId: body.did,
+    };
+
+    // The one place a bearer token comes into existence without the owner
+    // doing anything, so it is the one place a log line is the only record
+    // that it happened. errorMiddleware already logs denied-but-verified
+    // requests; this is its counterpart on the granting side.
+    logger.info(
+      { requestId: c.get('requestId'), did: body.did, expiresAt: expiresAt.toISOString() },
+      'Issued a token via the DID challenge-response handshake',
+    );
+    return c.json(response);
+  });
+
+  return app;
+}