@passflow/core 0.0.1 → 0.2.8

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

@@ -0,0 +1,217 @@
+/**
+ * M2M (Machine-to-Machine) Authentication Types
+ *
+ * OAuth 2.0 Client Credentials Grant implementation for server-to-server
+ * authentication without user involvement.
+ */
+/**
+ * M2M Client configuration options
+ */
+export type M2MClientConfig = {
+    /** Passflow server URL */
+    url: string;
+    /** M2M application client ID */
+    clientId: string;
+    /** M2M application client secret */
+    clientSecret: string;
+    /** Scopes to request (default: []) */
+    scopes?: string[];
+    /** Target audiences for the token */
+    audience?: string[];
+    /** Automatically refresh tokens before expiry (default: false) */
+    autoRefresh?: boolean;
+    /** Seconds before expiry to trigger refresh (default: 30) */
+    refreshThreshold?: number;
+    /** Request timeout in milliseconds (default: 10000) */
+    timeout?: number;
+    /** Number of retry attempts on failure (default: 3) */
+    retries?: number;
+    /** Delay between retries in milliseconds (default: 1000) */
+    retryDelay?: number;
+    /** Custom retry strategy */
+    retryStrategy?: RetryStrategy;
+    /** Custom token cache implementation */
+    cache?: M2MTokenCache;
+    /** Callback for token requests (for logging/metrics) */
+    onTokenRequest?: (request: M2MTokenRequestInfo) => void;
+    /** Callback for token responses (for logging/metrics) */
+    onTokenResponse?: (response: M2MTokenResponse) => void;
+    /** Callback for errors (for logging/metrics) */
+    onError?: (error: M2MErrorResponse) => void;
+};
+/**
+ * Token request options (can override defaults per-request)
+ */
+export type M2MTokenRequestOptions = {
+    /** Override default scopes for this request */
+    scopes?: string[];
+    /** Override default audience for this request */
+    audience?: string[];
+    /** Force a new token request, ignoring cache */
+    forceRefresh?: boolean;
+};
+/**
+ * Token request info (for logging callbacks)
+ */
+export type M2MTokenRequestInfo = {
+    /** Client ID being used */
+    clientId: string;
+    /** Scopes being requested */
+    scopes: string[];
+    /** Audiences being requested */
+    audience: string[];
+    /** Request timestamp */
+    timestamp: string;
+};
+/**
+ * OAuth 2.0 token response from the authorization server
+ */
+export type M2MTokenResponse = {
+    /** The access token (JWT) */
+    access_token: string;
+    /** Token type (always "Bearer") */
+    token_type: 'Bearer';
+    /** Token lifetime in seconds */
+    expires_in: number;
+    /** Granted scopes (space-separated string) */
+    scope?: string;
+    /** Timestamp when token was issued (added by client) */
+    issued_at?: number;
+};
+/**
+ * OAuth 2.0 error response from the authorization server
+ */
+export type M2MErrorResponse = {
+    /** OAuth 2.0 error code */
+    error: M2MErrorCode;
+    /** Human-readable error description */
+    error_description?: string;
+    /** URI with more information about the error */
+    error_uri?: string;
+};
+/**
+ * Parsed M2M JWT token claims
+ */
+export type M2MTokenClaims = {
+    /** Issuer (Passflow server URL) */
+    iss: string;
+    /** Subject (client_id) */
+    sub: string;
+    /** Audience (target APIs) */
+    aud: string | string[];
+    /** Issued at timestamp (Unix epoch seconds) */
+    iat: number;
+    /** Expiration timestamp (Unix epoch seconds) */
+    exp: number;
+    /** JWT ID (unique token identifier) */
+    jti?: string;
+    /** Token type ("m2m") */
+    type: 'm2m';
+    /** Client ID */
+    client_id: string;
+    /** Tenant ID (for tenant-scoped M2M apps) */
+    tenant_id?: string;
+    /** Granted scopes */
+    scopes: string[];
+};
+/**
+ * M2M error codes (OAuth 2.0 compliant)
+ */
+export type M2MErrorCode = 'invalid_request' | 'invalid_client' | 'invalid_grant' | 'invalid_scope' | 'unauthorized_client' | 'unsupported_grant_type' | 'rate_limit_exceeded' | 'server_error' | 'temporarily_unavailable';
+/**
+ * M2M error code enum for convenience
+ */
+export declare const M2MErrorCodes: {
+    InvalidRequest: "invalid_request";
+    InvalidClient: "invalid_client";
+    InvalidGrant: "invalid_grant";
+    InvalidScope: "invalid_scope";
+    UnauthorizedClient: "unauthorized_client";
+    UnsupportedGrantType: "unsupported_grant_type";
+    RateLimitExceeded: "rate_limit_exceeded";
+    ServerError: "server_error";
+    TemporarilyUnavailable: "temporarily_unavailable";
+};
+/**
+ * Custom token cache interface for external cache implementations
+ */
+export interface M2MTokenCache {
+    /**
+     * Get cached token by key
+     * @param key Cache key (typically clientId)
+     * @returns Cached token or null if not found/expired
+     */
+    get(key: string): Promise<M2MTokenResponse | null>;
+    /**
+     * Cache a token with TTL
+     * @param key Cache key (typically clientId)
+     * @param token Token to cache
+     * @param ttl Time-to-live in seconds
+     */
+    set(key: string, token: M2MTokenResponse, ttl: number): Promise<void>;
+    /**
+     * Delete cached token
+     * @param key Cache key (typically clientId)
+     */
+    delete(key: string): Promise<void>;
+}
+/**
+ * Custom retry strategy interface
+ */
+export interface RetryStrategy {
+    /**
+     * Determine if the request should be retried
+     * @param error The error that occurred
+     * @param attempt Current attempt number (1-based)
+     * @returns true if request should be retried
+     */
+    shouldRetry(error: {
+        code: M2MErrorCode;
+        status?: number;
+    }, attempt: number): boolean;
+    /**
+     * Get delay before next retry
+     * @param attempt Current attempt number (1-based)
+     * @returns Delay in milliseconds
+     */
+    getDelay(attempt: number): number;
+}
+/**
+ * Internal token request payload sent to the authorization server
+ */
+export type M2MTokenRequestPayload = {
+    grant_type: 'client_credentials';
+    client_id: string;
+    client_secret: string;
+    scope?: string;
+    audience?: string;
+};
+/**
+ * Rate limit information from response headers
+ */
+export type M2MRateLimitInfo = {
+    /** Maximum requests allowed in the window */
+    limit: number;
+    /** Remaining requests in the current window */
+    remaining: number;
+    /** Unix timestamp when the window resets */
+    reset: number;
+};
+/**
+ * Default configuration values
+ */
+export declare const M2M_DEFAULTS: {
+    /** Default token endpoint path */
+    readonly TOKEN_ENDPOINT: "/oauth2/token";
+    /** Default request timeout in milliseconds */
+    readonly TIMEOUT: 10000;
+    /** Default number of retry attempts */
+    readonly RETRIES: 3;
+    /** Default delay between retries in milliseconds */
+    readonly RETRY_DELAY: 1000;
+    /** Default refresh threshold in seconds */
+    readonly REFRESH_THRESHOLD: 30;
+    /** Content-Type for token requests */
+    readonly CONTENT_TYPE: "application/x-www-form-urlencoded";
+};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../lib/m2m/types.ts"],"names":[],"mappings":"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"}