Registry / auth-security / xumm-oauth2-pkce

xumm-oauth2-pkce

JSON →
library2.8.7jsnpmunverified

The `xumm-oauth2-pkce` JavaScript SDK facilitates client-side only OAuth2 Authorization Code with PKCE (Proof Key for Code Exchange) flow for the Xumm ecosystem. Currently at version 2.8.7, this package provides a secure method for web applications to authenticate users with Xumm without requiring a backend server for token exchange. It is actively maintained and typically follows a release cadence tied to Xumm ecosystem updates. Key differentiators include its focus on client-side security via PKCE, out-of-the-box handling of browser redirects and session persistence (using `localStorage` by default), and offering both event-driven and promise-based APIs. It integrates seamlessly into browser environments, abstracting away the complexities of the OAuth2 PKCE flow for Xumm users, and ships with TypeScript types for enhanced development experience.

npm install xumm-oauth2-pkce
INSTALL
IMPORT
SIG · XUMM-OAUTH2-PKCE
X
xumm-oauth2-pkce
auth-securityjavascriptv2.8.7
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

XummPkce
import { XummPkce } from 'xumm-oauth2-pkce'
const XummPkce = require('xumm-oauth2-pkce')
The package is primarily designed for ESM consumption. While UMD builds are available for browsers via CDN, direct Node.js usage should favor ESM imports. It is a named export, not a default export.
XummPkceOptions
import type { XummPkceOptions } from 'xumm-oauth2-pkce'
This type definition specifies the available options for the `XummPkce` constructor. Importing types separately is good practice in TypeScript.

This quickstart demonstrates how to initialize `XummPkce`, handle authentication events (success, retrieval, errors), and manage user login/logout state within a simple browser application. It uses both event listeners and `authorize()` for interactive authentication.

import { XummPkce } from 'xumm-oauth2-pkce'; // Replace with your actual Xumm API key or load from environment const XUMM_API_KEY = process.env.XUMM_API_KEY ?? 'your-xumm-api-key-uuidv4'; const xumm = new XummPkce(XUMM_API_KEY); const handleAuthResult = async () => { const state = await xumm.state(); if (state && state.me) { const { sdk, me } = state; console.log("Successfully authenticated with Xumm!"); console.log("User account:", me.account); console.log("Xumm SDK instance:", sdk); // This is an instance of xumm-sdk document.getElementById('auth-status')!.innerText = `Authenticated as ${me.account}`; document.getElementById('auth-button')!.innerText = 'Logout'; } else { console.log("Not authenticated."); document.getElementById('auth-status')!.innerText = 'Not authenticated.'; document.getElementById('auth-button')!.innerText = 'Sign in with Xumm'; } }; // Listen for retrieved session (e.g., after page refresh or mobile redirect) xumm.on("retrieved", handleAuthResult); // Listen for new successful authentication xumm.on("success", handleAuthResult); // Listen for errors xumm.on("error", (error) => { console.error("Xumm authentication error:", error); document.getElementById('auth-status')!.innerText = `Authentication failed: ${error.message}`; xumm.logout(); // Clear any partial state }); // Check authentication status on page load and set up interaction document.addEventListener('DOMContentLoaded', async () => { document.body.innerHTML = ` <div id="app" style="font-family: sans-serif; padding: 20px;"> <h1>Xumm PKCE Auth Demo</h1> <p id="auth-status">Checking authentication status...</p> <button id="auth-button">Loading...</button> </div> `; document.getElementById("auth-button")!.onclick = async () => { const currentState = await xumm.state(); if (currentState && currentState.me) { await xumm.logout(); console.log("Logged out."); } else { console.log("Initiating Xumm authorization..."); // For a new sign-in, the authorize() call will redirect or open a popup. // The 'success' event will handle the result. await xumm.authorize(); } handleAuthResult(); // Update button and status immediately after action }; handleAuthResult(); // Initial check });
Debug
Known issues
gotchaPrioritize the event-based API (`.on('success', ...)`) over the promise-based (`.authorize().then(...)`) for future compatibility, as explicitly recommended by the library maintainers. The promise will resolve, but state changes are best observed via events.
fix
Refactor promise-based authorization logic to use the event-driven approach where possible, listening for `success`, `retrieved`, and `error` events to manage application state.
affects: >=1.0
gotchaEnabling the `implicit` option (setting `implicit: true` in `XummPkceOptions`) reduces security by allowing cross-browser sign-in without a fresh PKCE challenge, making it susceptible to some attack vectors. Only use if absolutely necessary and fully understand the implications.
fix
Avoid setting `implicit: true` unless there's a specific, understood requirement for legacy cross-browser sign-in support. Stick to the default `implicit: false` for enhanced security.
affects: >=1.0
gotchaThe `redirectUrl` option defaults to `document.location.href`. If your application navigates away from the root path or uses complex routing that changes `document.location.href`, ensure this URL is explicitly set in the constructor and correctly configured in both the Xumm app and your constructor to prevent authorization flow failures.
fix
Always explicitly set `redirectUrl` in the `XummPkce` constructor to match the exact URL Xumm should redirect back to after authorization, and ensure this precisely matches your Xumm application's configuration in the Xumm Developer Console.
affects: *
Errors
Common errors & fixes
Error: Missing API Key
The `XummPkce` constructor was called without a valid Xumm API key (UUID v4 string) or with an invalid one.
fix
Provide a valid Xumm API key (UUID v4 format) as the first argument to the `XummPkce` constructor: `new XummPkce('your-api-key-uuidv4', { ... });`
redirect_uri_mismatch
The `redirectUrl` configured in the `XummPkce` constructor (or its default `document.location.href`) does not exactly match the `redirectUrl` registered for your application in the Xumm Developer Console.
fix
Verify that the `redirectUrl` option passed to `XummPkce` precisely matches the redirect URL configured for your application in the Xumm Developer Console. Pay close attention to trailing slashes, subdomains, and protocols (http/https).
ReferenceError: XummPkce is not defined
Occurs when attempting to use `XummPkce` in a browser environment without properly loading the library via a script tag, or when using CommonJS `require` syntax in an ESM-only context.
fix
For browser usage without a bundler, ensure `<script src="https://xumm.app/assets/cdn/xumm-oauth2-pkce.min.js"></script>` is loaded before your script attempts to use `XummPkce`. For module-based projects, use `import { XummPkce } from 'xumm-oauth2-pkce';` and ensure your bundler/runtime supports ESM.
Error: User cancelled authorization
The user explicitly cancelled the authentication flow in the Xumm app, closed the authorization window/tab, or denied the authorization request.
fix
Handle this gracefully in your application's error callback (e.g., `sdk.on('error', (err) => { /* display message to user */ })`). This is an expected user action and not typically a technical fault, so clear any pending UI states.
Upgrade
Version history
2.8.7latest on npm
Audit
Dependencies
xumm-sdkrequiredUsed internally by `xumm-oauth2-pkce` to interact with the Xumm API after authorization, an instance of which is accessible via `sdk.state().sdk`.
Agent activity
30 hits · last 30 days
node
26
OpenAI (training)
1
Resources
xumm-oauth2-pkce — npm install xumm-oauth2-pkce · libregistry