feat(rivetkit): canInvoke

[NathanFlurry]

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[railway-app]

🚅 Deployed to the rivet-pr-4237 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
ladle	❌ Build Failed (View Logs)	Web	Feb 19, 2026 at 10:48 pm
website	😴 Sleeping (View Logs)	Web	Feb 19, 2026 at 10:22 pm
frontend-inspector	❌ Build Failed (View Logs)	Web	Feb 19, 2026 at 10:14 pm
frontend-cloud	❌ Build Failed (View Logs)	Web	Feb 19, 2026 at 10:13 pm
mcp-hub	✅ Success (View Logs)	Web	Feb 19, 2026 at 10:13 pm

[NathanFlurry]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• fix(rivetkit): fix run workflow teardown #4239
• feat(rivetkit): canInvoke #4237 👈 (View in Graphite)
• chore(rivetkit): make execute generic #4231
• chore: update workflow queues api #4230
• chore: simplify queue api #4229
• refactor(rivetkit): add typed event and queue schemas for actors #4209 : 1 other dependent PR (#4224 )
• feat: configure rivetkit storage path #4233
• chore(rivetkit): migrate file system driver to sqlite #4206
• main

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[pkg-pr-new]

More templates

• actor-actions
• actor-actions-vercel
• ai-agent
• ai-agent-vercel
• example-ai-and-user-generated-actors-freestyle
• chat-room
• chat-room-vercel
• example-cloudflare-workers
• example-cloudflare-workers-hono
• collaborative-document
• collaborative-document-vercel
• cross-actor-actions
• cross-actor-actions-vercel
• example-cursors
• example-cursors-raw-websocket
• example-cursors-raw-websocket-vercel
• example-cursors-vercel
• custom-serverless
• custom-serverless-vercel
• example-elysia
• example-elysia-vercel
• example-experimental-durable-streams-ai-agent
• example-experimental-durable-streams-ai-agent-vercel
• geo-distributed-database
• geo-distributed-database-vercel
• hello-world
• hello-world-vercel
• example-hono
• hono-react
• hono-react-vercel
• example-hono-vercel
• example-kitchen-sink
• example-kitchen-sink-vercel
• multi-region-vercel
• multiplayer-game
• multiplayer-game-vercel
• native-websockets
• native-websockets-vercel
• next-js
• per-tenant-database
• per-tenant-database-vercel
• example-raw-fetch-handler
• example-raw-fetch-handler-vercel
• example-raw-websocket-handler
• example-raw-websocket-handler-proxy
• example-raw-websocket-handler-proxy-vercel
• example-raw-websocket-handler-vercel
• example-react
• example-react-vercel
• sandbox
• sandbox-coding-agent
• sandbox-coding-agent-vercel
• sandbox-vercel
• scheduling
• scheduling-vercel
• example-sqlite-drizzle
• example-sqlite-raw
• example-sqlite-raw-vercel
• state
• state-vercel
• example-stream
• example-stream-vercel
• example-trpc
• example-trpc-vercel

@rivetkit/virtual-websocket

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/virtual-websocket@4237

@rivetkit/cloudflare-workers

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/cloudflare-workers@4237

@rivetkit/framework-base

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/framework-base@4237

@rivetkit/next-js

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/next-js@4237

@rivetkit/react

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/react@4237

rivetkit

pnpm add https://pkg.pr.new/rivet-dev/rivet/rivetkit@4237

@rivetkit/sql-loader

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sql-loader@4237

@rivetkit/sqlite-vfs

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sqlite-vfs@4237

@rivetkit/traces

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/traces@4237

@rivetkit/workflow-engine

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/workflow-engine@4237

@rivetkit/engine-runner

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner@4237

@rivetkit/engine-runner-protocol

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner-protocol@4237

commit: 6c11637

[claude]

PR Review: feat(rivetkit): canInvoke

This PR adds a canInvoke hook to Rivet actors for fine-grained authorization of inbound invocations. The design is solid and the implementation covers all major entry points. A few issues worth addressing before merging.

---

Bugs / Correctness

1. Error code mismatch in the invalidCanInvokeReturn test

InvalidCanInvokeResponse is constructed with code "invalid_can_invoke_response":

// errors.ts
super("handler", "invalid_can_invoke_response", "Actor's canInvoke hook must return a boolean value.");

But the test expects:

// tests/access-control.ts
await expect(handle.allowedAction("x")).rejects.toMatchObject({
  code: "internal_error",
});

If the client normalizes all 500 responses to internal_error, the test is correct but this should be documented. If not, the test will pass for the wrong reason or fail unexpectedly across transports. The expected code should match the actual error code ("invalid_can_invoke_response") unless there is an intentional normalization layer.

---

2. Semantically incorrect context type in assertCanInvokeWebSocket

// mod.ts
async assertCanInvokeWebSocket(conn: Conn<...>): Promise<void> {
    await this.assertCanInvoke(new ActionContext(this, conn), {
        kind: "websocket",
    });
}

This passes an ActionContext for a websocket kind invocation. For request invocations, a RequestContext is correctly used. If a WebSocketContext is appropriate at this point in the call flow, it should be preferred for consistency. If not (e.g. the WebSocket object does not yet exist), add a comment explaining why ActionContext is used as a stand-in.

---

3. Partial connection state on WebSocket denial

In router-websocket-endpoints.ts:

createdConn = conn;  // already stored

if (isRawWebSocketRoute) {
    await actor.assertCanInvokeWebSocket(conn);  // may throw here
}

If assertCanInvokeWebSocket throws, createdConn is already set but the handler has not been created. Verify that the surrounding cleanup path handles a non-null createdConn with no associated handler correctly, or move the check before assigning createdConn.

---

Minor Issues

4. Missing canInvoke check on unsubscribe is intentional but worth a comment

In old.ts:

if (subscribe) {
    await actor.assertCanInvoke(..., { kind: "subscribe", name: eventName });
    await handler.onSubscribe(eventName, conn);
} else {
    await handler.onUnsubscribe(eventName, conn);  // no check
}

Skipping access control on unsubscribe is reasonable, but a short comment would make the intent clear to future readers.

5. Fragile WebSocket denial test

try {
    const deniedWs = await deniedHandle.webSocket();
    const closeEvent = await new Promise<any>((resolve) => { ... });
    expect(closeEvent.code).toBe(1011);
    denied = true;
} catch {
    denied = true;  // also passes
}
expect(denied).toBe(true);

The catch branch absorbs all errors and marks the test as passing. If webSocket() throws for an unrelated reason (network error, misconfiguration), the test still passes. Consider asserting on the caught error type to distinguish a legitimate denial from an unrelated failure.

6. Documentation: default behavior not explicitly stated

access-control.mdx does not mention what happens when canInvoke is omitted. Stating "If canInvoke is not defined, all invocations are allowed" removes ambiguity for readers.

---

Positive Notes

• The type system design (CanInvokeTarget with conditional generics for narrow name types, AnyCanInvokeTarget for internal use) is clean and well-structured.
• All five entry point kinds are covered with corresponding tests.
• Documentation follows the existing frontmatter schema and is linked correctly from authentication.mdx and the sitemap.
• The fail-by-default pattern is well-promoted in the docs.

[graphite-app]

Merge activity

• Feb 19, 10:48 PM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Feb 19, 10:49 PM UTC: CI is running for this pull request on a draft pull request (#4240) due to your merge queue CI optimization settings.
• Feb 19, 10:50 PM UTC: Merged by the Graphite merge queue via draft PR: #4240.