@haverstack/server 0.8.0 → 0.9.0

package/src/app.ts

@@ -1,86 +0,0 @@
-import { Hono } from 'hono';
-import { cors } from 'hono/cors';
-import { bodyLimit } from 'hono/body-limit';
-import { StackPayloadTooLargeError } from '@haverstack/core';
-import type { Logger } from 'pino';
-import type { StackContext } from './stack.js';
-import type { Config } from './config.js';
-import type { AppEnv } from './types.js';
-import { authMiddleware } from './middleware/auth.js';
-import { errorMiddleware } from './middleware/errors.js';
-import { wellknownRoutes } from './routes/wellknown.js';
-import { healthRoutes } from './routes/health.js';
-import { recordRoutes } from './routes/records.js';
-import { changeRoutes } from './routes/changes.js';
-import { typeRoutes } from './routes/types.js';
-import { attachmentRoutes } from './routes/attachments.js';
-import { entityRoutes } from './routes/entity.js';
-import { tokenRoutes } from './routes/tokens.js';
-import { authRoutes } from './routes/auth.js';
-import { wireError } from './wireError.js';
-
-export type { AppEnv };
-
-export function createApp(ctx: StackContext, config: Config, logger: Logger): Hono<AppEnv> {
-  const app = new Hono<AppEnv>();
-
-  // Assign a unique request ID to every request and expose it on the response.
-  app.use(async (c, next) => {
-    const id = crypto.randomUUID();
-    c.set('requestId', id);
-    await next();
-    c.header('X-Request-Id', id);
-  });
-
-  app.use(
-    cors({
-      origin:
-        config.corsOrigins === '*'
-          ? '*'
-          : config.corsOrigins
-            ? config.corsOrigins.split(',').map((s) => s.trim())
-            : [],
-      allowMethods: ['GET', 'POST', 'PATCH', 'PUT', 'DELETE'],
-      // Last-Event-ID: a browser resuming GET /changes sends it as a plain
-      // header (fetch, not EventSource, per the feed's no-token-in-the-URL
-      // rule). Omitted here, a cross-origin resume never reaches the route
-      // that would answer it with `reset`.
-      allowHeaders: ['Authorization', 'Content-Type', 'Content-Disposition', 'Last-Event-ID'],
-      exposeHeaders: ['X-Request-Id', 'Content-Disposition'],
-    }),
-  );
-  app.onError(errorMiddleware(logger, ctx.stack));
-  app.use(authMiddleware(config.ownerToken, ctx));
-
-  // Global rather than per-prefix, so a route added later can't end up with
-  // no limit at all. POST /attachments is the one exception: it enforces its
-  // own, larger ceiling, and running this one first would reject legitimate
-  // uploads before that check ran. Thrown as a StackError so
-  // errorMiddleware produces the conforming body, like any other failure.
-  const jsonBodyLimit = bodyLimit({
-    maxSize: config.maxContentBytes,
-    onError: () => {
-      throw new StackPayloadTooLargeError(
-        `Request body exceeds the ${config.maxContentBytes}-byte limit`,
-      );
-    },
-  });
-  app.use('*', async (c, next) => {
-    if (c.req.method === 'POST' && c.req.path === '/attachments') return next();
-    return jsonBodyLimit(c, next);
-  });
-
-  app.route('/.well-known', wellknownRoutes(ctx, config));
-  app.route('/health', healthRoutes());
-  app.route('/records', recordRoutes(ctx, config.queryTimeoutMs));
-  app.route('/changes', changeRoutes(ctx, config, logger));
-  app.route('/types', typeRoutes(ctx));
-  app.route('/attachments', attachmentRoutes(ctx, config.maxAttachmentBytes));
-  app.route('/entity', entityRoutes(ctx));
-  app.route('/tokens', tokenRoutes(ctx));
-  app.route('/auth', authRoutes(ctx, config.authOrigin, logger));
-
-  app.notFound((c) => wireError(c, 404, 'not_found', 'Not found'));
-
-  return app;
-}

package/src/config.ts

