auth

@moq/auth

The authorization contract for Media over QUIC, in TypeScript: the request a relay sends per session and the grant an auth server answers with, plus the JWT a client presents in its query and the keys that sign and verify it. For the contract, the relay flags, and worked examples, see the Authentication Documentation.

Grants and claims name paths with patterns from @moq/pattern: foo is one broadcast, foo/** is a subtree, ** is everything. A role may also carry a bitrate cap, written {"path": [...], "rate": bps} and parsed into publish_rate or subscribe_rate beside the patterns.

Installation

npm add @moq/auth

CLI

To use as a CLI (with node installed)

npm install -g @moq/auth
moq-auth generate ...

You can also just directly use it via bun as:

bunx @moq/auth generate ...

Usage

Generation

You would first generate a key as so:

import { Key } from "@moq/auth";
// Use this for signing
const key = await Key.generate("HS256");

or as a CLI

# generate secret key
moq-auth generate --out key.jwk

The default is HS256, you can choose other algorithms with --algorithm:

moq-auth generate --out key.jwk --algorithm ES256

Signing

You can sign a token as shown below:

import { type Claims, Key } from "@moq/auth";

const key = Key.parse(keyString); // See generate example above
// Create claims
const claims: Claims = {
  root: "demo",
  publish: ["bbb/**"], // `demo/bbb` and everything beneath it
  subscribe: ["**"], // Any broadcast under `demo/`
  exp: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now (in seconds)
  iat: Math.floor(Date.now() / 1000), // Issued at (in seconds)
};

// Sign a token
const token = await Key.sign(key, claims);

Or you can sign as a CLI

moq-auth sign --key "root.jwk" \
  --root "rooms/meeting-123" \
  --subscribe "**" \
  --publish "alice/**" \
  --expires 1703980800 > "alice.jwt"

Verifying

You can also verify a token, then scope it to a connection path the way moq auth serve does:

import { authorize, Key } from "@moq/auth";

const claims = await Key.verify(key, token); // signature, kid, strict claims, and expiry
const permissions = authorize(claims, "rooms/meeting-123"); // patterns relative to the path

Or as a CLI:

moq-auth verify --key root.jwk --in alice.jwt

Answering a relay

A server implementing the contract validates what the relay sends and answers a grant. encodeGrant writes a cap into its role, where the relay reads it:

import { encodeGrant, type Grant, RequestSchema } from "@moq/auth";

const request = RequestSchema.parse(await body.json());
const grant: Grant = { subscribe: ["**"], subscribe_rate: 8_000_000, expires: 4102444800, revalidate: 60 };
return Response.json(encodeGrant(grant));

Working example

See examples/sign-and-verify.ts for a complete working example.

License

MIT OR Apache-2.0