@highflame/policy 2.1.41 → 2.1.42

package/dist/aarm-annotation.js

@@ -0,0 +1,494 @@
+/**
+ * AARM-Aware Annotation Parser (TypeScript)
+ *
+ * Runtime layer over the generated AARM annotation registry
+ * (aarm-annotations.gen.ts). Ported from packages/go/aarm_annotation.go to
+ * give Studio's policy editor the SAME parse + validation rules Shield runs
+ * at policy sync time (Go's ValidateAARMAnnotations). The two
+ * implementations share a test corpus — see aarm-annotation.test.ts and its
+ * Go twin aarm_annotation_test.go.
+ *
+ * Takes the `Record<string, string>` of a policy's @-annotations and
+ * produces:
+ *
+ *   - typed directives Studio (and any TS consumer) can switch on
+ *     (StepUpRequiredDirective, DeferBelowConfidenceDirective, ...) and
+ *   - a list of typed validation errors (AARMAnnotationError).
+ *
+ * Three encoding shapes are accepted, matching the value_encoding block in
+ * schemas/annotations.json:
+ *
+ *  1. Marker:                  `@defer_on_conflict("")`        → no params
+ *  2. Single-param positional: `@defer_below_confidence("0.7")` → bare value
+ *     binds to the single required-positional parameter declared in the
+ *     registry. Fails closed if no such parameter exists.
+ *  3. Multi-param key=value:    `@step_up_required("role=finance_lead,timeout_seconds=3600")`
+ *     parameters are comma-separated key=value pairs. Unknown keys error;
+ *     missing required parameters error.
+ *
+ * Generic Cedar annotations (@id, @name, @severity, @tags, arbitrary custom
+ * KV pairs) are NOT parsed here — those live in annotations.ts and remain
+ * free-form. AARM annotations are a strict subset whose key MUST appear in
+ * AARM_ANNOTATION_BY_KEY.
+ *
+ * Validation is fail-closed (AARM R3/R4): a malformed AARM annotation never
+ * silently degrades to a no-op — the caller is told exactly which
+ * annotation, which parameter, and what was wrong, so Admin can reject the
+ * policy at deploy time and Studio's lint can surface it inline.
+ */
+import { AARM_ANNOTATION_BY_KEY, } from './aarm-annotations.gen.js';
+/** True iff at least one AARM directive was parsed. */
+export function hasAnyAARMDirective(d) {
+    if (!d)
+        return false;
+    return (d.stepUpRequired !== undefined ||
+        d.deferOnConflict !== undefined ||
+        d.deferBelowConfidence !== undefined ||
+        d.deferUntilContext !== undefined);
+}
+/**
+ * Structured error for a malformed AARM annotation. Mirrors Go's
+ * AARMAnnotationError. Studio's lint surfaces these inline; Admin serializes
+ * them in the policy-create rejection.
+ */
+export class AARMAnnotationError extends Error {
+    key;
+    parameter;
+    rawValue;
+    reason;
+    constructor(init) {
+        const key = init.key;
+        const parameter = init.parameter ?? '';
+        const rawValue = init.rawValue ?? '';
+        const reason = init.reason;
+        // Message format matches Go's AARMAnnotationError.Error().
+        const message = parameter !== ''
+            ? `AARM annotation "${key}" parameter "${parameter}": ${reason} (got "${rawValue}")`
+            : `AARM annotation "${key}": ${reason} (got "${rawValue}")`;
+        super(message);
+        this.name = 'AARMAnnotationError';
+        this.key = key;
+        this.parameter = parameter;
+        this.rawValue = rawValue;
+        this.reason = reason;
+        Object.setPrototypeOf(this, AARMAnnotationError.prototype);
+    }
+}
+/** True iff err is an AARMAnnotationError. */
+export function isAARMAnnotationError(err) {
+    return err instanceof AARMAnnotationError;
+}
+/**
+ * Walks the raw annotation map and extracts every AARM-recognized annotation
+ * into typed directives. Non-AARM keys are ignored (handled by the generic
+ * annotation surface in annotations.ts).
+ *
+ * Errors are COLLECTED, not fail-fast, so a single call surfaces every
+ * offending annotation at once — Studio shows all squiggles in one pass.
+ * Keys are processed in sorted order for stable error reporting.
+ */
+export function parseAARMAnnotations(raw) {
+    const directives = {};
+    const errors = [];
+    if (!raw) {
+        return { directives, errors };
+    }
+    const keys = Object.keys(raw).sort();
+    for (const key of keys) {
+        const def = AARM_ANNOTATION_BY_KEY[key];
+        if (!def) {
+            continue; // not an AARM-recognized annotation; ignore
+        }
+        const value = raw[key];
+        const parsed = parseAARMAnnotationParams(def, value);
+        if (parsed.error) {
+            errors.push(parsed.error);
+            continue;
+        }
+        const params = parsed.params;
+        switch (def.key) {
+            case 'step_up_required': {
+                const r = buildStepUpRequired(def, params, value);
+                if (r.error)
+                    errors.push(r.error);
+                else
+                    directives.stepUpRequired = r.directive;
+                break;
+            }
+            case 'defer_on_conflict':
+                directives.deferOnConflict = {};
+                break;
+            case 'defer_below_confidence': {
+                const r = buildDeferBelowConfidence(def, params, value);
+                if (r.error)
+                    errors.push(r.error);
+                else
+                    directives.deferBelowConfidence = r.directive;
+                break;
+            }
+            case 'defer_until_context': {
+                const r = buildDeferUntilContext(def, params, value);
+                if (r.error)
+                    errors.push(r.error);
+                else
+                    directives.deferUntilContext = r.directive;
+                break;
+            }
+            default:
+                // Registry entry exists but no typed extractor is wired here — a
+                // programming error in highflame-policy. Fail closed at runtime.
+                errors.push(new AARMAnnotationError({
+                    key,
+                    rawValue: value,
+                    reason: 'registry entry exists but no typed extractor is wired in ' +
+                        'aarm-annotation.ts; this is a programming error in highflame-policy',
+                }));
+        }
+    }
+    return { directives, 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.
+ */
+export function validateAARMAnnotations(raw) {
+    return parseAARMAnnotations(raw).errors;
+}
+/** True iff key is a platform-recognized AARM annotation. */
+export function isAARMAnnotationKey(key) {
+    return Object.prototype.hasOwnProperty.call(AARM_ANNOTATION_BY_KEY, key);
+}
+// Hard cap on a raw annotation value's length, enforced before any regex runs.
+// AARM annotation values are short by construction — a role + timeout, a
+// threshold, a dotted context-field path; the longest legitimate value is well
+// under 100 chars. Bounding length here keeps every regex below (including the
+// backtracking float matcher and the registry-sourced `defer_until_context`
+// pattern) in trivially-linear territory, closing a ReDoS vector that would
+// otherwise be reachable from policy-author input — this parser runs in Studio
+// lint AND Admin's policy-create endpoint. (Go's RE2 + strconv are linear and
+// don't share this hazard, so the cap is a TS-specific guard.)
+const MAX_AARM_VALUE_LEN = 512;
+// Compiled-pattern cache for registry-sourced regexes (defer_until_context's
+// `field` pattern). Registry patterns are build-time, bounded, and immutable
+// for the process lifetime, so compile once and reuse — parity with Go's
+// compileRegistryPattern cache, and avoids recompiling on every parse call.
+const patternCache = new Map();
+/**
+ * Normalizes a raw Cedar annotation value into a `name → string-value` map,
+ * honoring the three encoding shapes. Per-parameter coercion + bounds happen
+ * in the per-directive builders.
+ */
+function parseAARMAnnotationParams(def, raw) {
+    const values = {};
+    // The public type is Record<string,string>, but at runtime a value can be
+    // non-string — e.g. `{"step_up_required": null}` from a deserialized policy,
+    // or a JS caller. Guard before any string op so a malformed value yields a
+    // structured error instead of a TypeError that crashes the validating
+    // request (fail-closed, consistent with the rest of the parser).
+    if (typeof raw !== 'string') {
+        return {
+            params: {},
+            error: new AARMAnnotationError({
+                key: def.key,
+                rawValue: raw === undefined ? 'undefined' : raw === null ? 'null' : String(raw),
+                reason: 'annotation value must be a string',
+            }),
+        };
+    }
+    if (raw.length > MAX_AARM_VALUE_LEN) {
+        return {
+            params: {},
+            error: new AARMAnnotationError({
+                key: def.key,
+                // Truncate so the error itself doesn't echo the oversized value.
+                rawValue: `${raw.slice(0, 64)}…`,
+                reason: `annotation value exceeds the maximum length of ${MAX_AARM_VALUE_LEN} characters`,
+            }),
+        };
+    }
+    // Marker annotation — Cedar requires a string value, so authors pass
+    // anything; PRESENCE is the signal.
+    if (def.parameters.length === 0) {
+        return { params: values };
+    }
+    if (raw.includes('=')) {
+        // Multi-param k=v (also covers a single named param).
+        for (const segment of raw.split(',')) {
+            const seg = segment.trim();
+            if (seg === '')
+                continue;
+            const eq = seg.indexOf('=');
+            if (eq <= 0 || eq === seg.length - 1) {
+                return {
+                    params: {},
+                    error: new AARMAnnotationError({
+                        key: def.key,
+                        rawValue: raw,
+                        reason: `malformed key=value pair "${seg}"`,
+                    }),
+                };
+            }
+            const k = seg.slice(0, eq).trim();
+            const v = seg.slice(eq + 1).trim();
+            if (!hasParameter(def, k)) {
+                return {
+                    params: {},
+                    error: new AARMAnnotationError({
+                        key: def.key,
+                        parameter: k,
+                        rawValue: v,
+                        reason: `unknown parameter; allowed: ${parameterNames(def).join(', ')}`,
+                    }),
+                };
+            }
+            values[k] = v;
+        }
+        return { params: values };
+    }
+    // Single-positional shorthand. Bind the whole value to the positional param.
+    const pos = positionalParameter(def);
+    if (!pos) {
+        return {
+            params: {},
+            error: new AARMAnnotationError({
+                key: def.key,
+                rawValue: raw,
+                reason: 'bare value provided but the annotation has no positional parameter; ' +
+                    'use the key=value form',
+            }),
+        };
+    }
+    values[pos.name] = raw.trim();
+    return { params: values };
+}
+function buildStepUpRequired(def, params, raw) {
+    const role = requireStringParam(def, params, 'role', raw);
+    if ('error' in role)
+        return { error: role.error };
+    const timeoutDef = mustLookupParam(def, 'timeout_seconds');
+    const defaultTimeout = timeoutDef.default && timeoutDef.default.kind === 'int' ? timeoutDef.default.value : 0;
+    const timeout = optionalIntParam(def, params, 'timeout_seconds', defaultTimeout, raw);
+    if ('error' in timeout)
+        return { error: timeout.error };
+    const bounds = checkIntBounds(def, 'timeout_seconds', timeout.value, timeoutDef, raw);
+    if (bounds)
+        return { error: bounds };
+    return { directive: { role: role.value, timeoutSeconds: timeout.value } };
+}
+function buildDeferBelowConfidence(def, params, raw) {
+    const thresholdDef = mustLookupParam(def, 'threshold');
+    const threshold = requireFloatParam(def, params, 'threshold', raw);
+    if ('error' in threshold)
+        return { error: threshold.error };
+    const bounds = checkFloatBounds(def, 'threshold', threshold.value, thresholdDef, raw);
+    if (bounds)
+        return { error: bounds };
+    return { directive: { threshold: threshold.value } };
+}
+function buildDeferUntilContext(def, params, raw) {
+    const field = requireStringParam(def, params, 'field', raw);
+    if ('error' in field)
+        return { error: field.error };
+    const fieldDef = mustLookupParam(def, 'field');
+    if (fieldDef.pattern !== '') {
+        let re = patternCache.get(fieldDef.pattern);
+        if (!re) {
+            try {
+                re = new RegExp(fieldDef.pattern);
+            }
+            catch (e) {
+                return {
+                    error: new AARMAnnotationError({
+                        key: def.key,
+                        parameter: 'field',
+                        rawValue: field.value,
+                        reason: `registry pattern "${fieldDef.pattern}" does not compile: ${String(e)} (registry bug)`,
+                    }),
+                };
+            }
+            patternCache.set(fieldDef.pattern, re);
+        }
+        if (!re.test(field.value)) {
+            return {
+                error: new AARMAnnotationError({
+                    key: def.key,
+                    parameter: 'field',
+                    rawValue: field.value,
+                    reason: `value does not match required pattern "${fieldDef.pattern}" (Cedar context-attribute path)`,
+                }),
+            };
+        }
+    }
+    return { directive: { field: field.value } };
+}
+// Go's strconv.ParseFloat accepts NaN/Inf as valid float SYNTAX; we reject
+// them as non-finite (parity with requireFloatParam's finite-number gate).
+const NON_FINITE_RE = /^[+-]?(nan|inf|infinity)$/i;
+const FLOAT_RE = /^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/;
+const INT_RE = /^[+-]?\d+$/;
+function requireStringParam(def, params, name, raw) {
+    const v = params[name];
+    if (v === undefined || v === '') {
+        return {
+            error: new AARMAnnotationError({
+                key: def.key,
+                parameter: name,
+                rawValue: raw,
+                reason: 'required parameter is missing',
+            }),
+        };
+    }
+    return { value: v };
+}
+function requireFloatParam(def, params, name, raw) {
+    const v = params[name];
+    if (v === undefined || v === '') {
+        return {
+            error: new AARMAnnotationError({
+                key: def.key,
+                parameter: name,
+                rawValue: raw,
+                reason: 'required parameter is missing',
+            }),
+        };
+    }
+    // AARM R3/R4 fail-closed: NaN/Inf parse as "valid float syntax" in Go and
+    // would slip past bounds checks (NaN comparisons are uniformly false),
+    // letting Shield emit a directive that never fires. Reject up front.
+    if (NON_FINITE_RE.test(v)) {
+        return {
+            error: new AARMAnnotationError({
+                key: def.key,
+                parameter: name,
+                rawValue: v,
+                reason: 'value must be a finite number (NaN, +Inf, -Inf are rejected)',
+            }),
+        };
+    }
+    if (!FLOAT_RE.test(v)) {
+        return {
+            error: new AARMAnnotationError({
+                key: def.key,
+                parameter: name,
+                rawValue: v,
+                reason: 'value is not a valid float',
+            }),
+        };
+    }
+    const f = Number(v);
+    if (!Number.isFinite(f)) {
+        return {
+            error: new AARMAnnotationError({
+                key: def.key,
+                parameter: name,
+                rawValue: v,
+                reason: 'value must be a finite number (NaN, +Inf, -Inf are rejected)',
+            }),
+        };
+    }
+    return { value: f };
+}
+function optionalIntParam(def, params, name, defaultValue, raw) {
+    const v = params[name];
+    if (v === undefined || v === '') {
+        return { value: defaultValue };
+    }
+    if (!INT_RE.test(v)) {
+        return {
+            error: new AARMAnnotationError({
+                key: def.key,
+                parameter: name,
+                rawValue: v,
+                reason: 'value is not a valid int',
+            }),
+        };
+    }
+    return { value: Number(v) };
+}
+function checkFloatBounds(def, name, value, pdef, raw) {
+    // Belt-and-braces with requireFloatParam: a non-finite value reaching here
+    // (via a future code path that skips it) must still be rejected.
+    if (!Number.isFinite(value)) {
+        return new AARMAnnotationError({
+            key: def.key,
+            parameter: name,
+            rawValue: raw,
+            reason: 'value must be a finite number (NaN, +Inf, -Inf are rejected)',
+        });
+    }
+    if (pdef.min !== null) {
+        const min = pdef.min.value;
+        if (value < min) {
+            return new AARMAnnotationError({
+                key: def.key,
+                parameter: name,
+                rawValue: raw,
+                reason: `value ${value} is below the minimum ${min}`,
+            });
+        }
+    }
+    if (pdef.max !== null) {
+        const max = pdef.max.value;
+        if (value > max) {
+            return new AARMAnnotationError({
+                key: def.key,
+                parameter: name,
+                rawValue: raw,
+                reason: `value ${value} is above the maximum ${max}`,
+            });
+        }
+    }
+    return undefined;
+}
+function checkIntBounds(def, name, value, pdef, raw) {
+    if (pdef.min !== null) {
+        const min = pdef.min.value;
+        if (value < min) {
+            return new AARMAnnotationError({
+                key: def.key,
+                parameter: name,
+                rawValue: raw,
+                reason: `value ${value} is below the minimum ${min}`,
+            });
+        }
+    }
+    if (pdef.max !== null) {
+        const max = pdef.max.value;
+        if (value > max) {
+            return new AARMAnnotationError({
+                key: def.key,
+                parameter: name,
+                rawValue: raw,
+                reason: `value ${value} is above the maximum ${max}`,
+            });
+        }
+    }
+    return undefined;
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Registry-introspection helpers
+// ─────────────────────────────────────────────────────────────────────────
+function hasParameter(def, name) {
+    return def.parameters.some((p) => p.name === name);
+}
+function parameterNames(def) {
+    return def.parameters.map((p) => p.name);
+}
+function positionalParameter(def) {
+    return def.parameters.find((p) => p.positional);
+}
+/**
+ * Returns the named parameter def; throws if absent. Used only for
+ * parameters the builder REQUIRES the registry to declare — a missing entry
+ * means aarm-annotation.ts drifted from schemas/annotations.json, and a loud
+ * throw surfaces it at the test boundary rather than a later undefined-read.
+ */
+function mustLookupParam(def, name) {
+    const p = def.parameters.find((x) => x.name === name);
+    if (!p) {
+        throw new Error(`aarm-annotation.ts: registry entry for "${def.key}" does not declare ` +
+            `parameter "${name}" (schemas/annotations.json drift)`);
+    }
+    return p;
+}

package/dist/aarm-annotations.gen.js

@@ -66,7 +66,7 @@ export const AARM_ANNOTATIONS = [
     },
     {
         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).',
+        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).',
         aarmRequirement: 'R4',
         promotesCapability: 'CAP-ENF-004',
         decisionEffect: 'step_up',

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

@@ -30,7 +30,9 @@ export declare const AiGatewayContextKey: {
     readonly PiiDetected: "pii_detected";
     readonly PiiScore: "pii_score";
     readonly PiiTypes: "pii_types";
+    readonly PrivilegeScope: "privilege_scope";
     readonly ProfanityScore: "profanity_score";
+    readonly Role: "role";
     readonly RugPullDetected: "rug_pull_detected";
     readonly RugPullScore: "rug_pull_score";
     readonly SecretCount: "secret_count";

package/dist/ai_gateway-context.gen.js

@@ -32,7 +32,9 @@ export const AiGatewayContextKey = {
     PiiDetected: 'pii_detected',
     PiiScore: 'pii_score',
     PiiTypes: 'pii_types',
+    PrivilegeScope: 'privilege_scope',
     ProfanityScore: 'profanity_score',
+    Role: 'role',
     RugPullDetected: 'rug_pull_detected',
     RugPullScore: 'rug_pull_score',
     SecretCount: 'secret_count',

package/dist/guardrails-context.gen.d.ts

@@ -77,8 +77,10 @@ export declare const GuardrailsContextKey: {
     readonly PiiDetected: "pii_detected";
     readonly PiiScore: "pii_score";
     readonly PiiTypes: "pii_types";
+    readonly PrivilegeScope: "privilege_scope";
     readonly ProfanityScore: "profanity_score";
     readonly RequestId: "request_id";
+    readonly Role: "role";
     readonly RugPullDetected: "rug_pull_detected";
     readonly RugPullScore: "rug_pull_score";
     readonly RugPullType: "rug_pull_type";

package/dist/guardrails-context.gen.js

@@ -79,8 +79,10 @@ export const GuardrailsContextKey = {
     PiiDetected: 'pii_detected',
     PiiScore: 'pii_score',
     PiiTypes: 'pii_types',
+    PrivilegeScope: 'privilege_scope',
     ProfanityScore: 'profanity_score',
     RequestId: 'request_id',
+    Role: 'role',
     RugPullDetected: 'rug_pull_detected',
     RugPullScore: 'rug_pull_score',
     RugPullType: 'rug_pull_type',

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from './context.gen.js';
 export * from './schema.gen.js';
 export * from './decision-effects.gen.js';
 export * from './aarm-annotations.gen.js';
+export * from './aarm-annotation.js';
 export * from './engine.js';
 export * from './builder.js';
 export * from './parser.js';

package/dist/index.js

@@ -13,6 +13,9 @@ 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';
+// AARM annotation parser/validator (typed parse + fail-closed validation,
+// parity with Go's aarm_annotation.go).
+export * from './aarm-annotation.js';
 // Non-generated modules (require Node.js)
 export * from './engine.js';
 export * from './builder.js';

package/dist/overwatch-context.gen.d.ts

@@ -36,9 +36,11 @@ export declare const OverwatchContextKey: {
     readonly PiiDetected: "pii_detected";
     readonly PiiScore: "pii_score";
     readonly PiiTypes: "pii_types";
+    readonly PrivilegeScope: "privilege_scope";
     readonly ProfanityScore: "profanity_score";
     readonly PromptText: "prompt_text";
     readonly ResponseContent: "response_content";
+    readonly Role: "role";
     readonly RugPullDetected: "rug_pull_detected";
     readonly RugPullScore: "rug_pull_score";
     readonly SecretCount: "secret_count";

package/dist/overwatch-context.gen.js

@@ -38,9 +38,11 @@ export const OverwatchContextKey = {
     PiiDetected: 'pii_detected',
     PiiScore: 'pii_score',
     PiiTypes: 'pii_types',
+    PrivilegeScope: 'privilege_scope',
     ProfanityScore: 'profanity_score',
     PromptText: 'prompt_text',
     ResponseContent: 'response_content',
+    Role: 'role',
     RugPullDetected: 'rug_pull_detected',
     RugPullScore: 'rug_pull_score',
     SecretCount: 'secret_count',

package/dist/sentry-context.gen.d.ts

@@ -50,7 +50,9 @@ export declare const SentryContextKey: {
     readonly PiiDetected: "pii_detected";
     readonly PiiScore: "pii_score";
     readonly PiiTypes: "pii_types";
+    readonly PrivilegeScope: "privilege_scope";
     readonly ProfanityScore: "profanity_score";
+    readonly Role: "role";
     readonly ScriptConfidence: "script_confidence";
     readonly SecretCount: "secret_count";
     readonly SecretTypes: "secret_types";

package/dist/sentry-context.gen.js

@@ -52,7 +52,9 @@ export const SentryContextKey = {
     PiiDetected: 'pii_detected',
     PiiScore: 'pii_score',
     PiiTypes: 'pii_types',
+    PrivilegeScope: 'privilege_scope',
     ProfanityScore: 'profanity_score',
+    Role: 'role',
     ScriptConfidence: 'script_confidence',
     SecretCount: 'secret_count',
     SecretTypes: 'secret_types',