permdock 0.4.0 → 0.5.0

package/dist/express/index.js

@@ -1,8 +1,8 @@
 import { r as hasCredentials } from "../http-BBoKefeS.js";
-import { i as discoverViaSignatureAgent, r as InvalidSignatureError, s as verifyWebBotAuth } from "../evaluations-C9YJsv3H.js";
-import { t as problemFromError } from "../map-error-BE27PYkE.js";
-import { i as decorate, r as bindKernel } from "../bind-kk-uyCwH.js";
-import { i as toRequest, r as sendResponse } from "../http-BEbdMZ05.js";
+import { d as discoverViaSignatureAgent, m as webBotAuthVerifier, u as InvalidSignatureError } from "../evaluations-DZ2CbV5k.js";
+import { t as problemFromError } from "../map-error-TCAdw-eW.js";
+import { i as decorate, r as bindKernel } from "../bind-CZzhx-Vj.js";
+import { n as sendResponse, r as toRequest } from "../http-ujKm0JXE.js";
 import express from "express";
 //#region src/express/create.ts
 function run(work, next) {
@@ -33,16 +33,16 @@ const withPermDock = (fn) => (req, res, next) => {
 	}, next);
 };
 function createPermDock(policy, options) {
-	const { kernel, bind, rebind, scopeOf, handlerScope, guard: runGuard } = bindKernel(policy, options, "express", toRequest);
-	const permdock = () => (req, res, next) => {
+	const { kernel, bind, rebind, scopeOf, handlerScope, getPermDock, guard: runGuard } = bindKernel(policy, options, "express", toRequest);
+	const middleware = () => (req, res, next) => {
 		respond(req, res, next, async () => {
-			decorate(req, await kernel.permdock(bind(req), await scopeOf(req)));
+			decorate(req, await kernel.getPermDock(bind(req), await scopeOf(req)));
 			next();
 		});
 	};
-	const protect = (permission, loadData, protectOptions) => (req, res, next) => {
+	const protect = (permission, data, protectOptions) => (req, res, next) => {
 		respond(req, res, next, async () => {
-			const guard = await runGuard(permission, loadData, req, protectOptions);
+			const guard = await runGuard(permission, data, req, protectOptions);
 			if (!guard.ok) {
 				await sendResponse(res, guard.response);
 				return;
@@ -67,7 +67,8 @@ function createPermDock(policy, options) {
 		return router;
 	};
 	return {
-		permdock,
+		getPermDock,
+		middleware,
 		protect,
 		errorHandler,
 		permdockHandler,
@@ -76,4 +77,4 @@ function createPermDock(policy, options) {
 	};
 }
 //#endregion
-export { InvalidSignatureError, createPermDock, discoverViaSignatureAgent, sendResponse, toRequest, verifyWebBotAuth };
+export { InvalidSignatureError, createPermDock, discoverViaSignatureAgent, sendResponse, toRequest, webBotAuthVerifier };

package/dist/fastify/index.d.ts

@@ -1,11 +1,22 @@
-import { E as Policy, Or as Principal, j as PolicyVocabulary, jt as PermDock } from "../policy-types-sp9P1iIV.js";
-import { d as Permission } from "../permission-types-Dg39z9Kv.js";
-import { C as verifyWebBotAuth, b as discoverViaSignatureAgent, i as OpenApiHooks, m as InvalidSignatureError, o as ProtectOptions } from "../server-types-DdqBwZN_.js";
-import { t as ServerAdapterOptions } from "../bind-BzqG8SMb.js";
+import { T as Policy, j as PolicyVocabulary, rr as Principal } from "../policy-types-DzwivBgR.js";
+import { w as Permission } from "../vocabulary-D6lPdb4Z.js";
+import { r as PermDock } from "../permdock-D7eeLJER.js";
+import { f as InvalidSignatureError, i as OpenApiHooks, o as ProtectOptions, v as discoverViaSignatureAgent, x as webBotAuthVerifier } from "../server-types-BLd4MnBX.js";
+import { t as ServerAdapterOptions } from "../bind--9EFVYWF.js";
 import { FastifyPluginAsync, FastifyReply, FastifyRequest, FastifySchema, FastifyTypeProvider, FastifyTypeProviderDefault, RawRequestDefaultExpression, RawServerDefault, RouteGenericInterface } from "fastify";
+//#region src/server/http.d.ts
+/** A Fastify-style reply: `code`, `header` and `send`. */
+type ReplyLike = {
+  code(status: number): unknown;
+  header(key: string, value: string): unknown;
+  send(body: string): unknown;
+};
+/** Writes `response` to a Fastify-style reply. */
+declare function writeReply(reply: ReplyLike, response: Response): Promise<void>;
+//#endregion
 //#region src/fastify/create.d.ts
 type FastifyPermDockOptions<TUser = unknown> = ServerAdapterOptions<FastifyRequest, TUser>;
-type PermDockRequest<Route extends RouteGenericInterface = RouteGenericInterface, V extends PolicyVocabulary = PolicyVocabulary> = FastifyRequest<Route> & {
+type FastifyPermDockRequest<Route extends RouteGenericInterface = RouteGenericInterface, V extends PolicyVocabulary = PolicyVocabulary> = FastifyRequest<Route> & {
   permdock: PermDock<V>;
   permdockData?: unknown;
 };
@@ -13,31 +24,23 @@ type PermDockRequest<Route extends RouteGenericInterface = RouteGenericInterface
 type ProtectRequest<Route extends RouteGenericInterface = RouteGenericInterface, Schema extends FastifySchema = FastifySchema, Provider extends FastifyTypeProvider = FastifyTypeProviderDefault> = FastifyRequest<Route, RawServerDefault, RawRequestDefaultExpression, Schema, Provider>;
 /**
  * Generic over the route, schema and type provider so a `preHandler` slot
- * infers them: `loadData` sees the same typed `request.body` as the handler.
+ * infers them: `data` sees the same typed `request.body` as the handler.
  */
-type FastifyProtect = <Route extends RouteGenericInterface = RouteGenericInterface, Schema extends FastifySchema = FastifySchema, Provider extends FastifyTypeProvider = FastifyTypeProviderDefault>(permission: Permission | null, loadData?: (request: ProtectRequest<Route, Schema, Provider>) => unknown, protectOptions?: ProtectOptions) => (request: ProtectRequest<Route, Schema, Provider>, reply: FastifyReply) => Promise<void>;
+type FastifyProtect = <Route extends RouteGenericInterface = RouteGenericInterface, Schema extends FastifySchema = FastifySchema, Provider extends FastifyTypeProvider = FastifyTypeProviderDefault>(permission: Permission | null, data?: (request: ProtectRequest<Route, Schema, Provider>) => unknown, protectOptions?: ProtectOptions) => (request: ProtectRequest<Route, Schema, Provider>, reply: FastifyReply) => Promise<void>;
 type FastifyPermDock<V extends PolicyVocabulary = PolicyVocabulary> = {
-  readonly permdock: FastifyPluginAsync;
+  /** The `PermDock` for one request, for code the middleware does not run before. */
+  readonly getPermDock: (request: FastifyRequest) => Promise<PermDock<V>>;
+  readonly middleware: () => FastifyPluginAsync;
   readonly protect: FastifyProtect;
-  readonly permdockHandler: FastifyPluginAsync;
-  /** Types `request.permdock` for a route registered after `permdock` or `protect`. */
-  readonly withPermDock: <Route extends RouteGenericInterface = RouteGenericInterface>(fn: (request: PermDockRequest<Route, V>, reply: FastifyReply) => unknown) => (request: FastifyRequest<Route>, reply: FastifyReply) => unknown;
+  readonly permdockHandler: () => FastifyPluginAsync;
+  /** Types `request.permdock` for a route registered after `middleware()` or `protect`. */
+  readonly withPermDock: <Route extends RouteGenericInterface = RouteGenericInterface>(fn: (request: FastifyPermDockRequest<Route, V>, reply: FastifyReply) => unknown) => (request: FastifyRequest<Route>, reply: FastifyReply) => unknown;
   readonly openapi: OpenApiHooks;
 };
 export declare function createPermDock<TUser, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, options: FastifyPermDockOptions<TUser>): FastifyPermDock<V>;
 //#endregion
-//#region src/server/http.d.ts
-/** A Fastify-style reply: `code`, `header` and `send`. */
-type ReplyLike = {
-  code(status: number): unknown;
-  header(key: string, value: string): unknown;
-  send(body: string): unknown;
-};
-/** Writes `response` to a Fastify-style reply. */
-declare function writeReply(reply: ReplyLike, response: Response): Promise<void>;
-//#endregion
 //#region src/fastify/http.d.ts
 export declare function toRequest(request: FastifyRequest): Request;
 export declare const sendReply: typeof writeReply;
 //#endregion
-export { type FastifyPermDock, type FastifyPermDockOptions, type FastifyProtect, InvalidSignatureError, type PermDockRequest, discoverViaSignatureAgent, verifyWebBotAuth };
+export { type FastifyPermDock, type FastifyPermDockOptions, type FastifyPermDockRequest, type FastifyProtect, InvalidSignatureError, discoverViaSignatureAgent, webBotAuthVerifier };

package/dist/fastify/index.js

@@ -1,7 +1,7 @@
 import { c as writeReply, i as headersFrom, n as firstHeader, r as hasCredentials, t as fetchRequest } from "../http-BBoKefeS.js";
-import { i as discoverViaSignatureAgent, r as InvalidSignatureError, s as verifyWebBotAuth } from "../evaluations-C9YJsv3H.js";
-import { t as problemFromError } from "../map-error-BE27PYkE.js";
-import { i as decorate, r as bindKernel } from "../bind-kk-uyCwH.js";
+import { d as discoverViaSignatureAgent, m as webBotAuthVerifier, u as InvalidSignatureError } from "../evaluations-DZ2CbV5k.js";
+import { t as problemFromError } from "../map-error-TCAdw-eW.js";
+import { i as decorate, r as bindKernel } from "../bind-CZzhx-Vj.js";
 //#region src/fastify/http.ts
 function toRequest(request) {
 	const host = firstHeader(request.headers.host) ?? "localhost";
@@ -21,13 +21,13 @@ function skipped(request) {
 	return typeof config === "object" && config !== null && Reflect.get(config, "permdock") === false;
 }
 function createPermDock(policy, options) {
-	const { kernel, bind, rebind, scopeOf, handlerScope, guard: runGuard } = bindKernel(policy, options, "fastify", toRequest);
-	const permdock = breakEncapsulation((app) => {
+	const { kernel, bind, rebind, scopeOf, handlerScope, getPermDock, guard: runGuard } = bindKernel(policy, options, "fastify", toRequest);
+	const plugin = breakEncapsulation((app) => {
 		app.decorateRequest("permdock", null);
 		app.decorateRequest("permdockData", null);
 		app.addHook("onRequest", async (request) => {
 			if (skipped(request)) return;
-			decorate(request, await kernel.permdock(bind(request), await scopeOf(request)));
+			decorate(request, await kernel.getPermDock(bind(request), await scopeOf(request)));
 		});
 		const previous = app.errorHandler;
 		app.setErrorHandler(async function permdockErrors(err, request, reply) {
@@ -40,16 +40,16 @@ function createPermDock(policy, options) {
 		});
 		return Promise.resolve();
 	});
-	const protect = (permission, loadData, protectOptions) => async (request, reply) => {
+	const protect = (permission, data, protectOptions) => async (request, reply) => {
 		const plain = request;
-		const guard = await runGuard(permission, loadData === void 0 ? void 0 : () => loadData(request), plain, protectOptions);
+		const guard = await runGuard(permission, data === void 0 ? void 0 : () => data(request), plain, protectOptions);
 		if (!guard.ok) {
 			await sendReply(reply, guard.response);
 			return;
 		}
 		decorate(plain, guard.permdock, guard.data);
 	};
-	const permdockHandler = (app) => {
+	const handler = (app) => {
 		const { POST, GET } = kernel.permdockHandler(handlerScope);
 		app.post("/", async (request, reply) => {
 			await sendReply(reply, await POST(rebind(request)));
@@ -61,12 +61,13 @@ function createPermDock(policy, options) {
 	};
 	const withPermDock = (fn) => (request, reply) => fn(request, reply);
 	return {
-		permdock,
+		getPermDock,
+		middleware: () => plugin,
 		protect,
-		permdockHandler,
+		permdockHandler: () => handler,
 		withPermDock,
 		openapi: kernel.openapi
 	};
 }
 //#endregion
-export { InvalidSignatureError, createPermDock, discoverViaSignatureAgent, sendReply, toRequest, verifyWebBotAuth };
+export { InvalidSignatureError, createPermDock, discoverViaSignatureAgent, sendReply, toRequest, webBotAuthVerifier };

package/dist/fetch-adapter-g0ypLkID.js

@@ -0,0 +1,120 @@
+import { t as compact } from "./compact-CAf557ZB.js";
+import { o as isPermission } from "./permission-registry-Br4jSNVi.js";
+import { r as hasCredentials } from "./http-BBoKefeS.js";
+import { a as methodNotAllowed } from "./problem-CTviyH5L.js";
+import { t as problemFromError } from "./map-error-TCAdw-eW.js";
+import { i as decorate, r as bindKernel } from "./bind-CZzhx-Vj.js";
+//#region src/server/fetch-adapter.ts
+/**
+* `protect(target, data, options)(handler)` for a framework whose routes are
+* plain handlers: a refusal is the response, a grant sets `permdock` and
+* `permdockData` on the event's locals before `handler` runs.
+*/
+function guardedRoute(adapter, route, target, data, protectOptions) {
+	return (handler) => async (event) => {
+		const context = route.context(event);
+		const guard = await adapter.guard(target, data === void 0 ? void 0 : () => data(event), context, protectOptions);
+		if (!guard.ok) return guard.response;
+		decorate(route.locals(event), guard.permdock, guard.data);
+		return adapter.mapErrors(context, () => handler(event));
+	};
+}
+/** `withPermDock(handler)`: the instance on the event's locals, built when no middleware set it. */
+function instanceRoute(adapter, route) {
+	return (handler) => async (event) => {
+		const context = route.context(event);
+		const attached = await adapter.ensure(route.locals(event), context);
+		if (!attached.ok) return attached.response;
+		return adapter.mapErrors(context, () => handler(event));
+	};
+}
+const ALLOW = "GET, HEAD, POST";
+/**
+* The permission and row loader behind a `protect` target. For an operation,
+* `input` reads its input from the request and the operation's `data` loads
+* the row; an operation without `data` checks the permission with no row.
+*/
+function protectTarget(target, input) {
+	if (target === null || isPermission(target)) return {
+		permission: target,
+		data: input
+	};
+	const load = target.data;
+	return {
+		permission: target.permission,
+		data: load === void 0 ? void 0 : async (context) => load(input === void 0 ? void 0 : await input(context))
+	};
+}
+function held(target) {
+	const value = Reflect.get(target, "permdock");
+	return value === void 0 || value === null ? void 0 : value;
+}
+/**
+* The kernel of an adapter whose framework hands its handlers a Fetch
+* `Request` inside its own context object (SvelteKit, Astro, h3, SolidStart,
+* TanStack Start).
+*/
+function fetchAdapter(policy, options, adapter, requestOf) {
+	const { kernel, bind, scopeOf, handlerScope, attach, guard } = bindKernel(policy, options, adapter, requestOf);
+	const getPermDock = async (context) => kernel.getPermDock(bind(context), await scopeOf(context));
+	const getSnapshot = async (context, query = {}) => {
+		return (await kernel.getPermDock(bind(context), query.tenant === void 0 ? await scopeOf(context) : { tenant: query.tenant })).snapshot(compact({
+			include: query.include,
+			tenants: query.tenants
+		}));
+	};
+	const ensure = async (target, context) => {
+		const existing = held(target);
+		if (existing !== void 0) return {
+			ok: true,
+			permdock: existing
+		};
+		const result = await attach(context);
+		if (result.ok) decorate(target, result.permdock);
+		return result;
+	};
+	const mapErrors = async (context, work) => {
+		try {
+			return await work();
+		} catch (error) {
+			const problem = problemFromError(error, { credentials: hasCredentials(requestOf(context)) });
+			if (problem === void 0) throw error;
+			return problem;
+		}
+	};
+	const handlers = () => {
+		const { GET, POST } = kernel.permdockHandler(handlerScope);
+		return {
+			GET: (context) => GET(bind(context)),
+			POST: (context) => POST(bind(context))
+		};
+	};
+	const handler = () => {
+		const { GET, POST } = handlers();
+		return (context) => {
+			switch (requestOf(context).method) {
+				case "GET":
+				case "HEAD": return GET(context);
+				case "POST": return POST(context);
+				default: return Promise.resolve(methodNotAllowed(ALLOW));
+			}
+		};
+	};
+	return {
+		kernel,
+		getPermDock,
+		getSnapshot,
+		attach,
+		guard: (target, data, context, protectOptions) => {
+			const resolved = protectTarget(target, data);
+			return guard(resolved.permission, resolved.data, context, protectOptions);
+		},
+		ensure,
+		connection: async (context, connectionOptions) => kernel.connection(bind(context), connectionOptions, await scopeOf(context)),
+		mapErrors,
+		handlers,
+		handler
+	};
+}
+//#endregion
+export { guardedRoute as n, instanceRoute as r, fetchAdapter as t };

package/dist/fetch-adapter-qKJBuRqy.d.ts

@@ -0,0 +1,31 @@
+import { w as Permission } from "./vocabulary-D6lPdb4Z.js";
+import { a as OperationInput, t as Operation } from "./operations-CxybZErY.js";
+import { n as RevocationFeed } from "./revocations-R07lFBnX.js";
+import { o as ProtectOptions } from "./server-types-BLd4MnBX.js";
+import { t as ServerAdapterOptions } from "./bind--9EFVYWF.js";
+//#region src/server/fetch-adapter.d.ts
+/** What `protect` checks: a permission, an operation from `defineOperations`, or `null` for a route that needs only OAuth scopes. */
+type ProtectTarget = Permission | Operation | null;
+/** Reads a value from the framework context; may be async. */
+type ContextReader<TContext, T> = (context: TContext) => T | Promise<T>;
+/**
+ * `protect`'s overloads: a permission takes the row loader, an operation the
+ * reader of its input, which the operation's `data` turns into the row.
+ */
+type FetchProtect<TContext, TResult> = {
+  <T = unknown>(permission: Permission | null, data?: ContextReader<TContext, T | null | undefined>, protectOptions?: ProtectOptions): TResult;
+  <TOperation extends Operation>(operation: TOperation, input?: ContextReader<TContext, OperationInput<TOperation>>, protectOptions?: ProtectOptions): TResult;
+};
+type FetchAdapterOptions<TContext, TUser = unknown> = ServerAdapterOptions<TContext, TUser> & {
+  /** Ends or revalidates open streams and sockets; never a decision input. */
+  readonly revocations?: RevocationFeed;
+};
+/** The decision endpoint, one handler per method. */
+type PermDockHandlers<TContext> = {
+  /** The snapshot for `permdock/react` and the other client entries. */
+  readonly GET: (context: TContext) => Promise<Response>;
+  /** AuthZEN-shaped evaluations. */
+  readonly POST: (context: TContext) => Promise<Response>;
+};
+//#endregion
+export { ProtectTarget as a, PermDockHandlers as i, FetchAdapterOptions as n, FetchProtect as r, ContextReader as t };

package/dist/fields-D9tPVUUS.js

@@ -0,0 +1,203 @@
+import { i as configError } from "./errors-CWTY6uih.js";
+import { s as jsonSchemaOf } from "./catalog-doc-C9wjsfNY.js";
+import { F as quoteQualified, N as quoteIdent, P as quoteLiteral, j as helperSchema, s as signedIn } from "./shared-CD11nBbC.js";
+import { c as branchClauses, i as orSql, s as andSql, u as wrapSql } from "./policies-CO1oOymN.js";
+//#region src/cli/rls/fields.ts
+/** Names of the field-view objects. Part of the SQL contract. */
+const FIELD_VIEWS = {
+	/** `<table>_visible`: the `security_invoker` view clients read. */
+	view: "_visible",
+	/** `<table>_visible_fields`: the owner-rights companion `--revoke-columns` adds. */
+	companion: "_visible_fields",
+	/** The companion's row-key column, joined to the base table's key. */
+	key: "permdock_key",
+	/** Marks the companion so doctor PD022 knows it reads as its owner on purpose. */
+	comment: "permdock:field-companion"
+};
+function covers(branch, column) {
+	return branch.fields === void 0 || branch.fields.includes(column);
+}
+/**
+* A read grant that only shapes columns: a field-limited deny (it never
+* denies the row) or an allow with an empty list (it grants nothing). With
+* field views it leaves the row policy and lives in the view's masks.
+*/
+function fieldOnly(branch) {
+	if (branch.command !== "select" || branch.fields === void 0) return false;
+	return branch.effect === "deny" || branch.fields.length === 0;
+}
+/** Branches the row policies keep when field views compile. */
+function rowBranches(branches) {
+	return branches.filter((branch) => !fieldOnly(branch));
+}
+/**
+* Whether the reader is signed in, for branches with no helper call: a grant
+* to any signed-in user relies on `to authenticated` in its policy, which a
+* view does not have.
+*/
+function audience(ctx, branch) {
+	if (branch.access !== void 0 || branch.roles.length !== 1) return;
+	if (branch.roles[0] === "authenticated") return signedIn(ctx);
+	return branch.roles[0] === "anon" ? `not (${signedIn(ctx)})` : void 0;
+}
+function clause(ctx, branch) {
+	return andSql(audience(ctx, branch), branchClauses(branch).using) ?? "true";
+}
+/**
+* `can(permission, row, { field })` in SQL: an allow that covers the column
+* holds for the row and no covering deny does. Every access term is the
+* uncorrelated helper call the row policy uses, so it runs once per statement.
+*/
+function maskSql(ctx, allows, denies, column) {
+	const allowed = allows.filter((branch) => covers(branch, column)).map((branch) => clause(ctx, branch));
+	if (allowed.length === 0) return "false";
+	const denied = denies.filter((branch) => covers(branch, column)).map((branch) => clause(ctx, branch));
+	const allow = orSql(allowed);
+	if (denied.length === 0) return allow;
+	const deny = orSql(denied);
+	return allow === "true" ? `not ${wrapSql(deny)}` : `${wrapSql(allow)} and not ${wrapSql(deny)}`;
+}
+function schemaColumns(policy, resource) {
+	const node = policy.resources.get(resource);
+	const schema = node === void 0 ? null : jsonSchemaOf(node);
+	const properties = schema !== null && typeof schema === "object" ? schema.properties : void 0;
+	return properties !== null && typeof properties === "object" ? Object.keys(properties) : void 0;
+}
+function viewName(table, suffix) {
+	return `${table}${suffix}`;
+}
+/**
+* `<helper schema>.<table>_visible_fields`: outside the Data API's schemas,
+* so its owner rights reach clients only through the `_visible` join.
+*/
+function companionName(ctx, table) {
+	const base = table.startsWith("public.") ? table.slice(7) : table.replaceAll(".", "_");
+	return `${helperSchema(ctx)}.${viewName(base, FIELD_VIEWS.companion)}`;
+}
+/**
+* One view per table whose read grants limit fields. A column is restricted
+* when some read allow lists fields without it or some read deny lists it;
+* every other column, and the row key, passes through unchanged.
+*/
+function fieldViews(policy, ctx, branches, options, warnings) {
+	const byTable = /* @__PURE__ */ new Map();
+	for (const branch of branches) {
+		if (branch.command !== "select" || branch.coverage === true) continue;
+		byTable.set(branch.table, [...byTable.get(branch.table) ?? [], branch]);
+	}
+	const views = [];
+	for (const [table, reads] of byTable) {
+		const allows = reads.filter((branch) => branch.effect === "allow" && branch.fields?.length !== 0);
+		const denies = reads.filter((branch) => branch.effect === "deny");
+		const limited = reads.some((branch) => branch.fields !== void 0);
+		const resource = reads.find((branch) => branch.resource !== void 0)?.resource;
+		if (!limited || allows.length === 0 || resource === void 0) continue;
+		const names = schemaColumns(policy, resource);
+		if (names === void 0) throw configError(`PermDock CLI: --fields views needs the ${resource} schema's JSON Schema (Standard JSON Schema) to list the columns of ${table}`);
+		const key = policy.resources.get(resource)?.id ?? "id";
+		const restricted = (column) => column !== key && (allows.some((branch) => branch.fields !== void 0 && !branch.fields.includes(column)) || denies.some((branch) => branch.fields?.includes(column) === true));
+		const columns = names.map((name) => {
+			quoteIdent(name);
+			return restricted(name) ? {
+				name,
+				mask: maskSql(ctx, allows, denies, name)
+			} : { name };
+		});
+		if (columns.every((column) => column.mask === void 0)) continue;
+		const view = viewName(table, FIELD_VIEWS.view);
+		if (allows.some((branch) => branch.fields !== void 0 && !branch.fields.includes(key))) warnings.push(`field view ${view}: the key ${key} passes through, although a read grant on ${resource} omits it`);
+		const hidden = columns.filter((column) => column.mask !== void 0).map((column) => column.name);
+		if (options.helpersOnly === true) warnings.push(`field view ${view}: ${table} still returns ${hidden.join(", ")} to direct reads; revoke select on those columns from client roles in your own grants, or read them through a function`);
+		else if (!options.revokeColumns) warnings.push(`field view ${view}: ${table} still returns ${hidden.join(", ")} to direct reads; add --revoke-columns so clients read through the view`);
+		views.push({
+			resource,
+			table,
+			view,
+			key,
+			columns,
+			roles: reads.some((branch) => branch.roles.includes("anon")) ? ["anon", "authenticated"] : ["authenticated"],
+			...options.revokeColumns ? { companion: companionName(ctx, table) } : {}
+		});
+	}
+	return views;
+}
+/** Columns of `view`'s table that `anon` and `authenticated` keep on the base table with `--revoke-columns`. */
+function readableColumns(view) {
+	return view.columns.filter((column) => column.mask === void 0).map((column) => column.name);
+}
+function restrictedColumns(view) {
+	return view.columns.filter((column) => column.mask !== void 0).map((column) => column.name);
+}
+function columnList(names) {
+	return names.map(quoteIdent).join(", ");
+}
+function selectList(lines) {
+	return lines.map((line) => `  ${line}`).join(",\n");
+}
+function grantView(name, roles) {
+	return [`revoke all on table ${quoteQualified(name)} from anon, authenticated, public;`, `grant select on table ${quoteQualified(name)} to ${roles.join(", ")};`].join("\n");
+}
+function inlineViewSql(view) {
+	const targets = view.columns.map((column) => column.mask === void 0 ? quoteIdent(column.name) : `case when ${column.mask} then ${quoteIdent(column.name)} end as ${quoteIdent(column.name)}`);
+	return `create or replace view ${quoteQualified(view.view)} with (security_invoker = true) as
+select
+${selectList(targets)}
+from ${quoteQualified(view.table)};`;
+}
+function companionSql(view, companion) {
+	const restricted = view.columns.filter((column) => column.mask !== void 0);
+	const targets = [`${quoteIdent(view.key)} as ${quoteIdent(FIELD_VIEWS.key)}`, ...restricted.map((column) => `case when ${column.mask} then ${quoteIdent(column.name)} end as ${quoteIdent(column.name)}`)];
+	const any = orSql(restricted.map((column) => column.mask ?? "false"));
+	const name = companion.slice(0, companion.indexOf("."));
+	const schema = quoteIdent(name);
+	return `${name === "public" ? "" : `create schema if not exists ${schema};
+revoke all on schema ${schema} from public;
+grant usage on schema ${schema} to ${view.roles.join(", ")};
+`}create or replace view ${quoteQualified(companion)} with (security_barrier = true) as
+select
+${selectList(targets)}
+from ${quoteQualified(view.table)}
+where ${any};
+comment on view ${quoteQualified(companion)} is ${quoteLiteral(`${FIELD_VIEWS.comment} ${view.view}`)};`;
+}
+function joinedViewSql(view, companion) {
+	const targets = view.columns.map((column) => column.mask === void 0 ? `t.${quoteIdent(column.name)}` : `f.${quoteIdent(column.name)}`);
+	return `create or replace view ${quoteQualified(view.view)} with (security_invoker = true) as
+select
+${selectList(targets)}
+from ${quoteQualified(view.table)} t
+left join ${quoteQualified(companion)} f on f.${quoteIdent(FIELD_VIEWS.key)} = t.${quoteIdent(view.key)};`;
+}
+/** `select` on only the unrestricted columns (and the key) of the base table, for `--revoke-columns`. */
+function columnGrantSql(view, role) {
+	return `grant select (${columnList(readableColumns(view))}) on table ${quoteQualified(view.table)} to ${role};`;
+}
+function columnRevokeSql(view) {
+	return `revoke select (${columnList(restrictedColumns(view))}) on table ${quoteQualified(view.table)} from anon, authenticated;`;
+}
+/**
+* The view SQL: the `security_invoker` view, and with `--revoke-columns` the
+* owner-rights companion it joins for the restricted columns. The companion
+* masks every column with the full field decision and keeps only rows where
+* one is readable, so reading it directly shows nothing `pick` would not.
+*/
+function fieldViewsSql(views) {
+	return views.map((view) => {
+		const head = `-- field view over ${view.table}: ${restrictedColumns(view).join(", ")} read as null unless a read grant covers the column for the row`;
+		if (view.companion === void 0) return [
+			head,
+			inlineViewSql(view),
+			grantView(view.view, view.roles)
+		].join("\n");
+		return [
+			head,
+			`-- ${view.companion} reads ${view.table} as its owner; ${view.view} reads the rows as the caller and joins it`,
+			companionSql(view, view.companion),
+			grantView(view.companion, view.roles),
+			joinedViewSql(view, view.companion),
+			grantView(view.view, view.roles)
+		].join("\n");
+	}).join("\n\n");
+}
+//#endregion
+export { fieldViewsSql as a, fieldViews as i, columnGrantSql as n, rowBranches as o, columnRevokeSql as r, viewName as s, FIELD_VIEWS as t };

package/dist/files-C5ZI27eV.js

@@ -0,0 +1,124 @@
+import { n as CliError } from "./errors-CWTY6uih.js";
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import { execFileSync } from "node:child_process";
+//#region src/cli/core/files.ts
+function outcomeOf(abs, text) {
+	if (!existsSync(abs)) return "created";
+	return readFileSync(abs, "utf8") === text ? "unchanged" : "updated";
+}
+/** What writing `files` would do, without writing. */
+function planFiles(cwd, files) {
+	return files.map((file) => ({
+		path: file.path,
+		outcome: outcomeOf(resolve(cwd, file.path), file.text)
+	}));
+}
+/**
+* Writes every created or updated file, all or nothing: each one is staged
+* beside its target first, and a failed stage removes the others before
+* anything is replaced. `dryRun` only plans.
+*/
+function applyFiles(cwd, files, options = {}) {
+	const planned = planFiles(cwd, files);
+	if (options.dryRun === true) return planned;
+	const staged = [];
+	try {
+		for (const [index, file] of files.entries()) {
+			if (planned[index]?.outcome === "unchanged") continue;
+			const target = resolve(cwd, file.path);
+			const temp = `${target}.permdock-${String(process.pid)}.tmp`;
+			mkdirSync(dirname(target), { recursive: true });
+			writeFileSync(temp, file.text);
+			staged.push({
+				temp,
+				target
+			});
+		}
+	} catch (error) {
+		for (const { temp } of staged) rmSync(temp, { force: true });
+		throw new CliError("failed", `could not write ${describe(error)}; wrote nothing`, {
+			code: "write_failed",
+			cause: error
+		});
+	}
+	for (const { temp, target } of staged) renameSync(temp, target);
+	return planned;
+}
+function describe(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+const VERBS = {
+	created: ["Created", "Would create"],
+	updated: ["Updated", "Would update"],
+	unchanged: ["Unchanged", "Unchanged"]
+};
+/** One line per file: `Created x`, or `Would create x` under `--dry-run`. */
+function fileSummary(applied, dryRun) {
+	return applied.map((file) => `${VERBS[file.outcome][dryRun ? 1 : 0]} ${file.path}`).join("\n");
+}
+/**
+* The files among `paths` with uncommitted changes in git. Outside a git
+* work tree, or without git, nothing counts as dirty.
+*/
+function dirtyFiles(cwd, paths) {
+	if (paths.length === 0) return [];
+	let status;
+	try {
+		status = execFileSync("git", [
+			"status",
+			"--porcelain",
+			"-z",
+			"--",
+			...paths.map((path) => resolve(cwd, path))
+		], {
+			cwd,
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		});
+	} catch {
+		return [];
+	}
+	let root;
+	try {
+		root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+			cwd,
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim();
+	} catch {
+		return [];
+	}
+	return status.split("\0").filter((entry) => entry.length > 3).map((entry) => relative(realpathSync(cwd), resolve(root, entry.slice(3))));
+}
+/**
+* A rewrite of hand-written files stops when one of them has uncommitted
+* changes, so `git diff` shows only what the command changed. `--force`
+* rewrites anyway.
+*/
+function refuseDirty(input) {
+	if (input.force) return;
+	const dirty = dirtyFiles(input.cwd, input.paths);
+	if (dirty.length === 0) return;
+	throw new CliError("action", `${input.command} rewrites files with uncommitted changes: ${dirty.join(", ")}. Commit or stash them first, so git diff shows only the rewrite.`, {
+		code: "dirty_worktree",
+		extensions: { files: dirty },
+		next: [{
+			when: "to see the changes first",
+			command: `permdock ${input.invocation} --dry-run`
+		}, {
+			when: "to rewrite anyway",
+			command: `permdock ${input.invocation} --force`
+		}]
+	});
+}
+//#endregion
+export { fileSummary as n, refuseDirty as r, applyFiles as t };