@cynodia/axiom-core 0.15.0-alpha.2 → 0.15.0-alpha.3

package/dist/authorization.d.ts

@@ -21,6 +21,17 @@
  * equivalent to an inline `allow` over `PRINCIPAL`; `ReadPolicyDef` (spec10) remains the
  * row-level read mechanism, unified into query authorization by spec15 Phase D.
  *
+ * **spec15pt3 — one security-absence-aware evaluator for *every* authorization expression.**
+ * `AuthorizationPolicyDef.allow` and the legacy `ActionDef.authorization` expression share
+ * {@link evaluateAuthorizationExpression}: a `field(ref(PRINCIPAL), …)` / `field(ref(RESOURCE),
+ * …)` read of a key the scope object does not carry is **security-scope absence**, not an
+ * ordinary `undefined`, and `neq` / `not` / `or` / any comparison whose truth would depend on
+ * that absence is *not satisfied* — so a missing principal attribute can never manufacture
+ * authority through either surface (spec15pt3 §5, §7, §32). The two modes differ only in
+ * their *final interpretation* (a policy allows on exactly `true`; legacy keeps its historical
+ * truthiness), which `decideAuthorization` applies downstream — never in how absence, boolean
+ * composition or errors propagate.
+ *
  * This module is portable plain data + `Expression` trees; it carries no enforcement (that
  * is Phases C–F). The accessors are **total over any input** so a hand-tampered policy fails
  * closed with a structured diagnostic, never a native exception (spec15 §37).
@@ -122,6 +133,10 @@ export interface AuthorizationCheckInput {
     /**
      * The legacy `ActionDef.authorization` expression outcome, when that expression is present.
      * Its historical truthiness rule is kept: a non-empty array or any truthy value allows.
+     * spec15pt3 — this part MUST be produced by {@link evaluateAuthorizationExpression} (mode
+     * `'legacy-action'`), so `{ ok: true, value: false }` for a decision that depended on a
+     * missing security-scope field: absence reaches this combiner as a plain DENY, never as a
+     * truthy value.
      */
     legacy?: AuthorizationCheckPart;
 }
