@antasphere/chassis-server 1.0.0

package/src/platform/events.ts

@@ -0,0 +1,71 @@
+import type { Logger } from '../logger.js';
+
+/**
+ * Internal event bus: domain modules publish, platform modules (and later
+ * rail/ee modules registered at boot) subscribe. Deliberately synchronous
+ * fan-out with error isolation — a failing subscriber never breaks the
+ * publisher's request path.
+ */
+export type PlatformEvents = {
+  /**
+   * Fired by the identity layer (Better Auth databaseHooks.user.create.after,
+   * wired in boot) for EVERY account entrance — setup, invitation accept,
+   * collaborator claim, future SSO JIT. Trustworthy by construction; call
+   * sites never emit it.
+   */
+  'user.created': { userId: string; email: string };
+  'member.joined': { workspaceId: string; userId: string; role: string };
+  'member.updated': { workspaceId: string; userId: string };
+  'member.removed': { workspaceId: string; userId: string };
+  'apikey.created': { workspaceId: string; apiKeyId: string };
+  'apikey.revoked': { workspaceId: string; apiKeyId: string };
+  'invitation.created': { workspaceId: string; invitationId: string };
+  'invitation.accepted': { workspaceId: string; invitationId: string; userId: string };
+  'file.uploaded': { workspaceId: string; fileId: string; sizeBytes: number };
+  /** workspaceId is null on the cloud edition — setup creates no workspace there. */
+  /** A person created ANOTHER workspace from inside the product (POST /workspaces). */
+  'workspace.created': { workspaceId: string; ownerUserId: string };
+  'setup.completed': { workspaceId: string | null; instanceId: string };
+};
+
+/**
+ * The events a bus carries: the chassis ones plus the tool's own (`TExtra`, a
+ * map of event name to payload, declared by the tool that instantiates the bus).
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export type EventMap<TExtra = {}> = PlatformEvents & TExtra;
+
+type Handler<M, E extends keyof M> = (payload: M[E]) => void | Promise<void>;
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export class EventBus<TExtra = {}> {
+  private handlers = new Map<keyof EventMap<TExtra>, Set<Handler<EventMap<TExtra>, never>>>();
+
+  constructor(private readonly logger: Logger) {}
+
+  on<E extends keyof EventMap<TExtra>>(event: E, handler: Handler<EventMap<TExtra>, E>): () => void {
+    const set = this.handlers.get(event) ?? new Set();
+    set.add(handler as Handler<EventMap<TExtra>, never>);
+    this.handlers.set(event, set);
+    return () => set.delete(handler as Handler<EventMap<TExtra>, never>);
+  }
+
+  /**
+   * The SAME bus as the chassis sees it: the generic events only. The
+   * composition code is generic over the tool's event map, and a bus is
+   * invariant in it (it both takes and hands out payloads), so the chassis
+   * modules, written against the generic map, read the bus through this view.
+   * Sound as long as a tool never re-declares a chassis event name.
+   */
+  chassisView(): EventBus {
+    return this as unknown as EventBus;
+  }
+
+  emit<E extends keyof EventMap<TExtra>>(event: E, payload: EventMap<TExtra>[E]): void {
+    for (const handler of this.handlers.get(event) ?? []) {
+      Promise.resolve((handler as Handler<EventMap<TExtra>, E>)(payload)).catch((err) => {
+        this.logger.error({ err, event }, 'event handler failed');
+      });
+    }
+  }
+}

package/src/platform/index.ts

@@ -0,0 +1,7 @@
+export { AllowAllEntitlements } from './entitlements.js';
+export { EventBus } from './events.js';
+export { type PlatformRegistry, createRegistry } from './registry.js';
+export { NoopUsageSink } from './usage.js';
+export { WorkspaceService } from './workspaces.js';
+export { bindEditionSeams } from './edition.js';
+export { LocalIdentityProvider } from './local-identity.js';

package/src/platform/local-identity.ts

