oRPC

Requires: @orpc/server 2.x (beta)

PurposeCopy Anchor Link

oRPC is contract-first and generates OpenAPI natively, which makes it the RPC framework where the OpenAPI 3.2 story is most direct. permdock/orpc mirrors the tRPC adapter: ctx.permdock on every procedure, protect(permission, load) as a middleware after input validation, ORPCError denials carrying Problem Details, and openapi.security(permission) so the operation's security requirement can be attached with oRPC 2's openapi() metadata helper.

APICopy Anchor Link

// server/permdock.ts
import { os } from "@orpc/server";
import { openapi as orpcOpenapi } from "@orpc/openapi";
import { createPermDock } from "permdock/orpc";
import { policy } from "./policy";
import { permissions } from "./permissions";

export const { permdock, protect, openapi } = createPermDock(policy, {
  subject: ({ context }) => context.user ?? null,
});

export const base = os.$context<Context>().use(permdock()); // context.permdock is the request-scoped PermDock

// server/routers/posts.ts
export const remove = base
  .meta(
    orpcOpenapi({
      method: "DELETE",
      path: "/posts/{id}",
      spec: openapi.security(permissions.post.delete),
    }),
  )
  .input(z.object({ id: z.string() }))
  .use(protect(permissions.post.delete, ({ input }) => loadPost(input.id)))
  .handler(async ({ context }) => deletePost(context.permdockData));

export const list = base
  .meta(orpcOpenapi({ method: "GET", path: "/posts" }))
  .handler(async ({ context }) =>
    context.permdock.filter(permissions.post.read, await listPosts()),
  );

Contract-firstCopy Anchor Link

protect and permdock() attach to procedures from implement(contract) as they do to os procedures, including procedures whose contract declares an output. The contract package imports securityFor from permdock/openapi for each operation's security, without the policy (contract packages).

// contract.ts: permissions only
export const contract = { posts: { update: oc.input(byId).output(post) } };
export const security = {
  "posts.update": securityFor(permissions.post.update),
};

// server.ts
const os = implement(contract).$context<Context>();
export const router = os.router({
  posts: {
    update: os
      .use(permdock())
      .posts.update.use(
        protect(permissions.post.update, ({ input }) => loadPost(input.id)),
      )
      .handler(({ context }) => context.permdockData),
  },
});

Typed errorsCopy Anchor Link

Declare FORBIDDEN in the contract with problemDetails from permdock/openapi as its data schema. protect then throws through the procedure's own errors.FORBIDDEN constructor, so clients get a defined error whose data is typed as ProblemDetails, and the OpenAPI generator documents the 403 body. Without the declaration, protect throws a plain ORPCError with the same data. UNAUTHORIZED, BAD_REQUEST and the other codes protect uses work the same way when the contract declares them.

// contract.ts
import { problemDetails } from "permdock/openapi";

const guarded = oc.errors({ FORBIDDEN: { status: 403, data: problemDetails } });
export const contract = { posts: { update: guarded.input(byId).output(post) } };

// client
const [error] = await safe(client.posts.update({ id }));
if (isDefinedError(error) && error.code === "FORBIDDEN") {
  error.data.permission; // 'post.update'
}

problemDetails is a Standard Schema that also implements Standard JSON Schema (draft-2020-12, draft-07, openapi-3.0). It requires type, title, status (400 to 599) and detail, and passes extension members through. It imports nothing, so a contract package can use it.

Event iteratorsCopy Anchor Link

A procedure behind protect(permission, load?, { items }) whose handler returns an event iterator is wrapped the same way as a tRPC subscription: items the subscriber cannot read are dropped, load runs again only on revalidation, and an abort ends the iterator with an ORPCError (UNAUTHORIZED or FORBIDDEN) whose data is the Problem Details body. Pass revocations to createPermDock; connection(opts, options?) opens a Connection by hand.

With better-supabaseCopy Anchor Link

better-supabase's createOrpc puts the verified AuthState on context.auth through bs.middleware(), which also adds context.db. Map it with subjectFromBetterSupabase; pass its apiKeys option when API keys reach the router. Export one builder that takes a permission and keeps bs.middleware() inside it: a procedure built any other way has no context.db, and one built with procedure() does not compile without a permission. Serve the router with bs.fetchHandler.

import { os } from "@orpc/server";
import { createOrpc, type OrpcRequestContext } from "better-supabase/orpc";
import type { AuthState } from "better-supabase/server";
import type { Permission } from "permdock";
import { createPermDock } from "permdock/orpc";
import { subjectFromBetterSupabase } from "permdock/better-supabase";

export const bs = createOrpc(betterSupabase);

const authed = os.$context<OrpcRequestContext>().use(bs.middleware());
const { protect } = createPermDock<
  OrpcRequestContext & { readonly auth: AuthState }
>(policy, {
  subject: ({ context }) =>
    subjectFromBetterSupabase(context.auth, { anonymousSignIns: "deny" }),
});

const procedure = (permission: Permission) => authed.use(protect(permission));

export const router = {
  customers: {
    list: procedure(permissions.customers.read).handler(({ context }) =>
      bs.unwrap(context.db.customers.findMany({ select: ["id", "name"] })),
    ),
  },
};

protect throws FORBIDDEN with PermDock's Problem Details as data, the same shape bs.unwrap gives a DbError. @orpc/server must satisfy better-supabase's peer range (2.0.0-beta.40 or later).

Request lifecycleCopy Anchor Link

permdock/orpc follows the shared adapter contract with oRPC-specific steps:

• protect (or openapi.protect) runs after oRPC's input validation and hands the row on as context.permdockData. protect requires permdock in the inferred context, so the wrong order is a type error. Both guards stay exported: openapi.protect is the same guard for apps that generate OpenAPI and read it next to openapi.security.
• A PermDock error thrown in a handler propagates through permdock() and protect(), which rethrow it as the same ORPCError a guard denial produces, with the Problem Details body as data; the OpenAPI handler writes that body as application/problem+json.
• When OpenAPIGenerator runs, openapi({ spec }) metadata from each procedure carries the security fragment from openapi.security.

How denials surfaceCopy Anchor Link

• denied: ORPCError code FORBIDDEN, HTTP status 403, data carrying the Problem Details object. Through the OpenAPI handler the response body is application/problem+json.
• approval-required: FORBIDDEN with data.type ending in /approval-required and data.token.
• Boundary validation failure: BAD_REQUEST with issues.
• Anonymous subject: UNAUTHORIZED.

Example appCopy Anchor Link

apps/examples/orpc: oRPC with permdock() and protect on posts.update (granted) and posts.publish (denied for member). Unit tests call procedures through call() and assert ORPCError codes and Problem Details data.

tests/integration/src/http/orpc.test.ts runs the testHttpAdapter scenarios over RPCHandler with BatchHandlerPlugin on @hono/node-server and an RPCLink client with BatchLinkPlugin. Uploads are skipped: the mount takes JSON input.

Related standardsCopy Anchor Link

• OpenAPI 3.2.
• Problem Details.
• AuthZEN for the decision endpoint.