@agenticprimitives/tool-policy 1.0.0-alpha.15 → 1.0.0-alpha.17

package/dist/authority-tier.d.ts

@@ -0,0 +1,62 @@
+import type { Hex } from '@agenticprimitives/types';
+import type { RiskTier } from './types.js';
+/** The three authority tiers. T0 communication (sender-proof only), T1 execution-fast (cached-verdict read),
+ *  T2 execution-orchestrated (full delegation gate + async task). */
+export type AuthorityTier = 'communication' | 'execution-fast' | 'execution-orchestrated';
+/** The execution lane a tier rides. `fast` = the low-overhead warm path (T0/T1); `orchestrated` = the
+ *  heavyweight async task path (T2). */
+export type ExecLane = 'fast' | 'orchestrated';
+/** What a surface DOES below the authority line. Only `read` is ever fast-lane eligible. */
+export type SurfaceEffect = 'read' | 'write' | 'value' | 'admin';
+/** Data sensitivity of a surface. Anything other than `public` is hard-T2 (L3), never fast-lane. */
+export type SurfaceSensitivity = 'public' | 'confidential' | 'sensitive';
+/** The server-owned authority facet of a SurfaceDescriptor — the ONLY source of effect / sensitivity / T1
+ *  eligibility. Authored server-side; never derived from a request. */
+export interface SurfaceAuthorityDescriptor {
+    /** 4-byte skill selector = `keccak256(skill)[:4]`, server-computed (`computeSkillSelector`). */
+    selector: Hex;
+    effect: SurfaceEffect;
+    sensitivity: SurfaceSensitivity;
+    /** Positive, deny-by-default T1 allowlist membership. `false`/absent ⇒ never fast-lane. */
+    t1Eligible: boolean;
+    /** Optional risk tier carried into the verdict for downstream caveat / consent requirements. */
+    risk?: RiskTier;
+}
+/** The authority class the gate acts on. */
+export interface SkillAuthorityClass {
+    tier: AuthorityTier;
+    lane: ExecLane;
+    risk?: RiskTier;
+    /** For T1: the exact selector the cached verdict + per-call caveat pass are scoped to. */
+    toolScope?: Hex[];
+    /** Why the class was assigned (esp. why over-classified / hard-T2) — for the audit trail. */
+    reason?: string;
+}
+/** Classification input. `communication` = a message delivery (T0, no selector). `execution` = a skill/tool
+ *  invocation carrying its server-computed selector. `effect`/`sensitivity` are NEVER accepted here — the
+ *  fabric maps its closed `kind` set to `communication | execution` server-side before calling. */
+export type ClassifyInput = {
+    kind: 'communication';
+} | {
+    kind: 'execution';
+    skillSelector: Hex;
+};
+/** Server-owned registry: lowercased selector → authority descriptor. */
+export type SkillAuthorityRegistry = ReadonlyMap<string, SurfaceAuthorityDescriptor>;
+/** `keccak256(utf8(skill))[:4]` — the server-computed skill selector. The gate computes this ITSELF from the
+ *  invoked skill name; it is never trusted from the client. */
+export declare function computeSkillSelector(skill: string): Hex;
+/** Build a registry from descriptors, keyed by lowercased selector. Validates selector shape (fail-closed). */
+export declare function buildSkillAuthorityRegistry(descriptors: readonly SurfaceAuthorityDescriptor[]): SkillAuthorityRegistry;
+/**
+ * Classify an exchange into its authority tier + execution lane. Pure, server-authoritative, fail-closed.
+ *
+ * - `communication` → T0 fast (sender-proof only; no selector, no delegation).
+ * - `execution` + registry HIT that is `t1Eligible ∧ read ∧ public` → T1 fast.
+ * - `execution` + registry HIT otherwise (write/value/admin, or `sensitivity != public`, or not allowlisted) → T2.
+ * - `execution` + registry MISS → T2 / critical (over-classified).
+ *
+ * `effect`/`sensitivity` are read from the server-owned `registry`, never from the caller.
+ */
+export declare function classifyExchange(input: ClassifyInput, registry: SkillAuthorityRegistry): SkillAuthorityClass;
+//# sourceMappingURL=authority-tier.d.ts.map

