@highflame/policy 2.1.38 → 2.1.40

package/dist/aarm-annotations.gen.d.ts

@@ -0,0 +1,82 @@
+export declare const AARM_ANNOTATION_REGISTRY_VERSION = "1.0.0";
+export declare const AARM_ANNOTATION_REGISTRY_INTRODUCED_IN = "R4";
+export declare const AARM_ANNOTATION_REGISTRY_SPEC_URL = "https://aarm.dev/conformance/requirements";
+/**
+* Declared runtime type of an AARM annotation parameter.
+* Constrained to the four primitives the registry parser allows.
+*/
+export type AARMParameterType = 'string' | 'int' | 'float' | 'bool';
+/**
+* Typed parameter value used in Default / Min / Max. Discriminator
+* matches `AARMParameterType`; consumers should type-narrow on the
+* `kind` field rather than reading `value` directly.
+*/
+export type AARMParameterValue = {
+    kind: 'string';
+    value: string;
+} | {
+    kind: 'int';
+    value: number;
+} | {
+    kind: 'float';
+    value: number;
+} | {
+    kind: 'bool';
+    value: boolean;
+};
+/** One parameter on an AARM annotation. */
+export interface AARMParameterDef {
+    name: string;
+    type: AARMParameterType;
+    required: boolean;
+    positional: boolean;
+    description: string;
+    /** Default value when the parameter is omitted; null for required. */
+    default: AARMParameterValue | null;
+    /** Inclusive lower bound for int/float; null otherwise. */
+    min: AARMParameterValue | null;
+    /** Inclusive upper bound for int/float; null otherwise. */
+    max: AARMParameterValue | null;
+    /** Regex pattern (for string parameters); empty string when unset. */
+    pattern: string;
+    /** Runtime source identifier for typeahead (e.g. 'authn.roles'). */
+    valueSource: string;
+}
+/**
+* One entry in the platform's annotation registry.
+*
+*  - `key` is the @<name> bare identifier as it appears in Cedar policy text.
+*  - `decisionEffect`, when non-empty, names the Shield decision this
+*    annotation drives ('step_up' | 'defer' | 'modify').
+*  - `promotesCapability`, when non-empty, names the capabilities.yaml
+*    row that becomes implementable once Shield emits the named effect.
+*  - `parameters` preserve the order produced by the registry parser:
+*    the positional parameter (if any) first, then the rest alphabetically.
+*/
+export interface AARMAnnotationDef {
+    key: string;
+    description: string;
+    aarmRequirement: string;
+    promotesCapability: string;
+    decisionEffect: string;
+    parameters: AARMParameterDef[];
+}
+/**
+ * Authoritative annotation registry. Treat as read-only —
+ * mutation is a programming error.
+ */
+export declare const AARM_ANNOTATIONS: readonly AARMAnnotationDef[];
+/**
+* O(1) lookup over AARM_ANNOTATIONS. Use this when validating raw
+* policy annotations against the registry; the array form is for
+* iteration and stable order.
+*
+* The backing object is built with `Object.create(null)` so a
+* registry author who somehow lands `__proto__` / `constructor` /
+* `hasOwnProperty` as an annotation key (rejected by the Rust
+* registry validator, but defense-in-depth) cannot prototype-
+* pollute the lookup. `Object.freeze` is applied on top to lock
+* the top-level key set; consumers should still treat values as
+* immutable (see the `as const` literal types above).
+*/
+export declare const AARM_ANNOTATION_BY_KEY: Readonly<Record<string, AARMAnnotationDef>>;

package/dist/aarm-annotations.gen.js

