@antasphere/chassis-server 1.0.0

package/src/middleware/auth-context.ts

@@ -0,0 +1,384 @@
+import type { Context, MiddlewareHandler } from 'hono';
+import type { RateLimiterAbstract } from 'rate-limiter-flexible';
+import { ACTIVE_WORKSPACE_HEADER, type Principal } from '@antasphere/chassis-contract';
+import type { PlatformRegistry } from '../platform/registry.js';
+import { WorkspaceMismatchError } from '../apikeys/service.js';
+import { apiError } from '../api/errors.js';
+import {
+  quotaHeaderEntries,
+  type ClientIpFn,
+  type QuotaDecision,
+  type RequestQuotaService
+} from './rate-limit.js';
+import { looksLikeJwt } from './scopes.js';
+
+declare module 'hono' {
+  interface ContextVariableMap {
+    principal: Principal | null;
+    /** The tool's `guest_forbidden` sentence, set by `authContext` for `requireNonGuest()` to answer with. */
+    guestForbiddenMessage: string;
+    /** Demo sign-in: the pass that opened this request's session, when one did (the audit mark). */
+    demoPassId?: string;
+  }
+}
+
+/** Paths under /api/v1 that are reachable without any credential. */
+const PUBLIC_API_PATHS = new Set([
+  '/api/v1/instance',
+  '/api/v1/setup',
+  '/api/v1/openapi.json',
+  // CLI email-OTP sign-in (api/cli-auth.ts): pre-auth by definition — the
+  // flow exists to OBTAIN a credential. Both are rate-limited in api/index.ts.
+  '/api/v1/cli/auth/request',
+  '/api/v1/cli/auth/complete',
+  // CLI cross-tool connect (api/sso-connect.ts, cloud edition): pre-auth by
+  // the same definition — the hub-minted exchange JWT in the body IS the
+  // credential, verified hard by the handler. Rate-limited in api/index.ts.
+  // The entry is inert on oss: the route is never registered there, so the
+  // path falls through to the JSON 404 terminator for every caller.
+  '/api/v1/sso/cli-connect'
+]);
+
+export function isPublicApiPath(path: string): boolean {
+  return PUBLIC_API_PATHS.has(path) || path.startsWith('/api/v1/auth/');
+}
+
+/**
+ * An edition's post-resolution verdict on an otherwise-valid principal.
+ * `ok` with a `role` means "the caller's authoritative role just changed —
+ * run THIS request under it"; `ok` with a `workspace` means "the person's
+ * DEFAULT workspace just moved (the pass this request ran read it off the
+ * hub) — run THIS request there", which the gate says only for a request
+ * that selected nothing (`request.selector` null) on a credential that pins
+ * nothing (PRDCT-2958, F2: the command that runs the pass used to land in
+ * the old default, the one after it in the new); a refusal carries the
+ * exact wire error. The seam exists for the cloud edition's hub gates (org
+ * suspension + hub membership re-assertion, internal/federation.md P4); oss
+ * never wires one. The gate also sees WHAT is being asked (`request`), so a
+ * policy can exempt specific surfaces (e.g. suspension keeping GET /me
+ * readable — the visible-but-blocked posture); implementations may ignore
+ * it.
+ */
+export type PrincipalGateResult =
+  | { ok: true; role?: Principal['role']; workspace?: GateWorkspace }
+  | { ok: false; status: 401 | 403; code: string; message: string };
+
+/** The membership a gate re-resolved for the request: the fields of the principal it replaces. */
+export interface GateWorkspace {
+  workspaceId: string;
+  role: Principal['role'];
+  origin: Principal['origin'];
+  accountRef: string | null;
+}
+
+export interface PrincipalGateRequest {
+  path: string;
+  method: string;
+  /** The request's own workspace selector (the X-Workspace-Id header), null when it named none. */
+  selector: string | null;
+}
+
+export type PrincipalGate = (
+  principal: Principal,
+  request: PrincipalGateRequest
+) => Promise<PrincipalGateResult>;
+
+/** The gate's verdict applied: the principal to run the request as, or the exact wire refusal. */
+export type AdmitResult =
+  { ok: true; principal: Principal } | { ok: false; status: 401 | 403; code: string; message: string };
+
+/**
+ * The session half of the credential resolver: the identity provider's live
+ * resolve of the request's cookie (membership re-checked, the selection rule
+ * applied). One home for the call, shared by `authContext` and the
+ * zero-state re-admission of `GET /me`.
+ */
+export function resolveSessionPrincipal(c: Context, registry: PlatformRegistry): Promise<Principal | null> {
+  return registry.identity.resolve({
+    headers: c.req.raw.headers,
+    path: c.req.path,
+    method: c.req.method,
+    requestId: c.get('requestId')
+  });
+}
+
+/**
+ * The edition gate on a resolved principal, with a freshly synced hub role
+ * applied to THIS request (D11): a demoted admin loses admin surfaces now, a
+ * promoted member gains them now. No gate (oss) admits the principal as it
+ * is. One home for the step, shared by `authContext` and the zero-state
+ * re-admission of `GET /me`.
+ */
+export async function admitPrincipal(
+  c: Context,
+  principal: Principal,
+  principalGate: PrincipalGate | undefined
+): Promise<AdmitResult> {
+  if (!principalGate) return { ok: true, principal };
+  const verdict = await principalGate(principal, {
+    path: c.req.path,
+    method: c.req.method,
+    selector: c.req.header(ACTIVE_WORKSPACE_HEADER)?.trim() || null
+  });
+  if (!verdict.ok) return verdict;
+  let admitted = principal;
+  if (verdict.workspace && verdict.workspace.workspaceId !== principal.workspaceId) {
+    const { accountRef, ...rest } = verdict.workspace;
+    const { accountRef: _previous, ...withoutRef } = admitted;
+    admitted = { ...withoutRef, ...rest, ...(accountRef ? { accountRef } : {}) };
+  }
+  if (verdict.role !== undefined && verdict.role !== admitted.role) {
+    admitted = { ...admitted, role: verdict.role };
+  }
+  return { ok: true, principal: admitted };
+}
+
+export interface AuthContextDeps {
+  registry: PlatformRegistry;
+  /**
+   * Resolves `Bearer <prefix>_...` API keys under the user-scoped selection
+   * rule — `requested` is the request's X-Workspace-Id (or null). May throw
+   * WorkspaceMismatchError for a valid PINNED key whose pin differs from the
+   * header. Absent = keys rejected.
+   */
+  resolveApiKey?: (token: string, requested: string | null) => Promise<Principal | null>;
+  /** Resolves OAuth Bearer JWTs (local JWKS verify + live membership selection). */
+  resolveOauthJwt?: (token: string, requested: string | null) => Promise<Principal | null>;
+  /** Distinguishes an API-key credential from other bearers. */
+  isApiKeyToken: (token: string) => boolean;
+  /** Failed key verifications consume from this bucket (per IP) — brute-force wall. */
+  keyFailureLimiter?: RateLimiterAbstract;
+  /** Client identity (socket address unless TRUST_PROXY opts into XFF). */
+  clientIp: ClientIpFn;
+  /** General per-principal request quota (I3). Absent = no general limit. */
+  requestQuota?: RequestQuotaService;
+  /**
+   * Post-resolution principal veto (cloud edition only). Runs here — in the
+   * single credential resolver — rather than inside any one identity path,
+   * so sessions, API keys, AND OAuth bearers all pass the same gate
+   * (internal/decisions/016). Absent (oss) = zero overhead, zero hub surface.
+   */
+  principalGate?: PrincipalGate | undefined;
+  /**
+   * Demo sign-in (present only while DEMO_SIGN_IN is on, self-hosted): judges
+   * a resolved SESSION against the demo pass that opened it, if one did.
+   * `ended` = the pass has expired or was revoked and the session is gone:
+   * the request goes on signed out. Here, in the single credential resolver,
+   * so no route can be reached with a session its pass no longer backs.
+   */
+  demoSession?:
+    ((headers: Headers) => Promise<{ passId: string; sessionId: string } | 'ended' | null>) | undefined;
+  /**
+   * The composed fail-closed scope allowlist (`createScopeAllowlist` in
+   * scopes.ts: the chassis rules, then the tool's). `null` = the endpoint is
+   * not open to machine principals. Required: a tool must state its list.
+   */
+  requiredScopeFor: (path: string, method: string) => string | null;
+  /**
+   * The tool's `guest_forbidden` sentence (`copy.guestForbidden`). Carried on
+   * the request so `requireNonGuest()` keeps its argument-less call sites, in
+   * the chassis and in the tool alike. Required: the chassis has no wording.
+   */
+  guestForbiddenMessage: string;
+}
+
+/**
+ * The single credential resolver: every /api/v1 request passes through here
+ * and comes out with c.get('principal') set (or a 401/403 for bad machine
+ * credentials). Three paths, one output shape:
+ *
+ *  - session cookie → IdentityProvider.resolve (live membership re-check)
+ *  - Bearer API key → O(1) key lookup (M2)
+ *  - Bearer JWT → OAuth access token this instance minted: local JWKS
+ *    verification + live membership re-check (M6)
+ *
+ * Machine principals additionally pass the fail-closed scope allowlist:
+ * endpoints not consciously listed in scopes.ts are unreachable with a key
+ * or token, whatever the underlying user's role is.
+ */
+export function authContext({
+  registry,
+  resolveApiKey,
+  resolveOauthJwt,
+  isApiKeyToken,
+  keyFailureLimiter,
+  clientIp,
+  requestQuota,
+  principalGate,
+  demoSession,
+  requiredScopeFor,
+  guestForbiddenMessage
+}: AuthContextDeps): MiddlewareHandler {
+  return async (c, next) => {
+    c.set('principal', null);
+    c.set('guestForbiddenMessage', guestForbiddenMessage);
+
+    if (isPublicApiPath(c.req.path)) {
+      return next();
+    }
+
+    const authHeader = c.req.header('authorization')?.trim() ?? '';
+    const bearer = /^Bearer\s+(.+)$/i.exec(authHeader)?.[1]?.trim() ?? null;
+
+    // The universal per-request workspace selector (user-scoped credential
+    // model): EVERY credential kind resolves it through the shared
+    // resolveMembership rule — sessions inside the identity provider,
+    // machine credentials via the threaded `requested` below. A PINNED API
+    // key is the one exception: it always resolves its pin, and a header
+    // naming a different workspace is rejected loudly (403 below) instead of
+    // being silently served the pinned one.
+    const requested = c.req.header(ACTIVE_WORKSPACE_HEADER)?.trim() || null;
+
+    let principal: Principal | null = null;
+
+    if (bearer && looksLikeJwt(bearer)) {
+      if (!resolveOauthJwt) {
+        return apiError(c, 401, 'oauth_not_enabled', 'OAuth bearer tokens are not enabled on this instance');
+      }
+      principal = await resolveOauthJwt(bearer, requested);
+      if (!principal) {
+        return apiError(c, 401, 'invalid_token', 'OAuth bearer token is invalid, expired, or revoked');
+      }
+    } else if (bearer && isApiKeyToken(bearer)) {
+      if (!resolveApiKey) {
+        return apiError(c, 401, 'invalid_api_key', 'API key not recognized');
+      }
+      const ip = clientIp(c);
+      if (keyFailureLimiter) {
+        const bucket = await keyFailureLimiter.get(ip).catch(() => null);
+        if (bucket && bucket.remainingPoints <= 0 && bucket.msBeforeNext > 0) {
+          return apiError(c, 429, 'rate_limited', 'Too many failed API key attempts');
+        }
+      }
+      try {
+        principal = await resolveApiKey(bearer, requested);
+      } catch (cause) {
+        // A VALID pinned key + a mismatching selector: a client bug or a
+        // confused-deputy attempt — loud 403, and no failure-limiter charge
+        // (the credential itself verified fine).
+        if (cause instanceof WorkspaceMismatchError) {
+          return apiError(c, 403, 'workspace_mismatch', 'This credential is pinned to a different workspace');
+        }
+        throw cause;
+      }
+      if (!principal) {
+        if (keyFailureLimiter) await keyFailureLimiter.consume(ip).catch(() => {});
+        return apiError(c, 401, 'invalid_api_key', 'API key not recognized');
+      }
+    } else if (bearer) {
+      return apiError(c, 401, 'unsupported_credential', 'Unrecognized bearer credential format');
+    } else {
+      principal = await resolveSessionPrincipal(c, registry);
+      // Fail-closed: a judge that throws refuses the session for this
+      // request rather than letting a dead pass's session through.
+      if (principal && demoSession) {
+        const verdict = await demoSession(c.req.raw.headers);
+        if (verdict === 'ended') principal = null;
+        else if (verdict) c.set('demoPassId', verdict.passId);
+      }
+    }
+
+    // General per-principal request quota (I3), consumed BEFORE the scope
+    // gate so even fail-closed 403 hammering is bounded — once a credential
+    // resolves, the quota is the outermost cost control. The bucket key is
+    // derived from the principal (see principalBucketKey), never a header.
+    // Sessions are included: the default quota is far above any dashboard's
+    // request rate, and a hijacked/scripted session is the same cost vector.
+    let quota: QuotaDecision | null = null;
+    if (principal && requestQuota) {
+      quota = await requestQuota.consume(principal);
+      if (quota && !quota.ok) {
+        for (const [name, value] of quotaHeaderEntries(quota)) c.header(name, value);
+        c.header('Retry-After', String(quota.retryAfterSeconds ?? Math.max(1, quota.resetSeconds)));
+        return apiError(c, 429, 'rate_limited', 'API request quota exceeded, slow down');
+      }
+    }
+
+    // Edition principal gate (cloud: hub org-status + membership
+    // re-assertion, internal/federation.md P4). AFTER the quota — hammering a
+    // suspended org stays rate-bounded — and BEFORE the scope gate, so a
+    // definitive hub refusal wins over any per-endpoint outcome. Cache-first
+    // inside; the hub is never a hard round-trip in the hot path.
+    if (principal && principalGate) {
+      const admitted = await admitPrincipal(c, principal, principalGate);
+      if (!admitted.ok) {
+        return apiError(c, admitted.status, admitted.code, admitted.message);
+      }
+      principal = admitted.principal;
+    }
+
+    // Fail-closed scope gate for machine principals only.
+    if (principal?.scopes) {
+      const needed = requiredScopeFor(c.req.path, c.req.method);
+      if (!needed) {
+        return apiError(c, 403, 'endpoint_not_allowed', 'This endpoint is not available to this credential');
+      }
+      if (!principal.scopes.has(needed)) {
+        return apiError(c, 403, 'insufficient_scope', `This credential was not granted "${needed}"`);
+      }
+    }
+
+    c.set('principal', principal);
+    if (!quota) return next();
+
+    // Success path: stamp the quota headers on whatever response the route
+    // produced (set on c.res so streamed/raw Response bodies get them too),
+    // letting well-behaved agents self-throttle before hitting 429s.
+    await next();
+    for (const [name, value] of quotaHeaderEntries(quota)) c.res.headers.set(name, value);
+    return;
+  };
+}
+
+/** Route guard: 401 when unauthenticated. */
+export function requireAuth(): MiddlewareHandler {
+  return async (c, next) => {
+    if (!c.get('principal')) {
+      return apiError(c, 401, 'unauthenticated', 'Authentication required');
+    }
+    return next();
+  };
+}
+
+/**
+ * Route guard (D2, internal/federation.md P6): an `origin='guest'` membership
+ * belongs to an EXTERNAL per-resource collaborator — it exists so the platform
+ * can resolve them to a principal at all, not to make them a workspace
+ * actor. Guests keep every ADR 013 per-resource surface their grant opens
+ * (read, version push, share tokens, annotations on THAT resource) but are
+ * refused resource creation and workspace-level surfaces on BOTH editions.
+ * Judges the resolved principal, so sessions, API keys, and OAuth bearers
+ * all pass the same gate. 403 — the surfaces this guards are flat,
+ * documented workspace surfaces, not probeable per-grant resources, so the
+ * ADR 013 hide-existence 404 posture does not apply here (same stance as
+ * requireRole).
+ */
+export function requireNonGuest(): MiddlewareHandler {
+  return async (c, next) => {
+    const principal = c.get('principal');
+    if (!principal) {
+      return apiError(c, 401, 'unauthenticated', 'Authentication required');
+    }
+    if (principal.origin === 'guest') {
+      // A principal only ever comes out of `authContext`, which set the sentence first.
+      return apiError(c, 403, 'guest_forbidden', c.get('guestForbiddenMessage'));
+    }
+    return next();
+  };
+}
+
+const ROLE_RANK = { member: 0, admin: 1, owner: 2 } as const;
+
+/** Route guard: 403 below the required role. */
+export function requireRole(min: keyof typeof ROLE_RANK): MiddlewareHandler {
+  return async (c, next) => {
+    const principal = c.get('principal');
+    if (!principal) {
+      return apiError(c, 401, 'unauthenticated', 'Authentication required');
+    }
+    if (ROLE_RANK[principal.role] < ROLE_RANK[min]) {
+      return apiError(c, 403, 'forbidden', `Requires ${min} role`);
+    }
+    return next();
+  };
+}

