@highflame/policy 2.2.45 → 2.3.0

package/dist/aarm-annotation.js

@@ -45,7 +45,10 @@ export function hasAnyAARMDirective(d) {
         d.deferOnConflict !== undefined ||
         d.deferBelowConfidence !== undefined ||
         d.deferUntilContext !== undefined ||
-        d.redactionStrategy !== undefined);
+        d.redactionStrategy !== undefined ||
+        d.stepUpScope !== undefined ||
+        d.stepUpFourEyes !== undefined ||
+        d.singleUse !== undefined);
 }
 /**
  * Structured error for a malformed AARM annotation. Mirrors Go's
@@ -100,7 +103,11 @@ export function parseAARMAnnotations(raw) {
         if (!def) {
             continue; // not an AARM-recognized annotation; ignore
         }
-        const value = raw[key];
+        // cedar-wasm reports a value-less annotation (`@single_use`) as null:
+        // treat it as bare, like Go and parseAnnotations do. undefined and
+        // non-strings still fail closed in parseAARMAnnotationParams.
+        const rawValue = raw[key];
+        const value = (rawValue === null ? '' : rawValue);
         const parsed = parseAARMAnnotationParams(def, value);
         if (parsed.error) {
             errors.push(parsed.error);
@@ -143,6 +150,30 @@ export function parseAARMAnnotations(raw) {
                     directives.redactionStrategy = r.directive;
                 break;
             }
+            case 'step_up_scope': {
+                const r = buildStepUpScope(def, params, value);
+                if (r.error)
+                    errors.push(r.error);
+                else
+                    directives.stepUpScope = r.directive;
+                break;
+            }
+            case 'step_up_four_eyes': {
+                const r = buildStepUpFourEyes(def, params, value);
+                if (r.error)
+                    errors.push(r.error);
+                else
+                    directives.stepUpFourEyes = r.directive;
+                break;
+            }
+            case 'single_use': {
+                const r = buildSingleUse(def, params, value);
+                if (r.error)
+                    errors.push(r.error);
+                else
+                    directives.singleUse = r.directive;
+                break;
+            }
             default:
                 // Registry entry exists but no typed extractor is wired here — a
                 // programming error in highflame-policy. Fail closed at runtime.
@@ -154,12 +185,64 @@ export function parseAARMAnnotations(raw) {
                 }));
         }
     }
+    // The step-up modifiers only mean something next to @step_up_required.
+    // Without it the policy would permit outright while its author believes a
+    // human approval is required, so reject rather than ignore.
+    if (!directives.stepUpRequired) {
+        for (const key of ['step_up_four_eyes', 'step_up_scope']) {
+            if (key in raw && !errors.some((e) => e.key === key)) {
+                errors.push(new AARMAnnotationError({
+                    key,
+                    rawValue: raw[key] ?? '',
+                    reason: 'requires @step_up_required on the same policy',
+                }));
+            }
+        }
+    }
+    // "self" routes the approval to the requesting identity's owner, and
+    // four-eyes forbids exactly that person from approving: every gated call
+    // would wait for an approval that cannot happen, then deny.
+    if (directives.stepUpRequired?.role === 'self' && directives.stepUpFourEyes) {
+        errors.push(new AARMAnnotationError({
+            key: 'step_up_four_eyes',
+            rawValue: raw.step_up_four_eyes ?? '',
+            reason: 'cannot be combined with @step_up_required("self"): self sends the approval ' +
+                'to the owner, whom four-eyes forbids from approving',
+        }));
+    }
     return { directives, errors };
 }
+/**
+ * THE authoring-time AARM check: run it on every rule of a policy before
+ * saving it (Studio's lint, Admin's policy-create/update), passing the rule's
+ * effect. It is validateAARMAnnotations plus the checks that depend on the
+ * effect: `@single_use` is only meaningful on a permit (a forbid never
+ * produces an allow to consume). validateAARMAnnotations alone is
+ * effect-blind and is not sufficient.
+ *
+ * Shield runs the same check at sync, but there an error is not always a
+ * reject: a permit with an invalid annotation is dropped (fail closed), while
+ * a forbid is loaded with the offending annotation ignored, since dropping a
+ * forbid would remove a block. Surface the error here, at save time.
+ *
+ * Exported from both the package root and the browser-safe `./types` entry.
+ */
+export function validateAARMAnnotationsForEffect(effect, raw) {
+    const errors = validateAARMAnnotations(raw);
+    if (raw && 'single_use' in raw && effect !== 'permit' && !errors.some((e) => e.key === 'single_use')) {
+        errors.push(new AARMAnnotationError({
+            key: 'single_use',
+            rawValue: raw.single_use ?? '',
+            reason: 'is only valid on a permit policy',
+        }));
+    }
+    return errors;
+}
 /**
  * Validate-only variant: returns the error list without the typed
- * directives. Suitable for Admin's policy-create endpoint, which only needs
- * the yes/no verdict + error list.
+ * directives. Effect-blind: authoring checks that know the rule's effect
+ * (Admin's policy-create, Studio's lint) must use
+ * validateAARMAnnotationsForEffect instead.
  */
 export function validateAARMAnnotations(raw) {
     return parseAARMAnnotations(raw).errors;
@@ -258,6 +341,16 @@ function parseAARMAnnotationParams(def, raw) {
     // Single-positional shorthand. Bind the whole value to the positional param.
     const pos = positionalParameter(def);
     if (!pos) {
+        // An annotation whose only parameter is optional accepts both the bare
+        // (value-less) form, meaning "use the default", and a bare value as
+        // shorthand for that parameter: @single_use, @single_use("request").
+        const sole = soleOptionalParameter(def);
+        if (sole) {
+            const v = raw.trim();
+            if (v !== '')
+                values[sole.name] = v;
+            return { params: values };
+        }
         return {
             params: {},
             error: new AARMAnnotationError({
@@ -321,6 +414,56 @@ function buildRedactionStrategy(def, params, raw) {
     }
     return { directive: { strategy: strategy.value } };
 }
+/** Mirrors the enums in schemas/annotations.json (the generated registry carries none). */
+const STEP_UP_SCOPES = ['session'];
+const SINGLE_USE_GRANULARITIES = ['tool', 'request'];
+function buildStepUpScope(def, params, raw) {
+    const scope = requireStringParam(def, params, 'scope', raw);
+    if ('error' in scope)
+        return { error: scope.error };
+    if (!STEP_UP_SCOPES.includes(scope.value)) {
+        return {
+            error: new AARMAnnotationError({
+                key: def.key,
+                parameter: 'scope',
+                rawValue: raw,
+                reason: 'scope must be "session"; omit the annotation for the one-call default',
+            }),
+        };
+    }
+    return { directive: { scope: scope.value } };
+}
+function buildStepUpFourEyes(def, params, raw) {
+    // Bare or "true" only: "false" would make the annotation present yet
+    // disabled, which consumers checking presence would misread.
+    const v = params.enabled;
+    if (v !== undefined && v !== '' && v !== 'true') {
+        return {
+            error: new AARMAnnotationError({
+                key: def.key,
+                parameter: 'enabled',
+                rawValue: raw,
+                reason: 'value must be omitted or "true"',
+            }),
+        };
+    }
+    return { directive: {} };
+}
+function buildSingleUse(def, params, raw) {
+    const gDef = mustLookupParam(def, 'granularity');
+    const granularity = params.granularity || (gDef.default?.kind === 'string' ? gDef.default.value : 'tool');
+    if (!SINGLE_USE_GRANULARITIES.includes(granularity)) {
+        return {
+            error: new AARMAnnotationError({
+                key: def.key,
+                parameter: 'granularity',
+                rawValue: raw,
+                reason: 'value must be "tool" or "request" (or omitted for "tool"); values are case-sensitive',
+            }),
+        };
+    }
+    return { directive: { granularity } };
+}
 function buildDeferUntilContext(def, params, raw) {
     const field = requireStringParam(def, params, 'field', raw);
     if ('error' in field)
@@ -510,6 +653,11 @@ function hasParameter(def, name) {
 function parameterNames(def) {
     return def.parameters.map((p) => p.name);
 }
+/** The annotation's only parameter when it is optional and non-positional. */
+function soleOptionalParameter(def) {
+    const [only] = def.parameters;
+    return def.parameters.length === 1 && !only.required && !only.positional ? only : undefined;
+}
 function positionalParameter(def) {
     return def.parameters.find((p) => p.positional);
 }

package/dist/aarm-annotations.gen.js

@@ -85,6 +85,48 @@ export const AARM_ANNOTATIONS = [
             },
         ],
     },
+    {
+        key: 'single_use',
+        description: 'Make an allow by this permit spendable exactly once. Shield records a consume key on the first allow and denies replays of the same grant. Bare means per tool; @single_use(\"tool\") and @single_use(\"request\") are explicit. Valid only on permit. A request without a bearer token (gateway or internal-service traffic) has no token id to record against and is denied single_use_unbound.',
+        aarmRequirement: 'R9',
+        promotesCapability: '',
+        decisionEffect: '',
+        parameters: [
+            {
+                name: 'granularity',
+                type: 'string',
+                required: false,
+                positional: false,
+                description: 'What one use covers. tool: any call to the same action and tool. request: only a call with the same canonicalized arguments. Case-sensitive.',
+                default: { kind: 'string', value: 'tool' },
+                min: null,
+                max: null,
+                pattern: '',
+                valueSource: '',
+            },
+        ],
+    },
+    {
+        key: 'step_up_four_eyes',
+        description: 'Require that the approver is a different person from the requesting agent\'s owner. Bare (value-less) or @step_up_four_eyes(\"true\"); no other value is legal. Requires @step_up_required on the same policy.',
+        aarmRequirement: 'R4',
+        promotesCapability: '',
+        decisionEffect: '',
+        parameters: [
+            {
+                name: 'enabled',
+                type: 'bool',
+                required: false,
+                positional: false,
+                description: 'Always true when present. Accepted spellings are the bare annotation and the string \"true\"; \"false\" is rejected so the annotation cannot be present yet disabled.',
+                default: { kind: 'bool', value: true },
+                min: null,
+                max: null,
+                pattern: '',
+                valueSource: '',
+            },
+        ],
+    },
     {
         key: 'step_up_required',
         description: 'Suspend the action pending human approval from an approver with the named role. AARM R4 STEP_UP decision: Shield issues an OpenID CIBA bc-authorize challenge and the action does not execute until an approver carrying the role resolves it (POST /oauth2/bc-authorize/{auth_req_id}/approve via AuthN), OR timeout_seconds elapses (fail-closed: timeout DENYs the action, never permits).',
@@ -118,6 +160,27 @@ export const AARM_ANNOTATIONS = [
             },
         ],
     },
+    {
+        key: 'step_up_scope',
+        description: 'Widen a step-up approval from one call to the approved tool for the life of the approval token. Without this annotation an approval authorizes exactly one call. With scope session, repeated calls to the SAME tool are covered until the token expires; other tools are never covered. Requires @step_up_required on the same policy.',
+        aarmRequirement: 'R4',
+        promotesCapability: '',
+        decisionEffect: '',
+        parameters: [
+            {
+                name: 'scope',
+                type: 'string',
+                required: true,
+                positional: true,
+                description: 'Approval scope. The only legal value is \"session\"; omit the annotation for the one-call default. Case-sensitive.',
+                default: null,
+                min: null,
+                max: null,
+                pattern: '',
+                valueSource: '',
+            },
+        ],
+    },
 ];
 /**
 * O(1) lookup over AARM_ANNOTATIONS. Use this when validating raw

package/dist/ai_gateway-defaults.gen.d.ts

@@ -2,7 +2,7 @@
  * AiGateway policy category identifiers.
  * Maps to UI tab names in Studio.
  */
-export type AiGatewayCategory = 'semantic' | 'tools' | 'agent-security' | 'data-protection' | 'privacy' | 'organization';
+export type AiGatewayCategory = 'semantic' | 'tools' | 'agent-security' | 'data-protection' | 'privacy' | 'agent-identity' | 'organization';
 /**
  * Category metadata for UI display.
  */

package/dist/ai_gateway-defaults.gen.js

@@ -1321,6 +1321,126 @@ when {
     )
 };
 `;
+const AI_GATEWAY_AGENT_IDENTITY_BLOCK_UNADOPTED_AGENT_SENSITIVE_TOOLS_CEDAR = `// =============================================================================
+// Unadopted Agents: No Sensitive Tool Calls
+// =============================================================================
+// Agents that an enterprise registers in its own IdP (Entra Agent ID, Okta AI
+// agents) are discovered by Highflame before anyone adopts them. A discovered
+// or pending agent has an identity but no owner-reviewed policy, so it should
+// not reach sensitive tools until it is adopted (status "active").
+//
+// \`context.actor.status\` carries the agent lifecycle status. When no actor
+// record is present the rule falls back to the legacy \`context.principal.status\`
+// profile. Absence means "unknown", not "active": the has-guards below make a
+// request with no status fall through to the other rules instead of being
+// matched here. Any status other than "active" is matched, so suspended and
+// deactivated agents are blocked too. The comparison is case-sensitive, like
+// ZeroID's lowercase status values.
+//
+// Today this template is forward-looking. ZeroID mints tokens only for active
+// identities and stamps "active" at mint, and every caller of Shield forwards
+// that value, so no live path reports another status yet. It takes effect when
+// a non-active status reaches Shield, as ADR 0042 plans for agents registered
+// in a customer IdP. The status is a mint-time snapshot: an identity suspended
+// after its token was minted reads "active" until the token expires.
+//
+// \`tool_is_sensitive\` is set by Shield's tool_validator from a fixed list of
+// tool names (shell, execute_command, write_file, http_post, send_email,
+// delete_file, run_sql, plus Shield's configured list); other tools are not
+// sensitive and are not matched.
+//
+// This copy covers gateway traffic (Firehog), which Shield evaluates in the
+// AIGateway namespace. The Guardrails copy covers Guardrails traffic.
+//
+// Deploy in MONITOR mode first to see which discovered agents already call
+// sensitive tools, adopt them, then switch to enforce.
+//
+// Context keys consumed:
+//   - actor, principal: records - status is the agent lifecycle status
+//   - tool_is_sensitive: Bool
+//
+// Compliance:
+//   - OWASP ASI04
+//
+// Category:  agent-identity
+// Namespace: AIGateway
+// =============================================================================
+
+@id("agent-identity.block-unadopted-agent-sensitive-tools")
+@name("Block unadopted agents from sensitive tools")
+@description("Blocks call_tool on a sensitive tool when actor.status (or, without an actor record, principal.status) is present and is not active.")
+@severity("high")
+@tags("category:agent-identity,detection:rule,surface:call-tool,scope:per-agent,posture:deny-default,owasp:asi04")
+@reject_message("Tool execution blocked: this agent has not been adopted, so it may not call sensitive tools. Adopt the agent to activate it.")
+forbid (
+    principal,
+    action == AIGateway::Action::"call_tool",
+    resource
+)
+when {
+    (
+        (context has actor && context.actor has status && context.actor.status != "active") ||
+        (!(context has actor) && context has principal && context.principal has status &&
+         context.principal.status != "active")
+    ) &&
+    context has tool_is_sensitive && context.tool_is_sensitive
+};
+`;
+const AI_GATEWAY_AGENT_IDENTITY_PERMIT_SINGLE_USE_SENSITIVE_TOOLS_CEDAR = `// =============================================================================
+// Single-Use for Sensitive Tools
+// =============================================================================
+// Permits sensitive tool calls, but only once per grant. @single_use makes
+// Shield record the first allow in an atomic consume store and deny any replay
+// of the same grant ("grant_consumed"). Bare @single_use means per tool: one
+// allow covers any call to the same action and tool. Use
+// @single_use("request") instead to bind the allow to one exact set of
+// arguments.
+//
+// @single_use is only valid on a permit. Deny, DEFER and step-up outcomes
+// never consume. If the consume store is unavailable the request is denied
+// ("single_use_store_unavailable") unless the operator opted into fail-open.
+//
+// Requests that carry no bearer token, such as gateway and internal-service
+// traffic, have no token id to record the use against. Shield denies every
+// sensitive call_tool from them ("single_use_unbound"), whatever the
+// fail-open setting. Until the gateway forwards the caller's token to Shield
+// (ADR 0041 D16, ADR 0042 D10), that means every sensitive gateway call.
+//
+// Try it with request-level monitor mode (guard requests sent with
+// mode=monitor): single_use.would_deny on each response shows what enforcing
+// would deny. Per-policy monitor mode does NOT exercise @single_use, because
+// Shield reads it only from enforcing policies; a monitor-mode copy of this
+// template reports nothing, and switching it to enforce takes effect at once.
+//
+// Adopted alone, this permit also allows every sensitive call_tool (once per
+// grant). Pair it with the policies that decide which sensitive calls are
+// allowed at all.
+//
+// Context keys consumed:
+//   - tool_is_sensitive: Bool
+//
+// Compliance:
+//   - OWASP ASI02
+//
+// Category:  agent-identity
+// Namespace: AIGateway
+// =============================================================================
+
+@id("agent-identity.permit-single-use-sensitive-tools")
+@name("Permit sensitive tools once per grant")
+@description("Permits call_tool on a sensitive tool once per grant.")
+@severity("medium")
+@tags("category:agent-identity,surface:call-tool,scope:per-tool,owasp:asi02,single-use")
+@single_use
+permit (
+    principal,
+    action == AIGateway::Action::"call_tool",
+    resource
+)
+when {
+    context has tool_is_sensitive && context.tool_is_sensitive
+};
+`;
 // =============================================================================
 // CATEGORIES
 // =============================================================================
@@ -1330,6 +1450,7 @@ export const AI_GATEWAY_CATEGORIES = [
     { id: 'agent-security', name: 'Agent Security', description: 'Detect tool poisoning, rug pull attacks, indirect prompt injection, and MCP supply chain threats.', layer: 'guardrail' },
     { id: 'data-protection', name: 'Data Protection', description: 'Prevent secrets leakage in LLM chat completions and MCP operations.', layer: 'guardrail' },
     { id: 'privacy', name: 'Privacy', description: 'Block personally identifiable information (PII) in LLM prompts and MCP tool calls.', layer: 'guardrail' },
+    { id: 'agent-identity', name: 'Agent Identity', description: 'Agent lifecycle and provenance controls for gateway traffic: unadopted agents, single-use sensitive tools.', layer: 'guardrail' },
     { id: 'organization', name: 'Organization', description: 'Organization-wide baselines and default permit policies.', layer: 'access' },
 ];
 // =============================================================================
@@ -1451,6 +1572,24 @@ export const AI_GATEWAY_TEMPLATES = [
         severity: 'critical',
         tags: ['category:privacy', 'threat:pii', 'detection:pattern', 'compliance:pci-dss', 'compliance:hipaa'],
     },
+    {
+        id: 'agent-identity.block-unadopted-agent-sensitive-tools',
+        name: 'Unadopted Agents: No Sensitive Tool Calls',
+        description: 'Block sensitive tool calls from agents whose lifecycle status is not active (discovered or pending). Deploy in monitor mode first to see which discovered agents already call sensitive tools.',
+        category: 'agent-identity',
+        cedarText: AI_GATEWAY_AGENT_IDENTITY_BLOCK_UNADOPTED_AGENT_SENSITIVE_TOOLS_CEDAR,
+        severity: 'high',
+        tags: ['category:agent-identity', 'detection:rule', 'surface:call-tool', 'scope:per-agent', 'posture:deny-default', 'owasp:asi04'],
+    },
+    {
+        id: 'agent-identity.permit-single-use-sensitive-tools',
+        name: 'Single-Use for Sensitive Tools',
+        description: 'Permit sensitive tool calls once per grant: the first allow is recorded and a replay of the same grant is denied. Bare @single_use means per tool; use @single_use(\"request\") to bind to one set of arguments. Requests without a bearer token (gateway and internal-service traffic, until the gateway forwards the caller token) are denied (single_use_unbound). Try it with request-level mode=monitor: per-policy monitor mode does not exercise @single_use. Adopted alone, it also permits every sensitive call.',
+        category: 'agent-identity',
+        cedarText: AI_GATEWAY_AGENT_IDENTITY_PERMIT_SINGLE_USE_SENSITIVE_TOOLS_CEDAR,
+        severity: 'medium',
+        tags: ['category:agent-identity', 'surface:call-tool', 'scope:per-tool', 'owasp:asi02', 'single-use'],
+    },
 ];
 // =============================================================================
 // TEMPLATES METADATA
@@ -1491,6 +1630,12 @@ export const AI_GATEWAY_TEMPLATES_JSON = `{
       "description": "Block personally identifiable information (PII) in LLM prompts and MCP tool calls.",
       "layer": "guardrail"
     },
+    {
+      "id": "agent-identity",
+      "name": "Agent Identity",
+      "description": "Agent lifecycle and provenance controls for gateway traffic: unadopted agents, single-use sensitive tools.",
+      "layer": "guardrail"
+    },
     {
       "id": "organization",
       "name": "Organization",
@@ -1655,6 +1800,37 @@ export const AI_GATEWAY_TEMPLATES_JSON = `{
         "compliance:pci-dss",
         "compliance:hipaa"
       ]
+    },
+    {
+      "id": "agent-identity.block-unadopted-agent-sensitive-tools",
+      "name": "Unadopted Agents: No Sensitive Tool Calls",
+      "description": "Block sensitive tool calls from agents whose lifecycle status is not active (discovered or pending). Deploy in monitor mode first to see which discovered agents already call sensitive tools.",
+      "category": "agent-identity",
+      "file": "unadopted_agents.cedar",
+      "severity": "high",
+      "tags": [
+        "category:agent-identity",
+        "detection:rule",
+        "surface:call-tool",
+        "scope:per-agent",
+        "posture:deny-default",
+        "owasp:asi04"
+      ]
+    },
+    {
+      "id": "agent-identity.permit-single-use-sensitive-tools",
+      "name": "Single-Use for Sensitive Tools",
+      "description": "Permit sensitive tool calls once per grant: the first allow is recorded and a replay of the same grant is denied. Bare @single_use means per tool; use @single_use(\\"request\\") to bind to one set of arguments. Requests without a bearer token (gateway and internal-service traffic, until the gateway forwards the caller token) are denied (single_use_unbound). Try it with request-level mode=monitor: per-policy monitor mode does not exercise @single_use. Adopted alone, it also permits every sensitive call.",
+      "category": "agent-identity",
+      "file": "single_use_sensitive_tools.cedar",
+      "severity": "medium",
+      "tags": [
+        "category:agent-identity",
+        "surface:call-tool",
+        "scope:per-tool",
+        "owasp:asi02",
+        "single-use"
+      ]
     }
   ]
 }

package/dist/annotations.d.ts

@@ -112,13 +112,14 @@ export interface ParseAnnotationsResult {
     customAnnotations?: CustomAnnotations;
 }
 /**
- * Parse Cedar annotations from a Record<string, string> (as returned by cedar-wasm).
+ * Parse Cedar annotations from a Record<string, string | null> (as returned by cedar-wasm;
+ * null marks a value-less annotation).
  * Separates predefined annotations from custom annotations.
  *
  * @param rawAnnotations - Raw annotation map from Cedar JSON
  * @returns Parsed annotations object
  */
-export declare function parseAnnotations(rawAnnotations: Record<string, string> | undefined): ParseAnnotationsResult;
+export declare function parseAnnotations(rawAnnotations: Record<string, string | null> | undefined): ParseAnnotationsResult;
 /**
  * Generate a UUID v4 for rule IDs.
  * Uses crypto.randomUUID if available, falls back to manual generation.

package/dist/annotations.js

@@ -108,7 +108,8 @@ export function generateAnnotationLines(annotations, customAnnotations) {
     return lines;
 }
 /**
- * Parse Cedar annotations from a Record<string, string> (as returned by cedar-wasm).
+ * Parse Cedar annotations from a Record<string, string | null> (as returned by cedar-wasm;
+ * null marks a value-less annotation).
  * Separates predefined annotations from custom annotations.
  *
  * @param rawAnnotations - Raw annotation map from Cedar JSON
@@ -124,7 +125,10 @@ export function parseAnnotations(rawAnnotations) {
         return { annotations };
     }
     for (const [key, value] of Object.entries(rawAnnotations)) {
-        const unescapedValue = unescapeAnnotationValue(value);
+        // A value-less annotation (`@single_use`) arrives from cedar-wasm as null.
+        // Normalize to the empty string, which is what cedar-go reports and what
+        // the AARM validators read as "bare".
+        const unescapedValue = unescapeAnnotationValue(value ?? '');
         switch (key) {
             case 'id':
                 annotations.id = unescapedValue;