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

package/dist/authorization.d.ts

@@ -86,12 +86,6 @@ export interface AuthorizationPolicyProblem {
     code: 'AUTHORIZATION_INVALID_POLICY' | 'AUTHORIZATION_INVALID_SCOPE' | 'AUTHORIZATION_NONDETERMINISTIC';
     message: string;
 }
-/**
- * A **total** structural + scope check on an `AuthorizationPolicyDef` value — for any input,
- * including a hand-tampered Server IR where the policy is the wrong shape entirely (spec15
- * §37). Cross-node reference resolution (does an `authorizationPolicy` id point at a real
- * policy) is `validateGraph`'s job, not this function's.
- */
 export declare function authorizationPolicyProblems(policy: unknown): AuthorizationPolicyProblem[];
 export interface AuthorizationPolicyDependencies {
     /** Field ids the policy's `allow` expression reads off `PRINCIPAL`. */
@@ -147,6 +141,34 @@ export interface AuthorizationCheckResult {
  * - otherwise ALLOW (`allowed`). Both, when present, must pass (conjunction).
  */
 export declare function decideAuthorization(input: AuthorizationCheckInput): AuthorizationCheckResult;
+/**
+ * The closed scope an `AuthorizationPolicyDef.allow` expression is evaluated against. Each
+ * field is a plain record or `null` (anonymous / no resource); a `field` read of a key that
+ * is not present is **security-scope absence**, not an ordinary `undefined` (spec15pt2 §5-§7).
+ */
+export interface AuthorizationPolicyScope {
+    principal: Record<string, unknown> | null | undefined;
+    resource: Record<string, unknown> | null | undefined;
+    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:
+ *
+ * - `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 }`.
+ *
+ * A constant `literal(true)` is `{ ok: true, value: true }` regardless of principal — an
+ * explicitly public policy still admits an anonymous caller (spec15pt2 §13, §14).
+ */
+export declare function evaluateAuthorizationPolicyAllow(allow: unknown, scope: AuthorizationPolicyScope): AuthorizationCheckPart;
 /**
  * The distinct policy ids a graph node references for authorization — for dependency
  * analysis and `validateGraph` reference resolution. Total over malformed input.

package/dist/authorization.js

@@ -26,6 +26,7 @@
  * closed with a structured diagnostic, never a native exception (spec15 §37).
  */
 import { OPERATION, PRINCIPAL, RESOURCE } from './authority.js';
+import { EXPRESSION_KINDS } from './expressions.js';
 // --------------------------------------------------------------------- reserved scope ids
 /**
  * The canonical caller. The **same** reserved id `ActionDef.authorization` uses
@@ -136,6 +137,80 @@ function walkPolicyExpression(expression, refs, nondeterministic, seen = new Set
  * §37). Cross-node reference resolution (does an `authorizationPolicy` id point at a real
  * policy) is `validateGraph`'s job, not this function's.
  */
+/**
+ * spec15pt2 §39-§41 (F2) — a **total** structural check on an `allow` expression tree.
+ * Every node must be a plain object whose `kind` is a real `EXPRESSION_KINDS` member and
+ * whose per-kind required children are present and themselves structurally valid. Returns a
+ * short reason on the first problem, `null` when the tree is well-formed. Never throws.
+ */
+function malformedExpressionReason(expression, seen = new Set()) {
+    if (!isPlainObject(expression))
+        return 'a policy expression node is not an object';
+    if (seen.has(expression))
+        return 'a policy expression contains a cycle';
+    seen.add(expression);
+    const kind = expression.kind;
+    if (typeof kind !== 'string' || !EXPRESSION_KINDS.includes(kind)) {
+        return `unknown expression kind ${JSON.stringify(kind)}`;
+    }
+    const child = (name) => malformedExpressionReason(expression[name], seen);
+    const list = (name) => {
+        const arr = expression[name];
+        if (!Array.isArray(arr))
+            return `${kind}.${name} is not an array`;
+        for (const entry of arr) {
+            const r = malformedExpressionReason(entry, seen);
+            if (r)
+                return r;
+        }
+        return null;
+    };
+    switch (kind) {
+        case 'literal':
+            return 'value' in expression ? null : 'literal has no value';
+        case 'ref':
+            return typeof expression.targetId === 'string' ? null : 'ref has no targetId';
+        case 'field':
+            return (typeof expression.fieldId === 'string' ? null : 'field has no fieldId') ?? child('source');
+        case 'unary':
+            return (typeof expression.operator === 'string' ? null : 'unary has no operator') ?? child('operand');
+        case 'binary':
+            return (typeof expression.operator === 'string' ? null : 'binary has no operator') ?? child('left') ?? child('right');
+        case 'call':
+            return (typeof expression.function === 'string' ? null : 'call has no function') ?? list('arguments');
+        case 'conditional':
+            return child('condition') ?? child('whenTrue') ?? child('whenFalse');
+        case 'object': {
+            const entries = expression.entries;
+            if (!Array.isArray(entries))
+                return 'object has no entries array';
+            for (const e of entries) {
+                if (!isPlainObject(e) || typeof e.fieldId !== 'string')
+                    return 'an object entry is malformed';
+                const r = malformedExpressionReason(e.value, seen);
+                if (r)
+                    return r;
+            }
+            return null;
+        }
+        case 'filter':
+        case 'find':
+        case 'every':
+        case 'some':
+            return child('source') ?? child('predicate');
+        case 'map':
+            return child('source') ?? child('projection');
+        case 'sort':
+        case 'group':
+            return child('source') ?? child('by');
+        case 'flatten':
+            return child('source');
+        case 'expression-ref':
+            return typeof expression.targetId === 'string' ? null : 'expression-ref has no targetId';
+        default:
+            return `unsupported expression kind ${kind}`;
+    }
+}
 export function authorizationPolicyProblems(policy) {
     const problems = [];
     const pid = isPlainObject(policy) ? String(policy.id ?? '<unknown>') : '<unknown>';
@@ -149,6 +224,12 @@ export function authorizationPolicyProblems(policy) {
         });
         return problems;
     }
+    // spec15pt2 F2 — a malformed `allow` tree is rejected structurally here, before compile,
+    // rather than surviving to a native exception at evaluation.
+    const malformed = malformedExpressionReason(policy.allow);
+    if (malformed) {
+        return [{ code: 'AUTHORIZATION_INVALID_POLICY', message: `Authorization policy ${pid} has a malformed 'allow' expression: ${malformed}` }];
+    }
     const refs = new Set();
     const nondeterministic = new Set();
     walkPolicyExpression(policy.allow, refs, nondeterministic);
@@ -253,6 +334,243 @@ export function decideAuthorization(input) {
     }
     return { decision: 'ALLOW', reason: 'allowed' };
 }
+const U = { t: 'u' };
+const E = { t: 'e' };
+const C = (v) => ({ t: 'c', v });
+function asBool(v) {
+    return v === true ? true : v === false ? false : Boolean(v);
+}
+function deepEq(a, b) {
+    if (a === b)
+        return true;
+    try {
+        return JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether an expression tree reads only through `field` / `ref` rooted at PRINCIPAL / RESOURCE. */
+function isSecurityRooted(expression) {
+    if (!isPlainObject(expression))
+        return false;
+    if (expression.kind === 'ref') {
+        const t = String(expression.targetId);
+        return t === AUTHZ_PRINCIPAL_SCOPE || t === AUTHZ_RESOURCE_SCOPE;
+    }
+    if (expression.kind === 'field')
+        return isSecurityRooted(expression.source);
+    return false;
+}
+function evalAuthz(expression, scope, seen) {
+    if (!isPlainObject(expression) || seen.has(expression))
+        return E;
+    seen.add(expression);
+    switch (expression.kind) {
+        case 'literal':
+            return C(expression.value);
+        case 'ref': {
+            const t = String(expression.targetId);
+            if (t === AUTHZ_PRINCIPAL_SCOPE)
+                return C(scope.principal ?? null);
+            if (t === AUTHZ_RESOURCE_SCOPE)
+                return C(scope.resource ?? null);
+            if (t === AUTHZ_OPERATION_SCOPE)
+                return C(scope.operation);
+            return E; // out of the closed scope — validation rejects it; be total
+        }
+        case 'field': {
+            const src = evalAuthz(expression.source, scope, seen);
+            if (src.t === 'e')
+                return E;
+            if (src.t === 'u')
+                return U;
+            const key = String(expression.fieldId);
+            const rooted = isSecurityRooted(expression.source);
+            const obj = src.v;
+            if (obj === null || obj === undefined || typeof obj !== 'object') {
+                return rooted ? U : C(null);
+            }
+            const present = Object.prototype.hasOwnProperty.call(obj, key) && obj[key] !== undefined;
+            if (!present)
+                return rooted ? U : C(null);
+            return C(obj[key]);
+        }
+        case 'unary': {
+            const operand = evalAuthz(expression.operand, scope, seen);
+            if (operand.t !== 'c')
+                return operand; // NOT unknown ⇒ unknown; NOT error ⇒ error (§9, §12)
+            return expression.operator === 'not' ? C(!asBool(operand.v)) : C(-Number(operand.v));
+        }
+        case 'binary': {
+            const op = String(expression.operator);
+            if (op === 'and') {
+                const l = evalAuthz(expression.left, scope, seen);
+                if (l.t === 'c' && !asBool(l.v))
+                    return C(false); // FALSE AND _ ⇒ FALSE (short-circuit-independent)
+                const r = evalAuthz(expression.right, scope, seen);
+                if (l.t === 'e' || r.t === 'e')
+                    return E;
+                if (r.t === 'c' && !asBool(r.v))
+                    return C(false);
+                if (l.t === 'c' && r.t === 'c')
+                    return C(true); // both concrete-true
+                return U;
+            }
+            if (op === 'or') {
+                const l = evalAuthz(expression.left, scope, seen);
+                if (l.t === 'c' && asBool(l.v))
+                    return C(true); // TRUE OR _ ⇒ TRUE
+                const r = evalAuthz(expression.right, scope, seen);
+                if (l.t === 'e' || r.t === 'e')
+                    return E;
+                if (r.t === 'c' && asBool(r.v))
+                    return C(true);
+                if (l.t === 'c' && r.t === 'c')
+                    return C(false); // both concrete-false
+                return U;
+            }
+            const l = evalAuthz(expression.left, scope, seen);
+            const r = evalAuthz(expression.right, scope, seen);
+            if (l.t === 'e' || r.t === 'e')
+                return E;
+            if (l.t === 'u' || r.t === 'u')
+                return U; // any comparison touching absence ⇒ non-satisfied (§8)
+            const a = l.v;
+            const b = r.v;
+            switch (op) {
+                case 'eq':
+                    return C(deepEq(a, b));
+                case 'neq':
+                    return C(!deepEq(a, b));
+                case 'lt':
+                    return C(a < b);
+                case 'lte':
+                    return C(a <= b);
+                case 'gt':
+                    return C(a > b);
+                case 'gte':
+                    return C(a >= b);
+                case 'add':
+                    return C(a + b);
+                case 'subtract':
+                    return C(a - b);
+                case 'multiply':
+                    return C(a * b);
+                case 'divide':
+                    return C(a / b);
+                default:
+                    return E;
+            }
+        }
+        case 'conditional': {
+            const c = evalAuthz(expression.condition, scope, seen);
+            if (c.t !== 'c')
+                return c;
+            return asBool(c.v) ? evalAuthz(expression.whenTrue, scope, seen) : evalAuthz(expression.whenFalse, scope, seen);
+        }
+        case 'object': {
+            const out = {};
+            for (const entry of expression.entries ?? []) {
+                const v = evalAuthz(entry.value, scope, seen);
+                if (v.t === 'e')
+                    return E;
+                if (v.t === 'u')
+                    return U;
+                out[String(entry.fieldId)] = v.v;
+            }
+            return C(out);
+        }
+        case 'call': {
+            const args = [];
+            for (const argument of expression.arguments ?? []) {
+                const v = evalAuthz(argument, scope, seen);
+                if (v.t === 'e')
+                    return E;
+                if (v.t === 'u')
+                    return U; // conservative: any absent input ⇒ non-satisfied (spec15pt2 §57, §85)
+                args.push(v.v);
+            }
+            return applyPolicyBuiltin(String(expression.function), args);
+        }
+        default:
+            return E;
+    }
+}
+function applyPolicyBuiltin(fn, args) {
+    switch (fn) {
+        case 'required':
+            return C(args[0] !== null && args[0] !== undefined);
+        case 'is-empty':
+            return C(args[0] === null || args[0] === undefined || args[0] === '' || (Array.isArray(args[0]) && args[0].length === 0));
+        case 'non-empty':
+            return C(!(args[0] === null || args[0] === undefined || args[0] === '' || (Array.isArray(args[0]) && args[0].length === 0)));
+        case 'length':
+            return C(Array.isArray(args[0]) || typeof args[0] === 'string' ? args[0].length : 0);
+        case 'contains':
+            return C(typeof args[0] === 'string'
+                ? args[0].includes(String(args[1]))
+                : Array.isArray(args[0])
+                    ? args[0].some((x) => deepEq(x, args[1]))
+                    : false);
+        case 'one-of':
+            return C(args.slice(1).some((x) => deepEq(x, args[0])));
+        case 'concat':
+            return C(args.map((x) => (x === null || x === undefined ? '' : String(x))).join(''));
+        case 'to-string':
+            return C(args[0] === null || args[0] === undefined ? '' : String(args[0]));
+        case 'lowercase':
+            return C(String(args[0] ?? '').toLowerCase());
+        case 'trim':
+            return C(String(args[0] ?? '').trim());
+        case 'substring-before': {
+            const s = String(args[0] ?? '');
+            const i = s.indexOf(String(args[1] ?? ''));
+            return C(i < 0 ? '' : s.slice(0, i));
+        }
+        case 'substring-after': {
+            const s = String(args[0] ?? '');
+            const needle = String(args[1] ?? '');
+            const i = s.indexOf(needle);
+            return C(i < 0 ? '' : s.slice(i + needle.length));
+        }
+        case 'coalesce':
+            return C(args.find((x) => x !== null && x !== undefined) ?? null);
+        default:
+            return E; // an unknown / non-deterministic builtin fails closed
+    }
+}
+/**
+ * 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:
+ *
+ * - `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 }`.
+ *
+ * A constant `literal(true)` is `{ ok: true, value: true }` regardless of principal — an
+ * explicitly public policy still admits an anonymous caller (spec15pt2 §13, §14).
+ */
+export function evaluateAuthorizationPolicyAllow(allow, scope) {
+    let result;
+    try {
+        result = evalAuthz(allow, scope, new Set());
+    }
+    catch {
+        return { ok: false };
+    }
+    if (result.t === 'e')
+        return { ok: false };
+    if (result.t === 'u')
+        return { ok: true, value: false };
+    return { ok: true, value: result.v };
+}
 /**
  * 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

@@ -100,6 +100,15 @@ export interface AuthorityCompatibilityKey {
     schemaFingerprint: string;
     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).
+     */
+    authorizationRuntime?: string;
 }
 export declare function authorityCompatibilityKey(parts: AuthorityCompatibilityKey): AuthorityCompatibilityKey;
 /** A stable, comparable string form for storing on a durable work item (spec12 §43). */

package/dist/semantic-identity.js

@@ -138,6 +138,7 @@ export function authorityCompatibilityKey(parts) {
         schemaFingerprint: parts.schemaFingerprint,
         serverContract: parts.serverContract,
         semanticFingerprint: parts.semanticFingerprint,
+        ...(parts.authorizationRuntime !== undefined ? { authorizationRuntime: parts.authorizationRuntime } : {}),
     };
 }
 /** A stable, comparable string form for storing on a durable work item (spec12 §43). */
@@ -155,7 +156,10 @@ export function compareAuthorityCompatibility(a, b) {
         'schemaFingerprint',
         'serverContract',
         'semanticFingerprint',
+        'authorizationRuntime',
     ];
-    const mismatches = fields.filter((field) => a[field] !== b[field]);
+    // `authorizationRuntime` absent on both sides (a non-authorization graph) is a match;
+    // present-vs-absent (alpha.1 stored key vs alpha.2) is a mismatch (spec15pt2 §35, §76).
+    const mismatches = fields.filter((field) => (a[field] ?? null) !== (b[field] ?? null));
     return { compatible: mismatches.length === 0, mismatches };
 }

package/package.json

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