Server API

npm install @useceleris/server

The package runs on trusted servers only: Node.js 22.15+, Bun 1.3+ and Deno 2.5+. This package holds your signing secret and must never reach a browser or mobile bundle.

The current version is 1.0.0. It declares @useceleris/client ^1.0.0 as a peer dependency and uses it for types only, so client 1.1.0 is in its range.

createSigner(options)

function createSigner(options: SignerOptions): Signer;

type SignerOptions = {
  clientId: string; // no colon, no CR/LF
  signingSecret: string;
  clock?: () => number; // Unix ms; a test seam
};

type Signer = { sign(claims: SigningClaims): SignedCredentials };
type SignedCredentials = {
  readonly payload: string;
  readonly signature: string;
};

sign() is synchronous and deterministic for fixed inputs. It takes no cancellation signal and returns no promise.

import { createSigner } from "@useceleris/server";

const signer = createSigner({
  clientId: process.env.CELERIS_CLIENT_ID!,
  signingSecret: process.env.CELERIS_SIGNING_SECRET!,
});

const credentials = signer.sign({
  channels: { kind: "restricted", references: ["room-42"] },
  permissions: {
    kind: "restricted",
    segments: [{ segmentId: "chat", read: true, write: true }],
  },
  reference: "user-8317",
  replay: { lookbackMs: 30_000 },
});

Pass payload and signature back to the browser unchanged. They are opaque. Never parse, re-encode or cache them.

The claims surface

type SigningClaims = {
  readonly channels: ChannelScope;
  readonly permissions: SegmentPermissions;
  readonly reference?: string;
  readonly replay?: boolean | { readonly lookbackMs: number };
  readonly allowEcho?: boolean;
};

type SegmentClaim = {
  readonly segmentId: string;
  readonly read: boolean;
  readonly write: boolean;
};

Unrestricted access is always an explicit opt-in:

signer.sign({
  channels: { kind: "all" },
  permissions: { kind: "all", read: true, write: false },
});

createCredentialProvider(options)

Sometimes a backend is itself a realtime client, for example a worker that publishes events. This function bridges the signer to the client package's provider.

function createCredentialProvider(
  options: CredentialProviderOptions
): CredentialProvider;

type CredentialProviderOptions = {
  signer: Signer;
  claims: (
    request: CredentialRequest
  ) => SigningClaims | Promise<SigningClaims>;
};

The returned provider checks request.signal before and after it awaits the claims, and then it signs. If the signal aborts, the provider does not sign. You cannot interrupt the synchronous signer itself. The server package re-exports CredentialRequest. See the client types for its fields.

import { createClient } from "@useceleris/client";
import { createCredentialProvider, createSigner } from "@useceleris/server";

const signer = createSigner({
  clientId: process.env.CELERIS_CLIENT_ID!,
  signingSecret: process.env.CELERIS_SIGNING_SECRET!,
});

const client = createClient({
  credentialProvider: createCredentialProvider({
    signer,
    claims: (request) => ({
      channels: { kind: "restricted", references: [request.channelReference] },
      permissions: {
        kind: "restricted",
        segments: [{ segmentId: "chat", read: true, write: true }],
      },
      reference: "worker-1",
      replay:
        request.replayLookbackMs !== undefined
          ? { lookbackMs: Math.min(request.replayLookbackMs, 30_000) }
          : false,
    }),
  }),
});

const channel = client.channel("room-42");
await channel.connect();

Your claims callback runs freshly on every attempt and is the sole authority over scope. The provider copies nothing from the request into the claims automatically. From there you use the ordinary client API to publish and subscribe.

Trusted worker code chooses this example's channel. In an HTTP credential endpoint, authorize the requested channel against the verified user's access before you sign it. The 30-second replay cap is an example application policy, not a retention promise. See Authentication and Reconnection and Recovery.

A fresh signature does not guarantee a particular credential lifetime, and it does not revoke an existing connection. Keep signed credentials confidential and pass them unchanged. The signer has no expiry-duration or revocation option.

Errors

Both failure modes carry a stable code. A Configuration message names each option or claim that failed and the rule it broke, such as Invalid claims. channels.references[0]: Must not be empty.. The message never echoes your input, secrets or claims. The package deliberately does not export the error classes. Identify failures by code.

Both options objects are strict: an unexpected key is a Configuration error, not a silently ignored field.

This rule applies to signer and credential-provider options. The SDK validates claims separately and strips unknown claim keys. Do not rely on an unknown key to grant access or enforce a restriction.