permdock 0.6.0 → 0.8.0

package/dist/mcp/index.js

@@ -1,27 +1,33 @@
 import { r as isRecord, t as compact } from "../compact-CAf557ZB.js";
-import { n as freezeDeep } from "../freeze-CrU8nQeX.js";
-import { i as stepUpOf } from "../problem-details-cn5X30gZ.js";
-import { t as describe } from "../describe-BybMRY7A.js";
-import { m as annotationsFor } from "../permission-registry-Br4jSNVi.js";
-import { t as actorMayCallTool } from "../delegation-j6-rc37o.js";
+import { n as freezeDeep } from "../freeze-jjan0lCv.js";
+import { i as stepUpOf, o as statusProblem } from "../problem-details-CLDgX1KV.js";
+import { n as describe } from "../describe-Bb4hGK5d.js";
+import { m as annotationsFor } from "../permission-registry-B8tYxPIt.js";
+import { t as actorMayCallTool } from "../delegation-CDB6_keF.js";
 import { n as resourceRef } from "../resource-ref-CaS9yVPi.js";
-import { a as hasScope, c as withApp, i as challengeScope, o as scopesReaching } from "../permdock-BrAscV28.js";
+import { i as challengeScope, l as withApp, o as hasScope, s as scopesReaching } from "../permdock-L-_I_3zP.js";
 import { t as anonymousSubject } from "../subject-BGoM5o8B.js";
-import { t as composeWraps } from "../wrap-gX61EtpB.js";
-import { l as protectedResourceMetadataUrl, r as bearerChallenge } from "../problem-CTviyH5L.js";
-import { t as clientNameOf } from "../clients-DjU5ABMy.js";
-import { n as mapClaimsToSubject } from "../map-claims-D3oRmTk0.js";
-import { r as instanceOptions } from "../build-instance-Bu_eDqYw.js";
-import { n as createAgentKernel, r as refusalText } from "../kernel-D0NVb1cK.js";
+import { t as composeWraps } from "../wrap-B2wziJI_.js";
+import { l as problemResponse, o as methodNotAllowed, r as bearerChallenge, u as protectedResourceMetadataUrl } from "../problem-BVLHFK33.js";
+import { t as clientNameOf } from "../clients-DYr3U86j.js";
+import { r as mapClaimsToSubject } from "../map-claims-BNWCJtmP.js";
+import { r as instanceOptions } from "../build-instance-CNWaYJyr.js";
+import { i as refusalText, n as createAgentKernel } from "../kernel-C-fYydV2.js";
 import { t as boundedMap } from "../lru-8q4WZjBV.js";
 import { t as delegationFrom } from "../delegation-input-FTxMK3ji.js";
-import { n as deniedToolRefusal, r as toolErrorResult, t as approvalToolRefusal } from "../tool-refusal-CMLN5xhn.js";
+import { n as deniedToolRefusal, r as toolErrorResult, t as approvalToolRefusal } from "../tool-refusal-Qpjs_W6M.js";
 //#region src/mcp/mcp-auth.ts
-/** `_meta` key on `tools/call`, `resources/read` and `prompts/get` carrying an approval token. */
+/**
+* `_meta` key on `tools/call`, `resources/read` and `prompts/get` carrying an
+* approval token.
+*/
 const APPROVAL_META_KEY = "dev.permdock/approval";
 const CLIENT_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities";
 const PROTOCOL_VERSION = "io.modelcontextprotocol/protocolVersion";