@@ -152,21 +167,57 @@ export interface AuthorizationPolicyScope {
     operation: string;
 }
 /**
- * spec15pt2 F1 — the **canonical** three-valued `AuthorizationPolicyDef.allow` evaluator,
- * used by every policy-bearing surface (spec15pt2 §33). Returns the `{ ok, value }` shape
- * `decideAuthorization` already consumes:
+ * Which authorization surface an expression is evaluated for (spec15pt3 §32). Both modes
+ * share {@link evaluateAuthorizationExpression}'s security-absence, boolean-composition and
+ * error propagation; they differ only downstream, in `decideAuthorization` — a `'policy'`
+ * result allows on exactly `true`, a `'legacy-action'` result keeps the historical
+ * `ActionDef.authorization` truthiness rule.
+ */
+export type AuthorizationEvaluationMode = 'policy' | 'legacy-action';
+/**
+ * The evaluation context for {@link evaluateAuthorizationExpression}. `'policy'` mode uses the
+ * closed `{ principal, resource, operation }` scope only. `'legacy-action'` mode additionally
+ * honours the historical `ActionDef.authorization` scope, which could also read an ordinary
+ * `StateDef`: {@link resolveExternalRef} resolves such a `ref` through the caller's ordinary
+ * evaluator, and an id it cannot resolve fails **closed** (never silently allows), exactly as
+ * a throwing `runtime.evaluate` did pre-pt3.
+ */
+export interface AuthorizationExpressionContext {
+    principal: Record<string, unknown> | null | undefined;
+    resource?: Record<string, unknown> | null | undefined;
+    operation?: string;
+    resolveExternalRef?: (refId: string) => {
+        found: boolean;
+        value?: unknown;
+    };
+}
+/**
+ * spec15pt3 §32 — the **one** canonical security-absence-aware authorization-expression
+ * evaluator, shared by `AuthorizationPolicyDef.allow` (`mode: 'policy'`) and the legacy
+ * `ActionDef.authorization` expression (`mode: 'legacy-action'`). Returns the `{ ok, value }`
+ * shape `decideAuthorization` consumes:
  *
- * - `allow` reduces to **exactly `true`** (with every required security input present) ⇒
- *   `{ ok: true, value: true }` — the only ALLOW;
- * - `allow` reduces to any other concrete value ⇒ `{ ok: true, value: false }`;
- * - the truth of `allow` depends on a **missing PRINCIPAL / RESOURCE field**
- *   (`AbsentSecurityValue`) ⇒ `{ ok: true, value: false }` — absence never creates authority
- *   through `eq` / `neq` / `not` / `or` (spec15pt2 §8-§12);
- * - an evaluation error (malformed node reaching the runtime, unsupported builtin) ⇒
- *   `{ ok: false }`.
+ * - the expression reduces to a concrete value ⇒ `{ ok: true, value }` — for `'policy'` only
+ *   an exact `true` is ALLOW; for `'legacy-action'` the historical truthiness rule (a truthy
+ *   value / non-empty array) applies, both in `decideAuthorization`;
+ * - its truth depends on a **missing PRINCIPAL / RESOURCE field** ⇒ `{ ok: true, value: false }`
+ *   — absence never creates authority through `eq` / `neq` / `not` / `lt` / `contains` /
+ *   `or` / any composition (spec15pt2 §8-§12, spec15pt3 §11-§16, §79-§82);
+ * - an evaluation error (malformed node reaching the runtime, unsupported builtin, an
+ *   unresolvable legacy `ref`) ⇒ `{ ok: false }` — fail closed, and the error keeps its
+ *   provenance through `not` / `or` so it cannot be negated back to ALLOW (spec15pt3 §84).
  *
  * A constant `literal(true)` is `{ ok: true, value: true }` regardless of principal — an
- * explicitly public policy still admits an anonymous caller (spec15pt2 §13, §14).
+ * explicitly public rule still admits an anonymous caller; the invariant is "missing
+ * referenced security fields cannot create authority", not "anonymous is forbidden"
+ * (spec15pt2 §13, §14; spec15pt3 §17). A `literal` nullish value stays a concrete value,
+ * never security absence (spec15pt3 §58).
+ */
+export declare function evaluateAuthorizationExpression(expression: unknown, context: AuthorizationExpressionContext, mode: AuthorizationEvaluationMode): AuthorizationCheckPart;
+/**
+ * spec15pt2 F1 — the three-valued `AuthorizationPolicyDef.allow` evaluator. A thin, stable
+ * wrapper over {@link evaluateAuthorizationExpression} in `'policy'` mode, kept for every
+ * existing policy-bearing call site (spec15pt2 §33).
  */
 export declare function evaluateAuthorizationPolicyAllow(allow: unknown, scope: AuthorizationPolicyScope): AuthorizationCheckPart;
 /**

package/dist/authorization.js

@@ -21,6 +21,17 @@
  * equivalent to an inline `allow` over `PRINCIPAL`; `ReadPolicyDef` (spec10) remains the
  * row-level read mechanism, unified into query authorization by spec15 Phase D.
  *
+ * **spec15pt3 — one security-absence-aware evaluator for *every* authorization expression.**
+ * `AuthorizationPolicyDef.allow` and the legacy `ActionDef.authorization` expression share
+ * {@link evaluateAuthorizationExpression}: a `field(ref(PRINCIPAL), …)` / `field(ref(RESOURCE),
+ * …)` read of a key the scope object does not carry is **security-scope absence**, not an
+ * ordinary `undefined`, and `neq` / `not` / `or` / any comparison whose truth would depend on
+ * that absence is *not satisfied* — so a missing principal attribute can never manufacture
+ * authority through either surface (spec15pt3 §5, §7, §32). The two modes differ only in
+ * their *final interpretation* (a policy allows on exactly `true`; legacy keeps its historical
+ * truthiness), which `decideAuthorization` applies downstream — never in how absence, boolean
+ * composition or errors propagate.
+ *
  * This module is portable plain data + `Expression` trees; it carries no enforcement (that
  * is Phases C–F). The accessors are **total over any input** so a hand-tampered policy fails
  * closed with a structured diagnostic, never a native exception (spec15 §37).
@@ -377,6 +388,14 @@ function evalAuthz(expression, scope, seen) {
                 return C(scope.resource ?? null);
             if (t === AUTHZ_OPERATION_SCOPE)
                 return C(scope.operation);
+            // spec15pt3 — a legacy `ActionDef.authorization` expression's historical scope also
+            // reaches ordinary `StateDef` refs. Resolve them through the caller's ordinary
+            // evaluator; an unresolved ref fails closed (`E` ⇒ DENY), never silently allows. A
+            // policy expression's scope is closed, so this branch is unreachable in `'policy'` mode.
+            if (scope.mode === 'legacy-action' && scope.resolveExternalRef) {
+                const resolved = scope.resolveExternalRef(t);
+                return resolved.found ? C(resolved.value) : E;
+            }
             return E; // out of the closed scope — validation rejects it; be total
         }
         case 'field': {
@@ -541,26 +560,37 @@ function applyPolicyBuiltin(fn, args) {
     }
 }
 /**
- * spec15pt2 F1 — the **canonical** three-valued `AuthorizationPolicyDef.allow` evaluator,
- * used by every policy-bearing surface (spec15pt2 §33). Returns the `{ ok, value }` shape
- * `decideAuthorization` already consumes:
+ * spec15pt3 §32 — the **one** canonical security-absence-aware authorization-expression
+ * evaluator, shared by `AuthorizationPolicyDef.allow` (`mode: 'policy'`) and the legacy
+ * `ActionDef.authorization` expression (`mode: 'legacy-action'`). Returns the `{ ok, value }`
+ * shape `decideAuthorization` consumes:
  *
- * - `allow` reduces to **exactly `true`** (with every required security input present) ⇒
- *   `{ ok: true, value: true }` — the only ALLOW;
- * - `allow` reduces to any other concrete value ⇒ `{ ok: true, value: false }`;
- * - the truth of `allow` depends on a **missing PRINCIPAL / RESOURCE field**
- *   (`AbsentSecurityValue`) ⇒ `{ ok: true, value: false }` — absence never creates authority
- *   through `eq` / `neq` / `not` / `or` (spec15pt2 §8-§12);
- * - an evaluation error (malformed node reaching the runtime, unsupported builtin) ⇒
- *   `{ ok: false }`.
+ * - the expression reduces to a concrete value ⇒ `{ ok: true, value }` — for `'policy'` only
+ *   an exact `true` is ALLOW; for `'legacy-action'` the historical truthiness rule (a truthy
+ *   value / non-empty array) applies, both in `decideAuthorization`;
+ * - its truth depends on a **missing PRINCIPAL / RESOURCE field** ⇒ `{ ok: true, value: false }`
+ *   — absence never creates authority through `eq` / `neq` / `not` / `lt` / `contains` /
+ *   `or` / any composition (spec15pt2 §8-§12, spec15pt3 §11-§16, §79-§82);
+ * - an evaluation error (malformed node reaching the runtime, unsupported builtin, an
+ *   unresolvable legacy `ref`) ⇒ `{ ok: false }` — fail closed, and the error keeps its
+ *   provenance through `not` / `or` so it cannot be negated back to ALLOW (spec15pt3 §84).
  *
  * A constant `literal(true)` is `{ ok: true, value: true }` regardless of principal — an
- * explicitly public policy still admits an anonymous caller (spec15pt2 §13, §14).
+ * explicitly public rule still admits an anonymous caller; the invariant is "missing
+ * referenced security fields cannot create authority", not "anonymous is forbidden"
+ * (spec15pt2 §13, §14; spec15pt3 §17). A `literal` nullish value stays a concrete value,
+ * never security absence (spec15pt3 §58).
  */
