@ultimat3/policy 22.9.1 → 22.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/policy",
-  "version": "22.9.1",
+  "version": "22.11.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": "22.9.1"
+    "@ultimat3/core": "22.11.0"
   }
 }

package/src/errors.ts

@@ -4,6 +4,7 @@
 // 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 {
+  deniedCallerFix,
   type ErrorRetry,
   nearestName,
   registerErrorCodes,
@@ -75,11 +76,12 @@ registerErrorRetry(POLICY_ERROR_RETRY);
 export class PolicyError extends UltimateError {
   override readonly name = 'PolicyError';
 
-  constructor(init: { code: PolicyErrorCode; cause: string; fix: string }) {
+  constructor(init: { code: PolicyErrorCode; cause: string; fix: string; callerFix?: string }) {
     super({
       code: init.code,
       cause: init.cause,
       fix: init.fix,
+      ...(init.callerFix === undefined ? {} : { callerFix: init.callerFix }),
     });
   }
 }
@@ -105,6 +107,8 @@ export const forbidden = (label: string, reason: string): PolicyError =>
     fix: BARE_PERMISSION.test(label)
       ? `x policy explain ${label} --json   # shows which clause decided and why`
       : `x policy list --json   # then: x policy explain <permission> --json for the clause that decided`,
+    // The remote caller's half: it holds a credential, not the policy file.
+    callerFix: deniedCallerFix(BARE_PERMISSION.test(label) ? label : undefined),
   });
 
 export const policyMissing = (subject: string): PolicyError =>

package/src/index.ts

@@ -57,6 +57,8 @@ export type {
 } from './policy';
 export { ALLOWED, allow, and, can, denied, deny, not, or, policyPermissions } from './policy';
 export { admitsAnonymous } from './policy-anonymous';
