@technomoron/api-server-base 1.1.13 → 2.0.0-beta.10

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

@@ -4,49 +4,40 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { Application, Request, Response } from 'express';
-import jwt, { JwtPayload, SignOptions, VerifyOptions } from 'jsonwebtoken';
+import { Application, Request, Response, type ErrorRequestHandler, type RequestHandler } from 'express';
 import { ApiModule } from './api-module.js';
-import type { ApiAuthClass, ApiKey } from './api-module.js';
-import type { AuthProviderModule } from './auth-module.js';
-import type { AuthStorage, AuthIdentifier, AuthTokenData, AuthTokenMetadata } from './auth-storage.js';
+import { TokenStore, type JwtDecodeResult, type JwtSignResult, type JwtVerifyResult } from './token/base.js';
+import type { ApiAuthClass, ApiAuthType, ApiKey } from './api-module.js';
+import type { AuthProviderModule } from './auth-api/module.js';
+import type { AuthAdapter, AuthIdentifier } from './auth-api/types.js';
+import type { OAuthStore } from './oauth/base.js';
+import type { AuthCodeData, AuthCodeRequest, OAuthClient } from './oauth/types.js';
+import type { PasskeyService } from './passkey/service.js';
+import type { PasskeyChallenge, PasskeyChallengeParams, StoredPasskeyCredential, PasskeyVerificationParams, PasskeyVerificationResult } from './passkey/types.js';
+import type { Token } from './token/types.js';
+import type { UserStore } from './user/base.js';
+import type { JwtPayload, SignOptions, VerifyOptions } from 'jsonwebtoken';
 export type { Application, Request, Response, NextFunction, Router } from 'express';
 export type { Multer } from 'multer';
 export type { JwtPayload, SignOptions, VerifyOptions } from 'jsonwebtoken';