-export function evaluateAuthorizationPolicyAllow(allow, scope) {
+export function evaluateAuthorizationExpression(expression, context, mode) {
     let result;
     try {
-        result = evalAuthz(allow, scope, new Set());
+        result = evalAuthz(expression, {
+            principal: context.principal ?? null,
+            resource: context.resource ?? null,
+            operation: context.operation ?? 'action.invoke',
+            mode,
+            ...(context.resolveExternalRef ? { resolveExternalRef: context.resolveExternalRef } : {}),
+        }, new Set());
     }
     catch {
         return { ok: false };
@@ -571,6 +601,14 @@ export function evaluateAuthorizationPolicyAllow(allow, scope) {
         return { ok: true, value: false };
     return { ok: true, value: result.v };
 }
+/**
+ * spec15pt2 F1 — the three-valued `AuthorizationPolicyDef.allow` evaluator. A thin, stable
+ * wrapper over {@link evaluateAuthorizationExpression} in `'policy'` mode, kept for every
+ * existing policy-bearing call site (spec15pt2 §33).
+ */
+export function evaluateAuthorizationPolicyAllow(allow, scope) {
+    return evaluateAuthorizationExpression(allow, { principal: scope.principal, resource: scope.resource, operation: scope.operation }, 'policy');
+}
 /**
  * The distinct policy ids a graph node references for authorization — for dependency
  * analysis and `validateGraph` reference resolution. Total over malformed input.

package/dist/semantic-identity.d.ts

@@ -101,12 +101,15 @@ export interface AuthorityCompatibilityKey {
     serverContract: string;
     semanticFingerprint: string;
     /**
-     * spec15pt2 §35 — the runtime authorization-evaluator semantics version. `0.15.0-alpha.1`
-     * and `0.15.0-alpha.2` evaluate the *same* Server IR authorization policy differently
-     * (absent-value safety, F1), yet the graph — and therefore `semanticFingerprint` — is
-     * identical. This discriminator, present only when the IR carries authorization
-     * vocabulary, keeps the two builds from silently co-participating in one authority domain.
-     * Absent on a graph with no authorization policy (its evaluation is unchanged).
+     * spec15pt2 §35, spec15pt3 §37-§39 — the runtime authorization-evaluator semantics
+     * version. Successive builds evaluate the *same* Server IR authorization expression
+     * differently — `alpha.1` → `alpha.2` for `AuthorizationPolicyDef.allow` (absent-value
+     * safety, F1), `alpha.2` → `alpha.3` for the legacy `ActionDef.authorization` expression
+     * (F1-legacy) — yet the graph, and therefore `semanticFingerprint`, is identical. This
+     * discriminator, present whenever the IR carries an authorization *decision* (a policy
+     * reference or a legacy `authorization` expression), keeps builds that disagree from
+     * silently co-participating in one authority domain. Absent on a graph with no
+     * authorization decision (its evaluation is unchanged across every build).
      */
     authorizationRuntime?: string;
 }

package/dist/server-ir.d.ts

@@ -141,6 +141,18 @@ export declare function usesAuthorizationVocabulary(ir: {
         instanceAccessPolicy?: unknown;
     }[];
 }): boolean;
+/**
+ * Whether a document carries any legacy `ActionDef.authorization` expression (spec15pt3
+ * §39). This is not 0.15 *vocabulary* — it predates the milestone — but its runtime meaning
+ * changed in `0.15.0-alpha.3` (security-absence-aware evaluation, F1-legacy), so a mixed
+ * `alpha.2` / `alpha.3` cluster over a graph that can exercise it must fail closed. Total
+ * over a tampered IR.
+ */
+export declare function usesLegacyActionAuthorization(ir: {
+    actions?: Record<string, {
+        authorization?: unknown;
+    }>;
+}): boolean;
 /**
  * Authorization vocabulary whose *enforcement* has not shipped yet — the admission gate a
  * build uses to fail closed rather than run a declared policy as a silent no-op (spec4 §4,

package/dist/server-ir.js

@@ -177,6 +177,21 @@ export function usesAuthorizationVocabulary(ir) {
     }
     return false;
 }
+/**
+ * Whether a document carries any legacy `ActionDef.authorization` expression (spec15pt3
+ * §39). This is not 0.15 *vocabulary* — it predates the milestone — but its runtime meaning
+ * changed in `0.15.0-alpha.3` (security-absence-aware evaluation, F1-legacy), so a mixed
+ * `alpha.2` / `alpha.3` cluster over a graph that can exercise it must fail closed. Total
+ * over a tampered IR.
+ */
+export function usesLegacyActionAuthorization(ir) {
+    for (const action of Object.values(ir.actions ?? {})) {
+        if (action && typeof action === 'object' && action.authorization !== undefined) {
+            return true;
+        }
+    }
+    return false;
+}
 /**
  * Authorization vocabulary whose *enforcement* has not shipped yet — the admission gate a
  * build uses to fail closed rather than run a declared policy as a silent no-op (spec4 §4,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cynodia/axiom-core",
-  "version": "0.15.0-alpha.2",
+  "version": "0.15.0-alpha.3",
   "description": "Application Graph, semantic types, locations and validation for Axiom.",
   "license": "MIT",
   "author": "AskTech AS",