@atlasauth/pca-analyzer 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atlas Authorization
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,110 @@
-# Temporary Holding Version
+# @atlasauth/pca-analyzer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Static analyzability of authority for Proof-Carrying Authority (PCA). PCA can verify one action and prove a quantitative trust-budget bound, but on its own it cannot answer "what can this whole delegated authority ever do?". This package decides that over PCA's predicate/caveat policy (reachability, vacuity, totality, delegation-safety subsumption, disjointness, equivalence, and conformance to a declared intent) without an SMT dependency.
+
+It is a sound, bounded decision procedure in the spirit of AWS Cedar's symbolic compiler (SymCC, arXiv:2403.04651), which decides policy equivalence, subsumption and always-allow/deny with counterexamples. Instead of discharging to Z3, it exploits a finite-distinguishing-value property of PCA's predicate theory and decides by enumeration against the real `evaluatePredicates` from `@atlasauth/pca`.
+
+## Install
+
+```sh
+npm i @atlasauth/pca-analyzer @atlasauth/pca
+```
+
+## Usage
+
+```ts
+import { compilePolicy } from '@atlasauth/pca';
+import { subsumes, intentConformance, reachable } from '@atlasauth/pca-analyzer';
+
+const parent = compilePolicy({ permissions: { stripe: ['refund'] }, limits: { refund: '$500' } });
+const child  = compilePolicy({ permissions: { stripe: ['refund'] }, limits: { refund: '$100' } });
+
+// Delegation safety: a child must not widen its parent.
+subsumes(parent, child).subsumes;   // true
+subsumes(child, parent);            // { subsumes: false, counterexample: { verb: 'stripe.refund', params: { amount: 300 }, ... } }
+
+// Can any input complete this action into an ALLOW? Returns a verified witness.
+reachable(parent, { verb: 'stripe.refund', resource: 'charge:1', params: { amount: 50 } }); // { reachable: true, witness }
+
+// Intent conformance: does the authority stay inside what was meant?
+const policy = compilePolicy({ permissions: { stripe: ['refund'] }, limits: { refund: '$20000' } });
+const r = intentConformance(policy, { verbs: ['stripe.refund'], maxAmount: 10000 });
+// r.conforms === false; r.violations[0].kinds includes 'over-amount'
+```
+
+## Queries
+
+All take a `CompiledPolicy` (from `compilePolicy` / `agent().policy`) or a bare
+`{ predicates, caveats? }`. Every negative/relational verdict carries a concrete counterexample or
+witness.
+
+| Function | Decides |
+|---|---|
+| `reachable(policy, action)` | Can any input complete `(verb, resource, params)` into an ALLOW? Returns a verified `witness`. |
+| `alwaysDenies(policy, verb?)` | Is the policy vacuous (denies everything / everything for `verb`)? |
+| `alwaysAllows(policy, verb)` | Is the policy total for `verb` (admits every action of it)? |
+| `subsumes(a, b)` | Does `a` permit everything `b` does (`admitted(b) ⊆ admitted(a)`)? The delegation-safety check: a child must be subsumed by its parent. |
+| `disjoint(a, b)` | Do the two admit no common action? |
+| `equivalent(a, b)` | Do the two admit exactly the same actions? |
+| `intentConformance(policy, intent)` | Does the policy admit **only** actions inside a declared intent envelope (verbs + resource scopes + amount ceiling)? |
+
+`intentConformance` is a safety check distinct from the runtime trust-budget. It catches the
+*"a $14k renewal under a $10k cap on an approved vendor still violates intent"* class: an action that
+passes the policy's predicates and stays under budget, yet falls outside what the principal intended,
+because the policy's own ceiling is higher than (or absent relative to) the intent cap.
+
+
+## How it decides (the engine)
+
+PCA's `where` conditions are a conjunction of threshold tests (`lt/lte/gt/gte/eq` on numbers),
+membership tests (`eq/ne/in/nin` over finite values) and string `prefix` tests; predicates match on a
+verb allowlist and a resource matcher; the envelope caveats are append-only and conjunctive. The
+admitted region of a policy is therefore a **union of cells** of the arrangement defined by the literals
+that appear in it. The analyzer builds one representative value per cell — every literal and numeric
+threshold, the midpoints between consecutive thresholds, boundary points just outside the range, prefix
+probes, a *fresh* verb / resource / value matching none of the literals, and an *absent* probe for each
+field — then evaluates both policies at every representative with the real evaluator. Because that set
+is distinguishing, agreeing on all representatives implies agreeing on all actions, so the relational
+queries are decided exactly, and any mismatch is a real counterexample. Caveat satisfiability is decided
+separately (`analyzeCaveats`): the context (time window, blast radius, depth, rate) is taken as
+favourably chosen, and the one action-tied caveat, `reversibility_max`, becomes a per-action cap.
+
+## Decided exactly vs. sound-over-approximated
+
+**Decided exactly** (the fragment):
+
+- verb allowlists (`string`, `string[]`, `'*'`);
+- resource matchers that are exact, `'*'`, or a trailing-`*` **prefix**;
+- numeric `where` over `lt/lte/gt/gte/eq` (the interval engine; merges bounds, detects empty
+  conjunctions such as `amount >= 100 AND amount <= 10`);
+- finite-domain `eq/ne/in/nin` and string `prefix` (the set engine — the fresh/absent probes make
+  unbounded string domains decidable for these operators);
+- `exists` (via the absent probe);
+- the conjunctive envelope caveats: `expires`, `not_before` (empty-window detection), `rate`,
+  `max_blast_radius`, `reversibility_max`, `delegation_depth`, `budget_alloc`.
+
+**Sound but over-approximated** — the result is reported with `approximate: true` and **fails safe**
+(never claims *subsumed / always-deny / disjoint / equivalent / conforms* without proof; falls back to
+*not-subsumed / reachable / not-disjoint / not-equivalent / non-conforming*):
+
+- **`re:` regex resource matchers** — a regex relation (containment/overlap) is not decided; the
+  resource dimension cannot be soundly enumerated. (A regex is still evaluated *exactly* against a fully
+  concrete resource in `reachable`, where there is nothing to enumerate.)
+- **cross-field `ref` conditions** — a comparison whose operand is another field (`a != env.b`); the two
+  fields co-vary and are not resolved statically.
+- **whole-`action.params` conditions** (a condition on the container rather than a `.subfield`).
+- **grid overflow** — a representative grid larger than `maxCombinations` (default 200,000); no
+  enumeration is performed.
+
+The soundness contract: a proven verdict (`approximate` falsy) is correct for the fragment above; an
+`approximate` verdict is never a false "safe". 
+
+## Status
+
+Experimental. Verdicts without `approximate: true` are exact for the fragment listed above; the cryptography in `@atlasauth/pca` is unaudited, though this package performs no cryptography itself. An external SMT backend for the regex and cross-field fragments is not included.
+
+Source and issues: https://github.com/Atlas-Authorization/pca
+
+## License
+
+MIT - see LICENSE