@@ -1,176 +0,0 @@
-import { isValidDid } from '@haverstack/core/did';
-import { authOriginFromUrl } from '@haverstack/core/wire';
-
-const DEFAULT_MAX_ATTACHMENT_BYTES = 50 * 1024 * 1024; // 50 MB
-const DEFAULT_MAX_CONTENT_BYTES = 1 * 1024 * 1024; // 1 MB
-const DEFAULT_QUERY_TIMEOUT_MS = 10_000;
-const DEFAULT_SHUTDOWN_TIMEOUT_MS = 10_000;
-const DEFAULT_QUERY_WORKER_POOL_SIZE = 2;
-// Each worker is a thread plus its own SQLite connection to the same file,
-// so an accidental extra zero here is expensive in a way the other limits
-// aren't. The ceiling is a sanity bound, not a tuning recommendation.
-const MAX_QUERY_WORKER_POOL_SIZE = 32;
-const DEFAULT_QUERY_QUEUE_LIMIT = 64;
-const MAX_QUERY_QUEUE_LIMIT = 10_000;
-
-function required(name: string): string {
-  const val = process.env[name];
-  if (!val) throw new Error(`Missing required environment variable: ${name}`);
-  return val;
-}
-
-function optional(name: string, fallback: string): string {
-  return process.env[name] ?? fallback;
-}
-
-export type Config = {
-  port: number;
-  dbPath: string;
-  entityId: string | null;
-  ownerName: string | null;
-  ownerHandle: string | null;
-  timezone: string | undefined;
-  ownerToken: string;
-  corsOrigins: string;
-  baseUrl: string;
-  authOrigin: string;
-  maxAttachmentBytes: number;
-  maxContentBytes: number;
-  queryTimeoutMs: number;
-  queryWorkerPoolSize: number;
-  queryQueueLimit: number;
-  seedCommonsTypes: boolean;
-  shutdownTimeoutMs: number;
-};
-
-export function loadConfig(): Config {
-  const dbPath = required('DB_PATH');
-
-  const entityId = process.env['ENTITY_ID'] ?? null;
-  if (entityId && !isValidDid(entityId)) {
-    throw new Error(
-      `ENTITY_ID must be a DID (e.g. "did:key:z6Mk..."), got: "${entityId}". ` +
-        'See docs/spec/identity.md for how to generate one.',
-    );
-  }
-  const ownerName = process.env['OWNER_NAME'] ?? null;
-  const ownerHandle = process.env['OWNER_HANDLE'] ?? null;
-  // No default: an absent timezone stays undefined end to end rather than
-  // asserting knowledge the stack was never actually given. See
-  // docs/spec/wire-format.md § Discovery.
-  const timezone = process.env['TIMEZONE'] ?? undefined;
-
-  const port = parseInt(optional('PORT', '3000'), 10);
-  if (isNaN(port) || port < 1 || port > 65535) {
-    throw new Error(`Invalid PORT: ${process.env['PORT']}`);
-  }
-
-  const maxAttachmentBytes = parseInt(
-    optional('MAX_ATTACHMENT_BYTES', String(DEFAULT_MAX_ATTACHMENT_BYTES)),
-    10,
-  );
-  if (isNaN(maxAttachmentBytes) || maxAttachmentBytes < 1) {
-    throw new Error(`Invalid MAX_ATTACHMENT_BYTES: ${process.env['MAX_ATTACHMENT_BYTES']}`);
-  }
-
-  const maxContentBytes = parseInt(
-    optional('MAX_CONTENT_BYTES', String(DEFAULT_MAX_CONTENT_BYTES)),
-    10,
-  );
-  if (isNaN(maxContentBytes) || maxContentBytes < 1) {
-    throw new Error(`Invalid MAX_CONTENT_BYTES: ${process.env['MAX_CONTENT_BYTES']}`);
-  }
-
-  // Bounds a query *executing* on the worker pool, never its wait for a
-  // slot — that is QUERY_QUEUE_LIMIT's job, so ordinary contention makes a
-  // search slow rather than failed. See src/lib/queryWorker/pool.ts.
-  const queryTimeoutMs = parseInt(
-    optional('QUERY_TIMEOUT_MS', String(DEFAULT_QUERY_TIMEOUT_MS)),
-    10,
-  );
-  if (isNaN(queryTimeoutMs) || queryTimeoutMs < 1) {
-    throw new Error(`Invalid QUERY_TIMEOUT_MS: ${process.env['QUERY_TIMEOUT_MS']}`);
-  }
-
-  const queryWorkerPoolSize = parseInt(
-    optional('QUERY_WORKER_POOL_SIZE', String(DEFAULT_QUERY_WORKER_POOL_SIZE)),
-    10,
-  );
-  if (
-    isNaN(queryWorkerPoolSize) ||
-    queryWorkerPoolSize < 1 ||
-    queryWorkerPoolSize > MAX_QUERY_WORKER_POOL_SIZE
-  ) {
-    throw new Error(
-      `Invalid QUERY_WORKER_POOL_SIZE: ${process.env['QUERY_WORKER_POOL_SIZE']} ` +
-        `(expected 1-${MAX_QUERY_WORKER_POOL_SIZE})`,
-    );
-  }
-
-  // How many searches may wait for a worker before the pool sheds load
-  // with 503 `timeout` instead of queueing further. This is what keeps
-  // "slow under contention" from becoming an unbounded queue.
-  const queryQueueLimit = parseInt(
-    optional('QUERY_QUEUE_LIMIT', String(DEFAULT_QUERY_QUEUE_LIMIT)),
-    10,
-  );
-  if (isNaN(queryQueueLimit) || queryQueueLimit < 1 || queryQueueLimit > MAX_QUERY_QUEUE_LIMIT) {
-    throw new Error(
-      `Invalid QUERY_QUEUE_LIMIT: ${process.env['QUERY_QUEUE_LIMIT']} ` +
-        `(expected 1-${MAX_QUERY_QUEUE_LIMIT})`,
-    );
-  }
-
-  // How long shutdown() lets in-flight and keep-alive connections drain
-  // before forcing them closed and finishing the sequence anyway.
-  const shutdownTimeoutMs = parseInt(
-    optional('SHUTDOWN_TIMEOUT_MS', String(DEFAULT_SHUTDOWN_TIMEOUT_MS)),
-    10,
-  );
-  if (isNaN(shutdownTimeoutMs) || shutdownTimeoutMs < 1) {
-    throw new Error(`Invalid SHUTDOWN_TIMEOUT_MS: ${process.env['SHUTDOWN_TIMEOUT_MS']}`);
-  }
-
-  // Opt-in: @haverstack/commons is Draft status, so its definitions may
-  // change in place, and a registered type shows up in GET /types and every
-  // app's type cache whether or not that app wants it. See
-  // docs/deployment.md § Schema Commons seeding.
-  const seedCommonsTypes = optional('SEED_COMMONS_TYPES', 'false') === 'true';
-
-  // Required rather than auto-detected: the handshake signs a payload
-  // scoped to this server's public origin, and taking that from a
-  // client-controlled header (Host, X-Forwarded-Host) would let a client
-  // pick the origin it signs for, reopening the relay attack the binding
-  // closes. See docs/spec/wire-format.md § Authentication.
-  const baseUrl = required('BASE_URL');
-  let authOrigin: string;
-  try {
-    authOrigin = authOriginFromUrl(baseUrl);
-  } catch (err) {
-    throw new Error(
-      `BASE_URL must be an absolute URL with an origin (e.g. "https://stack.example.com"), got: "${baseUrl}". ` +
-        (err instanceof Error ? err.message : String(err)),
-      { cause: err },
-    );
-  }
-
-  return {
-    port,
-    dbPath,
-    entityId,
-    ownerName,
-    ownerHandle,
-    timezone,
-    ownerToken: required('OWNER_TOKEN'),
-    corsOrigins: optional('CORS_ORIGINS', ''),
-    baseUrl,
-    authOrigin,
-    maxAttachmentBytes,
-    maxContentBytes,
-    queryTimeoutMs,
-    queryWorkerPoolSize,
-    queryQueueLimit,
-    seedCommonsTypes,
-    shutdownTimeoutMs,
-  };
-}

