Feature: Token Vault Branding and Documentation

[btiernay]

Overview

The Auth0 JavaScript SDK already implements secure token storage through 1 and 2 . This specification outlines requirements to rebrand this functionality as "Token Vault" with complete working examples.

Requirements

1. Documentation Updates

Main README Enhancement
Update 3 to include Token Vault terminology in package descriptions.

Server SDK README Section
Add dedicated Token Vault section to 4 replacing current "Configuring the Store" section.

2. Complete Token Vault Examples

Stateless Token Vault (Cookie-based)
Based on the existing 5 :

import { FastifyReply, FastifyRequest } from 'fastify';
import { 
  ServerClient,
  StatelessStateStore,
  CookieTransactionStore,
  CookieHandler
} from '@auth0/auth0-server-js';

// Token Vault - Stateless Implementation
export class FastifyCookieHandler implements CookieHandler<StoreOptions> {
  setCookie(name: string, value: string, options?: any, storeOptions?: StoreOptions): void {
    storeOptions!.reply.setCookie(name, value, options || {});
  }
  
  getCookie(name: string, storeOptions?: StoreOptions): string | undefined {
    return storeOptions!.request.cookies?.[name];
  }
  
  getCookies(storeOptions?: StoreOptions): Record<string, string> {
    return storeOptions!.request.cookies as Record<string, string>;
  }
  
  deleteCookie(name: string, storeOptions?: StoreOptions): void {
    storeOptions!.reply.clearCookie(name);
  }
}

// Token Vault Configuration - Stateless (encrypted cookies)
const auth0 = new ServerClient<StoreOptions>({
  domain: process.env.AUTH0_DOMAIN!,
  clientId: process.env.AUTH0_CLIENT_ID!,
  clientSecret: process.env.AUTH0_CLIENT_SECRET!,
  // Token Vault - Stateless: encrypts all session data in cookies
  stateStore: new StatelessStateStore({ 
    secret: process.env.AUTH0_SECRET! 
  }, new FastifyCookieHandler()),
  transactionStore: new CookieTransactionStore({ 
    secret: process.env.AUTH0_SECRET! 
  }, new FastifyCookieHandler()),
  authorizationParams: {
    redirect_uri: 'http://localhost:3000/auth/callback'
  }
});

// Complete authentication flow with Token Vault
fastify.get('/auth/login', async (request, reply) => {
  const storeOptions = { request, reply };
  const authUrl = await auth0.startInteractiveLogin({}, storeOptions);
  reply.redirect(authUrl.href);
});

fastify.get('/auth/callback', async (request, reply) => {
  const storeOptions = { request, reply };
  await auth0.completeInteractiveLogin(new URL(request.url, 'http://localhost:3000'), storeOptions);
  reply.redirect('/dashboard');
});

// Token Vault automatically handles secure token storage
fastify.get('/api/profile', async (request, reply) => {
  const storeOptions = { request, reply };
  const user = await auth0.getUser(storeOptions);
  const tokenSet = await auth0.getAccessToken(storeOptions);
  
  reply.send({ user, accessToken: tokenSet.accessToken });
});

fastify.get('/auth/logout', async (request, reply) => {
  const storeOptions = { request, reply };
  const logoutUrl = await auth0.logout({ returnTo: 'http://localhost:3000' }, storeOptions);
  reply.redirect(logoutUrl.href);
});

Stateful Token Vault (Server-side)
Based on 6 :

import { FastifyReply, FastifyRequest } from 'fastify';
import { 
  ServerClient,
  StatefulStateStore,
  CookieTransactionStore
} from '@auth0/auth0-server-js';

// Token Vault - Stateful Implementation (most secure)
const auth0 = new ServerClient<StoreOptions>({
  domain: process.env.AUTH0_DOMAIN!,
  clientId: process.env.AUTH0_CLIENT_ID!,
  clientSecret: process.env.AUTH0_CLIENT_SECRET!,
  // Token Vault - Stateful: stores session IDs in cookies, tokens server-side
  stateStore: new StatefulStateStore({ 
    secret: process.env.AUTH0_SECRET!,
    // Custom session store implementation required
    sessionStore: new RedisSessionStore(redisClient)
  }, new FastifyCookieHandler()),
  transactionStore: new CookieTransactionStore({ 
    secret: process.env.AUTH0_SECRET! 
  }, new FastifyCookieHandler()),
  authorizationParams: {
    redirect_uri: 'http://localhost:3000/auth/callback'
  }
});