@@ -0,0 +1,90 @@
+import { type Db } from '@antasphere/chassis-db';
+import {
+  ACTIVE_WORKSPACE_HEADER,
+  type IdentityProvider,
+  type InstanceAuthDescriptor,
+  type Principal,
+  type RequestContext
+} from '@antasphere/chassis-contract';
+import type { Auth } from '../identity/better-auth.js';
+import {
+  isWorkspaceSelector,
+  resolveMembership,
+  type OnWorkspaceMiss
+} from '../identity/resolve-membership.js';
+
+/**
+ * The template's default IdentityProvider: Better Auth sessions + a LIVE
+ * workspace_members re-check on every request. The membership row — not the
+ * cookie — is the authorization decision, so deactivating a member locks
+ * them out instantly regardless of cookie age.
+ *
+ * Workspace scoping (ADR 014, user-scoped credential model): a session
+ * resolves to exactly ONE workspace per request via the shared
+ * resolveMembership rule — the X-Workspace-Id header names it (ACTIVE
+ * membership required, else null: fail closed, an unknown workspace and a
+ * workspace the user does not belong to are indistinguishable); without the
+ * header the user's default membership wins, else the deterministic oldest
+ * active membership.
+ *
+ * API-key and OAuth-bearer resolution live in the auth-context middleware
+ * (they are credential formats, not identity sources) and share the SAME
+ * selection rule; this provider is the seam the central account service
+ * replaces later.
+ */
+export class LocalIdentityProvider implements IdentityProvider {
+  constructor(
+    private readonly auth: Auth,
+    private readonly db: Db,
+    private readonly hasGoogle: boolean,
+    private readonly hasOtp: boolean = false,
+    private readonly hasPasswordReset: boolean = false,
+    private readonly hasEmailChange: boolean = false,
+    /** Cloud only: one cached reconcile on a well-formed selector miss. */
+    private readonly onWorkspaceMiss?: OnWorkspaceMiss | undefined
+  ) {}
+
+  async resolve(ctx: RequestContext): Promise<Principal | null> {
+    const session = await this.auth.api.getSession({
+      headers: ctx.headers as Headers
+    });
+    if (!session?.user) return null;
+
+    const requested = ctx.headers.get(ACTIVE_WORKSPACE_HEADER)?.trim() || null;
+    let row = await resolveMembership(this.db, session.user.id, requested);
+    if (!row && requested && this.onWorkspaceMiss && isWorkspaceSelector(requested)) {
+      // Unknown-workspace deep-link retry (cloud): the named workspace may
+      // be a hub org granted since the last pass. One cached reconcile, one
+      // re-run of the SAME lookup — no recursion.
+      await this.onWorkspaceMiss(session.user.id, requested);
+      row = await resolveMembership(this.db, session.user.id, requested);
+    }
+    if (!row) return null;
+
+    return {
+      userId: session.user.id,
+      email: session.user.email,
+      name: session.user.name,
+      workspaceId: row.workspaceId,
+      role: row.role,
+      origin: row.origin,
+      via: 'session',
+      scopes: null,
+      ...(row.accountRef ? { accountRef: row.accountRef } : {})
+    };
+  }
+
+  describe(): InstanceAuthDescriptor {
+    // 'oauth' is always on: every instance is an OAuth 2.1 AS for its /mcp (M6).
+    const methods: InstanceAuthDescriptor['methods'] = ['password', 'api-key', 'oauth'];
+    if (this.hasOtp) methods.push('email-otp');
+    if (this.hasGoogle) methods.push('google');
+    return {
+      methods,
+      passwordReset: this.hasPasswordReset,
+      emailChange: this.hasEmailChange,
+      // Opt-in TOTP needs no email driver — always available on the template.
+      twoFactor: true
+    };
+  }
+}

package/src/platform/registry.ts

