@antasphere/chassis-server 1.0.0

package/src/middleware/security-headers.ts

@@ -0,0 +1,129 @@
+import { createHash } from 'node:crypto';
+import type { MiddlewareHandler } from 'hono';
+import type { Env } from '../env.js';
+import type { RuntimeState } from '../state.js';
+
+/**
+ * Baseline headers on every response (brief §2.6). The CSP applies to HTML
+ * we serve (the dashboard SPA) and locks it to self — with hashes for the
+ * inline bootstrap script SvelteKit bakes into index.html, computed once at
+ * boot. User-uploaded content never renders on this origin (the files
+ * module forces attachment for active types), so this CSP is the only HTML
+ * policy the origin needs. frame-ancestors 'none' replaces X-Frame-Options.
+ */
+export function inlineScriptHashes(html: string): string[] {
+  const hashes: string[] = [];
+  const re = /<script(?![^>]*\bsrc=)[^>]*>([\s\S]*?)<\/script>/gi;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(html)) !== null) {
+    const body = match[1] ?? '';
+    if (body.trim().length === 0) continue;
+    hashes.push(`'sha256-${createHash('sha256').update(body).digest('base64')}'`);
+  }
+  return hashes;
+}
+
+export interface CspOptions {
+  /**
+   * Extra `frame-src` sources beyond 'self'. A dashboard may preview a resource in
+   * a sandboxed iframe whose URL honours VIEWER_BASE_URL (PRDCT-1352, DASH-4):
+   * with `default-src 'self'` and no `frame-src`, a split viewer origin made
+   * that preview a blank frame with no error anywhere but the console.
+   */
+  frameSrc?: readonly string[];
+  /**
+   * Extra `img-src` sources beyond 'self' and `data:`. A dashboard that
+   * fetches an image through its API (a request that must carry a header an
+   * `<img>` cannot send) shows it from an object URL, and `blob:` must be
+   * allowed for that or the browser refuses the picture with no error
+   * anywhere but the console. A scheme source here is a tool's declaration,
+   * never a chassis default.
+   */
+  imgSrc?: readonly string[];
+}
+
+export function buildCsp(scriptHashes: string[], { frameSrc = [], imgSrc = [] }: CspOptions = {}): string {
+  const script = ["'self'", ...scriptHashes].join(' ');
+  const frame = ["'self'", ...frameSrc].join(' ');
+  const img = ["'self'", 'data:', ...imgSrc].join(' ');
+  return [
+    "default-src 'self'",
+    `script-src ${script}`,
+    // Svelte injects component styles at runtime; hashes are impractical there.
+    // The two font CDNs the dashboard's app.html links (PRDCT-2308): the
+    // Observatory pairing rides Fontshare (Sentient, Synonym) and Google
+    // Fonts (Onest) because this repo is slated for the OSS cut and the
+    // faces may not be committed. Stylesheets from the two API hosts, the
+    // font files from their two file hosts, and nothing else — the
+    // dashboard's own origin stays the only script and connect source.
+    "style-src 'self' 'unsafe-inline' https://api.fontshare.com https://fonts.googleapis.com",
+    `img-src ${img}`,
+    "connect-src 'self'",
+    "font-src 'self' https://cdn.fontshare.com https://fonts.gstatic.com",
+    `frame-src ${frame}`,
+    "object-src 'none'",
+    "frame-ancestors 'none'",
+    "base-uri 'self'",
+    "form-action 'self'"
+  ].join('; ');
+}
+
+export interface SecurityHeaderOptions {
+  csp: string;
+  state: RuntimeState;
+  /**
+   * `Strict-Transport-Security` value, or null to send none. Computed once at
+   * boot from PUBLIC_BASE_URL + HSTS_MAX_AGE (see {@link hstsValue}) rather
+   * than sniffed per request: `X-Forwarded-Proto` is client-controlled unless
+   * TRUST_PROXY vouches for it, and this origin issues the session cookie —
+   * the operator's declared public scheme is the honest signal.
+   */
+  hsts?: string | null;
+}
+
+/**
+ * The HSTS header for this instance, or null when it must not be sent.
+ * Only an https PUBLIC_BASE_URL arms it: a browser MUST ignore HSTS received
+ * over plain http (RFC 6797 §7.2), and pinning an http-only self-host into
+ * https for 180 days would brick it. `HSTS_MAX_AGE=0` is the operator opt-out
+ * (e.g. a subdomain that cannot yet serve TLS).
+ */
+export function hstsValue(env: Pick<Env, 'PUBLIC_BASE_URL' | 'HSTS_MAX_AGE'>): string | null {
+  if (env.HSTS_MAX_AGE <= 0) return null;
+  let isHttps = false;
+  try {
+    isHttps = new URL(env.PUBLIC_BASE_URL).protocol === 'https:';
+  } catch {
+    isHttps = false;
+  }
+  if (!isHttps) return null;
+  return `max-age=${env.HSTS_MAX_AGE}; includeSubDomains`;
+}
+
+export function securityHeaders({ csp, state, hsts }: SecurityHeaderOptions): MiddlewareHandler {
+  return async (c, next) => {
+    await next();
+    c.header('x-content-type-options', 'nosniff');
+    // HSTS on EVERY response, not just HTML: the cookie this origin issues is
+    // sent with XHR too, so an http downgrade on /api/v1 is the same theft.
+    if (hsts && !c.res.headers.has('strict-transport-security')) {
+      c.header('strict-transport-security', hsts);
+    }
+    // Baseline defaults, but NEVER clobber a value a route set for itself:
+    // the public viewer (ADR 012) serves user-authored HTML under its own
+    // `Content-Security-Policy: sandbox …` + `Referrer-Policy: no-referrer`,
+    // and an unconditional overwrite here would silently replace the sandbox
+    // CSP with the dashboard CSP — re-opening the session-theft surface the
+    // sandbox exists to close (found by the ADR 012 spike; fail-dangerous
+    // class, see the ADR's residual-risk #1 and the viewer regression tests).
+    if (!c.res.headers.has('referrer-policy')) {
+      c.header('referrer-policy', 'strict-origin-when-cross-origin');
+    }
+    // Draining: ask keep-alive clients to reconnect elsewhere (rolling deploy).
+    if (state.draining) c.header('connection', 'close');
+    const contentType = c.res.headers.get('content-type') ?? '';
+    if (contentType.includes('text/html') && !c.res.headers.has('content-security-policy')) {
+      c.header('content-security-policy', csp);
+    }
+  };
+}

