postex-auth-sdk 1.0.0 → 1.1.0

package/dist/auth.d.ts

@@ -0,0 +1,189 @@
+interface AuthSDKConfig {
+    apiKey?: string;
+}
+type AuthStatusType = "no_session" | "session_found" | "webauthn_ready";
+interface AuthStatusResponse {
+    status: AuthStatusType;
+    email?: string;
+    webauthn?: boolean;
+    challenge?: string;
+    credentialIds?: string[];
+    rp?: {
+        name: string;
+        host: string;
+    };
+}
+/** Response from POST /auth/initiate */
+type InitiateAuthStatusType = "webauthn_challenge" | "otp_sent";
+interface InitiateAuthResponse {
+    status: InitiateAuthStatusType;
+    challenge?: string;
+    credentialIds?: string[];
+    rp?: {
+        name: string;
+        host: string;
+    };
+}
+interface OTPVerifyResponse {
+    access_token: string;
+    id_token: string;
+    refresh_token: string;
+    expires_in: number;
+    token_type: string;
+    verified: boolean;
+    email: string;
+    [key: string]: any;
+}
+interface PasskeyRegistrationChallenge {
+    challenge: string;
+    rp: {
+        name: string;
+        id: string;
+    };
+    user: {
+        id: string;
+        name: string;
+        displayName: string;
+    };
+    pubKeyCredParams?: Array<{
+        type: string;
+        alg: number;
+    }>;
+    authenticatorSelection?: AuthenticatorSelectionCriteria;
+    timeout?: number;
+    attestation?: AttestationConveyancePreference;
+    /** Existing credential IDs to exclude (prevents duplicate registration) */
+    excludeCredentials?: Array<{
+        id: string;
+        type: "public-key";
+        transports?: AuthenticatorTransport[];
+    }>;
+}
+interface PasskeyRegisterResponse {
+    registered: boolean;
+    [key: string]: any;
+}
+interface PasskeyStatusResponse {
+    credentialId?: string;
+    hasCredentials: boolean;
+    [key: string]: any;
+}
+interface AuthResponse {
+    access_token: string;
+    refresh_token: string;
+    id_token?: string;
+    email: string;
+    name: string;
+    expiresIn?: number;
+    tokenType?: string;
+    [key: string]: any;
+}
+/** Response from POST /auth/refresh */
+interface RefreshTokenResponse {
+    access_token: string;
+    id_token?: string;
+    token_type: string;
+    expires_in: number;
+}
+export declare class AuthSDKFetchError extends Error {
+    response: {
+        status: number;
+        data?: any;
+    };
+    constructor(status: number, data?: any, message?: string);
+}
+export declare class AuthSDK {
+    private config;
+    constructor(config: AuthSDKConfig);
+    private buildUrl;
+    private request;
+    /**
+     * Returns auth headers (Authorization + DPoP) for the given request.
+     * Use this to attach auth to your own HTTP client (e.g. axios request interceptor).
+     * @param method - HTTP method (e.g. "GET", "POST")
+     * @param url - Full request URL
+     */
+    getRequestAuthHeaders(method: string, url: string): Promise<Record<string, string>>;
+    /**
+     * 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(email: string): Promise<AuthStatusResponse>;
+    /**
+     * POST /auth/initiate - Unified entry: returns webauthn_challenge or otp_sent.
+     * Sets auth_session cookie when otp_sent.
+     */
+    initiateAuth(email: string): Promise<InitiateAuthResponse>;
+    /**
+     * POST /otp/verify - Verifies the OTP code entered by the user.
+     * Stores tokens from the response.
+     */
+    verifyOTP(otp: string): Promise<OTPVerifyResponse>;
+    /**
+     * GET /magic-link - Verify a magic link token.
+     * Sets auth_session cookie on success.
+     */
+    verifyMagicLink(token: string, email: string): Promise<void>;
+    /**
+     * POST /magic-link/complete - Complete magic link authentication.
+     * Requires auth_session cookie set by verifyMagicLink.
+     * Stores tokens from the response.
+     */
+    completeMagicLink(): Promise<OTPVerifyResponse>;
+    initiatePasskeyRegistration(): Promise<PasskeyRegistrationChallenge>;
+    registerPasskey(email: string): Promise<PasskeyRegisterResponse>;
+    /**
+     * POST /webauthn/authenticate/challenge - Authenticate with passkey.
+     */
+    authenticateWithPasskey({ challenge, rp, credentialIds, }: {
+        challenge: string;
+        rp: {
+            name: string;
+            host: string;
+        };
+        credentialIds: string[];
+    }): Promise<AuthResponse>;
+    /**
+     * GET /webauthn/credentials/:username - Get user's passkey status.
+     */
+    getPasskeyStatus(username: string): Promise<PasskeyStatusResponse>;
+    /**
+     * DELETE /webauthn/credentials/:username - Remove passkey.
+     */
+    removePasskey(username: string): Promise<void>;
+    /**
+     * Signs a request with DPoP and Authorization headers (internal use).
+     */
+    signRequest(method: string, url: string, config?: any): Promise<any>;
+    /**
+     * Replaces native fetch or Axios with a DPoP-signed version.
+     */
+    authenticatedFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    /**
+     * Store tokens from /webauthn/authenticate (per spec: sessionStorage preferred).
+     */
+    storeTokens(tokens: {
+        accessToken: string;
+        refreshToken?: string;
+        idToken?: string;
+        expiresIn?: number;
+        tokenType?: string;
+    }): Promise<void>;
+    /**
+     * Clear stored tokens (call on logout).
+     */
+    clearTokens(): Promise<void>;
+    /**
+     * POST /auth/refresh - Refresh access token using server-stored refresh token.
+     * Requires trusted device cookie (td). Refresh token is stored server-side.
+     * Rate limit: 10 requests per minute.
+     */
+    refreshToken(): Promise<RefreshTokenResponse>;
+    /**
+     * POST /auth/logout - Logout from the current device.
+     * Revokes the current token and trusted device, then clears local tokens.
+     */
+    logout(): Promise<void>;
+    getAccessToken(): Promise<string | null>;
+}
+export {};

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+export * from "./auth";
+export * from "./webauthn";

