Machine-auth: caller resolver for workflow-run children (CL-6286)

[TheGreatAxios]

Problem

Every route registerMemoryRoutes mounts is guarded by requirePrincipal() + grantGuard(), which read c.get("principal") — set by the host's tenant-session middleware for a browser/API caller. A workflow-run child has no browser session, only its own sidecar bearer token and run address, so a host wanting agents (not just humans) to reach memory had to build a second, parallel HTTP surface itself (see packages/memory-hub/src/workflow-routes.ts in the workbench repo — the workaround this closes).

The seam

RouteDeps gains an optional field:

export type ResolvedCaller = { tenantId: string; principalId: string };

export type CallerResolver = (
  c: Context<TenantEnv>,
) => ResolvedCaller | null | Promise<ResolvedCaller | null>;

export type RouteDeps = {
  memory: Memory;
  requireGrant: RequireGrant;
  grants: GrantConfig;
  callerResolver?: CallerResolver; // NEW, optional
};

createMemory({ callerResolver, ... }) threads it through to registerMemoryRoutes.

A new middleware, resolveCaller(deps), is inserted ahead of requirePrincipal()/grantGuard() on every route (add/search/list/feed):

• Unset (default): no-op passthrough. Every existing host is byte-for-byte unaffected — identity still comes only from c.get("principal"), set by the host's own tenant-session middleware. No existing test changed meaning.
• Set: calls deps.callerResolver(c). If it returns null, the request gets 401 unauthorized and never reaches requirePrincipal/grantGuard — it never falls through to a browser principal that might coincidentally be on the context. If it resolves, the {tenantId, principalId} is seated as the context principal/tenant (with placeholder fields Interchange's authorize() never reads — it only touches .id), and the request proceeds through the exact same requirePrincipal/grantGuard/caller() code every browser request goes through.

Why this doesn't violate "authenticate nothing"

The package still authenticates nothing. callerResolver is a function the host supplies and the host implements entirely — bearer-token lookup, run-address lookup, whatever the host's transport is. This package never validates a token, a signature, or a header; it only accepts an already-resolved {tenantId, principalId} and seats it where the rest of the request pipeline (grant guard, caller()) already expects to find it. The host still owns 100% of authentication; this ticket only stops the package from assuming how the host arrived at that identity.

Identity cannot be spoofed by the request body

No route body schema (AddRequest, SearchRequest, ListQuery, FeedQuery) has ever had a tenantId/principalId field, and every handler reads scope only from caller(c) (context), never from the parsed body. This ticket adds an explicit test proving it end-to-end for the new seam:

src/routes/routes.test.ts — "a request body naming a different tenant/principal is ignored — the resolved caller always wins": a machine caller resolves to tenant-run/run-principal; the POST body additionally claims tenantId: "tenant-evil" and principalId: "attacker"; the plane still records the write under tenant-run/run-principal.

Also covered: grant guarding still applies to a resolved caller (403 with no grant, 403 with a grant for a different principal, 200 with the right grant), and an unresolvable caller gets 401 without ever falling back to a stale/absent browser principal.

Rate limiting and payload caps: left as a host concern

The downstream workaround bolted a per-run sliding-window add-rate-limiter and a 64k-character add-text cap onto its parallel surface. Not ported here:

• No route in this package has ever had a rate limit or payload cap, browser or machine. Adding one only for machine callers would be an arbitrary asymmetry, not a security property this ticket is about.
• A meaningful rate limit is inherently host/topology-specific — it depends on process count, replica count, and how the host wants a runaway caller to degrade (the downstream file's own comments note its per-process limiter under-limits across replicas). That's a deployment decision, not something a shared library should hardcode.
• If a payload cap is wanted, it belongs to add generally (every caller, not just machine callers) and is a separate, uniformly-applied product decision — out of scope for a caller-resolution ticket.

A host that wants either can still enforce them itself in callerResolver (reject before we ever see the request) or with ordinary Hono middleware ahead of registerMemoryRoutes.

What a downstream host deletes

Once mounted with callerResolver, a host no longer needs a second Hono app (createWorkflowMemoryRoutes/createUnavailableWorkflowMemoryRoutes), a second store adapter (createWorkflowMemoryStore), or hand-rolled body validation/response shaping duplicating add/search/list — it authenticates the run, hands back {tenantId, principalId}, and reuses this package's routes and grant enforcement outright.

Tests

401 → 410 passing (bun test ./src); bun run typecheck clean. New tests: 4 unit tests for resolveCaller (src/routes/deps.test.ts), 5 end-to-end route tests for the machine-caller path (src/routes/routes.test.ts), including the identity-spoofing test above.

Refs CL-6286.

Adversarial review follow-ups

A review pass on the first version of this PR confirmed the core authorization
claim (machine and browser callers hit byte-identical
requireGrant("memory", action) → authorize() on all four routes, ordering
consistent, null fails closed with 401, a throwing resolver fails closed with
a generic 500 that does not leak the thrown message) but found four gaps,
addressed in the commits since:

1. BLOCKER — the resolver's return value was never parsed at a trust
   boundary. Any truthy object matching the TS shape was seated directly as
   the request principal, including {tenantId: "", principalId: ""} — a
   silent write under a garbage scope from a buggy host resolver.
   resolveCaller now parses the return with arktype (non-empty
   tenantId/principalId) before seating it.

   Status code: null still means "this caller could not be
   authenticated" — a caller problem, 401. A resolved value that fails the
   schema means the host's own resolver is broken — a host bug, not a
   caller's, so it is now 500, not 401: the request was never
   "unauthorized," the identity provider misbehaved. Covered by tests in
   src/routes/deps.ts's resolveCaller unit tests and an end-to-end test in
   routes.test.ts that also proves a grant existing for the empty-string
   principal never gets a chance to authorize the write.

2. Canary contract test for the fabricated rows. principalRowFor/
   tenantRowFor (deps.ts) synthesize PrincipalRow/TenantRow with
   placeholder fields, verified today to be safe against @intx/hub-api@0.2.2
   because authorize() only reads .id. A new test in routes.test.ts
   seats a Proxy-based canary row that throws on any property access beyond
   .id/.tenantId, run through the real requireGrant/authorize and
   caller(). A future Interchange version that starts reading a fabricated
   field (status, kind, parentId, config, ...) now breaks this suite
   instead of silently authorizing on fiction.

3. Machine-caller tests extended to search, list, and feed. The
   original tests only covered /memory/add; a failure on the read paths
   means reading another tenant's memories, the worst outcome in this ticket.
   New tests cover all four routes, including the :tenantId URL segment
   claiming a different tenant than the resolved caller's and a cross-tenant
   list fixture proving the resolved caller only ever sees its own tenant's
   events.

4. Adapted the reviewer's edge-case tests (throwing resolver fails closed
   without leaking; malformed resolver output) directly into
   routes.test.ts; the malformed-output test now asserts rejection (500)
   rather than a garbage-scope write, per fix 1.

5. Docs: IMPLEMENTATION.md now calls out explicitly that a host deleting
   a hand-rolled parallel surface (like the downstream workflow-routes.ts
   this PR obsoletes) must re-home that surface's per-run rate limiter and
   payload cap as its own middleware first — this package still does not
   implement either, and deleting the file silently drops both. A comment at
   registerMemoryRoutes now states that the :tenantId path segment is
   never read by any handler; scope always comes from caller(c).

Tests: 401 → 422 passing; bun run typecheck clean throughout.

Follow-up: whitespace-only identity

"string >= 1" on ResolvedCallerSchema is a LENGTH constraint, not a content
one — " " has length 1 and passed it, so a whitespace-only
tenantId/principalId was still seated as a "valid" scope: the same exploit
in a different costume (same bug class PR #34 fixed in optionalEnv, where
v.length > 0 accepted " "). Fixed by requiring at least one
non-whitespace character:

const NonBlankId = type("string").narrow(
  (s, ctx) => s.trim().length > 0 || ctx.mustBe("non-blank (not just whitespace)"),
);

The malformed-output regression test (deps.test.ts and the end-to-end test
in routes.test.ts) now covers a whitespace-only id (" ", "\t\n")
alongside the empty-string case via test.each.

Tests: 422 → 424 passing; bun run typecheck clean throughout.