@bojanrajkovic/mcp-paprika 1.2.0-beta.2 → 1.2.0-beta.3

package/dist/auth/build.d.ts

@@ -9,7 +9,8 @@
  * Called once per process from buildAppContext (src/server/build.ts)
  * after cache.init() completes.
  */
+import type { Logger } from "pino";
 import type { DiskCache } from "../cache/disk-cache.js";
 import type { PaprikaConfig } from "../utils/config.js";
 import type { AuthContext } from "./types.js";
-export declare function buildAuthContext(config: PaprikaConfig, cache: DiskCache): Promise<AuthContext | null>;
+export declare function buildAuthContext(config: PaprikaConfig, cache: DiskCache, parentLog: Logger): Promise<AuthContext | null>;

package/dist/auth/build.js

@@ -18,7 +18,7 @@ import { AuthCodeStore } from "./auth-code-store.js";
 import { MintingOAuthServerProvider } from "./provider.js";
 import { AuthCleanup } from "./cleanup.js";
 import { MAX_REGISTERED_CLIENTS } from "./routes.js";
-export async function buildAuthContext(config, cache) {
+export async function buildAuthContext(config, cache, parentLog) {
     if (config.transport !== "http")
         return null;
     if (config.oauth === undefined) {
@@ -61,15 +61,17 @@ export async function buildAuthContext(config, cache) {
         trustProxy: config.oauth.trustProxy,
         allowlist: config.oauth.allowlist,
     };
+    const authLog = parentLog.child({ component: "auth" });
+    const oidcClientLog = parentLog.child({ component: "oidc-client" });
     // Fetch + validate upstream discovery document (rejects http:// endpoints; checks alg overlap)
-    const discovery = await loadDiscovery(resolved.discoveryUrl, resolved.allowedAlgs);
+    const discovery = await loadDiscovery(resolved.discoveryUrl, resolved.allowedAlgs, oidcClientLog);
     const jwks = createJwksFor(discovery);
-    const clientStore = new DiskClientRegistrationStore(cache, resolved.publicUrl, MAX_REGISTERED_CLIENTS);
+    const clientStore = new DiskClientRegistrationStore(cache, resolved.publicUrl, authLog, MAX_REGISTERED_CLIENTS);
     const tokenStore = new TokenStore(cache);
     const requestStore = new AuthRequestStore();
     const codeStore = new AuthCodeStore();
-    const provider = new MintingOAuthServerProvider(clientStore, tokenStore, requestStore, codeStore, discovery, resolved, resolved.publicUrl);
-    const cleanup = new AuthCleanup(clientStore, tokenStore, cache, requestStore, codeStore);
+    const provider = new MintingOAuthServerProvider(clientStore, tokenStore, requestStore, codeStore, discovery, resolved, resolved.publicUrl, authLog);
+    const cleanup = new AuthCleanup(clientStore, tokenStore, cache, requestStore, codeStore, authLog);
     return {
         provider,
         config: resolved,
@@ -80,5 +82,9 @@ export async function buildAuthContext(config, cache) {
         tokenStore,
         clientStore,
         cleanup,
+        log: {
+            auth: authLog,
+            oidcClient: oidcClientLog,
+        },
     };
 }

package/dist/auth/cleanup.d.ts

@@ -15,6 +15,7 @@
  *
  * Public `sweepOnce()` is exposed for direct testing and for startup use.
  */
+import type { Logger } from "pino";
 import type { DiskCache } from "../cache/disk-cache.js";
 import type { AuthRequestStore } from "./auth-request-store.js";
 import type { AuthCodeStore } from "./auth-code-store.js";
@@ -26,10 +27,11 @@ export declare class AuthCleanup {
     private readonly _cache;
     private readonly _authRequests;
     private readonly _authCodes;
+    private readonly log;
     private readonly _now;
     private readonly _intervalMs;
     private _ac;
-    constructor(_clientStore: DiskClientRegistrationStore, _tokenStore: TokenStore, _cache: DiskCache, _authRequests: AuthRequestStore, _authCodes: AuthCodeStore, _now?: () => number, _intervalMs?: number);
+    constructor(_clientStore: DiskClientRegistrationStore, _tokenStore: TokenStore, _cache: DiskCache, _authRequests: AuthRequestStore, _authCodes: AuthCodeStore, log: Logger, _now?: () => number, _intervalMs?: number);
     /** Start the background cleanup loop. Idempotent — second call is a no-op. */
     start(): void;
     /** Stop the background cleanup loop. Idempotent — second call is a no-op. */

package/dist/auth/cleanup.js

@@ -24,15 +24,17 @@ export class AuthCleanup {
     _cache;
     _authRequests;
     _authCodes;
+    log;
     _now;
     _intervalMs;
     _ac = null;
-    constructor(_clientStore, _tokenStore, _cache, _authRequests, _authCodes, _now = () => nowSeconds(), _intervalMs = CLEANUP_INTERVAL_MS) {
+    constructor(_clientStore, _tokenStore, _cache, _authRequests, _authCodes, log, _now = () => nowSeconds(), _intervalMs = CLEANUP_INTERVAL_MS) {
         this._clientStore = _clientStore;
         this._tokenStore = _tokenStore;
         this._cache = _cache;
         this._authRequests = _authRequests;
         this._authCodes = _authCodes;
+        this.log = log;
         this._now = _now;
         this._intervalMs = _intervalMs;
     }
@@ -112,14 +114,16 @@ export class AuthCleanup {
             try {
                 await this.sweepOnce();
             }
-            catch {
-                // Never throws — loop must not crash on transient cache errors
+            catch (err) {
+                this.log.debug({ err }, "auth cleanup sweep failed; continuing");
             }
             try {
                 await wait(this._intervalMs, undefined, { signal: this._ac.signal });
             }
-            catch {
-                // AbortError from stop() — exit loop cleanly
+            catch (err) {
+                if (!(err instanceof Error && err.name === "AbortError")) {
+                    this.log.debug({ err }, "auth cleanup wait failed unexpectedly");
+                }
                 return;
             }
         }

package/dist/auth/client-registration.d.ts

@@ -9,6 +9,7 @@
  * - deleteClient: DELETE /register/{client_id} — removes from disk (cascade handled by caller)
  * - verifyRegistrationAccessToken: used by route handlers to gate PUT/DELETE access
  */
+import type { Logger } from "pino";
 import { DiskCache } from "../cache/disk-cache.js";
 /**
  * Wire format for client information (RFC 7591 response format).
@@ -30,6 +31,7 @@ interface OAuthClientInformationFull {
 export declare class DiskClientRegistrationStore {
     private readonly _cache;
     private readonly _publicUrl;
+    private readonly log;
     /**
      * Hard cap on the number of registered clients. Enforced atomically
      * inside `registerClient` (via `DiskCache.tryPutOAuthClient`) so concurrent
@@ -39,7 +41,7 @@ export declare class DiskClientRegistrationStore {
      * middleware's fast-path 429 limit).
      */
     private readonly _maxClients;
-    constructor(_cache: DiskCache, _publicUrl: string, 
+    constructor(_cache: DiskCache, _publicUrl: string, log: Logger, 
     /**
      * Hard cap on the number of registered clients. Enforced atomically
      * inside `registerClient` (via `DiskCache.tryPutOAuthClient`) so concurrent

package/dist/auth/client-registration.js

@@ -41,8 +41,9 @@ function storedToWire(stored, extras) {
 export class DiskClientRegistrationStore {
     _cache;
     _publicUrl;
+    log;
     _maxClients;
-    constructor(_cache, _publicUrl, 
+    constructor(_cache, _publicUrl, log, 
     /**
      * Hard cap on the number of registered clients. Enforced atomically
      * inside `registerClient` (via `DiskCache.tryPutOAuthClient`) so concurrent
@@ -54,6 +55,7 @@ export class DiskClientRegistrationStore {
     _maxClients = Number.POSITIVE_INFINITY) {
         this._cache = _cache;
         this._publicUrl = _publicUrl;
+        this.log = log;
         this._maxClients = _maxClients;
     }
     /**
@@ -72,8 +74,8 @@ export class DiskClientRegistrationStore {
      * Throws OAuthMetadataValidationError on invalid metadata.
      */
     async registerClient(metaIn) {
-        // Validate via dcr-validator; match() usage per FCIS + project neverthrow rules
-        const validated = validateRegistration(metaIn).match((v) => v, (e) => {
+        // Validate via dcr-validator; pass logger for URL-parse debug diagnosability
+        const validated = validateRegistration(metaIn, this.log).match((v) => v, (e) => {
             throw e;
         });
         const clientId = randomUUID();
@@ -104,6 +106,7 @@ export class DiskClientRegistrationStore {
             throw new InvalidRequestError(`client registration cap reached (${result.currentCount.toString()} clients)`);
         }
         await this._cache.flush();
+        this.log.info({ clientId: stored.clientId, redirectUriCount: stored.redirectUris.length }, "client registered via DCR");
         return storedToWire(stored, {
             registrationAccessToken,
             registrationClientUri: `${this._publicUrl}/register/${clientId}`,
@@ -120,8 +123,8 @@ export class DiskClientRegistrationStore {
         const existing = await this._cache.getOAuthClient(clientId);
         if (existing === null)
             throw OAuthClientNotFoundError.forId(clientId);
-        // Validate patch via dcr-validator
-        const validated = validateUpdate(metaIn).match((v) => v, (e) => {
+        // Validate patch via dcr-validator; pass logger for URL-parse debug diagnosability
+        const validated = validateUpdate(metaIn, this.log).match((v) => v, (e) => {
             throw e;
         });
         const now = nowSeconds();
@@ -168,8 +171,8 @@ export class DiskClientRegistrationStore {
         try {
             return timingSafeEqual(Buffer.from(presentedHash, "hex"), Buffer.from(storedHash, "hex"));
         }
-        catch {
-            // If buffer conversion fails (invalid hex), return false
+        catch (err) {
+            this.log.debug({ err, clientId }, "RAT timing-safe equality failed (likely invalid hex)");
             return false;
         }
     }

package/dist/auth/dcr-validator.d.ts

@@ -10,6 +10,7 @@
  * - scope preserved but non-empty
  */
 import type { Result } from "neverthrow";
+import type { Logger } from "pino";
 import { OAuthMetadataValidationError } from "./errors.js";
 export interface ValidatedClientMetadata {
     readonly tokenEndpointAuthMethod: "none";
@@ -36,12 +37,18 @@ export interface ValidatedClientMetadataPatch {
  * grant_types defaults to ["authorization_code", "refresh_token"].
  * response_types defaults to ["code"].
  * scope defaults to empty string.
+ *
+ * @param log — optional logger; when provided, URL parse failures on redirect_uris
+ *   emit debug records for diagnosability in production.
  */
-export declare function validateRegistration(meta: unknown): Result<ValidatedClientMetadata, OAuthMetadataValidationError>;
+export declare function validateRegistration(meta: unknown, log?: Logger): Result<ValidatedClientMetadata, OAuthMetadataValidationError>;
 /**
  * Validates client metadata for RFC 7592 updates.
  * All fields are optional (partial updates per RFC 7592 §2.2).
  * Present fields pass the same validation as registration.
  * Omitted fields are NOT synthesized in the output (unlike registration).
+ *
+ * @param log — optional logger; when provided, URL parse failures on redirect_uris
+ *   emit debug records for diagnosability in production.
  */
-export declare function validateUpdate(meta: unknown): Result<ValidatedClientMetadataPatch, OAuthMetadataValidationError>;
+export declare function validateUpdate(meta: unknown, log?: Logger): Result<ValidatedClientMetadataPatch, OAuthMetadataValidationError>;

package/dist/auth/dcr-validator.js

@@ -16,7 +16,7 @@ import { OAuthMetadataValidationError } from "./errors.js";
 // Validation Logic
 // ============================================================================
 // Helper: validate redirect URI scheme and hostname
-function isValidRedirectUri(uri) {
+function isValidRedirectUri(uri, log) {
     try {
         const url = new URL(uri);
         // https is always OK
@@ -33,7 +33,8 @@ function isValidRedirectUri(uri) {
         }
         return false;
     }
-    catch {
+    catch (err) {
+        log?.debug({ err, uri }, "invalid redirect_uri rejected by parser");
         return false;
     }
 }
@@ -48,7 +49,7 @@ const ClientMetadataFieldsSchema = z.object({
     id_token_signed_response_alg: z.enum(["RS256", "ES256"]).optional(),
 });
 // Shared helper: validate each redirect URI item in a non-empty array
-function validateRedirectUriItems(uris, ctx) {
+function validateRedirectUriItems(uris, ctx, log) {
     for (let i = 0; i < uris.length; i++) {
         const uri = uris[i];
         if (typeof uri !== "string") {
@@ -62,7 +63,8 @@ function validateRedirectUriItems(uris, ctx) {
             try {
                 new URL(uri);
             }
-            catch {
+            catch (err) {
+                log?.debug({ err, uri, index: i }, "invalid redirect_uri item in DCR request");
                 ctx.addIssue({
                     code: z.ZodIssueCode.custom,
                     path: ["redirect_uris", i],
@@ -70,7 +72,7 @@ function validateRedirectUriItems(uris, ctx) {
                 });
                 continue;
             }
-            if (!isValidRedirectUri(uri)) {
+            if (!isValidRedirectUri(uri, log)) {
                 ctx.addIssue({
                     code: z.ZodIssueCode.custom,
                     path: ["redirect_uris", i],
@@ -103,42 +105,48 @@ function validateGrantTypes(data, ctx) {
         }
     }
 }
-// Schema for validateRegistration: redirect_uris REQUIRED (must be present and non-empty)
-const RegistrationMetadataSchema = ClientMetadataFieldsSchema.passthrough() // Allow and preserve other RFC 7591 fields
-    .superRefine((data, ctx) => {
-    // Validate redirect_uris: must be present, non-empty, valid URLs with our scheme rules
-    if (!Array.isArray(data.redirect_uris) || data.redirect_uris.length === 0) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ["redirect_uris"],
-            message: "redirect_uris is required and must be a non-empty array of valid URLs",
-        });
-    }
-    else {
-        validateRedirectUriItems(data.redirect_uris, ctx);
-    }
-    validateResponseTypes(data, ctx);
-    validateGrantTypes(data, ctx);
-});
-// Schema for validateUpdate: redirect_uris OPTIONAL (whole block skipped when absent)
-const UpdateMetadataSchema = ClientMetadataFieldsSchema.passthrough() // Allow and preserve other RFC 7591 fields
-    .superRefine((data, ctx) => {
-    // Validate redirect_uris if present: must be non-empty with valid scheme
-    if (data.redirect_uris !== undefined) {
+// Schema factory for validateRegistration: redirect_uris REQUIRED (must be present and non-empty).
+// Accepts an optional logger to emit debug records on URL parse failures.
+function makeRegistrationSchema(log) {
+    return ClientMetadataFieldsSchema.passthrough() // Allow and preserve other RFC 7591 fields
+        .superRefine((data, ctx) => {
+        // Validate redirect_uris: must be present, non-empty, valid URLs with our scheme rules
         if (!Array.isArray(data.redirect_uris) || data.redirect_uris.length === 0) {
             ctx.addIssue({
                 code: z.ZodIssueCode.custom,
                 path: ["redirect_uris"],
-                message: "redirect_uris must be a non-empty array when present",
+                message: "redirect_uris is required and must be a non-empty array of valid URLs",
             });
         }
         else {
-            validateRedirectUriItems(data.redirect_uris, ctx);
+            validateRedirectUriItems(data.redirect_uris, ctx, log);
         }
-    }
-    validateResponseTypes(data, ctx);
-    validateGrantTypes(data, ctx);
-});
+        validateResponseTypes(data, ctx);
+        validateGrantTypes(data, ctx);
+    });
+}
+// Schema factory for validateUpdate: redirect_uris OPTIONAL (whole block skipped when absent).
+// Accepts an optional logger to emit debug records on URL parse failures.
+function makeUpdateSchema(log) {
+    return ClientMetadataFieldsSchema.passthrough() // Allow and preserve other RFC 7591 fields
+        .superRefine((data, ctx) => {
+        // Validate redirect_uris if present: must be non-empty with valid scheme
+        if (data.redirect_uris !== undefined) {
+            if (!Array.isArray(data.redirect_uris) || data.redirect_uris.length === 0) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["redirect_uris"],
+                    message: "redirect_uris must be a non-empty array when present",
+                });
+            }
+            else {
+                validateRedirectUriItems(data.redirect_uris, ctx, log);
+            }
+        }
+        validateResponseTypes(data, ctx);
+        validateGrantTypes(data, ctx);
+    });
+}
 // Helper: convert parsed data to ValidatedClientMetadata with defaults for registration
 function buildRegistrationMetadata(data) {
     return {
@@ -191,10 +199,13 @@ function buildUpdateMetadataPatch(data) {
  * grant_types defaults to ["authorization_code", "refresh_token"].
  * response_types defaults to ["code"].
  * scope defaults to empty string.
+ *
+ * @param log — optional logger; when provided, URL parse failures on redirect_uris
+ *   emit debug records for diagnosability in production.
  */
-export function validateRegistration(meta) {
+export function validateRegistration(meta, log) {
     // Parse with Zod schema (includes field validation and redirect_uri scheme checks)
-    const parseResult = RegistrationMetadataSchema.safeParse(meta);
+    const parseResult = makeRegistrationSchema(log).safeParse(meta);
     if (!parseResult.success) {
         // Translate first Zod error to OAuth error
         const issue = parseResult.error.issues[0];
@@ -213,10 +224,13 @@ export function validateRegistration(meta) {
  * All fields are optional (partial updates per RFC 7592 §2.2).
  * Present fields pass the same validation as registration.
  * Omitted fields are NOT synthesized in the output (unlike registration).
+ *
+ * @param log — optional logger; when provided, URL parse failures on redirect_uris
+ *   emit debug records for diagnosability in production.
  */
-export function validateUpdate(meta) {
+export function validateUpdate(meta, log) {
     // Parse with Zod schema (includes field validation and redirect_uri scheme checks)
-    const parseResult = UpdateMetadataSchema.safeParse(meta);
+    const parseResult = makeUpdateSchema(log).safeParse(meta);
     if (!parseResult.success) {
         // Translate first Zod error to OAuth error
         const issue = parseResult.error.issues[0];

package/dist/auth/oidc-client.d.ts

@@ -9,6 +9,7 @@
  * `loadDiscovery` is one-shot (no caching); `verifyIdToken` uses jose's built-in JWKS cache.
  */
 import { z } from "zod";
+import type { Logger } from "pino";
 import { type JWTVerifyGetKey } from "jose";
 import { type IdTokenPayload } from "./types.js";
 declare const DiscoveryDocSchema: z.ZodObject<{
@@ -63,7 +64,7 @@ export type DiscoveryDoc = z.infer<typeof DiscoveryDocSchema>;
  * @returns Validated discovery document
  * @throws OAuthMetadataValidationError if validation fails
  */
-export declare function loadDiscovery(discoveryUrl: string, allowedAlgs: ReadonlyArray<string>): Promise<DiscoveryDoc>;
+export declare function loadDiscovery(discoveryUrl: string, allowedAlgs: ReadonlyArray<string>, log?: Logger): Promise<DiscoveryDoc>;
 /**
  * Creates a remote JWKS fetcher with caching.
  *

package/dist/auth/oidc-client.js

@@ -57,12 +57,14 @@ const DiscoveryDocSchema = z.object({
  * @returns Validated discovery document
  * @throws OAuthMetadataValidationError if validation fails
  */
-export async function loadDiscovery(discoveryUrl, allowedAlgs) {
+export async function loadDiscovery(discoveryUrl, allowedAlgs, log) {
     // Step 1: Verify discoveryUrl itself is https://
     const url = new URL(discoveryUrl);
     if (url.protocol !== "https:") {
         throw OAuthMetadataValidationError.nonHttps("discoveryUrl", discoveryUrl);
     }
+    const t0 = performance.now();
+    log?.debug({ method: "GET", url: url.toString(), attempt: 1 }, "oidc discovery start");
     // Step 2: Fetch with timeout
     let response;
     try {
@@ -72,10 +74,13 @@ export async function loadDiscovery(discoveryUrl, allowedAlgs) {
         });
     }
     catch (cause) {
+        log?.error({ err: cause, method: "GET", url: url.toString(), attempt: 1 }, "oidc discovery fetch failed");
         throw new OAuthMetadataValidationError("failed to fetch OIDC discovery document", { cause });
     }
+    const attemptDurationMs = Math.round(performance.now() - t0);
     // Step 3: Check response status
     if (!response.ok) {
+        log?.error({ method: "GET", url: url.toString(), attempt: 1, status: response.status, attemptDurationMs }, "oidc discovery returned non-ok");
         throw OAuthMetadataValidationError.discoveryFetchFailed(url.toString(), response.status);
     }
     // Step 4: Parse and validate JSON
@@ -112,6 +117,7 @@ export async function loadDiscovery(discoveryUrl, allowedAlgs) {
     if (overlap.length === 0) {
         throw OAuthMetadataValidationError.noAlgOverlap(doc.id_token_signing_alg_values_supported, Array.from(allowedAlgs));
     }
+    log?.debug({ method: "GET", url: url.toString(), attempt: 1, status: response.status, attemptDurationMs }, "oidc discovery ok");
     return doc;
 }
 // ============================================================================

package/dist/auth/provider.d.ts

@@ -6,6 +6,7 @@ import type { DiskClientRegistrationStore } from "./client-registration.js";
 import type { TokenStore } from "./token-store.js";
 import type { AuthRequestStore } from "./auth-request-store.js";
 import type { AuthCodeStore } from "./auth-code-store.js";
+import type { Logger } from "pino";
 import type { Context } from "hono";
 import type { DiscoveryDoc } from "./oidc-client.js";
 import type { ResolvedOAuthConfig } from "./types.js";
@@ -29,7 +30,8 @@ export declare class MintingOAuthServerProvider implements OAuthServerProvider {
     private readonly _discovery;
     private readonly _oidcConfig;
     private readonly _publicUrl;
-    constructor(_clientStore: DiskClientRegistrationStore, _tokenStore: TokenStore, _authRequests: AuthRequestStore, _authCodes: AuthCodeStore, _discovery: DiscoveryDoc, _oidcConfig: ResolvedOAuthConfig, _publicUrl: string);
+    private readonly log;
+    constructor(_clientStore: DiskClientRegistrationStore, _tokenStore: TokenStore, _authRequests: AuthRequestStore, _authCodes: AuthCodeStore, _discovery: DiscoveryDoc, _oidcConfig: ResolvedOAuthConfig, _publicUrl: string, log: Logger);
     get clientsStore(): OAuthRegisteredClientsStore;
     authorize(client: OAuthClientInformationFull, params: AuthorizationParams, res: Context | unknown): Promise<void>;
     challengeForAuthorizationCode(_client: OAuthClientInformationFull, authorizationCode: string): Promise<string>;

package/dist/auth/provider.js

@@ -1,5 +1,5 @@
 import { InvalidGrantError, InvalidTokenError, InvalidTargetError, } from "@modelcontextprotocol/sdk/server/auth/errors.js";
-import { generateOpaqueToken, ACCESS_TOKEN_TTL_SECONDS, nowSeconds } from "./tokens.js";
+import { generateOpaqueToken, ACCESS_TOKEN_TTL_SECONDS, nowSeconds, hashTokenForStorage } from "./tokens.js";
 /**
  * Minting OAuth 2.1 server provider implementing OAuthServerProvider.
  *
@@ -20,7 +20,8 @@ export class MintingOAuthServerProvider {
     _discovery;
     _oidcConfig;
     _publicUrl;
-    constructor(_clientStore, _tokenStore, _authRequests, _authCodes, _discovery, _oidcConfig, _publicUrl) {
+    log;
+    constructor(_clientStore, _tokenStore, _authRequests, _authCodes, _discovery, _oidcConfig, _publicUrl, log) {
         this._clientStore = _clientStore;
         this._tokenStore = _tokenStore;
         this._authRequests = _authRequests;
@@ -28,6 +29,7 @@ export class MintingOAuthServerProvider {
         this._discovery = _discovery;
         this._oidcConfig = _oidcConfig;
         this._publicUrl = _publicUrl;
+        this.log = log;
     }
     get clientsStore() {
         // Type mismatch: SDK's OAuthRegisteredClientsStore interface requires mutable arrays
@@ -96,6 +98,8 @@ export class MintingOAuthServerProvider {
             scope: state.scope,
             resource: state.resource,
         });
+        const tokenHash = hashTokenForStorage(pair.access.plaintext);
+        this.log.info({ tokenHash, clientId: state.clientId, sub: state.identity.sub }, "access token minted (authorization_code grant)");
         return {
             access_token: pair.access.plaintext,
             refresh_token: pair.refresh.plaintext,
@@ -108,13 +112,19 @@ export class MintingOAuthServerProvider {
         // RFC 6749 §6 / OAuth 2.1 §4.3.1 — a refresh_token belongs to the client
         // it was issued to. TokenStore.rotateRefresh enforces that by comparing
         // expectedClientId to the stored record (atomically under its mutex).
+        // The returned IssuedPair.identity carries the rotated-out token's
+        // identity so we can log `sub` without a separate disk read.
         const result = await this._tokenStore.rotateRefresh(refreshToken, client.client_id, scopes, resource?.toString());
-        return result.match((pair) => ({
-            access_token: pair.access.plaintext,
-            refresh_token: pair.refresh.plaintext,
-            token_type: "Bearer",
-            expires_in: ACCESS_TOKEN_TTL_SECONDS,
-        }), (e) => {
+        return result.match((pair) => {
+            const tokenHash = hashTokenForStorage(pair.access.plaintext);
+            this.log.info({ tokenHash, clientId: client.client_id, sub: pair.identity.sub }, "access token minted (refresh_token grant)");
+            return {
+                access_token: pair.access.plaintext,
+                refresh_token: pair.refresh.plaintext,
+                token_type: "Bearer",
+                expires_in: ACCESS_TOKEN_TTL_SECONDS,
+            };
+        }, (e) => {
             throw e; // OAuthTokenError factories return SDK error subclasses, which the library serializes
         });
     }
@@ -138,5 +148,6 @@ export class MintingOAuthServerProvider {
         if (record.clientId !== client.client_id)
             return;
         await this._tokenStore.revoke(request.token);
+        this.log.info({ tokenHash: record.tokenHash, clientId: client.client_id, sub: record.identity.sub }, "access token revoked");
     }
 }

package/dist/auth/routes.d.ts

@@ -1,4 +1,5 @@
 import { Hono, type MiddlewareHandler } from "hono";
+import type { Logger } from "pino";
 import type { DiskClientRegistrationStore } from "./client-registration.js";
 import type { TokenStore } from "./token-store.js";
 import type { AuthRequestStore } from "./auth-request-store.js";
@@ -16,6 +17,10 @@ export interface AuthRoutesDeps {
     readonly discovery: DiscoveryDoc;
     readonly jwks: JWTVerifyGetKey;
     readonly publicUrl: string;
+    readonly log: {
+        readonly auth: Logger;
+        readonly oidcClient: Logger;
+    };
 }
 /**
  * Builds custom auth routes not mounted by @hono/mcp:

package/dist/auth/routes.js

@@ -1,4 +1,3 @@
-import { toMessage } from "../utils/log.js";
 import { Hono } from "hono";
 import { rateLimiter } from "hono-rate-limiter";
 import { z } from "zod";
@@ -83,7 +82,7 @@ export function buildAuthRoutes(deps) {
             idToken = validated.data.id_token;
         }
         catch (cause) {
-            process.stderr.write(`[auth] upstream token exchange failed: ${toMessage(cause)}\n`);
+            deps.log.oidcClient.error({ err: cause }, "upstream token exchange failed");
             return redirectToClient(c, stored.redirectUri, {
                 error: "server_error",
                 error_description: "upstream code exchange failed",
@@ -102,7 +101,7 @@ export function buildAuthRoutes(deps) {
             });
         }
         catch (cause) {
-            process.stderr.write(`[auth] id_token verification failed: ${toMessage(cause)}\n`);
+            deps.log.oidcClient.error({ err: cause }, "id_token verification failed");
             return redirectToClient(c, stored.redirectUri, {
                 error: "access_denied",
                 error_description: "id_token verification failed",
@@ -116,6 +115,7 @@ export function buildAuthRoutes(deps) {
             subs: new Set(deps.oidcConfig.allowlist.subs),
         });
         return identityResult.match(async (identity) => {
+            deps.log.auth.info({ email: identity.email ?? null, sub: identity.sub ?? null }, "allowlist accepted identity");
             const ourAuthCode = generateOpaqueToken("mcp_ac_");
             deps.authCodes.put(ourAuthCode, {
                 clientId: stored.clientId,
@@ -134,11 +134,15 @@ export function buildAuthRoutes(deps) {
             });
         }, (denial) => {
             // AC3.4: deny alert — log identity claims only, never the id_token.
-            // The full denial reason (including email/sub) goes to operator stderr;
+            // The full denial reason (including email/sub) goes to the auth logger;
             // the redirect-back error_description is generic so we don't leak the
             // user's email or subject id through claude.ai (or the user's browser
             // history) on a denial.
-            process.stderr.write(`[auth] allowlist denial: ${denial.message} email=${denial.identity.email ?? "-"} sub=${denial.identity.sub ?? "-"}\n`);
+            deps.log.auth.warn({
+                reason: denial.message,
+                email: denial.identity.email ?? null,
+                sub: denial.identity.sub ?? null,
+            }, "allowlist denied identity");
             return redirectToClient(c, stored.redirectUri, {
                 error: "access_denied",
                 error_description: "identity not allowed by server policy",

package/dist/auth/token-store.d.ts

@@ -23,6 +23,14 @@ export interface IssuedPair {
         readonly plaintext: string;
         readonly expiresAt: number;
     };
+    /**
+     * Identity bound to the issued/rotated pair. For `issueAccessRefreshPair`,
+     * this echoes the input identity; for `rotateRefresh`, it's the rotated-out
+     * token's identity (the new pair carries the same identity by definition).
+     * Surfacing it on the result lets the provider log refresh-grant state
+     * transitions without a separate disk read.
+     */
+    readonly identity: VerifiedIdentity;
 }
 export declare class TokenStore {
     private readonly _cache;

package/dist/auth/token-store.js

@@ -69,6 +69,7 @@ export class TokenStore {
         return {
             access: { plaintext: accessPlain, expiresAt: accessExpiresAt },
             refresh: { plaintext: refreshPlain, expiresAt: refreshExpiresAt },
+            identity: input.identity,
         };
     }
     /**
@@ -199,6 +200,7 @@ export class TokenStore {
             return ok({
                 access: { plaintext: accessPlain, expiresAt: accessExpiresAt },
                 refresh: { plaintext: refreshPlain, expiresAt: refreshExpiresAt },
+                identity: existing.identity,
             });
         });
     }