package/src/observability/index.ts

@@ -0,0 +1,2 @@
+export { type Otel, createOtel } from './otel.js';
+export { createMetrics } from './metrics.js';

package/src/observability/metrics.ts

@@ -0,0 +1,102 @@
+import { collectDefaultMetrics, Gauge, Histogram, Registry } from 'prom-client';
+import type { MiddlewareHandler } from 'hono';
+import { Hono } from 'hono';
+import { sql } from 'drizzle-orm';
+import { files, type Db } from '@antasphere/chassis-db';
+import type PgBoss from 'pg-boss';
+import { constantTimeEquals } from '../constant-time.js';
+import { USAGE_QUEUE } from '../jobs/pgboss.js';
+import { routeLabel } from '../route-label.js';
+
+/**
+ * Prometheus surface. Route labels use the MATCHED pattern (not the raw
+ * path) so label cardinality stays bounded. Queue depth and storage bytes
+ * are collected lazily at scrape time.
+ */
+export interface Metrics {
+  registry: Registry;
+  middleware: MiddlewareHandler;
+  routes: (token: string | undefined) => Hono;
+}
+
+export function createMetrics(db: Db, boss: PgBoss): Metrics {
+  const registry = new Registry();
+  collectDefaultMetrics({ register: registry });
+
+  const httpDuration = new Histogram({
+    name: 'http_request_duration_seconds',
+    help: 'HTTP request latency by route',
+    labelNames: ['method', 'route', 'status'] as const,
+    buckets: [0.005, 0.02, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
+    registers: [registry]
+  });
+
+  new Gauge({
+    name: 'job_queue_depth',
+    help: 'Pending jobs in the usage queue',
+    registers: [registry],
+    async collect() {
+      try {
+        this.set((await boss.getQueueSize(USAGE_QUEUE)) ?? 0);
+      } catch {
+        // queue may not exist yet (api-only role before first worker boot)
+      }
+    }
+  });
+
+  new Gauge({
+    name: 'storage_bytes_total',
+    help: 'Bytes referenced by live file rows',
+    registers: [registry],
+    async collect() {
+      const [row] = await db
+        .select({ total: sql<string>`coalesce(sum(${files.sizeBytes}), 0)::text` })
+        .from(files)
+        .where(sql`${files.deletedAt} IS NULL`);
+      this.set(Number(row?.total ?? '0'));
+    }
+  });
+
+  const middleware: MiddlewareHandler = async (c, next) => {
+    const start = performance.now();
+    try {
+      await next();
+    } finally {
+      const seconds = (performance.now() - start) / 1000;
+      httpDuration.observe(
+        {
+          method: c.req.method,
+          // routeLabel, same as the log line and the span: on the pinned
+          // Hono the previous `?? c.req.path` fallback was unreachable
+          // (routePath always answers a string here), but a raw-path
+          // expression in a label position is exactly what must not come
+          // back to life on a version bump — one shared, secret-free
+          // label instead (PRIV-1).
+          route: routeLabel(c),
+          status: String(c.error ? 500 : c.res.status)
+        },
+        seconds
+      );
+    }
+  };
+
+  const routes = (token: string | undefined): Hono => {
+    const app = new Hono();
+    app.get('/metrics', async (c) => {
+      // Default-closed: route names, queue depth, and storage totals are not
+      // for the open internet. setup.sh generates a METRICS_TOKEN.
+      if (!token) {
+        return c.text('metrics disabled: set METRICS_TOKEN', 401);
+      }
+      const auth = c.req.header('authorization') ?? '';
+      if (!constantTimeEquals(auth, `Bearer ${token}`)) {
+        return c.text('unauthorized', 401);
+      }
+      c.header('content-type', registry.contentType);
+      return c.body(await registry.metrics());
+    });
+    return app;
+  };
+
+  return { registry, middleware, routes };
+}

package/src/observability/otel.ts

@@ -0,0 +1,79 @@
+import { trace, type Tracer } from '@opentelemetry/api';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import type { MiddlewareHandler } from 'hono';
+import type { Env } from '../env.js';
+import type { Logger } from '../logger.js';
+import { routeLabel } from '../route-label.js';
+
+/**
+ * Tracing with the zero-phone-home default: spans are recorded ONLY when an
+ * operator configures OTEL_EXPORTER_OTLP_ENDPOINT — without it no exporter
+ * is registered and nothing leaves the instance. The request id rides every
+ * span as `request.id`, which is the correlation key across log line, span,
+ * and audit row.
+ */
+export interface Otel {
+  tracer: Tracer;
+  middleware: MiddlewareHandler;
+  shutdown: () => Promise<void>;
+}
+
+export async function createOtel(
+  env: Pick<Env, 'OTEL_EXPORTER_OTLP_ENDPOINT' | 'APP_VERSION' | 'EDITION'>,
+  logger: Logger,
+  options: { serviceName: string }
+): Promise<Otel> {
+  const resource = resourceFromAttributes({
+    'service.name': options.serviceName,
+    'service.version': env.APP_VERSION,
+    'deployment.environment.name': env.EDITION
+  });
+
+  const spanProcessors = [];
+  if (env.OTEL_EXPORTER_OTLP_ENDPOINT) {
+    const { OTLPTraceExporter } = await import('@opentelemetry/exporter-trace-otlp-http');
+    spanProcessors.push(
+      new BatchSpanProcessor(new OTLPTraceExporter({ url: `${env.OTEL_EXPORTER_OTLP_ENDPOINT}/v1/traces` }))
+    );
+    logger.info({ endpoint: env.OTEL_EXPORTER_OTLP_ENDPOINT }, 'otel export enabled');
+  }
+
+  const provider = new NodeTracerProvider({ resource, spanProcessors });
+  provider.register();
+  const tracer = trace.getTracer(options.serviceName);
+
+  const middleware: MiddlewareHandler = async (c, next) => {
+    // Start with a low-cardinality name (the matched route pattern isn't known
+    // until after routing); rename to the pattern in `finally` so span names
+    // stay bounded — a raw path with ids would explode span cardinality.
+    await tracer.startActiveSpan(`HTTP ${c.req.method}`, async (span) => {
+      span.setAttributes({
+        'http.request.method': c.req.method,
+        'request.id': c.get('requestId')
+      });
+      try {
+        await next();
+      } finally {
+        // The MATCHED ROUTE PATTERN, never the raw path (route-label.ts): a
+        // span attribute is exported OFF-INSTANCE, so a `/v/<share secret>`
+        // there hands a working capability to the trace backend.
+        const route = routeLabel(c);
+        span.updateName(`${c.req.method} ${route}`);
+        span.setAttributes({
+          'http.route': route,
+          'url.path': route,
+          'http.response.status_code': c.error ? 500 : c.res.status
+        });
+        span.end();
+      }
+    });
+  };
+
+  return {
+    tracer,
+    middleware,
+    shutdown: () => provider.shutdown()
+  };
+}

package/src/pagination.ts

@@ -0,0 +1,118 @@
+import { sql, type SQL } from 'drizzle-orm';
+import type { PgColumn, PgTable } from 'drizzle-orm/pg-core';
+
+/**
+ * Keyset (cursor) pagination over (created_at, id), newest first — the audit
+ * route's convention extended to the uuid-keyed tables. Two cursor dialects,
+ * one rule: the timestamp's precision never leaves Postgres, because a JS
+ * Date round-trip truncates its microseconds and a millisecond-equal
+ * boundary row would then be skipped or repeated.
+ *
+ *  - `keysetBefore`: the cursor is the last returned row's plain id, and the
+ *    timestamp is resolved from that row by subquery at page time. For the
+ *    tables that never hard-delete a row (members are deactivated, keys and
+ *    invitations revoked, projects archived): the cursor row is always there.
+ *  - `keysetBeforeValue`: the cursor CARRIES the timestamp, as the text
+ *    Postgres itself rendered (`created_at::text`, selected beside the row,
+ *    never a JS Date), with the id. For a table that hard-deletes rows
+ *    (project_members): a cursor naming a removed row would compare against
+ *    NULL under the subquery dialect and end the listing early.
+ */
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Shared UUID shape check — cursors here, and the id params of the
+ * plain-Hono routes that have no contract schema (files content/HEAD): a
+ * non-UUID string must be rejected before it reaches Postgres' uuid cast.
+ */
+export function isUuid(value: string): boolean {
+  return UUID_RE.test(value);
+}
+
+/**
+ * The cursor row id, or null when absent/malformed. A malformed cursor is
+ * silently ignored — the caller serves page 1 (the audit route's
+ * `Number('banana')` tolerance).
+ */
+export function cursorRowId(cursor: string | undefined): string | null {
+  if (!cursor || !isUuid(cursor)) return null;
+  return cursor;
+}
+
+/**
+ * Row-value keyset predicate: everything strictly older than the cursor row,
+ * with the cursor row's (created_at, id) resolved by a SQL-side subquery.
+ * The subquery is workspace-scoped so a foreign workspace's cursor can never
+ * position inside this workspace's ordering. A well-formed-but-unknown id
+ * makes the subquery empty → NULL predicate → empty page + nextCursor null;
+ * harmless, since cursors are server-issued and these tables never
+ * hard-delete rows.
+ */
+export function keysetBefore(opts: {
+  table: PgTable;
+  id: PgColumn;
+  createdAt: PgColumn;
+  workspaceId: PgColumn;
+  cursorId: string;
+  workspace: string;
+}): SQL {
+  return sql`(${opts.createdAt}, ${opts.id}) < (SELECT ${opts.createdAt}, ${opts.id} FROM ${opts.table} WHERE ${opts.id} = ${opts.cursorId} AND ${opts.workspaceId} = ${opts.workspace})`;
+}
+
+/** Slice a limit+1 fetch into the page + the audit-style nextCursor (last id of the page). */
+export function pageOf<T extends { id: string }>(
+  rows: T[],
+  limit: number
+): { page: T[]; nextCursor: string | null } {
+  const page = rows.slice(0, limit);
+  const nextCursor = rows.length > limit ? (page[page.length - 1]?.id ?? null) : null;
+  return { page, nextCursor };
+}
+
+/**
+ * The value-carrying cursor (`keysetBeforeValue`): the row's `created_at` as
+ * Postgres rendered it and its id, base64url of `<text>|<id>`. Opaque on the
+ * wire like the other dialect; a malformed one is ignored (page 1).
+ */
+const TIMESTAMPTZ_TEXT_RE =
+  /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}(?:\.\d{1,6})?[+-]\d{2}(?::\d{2}(?::\d{2})?)?$/;
+
+export interface KeysetValueCursor {
+  /** `created_at::text`, exactly as Postgres rendered it. */
+  createdAt: string;
+  id: string;
+}
+
+export function encodeKeysetCursor(row: { id: string; createdAtText: string }): string {
+  return Buffer.from(`${row.createdAtText}|${row.id}`, 'utf8').toString('base64url');
+}
+
+export function decodeKeysetCursor(cursor: string | undefined): KeysetValueCursor | null {
+  if (!cursor || cursor.length > 200) return null;
+  // Node's base64url decoder never throws (it drops what it cannot read):
+  // the guard is the two shape checks below, not the decode.
+  const decoded = Buffer.from(cursor, 'base64url').toString('utf8');
+  const at = decoded.lastIndexOf('|');
+  if (at < 0) return null;
+  const createdAt = decoded.slice(0, at);
+  const id = decoded.slice(at + 1);
+  // Both halves are validated before they reach a Postgres cast: a shape the
+  // casts would refuse must answer page 1, never a 500.
+  if (!TIMESTAMPTZ_TEXT_RE.test(createdAt) || !isUuid(id)) return null;
+  return { createdAt, id };
+}
+
+/** The `created_at::text` column to select beside a row that will mint a value cursor. */
+export function createdAtText(createdAt: PgColumn): SQL<string> {
+  return sql<string>`${createdAt}::text`;
+}
+
+/** `(created_at, id) < (cursor)` with the cursor's own values; `keysetBefore`'s twin for hard-deleting tables. */
+export function keysetBeforeValue(opts: {
+  id: PgColumn;
+  createdAt: PgColumn;
+  cursor: KeysetValueCursor;
+}): SQL {
+  return sql`(${opts.createdAt}, ${opts.id}) < (${opts.cursor.createdAt}::timestamptz, ${opts.cursor.id}::uuid)`;
+}

