Return 401 instead of a 500 when the host has not resolved a principal

A stock mount 500s on every knowledge route.

The routes read c.get("principal") but mount at /api/knowledge/*, which is
outside /api/tenants/:tenantId/* — the prefix Interchange's createResolveTenant
covers, and where it reads the tenant from the path param. Nothing populates the
context for our prefix, so a host that just calls mountKnowledgeEngine per the
README gets:

  TypeError: undefined is not an object (evaluating 'principal.id')
    at packages/hub-api/src/middleware/grant.ts:55:9

requireGrant dereferences the principal with no guard of its own, so it throws
before caller() runs — and caller() already has a good error message for exactly
this case that nobody ever sees. The failure surfaces as a 500 with a stack
trace pointing into Interchange, which reads as this SDK being broken rather
than as the host missing middleware.

Adds requirePrincipal(), mounted ahead of grantGuard on all three routes,
returning 401 principal_required with an actionable message. The README
documents the middleware the host has to supply.

This is the minimum fix. Moving the routes under /api/tenants/:tenantId/ would
remove the requirement entirely and need no host glue — worth considering, but
it is a breaking path change so it should be a deliberate call rather than
folded in here.

Tests: 145 pass, 0 fail. Typecheck clean.

Refs CL-4506

Claude-Session: https://claude.ai/code/session_017GTgGzn5xAwvkU2GAPAHpF

Author: TheGreatAxios

README.md

@@ -41,7 +41,7 @@ import { loadKnowledgeConfig } from "@corbits/knowledge-engine/config";
 // `app` is your Interchange createApp (Hono<TenantEnv>). Pass the same grant
 // store + condition registry you give createApp/createRequireGrant.
 mountKnowledgeEngine(app, {
-  config: loadKnowledgeConfig(),          // or build the object yourself
+  config: loadKnowledgeConfig(), // or build the object yourself
   grants: { grantStore, conditionRegistry },
 });
 ```
@@ -51,6 +51,42 @@ That mounts `POST /api/knowledge/capture`, `POST /api/knowledge/search`, and
 `requireGrant("knowledge", <action>)`. Clients never send tenant or principal —
 identity is the context principal.
 
+### The host must resolve tenant + principal for `/api/knowledge/*`
+
+These routes read `c.get("principal")`, but they mount at `/api/knowledge/*` —
+**outside** `/api/tenants/:tenantId/*`, which is where Interchange's own
+`createResolveTenant` middleware is scoped and where it reads the tenant from
+the path param. Nothing populates the context for our prefix, so the host has to:
+
+```ts
+// Mount BEFORE mountKnowledgeEngine — the grant guard runs first and needs a
+// principal on the context.
+app.use("/api/knowledge/*", async (c, next) => {
+  const user = c.get("user");
+  if (!user) return c.json({ error: "unauthorized" }, 401);
+
+  // Your choice how the tenant is selected — a header, a subdomain, or the
+  // user's only membership. There is no path param to read.
+  const tenantRow = await resolveTenantSomehow(c);
+  const principalRow = await db.query.principal.findFirst({
+    where: and(
+      eq(principal.tenantId, tenantRow.id),
+      eq(principal.kind, "user"),
+      eq(principal.refId, user.id),
+    ),
+  });
+  if (!principalRow) return c.json({ error: "not a member" }, 403);
+  if (principalRow.status !== "active")
+    return c.json({ error: "inactive" }, 403);
+
+  c.set("tenant", tenantRow);
+  c.set("principal", principalRow);
+  await next();
+});
+```
+
+Without it every knowledge route returns **401 `principal_required`**.
+
 Apply the knowledge/vector schema once (idempotent):
 
 ```ts

src/routes/capture.ts

@@ -6,7 +6,7 @@ import { type } from "arktype";
 import { formatCaughtError, log } from "../log.ts";
 import { parseAcl } from "../acl.ts";
 import type { RouteDeps } from "./deps.ts";
-import { caller, grantGuard } from "./deps.ts";
+import { caller, grantGuard, requirePrincipal } from "./deps.ts";
 
 const CaptureRequest = type({
   title: "string >= 1",
@@ -33,6 +33,7 @@ export function mountCaptureRoute(app: Hono<TenantEnv>, deps: RouteDeps): void {
         403: { description: "Missing the knowledge:capture grant" },
       },
     }),
+    requirePrincipal(),
     grantGuard(deps, "capture"),
     validator("json", CaptureRequest),
     async (c) => {

src/routes/deps.ts

@@ -38,6 +38,43 @@ export function caller(c: Context<TenantEnv>): {
   return { scopeId: principal.tenantId, subjectId: principal.id };
 }
 
+/**
+ * Reject the request if the host has not put a principal on the context.
+ *
+ * Must run BEFORE `grantGuard`. Interchange's `requireGrant` reads
+ * `principal.id` without a guard of its own, so on an unresolved context it
+ * throws `TypeError: undefined is not an object` and the host sees a 500 with a
+ * stack trace pointing into Interchange — which reads as this SDK being broken
+ * rather than as the host missing middleware. `caller()` below has a perfectly
+ * good error message for exactly this case, but it never gets to run.
+ *
+ * These routes mount at `/api/knowledge/*`, outside the
+ * `/api/tenants/:tenantId/*` prefix that Interchange's `createResolveTenant`
+ * covers, so an unresolved context is the DEFAULT for a host that just calls
+ * `mountKnowledgeEngine`. See the README for the middleware the host supplies.
+ */
+export function requirePrincipal(): MiddlewareHandler<TenantEnv> {
+  return async (c, next) => {
+    if (!c.get("principal")) {
+      return c.json(
+        {
+          error: {
+            code: "principal_required",
+            message:
+              "No principal on the request context. The knowledge routes mount " +
+              "at /api/knowledge/*, which is outside Interchange's " +
+              "/api/tenants/:tenantId/* tenant middleware — the host must " +
+              "resolve tenant + principal for this prefix. See the " +
+              "@corbits/knowledge-engine README.",
+          },
+        },
+        401,
+      );
+    }
+    await next();
+  };
+}
+
 /** Route-guard middleware for a knowledge action (Interchange `requireGrant`). */
 export function grantGuard(
   deps: RouteDeps,

src/routes/search.ts

@@ -7,7 +7,7 @@ import { formatCaughtError, log } from "../log.ts";
 import { KnowledgeError } from "../knowledge.ts";
 import { SearchResponseSchema } from "../core/schemas/search.ts";
 import type { RouteDeps } from "./deps.ts";
-import { caller, grantGuard } from "./deps.ts";
+import { caller, grantGuard, requirePrincipal } from "./deps.ts";
 
 const SearchRequest = type({
   query: "string >= 1",
@@ -31,6 +31,7 @@ export function mountSearchRoute(app: Hono<TenantEnv>, deps: RouteDeps): void {
         403: { description: "Missing the knowledge:search grant" },
       },
     }),
+    requirePrincipal(),
     grantGuard(deps, "search"),
     validator("json", SearchRequest),
     async (c) => {

src/routes/timeline.ts

@@ -4,7 +4,7 @@ import { describeRoute, resolver } from "hono-openapi";
 import { type } from "arktype";
 
 import type { RouteDeps } from "./deps.ts";
-import { caller, grantGuard } from "./deps.ts";
+import { caller, grantGuard, requirePrincipal } from "./deps.ts";
 
 const TimelineResponse = type({
   events: type({
@@ -16,7 +16,10 @@ const TimelineResponse = type({
   }).array(),
 });
 
-export function mountTimelineRoute(app: Hono<TenantEnv>, deps: RouteDeps): void {
+export function mountTimelineRoute(
+  app: Hono<TenantEnv>,
+  deps: RouteDeps,
+): void {
   app.get(
     "/api/knowledge/timeline",
     describeRoute({
@@ -32,6 +35,7 @@ export function mountTimelineRoute(app: Hono<TenantEnv>, deps: RouteDeps): void
         403: { description: "Missing the knowledge:search grant" },
       },
     }),
+    requirePrincipal(),
     grantGuard(deps, "search"),
     (c) => {
       const { scopeId } = caller(c);