@braidhq/server 0.0.1 → 0.2.0

package/README.md

@@ -0,0 +1,164 @@
+# @braidhq/server
+
+Braid keeps a product's intent and its code aligned in one knowledge graph. `@braidhq/server` is the process that runs it. It wires core's ports to real filesystem, git, and vendor adapters, exposes the graph over HTTP, and drives the agents that fill it.
+
+## Role
+
+Server is the composition root and the presentation layer. It turns the framework into a running application.
+
+- **The Wiring**: The composition root that binds core's ports to concrete adapters, the one place infrastructure is instantiated.
+- **The Adapters**: Filesystem and git implementations of core's repositories and history, plus the subprocess runner that executes skills.
+- **The API**: A REST and SSE surface built on Hono, one router per resource, with authentication, workspace scoping, and an OpenAPI 3 spec at `GET /openapi.json`.
+
+## Positioning: framework kernel and worldview preset
+
+Braid is worldview-agnostic. The intent-graph engine, workspaces, proposals, HITL review, the reactor, and the authorization policy, knows nothing about software. A worldview supplies the rest: an ontology plus the storage, source loaders, and agent that serve it. The software worldview, a DDD ontology whose sources split into `intent` and `code`, is the default, not a built-in.
+
+Two layers share this package for now.
+
+- **Kernel**: `composeApp`, routes, middleware, policy, auth mode, and the generic filesystem infrastructure. Worldview-agnostic. `composeApp` registers no plugin, a caller hands it a `PluginRegistry`. Nothing here imports a concrete ontology, storage, loader, or agent.
+- **Coding preset**: `composeFsApp` assembles the default bundle, Kuzu storage, the DDD ontology, the git, github, and drive loaders, and the claude-code agent, over filesystem persistence. Its default identities live as `DEFAULT_*` constants at the head of the file.
+
+A future app, a story world or a research-notes base, reuses the kernel and swaps the preset for its own ontology and adapters. When that second worldview arrives, the coding preset extracts into its own package, `@braidhq/preset-code`, and this package drops its plugin dependencies. Until a second worldview exists that pressure is speculative, so both layers stay here at no cost. The seam is `composeApp`: whatever the kernel reaches without a concrete plugin already belongs to it.
+
+## Structure
+
+The package layers outward from core. Infrastructure implements core's ports, routes expose them, and composition binds the two.
+
+```
+src/
+├── server.ts          process entry, serves the app
+├── app.ts             builds the Hono app, mounts middleware and routes
+├── composeApp.ts      the worldview-agnostic kernel root
+├── composeFsApp.ts    the coding preset, filesystem and vendor adapters
+├── startup.ts         blocking per-workspace boot steps
+├── authMode.ts        AuthMode strategy, localTrust and authenticated
+├── routes/            one router per resource
+├── middleware/        auth, cors, error mapping, workspace scoping
+├── policy/            authorization rules
+└── infrastructure/   adapters behind core ports, one folder per domain concern
+    ├── hitl/         proposal and clarification stores
+    ├── workspace/    workspace repository, registry, discovery, PRODUCT.md writer
+    ├── skill/        skill registry, run store, subprocess runner and its event stream
+    ├── source/       source unit observations, digests, intent listing
+    ├── model/        graph serializer
+    ├── reactor/      reactor cycle store
+    ├── batch/        batch plan store
+    ├── history/      GitWorkspaceHistory, commit messages
+    ├── users/, auth/, secrets/, oauth/   host services, no core port
+    └── _shared/      cross-cutting fs plumbing, paths, json store, frontmatter
+```
+
+- **composeApp / composeFsApp**: The kernel root and the coding preset. `composeApp` takes a deps object, registers no plugin, and defaults every unset port to an in-memory adapter. `composeFsApp` builds the filesystem, git, and vendor adapters, registers the default plugin bundle, then hands the result to `composeApp`. Production runs the latter. See Positioning above.
+- **startup**: The two boot passes, `startupBeforeServe` and `startupAfterServe`. See Startup below for the full order.
+- **infrastructure**: The real adapters behind core's ports, grouped by domain concern to mirror `core/domain`, never by storage technology. Each folder owns one aggregate's adapter, so a future SQLite or Postgres store lands beside the filesystem one instead of in a separate `sql/` tree. `hitl/` persists proposals and clarifications, `workspace/` the graph and workspace files, `history/` records every change as a git commit, `skill/` runs a skill as a subprocess and streams its events back. `_shared/` holds the cross-cutting fs plumbing, its underscore marking it as the one folder that is not a domain concern, matching `routes/_shared.ts`. `users/ auth/ secrets/ oauth/` are host services with no core port.
+- **routes**: One `createXxxRouter(deps)` per resource, each taking only the services it needs. Bodies validate through zod, path ids parse through their branded schema.
+- **middleware**: The cross-cutting edge. Auth resolves the user, workspace middleware scopes and authorizes the request, and the error middleware maps `BraidError` subclasses to problem+json status codes.
+
+## Startup
+
+The blocking phase runs inside `composeFsApp` before the server accepts a request, in two groups.
+
+Provision host identity, who may use this server:
+
+1. `authMode.provision` seeds what the deployment's mode needs. Local trust seeds the `local-user` fallback account, authenticated mode syncs the login allowlist to the user roster. See Auth Mode below.
+
+Reconcile workspaces, register then boot each:
+
+2. `discoverCanonicalWorkspaces` registers workspaces present on disk but absent from the registry.
+3. `ensureWorkspaceOwners` gives any ownerless workspace the auth mode's default principal, or throws under authenticated mode where every workspace must have an explicit owner.
+4. `startupBeforeServe` runs the per-workspace pass. Per workspace it provisions the git repo and store, recovers a batch left running by a killed process, subscribes the reactor when the workspace opts in, and fires a catch-up sync for each loader-backed source.
+
+After `serve()`, the background phase runs cosmetic recovery that need not finish first, via `startupAfterServe`:
+
+5. `reapOrphanRuns` marks runs left without a completion, from a killed process, as aborted so the UI does not show them active forever.
+
+Both passes live in `startup.ts`, `startupBeforeServe` before `serve()` and `startupAfterServe` after. A new blocking per-workspace step is added to `startupBeforeServe`, a new background step to `startupAfterServe`. Provisioning tied to one adapter stays next to that adapter's construction. Source loaders take part without a bespoke step, the sync in step 4 fires for any registered loader.
+
+## Auth Mode
+
+One axis separates a trusted local install from an authenticated remote server, who the implicit user is. Rather than scatter that decision, an `AuthMode` strategy carries it, and the auth and ownership code reads the strategy, never a hardcoded `local-user`.
+
+```mermaid
+classDiagram
+    class AuthMode {
+        <<interface>>
+        +defaultPrincipal: UserId | null
+        +requiresAuth: boolean
+        +provision(context) Promise
+    }
+    class localTrust {
+        <<const>>
+        defaultPrincipal = local-user
+        requiresAuth = false
+        provision() seeds local-user
+    }
+    class authenticated {
+        <<const>>
+        defaultPrincipal = null
+        requiresAuth = true
+        provision() syncs allowlist
+    }
+    AuthMode <|.. localTrust
+    AuthMode <|.. authenticated
+```
+
+Two consumers read the strategy, neither a hardcoded account. `authMiddleware` resolves the caller, applying the Bearer gate under `requiresAuth` and falling back to `defaultPrincipal` when one is present. `ensureWorkspaceOwners` gives an ownerless workspace the principal, or throws when there is none.
+
+`composeFsApp` picks the mode from `BRAID_LOCAL_TRUST`, local trust by default. Adding a mode, a service account or an SSO-only deployment, is a new `AuthMode`, with no change to the middleware, the ownership code, or boot.
+
+## Authorization
+
+Every gated action is a capability. The server is the authoritative check, and Studio mirrors the same list to grey out affordances it cannot use. The authoritative logic is `packages/server/src/policy/checks.ts`, the matrix below is a readable mirror of it.
+
+### Where the decision happens
+
+A request's permission is decided in three steps, all under `policy/`.
+
+1. `resolveViewer(user, member)` builds a `ViewerContext` once per request, the caller's `effectiveRole` in this workspace. It is the sole place a server admin short-circuits to an `owner` role.
+2. `workspaceAccessMiddleware` runs `resolveViewer`, stamps the viewer on the request, and rejects an outright outsider. `requirePermission(cap)` and the server-scope `requireServerCapability(cap)` are the route gates that read it.
+3. `PermissionRegistry.can(capability, viewer)` finds the capability's check and evaluates it against the viewer. An unregistered capability denies by default.
+
+Each capability owns one pure check in `checks.ts`, a stateless const object. Plugins register their own checks on the same registry, so adding a capability never edits an existing one.
+
+### Capability matrix
+
+Workspace roles resolve from membership. `admin` is the server role, which short-circuits to an `owner` effectiveRole in any workspace, so an admin holds every workspace capability below.
+
+| Capability | owner | maintainer | member | Notes |
+|---|:--:|:--:|:--:|---|
+| `server.admin` | n/a | n/a | n/a | Server role `admin` only. Gates `/admin`, read from the server role, not `effectiveRole`, since a workspace owner also resolves to `owner`. |
+| `workspace.create` | n/a | n/a | n/a | Server scope, resolved with no member, so only a server admin passes. |
+| `workspace.read` | yes | yes | yes | Any member. |
+| `workspace.write` | yes | | | Owner only. |
+| `proposal.read` | yes | yes | | Owner or maintainer. |
+| `proposal.write` | yes | yes | | Owner or maintainer. |
+| `clarification.read` | yes | yes | | Owner or maintainer. |
+| `clarification.write` | yes | yes | | Owner or maintainer. |
+| `history.write` | yes | | | Owner only. |
+| `skill.run` | yes | maybe | maybe | Owner always. Otherwise the skill's `allowedRoles`, overridden per member by `skillOverrides`. |
+
+## Boundaries
+
+These are the rules for anyone editing server. They are enforced in review rather than by tooling.
+
+- **Composition Only Here**: Infrastructure concretes are instantiated at the composition root, never inside a route or a service.
+- **Routes Stay Thin**: A route validates input, calls one service, and shapes the response. Business rules live in core, not in the handler.
+- **Adapters Implement Ports**: Every fs, git, or agent class satisfies an interface declared in core, so swapping one never touches the framework.
+- **Errors Map at the Edge**: Domain code throws a `BraidError`, and the error middleware is the only place that turns it into an HTTP status.
+- **Scope Through Middleware**: Workspace access is checked once in middleware, not re-derived inside each route.
+
+## Dependencies
+
+Server sits at the outer edge, above core and the plugin packages the coding preset bundles as defaults.
+
+- **Depends On**: `@braidhq/core` and `@braidhq/schema`, `hono` for HTTP, `simple-git` for history, and, only through the coding preset, the default plugin bundle of `storage-kuzu`, `agent-claude-code`, `ontology-ddd`, and `source-loader-*`. The kernel itself needs none of the plugin packages; they leave with the preset when it extracts. See Positioning.
+- **Consumed By**: `cli` and the `desktop` Tauri shell, which run it as their backend.
+
+## MCP Gateway
+
+Skills run as coding-agent subprocesses and reach this server's REST API as MCP tools, not by curl. An off-the-shelf translator, `openapi-mcp-gateway`, reads `/openapi.json` and re-exposes each operation as a tool named `braid-core`.
+
+The gateway is spawned per skill run and torn down with it, so there is no long-lived gateway process, no open port, and no network auth to manage. The transport is an implementation detail of the runner.
+
+SSE streams, the OAuth HTML callback, and the workspace-admin routes are deliberately absent from the spec, they are not one-shot MCP tools. The `GET /openapi.json` test in `test/app.test.ts` pins that boundary.

