1 release (0 unstable)
1.0.1-beta.1 | Jul 26, 2024 |
---|
#222 in Command line utilities
62KB
536 lines
PASETO CLI
PASETO CLI generates and validates PASETO v4.local tokens.
Quick Start
Installation
// Available on NPM
npm i -g @govcraft/paseto_cli@latest
Or with Cargo or direct install from binary.
Generate a Token
echo "your-32-byte-key-in-base64" | paseto_cli generate --subject "user123" --expiration "2h"
Validate a Token
echo "your-32-byte-key-in-base64" | paseto_cli validate --token "v4.local.your-token-here" --subject "user123"
Features
- Generates PASETO v4.local tokens with custom claims
- Validates existing tokens and verifies their claims
- Supports multiple output formats: plain, pretty, and JSON
- Handles relative time expressions (e.g., "2h", "1d")
- Adheres to PASETO best practices
- Implicit assertion and Footer support will be added before 1.0 release
Table of Contents
Installation
Download Release Binary
You can download the precompiled binary for your system directly from the PASETO CLI Releases page. This is the easiest method to get started quickly.
Using npm
To install PASETO CLI using npm, run the following command:
npm i -g @govcraft/paseto_cli@latest
This will install the PASETO CLI tool globally on your system.
Using Cargo (Rust's package manager)
If you have Rust installed on your system, you can use Cargo, Rust's package manager, to install PASETO CLI. First, ensure you have Rust and Cargo installed (you can get them from rustup.rs), then run:
cargo install paseto_cli
This command will download, compile, and install the PASETO CLI tool on your system.
From Source
To build from source:
git clone https://github.com/Govcraft/paseto-cli.git
cd paseto-cli
cargo build --release
The binary will be available at target/release/paseto_cli
.
Usage
PASETO CLI provides two main commands: generate
and validate
.
Generate a Token
echo "your-32-byte-key-in-base64" | paseto_cli generate [OPTIONS]
Options:
-s, --subject <SUBJECT>
: Sets the subject claim-i, --issuer <ISSUER>
: Sets the issuer claim-a, --audience <AUDIENCE>
: Sets the audience claim--jti <JTI>
: Sets the token identifier claim--expiration <EXPIRATION>
: Sets the expiration time--not-before <NOT_BEFORE>
: Sets the not-before time--issued-at <ISSUED_AT>
: Sets the issued-at time-c, --custom <KEY=VALUE>
: Adds custom claims
Validate a Token
echo "your-32-byte-key-in-base64" | paseto_cli validate --token <TOKEN> [OPTIONS]
Options:
-t, --token <TOKEN>
: Specifies the PASETO token to validate (required)-s, --subject <SUBJECT>
: Specifies the expected subject claim-i, --issuer <ISSUER>
: Specifies the expected issuer claim-a, --audience <AUDIENCE>
: Specifies the expected audience claim--jti <JTI>
: Specifies the expected token identifier claim--expiration <EXPIRATION>
: Specifies the expected expiration time--not-before <NOT_BEFORE>
: Specifies the expected not-before time--issued-at <ISSUED_AT>
: Specifies the expected issued-at time-c, --custom <KEY=VALUE>
: Specifies expected custom claims
Global Options
-f, --format <FORMAT>
: Sets the output format (plain, pretty, json)-h, --help
: Prints help information-V, --version
: Prints version information
Examples
Generate a Token with Custom Claims
echo "your-32-byte-key-in-base64" | paseto_cli generate --subject "user123" --expiration "2h" --custom role=admin
Validate a Token with Pretty Output
echo "your-32-byte-key-in-base64" | paseto_cli --format pretty validate --token "v4.local.your-token-here" --subject "user123"
Generate a Token with JSON Output
echo "your-32-byte-key-in-base64" | paseto_cli --format json generate --subject "user123" --expiration "2h"
Use Cases
- User Authentication: Generates tokens for user login systems.
- API Authorization: Includes role-based access control in tokens.
- Single Sign-On (SSO): Creates tokens for multi-service authentication.
- API Key Management: Generates and validates long-lived API keys.
- Session Management: Creates short-lived tokens for web application sessions.
- Microservices Communication: Secures inter-service data exchange.
- IoT Device Authentication: Authenticates IoT devices with central servers.
- Audit Logging: Tracks user actions with custom claims for logs.
- Testing and Development: Generates specific tokens for auth flow testing.
- Token Rotation: Implements token rotation strategies.
Security Considerations
- Key Management: Store the PASETO v4 key securely.
- Token Lifetime: Set appropriate expiration times based on security requirements.
- Claim Validation: Validate all relevant claims when verifying tokens.
- Encrypted Payload: v4.local tokens encrypt their payload, protecting the confidentiality of claims. The encryption key must be kept secure.
- Key Rotation: Implement a strategy to periodically update the PASETO v4 key.
Contributing
Contributions are welcome. See Contributing Guidelines for more details.
License
PASETO CLI is licensed under the GNU General Public License v3.0. See the LICENSE file for details.
About the Author
I'm @rrrodzilla, a technologist with 30 years of industry experience. I'm a former SOA and cloud architect, and former Principal Technical Product Manager at AWS for the Rust Programming Language. Currently, I'm the owner and operator of Govcraft, building and consulting on Rust and AI solutions.
For more information, visit https://www.govcraft.ai
For issues, feature requests, or questions, open an issue at https://github.com/Govcraft/paseto-cli/issues.
Dependencies
~12–22MB
~410K SLoC