Extend PermDock

PermDock is extended through options on the functions you already call. Each need below has one extension point, and none of them can turn a denial into a grant.

App dataCopy Anchor Link

Every definition takes an x field for data your application owns: a risk level, an owning team, a ticket id, a department. PermDock checks that it is plain JSON, freezes it, carries it to decisions, events, snapshots and the catalog, and never reads it.

import { z } from "zod";

const permissions = definePermissions(
  {
    invoice: resource(Invoice, {
      actions: { pay: { title: "Pay invoice", x: { risk: "high" } }, read: {} },
      meta: { title: "Invoice", x: { owner: "billing" } },
    }),
  },
  {
    x: {
      permission: z.object({ risk: z.enum(["low", "high"]) }),
      resource: z.object({ owner: z.string() }),
    },
  },
);

const roles = defineRoles(
  { clerk: { meta: { title: "Clerk", x: { tier: 1 } } } },
  { x: z.object({ tier: z.number() }) },
);

export const policy = definePolicy(
  { permissions, roles },
  {
    roles: [
      role(roles.clerk, [
        allow(permissions.invoice.pay, {
          name: "clerk-pays",
          meta: { description: "Clerks pay invoices", x: { ticket: "FIN-1" } },
        }),
      ]),
    ],
    principal: (user) => user,
    x: {
      grant: z.object({ ticket: z.string() }),
      membership: z.object({ department: z.string() }),
    },
  },
);

Data you write in code throws when it is invalid, because that is an author error. Data a MembershipSource or RoleSource returns is dropped when invalid, because a request should never fail on a bad row: the x goes, the membership or role stays. Each schema must validate synchronously. With a schema, the field takes its output type; without one, it is AppData, a plain JSON object.

All of it is visible to whoever holds a snapshot: grant meta, membership x and every leaf's meta ship to the client. Never put a secret in x. Grant meta stays out of the policy fingerprint, so editing a description invalidates no decision or approval token. The Supabase sources read Membership.x from a jsonb column (fromTable({ columns: { x } }), fromJunction({ x })) and the token hook never writes it into claims (tenancy).

Request dataCopy Anchor Link

A condition can read context.<key>. The policy's own context function loads values once per subject; an adapter's context hook adds values from the request itself:

import { createPermDock } from "permdock/hono";

const { protect } = createPermDock(policy, {
  subject: (c) => c.get("user"),
  context: (c) => ({ region: c.get("geo").region }),
});

The hook returns a plain JSON object, merged into subject.context under the policy's context: on a clash, the policy's key wins. A hook that throws, or returns something other than a JSON object, adds no request context and reports through on('error'). It cannot set the subject, memberships, tenant or actor.

Return only values the server derived: a verified session field, a geo lookup your edge did, a flag the server evaluated. A header, query parameter, request body or tool argument is client input, and copying it into context lets the client choose what a condition sees (threat model). The merged context also appears in the snapshot's subject.context, so it never holds a secret. A context.* reference cannot compile to RLS; permdock rls generate refuses it.

Custom logicCopy Anchor Link

Logic PermDock does not model goes in code you own, behind a fixed contract:

• A closure grant, allow(p, (row, ctx) => …), runs any synchronous check in process; it is non-portable, so snapshots send it to the decision endpoint (policies).
• sqlFunction names a database function with a portable twin, for a rule that must hold in RLS too (conditions).
• A DecisionProvider delegates chosen permissions to a remote PDP, OpenFGA or SpiceDB (PDP).
• The extension interfaces cover subjects, memberships, roles, relations, stores and sinks, each with a conformance runner.

SteeringCopy Anchor Link

allow(p, { obligations }) attaches follow-ups your code owes when that grant applies. Each becomes { kind: 'app', name, detail? } on the granted decision:

allow(permissions.report.export, {
  obligations: ["watermark", { name: "mfa-reprompt", detail: { maxAge: 300 } }],
});

The snapshot carries them, so a client decision owes the same obligations as the server's. Decision events, OCSF and OpenTelemetry carry their names. Obligations lists every kind.

To steer on a denial, read decision.permission: the key that was checked, which findPermission resolves to the leaf and its meta.

UI defaultsCopy Anchor Link

PermDockProvider (and the Vue plugin, Svelte context setter and Solid provider) takes defaults for the pending, fallback and approval slots every <Protected> leaves out, and messages for useDescribe(). <Protected approval> renders an approval-required decision separately from a denial. Provider defaults has the props and the order a slot resolves in.

Adapter responsesCopy Anchor Link

The HTTP adapters take onDenied, called after a refusal with the decision, the Problem Details PermDock built and the request:

import { createPermDock } from "permdock/server";

const { protect } = createPermDock(policy, {
  subject: (request) => sessionUser(request),
  onDenied: ({ problem, decision }) => ({
    ...problem,
    code: decision.outcome === "denied" ? "FORBIDDEN" : "NEEDS_APPROVAL",
  }),
});

• Return Problem Details with extra members to keep the status and headers, a Response to replace the answer, or undefined for the default.
• It runs for an unauthenticated subject, a missing OAuth scope, a loader that threw and every denied or approval-required decision.
• A status below 300, a throw or an invalid return keeps the default response and reports through on('error'). The handler behind the guard never runs.
• A failed guard returns { ok: false, response, decision }, so a framework that builds its own answer can read the decision.

On Next.js the factory's onDenied also runs before requireAccess interrupts, unless the call passes its own (Next.js). On MCP and the AI SDK, onDenied receives { decision, permission, text } and may return replacement text only; isError, structuredContent and the approval shape stay as PermDock built them (MCP, AI SDK).

Wrapping an instanceCopy Anchor Link

wrap on the HTTP, MCP and AI SDK adapters receives each request's instance after otel and returns the one handlers see. Build it with wrapPermDock(permdock, overrides), which replaces the members overrides returns and applies it again to every instance tenant(), team() and derive() return:

import { wrapPermDock } from "permdock";

const { protect } = createPermDock(policy, {
  subject: (request) => sessionUser(request),
  wrap: (permdock) =>
    wrapPermDock(permdock, (inner) => ({
      // `can` is overloaded; the cast restores the overloads.
      can: ((...args: Parameters<typeof inner.can>) => {
        metrics.increment("permdock.can", { permission: args[0].key });
        return inner.can(...args);
      }) as typeof inner.can,
    })),
});

withOtel is built on the same helper. A wrapper changes what your code calls; the decision engine inside is untouched, so a wrapper that returns true from can lies to your code without changing decide, the decision log or RLS.

WhyCopy Anchor Link

• Options, not a plugin system. A plugin registry is module-level mutable state, and PermDock instances are immutable and request-scoped. Every extension point here is an option on a function you already call, scoped to the policy or adapter you pass it to, and visible in its type.
• PermDock never reads x. App data that fed evaluation would need a portable form for snapshots, RLS and ORM filters, which turns it into a condition operator. Keeping x out of evaluation lets it be any JSON your app needs and lets you change it without moving a decision. A value a decision should depend on belongs in a condition, through the principal, context or a relation.
• One schema per kind. The subjectFrom* helpers already take a Standard Schema, so the same shape types app data with no declare module augmentation, and the schema runs at the boundary where the data enters.
• App obligations share one kind. A new kind per need would break every exhaustive switch over Obligation. One namespaced variant keeps the list closed and leaves the names to you.
• Hooks cannot grant. onDenied runs only after a refusal and is checked for a refusal status; context cannot set who the subject is. A hook that throws falls back to the default, so a bug in extension code fails closed.