package/dist/app.d.ts

@@ -1,7 +1,16 @@
-import type { AppDependencies } from './composition.js';
-import { Hono } from 'hono';
+import type { AppDependencies } from './composeApp.js';
+import { OpenAPIHono } from '@hono/zod-openapi';
 export interface AppOptions {
     readonly corsOrigins?: readonly string[];
+    /**
+     * Base URL the OpenAPI spec advertises in its `servers[]` block.
+     * Downstream consumers use it to dispatch REST calls,
+     * openapi-mcp-gateway, Swagger UI, and code generators among them.
+     * When unset, the spec omits `servers[]` and leaves the consumer to guess.
+     * `composeFsApp` threads its `apiUrl` here,
+     * so the gateway routes calls back without an explicit base-url flag.
+     */
+    readonly apiUrl?: string;
 }
-export declare function createApp(deps: AppDependencies, options?: AppOptions): Hono;
+export declare function createApp(deps: AppDependencies, options?: AppOptions): OpenAPIHono;
 //# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAkB3B,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACzC;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,GAAE,UAAe,GAAG,IAAI,CA6D/E"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AA8B/C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACxC;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,GAAE,UAAe,GAAG,WAAW,CAqMtF"}

package/dist/app.js

@@ -1,34 +1,115 @@
-import { Hono } from 'hono';
+import { OpenAPIHono } from '@hono/zod-openapi';
+import { authMiddleware } from './middleware/auth.js';
 import { corsMiddleware } from './middleware/cors.js';
 import { errorHandler } from './middleware/error.js';
