@technomoron/api-server-base 1.1.9 → 1.1.11

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

@@ -588,6 +588,7 @@ class ApiServer {
     }
     async authenticate(apiReq, authType) {
         if (authType === 'none') {
+            apiReq.realUid = null;
             return null;
         }
         let token = null;
@@ -600,15 +601,14 @@ class ApiServer {
         if (authHeader?.startsWith('Bearer ')) {
             token = authHeader.slice(7).trim();
         }
-        else if (requiresAuthToken && !authHeader) {
-            throw new ApiError({ code: 401, message: 'Authorization header is missing or invalid' });
-        }
-        if (!token || token === null) {
+        if (!token) {
             const access = apiReq.req.cookies?.dat;
             if (access) {
                 token = access;
             }
-            else if (requiresAuthToken) {
+        }
+        if (!token || token === null) {
+            if (requiresAuthToken) {
                 throw new ApiError({ code: 401, message: 'Authorization token is required (Bearer/cookie)' });
             }
         }
@@ -624,6 +624,8 @@ class ApiServer {
         if (!tokenData) {
             throw new ApiError({ code: 401, message: 'Unathorized Access - ' + error });
         }
+        const effectiveUserId = this.extractTokenUserId(tokenData);
+        apiReq.realUid = this.resolveRealUserId(tokenData, effectiveUserId);
         if (this.shouldValidateStoredToken(authType)) {
             await this.assertStoredAccessToken(apiReq, token, tokenData);
         }
@@ -666,10 +668,7 @@ class ApiServer {
         return this.config.validateTokens || authType === 'strict';
     }
     async assertStoredAccessToken(apiReq, token, tokenData) {
-        if (typeof tokenData.uid !== 'string' && typeof tokenData.uid !== 'number') {
-            throw new ApiError({ code: 401, message: 'Authorization token is malformed' });
-        }
-        const userId = tokenData.uid;
+        const userId = this.extractTokenUserId(tokenData);
         const stored = await this.storageAdapter.getToken({
             accessToken: token,
             userId
@@ -679,6 +678,36 @@ class ApiServer {
         }
         apiReq.authToken = stored;
     }
+    normalizeAuthIdentifier(candidate) {
+        if (typeof candidate === 'number' && Number.isFinite(candidate)) {
+            return candidate;
+        }
+        if (typeof candidate === 'string') {
+            const trimmed = candidate.trim();
+            if (trimmed.length > 0) {
+                return trimmed;
+            }
+        }
+        return null;
+    }
+    extractTokenUserId(tokenData) {
+        const normalized = this.normalizeAuthIdentifier(tokenData.uid);
+        if (normalized === null) {
+            throw new ApiError({ code: 401, message: 'Authorization token is malformed' });
+        }
+        return normalized;
+    }
+    resolveRealUserId(tokenData, effectiveUserId) {
+        const withReal = tokenData;
+        const rawReal = this.normalizeAuthIdentifier(withReal.ruid);
+        if (rawReal === null) {
+            return effectiveUserId;
+        }
+        if (typeof rawReal === 'number' && rawReal === 0) {
+            return effectiveUserId;
+        }
+        return rawReal;
+    }
     handle_request(handler, auth) {
         return async (req, res, next) => {
             void next;
@@ -688,9 +717,22 @@ class ApiServer {
                 res,
                 token: '',
                 tokenData: null,
+                realUid: null,
                 getClientInfo: () => ensureClientInfo(apiReq),
                 getClientIp: () => ensureClientInfo(apiReq).ip,
-                getClientIpChain: () => ensureClientInfo(apiReq).ipchain
+                getClientIpChain: () => ensureClientInfo(apiReq).ipchain,
+                getRealUid: () => apiReq.realUid ?? null,
+                isImpersonating: () => {
+                    const realUid = apiReq.realUid;
+                    const tokenUid = apiReq.tokenData?.uid;
+                    if (realUid === null || realUid === undefined) {
+                        return false;
+                    }
+                    if (tokenUid === null || tokenUid === undefined) {
+                        return false;
+                    }
+                    return realUid !== tokenUid;
+                }
             };
             this.currReq = apiReq;
             try {

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

@@ -9,7 +9,7 @@ import jwt, { JwtPayload, SignOptions, VerifyOptions } from 'jsonwebtoken';
 import { ApiModule } from './api-module.js';
 import type { ApiAuthClass, ApiKey } from './api-module.js';
 import type { AuthProviderModule } from './auth-module.js';
-import type { AuthStorage, AuthTokenData, AuthTokenMetadata } from './auth-storage.js';
+import type { AuthStorage, AuthIdentifier, AuthTokenData, AuthTokenMetadata } from './auth-storage.js';
 export type { Application, Request, Response, NextFunction, Router } from 'express';
 export type { Multer } from 'multer';
 export type { JwtPayload, SignOptions, VerifyOptions } from 'jsonwebtoken';
@@ -49,9 +49,12 @@ export interface ApiRequest {
     authToken?: AuthTokenData | null;
     apiKey?: ApiKey | null;
     clientInfo?: ClientInfo;
+    realUid?: AuthIdentifier | null;
     getClientInfo: () => ClientInfo;
     getClientIp: () => string | null;
     getClientIpChain: () => string[];
+    getRealUid: () => AuthIdentifier | null;
+    isImpersonating: () => boolean;
 }
 export interface ClientAgentProfile {
     ua: string;
@@ -148,6 +151,9 @@ export declare class ApiServer {
     private requiresAuthToken;
     private shouldValidateStoredToken;
     private assertStoredAccessToken;
+    private normalizeAuthIdentifier;
+    private extractTokenUserId;
+    private resolveRealUserId;
     private handle_request;
     api<T extends ApiModule<any>>(module: T): this;
     dumpRequest(apiReq: ApiRequest): void;

package/dist/cjs/auth-storage.cjs

@@ -82,6 +82,11 @@ class BaseAuthStorage {
         void clientId;
         return null;
     }
+    // Override to decide if a real user may impersonate another user
+    async canImpersonate(params) {
+        void params;
+        return false;
+    }
 }
 exports.BaseAuthStorage = BaseAuthStorage;
 exports.nullAuthStorage = new BaseAuthStorage();

package/dist/cjs/auth-storage.d.ts

@@ -1,5 +1,6 @@
 export type AuthIdentifier = string | number;
 export interface AuthTokenMetadata {
+    ruid?: AuthIdentifier;
     clientId?: string;
     domain?: string;
     fingerprint?: string;
@@ -101,6 +102,10 @@ export interface AuthStorage<UserRow, SafeUser> {
     verifyClientSecret?(client: OAuthClient, clientSecret: string | null): Promise<boolean>;
     createAuthCode?(request: AuthCodeRequest): Promise<AuthCodeData>;
     consumeAuthCode?(code: string, clientId: string): Promise<AuthCodeData | null>;
+    canImpersonate?(params: {
+        realUserId: AuthIdentifier;
+        effectiveUserId: AuthIdentifier;
+    }): Promise<boolean>;
 }
 export declare class BaseAuthStorage<UserRow = unknown, SafeUser = unknown> implements AuthStorage<UserRow, SafeUser> {
     getUser(identifier: AuthIdentifier): Promise<UserRow | null>;
@@ -120,5 +125,9 @@ export declare class BaseAuthStorage<UserRow = unknown, SafeUser = unknown> impl
     verifyClientSecret(client: OAuthClient, clientSecret: string | null): Promise<boolean>;
     createAuthCode(request: AuthCodeRequest): Promise<AuthCodeData>;
     consumeAuthCode(code: string, clientId: string): Promise<AuthCodeData | null>;
+    canImpersonate(params: {
+        realUserId: AuthIdentifier;
+        effectiveUserId: AuthIdentifier;
+    }): Promise<boolean>;
 }
 export declare const nullAuthStorage: AuthStorage<unknown, unknown>;

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

@@ -9,7 +9,7 @@ import jwt, { JwtPayload, SignOptions, VerifyOptions } from 'jsonwebtoken';
 import { ApiModule } from './api-module.js';
 import type { ApiAuthClass, ApiKey } from './api-module.js';
 import type { AuthProviderModule } from './auth-module.js';
-import type { AuthStorage, AuthTokenData, AuthTokenMetadata } from './auth-storage.js';
+import type { AuthStorage, AuthIdentifier, AuthTokenData, AuthTokenMetadata } from './auth-storage.js';
 export type { Application, Request, Response, NextFunction, Router } from 'express';
 export type { Multer } from 'multer';
 export type { JwtPayload, SignOptions, VerifyOptions } from 'jsonwebtoken';
@@ -49,9 +49,12 @@ export interface ApiRequest {
     authToken?: AuthTokenData | null;
     apiKey?: ApiKey | null;
     clientInfo?: ClientInfo;
+    realUid?: AuthIdentifier | null;
     getClientInfo: () => ClientInfo;
     getClientIp: () => string | null;
     getClientIpChain: () => string[];
+    getRealUid: () => AuthIdentifier | null;
+    isImpersonating: () => boolean;
 }
 export interface ClientAgentProfile {
     ua: string;
@@ -148,6 +151,9 @@ export declare class ApiServer {
     private requiresAuthToken;
     private shouldValidateStoredToken;
     private assertStoredAccessToken;
+    private normalizeAuthIdentifier;
+    private extractTokenUserId;
+    private resolveRealUserId;
     private handle_request;
     api<T extends ApiModule<any>>(module: T): this;
     dumpRequest(apiReq: ApiRequest): void;

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

@@ -580,6 +580,7 @@ export class ApiServer {
     }
     async authenticate(apiReq, authType) {
         if (authType === 'none') {
+            apiReq.realUid = null;
             return null;
         }
         let token = null;
@@ -592,15 +593,14 @@ export class ApiServer {
         if (authHeader?.startsWith('Bearer ')) {
             token = authHeader.slice(7).trim();
         }
-        else if (requiresAuthToken && !authHeader) {
-            throw new ApiError({ code: 401, message: 'Authorization header is missing or invalid' });
-        }
-        if (!token || token === null) {
+        if (!token) {
             const access = apiReq.req.cookies?.dat;
             if (access) {
                 token = access;
             }
-            else if (requiresAuthToken) {
+        }
+        if (!token || token === null) {
+            if (requiresAuthToken) {
                 throw new ApiError({ code: 401, message: 'Authorization token is required (Bearer/cookie)' });
             }
         }
@@ -616,6 +616,8 @@ export class ApiServer {
         if (!tokenData) {
             throw new ApiError({ code: 401, message: 'Unathorized Access - ' + error });
         }
+        const effectiveUserId = this.extractTokenUserId(tokenData);
+        apiReq.realUid = this.resolveRealUserId(tokenData, effectiveUserId);
         if (this.shouldValidateStoredToken(authType)) {
             await this.assertStoredAccessToken(apiReq, token, tokenData);
         }
@@ -658,10 +660,7 @@ export class ApiServer {
         return this.config.validateTokens || authType === 'strict';
     }
     async assertStoredAccessToken(apiReq, token, tokenData) {
-        if (typeof tokenData.uid !== 'string' && typeof tokenData.uid !== 'number') {
-            throw new ApiError({ code: 401, message: 'Authorization token is malformed' });
-        }
-        const userId = tokenData.uid;
+        const userId = this.extractTokenUserId(tokenData);
         const stored = await this.storageAdapter.getToken({
             accessToken: token,
             userId
@@ -671,6 +670,36 @@ export class ApiServer {
         }
         apiReq.authToken = stored;
     }
+    normalizeAuthIdentifier(candidate) {
+        if (typeof candidate === 'number' && Number.isFinite(candidate)) {
+            return candidate;
+        }
+        if (typeof candidate === 'string') {
+            const trimmed = candidate.trim();
+            if (trimmed.length > 0) {
+                return trimmed;
+            }
+        }
+        return null;
+    }
+    extractTokenUserId(tokenData) {
+        const normalized = this.normalizeAuthIdentifier(tokenData.uid);
+        if (normalized === null) {
+            throw new ApiError({ code: 401, message: 'Authorization token is malformed' });
+        }
+        return normalized;
+    }
+    resolveRealUserId(tokenData, effectiveUserId) {
+        const withReal = tokenData;
+        const rawReal = this.normalizeAuthIdentifier(withReal.ruid);
+        if (rawReal === null) {
+            return effectiveUserId;
+        }
+        if (typeof rawReal === 'number' && rawReal === 0) {
+            return effectiveUserId;
+        }
+        return rawReal;
+    }
     handle_request(handler, auth) {
         return async (req, res, next) => {
             void next;
@@ -680,9 +709,22 @@ export class ApiServer {
                 res,
                 token: '',
                 tokenData: null,
+                realUid: null,
                 getClientInfo: () => ensureClientInfo(apiReq),
                 getClientIp: () => ensureClientInfo(apiReq).ip,
-                getClientIpChain: () => ensureClientInfo(apiReq).ipchain
+                getClientIpChain: () => ensureClientInfo(apiReq).ipchain,
+                getRealUid: () => apiReq.realUid ?? null,
+                isImpersonating: () => {
+                    const realUid = apiReq.realUid;
+                    const tokenUid = apiReq.tokenData?.uid;
+                    if (realUid === null || realUid === undefined) {
+                        return false;
+                    }
+                    if (tokenUid === null || tokenUid === undefined) {
+                        return false;
+                    }
+                    return realUid !== tokenUid;
+                }
             };
             this.currReq = apiReq;
             try {

package/dist/esm/auth-storage.d.ts

@@ -1,5 +1,6 @@
 export type AuthIdentifier = string | number;
 export interface AuthTokenMetadata {
+    ruid?: AuthIdentifier;
     clientId?: string;
     domain?: string;
     fingerprint?: string;
@@ -101,6 +102,10 @@ export interface AuthStorage<UserRow, SafeUser> {
     verifyClientSecret?(client: OAuthClient, clientSecret: string | null): Promise<boolean>;
     createAuthCode?(request: AuthCodeRequest): Promise<AuthCodeData>;
     consumeAuthCode?(code: string, clientId: string): Promise<AuthCodeData | null>;
+    canImpersonate?(params: {
+        realUserId: AuthIdentifier;
+        effectiveUserId: AuthIdentifier;
+    }): Promise<boolean>;
 }
 export declare class BaseAuthStorage<UserRow = unknown, SafeUser = unknown> implements AuthStorage<UserRow, SafeUser> {
     getUser(identifier: AuthIdentifier): Promise<UserRow | null>;
@@ -120,5 +125,9 @@ export declare class BaseAuthStorage<UserRow = unknown, SafeUser = unknown> impl
     verifyClientSecret(client: OAuthClient, clientSecret: string | null): Promise<boolean>;
     createAuthCode(request: AuthCodeRequest): Promise<AuthCodeData>;
     consumeAuthCode(code: string, clientId: string): Promise<AuthCodeData | null>;
+    canImpersonate(params: {
+        realUserId: AuthIdentifier;
+        effectiveUserId: AuthIdentifier;
+    }): Promise<boolean>;
 }
 export declare const nullAuthStorage: AuthStorage<unknown, unknown>;

package/dist/esm/auth-storage.js

@@ -79,5 +79,10 @@ export class BaseAuthStorage {
         void clientId;
         return null;
     }
+    // Override to decide if a real user may impersonate another user
+    async canImpersonate(params) {
+        void params;
+        return false;
+    }
 }
 export const nullAuthStorage = new BaseAuthStorage();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@technomoron/api-server-base",
-	"version": "1.1.9",
+	"version": "1.1.11",
 	"description": "Api Server Skeleton / Base Class",
 	"type": "module",
 	"main": "./dist/cjs/index.cjs",