@@ -0,0 +1,28 @@
+import type { EntitlementService, IdentityProvider, UsageSink } from '@antasphere/chassis-contract';
+import type { EventBus } from './events.js';
+import type { WorkspaceService } from './workspaces.js';
+
+/**
+ * Boot-time module registry: the single place where seam implementations are
+ * bound. The template binds local defaults; a rail-connected or ee edition
+ * re-binds its own implementations here at boot (Cal.com/n8n pattern) and
+ * nothing else in the codebase changes.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface PlatformRegistry<TExtra = {}> {
+  identity: IdentityProvider;
+  entitlements: EntitlementService;
+  usage: UsageSink;
+  events: EventBus<TExtra>;
+  /**
+   * Workspace lifecycle (ADR 014). Setup creates the FIRST workspace through
+   * it; product flows that open workspace creation (the cloud edition's lazy
+   * org projection) call it here instead of inserting rows themselves.
+   */
+  workspaces: WorkspaceService;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export function createRegistry<TExtra = {}>(defaults: PlatformRegistry<TExtra>): PlatformRegistry<TExtra> {
+  return { ...defaults };
+}

package/src/platform/usage.ts

@@ -0,0 +1,13 @@
+import type { UsageEvent, UsageSink } from '@antasphere/chassis-contract';
+
+/**
+ * Default UsageSink: drop everything. Domain code always emits usage events
+ * (they double as local analytics hooks); only a rail-connected sink turns
+ * them into billing. Zero phone-home is the default posture — nothing leaves
+ * the instance unless an operator explicitly configures a sink.
+ */
+export class NoopUsageSink implements UsageSink {
+  async emit(_event: UsageEvent): Promise<void> {
+    // intentionally empty
+  }
+}

package/src/platform/workspaces.ts

@@ -0,0 +1,41 @@
+import { workspaceMembers, workspaces, type DbConn } from '@antasphere/chassis-db';
+
+/**
+ * Workspace lifecycle — the template's one creation path (ADR 014). Setup
+ * creates the FIRST workspace through it; products that open their own
+ * workspace-creation flow (a hub's sign-up, a cloud edition's lazy org
+ * projection) call it via the platform registry instead of hand-rolling
+ * the two inserts. The template exposed no HTTP endpoint for this (workspace
+ * creation is a product decision); the chassis took that decision with
+ * `POST /workspaces` (api/workspaces.ts, PRDCT-2444): sessions only, capped
+ * per person, and still through THIS service — never a second insert path.
+ */
+export class WorkspaceService {
+  constructor(private readonly db: DbConn) {}
+
+  /**
+   * Create a workspace with `ownerUserId` as its ACTIVE OWNER — one unit:
+   * pass a transaction handle (`conn`) to join an enclosing transaction
+   * (setup does), or omit it to run the two inserts on this service's
+   * connection inside their own transaction when it supports one.
+   */
+  async create(name: string, ownerUserId: string, conn: DbConn = this.db): Promise<{ workspaceId: string }> {
+    const run = async (tx: DbConn) => {
+      const [workspace] = await tx.insert(workspaces).values({ name }).returning({ id: workspaces.id });
+      if (!workspace) throw new Error('workspace insert returned no row');
+      await tx.insert(workspaceMembers).values({
+        workspaceId: workspace.id,
+        userId: ownerUserId,
+        role: 'owner'
+      });
+      return { workspaceId: workspace.id };
+    };
+    // A DbConn may already BE a transaction (no .transaction on the type);
+    // when the caller hands us a plain Db, wrap the pair so a workspace can
+    // never exist without its owner membership.
+    if ('transaction' in conn && typeof conn.transaction === 'function') {
+      return conn.transaction(async (tx) => run(tx));
+    }
+    return run(conn);
+  }
+}

package/src/projects/access.ts