+import { workspaceAccessMiddleware } from './middleware/workspaceAccess.js';
 import { workspaceIdMiddleware } from './middleware/workspaceId.js';
-import { createClarifyRouter } from './routes/clarify.js';
-import { createDecisionsRouter } from './routes/decisions.js';
+import { createAdminRouter } from './routes/admin.js';
+import { createAuthRouter } from './routes/auth.js';
+import { createBatchRouter } from './routes/batch.js';
+import { createClarificationRouter } from './routes/clarifications.js';
 import { createEdgesRouter } from './routes/edges.js';
 import { healthRouter } from './routes/health.js';
+import { createHistoryRouter } from './routes/history.js';
 import { createModelRouter } from './routes/model.js';
 import { createNodesRouter } from './routes/nodes.js';
 import { createOAuthRouter } from './routes/oauth.js';
 import { createOntologyRouter } from './routes/ontology.js';
 import { createProposalsRouter } from './routes/proposals.js';
+import { createReactorCyclesRouter } from './routes/reactorCycles.js';
 import { createRunsRouter } from './routes/runs.js';
+import { createSkillInputOptionsRouter } from './routes/skillInputOptions.js';
 import { createSkillsRouter } from './routes/skills.js';
+import { createSourceLoadersRouter } from './routes/sourceLoaders.js';
+import { createSourceUnitObservationsRouter } from './routes/sourceUnitObservations.js';
+import { createGithubWebhookReceiver, createSourceWebhooksAdminRouter } from './routes/sourceWebhooks.js';
+import { createUsersRouter } from './routes/users.js';
 import { createWorkspaceEventsRouter } from './routes/workspaceEvents.js';
