@odingard/guardian-sdk 0.0.0-stage → 0.1.0

package/dist-dts/__tests__/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist-dts/client.d.ts

@@ -0,0 +1,80 @@
+import { type AgentExecutionReceipt, type McpInstallParametersV1 } from "./contracts/index.js";
+/**
+ * WO-015 developer SDK — a thin typed client over the Guardian agent REST
+ * surface. External agents call this instead of hand-rolling envelopes: the
+ * request, claim and execute calls produce the same canonical action
+ * envelopes the gateway/kernel/capability path already governs.
+ *
+ * Repo-level client + docs; NOT a published package (no SDK SLA).
+ */
+export type GuardianClientConfig = Readonly<{
+    /** e.g. https://guardian-api-staging.odingard.com */
+    baseUrl: string;
+    /** Agent credential (gac1.…). */
+    credential: string;
+    /** Adapter audience for executes; defaults to the tool adapter. */
+    adapterId?: string;
+    fetch?: typeof fetch;
+}>;
+export type GuardianToolInvocation = Readonly<{
+    action: "tool.invoke";
+    connectionId: string;
+    toolName: string;
+    arguments: Record<string, unknown>;
+    adapterId?: string;
+    purpose?: string;
+}>;
+export type GuardianMcpInvocation = Readonly<{
+    action: "mcp.install";
+    connectionId: string;
+    tool: McpInstallParametersV1["tool"];
+    adapterId?: string;
+    purpose?: string;
+}> | Readonly<{
+    action: "mcp.enable";
+    connectionId: string;
+    toolName: string;
+    adapterId?: string;
+    purpose?: string;
+}>;
+export type GuardianRequestResult = {
+    ok: true;
+    requestId: string;
+    decision: "ALLOW" | "ASK" | "DENY";
+    capabilityToken?: string;
+    reasonCode?: string;
+} | {
+    ok: false;
+    reasonCode: string;
+};
+export interface GuardianClient {
+    /**
+     * Request a capability for a tool/MCP action. ALLOW returns a
+     * capabilityToken immediately; ASK returns decision "ASK" and the human
+     * approves out-of-band (then call `claim`); DENY refuses.
+     */
+    request(invocation: GuardianToolInvocation | GuardianMcpInvocation): 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. */
+    execute(input: {
+        requestId: string;
+        capabilityToken: string;
+    }): Promise<{
+        ok: true;
+        receipt: AgentExecutionReceipt;
+    } | {
+        ok: false;
+        reasonCode: string;
+    }>;
+    /** Machine-readable proof for a request (WO-015 developer receipts). */
+    receipts(requestId: string): Promise<{
+        ok: true;
+        requestId: string;
+        receipts: readonly unknown[];
+    } | {
+        ok: false;
+        reasonCode: string;
+    }>;
+}
+export declare function createGuardianClient(config: GuardianClientConfig): GuardianClient;

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

@@ -0,0 +1,34 @@
+import { type ActionDefinition, type ActionRegistry } from "./action-registry.js";
+import type { TaskId } from "./identifiers.js";
+export type ActionParameterValidation = {
+    ok: true;
+    kind: string;
+    definition: ActionDefinition;
+    params: unknown;
+} | {
+    ok: true;
+    kind: "generic";
+} | {
+    ok: false;
+};
+type FactInput = {
+    valueCents?: number | undefined;
+    merchantId?: string | undefined;
+    merchantCategory?: string | undefined;
+    recurring?: boolean | undefined;
+    taskId?: TaskId | undefined;
+};
+/**
+ * Generic parameter gate (GUA-UNIVERSAL-001 §11/K15): resolves the action
+ * through the Universal Action Registry and applies only action-agnostic
+ * checks — capability uses, declared monetary facts vs derived facts, and
+ * the `${resourceType}:${connectionId}` resource binding. Action semantics
+ * live in the registered definition's hooks.
+ */
+export declare function validateActionParameters(input: {
+    action: string;
+    resource: string;
+    uses: number;
+    materialParameters: unknown;
+} & FactInput, registry?: ActionRegistry): ActionParameterValidation;
+export {};

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

