postex-auth-sdk-stage 1.4.0 → 2.1.0

package/README.md

@@ -364,6 +364,7 @@ DPoP provides enhanced security by binding tokens to cryptographic keys. The SDK
 #### getRequestAuthHeaders()
 
 Get authentication headers (Authorization + DPoP) for a request. Use this to attach auth to your own HTTP client.
+If DPoP proof generation fails, this method throws and does not return bearer-only headers.
 
 ```typescript
 async getRequestAuthHeaders(
@@ -475,33 +476,6 @@ async function clearPasskeyMobileNumber(): Promise<void>
 
 ---
 
-### DPoP Utility Functions
-
-Low-level DPoP functions. Most developers won't need these as they're handled automatically by the SDK.
-
-```typescript
-// Generate DPoP key pair
-async function generateDPoPKeyPair(): Promise<{
-  publicKey: MinimalECPublicKeyJWK;
-  thumbprint: string;
-}>
-
-// Generate DPoP proof JWT
-async function generateDPoPProof(
-  httpMethod: string,
-  httpUri: string,
-  accessToken?: string
-): Promise<string | null>
-
-// Check if DPoP is enabled
-async function isDPoPEnabled(): Promise<boolean>
-
-// Clear DPoP keys
-async function clearDPoPKey(): Promise<void>
-```
-
----
-
 ## Complete Examples
 
 ### Passkey Registration Flow
@@ -620,14 +594,18 @@ const response2 = await fetch('https://api.example.com/data', {
 
 ## Error Handling
 
-The SDK throws `AuthSDKFetchError` for HTTP errors. This error includes the status code and response data.
+The SDK throws `AuthSDKFetchError` for HTTP errors and `SDKValidationError` for client-side input validation failures before any network request is sent.
 
 ```javascript