@@ -0,0 +1,160 @@
+import { sql, type SQL, type SQLWrapper } from 'drizzle-orm';
+import type { Principal, ProjectRole } from '@antasphere/chassis-contract';
+import { projects, type DbConn } from '@antasphere/chassis-db';
+
+/**
+ * THE project access rule, stated once. A tool links its own resources to
+ * projects through a table of its own, and asks ONE question of the chassis:
+ * "does this principal hold a grant of at least `<role>` on the project in
+ * this column?". The chassis routes (`api/projects.ts`) ask the same question
+ * through the same builder, so a tool cannot drift from them.
+ *
+ * What the predicate carries, and every clause is load-bearing:
+ *
+ *  - **The guest refusal.** An `origin='guest'` membership exists for
+ *    principal resolution only (D2): it is never a project member. Refused on
+ *    the PRINCIPAL (`false`, no query at all) AND on the membership row the
+ *    grant rides on (`origin <> 'guest'`), so a stray row is inert.
+ *  - **The live membership.** The grant is read THROUGH its
+ *    `workspace_members` row: same user, same workspace as the request,
+ *    `is_active`. A deleted membership took the grant with it (the foreign
+ *    key's cascade); a deactivated one resolves no principal at all.
+ *  - **One workspace.** The project belongs to the request's workspace and to
+ *    the membership's. A request never spans workspaces (ADR 014).
+ *  - **The role ladder.** `manager` contains `editor` contains `viewer`.
+ *  - **A team's grant (PRDCT-2794).** A person seated in a team that holds a
+ *    place on the project holds the team's role, on the same live membership
+ *    row; their effective role is the highest of their own grant and their
+ *    teams'. A seat or a grant removed is felt on the next request.
+ *  - **The operator view.** A workspace owner or admin acts as a manager on
+ *    every project of the workspace (ADR 006), which is why a project with no
+ *    manager stays manageable and there is no last-manager guard.
+ *  - **The archived-write rule.** `access: 'write'` is off while the project
+ *    is archived, for everyone, the operator included. A READ stays.
+ *
+ * Callers answer 404, never 403, when a READ predicate is false: a project a
+ * principal cannot read must not reveal its existence.
+ */
+
+const LADDER: Record<ProjectRole, readonly ProjectRole[]> = {
+  viewer: ['viewer', 'editor', 'manager'],
+  editor: ['editor', 'manager'],
+  manager: ['manager']
+};
+
+export interface ProjectGrantOptions {
+  /** The least role that satisfies the predicate. */
+  atLeast: ProjectRole;
+  /** `write` adds the archived-write rule; `read` does not look at the archive. */
+  access: 'read' | 'write';
+}
+
+/**
+ * A boolean SQL expression over `projectId`, a column (or expression) of the
+ * CALLER's query that holds a project id: the tool's link table column, or
+ * `projects.id` itself. The aliases are prefixed so they cannot collide with
+ * the ones of the query the predicate is embedded in.
+ *
+ * **Pass a QUALIFIED reference when the predicate lands in a SELECT LIST.**
+ * drizzle renders a column object of a single-table select WITHOUT its table
+ * name there (`"id"`), and inside this subquery a bare `"id"` binds to the
+ * subquery's own tables: ambiguous at best, always-true at worst. A raw
+ * `sql\`"link_table"."project_id"\`` (or `PROJECTS_ID` below) is immune; a
+ * column object is safe in a WHERE, where drizzle always qualifies it.
+ */
+export function projectGrantPredicate(
+  principal: Pick<Principal, 'userId' | 'workspaceId' | 'role' | 'origin'>,
+  projectId: SQLWrapper,
+  opts: ProjectGrantOptions
+): SQL {
+  if (principal.origin === 'guest') return sql`false`;
+  const live = opts.access === 'write' ? sql`AND prj_pr.archived_at IS NULL` : sql``;
+  if (principal.role === 'owner' || principal.role === 'admin') {
+    return sql`EXISTS (
+      SELECT 1 FROM projects prj_pr
+      WHERE prj_pr.id = ${projectId}
+        AND prj_pr.workspace_id = ${principal.workspaceId}
+        ${live}
+    )`;
+  }
+  const roles = sql.join(
+    LADDER[opts.atLeast].map((role) => sql`${role}`),
+    sql`, `
+  );
+  // Two ways to hold a grant, judged on the SAME live membership row: the
+  // person's own entry (`project_members`), or the entry of a team the person
+  // is seated in (`project_teams` through `workspace_team_members`, PRDCT-2794).
+  // The team's workspace is checked against the membership's like the
+  // project's, so a seat can never reach across workspaces; the effective
+  // role is the highest of the two, which the ladder's IN list yields.
+  return sql`EXISTS (
+    SELECT 1
+    FROM workspace_members prj_wm
+    JOIN projects prj_pr ON prj_pr.workspace_id = prj_wm.workspace_id
+    WHERE prj_pr.id = ${projectId}
+      AND prj_wm.user_id = ${principal.userId}
+      AND prj_wm.workspace_id = ${principal.workspaceId}
+      AND prj_wm.is_active
+      AND prj_wm.origin <> 'guest'
+      ${live}
+      AND (
+        EXISTS (
+          SELECT 1 FROM project_members prj_pm
+          WHERE prj_pm.project_id = prj_pr.id
+            AND prj_pm.member_id = prj_wm.id
+            AND prj_pm.role IN (${roles})
+        )
+        OR EXISTS (
+          SELECT 1
+          FROM project_teams prj_pt
+          JOIN workspace_team_members prj_tm ON prj_tm.team_id = prj_pt.team_id
+          JOIN workspace_teams prj_t ON prj_t.id = prj_pt.team_id
+          WHERE prj_pt.project_id = prj_pr.id
+            AND prj_tm.member_id = prj_wm.id
+            AND prj_t.workspace_id = prj_wm.workspace_id
+            AND prj_pt.role IN (${roles})
+        )
+      )
+  )`;
+}
+
+/** `projects.id`, always qualified: safe in a select list as in a WHERE (see above). */
+export const PROJECTS_ID: SQL = sql.raw('"projects"."id"');
+
+/**
+ * The caller's effective role on a project AS A SQL EXPRESSION over a project
+ * id column: `manager`, `editor`, `viewer`, or NULL (no read). Built from the
+ * predicate above, never beside it. Archive-blind on purpose: a role is a
+ * READ fact, and whether an act is allowed on an archived project is the
+ * act's own question (`access: 'write'`, or the route's 409).
+ */
+export function projectRoleExpression(
+  principal: Pick<Principal, 'userId' | 'workspaceId' | 'role' | 'origin'>,
+  projectId: SQLWrapper
+): SQL<ProjectRole | null> {
+  const has = (atLeast: ProjectRole) =>
+    projectGrantPredicate(principal, projectId, { atLeast, access: 'read' });
+  return sql<ProjectRole | null>`CASE
+    WHEN ${has('manager')} THEN 'manager'
+    WHEN ${has('editor')} THEN 'editor'
+    WHEN ${has('viewer')} THEN 'viewer'
+  END`;
+}
+
+/**
+ * The effective role of `principal` on one project of the request's
+ * workspace, or null. **null = 404**: no such project here, or a project the
+ * principal cannot read; the two must stay indistinguishable to the caller.
+ */
+export async function projectRole(
+  conn: DbConn,
+  principal: Pick<Principal, 'userId' | 'workspaceId' | 'role' | 'origin'>,
+  projectId: string
+): Promise<ProjectRole | null> {
+  const rows = await conn
+    .select({ role: projectRoleExpression(principal, PROJECTS_ID) })
+    .from(projects)
+    .where(sql`${projects.id} = ${projectId} AND ${projects.workspaceId} = ${principal.workspaceId}`)
+    .limit(1);
+  return rows[0]?.role ?? null;
+}

