@technomoron/api-server-base 2.0.0-beta.21 → 2.0.0-beta.22

package/README.txt

@@ -111,6 +111,9 @@ cookiePath (string, default '/') Path applied to auth cookies.
 cookieSameSite ('lax' | 'strict' | 'none', default 'lax') SameSite attribute applied to auth cookies.
 cookieSecure (boolean | 'auto', default 'auto') Secure attribute applied to auth cookies; 'auto' enables Secure only when the request is HTTPS (or forwarded as HTTPS).
 cookieHttpOnly (boolean, default true) HttpOnly attribute applied to auth cookies.
+apiKeyPrefix (string, default '') Optional prefix required before API key secrets in Authorization Bearer tokens.
+tokenParam (string, default '') Optional request field name used for token fallback when Bearer is missing.
+tokenParamLocation ('body' | 'query' | 'body-query', default 'body') Controls where tokenParam is read from.
 accessCookie (string, default 'dat') Access token cookie name.
 refreshCookie (string, default 'drt') Refresh token cookie name.
 accessExpiry (number, default 60 * 15) Access token lifetime in seconds.
@@ -129,7 +132,7 @@ Tip: If you add new configuration fields in downstream projects, extend ApiServe
 	-----------------
 	1. Express middlewares (express.json, cookie-parser, optional multer) run before your handler.
 	2. ApiServer wraps the route inside handle_request, creating an ApiRequest and logging when debug is enabled.
-	3. authenticate enforces the ApiRoute auth type: `none`, `maybe`, `yes`, `strict`, or `apikey`. Bearer JWTs and the access cookie (`accessCookie`, default `dat`) are accepted for `yes`/`strict`, while API key tokens prefixed with `apikey-` always delegate to `getApiKey`. When `refreshSecret` is configured and your storage supports refresh lookups (`getToken({ refreshToken })` + `updateToken(...)`), `yes`/`strict` routes will automatically mint a new access token when it is missing or expired (and also recover from "Authorization token is no longer valid" by refreshing). `maybe` routes only do the same when `refreshMaybe: true`. The optional `strict` type (or server-wide `validateTokens` flag) requires the signed JWT to exist in storage; when it does, the persisted row is attached to `apiReq.authToken`. The dedicated `apikey` type simply means “an API key is required”; otherwise API keys are still accepted by `yes`/`strict` routes alongside JWTs, and `apiReq.apiKey` is populated when present.
+	3. authenticate enforces the ApiRoute auth type: `none`, `maybe`, `yes`, `strict`, or `apikey`. It always prioritizes `Authorization: Bearer ...`. If Bearer is missing and `tokenParam` is configured, token fallback is read from the configured request location (`body`, `query`, or `body-query`) before checking the access cookie (`accessCookie`, default `dat`). API key tokens are matched with the optional `apiKeyPrefix` config (default `''`, meaning raw key values). When `refreshSecret` is configured and your storage supports refresh lookups (`getToken({ refreshToken })` + `updateToken(...)`), `yes`/`strict` routes will automatically mint a new access token when it is missing or expired (and also recover from "Authorization token is no longer valid" by refreshing). `maybe` routes only do the same when `refreshMaybe: true`. The optional `strict` type (or server-wide `validateTokens` flag) requires the signed JWT to exist in storage; when it does, the persisted row is attached to `apiReq.authToken`. The dedicated `apikey` type simply means “an API key is required”; otherwise API keys are still accepted by `yes`/`strict` routes alongside JWTs, and `apiReq.apiKey` is populated when present.
 	4. authorize runs with the requested auth class (any or admin in the base implementation). Override to connect to your role system.
 	5. The handler executes and returns its tuple. Responses are normalized to { code, message, data } JSON.
 	6. Errors bubble into the wrapper. ApiError instances respect the provided status codes; other exceptions result in a 500 with text derived from guessExceptionText.

package/dist/cjs/api-module.d.ts