package/dist/webauthn.d.ts

@@ -0,0 +1,75 @@
+export declare function isWebAuthnSupported(): boolean;
+export declare function isConditionalUISupported(): Promise<boolean>;
+export declare function arrayBufferToBase64(buffer: ArrayBuffer): string;
+export declare function base64ToArrayBuffer(base64: string): ArrayBuffer;
+export declare function arrayBufferToBase64url(buffer: ArrayBuffer): string;
+export declare function base64urlToArrayBuffer(input: string): ArrayBuffer;
+export declare function stringToArrayBuffer(str: string): ArrayBuffer;
+export declare function uint8ArrayToString(arr: Uint8Array): string;
+/**
+ * Get the stored passkey email from IndexedDB
+ */
+export declare function getPasskeyEmail(): Promise<string | null>;
+export declare function setPasskeyEmail(email: string): Promise<void>;
+/**
+ * Remove the passkey email from IndexedDB
+ */
+export declare function clearPasskeyEmail(): Promise<void>;
+/**
+ * Minimal JWK for EC P-256 public key (only required fields per RFC 7517)
+ */
+export interface MinimalECPublicKeyJWK {
+    kty: "EC";
+    crv: "P-256";
+    x: string;
+    y: string;
+}
+/**
+ * Create a minimal JWK from a full JWK (removes ext, key_ops, etc.)
+ */
+export declare function toMinimalJWK(jwk: JsonWebKey): MinimalECPublicKeyJWK;
+/**
+ * Calculate JWK Thumbprint (SHA-256) per RFC 7638
+ * Uses canonical JSON with lexicographically ordered required members
+ */
+export declare function calculateThumbprint(jwk: MinimalECPublicKeyJWK): Promise<string>;
+/**
+ * Store DPoP Private Key in IndexedDB
+ */
+declare function storeDPoPPrivateKey(key: CryptoKey): Promise<void>;
+/**
+ * Retrieve DPoP Private Key from IndexedDB
+ */
+export declare function getDPoPKey(): Promise<CryptoKey | null>;
+/**
+ * Retrieve DPoP Public Key JWK from IndexedDB
+ */
+export declare function getDPoPPublicKeyJWK(): Promise<MinimalECPublicKeyJWK | null>;
+/**
+ * Clear stored DPoP Keys from IndexedDB
+ */
+export declare function clearDPoPKey(): Promise<void>;
+/**
+ * Generate a new ECDSA P-256 Key Pair for DPoP.
+ * Stores both Private Key (CryptoKey) and Public Key (JWK) in IndexedDB.
+ * Returns minimal Public Key JWK and its Thumbprint for backend transmission.
+ */
+export declare function generateDPoPKeyPair(): Promise<{
+    publicKey: MinimalECPublicKeyJWK;
+    thumbprint: string;
+}>;
+/**
+ * Generate a DPoP proof JWT using ECDSA P-256 (ES256)
+ * Per RFC 9449 Section 4.2
+ *
+ * @param httpMethod - HTTP method (GET, POST, etc.)
+ * @param httpUri - Full URL of the request (without query/fragment for htu)
+ * @param accessToken - Optional access token to bind (adds ath claim)
+ */
+export declare function generateDPoPProof(httpMethod: string, httpUri: string, accessToken?: string): Promise<string | null>;
+/**
+ * Check if DPoP is enabled (Keys are stored)
+ */
+export declare function isDPoPEnabled(): Promise<boolean>;
+export declare const storeDPoPKey: typeof storeDPoPPrivateKey;
+export {};

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "postex-auth-sdk",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "PostEx Auth SDK for authentication flows: OTP, magic links, passkeys, and token management",
   "main": "./dist/postex-auth-sdk.umd.js",
   "module": "./dist/postex-auth-sdk.es.js",
   "types": "./dist/main.d.ts",
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "exports": {
     ".": {
       "types": "./dist/main.d.ts",
@@ -13,7 +15,14 @@
       "require": "./dist/postex-auth-sdk.umd.js"
     }
   },
-  "keywords": ["auth", "webauthn", "passkey", "otp", "sdk", "postex"],
+  "keywords": [
+    "auth",
+    "webauthn",
+    "passkey",
+    "otp",
+    "sdk",
+    "postex"
+  ],
   "author": "",
   "license": "MIT",
   "repository": {
@@ -22,11 +31,14 @@
   },
   "scripts": {
     "dev": "vite",
-    "build": "tsc && vite build",
+    "build": "vite build && tsc",
     "preview": "vite preview"
   },
   "devDependencies": {
     "typescript": "~5.9.3",
     "vite": "^7.3.1"
+  },
+  "dependencies": {
+    "postex-auth-sdk": "^1.0.0"
   }
 }