suaveplan/openspec/archive/2026-05-26-api-tenant-resolver-header/proposal.md

@suaveplan/api-tenant-resolver-header — header-based tenant resolver

Package: @suaveplan/api-tenant-resolver-header Status: PROPOSED Type: new-package Stage: 8 — see umbrella openspec/changes/api-plugin-foundation/

Why

Per design doc §6 step 4, the per-request pipeline runs a tenant resolver chain — first the principal's tenantId, then fallback resolvers. Service-to-service traffic frequently carries the tenant in an HTTP header (X-Tenant-Id, X-Acme-Tenant, etc.) because no end-user session exists to resolve it from. This adapter handles that case.

What changes

• ADDED: createHeaderTenantResolver({ headerName, validate, registry }) — implements the TenantResolver contract from api-types. Reads headerName (default X-Tenant-Id); validates the value via the supplied validate function (default: must match ^[a-z0-9-]{1,64}$) AND optionally checks membership in tenant.provider's registry; resolves to { tenantId, source: "header" } or null.
• ADDED: Strict mode — when strict: true (host config), a value that fails validation raises TENANT_HEADER_INVALID (HTTP 400). When strict: false, invalid values cause the resolver to return null so a downstream resolver may match.
• ADDED: Trusted-source enforcement — trustedSources config (default: ["service-mesh"]) lists which traffic sources are allowed to set the header. The resolver consults request.metadata.source (set by upstream middleware); if the source is not trusted, the header is ignored. This prevents end-user clients from spoofing the tenant.
• ADDED: Conformance — passes runTenantResolverConformance from api-tenant-provider/testing.
• ADDED: Error codes (TENANT_HEADER_*): INVALID, NOT_FOUND_IN_REGISTRY, UNTRUSTED_SOURCE.

Out of scope

• The trusted-source metadata itself — set by the router adapter when traffic enters from a service mesh / mTLS-verified ingress.
• Resolving multiple tenants (multi-tenant batch operations) — outside the per-request model.

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	§6 step 4
Service-to-service tenant injection	§6 step 4

Verification approach

• src/resolver/resolver.test.ts — valid header → tenantId; invalid + strict → 400; invalid + non-strict → null; missing header → null.
• src/trust/trust.test.ts — untrusted source ignored even when header is well-formed; trusted source resolves.
• src/resolver/resolver.spec-conformance.test.ts — runs runTenantResolverConformance.
• tests/dep-graph.test.ts — runtime deps.

Migration impact

None — additive only. api-host wires this into the tenant-resolver chain when host.tenant.resolvers includes "header".