@oxy.so/core 1.4.0 → 1.5.0

package/dist/esm/mixins/OxyServices.utility.js

@@ -209,10 +209,51 @@ export function OxyServicesUtilityMixin(Base) {
          * @returns Express middleware function
          */
         auth(options = {}) {
-            const { debug = false, onError, loadUser = false, optional = false, jwtSecret, serviceTokenJwksUrl = new URL('/.well-known/jwks.json', this.getBaseURL()).toString(), expectedIssuer = OXY_JWT_ISSUER, expectedAudience = OXY_JWT_AUDIENCE, } = options;
+            const { debug = false, onError, onRefusal, loadUser = false, optional = false, jwtSecret, serviceTokenJwksUrl = new URL('/.well-known/jwks.json', this.getBaseURL()).toString(), expectedIssuer = OXY_JWT_ISSUER, expectedAudience = OXY_JWT_AUDIENCE, } = options;
             // Cross-mixin method access: typed as a structural subset of the
             // composed OxyServices we know we have at runtime.
             const oxyInstance = this;
+            /**
+             * Make a refusal observable to the HOST, without telling the client
+             * anything it is not already told.
+             *
+             * Called at the top of every branch that rejects a PRESENTED credential,
+             * including the ones `optional` then swallows — those are the expensive
+             * ones, because they leave no trace anywhere else. The response bodies
+             * below are untouched by design: what a client sees does not change.
+             *
+             * `warn`, not `debug`: a debug-gated reason is only there for whoever
+             * already suspects this middleware, and the failure mode this exists for
+             * is the one where nobody does. The volume is bounded by refusals, and a
+             * host drowning in them has a fault worth the lines.
+             */
+            const recordRefusal = (req, refusal) => {
+                const recorded = { ...refusal, optional };
+                req.oxyAuthRefusal = recorded;
+                logger.warn(`[oxy.auth] refused ${recorded.code}: ${recorded.reason}`, {
+                    component: 'auth',
+                    method: 'auth',
+                    code: recorded.code,
+                    stage: recorded.stage,
+                    reason: recorded.reason,
+                    status: recorded.status,
+                    // Says whether the client will see this status or the host's own
+                    // generic answer — the difference that made the JWKS outage invisible.
+                    optional: recorded.optional,
+                    path: req.path,
+                });
+                if (onRefusal) {
+                    try {
+                        onRefusal(recorded);
+                    }
+                    catch (observerError) {
+                        logger.warn('[oxy.auth] onRefusal observer threw', {
+                            component: 'auth',
+                            method: 'auth',
+                        }, observerError);
+                    }
+                }
+            };
             // Return an async middleware function
             return async (req, res, next) => {
                 try {
@@ -250,6 +291,12 @@ export function OxyServicesUtilityMixin(Base) {
                         decoded = jwtDecode(token);
                     }
                     catch (decodeError) {
+                        recordRefusal(req, {
+                            code: 'INVALID_TOKEN_FORMAT',
+                            stage: 'token',
+                            reason: 'Bearer credential is not a decodable JWT',
+                            status: 401,
+                        });
                         if (debug) {
                             logger.debug('[oxy.auth] Token decode failed', {
                                 component: 'auth',
@@ -296,6 +343,12 @@ export function OxyServicesUtilityMixin(Base) {
                             // else (e.g. Node crypto failing to load on a misconfigured host)
                             // genuinely IS a 500.
                             if (verifyError instanceof ServiceTokenConfigurationError) {
+                                recordRefusal(req, {
+                                    code: 'SERVICE_TOKEN_NOT_CONFIGURED',
+                                    stage: 'service-token',
+                                    reason: verifyError.message,
+                                    status: 403,
+                                });
                                 if (optional) {
                                     req.userId = null;
                                     req.user = null;
@@ -314,6 +367,20 @@ export function OxyServicesUtilityMixin(Base) {
                             if (verifyError instanceof ServiceTokenStructureError ||
                                 verifyError instanceof ServiceTokenSignatureError ||
                                 verifyError instanceof ServiceTokenClaimError) {
+                                const code = verifyError instanceof ServiceTokenClaimError
+                                    ? 'INVALID_SERVICE_TOKEN_CLAIMS'
+                                    : 'INVALID_SERVICE_TOKEN';
+                                // The SDK's own message is the whole diagnostic value here —
+                                // "signing key is unknown" (rotated/unpublished kid), "key set
+                                // is unavailable" (JWKS empty, unreachable or malformed) and
+                                // "audience mismatch" are three different outages that answer
+                                // the client identically.
+                                recordRefusal(req, {
+                                    code,
+                                    stage: 'service-token',
+                                    reason: `${verifyError.name}: ${verifyError.message}`,
+                                    status: 401,
+                                });
                                 if (debug) {
                                     logger.debug('[oxy.auth] Service token rejected', {
                                         component: 'auth',
@@ -327,11 +394,6 @@ export function OxyServicesUtilityMixin(Base) {
                                     req.user = null;
                                     return next();
                                 }
-                                const code = verifyError instanceof ServiceTokenSignatureError
-                                    ? 'INVALID_SERVICE_TOKEN'
-                                    : verifyError instanceof ServiceTokenStructureError
-                                        ? 'INVALID_SERVICE_TOKEN'
-                                        : 'INVALID_SERVICE_TOKEN_CLAIMS';
                                 const error = {
                                     error: code,
                                     message: verifyError.message,
@@ -359,6 +421,14 @@ export function OxyServicesUtilityMixin(Base) {
                         // Check expiration — reject tokens at exact expiry second (use <=)
                         const now = Math.floor(Date.now() / 1000);
                         if (!Number.isInteger(decoded.exp) || decoded.exp <= now) {
+                            recordRefusal(req, {
+                                code: 'TOKEN_EXPIRED',
+                                stage: 'service-token',
+                                reason: Number.isInteger(decoded.exp)
+                                    ? 'Service token expired'
+                                    : 'Service token has no integer exp claim',
+                                status: 401,
+                            });
                             if (optional) {
                                 req.userId = null;
                                 req.user = null;
@@ -370,6 +440,12 @@ export function OxyServicesUtilityMixin(Base) {
                             return res.status(401).json(error);
                         }
                         if (decoded.nbf !== undefined && (!Number.isInteger(decoded.nbf) || decoded.nbf > now)) {
+                            recordRefusal(req, {
+                                code: 'INVALID_SERVICE_TOKEN_CLAIMS',
+                                stage: 'service-token',
+                                reason: 'Service token is not yet valid (nbf)',
+                                status: 401,
+                            });
                             const error = { error: 'INVALID_SERVICE_TOKEN_CLAIMS', message: 'Service token is not yet valid', code: 'INVALID_SERVICE_TOKEN_CLAIMS', status: 401 };
                             if (onError)
                                 return onError(error);
@@ -391,6 +467,22 @@ export function OxyServicesUtilityMixin(Base) {
                             || !Array.isArray(decoded.scopes)
                             || !decoded.scopes.every((scope) => typeof scope === 'string' && scope.length > 0 && scope === scope.trim())
                             || new Set(decoded.scopes).size !== decoded.scopes.length) {
+                            recordRefusal(req, {
+                                code: 'INVALID_SERVICE_TOKEN',
+                                stage: 'service-token',
+                                // Names the field rather than its value: an exact-match claim
+                                // failing on invisible whitespace reads as "present" in a log
+                                // that only says which claims were missing.
+                                reason: `Service token claims unusable (${[
+                                    !isExactNonEmptyServiceClaim(appId) ? 'appId' : null,
+                                    !isExactNonEmptyServiceClaim(decoded.appName) ? 'appName' : null,
+                                    !isExactNonEmptyServiceClaim(credentialId) ? 'credentialId' : null,
+                                    !isExactNonEmptyServiceClaim(ownerAccountId) ? 'ownerAccountId' : null,
+                                    !isOxyServiceEnvironment(environment) ? 'environment' : null,
+                                    !Array.isArray(decoded.scopes) ? 'scopes' : null,
+                                ].filter((field) => field !== null).join(', ') || 'scopes'})`,
+                                status: 401,
+                            });
                             if (optional) {
                                 req.userId = null;
                                 req.user = null;
@@ -405,6 +497,12 @@ export function OxyServicesUtilityMixin(Base) {
                         const oxyUserIdRaw = req.headers['x-oxy-user-id'];
                         const oxyUserId = isExactNonEmptyServiceClaim(oxyUserIdRaw) ? oxyUserIdRaw : null;
                         if (oxyUserIdRaw !== undefined && oxyUserId === null) {
+                            recordRefusal(req, {
+                                code: 'INVALID_SERVICE_TOKEN_CLAIMS',
+                                stage: 'service-token',
+                                reason: 'X-Oxy-User-Id is not an exact non-empty id',
+                                status: 401,
+                            });
                             const error = {
                                 error: 'INVALID_SERVICE_TOKEN_CLAIMS',
                                 message: 'Delegated user id must be an exact non-empty id',
@@ -429,6 +527,16 @@ export function OxyServicesUtilityMixin(Base) {
                                     appId,
                                     attemptedUserId: oxyUserId,
                                 });
+                                // A verifier with no service credentials of its own cannot
+                                // reach the verify endpoint at all, so `null` here can mean
+                                // "no grant" OR "this host cannot ask". Both refuse, and both
+                                // are worth naming on the request.
+                                recordRefusal(req, {
+                                    code: 'SERVICE_ACTING_AS_UNAUTHORIZED',
+                                    stage: 'service-token',
+                                    reason: `No delegation grant for app ${appId} acting as ${oxyUserId} (or this verifier could not reach the grant check)`,
+                                    status: 403,
+                                });
                                 const error = {
                                     error: 'SERVICE_ACTING_AS_UNAUTHORIZED',
                                     message: 'Service not authorized to act as this user',
@@ -474,6 +582,12 @@ export function OxyServicesUtilityMixin(Base) {
                     // compared against the id the validated session resolves to.
                     const claimedUserId = readStringClaim(decoded.userId) ?? readStringClaim(decoded.id);
                     if (!claimedUserId) {
+                        recordRefusal(req, {
+                            code: 'INVALID_TOKEN_PAYLOAD',
+                            stage: 'token',
+                            reason: 'Token carries no usable user id claim',
+                            status: 401,
+                        });
                         if (optional) {
                             req.userId = null;
                             req.user = null;
@@ -492,6 +606,12 @@ export function OxyServicesUtilityMixin(Base) {
                     // Check token expiration locally first (fast path)
                     // Reject tokens at exact expiry second (use <=)
                     if (decoded.exp && decoded.exp <= Math.floor(Date.now() / 1000)) {
+                        recordRefusal(req, {
+                            code: 'TOKEN_EXPIRED',
+                            stage: 'token',
+                            reason: 'User access token expired',
+                            status: 401,
+                        });
                         if (optional) {
                             req.userId = null;
                             req.user = null;
@@ -514,6 +634,12 @@ export function OxyServicesUtilityMixin(Base) {
                     // required this.
                     const sessionId = readStringClaim(decoded.sessionId);
                     if (!sessionId) {
+                        recordRefusal(req, {
+                            code: 'SESSION_REQUIRED',
+                            stage: 'token',
+                            reason: 'User access token is not bound to a session',
+                            status: 401,
+                        });
                         if (optional) {
                             req.userId = null;
                             req.user = null;
@@ -536,6 +662,12 @@ export function OxyServicesUtilityMixin(Base) {
                             useHeaderValidation: true,
                         });
                         if (!validationResult || !validationResult.valid || !validationResult.user) {
+                            recordRefusal(req, {
+                                code: 'INVALID_SESSION',
+                                stage: 'session',
+                                reason: 'Session is invalid, revoked or expired',
+                                status: 401,
+                            });
                             if (optional) {
                                 req.userId = null;
                                 req.user = null;
@@ -554,6 +686,12 @@ export function OxyServicesUtilityMixin(Base) {
                         // The session — not the token — is the source of truth for identity.
                         const validatedUserId = getUserIdentityId(validationResult.user);
                         if (!validatedUserId) {
+                            recordRefusal(req, {
+                                code: 'INVALID_SESSION',
+                                stage: 'session',
+                                reason: 'Session did not resolve to a usable identity',
+                                status: 401,
+                            });
                             if (optional) {
                                 req.userId = null;
                                 req.user = null;
@@ -579,6 +717,12 @@ export function OxyServicesUtilityMixin(Base) {
                                 claimedUserId,
                                 validatedUserId,
                             });
+                            recordRefusal(req, {
+                                code: 'SESSION_USER_MISMATCH',
+                                stage: 'session',
+                                reason: 'Token user claim does not own the presented session',
+                                status: 401,
+                            });
                             if (optional) {
                                 req.userId = null;
                                 req.user = null;
@@ -609,6 +753,15 @@ export function OxyServicesUtilityMixin(Base) {
                         return next();
                     }
                     catch (validationError) {
+                        recordRefusal(req, {
+                            code: 'SESSION_VALIDATION_ERROR',
+                            stage: 'session',
+                            // Name and transport code only. The message of a failed
+                            // `validateSession` can carry the request URL, and that URL
+                            // contains the session id — which is a credential.
+                            reason: `Session validation call failed (${describeErrorSafely(validationError)})`,
+                            status: 401,
+                        });
                         if (debug) {
                             logger.debug('[oxy.auth] Session validation failed', {
                                 component: 'auth',
@@ -1034,6 +1187,20 @@ async function verifyServiceTokenSignature(token, options) {
  * those values out of URL construction and identity comparison, so an
  * unexpected shape becomes a 401 rather than a stringified surprise.
  */
+/**
+ * A short, log-safe description of a thrown value: its class name and, when the
+ * transport attached one, its `code` (`ECONNREFUSED`, `ETIMEDOUT`, `ENOTFOUND`
+ * …). Never the message — a failed request's message can quote the URL it was
+ * made against, and a session-validation URL contains the session id.
+ */
+function describeErrorSafely(error) {
+    if (!(error instanceof Error))
+        return typeof error;
+    const code = error.code;
+    return typeof code === 'string' && /^[A-Za-z0-9_]{1,40}$/.test(code)
+        ? `${error.name}: ${code}`
+        : error.name;
+}
 function readStringClaim(value) {
     return typeof value === 'string' && value.length > 0 ? value : null;
 }

package/dist/esm/server/auth.js

@@ -1,3 +1,4 @@
+import { logger } from '../logger/index.js';
 import { OXY_SERVICE_ENVIRONMENTS } from '../utils/oxyServiceEnvironment.js';
 export { OXY_SERVICE_ENVIRONMENTS };
 function normalizeId(value) {
@@ -106,9 +107,36 @@ export function getRequiredOxyUserId(req) {
     }
     return userId;
 }
+/**
+ * Why the credential on this request was refused, or `null` when none was
+ * presented (or it was accepted).
+ *
+ * Set by `oxy.auth()` — including the `optional: true` mount the composed
+ * helpers use, where a refusal otherwise leaves no trace: the request simply
+ * arrives unauthenticated and the host answers its own generic 401. Hosts log
+ * this beside their own 401; it is diagnostic and **must not be put into a
+ * response body**, which is exactly what it is kept out of.
+ */
+export function getOxyAuthRefusal(req) {
+    return req.oxyAuthRefusal ?? null;
+}
 export function requireOxyAuth(req, res, next) {
     const userId = getOxyUserId(req);
     if (!userId) {
+        // The body stays exactly as generic as it was. The LOG does not: this 401
+        // is the one a caller sees when the optional resolver already refused a
+        // real credential, and printing that code here is what turns "Homiio got
+        // 401, Alia logged nothing" into one greppable line.
+        const refusal = getOxyAuthRefusal(req);
+        if (refusal) {
+            logger.warn(`[oxy.auth] 401 after refusal ${refusal.code}: ${refusal.reason}`, {
+                component: 'auth',
+                method: 'requireOxyAuth',
+                code: refusal.code,
+                stage: refusal.stage,
+                reason: refusal.reason,
+            });
+        }
         res.status(401).json({
             error: 'Unauthorized',
             message: 'Authentication required',

package/dist/esm/server/index.js

@@ -14,7 +14,7 @@
  * app.use(createOxyRateLimit(oxy, { store: redisStore }));
  * ```
  */
-export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyBillingPrincipal, getOxyDelegatedUserId, getOxyRequestAttribution, getOxyUserId, getRequiredOxyBillingPrincipal, getRequiredOxyUserId, isOxyAuthenticated, requireOxyAuth, OXY_SERVICE_ENVIRONMENTS, } from './auth.js';
+export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyAuthRefusal, getOxyBillingPrincipal, getOxyDelegatedUserId, getOxyRequestAttribution, getOxyUserId, getRequiredOxyBillingPrincipal, getRequiredOxyUserId, isOxyAuthenticated, requireOxyAuth, OXY_SERVICE_ENVIRONMENTS, } from './auth.js';
 export { createOxyRateLimit } from './rateLimit.js';
 // SSRF-safe upstream fetch + URL validation (Node-only).
 export { assertSafePublicUrl, isBlockedIp, safeFetch, SsrfRejection, UpstreamError, ALLOWED_PORTS, ALLOWED_PROTOCOLS, BLOCKED_HOSTNAMES, DEFAULT_USER_AGENT, MAX_REDIRECTS, MAX_URL_LENGTH, UPSTREAM_HEADERS_TIMEOUT_MS, } from './safeFetch.js';