@ultimat3/policy 24.0.0 → 25.1.0

package/CLAUDE.md

@@ -66,7 +66,7 @@ two differ, and it is why a surface that decides on input alone needs no edit.
   `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
+  `X_FORBIDDEN` through `policyForbidden()`, 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
@@ -111,6 +111,10 @@ two differ, and it is why a surface that decides on input alone needs no edit.
   which this file and `policy-anonymous.ts` both document as ALLOWED, and it states the wrong rule —
   `not` inverts a decision about grants, and whether one was made without an actor is `or`'s to
   report.
+- **A wildcard grant reaches its PREFIX, never its first segment**: `grantMatches` and the grant
+  index both ask core's `grantCovers` (`auth` cuts API keys with it too — same tier, so the one
+  copy lives in core). `billing:invoice:*` never grants `billing:refund:issue`
+  (`grant-wildcard.test.ts`). `resourceOf` is for grouping (`byResource`), never for coverage.
 - **`defineRoles()` merges** and refuses a role two modules define differently
   (`X_ROLE_REDEFINED`, naming both declaration sites). A re-declaration of an *identical*
   role is a no-op, which is what keeps `defineRoles({ ...roleDefinitions(), … })` legal.
@@ -177,7 +181,7 @@ reappearing there is a failing test.
 | `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 })` |
+| `test-kit.ts` | `policyMatrix()` for generated policy tests, and `testActor()` — whose `.actor` is typed `Actor`, never `null`, so it goes straight into `ctxOf({ actor })` |
 
 ## The hot path
 

package/README.md

@@ -151,7 +151,9 @@ dispatch failed **closed with a `SurfaceDenial` no caller could read**.
 `PermissionRegistry` (which `x g policy` generates) makes a typo a compile error, and
 `can()` throws `X_PERMISSION_UNKNOWN` at declaration time either way. Roles are sugar:
 `defineRoles({ owner: { grants: ['post:delete'], inherits: ['editor'] } })` expands
-depth-first to a flat set, cycles included. `post:*` and `*` are supported.
+depth-first to a flat set, cycles included. `post:*` and `*` are supported. A wildcard reaches
+its PREFIX and nothing beside it: `billing:invoice:*` grants `billing:invoice:read`, never
+`billing:refund:issue` (`@ultimat3/core`'s `grantCovers`, the one reading `auth` shares).
 
 `defineRoles()` **merges** into the app's one role map. A second call in a new feature folder
 adds roles; it never deletes the first module's. A role two modules define *differently* is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/policy",
-  "version": "24.0.0",
+  "version": "25.1.0",
   "description": "The one authz rule, evaluated identically in every surface",
   "license": "MIT",
   "type": "module",
@@ -25,13 +25,13 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "24.0.0"
+    "@ultimat3/core": "25.1.0"
   }
 }

package/src/declaration-site.ts

@@ -3,6 +3,9 @@
 
 export const UNKNOWN_SITE = 'unknown site';
 
+/** `\` → `/`: Windows frames and `import.meta.dir` use `\`, and the match must hold on both. */
+const toPosix = (text: string): string => text.replaceAll('\\', '/');
+
 /**
  * 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
@@ -10,19 +13,32 @@ export const UNKNOWN_SITE = 'unknown site';
  * `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}/`;
+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 INTERNAL_NAMES = ['declaration-site', 'permissions', 'roles'] as const;
 
-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 of `stack` that runs outside `ownDir`'s three implementation files. Both sides
+ * are compared `/`-normalised — on Windows neither the frame nor `import.meta.dir` holds a `/`,
+ * so a raw `${dir}/` prefix matched nothing and every site was `callerSite` itself. The frame is
+ * returned as written: its readers (`frameFile`) take a native path.
+ */
+export const pickCallerSite = (stack: string, ownDir: string): string => {
+  const dir = toPosix(ownDir).replace(/\/$/, '');
+  const prefixes = INTERNAL_NAMES.map((name) => `${dir}/${name}.`);
+  const isInternal = (frame: string): boolean => {
+    const posix = toPosix(frame);
+    return prefixes.some((prefix) => {
+      const at = posix.indexOf(prefix);
+      // `permissions.test.ts` shares the prefix; only `<name>.<ext>:<line>` is the file itself.
+      return at !== -1 && /^[cm]?[jt]sx?:\d/.test(posix.slice(at + prefix.length));
+    });
+  };
+  const frames = stack.split('\n').slice(1);
+  const chosen = frames.find((line) => !isInternal(line)) ?? frames[0] ?? '';
+  return chosen.trim() === '' ? UNKNOWN_SITE : chosen.trim();
+};
 
 /**
  * The first frame outside this package. Not a throw: an `Error` is built only to read its stack,
@@ -31,8 +47,5 @@ const isInternal = (frame: string): boolean =>
  */
 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();
+  return stack === undefined ? UNKNOWN_SITE : pickCallerSite(stack, OWN_DIR);
 };

package/src/errors.ts

@@ -98,7 +98,7 @@ export class PolicyError extends UltimateError {
 const BARE_PERMISSION = /^[a-z0-9_-]+:[a-z0-9_-]+$/;
 
 /** `reason` comes from a decision and is always safe to log: no row data, no PII. */
-export const forbidden = (label: string, reason: string): PolicyError =>
+export const policyForbidden = (label: string, reason: string): PolicyError =>
   new PolicyError({
     code: 'X_FORBIDDEN',
     cause: `${label} denied: ${reason}`,
@@ -128,13 +128,13 @@ export class PolicyDenialError extends UltimateError {
 }
 
 /**
- * The error a denial is thrown as: `X_FORBIDDEN` through `forbidden()`, anything else under its
+ * The error a denial is thrown as: `X_FORBIDDEN` through `policyForbidden()`, 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);
+  if (code === 'X_FORBIDDEN') return policyForbidden(label, reason);
   const subject = BARE_PERMISSION.test(label)
     ? `x policy explain ${label} --json`
     : 'x policy list --json';

package/src/grant-index.ts

@@ -2,18 +2,23 @@
 // stays put. Why it earns a file: a live query evaluates policy PER SUBSCRIBER on every change
 // event, and every `can()` clause asks this question — so an unmemoised expansion turned one
 // write on a channel with 10k subscribers into 10k role-graph walks in a single tick.
-import { type Permission, resourceOf } from './permissions';
+import { grantCovers } from '@ultimat3/core';
+import type { Permission } from './permissions';
 import { type Actor, expandRoles, type RoleMap, roleDefinitions, roleMapGeneration } from './roles';
 
 /**
  * The three shapes `grantMatches()` can take, pre-split so a lookup is a `Set.has` instead of a
- * scan: an exact grant, a `<resource>:*` wildcard, and the bare `*`. Equivalent to
+ * scan: an exact grant, a `<prefix>:*` wildcard, and the bare `*`. Equivalent to
  * `actorPermissions(actor).some((grant) => grantMatches(grant, permission))`, per grant kind.
  */
 interface GrantIndex {
   readonly exact: ReadonlySet<string>;
-  /** Resources covered by a `<resource>:*` grant. */
-  readonly wildcards: ReadonlySet<string>;
+  /**
+   * The `<prefix>:*` grants themselves, asked through core's `grantCovers` — a list, not a set of
+   * resources: keyed by the first segment, `billing:invoice:*` answered for `billing:refund:issue`.
+   * An actor holds a handful, so the scan is a few `startsWith`.
+   */
+  readonly wildcards: readonly string[];
   readonly all: boolean;
   /** Deduped and sorted, built once so `actorPermissions()` never sorts per clause. */
   readonly sorted: readonly string[];
@@ -39,11 +44,11 @@ const buildIndex = (actor: Actor, map: RoleMap): GrantIndex => {
   // read that throws where it should have DENIED is the `testActor` defect one layer down.
   const exact = new Set<string>(actor.permissions ?? []);
   for (const grant of expandRoles(actor.roles ?? [], map)) exact.add(grant);
-  const wildcards = new Set<string>();
+  const wildcards: string[] = [];
   let all = false;
   for (const grant of exact) {
     if (grant === '*') all = true;
-    else if (grant.endsWith(':*')) wildcards.add(resourceOf(grant));
+    else if (grant.endsWith(':*')) wildcards.push(grant);
   }
   return { exact, wildcards, all, sorted: [...exact].sort() };
 };
@@ -78,5 +83,5 @@ export const actorHas = (
   if (actor === null) return false;
   const index = indexFor(actor, map);
   if (index.all || index.exact.has(permission)) return true;
-  return index.wildcards.has(resourceOf(permission));
+  return index.wildcards.some((grant) => grantCovers(grant, permission));
 };

package/src/index.ts

@@ -13,13 +13,13 @@ export type { PolicyErrorCode } from './errors';
 export {
   denialError,
   emptyClauseList,
-  forbidden,
   POLICY_BORROWED_ERROR_CODES,
   POLICY_ERROR_CODES,
   POLICY_ERROR_TITLES,
   PolicyDenialError,
   PolicyError,
   permissionUnknown,
+  policyForbidden,
   policyMissing,
   roleRedefined,
 } from './errors';
@@ -59,7 +59,18 @@ export type {
   Recorder,
   TraceEntry,
 } from './policy';
-export { ALLOWED, allow, and, can, denied, deny, not, or, policyPermissions } from './policy';
+export {
+  ALLOWED,
+  allow,
+  and,
+  can,
+  denied,
+  deny,
+  not,
+  or,
+  policyCapability,
+  policyPermissions,
+} from './policy';
 export { admitsAnonymous } from './policy-anonymous';
 export type { PreInputArgs } from './pre-input';
 export { decideBeforeInput, enforceBeforeInput } from './pre-input';

package/src/policy.ts

@@ -197,6 +197,13 @@ export const policyPermissions = <I = unknown, R = unknown>(
   policy: Policy<I, R>,
 ): readonly Permission[] => policy.permissions;
 
+/**
+ * The capability a policy names, for manifests, OpenAPI metadata and the `/_x` dashboard — a
+ * DISPLAY label. What a report MATCHES on is `policyPermissions`; this is the sentence beside it.
+ */
+export const policyCapability = <I = unknown, R = unknown>(policy: Policy<I, R>): string =>
+  policy.label;
+
 const flatten = (children: readonly { readonly permissions: readonly Permission[] }[]) =>
   [...new Set(children.flatMap((child) => child.permissions))].sort();
 

package/src/roles.ts

@@ -3,9 +3,9 @@
 // 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 { grantCovers } from '@ultimat3/core';
 import { callerSite, UNKNOWN_SITE } from './declaration-site';
 import { roleRedefined } from './errors';
-import { resourceOf } from './permissions';
 
 /**
  * An **alias** of core's declaration, and nothing more (`As of 2026-08-19`) — so the actor
@@ -156,12 +156,12 @@ export const expandRoles = (
   return [...out].sort();
 };
 
-/** `post:*` matches every verb on `post`; `*` matches everything. */
-export const grantMatches = (grant: string, wanted: string): boolean => {
-  if (grant === '*' || grant === wanted) return true;
-  if (grant.endsWith(':*')) return resourceOf(grant) === resourceOf(wanted);
-  return false;
-};
+/**
+ * `post:*` matches every name under `post:`; `billing:invoice:*` only those under
+ * `billing:invoice:`; `*` matches everything. Core's `grantCovers` is the one reading — `auth`
+ * cuts an API key to its owner with it too, and the two may not share a copy at tier 2.
+ */
+export const grantMatches = (grant: string, wanted: string): boolean => grantCovers(grant, wanted);
 
 /** For the `/_x` dashboard: which roles would satisfy a permission. */
 export const rolesGranting = (permission: string, map: RoleMap = roleMap): readonly string[] =>

package/src/test-kit.ts

@@ -100,7 +100,7 @@ export const policyMatrix = <I, R = unknown>(
  * arrays, exactly as the actor `@ultimat3/auth` resolves per request is.
  *
  * The return type says the actor is THERE. `NamedActor` keeps `null` for the matrix's signed-out
- * row; a minted actor is never that, and while the type said it might be, `createContext({ actor })`
+ * row; a minted actor is never that, and while the type said it might be, `ctxOf({ actor })`
  * refused it — so every fixture that built a context reached for core's `userActor` instead and a
  * generated test held two idioms for one thing.
  */