package/dist/caveats.d.ts

@@ -0,0 +1,22 @@
+import type { Caveat } from '@atlasauth/pca';
+/**
+ * Static satisfiability of a PCA envelope caveat set (the leaf's cumulative, append-only, conjunctive
+ * caveats). This answers "is there ANY runtime context under which these caveats can all hold?" — the
+ * global gate on whether the authority can ever admit anything.
+ *
+ * The caveats constrain the runtime CaveatContext (now, blast radius, delegation depth, rate window,
+ * reversibility class), not the action's predicate fields. The analyzer treats the context as chosen
+ * favourably (the most permissive the authority could ever encounter) — the right stance for "what can
+ * this authority EVER do". The one caveat tied to the action itself is `reversibility_max`, whose cap
+ * is returned so the per-action check can enforce `class(action) <= cap`.
+ *
+ * Mirrors `envelopeCaveatEvaluator` in @atlasauth/pca (unknown/ malformed => fail closed).
+ */
+export interface CaveatAnalysis {
+    /** Some context satisfies every caveat. */
+    sat: boolean;
+    reason?: string;
+    /** Strictest `reversibility_max` cap as an index into REVERSIBILITY_ORDER, if any caveat sets one. */
+    revCap?: number;
+}
+export declare function analyzeCaveats(caveats: readonly Caveat[] | undefined): CaveatAnalysis;

