[kriszyp]

⊙ Problem

Components that issue their own access tokens, like the OAuth plugin's MCP authorization server (MCP OAuth does not populate context.user for Harper core's native /mcp endpoint), cannot use them on Harper's routes. Core authentication accepts only Harper's own Bearer tokens and defers any other (Defer unrecognized app-port Authorization until route ownership), so REST, GraphQL, WebSocket, MQTT and /mcp answer 401.

🤔 Should core own this, rather than the plugin authenticating its own requests?

Yes, as specified: one place decides request.user for every route. Plugin middleware would re-implement token precedence, the minting block and cache expiry.

🤔 Ship from main (v5.4), not as a v5.3 backport?

Main: it is a new public API. The review suggested v5.3 only because it extends will code backported there.

💡 Solution

• server.registerBearerValidator(validator, { timeoutMs }) returns a function that removes it.
• A validator returns null, { username, authExpiresAt?, authCacheable? }, or throws credentialRejectionError. server.getUser resolves the user, so its own role applies.
• Harper's tokens are checked first. No validators on a dedicated operations port, and the token cannot be exchanged for Harper tokens.
• Logins are cached until authExpiresAt, capped at the JWT exp (default 5 minutes). Live subscriptions and MQTT wills end then.

server.registerBearerValidator(async (token, request, signal) => {
	const claims = await verifyMyAccessToken(token, { signal }); // null for tokens this issuer did not sign
	if (!claims) return null;
	if (claims.aud !== MY_AUDIENCE) throw credentialRejectionError('wrong audience', 401);
	return { username: claims.sub, authExpiresAt: claims.exp };
});

🤔 Is caching by the Authorization header the right default?

A cached login is reused on every route without asking the validator, so a route-dependent validator must return authCacheable: false (documented). Keying by route would cost every login.

⚖️ Alternatives

Other approaches

• Plugin middleware — every plugin re-implements precedence, the minting block and expiry.
• Issue Harper operation tokens — no RFC 8707 audience binding, which MCP requires.
• Fallback in validateOperationToken — no request there, and operations-port auth calls it too.

🤔 Username only, or also per-token permissions?

Username only; any other field, role included, fails. OAuth plugin tokens name a Harper user and carry no permissions, while a role-carrying login needs its own revocation wherever users are re-read by name. Refusing role keeps adding it later compatible.

🔧 Changes

Product and architecture tour

Product and architecture tour

Where validators run

How does a Bearer token Harper did not issue become request.user?

Bearer token path through authentication()

Harper's own tokens are tried first. Validators only see a token those reject, and a claimed username still goes through server.getUser.

flowchart TD
  A[Bearer header] --> B{cached and unexpired}
  B -- yes --> U[request.user]
  B -- no --> C{Harper operation token}
  C -- valid --> U
  C -- expired --> R[credential rejection]
  C -- invalid --> D{refresh token}
  D -- yes --> O[operations API handles it]
  D -- no --> E{validators registered, not ops port}
  E -- no --> F[deferred as before]
  E -- yes --> G[validators in order]
  G -- all decline --> F
  G -- tagged throw --> R
  G -- other throw or timeout --> X[401 in place]
  G -- username --> H[server.getUser, expiry recheck]
  H --> U

Loading

• The chain runs only when validators are registered and the request is not on a dedicated operations port, after the refresh probe. A cached validator principal is ignored on the operations port too.
• The refresh probe now runs only for a non-JWT or a JWT whose sub is refresh; refresh tokens are always signed with that subject, so other JWTs skip a second RSA verify.
• A claim whose validator was disposed while it resolved reads as an unrecognized token.
• When a validator claims a token, the invalid-token warnings are dropped; when all decline, they are logged as before.

The validator contract

What may a validator return, and what does Harper do with it?

A validator returns null, { username, authExpiresAt?, authCacheable? }, or throws. Any other field fails closed.
The username is resolved by server.getUser(username, null, request), with the Basic path's record tracking.
A tagged throw is a credential rejection; an untagged throw, a malformed result or a timeout is a 401 in place.

• runBearerValidators runs validators in registration order and refuses any field outside the three (the allowed set).
• principalFromClaim resolves the user through resolveUser. An unknown username or a user with no role is a tagged rejection, like an unknown Basic user.
• withinDeadline bounds each validator by its timeoutMs and the whole chain, lookup included, by the largest one. On a timeout it rejects before aborting the signal, so an abort listener that resolves cannot win.
• Public types: BearerValidatorIdentity and BearerValidatorOptions, exported from harper. The JSDoc on registerBearerValidator is the contract.

Caching and expiry

How long does an accepted token stay accepted?

• effectiveExpiry takes the validator's authExpiresAt (now + 300 s when omitted), capped by the token's own JWT exp, so a JWT whose exp has passed is refused as token expired even when the validator accepts it. It is checked again after the lookup.
• authorizationCache stays keyed by the Authorization header. A cached validator principal is evicted once its validator is disposed, via validatorClaims, so registering or disposing never flushes Basic or session logins.
• An invalidation generation keeps a login resolved across a user/role change from refilling the new cache.
• User gains authExpiresAt. trackUserRecords now reports whether the user came from a component override, and the Basic path copies only those before caching, so a memoizing override's object cannot be re-stamped under a cached login.

Registration lifecycle and token minting

Who can register, and what can a validator-authenticated user not do?