package/src/index.ts

@@ -1,54 +0,0 @@
-import { serve } from '@hono/node-server';
-import pino from 'pino';
-import { loadConfig } from './config.js';
-import { initStack, type StackContext } from './stack.js';
-import { createApp } from './app.js';
-import { createShutdownHandler } from './shutdown.js';
-
-const logger = pino({
-  level: process.env['LOG_LEVEL'] ?? 'info',
-  transport:
-    process.env['NODE_ENV'] !== 'production'
-      ? { target: 'pino-pretty', options: { colorize: true } }
-      : undefined,
-});
-
-// Set once initStack() resolves, so the fatal-error handler below can flush
-// a crash that happens after startup. Undefined before then: nothing to
-// flush yet.
-let ctx: StackContext | undefined;
-
-async function main() {
-  const config = loadConfig();
-  ctx = await initStack(config, logger);
-  const app = createApp(ctx, config, logger);
-
-  logger.info({ dbPath: config.dbPath }, 'Stack initialized');
-
-  const server = serve({ fetch: app.fetch, port: config.port }, (info) => {
-    logger.info({ port: info.port }, 'Server listening');
-  });
-
-  const shutdown = createShutdownHandler(server, ctx, logger, config.shutdownTimeoutMs);
-  const onSignal = (signal: string) => {
-    shutdown(signal)
-      .then(() => process.exit(0))
-      .catch((err) => {
-        logger.error({ err }, 'Error during shutdown');
-        process.exit(1);
-      });
-  };
-
-  process.on('SIGTERM', () => onSignal('SIGTERM'));
-  process.on('SIGINT', () => onSignal('SIGINT'));
-}
-
-main().catch(async (err) => {
-  logger.error({ err }, 'Fatal startup error');
-  if (ctx) {
-    await ctx.stack.flush().catch((flushErr) => {
-      logger.error({ err: flushErr }, 'Failed to flush during fatal-error shutdown');
-    });
-  }
-  process.exit(1);
-});