@@ -0,0 +1,117 @@
+// Code generated by highflame-policy-codegen. DO NOT EDIT.
+// Source: schemas/annotations.json
+//
+// AARM-aware annotation registry. Single source of truth for the
+// annotations Shield's scheduler interprets at evaluation time and
+// that Studio's editor surfaces for autocomplete/lint. Generic Cedar
+// annotations (@id, @name, @description, @severity, @tags) remain
+// free-form and are unrelated.
+export const AARM_ANNOTATION_REGISTRY_VERSION = '1.0.0';
+export const AARM_ANNOTATION_REGISTRY_INTRODUCED_IN = 'R4';
+export const AARM_ANNOTATION_REGISTRY_SPEC_URL = 'https://aarm.dev/conformance/requirements';
+/**
+ * Authoritative annotation registry. Treat as read-only —
+ * mutation is a programming error.
+ */
+export const AARM_ANNOTATIONS = [
+    {
+        key: 'defer_below_confidence',
+        description: 'Defer the decision when ANY detector this policy conditions on returned a confidence below the threshold. AARM R3 DEFER on low confidence: prevents both false-positive blocks and false-negative permits at the gray-zone boundary, suspending until a stronger signal arrives.',
+        aarmRequirement: 'R3',
+        promotesCapability: 'CAP-ENF-005',
+        decisionEffect: 'defer',
+        parameters: [
+            {
+                name: 'threshold',
+                type: 'float',
+                required: true,
+                positional: true,
+                description: 'Confidence threshold in [0.0, 1.0]. Detector scores strictly less than this value trigger a deferral. 0.0 disables (matches no detector). 1.0 always defers.',
+                default: null,
+                min: { kind: 'float', value: 0.0 },
+                max: { kind: 'float', value: 1.0 },
+                pattern: '',
+                valueSource: '',
+            },
+        ],
+    },
+    {
+        key: 'defer_on_conflict',
+        description: 'Defer the decision when two or more equal-priority `forbid` rules disagree about whether to block this action. AARM R3 + R4 DEFER on policy conflict: the scheduler suspends rather than picking deny-by-default, so a policy author can resolve the conflict explicitly. Default behavior absent this annotation remains deny-overrides.',
+        aarmRequirement: 'R3',
+        promotesCapability: 'CAP-ENF-005',
+        decisionEffect: 'defer',
+        parameters: [],
+    },
+    {
+        key: 'defer_until_context',
+        description: 'Defer the decision when a named Cedar context field is null, missing, or the empty string. AARM R3 DEFER on missing context: lets the policy author require a populated field (e.g. `session_max_sensitivity`, `agent_identity_verified`) before letting a decision land, suspending the action rather than evaluating against a half-built session.',
+        aarmRequirement: 'R3',
+        promotesCapability: 'CAP-ENF-005',
+        decisionEffect: 'defer',
+        parameters: [
+            {
+                name: 'field',
+                type: 'string',
+                required: true,
+                positional: true,
+                description: 'Dotted Cedar context-attribute path (e.g. `session_max_sensitivity`, `agent.identity_verified`). Matched against the request\'s projected context at evaluation time.',
+                default: null,
+                min: null,
+                max: null,
+                pattern: '^[a-zA-Z_][a-zA-Z0-9_.]*$',
+                valueSource: '',
+            },
+        ],
+    },
+    {
+        key: 'step_up_required',
+        description: 'Suspend the action pending human approval from an approver with the named role. AARM R4 STEP_UP decision: action does not execute until POST /v1/approvals/{id}/resolve returns allow, OR timeout_seconds elapses (fail-closed: timeout DENYs the action, never permits).',
+        aarmRequirement: 'R4',
+        promotesCapability: 'CAP-ENF-004',
+        decisionEffect: 'step_up',
+        parameters: [
+            {
+                name: 'role',
+                type: 'string',
+                required: true,
+                positional: true,
+                description: 'AuthN role string the approver must carry (e.g. "finance_lead", "security_oncall"). Validated against authn.roles at deploy time; unknown roles reject the policy.',
+                default: null,
+                min: null,
+                max: null,
+                pattern: '',
+                valueSource: 'authn.roles',
+            },
+            {
+                name: 'timeout_seconds',
+                type: 'int',
+                required: false,
+                positional: false,
+                description: 'Seconds the action waits for approval before fail-closed DENY. Default 24h (86400s); bounded [60s, 7d].',
+                default: { kind: 'int', value: 86400 },
+                min: { kind: 'int', value: 60 },
+                max: { kind: 'int', value: 604800 },
+                pattern: '',
+                valueSource: '',
+            },
+        ],
+    },
+];
+/**
+* O(1) lookup over AARM_ANNOTATIONS. Use this when validating raw
+* policy annotations against the registry; the array form is for
+* iteration and stable order.
+*
+* The backing object is built with `Object.create(null)` so a
+* registry author who somehow lands `__proto__` / `constructor` /
+* `hasOwnProperty` as an annotation key (rejected by the Rust
+* registry validator, but defense-in-depth) cannot prototype-
+* pollute the lookup. `Object.freeze` is applied on top to lock
+* the top-level key set; consumers should still treat values as
+* immutable (see the `as const` literal types above).
+*/
+export const AARM_ANNOTATION_BY_KEY = Object.freeze(AARM_ANNOTATIONS.reduce((acc, ann) => {
+    acc[ann.key] = ann;
+    return acc;
+}, Object.create(null)));

