@haverstack/server 0.8.0 → 0.9.0

package/src/middleware/auth.ts

@@ -1,77 +0,0 @@
-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

@@ -1,73 +0,0 @@
-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

@@ -1,126 +0,0 @@
-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

@@ -1,137 +0,0 @@
-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;
-}