package/src/middleware/body-cap.ts

@@ -0,0 +1,33 @@
+import type { Context, MiddlewareHandler } from 'hono';
+import { bodyLimit } from 'hono/body-limit';
+import type { BodyCap } from '../tool-definition.js';
+
+/**
+ * A body-size cap that DEFERS its declared-size refusal to the entitlement
+ * gate (PRDCT-2632). Built once per `BodyCap` from hono's `bodyLimit` (a
+ * declared Content-Length over the cap is refused before a byte is read; an
+ * undeclared body is counted and cut at the cap), with one difference: when
+ * the request's matched route carries a gate that judges a plan limit
+ * (`isDeferring`), a declared oversize body is not refused HERE — the
+ * refusal is parked on the context (`bodyRefusal`) for the gate to fire
+ * after the plan check, and the request is rebuilt WITHOUT a body, so
+ * nothing downstream can read a byte of it whatever the middleware order.
+ * A metered account thus meets 403 `plan_required` with its upgrade link at
+ * any size, and the cap's 413 only when the plan allows the size.
+ */
+export function deferrableBodyCap(cap: BodyCap, isDeferring: (c: Context) => boolean): MiddlewareHandler {
+  const streamCap = bodyLimit({ maxSize: cap.maxBytes, onError: cap.onError });
+  return (c, next) => {
+    const declared = Number(c.req.header('content-length') ?? '');
+    if (Number.isFinite(declared) && declared > cap.maxBytes && isDeferring(c)) {
+      c.set('bodyRefusal', () => cap.onError(c));
+      // Rebuilt from the URL, the method and the headers: a `body: null`
+      // in a Request init keeps the input's body (the Fetch spec), so the
+      // drop must be a request that never had one.
+      const raw = c.req.raw;
+      c.req.raw = new Request(raw.url, { method: raw.method, headers: raw.headers, signal: raw.signal });
+      return next();
+    }
+    return streamCap(c, next);
+  };
+}

