@ultimat3/policy 23.0.0 → 24.0.0

package/CLAUDE.md

@@ -62,6 +62,13 @@ two differ, and it is why a surface that decides on input alone needs no edit.
   say it in a type (a config-driven route table, a policy resolved by name). Never default
   to allow.
 - `can()` validates its permission at declaration time, not at request time.
+- **Only `true` or a real decision allows** (`isDecision`, `policy.ts`). A predicate or a
+  `definePolicy` `check` returning anything else — `undefined`, `1`, `{ allowed: 'yes' }` — DENIES;
+  it used to reach `decision.allowed` as a bare `TypeError`, and a truthy `allowed` read as ALLOWED.
+- **A denial keeps its code everywhere.** `assertAllowed` throws `codeOf(decision)` (`denialError`:
+  `X_FORBIDDEN` through `forbidden()`, any other code as a `PolicyDenialError`) and
+  `HttpDenial.status` follows it — 401 for `X_UNAUTHENTICATED`, 403 otherwise. `X_UNAUTHENTICATED`
+  is `@ultimat3/auth`'s (`POLICY_BORROWED_ERROR_CODES`): named here, titled there.
 - **`definePermissions()` merges, and an EMPTY registry is permissive.** It only ever `add`s, so a
   package that declares its own names at import time (`@ultimat3/admin`'s policy bridge) cannot
   clobber an app's set. What it does change is the mode: `isKnownPermission` answers `true` to
@@ -73,6 +80,14 @@ two differ, and it is why a surface that decides on input alone needs no edit.
   process — so a clear in one test file is permanent for every file after it, whose own `import` is a
   cache hit that declares nothing. `restoreRoles` takes the declaration sites too: `defineRoles()` derives
   them from the CALLER's stack, so restoring through it would make `X_ROLE_REDEFINED` name the harness.
+- **Every permission records WHERE it was declared** (`permissionDeclarationSites()`, `As of 2026-10-02`):
+  one stack frame per distinct `definePermissions()` call, through `declaration-site.ts`, the helper
+  `defineRoles()` uses. All sites, not the first — the question asked of it is provenance:
+  `@ultimat3/cli`'s `policy` step flags an app rule whose permission only a package declared
+  (`defineAdmin()`'s `<entity>:read`), `X_PERMISSION_BORROWED`. `restorePermissions(names, sites)`
+  takes them back for the same reason `restoreRoles` does, and the second argument is REQUIRED — a
+  name restored with none has no provable origin and is not judged, so a default would have let a
+  forgotten argument switch the check off.
 - **`and()` and `or()` REFUSE an empty clause list** (`X_POLICY_CLAUSE_EMPTY`, `As of 2026-08-25`),
   at the call that builds them. An empty `and()` found nothing to deny and answered ALLOWED, so
   `and(...requiredCaps.map(can))` over a list that filtered to nothing — a config-driven or
@@ -160,6 +175,7 @@ reappearing there is a failing test.
 | `decisions.ts` | the `DecisionSink` seam — no-op default, one call site, never PII |
 | `surfaces.ts` | http/live/job/mcp adapters — the "one system" proof |
 | `roles.ts` | the role map: merge, conflict, inheritance, wildcards |
+| `declaration-site.ts` | the caller's stack frame a role or permission declaration records |
 | `grant-index.ts` | the per-actor flattened grant set, memoised against the role generation |
 | `test-kit.ts` | `policyMatrix()` for generated policy tests, and `testActor()` — whose `.actor` is typed `Actor`, never `null`, so it goes straight into `createContext({ actor })` |
 

package/README.md

@@ -121,13 +121,24 @@ error shape; allowed returns `undefined`.
 
 | Adapter | Denial shape |
 |---|---|
-| `enforceHttp` | `403` + RFC-9457 fields |
+| `enforceHttp` | RFC-9457 fields, and the status its code means: `401` for `X_UNAUTHENTICATED` (no actor), `403` for every other denial. The title is the code's registered one |
 | `enforceLive` | close frame `4403` |
 | `enforceJob` | `failed`, `retryable: false` — the answer will not change on retry |
 | `enforceMcp` | `isError: true` with readable text |
 
 Adding a fifth surface means adding an adapter here **and nothing else**.
 
+`assertAllowed(policy, args)` is the throwing form, and it throws the code the DECISION carries:
+`X_UNAUTHENTICATED` for no actor, `X_FORBIDDEN` for an actor who may not, and the code a predicate
+chose with `denied(reason, code)` otherwise (`denialError`, a `PolicyDenialError` for a code this
+package does not own).
+
+A predicate — `can(p, fn)` or `definePolicy`'s `check` — allows only by returning `true` or an
+`{ allowed: true }` decision. `false` denies, and so does anything that is neither a boolean nor a
+decision (`undefined` from a forgotten `return`, `1`, `{ allowed: 'yes' }`): with `check` under
+the declared `deny` key, with `can()` as `<permission> predicate returned neither a boolean nor a
+decision`. Never a bare `TypeError`, and never an allow.
+
 `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
@@ -147,6 +158,11 @@ adds roles; it never deletes the first module's. A role two modules define *diff
 `X_ROLE_REDEFINED`, naming both declaration sites — and an identical re-declaration is a no-op,
 so `defineRoles({ ...roleDefinitions(), … })` stays legal.
 
+`permissionDeclarationSites()` answers where each permission was declared — one stack frame per
+distinct `definePermissions()` call. `x verify`'s `policy` step reads it to refuse an app rule
+whose permission only a package declared (`X_PERMISSION_BORROWED`: `defineAdmin()` declares
+`<entity>:read|write|delete`, and a process that never mounts the admin does not).
+
 The flattened grant set is memoised per actor and invalidated the moment the role map changes.
 It is keyed on the actor object, so it lives exactly as long as the request does: `@ultimat3/auth`
 re-reads the user row every request, and a revoked role takes effect on the next one.

package/package.json

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

package/src/declaration-site.ts

@@ -0,0 +1,38 @@
+// Single responsibility: the stack frame of whoever called a declaration — `defineRoles()` or
+// `definePermissions()` — which is the only place the declaring module's name exists by then.
+
+export const UNKNOWN_SITE = 'unknown site';
+
+/**
+ * This package's own source directory — `src/` in the workspace, `dist/` or `node_modules/…` once
+ * installed. A frame is internal by the FILE it runs in (one of the three below), never by a name it spells: matching
+ * `/definePermissions/` against the whole line skipped an app helper named
+ * `definePermissionsForPosts`, and the site became whichever frame came next — a layout, or a
+ * module outside the app root that the `policy` step then read as a package's declaration.
+ */
+const OWN_DIR = `${import.meta.dir}/`;
+
+/** The three implementation files a declaration passes through — a test beside them is a caller. */
+const INTERNAL_FILES = ['declaration-site', 'permissions', 'roles'].map(
+  (name) => `${OWN_DIR}${name}.`,
+);
+
+const isInternal = (frame: string): boolean =>
+  INTERNAL_FILES.some((prefix) => {
+    const at = frame.indexOf(prefix);
+    // `permissions.test.ts` shares the prefix; only `<name>.<ext>:<line>` is the file itself.
+    return at !== -1 && /^[cm]?[jt]sx?:\d/.test(frame.slice(at + prefix.length));
+  });
+
+/**
+ * The first frame outside this package. Not a throw: an `Error` is built only to read its stack,
+ * because `X_ROLE_REDEFINED` is unactionable without both sides of a collision and the policy step
+ * cannot say which module declared a permission without it.
+ */
+export const callerSite = (): string => {
+  const stack = new Error().stack;
+  if (stack === undefined) return UNKNOWN_SITE;
+  const frames = stack.split('\n').slice(1);
+  const chosen = frames.find((line) => !isInternal(line)) ?? frames[0] ?? '';
+  return chosen.trim() === '' ? UNKNOWN_SITE : chosen.trim();
+};

package/src/define.ts

@@ -15,7 +15,7 @@
 
 import type { KnownPermission } from './permissions';
 import type { Policy, PolicyArgs, PolicyDecision } from './policy';
-import { can, denied } from './policy';
+import { can, denied, isDecision } from './policy';
 
 export interface DefinePolicyInput<I, R = unknown> {
   /**
@@ -25,7 +25,8 @@ export interface DefinePolicyInput<I, R = unknown> {
   readonly deny: string;
   /**
    * Pure decision over the actor, the already-loaded input and the already-loaded row.
-   * Returning `false` denies with `deny`; return a `PolicyDecision` for a more specific reason.
+   * Returning `false` — or anything that is neither `true` nor a `PolicyDecision` — denies with
+   * `deny`; return a `PolicyDecision` for a more specific reason.
    *
    * Must not perform I/O — see the file header. A rule that needs a row reads `args.row`,
    * which the surface loaded and passed in; `row` is `null` when the rule decides on input
@@ -63,9 +64,10 @@ export const definePolicy = <I = unknown, R = unknown>(
   const { deny, check } = input;
   if (check === undefined) return can<I, R>(permission);
   return can<I, R>(permission, (args) => {
-    const outcome = check(args);
+    // `unknown`, whatever the type says: only `true` allows and only a real decision speaks for
+    // itself. `undefined` from a forgotten `return` — and anything else — denies with `deny`.
+    const outcome: unknown = check(args);
     if (outcome === true) return true;
-    if (outcome === false) return denied(deny);
-    return outcome;
+    return isDecision(outcome) ? outcome : denied(deny);
   });
 };

package/src/errors.ts

@@ -111,6 +111,47 @@ export const forbidden = (label: string, reason: string): PolicyError =>
     callerFix: deniedCallerFix(BARE_PERMISSION.test(label) ? label : undefined),
   });
 
+/**
+ * The codes a DENIAL may carry that this package does not own. `X_UNAUTHENTICATED` is
+ * `@ultimat3/auth`'s — a sibling tier, so it is named here and titled there — and it is the one
+ * `can()` itself decides with, for a null actor.
+ */
+export const POLICY_BORROWED_ERROR_CODES = ['X_UNAUTHENTICATED'] as const;
+
+/**
+ * A denial thrown under the code its DECISION carries, when that code is not `X_FORBIDDEN`: the
+ * borrowed `X_UNAUTHENTICATED`, or one an app's own predicate chose with `denied(reason, code)`.
+ * Not a `PolicyError` — that class is closed over the codes this package owns.
+ */
+export class PolicyDenialError extends UltimateError {
+  override readonly name = 'PolicyDenialError';
+}
+
+/**
+ * The error a denial is thrown as: `X_FORBIDDEN` through `forbidden()`, anything else under its
+ * own code. `assertAllowed` threw `X_FORBIDDEN` for every denial, so an anonymous caller read
+ * "denied" where every adapter reports `X_UNAUTHENTICATED` — the code a 401 and a sign-in
+ * redirect key on.
+ */
+export const denialError = (label: string, reason: string, code: string): UltimateError => {
+  if (code === 'X_FORBIDDEN') return forbidden(label, reason);
+  const subject = BARE_PERMISSION.test(label)
+    ? `x policy explain ${label} --json`
+    : 'x policy list --json';
+  return new PolicyDenialError({
+    code,
+    cause: `${label} denied: ${reason}`,
+    fix:
+      code === 'X_UNAUTHENTICATED'
+        ? `${subject}   # the rule needs an actor: evaluate it with the request's actor, after the caller has signed in`
+        : `${subject}   # shows which clause decided and why`,
+    callerFix:
+      code === 'X_UNAUTHENTICATED'
+        ? 'sign in, or send a session cookie or an Authorization header, then call again'
+        : deniedCallerFix(BARE_PERMISSION.test(label) ? label : undefined),
+  });
+};
+
 export const policyMissing = (subject: string): PolicyError =>
   new PolicyError({
     code: 'X_POLICY_MISSING',

package/src/index.ts

@@ -11,10 +11,13 @@ export type { DefinePolicyInput } from './define';
 export { definePolicy } from './define';
 export type { PolicyErrorCode } from './errors';
 export {
+  denialError,
   emptyClauseList,
   forbidden,
+  POLICY_BORROWED_ERROR_CODES,
   POLICY_ERROR_CODES,
   POLICY_ERROR_TITLES,
+  PolicyDenialError,
   PolicyError,
   permissionUnknown,
   policyMissing,
@@ -42,6 +45,7 @@ export {
   definePermissions,
   isKnownPermission,
   knownPermissions,
+  permissionDeclarationSites,
   resourceOf,
   restorePermissions,
   verbOf,
@@ -72,6 +76,7 @@ export {
   rolesGranting,
 } from './roles';
 export type {
+  DenialStatus,
   HttpDenial,
   JobDenial,
   LiveDenial,

package/src/permissions.ts

@@ -1,6 +1,7 @@
 // Permissions are `resource:verb` strings. Two layers of protection: the template
 // literal type rejects a malformed string at compile time, and an app that augments
 // `PermissionRegistry` (which `x g policy` does) turns a typo into a type error.
+import { callerSite } from './declaration-site';
 import { permissionUnknown } from './errors';
 
 export type Permission = `${string}:${string}`;
@@ -36,9 +37,27 @@ export interface PermissionSet<P extends Permission> {
 }
 
 const declared = new Set<string>();
+/** Every distinct module that declared each name — a `Map`, because a name is caller data. */
+const sites = new Map<string, Set<string>>();
 
 export const knownPermissions = (): readonly string[] => [...declared].sort();
 
+/**
+ * Where each permission was declared: one stack frame per distinct declaring call, as
+ * `roleDeclarationSites()` answers for roles. ALL of them rather than the first, because the
+ * question asked of it is provenance — the `policy` step flags an app rule that holds only because
+ * a package it imports (`@ultimat3/admin`'s `defineAdmin()`) declared the name, and an app that
+ * declares the same name itself is then not leaning on anything.
+ */
+export const permissionDeclarationSites = (): Readonly<Record<string, readonly string[]>> =>
+  Object.fromEntries([...sites].map(([name, at]) => [name, [...at]]));
+
+const recordSite = (permission: string, site: string): void => {
+  const at = sites.get(permission);
+  if (at === undefined) sites.set(permission, new Set([site]));
+  else at.add(site);
+};
+
 /**
  * Runtime membership check. It stays silent until an app has declared its set,
  * because there is nothing to check against before then — `x verify` is what fails
@@ -59,7 +78,11 @@ export const verbOf = (permission: string): string => permission.split(':')[1] ?
 export const definePermissions = <const P extends readonly Permission[]>(
   list: P,
 ): PermissionSet<P[number]> => {
-  for (const permission of list) declared.add(permission);
+  const site = callerSite();
+  for (const permission of list) {
+    declared.add(permission);
+    recordSite(permission, site);
+  }
   const all = [...list] as P[number][];
   return {
     all,
@@ -74,7 +97,10 @@ export const definePermissions = <const P extends readonly Permission[]>(
 };
 
 /** Test seam; production never forgets a permission it declared. */
-export const clearPermissions = (): void => declared.clear();
+export const clearPermissions = (): void => {
+  declared.clear();
+  sites.clear();
+};
 
 /**
  * `clearPermissions()`'s other half, taking exactly what `knownPermissions()` answers.
@@ -85,8 +111,22 @@ export const clearPermissions = (): void => declared.clear();
  * registers nothing, and `can('admin:read')` throws X_PERMISSION_UNKNOWN for a permission the
  * process really did declare. Only putting the captured set back repairs it; re-importing cannot.
  * Replaces rather than merges — a capture is the whole truth about the process, not an addition.
+ *
+ * `declaredAt` is what `permissionDeclarationSites()` answered, and the same rule `restoreRoles`
+ * states: re-declaring through `definePermissions` would name THIS frame as every permission's
+ * origin. REQUIRED, never defaulted: an omitted argument restored every name with no site, and a
+ * name with no site is one the policy step cannot judge — so a forgotten argument silently turned
+ * `X_PERMISSION_BORROWED` off for the rest of the process. `{}` says "no provenance" on purpose.
  */
-export const restorePermissions = (permissions: readonly string[]): void => {
+export const restorePermissions = (
+  permissions: readonly string[],
+  declaredAt: Readonly<Record<string, readonly string[]>>,
+): void => {
   declared.clear();
-  for (const permission of permissions) declared.add(permission);
+  sites.clear();
+  for (const permission of permissions) {
+    declared.add(permission);
+    const at = Object.hasOwn(declaredAt, permission) ? declaredAt[permission] : undefined;
+    for (const site of at ?? []) recordSite(permission, site);
+  }
 };

package/src/policy.ts

@@ -84,11 +84,33 @@ const record = (
   return decision;
 };
 
-const asDecision = (result: boolean | PolicyDecision, label: string): PolicyDecision => {
-  if (typeof result === 'boolean') {
-    return result ? ALLOWED : denied(`${label} predicate returned false`);
-  }
-  return result;
+/**
+ * A value that IS a decision, by its shape and nothing looser: `allowed` exactly `true`, or
+ * exactly `false` with the reason and code a denial carries. `{ allowed: 'yes' }` is not one —
+ * read as a decision it was truthy, and every surface took it for ALLOWED.
+ */
+export const isDecision = (value: unknown): value is PolicyDecision => {
+  if (typeof value !== 'object' || value === null) return false;
+  const { allowed, reason, code } = value as Readonly<Record<string, unknown>>;
+  return (
+    allowed === true ||
+    (allowed === false && typeof reason === 'string' && typeof code === 'string')
+  );
+};
+
+/**
+ * `true` allows. Everything that is not `true` and not a decision DENIES: a predicate is typed
+ * `boolean | PolicyDecision`, but a JS caller, an `as` and a forgotten `return` all hand back
+ * something else, and passing it through made `decision.allowed` a bare `TypeError` out of `run`.
+ */
+const asDecision = (result: unknown, label: string): PolicyDecision => {
+  if (result === true) return ALLOWED;
+  if (isDecision(result)) return result;
+  return denied(
+    result === false
+      ? `${label} predicate returned false`
+      : `${label} predicate returned neither a boolean nor a decision`,
+  );
 };
 
 /**

package/src/roles.ts

@@ -3,6 +3,7 @@
 // evaluator never has to reason about hierarchy — and a cycle is caught here, once.
 // The per-actor flattening and its memo live in `grant-index.ts`; this file owns the map.
 import type { Actor as CoreActor } from '@ultimat3/core';
+import { callerSite, UNKNOWN_SITE } from './declaration-site';
 import { roleRedefined } from './errors';
 import { resourceOf } from './permissions';
 
@@ -42,19 +43,6 @@ let generation = 0;
  */
 export const roleMapGeneration = (): number => generation;
 
-/** Frames inside this file — never the answer to "who declared this role?". */
-const INTERNAL_FRAME = /declarationSite|defineRoles/;
-
-const declarationSite = (): string => {
-  // Not a throw: the stack is the only place the declaring module's name exists at this point,
-  // and `X_ROLE_REDEFINED` is unactionable without both sides of the collision.
-  const stack = new Error().stack;
-  if (stack === undefined) return 'unknown site';
-  const frames = stack.split('\n').slice(1);
-  const frame = frames.find((line) => !INTERNAL_FRAME.test(line)) ?? frames[0] ?? '';
-  return frame.trim() === '' ? 'unknown site' : frame.trim();
-};
-
 /**
  * A role name is caller data, and an app's role map is a plain object literal — so `map['constructor']`
  * answers the `Object` FUNCTION rather than `undefined`, the `=== undefined` guard at the call site
@@ -100,13 +88,13 @@ const sameDefinition = (left: RoleDef, right: RoleDef): boolean =>
  * and every request 403'd on whichever bundler ordering CI happened to pick.
  */
 export const defineRoles = <const M extends RoleMap>(map: M): M => {
-  const site = declarationSite();
+  const site = callerSite();
   const merged: Record<string, RoleDef> = { ...roleMap };
   const nextSites: Record<string, string> = { ...sites };
   for (const [role, definition] of Object.entries(map)) {
     const existing = own(merged, role);
     if (existing !== undefined && !sameDefinition(existing, definition)) {
-      throw roleRedefined(role, own(sites, role) ?? 'unknown site', site);
+      throw roleRedefined(role, own(sites, role) ?? UNKNOWN_SITE, site);
     }
     put(merged, role, definition);
     put(nextSites, role, own(nextSites, role) ?? site);

package/src/surfaces.ts

@@ -9,19 +9,23 @@
 // 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, surfaceUnknown } from './errors';
+import { describeErrorCode } from '@ultimat3/core';
+import { denialError, surfaceUnknown } from './errors';
 import { codeOf, type EvaluateArgs, evaluate, type PolicyEvaluation, reasonOf } from './evaluate';
 import type { Policy } from './policy';
 
 export type Surface = 'http' | 'live' | 'job' | 'mcp';
 
+/** 401 when the decision says nobody is signed in, 403 for every other denial. */
+export type DenialStatus = 401 | 403;
+
 export interface HttpDenial {
   readonly surface: 'http';
-  readonly status: 403;
+  readonly status: DenialStatus;
   /** RFC-9457 fields `@ultimat3/http` renders verbatim. */
   readonly problem: {
     readonly title: string;
-    readonly status: 403;
+    readonly status: DenialStatus;
     readonly detail: string;
     readonly code: string;
   };
@@ -54,20 +58,32 @@ const reason = (evaluation: PolicyEvaluation): string => reasonOf(evaluation.dec
 
 const code = (evaluation: PolicyEvaluation): string => codeOf(evaluation.decision) ?? 'X_FORBIDDEN';
 
+/**
+ * The status a denial's code means. Only `X_UNAUTHENTICATED` is "come back signed in"; every other
+ * code — `X_FORBIDDEN`, or one an app's predicate chose — is a refusal of this actor. It was a
+ * pinned `403` beside a problem whose own `code` said `X_UNAUTHENTICATED`.
+ */
+const statusOf = (denialCode: string): DenialStatus =>
+  denialCode === 'X_UNAUTHENTICATED' ? 401 : 403;
+
 export const enforceHttp = <I, R = unknown>(
   policy: Policy<I, R>,
   args: EvaluateArgs<I, R>,
 ): HttpDenial | undefined => {
   const evaluation = evaluate(policy, args, { surface: 'http' });
   if (evaluation.allowed) return undefined;
+  const denialCode = code(evaluation);
+  const status = statusOf(denialCode);
   return {
     surface: 'http',
-    status: 403,
+    status,
     problem: {
-      title: 'policy denied this actor',
-      status: 403,
+      // The CODE's registered title, so the document reads as one fact: the owner of the code
+      // wrote it once, and `X_FORBIDDEN`'s own title is this package's.
+      title: describeErrorCode(denialCode).title,
+      status,
       detail: reason(evaluation),
-      code: code(evaluation),
+      code: denialCode,
     },
   };
 };
@@ -143,12 +159,12 @@ export const enforce = <I, R = unknown>(
   return adapters[surface](policy, args);
 };
 
-/** For call sites that would rather throw than branch. Same decision, same reason. */
+/** For call sites that would rather throw than branch. Same decision, same reason, same CODE. */
 export const assertAllowed = <I, R = unknown>(
   policy: Policy<I, R>,
   args: EvaluateArgs<I, R>,
 ): PolicyEvaluation => {
   const evaluation = evaluate(policy, args);
-  if (!evaluation.allowed) throw forbidden(policy.label, reason(evaluation));
+  if (!evaluation.allowed) throw denialError(policy.label, reason(evaluation), code(evaluation));
   return evaluation;
 };