-export interface RequestWithStuff extends Request {
+export interface ExtendedReq extends Request {
     file?: Express.Multer.File;
     files?: Express.Multer.File[] | {
         [fieldname: string]: Express.Multer.File[];
     };
 }
-interface JwtSignResult {
-    success: boolean;
-    token?: string;
-    error?: string;
-}
-interface JwtVerifyResult<T> {
-    success: boolean;
-    data?: T;
-    expired?: boolean;
-    error?: string;
-}
-interface JwtDecodeResult<T> {
-    success: boolean;
-    data?: T;
-    error?: string;
-}
-export interface ApiTokenData extends JwtPayload, AuthTokenMetadata {
+export interface ApiTokenData extends JwtPayload, Partial<Token> {
     uid: unknown;
     iat?: number;
     exp?: number;
 }
 export interface ApiRequest {
     server: any;
-    req: RequestWithStuff;
+    req: ExtendedReq;
     res: Response;
     tokenData?: ApiTokenData | null;
     token?: string;
-    authToken?: AuthTokenData | null;
+    authToken?: Token | null;
     apiKey?: ApiKey | null;
     clientInfo?: ClientInfo;
     realUid?: AuthIdentifier | null;
@@ -56,6 +47,12 @@ export interface ApiRequest {
     getRealUid: () => AuthIdentifier | null;
     isImpersonating: () => boolean;
 }
+export interface ExpressApiRequest extends ExtendedReq {
+    apiReq?: ApiRequest;
+}
+export interface ExpressApiLocals {
+    apiReq?: ApiRequest;
+}
 export interface ClientAgentProfile {
     ua: string;
     browser: string;
@@ -66,6 +63,16 @@ export interface ClientInfo extends ClientAgentProfile {
     ip: string | null;
     ipchain: string[];
 }
+export interface ApiServerAuthStores {
+    userStore: UserStore<any, any>;
+    tokenStore: TokenStore;
+    passkeyService?: PasskeyService;
+    oauthStore?: OAuthStore;
+    canImpersonate?: (params: {
+        realUserId: AuthIdentifier;
+        effectiveUserId: AuthIdentifier;
+    }) => boolean | Promise<boolean>;
+}
 export { ApiModule } from './api-module.js';
 export type { ApiHandler, ApiAuthType, ApiAuthClass, ApiRoute, ApiKey } from './api-module.js';
 export interface ApiErrorParams {
@@ -100,8 +107,11 @@ export interface ApiServerConf {
     devMode: boolean;
     hydrateGetBody: boolean;
     validateTokens: boolean;
+    refreshMaybe: boolean;
     apiVersion: string;
     minClientVersion: string;
+    tokenStore?: TokenStore;
+    authStores?: ApiServerAuthStores;
 }
 export declare class ApiServer {
     app: Application;
@@ -112,33 +122,69 @@ export declare class ApiServer {
     private storageAdapter;
     private moduleAdapter;
     private apiNotFoundHandler;
+    private tokenStoreAdapter;
+    private userStoreAdapter;
+    private passkeyServiceAdapter;
+    private oauthStoreAdapter;
+    private canImpersonateAdapter;
+    private readonly jwtHelper;
     constructor(config?: Partial<ApiServerConf>);
-    authStorage<UserRow, SafeUser>(storage: AuthStorage<UserRow, SafeUser>): this;
+    authStorage<UserRow, SafeUser>(storage: AuthAdapter<UserRow, SafeUser>): this;
     /**
      * @deprecated Use {@link ApiServer.authStorage} instead.
      */
-    useAuthStorage<UserRow, SafeUser>(storage: AuthStorage<UserRow, SafeUser>): this;
+    useAuthStorage<UserRow, SafeUser>(storage: AuthAdapter<UserRow, SafeUser>): this;
     authModule<UserRow>(module: AuthProviderModule<UserRow>): this;
     /**
      * @deprecated Use {@link ApiServer.authModule} instead.
      */
     useAuthModule<UserRow>(module: AuthProviderModule<UserRow>): this;
-    getAuthStorage(): AuthStorage<any, any>;
+    getAuthStorage(): AuthAdapter<any, any>;
     getAuthModule(): AuthProviderModule<any>;
+    setTokenStore(store: TokenStore): this;
+    getTokenStore(): TokenStore | null;
+    private ensureUserStore;
+    private ensureTokenStore;
+    private ensurePasskeyService;
+    listUserCredentials(userId: AuthIdentifier): Promise<StoredPasskeyCredential[]>;
+    deletePasskeyCredential(credentialId: Buffer | string): Promise<boolean>;
+    private ensureOAuthStore;
+    getUser(identifier: AuthIdentifier): Promise<any | null>;
+    getUserPasswordHash(user: any): string;
+    getUserId(user: any): AuthIdentifier;
+    filterUser(user: any): any;
+    verifyPassword(password: string, hash: string): Promise<boolean>;
+    storeToken(data: Token): Promise<void>;
+    getToken(query: Partial<Token> & {
+        userId?: AuthIdentifier;
+        ruid?: AuthIdentifier;
+    }, opts?: {
+        includeExpired?: boolean;
+    }): Promise<Token | null>;
+    deleteToken(query: Partial<Token> & {
+        userId?: AuthIdentifier;
+        ruid?: AuthIdentifier;
+    }): Promise<number>;
+    createPasskeyChallenge(params: PasskeyChallengeParams): Promise<PasskeyChallenge>;
+    verifyPasskeyResponse(params: PasskeyVerificationParams): Promise<PasskeyVerificationResult>;
+    getClient(clientId: string): Promise<OAuthClient | null>;
+    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>;
     jwtSign(payload: any, secret: string, expiresInSeconds: number, options?: SignOptions): JwtSignResult;
     jwtVerify<T>(token: string, secret: string, options?: VerifyOptions): JwtVerifyResult<T>;
-    jwtDecode<T>(token: string, options?: jwt.DecodeOptions): JwtDecodeResult<T>;
+    jwtDecode<T>(token: string, options?: import('jsonwebtoken').DecodeOptions): JwtDecodeResult<T>;
     getApiKey<T = ApiKey>(token: string): Promise<T | null>;
     authenticateUser(params: {
         login: string;
         password: string;
     }): Promise<boolean>;
-    updateToken(updates: {
-        accessToken: string;
+    updateToken(updates: Partial<Token> & {
         refreshToken: string;
-        expires?: Date;
-        clientId?: string;
-        scope?: string[];
     }): Promise<boolean>;
     guessExceptionText(error: any, defMsg?: string): string;
     protected authorize(apiReq: ApiRequest, requiredClass: ApiAuthClass): Promise<void>;
@@ -150,6 +196,9 @@ export declare class ApiServer {
     private describeMissingEndpoint;
     start(): this;
     private verifyJWT;
+    private jwtCookieOptions;
+    private setAccessCookie;
+    private tryRefreshAccessToken;
     private authenticate;
     private tryAuthenticateApiKey;
     private requiresAuthToken;
@@ -158,6 +207,14 @@ export declare class ApiServer {
     private normalizeAuthIdentifier;
     private extractTokenUserId;
     private resolveRealUserId;
+    useExpress(path: string, ...handlers: Array<RequestHandler | ErrorRequestHandler>): this;
+    useExpress(...handlers: Array<RequestHandler | ErrorRequestHandler>): this;
+    private createApiRequest;
+    expressAuth(auth: {
+        type: ApiAuthType;
+        req: ApiAuthClass;
+    }): RequestHandler;
+    expressErrorHandler(): ErrorRequestHandler;
     private handle_request;
     api<T extends ApiModule<any>>(module: T): this;
     dumpRequest(apiReq: ApiRequest): void;

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

@@ -0,0 +1,105 @@
+import { type ApiRequest, type ApiRoute, type ApiServer } from '../api-server-base.js';
+import { BaseAuthModule, type AuthProviderModule } from './module.js';
+import type { AuthAdapter, AuthIdentifier } from './types.js';
+import type { OAuthCallbackParams, OAuthCallbackResult, OAuthStartParams, OAuthStartResult } from '../oauth/types.js';
+import type { TokenPair, Token } from '../token/types.js';
+interface CanImpersonateContext<UserEntity> {
+    apiReq: ApiRequest;
+    realUser: UserEntity;
+    realUserId: AuthIdentifier;
+    targetUser: UserEntity;
+    effectiveUserId: AuthIdentifier;
+}
+interface AuthModuleOptions<UserEntity> {
+    namespace?: string;
+    defaultDomain?: string;
+    canImpersonate?: (context: CanImpersonateContext<UserEntity>) => Promise<boolean> | boolean;
+}
+type TokenMetadata = Partial<Token> & {
+    sessionCookie?: boolean;
+};
+interface TokenIssueOptions extends TokenMetadata {
+    expires?: Date;
+    sessionCookie?: boolean;
+}
+interface NormalizedTokenMetadata extends TokenMetadata {
+    domain: string;
+    fingerprint: string;
+    label: string;
+    browser: string;
+    device: string;
+    ip: string;
+    os: string;
+}
+type TokenClaims = TokenMetadata & {
+    uid: string;
+    exp?: number;
+    iat?: number;
+};
+type AuthCapableServer<PublicUser> = ApiServer & {
+    initiateOAuth?: (params: OAuthStartParams) => Promise<OAuthStartResult>;
+    completeOAuth?: (params: OAuthCallbackParams) => Promise<OAuthCallbackResult<PublicUser>>;
+};
+export default class AuthModule<UserEntity, PublicUser> extends BaseAuthModule<UserEntity> implements AuthProviderModule<UserEntity> {
+    static defaultNamespace: string;
+    server: AuthCapableServer<PublicUser>;
+    private readonly defaultDomain?;
+    private readonly canImpersonateHook?;
+    constructor(options?: AuthModuleOptions<UserEntity>);
+    protected get storage(): AuthAdapter<UserEntity, PublicUser>;
+    protected canImpersonate(apiReq: ApiRequest, realUser: UserEntity, targetUser: UserEntity): Promise<boolean>;
+    protected ensureImpersonationAllowed(apiReq: ApiRequest, realUser: UserEntity, targetUser: UserEntity): Promise<void>;
+    protected buildTokenPayload(user: UserEntity, metadata?: TokenMetadata): TokenClaims;
+    protected buildTokenMetadata(metadata?: TokenMetadata): NormalizedTokenMetadata;
+    protected enrichTokenMetadata(apiReq: ApiRequest, metadata?: TokenMetadata): TokenMetadata;
+    private sessionRefreshTtlSeconds;
+    private normalizeRefreshTtlSeconds;
+    private resolveSessionPreferences;
+    private mergeSessionPreferences;
+    private sessionPrefsFromRecord;
+    private validateCredentialId;
+    private normalizeCredentialId;
+    private toIsoDate;
+    private cookieOptions;
+    private setJwtCookies;
+    issueTokens(apiReq: ApiRequest, user: UserEntity, metadata?: TokenIssueOptions): Promise<TokenPair>;
+    private assertAuthReady;
+    private parseLoginBody;
+    private parseImpersonationRequest;
+    private resolveImpersonationIdentifier;
+    private buildImpersonationMetadata;
+    private getUserOrThrow;
+    private getRealUserIdentifier;
+    private resolveActorContext;
+    private extractRefreshToken;
+    private normalizeScope;
+    private postLogin;
+    private postRefresh;
+    private postLogout;
+    private postWhoAmI;
+    private postPasskeyChallenge;
+    private postPasskeyVerify;
+    private getPasskeys;
+    private deletePasskey;
+    private postImpersonation;
+    private deleteImpersonation;
+    private getUserFromPasskey;
+    private postOAuthStart;
+    private postOAuthCallback;
+    private postOAuthAuthorize;
+    private postOAuthToken;
+    private handleAuthorizationCodeGrant;
+    private handleRefreshTokenGrant;
+    private clearOAuthCookies;
+    private buildTokenResponse;
+    private resolveScope;
+    private resolveClientAuthentication;
+    private assertRedirectUriAllowed;
+    private resolveUserForOAuth;
+    private hasPasskeyService;
+    private hasOAuthStore;
+    private storageImplements;
+    private storageImplementsAll;
+    defineRoutes(): ApiRoute[];
+}
+export {};