# `@suaveplan/api-tenant-resolver-jwt` — Principal-derived tenant resolver

**Package**: `@suaveplan/api-tenant-resolver-jwt`
**Status**: PROPOSED
**Type**: new-package
**Stage**: 4 (Base adapters) — see umbrella `openspec/changes/api-plugin-foundation/`

## Why

Per design doc §6 step 4, the tenant resolver chain runs after the session resolver. When the session is a JWT carrying `tenant_id` (or `tid`), the tenant resolver's job is trivial: read `ctx.principal.tenantId`. Collapsing this into a dedicated adapter — rather than encoding it inside `api-auth-jwt` — keeps the two contracts orthogonal and lets operators chain it with header- or subdomain-based resolvers (Stage 8) for paths the JWT doesn't cover.

When paired with `api-auth-jwt`, this resolver effectively degenerates to an identity read; its presence makes the data-flow explicit and lets the conformance suite test the empty/missing-tenant edge cases uniformly.

Stage 4 invariant: both direct and worker-proxy surfaces ship; both pass `runTenantResolverConformance` (§5.2a, §13.4).

## What changes

Net-new package depending on `@suaveplan/api-tenant-resolver` (contract), `@suaveplan/api-types`, `@suaveplan/api-worker-rpc`, `@suaveplan/error`, `zod`.

- ADDED: `createJwtTenantResolver(opts)` — direct surface returning a `TenantResolver`. Reads `ctx.principal.tenantId`; returns it if present, otherwise returns the chain-sentinel `undefined` (so the next resolver in the chain runs).
- ADDED: `createJwtTenantResolverWorkerProxy(port, opts)` — proxy surface.
- ADDED: `JwtTenantResolverOptions` — Zod schema with `requirePrincipal: boolean` (default false; if true, throws `TENANT_JWT_PRINCIPAL_REQUIRED` when principal is null) and `mode: "identity" | "claim-fallback"` (default `"identity"`).
- ADDED: `TENANT_JWT_*` error codes (`TENANT_JWT_PRINCIPAL_REQUIRED`, `TENANT_JWT_INVALID_OPTIONS`).

## Out of scope

- Reading tenant from arbitrary JWT claims independent of `Principal` projection — that responsibility belongs to `api-auth-jwt`'s `claimToPrincipal` mapping.
- Header- or subdomain-based resolution — `api-tenant-resolver-header` and `api-tenant-resolver-subdomain` (Stage 8).
- Tenant enumeration (for `perTenant: true` jobs) — `api-tenant-provider-memory` (this stage).

## Source mapping

Genesis-original. Source of design intent: `docs/superpowers/specs/2026-05-13-api-plugin-foundation-design.md`.

| Requirement | Design doc section |
|---|---|
| Tenant resolver chain step 4 | §6 |
| First match wins; sentinel for chain advance | §6 |
| Worker-proxy variant required | §5.2a |
| Conformance both surfaces | §13.4 |

## Verification approach

- `src/factory/create-jwt-tenant-resolver.test.ts` — principal with tenantId → returns it; principal without tenantId → returns `undefined` (advance chain); null principal → `undefined` unless `requirePrincipal: true` (throws).
- `src/factory/create-jwt-tenant-resolver.spec-conformance.test.ts` — `runTenantResolverConformance("jwt-direct", ...)`.
- `src/proxy/create-jwt-tenant-resolver-worker-proxy.test.ts` — proxy unit tests.
- `src/proxy/create-jwt-tenant-resolver-worker-proxy.spec-conformance.test.ts` — `runTenantResolverConformance("jwt-worker-proxy", ...)`.

## Migration impact

None — additive only.