Skip to content

docs: describe JWKS_KID as the service token kid, not the signing key id - #269

Merged
Bccorb merged 1 commit into
mainfrom
docs/jwks-kid-meaning
Oct 13, 2026
Merged

Bccorb merged 1 commit into
mainfrom
docs/jwks-kid-meaning

Conversation

@Bccorb

@Bccorb Bccorb commented Oct 13, 2026

Copy link
Copy Markdown
Contributor

Summary

Several CLI strings described JWKS_KID as the auth server's signing key id, or said the adapter must match the API's active kid. It is the kid header on the HS256 service tokens the adapter signs with API_SERVICE_TOKEN, and the auth API never checks it.

How JWKS_KID is actually used (checked against origin/main):

  • seamless-auth-server packages/core/src/createServiceToken.ts:27-31: adapters sign service tokens with serviceSecret (API_SERVICE_TOKEN), algorithm: "HS256", keyid: opts.keyId. jwksKid is that keyId (packages/core/src/apiContract.ts:62, packages/express/src/createServer.ts:252,345, packages/nextjs/src/handler.ts:58), defaulting to DEV_JWKS_KID = "dev-main" (apiContract.ts:31-36).
  • seamless-auth-api src/middleware/authenticateServiceToken.ts:45,70-72: the API verifies service tokens with jwt.verify(token, API_SERVICE_TOKEN, { algorithms: HS256/384/512 }) and only checks iss/aud afterwards (src/middleware/trustedClientContext.ts:85, src/lib/externalDelivery.ts:70). It never reads the kid header, and no API env var or setting has to match it (the API source has no JWKS_KID).
  • The auth server's own RS256 signing key id is a different value: ${prefix}_ACTIVE_KID in src/utils/signingKeyStore.ts:156, published at /.well-known/jwks.json. Adapters find that key from the access token header, not from JWKS_KID.

So JWKS_KID is a label on the adapter's HS256 service tokens. The adapters warn on boot while it is unset or dev-main; nothing else depends on its value.

Changes

  • src/core/managedConnect.ts: the fallback warning said "your adapter will warn on boot until it matches". The adapter warns only while the value is unset or dev-main, so the message now says that, and that the auth server does not check JWKS_KID. The comment above FALLBACK_JWKS_KID is corrected the same way. Behavior is unchanged: a managed scaffold still writes the instance's active key id, which keeps the adapter's warning quiet.
  • src/commands/helpTopics.ts (seamless help add) and README.md: "signing key id" becomes "service token kid".
  • verify/docker-compose.verify.yml: the header comment said JWKS_KID must match the API's active kid.
  • src/commands/init.test.ts: assertion follows the new wording.
  • Patch changeset, since user-facing text in src changed.

verify/CONFORMANCE.md already described it correctly. docs/ has no mention.

Checks

  • npm run build (tsc): pass
  • npm test: 1274 passed, 4 skipped; npm run coverage (pre-commit) passes thresholds

@Bccorb
Bccorb merged commit 7089e5c into main Oct 13, 2026
5 checks passed
@Bccorb
Bccorb deleted the docs/jwks-kid-meaning branch October 13, 2026 00:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant