@odingard/guardian-sdk 0.1.0 → 0.2.0

package/dist-dts/contracts/obligation.d.ts

@@ -0,0 +1,196 @@
+import { z } from "zod";
+import type { StepUpLevel } from "./multi-principal.js";
+/**
+ * WO-023: guardian.obligation.v1 — declarative obligations.
+ *
+ * An obligation is a human-authored condition attached to an intent: "ALLOW,
+ * provided these conditions are satisfied." Obligations are declarative
+ * inputs to the ONE authority kernel (directive §89, K15): they never add a
+ * verdict (the triad stays ALLOW/ASK/DENY), never widen a grant, and never
+ * issue authority. This evaluator is pure and read-only — it may look at the
+ * context and return a state; it cannot broaden authority, mint
+ * capabilities, or bypass the existing ASK machinery.
+ *
+ * Evaluation phases (§11–12):
+ *   - "decision"  — mechanical verifiers settled deterministically at the
+ *                   decision point (satisfied | failed).
+ *   - "human"     — human-facing conditions that force the existing ASK
+ *                   machinery (step-up / second approver / quorum compose
+ *                   with the WO-019 approval chain).
+ *   - "post_action" — recorded as pending and transitioned by evidence or
+ *                   the sweeper; unfulfilled ones surface as overdue, never
+ *                   silently dropped.
+ *   - "time"      — pending until a derived due instant elapses.
+ *   - "unwired"   — types with no verifier in this build: they evaluate
+ *                   `failed` with rule OBLIGATION_VERIFIER_UNAVAILABLE and
+ *                   therefore DENY (fail-closed).
+ */
+export declare const OBLIGATION_CONTRACT_SCHEMA = "guardian.obligation.v1";
+/** All 23 obligation types named by directive §12. */
+export declare const ObligationTypeSchema: z.ZodEnum<{
+    log: "log";
+    retain_receipt: "retain_receipt";
+    notify: "notify";
+    delay: "delay";
+    cooling_period: "cooling_period";
+    delete_after_use: "delete_after_use";
+    redact: "redact";
+    encrypt: "encrypt";
+    tokenize: "tokenize";
+    minimize: "minimize";
+    verify_counterparty: "verify_counterparty";
+    verify_resource: "verify_resource";
+    verify_effect: "verify_effect";
+    attest_runtime: "attest_runtime";
+    require_consent: "require_consent";
+    require_location: "require_location";
+    require_device: "require_device";
+    require_network: "require_network";
+    require_contract: "require_contract";
+    step_up: "step_up";
+    second_approver: "second_approver";
+    quorum: "quorum";
+    authenticate: "authenticate";
+}>;
+export type ObligationType = z.infer<typeof ObligationTypeSchema>;
+/** Bounded, deterministic per-type params (fields[], seconds, quorumSize, level...). */
+export declare const ObligationParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
+export type ObligationParams = z.infer<typeof ObligationParamsSchema>;
+export declare const ObligationSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        log: "log";
+        retain_receipt: "retain_receipt";
+        notify: "notify";
+        delay: "delay";
+        cooling_period: "cooling_period";
+        delete_after_use: "delete_after_use";
+        redact: "redact";
+        encrypt: "encrypt";
+        tokenize: "tokenize";
+        minimize: "minimize";
+        verify_counterparty: "verify_counterparty";
+        verify_resource: "verify_resource";
+        verify_effect: "verify_effect";
+        attest_runtime: "attest_runtime";
+        require_consent: "require_consent";
+        require_location: "require_location";
+        require_device: "require_device";
+        require_network: "require_network";
+        require_contract: "require_contract";
+        step_up: "step_up";
+        second_approver: "second_approver";
+        quorum: "quorum";
+        authenticate: "authenticate";
+    }>;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
+}, z.core.$strict>;
+export type Obligation = z.infer<typeof ObligationSchema>;
+export declare const ObligationStateValueSchema: z.ZodEnum<{
+    satisfied: "satisfied";
+    pending: "pending";
+    failed: "failed";
+    not_applicable: "not_applicable";
+}>;
+export type ObligationStateValue = z.infer<typeof ObligationStateValueSchema>;
+/** Outcome rules reported on each obligation state. */
+export declare const ObligationRuleSchema: z.ZodEnum<{
+    OBLIGATION_SATISFIED: "OBLIGATION_SATISFIED";
+    PENDING_POST_ACTION: "PENDING_POST_ACTION";
+    PENDING_TIME: "PENDING_TIME";
+    PENDING_HUMAN: "PENDING_HUMAN";
+    OBLIGATION_PARAMS_INVALID: "OBLIGATION_PARAMS_INVALID";
+    COUNTERPARTY_UNVERIFIED: "COUNTERPARTY_UNVERIFIED";
+    RESOURCE_NOT_COVERED: "RESOURCE_NOT_COVERED";
+    OBLIGATION_VERIFIER_UNAVAILABLE: "OBLIGATION_VERIFIER_UNAVAILABLE";
+}>;
+export type ObligationRule = z.infer<typeof ObligationRuleSchema>;
+export declare const ObligationStateSchema: z.ZodObject<{
+    obligationType: z.ZodEnum<{
+        log: "log";
+        retain_receipt: "retain_receipt";
+        notify: "notify";
+        delay: "delay";
+        cooling_period: "cooling_period";
+        delete_after_use: "delete_after_use";
+        redact: "redact";
+        encrypt: "encrypt";
+        tokenize: "tokenize";
+        minimize: "minimize";
+        verify_counterparty: "verify_counterparty";
+        verify_resource: "verify_resource";
+        verify_effect: "verify_effect";
+        attest_runtime: "attest_runtime";
+        require_consent: "require_consent";
+        require_location: "require_location";
+        require_device: "require_device";
+        require_network: "require_network";
+        require_contract: "require_contract";
+        step_up: "step_up";
+        second_approver: "second_approver";
+        quorum: "quorum";
+        authenticate: "authenticate";
+    }>;
+    state: z.ZodEnum<{
+        satisfied: "satisfied";
+        pending: "pending";
+        failed: "failed";
+        not_applicable: "not_applicable";
+    }>;
+    rule: z.ZodEnum<{
+        OBLIGATION_SATISFIED: "OBLIGATION_SATISFIED";
+        PENDING_POST_ACTION: "PENDING_POST_ACTION";
+        PENDING_TIME: "PENDING_TIME";
+        PENDING_HUMAN: "PENDING_HUMAN";
+        OBLIGATION_PARAMS_INVALID: "OBLIGATION_PARAMS_INVALID";
+        COUNTERPARTY_UNVERIFIED: "COUNTERPARTY_UNVERIFIED";
+        RESOURCE_NOT_COVERED: "RESOURCE_NOT_COVERED";
+        OBLIGATION_VERIFIER_UNAVAILABLE: "OBLIGATION_VERIFIER_UNAVAILABLE";
+    }>;
+    detail: z.ZodOptional<z.ZodString>;
+    dueEpochMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type ObligationState = z.infer<typeof ObligationStateSchema>;
+export type ObligationPhase = "decision" | "human" | "post_action" | "time" | "unwired";
+export declare function obligationPhase(type: ObligationType): ObligationPhase;
+export declare function isHumanFacingObligation(type: ObligationType): boolean;
+/** True for pending obligations the sweeper completes when due time passes. */
+export declare function isTimeElapsedObligation(type: ObligationType): boolean;
+/** True for obligations that run as recorded parameter transforms. */
+export declare function isTransformObligation(type: ObligationType): boolean;
+/** Read-only facts the evaluator may consult. It cannot mutate or mint. */
+export type ObligationContext = Readonly<{
+    nowEpochMs: number;
+    /** The action's declared counterparty (merchant) label, if any. */
+    merchantId?: string | undefined;
+    /** The action's resource ref. */
+    resource: string;
+    /** Counterparties declared on the enclosing intent (absent = none declared). */
+    intentCounterparties?: readonly string[] | undefined;
+    /** Resources declared on the enclosing intent (absent = unconstrained). */
+    intentResources?: readonly string[] | undefined;
+    /** True when the narrowed authority chain still covers this action. */
+    chainCoversAction: boolean;
+}>;
+export declare function positiveIntParam(params: ObligationParams | undefined, key: string): number | null;
+export declare function stringArrayParam(params: ObligationParams | undefined, key: string): readonly string[] | null;
+export declare function stringParam(params: ObligationParams | undefined, key: string): string | null;
+/**
+ * Pure obligation evaluation. Deterministic and read-only: identical inputs
+ * always produce identical states and the evaluator issues no authority.
+ */
+export declare function evaluateObligation(obligation: Obligation, context: ObligationContext): ObligationState;
+/**
+ * Deterministically evaluate every declared obligation, in declared order.
+ */
+export declare function evaluateObligations(obligations: readonly Obligation[], context: ObligationContext): readonly ObligationState[];
+/** First failed state, if any — a failed/unsettleable obligation denies. */
+export declare function firstFailedObligation(states: readonly ObligationState[]): ObligationState | null;
+/**
+ * Human-facing obligations raise the WO-019 approval requirement. This
+ * composes step_up → requiredFactor and second_approver/quorum →
+ * requiredApprovals; it never lowers an existing requirement.
+ */
+export declare function obligationApprovalRequirement(obligations: readonly Obligation[]): {
+    requiredFactor?: StepUpLevel;
+    requiredApprovals?: number;
+};

package/dist-dts/contracts/plan.d.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+import type { IntentContract } from "./intent.js";
+/**
+ * WO-022: guardian.plan.v1 — Plan Authority.
+ *
+ * A plan is a PROPOSAL, never authority. It decomposes an intent into an
+ * ordered task graph; submitting one enlarges nothing. The gateway's
+ * intent pre-gate uses plan task membership only to bind taskId → plan →
+ * intent provenance. Scope validation (validatePlanAgainstIntent) runs at
+ * submission so a plan cannot even propose work outside its intent.
+ */
+export declare const PLAN_CONTRACT_SCHEMA = "guardian.plan.v1";
+export declare const PlanStatusSchema: z.ZodEnum<{
+    draft: "draft";
+    active: "active";
+    revoked: "revoked";
+    completed: "completed";
+}>;
+export type PlanStatus = z.infer<typeof PlanStatusSchema>;
+export declare const PlanNodeSchema: z.ZodObject<{
+    taskId: z.core.$ZodBranded<z.ZodString, "TaskId", "out">;
+    title: z.ZodString;
+    actionFamily: z.ZodOptional<z.ZodString>;
+    actionIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    agentId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "AgentId", "out">>;
+    dependsOn: z.ZodArray<z.core.$ZodBranded<z.ZodString, "TaskId", "out">>;
+}, z.core.$strict>;
+export type PlanNode = z.infer<typeof PlanNodeSchema>;
+export declare const PlanContractSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"guardian.plan.v1">;
+    planId: z.core.$ZodBranded<z.ZodString, "PlanId", "out">;
+    intentId: z.core.$ZodBranded<z.ZodString, "IntentId", "out">;
+    tenantId: z.core.$ZodBranded<z.ZodString, "TenantId", "out">;
+    principalId: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+    createdBy: z.ZodString;
+    title: z.ZodString;
+    nodes: z.ZodArray<z.ZodObject<{
+        taskId: z.core.$ZodBranded<z.ZodString, "TaskId", "out">;
+        title: z.ZodString;
+        actionFamily: z.ZodOptional<z.ZodString>;
+        actionIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        agentId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "AgentId", "out">>;
+        dependsOn: z.ZodArray<z.core.$ZodBranded<z.ZodString, "TaskId", "out">>;
+    }, z.core.$strict>>;
+    status: z.ZodEnum<{
+        draft: "draft";
+        active: "active";
+        revoked: "revoked";
+        completed: "completed";
+    }>;
+    version: z.ZodNumber;
+    createdAtEpochMs: z.ZodNumber;
+}, z.core.$strict>;
+export type PlanContract = z.infer<typeof PlanContractSchema>;
+export type PlanValidationFailure = "PLAN_DUPLICATE_TASK" | "PLAN_UNKNOWN_DEPENDENCY" | "PLAN_FORWARD_DEPENDENCY" | "PLAN_CYCLE";
+/** Structural DAG validation: unique taskIds, resolvable backward-only
+ *  dependsOn references, acyclic. */
+export declare function validatePlanDag(nodes: readonly PlanNode[]): PlanValidationFailure | null;
+export type PlanScopeFailure = "PLAN_TASK_FAMILY_OUT_OF_SCOPE" | "PLAN_TASK_ACTIONS_OUT_OF_SCOPE" | "PLAN_TASK_AGENT_UNAUTHORIZED";
+/**
+ * Every task a plan proposes must fit inside the intent: declared families
+ * must be in allowedActionFamilies (when the intent constrains them), and
+ * declared agents must be in authorizedAgents.
+ */
+export declare function validatePlanAgainstIntent(plan: Pick<PlanContract, "nodes">, intent: Pick<IntentContract, "allowedActionFamilies" | "authorizedAgents">): PlanScopeFailure | null;
+/** Whether any active plan contains the given taskId. */
+export declare function planContainsTask(plan: Pick<PlanContract, "nodes" | "status">, taskId: string): boolean;