@ralalabs/manifest-signer

JavaScript/TypeScript utility for generating signed restreamer manifest URLs used by Rala Media infrastructure.

A small, runtime-agnostic cryptographic helper designed to work in:

• Node.js 18+
• Browsers
• Cloudflare Workers
• Edge runtimes (WebCrypto-based)

Zero runtime dependencies.

What it does

This package generates deterministic restreamer URLs in the format:

https://<publicHost>/manifest/<sid>.<ext>?u=<sealed>

Compatibility contract

Must match the Media Restreamer implementation:

• sid

  • sid = HMAC-SHA256(PROXY_SECRET_HEX, originUrl) truncated to 16 hex chars (first 8 bytes).

• sealed token (u)

  • AES-256-GCM encrypted JSON payload:

{
  "u": "<originUrl>",
  "iat": 1700000000
}

• AAD (Additional Authenticated Data)

  • "u:manifest:<sid>"

• Wire format (base64url, no padding)

  • [12B IV][16B TAG][CIPHERTEXT]

Features

• Fully typed TypeScript API
• Works in Node + Edge (WebCrypto only)
• ESM + CJS exports
• Deterministic sid
• No runtime dependencies
• Small footprint

Installation

pnpm add @ralalabs/manifest-signer
# or
npm install @ralalabs/manifest-signer

Usage

Basic function

import { signManifest } from '@ralalabs/manifest-signer';

const result = await signManifest({
  originUrl: 'https://cdn.example.com/master.m3u8',
  proxySecretHex: process.env.PROXY_SECRET_HEX!,
  publicHost: 'https://stream.example.com',
});

console.log(result.url);

Using the class (recommended for bulk signing)

Use .sign() when signing many URLs — it reuses cached CryptoKeys per instance.

import { ManifestSigner } from '@ralalabs/manifest-signer';

const signer = new ManifestSigner(process.env.PROXY_SECRET_HEX!);

const signed = await signer.sign(
  'https://cdn.example.com/master.m3u8',
  'https://stream.example.com',
);

console.log(signed.url);

You can also use the object-style wrapper:

const signed2 = await signer.signManifest({
  originUrl: 'https://cdn.example.com/master.m3u8',
  publicHost: 'https://stream.example.com',
});

API

signManifest(input)

| Field | Type | Required | | -------------- | ----------------- | -------- | | originUrl | string | ✅ | | proxySecretHex | string (64hex) | ✅ | | publicHost | string | ✅ | | ext | 'mpd' \| 'm3u8' | optional |

Returns:

{
  url: string;
  sid: string;
  ext: 'mpd' | 'm3u8';
  originUrl: string;
}

new ManifestSigner(proxySecretHex)

• sign(originUrl, publicHost, ext?)
• signManifest({ originUrl, publicHost, ext? })

Runtime compatibility

| Environment | Supported | | ------------------ | --------- | | Node.js 18+ | ✅ | | Browsers | ✅ | | Cloudflare Workers | ✅ | | Bun | ✅ | | Deno | ✅ |

This library relies only on the standard WebCrypto API.

Security notes

• This package does not validate upstream hostnames.
• Keep PROXY_SECRET_HEX secret and never expose it publicly.
• Tokens are infrastructure-level and generally not meant to be user-visible.

License

MIT