PASETO CLI

A command-line interface for working with PASETO (Platform-Agnostic Security Tokens) using the paseto-ts library.

Features

• Generate PASETO v4 tokens (local and public)
• Encrypt and decrypt payloads
• Sign and verify tokens
• Support for footer data and implicit assertions
• JSON output mode for scripting
• Detailed command-specific help

Installation

1npm install -g paseto-cli

or with npx:

1npx paseto-cli --help

Usage

Generate Keys

1# Generate a local key
2paseto-cli -g local
3
4# Generate a key pair
5paseto-cli -g public
6
7# Generate keys with JSON output
8paseto-cli -g local -j

Encrypt/Decrypt

1# Encrypt a payload
2paseto-cli -c encrypt -k k4.local.YOUR_KEY -p '{"data":"test"}'
3
4# Encrypt with footer and assertion
5paseto-cli -c encrypt -k k4.local.YOUR_KEY -p '{"data":"test"}' -F '{"kid":"key1"}' -a '{"aud":"example"}'
6
7# Decrypt a token
8paseto-cli -c decrypt -k k4.local.YOUR_KEY -t v4.local.ENCRYPTED_TOKEN

Sign/Verify

1# Sign a payload
2paseto-cli -c sign -k k4.secret.YOUR_SECRET_KEY -p '{"data":"test"}'
3
4# Verify a token
5paseto-cli -c verify -k k4.public.YOUR_PUBLIC_KEY -t v4.public.SIGNED_TOKEN

Reading from files

1# Encrypt payload from file
2paseto-cli -c encrypt -k k4.local.YOUR_KEY -f ./payload.json
3
4# Decrypt token from file
5paseto-cli -c decrypt -k k4.local.YOUR_KEY -f ./token.txt

JSON Output

1# Enable JSON output
2paseto-cli -c decrypt -k k4.local.YOUR_KEY -t v4.local.TOKEN -j

Working with Assertions

PASETO supports "implicit assertions" which are used to validate token claims without including them in the token payload. This is useful for validating properties like audience, issuer, or other contextual security information.

Basic Assertion Examples

1# Encrypt with audience assertion
2paseto-cli -c encrypt -k k4.local.YOUR_KEY -p '{"data":"test"}' -a '{"aud":"api.example.com"}'
3
4# Decrypt with audience assertion (will validate the audience claim)
5paseto-cli -c decrypt -k k4.local.YOUR_KEY -t v4.local.TOKEN -a '{"aud":"api.example.com"}'
6
7# Sign with issuer and audience assertions
8paseto-cli -c sign -k k4.secret.YOUR_KEY -p '{"data":"test"}' -a '{"iss":"auth.example.com","aud":"api.example.com"}'
9
10# Verify with multiple assertions
11paseto-cli -c verify -k k4.public.YOUR_KEY -t v4.public.TOKEN -a '{"iss":"auth.example.com","aud":"api.example.com"}'

Complex Assertions

You can use more complex assertions with nested objects:

1# Encrypt with complex assertion structure
2paseto-cli -c encrypt -k k4.local.YOUR_KEY -p '{"data":"test"}' -a '{
3  "aud": "api.example.com",
4  "iss": "auth.example.com",
5  "sub": "user123",
6  "context": {
7    "ip": "192.168.1.1",
8    "userAgent": "Mozilla/5.0",
9    "permissions": ["read", "write"]
10  }
11}'

Combining Assertions and Footers

Assertions and footers can be used together:

1# Encrypt with both footer and assertions
2paseto-cli -c encrypt -k k4.local.YOUR_KEY -p '{"data":"test"}' \
3  -F '{"kid":"key-2022-01"}' \
4  -a '{"aud":"api.example.com"}'

Reading Assertions from File

For complex assertions, you might want to read them from a file:

1# Store your assertions in a file
2echo '{"aud":"api.example.com","iss":"auth.example.com"}' > assertions.json
3
4# Use assertions from file (requires shell that supports command substitution)
5paseto-cli -c verify -k k4.public.YOUR_KEY -t v4.public.TOKEN -a "$(cat assertions.json)"

Help

1# General help
2paseto-cli --help
3
4# Command-specific help
5paseto-cli -c encrypt --help
6paseto-cli -c decrypt --help
7paseto-cli -c sign --help
8paseto-cli -c verify --help

Development

Setup

1# Clone the repository
2git clone https://github.com/auth70/paseto-cli.git
3cd paseto-cli
4
5# Install dependencies
6npm install
7
8# Build the project
9npm run build

Testing

Tests are written with Vitest. The test suite includes unit tests for the CLI functionality.

1# Run tests
2npm test
3
4# Run tests in watch mode
5npm run test:watch

Project Structure

• src/index.ts - CLI entry point
• src/cli.ts - CLI functionality implementation
• test/ - Test files

License

MIT