feat!: per-flow PKCE verifier cookies + pure URL helpers (0.5.0)

[nicknisi]

Summary

• Per-flow PKCE verifier cookies: wos-auth-verifier-<fnv1a>, with suffix derived from the sealed state. Concurrent sign-ins from multiple tabs no longer clobber each other.
• Breaking: clearPendingVerifier(response, { state }) — state is now required to identify the per-flow cookie. Guard the call on state presence; skip it when the callback URL is malformed (10-min TTL cleans up orphans).
• Breaking: CreateAuthorizationResult gains a required cookieName: string field.
• PKCE_COOKIE_PREFIX and getPKCECookieNameForState are exported from the package root for cookie introspection.

Why the hash is safe

FNV-1a 32-bit is a namespacing mechanism, not a security primitive. Integrity of the sealed blob comes from AEAD in SessionEncryption, and verifyCallbackState still does a constant-time byte comparison of the full state. Collision probability is ~n²/2³² (vanishingly small even with 50 concurrent flows); a collision fails closed via state mismatch.

Dropped before merge

An earlier draft added getAuthorizationUrl / getSignInUrl / getSignUpUrl — pure variants that returned { url, cookieName } without writing a cookie. Removed after review: no concrete consumer, and using them for a document-request redirect silently produces a broken callback with no surfaced sealedState to recover with. The motivating "non-document requests in middleware" case is better solved by calling createSignIn only on the actual sign-in route. Can be reintroduced later with a better-signalled API if a real caller materializes.

Test plan

• vitest run — 215/215 passing
• tsc --noEmit clean
• New cookieName.spec.ts with known-answer FNV-1a vectors (empty string, a, foobar)
• Concurrent-flow isolation: callback for flow A does not touch flow B's cookie
• Tampered-cookie, missing-cookie, scheme-agnostic delete, and redirectUri-override cases all rewired under derived names
• Verified neither authkit-tanstack-start (0.4.0 dep) nor authkit-sveltekit (^0.4.0 dep) consume the dropped pure helpers — name collisions in those adapters are independent wrappers around createSignIn / createSignUp
• Smoke-test one downstream adapter on the breaking clearPendingVerifier call site before release

[greptile-apps]

Greptile Summary

This PR replaces the single static wos-auth-verifier PKCE verifier cookie with per-flow cookies suffixed by an FNV-1a 32-bit hash of the sealed state (wos-auth-verifier-<fnv1a>), so concurrent sign-ins from multiple tabs no longer clobber each other. The breaking changes — clearPendingVerifier now requires options.state, and CreateAuthorizationResult gains a required cookieName field — are clearly documented in MIGRATION.md with before/after examples.

The implementation is consistent end-to-end: generateAuthorizationUrl derives the name from sealedState, handleCallback re-derives it from the callback URL's state parameter (same sealed blob), and clearPendingVerifier follows the same derivation. Absent-state paths (cookieName = null) correctly skip cookie I/O and rely on the 10-minute TTL, which is the right fail-safe. The pure URL helpers flagged in a prior review were dropped before merge.

Confidence Score: 5/5

Safe to merge — no P0/P1 findings; all changed paths are covered by 215 passing tests including concurrent-flow isolation, tamper, missing-cookie, scheme-agnostic delete, and redirectUri-override scenarios.

All remaining findings are at most P2. The hash derivation is correct (verified by known-answer vectors), the cookie read/write/clear paths are consistent, null-guarded absent-state paths are intentional, and the breaking changes are thoroughly documented. The prior concern about pure URL helpers is resolved by their removal.

No files require special attention.

Important Files Changed

Filename	Overview
src/core/pkce/cookieName.ts	New module introducing FNV-1a 32-bit hash and per-flow cookie name derivation; implementation is correct and verified against known-answer vectors.
src/core/pkce/generateAuthorizationUrl.ts	Derives cookieName from sealedState via getPKCECookieNameForState and threads it through the size check, serialization, and return value; logic is sound.
src/service/AuthService.ts	Correctly plumbs per-flow cookieName through createAuthorization, handleCallback, and clearPendingVerifier; null-guarded paths (absent state) are intentional and correctly fall back to TTL cleanup.
src/core/session/types.ts	Flattens GetAuthorizationUrlResult into CreateAuthorizationResult and adds required cookieName: string; breaking change is well-documented in MIGRATION.md.
src/index.ts	Exports PKCE_COOKIE_PREFIX and getPKCECookieNameForState for downstream adapter introspection; PKCE_COOKIE_NAME correctly removed as a public export.
src/core/pkce/cookieName.spec.ts	Thorough known-answer tests for FNV-1a 32-bit (empty string offset basis, single char, multi-char) plus determinism and prefix-constant checks.
src/service/AuthService.spec.ts	Comprehensive test updates: per-flow cookie isolation, concurrent flow non-interference, tampered/missing cookie scenarios, scheme-agnostic delete, and redirectUri threading all rewired to derived cookie names.
src/core/pkce/cookieOptions.ts	Removes the static PKCE_COOKIE_NAME export; the cookie-options helper itself is unchanged.
MIGRATION.md	Well-structured 0.5.0 migration section covering the state-required clearPendingVerifier change, removed exports, and updated firewall/proxy checklist.

_{Reviews (5): Last reviewed commit: "chore: drop PKCE_COOKIE_NAME and GetAuth..." | Re-trigger Greptile}