@ultimat3/policy 9.0.0 → 10.0.0

package/CLAUDE.md

@@ -32,6 +32,14 @@ two differ, and it is why a surface that decides on input alone needs no edit.
 
 - **Never add a second authz path.** If a surface cannot use `evaluate()`, add an
   adapter to `surfaces.ts` — nothing else.
+- **`enforce()` dispatches with `Object.hasOwn`, never a bare index** (`As of 2026-08-23`). The
+  adapter table is an object literal and so inherits `Object.prototype`: `adapters['valueOf']`
+  answered a FUNCTION, so `enforce('valueOf' as Surface, …)` called it with the table as receiver
+  and returned the table typed as a `SurfaceDenial` — truthy, so the public authz dispatcher failed
+  **closed with a denial carrying no code and no reason**. Same hazard, same fix and same reason as
+  the role map below (`Object.hasOwn`, `defineProperty`). An unknown surface is `X_POLICY_SURFACE_UNKNOWN`, whose `fix:`
+  lists `Object.keys(adapters)` so a fifth surface joins it by existing. Pinned in
+  `surfaces.test.ts`.
 - **A derived question about a policy TREE is answered in this PACKAGE, once.** `policyPermissions`
   (in `policy.ts`) and `admitsAnonymous` (in `policy-anonymous.ts`) both walk the combinators
   `policy.ts` declares, so an answer computed in a surface package would drift from them the first

package/README.md

@@ -118,6 +118,12 @@ error shape; allowed returns `undefined`.
 
 Adding a fifth surface means adding an adapter here **and nothing else**.
 
+`enforce(surface, policy, args)` dispatches over that table with `Object.hasOwn`, and a surface
+with no adapter is `X_POLICY_SURFACE_UNKNOWN`. Not a formality: the table is an object literal, so
+it inherits `Object.prototype` — `enforce('valueOf' as Surface, …)` used to call
+`Object.prototype.valueOf` with the table as its receiver and return a truthy value, so an authz
+dispatch failed **closed with a `SurfaceDenial` no caller could read**.
+
 ## Permissions and roles
 
 `definePermissions(['post:publish', ...])` gives a typed set; augmenting
@@ -170,7 +176,8 @@ it never turns an allowed request into a 500.
 
 ## Errors
 
-`X_FORBIDDEN` · `X_POLICY_MISSING` · `X_PERMISSION_UNKNOWN` · `X_ROLE_REDEFINED`
+`X_FORBIDDEN` · `X_POLICY_MISSING` · `X_PERMISSION_UNKNOWN` · `X_POLICY_SURFACE_UNKNOWN` ·
+`X_ROLE_REDEFINED`
 
 A missing policy is a **type** error, not a throw: `ActionDef.policy` is required, so an action
 without one does not compile. `policyMissing()` stays for a declaration site that cannot say it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/policy",
-  "version": "9.0.0",
+  "version": "10.0.0",
   "description": "The one authz rule, evaluated identically in every surface",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "9.0.0"
+    "@ultimat3/core": "10.0.0"
   }
 }

package/src/errors.ts

@@ -3,12 +3,13 @@
 // an action with no policy never compiles. The code and its factory stay published for a
 // declaration site that cannot express the requirement in a type — a config-driven route table,
 // a policy resolved by name — and `policyMissing()` is how such a site says it.
-import { nearestName, registerErrorCodes, UltimateError } from '@ultimat3/core';
+import { nearestName, registerErrorCodes, renderCauseValue, UltimateError } from '@ultimat3/core';
 
 export const POLICY_ERROR_CODES = [
   'X_FORBIDDEN',
   'X_POLICY_MISSING',
   'X_PERMISSION_UNKNOWN',
+  'X_POLICY_SURFACE_UNKNOWN',
   'X_ROLE_REDEFINED',
 ] as const;
 
