Passport-PASETO

A Passport strategy for authenticating with a PASETO (Platform-Agnostic Security Tokens) v4 token.

This module lets you authenticate endpoints using PASETO tokens in your Node.js applications. It supports both PASETO v4.local (symmetric encryption) and v4.public (asymmetric signatures) purposes. It uses paseto-ts under the hood.

Installation

npm install passport-paseto passport passport-strategy express

Note: This package requires express and passport-strategy as peer dependencies, as well as paseto-ts which is included as a direct dependency.

Usage

Configure Strategy

The PASETO authentication strategy authenticates users using a PASETO v4 token. The strategy requires a secretOrKey for verification or decryption, the purpose of the token (local or public), and an extractor function to retrieve the PASETO from the request.

import { Strategy as PasetoStrategy, ExtractPaseto, StrategyOptions } from 'passport-paseto';
import passport from 'passport';

const opts: StrategyOptions = {
    pasetoFromRequest: ExtractPaseto.fromAuthHeaderAsBearerToken(),
    purpose: 'local', // Use 'public' for asymmetric tokens
    key: 'k4.local.your_secret_key_here...' // PASERK string or Uint8Array
};

passport.use(new PasetoStrategy(opts, (payload, done) => {
    User.findOne({ id: payload.sub }, (err, user) => {
        if (err) {
            return done(err, false);
        }
        if (user) {
            return done(null, user);
        } else {
            return done(null, false);
            // or you could create a new account
        }
    });
}));

Options

• key: (REQUIRED) A string (PASERK format) or Uint8Array representing the key used to verify/decrypt the token. For purpose: 'local', this is the symmetric key. For purpose: 'public', this is the public key.
• purpose: (REQUIRED) The PASETO version/purpose to use. Must be either 'local' (symmetric encryption) or 'public' (asymmetric signatures).
• pasetoFromRequest: (REQUIRED) A function that accepts a request as the only parameter and returns either the PASETO as a string or null. See Extracting the PASETO below.
• passReqToCallback: (OPTIONAL) If true, the verify callback will be called with req as the first argument (e.g. (req, payload, done)). Defaults to false.
• assertion: (OPTIONAL) A JSON-stringifyable object, string, or buffer to validate against the token's implicit assertion.
• maxDepth: (OPTIONAL) Maximum depth of the JSON in the payload. Defaults to 32. Set to 0 to disable.
• maxKeys: (OPTIONAL) Maximum number of keys in the payload object. Defaults to 128. Set to 0 to disable.
• validatePayload: (OPTIONAL) If true, validates standard PASETO registered claims (like exp, iat, nbf). Defaults to true.

Extracting the PASETO

There are several ways to include a PASETO in a request. The ExtractPaseto class provides factory functions that return pasetoFromRequest extractors.

• ExtractPaseto.fromHeader(header_name)
• ExtractPaseto.fromBodyField(field_name)
• ExtractPaseto.fromUrlQueryParameter(param_name)
• ExtractPaseto.fromAuthHeaderWithScheme(auth_scheme)
• ExtractPaseto.fromAuthHeaderAsBearerToken()
• ExtractPaseto.fromExtractors([array of extractor functions])

Authenticate Requests

Use passport.authenticate(), specifying the 'paseto' strategy, to authenticate requests.

app.get('/profile', passport.authenticate('paseto', { session: false }),
    (req, res) => {
        res.send(req.user.profile);
    }
);

Running Tests

pnpm install
pnpm test

License

MIT