Policies: specificity-aware default position on the server (#1395)

* fix(policies): specificity-aware default position on the server The UI computed a specificity-aware position for new rules client-side, but the server defaulted a positionless create to the TOP of the owner's list. When the client's policy list was stale (e.g. the optimistic atom hadn't refreshed between two quick writes), the UI sent no usable position and the top-of-list default let a broad category rule shadow a narrower leaf rule written moments earlier — surfaced by the policies-ui scenario failing against the production selfhost image. Move the specificity placement into the sdk (positionForNewPattern) and make it the server-side default for create; the React hook now reuses the same helper so the optimistic order matches what the server commits. * fix(policies): badge Clear works while the policies list is mid-refresh The detail badge's Clear resolved the rule to remove by pattern-matching the local policies list. Right after the badge authors a rule, the post-commit refetch may not have landed, so the lookup missed and the clear silently no-oped — the second race the policies-ui scenario hit on the production image. Thread the resolved EffectivePolicy's policyId through as a fallback for exactly that window.

Rhys Sullivan committed 4 months ago

Commit d90d8be1 parent 1ca51119 files · +147 −50Browse files

Unified · Split

9 files

.changeset/policy-position-server-default.md +5 −0
packages/core/sdk/src/executor.ts +6 −7
packages/core/sdk/src/policies.test.ts +42 −1
packages/core/sdk/src/policies.ts +41 −0
packages/core/sdk/src/shared.ts +2 −0
packages/react/src/components/tool-detail.tsx +6 −3
packages/react/src/hooks/use-policy-actions.ts +39 −37
packages/react/src/pages/integration-detail.tsx +3 −1
packages/react/src/pages/tools.tsx +3 −1

.changeset/policy-position-server-default.md+5−0

@@ -0,0 +1,5 @@
	1	---
	2	"executor": patch
	3	---
	4
	5	Policy create now defaults a new rule's position below any more-specific existing rule on the server, so a broad rule written without an explicit position (stale UI, API, agent tool) cannot shadow an existing narrower rule.

packages/core/sdk/src/executor.ts+6−7

 import { withQueryContext, type Condition, type ConditionBuilder } from "@executor-js/fumadb/query";
 import { schema as fumaSchema, type RelationsMap } from "@executor-js/fumadb/schema";
 import type { AnyColumn } from "@executor-js/fumadb/schema";
-import { generateKeyBetween } from "fractional-indexing";
 import {
   StorageError,
   isStorageFailure,
   comparePolicyRow,
   isValidPattern,
   matchPattern,
+  positionForNewPattern,
   resolveEffectivePolicy,
   rowToToolPolicy,
   type CreateToolPolicyInput,
         const existing = yield* core.findMany("tool_policy", {
           where: byOwner(input.owner),
         });
-        const minPosition = existing
+        // Default placement is specificity-aware (below any more-specific
-          .map((row) => row.position)
+        // rule), not top-of-list: a client that omits position — the UI when
-          .sort()
+        // its policy list is stale, the API, an agent tool — must not have its
-          .at(0);
+        // broad rule silently shadow an existing narrow one.
-        const position = input.position ?? generateKeyBetween(null, minPosition ?? null);
+        const position = input.position ?? positionForNewPattern(input.pattern, existing);
         const id = PolicyId.make(
           `pol_${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`,
         );

packages/core/sdk/src/policies.test.ts+42−1

@@ -367,7 +367,7 @@ describe("executor.policies", () => { · 366 unmodified lines
367	}),	367	}),
368	);	368	);
369		369
370	it.effect("create defaults new rules to the top of the list", () =>	370	it.effect("create defaults new rules above equally-or-less-specific ones", () =>
371	Effect.gen(function* () {	371	Effect.gen(function* () {
372	const executor = yield* setupExecutor();	372	const executor = yield* setupExecutor();
373	const first = yield* executor.policies.create({	373	const first = yield* executor.policies.create({
@@ -387,6 +387,47 @@ describe("executor.policies", () => { · 13 unmodified lines
387	}),	387	}),
388	);	388	);
389		389
		390	it.effect("create places a broad rule below an existing narrower one", () =>
		391	Effect.gen(function* () {
		392	const executor = yield* setupExecutor();
		393	// Narrow leaf rule first, then a broad category rule WITHOUT an explicit
		394	// position — the category rule must not shadow the leaf rule.
		395	yield* executor.policies.create({
		396	owner: "org",
		397	pattern: "vercel...records.create",
		398	action: "block",
		399	});
		400	yield* executor.policies.create({
		401	owner: "org",
		402	pattern: "vercel...records.*",
		403	action: "require_approval",
		404	});
		405
		406	const rules = yield* executor.policies.list();
		407	expect(rules.map((r) => r.pattern)).toEqual([
		408	"vercel...records.create",
		409	"vercel...records.*",
		410	]);
		411
		412	const rows = rules.map(
		413	(r) =>
		414	({
		415	id: String(r.id),
		416	owner: r.owner,
		417	subject: "",
		418	pattern: r.pattern,
		419	action: r.action,
		420	position: r.position,
		421	created_at: r.createdAt,
		422	updated_at: r.updatedAt,
		423	}) as ToolPolicyRow,
		424	);
		425	const match = resolveToolPolicy("vercel.org.acct.records.create", rows, () => 0);
		426	expect(match?.action).toBe("block");
		427	expect(match?.pattern).toBe("vercel...records.create");
		428	}),
		429	);
		430
390	it.effect("create stores rules at the requested owner", () =>	431	it.effect("create stores rules at the requested owner", () =>
391	Effect.gen(function* () {	432	Effect.gen(function* () {
392	const executor = yield* setupExecutor();	433	const executor = yield* setupExecutor();

packages/core/sdk/src/policies.ts+41−0

@@ -10,6 +10,7 @@ · 9 unmodified lines
10	// ---------------------------------------------------------------------------	10	// ---------------------------------------------------------------------------
11		11
12	import { Match, Schema } from "effect";	12	import { Match, Schema } from "effect";
		13	import { generateKeyBetween } from "fractional-indexing";
13		14
14	import type { ToolPolicyAction, ToolPolicyRow } from "./core-schema";	15	import type { ToolPolicyAction, ToolPolicyRow } from "./core-schema";
15	import { Owner, PolicyId } from "./ids";	16	import { Owner, PolicyId } from "./ids";
@@ -139,6 +140,46 @@ export const comparePolicyRow = ( · 123 unmodified lines
139	return ia < ib ? -1 : ia > ib ? 1 : 0;	140	return ia < ib ? -1 : ia > ib ? 1 : 0;
140	};	141	};
141		142
		143	// Specificity score for ordering. Higher = more specific = should sit at a
		144	// lower position-key (higher precedence). New rules are auto-placed below
		145	// any more-specific existing rules so a freshly-added group rule never
		146	// silently shadows an existing leaf rule.
		147	// `*` → 0
		148	// `vercel.*` → 2 (1 literal segment, wildcard)
		149	// `vercel.dns.*` → 4 (2 literal segments, wildcard)
		150	// `vercel.dns` → 5 (2 literal segments, exact — beats same-prefix wildcard)
		151	// `vercel.dns.create` → 7 (3 literal segments, exact)
		152	export const patternSpecificity = (pattern: string): number => {
		153	if (pattern === "*") return 0;
		154	if (pattern.endsWith(".*")) {
		155	const prefix = pattern.slice(0, -2);
		156	return prefix.split(".").length * 2;
		157	}
		158	return pattern.split(".").length * 2 + 1;
		159	};
		160
		161	/**
		162	* Position key for a new rule among an owner's existing rules, placed just
		163	* below every existing rule that is MORE specific (and above everything
		164	* equally or less specific). Rows must be the owner's committed rules; order
		165	* doesn't matter, they're sorted here. This is the authoritative default —
		166	* the server applies it when `create` gets no explicit position, so a rule
		167	* written by any client (UI, API, agent tool) cannot shadow a more-specific
		168	* existing rule by racing to the top of the list.
		169	*/
		170	export const positionForNewPattern = (
		171	pattern: string,
		172	rows: ReadonlyArray<Pick<ToolPolicyRow, "pattern" \| "position" \| "id">>,
		173	): string => {
		174	const committed = [...rows].sort(comparePolicyRow);
		175	const newScore = patternSpecificity(pattern);
		176	let idx = committed.findIndex((r) => patternSpecificity(r.pattern) <= newScore);
		177	if (idx === -1) idx = committed.length; // below every more-specific rule
		178	const prev = idx === 0 ? null : committed[idx - 1]!.position;
		179	const next = idx === committed.length ? null : committed[idx]!.position;
		180	return generateKeyBetween(prev, next);
		181	};
		182
142	const actionRestrictionRank = (action: ToolPolicyAction): number =>	183	const actionRestrictionRank = (action: ToolPolicyAction): number =>
143	Match.value(action).pipe(	184	Match.value(action).pipe(
144	Match.when("block", () => 3),	185	Match.when("block", () => 3),

packages/core/sdk/src/shared.ts+2−0

   isValidPattern,
   effectivePolicyFromSorted,
   comparePolicyRow,
+  patternSpecificity,
+  positionForNewPattern,
   ToolPolicyActionSchema,
   type ToolPolicy,
   type CreateToolPolicyInput,

packages/react/src/components/tool-detail.tsx+6−3

   /** When provided, the policy badge becomes a dropdown trigger that
    *  applies a user rule to this tool's exact id. */
   onSetPolicy?: (pattern: string, action: ToolPolicyAction) => void;
-  onClearPolicy?: (pattern: string) => void;
+  onClearPolicy?: (pattern: string, policyId?: string) => void;
   patternForDisplay?: (displayPattern: string) => string;
   /** Run-tab wiring. When `integration` + `runToolName` are provided, a third
    *  "Run" tab hosts the per-connection tool tester. */
   staticTool?: boolean;
   policy?: EffectivePolicy;
   onSetPolicy?: (pattern: string, action: ToolPolicyAction) => void;
-  onClearPolicy?: (pattern: string) => void;
+  onClearPolicy?: (pattern: string, policyId?: string) => void;
   patternForDisplay?: (displayPattern: string) => string;
 }) {
   const interactive = !!props.onSetPolicy;
           <>
             <DropdownMenuSeparator />
             <DropdownMenuItem
-              onSelect={() => props.onClearPolicy?.(pattern)}
+              // Pass the resolved rule's id: right after this menu authored
+              // the rule, the policies list may still be mid-refresh, and a
+              // pattern-only lookup there would silently no-op the clear.
+              onSelect={() => props.onClearPolicy?.(pattern, props.policy?.policyId)}
               className="text-muted-foreground"
             >
               Clear

packages/react/src/hooks/use-policy-actions.ts+39−37

-import { useCallback, useMemo } from "react";
+import { useCallback, useMemo, useRef } from "react";
 import { useAtomSet, useAtomValue } from "@effect/atom-react";
 import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
-import { generateKeyBetween } from "fractional-indexing";
+import {
-import { PolicyId, type Owner, type ToolPolicyAction } from "@executor-js/sdk/shared";
+  PolicyId,
+  positionForNewPattern,
+  type Owner,
+  type ToolPolicyAction,
+} from "@executor-js/sdk/shared";
 import {
   createPolicyOptimistic,
 import { policyWriteKeys } from "../api/reactivity-keys";
 import { trackEvent } from "../api/analytics";
-// Specificity score for ordering. Higher = more specific = should sit at a
-// lower position-key (higher precedence). New rules are auto-placed below
-// any more-specific existing rules so a freshly-added group rule never
-// silently shadows an existing leaf rule.
-//   `*`            → 0
-//   `vercel.*`     → 2  (1 literal segment, wildcard)
-//   `vercel.dns.*` → 4  (2 literal segments, wildcard)
-//   `vercel.dns`   → 5  (2 literal segments, exact — beats same-prefix wildcard)
-//   `vercel.dns.create` → 7  (3 literal segments, exact)
-const specificity = (pattern: string): number => {
-  if (pattern === "*") return 0;
-  if (pattern.endsWith(".*")) {
-    const prefix = pattern.slice(0, -2);
-    return prefix.split(".").length * 2;
-  }
-  return pattern.split(".").length * 2 + 1;
-};
 export interface PolicyAction {
   /** Set the action on a pattern. If a user rule with this exact pattern
    *  already exists, update it. Otherwise create with auto-placed
    *  position so more-specific rules keep precedence. */
   readonly set: (pattern: string, action: ToolPolicyAction) => Promise<void>;
-  /** Remove the user rule with this exact pattern, if any. No-op if none. */
+  /** Remove the user rule with this exact pattern, if any. `policyId` is the
-  readonly clear: (pattern: string) => Promise<void>;
+   *  id of the rule the caller believes is active (e.g. from the tool's
+   *  resolved EffectivePolicy); it is the fallback when the local policies
+   *  list is mid-refresh and doesn't contain the rule yet — without it a
+   *  clear in that window silently no-ops. */
+  readonly clear: (pattern: string, policyId?: string) => Promise<void>;
   /** True while a write is in flight. */
   readonly busy: boolean;
 }
   const busy = policies.waiting;
+  // Server-assigned ids of rules this hook created, by pattern. The local
+  // policies list is optimistic: right after a create it holds a placeholder
+  // row with a fake `pending-*` id (and the resolved EffectivePolicy a caller
+  // hands back can carry that same fake id), so neither is safe to DELETE
+  // with. The create response is the one authoritative id source in that
+  // window.
+  const createdIdByPattern = useRef(new Map<string, string>());
+  // Specificity-aware placement (below any more-specific rule) via the shared
+  // sdk helper — the same computation the server applies when no position is
+  // sent. Computing it here too keeps the optimistic UI's final order stable;
+  // if this client's list is stale, the server default is the backstop.
   const computePosition = useCallback(
     (newPattern: string): string | undefined => {
       const committed = sorted.filter((r) => r.position !== "");
       if (committed.length === 0) return undefined;
-      const newScore = specificity(newPattern);
+      return positionForNewPattern(newPattern, committed);
-      // Walk down the list (most-precedent first); place the new rule
-      // just before the first existing rule whose specificity is <= the
-      // new one. That way more-specific rules stay above us, and we win
-      // against everything equally or less specific.
-      let idx = committed.findIndex((r) => specificity(r.pattern) <= newScore);
-      if (idx === -1) idx = committed.length; // append at bottom
-      const prev = idx === 0 ? null : committed[idx - 1]!.position;
-      const next = idx === committed.length ? null : committed[idx]!.position;
-      return generateKeyBetween(prev, next);
     },
     [sorted],
   );
         return;
       }
       const position = computePosition(pattern);
-      await doCreate({
+      const created = await doCreate({
         payload:
           position === undefined
             ? { owner, pattern, action }
             : { owner, pattern, action, position },
         reactivityKeys: policyWriteKeys,
       });
+      createdIdByPattern.current.set(pattern, String(created.id));
       trackEvent("tool_policy_set", { action, pattern_kind: patternKind, owner });
     },
     [owner, doCreate, doUpdate, findExact, computePosition],
   );
   const clear = useCallback(
-    async (pattern: string) => {
+    async (pattern: string, policyId?: string) => {
+      // Resolve the id to delete, most-authoritative first. The local list
+      // and the caller's resolved policy can both hold an optimistic
+      // `pending-*` placeholder id right after a create (before the
+      // post-commit refetch lands); the create response we recorded is real,
+      // and a placeholder id must never reach the server.
       const existing = findExact(pattern);
-      if (!existing) return;
+      const isReal = (id: string | undefined): id is string => !!id && !id.startsWith("pending-");
+      const id = [existing?.id, createdIdByPattern.current.get(pattern), policyId].find(isReal);
+      if (!id) return;
+      createdIdByPattern.current.delete(pattern);
       await doRemove({
-        params: { policyId: PolicyId.make(existing.id) },
+        params: { policyId: PolicyId.make(id) },
         payload: { owner },
         reactivityKeys: policyWriteKeys,
       });

packages/react/src/pages/integration-detail.tsx+3−1

                         staticTool={selection?.static}
                         policy={selectedTool.policy}
                         onSetPolicy={(pattern, action) => void policyActions.set(pattern, action)}
-                        onClearPolicy={(pattern) => void policyActions.clear(pattern)}
+                        onClearPolicy={(pattern, policyId) =>
+                          void policyActions.clear(pattern, policyId)
+                        }
                         {...(!selection?.static && selectedBareName
                           ? {
                               integration: slug,

packages/react/src/pages/tools.tsx+3−1

                       staticTool={selection?.static}
                       policy={selectedTool.policy}
                       onSetPolicy={(pattern, action) => void policyActions.set(pattern, action)}
-                      onClearPolicy={(pattern) => void policyActions.clear(pattern)}
+                      onClearPolicy={(pattern, policyId) =>
+                        void policyActions.clear(pattern, policyId)
+                      }
                     />
                   ) : (
                     <ToolDetailEmpty hasTools={summaries.length > 0} />