glirastes 0.3.2 → 0.5.0

package/dist/contracts/tool-policy-entry.d.ts

@@ -0,0 +1,107 @@
+import { z } from 'zod';
+/**
+ * Leaf module of the policy contract. `revisions.ts` (signed Platform
+ * revisions) and `tool-policy.ts` (local policy resolution) both import it
+ * and it imports neither, so the two never form an ESM import cycle.
+ */
+export declare const ToolRiskClassSchema: z.ZodEnum<{
+    unknown: "unknown";
+    "safe-read": "safe-read";
+    "read-sensitive": "read-sensitive";
+    write: "write";
+    delete: "delete";
+    financial: "financial";
+    external: "external";
+}>;
+export type ToolRiskClass = z.infer<typeof ToolRiskClassSchema>;
+export declare const ToolPolicyPinSchema: z.ZodObject<{
+    toolId: z.ZodUUID;
+    atRiskClass: z.ZodEnum<{
+        unknown: "unknown";
+        "safe-read": "safe-read";
+        "read-sensitive": "read-sensitive";
+        write: "write";
+        delete: "delete";
+        financial: "financial";
+        external: "external";
+    }>;
+}, z.core.$strict>;
+/** One policy layer entry: the same shape for local files and Platform deltas. */
+export declare const ToolPolicyEntrySchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    requiresApproval: z.ZodOptional<z.ZodBoolean>;
+    riskClass: z.ZodOptional<z.ZodEnum<{
+        unknown: "unknown";
+        "safe-read": "safe-read";
+        "read-sensitive": "read-sensitive";
+        write: "write";
+        delete: "delete";
+        financial: "financial";
+        external: "external";
+    }>>;
+    allowedRoles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    description: z.ZodOptional<z.ZodString>;
+    reason: z.ZodOptional<z.ZodString>;
+    pin: z.ZodOptional<z.ZodObject<{
+        toolId: z.ZodUUID;
+        atRiskClass: z.ZodEnum<{
+            unknown: "unknown";
+            "safe-read": "safe-read";
+            "read-sensitive": "read-sensitive";
+            write: "write";
+            delete: "delete";
+            financial: "financial";
+            external: "external";
+        }>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export interface ToolPolicyEntry {
+    enabled?: boolean;
+    requiresApproval?: boolean;
+    riskClass?: ToolRiskClass;
+    allowedRoles?: string[];
+    description?: string;
+    reason?: string;
+    pin?: {
+        toolId: string;
+        atRiskClass: ToolRiskClass;
+    };
+}
+/**
+ * A signed Platform decision for one tool the deployed code reported
+ * (P08b shared contract item 1): only fields an operator decided, never a
+ * copy of the local value. The runtime applies its restrictions, and its
+ * `requiresApproval: false` only as the pinned D16 relaxation up to tier 2.
+ */
+export declare const ToolOverrideDeltaSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    requiresApproval: z.ZodOptional<z.ZodBoolean>;
+    riskClass: z.ZodOptional<z.ZodEnum<{
+        unknown: "unknown";
+        "safe-read": "safe-read";
+        "read-sensitive": "read-sensitive";
+        write: "write";
+        delete: "delete";
+        financial: "financial";
+        external: "external";
+    }>>;
+    allowedRoles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    description: z.ZodOptional<z.ZodString>;
+    reason: z.ZodOptional<z.ZodString>;
+    pin: z.ZodOptional<z.ZodObject<{
+        toolId: z.ZodUUID;
+        atRiskClass: z.ZodEnum<{
+            unknown: "unknown";
+            "safe-read": "safe-read";
+            "read-sensitive": "read-sensitive";
+            write: "write";
+            delete: "delete";
+            financial: "financial";
+            external: "external";
+        }>;
+    }, z.core.$strict>>;
+    toolId: z.ZodUUID;
+}, z.core.$strict>;
+export type ToolOverrideDelta = {
+    toolId: string;
+} & ToolPolicyEntry;