@@ -18,6 +19,7 @@ export const POLICY_ERROR_TITLES: Readonly<Record<PolicyErrorCode, string>> = {
   X_FORBIDDEN: 'policy denied this actor',
   X_POLICY_MISSING: 'an action was declared without a policy',
   X_PERMISSION_UNKNOWN: 'permission string is not in the permission set',
+  X_POLICY_SURFACE_UNKNOWN: 'enforce() was handed a surface no adapter answers to',
   X_ROLE_REDEFINED: 'two modules define the same role differently',
 };
 
@@ -37,7 +39,6 @@ export class PolicyError extends UltimateError {
       code: init.code,
       cause: init.cause,
       fix: init.fix,
-      docs: `https://ultimate.dev/errors/${init.code}`,
     });
   }
 }
@@ -105,3 +106,22 @@ export const permissionUnknown = (permission: string, known: readonly string[]):
         : `use '${nearest}', the nearest declared permission — or add '${permission}' to definePermissions([...]) if it is genuinely new`,
   });
 };
+
+/**
+ * `enforce()` was handed a surface with no adapter. Thrown rather than denied, because the value
+ * this reports on is one an index would have resolved to something: every object literal inherits
+ * `Object.prototype`, so `adapters['valueOf']` answers a function and `adapters['constructor']`
+ * answers a constructor. Both are truthy, so the dispatcher fails CLOSED and returns a
+ * `SurfaceDenial` no caller can read — a refusal with no code and no reason, which is worse than
+ * the refusal it is standing in for.
+ *
+ * `known` comes from the adapter table itself, so a fifth surface joins this fix line by existing.
+ * The received value goes through `renderCauseValue` and never `${}`: the parameter is typed
+ * `Surface`, and the call site this guard exists for is one no type reached.
+ */
+export const surfaceUnknown = (surface: unknown, known: readonly string[]): PolicyError =>
+  new PolicyError({
+    code: 'X_POLICY_SURFACE_UNKNOWN',
+    cause: `enforce() was handed surface ${renderCauseValue(surface)}, which no policy adapter answers to`,
+    fix: `pass one of ${known.join(', ')} — e.g. enforce('${known[0] ?? 'http'}', policy, args)`,
+  });

package/src/surfaces.ts

@@ -9,7 +9,7 @@
 // The shapes are declared structurally rather than imported: `@ultimat3/http` is a
 // sibling tier, and jobs/realtime/mcp are higher tiers that import this package.
 
-import { forbidden } from './errors';
+import { forbidden, surfaceUnknown } from './errors';
 import { codeOf, type EvaluateArgs, evaluate, type PolicyEvaluation, reasonOf } from './evaluate';
 import type { Policy } from './policy';
 
@@ -121,12 +121,27 @@ const adapters: Readonly<Record<Surface, Adapter>> = {
   mcp: enforceMcp,
 };
 
-/** Dispatcher for code that is generic over surfaces (the action projector). */
+/** The surfaces that have an adapter, derived from the table so the two cannot disagree. */
+const SURFACES: readonly string[] = Object.keys(adapters);
+
+/**
+ * Dispatcher for code that is generic over surfaces (the action projector).
+ *
+ * `Object.hasOwn` and not a truthiness check on `adapters[surface]`: the table is an object
+ * literal, so it inherits `Object.prototype`, and `enforce('valueOf' as Surface, …)` called
+ * `Object.prototype.valueOf` with `adapters` as its receiver — a truthy return, so the call failed
+ * CLOSED, and the adapter table typed as a `SurfaceDenial`, so nothing downstream could say what
+ * was denied. Every in-repo caller passes a literal; a config-driven table, a surface name off the
+ * wire or a JS host does not, and this is a public authz entry point.
+ */
 export const enforce = <I, R = unknown>(
   surface: Surface,
   policy: Policy<I, R>,
   args: EvaluateArgs<I, R>,
-): SurfaceDenial | undefined => adapters[surface](policy, args);
+): SurfaceDenial | undefined => {
+  if (!Object.hasOwn(adapters, surface)) throw surfaceUnknown(surface, SURFACES);
+  return adapters[surface](policy, args);
+};
 
 /** For call sites that would rather throw than branch. Same decision, same reason. */
 export const assertAllowed = <I, R = unknown>(