package/src/lib/frameGate.ts

@@ -1,42 +0,0 @@
-/**
- * Bounds a change-feed connection's in-flight frame count. Each accepted
- * send is paired with the write that delivers it; once `maxPending` sends
- * are outstanding at once — a client that isn't draining as fast as
- * changes arrive — the gate reports overflow instead of queuing further
- * sends without bound.
- *
- * Close on overflow, never drop a frame silently: a client that can't tell
- * it missed something can't repair it either, so dropping is worse than
- * disconnecting and letting it reconnect and reconcile.
- */
-export class FrameGate {
-  private pending = 0;
-  private overflowed = false;
-
-  constructor(
-    private readonly maxPending: number,
-    private readonly onOverflow: () => void,
-  ) {}
-
-  /**
-   * Accepts one send if there's room, invoking `write` and tracking it
-   * until it settles. Returns whether it was accepted; a `false` return
-   * means this call (and every one after it) triggered — or already
-   * followed — overflow, and `onOverflow` has fired at most once.
-   */
-  send(write: () => Promise<unknown>): boolean {
-    if (this.overflowed) return false;
-    if (this.pending >= this.maxPending) {
-      this.overflowed = true;
-      this.onOverflow();
-      return false;
-    }
-    this.pending++;
-    write()
-      .catch(() => {})
-      .finally(() => {
-        this.pending--;
-      });
-    return true;
-  }
-}

package/src/lib/json.ts

@@ -1,27 +0,0 @@
-import type { Context } from 'hono';
-import { StackQueryError } from '@haverstack/core';
-import type { AppEnv } from '../types.js';
-
-/**
- * `c.req.json()` throws a bare `SyntaxError` on malformed input, which isn't
- * a `StackError` — left uncaught it falls through errorMiddleware's
- * catch-all as an unlabeled 500 instead of the 400 `bad_request` every other
- * structurally-invalid request gets (docs/spec/wire-format.md § 400 vs 422).
- */
-export async function readJson<T = unknown>(c: Context<AppEnv>): Promise<T> {
-  let parsed: unknown;
-  try {
-    parsed = await c.req.json<T>();
-  } catch (err) {
-    if (err instanceof SyntaxError) throw new StackQueryError('Invalid JSON in request body');
-    throw err;
-  }
-  // `null`, a bare string or a number parses fine, but every call site
-  // indexes fields off the result, so a non-object reaches the handler and
-  // throws a bare TypeError — another unlabeled 500, unauthenticated on the
-  // /auth routes. Structurally invalid like malformed JSON, so a 400 too.
-  if (parsed === null || typeof parsed !== 'object') {
-    throw new StackQueryError('Request body must be a JSON object');
-  }
-  return parsed as T;
-}

package/src/lib/nonceStore.ts