package/src/middleware/body-refusal.ts

@@ -0,0 +1,23 @@
+import type { Context } from 'hono';
+
+declare module 'hono' {
+  interface ContextVariableMap {
+    /**
+     * A body-size refusal the size cap DEFERRED (PRDCT-2632): the request
+     * declared a Content-Length over the tool's cap on a route whose gate
+     * judges a plan limit, so the gate must see the declared size first (a
+     * metered account meets 403 `plan_required` with the upgrade link at any
+     * size, never the instance-cap 413 in its place). The cap DROPS the
+     * request's body when it defers (`c.req.raw` is rebuilt without one), so
+     * nothing downstream can read a byte of it by construction; the gate
+     * fires the refusal right after the plan check, or before anything else
+     * when no plan applies. Undefined otherwise.
+     */
+    bodyRefusal: (() => Response) | undefined;
+  }
+}
+
+/** The pending deferred refusal of this request, if any. */
+export function pendingBodyRefusal(c: Context): (() => Response) | undefined {
+  return c.get('bodyRefusal');
+}

package/src/middleware/cross-site.ts

@@ -0,0 +1,122 @@
+import type { Context, MiddlewareHandler } from 'hono';
+import { apiError } from '../api/errors.js';
+import { isPublicOauthPath } from './oauth-public.js';
+
+/**
+ * Cross-site request forgery defence for the whole `/api/v1` surface.
+ *
+ * The session cookie authenticates every business route (`/orgs`, `/members`,
+ * `/invitations`, `/me/*`, `/apikeys`, every product route a instantiation
+ * adds), and a cookie is attached by the browser on a cross-site POST just as
+ * happily as on a same-origin one. Better Auth's own origin check covers only
+ * its `/sign-in` paths, so without this middleware a page on any origin could
+ * drive a signed-in user's whole API.
+ *
+ * Two independent signals, both browser-set and unforgeable by page script
+ * (both are Forbidden Header Names — `fetch` cannot override them):
+ *
+ *  1. `Sec-Fetch-Site: cross-site` — a request initiated by a document on a
+ *     different site. Refused outright.
+ *  2. `Origin` — present on every browser request with an unsafe method.
+ *     Refused unless it is the origin we are being served on, the configured
+ *     public origin, or an explicitly trusted extra.
+ *
+ * Deliberately NOT refused:
+ *
+ *  - Safe methods (GET/HEAD/OPTIONS). A cross-site read cannot be seen by the
+ *    attacker — `/api/v1` sends no `Access-Control-Allow-Origin` except on the
+ *    OAuth surfaces below — and refusing them would break legitimate
+ *    cross-origin embeds of authenticated content.
+ *  - Requests presenting an `Authorization` header. Those are API keys and
+ *    OAuth bearers: not ambient credentials, so not forgeable cross-site (a
+ *    page cannot attach the header without a preflight we never approve).
+ *    Refusing them would break every scripted and browser-based MCP client.
+ *  - The deliberate wildcard-CORS OAuth endpoints (oauth-public.ts): token,
+ *    register, introspect, revoke, jwks and discovery are cookie-less by
+ *    design and MUST answer any origin.
+ *  - Requests with neither header. Non-browser clients (curl, the CLI, the
+ *    SDK, server-to-server) send neither, and this middleware must not become
+ *    a browser-only gate on a self-hosted API. The ambient-credential threat
+ *    this closes is browser-only, and browsers always send at least one.
+ */
+export interface CrossSiteGuardOptions {
+  /** The instance's configured public origin (PUBLIC_BASE_URL). */
+  publicBaseUrl: string;
+  /**
+   * Additional origins allowed to drive the API with cookies — a separately
+   * hosted first-party dashboard, say. Empty on the template.
+   */
+  extraTrustedOrigins?: readonly string[];
+  /**
+   * Origins REFUSED even when they equal the origin this request was served
+   * on: the viewer origin (VIEWER_BASE_URL, PRDCT-1352). The host gate keeps
+   * `/api/v1` (minus the token-authed `/viewer/*` subset) off that hostname
+   * altogether, so in the shipped assembly no request here carries it as the
+   * serving origin — this is the second lock, so that a gate regression or a
+   * proxy routing the viewer hostname at the app never turns "the origin we
+   * are served on" into a trust grant for author-controlled script.
+   */
+  deniedOrigins?: readonly string[];
+  /** Escape hatch for surfaces that must stay open (paths are `/api/v1/...`). */
+  isExempt?: (path: string) => boolean;
+}
+
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+
+function originOf(value: string): string | null {
+  try {
+    return new URL(value).origin;
+  } catch {
+    return null;
+  }
+}
+
+/** The origin this very request was addressed to (works on localhost, previews, any domain). */
+function servingOrigin(c: Context): string | null {
+  return originOf(c.req.url);
+}
+
+export function crossSiteGuard({
+  publicBaseUrl,
+  extraTrustedOrigins = [],
+  deniedOrigins = [],
+  isExempt
+}: CrossSiteGuardOptions): MiddlewareHandler {
+  const configured = new Set<string>();
+  const publicOrigin = originOf(publicBaseUrl);
+  if (publicOrigin) configured.add(publicOrigin);
+  for (const extra of extraTrustedOrigins) {
+    const origin = originOf(extra);
+    if (origin) configured.add(origin);
+  }
+  const denied = new Set<string>();
+  for (const value of deniedOrigins) {
+    const origin = originOf(value);
+    if (origin) denied.add(origin);
+  }
+  // A denied origin wins over every trust source, the serving origin included.
+  for (const origin of denied) configured.delete(origin);
+
+  return async (c, next) => {
+    if (SAFE_METHODS.has(c.req.method)) return next();
+    if (c.req.header('authorization')) return next();
+    if (isPublicOauthPath(c.req.path)) return next();
+    if (isExempt?.(c.req.path)) return next();
+
+    const secFetchSite = c.req.header('sec-fetch-site');
+    if (secFetchSite === 'cross-site') {
+      return apiError(c, 403, 'cross_site_forbidden', 'Cross-site requests are not accepted on this API');
+    }
+
+    const origin = c.req.header('origin');
+    if (origin) {
+      const serving = servingOrigin(c);
+      const trusted = !denied.has(origin) && (origin === serving || configured.has(origin));
+      if (!trusted) {
+        return apiError(c, 403, 'cross_site_forbidden', 'Cross-site requests are not accepted on this API');
+      }
+    }
+
+    return next();
+  };
+}