package/dist/authority-tier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authority-tier.d.ts","sourceRoot":"","sources":["../src/authority-tier.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;qEACqE;AACrE,MAAM,MAAM,aAAa,GAAG,eAAe,GAAG,gBAAgB,GAAG,wBAAwB,CAAC;AAE1F;wCACwC;AACxC,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,cAAc,CAAC;AAE/C,4FAA4F;AAC5F,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AAEjE,oGAAoG;AACpG,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,cAAc,GAAG,WAAW,CAAC;AAEzE;uEACuE;AACvE,MAAM,WAAW,0BAA0B;IACzC,gGAAgG;IAChG,QAAQ,EAAE,GAAG,CAAC;IACd,MAAM,EAAE,aAAa,CAAC;IACtB,WAAW,EAAE,kBAAkB,CAAC;IAChC,2FAA2F;IAC3F,UAAU,EAAE,OAAO,CAAC;IACpB,gGAAgG;IAChG,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED,4CAA4C;AAC5C,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,0FAA0F;IAC1F,SAAS,CAAC,EAAE,GAAG,EAAE,CAAC;IAClB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;mGAEmG;AACnG,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,aAAa,EAAE,GAAG,CAAA;CAAE,CAAC;AAE9C,yEAAyE;AACzE,MAAM,MAAM,sBAAsB,GAAG,WAAW,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;AAIrF;+DAC+D;AAC/D,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAKvD;AAED,+GAA+G;AAC/G,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,SAAS,0BAA0B,EAAE,GACjD,sBAAsB,CASxB;AAUD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,sBAAsB,GAC/B,mBAAmB,CAqBrB"}

package/dist/authority-tier.js

@@ -0,0 +1,78 @@
+// Authority-tier classification — the ONE server-authoritative source that BOTH the fabric ingress gate and
+// the mcp-runtime delegation gate read to decide which execution LANE an exchange rides (spec 316 §3a/§(c),
+// Blocker 2 + L3). One table, two gates.
+//
+// Invariants (all fail-closed):
+//  - The tier is derived SERVER-SIDE from the skill SELECTOR looked up in a server-owned registry — NEVER
+//    from a client-supplied effect/sensitivity/kind. `classifyExchange` therefore accepts only a
+//    discriminated `{communication | execution+selector}` input; effect/sensitivity live in the registry.
+//  - Over-classify by default: a registry MISS returns the MOST RESTRICTIVE class (execution-orchestrated /
+//    critical), never a permissive default (ADR-0013 fail-closed; mirrors smart-agent `risk-tiers`
+//    "miss → the heavier tier, never the lighter").
+//  - L3 hard-T2: a surface with `sensitivity != 'public'` is NEVER fast-lane (T1) eligible regardless of its
+//    effect flag. T1 eligibility is a positive, deny-by-default allowlist AND `effect === 'read'` AND
+//    `sensitivity === 'public'`.
+//  - Communication (T0) is the delivery of a message; it carries no skill selector and can never reach an
+//    execution handler, so a mislabeled communication exchange is at most delivered, never executed.
+import { keccak_256 } from '@noble/hashes/sha3.js';
+const SELECTOR_RE = /^0x[0-9a-fA-F]{8}$/;
+/** `keccak256(utf8(skill))[:4]` — the server-computed skill selector. The gate computes this ITSELF from the
+ *  invoked skill name; it is never trusted from the client. */
+export function computeSkillSelector(skill) {
+    const out = keccak_256(new TextEncoder().encode(skill));
+    let s = '0x';
+    for (let i = 0; i < 4; i++)
+        s += out[i].toString(16).padStart(2, '0');
+    return s;
+}
+/** Build a registry from descriptors, keyed by lowercased selector. Validates selector shape (fail-closed). */
+export function buildSkillAuthorityRegistry(descriptors) {
+    const m = new Map();
+    for (const d of descriptors) {
+        if (!SELECTOR_RE.test(d.selector)) {
+            throw new Error(`buildSkillAuthorityRegistry: selector must be 4 bytes (0x + 8 hex); got "${d.selector}"`);
+        }
+        m.set(d.selector.toLowerCase(), d);
+    }
+    return m;
+}
+/** The MOST RESTRICTIVE class — the fail-closed default for a registry miss. */
+const OVER_CLASSIFIED = Object.freeze({
+    tier: 'execution-orchestrated',
+    lane: 'orchestrated',
+    risk: 'critical',
+    reason: 'registry-miss:over-classified',
+});
+/**
+ * Classify an exchange into its authority tier + execution lane. Pure, server-authoritative, fail-closed.
+ *
+ * - `communication` → T0 fast (sender-proof only; no selector, no delegation).
+ * - `execution` + registry HIT that is `t1Eligible ∧ read ∧ public` → T1 fast.
+ * - `execution` + registry HIT otherwise (write/value/admin, or `sensitivity != public`, or not allowlisted) → T2.
+ * - `execution` + registry MISS → T2 / critical (over-classified).
+ *
+ * `effect`/`sensitivity` are read from the server-owned `registry`, never from the caller.
+ */
+export function classifyExchange(input, registry) {
+    if (input.kind === 'communication') {
+        return { tier: 'communication', lane: 'fast' };
+    }
+    const d = registry.get(input.skillSelector.toLowerCase());
+    if (!d)
+        return { ...OVER_CLASSIFIED };
+    const fastEligible = d.t1Eligible && d.effect === 'read' && d.sensitivity === 'public';
+    if (fastEligible) {
+        return { tier: 'execution-fast', lane: 'fast', risk: d.risk, toolScope: [d.selector.toLowerCase()] };
+    }
+    return {
+        tier: 'execution-orchestrated',
+        lane: 'orchestrated',
+        risk: d.risk ?? 'critical',
+        reason: d.sensitivity !== 'public'
+            ? 'hard-T2:sensitivity'
+            : d.effect !== 'read'
+                ? 'hard-T2:effect'
+                : 'hard-T2:not-allowlisted',
+    };
+}
+//# sourceMappingURL=authority-tier.js.map

