@armoriq/policy-ir 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,426 @@
+/**
+ * `armor.policy.v2` intermediate representation.
+ *
+ * Data, never a program: the same JSON is evaluated by conmap, the Armor CLI
+ * daemon, the SDK pre-check and OPA. The document is the hashing and signing
+ * boundary, so every field here is part of `policyHash` except `policyHash`.
+ */
+declare const SCHEMA_VERSION: "armor.policy.v2";
+type Verdict = 'allow' | 'hold' | 'block';
+/** Where a document sits in the layering ladder. A boundary is a floor: it can only tighten. */
+type Layer = 'floor' | 'group' | 'agent' | 'member' | 'local';
+type PolicyTarget = {
+    org: '*';
+} | {
+    group: string;
+} | {
+    agent: string;
+    mcpServers?: string[];
+} | {
+    device: 'local';
+    products?: string[];
+};
+interface Defaults {
+    tools: Verdict;
+    network: Verdict;
+    files: Verdict;
+    skills: Verdict;
+}
+interface Capture {
+    arguments: boolean;
+    redact: string[];
+    maxBytesPerCall: number;
+    sample: number;
+}
+type KeyTier = 'exact' | 'glob';
+type StatementMatch = {
+    tool: string;
+    keyTier: KeyTier;
+    order: number;
+} | {
+    capability: string;
+};
+type ConditionOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'notIn' | 'glob' | 'regex' | 'notRegex' | 'startsWith' | 'exists';
+interface SchemaBinding {
+    /** `sha256:` of the tool's canonical input schema at compile time; null when the inventory had none. */
+    schemaHash: string | null;
+}
+interface Condition {
+    /** Dotpath into the call: `args.amount`, `args.command.program`, `path`. */
+    field: string;
+    op: ConditionOp;
+    value?: unknown;
+    schemaBinding?: SchemaBinding;
+}
+interface Approval {
+    approvers: number;
+    roles?: string[];
+    members?: string[];
+    anyMember?: boolean;
+}
+/** Who a statement applies to. Absent means everyone the document targets. */
+type Subject = {
+    membershipId: string;
+} | {
+    email: string;
+} | {
+    group: string;
+} | {
+    product: string;
+};
+interface Provenance {
+    ruleKey: string;
+    variant: number;
+    source: 'yaml' | 'converter' | 'compose' | 'settings-import';
+    layer: Layer;
+}
+interface Statement {
+    id: string;
+    subject: Subject | null;
+    match: StatementMatch;
+    effect: Verdict;
+    conditions: Condition[];
+    approval?: Approval;
+    /** ISO date-time, or the literal `never`. Always present. */
+    expiresAt: string | 'never';
+    controls?: string[];
+    provenance: Provenance;
+}
+interface PolicyDocument {
+    schemaVersion: typeof SCHEMA_VERSION;
+    policyId: string;
+    /** `sha256:` over the canonical document without this field. */
+    policyHash?: string;
+    target: PolicyTarget;
+    layer: Layer;
+    defaults: Defaults;
+    capture: Capture;
+    /** ISO date-time, or the literal `never`. Always present. */
+    expiresAt: string | 'never';
+    statements: Statement[];
+}
+declare function layerOfTarget(target: PolicyTarget): Layer;
+
+/**
+ * Canonical JSON: sorted keys, no whitespace, ASCII escapes for anything
+ * outside printable ASCII. Byte-for-byte the rule the SDKs and the tool
+ * inventory use for `schemaHash`, so the platform has one hashing rule.
+ * Not RFC 8785. `undefined` object members are dropped; `undefined` and
+ * `null` values both serialize as `null`.
+ */
+declare function canonicalJson(value: unknown): string;
+
+declare const HASH_PREFIX = "sha256:";
+/** `sha256:` over the canonical JSON of any value. */
+declare function sha256Canonical(value: unknown): string;
+/**
+ * The document's hash: canonical JSON of the document with `policyHash`
+ * removed. Stable across key order and whitespace; any change to a
+ * statement, default, target or capture setting changes it. This is the
+ * hashing and signing boundary shared by every runtime.
+ */
+declare function policyHash(document: PolicyDocument): string;
+/** True when `document.policyHash` is present and matches its content. */
+declare function verifyPolicyHash(document: PolicyDocument): boolean;
+
+/**
+ * A tool's input schema reduced to what governs a call: annotations
+ * (`description`, `title`) are dropped, local `$ref`s are resolved, and the
+ * result is hashed in canonical form. Byte-for-byte the rule the SDKs and the
+ * tool inventory use, pinned by the shared vectors, so a policy compiled
+ * against a snapshot hash and a call carrying the live hash compare equal
+ * only when the schema is the same.
+ */
+declare function schemaHash(inputSchema: unknown): string | null;
+
+interface Principal {
+    membershipId?: string;
+    email?: string;
+    groups?: string[];
+    /** The local agent making the call, for a `products:` overlay. */
+    product?: string;
+}
+/** One call, as the enforce path and the local hook both see it. */
+interface CallInput {
+    tool: string;
+    arguments: Record<string, unknown>;
+    /**
+     * Derived fields a host may supply: `path`, `program`, `command`,
+     * `writeRedirection`, `withinWorkspace`, `url`, `host`, `skill`, `env`.
+     * Globs are literal, so a host writes `path` home-relative (`~/.ssh/id_rsa`)
+     * when the path is under the user's home; `files.deny: ["~/.ssh/**"]` then
+     * matches exactly what the author wrote.
+     */
+    derived?: Record<string, unknown>;
+    /** Capability tags the inventory holds for this tool. */
+    capabilities?: string[];
+    /** The tool's live input-schema hash, when the caller knows it. */
+    schemaHash?: string | null;
+    member?: Principal;
+    /** ISO date-time the call is evaluated at. */
+    timestamp: string;
+}
+interface SchemaDriftObligation {
+    type: 'schema_drift';
+    statementId: string;
+    bound: string;
+    observed: string | null;
+}
+type Obligation = SchemaDriftObligation;
+interface VerdictProvenance {
+    policyId: string;
+    statementId: string | null;
+    ruleKey: string;
+    variant: number;
+    layer: Layer;
+}
+interface Evaluation {
+    verdict: Verdict;
+    /** The floor's own verdict, so a caller can tell a floor block from a rule block. */
+    floorVerdict: Verdict | null;
+    approval: Approval | null;
+    obligations: Obligation[];
+    provenance: VerdictProvenance;
+}
+declare const VERDICT_RANK: Record<Verdict, number>;
+declare function stricter(a: Verdict, b: Verdict): Verdict;
+
+/**
+ * The documents bound to one target. At most one per layer, enforced by the
+ * single-active trigger; the floor is the organization's.
+ */
+interface BoundDocuments {
+    floor?: PolicyDocument;
+    group?: PolicyDocument;
+    agent?: PolicyDocument;
+}
+/**
+ * Four stages over four layers (PRD §7.4):
+ *   1. floor: a floor block ends evaluation; otherwise its verdict is retained
+ *   2. resolve: the member scope inside the most specific document
+ *   3. candidate: member rule, then agent, then group, then the most specific tools.default
+ *   4. merge: the stricter of floor and candidate
+ */
+declare function evaluate(input: CallInput, bound: BoundDocuments): Evaluation;
+
+/**
+ * Glob matching for tool keys and paths. `*` matches any run of characters
+ * except `/`; `**` matches across `/`; `?` matches one character. Tool keys
+ * carry no `/`, so `*` spans the whole name there. Anchored at both ends.
+ */
+declare function globToRegExp(pattern: string): RegExp;
+declare function matchGlob(pattern: string, value: string): boolean;
+declare function isGlob(key: string): boolean;
+
+/**
+ * Resolve a dotpath against the call. `args.*` reads `arguments`; any other
+ * root reads the host-derived fields. `undefined` means absent, and an absent
+ * field fails the condition rather than throwing or matching.
+ */
+declare function resolveField(input: CallInput, field: string): unknown;
+declare function conditionsHold(input: CallInput, conditions: Condition[]): boolean;
+declare function conditionHolds(input: CallInput, condition: Condition): boolean;
+
+/**
+ * Key selection: an exact key beats any glob, a longer glob beats a shorter
+ * one. Two same-length globs matching one tool are rejected at compile time;
+ * here the first in document order wins so evaluation stays deterministic.
+ */
+declare function selectRuleKey(statements: Statement[], tool: string): string | null;
+
+type Severity = 'error' | 'warning';
+interface Diagnostic {
+    code: string;
+    severity: Severity;
+    /** JSON-pointer-like path into the source document, `/spec/tools/rules/Bash/0`. */
+    path: string;
+    message: string;
+}
+declare class Diagnostics {
+    readonly items: Diagnostic[];
+    error(code: string, path: string, message: string): void;
+    warning(code: string, path: string, message: string): void;
+    get hasErrors(): boolean;
+}
+
+/** The `armor.io/v2` source document after strict parsing, before lowering. */
+interface PolicySource {
+    apiVersion: 'armor.io/v2';
+    kind: 'Policy';
+    metadata: {
+        name: string;
+        description?: string;
+        orgId?: string;
+        labels?: Record<string, string>;
+    };
+    target: SourceTarget;
+    precedence?: 'device-first' | 'agent-first';
+    spec: PolicySpec;
+}
+type SourceTarget = {
+    agent: string;
+    mcpServers?: string[];
+} | {
+    group: string;
+} | {
+    org: '*';
+} | {
+    device: 'local';
+};
+interface PolicySpec {
+    tools: ToolsSection;
+    files?: {
+        deny?: string[];
+        allowOutsideWorkspace?: boolean;
+    };
+    network?: {
+        default?: Verdict;
+        allow?: NetworkEntry[];
+        deny?: NetworkEntry[];
+    };
+    skills?: {
+        default?: Verdict;
+        hold?: string[];
+        block?: string[];
+    };
+    secrets?: {
+        envBlocklist?: string[];
+    };
+    members?: Record<string, Overlay>;
+    products?: Record<string, Overlay>;
+    capture?: {
+        arguments?: boolean;
+        redact?: string[];
+        maxBytesPerCall?: number;
+        sample?: number;
+    };
+    approvalDefaults?: Approval;
+    expiresAt: string;
+}
+type NetworkEntry = string | {
+    host: string;
+    reason?: string;
+};
+interface ToolsSection {
+    default: Verdict;
+    rules?: Record<string, RuleValue>;
+}
+interface Overlay {
+    tools?: {
+        default?: Verdict;
+        rules?: Record<string, RuleValue>;
+    };
+    expiresAt: string;
+}
+/** A scalar verdict is shorthand for one unconditional variant. */
+type RuleValue = Verdict | RuleVariant[];
+interface RuleVariant {
+    action: Verdict;
+    when?: Record<string, ConditionSpec>;
+    approval?: Approval;
+    reason?: string;
+    controls?: string[];
+    expiresAt: string;
+}
+/** `{gt: 5000}`, `{in: [a, b]}`, `{matches: '^x'}`, `{exists: true}`. Exactly one operator. */
+type ConditionSpec = Partial<Record<SourceOperator, unknown>>;
+declare const SOURCE_OPERATORS: readonly ["eq", "neq", "in", "notIn", "gt", "gte", "lt", "lte", "matches", "notMatches", "startsWith", "glob", "withinWorkspace", "exists"];
+type SourceOperator = (typeof SOURCE_OPERATORS)[number];
+declare const VERDICTS: readonly Verdict[];
+declare const NEVER = "never";
+
+interface ParseResult {
+    source: PolicySource | null;
+    diagnostics: Diagnostics;
+}
+/** Parse `armor.io/v2` YAML text strictly. */
+declare function parseYaml(text: string): ParseResult;
+/** Parse an already-loaded YAML/JSON value strictly. */
+declare function parseDocument(value: unknown): ParseResult;
+
+/**
+ * Everything that can be checked without an inventory. Inventory-dependent
+ * checks (roster clamp, glob collisions on real tools, schema binding) live in
+ * the compiler.
+ */
+declare function validate(source: PolicySource): Diagnostics;
+
+/** One tool the target can reach, as the inventory knows it. */
+interface InventoryTool {
+    /** The wire name the model sees; for an MCP tool the host may also supply the qualified `mcp__<server>__<tool>` form as `qualifiedName`. */
+    name: string;
+    qualifiedName?: string;
+    owner: {
+        type: 'mcp_server' | 'agent' | 'local';
+        id: string;
+        name?: string;
+    };
+    schemaHash: string | null;
+    inputSchema?: unknown;
+    capabilities?: string[];
+    /** False for a row the observed feed created and no owner has declared: the compiler warns instead of binding. */
+    declared: boolean;
+}
+/** What a host implements: conmap on `tool_snapshots`, the Armor CLI on the local tool list. */
+interface InventoryPort {
+    toolsForTarget(target: SourceTarget): Promise<InventoryTool[]>;
+}
+declare const CAPABILITY_KEYS: ReadonlySet<string>;
+
+type Enforceability = 'enforced' | 'argument-only' | 'inert';
+type Section = 'tools' | 'files' | 'network' | 'skills' | 'secrets';
+/**
+ * Per-section honesty (FR-9, FR-19): a local device sees real paths and
+ * hosts; the enterprise SDK path sees only path-shaped and URL-shaped
+ * arguments; skills and secrets have no enterprise surface at all.
+ */
+interface EnforceabilityReport {
+    sections: Partial<Record<Section, Enforceability>>;
+    /** Tools in the inventory that no capability rule reaches, when the document uses capability keys (M-12). */
+    notCoveredByCapabilityRules: string[];
+}
+declare function enforceabilityReport(source: PolicySource, inventory: InventoryTool[]): EnforceabilityReport;
+
+interface CompileOptions {
+    policyId: string;
+    source?: Statement['provenance']['source'];
+}
+interface CompileResult {
+    document: PolicyDocument | null;
+    diagnostics: Diagnostics;
+    report: EnforceabilityReport;
+}
+/** Validate, clamp against the inventory, lower to IR, hash. Synchronous once the inventory is in hand. */
+declare function compile(source: PolicySource, inventory: InventoryTool[], options: CompileOptions): CompileResult;
+declare function compileWithPort(source: PolicySource, port: InventoryPort, options: CompileOptions): Promise<CompileResult>;
+
+/**
+ * PolicySource back to YAML such that `parse(serialize(x))` equals `x`
+ * (VC-10). A single unconditional variant with no other fields is written as
+ * the scalar shorthand; `expiresAt: never` is written only where the parser
+ * would not materialize it identically anyway (everywhere), so it is kept.
+ */
+declare function serialize(source: PolicySource): string;
+
+type KeyKind = 'exact' | 'glob' | 'capability';
+interface ResolvedKey {
+    kind: KeyKind;
+    /** For an exact key: the one inventory tool it binds, when declared. */
+    tool: InventoryTool | null;
+}
+/**
+ * Tell a rule key's kind apart by lookup, not by syntax: a glob if it has
+ * wildcards, a capability if it names a known capability or a tag the
+ * inventory carries, else an exact tool name clamped against the inventory
+ * (VC-8). A bare name declared by more than one owner is an error that asks
+ * for the qualified form.
+ */
+declare function resolveKey(key: string, inventory: InventoryTool[], diag: Diagnostics, path: string): ResolvedKey;
+/** Two same-length globs matching one real tool is rejected at compile time (VC-4). */
+declare function checkGlobCollisions(keys: string[], inventory: InventoryTool[], diag: Diagnostics, path: string): void;
+/** An `args.*` key the tool's schema does not declare is a warning (VC-9). */
+declare function checkArgumentKeys(fields: string[], tool: InventoryTool, diag: Diagnostics, path: string): void;
+
+declare const KNOWN_CONTROLS: ReadonlySet<string>;
+
+export { type Approval, type BoundDocuments, CAPABILITY_KEYS, type CallInput, type Capture, type CompileOptions, type CompileResult, type Condition, type ConditionOp, type ConditionSpec, type Defaults, type Diagnostic, Diagnostics, type Enforceability, type EnforceabilityReport, type Evaluation, HASH_PREFIX, type InventoryPort, type InventoryTool, KNOWN_CONTROLS, type KeyTier, type Layer, NEVER, type NetworkEntry, type Obligation, type Overlay, type ParseResult, type PolicyDocument, type PolicySource, type PolicySpec, type PolicyTarget, type Principal, type Provenance, type RuleValue, type RuleVariant, SCHEMA_VERSION, SOURCE_OPERATORS, type SchemaBinding, type SchemaDriftObligation, type Section, type Severity, type SourceOperator, type SourceTarget, type Statement, type StatementMatch, type Subject, type ToolsSection, VERDICTS, VERDICT_RANK, type Verdict, type VerdictProvenance, canonicalJson, checkArgumentKeys, checkGlobCollisions, compile, compileWithPort, conditionHolds, conditionsHold, enforceabilityReport, evaluate, globToRegExp, isGlob, layerOfTarget, matchGlob, parseDocument, parseYaml, policyHash, resolveField, resolveKey, schemaHash, selectRuleKey, serialize, sha256Canonical, stricter, validate, verifyPolicyHash };