package/dist/caveats.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeCaveats = analyzeCaveats;
+const types_1 = require("./types");
+function finite(v) {
+    return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+}
+function analyzeCaveats(caveats) {
+    if (!Array.isArray(caveats))
+        return { sat: false, reason: 'caveats are not an array' };
+    let notBeforeMax = -Infinity; // the action can only happen at now >= this
+    let expiresMin = Infinity; // ...and now < this
+    let revCap;
+    for (const cv of caveats) {
+        if (cv === null || typeof cv !== 'object' || typeof cv.type !== 'string') {
+            return { sat: false, reason: 'malformed caveat (not an object with a string type)' };
+        }
+        switch (cv.type) {
+            case 'expires': {
+                const at = finite(cv.at);
+                if (at === undefined)
+                    return { sat: false, reason: 'expires.at is not a finite number' };
+                expiresMin = Math.min(expiresMin, at);
+                break;
+            }
+            case 'not_before': {
+                const at = finite(cv.at);
+                if (at === undefined)
+                    return { sat: false, reason: 'not_before.at is not a finite number' };
+                notBeforeMax = Math.max(notBeforeMax, at);
+                break;
+            }
+            case 'rate': {
+                const max = finite(cv.max);
+                const per = finite(cv.per_secs);
+                if (max === undefined || per === undefined || per <= 0) {
+                    return { sat: false, reason: 'rate caveat requires finite max and per_secs > 0' };
+                }
+                // With zero prior actions the count is 0, so the gate `0 < max` needs max >= 1.
+                if (max < 1)
+                    return { sat: false, reason: `rate.max ${max} < 1 forbids every action` };
+                break;
+            }
+            case 'max_blast_radius': {
+                const max = finite(cv.max);
+                if (max === undefined)
+                    return { sat: false, reason: 'max_blast_radius.max is not a finite number' };
+                // The least blast radius is 0, so this is satisfiable iff max >= 0.
+                if (max < 0)
+                    return { sat: false, reason: 'max_blast_radius.max < 0 forbids every action' };
+                break;
+            }
+            case 'reversibility_max': {
+                const idx = types_1.REVERSIBILITY_ORDER.indexOf(String(cv.class));
+                if (idx < 0)
+                    return { sat: false, reason: `reversibility_max.class '${String(cv.class)}' is unknown` };
+                revCap = revCap === undefined ? idx : Math.min(revCap, idx);
+                break;
+            }
+            case 'delegation_depth': {
+                const max = finite(cv.max);
+                if (max === undefined)
+                    return { sat: false, reason: 'delegation_depth.max is not a finite number' };
+                // The least depth is 0, so this is satisfiable iff max >= 0.
+                if (max < 0)
+                    return { sat: false, reason: 'delegation_depth.max < 0 forbids every action' };
+                break;
+            }
+            case 'budget_alloc': {
+                const lim = finite(cv.limit);
+                if (lim === undefined || lim < 0) {
+                    return { sat: false, reason: 'budget_alloc.limit must be a finite number >= 0' };
+                }
+                break;
+            }
+            default:
+                return { sat: false, reason: `unknown caveat type '${cv.type}' (fail closed)` };
+        }
+    }
+    if (notBeforeMax !== -Infinity && expiresMin !== Infinity && notBeforeMax >= expiresMin) {
+        return {
+            sat: false,
+            reason: `not_before (${notBeforeMax}) >= expires (${expiresMin}): the validity window is empty`,
+        };
+    }
+    return { sat: true, revCap };
+}
+//# sourceMappingURL=caveats.js.map

package/dist/caveats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"caveats.js","sourceRoot":"","sources":["../src/caveats.ts"],"names":[],"mappings":"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"}

package/dist/enumerate.d.ts

@@ -0,0 +1,68 @@
+import type { Caveat, Condition, Predicate } from '@atlasauth/pca';
+import type { AnalyzerAction, PolicyInput } from './types';
+type Cell = unknown;
+/** Default cap on the representative grid size (product of all dimensions). */
+export declare const DEFAULT_MAX_COMBINATIONS = 200000;
+export interface PolicyModel {
+    predicates: Predicate[];
+    caveats: Caveat[];
+    caveatSat: boolean;
+    caveatReason?: string;
+    /** Strictest `reversibility_max` cap (index into REVERSIBILITY_ORDER), if any. */
+    revCap?: number;
+    /** Non-empty when the policy uses features the analyzer cannot decide exactly. */
+    undecidable: string[];
+}
+export declare function normalizePolicy(p: PolicyInput): {
+    predicates: Predicate[];
+    caveats: Caveat[];
+};
+export declare function toModel(p: PolicyInput): PolicyModel;
+export interface Probes {
+    verbs: string[];
+    resources: string[];
+    /** `undefined` means "no reversibility dimension" (no policy sets a `reversibility_max`). */
+    revClasses: (string | undefined)[];
+    fields: {
+        path: string;
+        values: Cell[];
+    }[];
+}
+export interface ProbeInputs {
+    predicateSets: Predicate[][];
+    extraVerbs?: string[];
+    extraResources?: string[];
+    extraFieldConditions?: {
+        path: string;
+        cond: Condition;
+    }[];
+    /** Vary the reversibility class over all three classes (needed when any policy caps reversibility). */
+    varyReversibility: boolean;
+}
+export declare function collectProbes(inputs: ProbeInputs): Probes;
+export declare function productSize(pr: Probes): number;
+export interface Rep {
+    verb: string;
+    resource: string;
+    revClass: string | undefined;
+    /** Field path -> value, excluding absent fields. */
+    assignments: ReadonlyMap<string, unknown>;
+}
+export declare function representatives(pr: Probes): Generator<Rep>;
+/** Does the policy admit this representative action? (predicate match AND static caveat gate.) */
+export declare function admits(model: PolicyModel, rep: Rep): boolean;
+/** Concrete admission of a fully-specified action (used by reachable's fast path; exact). */
+export declare function admitsAction(model: PolicyModel, action: AnalyzerAction): boolean;
+export declare function repToAction(rep: Rep): AnalyzerAction;
+export interface SearchOutcome {
+    /** A representative for which the predicate returned true, if the search stopped on one. */
+    hit?: Rep;
+    /** The grid exceeded the configured bound; no enumeration was performed. */
+    overflow: boolean;
+}
+/**
+ * Walk the representative grid, stopping at the first rep for which `predicate` is true. Returns
+ * `overflow: true` (without walking) when the grid is larger than `max`.
+ */
+export declare function search(pr: Probes, predicate: (rep: Rep) => boolean, max: number): SearchOutcome;
+export {};