Cross-Origin Resource Sharing

Cross-Origin Resource Sharing (CORS) controls which origins (domains) can access your actors. When actors are exposed to the public internet, proper origin validation is critical to prevent security breaches and denial of service attacks.

Unlike stateless HTTP APIs that use CORS headers, Rivet Actors are stateful and support persistent WebSocket connections. Since WebSockets don't natively support CORS, we validate origins manually in the onBeforeConnect hook before connections may open.

Implementing Origin Restrictions

To implement origin restrictions on Rivet Actors, use the onBeforeConnect hook to verify the request.

import { actor, UserError } from "rivetkit";

const ALLOWED_ORIGINS = [
  "http://localhost:3000",
  "https://myapp.com",
  "https://www.myapp.com"
];

const myActor = actor({
  state: { count: 0 },

  onBeforeConnect: (c, params) => {
    // Check if origin is allowed
	//
	// This works for both HTTP & WebSocket requests
    const origin = c.request?.headers.get("origin");
    if (!ALLOWED_ORIGINS.includes(origin)) {
      throw new UserError("Origin not allowed", { code: "origin_not_allowed" });
    }
  },

  actions: {
    increment: (c) => {
      c.state.count++;
      return c.state.count;
    }
  }
});

server.ts

To catch the error on the client, use the following code:

import { createClient, ActorError } from "rivetkit/client";
import type { registry } from "./registry";

const client = createClient<typeof registry>();

try {
  const actor = client.myActor.getOrCreate("my-actor");
  const conn = actor.connect();

  // Connection will be established or error will be thrown
  await conn.increment();
} catch (error) {
  if (error instanceof ActorError && error.code === "origin_not_allowed") {
    console.error("Connection rejected: Origin not allowed");
  }
}

client.ts

See tracking issue for configuring CORS per-actor on the gateway that will remove the need to implement origin restrictions in onBforeRequest.