moq-token

JWT authentication library and CLI tool for MoQ relay authentication.

Overview

moq-token provides:

• Library - Generate and verify JWT tokens in Rust
• CLI - Command-line tool for key and token management
• Multiple algorithms - HMAC, RSA, ECDSA, EdDSA

Installation

Library

Add to your Cargo.toml:

[dependencies]
moq-token = "0.1"

CLI

cargo install moq-token-cli

The binary is named moq-token-cli.

Using Nix

# Run directly
nix run github:moq-dev/moq#moq-token-cli

# Or build and find the binary in ./result/bin/
nix build github:moq-dev/moq#moq-token-cli

Using Docker

docker pull kixelated/moq-token-cli
docker run -v "$(pwd):/app" -w /app kixelated/moq-token-cli --key root.jwk generate

Multi-arch images (linux/amd64 and linux/arm64) are published to Docker Hub.

CLI Usage

Generate a Key

# Symmetric key (HMAC)
moq-token-cli generate --out root.jwk --algorithm HS256

# Asymmetric key pair (RSA)
moq-token-cli generate --algorithm RS256 --out private.jwk --public public.jwk

# Asymmetric key pair (EdDSA)
moq-token-cli generate --algorithm EdDSA --out private.jwk --public public.jwk

Sign a Token

moq-token-cli sign --key root.jwk \
  --root "rooms/123" \
  --publish "alice" \
  --subscribe "" \
  --expires 1735689600 > alice.jwt

Verify a Token

moq-token-cli verify --key root.jwk < alice.jwt

Supported Algorithms

Symmetric (HMAC):

• HS256
• HS384
• HS512

Asymmetric (RSA):

• RS256, RS384, RS512
• PS256, PS384, PS512

Asymmetric (Elliptic Curve):

• EC256, EC384
• EdDSA

Library Usage

Generate a Key

use moq_token::*;

// Generate HMAC key
let key = Key::generate(Algorithm::HS256, None)?;
key.to_file("root.jwk")?;

// Generate RSA key pair
let key = Key::generate(Algorithm::RS256, None)?;
key.to_public()?.to_file("public.jwk")?;
key.to_file("private.jwk")?;

Sign a Token

use moq_token::*;

let key = Key::from_file("root.jwk")?;

let claims = Claims {
    root: "rooms/123".to_string(),
    publish: vec!["alice".to_string()],
    subscribe: vec!["".to_string()],
    ..Default::default()
};

let token = key.encode(&claims)?;
println!("Token: {}", token);

Verify a Token

use moq_token::*;

let key = Key::from_file("root.jwk")?;
let claims = key.decode(&token)?;

println!("Root: {}", claims.root);
println!("Publish: {:?}", claims.publish);
println!("Subscribe: {:?}", claims.subscribe);

Token Claims

Claim	Type	Description
root	string	Root path for all operations
put	string | string[]?	Publishing permission paths
get	string | string[]?	Subscription permission paths
cluster	bool?	Cluster node flag
exp	number?	Expiration (Unix timestamp)
iat	number?	Issued at (Unix timestamp)

Integration with moq-relay

Configure the relay to use your key:

[auth]
key = "root.jwk"
public = "anon"  # Optional: anonymous access

See Relay Authentication for details.

Security Considerations

• Symmetric keys should only be used when the same entity signs and verifies
• Asymmetric keys are preferred for distributed systems (relay only needs public key)
• Token expiration should be set appropriately for your use case
• Secure transmission - Only transmit tokens over HTTPS
• Secure storage - Keep private keys secure

JWK Set Support

For key rotation, you can host a JWK set:

{
  "keys": [
    {
      "kid": "2026-01-01",
      "alg": "RS256",
      "kty": "RSA",
      "n": "...",
      "e": "AQAB"
    }
  ]
}

Configure the relay:

[auth]
key = "https://auth.example.com/keys.json"
refresh_interval = 86400

API Reference

Full API documentation: docs.rs/moq-token

Next Steps

• Configure Relay Authentication
• Deploy a Relay Server
• Learn about Authentication