@@ -4,7 +4,10 @@ export type ApiHandler<Data = unknown> = (apiReq: ApiRequest) => Promise<ApiHand
 export type ApiAuthType = 'none' | 'maybe' | 'yes' | 'strict' | 'apikey';
 export type ApiAuthClass = 'any' | 'admin';
 export interface ApiKey {
+    /** Real user identity — who the key belongs to. */
     uid: unknown;
+    /** Effective user identity — who the key acts as. When set, the request is treated as impersonation (isImpersonating() === true). */
+    euid?: unknown;
 }
 export type ApiRoute = {
     method: 'get' | 'post' | 'put' | 'patch' | 'delete';

package/dist/cjs/api-server-base.cjs

@@ -372,6 +372,10 @@ function fillConfig(config) {
         cookieSameSite: config.cookieSameSite ?? 'lax',
         cookieSecure: config.cookieSecure ?? 'auto',
         cookieHttpOnly: config.cookieHttpOnly ?? true,
+        apiKeyPrefix: config.apiKeyPrefix ?? '',
+        apiKeyEnabled: config.apiKeyEnabled ?? false,
+        tokenParam: config.tokenParam ?? '',
+        tokenParamLocation: config.tokenParamLocation ?? 'body',
         accessCookie: config.accessCookie ?? 'dat',
         refreshCookie: config.refreshCookie ?? 'drt',
         accessExpiry: config.accessExpiry ?? 60 * 15,
@@ -1042,19 +1046,28 @@ class ApiServer {
         }
         let token = null;
         const authHeader = apiReq.req.headers.authorization;
+        const bearerToken = authHeader?.startsWith('Bearer ') ? authHeader.slice(7).trim() || null : null;
+        const paramToken = bearerToken ? null : this.resolveTokenFromRequest(apiReq.req);
         const requiresAuthToken = this.requiresAuthToken(authType);
         const allowRefresh = requiresAuthToken || (authType === 'maybe' && this.config.refreshMaybe);
-        const apiKeyAuth = await this.tryAuthenticateApiKey(apiReq, authType, authHeader);
-        if (apiKeyAuth) {
-            return apiKeyAuth;
+        if (this.config.apiKeyEnabled || authType === 'apikey') {
+            const apiKeyAuth = await this.tryAuthenticateApiKey(apiReq, authType, bearerToken ?? paramToken);
+            if (apiKeyAuth) {
+                return apiKeyAuth;
+            }
+        }
+        token = bearerToken ?? paramToken;
+        if (bearerToken) {
+            apiReq.authMethod = 'bearer';
         }
-        if (authHeader?.startsWith('Bearer ')) {
-            token = authHeader.slice(7).trim();
+        else if (paramToken) {
+            apiReq.authMethod = 'param';
         }
         if (!token) {
             const access = apiReq.req.cookies?.[this.config.accessCookie];
             if (access) {
                 token = access;
+                apiReq.authMethod = 'cookie';
             }
         }
         let tokenData;
@@ -1134,40 +1147,83 @@ class ApiServer {
         apiReq.token = token;
         return tokenData;
     }
-    async tryAuthenticateApiKey(apiReq, authType, authHeader) {
-        if (!authHeader?.startsWith('Bearer ')) {
+    async tryAuthenticateApiKey(apiReq, authType, tokenCandidate) {
+        if (!tokenCandidate) {
             if (authType === 'apikey') {
                 throw new ApiError({ code: 401, message: 'Authorization header is missing or invalid' });
             }
             return null;
         }
-        const keyToken = authHeader.slice(7).trim();
-        if (!keyToken.startsWith('apikey-')) {
+        const keyToken = tokenCandidate;
+        const prefix = this.config.apiKeyPrefix;
+        const secret = prefix === '' ? keyToken : keyToken.startsWith(prefix) ? keyToken.slice(prefix.length) : null;
+        if (!secret) {
             if (authType === 'apikey') {
                 throw new ApiError({ code: 401, message: 'Invalid API Key' });
             }
             return null;
         }
-        const secret = keyToken.replace(/^apikey-/, '');
         const key = await this.getApiKey(secret);
         if (!key) {
-            throw new ApiError({ code: 401, message: 'Invalid API Key' });
+            if (authType === 'apikey') {
+                throw new ApiError({ code: 401, message: 'Invalid API Key' });
+            }
+            return null;
         }
         apiReq.token = secret;
         apiReq.apiKey = key;
-        // Treat API keys as authenticated identities, consistent with JWT-based flows.
-        const resolvedUid = this.normalizeAuthIdentifier(key.uid);
-        if (resolvedUid !== null) {
-            apiReq.realUid = resolvedUid;
+        apiReq.authMethod = 'apikey';
+        // uid is the real identity; euid (if set) is the effective/impersonated identity.
+        const resolvedRuid = this.normalizeAuthIdentifier(key.uid);
+        const resolvedEuid = key.euid !== undefined ? this.normalizeAuthIdentifier(key.euid) : null;
+        const effectiveUid = resolvedEuid ?? resolvedRuid;
+        if (resolvedRuid !== null) {
+            apiReq.realUid = resolvedRuid;
         }
         return {
-            uid: key.uid,
+            uid: effectiveUid,
+            ...(resolvedEuid !== null ? { ruid: resolvedRuid !== null ? String(resolvedRuid) : undefined } : {}),
             domain: '',
             fingerprint: '',
             iat: 0,
             exp: 0
         };
     }
+    resolveTokenFromRequest(req) {
+        const paramName = this.config.tokenParam.trim();
+        if (!paramName) {
+            return null;
+        }
+        const location = this.config.tokenParamLocation;
+        if (location === 'body') {
+            return this.readNamedValue(req.body, paramName);
+        }
+        if (location === 'query') {
+            return this.readNamedValue(req.query, paramName);
+        }
+        return this.readNamedValue(req.body, paramName) ?? this.readNamedValue(req.query, paramName);
+    }
+    readNamedValue(container, key) {
+        if (!container || typeof container !== 'object' || Array.isArray(container)) {
+            return null;
+        }
+        const raw = container[key];
+        if (typeof raw === 'string') {
+            const token = raw.trim();
+            return token.length > 0 ? token : null;
+        }
+        if (Array.isArray(raw)) {
+            for (const entry of raw) {
+                if (typeof entry === 'string') {
+                    const token = entry.trim();
+                    if (token.length > 0) {
+                        return token;
+                    }
+                }
+            }
+        }
+        return null;
+    }
     requiresAuthToken(authType) {
         return authType === 'yes' || authType === 'strict';
     }
@@ -1238,6 +1294,7 @@ class ApiServer {
             res,
             token: '',
             tokenData: null,
+            authMethod: null,
             realUid: null,
             getClientInfo: () => ensureClientInfo(apiReq),
             getClientIp: () => ensureClientInfo(apiReq).ip,
@@ -1431,12 +1488,25 @@ class ApiServer {
     }
     dumpRequest(apiReq) {
         const req = apiReq.req;
+        const tokenParam = this.config.tokenParam.trim();
         console.log('--- Incoming Request! ---');
         const url = req.originalUrl || req.url;
         console.log('URL:', url);
         console.log('Method:', req.method);
-        console.log('Query Params:', req.query || {});
+        if (tokenParam &&
+            req.query &&
+            typeof req.query === 'object' &&
+            tokenParam in req.query) {
+            const maskedQuery = { ...req.query, [tokenParam]: '[REDACTED]' };
+            console.log('Query Params:', maskedQuery);
+        }
+        else {
+            console.log('Query Params:', req.query || {});
+        }
         const sensitiveBodyKeys = ['password', 'client_secret', 'clientSecret', 'secret'];
+        if (tokenParam) {
+            sensitiveBodyKeys.push(tokenParam);
+        }
         const body = req.body && typeof req.body === 'object' ? { ...req.body } : req.body;
         if (body && typeof body === 'object') {
             for (const key of sensitiveBodyKeys) {
@@ -1507,7 +1577,21 @@ class ApiServer {
         return value;
     }
     dumpResponse(apiReq, payload, status) {
-        const url = apiReq.req.originalUrl || apiReq.req.url;
+        const rawUrl = apiReq.req.originalUrl || apiReq.req.url;
+        const tokenParam = this.config.tokenParam.trim();
+        let url = rawUrl;
+        if (tokenParam && rawUrl) {
+            try {
+                const parsed = new URL(rawUrl, 'http://x');
+                if (parsed.searchParams.has(tokenParam)) {
+                    parsed.searchParams.set(tokenParam, '[REDACTED]');
+                    url = parsed.pathname + '?' + parsed.searchParams.toString();
+                }
+            }
+            catch {
+                // Leave url unmodified if parsing fails
+            }
+        }
         console.log('--- Outgoing Response! ---');
         console.log('URL:', url);
         console.log('Status:', status);

package/dist/cjs/api-server-base.d.ts

@@ -31,6 +31,7 @@ export interface ApiTokenData extends JwtPayload, Partial<Token> {
     iat?: number;
     exp?: number;
 }
+export type ApiAuthMethod = 'bearer' | 'cookie' | 'param' | 'apikey' | null;
 export interface ApiRequest {
     server: ApiServer;
     req: ExtendedReq;
@@ -39,6 +40,8 @@ export interface ApiRequest {
     token?: string;
     authToken?: Token | null;
     apiKey?: ApiKey | null;
+    /** How this request was authenticated. null when unauthenticated. */
+    authMethod?: ApiAuthMethod;
     clientInfo?: ClientInfo;
     realUid?: AuthIdentifier | null;
     getClientInfo: () => ClientInfo;
@@ -115,6 +118,18 @@ export interface ApiServerConf {
     cookieSecure?: boolean | 'auto';
     /** Cookie HttpOnly attribute for auth cookies. */
     cookieHttpOnly?: boolean;
+    /** Prefix used for API keys in Authorization Bearer tokens. */
+    apiKeyPrefix: string;
+    /**
+     * Enable API key authentication on non-apikey routes (e.g. 'yes', 'strict', 'maybe').
+     * When false (default), API key lookups only run on routes with authType 'apikey'.
+     * Set to true if you need API keys to authenticate on JWT routes as well.
+     */
+    apiKeyEnabled: boolean;
+    /** Optional request field name used to read auth tokens when Bearer is missing. */
+    tokenParam: string;
+    /** Where to read `tokenParam` from. */
+    tokenParamLocation: 'body' | 'query' | 'body-query';
     accessCookie: string;
     refreshCookie: string;
     accessExpiry: number;
@@ -238,6 +253,8 @@ export declare class ApiServer {
     private tryRefreshAccessToken;
     private authenticate;
     private tryAuthenticateApiKey;
+    private resolveTokenFromRequest;
+    private readNamedValue;
     private requiresAuthToken;
     private shouldValidateStoredToken;
     private assertStoredAccessToken;

package/dist/esm/api-module.d.ts

@@ -4,7 +4,10 @@ export type ApiHandler<Data = unknown> = (apiReq: ApiRequest) => Promise<ApiHand
 export type ApiAuthType = 'none' | 'maybe' | 'yes' | 'strict' | 'apikey';
 export type ApiAuthClass = 'any' | 'admin';
 export interface ApiKey {
+    /** Real user identity — who the key belongs to. */
     uid: unknown;
+    /** Effective user identity — who the key acts as. When set, the request is treated as impersonation (isImpersonating() === true). */
+    euid?: unknown;
 }
 export type ApiRoute = {
     method: 'get' | 'post' | 'put' | 'patch' | 'delete';

package/dist/esm/api-server-base.d.ts

@@ -31,6 +31,7 @@ export interface ApiTokenData extends JwtPayload, Partial<Token> {
     iat?: number;
     exp?: number;
 }
+export type ApiAuthMethod = 'bearer' | 'cookie' | 'param' | 'apikey' | null;
 export interface ApiRequest {
     server: ApiServer;
     req: ExtendedReq;
@@ -39,6 +40,8 @@ export interface ApiRequest {
     token?: string;
     authToken?: Token | null;
     apiKey?: ApiKey | null;
+    /** How this request was authenticated. null when unauthenticated. */
+    authMethod?: ApiAuthMethod;
     clientInfo?: ClientInfo;
     realUid?: AuthIdentifier | null;
     getClientInfo: () => ClientInfo;
@@ -115,6 +118,18 @@ export interface ApiServerConf {
     cookieSecure?: boolean | 'auto';
     /** Cookie HttpOnly attribute for auth cookies. */
     cookieHttpOnly?: boolean;
+    /** Prefix used for API keys in Authorization Bearer tokens. */
+    apiKeyPrefix: string;
+    /**
+     * Enable API key authentication on non-apikey routes (e.g. 'yes', 'strict', 'maybe').
+     * When false (default), API key lookups only run on routes with authType 'apikey'.
+     * Set to true if you need API keys to authenticate on JWT routes as well.
+     */
+    apiKeyEnabled: boolean;
+    /** Optional request field name used to read auth tokens when Bearer is missing. */
+    tokenParam: string;
+    /** Where to read `tokenParam` from. */
+    tokenParamLocation: 'body' | 'query' | 'body-query';
     accessCookie: string;
     refreshCookie: string;
     accessExpiry: number;
@@ -238,6 +253,8 @@ export declare class ApiServer {
     private tryRefreshAccessToken;
     private authenticate;
     private tryAuthenticateApiKey;
+    private resolveTokenFromRequest;
+    private readNamedValue;
     private requiresAuthToken;
     private shouldValidateStoredToken;
     private assertStoredAccessToken;

package/dist/esm/api-server-base.js

@@ -364,6 +364,10 @@ function fillConfig(config) {
         cookieSameSite: config.cookieSameSite ?? 'lax',
         cookieSecure: config.cookieSecure ?? 'auto',
         cookieHttpOnly: config.cookieHttpOnly ?? true,
+        apiKeyPrefix: config.apiKeyPrefix ?? '',
+        apiKeyEnabled: config.apiKeyEnabled ?? false,
+        tokenParam: config.tokenParam ?? '',
+        tokenParamLocation: config.tokenParamLocation ?? 'body',
         accessCookie: config.accessCookie ?? 'dat',
         refreshCookie: config.refreshCookie ?? 'drt',
         accessExpiry: config.accessExpiry ?? 60 * 15,
@@ -1034,19 +1038,28 @@ export class ApiServer {
         }
         let token = null;
         const authHeader = apiReq.req.headers.authorization;
+        const bearerToken = authHeader?.startsWith('Bearer ') ? authHeader.slice(7).trim() || null : null;
+        const paramToken = bearerToken ? null : this.resolveTokenFromRequest(apiReq.req);
         const requiresAuthToken = this.requiresAuthToken(authType);
         const allowRefresh = requiresAuthToken || (authType === 'maybe' && this.config.refreshMaybe);
-        const apiKeyAuth = await this.tryAuthenticateApiKey(apiReq, authType, authHeader);
-        if (apiKeyAuth) {
-            return apiKeyAuth;
+        if (this.config.apiKeyEnabled || authType === 'apikey') {
+            const apiKeyAuth = await this.tryAuthenticateApiKey(apiReq, authType, bearerToken ?? paramToken);
+            if (apiKeyAuth) {
+                return apiKeyAuth;
+            }
+        }
+        token = bearerToken ?? paramToken;
+        if (bearerToken) {
+            apiReq.authMethod = 'bearer';
         }
-        if (authHeader?.startsWith('Bearer ')) {
-            token = authHeader.slice(7).trim();
+        else if (paramToken) {
+            apiReq.authMethod = 'param';
         }
         if (!token) {
             const access = apiReq.req.cookies?.[this.config.accessCookie];
             if (access) {
                 token = access;
+                apiReq.authMethod = 'cookie';
             }
         }
         let tokenData;
@@ -1126,40 +1139,83 @@ export class ApiServer {
         apiReq.token = token;
         return tokenData;
     }
-    async tryAuthenticateApiKey(apiReq, authType, authHeader) {
-        if (!authHeader?.startsWith('Bearer ')) {
+    async tryAuthenticateApiKey(apiReq, authType, tokenCandidate) {
+        if (!tokenCandidate) {
             if (authType === 'apikey') {
                 throw new ApiError({ code: 401, message: 'Authorization header is missing or invalid' });
             }
             return null;
         }
-        const keyToken = authHeader.slice(7).trim();
-        if (!keyToken.startsWith('apikey-')) {
+        const keyToken = tokenCandidate;
+        const prefix = this.config.apiKeyPrefix;
+        const secret = prefix === '' ? keyToken : keyToken.startsWith(prefix) ? keyToken.slice(prefix.length) : null;
+        if (!secret) {
             if (authType === 'apikey') {
                 throw new ApiError({ code: 401, message: 'Invalid API Key' });
             }
             return null;
         }
-        const secret = keyToken.replace(/^apikey-/, '');
         const key = await this.getApiKey(secret);
         if (!key) {
-            throw new ApiError({ code: 401, message: 'Invalid API Key' });
+            if (authType === 'apikey') {
+                throw new ApiError({ code: 401, message: 'Invalid API Key' });
+            }
+            return null;
         }
         apiReq.token = secret;
         apiReq.apiKey = key;
-        // Treat API keys as authenticated identities, consistent with JWT-based flows.
-        const resolvedUid = this.normalizeAuthIdentifier(key.uid);
-        if (resolvedUid !== null) {
-            apiReq.realUid = resolvedUid;
+        apiReq.authMethod = 'apikey';
+        // uid is the real identity; euid (if set) is the effective/impersonated identity.
+        const resolvedRuid = this.normalizeAuthIdentifier(key.uid);
+        const resolvedEuid = key.euid !== undefined ? this.normalizeAuthIdentifier(key.euid) : null;
+        const effectiveUid = resolvedEuid ?? resolvedRuid;
+        if (resolvedRuid !== null) {
+            apiReq.realUid = resolvedRuid;
         }
         return {
-            uid: key.uid,
+            uid: effectiveUid,
+            ...(resolvedEuid !== null ? { ruid: resolvedRuid !== null ? String(resolvedRuid) : undefined } : {}),
             domain: '',
             fingerprint: '',
             iat: 0,
             exp: 0
         };
     }
+    resolveTokenFromRequest(req) {
+        const paramName = this.config.tokenParam.trim();
+        if (!paramName) {
+            return null;
+        }
+        const location = this.config.tokenParamLocation;
+        if (location === 'body') {
+            return this.readNamedValue(req.body, paramName);
+        }
+        if (location === 'query') {
+            return this.readNamedValue(req.query, paramName);
+        }
+        return this.readNamedValue(req.body, paramName) ?? this.readNamedValue(req.query, paramName);
+    }
+    readNamedValue(container, key) {
+        if (!container || typeof container !== 'object' || Array.isArray(container)) {
+            return null;
+        }
+        const raw = container[key];
+        if (typeof raw === 'string') {
+            const token = raw.trim();
+            return token.length > 0 ? token : null;
+        }
+        if (Array.isArray(raw)) {
+            for (const entry of raw) {
+                if (typeof entry === 'string') {
+                    const token = entry.trim();
+                    if (token.length > 0) {
+                        return token;
+                    }
+                }
+            }
+        }
+        return null;
+    }
     requiresAuthToken(authType) {
         return authType === 'yes' || authType === 'strict';
     }
@@ -1230,6 +1286,7 @@ export class ApiServer {
             res,
             token: '',
             tokenData: null,
+            authMethod: null,
             realUid: null,
             getClientInfo: () => ensureClientInfo(apiReq),
             getClientIp: () => ensureClientInfo(apiReq).ip,
@@ -1423,12 +1480,25 @@ export class ApiServer {
     }
     dumpRequest(apiReq) {
         const req = apiReq.req;
+        const tokenParam = this.config.tokenParam.trim();
         console.log('--- Incoming Request! ---');
         const url = req.originalUrl || req.url;
         console.log('URL:', url);
         console.log('Method:', req.method);
-        console.log('Query Params:', req.query || {});
+        if (tokenParam &&
+            req.query &&
+            typeof req.query === 'object' &&
+            tokenParam in req.query) {
+            const maskedQuery = { ...req.query, [tokenParam]: '[REDACTED]' };
+            console.log('Query Params:', maskedQuery);
+        }
+        else {
+            console.log('Query Params:', req.query || {});
+        }
         const sensitiveBodyKeys = ['password', 'client_secret', 'clientSecret', 'secret'];
+        if (tokenParam) {
+            sensitiveBodyKeys.push(tokenParam);
+        }
         const body = req.body && typeof req.body === 'object' ? { ...req.body } : req.body;
         if (body && typeof body === 'object') {
             for (const key of sensitiveBodyKeys) {
@@ -1499,7 +1569,21 @@ export class ApiServer {
         return value;
     }
     dumpResponse(apiReq, payload, status) {
-        const url = apiReq.req.originalUrl || apiReq.req.url;
+        const rawUrl = apiReq.req.originalUrl || apiReq.req.url;
+        const tokenParam = this.config.tokenParam.trim();
+        let url = rawUrl;
+        if (tokenParam && rawUrl) {
+            try {
+                const parsed = new URL(rawUrl, 'http://x');
+                if (parsed.searchParams.has(tokenParam)) {
+                    parsed.searchParams.set(tokenParam, '[REDACTED]');
+                    url = parsed.pathname + '?' + parsed.searchParams.toString();
+                }
+            }
+            catch {
+                // Leave url unmodified if parsing fails
+            }
+        }
         console.log('--- Outgoing Response! ---');
         console.log('URL:', url);
         console.log('Status:', status);