@@ -0,0 +1,197 @@
+import { type ActionAuthorityFacts } from "./commerce.js";
+import { type ProtectedCatalogEntry } from "./protected-data.js";
+import { type ToolDescriptor } from "./tools.js";
+/**
+ * GUA-UNIVERSAL-001 §7 — Universal Action Registry.
+ *
+ * Every consequential action is registered independently of provider. The
+ * authority kernel resolves an action_id to an ActionDefinition and invokes
+ * its hooks uniformly; it never branches on action/provider identity (K15).
+ * Adding a new action means adding a registry definition plus an adapter —
+ * no kernel change.
+ */
+export type Reversibility = "reversible" | "limited" | "difficult" | "destructive" | "safety-sensitive";
+export type RiskClass = "R0" | "R1" | "R2" | "R3" | "R4" | "R5";
+/** The connection facts an action definition may bind against. */
+export type ActionConnectionBinding = Readonly<{
+    provider: string;
+    mailboxAddress?: string;
+    endpointAllowlist?: readonly string[];
+    /** Provider "tool" connections carry the installed tool-server catalog. */
+    toolServer?: Readonly<{
+        serverName: string;
+        serverVersion: string;
+        tools: readonly ToolDescriptor[];
+    }>;
+    /** Tool names enabled for the requesting agent (agent_tools registry). */
+    enabledToolNames?: readonly string[];
+    calendarId?: string;
+    /** Canonical path prefixes file ops may touch (files provider). */
+    pathAllowlist?: readonly string[];
+    /** Canonical path prefixes a file may be shared from (files provider). */
+    shareAllowlist?: readonly string[];
+    /** Declared protected fields for this connection (protected_data). */
+    protectedCatalog?: readonly ProtectedCatalogEntry[];
+}>;
+export type ActionBindingResult = Readonly<{
+    ok: true;
+}> | Readonly<{
+    ok: false;
+    reasonCode: string;
+}>;
+export interface ActionDefinition<P = unknown> {
+    readonly actionId: string;
+    readonly schemaVersion: 1;
+    readonly actionFamily: string;
+    readonly humanLabel: string;
+    readonly description: string;
+    /** Typed kind returned to the pipeline after parameter validation. */
+    readonly parametersKind: string;
+    /** Raw field names, for rendering + policy primitives. */
+    readonly requiredParameters: readonly string[];
+    /** Fields bound into the material-parameter digest (TOCTOU, §27). */
+    readonly materialParameters: readonly string[];
+    /** Resource pattern: `${resourceType}:${connectionId}`. */
+    readonly resourceType: string;
+    /** Providers a connection may use for this action. */
+    readonly providers: readonly string[];
+    readonly counterpartyRules: string;
+    readonly dataEffects: string;
+    readonly reversibility: Reversibility;
+    readonly riskClass: RiskClass;
+    readonly defaultDecisionPosture: "allow" | "ask" | "deny";
+    /** Generic fields the Authority Slip renders. */
+    readonly approvalPresentationSchema: readonly string[];
+    readonly capabilityRequirements: Readonly<{
+        uses: number;
+    }>;
+    readonly executionContract: string;
+    readonly verificationContract: Readonly<{
+        level: string;
+    }>;
+    readonly evidenceRequirements: readonly string[];
+    readonly version: 1;
+    readonly status: "active" | "deprecated" | "disabled";
+    /**
+     * When true the action is capability-expanding: authority derivation never
+     * auto-includes it in a grant's action set. It can only enter a grant when
+     * a human selects it explicitly (WO-015 self-serve-escalation denial).
+     */
+    readonly requiresExplicitGrant?: boolean;
+    /**
+     * Action-specific logic lives HERE — inside the registered definition —
+     * never inside the kernel. Hooks receive only kernel-verified inputs.
+     */
+    validateParameters(materialParameters: unknown): Readonly<{
+        ok: true;
+        params: P;
+    } | {
+        ok: false;
+    }>;
+    /** Pre-execution binding the agent's params to the leased connection. */
+    validateBinding(input: {
+        params: P;
+        connection: ActionConnectionBinding;
+    }): ActionBindingResult;
+    /** Canonical projection whose digest the verified outcome must match. */
+    verificationProjection(params: P): unknown;
+    /** Envelope projection recorded at reservation time. */
+    envelopeProjection(params: P): unknown;
+    /**
+     * Generic monetary-authority facts derived from validated parameters
+     * (WO-014). When present, the envelope's declared facts must equal the
+     * derived values, so an agent cannot understate an amount or smuggle a
+     * merchant/category/recurrence fact past the kernel.
+     */
+    authorityFacts?(params: P): ActionAuthorityFacts;
+}
+export type ActionRegistry = Readonly<{
+    get(actionId: string): ActionDefinition | undefined;
+    entries(): readonly ActionDefinition[];
+}>;
+export declare function createActionRegistry(definitions: readonly ActionDefinition[]): ActionRegistry;
+export declare const EMAIL_SEND_DEFINITION: ActionDefinition<{
+    schema: "odingard.guardian.email.send.v1";
+    connectionId: string & import("zod").$brand<"ConnectionId">;
+    from: string;
+    to: string[];
+    cc: string[];
+    bcc: string[];
+    replyTo: never[];
+    subject: string;
+    body: {
+        format: "text/plain";
+        text: string;
+    };
+    attachments: never[];
+    inReplyTo: null;
+}>;
+export declare const API_REQUEST_DEFINITION: ActionDefinition<{
+    schema: "odingard.guardian.api.request.v1";
+    connectionId: string & import("zod").$brand<"ConnectionId">;
+    method: "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
+    url: string;
+    headers: {
+        name: string;
+        value: string;
+    }[];
+    body?: string | undefined;
+    idempotencyKey?: string | undefined;
+}>;
+export declare const TOOL_INVOKE_DEFINITION: ActionDefinition<{
+    schema: "odingard.guardian.tool.invoke.v1";
+    connectionId: string & import("zod").$brand<"ConnectionId">;
+    toolName: string;
+    arguments: Record<string, unknown>;
+}>;
+export declare const MCP_INSTALL_DEFINITION: ActionDefinition<{
+    schema: "odingard.guardian.mcp.install.v1";
+    connectionId: string & import("zod").$brand<"ConnectionId">;
+    tool: {
+        name: string;
+        method: "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
+        url: string;
+        description?: string | undefined;
+    };
+}>;
+export declare const MCP_ENABLE_DEFINITION: ActionDefinition<{
+    schema: "odingard.guardian.mcp.enable.v1";
+    connectionId: string & import("zod").$brand<"ConnectionId">;
+    toolName: string;
+}>;
+export declare const COMMERCE_PURCHASE_DEFINITION: ActionDefinition<{
+    schema: "commerce.purchase.v1";
+    connectionId: string & import("zod").$brand<"ConnectionId">;
+    merchantId: string;
+    merchantCategory: string;
+    amountCents: number;
+    currency: "USD";
+    orderDescription: string;
+    idempotencyKey: string;
+    taskId?: (string & import("zod").$brand<"TaskId">) | undefined;
+}>;
+export declare const COMMERCE_REFUND_DEFINITION: ActionDefinition<{
+    schema: "commerce.refund.v1";
+    connectionId: string & import("zod").$brand<"ConnectionId">;
+    chargeId: string;
+    reason: string;
+    amountCents?: number | undefined;
+}>;
+export declare const COMMERCE_RETURN_DEFINITION: ActionDefinition<{
+    schema: "commerce.return.v1";
+    connectionId: string & import("zod").$brand<"ConnectionId">;
+    chargeId: string;
+    reason: string;
+}>;
+export declare const SUBSCRIPTION_CREATE_DEFINITION: ActionDefinition<{
+    schema: "subscription.create.v1";
+    connectionId: string & import("zod").$brand<"ConnectionId">;
+    merchantId: string;
+    planId: string;
+    amountCents: number;
+    currency: "USD";
+    interval: "week" | "month" | "year";
+    idempotencyKey: string;
+}>;
+/** The shipped registry: enforced surfaces as first-class definitions. */
+export declare const universalActionRegistry: ActionRegistry;