package/dist/contracts/tool-policy-entry.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+/**
+ * Leaf module of the policy contract. `revisions.ts` (signed Platform
+ * revisions) and `tool-policy.ts` (local policy resolution) both import it
+ * and it imports neither, so the two never form an ESM import cycle.
+ */
+export const ToolRiskClassSchema = z.enum([
+    'safe-read',
+    'read-sensitive',
+    'write',
+    'delete',
+    'financial',
+    'external',
+    'unknown',
+]);
+const boundedText = (max) => z.string().trim().min(1).max(max);
+export const ToolPolicyPinSchema = z.object({
+    toolId: z.uuid(),
+    atRiskClass: ToolRiskClassSchema,
+}).strict();
+/** One policy layer entry: the same shape for local files and Platform deltas. */
+export const ToolPolicyEntrySchema = z.object({
+    enabled: z.boolean().optional(),
+    requiresApproval: z.boolean().optional(),
+    riskClass: ToolRiskClassSchema.optional(),
+    allowedRoles: z.array(boundedText(200)).max(100).optional(),
+    description: boundedText(4_000).optional(),
+    reason: boundedText(500).optional(),
+    pin: ToolPolicyPinSchema.optional(),
+}).strict();
+/**
+ * A signed Platform decision for one tool the deployed code reported
+ * (P08b shared contract item 1): only fields an operator decided, never a
+ * copy of the local value. The runtime applies its restrictions, and its
+ * `requiresApproval: false` only as the pinned D16 relaxation up to tier 2.
+ */
+export const ToolOverrideDeltaSchema = ToolPolicyEntrySchema.extend({
+    toolId: z.uuid(),
+}).strict();
+//# sourceMappingURL=tool-policy-entry.js.map

package/dist/contracts/tool-policy-entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-policy-entry.js","sourceRoot":"","sources":["../../src/contracts/tool-policy-entry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,IAAI,CAAC;IACxC,WAAW;IACX,gBAAgB;IAChB,OAAO;IACP,QAAQ;IACR,WAAW;IACX,UAAU;IACV,SAAS;CACV,CAAC,CAAC;AAIH,MAAM,WAAW,GAAG,CAAC,GAAW,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAEvE,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE;IAChB,WAAW,EAAE,mBAAmB;CACjC,CAAC,CAAC,MAAM,EAAE,CAAC;AAEZ,kFAAkF;AAClF,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC/B,gBAAgB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IACxC,SAAS,EAAE,mBAAmB,CAAC,QAAQ,EAAE;IACzC,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAC3D,WAAW,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE;IAC1C,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IACnC,GAAG,EAAE,mBAAmB,CAAC,QAAQ,EAAE;CACpC,CAAC,CAAC,MAAM,EAAE,CAAC;AAYZ;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,qBAAqB,CAAC,MAAM,CAAC;IAClE,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE;CACjB,CAAC,CAAC,MAAM,EAAE,CAAC"}

package/dist/contracts/tool-policy.d.ts

