PermDock
CLI

policy

Write the static grants of a policy as a content-addressed bundle that rls.staticGrants 'ref' pins by hash.

permdock policy bundle compiles the role grants of a policy into one JSON document, the policy-bundle v1 wire format (wire formats), and prints it with its sha-256 hash. The grants are the role_permissions rows permdock generate --only rls would otherwise write into the SQL.

Usage

permdock policy bundle
permdock policy bundle --out supabase/permdock-policy-bundle.json
permdock policy bundle --kind sql --out supabase/seeds/permdock-bundle.sql
permdock policy bundle --out supabase/permdock-policy-bundle.json --check
FlagMeaning
--policy <module>Module exporting the policy; default policy in the config
--kind <kind>bundle (default) prints the bundle JSON; sql prints the statement that loads it into the database
--out <file>File to write; without it the document goes to stdout, and - means stdout
--checkExit 1 when --out differs from what the policy compiles to; write nothing
--dry-runPrint what would be written; write nothing
--jsonPrint format, v, kind, hash, rows and, with --out, out as the cli-result-v2 data

The compile reads rls from permdock.config.ts, so the rows are the ones the generated SQL would carry for that dialect, memberships and custom roles.

Output

The bundle is deterministic. Rows are sorted by scope, role and grant key and deduplicated, and every object is written as RFC 8785 JSON, so the same policy gives the same bytes. The hash is sha-256: followed by the base64url digest of those bytes, the digest form every PermDock signed output uses. Hashing the file with any SHA-256 tool gives the same value.

The sql kind is one idempotent insert keyed by the hash. Running it twice, or loading an older bundle next to a newer one, changes nothing the generated helpers read.

Use it with rls.staticGrants

export default defineConfig({ rls: { staticGrants: "ref" } });
  1. permdock generate --only rls writes the helpers with the bundle hash pinned and no grant rows.
  2. permdock policy bundle --kind sql --out supabase/migrations/<version>_permdock_bundle.sql writes the migration that loads the bundle.
  3. Apply both. The helpers deny every static grant until the bundle with the pinned hash is in <schema>.permdock_policy_bundle.

See static grants by reference for the SQL and the migration order.

Side effects

CommandEffects
permdock policy bundlefiles

Why

A policy that changes one grant rewrites the role_permissions rows, and with rls.seeds: 'view' those rows sit inside a generated schema file. Every change then touches a large file that reviewers cannot read. A bundle moves the rows into a separate file whose name is its hash: the schema file changes only when the hash changes, and a database that holds a bundle with another hash grants nothing instead of the wrong thing.

  • rls: the staticGrants option and the generated helpers
  • Seeds: role defaults and fixtures

Last updated on

On this page