package/src/platform/edition.ts

@@ -0,0 +1,140 @@
+import type { Db } from '@antasphere/chassis-db';
+import type {
+  EntitlementService,
+  IdentityProvider,
+  InstanceAuthDescriptor,
+  Principal,
+  RequestContext,
+  UsageSink
+} from '@antasphere/chassis-contract';
+import { HUB_SSO_PROVIDER_ID } from '../identity/hub-sso.js';
+import { HubLiveGate } from '../identity/hub-live-gate.js';
+import type { HubOrgReconciler } from '../identity/hub-reconcile.js';
+import type { PrincipalGate } from '../middleware/auth-context.js';
+import type { HubConfig } from '../env.js';
+import type { Logger } from '../logger.js';
+
+/**
+ * The edition split (internal/federation.md): one codebase, one Docker image,
+ * two seam bindings selected purely by instance config. This module is the
+ * ONLY place edition decides which implementations the boot-time registry
+ * gets — `oss` binds the local defaults byte-identically; `cloud` rebinds
+ * the hub-federating variants here.
+ */
+
+/**
+ * The hub SSO method name the cloud edition advertises in discovery — the
+ * better-auth `genericOAuth` providerId registered by identity/hub-sso.ts
+ * (its callback lands on /api/v1/auth/oauth2/callback/antasphere, the
+ * redirect URI in the hub's TOOL_REGISTRY entry).
+ */
+export const HUB_SSO_METHOD = HUB_SSO_PROVIDER_ID;
+
+/**
+ * The cloud identity binding. Request RESOLUTION stays exactly the local
+ * provider's — after the SSO callback mints an ordinary session, every
+ * request is sessions + live membership re-check (the live hub gate runs
+ * post-resolution in authContext, not here). What changes is the ADVERTISED
+ * entrance (D1, hub-only human login):
+ *
+ *  - `antasphere` replaces password/email-otp/google — the login page
+ *    renders ONLY "Sign in with Antasphere". The local password machinery
+ *    stays WIRED (hidden, not blocked): the break-glass CLI remains the
+ *    operator door, and blocking /sign-in/email would dead-end it.
+ *  - `passwordReset`/`emailChange` are off: credentials and email are the
+ *    HUB's to manage (D10 re-syncs email at every login); a local reset
+ *    surface would fight the sync. Since the P8 close (ADR 017) the reset
+ *    routes don't just report false — they REFUSE on cloud (403; the
+ *    before-hook in identity/better-auth.ts + the members reset-link mint),
+ *    so a hub-JIT user can never SET a local password and sidestep SSO.
+ *  - `twoFactor` is off: the second factor guards local password/OTP
+ *    sign-ins, which the cloud page no longer offers — MFA is the hub's
+ *    concern at its own login.
+ */
+class HubSsoIdentityProvider implements IdentityProvider {
+  constructor(private readonly local: IdentityProvider) {}
+
+  resolve(ctx: RequestContext): Promise<Principal | null> {
+    return this.local.resolve(ctx);
+  }
+
+  describe(): InstanceAuthDescriptor {
+    return {
+      // Machine entrances are edition-independent; the human entrance is
+      // hub-only. 'oauth' stays: every instance is its own OAuth 2.1 AS for
+      // /mcp — the hub never appears in the MCP dance.
+      methods: [HUB_SSO_METHOD, 'api-key', 'oauth'],
+      passwordReset: false,
+      emailChange: false,
+      twoFactor: false
+    };
+  }
+}
+
+/** The three registry seams the edition owns (events/workspaces are edition-independent). */
+export interface EditionSeams {
+  identity: IdentityProvider;
+  entitlements: EntitlementService;
+  usage: UsageSink;
+}
+
+/** What the cloud bindings need beyond the seams themselves. */
+export interface EditionBindingDeps {
+  db: Db;
+  /**
+   * The live org reconciler (identity/hub-reconcile.ts), constructed by
+   * boot on cloud — the ONE hub data path, shared by the login pass, the
+   * live gate, and the unknown-workspace miss hook.
+   */
+  reconciler?: HubOrgReconciler | undefined;
+}
+
+/**
+ * The bound seams plus the cloud-only extra boot wires alongside them: the
+ * post-resolution principal gate (authContext). Absent on oss by
+ * construction.
+ */
+export interface BoundEditionSeams extends EditionSeams {
+  principalGate?: PrincipalGate;
+}
+
+/**
+ * Bind the registry seams for this instance's edition. `hub` is the single
+ * switch: null (EDITION=oss) returns the local defaults UNTOUCHED — the
+ * self-host edition carries zero hub surface at runtime; a HubConfig
+ * (EDITION=cloud, validated at env parse) selects the cloud bindings.
+ *
+ * Entitlements bind LOCAL on BOTH editions: the live gate refuses a
+ * suspended/revoked/unavailable principal at the door, before any handler
+ * or entitlement check runs — a hub-wrapping entitlement layer would be a
+ * second, redundant enforcement path.
+ */
+export function bindEditionSeams(
+  hub: HubConfig | null,
+  local: EditionSeams,
+  logger: Logger,
+  deps: EditionBindingDeps
+): BoundEditionSeams {
+  if (!hub) return local;
+
+  logger.info(
+    { hubIssuer: hub.issuerUrl },
+    'EDITION=cloud: hub SSO is the human entrance (identity resolution stays local sessions); ' +
+      'org/membership truth is reconciled live AS THE USER via each user’s own hub grant ' +
+      '(internal/federation.md).'
+  );
+  const gate = deps.reconciler
+    ? new HubLiveGate({ db: deps.db, reconciler: deps.reconciler, logger })
+    : undefined;
+  return {
+    // Hub-only entrance advertised; the SSO machinery itself (relying
+    // party, JIT, login reconcile) lives in identity/hub-sso.ts and is
+    // wired through createAuth — resolution stays local by design.
+    identity: new HubSsoIdentityProvider(local.identity),
+    entitlements: local.entitlements,
+    // D6: usage stays the local sink with a no-op downstream for v1; hub
+    // ingest is a one-class downstream swap when it ships (plan §4.3).
+    usage: local.usage,
+    ...(gate ? { principalGate: gate.assert } : {})
+  };
+}