package/src/projects/index.ts

@@ -0,0 +1,7 @@
+export {
+  PROJECTS_ID,
+  projectGrantPredicate,
+  projectRole,
+  projectRoleExpression,
+  type ProjectGrantOptions
+} from './access.js';

package/src/route-label.ts

@@ -0,0 +1,29 @@
+import type { Context } from 'hono';
+
+/**
+ * The low-cardinality, secret-free label for a request, used by BOTH the
+ * completion log line and the trace span.
+ *
+ * The raw `c.req.path` must never reach the log stream or a span attribute.
+ * Path segments are request data like any other: the moment a route puts a
+ * capability in the URL — a share secret, a one-time token, an invitation
+ * code — every log sink, every trace backend, and every operator with
+ * `docker logs` holds a working credential, and the redaction list cannot
+ * help (it keys off object properties, and `path` is one opaque string).
+ * Logging the MATCHED ROUTE PATTERN instead (`/v/:secret`, not
+ * `/v/9f3c…`) keeps the line just as useful for debugging and cardinality
+ * bounded, and it is secret-free by construction for every route that will
+ * ever be added.
+ *
+ * `routePath` is only populated once routing has run, so callers must read
+ * this AFTER `await next()`. Unmatched requests have no pattern to report:
+ * they get the literal `(unmatched)` rather than the attacker-controlled URL
+ * they probed with.
+ */
+export function routeLabel(c: Context): string {
+  const matched = c.req.routePath;
+  // Hono answers '/*' for a catch-all match and for no match at all; neither
+  // says anything the pattern doesn't, and both are safe to report as-is.
+  if (!matched) return '(unmatched)';
+  return matched;
+}