package/dist/decision-effects.gen.d.ts

@@ -0,0 +1,8 @@
+export declare const DecisionEffect: {
+    readonly StepUp: "step_up";
+    readonly Defer: "defer";
+    readonly Modify: "modify";
+};
+export type DecisionEffect = (typeof DecisionEffect)[keyof typeof DecisionEffect];
+/** Every legal decision effect, in canonical order. */
+export declare const AllDecisionEffects: DecisionEffect[];

package/dist/decision-effects.gen.js

@@ -0,0 +1,17 @@
+// Code generated by highflame-policy-codegen. DO NOT EDIT.
+// Source: ALLOWED_DECISION_EFFECTS in codegen/src/lib.rs
+//
+// Canonical decision-effect vocabulary. Studio's policy editor and any
+// other TypeScript consumer should import these symbols rather than
+// hard-coding the string literals.
+export const DecisionEffect = {
+    StepUp: "step_up",
+    Defer: "defer",
+    Modify: "modify",
+};
+/** Every legal decision effect, in canonical order. */
+export const AllDecisionEffects = [
+    DecisionEffect.StepUp,
+    DecisionEffect.Defer,
+    DecisionEffect.Modify,
+];

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export * from './entities.gen.js';
 export * from './actions.gen.js';
 export * from './context.gen.js';
 export * from './schema.gen.js';
+export * from './decision-effects.gen.js';
+export * from './aarm-annotations.gen.js';
 export * from './engine.js';
 export * from './builder.js';
 export * from './parser.js';

package/dist/index.js

@@ -7,6 +7,12 @@ export * from './entities.gen.js';
 export * from './actions.gen.js';
 export * from './context.gen.js';
 export * from './schema.gen.js';
+// Canonical decision-effect vocabulary (AARM R4 Wave A). Always emitted —
+// source is ALLOWED_DECISION_EFFECTS in codegen/src/lib.rs, not annotations.json.
+export * from './decision-effects.gen.js';
+// AARM-aware annotation registry (typed Cedar annotation vocabulary
+// Shield interprets at decision time; Studio/Admin use for lint).
+export * from './aarm-annotations.gen.js';
 // Non-generated modules (require Node.js)
 export * from './engine.js';
 export * from './builder.js';

package/dist/types.d.ts

@@ -2,6 +2,8 @@ export * from './entities.gen.js';
 export * from './actions.gen.js';
 export * from './context.gen.js';
 export * from './schema.gen.js';
+export * from './decision-effects.gen.js';
+export * from './aarm-annotations.gen.js';
 export * from './builder.js';
 export * from './errors.js';
 export * from './annotations.js';

package/dist/types.js

@@ -9,6 +9,12 @@ export * from './entities.gen.js';
 export * from './actions.gen.js';
 export * from './context.gen.js';
 export * from './schema.gen.js';
+// Canonical decision-effect vocabulary (browser-safe). Studio's Monaco
+// policy editor imports these typed symbols rather than string literals.
+export * from './decision-effects.gen.js';
+// AARM-aware annotation registry (browser-safe — Studio uses this
+// for Monaco autocomplete + lint of @step_up_required / @defer_* keys).
+export * from './aarm-annotations.gen.js';
 // PolicyBuilder - works in browser (no WASM dependency)
 export * from './builder.js';
 // Error types - works in browser (no WASM dependency)

package/package.json

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