-/** The first protocol revision whose list results define `ttlMs` and `cacheScope`. */
+/**
+* The first protocol revision whose list results define `ttlMs` and
+* `cacheScope`.
+*/
 const CACHEABLE_LISTS_SINCE = "2026-07-28";
 function contextOf(value) {
 	return isRecord(value) ? value : {};
@@ -54,8 +60,8 @@ function sameResource(expected, actual) {
 }
 /**
 * Whether the request was sent under a revision that defines `cacheScope` on
-* list results. Only those requests carry the per-request envelope; a
-* 2025-era request has none and gets no cache fields.
+* list results. Only those requests carry the per-request envelope; a 2025-era
+* request has none and gets no cache fields.
 */
 function definesCacheScope(context) {
 	const version = context.mcpReq?.envelope?.[PROTOCOL_VERSION];
@@ -165,7 +171,10 @@ function throwRefusal(refusal) {
 	if (refusal.inputRequired !== void 0) return refusal.inputRequired;
 	throw new Error(refusal.text);
 }
-/** The MRTR URL elicitation that sends the user to `options.approval.at`, when the client accepts one. */
+/**
+* The MRTR URL elicitation that sends the user to `options.approval.at`, when
+* the client accepts one.
+*/
 async function approvalInput(options, decision, handlerContext, context, capabilities) {
 	const at = options.approval?.at;
 	if (at === void 0 || !acceptsUrlElicitation(context, capabilities)) return;
@@ -174,7 +183,10 @@ async function approvalInput(options, decision, handlerContext, context, capabil
 	const requestState = options.requestState === void 0 ? decision.token : await options.requestState.mint(decision.token, handlerContext);
 	return urlElicitation("approval", options.approval?.hint ?? describe(decision).detail, url, requestState);
 }
-/** A step-up denial: the RFC 9470 challenge, and a URL elicitation to `stepUpAt` when the client accepts one. */
+/**
+* A step-up denial: the RFC 9470 challenge, and a URL elicitation to `stepUpAt`
+* when the client accepts one.
+*/
 function stepUpRefusal(stepUpAt, decision, permission, data, context, capabilities) {
 	const base = deniedRefusal(decision, permission, data);
 	const { acrValues, maxAge } = stepUpOf(decision);
@@ -215,7 +227,10 @@ function forThisServer(checks, authInfo) {
 function reachable(checks, authInfo, reach) {
 	return authInfo === void 0 ? checks.options.requireAuthInfo !== true : forThisServer(checks, authInfo) && hasScope(authInfo.scopes, reach.scopes);
 }
-/** The refusal a token earns before any decision: none, the wrong resource, or a missing scope. */
+/**
+* The refusal a token earns before any decision: none, the wrong resource, or a
+* missing scope.
+*/
 function credentialRefusal(checks, permission, reach, authInfo) {
 	if (authInfo === void 0) return checks.options.requireAuthInfo === true ? plainRefusal(permission, "Denied: no verified credentials.", { error: "invalid_token" }) : void 0;
 	if (!forThisServer(checks, authInfo)) return plainRefusal(permission, "Denied: the token was not issued for this server.", { error: "invalid_token" });
@@ -233,7 +248,10 @@ function credentialRefusal(checks, permission, reach, authInfo) {
 		}))
 	}));
 }
