@odingard/guardian-sdk 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,169 @@
+import { z } from "zod";
+/**
+ * WO-027: guardian.multiparty.v1 — declarative multi-party approval
+ * structures (GUA-AUTHORITY-OS-001 §28–30).
+ *
+ * An approval structure declares WHICH human approvals must be recorded
+ * before consent can resolve: a single approver, an n-of-m quorum, a
+ * unanimous set, a role quorum, composable required members, vetoes,
+ * separation of duties, and temporary / delegated / emergency approvers.
+ * It is a pure declarative input: the approval service freezes the
+ * resolved structure into the approval binding at creation (consent can
+ * never widen), records each member's decision, and evaluates the
+ * structure deterministically. Nothing here enlarges authority — an
+ * unsatisfiable structure fails closed, a veto terminates as denied, and
+ * a declared cooling period keeps authority pending for its window.
+ */
+export declare const MULTIPARTY_CONTRACT_SCHEMA = "guardian.multiparty.v1";
+/** One roster entry: a member plus the role labels they hold under this structure. */
+export declare const StructureMemberSchema: z.ZodObject<{
+    memberId: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+    roles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type StructureMember = z.infer<typeof StructureMemberSchema>;
+/** The primary approval requirement — exactly one of four shapes. */
+export declare const StructureRequirementSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"single">;
+    memberId: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"nOfM">;
+    n: z.ZodNumber;
+    members: z.ZodArray<z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"unanimous">;
+    members: z.ZodArray<z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"roleQuorum">;
+    role: z.ZodString;
+    n: z.ZodNumber;
+    m: z.ZodNumber;
+}, z.core.$strict>], "kind">;
+export type StructureRequirement = z.infer<typeof StructureRequirementSchema>;
+/** §30 — a declared delay between satisfaction and resolved consent. */
+export declare const CoolingPeriodSchema: z.ZodObject<{
+    seconds: z.ZodNumber;
+}, z.core.$strict>;
+export type CoolingPeriod = z.infer<typeof CoolingPeriodSchema>;
+/** A member whose recorded approvals count only while unexpired. */
+export declare const TemporaryApproverSchema: z.ZodObject<{
+    memberId: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+    expiresAtEpochMs: z.ZodNumber;
+}, z.core.$strict>;
+export type TemporaryApprover = z.infer<typeof TemporaryApproverSchema>;
+/**
+ * A member who may act on behalf of a delegator. The delegate's authority can
+ * only narrow the delegator's — the delegator must itself be a structure
+ * member, so a delegate can never act for an authority the delegator lacks.
+ */
+export declare const DelegatedApproverSchema: z.ZodObject<{
+    memberId: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+    delegatedBy: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+}, z.core.$strict>;
+export type DelegatedApprover = z.infer<typeof DelegatedApproverSchema>;
+/**
+ * §28–29 — one declarative approval structure. `members` is the roster of
+ * principals the structure recognizes and the roles each holds (frozen into
+ * the binding, so a later roster edit cannot retroactively alter consent).
+ */
+export declare const ApprovalStructureSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"guardian.multiparty.v1">;
+    structureId: z.ZodString;
+    members: z.ZodArray<z.ZodObject<{
+        memberId: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+        roles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    requirement: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"single">;
+        memberId: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"nOfM">;
+        n: z.ZodNumber;
+        members: z.ZodArray<z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"unanimous">;
+        members: z.ZodArray<z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"roleQuorum">;
+        role: z.ZodString;
+        n: z.ZodNumber;
+        m: z.ZodNumber;
+    }, z.core.$strict>], "kind">;
+    specificRequired: z.ZodOptional<z.ZodArray<z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">>>;
+    veto: z.ZodOptional<z.ZodArray<z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">>>;
+    separationOfDuties: z.ZodOptional<z.ZodObject<{
+        mutuallyExclusive: z.ZodArray<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    temporaryApprovers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        memberId: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+        expiresAtEpochMs: z.ZodNumber;
+    }, z.core.$strict>>>;
+    delegatedApprovers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        memberId: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+        delegatedBy: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+    }, z.core.$strict>>>;
+    emergencyApprovers: z.ZodOptional<z.ZodArray<z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">>>;
+    coolingPeriod: z.ZodOptional<z.ZodObject<{
+        seconds: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ApprovalStructure = z.infer<typeof ApprovalStructureSchema>;
+/** Every principal a structure recognizes as a potential decision actor. */
+export declare function structureMemberIds(structure: ApprovalStructure): readonly string[];
+/** The approvals a structure's primary requirement calls for (for display). */
+export declare function structureRequiredCount(structure: ApprovalStructure): number;
+/** One member's recorded decision under a structure (append-only). */
+export declare const RecordedStructureApprovalSchema: z.ZodObject<{
+    memberId: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+    decision: z.ZodEnum<{
+        veto: "veto";
+        approve: "approve";
+        deny: "deny";
+    }>;
+    atEpochMs: z.ZodNumber;
+    via: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">>;
+    emergency: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strict>;
+export type RecordedStructureApproval = z.infer<typeof RecordedStructureApprovalSchema>;
+export declare const CoolingWindowSchema: z.ZodObject<{
+    startedAtEpochMs: z.ZodNumber;
+    endsAtEpochMs: z.ZodNumber;
+}, z.core.$strict>;
+export type CoolingWindow = z.infer<typeof CoolingWindowSchema>;
+export type ApprovalStructureEvaluation = Readonly<{
+    status: "satisfied";
+    approvedBy: readonly string[];
+}> | Readonly<{
+    status: "pending";
+    recordedCount: number;
+    requiredCount: number;
+    missing: readonly string[];
+    cooling?: Readonly<{
+        startedAtEpochMs: number;
+        endsAtEpochMs: number;
+        remainingMs: number;
+    }>;
+}> | Readonly<{
+    status: "vetoed";
+    by: string;
+}> | Readonly<{
+    status: "impossible";
+    reason: string;
+}>;
+/**
+ * Pure evaluator (§29): every recorded decision is replayed against the
+ * declared structure. First-recorded decision per member wins (append-only);
+ * a recorded veto by a veto-listed member terminates as vetoed; a recorded
+ * deny removes that member's ability to approve and can make the structure
+ * impossible; temporary approvals void once expired; delegated approvals count
+ * only under a declared delegation whose delegator is a roster member; a
+ * separation-of-duties violation is impossible; an emergency approval
+ * satisfies the requirement only when the context declares the emergency.
+ * The result only ever holds authority pending or closes it — never widens it.
+ */
+export declare function evaluateApprovalStructure(structure: ApprovalStructure, recorded: readonly RecordedStructureApproval[], ctx: {
+    nowEpochMs: number;
+    emergency?: boolean;
+    /** When the requirements were first satisfied (recorded by the caller). */
+    satisfiedAtEpochMs?: number;
+}): ApprovalStructureEvaluation;
+export declare function approvalStructureDigest(structure: ApprovalStructure): string;

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;