@highflame/policy 2.2.45 → 2.4.0

package/dist/service-schemas.gen.js

@@ -136,6 +136,18 @@ namespace AgentOps {
         context: ProvisionSandboxContext
     };
 
+    /// The acting agent's lifecycle and IdP provenance, projected as
+    /// \`context.actor\`. Same four attributes, names and types as the legacy
+    /// members on PrincipalContext (which keeps them). Every member is optional
+    /// and the record is absent when none is supplied; absence means unknown,
+    /// not "active".
+    type ActorContext = {
+        "status"?: String,             // Agent lifecycle: "discovered" | "pending" | "active"
+        "origin"?: String,             // "native" | "entra" | "okta" | ...
+        "idp_iss"?: String,            // Upstream IdP issuer for IdP-registered agents
+        "idp_parent"?: String,         // Upstream parent object (e.g. Entra blueprint app id)
+    };
+
     // =========================================================================
     // Context Types (Action-Specific)
     // =========================================================================
@@ -176,6 +188,10 @@ namespace AgentOps {
         "act_iss"?: String,            // Issuer of the actor claim
         "mission_id"?: String,         // Correlates one delegation tree
         "grant_type"?: String,         // How the token was obtained (e.g. "api_key")
+        "status"?: String,             // Agent lifecycle: "discovered" | "pending" | "active"; absent = unknown, not active
+        "origin"?: String,             // Where the identity came from: "native" | "entra" | "okta" | ...
+        "idp_iss"?: String,            // Upstream IdP issuer for IdP-registered agents
+        "idp_parent"?: String,         // Upstream parent object (e.g. Entra blueprint app id)
     };
 
     /// Context for the process_response action.