+import { createTransferOwnershipRouter, createWorkspaceMembersRouter } from './routes/workspaceMembers.js';
 import { createWorkspacesRouter } from './routes/workspaces.js';
 export function createApp(deps, options = {}) {
-    const app = new Hono();
+    const app = new OpenAPIHono();
+    // Global middleware, every request passes these in order.
     app.use('*', options.corsOrigins
         ? corsMiddleware({ allowedOrigins: options.corsOrigins })
         : corsMiddleware());
+    // Identity and auth gate. Resolves the caller's `userId` from a Bearer session
+    // when auth is enforced, else the `X-Braid-User` header or the default principal.
+    // Non-public routes that lack a required Bearer token are rejected.
+    app.use('*', authMiddleware({
+        ...(deps.sessionStore ? { sessionStore: deps.sessionStore } : {}),
+        requireAuth: deps.authMode.requiresAuth,
+        defaultPrincipal: deps.authMode.defaultPrincipal,
+    }));
     app.onError(errorHandler);
+    // Host-level routes, not scoped to a single workspace.
     app.route('/health', healthRouter);
+    if (deps.sessionStore && deps.accessPolicy && deps.userRegistry) {
+        app.route('/auth', createAuthRouter({
+            clock: deps.clock,
+            sessionStore: deps.sessionStore,
+            accessPolicy: deps.accessPolicy,
+            userRegistry: deps.userRegistry,
+            ...(deps.googleOAuth ? { googleOAuth: deps.googleOAuth } : {}),
+            studioUrl: deps.studioUrl ?? 'http://localhost:5173',
+            requiresAuth: deps.authMode.requiresAuth,
+        }));
+    }
+    if (deps.userRegistry) {
+        app.route('/users', createUsersRouter({
+            userRegistry: deps.userRegistry,
+        }));
+    }
+    if (deps.userRegistry && deps.accessPolicy && deps.workspaceRegistry) {
+        app.route('/admin', createAdminRouter({
+            userRegistry: deps.userRegistry,
+            accessPolicy: deps.accessPolicy,
+            workspaceRegistry: deps.workspaceRegistry,
+            workspaceService: deps.workspaceService,
+        }));
+    }
     app.route('/workspaces', createWorkspacesRouter({
         workspaceService: deps.workspaceService,
         sourceLoaderRunner: deps.sourceLoaderRunner,
+        workspacesRoot: deps.workspacesRoot,
+        pluginRegistry: deps.pluginRegistry,
+        ...(deps.bootstrap ? { bootstrap: deps.bootstrap } : {}),
+        ...(deps.workspaceRegistry ? { workspaceRegistry: deps.workspaceRegistry } : {}),
+        ...(deps.userRegistry ? { userRegistry: deps.userRegistry } : {}),
+        ...(deps.historyService ? { historyService: deps.historyService } : {}),
     }));
     app.route('/workspaces', createWorkspaceEventsRouter({ eventBus: deps.eventBus }));
-    const workspaceScoped = new Hono();
+    // Server-level plugin discovery for Studio's loader dropdown,
+    // sourced from the active PluginRegistry, not hardcoded strings.
+    // Installed loaders are identical across workspaces, not scoped to one.
+    app.route('/source-loaders', createSourceLoadersRouter({ pluginRegistry: deps.pluginRegistry }));
+    // Public webhook receivers, authenticated by per-source HMAC secrets,
+    // inside the handler, not by a Bearer token.
+    // The auth middleware exempts the `/webhooks/` prefix.
+    // Mounted only when a SecretStore is wired,
+    // without one there is nowhere to read the secrets.
+    if (deps.secretStore) {
+        app.route('/webhooks', createGithubWebhookReceiver({
+            workspaceService: deps.workspaceService,
+            sourceLoaderRunner: deps.sourceLoaderRunner,
+            secretStore: deps.secretStore,
+            pluginRegistry: deps.pluginRegistry,
+        }));
+    }
+    // Workspace-scoped sub-app, mounted under `/workspaces/:workspaceId` below.
+    const workspaceScoped = new OpenAPIHono();
     workspaceScoped.use('*', workspaceIdMiddleware);
+    // Workspace membership gate, present only in composeFsApp,
+    // which wires both the workspace registry and the user registry.
+    // In-memory tests compose without these and stay open,
+    // so existing routes keep behaving.
+    if (deps.workspaceRegistry && deps.userRegistry) {
+        workspaceScoped.use('*', workspaceAccessMiddleware({
+            registry: deps.workspaceRegistry,
+            workspaceService: deps.workspaceService,
+            userRegistry: deps.userRegistry,
+        }));
+    }
     workspaceScoped.route('/model', createModelRouter({ modelService: deps.modelService }));
     workspaceScoped.route('/nodes', createNodesRouter({ modelService: deps.modelService }));
     workspaceScoped.route('/edges', createEdgesRouter({ modelService: deps.modelService }));
@@ -36,13 +117,25 @@ export function createApp(deps, options = {}) {
         hitlService: deps.hitlService,
         proposalRepository: deps.proposalRepository,
         modelRepository: deps.modelRepository,
-        validationService: deps.validationService,
+        modelValidationService: deps.modelValidationService,
+        workspaceService: deps.workspaceService,
     }));
