feat(transport): bearer transport on the auth routes and POST /refresh - #164
Merged
Merged
Conversation
requireAuth and getSeamlessUser read req.cookies and nothing else, so a native client, which has no cookie jar and holds the auth API's own tokens, was rejected on every request to an adopter's routes. requireAuth takes an optional authServerUrl + audience pair. With both set it also accepts Authorization: Bearer <access token>, verified against the auth API's JWKS and required to carry typ "access", so a sign-in flow's ephemeral token is refused even though the same key signs it. The cookie wins when both are present, and leaving the pair out keeps the guard cookie-only. getSeamlessUser resolves a bearer session too. The router options already carry the audience, so a request with no cookie but a valid bearer token is verified the same way and forwarded to GET /users/me, while a request with neither, or a token that fails verification, returns null without an upstream call. Core exports verifyAccessToken, extractBearerToken, authenticateBearer and authenticateRequest. The JWKS memo moves to a shared module so both verifiers share one instance per auth server. Fastify gains direct guard tests, which it had only through the parity suite. Refs #147.
jose skips the claim check for an empty expected value, so a blank audience would have verified against any audience. verifyAccessToken returns null for an empty issuer or audience, and requireAuth refuses the pair at setup.
…/refresh Every proxied route assumed cookies: identity came from the cookie payload, session responses were stripped of their tokens and minted into cookies, and silent refresh ran on the refresh cookie. A native app has no cookie jar, so it could not sign in through the adapter, and going around it to the auth API would bypass message delivery, client IP forwarding and the service token. A request carrying x-seamless-auth-transport: bearer gets a bearer contract on the same routes. The client presents the token a route needs in Authorization and the adapter forwards it as-is. Session-issuing responses come back whole, tokens included, with no Set-Cookie, and the access token's signature is still verified before the body goes out. ensureCookies is skipped. Requests without the header are served exactly as before. POST /refresh is new in both adapters. In bearer transport it rotates from Authorization: Bearer <refreshToken> and passes the auth API's failure body through, collapsing concurrent rotations of one token into a single upstream call. In cookie transport it rotates the refresh cookie into fresh cookies. Closes #163.
Bccorb
force-pushed
the
feat/bearer-transport
branch
from
September 13, 2026 02:09
a079271 to
3b640cd
Compare
4 tasks
This was referenced Sep 13, 2026
Merged
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
Stacked on #162 (merge that first; this PR's base will then be retargeted to
main). Closes #163. Part of the mobile track fells-code/seamless-templates#40.Every proxied
/auth/*route assumed cookies. A native client has no cookie jar, so it could not sign in through the adapter, and going around it to the auth API directly would bypass message delivery (adopter templates), client IP / user agent forwarding, and the service token, and would need the auth API exposed.A request that carries
x-seamless-auth-transport: bearernow gets a bearer contract on the same routes:Authorization: Bearer(the ephemeral token/loginor/registration/registerreturned on pre-auth routes, the access token on access routes). The adapter forwards it to the auth API as-is; the auth API decides whether it is the right kind for the route.tokenandrefreshTokenincluded, with noSet-Cookie. The auth API's RS256 signature on the access token is still verified before the body goes out (sessionResult).ensureCookiesis skipped. A route that needs an identity and gets no bearer token answers 401 with the same error a missing cookie gets.Authorization, selects the transport, because the first request of a flow carries no token in either. Requests without the header are served exactly as before (the whole existing suite passes untouched).POST /refreshis new in both adapters:Authorization: Bearer <refreshToken>in, rotated pair out. The auth API's failure body passes through so a client can tellrefresh_token_reused(chain revoked, sign in again) from a transient error. Concurrent rotations of the same token are collapsed into one upstream call and a straggler within 5s gets the same pair, since the auth API treats a replayed refresh token as theft.refreshAccessTokendedupe.Core surface
AuthTransport,resolveAuthTransport,AUTH_TRANSPORT_HEADER,BEARER_TRANSPORT,sessionResult,transportoption onloginHandler,registerHandler,finishLoginHandler, OTP verify handlers,pollMagicLinkConfirmationHandler,switchOrganizationHandler,finishOAuthLoginHandler;transport+authorizationoncheckProxyIdentity;transportonapplyResult;refreshBearerSession;refreshHandler.Security notes
originGuardis unchanged; it is inert for native clients (noOrigin/Sec-Fetch-Site).Test plan
pnpm -r test: core 304, express 183, fastify 100 passingcore/tests/transport.test.js(transport resolution, identity check,applyResult,sessionResult,refreshBearerSessiondedupe and failure passthrough),fastify/tests/bearerTransport.parity.test.js(full bearer sign-in through both adapters: login, OTP verify, me, refresh, reuse failure, logout, proxied route, cookie jar untouched; both adapters held to the same answer),express/tests/refreshRoute.test.js(cookie-mode/refresh)Follow-ups
@seamless-auth/clientbearer transport in the React SDK monorepo consumes this contract.seamless-templatesAPI starters passauthServerUrl/audienceintorequireAuth.