Repository navigation
docs: describe JWKS_KID as the service token kid, not the signing key id - #269
Merged
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Several CLI strings described
JWKS_KIDas the auth server's signing key id, or said the adapter must match the API's active kid. It is thekidheader on the HS256 service tokens the adapter signs withAPI_SERVICE_TOKEN, and the auth API never checks it.How
JWKS_KIDis actually used (checked against origin/main):packages/core/src/createServiceToken.ts:27-31: adapters sign service tokens withserviceSecret(API_SERVICE_TOKEN),algorithm: "HS256",keyid: opts.keyId.jwksKidis thatkeyId(packages/core/src/apiContract.ts:62,packages/express/src/createServer.ts:252,345,packages/nextjs/src/handler.ts:58), defaulting toDEV_JWKS_KID = "dev-main"(apiContract.ts:31-36).src/middleware/authenticateServiceToken.ts:45,70-72: the API verifies service tokens withjwt.verify(token, API_SERVICE_TOKEN, { algorithms: HS256/384/512 })and only checksiss/audafterwards (src/middleware/trustedClientContext.ts:85,src/lib/externalDelivery.ts:70). It never reads thekidheader, and no API env var or setting has to match it (the API source has noJWKS_KID).${prefix}_ACTIVE_KIDinsrc/utils/signingKeyStore.ts:156, published at/.well-known/jwks.json. Adapters find that key from the access token header, not fromJWKS_KID.So
JWKS_KIDis a label on the adapter's HS256 service tokens. The adapters warn on boot while it is unset ordev-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 ordev-main, so the message now says that, and that the auth server does not checkJWKS_KID. The comment aboveFALLBACK_JWKS_KIDis 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) andREADME.md: "signing key id" becomes "service token kid".verify/docker-compose.verify.yml: the header comment saidJWKS_KIDmust match the API's active kid.src/commands/init.test.ts: assertion follows the new wording.srcchanged.verify/CONFORMANCE.mdalready described it correctly.docs/has no mention.Checks
npm run build(tsc): passnpm test: 1274 passed, 4 skipped;npm run coverage(pre-commit) passes thresholds