https://github.com/ysdragon/ring-jwt
JWT library for the Ring programming language
https://github.com/ysdragon/ring-jwt
jwt ring-programming-language
Last synced: 2 months ago
JSON representation
JWT library for the Ring programming language
- Host: GitHub
- URL: https://github.com/ysdragon/ring-jwt
- Owner: ysdragon
- License: mit
- Created: 2025-08-20T18:43:55.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-08-28T07:51:49.000Z (8 months ago)
- Last Synced: 2025-10-10T09:46:44.435Z (7 months ago)
- Topics: jwt, ring-programming-language
- Language: Ring
- Homepage:
- Size: 54.7 KB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Ring JWT
[license]: https://img.shields.io/github/license/ysdragon/ring-jwt?style=for-the-badge&logo=opensourcehardware&label=License&logoColor=C0CAF5&labelColor=414868&color=8c73cc
[![][license]](https://github.com/ysdragon/ring-jwt/blob/main/LICENSE)
[ring]: https://img.shields.io/badge/Made_with_❤️_for-Ring-2D54CB?style=for-the-badge
[![][ring]](https://ring-lang.net/)
**JWT authentication and authorization library for the Ring programming language.**
## Features
- **JWT Encoding:** Create JSON Web Tokens with a given payload and secret.
- **JWT Decoding & Verification:** Decode JWTs and verify their signature and expiration.
- **Multiple Algorithm Support:** Supports HMAC, RSA PKCS#1 v1.5, and RSA-PSS algorithms.
- **Flexible Signing:** Choose from 9 different signing algorithms for various security needs.
## Supported Algorithms
Ring JWT supports the following JWT signing algorithms:
### HMAC Algorithms (Symmetric)
- **HS256** - HMAC with SHA-256
- **HS384** - HMAC with SHA-384
- **HS512** - HMAC with SHA-512
### RSA Algorithms (Asymmetric - PKCS#1 v1.5)
- **RS256** - RSA with SHA-256
- **RS384** - RSA with SHA-384
- **RS512** - RSA with SHA-512
### RSA-PSS Algorithms (Asymmetric - Probabilistic Signature Scheme)
- **PS256** - RSA-PSS with SHA-256
- **PS384** - RSA-PSS with SHA-384
- **PS512** - RSA-PSS with SHA-512
### Currently Unsupported Algorithms
The following algorithms are **not yet supported**:
- **ES256/ES384/ES512** - ECDSA (Elliptic Curve Digital Signature Algorithm)
- **EdDSA** - Edwards-curve Digital Signature Algorithm
- **none** - Unsigned tokens (intentionally not supported for security reasons)
## Installation
This library can be installed using the Ring Package Manager (RingPM).
```bash
ringpm install ring-jwt from ysdragon
```
## Usage
### Basic JWT Operations (HMAC)
The core functionality is provided by the `JWT` class. By default, it uses **HS256**.
```ring
load "jwt.ring"
oJWT = new JWT
cSecret = "your_super_secret_key_here"
# Example Payload
payload = [
:sub = "user123",
:iat = unixtime(),
:exp = unixtime() + 3600, # Expires in 1 hour
:role = "member"
]
# Encode the token
cToken = oJWT.Encode(payload, cSecret)
? "Encoded JWT: " + cToken
# Decode and verify the token
try
aDecodedPayload = oJWT.Decode(cToken, cSecret)
? "Decoded Payload: " + list2code(aDecodedPayload)
catch
? "Error decoding token: " + cCatchError
done
```
### Using Different HMAC Algorithms
```ring
load "jwt.ring"
# Use HS384
oJWT = new JWT {
algorithm = "HS384"
}
cSecret = "your_super_secret_key_here"
payload = [:sub = "user123", :iat = unixtime()]
cToken = oJWT.Encode(payload, cSecret)
aDecodedPayload = oJWT.Decode(cToken, cSecret)
```
### Using RSA Algorithms (Asymmetric)
RSA algorithms require a private key for signing and a public key for verification.
```ring
load "jwt.ring"
# Use RS256 (RSA with SHA-256)
oJWT = new JWT {
algorithm = "RS256"
}
# Read RSA keys
privateKey = read("private_key.pem")
publicKey = read("public_key.pem")
payload = [:sub = "user123", :iat = unixtime()]
# Sign with private key
cToken = oJWT.Encode(payload, privateKey)
# Verify with public key
aDecodedPayload = oJWT.Decode(cToken, publicKey)
```
### Using RSA-PSS Algorithms
RSA-PSS provides enhanced security with probabilistic padding.
```ring
load "jwt.ring"
# Use PS256 (RSA-PSS with SHA-256)
oJWT = new JWT {
algorithm = "PS256"
}
privateKey = read("private_key.pem")
publicKey = read("public_key.pem")
payload = [:sub = "user123", :iat = unixtime()]
cToken = oJWT.Encode(payload, privateKey)
aDecodedPayload = oJWT.Decode(cToken, publicKey)
```
### 2. API Reference
#### `JWT` Class
The `JWT` class provides methods for encoding and decoding JSON Web Tokens.
##### `new JWT()`
Creates a new instance of the `JWT` class.
**Properties:**
- `algorithm` (String): The signing algorithm to use. Default is `"HS256"`.
- Supported values: `"HS256"`, `"HS384"`, `"HS512"`, `"RS256"`, `"RS384"`, `"RS512"`, `"PS256"`, `"PS384"`, `"PS512"`
**Example:**
```ring
# Create JWT with default algorithm (HS256)
oJWT = new JWT
# Create JWT with specific algorithm
oJWT = new JWT {
algorithm = "RS256"
}
```
##### `Encode(payload, secret)`
Encodes a given payload into a JWT string.
**Parameters:**
- `payload` (List): The data to be encoded into the JWT. This should be a Ring list.
- `secret` (String): The secret key or private key used for signing the JWT.
- For HMAC algorithms (HS256/HS384/HS512): Use a shared secret string
- For RSA algorithms (RS*/PS*): Use a PEM-formatted private key string
**Returns:** (String) The encoded JWT string.
**Example:**
```ring
# HMAC
payload = [:sub = "user123", :iat = unixtime()]
token = oJWT.Encode(payload, "my-secret-key")
# RSA
privateKey = read("private_key.pem")
token = oJWT.Encode(payload, privateKey)
```
##### `Decode(token, secret)`
Decodes a JWT string, verifies its signature, and returns the payload.
**Parameters:**
- `token` (String): The JWT string to decode.
- `secret` (String): The secret key or public key used for verifying the JWT's signature.
- For HMAC algorithms (HS256/HS384/HS512): Use the same shared secret string used for encoding
- For RSA algorithms (RS*/PS*): Use a PEM-formatted public key string
**Returns:** (List) The decoded payload as a Ring list.
**Raises/Throws:**
- `Invalid token format` if the token does not have three parts.
- `Token has expired` if the `exp` claim in the payload indicates the token is expired.
- `Invalid signature` if the token's signature is invalid.
**Example:**
```ring
# HMAC
decoded = oJWT.Decode(token, "my-secret-key")
# RSA
publicKey = read("public_key.pem")
decoded = oJWT.Decode(token, publicKey)
```
## Examples
You can find various usage examples in the [`examples`](examples).
## Contributing
Contributions are welcome! Please feel free to open issues or submit pull requests.
## License
This project is licensed under the [MIT License](LICENSE).