@futureverse/auth

OIDC client for FuturePass — handles the OAuth2-style flow against auth.futureverse.app.

Futureverse winddown

Futureverse (the publisher of @futureverse/*) is in winddown. The hosted services this package talked to (auth.futureverse.app, pass-api.futureverse.app, signer.futureverse.app) have been re-hosted by gen3labs at futurepass.gen3labs.tech (issuer) and fpsigner.gen3labs.tech (signer). For new projects, switch to the matching @gen3labs/* package — drop-in surface, default URLs already point at the gen3labs infra. The Asset Register API has no community replacement yet; see the Migration playbook for the per-package map.

Version

5.0.3

Published

2025-09-16

License

n/a

Status

fv-winddown

npm

https://www.npmjs.com/package/@futureverse/auth

Types

./index.d.ts

Maintainers

admin-futureverse, garethdainesnpm, jcsanpedro

Depends on

cookie-storage · oidc-client-ts · @futureverse/auth-core

Recent versions

4.3.0 · 3.10.0-beta.1 · 4.4.0 · 5.0.0 · 5.0.1 · 3.10.0-beta.2 · 5.0.2 · 5.0.3

## Technical notes

Why use it

You want users to sign in with their FuturePass identity (custodial Pass account) rather than connecting a wallet. Returns a session you can pair with @futureverse/transact to dispatch chain calls on the user’s behalf.

When to skip it

You only support EOA-wallet sign-in (MetaMask etc). Then you skip the custodial layer entirely; use @futureverse/wagmi-connectors or the @gen3labs fork.

Pairs with

• @futureverse/auth-react — React provider/hooks
• @futureverse/auth-ui — drop-in UI
• @futureverse/transact — submit txs as the signed-in user

Alternatives

• @gen3labs/futurepass-auth (fork-active) — community fork of this package
• plain SIWE on top of @therootnetwork/api (works) — no custodial; you manage keys

Example

import { FutureverseAuthClient } from '@futureverse/auth';
const client = new FutureverseAuthClient({
  clientId: 'YOUR_CLIENT_ID',
  redirectUri: 'https://app.example.com/callback',
});
await client.signIn();
const session = client.getSession();

Gotchas

• Issuer is https://login.passonline.cloud — if that goes down, the OIDC flow stops working entirely.
• You need a Pass developer client_id from https://identity.passonline.cloud (Futureverse-operated).

Upstream README

Futureverse Auth

Provides an Open ID Connect Authentication library for FuturePass.

Installation

npm:

    npm install @futureverse/auth --save

yarn:

    yarn add @futureverse/auth

pnpm:

    pnpm add @futureverse/auth

bun:

    bun add @futureverse/auth

Register your client

First, you will need to register an OAuth2 client with the Pass Online Identity Provider using the Manage Clients Console:

• Production: https://login.pass.online/manageclients
• Development / Staging: https://login.passonline.cloud/manageclients

Usage

PKCE Auth Client Setup

Use the same client ID and redirect URI for the environment you configured your client in.

import { FutureverseAuthClient } from '@futureverse/auth';

const authClient = new FutureverseAuthClient({
  clientId: '<your-client-id>',
  environment: 'production',
  redirectUri: '<your-redirect-uri>',
  postLogoutRedirectUri: '<your-post-logout-redirect-uri>',
});

Sign in

For Web3 wallet authentication, a signer interface is required. The user needs to sign a message so the identity service can verify their identity.

Signer adapters are available from the Signer SDK.

For custodial authentication, set type as email, facebook, google, tiktok or x.

import { EthereumSigner } from '@futureverse/signer';
...
// Sign in custodial options with popup
const type = 'eoa' // 'eoa' is for web3 wallet sign in
const address = '<selected-web3-wallet-address>';
const signer: Signer = new EthereumSigner(...);

await authClient.signInPass({
    type, // eoa | email | facebook | google | tiktok | x
    address,
    state,
    signer,
    authFlow, //'popup' | 'redirect' | 'silent' 
    responseMode, //'query' | 'fragment' | 'form_post' | 'web_message'
});

Handle Redirect

Once the user has signed in, they will be redirected to the redirect URI that was set up in the client. This step is required for the user session to be updated and any open sign in popups to close automatically.

...
await authClient.verifyAndLoadUser();

Getting the user

This method can return the current user if signed in.

...
await authClient.getUser();

Sessions

The session object contains the user object as well as the FuturePass address and EOA address.

...
const session = authClient.userSession;
const futurepassAddress = session.futurepass;
const eoaAddress = session.eoa;
const user = session.user;

Sign out

...
await authClient.signOutPass({ 
    flow: 'redirect', // redirect | silent
    postRedirecturi: '<post_logout_redirect_uri>' // optional
    disableConsent: false // "true" by default
});

Source: https://www.npmjs.com/package/@futureverse/auth · captured 2026-05-02