-import { AuthSDK, AuthSDKFetchError } from 'postex-auth-sdk-stage';
+import { AuthSDK, AuthSDKFetchError, SDKValidationError } from 'postex-auth-sdk-stage';
 
 try {
   await auth.verifyOTP(otpCode);
 } catch (error) {
+  if (error instanceof SDKValidationError) {
+    console.error('Invalid field:', error.field);
+    console.error('Validation message:', error.message);
+  }
   if (error instanceof AuthSDKFetchError) {
     console.error('Status:', error.response.status);
     console.error('Data:', error.response.data);
@@ -656,7 +634,8 @@ The SDK automatically implements DPoP (RFC 9449) to bind tokens to cryptographic
 - Generated using ECDSA P-256 (ES256)
 - Stored securely in IndexedDB
 - Non-extractable (private key cannot be exported)
-- Automatically included in all authenticated requests
+- Checked during SDK initialization and regenerated once if missing or incomplete
+- Required for authenticated requests; the SDK fails closed instead of sending bearer-only requests
 
 ---
 
@@ -732,7 +711,8 @@ import {
   PasskeyRegisterResponse,
   PasskeyStatusResponse,
   RefreshTokenResponse,
-  AuthSDKFetchError
+  AuthSDKFetchError,
+  SDKValidationError
 } from 'postex-auth-sdk-stage';
 ```
 
@@ -750,8 +730,9 @@ import {
 ## API overview
 
 - **AuthSDK** – Main client: `getStatus`, `initiateAuth`, `initiateOTP`, `verifyOTP`, `resendOTP`, `verifySignupOTP`, `resendSignupOTP`, `verifyMagicLink`, `completeMagicLink`, `authenticateWithPasskey`, `registerPasskey`, `getPasskeyStatus`, `removePasskey`, `getRequestAuthHeaders`, `authenticatedFetch`, `refreshToken`, `logout`, `getAccessToken`, `storeTokens`, `clearTokens`
-- **WebAuthn** – Helpers: `isWebAuthnSupported`, `isConditionalUISupported`, base64/ArrayBuffer conversion, DPoP key and proof helpers, passkey email/mobile storage (`getPasskeyEmail`, `setPasskeyEmail`, `clearPasskeyEmail`, `getPasskeyMobileNumber`, `setPasskeyMobileNumber`, `clearPasskeyMobileNumber`)
+- **WebAuthn** – Helpers: `isWebAuthnSupported`, `isConditionalUISupported`, base64/ArrayBuffer conversion, and passkey email/mobile storage (`getPasskeyEmail`, `setPasskeyEmail`, `clearPasskeyEmail`, `getPasskeyMobileNumber`, `setPasskeyMobileNumber`, `clearPasskeyMobileNumber`)
 - **AuthSDKFetchError** – Error class with `response.status` and `response.data`
+- **SDKValidationError** – Error class with `field`, `code`, and a validation message for invalid client input
 
 ## Versioning
 

package/dist/auth.d.ts

@@ -1,4 +1,12 @@
 type AuthEntity = "xstak" | "postex" | "callcourier" | "postexglobal" | "postexsa";
+type AuthIdentifierInput = string | {
+    email?: string;
+    mobileNumber?: string;
+    realm?: string;
+};
+interface RealmOptions {
+    realm?: string;
+}
 interface AuthSDKConfig {
     apiKey?: string;
     appId?: AuthEntity;
@@ -101,11 +109,33 @@ export declare class AuthSDKFetchError extends Error {
     };
     constructor(status: number, data?: any, message?: string);
 }
+export declare class SDKValidationError extends Error {
+    field: string;
+    code: string;
+    constructor(field: string, message: string, code?: string);
+}
 export declare class AuthSDK {
     private config;
+    private dpopInitializationPromise;
     constructor(config: AuthSDKConfig);
     private getBaseUrl;
+    private initializeDPoPState;
+    private ensureDPoPInitialized;
+    private createDPoPInitializationPromise;
+    private resetDPoPInitialization;
+    private getRequiredDPoPProof;
+    private containsControlChars;
+    private hasMixedLatinAndCyrillic;
+    private assertNoControlChars;
+    private validateEmail;
+    private validateMobileNumber;
+    private validateOTP;
+    private validateMagicLinkToken;
+    private validateRealm;
+    private normalizeAndValidateIdentifier;
     private normalizeAuthIdentifier;
+    private extractRealm;
+    private buildAuthRequestBody;
     private buildUrl;
     private request;
     /**
@@ -119,26 +149,17 @@ export declare class AuthSDK {
      * GET /auth/status - Check if client has trusted device session and what auth method is available.
      * Returns no_session | session_found | webauthn_ready per PostEx Auth BFF spec.
      */
-    getStatus(identifier: string | {
-        email?: string;
-        mobileNumber?: string;
-    }): Promise<AuthStatusResponse>;
+    getStatus(identifier: AuthIdentifierInput, options?: RealmOptions): Promise<AuthStatusResponse>;
     /**
      * POST /auth/initiate - Unified entry: returns webauthn_challenge or otp_sent.
      * Sets auth_session cookie when otp_sent.
      */
-    initiateAuth(identifier: string | {
-        email?: string;
-        mobileNumber?: string;
-    }): Promise<InitiateAuthResponse>;
+    initiateAuth(identifier: AuthIdentifierInput, options?: RealmOptions): Promise<InitiateAuthResponse>;
     /**
      * POST /otp/initiate - Direct OTP initiation using email or mobile number.
      * Requires at least one identifier: email or mobileNumber.
      */
-    initiateOTP(identifier: string | {
-        email?: string;
-        mobileNumber?: string;
-    }): Promise<OTPInitiateResponse>;
+    initiateOTP(identifier: AuthIdentifierInput, options?: RealmOptions): Promise<OTPInitiateResponse>;
     /**
      * POST /otp/verify - Verifies the OTP code entered by the user.
      * Stores tokens from the response.
@@ -174,7 +195,7 @@ export declare class AuthSDK {
      * GET /magic-link - Verify a magic link token.
      * Sets auth_session cookie on success.
      */
-    verifyMagicLink(token: string, email: string): Promise<void>;
+    verifyMagicLink(token: string): Promise<void>;
     /**
      * POST /magic-link/complete - Complete magic link authentication.
      * Requires auth_session cookie set by verifyMagicLink.
@@ -229,7 +250,7 @@ export declare class AuthSDK {
      * Requires trusted device cookie (td). Refresh token is stored server-side.
      * Rate limit: 10 requests per minute.
      */
-    refreshToken(): Promise<RefreshTokenResponse>;
+    refreshToken(options?: RealmOptions): Promise<RefreshTokenResponse>;
     /**
      * POST /auth/logout - Logout from the current device.
      * Revokes the current token and trusted device, then clears local tokens.

package/dist/main.d.ts

@@ -1,2 +1,2 @@
 export * from "./auth";
-export * from "./webauthn";
+export { isWebAuthnSupported, isConditionalUISupported, arrayBufferToBase64, base64ToArrayBuffer, arrayBufferToBase64url, base64urlToArrayBuffer, stringToArrayBuffer, uint8ArrayToString, getPasskeyEmail, setPasskeyEmail, clearPasskeyEmail, getPasskeyMobileNumber, setPasskeyMobileNumber, clearPasskeyMobileNumber, } from "./webauthn";