Service: NodeCat - EyevinnOSC/community GitHub Wiki

NodeCat

NodeCat (serviceId andersnas-nodecat) is a NodeJS-based service for generating and validating Common Access Tokens (CAT). CAT is a compact, CBOR-encoded token format designed for streaming media workflows, for example protecting HLS manifest URLs so that only authenticated clients can fetch them. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance. License: Apache-2.0.

What it can do

  • Issue Common Access Tokens through an HTTP API.
  • Validate Common Access Tokens.
  • Add token-based access control to HLS manifests without a session cookie or heavyweight auth layer.

Creating an instance

NodeCat has no dependencies on other OSC services. Store the signing key as a service secret first with create-service-secret (serviceId: "andersnas-nodecat", for example name signingkey), then create the instance with create-service-instance using serviceId: "andersnas-nodecat". The instance name must be alphanumeric and at most 20 characters.

{ "name": "mynodecat", "SigningKey": "{{secrets.signingkey}}" }

Wait with wait-for-service-ready or get-instance-status, then read the instance URL with describe-service-instance.

Options

Option Required Type Meaning
name Yes string Name of the instance. Letters, digits and underscore only; on OSC at most 20 characters.
SigningKey Yes string, sensitive Key used to sign the tokens. Store as a service secret and pass as {{secrets.NAME}}.

A {{secrets.NAME}} reference must be the whole field value. Overwriting a secret does not restart a running instance.

Using the instance

NodeCat exposes an HTTP API for issuing and validating Common Access Tokens.

Issue a token:

curl -X POST https://<instance-url>/token \
  -H "Content-Type: application/json" \
  -d '{"sub": "user123", "exp": 3600}'

Validate a token:

curl https://<instance-url>/validate \
  -H "Authorization: Bearer <token>"

Use case: protecting HLS streams

  1. Your backend mints a short-lived CAT token for each authenticated viewer.
  2. The token is appended to the HLS manifest URL as a query parameter.
  3. A CDN or origin validates the token using NodeCat before serving the manifest.

Resources

⚠️ **GitHub.com Fallback** ⚠️