-/** The completion re-check of a long-running tool: the call must still be allowed, or approved with the same token. */
+/**
+* The completion re-check of a long-running tool: the call must still be
+* allowed, or approved with the same token.
+*/
 async function recheck(checks, binding, args, call, permission, approved, tool) {
 	const rechecked = await checks.kernel.check(binding, args, call, compact({
 		simulate: true,
@@ -328,8 +346,9 @@ async function checkCall(checks, permission, reach, args, load, context, handler
 	};
 }
 /**
-* The keys a list shows: unguarded ones, and guarded ones the token reaches and the subject may use.
-* With `tools`, a guarded key is also a tool name an `agent` actor's `tools` list must name.
+* The keys a list shows: unguarded ones, and guarded ones the token reaches and
+* the subject may use. With `tools`, a guarded key is also a tool name an
+* `agent` actor's `tools` list must name.
 */
 async function visible(checks, context, permissionOf, keys, declaredOf = () => void 0, tools = false) {
 	const authInfo = context.http?.authInfo;
@@ -383,6 +402,13 @@ function requirePermission(kind, name, config) {
 	if (!isRecord(permission) || typeof permission["key"] !== "string") throw new TypeError(`permdock/mcp: ${kind} ${name} has no permission; every guarded registration needs one.`);
 	return permission;
 }
+const UI_SCHEME = "ui://";
+/** The MCP Apps view a tool links through `_meta.ui.resourceUri`. */
+function uiResourceUri(meta) {
+	const ui = isRecord(meta) ? meta["ui"] : void 0;
+	const uri = isRecord(ui) ? ui["resourceUri"] : void 0;
+	return typeof uri === "string" && uri.startsWith(UI_SCHEME) ? uri : void 0;
+}
 function guardUpdates(registered, wrap, rename, currentName) {
 	const update = registered.update.bind(registered);
 	registered.update = (updates) => {
@@ -400,21 +426,23 @@ function protectServer(checks, server, enforcement) {
 	const toolScopes = /* @__PURE__ */ new Map();
 	const prompts = /* @__PURE__ */ new Map();
 	const resources = /* @__PURE__ */ new Map();
+	const views = /* @__PURE__ */ new Set();
+	const uiLinks = /* @__PURE__ */ new Map();
 	const templates = [];
 	const lastListed = boundedMap(SESSIONS_PER_SERVER);
 	const toolPermission = (name) => tools.get(name);
 	const toolDeclared = (name) => toolScopes.get(name);
 	const promptPermission = (name) => prompts.get(name);
 	const resourcePermission = (uri) => {
-		const direct = resources.get(uri);
+		const direct = resources.get(uri) ?? uiLinks.get(uri)?.permission;
 		if (direct !== void 0) return direct;
 		return templates.find((entry) => entry.template.uriTemplate.match(uri) !== null)?.permission;
 	};
 	const templatePermission = (uriTemplate) => templates.find((entry) => entry.template.uriTemplate.toString() === uriTemplate)?.permission;
-	const listFilter = (field, keyOf, permissionOf, remember) => async (result, rawContext) => {
+	const listFilter = (field, keyOf, permissionOf, remember, hidden = () => false) => async (result, rawContext) => {
 		if (!isRecord(result) || !Array.isArray(result[field])) return result;
 		const context = contextOf(rawContext);
-		const entries = result[field];
+		const entries = result[field].filter((entry) => !hidden(keyOf(entry)));
 		const shown = await visible(checks, context, permissionOf, entries.map(keyOf), remember ? toolDeclared : void 0, remember);
 		const kept = entries.filter((entry) => shown.has(keyOf(entry)));
 		if (remember) lastListed.set(sessionKey(context), [...shown].toSorted().join(","));
@@ -430,7 +458,7 @@ function protectServer(checks, server, enforcement) {
 	const filters = {
 		"tools/list": listFilter("tools", (entry) => entry.name, toolPermission, true),
 		"prompts/list": listFilter("prompts", (entry) => entry.name, promptPermission, false),
-		"resources/list": listFilter("resources", (entry) => entry.uri, resourcePermission, false),
+		"resources/list": listFilter("resources", (entry) => entry.uri, resourcePermission, false, (uri) => views.has(uri) && resourcePermission(uri) === void 0),
 		"resources/templates/list": listFilter("resourceTemplates", (entry) => entry.uriTemplate, templatePermission, false)
 	};
 	const inner = server.server;
@@ -476,7 +504,10 @@ function protectServer(checks, server, enforcement) {
 		for (const field of ["data", "longRunning"]) if (config[field] !== void 0) throw new TypeError(`permdock/mcp: tool ${name} sets ${field}, but with enforce: 'procedure' its procedure decides.`);
 		return requirePermission("tool", name, { permission: enforcement.permissionFor(name) });
 	};
-	/** With `enforce: 'procedure'` the handler runs undecided: the procedure it calls decides. */
+	/**
+	* With `enforce: 'procedure'` the handler runs undecided: the procedure it
+	* calls decides.
+	*/
 	const wrapTool = (tool, permission, reach, load, handler, longRunning) => enforcement === void 0 ? guardTool(tool, permission, reach, load, handler, longRunning) : async (...params) => {
 		const result = await handler(...params);
 		await announce(contextOf(params.at(-1)));
@@ -484,6 +515,9 @@ function protectServer(checks, server, enforcement) {
 	};
 	const registerTool = (name, config, handler) => {
 		const permission = toolPermissionOf(name, config);
+		const view = uiResourceUri(config["_meta"]);
+		const linked = view === void 0 ? void 0 : uiLinks.get(view);
+		if (view !== void 0 && linked !== void 0 && linked.permission.key !== permission.key) throw new TypeError(`permdock/mcp: tools ${linked.tool} and ${name} link ${view} under different permissions; give the resource its own permission.`);
 		const { permission: _permission, data, scopeChallenge, longRunning: rawLongRunning, oauthScopes: rawScopes, ...passthrough } = config;
 		const load = data;
 		const longRunning = rawLongRunning === true;
@@ -501,6 +535,10 @@ function protectServer(checks, server, enforcement) {
 		}, wrapTool(tool, permission, reach, load, handler, longRunning));
 		tools.set(name, permission);
 		if (declared !== void 0) toolScopes.set(name, declared);
+		if (view !== void 0 && linked === void 0) uiLinks.set(view, {
+			tool: name,
+			permission
+		});
 		guardUpdates(registered, (callback) => wrapTool(tool, permission, reach, load, callback, longRunning), (from, to) => {
 			tools.delete(from);
 			toolScopes.delete(from);
@@ -528,18 +566,33 @@ function protectServer(checks, server, enforcement) {
 	};
 	const originalResource = server.registerResource.bind(server);
 	const registerResource = (name, uriOrTemplate, config, read) => {
-		const permission = requirePermission("resource", name, config);
+		const own = config["permission"] === void 0 && typeof uriOrTemplate === "string" && uriOrTemplate.startsWith(UI_SCHEME) ? void 0 : requirePermission("resource", name, config);
+		/**
+		* A `ui://` view without its own permission takes the one of the tool
+		* linking it; unlinked, it denies.
+		*/
+		const permissionNow = () => own ?? (typeof uriOrTemplate === "string" ? uiLinks.get(uriOrTemplate)?.permission : void 0);
 		const { permission: _permission, data, scopeChallenge, ...passthrough } = config;
 		const load = data;
-		const wrap = (callback) => guard(checks, permission, load, callback, (params) => params.slice(0, -1), throwRefusal, { capabilities });
+		const ownChallenge = scopeChallenge;
+		const wrap = (callback) => (...params) => {
+			const permission = permissionNow();
+			if (permission === void 0) return Promise.reject(/* @__PURE__ */ new Error(`Denied: resource ${name} is linked to no guarded tool.`));
+			return guard(checks, permission, load, callback, (args) => args.slice(0, -1), throwRefusal, { capabilities })(...params);
+		};
 		const registered = originalResource(name, uriOrTemplate, {
 			...passthrough,
-			scopeChallenge: challengeFor(scopeChallenge, scopesReaching(checks.policy, permission), challengeScope(checks.policy, permission))
+			scopeChallenge: (context) => {
+				const permission = permissionNow();
+				return permission === void 0 ? ownChallenge?.(context) : challengeFor(ownChallenge, scopesReaching(checks.policy, permission), challengeScope(checks.policy, permission))(context);
+			}
 		}, wrap(read));
-		if (typeof uriOrTemplate === "string") resources.set(uriOrTemplate, permission);
-		else templates.push({
+		if (typeof uriOrTemplate === "string") {
+			if (own === void 0) views.add(uriOrTemplate);
+			else resources.set(uriOrTemplate, own);
+		} else if (own !== void 0) templates.push({
 			template: uriOrTemplate,
-			permission
+			permission: own
 		});
 		guardUpdates(registered, wrap);
 		return registered;
@@ -553,18 +606,20 @@ function protectServer(checks, server, enforcement) {
 //#endregion
 //#region src/mcp/subject.ts
 const DEFAULT_MCP_ACTOR_KIND = "mcp-client";
-/** `kind`, or the default when absent; `undefined` for a kind that is not a non-empty string. */
+/**
+* `kind`, or the default when absent; `undefined` for a kind that is not a
+* non-empty string.
+*/
 function mcpActorKind(kind) {
 	if (kind === void 0) return DEFAULT_MCP_ACTOR_KIND;
 	return typeof kind === "string" && kind !== "" ? kind : void 0;
 }
 /**
 * Maps the `AuthInfo` the MCP SDK's bearer verification produced to a
-* `Subject`: the principal from the verified claims in `extra`, the client
-* as an actor of kind `actorKind` (`mcp-client` by default), the granted
-* scopes as the delegation. Never verifies and never throws; anything
-* unusable, including an `actorKind` that is not a non-empty string, is
-* the anonymous subject.
+* `Subject`: the principal from the verified claims in `extra`, the client as
+* an actor of kind `actorKind` (`mcp-client` by default), the granted scopes as
+* the delegation. Never verifies and never throws; anything unusable, including
+* an `actorKind` that is not a non-empty string, is the anonymous subject.
 */
 function subjectFromMcp(authInfo, options = {}) {
 	try {
@@ -628,4 +683,108 @@ function createPermDock(policy, given) {
 	return { protectServer: ((server, enforcement) => protectServer(checks, server, enforcement)) };
 }
 //#endregion
-export { APPROVAL_META_KEY, createPermDock, subjectFromMcp };
+//#region src/mcp/resource-guard.ts
+/**
+* The `error_description` of every `invalid_token` challenge (RFC 6750 section
+* 3.1).
+*/
+const INVALID_TOKEN = "The access token is invalid";
+const BEARER = /^Bearer +([\w~+/.-]+=*)$/iu;
+function tokenScopes(claims) {
+	const { scope, scp } = claims;
+	if (typeof scope === "string") return scope.split(" ").filter((name) => name !== "");
+	return Array.isArray(scp) ? scp.filter((name) => typeof name === "string") : [];
+}
+function refuse(status, challenge, detail) {
+	return {
+		ok: false,
+		response: problemResponse(statusProblem(status, detail), void 0, void 0, { "WWW-Authenticate": challenge })
+	};
+}
+/**
+* The resource-server check in front of an MCP endpoint (MCP authorization, RFC
+* 6750, RFC 9728): reads the bearer token from `Authorization`, verifies it for
+* `resource`, refuses a revoked one and checks `scopes`. It answers the
+* `McpAuthInfo` the SDK's handlers read, or the `401` or `403` response with a
+* `WWW-Authenticate` challenge naming the metadata URL. A token in the query
+* string is never read. Never throws.
+*/
+function mcpResourceGuard(options) {
+	const resource = new URL(String(options.resource));
+	const resourceMetadata = options.resourceMetadataUrl ?? protectedResourceMetadataUrl(resource);
+	const required = options.scopes ?? [];
+	const invalid = () => refuse(401, bearerChallenge({
+		error: "invalid_token",
+		description: INVALID_TOKEN,
+		resourceMetadata
+	}), "invalid access token");
+	return async (request) => {
+		const header = request.headers.get("authorization");
+		if (header === null || header.trim() === "") return refuse(401, `Bearer resource_metadata="${resourceMetadata}"`, "access token required");
+		const token = BEARER.exec(header.trim())?.[1];
+		if (token === void 0) return invalid();
+		let claims;
+		try {
+			const verified = await options.verifier.verify(token, compact({
+				audience: resource.href,
+				issuer: options.issuer
+			}));
+			if (!verified.ok) return invalid();
+			claims = verified.claims;
+			if (options.revoked !== void 0 && await options.revoked(claims)) return invalid();
+		} catch {
+			return invalid();
+		}
+		const scopes = tokenScopes(claims);
+		if (required.some((scope) => !scopes.includes(scope))) return refuse(403, bearerChallenge({
+			error: "insufficient_scope",
+			scopes: required,
+			resourceMetadata
+		}), "insufficient scope");
+		const clientId = claims["client_id"] ?? claims["azp"];
+		return {
+			ok: true,
+			authInfo: compact({
+				token,
+				clientId: typeof clientId === "string" ? clientId : void 0,
+				scopes,
+				expiresAt: claims.exp,
+				resource,
+				resourceMetadataUrl: resourceMetadata,
+				extra: { claims }
+			})
+		};
+	};
+}
+/**
+* The RFC 9728 Protected Resource Metadata document as a Fetch handler, for
+* `/.well-known/oauth-protected-resource<path>`. `bearer_methods_supported` is
+* `header`, the only method `mcpResourceGuard` reads. Any origin may read it.
+*/
+function protectedResourceMetadata(options) {
+	const body = JSON.stringify(compact({
+		resource: new URL(String(options.resource)).href,
+		authorization_servers: options.authorizationServers,
+		scopes_supported: options.scopesSupported,
+		bearer_methods_supported: ["header"],
+		resource_name: options.resourceName,
+		resource_documentation: options.resourceDocumentation
+	}));
+	return (request) => {
+		if (request.method === "OPTIONS") return new Response(null, {
+			status: 204,
+			headers: {
+				"access-control-allow-origin": "*",
+				"access-control-allow-methods": "GET, OPTIONS"
+			}
+		});
+		if (request.method !== "GET" && request.method !== "HEAD") return methodNotAllowed("GET, HEAD, OPTIONS");
+		return new Response(request.method === "HEAD" ? null : body, { headers: {
+			"content-type": "application/json",
+			"access-control-allow-origin": "*",
+			"cache-control": "public, max-age=3600"
+		} });
+	};
+}
+//#endregion
+export { APPROVAL_META_KEY, createPermDock, mcpResourceGuard, protectedResourceMetadata, subjectFromMcp };

package/dist/{migrate-CIq4-E9F.js → migrate-B7oP_sQU.js}

@@ -1,15 +1,15 @@
 import { r as isRecord } from "./compact-CAf557ZB.js";
-import { i as dateAt } from "./time-DkWjdL98.js";
-import { a as describeError } from "./errors-CWTY6uih.js";
-import { o as sqlFiles } from "./files-D_JIzUrP.js";
-import { r as escapeSqlIdent, s as quoteSqlLiteral } from "./sql-B5T1IL83.js";
-import "./sources-vs5dGOsS.js";
-import { a as RETIRE_MARKER } from "./markers-C6joDI3o.js";
-import { r as refuseDirty, t as applyFiles } from "./files-C5ZI27eV.js";
-import { f as writeOutputFiles, n as dataMigrationFile } from "./output-files-DhRBBE4n.js";
-import { r as HELPERS } from "./shared-BAK8t4Uo.js";
-import { o as sqlStatements } from "./deciding-columns-Sq12mEA6.js";
-import { i as retireSql, r as retirePlan } from "./retire-CALjIQ7e.js";
+import { i as dateAt } from "./time-nR1JesoH.js";
+import { a as describeError } from "./errors-Vpu6rKHl.js";
+import { o as sqlFiles } from "./files-BSjrtIHw.js";
+import { r as escapeSqlIdent, s as quoteSqlLiteral } from "./sql-0WjxIp9g.js";
+import "./sources-CMAM-2A3.js";
+import { a as RETIRE_MARKER } from "./markers-BeHZ4x9Q.js";
+import { i as refuseDirty, t as applyFiles } from "./files-B3AA05f1.js";
+import { f as writeOutputFiles, n as dataMigrationFile } from "./output-files-BIQ_9pIs.js";
+import { r as HELPERS } from "./shared-Afctg7B0.js";
+import { o as sqlStatements } from "./deciding-columns-NB4wcyBf.js";
+import { i as retireSql, r as retirePlan } from "./retire-B2xffQgY.js";
 import { existsSync, readFileSync } from "node:fs";
 import { relative, resolve } from "node:path";
 import { parse } from "pgsql-parser";
@@ -84,6 +84,32 @@ function callEnd(text, start) {
 	}
 	return -1;
 }
+/**
+* The top-level arguments of the call at `start`, as written; `end` is past its
+* closing paren.
+*/
+function argTexts(text, start, end) {
+	const open = text.indexOf("(", start);
+	const args = [];
+	let from = open + 1;
+	let depth = 0;
+	for (let index = open; index < end; index += 1) {
+		const char = text[index];
+		if (char === "'" || char === "\"") {
+			index = Math.max(text.indexOf(char, index + 1), index);
+			continue;
+		}
+		if (char === "(" || char === "[") depth += 1;
+		else if (char === ")" || char === "]") {
+			depth -= 1;
+			if (depth === 0) args.push(text.slice(from, index));
+		} else if (char === "," && depth === 1) {
+			args.push(text.slice(from, index));
+			from = index + 1;
+		}
+	}
+	return args.map((arg) => arg.trim());
+}
 const IDENTIFIER = String.raw`(?:"(?:[^"]|"")+"|[A-Za-z_][\w$]*)`;
 const COLUMN = new RegExp(String.raw`${IDENTIFIER}(?:\s*\.\s*${IDENTIFIER})*`, "uy");
 function columnText(text, start) {
@@ -106,7 +132,10 @@ function isNullConst(node) {
 	return child(child(node, "A_Const"), "isnull") === true;
 }
 const literal = quoteSqlLiteral;
-/** The PermDock key for a legacy one: `keys` first, then `renamed`, then the longest matching prefix. */
+/**
+* The PermDock key for a legacy one: `keys` first, then `renamed`, then the
+* longest matching prefix.
+*/
 function mapKey(config, key, renamed = {}) {
 	const exact = config.keys?.[key];
 	if (exact !== void 0) return exact;
@@ -125,6 +154,8 @@ var Rewriter = class {
 	#target;
 	#text;
 	#at;
+	/** The written arguments of the call being rewritten. */
+	#args = [];
 	constructor(config, target, text) {
 		this.#config = config;
 		this.#target = target;
@@ -146,9 +177,12 @@ var Rewriter = class {
 		if (this.#target.granted.get(scope)?.has(key) !== true) return skip("not-granted-on-scope", [...this.#target.granted.values()].some((keys) => keys.has(key)) ? `no role grants ${key} on ${scope}, so the helper would always deny` : `${key} has no unconditional allow row in role_permissions: a conditional, time-bounded or deny-mixed grant splits its grant key, so the helper would always deny`);
 		return { to: literal(key) };
 	}
-	#column(arg) {
+	#column(arg, index) {
 		const location = child(child(arg, "ColumnRef"), "location");
-		if (typeof location !== "number") return skip("not-a-column", "the id is an expression, not a plain column; rewrite it by hand");
+		if (typeof location !== "number") {
+			const written = this.#args[index];
+			return written === void 0 || written === "" ? skip("not-a-column", "the id is an expression whose text could not be read; rewrite it by hand") : { to: `(${written})` };
+		}
 		const text = columnText(this.#text, this.#at(location));
 		return text === void 0 ? skip("not-a-column", "the id could not be read as a column") : { to: text };
 	}
@@ -158,8 +192,8 @@ var Rewriter = class {
 		const key = this.#key(keyArg, scope);
 		return "to" in key ? { to: `${helper}(${key.to})` } : key;
 	}
-	#row(scope, idArg, keyArg) {
-		const column = this.#column(idArg);
+	#row(scope, idArg, keyArg, idIndex) {
+		const column = this.#column(idArg, idIndex);
 		if (!("to" in column)) return column;
 		const ids = this.#ids(scope, keyArg);
 		return "to" in ids ? { to: `(${column.to} in (select ${ids.to}))` } : ids;
@@ -175,7 +209,7 @@ var Rewriter = class {
 	#membership(scope, idArg) {
 		const helper = this.#helper(`member_${scope}_ids`);
 		if (helper === void 0) return skip("missing-helper", `rls generate writes no member_${scope}_ids: ${scope} has no membership source`);
-		const column = this.#column(idArg);
+		const column = this.#column(idArg, 0);
 		return "to" in column ? { to: `(${column.to} in (select ${helper}()))` } : column;
 	}
 	#role(scope, idArg, roleArgs) {
@@ -190,7 +224,7 @@ var Rewriter = class {
 			if (!this.#target.roles.has(declared)) return skip("unknown-role", `${value} maps to ${declared}, which no role grants; add it to rls.roleValues or declare the role`);
 			mapped.push(declared);
 		}
-		const column = this.#column(idArg);
+		const column = this.#column(idArg, 0);
 		return "to" in column ? { to: `(${column.to} in (select ${helper}(array[${mapped.map(literal).join(", ")}])))` } : column;
 	}
 	#scoped(args, selected) {
@@ -198,14 +232,18 @@ var Rewriter = class {
 		const named = stringConst(scopeArg);
 		if (named === void 0) return skip("unknown-scope", "the scope is not a string literal; rewrite it by hand");
 		if (this.#config.globalScopes?.includes(named) === true || isNullConst(idArg)) return this.#global(keyArg, selected);
-		return this.#row(this.#config.scopes?.[named] ?? named, idArg, keyArg);
+		return this.#row(this.#config.scopes?.[named] ?? named, idArg, keyArg, 1);
 	}
-	/** `selected`: the call is already a `select` target, so `permdock_has` needs no wrapping subquery. */
+	/**
+	* `selected`: the call is already a `select` target, so `permdock_has` needs
+	* no wrapping subquery.
+	*/
 	rewrite(call, selected) {
 		const { helper, args } = call;
+		this.#args = argTexts(this.#text, call.start, call.end);
 		switch (helper.form) {
 			case "ids": return this.#ids(helper.scope, args[0]);
-			case "row": return this.#row(helper.scope, args[0], args[1]);
+			case "row": return this.#row(helper.scope, args[0], args[1], 0);
 			case "membership": return this.#membership(helper.scope, args[0]);
 			case "role": return this.#role(helper.scope, args[0], args.slice(1));
 			case "scoped": return this.#scoped(args, selected);
@@ -246,7 +284,31 @@ function bodyStrings(statement) {
 	}
 	return found;
 }
-/** Rewrites the configured helper calls in one file's policies; everything else is reported. */
+/**
+* What `call`, written inside a function body, becomes: the rewrite that its
+* place keeps from being applied.
+*/
+async function suggest(call, config, target) {
+	const sql = `select ${call}`;
+	let tree;
+	try {
+		tree = await parse(sql);
+	} catch {
+		return;
+	}
+	const target0 = list(child(child(child(list(child(tree, "stmts"))[0], "stmt"), "SelectStmt"), "targetList"))[0];
+	const node = child(child(child(target0, "ResTarget"), "val"), "FuncCall");
+	if (!isRecord(node)) return;
+	const rewriter = new Rewriter(config, target, sql);
+	const found = rewriter.call(node);
+	if (found === void 0 || found.end === -1) return;
+	const outcome = rewriter.rewrite(found, true);
+	return "to" in outcome ? outcome.to : void 0;
+}
+/**
+* Rewrites the configured helper calls in one file's policies; everything else
+* is reported.
+*/
 async function migrateSql(file, text, config, target) {
 	const rewrites = [];
 	const skipped = [];
@@ -332,13 +394,19 @@ async function migrateSql(file, text, config, target) {
 		if (kind !== void 0 && BODY_STATEMENTS.has(kind)) {
 			for (const body of bodyStrings(child(statement, kind))) {
 				const bodyStart = text.indexOf(body, statementStart);
-				for (const match of body.matchAll(called)) skipped.push({
-					file,
-					line: lineOf(text, (bodyStart === -1 ? statementStart : bodyStart) + (match.index ?? 0)),
-					call: match[1] ?? "",
-					reason: "function-body",
-					detail: "the call is inside a function body, which runs with its own privileges; rewrite it by hand"
-				});
+				for (const match of body.matchAll(called)) {
+					const matchAt = match.index ?? 0;
+					const end = callEnd(body, matchAt);
+					const suggestion = end === -1 ? void 0 : await suggest(body.slice(matchAt, end), config, target);
+					skipped.push({
+						file,
+						line: lineOf(text, (bodyStart === -1 ? statementStart : bodyStart) + matchAt),
+						call: match[1] ?? "",
+						reason: "function-body",
+						detail: "the call is inside a function body, which runs with its own privileges; rewrite it by hand",
+						...suggestion === void 0 ? {} : { suggestion }
+					});
+				}
 			}
 			continue;
 		}
@@ -359,13 +427,16 @@ function describeRetire(plan) {
 	});
 }
 function describe(report, write) {
-	const lines = [...report.rewrites.map((item) => `${item.file}:${String(item.line)}  ${item.from}  ->  ${item.to}`), ...report.skipped.map((item) => `skipped ${item.file}:${String(item.line)}  ${item.call}: ${item.detail}`)];
+	const lines = [...report.rewrites.map((item) => `${item.file}:${String(item.line)}  ${item.from}  ->  ${item.to}`), ...report.skipped.map((item) => `skipped ${item.file}:${String(item.line)}  ${item.call}: ${item.detail}${item.suggestion === void 0 ? "" : `; use ${item.suggestion}`}`)];
 	const files = new Set(report.rewrites.map((item) => item.file)).size;
 	const unknown = report.skipped.filter((item) => item.reason === "unknown-key").length;
 	lines.push(`rls migrate: ${write ? "rewrote" : "would rewrite"} ${String(report.rewrites.length)} call(s) in ${String(files)} file(s), skipped ${String(report.skipped.length)}${unknown === 0 ? "" : `, ${String(unknown)} with an unknown key`}${write ? "" : "; drop --dry-run to apply them"}`);
 	return lines.join("\n");
 }
-/** `permdock rls migrate`: a dry run unless `write`; exits 1 while a key is unknown. */
+/**
+* `permdock rls migrate`: a dry run unless `write`; exits 1 while a key is
+* unknown.
+*/
 async function runRlsMigrate(input) {
 	const root = resolve(input.cwd, input.sql);
 	if (!existsSync(root)) return {