package/dist/authority-tier.js.map

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

package/dist/index.d.ts

@@ -4,5 +4,7 @@ export { evaluatePolicy } from './decision.js';
 export { clampTtlForRiskTier, requiredCaveatsForRiskTier, evaluateThresholdPolicy, RISK_TIER_REQUIREMENTS, } from './risk-tier.js';
 export { lintClassification } from './lint.js';
 export { ThresholdTier } from './types.js';
+export { classifyExchange, computeSkillSelector, buildSkillAuthorityRegistry, } from './authority-tier.js';
+export type { AuthorityTier, ExecLane, SurfaceEffect, SurfaceSensitivity, SurfaceAuthorityDescriptor, SkillAuthorityClass, ClassifyInput, SkillAuthorityRegistry, } from './authority-tier.js';
 export type { Address, Hex, RiskTier, ToolClassification, ExactCallPolicy, CaveatLike, DelegationLike, CaveatContext, PolicyContext, PolicyDecision, ThresholdPolicyDecision, LintResult, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,mBAAmB,EACnB,0BAA0B,EAC1B,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,YAAY,EACV,OAAO,EACP,GAAG,EACH,QAAQ,EACR,kBAAkB,EAClB,eAAe,EACf,UAAU,EACV,cAAc,EACd,aAAa,EACb,aAAa,EACb,cAAc,EACd,uBAAuB,EACvB,UAAU,GACX,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,mBAAmB,EACnB,0BAA0B,EAC1B,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAI3C,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,aAAa,EACb,QAAQ,EACR,aAAa,EACb,kBAAkB,EAClB,0BAA0B,EAC1B,mBAAmB,EACnB,aAAa,EACb,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAE7B,YAAY,EACV,OAAO,EACP,GAAG,EACH,QAAQ,EACR,kBAAkB,EAClB,eAAe,EACf,UAAU,EACV,cAAc,EACd,aAAa,EACb,aAAa,EACb,cAAc,EACd,uBAAuB,EACvB,UAAU,GACX,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -13,4 +13,7 @@ export { clampTtlForRiskTier, requiredCaveatsForRiskTier, evaluateThresholdPolic
 export { lintClassification } from './lint.js';
 // ThresholdTier is an enum (value export, not type-only).
 export { ThresholdTier } from './types.js';
+// Authority-tier classification (spec 316 §3a/§(c)) — the ONE server-authoritative source the fabric
+// ingress gate and the mcp-runtime delegation gate both read to pick the execution LANE. Fail-closed.
+export { classifyExchange, computeSkillSelector, buildSkillAuthorityRegistry, } from './authority-tier.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,EAAE;AACF,4DAA4D;AAC5D,EAAE;AACF,2EAA2E;AAC3E,4EAA4E;AAC5E,6EAA6E;AAC7E,YAAY;AAEZ,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,mBAAmB,EACnB,0BAA0B,EAC1B,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,0DAA0D;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,EAAE;AACF,4DAA4D;AAC5D,EAAE;AACF,2EAA2E;AAC3E,4EAA4E;AAC5E,6EAA6E;AAC7E,YAAY;AAEZ,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,mBAAmB,EACnB,0BAA0B,EAC1B,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,0DAA0D;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,qGAAqG;AACrG,sGAAsG;AACtG,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,qBAAqB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticprimitives/tool-policy",
-  "version": "1.0.0-alpha.15",
+  "version": "1.0.0-alpha.17",
   "description": "Protocol-agnostic classification, risk tiers, and exact-call policy. Consumable by MCP, A2A, LangGraph, and Vercel AI tool runtimes.",
   "license": "MIT",
   "repository": {
@@ -38,7 +38,7 @@
     "@noble/hashes": "^2.2.0"
   },
   "peerDependencies": {
-    "@agenticprimitives/types": "1.0.0-alpha.15"
+    "@agenticprimitives/types": "1.0.0-alpha.17"
   },
   "devDependencies": {
     "@types/node": "^22.7.0",