@ultimat3/policy 24.0.0 → 25.0.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
@@ -177,7 +177,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/policy",
-  "version": "24.0.0",
+  "version": "25.0.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.0.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/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/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.
  */