@@ -1,103 +0,0 @@
-import { DatabaseSync } from 'node:sqlite';
-import { base64urlEncode } from '@haverstack/core/wire';
-
-// Matches the ~5-minute issued→expires gap in the handshake conformance
-// fixtures (@haverstack/conformance-fixtures' authChallengeFixtures).
-const NONCE_TTL_MS = 5 * 60 * 1000;
-// 18 raw bytes base64url-encodes to 24 characters — short, opaque, and
-// comfortably unguessable for a value that's live for minutes, not stored
-// long-term like a token.
-const NONCE_BYTES = 18;
-
-/** Conventional sibling path for the nonce store beside a stack's main .db file. */
-export const defaultNonceStorePath = (dbPath: string): string => `${dbPath}.nonces`;
-
-export type NonceRedeemResult = 'ok' | 'unknown' | 'expired';
-
-/**
- * Single-use, DID-bound nonces for the DID challenge–response handshake
- * (POST /auth/challenge, POST /auth/token). Core verifies signatures but
- * deliberately doesn't run a server, so nonce storage, single-use
- * enforcement, and DID binding are this server's own to implement — see
- * docs/spec/wire-format.md § Authentication.
- *
- * Kept beside the token store (its own sibling file) rather than in the
- * portable stack file or in memory, so a restart doesn't silently make
- * every in-flight handshake unrecoverable. node:sqlite, like
- * NativeTokenStore — no extra dependency.
- */
-export class AuthNonceStore {
-  private constructor(private readonly db: DatabaseSync) {}
-
-  static open(path: string): AuthNonceStore {
-    const db = new DatabaseSync(path);
-    db.exec('PRAGMA journal_mode = WAL;');
-    db.exec(
-      `CREATE TABLE IF NOT EXISTS nonces (
-        nonce TEXT PRIMARY KEY,
-        did TEXT NOT NULL,
-        expiresAt INTEGER NOT NULL
-      );`,
-    );
-    // sweepExpired() runs on every issue(), and POST /auth/challenge is
-    // unauthenticated — without this the sweep is a full table scan whose
-    // cost rises with the issue rate, so the endpoint would pay more the
-    // harder it is hit.
-    db.exec('CREATE INDEX IF NOT EXISTS idx_nonces_expiresAt ON nonces (expiresAt);');
-    return new AuthNonceStore(db);
-  }
-
-  issue(did: string): { nonce: string; expiresAt: Date } {
-    this.sweepExpired();
-    const nonce = base64urlEncode(crypto.getRandomValues(new Uint8Array(NONCE_BYTES)));
-    const expiresAt = new Date(Date.now() + NONCE_TTL_MS);
-    this.db
-      .prepare('INSERT INTO nonces (nonce, did, expiresAt) VALUES (?, ?, ?)')
-      .run(nonce, did, expiresAt.getTime());
-    return { nonce, expiresAt };
-  }
-
-  /**
-   * Checks and spends a nonce in one step — single-use means a redemption
-   * consumes it regardless of outcome, not merely observes it. A missing
-   * nonce and one bound to a different DID both report 'unknown': a server
-   * MUST NOT let a caller distinguish never-issued from already-spent, or
-   * spent-by-someone-else, since the difference only tells an attacker
-   * something.
-   *
-   * One `DELETE ... RETURNING` rather than a SELECT then a DELETE, which
-   * would be indivisible only for as long as nothing awaits between the two
-   * statements — an invariant no reader can see. The `did` predicate sits in
-   * the WHERE clause, so a mismatch deletes nothing.
-   */
-  redeem(did: string, nonce: string): NonceRedeemResult {
-    const row = this.db
-      .prepare('DELETE FROM nonces WHERE nonce = ? AND did = ? RETURNING expiresAt')
-      .get(nonce, did) as { expiresAt: number } | undefined;
-    if (!row) return 'unknown';
-    if (Date.now() > row.expiresAt) return 'expired';
-    return 'ok';
-  }
-
-  /**
-   * Seeds a nonce with a caller-chosen value rather than a random one.
-   * Production code never needs this — issue() is the only way a nonce is
-   * meant to come into existence — but a conformance fixture carrying a
-   * real signature is signed over one exact, fixed nonce value, so tests
-   * need a way to get that value into the store directly. Named for what
-   * it is so no production call site can reach for it without saying so.
-   */
-  seedForTesting(nonce: string, did: string, expiresAt: Date): void {
-    this.db
-      .prepare('INSERT OR REPLACE INTO nonces (nonce, did, expiresAt) VALUES (?, ?, ?)')
-      .run(nonce, did, expiresAt.getTime());
-  }
-
-  private sweepExpired(): void {
-    this.db.prepare('DELETE FROM nonces WHERE expiresAt < ?').run(Date.now());
-  }
-
-  close(): void {
-    this.db.close();
-  }
-}