// Custom Redis session store for Token Vault
class RedisSessionStore {
  constructor(private redis: RedisClient) {}
  
  async get(key: string): Promise<any> {
    const data = await this.redis.get(key);
    return data ? JSON.parse(data) : undefined;
  }
  
  async set(key: string, value: any, ttl?: number): Promise<void> {
    await this.redis.setex(key, ttl || 3600, JSON.stringify(value));
  }
  
  async delete(key: string): Promise<void> {
    await this.redis.del(key);
  }
}

// Environment setup for Token Vault
const requiredEnvVars = [
  'AUTH0_DOMAIN',
  'AUTH0_CLIENT_ID', 
  'AUTH0_CLIENT_SECRET',
  'AUTH0_SECRET', // Used for Token Vault encryption
  'REDIS_URL'     // For stateful Token Vault storage
];

requiredEnvVars.forEach(envVar => {
  if (!process.env[envVar]) {
    throw new Error(`Missing required environment variable: ${envVar}`);
  }
});

Express.js Token Vault Example

import express from 'express';
import session from 'express-session';
import { 
  ServerClient,
  StatefulStateStore,
  CookieTransactionStore,
  CookieHandler
} from '@auth0/auth0-server-js';

interface ExpressStoreOptions {
  request: express.Request;
  response: express.Response;
}

class ExpressCookieHandler implements CookieHandler<ExpressStoreOptions> {
  setCookie(name: string, value: string, options: any, storeOptions?: ExpressStoreOptions): void {
    storeOptions!.response.cookie(name, value, options);
  }
  
  getCookie(name: string, storeOptions?: ExpressStoreOptions): string | undefined {
    return storeOptions!.request.cookies[name];
  }
  
  getCookies(storeOptions?: ExpressStoreOptions): Record<string, string> {
    return storeOptions!.request.cookies;
  }
  
  deleteCookie(name: string, storeOptions?: ExpressStoreOptions): void {
    storeOptions!.response.clearCookie(name);
  }
}

const app = express();
app.use(express.json());
app.use(require('cookie-parser')());

// Token Vault with Express
const auth0 = new ServerClient<ExpressStoreOptions>({
  domain: process.env.AUTH0_DOMAIN!,
  clientId: process.env.AUTH0_CLIENT_ID!,
  clientSecret: process.env.AUTH0_CLIENT_SECRET!,
  stateStore: new StatefulStateStore({ 
    secret: process.env.AUTH0_SECRET! 
  }, new ExpressCookieHandler()),
  transactionStore: new CookieTransactionStore({ 
    secret: process.env.AUTH0_SECRET! 
  }, new ExpressCookieHandler()),
  authorizationParams: {
    redirect_uri: 'http://localhost:3000/auth/callback'
  }
});

app.get('/auth/login', async (req, res) => {
  const storeOptions = { request: req, response: res };
  const authUrl = await auth0.startInteractiveLogin({}, storeOptions);
  res.redirect(authUrl.href);
});

app.get('/auth/callback', async (req, res) => {
  const storeOptions = { request: req, response: res };
  await auth0.completeInteractiveLogin(new URL(req.url, 'http://localhost:3000'), storeOptions);
  res.redirect('/dashboard');
});

3. Token Vault Security Features

The existing implementation provides these Token Vault security features through 7 :

• AES Encryption: All session data encrypted with secret key
• Cookie Chunking: Large tokens split across multiple cookies 8
• Automatic Token Refresh: Handled by 9
• Backchannel Logout: Supported via 10

Implementation Deliverables

1. Updated README sections with Token Vault branding
2. Complete working examples for Fastify, Express, and Next.js
3. Environment configuration guides for both Token Vault modes
4. Migration documentation showing how existing implementations already use Token Vault

Notes

The existing secure storage architecture 2 already provides enterprise-grade Token Vault functionality. This specification focuses on rebranding and providing comprehensive examples that demonstrate the full authentication lifecycle with proper Token Vault configuration.

[arpit-jn]

Thank you @btiernay for putting together this detailed specification for the Token Vault rebranding. This is a great proposal.

To ensure this gets the broader visibility it deserves, both for internal review and community feedback, I'm moving this to GitHub Discussions. That's the perfect forum for us to collaborate on refining this plan before breaking it down into actionable issues.

Looking forward to continuing the conversation there.