permdock 0.5.0 → 0.7.0

package/skills/permdock-tenancy/references/ownership-and-custom-roles.md

@@ -86,6 +86,8 @@ type CustomRole = {
 - `permdock.assignablePermissions({ tenant })` is the ceiling intersected with what the subject holds. `useAssignablePermissions()` in `permdock/react` builds the editor from it.
 - The save action runs `validateCustomRole(policy, role)` and refuses the role when `ok` is false or `permissions` contains a key outside `assignablePermissions()`. `dropped` names each entry left out (`unknown-permission`, `outside-ceiling`, `condition-not-allowed`, `unknown-level`, `unknown-role`).
 - A platform custom role (`scope: 'global'`, no `tenant`, `team` or `id`) is held through `principal.roles` and capped by the allows of declared global roles marked `assignable`. `CustomRoleSource.globalRoles({ held })` returns them; `customRoleSource(reader, { read: 'held', policy })` skips that read while every held global role is declared.
+- A shared custom role (`shared: true`, no `tenant`, `team` or `id`; `scope` below global, default the first) is defined once by the platform and held by name on a membership of its scope in any tenant. `CustomRoleSource.sharedRoles({ held })` returns them. Its name wins over a tenant custom role's: pass the shared roles to `validateCustomRole(policy, role, { shared })` in the save action, which refuses a clash with `name-taken`. Require a `meta.manageRoles` permission held through a global role before saving one.
 - A stored grant under a key renamed with `definePermissions(..., { renamed })` still resolves; `validateCustomRole` lists it in `renamed` as `{ from, to }`, and `permdock doctor` PD055 prints the `update` that rewrites it.
 - For generated RLS, add `--custom-roles` (or `rls.customRoles: true`) to `permdock rls generate`. Platform roles are rows with `scope = 'global'` and a null `tenant_id`, or the top-level `role_grants` claim in `jwt` mode. With levels, `custom_role_permissions` gains a `level` column and the claim writes `key@level`.
 - To adopt custom roles the app already stores in its own tables, set `rls.customRoles.from` and `rls.customRoleWrites.roles`, then run `permdock rls generate --backfill-out <migrations dir>/`. The migration saves each role through the trusted replace function, drops entries outside the ceiling with a warning, and skips roles that already have rows; never write the copy by hand ([backfill](https://permdock.com/docs/cli/rls#backfill-from-existing-tables)).
+- To keep the copy current instead of copying once, set `rls.customRoles.from.sync: 'trigger'`: after-row triggers on the app's permission and include tables rewrite the copy through the trusted replace function. The generated name guard on `rls.customRoleWrites.roles` refuses a tenant row named like a declared role (`declared-role`) or a shared role (`name-taken`). A stored entry is `<permission>[@<level>]`; check one with `parseCustomRoleEntry(policy, entry, { scope })` in process or `permdock_custom_role_entry_problem(p_scope, p_entry)` in SQL, which answer `unknown-permission`, `outside-ceiling` or `unknown-level`.

package/skills/permdock-wire/references/adapters.md

@@ -397,6 +397,20 @@ export const scim = scimHandler({
 
 The handler writes users and groups. It never decides. Unknown or non-assignable role names are stored and dropped when memberships are read. Pass the app's `revocations` feed so a deprovisioned member's open streams revalidate and close.
 
+In production, keep the directory in Postgres: `permdock scim generate` writes the tenant-keyed tables (`supabase/schemas/permdock/scim.sql` by default; `--dialect`, `--schema`), and `postgresDirectoryStore(query)` reads and writes them through the same `SqlQuery` function `tableMembershipSource` takes:
+
+```ts
+import { postgresDirectoryStore } from "permdock/scim";
+import pg from "pg";
+
+const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
+const directory = postgresDirectoryStore((text, values) =>
+  pool.query(text, [...values]),
+);
+```
+
+Read memberships through `directoryMembershipSource(directory)`, never through a `tableMembershipSource` over the SCIM tables: the source applies the `externalId` / `userName` match, drops inactive users and enforces `assignable`. The tables are revoked from `anon` and `authenticated`; the store's connection must own them or be granted on them, never `service_role` in generated SQL.
+
 ## Cloud — `permdock/cloud`
 
 No factory for a `PermDock`. `cloud({ url, key, environment })` returns `approvals`, `sink` and `policies` to pass into any adapter, `snapshotsFor(token)` (a `SnapshotSource` for the subject an `at+jwt` proves, sent as `PermDock-Subject`), `catalog.push`, plus the environment `issuer` (`<url>/v1/environments/<environment>`) and its `jwks` URL; `cloudEndpoints({ url, environment })` computes the same two without a key. It never implements `MembershipSource` or `CustomRoleSource` and never decides.

package/skills/permdock-wire/references/policy-options.md

@@ -36,6 +36,7 @@ Adopting PermDock in an app with its own keys, SQL helpers and tokens is a step-
 - Put application-owned metadata in `meta.x`; PermDock carries it and never reads it (see App data below).
 - Rename a key later with `definePermissions(tree, { renamed: { "old.key": "new.key" } })`. Remove the alias only when `permdock doctor` PD055 and PD056 are quiet; `permdock diff` reports the removal as the breaking `alias-removed`.
 - Generate helpers beside legacy SQL with `permdock rls generate --helpers-only --shims`, then rewrite policies with `permdock rls migrate`.
+- `permdock rls migrate` and `rls import` need `pgsql-parser` 18 or later; the CLI names the installed version when it is older. A hook that should carry team ids sets `supabase.hook.teams: { table, user, team, tenant? }` and writes the `team_ids` claim within the same size budget as `memberships`.
 
 ## App data and app obligations
 

package/dist/catalog-DjhMYYCq.js

@@ -1 +0,0 @@
-export { t as catalogFile, n as runCatalog } from "./catalog-BECMPrwc.js";

package/dist/collect-FlXJlhus.js

@@ -1 +0,0 @@
-export { r as runCollect } from "./collect-CrZJJnEF.js";

package/dist/index-D8EovfsP.d.ts

@@ -1,91 +0,0 @@
-import { T as Policy, rr as Principal, ut as TokenSigner } from "./policy-types-DzwivBgR.js";
-import { E as SsfPermDockOptions, T as SsfPermDock, _ as SetSubject, c as PushSetOptions, d as SetDelivery, g as SetQueue, h as SetPollHandlerOptions, m as SetEvent, t as CaepCommon, v as SignSetOptions } from "./types-DiQjupG2.js";
-//#region src/ssf/create.d.ts
-declare function createPermDock<TUser, TPrincipal extends Principal = Principal>(policy: Policy<TUser, TPrincipal>, options: SsfPermDockOptions): SsfPermDock;
-//#endregion
-//#region src/ssf/set-queue.d.ts
-/**
- * An in-process `SetQueue`: pending SETs per stream in insertion order. A
- * process restart loses them; a deployment with more than one instance needs
- * a shared queue.
- */
-declare function memorySetQueue(): SetQueue;
-/**
- * The RFC 8936 poll endpoint over a `SetQueue`. It applies the request's
- * `acks` and `setErrs`, then answers `{ sets, moreAvailable }` with up to
- * `maxEvents` pending SETs. It answers at once whatever `returnImmediately`
- * says, which RFC 8936 section 2.4 allows.
- */
-declare function setPollHandler(options: SetPollHandlerOptions): (request: Request) => Promise<Response>;
-//#endregion
-//#region src/ssf/transmitter.d.ts
-/** SSF 1.0 delivery method URN for RFC 8935 push. */
-declare const SSF_PUSH_DELIVERY = "urn:ietf:rfc:8935";
-/** SSF 1.0 delivery method URN for RFC 8936 poll. */
-declare const SSF_POLL_DELIVERY = "urn:ietf:rfc:8936";
-/**
- * Signs one event as an RFC 8417 Security Event Token (`typ: secevent+jwt`):
- * `sub_id` is the event's subject and `events` holds exactly one entry, as
- * SSF 1.0 requires. `iss` is the signer's own.
- */
-declare function signSet(event: SetEvent, signer: TokenSigner, options: SignSetOptions): Promise<string>;
-/**
- * Pushes one SET to a receiver (RFC 8935). A `2xx` is delivery; a `400`
- * maps the receiver's `err` to a cause; `401` and `403` are
- * `authentication-failed` and `access-denied`; a network failure, a timeout,
- * a `429` or a `5xx` is `unavailable` with `retry: true`. Never throws.
- */
-declare function pushSet(set: string, options: PushSetOptions): Promise<SetDelivery>;
-type CaepCredentialChange = CaepCommon & {
-  readonly credentialType: string;
-  readonly changeType: "create" | "revoke" | "update" | "delete";
-  readonly friendlyName?: string;
-  readonly x509Issuer?: string;
-  readonly x509Serial?: string;
-  readonly fido2Aaguid?: string;
-};
-type CaepTokenClaimsChange = CaepCommon & {
-  readonly claims: Readonly<Record<string, unknown>>;
-};
-type CaepAssuranceLevelChange = CaepCommon & {
-  readonly namespace: string;
-  readonly currentLevel: string;
-  readonly previousLevel?: string;
-  readonly changeDirection?: "increase" | "decrease";
-};
-type CaepDeviceComplianceChange = CaepCommon & {
-  readonly previousStatus: "compliant" | "not-compliant";
-  readonly currentStatus: "compliant" | "not-compliant";
-};
-type CaepEvents = {
-  readonly sessionRevoked: (input: CaepCommon) => SetEvent;
-  readonly credentialChange: (input: CaepCredentialChange) => SetEvent;
-  readonly tokenClaimsChange: (input: CaepTokenClaimsChange) => SetEvent;
-  readonly assuranceLevelChange: (input: CaepAssuranceLevelChange) => SetEvent;
-  readonly deviceComplianceChange: (input: CaepDeviceComplianceChange) => SetEvent;
-};
-/** CAEP 1.0 event builders; each returns a `SetEvent` for `signSet`. */
-declare const caepEvents: CaepEvents;
-type RiscAccountDisabled = {
-  readonly subject: SetSubject;
-  readonly reason?: "hijacking" | "bulk-account";
-};
-type RiscCredentialCompromise = CaepCommon & {
-  readonly credentialType: string;
-};
-type RiscEvents = {
-  readonly accountDisabled: (input: RiscAccountDisabled) => SetEvent;
-  readonly accountPurged: (input: {
-    readonly subject: SetSubject;
-  }) => SetEvent;
-  readonly credentialCompromise: (input: RiscCredentialCompromise) => SetEvent;
-};
-/** RISC 1.0 event builders for the events PermDock's receiver treats as revoking every session. */
-declare const riscEvents: RiscEvents;
-/**
- * The SSF 1.0 section 8.1.4 verification event for `stream`, echoing the
- * receiver's `state`. Its subject is the stream, never a principal.
- */
-declare function streamVerificationEvent(stream: string, state?: string): SetEvent;
-//#endregion
-export { setPollHandler as _, CaepTokenClaimsChange as a, RiscEvents as c, caepEvents as d, pushSet as f, memorySetQueue as g, streamVerificationEvent as h, CaepEvents as i, SSF_POLL_DELIVERY as l, signSet as m, CaepCredentialChange as n, RiscAccountDisabled as o, riscEvents as p, CaepDeviceComplianceChange as r, RiscCredentialCompromise as s, CaepAssuranceLevelChange as t, SSF_PUSH_DELIVERY as u, createPermDock as v };

package/dist/load-BxEtwlBS.js

@@ -1 +0,0 @@
-export { a as loadModule, s as pickNamed } from "./load-DFS_ry0W.js";

package/dist/output-files-B3IZJksC.js

@@ -1 +0,0 @@
-export { t as SPLIT_PARTS } from "./output-files-DhRBBE4n.js";

package/dist/parse-Cxq0WxrA.js

@@ -1,53 +0,0 @@
-import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
-import { n as PermDockValidationError } from "./validation-error-ZfUHbKvf.js";
-import { n as copyJson, t as checkSchema } from "./json-schema-B-vAwlde.js";
-import { t as catalogSchema } from "./schema-B4v0Qrac.js";
-//#region src/catalog/parse.ts
-function invalid(issues) {
-	const [first] = issues;
-	const where = first?.path === void 0 || first.path.length === 0 ? "" : ` at ${first.path.map(String).join(".")}`;
-	const more = issues.length > 1 ? ` (and ${String(issues.length - 1)} more)` : "";
-	throw new PermDockValidationError({
-		code: "invalid-data",
-		permission: "",
-		resource: "",
-		boundary: "catalog",
-		issues,
-		message: `PermDock: invalid catalog${where}: ${first?.message ?? "unknown"}${more}`
-	});
-}
-/**
-* Reads a `permissions.catalog.json` document (parsed, or the JSON text) and
-* validates it against `schemas/catalog-v1.json`. Returns a deep-frozen copy
-* built from own keys; throws `PermDockValidationError` with every issue.
-*/
-function parseCatalog(json) {
-	const issues = [];
-	let input = json;
-	if (typeof json === "string") try {
-		input = JSON.parse(json);
-	} catch (error) {
-		invalid([{
-			message: `Expected JSON text: ${error instanceof Error ? error.message : String(error)}`,
-			path: []
-		}]);
-	}
-	let copy;
-	try {
-		copy = copyJson(input, [], issues, /* @__PURE__ */ new Set());
-	} catch (error) {
-		invalid([{
-			message: `Could not read the input: ${error instanceof Error ? error.message : String(error)}`,
-			path: []
-		}]);
-	}
-	if (issues.length === 0) checkSchema(catalogSchema, copy, [], issues);
-	if (issues.length > 0) invalid(issues);
-	return freezeDeep(copy);
-}
-/** Keys of the permissions the catalog marks `rowConditions: true`: the SQL helpers alone cannot enforce them. */
-function rowConditionKeys(catalog) {
-	return new Set(catalog.permissions.filter((permission) => permission.rowConditions === true).map((permission) => permission.key));
-}
-//#endregion
-export { rowConditionKeys as n, parseCatalog as t };

package/dist/peer-C8swJ2GH.js

@@ -1,50 +0,0 @@
-import { n as CliError } from "./errors-CWTY6uih.js";
-import { detect, getUserAgent, resolveCommand } from "package-manager-detector";
-//#region src/cli/core/peer.ts
-/**
-* Loads an optional peer dependency for one command, or fails with the line
-* that installs it with the project's package manager. Only the commands that
-* need a peer ever load it.
-*/
-async function requirePeer(load, name, command, cwd = process.cwd()) {
-	try {
-		return await load();
-	} catch (error) {
-		if (!isMissingModule(error)) throw error;
-		const agent = await packageManagerOf(cwd);
-		throw new CliError("unavailable", peerHint(name, command, agent), {
-			cause: error,
-			code: "dependency_missing",
-			extensions: { package: name },
-			next: [{
-				command: addLine(agent, [name], { dev: true }),
-				when: "to install it"
-			}]
-		});
-	}
-}
-/** The package manager whose lockfile the project has, else the one running the CLI. */
-async function packageManagerOf(cwd) {
-	return (await detect({ cwd }))?.agent ?? getUserAgent() ?? void 0;
-}
-/** The command that adds `packages` with `agent`, npm when there is none. */
-function addLine(agent, packages, options) {
-	const args = options?.dev === true ? ["-D", ...packages] : [...packages];
-	const command = resolveCommand(agent ?? "npm", "add", args);
-	return command === null ? `npm install ${args.join(" ")}` : [command.command, ...command.args].join(" ");
-}
-function isMissingModule(error) {
-	if (typeof error !== "object" || error === null || !("code" in error)) return false;
-	return error.code === "ERR_MODULE_NOT_FOUND" || error.code === "MODULE_NOT_FOUND";
-}
-/**
-* The error for a missing peer. `agent` is the package manager that ran the
-* command, or the one whose lockfile the project has; without one the line
-* names pnpm and npm.
-*/
-function peerHint(name, command, agent = getUserAgent() ?? void 0) {
-	const install = agent === void 0 ? void 0 : resolveCommand(agent, "add", ["-D", name]);
-	return `PermDock CLI: ${command} needs the optional peer ${name}. Install it with: ${install === null || install === void 0 ? `pnpm add -D ${name} (or npm install -D ${name})` : [install.command, ...install.args].join(" ")}`;
-}
-//#endregion
-export { requirePeer as i, packageManagerOf as n, peerHint as r, addLine as t };

package/dist/powersync-CbzkqL_M.js

@@ -1 +0,0 @@
-export { n as runPowerSync } from "./powersync-bYUDLOAO.js";