package/src/platform/entitlements.ts

@@ -0,0 +1,47 @@
+import type {
+  EntitlementDecision,
+  EntitlementService,
+  MeteredAction,
+  Principal,
+  RequestQuota
+} from '@antasphere/chassis-contract';
+
+/**
+ * Default EntitlementService: everything is allowed, bounded only by
+ * instance-level env caps. The cloud/central edition swaps this via the
+ * registry for a credits-backed implementation; handlers only ever call
+ * `entitlements.check(...)` and never know the difference.
+ */
+export interface InstanceCaps {
+  maxFileSizeMb: number;
+  /** General-API quota defaults: sustained per-minute + 1 s spike cap (env-driven). */
+  apiRequestsPerMinute: number;
+  apiRequestsBurstPerSecond: number;
+}
+
+export class AllowAllEntitlements implements EntitlementService {
+  constructor(private readonly caps: InstanceCaps) {}
+
+  async check(_principal: Principal, action: MeteredAction): Promise<EntitlementDecision> {
+    if (action.key === 'files.upload' && action.unit === 'bytes') {
+      const max = this.caps.maxFileSizeMb * 1024 * 1024;
+      if (action.quantity > max) {
+        return { allowed: false, reason: `file exceeds MAX_FILE_SIZE_MB (${this.caps.maxFileSizeMb}MB)` };
+      }
+    }
+    return { allowed: true };
+  }
+
+  /**
+   * One flat instance-level quota for every principal. A plan-aware edition
+   * returns different values per plan here — the enforcing middleware keys
+   * buckets by (quota size, principal), so per-plan variation needs no other
+   * change.
+   */
+  async getRequestQuota(_principal: Principal): Promise<RequestQuota> {
+    return {
+      perMinute: this.caps.apiRequestsPerMinute,
+      burstPerSecond: this.caps.apiRequestsBurstPerSecond
+    };
+  }
+}