tRPC Context Scope Gap After Router Merges

Synchronizing Scope Claims When Routers are Split

When a tRPC API is organized into multiple router files, each router can add its own ctx.scopes value. If the routers are merged after their individual context middlewares have run, the last router wins and earlier scopes are lost. The safe pattern is: build the entire context in one place, before any router is merged.

1. Define a buildContext middleware that extracts the token, validates it, and normalises the scopes array.
2. Attach this middleware to the root router (the one returned by createTRPCRouter()) before calling merge() on any child routers.
3. Inside child routers, read ctx.scopes but do not overwrite it. If a router needs to augment scopes, merge immutably: ctx.scopes = [...ctx.scopes, ...extraScopes].
4. Because the context is built once, every procedure – no matter which file it lives in – sees the same, complete scope set.

Signalling an Expired or Revoked Token

tRPC’s error handling treats all failures as generic errors unless you throw a TRPCError with a recognised code. To surface a token expiry without breaking existing logic:

• Throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Token expired', details: { type: 'TOKEN_EXPIRED' } }) from your token‑validation middleware.
• Clients can inspect error.code (still "UNAUTHORIZED") and error.data.details.type to distinguish an expiration from a generic auth failure.
• Because the code remains standard, server‑side generic error handlers continue to work; only the client can react specially.

Least‑Privilege Enforcement with Custom Middleware

tRPC lacks a built‑in permission system, but you can scaffold one that plays well with any custom middleware:

1. Create a requireScope middleware that accepts a required scope string.
2. Inside the middleware, check ctx.scopes.includes(requiredScope). If not, throw new TRPCError({ code: 'FORBIDDEN', message: 'Missing scope: ' + requiredScope }).
3. Attach the middleware to individual procedures via procedure.use(requireScope('user:read')) or compose it with other middlewares using procedure.use(...).
4. Because the middleware is pure and stateless, it can coexist with any token‑validation middleware you already have.

With this pattern you get:

• Centralised scope extraction.
• Explicit error signaling for token expiry.
• Declarative, least‑privilege checks that are composable.

What to Verify Next

To ensure the implementation behaves as expected, run the following checks:

• Send a request with a token that contains scopes from both router files; assert that ctx.scopes contains the union.
• Mock an expired token and confirm the server responds with code "UNAUTHORIZED" and a detail flag of "TOKEN_EXPIRED".
• Test a procedure guarded by requireScope('admin:write') with a user lacking that scope; the response should be code "FORBIDDEN".

Do you currently store scopes as a claim inside the JWT, or do you fetch them from a database during validation? Knowing this will help fine‑tune the buildContext middleware.