Registry / auth-security / postex-auth-sdk

postex-auth-sdk

library1.3.0jsnpmunverified

The PostEx Auth SDK (v1.3.0) provides a comprehensive authentication solution for web applications, supporting WebAuthn/passkeys, OTP, magic links, and DPoP token binding (RFC 9449). Built for PostEx ecosystem apps, it offers automatic token management, trusted device recognition, and browser feature detection. Ships TypeScript types. Release cadence: active development. Key differentiators: multi-factor with passkeys, ECDSA P-256 DPoP, and integrated session/device tracking.

auth-security

npm install postex-auth-sdk

package ↗

INSTALL

IMPORT

SIG · POSTEX-AUTH-SDK

postex-auth-sdk

auth-securityjavascriptv1.3.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

AuthSDK

✓ import { AuthSDK } from 'postex-auth-sdk-stage'

✗ import AuthSDK from 'postex-auth-sdk-stage'

Named export, not default. ESM only; no CJS support.

AuthSDKConfig

✓ import { AuthSDKConfig } from 'postex-auth-sdk-stage'

✗ import { config } from 'postex-auth-sdk-stage'

Only available with TypeScript or JSDoc type imports.

AuthStatusResponse

✓ import type { AuthStatusResponse } from 'postex-auth-sdk-stage'

✗ import { AuthStatusResponse } from 'postex-auth-sdk-stage'

Type-only import to avoid runtime overhead.

Initializes the SDK with API key and appId, checks auth status, then handles passkey or OTP based on the initiate response.

import { AuthSDK } from 'postex-auth-sdk-stage'; const auth = new AuthSDK({ apiKey: process.env.POSTEX_API_KEY ?? '', appId: 'postexglobal' }); async function login(email: string) { const status = await auth.getStatus({ email }); const initResult = await auth.initiateAuth({ email }); if (initResult.status === 'webauthn_challenge') { const response = await auth.authenticateWithPasskey({ challenge: initResult.challenge, rp: initResult.rp, credentialIds: initResult.credentialIds }); console.log('Authenticated with passkey:', response); } else if (initResult.status === 'otp_sent') { const otpCode = await getUserOTP(); const verifyResult = await auth.verifyOTP(otpCode); console.log('Authenticated with OTP:', verifyResult); } }

Debug

Known issues

breakingVersion 1.0.0 changed constructor signature: apiKey and appId moved from positional to config object.

fix

Use new AuthSDK({ apiKey, appId }) instead of new AuthSDK(apiKey, appId).

affects: <1.0.0

deprecatedThe appId 'postex' and 'callcourier' are deprecated and will be removed in v2. Use 'postexglobal' or 'postexsa'.

fix

Switch to appId: 'postexglobal' for global environment.

affects: >=1.2.0

gotchagetStatus() with a string argument must be a valid email; mobile numbers are not accepted as string. Use object form for mobile.

fix

Use auth.getStatus({ mobileNumber: '...' }) instead of auth.getStatus('...').

affects: >=1.0.0

gotchainitiateAuth() does not accept a mobile-only identifier via string; always use object form { mobileNumber }.

fix

Use auth.initiateAuth({ mobileNumber: '...' }).

affects: >=1.0.0

deprecatedThe method 'authenticateWithMagicLink' was renamed to 'authenticateMagicLink' in v1.1.0.

fix

Use auth.authenticateMagicLink(token) instead.

affects: <1.1.0

Errors

Common errors & fixes

TypeError: auth.getStatus is not a function

Using a default import instead of named import, or using an older version.

fix

Use import { AuthSDK } from 'postex-auth-sdk-stage' and ensure version >= 1.0.0.

AuthSDK is not a constructor

Package is ESM-only and may be imported in a CommonJS context.

fix

Use dynamic import: const { AuthSDK } = await import('postex-auth-sdk-stage'); or switch to ES modules.

Error: Both email and mobileNumber are missing

Calling initiateOTP() without any identifier.

fix

Provide at least one identifier: auth.initiateOTP({ email: 'user@example.com' }) or { mobileNumber: '...' }.

Uncaught (in promise) TypeError: Failed to parse URL from undefined/api/...

apiKey is undefined or empty, causing an invalid base URL.

fix

Ensure apiKey is provided in the config and is non-empty.

Upgrade

Version history

1.3.0latest on npm

Audit

Dependencies

@postex/webauthn-utilsrequiredInternal WebAuthn helpers for passkey registration and authentication

@postex/crypto-utilsrequiredECDSA P-256 signing for DPoP proof generation and verification

cookierequiredUsed for trusted device cookie management

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/postex-auth-sdk ↗