@armoriq/policy-ir 0.1.2 → 0.1.3

package/README.md

@@ -16,6 +16,7 @@ exported from this package, is what every evaluator must pass before release.
 | `policyHash(document)` | `sha256:` over the canonical document without `policyHash` |
 | `schemaHash(inputSchema)` | `sha256:` over the canonicalized tool input schema, as the SDKs and the tool inventory compute it |
 | `@armoriq/policy-ir/vectors` | the fixtures: canonical forms, policy hashes, schema hashes |
+| `@armoriq/policy-ir/document` | `parseYaml`, `parseDocument`, `validate`, `serialize` and the source grammar types, with no Node built-ins, for browsers |
 
 C0 is complete in this package; the conmap binding of the inventory port and the compile endpoint follow in conmap-auto.
 

package/dist/document-entry-CDOQVeis.d.cts

@@ -0,0 +1,229 @@
+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;
+}
+
+/**
+ * `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;
+
+/** 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;
+
+/**
+ * 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;
+
+export { type Approval as A, type Condition as C, Diagnostics as D, type KeyTier as K, type Layer as L, NEVER as N, type Overlay as O, type PolicyDocument as P, type RuleValue as R, type Statement as S, type ToolsSection as T, type Verdict as V, type SourceTarget as a, type PolicySource as b, type Capture as c, type ConditionOp as d, type ConditionSpec as e, type Defaults as f, type Diagnostic as g, type NetworkEntry as h, type ParseResult as i, type PolicySpec as j, type PolicyTarget as k, type Provenance as l, type RuleVariant as m, SCHEMA_VERSION as n, SOURCE_OPERATORS as o, type SchemaBinding as p, type Severity as q, type SourceOperator as r, type StatementMatch as s, type Subject as t, VERDICTS as u, layerOfTarget as v, parseDocument as w, parseYaml as x, serialize as y, validate as z };

package/dist/document-entry-CDOQVeis.d.ts

@@ -0,0 +1,229 @@
+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;
+}
+
+/**
+ * `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;
+
+/** 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;
+
+/**
+ * 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;
+
+export { type Approval as A, type Condition as C, Diagnostics as D, type KeyTier as K, type Layer as L, NEVER as N, type Overlay as O, type PolicyDocument as P, type RuleValue as R, type Statement as S, type ToolsSection as T, type Verdict as V, type SourceTarget as a, type PolicySource as b, type Capture as c, type ConditionOp as d, type ConditionSpec as e, type Defaults as f, type Diagnostic as g, type NetworkEntry as h, type ParseResult as i, type PolicySpec as j, type PolicyTarget as k, type Provenance as l, type RuleVariant as m, SCHEMA_VERSION as n, SOURCE_OPERATORS as o, type SchemaBinding as p, type Severity as q, type SourceOperator as r, type StatementMatch as s, type Subject as t, VERDICTS as u, layerOfTarget as v, parseDocument as w, parseYaml as x, serialize as y, validate as z };