@@ -193,6 +209,7 @@ namespace AgentOps {
         "privilege_scope"?: Set<String>,
         "identity_type"?: String,        // Principal identity class: "human" | "agent" | "service" | "mcp_server"
         "principal"?: PrincipalContext, // ZeroID NHI identity block; absent when the token carries no NHI claims
+        "actor"?: ActorContext,         // Acting agent attributes (status/origin/IdP provenance); absent when none supplied
         // Core metadata (required)
         "request_id": String,
         "timestamp": Long,
@@ -388,6 +405,7 @@ namespace AgentOps {
         "privilege_scope"?: Set<String>,
         "identity_type"?: String,
         "principal"?: PrincipalContext, // ZeroID NHI identity block; absent when the token carries no NHI claims
+        "actor"?: ActorContext,         // Acting agent attributes (status/origin/IdP provenance); absent when none supplied
         // Core metadata (required)
         "request_id": String,
         "timestamp": Long,
@@ -599,6 +617,7 @@ namespace AgentOps {
         "privilege_scope"?: Set<String>,
         "identity_type"?: String,
         "principal"?: PrincipalContext, // ZeroID NHI identity block; absent when the token carries no NHI claims
+        "actor"?: ActorContext,         // Acting agent attributes (status/origin/IdP provenance); absent when none supplied
         // Core metadata (required)
         "request_id": String,
         "timestamp": Long,
@@ -707,6 +726,7 @@ namespace AgentOps {
         "privilege_scope"?: Set<String>,
         "identity_type"?: String,
         "principal"?: PrincipalContext, // ZeroID NHI identity block; absent when the token carries no NHI claims
+        "actor"?: ActorContext,         // Acting agent attributes (status/origin/IdP provenance); absent when none supplied
         // Core metadata (required)
         "request_id": String,
         "timestamp": Long,
@@ -819,6 +839,7 @@ namespace AgentOps {
         "privilege_scope"?: Set<String>,
         "identity_type"?: String,
         "principal"?: PrincipalContext, // ZeroID NHI identity block; absent when the token carries no NHI claims
+        "actor"?: ActorContext,         // Acting agent attributes (status/origin/IdP provenance); absent when none supplied
         // Core metadata (required)
         "request_id": String,
         "timestamp": Long,
@@ -952,6 +973,7 @@ namespace AgentOps {
         "privilege_scope"?: Set<String>,
         "identity_type"?: String,        // Principal identity class: "human" | "agent" | "service" | "mcp_server"
         "principal"?: PrincipalContext, // ZeroID NHI identity block; absent when the token carries no NHI claims
+        "actor"?: ActorContext,         // Acting agent attributes (status/origin/IdP provenance); absent when none supplied
         "agent_trust_level"?: String,    // "untrusted" | "low" | "verified" | "trusted"
 
         // Core metadata (required)
@@ -1072,6 +1094,8 @@ action call_tool appliesTo {
     // Identity (AARM R6 / CAP-IDN-011) — projected from the principal's token; optional.
     role?: String,
     privilege_scope?: Set<String>,
+    "principal"?: PrincipalContext,   // ZeroID NHI identity block; absent when the token carries no NHI claims
+    "actor"?: ActorContext,           // Acting agent status/origin/IdP provenance; absent when none supplied
     // --- Content ---
     content: String,                  // Raw content being scanned
 
@@ -1194,6 +1218,8 @@ action connect_server appliesTo {
     // Identity (AARM R6 / CAP-IDN-011) — projected from the principal's token; optional.
     role?: String,
     privilege_scope?: Set<String>,
+    "principal"?: PrincipalContext,   // ZeroID NHI identity block; absent when the token carries no NHI claims
+    "actor"?: ActorContext,           // Acting agent status/origin/IdP provenance; absent when none supplied
     content?: String,                 // Server config content (if available)
     mcp_server?: String,
 
@@ -1291,6 +1317,8 @@ action list appliesTo {
     // Identity (AARM R6 / CAP-IDN-011) — projected from the principal's token; optional.
     role?: String,
     privilege_scope?: Set<String>,
+    "principal"?: PrincipalContext,   // ZeroID NHI identity block; absent when the token carries no NHI claims
+    "actor"?: ActorContext,           // Acting agent status/origin/IdP provenance; absent when none supplied
 
     // --- Content ---
     // The enumerated item's description. Optional: a tool may declare none,
@@ -1365,6 +1393,43 @@ action list appliesTo {
   },
 };
 
+// ZeroID NHI principal block, projected by Shield as \`context.principal\` when
+// the caller's token carries NHI claims. Same shape as the Guardrails and
+// AgentOps PrincipalContext, so one policy text reads the same keys on every
+// product. Every member is optional except \`delegation_depth\` (always emitted;
+// 0 for a direct token). The record is absent, not empty, when the request
+// carries no NHI claims, so \`context has principal\` is false.
+type PrincipalContext = {
+  "identity_type"?: String,      // "human" | "agent" | "service" | "mcp_server"
+  "sub_type"?: String,           // Identity subtype (e.g. "coding_agent")
+  "trust_level"?: String,        // "first_party" | "verified" | "unverified"
+  "framework"?: String,          // Agent framework (e.g. "langchain")
+  "publisher"?: String,          // Agent publisher
+  "capabilities"?: Set<String>,  // Capabilities granted to the identity
+  "scopes"?: Set<String>,        // OAuth scopes carried by the token
+  "delegation_depth": Long,      // Delegation hops; 0 for a direct token
+  "act_sub"?: String,            // RFC 8693 actor: the accountable human
+  "act_iss"?: String,            // Issuer of the actor claim
+  "mission_id"?: String,         // Correlates one delegation tree
+  "grant_type"?: String,         // How the token was obtained (e.g. "api_key")
+  "status"?: String,             // Agent lifecycle: "discovered" | "pending" | "active"; absent = unknown, not active
+  "origin"?: String,             // Where the identity came from: "native" | "entra" | "okta" | ...
+  "idp_iss"?: String,            // Upstream IdP issuer for IdP-registered agents
+  "idp_parent"?: String,         // Upstream parent object (e.g. Entra blueprint app id)
+};
+
+// The acting agent's lifecycle and IdP provenance, projected as
+// \`context.actor\`. Firehog traffic is evaluated in this namespace, which is
+// where agents registered in Okta or Entra reach Shield (ADR 0041 D5,
+// ADR 0042). Every member is optional and the record is absent when none is
+// supplied; absence means unknown, not "active".
+type ActorContext = {
+  "status"?: String,             // Agent lifecycle: "discovered" | "pending" | "active"
+  "origin"?: String,             // "native" | "entra" | "okta" | ...
+  "idp_iss"?: String,            // Upstream IdP issuer for IdP-registered agents
+  "idp_parent"?: String,         // Upstream parent object (e.g. Entra blueprint app id)
+};
+
 // Shared content-inspection context.
 //
 // Prompts and responses are inspected by the same detector pipeline and so
@@ -1375,6 +1440,8 @@ type ContentInspectionContext = {
     // Identity (AARM R6 / CAP-IDN-011) — projected from the principal's token; optional.
     role?: String,
     privilege_scope?: Set<String>,
+    "principal"?: PrincipalContext,   // ZeroID NHI identity block; absent when the token carries no NHI claims
+    "actor"?: ActorContext,           // Acting agent status/origin/IdP provenance; absent when none supplied
     content: String,
     mcp_server?: String,
 
@@ -1486,6 +1553,8 @@ action read_file appliesTo {
     // Identity (AARM R6 / CAP-IDN-011) — projected from the principal's token; optional.
     role?: String,
     privilege_scope?: Set<String>,
+    "principal"?: PrincipalContext,   // ZeroID NHI identity block; absent when the token carries no NHI claims
+    "actor"?: ActorContext,           // Acting agent status/origin/IdP provenance; absent when none supplied
     content: String,
     mcp_server?: String,
 
@@ -1553,6 +1622,8 @@ action write_file appliesTo {
     // Identity (AARM R6 / CAP-IDN-011) — projected from the principal's token; optional.
     role?: String,
     privilege_scope?: Set<String>,
+    "principal"?: PrincipalContext,   // ZeroID NHI identity block; absent when the token carries no NHI claims
+    "actor"?: ActorContext,           // Acting agent status/origin/IdP provenance; absent when none supplied
     content: String,
     mcp_server?: String,
 
@@ -1761,6 +1832,22 @@ namespace Guardrails {
         "act_iss"?: String,            // Issuer of the actor claim
         "mission_id"?: String,         // Correlates one delegation tree
         "grant_type"?: String,         // How the token was obtained (e.g. "api_key")
+        "status"?: String,             // Agent lifecycle: "discovered" | "pending" | "active"; absent = unknown, not active
+        "origin"?: String,             // Where the identity came from: "native" | "entra" | "okta" | ...
+        "idp_iss"?: String,            // Upstream IdP issuer for IdP-registered agents
+        "idp_parent"?: String,         // Upstream parent object (e.g. Entra blueprint app id)
+    };
+
+    /// The acting agent's lifecycle and IdP provenance, projected as
+    /// \`context.actor\`. Same four attributes, names and types as the legacy
+    /// members on PrincipalContext (which keeps them). Every member is optional
+    /// and the record is absent when none is supplied; absence means unknown,
+    /// not "active".
+    type ActorContext = {
+        "status"?: String,             // Agent lifecycle: "discovered" | "pending" | "active"
+        "origin"?: String,             // "native" | "entra" | "okta" | ...
+        "idp_iss"?: String,            // Upstream IdP issuer for IdP-registered agents
+        "idp_parent"?: String,         // Upstream parent object (e.g. Entra blueprint app id)
     };
 
     /// Context for the process_response action.
@@ -1780,6 +1867,7 @@ namespace Guardrails {
         "privilege_scope"?: Set<String>,
         "identity_type"?: String,        // Principal identity class: "human" | "agent" | "service"
         "principal"?: PrincipalContext, // ZeroID NHI identity block; absent when the token carries no NHI claims
+        "actor"?: ActorContext,         // Acting agent attributes (status/origin/IdP provenance); absent when none supplied
         // Core metadata (required)
         "request_id": String,
         "timestamp": Long,
@@ -1932,6 +2020,7 @@ namespace Guardrails {
         "privilege_scope"?: Set<String>,
         "identity_type"?: String,        // Principal identity class: "human" | "agent" | "service"
         "principal"?: PrincipalContext, // ZeroID NHI identity block; absent when the token carries no NHI claims
+        "actor"?: ActorContext,         // Acting agent attributes (status/origin/IdP provenance); absent when none supplied
         // Core metadata (required)
         "request_id": String,
         "timestamp": Long,
@@ -2128,6 +2217,7 @@ namespace Guardrails {
         "privilege_scope"?: Set<String>,
         "identity_type"?: String,        // Principal identity class: "human" | "agent" | "service"
         "principal"?: PrincipalContext, // ZeroID NHI identity block; absent when the token carries no NHI claims
+        "actor"?: ActorContext,         // Acting agent attributes (status/origin/IdP provenance); absent when none supplied
         // Core metadata (required)
         "request_id": String,
         "timestamp": Long,
@@ -2201,6 +2291,7 @@ namespace Guardrails {
         "privilege_scope"?: Set<String>,
         "identity_type"?: String,        // Principal identity class: "human" | "agent" | "service"
         "principal"?: PrincipalContext, // ZeroID NHI identity block; absent when the token carries no NHI claims
+        "actor"?: ActorContext,         // Acting agent attributes (status/origin/IdP provenance); absent when none supplied
         // Core metadata (required)
         "request_id": String,
         "timestamp": Long,
@@ -2278,6 +2369,7 @@ namespace Guardrails {
         "privilege_scope"?: Set<String>,
         "identity_type"?: String,        // Principal identity class: "human" | "agent" | "service"
         "principal"?: PrincipalContext, // ZeroID NHI identity block; absent when the token carries no NHI claims
+        "actor"?: ActorContext,         // Acting agent attributes (status/origin/IdP provenance); absent when none supplied
         // Core metadata (required)
         "request_id": String,
         "timestamp": Long,

package/dist/step-up-role-conflict.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Authoring-time lint for @step_up_required role conflicts across a policy set.
+ *
+ * Shield picks one approver role per call. When two enforce-mode step-up
+ * policies of the same effect match one call and name different roles, no
+ * single approval satisfies both, so Shield denies the call with
+ * step_up_internal_error (highflame-shield internal/cedar/annotations.go,
+ * resolveStepUpRole). This lint warns about such pairs before they ship.
+ *
+ * It is a WARNING, not an error: the policy set is valid Cedar and the
+ * conflict only bites on calls both policies match.
+ *
+ * Parity: packages/go/step_up_role_conflict.go.
+ */
+import type { PolicyRule } from './builder.js';
+/** Stable code carried by every StepUpRoleConflictWarning. */
+export declare const STEP_UP_ROLE_CONFLICT_CODE = "step_up_role_conflict";
+/** Owner-approval role. Any named role outranks it, so it never conflicts. */
+export declare const STEP_UP_ROLE_SELF = "self";
+/** Two step-up policies whose roles differ and whose scopes could match the same call. */
+export interface StepUpRoleConflictWarning {
+    code: typeof STEP_UP_ROLE_CONFLICT_CODE;
+    message: string;
+    ruleIdA: string;
+    roleA: string;
+    ruleIdB: string;
+    roleB: string;
+}
+/**
+ * Returns one warning per pair of enabled rules that Shield would treat as a
+ * role conflict if both matched one call.
+ *
+ * The pair rule mirrors Shield's resolveStepUpRole:
+ *  - both rules carry a valid @step_up_required;
+ *  - both have the same effect (a forbid's step-up outranks a permit's, so a
+ *    forbid/permit pair never conflicts);
+ *  - neither role is "self" (a named role outranks owner approval);
+ *  - the roles differ (exact, case-sensitive comparison).
+ *
+ * Overlap heuristic (conservative; exact Cedar satisfiability is out of
+ * scope): the pair warns unless the scope heads clearly cannot match the same
+ * request. Heads are disjoint when the literal action sets do not intersect
+ * (no "*"), or when principal or resource are both exact/`is` constraints on
+ * different entity types, or on the same type with different entity IDs.
+ * `in` (hierarchy) constraints and when/unless conditions are assumed to
+ * overlap. Per-policy mode is not visible in Cedar text, so observe-only
+ * (monitor/alert) policies, which Shield excludes, can still warn here.
+ */
+export declare function lintStepUpRoleConflicts(rules: readonly PolicyRule[]): StepUpRoleConflictWarning[];

package/dist/step-up-role-conflict.js

@@ -0,0 +1,117 @@
+/**
+ * Authoring-time lint for @step_up_required role conflicts across a policy set.
+ *
+ * Shield picks one approver role per call. When two enforce-mode step-up
+ * policies of the same effect match one call and name different roles, no
+ * single approval satisfies both, so Shield denies the call with
+ * step_up_internal_error (highflame-shield internal/cedar/annotations.go,
+ * resolveStepUpRole). This lint warns about such pairs before they ship.
+ *
+ * It is a WARNING, not an error: the policy set is valid Cedar and the
+ * conflict only bites on calls both policies match.
+ *
+ * Parity: packages/go/step_up_role_conflict.go.
+ */
+import { parseAARMAnnotations } from './aarm-annotation.js';
+/** Stable code carried by every StepUpRoleConflictWarning. */
+export const STEP_UP_ROLE_CONFLICT_CODE = 'step_up_role_conflict';
+/** Owner-approval role. Any named role outranks it, so it never conflicts. */
+export const STEP_UP_ROLE_SELF = 'self';
+/**
+ * Returns one warning per pair of enabled rules that Shield would treat as a
+ * role conflict if both matched one call.
+ *
+ * The pair rule mirrors Shield's resolveStepUpRole:
+ *  - both rules carry a valid @step_up_required;
+ *  - both have the same effect (a forbid's step-up outranks a permit's, so a
+ *    forbid/permit pair never conflicts);
+ *  - neither role is "self" (a named role outranks owner approval);
+ *  - the roles differ (exact, case-sensitive comparison).
+ *
+ * Overlap heuristic (conservative; exact Cedar satisfiability is out of
+ * scope): the pair warns unless the scope heads clearly cannot match the same
+ * request. Heads are disjoint when the literal action sets do not intersect
+ * (no "*"), or when principal or resource are both exact/`is` constraints on
+ * different entity types, or on the same type with different entity IDs.
+ * `in` (hierarchy) constraints and when/unless conditions are assumed to
+ * overlap. Per-policy mode is not visible in Cedar text, so observe-only
+ * (monitor/alert) policies, which Shield excludes, can still warn here.
+ */
+export function lintStepUpRoleConflicts(rules) {
+    const candidates = [];
+    for (const rule of rules) {
+        if (!rule.enabled || !rule.customAnnotations)
+            continue;
+        const role = parseAARMAnnotations(rule.customAnnotations).directives.stepUpRequired?.role;
+        if (!role || role === STEP_UP_ROLE_SELF)
+            continue;
+        candidates.push({ rule, role });
+    }
+    const warnings = [];
+    for (let i = 0; i < candidates.length; i++) {
+        for (let j = i + 1; j < candidates.length; j++) {
+            const a = candidates[i];
+            const b = candidates[j];
+            if (a.role === b.role || a.rule.effect !== b.rule.effect)
+                continue;
+            if (!actionsCanOverlap(a.rule.action, b.rule.action) ||
+                !entitiesCanOverlap(a.rule.principal, b.rule.principal) ||
+                !entitiesCanOverlap(a.rule.resource, b.rule.resource)) {
+                continue;
+            }
+            const idA = ruleLabel(a.rule);
+            const idB = ruleLabel(b.rule);
+            warnings.push({
+                code: STEP_UP_ROLE_CONFLICT_CODE,
+                message: `Rules "${idA}" (@step_up_required("${a.role}")) and "${idB}" (@step_up_required("${b.role}")) ` +
+                    'can match the same call but require different approver roles; Shield allows one role per call ' +
+                    'and denies such calls with step_up_internal_error',
+                ruleIdA: idA,
+                roleA: a.role,
+                ruleIdB: idB,
+                roleB: b.role,
+            });
+        }
+    }
+    return warnings;
+}
+function ruleLabel(rule) {
+    return rule.annotations?.id || rule.annotations?.name || '';
+}
+/** Literal action set, or null for a wildcard (or unrecognized shape). */
+function actionSet(action) {
+    const list = typeof action === 'string' ? [action] : Array.isArray(action) ? action : null;
+    if (!list || list.length === 0)
+        return null;
+    const set = new Set();
+    for (const a of list) {
+        if (typeof a !== 'string' || a === '*' || a === '')
+            return null;
+        set.add(a);
+    }
+    return set;
+}
+function actionsCanOverlap(a, b) {
+    const sa = actionSet(a);
+    const sb = actionSet(b);
+    if (!sa || !sb)
+        return true;
+    for (const x of sa)
+        if (sb.has(x))
+            return true;
+    return false;
+}
+/**
+ * Whether two principal/resource constraints could both match one entity.
+ * null means any entity. An `in` constraint names an ancestor, whose type says
+ * nothing about the matched entity's type, so it is assumed to overlap.
+ */
+function entitiesCanOverlap(a, b) {
+    if (!a || !b || a.operator === 'in' || b.operator === 'in')
+        return true;
+    if (a.type !== b.type)
+        return false;
+    if (a.id && b.id && a.id !== b.id)
+        return false;
+    return true;
+}

package/dist/types.d.ts

@@ -6,6 +6,7 @@ export * from './category-layers.gen.js';
 export * from './decision-effects.gen.js';
 export * from './aarm-annotations.gen.js';
 export * from './aarm-annotation.js';
+export * from './step-up-role-conflict.js';
 export * from './privilege-catalog.gen.js';
 export * from './builder.js';
 export * from './errors.js';

package/dist/types.js

@@ -19,6 +19,9 @@ export * from './aarm-annotations.gen.js';
 // AARM annotation parser/validator (browser-safe — typed parse + fail-closed
 // validation; Studio lints with the exact rules Shield runs at sync time).
 export * from './aarm-annotation.js';
+// Policy-set lint: warns when step-up policies naming different approver
+// roles can match the same call (Shield denies with step_up_internal_error).
+export * from './step-up-role-conflict.js';
 // Role -> capability privilege catalog (browser-safe — Studio surfaces
 // the default scope per role; checked by role-conditioned Cedar policies).
 export * from './privilege-catalog.gen.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@highflame/policy",
-  "version": "2.2.45",
+  "version": "2.4.0",
   "engines": {
     "node": ">=18"
   },