@passflow/core 0.0.1 → 0.2.0

package/dist/lib/api/two-factor.d.ts

@@ -0,0 +1,75 @@
+import { DeviceService } from '../device';
+import { StorageManager } from '../storage';
+import { AxiosClient } from './axios-client';
+import { PassflowConfig, TwoFactorConfirmRequest, TwoFactorConfirmResponse, TwoFactorDisableRequest, TwoFactorDisableResponse, TwoFactorRecoveryRequest, TwoFactorRecoveryResponse, TwoFactorRegenerateRequest, TwoFactorRegenerateResponse, TwoFactorSetupMagicLinkValidationResponse, TwoFactorSetupResponse, TwoFactorStatusResponse, TwoFactorVerifyRequest, TwoFactorVerifyResponse } from './model';
+/**
+ * API client for Two-Factor Authentication operations
+ */
+export declare class TwoFactorApiClient {
+    protected axiosClient: AxiosClient;
+    constructor(config: PassflowConfig, storageManager?: StorageManager, deviceService?: DeviceService);
+    setAppId(appId: string): void;
+    /**
+     * Get current 2FA enrollment status
+     * GET /user/2fa/status
+     */
+    getStatus(): Promise<TwoFactorStatusResponse>;
+    /**
+     * Begin 2FA setup process
+     * POST /user/2fa/setup/begin
+     * Returns secret and QR code for authenticator app
+     */
+    beginSetup(): Promise<TwoFactorSetupResponse>;
+    /**
+     * Confirm 2FA setup with TOTP code
+     * POST /user/2fa/setup/confirm
+     * Returns recovery codes on success
+     */
+    confirmSetup(payload: TwoFactorConfirmRequest): Promise<TwoFactorConfirmResponse>;
+    /**
+     * Verify TOTP code during login
+     * POST /auth/2fa/verify
+     * Uses tfa_token as Bearer token for authentication
+     */
+    verify(payload: TwoFactorVerifyRequest): Promise<TwoFactorVerifyResponse>;
+    /**
+     * Use recovery code for authentication
+     * POST /auth/2fa/recovery
+     * Uses tfa_token as Bearer token for authentication
+     */
+    useRecoveryCode(payload: TwoFactorRecoveryRequest): Promise<TwoFactorRecoveryResponse>;
+    /**
+     * Disable 2FA (requires TOTP verification)
+     * DELETE /user/2fa
+     */
+    disable(payload: TwoFactorDisableRequest): Promise<TwoFactorDisableResponse>;
+    /**
+     * Regenerate recovery codes
+     * POST /user/2fa/recovery-codes/regenerate
+     */
+    regenerateRecoveryCodes(payload: TwoFactorRegenerateRequest): Promise<TwoFactorRegenerateResponse>;
+    /**
+     * Validate magic link token for 2FA setup
+     * GET /auth/2fa-setup/:token
+     *
+     * This endpoint validates an admin-generated magic link token
+     * and returns a scoped session (scope: "2fa_setup") that can ONLY
+     * be used for completing 2FA setup operations.
+     *
+     * This method never throws - it always returns a TwoFactorSetupMagicLinkValidationResponse
+     * with either success=true and session data, or success=false and error details.
+     *
+     * @param token - Magic link token from URL parameter
+     * @returns Validation response with scoped session token or error
+     */
+    validateTwoFactorSetupMagicLink(token: string): Promise<TwoFactorSetupMagicLinkValidationResponse>;
+    /**
+     * Map HTTP status code to magic link error code
+     */
+    private mapStatusToErrorCode;
+    /**
+     * Get default error message for HTTP status code
+     */
+    private getDefaultErrorMessage;
+}
+//# sourceMappingURL=two-factor.d.ts.map