+export type { PreInputArgs } from './pre-input';
+export { decideBeforeInput, enforceBeforeInput } from './pre-input';
 export type { Actor, RoleDef, RoleMap } from './roles';
 export {
   clearRoles,

package/src/policy.ts

@@ -5,6 +5,7 @@ import type { Ctx } from '@ultimat3/core';
 import { emptyClauseList } from './errors';
 import { actorHas } from './grant-index';
 import { assertPermission, type KnownPermission, type Permission } from './permissions';
+import { markPreInput, type PreInputRun, preInputRun } from './pre-input-brand';
 import type { Actor } from './roles';
 
 export type PolicyDecision =
@@ -101,47 +102,65 @@ export const can = <I = unknown, R = unknown>(
 ): Policy<I, R> => {
   assertPermission(permission);
   const label = permission;
-  return {
+  // The actor half of the rule, on its own: it reads nothing the caller sent, which is what lets
+  // the before-input gate (`pre-input.ts`) refuse a caller who may never call this before their
+  // payload is parsed — and a 403 then says nothing about the input schema.
+  const gate = (actor: Actor | null): PolicyDecision | undefined => {
+    if (actor === null) return denied(`no actor for ${label}`, 'X_UNAUTHENTICATED');
+    if (!actorHas(actor, permission as Permission)) return denied(`actor lacks ${label}`);
+    return undefined;
+  };
+  const policy: Policy<I, R> = {
     kind: 'permission',
     label,
     permissions: [permission as Permission],
     children: [],
     run(args, recorder, depth = 0) {
-      if (args.actor === null) {
-        return record(recorder, this, depth, denied(`no actor for ${label}`, 'X_UNAUTHENTICATED'));
-      }
-      if (!actorHas(args.actor, permission as Permission)) {
-        return record(recorder, this, depth, denied(`actor lacks ${label}`));
-      }
+      const refused = gate(args.actor);
+      if (refused !== undefined) return record(recorder, this, depth, refused);
       if (predicate === undefined) return record(recorder, this, depth, ALLOWED);
       return record(recorder, this, depth, asDecision(predicate(args), label));
     },
   };
+  return markPreInput(policy, (args, recorder, depth) => {
+    const refused = gate(args.actor);
+    if (refused !== undefined) return record(recorder, policy, depth, refused);
+    // A predicate reads the input (or the row), so with one the clause is undecided until then.
+    return predicate === undefined ? record(recorder, policy, depth, ALLOWED) : undefined;
+  });
 };
 
 /** Explicitly public. Saying so is required; forgetting a policy is a build error. */
-export const allow = <I = unknown, R = unknown>(label = 'allow'): Policy<I, R> => ({
-  kind: 'allow',
-  label,
-  permissions: [],
-  children: [],
-  run(_args, recorder, depth = 0) {
-    return record(recorder, this, depth, ALLOWED);
-  },
-});
+export const allow = <I = unknown, R = unknown>(label = 'allow'): Policy<I, R> => {
+  const policy: Policy<I, R> = {
+    kind: 'allow',
+    label,
+    permissions: [],
+    children: [],
+    run(_args, recorder, depth = 0) {
+      return record(recorder, this, depth, ALLOWED);
+    },
+  };
+  return markPreInput(policy, (_args, recorder, depth) => record(recorder, policy, depth, ALLOWED));
+};
 
 export const deny = <I = unknown, R = unknown>(
   reason: string,
   code = 'X_FORBIDDEN',
-): Policy<I, R> => ({
-  kind: 'deny',
-  label: `deny(${reason})`,
-  permissions: [],
-  children: [],
-  run(_args, recorder, depth = 0) {
-    return record(recorder, this, depth, denied(reason, code));
-  },
-});
+): Policy<I, R> => {
+  const policy: Policy<I, R> = {
+    kind: 'deny',
+    label: `deny(${reason})`,
+    permissions: [],
+    children: [],
+    run(_args, recorder, depth = 0) {
+      return record(recorder, this, depth, denied(reason, code));
+    },
+  };
+  return markPreInput(policy, (_args, recorder, depth) =>
+    record(recorder, policy, depth, denied(reason, code)),
+  );
+};
 
 /**
  * Every permission a policy tree references, deduped and sorted. This is the list a compliance
@@ -166,15 +185,22 @@ const combined = <I, R>(
   label: string,
   children: readonly Policy<I, R>[],
   decide: (args: PolicyArgs<I, R>, recorder: Recorder | undefined, depth: number) => PolicyDecision,
-): Policy<I, R> => ({
-  kind,
-  label,
-  permissions: flatten(children),
-  children,
-  run(args, recorder, depth = 0) {
-    return record(recorder, this, depth, decide(args, recorder, depth + 1));
-  },
-});
+  pre: PreInputRun,
+): Policy<I, R> => {
+  const policy: Policy<I, R> = {
+    kind,
+    label,
+    permissions: flatten(children),
+    children,
+    run(args, recorder, depth = 0) {
+      return record(recorder, this, depth, decide(args, recorder, depth + 1));
+    },
+  };
+  return markPreInput(policy, (args, recorder, depth) => {
+    const decision = pre(args, recorder, depth + 1);
+    return decision === undefined ? undefined : record(recorder, policy, depth, decision);
+  });
+};
 
 /**
  * First denial wins, and its reason is the reason — short-circuit, left to right.
@@ -198,6 +224,17 @@ export const and = <I, R = unknown>(...policies: readonly Policy<I, R>[]): Polic
       }
       return ALLOWED;
     },
+    // Any clause that denies whatever the input is denies the conjunction whatever the input is —
+    // even past an undecided clause to its left, whose own verdict could only add a denial.
+    (args, recorder, depth) => {
+      let undecided = false;
+      for (const policy of policies) {
+        const decision = preInputRun(policy, args, recorder, depth);
+        if (decision === undefined) undecided = true;
+        else if (!decision.allowed) return decision;
+      }
+      return undecided ? undefined : ALLOWED;
+    },
   );
 };
 
@@ -235,6 +272,25 @@ export const or = <I, R = unknown>(...policies: readonly Policy<I, R>[]): Policy
       }
       return unauthenticated ?? last;
     },
+    // Decided only when some clause allows, or every clause denies; one undecided clause could
+    // still allow, so the disjunction waits for the input.
+    (args, recorder, depth) => {
+      let last: PolicyDecision = denied('no clause allowed this actor');
+      let unauthenticated: PolicyDecision | undefined;
+      let undecided = false;
+      for (const policy of policies) {
+        const decision = preInputRun(policy, args, recorder, depth);
+        if (decision === undefined) {
+          undecided = true;
+          continue;
+        }
+        if (decision.allowed) return ALLOWED;
+        if (decision.code === 'X_UNAUTHENTICATED') unauthenticated = decision;
+        last = decision;
+      }
+      if (undecided) return undefined;
+      return unauthenticated ?? last;
+    },
   );
 };
 
@@ -247,10 +303,20 @@ export const or = <I, R = unknown>(...policies: readonly Policy<I, R>[]): Policy
  * route becomes a public internal route: the mistake is invisible in `and(can(…), not(can(…)))`
  * because the first clause carries the authentication, and it ships the moment someone simplifies.
  */
-export const not = <I, R = unknown>(policy: Policy<I, R>): Policy<I, R> =>
-  combined('not', `not(${policy.label})`, [policy], (args, recorder, depth) => {
-    const decision = policy.run(args, recorder, depth);
+export const not = <I, R = unknown>(policy: Policy<I, R>): Policy<I, R> => {
+  const invert = (decision: PolicyDecision): PolicyDecision => {
     if (decision.allowed) return denied(`not(${policy.label}) — inner clause allowed`);
     if (decision.code === 'X_UNAUTHENTICATED') return decision;
     return ALLOWED;
-  });
+  };
+  return combined(
+    'not',
+    `not(${policy.label})`,
+    [policy],
+    (args, recorder, depth) => invert(policy.run(args, recorder, depth)),
+    (args, recorder, depth) => {
+      const decision = preInputRun(policy, args, recorder, depth);
+      return decision === undefined ? undefined : invert(decision);
+    },
+  );
+};

package/src/pre-input-brand.ts

@@ -0,0 +1,41 @@
+// What each built policy can decide BEFORE its input is parsed, stored beside the policy rather
+// than on it. A WeakMap keyed by the objects `policy.ts` builds, so a foreign `Policy` — one an
+// app assembled by hand, with a `run` this package never saw — has no entry and is answered
+// "depends on input": the before-input gate can only ever DEFER to the full evaluation for it,
+// never decide on its behalf.
+import type { Ctx } from '@ultimat3/core';
+import type { PolicyDecision, Recorder } from './policy';
+import type { Actor } from './roles';
+
+/** Everything a decision before the input parse may read: who is asking, and nothing they sent. */
+export interface PreInputArgs {
+  readonly actor: Actor | null;
+  readonly ctx?: Ctx | undefined;
+}
+
+/**
+ * `undefined` is "this clause cannot be decided without the input" — a predicate would have to
+ * run. A decision is final: the full evaluation of the same clause over ANY input reaches the
+ * same `allowed`.
+ */
+export type PreInputRun = (
+  args: PreInputArgs,
+  recorder: Recorder | undefined,
+  depth: number,
+) => PolicyDecision | undefined;
+
+const PRE_INPUT = new WeakMap<object, PreInputRun>();
+
+/** Called once per policy `policy.ts` builds. Never exported from `src/index.ts`. */
+export const markPreInput = <P extends object>(policy: P, run: PreInputRun): P => {
+  PRE_INPUT.set(policy, run);
+  return policy;
+};
+
+/** The before-input decision of one clause; unbranded clauses depend on input by definition. */
+export const preInputRun = (
+  policy: object,
+  args: PreInputArgs,
+  recorder: Recorder | undefined,
+  depth: number,
+): PolicyDecision | undefined => PRE_INPUT.get(policy)?.(args, recorder, depth);

package/src/pre-input.ts

@@ -0,0 +1,56 @@
+// The before-input gate: the part of a policy that reads only WHO is asking, decided before the
+// caller's payload is parsed. Without it a caller who may never call an operation learns its input
+// schema from the 400 (`X_INPUT_INVALID` lists every field it wanted) instead of getting the 403
+// the policy would give — a staff operation's shape, told to any customer who sends `{}`.
+//
+// Exact, not a heuristic: a clause is decided here only when no predicate would have to run
+// (`can()` without one, `allow()`, `deny()`, and the combinators over them — plus `can(p, pred)`
+// for an actor WITHOUT `p`, whose predicate never runs either). Everything else is "undecided",
+// the surface parses the input, and the full `evaluate()` decides as it always did.
+
+import { ALLOWED, type Policy, type PolicyDecision } from './policy';
+import { type PreInputArgs, preInputRun } from './pre-input-brand';
+import { enforce, type Surface, type SurfaceDenial } from './surfaces';
+
+export type { PreInputArgs } from './pre-input-brand';
+
+/**
+ * What the policy decides for this actor whatever the input is; `undefined` when the answer
+ * depends on the input (or on a row). A policy this package did not build is always `undefined`.
+ */
+export const decideBeforeInput = <I, R>(
+  policy: Policy<I, R>,
+  args: PreInputArgs,
+): PolicyDecision | undefined => preInputRun(policy, args, undefined, 0);
+
+/**
+ * The surface adapter for the gate: a denial shaped exactly like `enforce()`'s for the same
+ * surface, or `undefined` — for an allowance AND for "undecided", because either way the full
+ * evaluation still runs after the parse. A denial goes through `enforce()` itself, so it is traced
+ * and reaches the `DecisionSink` once, like any other; a caller let through here emits nothing,
+ * which keeps one decision event per call.
+ */
+export const enforceBeforeInput = <I, R>(
+  surface: Surface,
+  policy: Policy<I, R>,
+  args: PreInputArgs,
+): SurfaceDenial | undefined => {
+  const decision = decideBeforeInput(policy, args);
+  if (decision === undefined || decision.allowed) return undefined;
+  // The same tree, answering only what it can decide without input. `run` is re-entered by
+  // `evaluate()` with a recorder, so the trace names the clause that refused.
+  const projected: Policy<I, R> = {
+    kind: policy.kind,
+    label: policy.label,
+    permissions: policy.permissions,
+    children: policy.children,
+    run: (runArgs, recorder, depth = 0) =>
+      preInputRun(policy, { actor: runArgs.actor, ctx: runArgs.ctx }, recorder, depth) ?? ALLOWED,
+  };
+  return enforce(surface, projected, {
+    // Never read: every clause the projection answers ignores the input by construction.
+    input: undefined as I,
+    actor: args.actor,
+    ...(args.ctx === undefined ? {} : { ctx: args.ctx }),
+  });
+};