package/src/middleware/hub-managed.ts

@@ -0,0 +1,61 @@
+import type { MiddlewareHandler } from 'hono';
+import { apiError } from '../api/errors.js';
+
+/**
+ * P7 (internal/federation.md "Hub-managed membership"): on the cloud edition,
+ * membership of a HUB-ORIGIN (projected) workspace is the hub's source of
+ * truth — invites, roles, and removals happen at the hub and flow in via
+ * SSO login + the P4 re-assertion. A local membership mutation on such a
+ * workspace would create divergence the next login/re-assertion fights, so
+ * every mutation on the local /members + /invitations surfaces answers this
+ * refusal instead. READS stay open: the projected roster is real.
+ *
+ * Why 403 (not 410): the member rows demonstrably exist (GET /members
+ * serves them), so "the resource is gone" would be false — what is denied
+ * is the OPERATION's local authority, for every caller, regardless of role
+ * or credential. That is RFC 9110 403's "forbidden for reasons unrelated to
+ * the credentials", and it keeps the platform's refusal vocabulary in one
+ * register (guest_forbidden, endpoint_not_allowed, workspace_mismatch are
+ * all 403). The `hub_managed` code + `details.manageUrl` carry the pointer.
+ *
+ * Fail-closed by construction:
+ *  - Hub-origin detection keys on `principal.accountRef`, which every
+ *    credential resolver (session: platform/local-identity.ts; API key:
+ *    apikeys/service.ts; OAuth bearer: identity/oauth-jwt.ts) populates from
+ *    a LIVE join on `workspaces.central_account_id` for the request's ONE
+ *    workspace (ADR 014) — the same signal the live hub gate keys on
+ *    (identity/hub-live-gate.ts). There is no principal-construction path
+ *    that skips the join.
+ *  - The gate is method-keyed, not route-enumerated, and mounted ONCE per
+ *    subtree wildcard (`/members/*`, `/invitations/*` — in Hono the
+ *    wildcard also matches the collection root): any FUTURE mutation
+ *    registered anywhere under those surfaces is refused by default, with
+ *    no per-path registration to remember.
+ *  - It is registered only on EDITION=cloud (the `hubConfig` presence
+ *    switch, like every cloud seam) — oss carries zero behavior change, and
+ *    on oss `centralAccountId` is never set anyway (double cover).
+ *
+ * Principal-less requests pass through untouched: the public invitation
+ * accept/lookup segments are explicitly SKIPPED where this is mounted (their
+ * target workspace is the invitation's, not the caller's — the accept
+ * handler runs its own hub-origin check on the invitation's workspace), and
+ * every other gated route 401s in its requireAuth/requireRole gate.
+ */
+export function hubManagedMembershipGate(
+  manageUrl: string,
+  message = 'Membership of this workspace is managed at the Antasphere hub — invite, remove, and change roles there'
+): MiddlewareHandler {
+  return async (c, next) => {
+    const method = c.req.method;
+    if (method === 'GET' || method === 'HEAD' || method === 'OPTIONS') return next();
+    const principal = c.get('principal');
+    if (principal?.accountRef) {
+      return apiError(c, 403, 'hub_managed', message, { manageUrl });
+    }
+    return next();
+  };
+}
+
+/** The teams' sentence for the same gate (PRDCT-2813): a projected team is shaped on the account site. */
+export const HUB_MANAGED_TEAMS_MESSAGE =
+  'Teams of this workspace are managed at the Antasphere hub — create, rename, and seat people there';