package/dist/lib/api/two-factor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"two-factor.d.ts","sourceRoot":"","sources":["../../../lib/api/two-factor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EACL,cAAc,EAEd,uBAAuB,EACvB,wBAAwB,EACxB,uBAAuB,EACvB,wBAAwB,EACxB,wBAAwB,EACxB,yBAAyB,EACzB,0BAA0B,EAC1B,2BAA2B,EAE3B,yCAAyC,EACzC,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACxB,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,qBAAa,kBAAkB;IAC7B,SAAS,CAAC,WAAW,EAAE,WAAW,CAAC;gBAEvB,MAAM,EAAE,cAAc,EAAE,cAAc,CAAC,EAAE,cAAc,EAAE,aAAa,CAAC,EAAE,aAAa;IAIlG,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI7B;;;OAGG;IACH,SAAS,IAAI,OAAO,CAAC,uBAAuB,CAAC;IAI7C;;;;OAIG;IACH,UAAU,IAAI,OAAO,CAAC,sBAAsB,CAAC;IAI7C;;;;OAIG;IACH,YAAY,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAOjF;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAazE;;;;OAIG;IACH,eAAe,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,yBAAyB,CAAC;IAatF;;;OAGG;IACH,OAAO,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAI5E;;;OAGG;IACH,uBAAuB,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,2BAA2B,CAAC;IAOlG;;;;;;;;;;;;;OAaG;IACH,+BAA+B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,yCAAyC,CAAC;IA4DlG;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAe5B;;OAEG;IACH,OAAO,CAAC,sBAAsB;CAc/B"}

package/dist/lib/api/user.d.ts

@@ -1,9 +1,12 @@
 import { RegistrationResponseJSON } from '@simplewebauthn/types';