@@ -0,0 +1,198 @@
+import { z } from 'zod';
+import { type ToolPolicyEntry, type ToolRiskClass } from './tool-policy-entry.js';
+export { ToolOverrideDeltaSchema, ToolPolicyEntrySchema, ToolPolicyPinSchema, } from './tool-policy-entry.js';
+export type { ToolOverrideDelta, ToolPolicyEntry } from './tool-policy-entry.js';
+/**
+ * Version of the default table and the policy bounds below. The golden
+ * vectors in `__vectors__/tool-policy.v1.json` pin it; the Platform port
+ * must produce byte-identical results for the same version.
+ */
+export declare const TOOL_POLICY_RULES_VERSION: 1;
+export type RiskTier = 0 | 1 | 2 | 3;
+/** Fails closed: an out-of-enum class is tier 3, like `unknown`. */
+export declare function riskTier(riskClass: ToolRiskClass): RiskTier;
+/**
+ * The runtime confirmation floor: tier 3 always asks before it runs,
+ * whatever any policy layer says.
+ */
+export declare function confirmationFloor(riskClass: ToolRiskClass, requiresApproval: boolean): boolean;
+export type ConfirmationRelaxationOutcome = 'applies' | 'pin-for-other-tool' | 'relaxation-requires-reviewed-pin' | 'tier-3-always-requires-approval' | 'override-lapsed-risk-raised';
+/**
+ * The one relaxation rule (spec 4.5, D16), shared by `resolveToolPolicy` and
+ * the runtime overlay: whether a `requiresApproval: false` entry with this pin
+ * takes effect at the effective risk class. A pin for another tool id (an
+ * earlier incarnation) lapses. Tier 0-1 relaxes freely. From tier 2 on the
+ * entry needs a reviewed pin at a tier-2 class the effective class does not
+ * exceed, so the relaxation lapses as soon as the risk rises. Tier 3 never
+ * relaxes, pinned or not.
+ */
+export declare function confirmationRelaxationOutcome(toolId: string, pin: ToolPolicyEntry['pin'], riskClass: ToolRiskClass): ConfirmationRelaxationOutcome;
+/**
+ * D16 local lock: may a signed Platform decision switch off this tool's
+ * confirmation at all? Only a confirmation the local code report attributes
+ * to the code default, on a tool of tier 0-2. Whatever tool-policy.json
+ * decided (an explicit `requiresApproval: true`, or a risk raise that brings
+ * confirmation) and an origin the report does not name are local locks the
+ * Platform never relaxes; tier 3 always confirms.
+ */
+export declare function platformMayRelaxConfirmation(riskClass: ToolRiskClass, requiresApprovalOrigin: PolicyOrigin | undefined): boolean;
+/**
+ * Raise-only combination. A candidate replaces the current class only from a
+ * strictly higher tier; a same-tier relabel or a lower class never applies.
+ * An out-of-enum candidate raises as `unknown`, so none enters the result.
+ */
+export declare function mostRestrictiveRiskClass(current: ToolRiskClass, candidate: ToolRiskClass | undefined): ToolRiskClass;
+export interface AllowedRolesIntersection {
+    /** Sorted, de-duplicated roles; empty means "no additional restriction". */
+    roles: string[];
+    /** Both sides restrict and nothing is left: nobody may call the tool. */
+    disjoint: boolean;
+}
+export declare function intersectAllowedRoles(current: ReadonlyArray<string>, restriction: ReadonlyArray<string> | undefined): AllowedRolesIntersection;
+export type DeclaredEffect = 'read' | 'write' | 'destructive' | 'external' | 'financial';
+export interface ToolPolicyDefaultsInput {
+    executionKind: 'endpoint' | 'ui';
+    method?: string;
+    path?: string;
+    definitionId: string;
+    declaredEffect?: DeclaredEffect;
+    evidence?: {
+        externalCall?: boolean;
+        uiMutation?: boolean;
+    };
+}
+export interface ToolPolicyDefaults {
+    operationGroup: 'read' | 'create' | 'update' | 'delete' | 'ui';
+    riskClass: Exclude<ToolRiskClass, 'unknown'>;
+    requiresApproval: boolean;
+    rulesVersion: typeof TOOL_POLICY_RULES_VERSION;
+}
+type AssessedRiskClass = Exclude<ToolRiskClass, 'unknown'>;
+/**
+ * The risk class a declared effect stands for. `deriveToolPolicyDefaults`
+ * raises to it, and anything that checks an effect against the code's class
+ * (the agent resolution gate) must read it here, never from a copy.
+ */
+export declare function declaredEffectRiskClass(effect: DeclaredEffect): AssessedRiskClass;
+/**
+ * Deterministic stage-1 defaults (spec 4.5). Escalations only ever raise;
+ * `unknown` is never produced. Roles are not part of the defaults: the
+ * endpoint's own authorization applies.
+ */
+export declare function deriveToolPolicyDefaults(input: ToolPolicyDefaultsInput): ToolPolicyDefaults;
+/** `src/components/ui-size-provider.tsx#setSize`: the file that declares a control and its setter. */
+export declare const CONTROL_REF: RegExp;
+/**
+ * `.glirastes/tool-policy.json`. Written by the developer or the CLI only,
+ * never by an agent; `tools refresh` never rewrites it.
+ */
+export declare const ToolPolicyFileSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    tools: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        requiresApproval: z.ZodOptional<z.ZodBoolean>;
+        riskClass: z.ZodOptional<z.ZodEnum<{
+            unknown: "unknown";
+            "safe-read": "safe-read";
+            "read-sensitive": "read-sensitive";
+            write: "write";
+            delete: "delete";
+            financial: "financial";
+            external: "external";
+        }>>;
+        allowedRoles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        description: z.ZodOptional<z.ZodString>;
+        reason: z.ZodOptional<z.ZodString>;
+        pin: z.ZodOptional<z.ZodObject<{
+            toolId: z.ZodUUID;
+            atRiskClass: z.ZodEnum<{
+                unknown: "unknown";
+                "safe-read": "safe-read";
+                "read-sensitive": "read-sensitive";
+                write: "write";
+                delete: "delete";
+                financial: "financial";
+                external: "external";
+            }>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+    exclude: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        match: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strict>>>;
+    acceptedRisk: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        riskClass: z.ZodEnum<{
+            unknown: "unknown";
+            "safe-read": "safe-read";
+            "read-sensitive": "read-sensitive";
+            write: "write";
+            delete: "delete";
+            financial: "financial";
+            external: "external";
+        }>;
+        toolId: z.ZodUUID;
+    }, z.core.$strict>>>;
+    excludeControls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        control: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type ToolPolicyFile = z.infer<typeof ToolPolicyFileSchema>;
+export declare function parseToolPolicyFile(value: unknown): ToolPolicyFile;
+export type PolicyOrigin = 'code-default' | 'local-policy' | 'platform';
+export interface EffectiveToolPolicy {
+    enabled: boolean;
+    requiresApproval: boolean;
+    riskClass: ToolRiskClass;
+    allowedRoles: string[];
+    description?: string;
+    origin: {
+        enabled: PolicyOrigin;
+        requiresApproval: PolicyOrigin;
+        riskClass: PolicyOrigin;
+        allowedRoles: PolicyOrigin;
+        description: PolicyOrigin;
+    };
+}
+export type ToolPolicyWarningCode = 'override-lapsed-risk-raised' | 'risk-lower-available' | 'policy-entry-orphaned';
+export interface ResolveToolPolicyInput {
+    toolId: string;
+    defaults: ToolPolicyDefaults;
+    /** False for needs_attention, excluded or missing tools; nothing re-enables them. */
+    codeEnabled: boolean;
+    local?: ToolPolicyEntry;
+    platform?: ToolPolicyEntry;
+    /**
+     * Releases a held `risk-lower-available` decrease. `riskClass` is matched
+     * exactly against the layered class (code defaults plus local/Platform
+     * raises), not the class the code alone derives; record the `riskClass`
+     * that the `risk-lower-available` warning names.
+     */
+    acceptedRisk?: {
+        riskClass: ToolRiskClass;
+        toolId: string;
+    };
+    /** The riskClass this toolId resolved to in the previous committed refresh. */
+    previousEffectiveRiskClass?: ToolRiskClass;
+}
+export interface ResolveToolPolicyResult {
+    effective: EffectiveToolPolicy;
+    warnings: Array<{
+        code: ToolPolicyWarningCode;
+        field?: string;
+        /** `risk-lower-available` only: the class `acceptedRisk` must record. */
+        riskClass?: ToolRiskClass;
+    }>;
+    errors: Array<{
+        code: 'E-POLICY-001' | 'E-POLICY-002';
+        field: string;
+        reason: string;
+    }>;
+}
+/**
+ * Pure policy resolution shared with the Platform port via golden vectors.
+ * Code defaults are the base; local and Platform entries restrict, except a
+ * reviewed, pinned relaxation of confirmation up to tier 2. Across all layers
+ * the most restrictive protection value wins.
+ */
+export declare function resolveToolPolicy(input: ResolveToolPolicyInput): ResolveToolPolicyResult;