package/src/routes/health.ts

@@ -0,0 +1,79 @@
+import { Hono } from 'hono';
+import type { RuntimeState } from '../state.js';
+
+/**
+ * /healthz — liveness. No dependencies: answers 200 whenever the event loop
+ * runs, so orchestrators never restart a replica that is merely waiting on
+ * the database.
+ *
+ * /readyz — readiness. 503 until env is parsed, migrations are applied (or
+ * confirmed current), and the DB is reachable; 503 again while draining; and
+ * 503 whenever the backing store stops being writable.
+ *
+ * That last clause is the whole point of `probeStorage`. Readiness used to be
+ * a boot-time boolean, so the storage probe ran exactly once, at startup: an
+ * instance whose /data volume was emptied, unmounted or turned read-only
+ * after boot — the state a failed restore leaves behind — kept answering 200
+ * and kept taking traffic it could not serve. Readiness has to be a live
+ * claim about the dependencies, not a memory of them.
+ */
+export interface HealthDeps {
+  /** Re-probe the backing store. Must throw when it is not writable. */
+  probeStorage?: () => Promise<void>;
+  /** How long a SUCCESSFUL probe is trusted before it re-runs. */
+  storageProbeTtlMs?: number;
+  /** Called with the probe failure so it lands in the logs. */
+  onStorageFailure?: (err: unknown) => void;
+  /** Injectable clock (tests). */
+  now?: () => number;
+}
+
+/**
+ * Successes are cached briefly so a fast readiness poll does not become a
+ * PUT+DELETE per second against S3. Failures are NEVER cached: the next
+ * request re-probes, so recovery is observed immediately.
+ */
+const DEFAULT_STORAGE_PROBE_TTL_MS = 10_000;
+
+export function healthRoutes(state: RuntimeState, deps: HealthDeps = {}): Hono {
+  const app = new Hono();
+  const { probeStorage, onStorageFailure } = deps;
+  const ttlMs = deps.storageProbeTtlMs ?? DEFAULT_STORAGE_PROBE_TTL_MS;
+  const now = deps.now ?? (() => Date.now());
+
+  let trustedUntil = 0;
+  let inflight: Promise<unknown> | null = null;
+
+  /** Resolves to the failure, or null when storage is reachable. */
+  function checkStorage(): Promise<unknown> {
+    if (!probeStorage) return Promise.resolve(null);
+    if (now() < trustedUntil) return Promise.resolve(null);
+    // One probe at a time: a burst of readiness polls must not fan out into a
+    // burst of writes against the store.
+    const pending = (inflight ??= (async () => {
+      try {
+        await probeStorage();
+        trustedUntil = now() + ttlMs;
+        return null;
+      } catch (err) {
+        trustedUntil = 0;
+        onStorageFailure?.(err);
+        return err ?? new Error('storage probe failed');
+      } finally {
+        inflight = null;
+      }
+    })());
+    return pending;
+  }
+
+  app.get('/healthz', (c) => c.json({ status: 'ok' }));
+  app.get('/readyz', async (c) => {
+    if (state.draining) return c.json({ status: 'unavailable', reason: 'draining' }, 503);
+    if (!state.ready) return c.json({ status: 'unavailable', reason: state.reason }, 503);
+    // The reason stays coarse on purpose: /readyz is unauthenticated and a
+    // driver's error text carries bucket names and filesystem paths.
+    if (await checkStorage()) return c.json({ status: 'unavailable', reason: 'storage' }, 503);
+    return c.json({ status: 'ready' });
+  });
+  return app;
+}