+import { DeviceService } from '../device';
+import { StorageManager } from '../storage';
 import { AxiosClient } from './axios-client';
 import { OS, PassflowConfig, PassflowPasskeyStart, PassflowSuccessResponse, PassflowUserPasskey } from './model';
 export declare class UserAPI {
     protected axiosClient: AxiosClient;
-    constructor(config: PassflowConfig);
+    constructor(config: PassflowConfig, storageManager?: StorageManager, deviceService?: DeviceService);
+    setAppId(appId: string): void;
     getUserPasskeys(): Promise<PassflowUserPasskey[]>;
     renameUserPasskey(name: string, passkeyId: string): Promise<PassflowSuccessResponse>;
     deleteUserPasskey(passkeyId: string): Promise<PassflowSuccessResponse>;

package/dist/lib/api/user.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../../../lib/api/user.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAEjE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EACL,EAAE,EACF,cAAc,EAGd,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACpB,MAAM,SAAS,CAAC;AAEjB,qBAAa,OAAO;IAClB,SAAS,CAAC,WAAW,EAAE,WAAW,CAAC;gBAEvB,MAAM,EAAE,cAAc;IAIlC,eAAe;IAIf,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC;IASpF,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAItE,mBAAmB,CAAC,EAClB,cAAc,EACd,QAAQ,EACR,EAAE,EACF,kBAAkB,EAClB,eAAe,GAChB,EAAE;QACD,cAAc,EAAE,MAAM,CAAC;QACvB,QAAQ,EAAE,MAAM,CAAC;QACjB,EAAE,EAAE,EAAE,CAAC;QACP,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAYjC,sBAAsB,CAAC,WAAW,EAAE,wBAAwB,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAOpH"}
+{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../../../lib/api/user.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAEjE,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EACL,EAAE,EACF,cAAc,EAGd,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACpB,MAAM,SAAS,CAAC;AAEjB,qBAAa,OAAO;IAClB,SAAS,CAAC,WAAW,EAAE,WAAW,CAAC;gBAEvB,MAAM,EAAE,cAAc,EAAE,cAAc,CAAC,EAAE,cAAc,EAAE,aAAa,CAAC,EAAE,aAAa;IAIlG,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI7B,eAAe;IAIf,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC;IASpF,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAItE,mBAAmB,CAAC,EAClB,cAAc,EACd,QAAQ,EACR,EAAE,EACF,kBAAkB,EAClB,eAAe,GAChB,EAAE;QACD,cAAc,EAAE,MAAM,CAAC;QACvB,QAAQ,EAAE,MAAM,CAAC;QACjB,EAAE,EAAE,EAAE,CAAC;QACP,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAYjC,sBAAsB,CAAC,WAAW,EAAE,wBAAwB,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAOpH"}

package/dist/lib/constants/index.d.ts

@@ -2,7 +2,32 @@ export declare const APP_ID_HEADER_KEY = "X-Passflow-Clientid";
 export declare const AUTHORIZATION_HEADER_KEY = "Authorization";
 export declare const DEVICE_ID_HEADER_KEY = "X-Passflow-DeviceId";
 export declare const DEVICE_TYPE_HEADER_KEY = "X-Passflow-DeviceType";
+/**
+ * SDK version from package.json.
+ * Useful for debugging and logging version information.
+ */
+export declare const SDK_VERSION: string;
+/**
+ * Minimal set of scopes for basic authentication.
+ * Includes only essential scopes: user ID, token refresh, and OpenID Connect.
+ * Use this for applications that need minimal permissions.
+ */
+export declare const MINIMAL_DEFAULT_SCOPES: string[];
+/**
+ * Default scopes used by the SDK.
+ * Includes comprehensive permissions: user ID, token refresh, tenant access, email, OIDC, and full tenant access.
+ * Note: 'access:tenant:all' is a very permissive scope and may not be appropriate for all applications.
+ * Consider using MINIMAL_DEFAULT_SCOPES or custom scopes for production applications.
+ */
 export declare const DEFAULT_SCOPES: string[];
 export declare const PASSFLOW_CLOUD_URL = "https://auth.passflow.cloud";
 export declare const DEFAULT_GROUP_NAME = "default";
+export declare const POPUP_WIDTH = 500;
+export declare const POPUP_HEIGHT = 600;
+export declare const POPUP_POLL_INTERVAL_MS = 100;
+export declare const POPUP_TIMEOUT_MS = 60000;
+export declare const TOKEN_EXPIRY_BUFFER_SECONDS = 30;
+export declare const USERNAME_MIN_LENGTH = 3;
+export declare const USERNAME_MAX_LENGTH = 30;
+export declare const ERROR_MESSAGE_MAX_LENGTH = 200;
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/constants/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/constants/index.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,wBAAwB,CAAC;AACvD,eAAO,MAAM,wBAAwB,kBAAkB,CAAC;AACxD,eAAO,MAAM,oBAAoB,wBAAwB,CAAC;AAC1D,eAAO,MAAM,sBAAsB,0BAA0B,CAAC;AAC9D,eAAO,MAAM,cAAc,UAA8E,CAAC;AAC1G,eAAO,MAAM,kBAAkB,gCAAgC,CAAC;AAChE,eAAO,MAAM,kBAAkB,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/constants/index.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,iBAAiB,wBAAwB,CAAC;AACvD,eAAO,MAAM,wBAAwB,kBAAkB,CAAC;AACxD,eAAO,MAAM,oBAAoB,wBAAwB,CAAC;AAC1D,eAAO,MAAM,sBAAsB,0BAA0B,CAAC;AAE9D;;;GAGG;AACH,eAAO,MAAM,WAAW,EAA0B,MAAM,CAAC;AAEzD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,UAA8B,CAAC;AAElE;;;;;GAKG;AACH,eAAO,MAAM,cAAc,UAA8E,CAAC;AAE1G,eAAO,MAAM,kBAAkB,gCAAgC,CAAC;AAChE,eAAO,MAAM,kBAAkB,YAAY,CAAC;AAG5C,eAAO,MAAM,WAAW,MAAM,CAAC;AAC/B,eAAO,MAAM,YAAY,MAAM,CAAC;AAChC,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAC1C,eAAO,MAAM,gBAAgB,QAAQ,CAAC;AAGtC,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAG9C,eAAO,MAAM,mBAAmB,IAAI,CAAC;AACrC,eAAO,MAAM,mBAAmB,KAAK,CAAC;AACtC,eAAO,MAAM,wBAAwB,MAAM,CAAC"}

package/dist/lib/device/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Device Service
+ *
+ * Manages device identification for security and tracking purposes.
+ * Generates and persists unique device IDs using UUID v4.
+ * Used for device-based authentication and session management.
+ *
+ * @module device
+ */
+import { StorageManager } from '../storage';
+export declare class DeviceService {
+    private storageManager;
+    constructor(storageManager?: StorageManager);
+    getDeviceId(): string;
+    generateUniqueDeviceId(): string;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/device/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/device/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,qBAAa,aAAa;IACxB,OAAO,CAAC,cAAc,CAAiB;gBAE3B,cAAc,CAAC,EAAE,cAAc;IAI3C,WAAW,IAAI,MAAM;IAUrB,sBAAsB,IAAI,MAAM;CAGjC"}

package/dist/lib/index.d.ts

@@ -1,8 +1,15 @@
 export * from './api';
 export * from './constants';
-export * from './types';
-export { PassflowEvent, type PassflowSubscriber, type ErrorPayload, type PassflowEventPayload } from './store';
-export { isTokenExpired, parseToken, TokenType, type InvitationToken, type Token, type UserMembership, type TenantMembership, type GroupMembership, type Tenant, type Group, type RawUserMembership, } from './token-service';
 export { Passflow } from './passflow';
 export * from './services';
+export { type ErrorPayload, PassflowEvent, type PassflowEventPayload, type PassflowSubscriber } from './store';
+export { type Group, type GroupMembership, type InvitationToken, isTokenExpired, parseToken, type RawUserMembership, type Tenant, type TenantMembership, type Token, TokenType, type UserMembership, } from './token';
+export * from './types';
+export { isValidEmail, isValidJWTFormat, isValidPhoneNumber, isValidUsername, sanitizeErrorMessage } from './utils/validation';
+export type { TwoFactorConfirmRequest, TwoFactorConfirmResponse, TwoFactorDisableRequest, TwoFactorDisableResponse, TwoFactorErrorCode, TwoFactorPolicy, TwoFactorRecoveryRequest, TwoFactorRecoveryResponse, TwoFactorRegenerateRequest, TwoFactorRegenerateResponse, TwoFactorSetupMagicLinkError, TwoFactorSetupMagicLinkErrorCode, TwoFactorSetupMagicLinkSession, TwoFactorSetupMagicLinkValidationResponse, TwoFactorSetupResponse, TwoFactorStatusResponse, TwoFactorVerifyRequest, TwoFactorVerifyResponse, } from './api/model';
+export { TwoFactorApiClient } from './api/two-factor';
+export { TwoFactorService } from './services/two-factor-service';
+export { M2MClient, M2MError, M2MNetworkError, M2MTokenParseError, M2MConfigError, M2MErrorCodes, M2M_DEFAULTS } from './m2m';
+export type { M2MClientConfig, M2MTokenRequestOptions, M2MTokenRequestInfo, M2MTokenResponse, M2MErrorResponse, M2MTokenClaims, M2MErrorCode, M2MTokenCache, RetryStrategy, M2MRateLimitInfo, } from './m2m';
+export { TokenDeliveryMode, SessionState } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/index.ts"],"names":[],"mappings":"AACA,cAAc,OAAO,CAAC;AAGtB,cAAc,aAAa,CAAC;AAG5B,cAAc,SAAS,CAAC;AAGxB,OAAO,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,KAAK,YAAY,EAAE,KAAK,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAG/G,OAAO,EACL,cAAc,EACd,UAAU,EACV,SAAS,EACT,KAAK,eAAe,EACpB,KAAK,KAAK,EACV,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,MAAM,EACX,KAAK,KAAK,EACV,KAAK,iBAAiB,GACvB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGtC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/index.ts"],"names":[],"mappings":"AACA,cAAc,OAAO,CAAC;AAGtB,cAAc,aAAa,CAAC;AAE5B,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,cAAc,YAAY,CAAC;AAE3B,OAAO,EAAE,KAAK,YAAY,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAE/G,OAAO,EACL,KAAK,KAAK,EACV,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,cAAc,EACd,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,MAAM,EACX,KAAK,gBAAgB,EACrB,KAAK,KAAK,EACV,SAAS,EACT,KAAK,cAAc,GACpB,MAAM,SAAS,CAAC;AAEjB,cAAc,SAAS,CAAC;AAExB,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAG/H,YAAY,EACV,uBAAuB,EACvB,wBAAwB,EACxB,uBAAuB,EACvB,wBAAwB,EACxB,kBAAkB,EAClB,eAAe,EACf,wBAAwB,EACxB,yBAAyB,EACzB,0BAA0B,EAC1B,2BAA2B,EAC3B,4BAA4B,EAC5B,gCAAgC,EAChC,8BAA8B,EAC9B,yCAAyC,EACzC,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGjE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,eAAe,EAAE,kBAAkB,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAC9H,YAAY,EACV,eAAe,EACf,sBAAsB,EACtB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,aAAa,EACb,gBAAgB,GACjB,MAAM,OAAO,CAAC;AAGf,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC"}

package/dist/lib/m2m/client.d.ts

@@ -0,0 +1,196 @@
+/**
+ * M2M (Machine-to-Machine) Authentication Client
+ *
+ * OAuth 2.0 Client Credentials Grant implementation for server-to-server
+ * authentication without user involvement.
+ *
+ * @example
+ * ```typescript
+ * const m2m = new M2MClient({
+ *   url: 'https://auth.yourapp.com',
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ *   scopes: ['users:read', 'orders:write'],
+ * });
+ *
+ * const token = await m2m.getToken();
+ * ```
+ */
+import type { M2MClientConfig, M2MTokenClaims, M2MTokenRequestOptions, M2MTokenResponse } from './types';
+/**
+ * M2M Authentication Client
+ *
+ * Implements OAuth 2.0 Client Credentials Grant for machine-to-machine
+ * authentication. Provides automatic token caching, refresh, and retry logic.
+ */
+export declare class M2MClient {
+    private readonly config;
+    private readonly cache;
+    private readonly retryStrategy;
+    private readonly tokenEndpoint;
+    /**
+     * Create a new M2M client
+     *
+     * @param config - Client configuration
+     * @throws {M2MConfigError} If required configuration is missing
+     *
+     * @example
+     * ```typescript
+     * const m2m = new M2MClient({
+     *   url: 'https://auth.yourapp.com',
+     *   clientId: 'your-client-id',
+     *   clientSecret: 'your-client-secret',
+     * });
+     * ```
+     */
+    constructor(config: M2MClientConfig);
+    /**
+     * Get the cache key for this client
+     */
+    private getCacheKey;
+    /**
+     * Request an access token from the authorization server
+     *
+     * @param options - Optional request overrides
+     * @returns Token response
+     * @throws {M2MError} On authentication failure
+     *
+     * @example
+     * ```typescript
+     * // Basic usage
+     * const token = await m2m.getToken();
+     *
+     * // With options
+     * const token = await m2m.getToken({
+     *   scopes: ['users:read'],
+     *   forceRefresh: true,
+     * });
+     * ```
+     */
+    getToken(options?: M2MTokenRequestOptions): Promise<M2MTokenResponse>;
+    /**
+     * Get a valid token, automatically refreshing if needed
+     *
+     * When autoRefresh is enabled, this will proactively refresh tokens
+     * that are about to expire (within refreshThreshold seconds).
+     *
+     * @returns Valid token response
+     * @throws {M2MError} On authentication failure
+     *
+     * @example
+     * ```typescript
+     * // Always returns a valid, non-expired token
+     * const token = await m2m.getValidToken();
+     * ```
+     */
+    getValidToken(): Promise<M2MTokenResponse>;
+    /**
+     * Request a new token from the authorization server
+     */
+    private requestToken;
+    /**
+     * Execute the actual HTTP request to the token endpoint
+     */
+    private doTokenRequest;
+    /**
+     * Execute a request with retry logic
+     */
+    private executeWithRetry;
+    /**
+     * Sleep for a given duration
+     */
+    private sleep;
+    /**
+     * Get the currently cached token without making a request
+     *
+     * @returns Cached token or null if not cached
+     *
+     * @example
+     * ```typescript
+     * const token = m2m.getCachedToken();
+     * if (token && !m2m.isTokenExpired(token)) {
+     *   console.log('Using cached token');
+     * }
+     * ```
+     */
+    getCachedToken(): M2MTokenResponse | null;
+    /**
+     * Check if a token is expired or about to expire
+     *
+     * @param token - Token to check (uses issued_at + expires_in if available)
+     * @param threshold - Seconds before actual expiry to consider expired (default: 0)
+     * @returns true if expired or about to expire
+     *
+     * @example
+     * ```typescript
+     * if (m2m.isTokenExpired(token)) {
+     *   console.log('Token is expired');
+     * }
+     *
+     * // Check if expiring within 5 minutes
+     * if (m2m.isTokenExpired(token, 300)) {
+     *   console.log('Token expires soon');
+     * }
+     * ```
+     */
+    isTokenExpired(token?: M2MTokenResponse | null, threshold?: number): boolean;
+    /**
+     * Parse token claims from a JWT access token
+     *
+     * @param token - JWT access token string
+     * @returns Decoded token claims
+     * @throws {M2MTokenParseError} If token format is invalid
+     *
+     * @example
+     * ```typescript
+     * const token = await m2m.getToken();
+     * const claims = m2m.parseToken(token.access_token);
+     * console.log('Client ID:', claims.client_id);
+     * console.log('Scopes:', claims.scopes);
+     * ```
+     */
+    parseToken(token: string): M2MTokenClaims;
+    /**
+     * Clear the token cache, forcing a new request on next getToken()
+     *
+     * @example
+     * ```typescript
+     * m2m.clearCache();
+     * // Next getToken() will request a new token
+     * const token = await m2m.getToken();
+     * ```
+     */
+    clearCache(): void;
+    /**
+     * Revoke the current token
+     *
+     * Note: Requires the server to support token revocation (RFC 7009).
+     * Not all Passflow deployments may support this endpoint.
+     *
+     * @throws {M2MError} If revocation fails
+     *
+     * @example
+     * ```typescript
+     * await m2m.revokeToken();
+     * console.log('Token revoked');
+     * ```
+     */
+    revokeToken(): Promise<void>;
+    /**
+     * Get the configured URL
+     */
+    get url(): string;
+    /**
+     * Get the configured client ID
+     */
+    get clientId(): string;
+    /**
+     * Get the configured scopes
+     */
+    get scopes(): string[] | undefined;
+    /**
+     * Get the configured audience
+     */
+    get audience(): string[] | undefined;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/lib/m2m/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../lib/m2m/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EACV,eAAe,EAGf,cAAc,EACd,sBAAsB,EAEtB,gBAAgB,EAEjB,MAAM,SAAS,CAAC;AAwDjB;;;;;GAKG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAMnB;IAEJ,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IAEvC;;;;;;;;;;;;;;OAcG;gBACS,MAAM,EAAE,eAAe;IAsCnC;;OAEG;IACH,OAAO,CAAC,WAAW;IAMnB;;;;;;;;;;;;;;;;;;OAkBG;IACG,QAAQ,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAiB3E;;;;;;;;;;;;;;OAcG;IACG,aAAa,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAwBhD;;OAEG;YACW,YAAY;IA6C1B;;OAEG;YACW,cAAc;IAqF5B;;OAEG;YACW,gBAAgB;IA8B9B;;OAEG;IACH,OAAO,CAAC,KAAK;IAIb;;;;;;;;;;;;OAYG;IACH,cAAc,IAAI,gBAAgB,GAAG,IAAI;IAczC;;;;;;;;;;;;;;;;;;OAkBG;IACH,cAAc,CAAC,KAAK,CAAC,EAAE,gBAAgB,GAAG,IAAI,EAAE,SAAS,SAAI,GAAG,OAAO;IAUvE;;;;;;;;;;;;;;OAcG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc;IAgCzC;;;;;;;;;OASG;IACH,UAAU,IAAI,IAAI;IAKlB;;;;;;;;;;;;;OAaG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IA4ClC;;OAEG;IACH,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,EAAE,GAAG,SAAS,CAEjC;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,MAAM,EAAE,GAAG,SAAS,CAEnC;CACF"}

package/dist/lib/m2m/errors.d.ts

@@ -0,0 +1,107 @@
+/**
+ * M2M Authentication Error Classes
+ *
+ * Custom error classes for M2M authentication failures with
+ * OAuth 2.0 compliant error codes and detailed information.
+ */
+import type { M2MErrorCode, M2MRateLimitInfo } from './types';
+/**
+ * M2M Authentication Error
+ *
+ * Thrown when M2M authentication fails. Contains OAuth 2.0 compliant
+ * error codes and additional debugging information.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const token = await m2m.getToken();
+ * } catch (error) {
+ *   if (error instanceof M2MError) {
+ *     console.error(`Error: ${error.code} - ${error.message}`);
+ *     if (error.code === 'rate_limit_exceeded') {
+ *       console.log(`Retry after: ${error.rateLimitInfo?.reset}`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare class M2MError extends Error {
+    /** OAuth 2.0 error code */
+    readonly code: M2MErrorCode;
+    /** HTTP status code from the response */
+    readonly status: number;
+    /** URI with more information about the error (if provided) */
+    readonly errorUri?: string;
+    /** Rate limit information (if rate limited) */
+    readonly rateLimitInfo?: M2MRateLimitInfo;
+    /** Response headers from the server */
+    readonly headers?: Record<string, string>;
+    /** Original error (if this wraps another error) */
+    readonly cause?: Error;
+    /** Timestamp when the error occurred */
+    readonly timestamp: string;
+    constructor(options: {
+        code: M2MErrorCode;
+        message: string;
+        status?: number;
+        errorUri?: string;
+        rateLimitInfo?: M2MRateLimitInfo;
+        headers?: Record<string, string>;
+        cause?: Error;
+    });
+    /**
+     * Create an M2MError from an OAuth 2.0 error response
+     */
+    static fromOAuthError(errorResponse: {
+        error: M2MErrorCode;
+        error_description?: string;
+        error_uri?: string;
+    }, status: number, headers?: Record<string, string>): M2MError;
+    /**
+     * Create an M2MError from a network or other error
+     */
+    static fromError(error: Error, code?: M2MErrorCode): M2MError;
+    /**
+     * Parse rate limit headers from response
+     */
+    static parseRateLimitHeaders(headers: Record<string, string>): M2MRateLimitInfo | undefined;
+    /**
+     * Get default error message for an error code
+     */
+    static getDefaultMessage(code: M2MErrorCode): string;
+    /**
+     * Check if the error is retryable
+     */
+    isRetryable(): boolean;
+    /**
+     * Get suggested wait time before retry (in milliseconds)
+     */
+    getRetryAfter(): number;
+    /**
+     * Convert to JSON-serializable object
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Create a human-readable string representation
+     */
+    toString(): string;
+}
+/**
+ * Network error (connection failed, timeout, etc.)
+ */
+export declare class M2MNetworkError extends M2MError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Token parsing error (invalid JWT format)
+ */
+export declare class M2MTokenParseError extends M2MError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Configuration error (missing or invalid config)
+ */
+export declare class M2MConfigError extends M2MError {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/lib/m2m/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../lib/m2m/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,2BAA2B;IAC3B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAE5B,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B,+CAA+C;IAC/C,QAAQ,CAAC,aAAa,CAAC,EAAE,gBAAgB,CAAC;IAE1C,uCAAuC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE1C,mDAAmD;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IAEvB,wCAAwC;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,OAAO,EAAE;QACnB,IAAI,EAAE,YAAY,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,aAAa,CAAC,EAAE,gBAAgB,CAAC;QACjC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACjC,KAAK,CAAC,EAAE,KAAK,CAAC;KACf;IAiBD;;OAEG;IACH,MAAM,CAAC,cAAc,CACnB,aAAa,EAAE;QACb,KAAK,EAAE,YAAY,CAAC;QACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,EACD,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,QAAQ;IAaX;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,GAAE,YAA6B,GAAG,QAAQ;IAS7E;;OAEG;IACH,MAAM,CAAC,qBAAqB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,gBAAgB,GAAG,SAAS;IAgB3F;;OAEG;IACH,MAAM,CAAC,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM;IAgBpD;;OAEG;IACH,WAAW,IAAI,OAAO;IAStB;;OAEG;IACH,aAAa,IAAI,MAAM;IAWvB;;OAEG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAYjC;;OAEG;IACH,QAAQ,IAAI,MAAM;CAOnB;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;gBAC/B,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAS3C;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;gBAClC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAS3C;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,QAAQ;gBAC9B,OAAO,EAAE,MAAM;CAQ5B"}

package/dist/lib/m2m/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * M2M (Machine-to-Machine) Authentication Module
+ *
+ * OAuth 2.0 Client Credentials Grant implementation for server-to-server
+ * authentication without user involvement.
+ *
+ * @example
+ * ```typescript
+ * import { M2MClient } from '@passflow/core';
+ *
+ * const m2m = new M2MClient({
+ *   url: 'https://auth.yourapp.com',
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ *   scopes: ['users:read', 'orders:write'],
+ * });
+ *
+ * const token = await m2m.getToken();
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { M2MClient } from './client';
+export { M2MError, M2MNetworkError, M2MTokenParseError, M2MConfigError } from './errors';
+export type { M2MClientConfig, M2MTokenRequestOptions, M2MTokenRequestInfo, M2MTokenResponse, M2MErrorResponse, M2MTokenClaims, M2MErrorCode, M2MTokenCache, RetryStrategy, M2MRateLimitInfo, } from './types';
+export { M2MErrorCodes, M2M_DEFAULTS } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/m2m/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/m2m/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAGrC,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAGzF,YAAY,EACV,eAAe,EACf,sBAAsB,EACtB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,aAAa,EACb,gBAAgB,GACjB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC"}