-    workspaceScoped.route('/clarify', createClarifyRouter({
+    workspaceScoped.route('/clarifications', createClarificationRouter({
         hitlService: deps.hitlService,
-        clarifyRepository: deps.clarifyRepository,
+        clarificationRepository: deps.clarificationRepository,
+    }));
+    workspaceScoped.route('/source-unit-states', createSourceUnitObservationsRouter({
+        sourceUnitObservationService: deps.sourceUnitObservationService,
+        ...(deps.intentLister && deps.sourceUnitDigest
+            ? {
+                diffSupport: {
+                    workspaceService: deps.workspaceService,
+                    intentLister: deps.intentLister,
+                    digest: deps.sourceUnitDigest,
+                },
+            }
+            : {}),
     }));
-    workspaceScoped.route('/decisions', createDecisionsRouter({ decisionRepository: deps.decisionRepository }));
     workspaceScoped.route('/ontology', createOntologyRouter({
         workspaceRepository: deps.workspaceRepository,
         pluginRegistry: deps.pluginRegistry,
@@ -52,6 +145,9 @@ export function createApp(deps, options = {}) {
             skillRegistry: deps.skillRegistry,
             skillRunner: deps.skillRunner,
             workspaceRepository: deps.workspaceRepository,
+            sourceUnitObservationService: deps.sourceUnitObservationService,
+            runRepository: deps.runRepository,
+            pluginRegistry: deps.pluginRegistry,
         }));
         workspaceScoped.route('/runs', createRunsRouter({
             runRepository: deps.runRepository,
@@ -59,6 +155,41 @@ export function createApp(deps, options = {}) {
             workspaceRepository: deps.workspaceRepository,
         }));
     }
+    if (deps.historyService) {
+        workspaceScoped.route('/history', createHistoryRouter({ historyService: deps.historyService }));
+    }
+    if (deps.batchService) {
+        workspaceScoped.route('/batch', createBatchRouter({ batchService: deps.batchService }));
+    }
+    workspaceScoped.route('/reactor-cycles', createReactorCyclesRouter({
+        reactorCycleRepository: deps.reactorCycleRepository,
+    }));
+    if (deps.secretStore) {
+        workspaceScoped.route('/source-webhooks', createSourceWebhooksAdminRouter({
+            workspaceService: deps.workspaceService,
+            secretStore: deps.secretStore,
+            pluginRegistry: deps.pluginRegistry,
+            ...(options.apiUrl ? { apiUrl: options.apiUrl } : {}),
+        }));
+    }
+    workspaceScoped.route('/skill-input-options', createSkillInputOptionsRouter({
+        modelRepository: deps.modelRepository,
+        clarificationRepository: deps.clarificationRepository,
+        workspaceRepository: deps.workspaceRepository,
+        pluginRegistry: deps.pluginRegistry,
+    }));
+    if (deps.workspaceRegistry) {
+        workspaceScoped.route('/members', createWorkspaceMembersRouter({
+            workspaceService: deps.workspaceService,
+            registry: deps.workspaceRegistry,
+            clock: deps.clock,
+        }));
+        workspaceScoped.route('/transfer-ownership', createTransferOwnershipRouter({
+            workspaceService: deps.workspaceService,
+            registry: deps.workspaceRegistry,
+            clock: deps.clock,
+        }));
+    }
     app.route('/workspaces/:workspaceId', workspaceScoped);
     if (deps.secretStore) {
         app.route('/oauth', createOAuthRouter({
@@ -66,6 +197,20 @@ export function createApp(deps, options = {}) {
             ...(deps.googleOAuth ? { google: deps.googleOAuth } : {}),
         }));
     }
+    // OpenAPI 3 spec, consumed by openapi-mcp-gateway, to surface REST operations as MCP tools.
+    // SSE routes and the OAuth HTML callback are intentionally absent,
+    // they mount plain Hono sub-routers, so they never register with the doc.
+    // The `servers[]` block lets the gateway resolve the upstream base URL,
+    // without an explicit --base-url flag.
+    app.doc('/openapi.json', {
+        openapi: '3.0.0',
+        info: {
+            title: 'Braid REST API',
+            version: '0.0.1',
+            description: 'REST surface exposed by @braidhq/server. Each operation also becomes an MCP tool via openapi-mcp-gateway.',
+        },
+        ...(options.apiUrl ? { servers: [{ url: options.apiUrl }] } : {}),
+    });
     return app;
 }
 //# sourceMappingURL=app.js.map

package/dist/app.js.map

@@ -1 +1 @@
-{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}

package/dist/authMode.d.ts

@@ -0,0 +1,39 @@
+import type { UserId } from '@braidhq/schema';
+import type { AccessPolicy } from './infrastructure/auth/AccessPolicy.js';
+import type { UserRegistryFile } from './infrastructure/users/UserRegistryFile.js';
+export declare const LOCAL_USER_ID: string & import("zod").$brand<"UserId">;
+export interface AuthContext {
+    readonly userRegistry: UserRegistryFile;
+    readonly accessPolicy: AccessPolicy;
+}
+/**
+ * How a deployment resolves identity.
+ * The one axis that separates a trusted local install,
+ * from an authenticated remote server.
+ *
+ * Two separate axes, not one nullable field.
+ * `defaultPrincipal` is the identity axis, the implicit user for an
+ * unauthenticated request, and the owner a workspace falls back to,
+ * or null when there is no implicit user.
+ * `requiresAuth` is the policy axis, whether a caller must present a valid
+ * Bearer token. The middleware reads this, never the principal's null-ness.
+ *
+ * Stateless behaviour behind an interface, so a const object per mode,
+ * the idiomatic strategy form when there is no constructor dependency.
+ */
+export interface AuthMode {
+    readonly defaultPrincipal: UserId | null;
+    readonly requiresAuth: boolean;
+    provision: (context: AuthContext) => Promise<void>;
+}
+/**
+ * A local desktop or sidecar. One implicit user owns everything,
+ * so provision seeds that `local-user` admin account, idempotently.
+ */
+export declare const localTrust: AuthMode;
+/**
+ * A remote server. Real users authenticate against an allowlist,
+ * so provision back-fills `approvedEmails` from the roster, idempotently.
+ */
+export declare const authenticated: AuthMode;
+//# sourceMappingURL=authMode.d.ts.map

package/dist/authMode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authMode.d.ts","sourceRoot":"","sources":["../src/authMode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAa,MAAM,EAAE,MAAM,iBAAiB,CAAA;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAA;AACzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4CAA4C,CAAA;AAKlF,eAAO,MAAM,aAAa,yCAAmC,CAAA;AAE7D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAA;IACvC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAA;CACpC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IACxC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAE9B,SAAS,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACnD;AAED;;;GAGG;AACH,eAAO,MAAM,UAAU,EAAE,QAaxB,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,QAS3B,CAAA"}

package/dist/authMode.js

@@ -0,0 +1,50 @@
+import { userInfo } from 'node:os';
+import process from 'node:process';
+import { UserId as UserIdSchema } from '@braidhq/schema';
+export const LOCAL_USER_ID = UserIdSchema.parse('local-user');
+/**
+ * A local desktop or sidecar. One implicit user owns everything,
+ * so provision seeds that `local-user` admin account, idempotently.
+ */
+export const localTrust = {
+    defaultPrincipal: LOCAL_USER_ID,
+    requiresAuth: false,
+    async provision({ userRegistry }) {
+        if (await userRegistry.get(LOCAL_USER_ID))
+            return;
+        await userRegistry.create({
+            id: LOCAL_USER_ID,
+            displayName: osUsername(),
+            serverRole: 'admin',
+            createdAt: new Date().toISOString(),
+        });
+    },
+};
+/**
+ * A remote server. Real users authenticate against an allowlist,
+ * so provision back-fills `approvedEmails` from the roster, idempotently.
+ */
+export const authenticated = {
+    defaultPrincipal: null,
+    requiresAuth: true,
+    async provision({ userRegistry, accessPolicy }) {
+        for (const user of await userRegistry.list()) {
+            if (user.email)
+                await accessPolicy.approveEmail(user.email);
+        }
+    },
+};
+// Default display name from the OS account.
+// Some sandboxed environments throw on userInfo(), so fall through.
+function osUsername() {
+    try {
+        const info = userInfo();
+        if (info.username && info.username.length > 0)
+            return info.username;
+    }
+    catch {
+        // The userInfo lookup can throw, fall through to the env vars below.
+    }
+    return process.env.USER ?? process.env.USERNAME ?? 'local';
+}
+//# sourceMappingURL=authMode.js.map

package/dist/authMode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authMode.js","sourceRoot":"","sources":["../src/authMode.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAClC,OAAO,OAAO,MAAM,cAAc,CAAA;AAClC,OAAO,EAAE,MAAM,IAAI,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAExD,MAAM,CAAC,MAAM,aAAa,GAAG,YAAY,CAAC,KAAK,CAAC,YAAY,CAAC,CAAA;AA6B7D;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAa;IAClC,gBAAgB,EAAE,aAAa;IAC/B,YAAY,EAAE,KAAK;IACnB,KAAK,CAAC,SAAS,CAAC,EAAE,YAAY,EAAE;QAC9B,IAAI,MAAM,YAAY,CAAC,GAAG,CAAC,aAAa,CAAC;YACvC,OAAM;QACR,MAAM,YAAY,CAAC,MAAM,CAAC;YACxB,EAAE,EAAE,aAAa;YACjB,WAAW,EAAE,UAAU,EAAE;YACzB,UAAU,EAAE,OAAO;YACnB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAe;SACjD,CAAC,CAAA;IACJ,CAAC;CACF,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAa;IACrC,gBAAgB,EAAE,IAAI;IACtB,YAAY,EAAE,IAAI;IAClB,KAAK,CAAC,SAAS,CAAC,EAAE,YAAY,EAAE,YAAY,EAAE;QAC5C,KAAK,MAAM,IAAI,IAAI,MAAM,YAAY,CAAC,IAAI,EAAE,EAAE,CAAC;YAC7C,IAAI,IAAI,CAAC,KAAK;gBACZ,MAAM,YAAY,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAC/C,CAAC;IACH,CAAC;CACF,CAAA;AAED,4CAA4C;AAC5C,oEAAoE;AACpE,SAAS,UAAU;IACjB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,QAAQ,EAAE,CAAA;QACvB,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC;YAC3C,OAAO,IAAI,CAAC,QAAQ,CAAA;IACxB,CAAC;IACD,MAAM,CAAC;QACL,qEAAqE;IACvE,CAAC;IACD,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,OAAO,CAAA;AAC5D,CAAC"}

package/dist/composeApp.d.ts

@@ -0,0 +1,79 @@
+import type { BatchPlanRepository, ClarificationRepository, Clock, IntentLister, ModelRepository, ModelSerializer, ProposalRepository, ReactorCycleRepository, RunRepository, SkillRegistry, SkillRunner, SourceUnitDigest, SourceUnitObservationRepository, UserDirectory, WorkspaceBootstrapService, WorkspaceEventBus, WorkspaceHistory, WorkspaceRepository } from '@braidhq/core';
+import type { AbsolutePath } from '@braidhq/schema';
+import type { AuthMode } from './authMode.js';
+import type { AccessPolicy } from './infrastructure/auth/AccessPolicy.js';
+import type { SessionStore } from './infrastructure/auth/SessionStore.js';
+import type { GoogleOAuth } from './infrastructure/oauth/GoogleOAuth.js';
+import type { SecretStore } from './infrastructure/secrets/SecretStore.js';
+import type { UserRegistryFile } from './infrastructure/users/UserRegistryFile.js';
+import type { WorkspaceRegistryFile } from './infrastructure/workspace/WorkspaceRegistryFile.js';
+import { BatchService, HistoryService, HITLService, ModelService, ModelValidationService, PluginRegistry, ReactorService, SourceLoaderRunner, SourceUnitObservationService, WorkspaceService } from '@braidhq/core';
+/**
+ * The assembled application, what routes and middleware consume.
+ * A required field is always present.
+ * An optional field is a capability slot,
+ * absent under in-memory or test wiring, filled by `composeFsApp`.
+ */
+export interface AppDependencies {
+    workspaceService: WorkspaceService;
+    hitlService: HITLService;
+    modelService: ModelService;
+    modelValidationService: ModelValidationService;
+    sourceLoaderRunner: SourceLoaderRunner;
+    sourceUnitObservationService: SourceUnitObservationService;
+    historyService?: HistoryService;
+    batchService?: BatchService;
+    reactorService?: ReactorService;
+    modelRepository: ModelRepository;
+    workspaceRepository: WorkspaceRepository;
+    proposalRepository: ProposalRepository;
+    clarificationRepository: ClarificationRepository;
+    runRepository: RunRepository;
+    reactorCycleRepository: ReactorCycleRepository;
+    intentLister?: IntentLister;
+    sourceUnitDigest?: SourceUnitDigest;
+    skillRegistry: SkillRegistry | undefined;
+    skillRunner: SkillRunner | undefined;
+    eventBus: WorkspaceEventBus;
+    pluginRegistry: PluginRegistry;
+    clock: Clock;
+    workspacesRoot: AbsolutePath;
+    bootstrap?: WorkspaceBootstrapService;
+    authMode: AuthMode;
+    userRegistry?: UserRegistryFile;
+    workspaceRegistry?: WorkspaceRegistryFile;
+    sessionStore?: SessionStore;
+    accessPolicy?: AccessPolicy;
+    secretStore?: SecretStore;
+    googleOAuth?: GoogleOAuth;
+    studioUrl?: string;
+}
+/**
+ * Every field is optional, an unset one falls to an in-memory default.
+ * `composeFsApp` passes the fs, git, and vendor adapters through here.
+ */
+export interface ComposeOptions {
+    clock?: Clock;
+    eventBus?: WorkspaceEventBus;
+    pluginRegistry?: PluginRegistry;
+    modelRepository?: ModelRepository;
+    workspaceRepository?: WorkspaceRepository;
+    proposalRepository?: ProposalRepository;
+    clarificationRepository?: ClarificationRepository;
+    runRepository?: RunRepository;
+    reactorCycleRepository?: ReactorCycleRepository;
+    sourceUnitObservationRepository?: SourceUnitObservationRepository;
+    batchPlanRepository?: BatchPlanRepository;
+    intentLister?: IntentLister;
+    sourceUnitDigest?: SourceUnitDigest;
+    skillRegistry?: SkillRegistry;
+    skillRunner?: SkillRunner;
+    history?: WorkspaceHistory;
+    modelSerializer?: ModelSerializer;
+    bootstrap?: WorkspaceBootstrapService;
+    userDirectory?: UserDirectory;
+    authMode?: AuthMode;
+    workspacesRoot?: AbsolutePath;
+}
+export declare function composeApp(options?: ComposeOptions): AppDependencies;
+//# sourceMappingURL=composeApp.d.ts.map

package/dist/composeApp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composeApp.d.ts","sourceRoot":"","sources":["../src/composeApp.ts"],"names":[],"mappings":"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"}