package/src/routes/index.ts

@@ -0,0 +1,2 @@
+export { healthRoutes } from './health.js';
+export { wellKnownRoutes } from './wellknown.js';

package/src/routes/wellknown.ts

@@ -0,0 +1,67 @@
+import { Hono, type Context } from 'hono';
+import {
+  oauthProviderAuthServerMetadata,
+  oauthProviderOpenIdConfigMetadata
+} from '@better-auth/oauth-provider';
+import { mcpResourceUrl, type Auth } from '../identity/better-auth.js';
+
+/**
+ * Root-level OAuth discovery surface.
+ *
+ * The oauthProvider plugin serves RFC 8414 / OIDC discovery under the
+ * /api/v1/auth base path, but clients resolve discovery from the ISSUER (the
+ * bare origin — jwt.issuer in identity/better-auth.ts), so the same documents
+ * must exist at the origin root. RFC 9728 protected-resource metadata is ours:
+ * it points the 401-challenged MCP client at this same origin as its
+ * authorization server. All documents are public by design and fetched
+ * cross-origin by browser-based MCP hosts — wide-open CORS is correct.
+ */
+const CORS_HEADERS = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Methods': 'GET, OPTIONS',
+  'Access-Control-Allow-Headers': 'Content-Type, Authorization, mcp-protocol-version',
+  'Access-Control-Max-Age': '86400'
+} as const;
+
+export interface WellKnownDeps {
+  auth: Auth;
+  publicBaseUrl: string;
+  instanceName?: string;
+  /** The tool's OAuth scope list, as registered with the provider: what `scopes_supported` advertises. */
+  oauthScopes: readonly string[];
+}
+
+export function wellKnownRoutes({ auth, publicBaseUrl, oauthScopes }: WellKnownDeps): Hono {
+  const app = new Hono();
+
+  const asMetadata = oauthProviderAuthServerMetadata(auth, {
+    headers: { ...CORS_HEADERS, 'Cache-Control': 'public, max-age=3600' }
+  });
+  const oidcMetadata = oauthProviderOpenIdConfigMetadata(auth, {
+    headers: { ...CORS_HEADERS, 'Cache-Control': 'public, max-age=3600' }
+  });
+
+  app.get('/.well-known/oauth-authorization-server', (c) => asMetadata(c.req.raw));
+  app.get('/.well-known/openid-configuration', (c) => oidcMetadata(c.req.raw));
+
+  // RFC 9728: served at the origin level AND at the path-aware derivation
+  // (clients insert /.well-known/oauth-protected-resource between origin and
+  // the resource path /mcp) — both return the same document.
+  const protectedResource = (c: Context) =>
+    c.json(
+      {
+        resource: mcpResourceUrl(publicBaseUrl),
+        authorization_servers: [publicBaseUrl],
+        scopes_supported: [...oauthScopes],
+        bearer_methods_supported: ['header']
+      },
+      200,
+      { ...CORS_HEADERS, 'Cache-Control': 'public, max-age=3600' }
+    );
+  app.get('/.well-known/oauth-protected-resource', (c) => protectedResource(c));
+  app.get('/.well-known/oauth-protected-resource/mcp', (c) => protectedResource(c));
+
+  app.options('/.well-known/*', (c) => c.body(null, 204, { ...CORS_HEADERS }));
+
+  return app;
+}