postex-auth-sdk-stage 1.0.0

package/README.md

@@ -0,0 +1,94 @@
+# PostEx Auth SDK
+
+PostEx Auth SDK for authentication flows: OTP, magic links, passkeys (WebAuthn), and token management. Use it in any frontend project via NPM or CDN.
+
+## Installation
+
+### NPM
+
+```bash
+npm install postex-auth-sdk
+```
+
+### CDN (jsDelivr)
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/postex-auth-sdk@1/dist/postex-auth-sdk.umd.js"></script>
+```
+
+### CDN (unpkg)
+
+```html
+<script src="https://unpkg.com/postex-auth-sdk@1/dist/postex-auth-sdk.umd.js"></script>
+```
+
+Use a specific version for production (e.g. `@1.0.0` instead of `@1`).
+
+## Usage
+
+### Via CDN (script tag)
+
+After loading the script, the SDK is available on the global `PostexAuthSDK` object:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/postex-auth-sdk@1/dist/postex-auth-sdk.umd.js"></script>
+<script>
+  const { AuthSDK, WebAuthn } = PostexAuthSDK;
+  const sdk = new AuthSDK({ apiKey: "your-api-key" });
+
+  // Check auth status
+  const status = await sdk.getStatus("user@example.com");
+
+  // Initiate auth (OTP or WebAuthn)
+  const result = await sdk.initiateAuth("user@example.com");
+  if (result.status === "webauthn_challenge") {
+    const authResult = await sdk.authenticateWithPasskey({
+      challenge: result.challenge,
+      rp: result.rp,
+      credentialIds: result.credentialIds || [],
+    });
+  } else if (result.status === "otp_sent") {
+    const verified = await sdk.verifyOTP("123456");
+  }
+</script>
+```
+
+### Via NPM (ESM)
+
+```javascript
+import { AuthSDK, WebAuthn, AuthSDKFetchError } from "postex-auth-sdk";
+
+const sdk = new AuthSDK({ apiKey: "your-api-key" });
+
+// Use SDK methods
+const status = await sdk.getStatus("user@example.com");
+```
+
+### WebAuthn utilities
+
+```javascript
+import { WebAuthn } from "postex-auth-sdk";
+
+if (WebAuthn.isWebAuthnSupported()) {
+  const conditionalUI = await WebAuthn.isConditionalUISupported();
+  // ...
+}
+```
+
+## API overview
+
+- **AuthSDK** – Main client: `getStatus`, `initiateAuth`, `verifyOTP`, `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 storage
+- **AuthSDKFetchError** – Error class with `response.status` and `response.data`
+
+## Versioning
+
+This package follows [semantic versioning](https://semver.org/). CDN URLs support:
+
+- `@1` – latest 1.x.x
+- `@1.0` – latest 1.0.x
+- `@1.0.0` – exact version
+
+## License
+
+MIT

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";