@odingard/guardian-sdk 0.1.0 → 0.2.0

package/dist-dts/catalog.d.ts

@@ -0,0 +1,14 @@
+import catalog from "./catalog/public-catalog.v1.json";
+/**
+ * Guardian's public catalog metadata, generated from the canonical private
+ * catalog (`@odingard/guardian-catalog`) and synced verbatim. Declarative
+ * only: reading it grants nothing — every action is still decided at
+ * runtime by the Guardian authority path under a human's policy.
+ */
+export type GuardianPublicCatalog = typeof catalog;
+export type GuardianCatalogVertical = GuardianPublicCatalog["verticals"][number];
+export type GuardianCatalogAgentSystem = GuardianPublicCatalog["agentSystems"][number];
+export declare const guardianCatalog: GuardianPublicCatalog;
+/** Verticals whose catalog rows include `actionId`, with honest maturity. */
+export declare function verticalsForAction(actionId: string): readonly GuardianCatalogVertical[];
+export declare function findAgentSystem(systemPackId: string): GuardianCatalogAgentSystem | undefined;

package/dist-dts/client.d.ts

@@ -23,6 +23,16 @@ export type GuardianToolInvocation = Readonly<{
     arguments: Record<string, unknown>;
     adapterId?: string;
     purpose?: string;
+    /** WO-022 — optional intent/plan provenance bound into the action. */
+    intentId?: string;
+    planId?: string;
+    /**
+     * WO-024 — optional causal provenance: the recorded parent action
+     * (request id) and/or the recorded effect (attempt id) this action
+     * uses. Validated fail-closed against recorded evidence.
+     */
+    parentActionId?: string;
+    sourceEffectId?: string;
 }>;
 export type GuardianMcpInvocation = Readonly<{
     action: "mcp.install";
@@ -30,13 +40,39 @@ export type GuardianMcpInvocation = Readonly<{
     tool: McpInstallParametersV1["tool"];
     adapterId?: string;
     purpose?: string;
+    intentId?: string;
+    planId?: string;
+    parentActionId?: string;
+    sourceEffectId?: string;
 }> | Readonly<{
     action: "mcp.enable";
     connectionId: string;
     toolName: string;
     adapterId?: string;
     purpose?: string;
+    intentId?: string;
+    planId?: string;
+    parentActionId?: string;
+    sourceEffectId?: string;
+}>;
+/**
+ * WO-025 — minimal passthrough for the data-lineage + agent-communication
+ * actions. Callers supply the already-formed material parameters (the
+ * corresponding *V1Schema validates server-side); the SDK forwards them
+ * into the canonical proposal unchanged.
+ */
+export type GuardianGovernedInvocation = Readonly<{
+    action: "api.request" | "protected_data.derive" | "protected_data.transform" | "protected_data.export" | "agent.message" | "agent.share_context" | "agent.share_memory" | "agent.transfer_task" | "agent.transfer_capability";
+    connectionId: string;
+    materialParameters: Record<string, unknown>;
+    adapterId?: string;
+    purpose?: string;
+    intentId?: string;
+    planId?: string;
+    parentActionId?: string;
+    sourceEffectId?: string;
 }>;
+export type GuardianInvocation = GuardianToolInvocation | GuardianMcpInvocation | GuardianGovernedInvocation;
 export type GuardianRequestResult = {
     ok: true;
     requestId: string;
@@ -46,6 +82,8 @@ export type GuardianRequestResult = {
 } | {
     ok: false;
     reasonCode: string;
+    /** The proposal's request id — needed to `claim` after an ASK. */
+    requestId?: string;
 };
 export interface GuardianClient {
     /**
@@ -53,7 +91,7 @@ export interface GuardianClient {
      * capabilityToken immediately; ASK returns decision "ASK" and the human
      * approves out-of-band (then call `claim`); DENY refuses.
      */
-    request(invocation: GuardianToolInvocation | GuardianMcpInvocation): Promise<GuardianRequestResult>;
+    request(invocation: GuardianInvocation): Promise<GuardianRequestResult>;
     /** Collect a capability after human approval of a prior ASK. */
     claim(requestId: string): Promise<GuardianRequestResult>;
     /** Execute a held capability; resolves to the execution receipt. */
@@ -67,6 +105,18 @@ export interface GuardianClient {
         ok: false;
         reasonCode: string;
     }>;
+    /**
+     * WO-042 — the signed portable authority receipt (`greceipt.v1`) for a
+     * completed request. Verify it with `verifyReceiptOffline` (no Guardian
+     * credential or service needed) or `verifyReceiptOnline`.
+     */
+    portableReceipt(requestId: string): Promise<{
+        ok: true;
+        receipt: unknown;
+    } | {
+        ok: false;
+        reasonCode: string;
+    }>;
     /** Machine-readable proof for a request (WO-015 developer receipts). */
     receipts(requestId: string): Promise<{
         ok: true;

package/dist-dts/contracts/action-pack.d.ts

@@ -0,0 +1,464 @@
+import { z } from "zod";
+import { ActionDefinition } from "./action-registry.js";
+/**
+ * WO-021 — Action Pack v1 (`guardian.action.v1`).
+ *
+ * A signed, declarative package that defines one governed action: identity,
+ * family, resource type, risk class, reversibility, material parameters,
+ * required fields, approval display, verification method, compatibility,
+ * provenance, review state, rollback metadata, integrity digest and a trusted
+ * publisher's Ed25519 signature. Packs are inputs, never executables: nothing
+ * a pack declares is interpreted inside the authority kernel (K15). A pack
+ * whose signature, integrity, publisher trust, review state, compatibility or
+ * internal consistency fails is rejected at load time — the action it names
+ * stays unregistered, so every proposal deterministically DENYs (K14).
+ */
+export declare const ACTION_PACK_FORMAT = "guardian.action.v1";
+export declare const ACTION_PACK_DOMAIN = "odingard.guardian.action-pack.v1";
+export declare const ACTION_PACK_REGISTRY_COMPATIBILITY = 1;
+export declare const ACTION_PACK_MAX_FIELDS = 32;
+export declare const ACTION_PACK_MAX_DISPLAY_FIELDS = 16;
+export declare const ACTION_PACK_MAX_PROVIDERS = 8;
+export declare const ACTION_PACK_MAX_EVIDENCE = 16;
+export declare const ACTION_PACK_MAX_ENUM = 64;
+/** Transports a pack may bind its material parameters to. v1: api.request. */
+export declare const ACTION_PACK_TRANSPORTS: readonly ["api.request.v1"];
+export type ActionPackTransport = (typeof ACTION_PACK_TRANSPORTS)[number];
+export declare const ActionPackActionIdSchema: z.ZodString;
+export declare const ActionPackPublisherIdSchema: z.ZodString;
+export declare const ActionPackKeyIdSchema: z.ZodString;
+/** RFC 8037 Ed25519 JWK (public parts only) for a trusted pack publisher. */
+export declare const ActionPackPublisherKeySchema: z.ZodObject<{
+    kty: z.ZodLiteral<"OKP">;
+    crv: z.ZodLiteral<"Ed25519">;
+    kid: z.ZodString;
+    use: z.ZodLiteral<"sig">;
+    alg: z.ZodLiteral<"EdDSA">;
+    x: z.ZodString;
+}, z.core.$strict>;
+export type ActionPackPublisherKey = z.infer<typeof ActionPackPublisherKeySchema>;
+/** The human-governed trust set: which publishers may sign installed packs. */
+export type ActionPackTrustSet = Readonly<{
+    publishers: readonly ActionPackPublisherKey[];
+}>;
+/**
+ * Declarative constraint on one material field. Bounds are data the pipeline
+ * evaluates deterministically — no pack-supplied logic executes.
+ */
+export declare const ActionPackFieldSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+        object: "object";
+        array: "array";
+        integer: "integer";
+    }>;
+    required: z.ZodBoolean;
+    maxLength: z.ZodOptional<z.ZodNumber>;
+    enum: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    mustStartWith: z.ZodOptional<z.ZodString>;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type ActionPackField = z.infer<typeof ActionPackFieldSchema>;
+export declare const ActionPackContentSchema: z.ZodObject<{
+    actionId: z.ZodString;
+    family: z.ZodString;
+    resourceType: z.ZodString;
+    humanLabel: z.ZodString;
+    description: z.ZodString;
+    risk: z.ZodEnum<{
+        R0: "R0";
+        R1: "R1";
+        R2: "R2";
+        R3: "R3";
+        R4: "R4";
+        R5: "R5";
+    }>;
+    reversibility: z.ZodEnum<{
+        destructive: "destructive";
+        reversible: "reversible";
+        limited: "limited";
+        difficult: "difficult";
+        "safety-sensitive": "safety-sensitive";
+    }>;
+    posture: z.ZodEnum<{
+        deny: "deny";
+        allow: "allow";
+        ask: "ask";
+    }>;
+    providers: z.ZodArray<z.ZodString>;
+    transport: z.ZodEnum<{
+        "api.request.v1": "api.request.v1";
+    }>;
+    materialFields: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            object: "object";
+            array: "array";
+            integer: "integer";
+        }>;
+        required: z.ZodBoolean;
+        maxLength: z.ZodOptional<z.ZodNumber>;
+        enum: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        mustStartWith: z.ZodOptional<z.ZodString>;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    requiredFields: z.ZodArray<z.ZodString>;
+    approvalDisplay: z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strict>>;
+    verification: z.ZodObject<{
+        method: z.ZodEnum<{
+            "provider-receipt": "provider-receipt";
+            "recorded-outcome": "recorded-outcome";
+        }>;
+        level: z.ZodEnum<{
+            "post-commit-content": "post-commit-content";
+        }>;
+    }, z.core.$strict>;
+    counterpartyRules: z.ZodString;
+    dataEffects: z.ZodString;
+    executionContract: z.ZodString;
+    evidenceRequirements: z.ZodArray<z.ZodString>;
+    capabilityUses: z.ZodNumber;
+    requiresExplicitGrant: z.ZodOptional<z.ZodBoolean>;
+    minPrincipalClass: z.ZodOptional<z.ZodLiteral<"adult">>;
+    claimRules: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        op: z.ZodEnum<{
+            in: "in";
+            includes: "includes";
+            eq: "eq";
+            neq: "neq";
+            excludes: "excludes";
+        }>;
+        value: z.ZodUnknown;
+    }, z.core.$strict>>;
+    bindingRules: z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        claim: z.ZodString;
+        op: z.ZodEnum<{
+            within: "within";
+            memberOf: "memberOf";
+        }>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ActionPackContent = z.infer<typeof ActionPackContentSchema>;
+export declare const ActionPackBodySchema: z.ZodObject<{
+    pack: z.ZodLiteral<"guardian.action.v1">;
+    content: z.ZodObject<{
+        actionId: z.ZodString;
+        family: z.ZodString;
+        resourceType: z.ZodString;
+        humanLabel: z.ZodString;
+        description: z.ZodString;
+        risk: z.ZodEnum<{
+            R0: "R0";
+            R1: "R1";
+            R2: "R2";
+            R3: "R3";
+            R4: "R4";
+            R5: "R5";
+        }>;
+        reversibility: z.ZodEnum<{
+            destructive: "destructive";
+            reversible: "reversible";
+            limited: "limited";
+            difficult: "difficult";
+            "safety-sensitive": "safety-sensitive";
+        }>;
+        posture: z.ZodEnum<{
+            deny: "deny";
+            allow: "allow";
+            ask: "ask";
+        }>;
+        providers: z.ZodArray<z.ZodString>;
+        transport: z.ZodEnum<{
+            "api.request.v1": "api.request.v1";
+        }>;
+        materialFields: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodEnum<{
+                string: "string";
+                number: "number";
+                boolean: "boolean";
+                object: "object";
+                array: "array";
+                integer: "integer";
+            }>;
+            required: z.ZodBoolean;
+            maxLength: z.ZodOptional<z.ZodNumber>;
+            enum: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+            mustStartWith: z.ZodOptional<z.ZodString>;
+            min: z.ZodOptional<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        requiredFields: z.ZodArray<z.ZodString>;
+        approvalDisplay: z.ZodArray<z.ZodObject<{
+            field: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strict>>;
+        verification: z.ZodObject<{
+            method: z.ZodEnum<{
+                "provider-receipt": "provider-receipt";
+                "recorded-outcome": "recorded-outcome";
+            }>;
+            level: z.ZodEnum<{
+                "post-commit-content": "post-commit-content";
+            }>;
+        }, z.core.$strict>;
+        counterpartyRules: z.ZodString;
+        dataEffects: z.ZodString;
+        executionContract: z.ZodString;
+        evidenceRequirements: z.ZodArray<z.ZodString>;
+        capabilityUses: z.ZodNumber;
+        requiresExplicitGrant: z.ZodOptional<z.ZodBoolean>;
+        minPrincipalClass: z.ZodOptional<z.ZodLiteral<"adult">>;
+        claimRules: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            op: z.ZodEnum<{
+                in: "in";
+                includes: "includes";
+                eq: "eq";
+                neq: "neq";
+                excludes: "excludes";
+            }>;
+            value: z.ZodUnknown;
+        }, z.core.$strict>>;
+        bindingRules: z.ZodArray<z.ZodObject<{
+            field: z.ZodString;
+            claim: z.ZodString;
+            op: z.ZodEnum<{
+                within: "within";
+                memberOf: "memberOf";
+            }>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    version: z.ZodNumber;
+    compatibility: z.ZodObject<{
+        registry: z.ZodLiteral<1>;
+    }, z.core.$strict>;
+    review: z.ZodObject<{
+        state: z.ZodEnum<{
+            draft: "draft";
+            revoked: "revoked";
+            approved: "approved";
+        }>;
+        reviewer: z.ZodString;
+        atEpochMs: z.ZodNumber;
+    }, z.core.$strict>;
+    rollback: z.ZodObject<{
+        supersedes: z.ZodOptional<z.ZodObject<{
+            actionId: z.ZodString;
+            version: z.ZodNumber;
+        }, z.core.$strict>>;
+        restores: z.ZodOptional<z.ZodObject<{
+            actionId: z.ZodString;
+            version: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    provenance: z.ZodObject<{
+        source: z.ZodString;
+        generatedBy: z.ZodString;
+    }, z.core.$strict>;
+    publisher: z.ZodObject<{
+        id: z.ZodString;
+        keyId: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ActionPackBody = z.infer<typeof ActionPackBodySchema>;
+export declare const ActionPackSchema: z.ZodObject<{
+    pack: z.ZodLiteral<"guardian.action.v1">;
+    content: z.ZodObject<{
+        actionId: z.ZodString;
+        family: z.ZodString;
+        resourceType: z.ZodString;
+        humanLabel: z.ZodString;
+        description: z.ZodString;
+        risk: z.ZodEnum<{
+            R0: "R0";
+            R1: "R1";
+            R2: "R2";
+            R3: "R3";
+            R4: "R4";
+            R5: "R5";
+        }>;
+        reversibility: z.ZodEnum<{
+            destructive: "destructive";
+            reversible: "reversible";
+            limited: "limited";
+            difficult: "difficult";
+            "safety-sensitive": "safety-sensitive";
+        }>;
+        posture: z.ZodEnum<{
+            deny: "deny";
+            allow: "allow";
+            ask: "ask";
+        }>;
+        providers: z.ZodArray<z.ZodString>;
+        transport: z.ZodEnum<{
+            "api.request.v1": "api.request.v1";
+        }>;
+        materialFields: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodEnum<{
+                string: "string";
+                number: "number";
+                boolean: "boolean";
+                object: "object";
+                array: "array";
+                integer: "integer";
+            }>;
+            required: z.ZodBoolean;
+            maxLength: z.ZodOptional<z.ZodNumber>;
+            enum: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+            mustStartWith: z.ZodOptional<z.ZodString>;
+            min: z.ZodOptional<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        requiredFields: z.ZodArray<z.ZodString>;
+        approvalDisplay: z.ZodArray<z.ZodObject<{
+            field: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strict>>;
+        verification: z.ZodObject<{
+            method: z.ZodEnum<{
+                "provider-receipt": "provider-receipt";
+                "recorded-outcome": "recorded-outcome";
+            }>;
+            level: z.ZodEnum<{
+                "post-commit-content": "post-commit-content";
+            }>;
+        }, z.core.$strict>;
+        counterpartyRules: z.ZodString;
+        dataEffects: z.ZodString;
+        executionContract: z.ZodString;
+        evidenceRequirements: z.ZodArray<z.ZodString>;
+        capabilityUses: z.ZodNumber;
+        requiresExplicitGrant: z.ZodOptional<z.ZodBoolean>;
+        minPrincipalClass: z.ZodOptional<z.ZodLiteral<"adult">>;
+        claimRules: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            op: z.ZodEnum<{
+                in: "in";
+                includes: "includes";
+                eq: "eq";
+                neq: "neq";
+                excludes: "excludes";
+            }>;
+            value: z.ZodUnknown;
+        }, z.core.$strict>>;
+        bindingRules: z.ZodArray<z.ZodObject<{
+            field: z.ZodString;
+            claim: z.ZodString;
+            op: z.ZodEnum<{
+                within: "within";
+                memberOf: "memberOf";
+            }>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    version: z.ZodNumber;
+    compatibility: z.ZodObject<{
+        registry: z.ZodLiteral<1>;
+    }, z.core.$strict>;
+    review: z.ZodObject<{
+        state: z.ZodEnum<{
+            draft: "draft";
+            revoked: "revoked";
+            approved: "approved";
+        }>;
+        reviewer: z.ZodString;
+        atEpochMs: z.ZodNumber;
+    }, z.core.$strict>;
+    rollback: z.ZodObject<{
+        supersedes: z.ZodOptional<z.ZodObject<{
+            actionId: z.ZodString;
+            version: z.ZodNumber;
+        }, z.core.$strict>>;
+        restores: z.ZodOptional<z.ZodObject<{
+            actionId: z.ZodString;
+            version: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    provenance: z.ZodObject<{
+        source: z.ZodString;
+        generatedBy: z.ZodString;
+    }, z.core.$strict>;
+    publisher: z.ZodObject<{
+        id: z.ZodString;
+        keyId: z.ZodString;
+    }, z.core.$strict>;
+    integrity: z.ZodObject<{
+        algorithm: z.ZodLiteral<"sha256">;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    signature: z.ZodObject<{
+        algorithm: z.ZodLiteral<"Ed25519">;
+        domain: z.ZodLiteral<"odingard.guardian.action-pack.v1">;
+        canonicalization: z.ZodLiteral<"guardian-jcs-v1">;
+        keyId: z.ZodString;
+        signature: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ActionPack = z.infer<typeof ActionPackSchema>;
+/** The canonical body the integrity digest covers (pack minus integrity/sig). */
+export declare function actionPackBody(pack: ActionPack): ActionPackBody;
+/** sha256 over the canonical pack body — the declared integrity digest. */
+export declare function actionPackIntegrity(pack: ActionPack): string;
+/** UTF-8 bytes of the canonical signed document (domain-separated). */
+export declare function actionPackSigningInput(pack: ActionPack): Uint8Array;
+export type ActionPackRejection = "PACK_SCHEMA_INVALID" | "PACK_INTEGRITY_MISMATCH" | "PACK_KEY_MISMATCH" | "PACK_PUBLISHER_UNTRUSTED" | "PACK_SIGNATURE_INVALID" | "PACK_NOT_APPROVED" | "PACK_FIELD_SCOPE_INVALID" | "PACK_TRANSPORT_FIELDS_INVALID" | "PACK_ACTION_SHADOWS_BUILTIN" | "PACK_VERSION_AMBIGUOUS";
+/**
+ * Verifies a signed Action Pack against the human-governed trust set. Every
+ * rejection is deterministic: the named action never enters the registry, so
+ * proposals for it resolve as unknown actions and DENY.
+ */
+export declare function verifyActionPack(input: unknown, trust: ActionPackTrustSet): Readonly<{
+    ok: true;
+    pack: ActionPack;
+}> | Readonly<{
+    ok: false;
+    reasonCode: ActionPackRejection;
+}>;
+/**
+ * Derives the ActionDefinition a verified pack installs. The definition's
+ * hooks are registry-side executable logic (allowed: §43) — the pack itself
+ * only carries declarative data the hooks evaluate.
+ */
+export declare function actionDefinitionFromPack(body: ActionPackBody): ActionDefinition;
+/**
+ * Installs verified packs into a registry composed over an optional builtin
+ * base. Selection is deterministic: the highest-version approved pack per
+ * actionId wins; a pack cannot shadow a builtin action; equal-version
+ * ambiguity rejects every candidate. `rejected` reports each pack that did
+ * not install and why — the action stays unregistered and DENYs.
+ */
+export declare function createPackBackedRegistry(input: {
+    packs: readonly unknown[];
+    trust: ActionPackTrustSet;
+    base?: {
+        get(actionId: string): unknown;
+        entries(): readonly ActionDefinition[];
+    };
+}): {
+    registry: {
+        get(actionId: string): ActionDefinition | undefined;
+        entries(): readonly ActionDefinition[];
+    };
+    installed: readonly {
+        actionId: string;
+        version: number;
+    }[];
+    rejected: readonly {
+        actionId?: string;
+        reasonCode: ActionPackRejection;
+    }[];
+};