• server.registerBearerValidator validates timeoutMs (max 60 s), publishes a frozen snapshot read by getBearerValidators, and returns a disposer that marks the entry inactive.
• The Scope proxy records what a plugin registers through scope.server; disposeBearerValidators removes them when the plugin's load fails, and a closed scope refuses new ones. Registrations otherwise outlive scope.close() so in-flight requests drain.
• A _bearerValidator user cannot mint operation or refresh tokens without a password or, unless operation authorization is bypassed, scoped tokens; the marker survives impersonation.
• server/DESIGN.md records these rules, the rejection table row and the refresh-probe ordering.

MQTT last wills

Can a will outlive the token that authorized it?

• A validator principal's will persists its authExpiresAt, and isPastBearerExpiry drops it on live disconnect.
• Restart replay moved into replayLastWill, which checks the expiry again after its server.getUser lookup.

Docs: Document server.registerBearerValidator

Tests and fixtures

• authCredentialDeferral.test.js: the validator suite, covering malformed results, header-keyed caching, will expiry and replay and expiry during the lookup. The existing deferral suite only seeds system tables first.
• deferred-credential-rejection.test.ts runs a real read-only user over REST, MCP (with the MCP mount enabled), GraphQL and WebSocket, and the operations port; it creates that user. The fixture registers the validators; its session-user names became module-private.
• Scope.test.js covers proxy registration, close and failed-load rollback. gitSSHMaterialization.test.js now restores ROOTPATH; it leaked into later suites.

✅ Verification

• Integration (REST, /mcp tools/list, GraphQL, WebSocket) and security suites: 45/45. Unit: 155 passing.
• The two expiry rechecks (after the server.getUser lookup, after will replay) each have a test that fails without the fix.
• Full local gates pass, apart from two blob tests that pass alone and in CI.

Gate details

• test:unit:main: 7330 passing; 2 failing in blobMsgpackSerialization.test.js, which registers REST on the default mount and gets no handler when an earlier suite already has. It passes alone and in this PR's CI.
• test:unit:resources: 4407 passing, 0 failing.
• test:integration:all: 2548 passing, 0 failing; 9 cancelled. Six are the local Ollama suite (no models on this machine). Three are record-caching-scan-coherence, whose server was not up in time under load; 3/3 alone.

- PR QA: skipped @ 44ee648 — dispatch unavailable (no worker token in the agent's home)

_{🤖 Generated by Claude Code (Claude Opus 5.5); posted via @kriszyp.}

https://claude.ai/code/session_01FKif56wJ3LB5ZqsGi3E9eg

Release target: main — new API surface, ships in v5.4

Related PRs: #2906 overlaps (both edit the Bearer and deferral branch of security/auth.ts), 1 others independent
Complexity: complicated

Deferred findings

• 258b53374ec1279b minor correctness — components/mcp/listChanged.ts — non-scoped MCP session refresh via findAndValidateUser yields role-less user for custom getUser principals — NOT FILED
• 68be2bfdb6d78f3b minor correctness — resources/Resource.ts — live-subscription recheck via findAndValidateUser revokes custom-getUser-only validator principals — NOT FILED
• 0c33e36d230f384b nit maintainability — server/Server.ts — default validator timeout 5 s instead of 30 s — NOT FILED
• 714610fa6104ed27 nit correctness — security/user.ts — nested in-place permission write on a getUser view mutates the shared derivedRoles memo — filed security/user: userView shallow-copies role.permission so nested in-place edits mutate shared derivedRoles memo #3267
• af8801a2b5517bc7 nit performance — security/user.ts — record provenance per userView and cloneUserView on cache hits — NOT FILED
• 1882fe06c54011d3 nit security — components/Scope.ts — validator registered via module-level harper server bypasses Scope rollback and closed guard — NOT FILED
• a6a257702252e7a8 nit reliability — security/auth.ts — authorizationCache accumulates rotated external Bearer tokens — NOT FILED
• abd015a7d4414ec8 nit reliability — components/Scope.ts — validator registrations outlive scope.close() and would accumulate on an in-process reload — NOT FILED
• 1b6ae28adda30edb nit security — server/DurableSubscriptionsSession.ts — restart replay of non-scoped will skips revocation checks the live path applies — NOT FILED
• 12e79a86e3c23afb nit reliability — security/bearerValidators.ts — synchronous validator work is not charged to timeoutMs — NOT FILED
• +5 more in the review receipt

_{Dispatch: task harper-oauth279-bearer-validator-hook · queued by unknown · ran by claude/opus/xhigh · worker kzyp-xps-1}

_{Review-Coverage: authored=claude; ran=cursor-composer,gemini,codex; adjudicated=domain; declined=cursor-grok,cursor-kimi,cursor-muse,muse; rounds=22; full=8 @ 8194686}

_{Review-Attention: deep ~45m (sensitive: auth.ts, bearerValidators.ts +3; hot: DurableSubscriptionsSession.ts; decisions: jwt-exp-hard-cap, expiry-check-after-validator, validators-inside-authentication, cache-keyed-by-header, ops-exclusion-dedicated-port-only, do-less-alternative, release-target-unclear) @ 8194686}

[gemini-code-assist]

Code Review

This pull request introduces a mechanism for registering custom Bearer token validators via server.registerBearerValidator, allowing Harper to authenticate external tokens. It integrates these validators into the core authentication flow, handles exact token expiration (including for MQTT last-wills), enforces timeout budgets, and prevents passwordless token minting. Feedback on the changes highlights a potential bug in server/Server.ts where disposing of a validator could accidentally remove the last active validator if the entry is not found in the array due to splice(-1, 1).