# xumm-js-pkce

> A package that makes using the OAuth2 PKCE (+Implicit support) flow easier

Latest version **1.0.2** (published 2023-11-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install xumm-js-pkce
pnpm add xumm-js-pkce
yarn add xumm-js-pkce
bun add xumm-js-pkce
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.2 |
| Published | 2023-11-13 |
| First published | 2022-11-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 69.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Bryan Pedroza, extended by Wietse Wind |
| Maintainers | wietsewind |
| Keywords | oauth, oauth2, pkce |

## Links

- npm: https://www.npmjs.com/package/xumm-js-pkce
- Repository: https://github.com/XRPL-Labs/xumm-js-pkce
- Homepage: https://github.com/XRPL-Labs/xumm-js-pkce/#readme
- Issues: https://github.com/XRPL-Labs/xumm-js-pkce/issues
- npm.io page: https://npm.io/package/xumm-js-pkce

## Dependencies (1)

- [crypto-js](https://npm.io/package/crypto-js.md) ^4.0.0

## Alternatives

- [@pothos/plugin-authz](https://npm.io/package/@pothos/plugin-authz.md) — 12.4K weekly downloads
- [@bounded-sh/client](https://npm.io/package/@bounded-sh/client.md) — 3.2K weekly downloads
- [@luigi-project/plugin-auth-oauth2](https://npm.io/package/@luigi-project/plugin-auth-oauth2.md) — 2.3K weekly downloads
- [@nocobase/plugin-verification](https://npm.io/package/@nocobase/plugin-verification.md) — 2.0K weekly downloads
- [escher-request](https://npm.io/package/escher-request.md) — 545 weekly downloads

## Recent versions

- 1.0.2 (latest) — 2023-11-13
- 1.0.0 — 2022-11-21

## README

# js-pkce
A package that makes using the OAuth2 PKCE flow easier

## Installation
`npm i js-pkce`

## Create a new instance
Create a new instance of js-pkce with all of the details needed.

```javascript
import PKCE from 'js-pkce';
const pkce = new PKCE({
  client_id: 'myclientid',
  redirect_uri: 'http://localhost:8080/auth',
  authorization_endpoint: 'https://authserver.com/oauth/authorize',
  token_endpoint: 'https://authserver.com/oauth/token',
  requested_scopes: '*',
});
```

## Start the authorization process
Typically you just need to go to the authorization url to start the process.
This example is something that might work in a SPA.

```javascript
window.location.replace(pkce.authorizeUrl());
```

You may add additional query parameters to the authorize url by using an optional second parameter:

```javascript
const additionalParams = {test_param: 'testing'};
window.location.replace(pkce.authorizeUrl(additionalParams));
```

## Trade the code for a token
After logging in with the authorization server, you will be redirected to the value in
the `redirect_uri` parameter you set when creating the instance.
Again, this is an example that might work for a SPA.

When you get back here, you need to exchange the code for a token.

```javascript
const url = window.location.href;
pkce.exchangeForAccessToken(url).then((resp) => {
  const token = resp.access_token;
  // Do stuff with the access token.
});
```

As with the authorizeUrl method, an optional second parameter may be passed to
the `exchangeForAccessToken` method to send additional parameters to the request:

```javascript
const url = window.location.href;
const additionalParams = {test_param: 'testing'};

pkce.exchangeForAccessToken(url, additionalParams).then((resp) => {
  const token = resp.access_token;
  // Do stuff with the access token.
});
```

## A note on Storage
By default, this package will use `sessionStorage` to persist the `pkce_state`. On (mostly) mobile
devices there's a higher chance users are returning in a different browser tab. E.g. they kick off
in a WebView & get redirected to a new tab. The `sessionStorage` will be empty there.

In this case it you can opt in to use `localStorage` instead of `sessionStorage`:

```javascript
import PKCE from 'js-pkce';
const pkce = new PKCE({
  // ...
  storage: localStorage, // any Storage object, sessionStorage (default) or localStorage 
});
```

---
_Source: https://npm.io/package/xumm-js-pkce · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._