@odingard/guardian-sdk 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,78 @@
+import { z } from "zod";
+export declare const ApiRequestMethodSchema: z.ZodEnum<{
+    GET: "GET";
+    HEAD: "HEAD";
+    POST: "POST";
+    PUT: "PUT";
+    PATCH: "PATCH";
+    DELETE: "DELETE";
+}>;
+export type ApiRequestMethod = z.infer<typeof ApiRequestMethodSchema>;
+export declare const API_REQUEST_BODY_MAX_LENGTH = 16384;
+export declare const API_REQUEST_MAX_HEADERS = 32;
+export declare const API_RESPONSE_BODY_CAPTURE_MAX_BYTES: number;
+export declare const API_RESPONSE_BODY_PREVIEW_MAX_LENGTH = 256;
+export declare const API_ENDPOINT_ALLOWLIST_MAX_ENTRIES = 64;
+export declare function isSafeApiHeaderValue(value: string): boolean;
+/**
+ * Canonicalizes an https request URL. Returns null when the URL is not a
+ * plain https absolute URL (userinfo, fragments, non-default ports left
+ * unnormalized are rejected or normalized here). Query parameters are
+ * sorted so two submissions of the same request canonicalize identically.
+ */
+export declare function canonicalizeApiRequestUrl(value: string): string | null;
+export declare const ApiRequestUrlSchema: z.ZodString;
+export declare const ApiRequestHeaderSchema: z.ZodObject<{
+    name: z.ZodString;
+    value: z.ZodString;
+}, z.core.$strict>;
+export declare const ApiRequestParametersV1Schema: z.ZodObject<{
+    schema: z.ZodLiteral<"odingard.guardian.api.request.v1">;
+    connectionId: z.core.$ZodBranded<z.ZodString, "ConnectionId", "out">;
+    method: z.ZodEnum<{
+        GET: "GET";
+        HEAD: "HEAD";
+        POST: "POST";
+        PUT: "PUT";
+        PATCH: "PATCH";
+        DELETE: "DELETE";
+    }>;
+    url: z.ZodString;
+    headers: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strict>>;
+    body: z.ZodOptional<z.ZodString>;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ApiRequestParametersV1 = z.infer<typeof ApiRequestParametersV1Schema>;
+export declare function apiVerificationProjection(input: ApiRequestParametersV1): Readonly<{
+    domain: "odingard.guardian.api-projection.v1";
+    connectionId: string & z.core.$brand<"ConnectionId">;
+    method: "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
+    url: string;
+    headersDigest: string;
+    bodyDigest: string | null;
+    idempotencyKey: string | null;
+}>;
+/**
+ * api.request has a single verification level: the envelope and the content
+ * projection are the same canonical request. The post-commit envelope digest
+ * therefore equals the projection digest.
+ */
+export declare function apiEnvelopeProjection(input: ApiRequestParametersV1): Readonly<{
+    domain: "odingard.guardian.api-projection.v1";
+    connectionId: string & z.core.$brand<"ConnectionId">;
+    method: "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
+    url: string;
+    headersDigest: string;
+    bodyDigest: string | null;
+    idempotencyKey: string | null;
+}>;
+export declare function isSafeAllowlistEntry(value: string): boolean;
+/**
+ * Fail-closed allowlist match: the request URL must equal an allowlist entry
+ * or extend it at a path boundary. Entries are canonical https URL prefixes
+ * such as "https://api.github.com/repos/odingard/".
+ */
+export declare function apiEndpointWithinAllowlist(canonicalUrl: string, allowlist: readonly string[]): boolean;

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

@@ -0,0 +1,206 @@
+import { z } from "zod";
+/**
+ * Agent-written prose is carried only as a labelled, explicitly non-authoritative
+ * statement. It never participates in authority evaluation or approval binding
+ * beyond being shown verbatim (and safely rendered) to the human.
+ */
+export declare const AgentStatementSchema: z.ZodObject<{
+    source: z.ZodLiteral<"agent">;
+    authoritative: z.ZodLiteral<false>;
+    text: z.ZodString;
+}, z.core.$strict>;
+/**
+ * Guardian's own reason for asking the human. It is derived only from the
+ * server-held authority the deterministic kernel evaluated for the ASK decision
+ * and never contains agent input.
+ */
+export declare const ApprovalReasonSchema: z.ZodObject<{
+    source: z.ZodLiteral<"guardian">;
+    code: z.ZodLiteral<"APPROVAL_REQUIRED">;
+    authority: z.ZodObject<{
+        policy: z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodString, "PolicyId", "out">;
+            version: z.ZodNumber;
+        }, z.core.$strict>;
+        evaluatedGrants: z.ZodArray<z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodString, "GrantId", "out">;
+            version: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/**
+ * Server-generated description of the exact canonical action a human is asked to
+ * decide. Every field is copied from server-held canonical action state; values
+ * the agent chose (parameters, purpose, initiating context, request identifier)
+ * remain agent assertions and must be presented with agent provenance.
+ */
+export declare const ApprovalPresentationSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    approvalId: z.core.$ZodBranded<z.ZodString, "ApprovalId", "out">;
+    tenantId: z.core.$ZodBranded<z.ZodString, "TenantId", "out">;
+    principalId: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+    agentId: z.core.$ZodBranded<z.ZodString, "AgentId", "out">;
+    requestId: z.core.$ZodBranded<z.ZodString, "RequestId", "out">;
+    correlationId: z.core.$ZodBranded<z.ZodString, "CorrelationId", "out">;
+    action: z.core.$ZodBranded<z.ZodString, "ActionType", "out">;
+    resource: z.core.$ZodBranded<z.ZodString, "ResourceRef", "out">;
+    adapterId: z.core.$ZodBranded<z.ZodString, "AdapterId", "out">;
+    interface: z.ZodEnum<{
+        internal: "internal";
+        mcp: "mcp";
+        rest: "rest";
+    }>;
+    initiatingContext: z.ZodEnum<{
+        agent: "agent";
+        user: "user";
+        scheduled: "scheduled";
+        "external-event": "external-event";
+    }>;
+    materialParameters: z.ZodPipe<z.ZodUnknown, z.ZodTransform<Readonly<Record<string, import("./canonical-json.js").CanonicalJsonValue>>, unknown>>;
+    valueCents: z.ZodOptional<z.ZodNumber>;
+    uses: z.ZodNumber;
+    agentStatement: z.ZodObject<{
+        source: z.ZodLiteral<"agent">;
+        authoritative: z.ZodLiteral<false>;
+        text: z.ZodString;
+    }, z.core.$strict>;
+    reason: z.ZodObject<{
+        source: z.ZodLiteral<"guardian">;
+        code: z.ZodLiteral<"APPROVAL_REQUIRED">;
+        authority: z.ZodObject<{
+            policy: z.ZodObject<{
+                id: z.core.$ZodBranded<z.ZodString, "PolicyId", "out">;
+                version: z.ZodNumber;
+            }, z.core.$strict>;
+            evaluatedGrants: z.ZodArray<z.ZodObject<{
+                id: z.core.$ZodBranded<z.ZodString, "GrantId", "out">;
+                version: z.ZodNumber;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    actionDigest: z.ZodString;
+    expiresAtEpochMs: z.ZodNumber;
+}, z.core.$strict>;
+export declare const ApprovalBindingSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    approvalId: z.core.$ZodBranded<z.ZodString, "ApprovalId", "out">;
+    tenantId: z.core.$ZodBranded<z.ZodString, "TenantId", "out">;
+    principalId: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+    agentId: z.core.$ZodBranded<z.ZodString, "AgentId", "out">;
+    requestId: z.core.$ZodBranded<z.ZodString, "RequestId", "out">;
+    correlationId: z.core.$ZodBranded<z.ZodString, "CorrelationId", "out">;
+    actionDigest: z.ZodString;
+    actionDecisionRecordDigest: z.ZodString;
+    askDecisionDigest: z.ZodString;
+    adapterId: z.core.$ZodBranded<z.ZodString, "AdapterId", "out">;
+    policy: z.ZodObject<{
+        id: z.core.$ZodBranded<z.ZodString, "PolicyId", "out">;
+        version: z.ZodNumber;
+    }, z.core.$strict>;
+    evaluatedGrants: z.ZodArray<z.ZodObject<{
+        id: z.core.$ZodBranded<z.ZodString, "GrantId", "out">;
+        version: z.ZodNumber;
+    }, z.core.$strict>>;
+    presentationDigest: z.ZodString;
+    requestedAtEpochMs: z.ZodNumber;
+    expiresAtEpochMs: z.ZodNumber;
+}, z.core.$strict>;
+export declare const ApprovalStateSchema: z.ZodEnum<{
+    revoked: "revoked";
+    pending: "pending";
+    approved: "approved";
+    denied: "denied";
+    expired: "expired";
+    superseded: "superseded";
+    consumed: "consumed";
+}>;
+export declare const ApprovalRecordSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    binding: z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        approvalId: z.core.$ZodBranded<z.ZodString, "ApprovalId", "out">;
+        tenantId: z.core.$ZodBranded<z.ZodString, "TenantId", "out">;
+        principalId: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+        agentId: z.core.$ZodBranded<z.ZodString, "AgentId", "out">;
+        requestId: z.core.$ZodBranded<z.ZodString, "RequestId", "out">;
+        correlationId: z.core.$ZodBranded<z.ZodString, "CorrelationId", "out">;
+        actionDigest: z.ZodString;
+        actionDecisionRecordDigest: z.ZodString;
+        askDecisionDigest: z.ZodString;
+        adapterId: z.core.$ZodBranded<z.ZodString, "AdapterId", "out">;
+        policy: z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodString, "PolicyId", "out">;
+            version: z.ZodNumber;
+        }, z.core.$strict>;
+        evaluatedGrants: z.ZodArray<z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodString, "GrantId", "out">;
+            version: z.ZodNumber;
+        }, z.core.$strict>>;
+        presentationDigest: z.ZodString;
+        requestedAtEpochMs: z.ZodNumber;
+        expiresAtEpochMs: z.ZodNumber;
+    }, z.core.$strict>;
+    state: z.ZodEnum<{
+        revoked: "revoked";
+        pending: "pending";
+        approved: "approved";
+        denied: "denied";
+        expired: "expired";
+        superseded: "superseded";
+        consumed: "consumed";
+    }>;
+    version: z.ZodNumber;
+    updatedAtEpochMs: z.ZodNumber;
+    decidedByPrincipalId: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">>;
+}, z.core.$strict>;
+/** Human-facing REST body for an explicit approve or deny decision. */
+export declare const ApprovalDecisionRequestSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    decision: z.ZodEnum<{
+        deny: "deny";
+        approve: "approve";
+    }>;
+    expectedVersion: z.ZodNumber;
+    presentationDigest: z.ZodString;
+}, z.core.$strict>;
+/** Human-facing REST body for revoking a pending or approved decision. */
+export declare const ApprovalRevocationRequestSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    expectedVersion: z.ZodNumber;
+}, z.core.$strict>;
+/** The exact values a human must echo back to decide; protects against stale tabs. */
+export declare const ApprovalChallengeSchema: z.ZodObject<{
+    approvalId: z.core.$ZodBranded<z.ZodString, "ApprovalId", "out">;
+    version: z.ZodNumber;
+    presentationDigest: z.ZodString;
+    expiresAtEpochMs: z.ZodNumber;
+}, z.core.$strict>;
+export declare const ApprovalReceiptSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    approvalId: z.core.$ZodBranded<z.ZodString, "ApprovalId", "out">;
+    state: z.ZodEnum<{
+        revoked: "revoked";
+        pending: "pending";
+        approved: "approved";
+        denied: "denied";
+        expired: "expired";
+        superseded: "superseded";
+        consumed: "consumed";
+    }>;
+    version: z.ZodNumber;
+    updatedAtEpochMs: z.ZodNumber;
+    approvalDigest: z.ZodString;
+}, z.core.$strict>;
+export declare function approvalPresentationDigest(presentation: z.infer<typeof ApprovalPresentationSchema>): string;
+export declare function approvalBindingDigest(binding: z.infer<typeof ApprovalBindingSchema>): string;
+export declare function approvalRecordDigest(record: z.infer<typeof ApprovalRecordSchema>): string;
+export type AgentStatement = z.infer<typeof AgentStatementSchema>;
+export type ApprovalReason = z.infer<typeof ApprovalReasonSchema>;
+export type ApprovalPresentation = z.infer<typeof ApprovalPresentationSchema>;
+export type ApprovalBinding = z.infer<typeof ApprovalBindingSchema>;
+export type ApprovalState = z.infer<typeof ApprovalStateSchema>;
+export type ApprovalRecord = z.infer<typeof ApprovalRecordSchema>;
+export type ApprovalDecisionRequest = z.infer<typeof ApprovalDecisionRequestSchema>;
+export type ApprovalRevocationRequest = z.infer<typeof ApprovalRevocationRequestSchema>;
+export type ApprovalChallenge = z.infer<typeof ApprovalChallengeSchema>;
+export type ApprovalReceipt = z.infer<typeof ApprovalReceiptSchema>;

package/dist-dts/contracts/authority-state.d.ts

@@ -0,0 +1,93 @@
+import { z } from "zod";
+import { type CanonicalAction, type RecordedAuthorityEvaluationInput } from "./action.js";
+export declare const AuthorityStateSnapshotSchema: z.ZodObject<{
+    principal: z.ZodObject<{
+        id: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+        tenantId: z.core.$ZodBranded<z.ZodString, "TenantId", "out">;
+        status: z.ZodEnum<{
+            active: "active";
+            disabled: "disabled";
+        }>;
+    }, z.core.$strict>;
+    agent: z.ZodObject<{
+        id: z.core.$ZodBranded<z.ZodString, "AgentId", "out">;
+        tenantId: z.core.$ZodBranded<z.ZodString, "TenantId", "out">;
+        ownerPrincipalId: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+        status: z.ZodEnum<{
+            active: "active";
+            disabled: "disabled";
+            revoked: "revoked";
+        }>;
+        allowedInterfaces: z.ZodPipe<z.ZodArray<z.ZodEnum<{
+            internal: "internal";
+            mcp: "mcp";
+            rest: "rest";
+        }>>, z.ZodTransform<("internal" | "mcp" | "rest")[], ("internal" | "mcp" | "rest")[]>>;
+    }, z.core.$strict>;
+    policy: z.ZodObject<{
+        id: z.core.$ZodBranded<z.ZodString, "PolicyId", "out">;
+        version: z.ZodNumber;
+    }, z.core.$strict>;
+    authorityChain: z.ZodArray<z.ZodObject<{
+        id: z.core.$ZodBranded<z.ZodString, "GrantId", "out">;
+        tenantId: z.core.$ZodBranded<z.ZodString, "TenantId", "out">;
+        principalId: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+        agentId: z.core.$ZodBranded<z.ZodString, "AgentId", "out">;
+        parentGrantId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "GrantId", "out">>;
+        issuedBy: z.ZodObject<{
+            type: z.ZodLiteral<"principal">;
+            principalId: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+        }, z.core.$strict>;
+        status: z.ZodEnum<{
+            active: "active";
+            disabled: "disabled";
+            revoked: "revoked";
+        }>;
+        version: z.ZodNumber;
+        delegable: z.ZodDefault<z.ZodBoolean>;
+        constraints: z.ZodObject<{
+            actions: z.ZodPipe<z.ZodArray<z.core.$ZodBranded<z.ZodString, "ActionType", "out">>, z.ZodTransform<(string & z.core.$brand<"ActionType">)[], (string & z.core.$brand<"ActionType">)[]>>;
+            resources: z.ZodPipe<z.ZodArray<z.core.$ZodBranded<z.ZodString, "ResourceRef", "out">>, z.ZodTransform<(string & z.core.$brand<"ResourceRef">)[], (string & z.core.$brand<"ResourceRef">)[]>>;
+            adapterIds: z.ZodPipe<z.ZodArray<z.core.$ZodBranded<z.ZodString, "AdapterId", "out">>, z.ZodTransform<(string & z.core.$brand<"AdapterId">)[], (string & z.core.$brand<"AdapterId">)[]>>;
+            maxValueCents: z.ZodOptional<z.ZodNumber>;
+            maxUsesPerRequest: z.ZodNumber;
+            notBeforeEpochMs: z.ZodOptional<z.ZodNumber>;
+            expiresAtEpochMs: z.ZodNumber;
+            approvalRequired: z.ZodBoolean;
+            askAboveValueCents: z.ZodOptional<z.ZodNumber>;
+            merchantAllowlist: z.ZodOptional<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string[], string[]>>>;
+            categoryAllowlist: z.ZodOptional<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string[], string[]>>>;
+            recurrence: z.ZodOptional<z.ZodEnum<{
+                never: "never";
+                allowed: "allowed";
+            }>>;
+            budgetIds: z.ZodOptional<z.ZodPipe<z.ZodArray<z.core.$ZodBranded<z.ZodString, "BudgetId", "out">>, z.ZodTransform<(string & z.core.$brand<"BudgetId">)[], (string & z.core.$brand<"BudgetId">)[]>>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    revocations: z.ZodArray<z.ZodObject<{
+        grantId: z.core.$ZodBranded<z.ZodString, "GrantId", "out">;
+        revokedAtEpochMs: z.ZodNumber;
+        reasonCode: z.ZodString;
+    }, z.core.$strict>>;
+    allowedAdapterIds: z.ZodArray<z.core.$ZodBranded<z.ZodString, "AdapterId", "out">>;
+    budgets: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.core.$ZodBranded<z.ZodString, "BudgetId", "out">;
+        scope: z.ZodEnum<{
+            agent: "agent";
+            task: "task";
+        }>;
+        taskId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "TaskId", "out">>;
+        limitCents: z.ZodNumber;
+        consumedCents: z.ZodNumber;
+        transactionLimit: z.ZodNumber;
+        consumedTransactions: z.ZodNumber;
+        expiresAtEpochMs: z.ZodOptional<z.ZodNumber>;
+        status: z.ZodEnum<{
+            active: "active";
+            exhausted: "exhausted";
+            revoked: "revoked";
+        }>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type AuthorityStateSnapshot = z.infer<typeof AuthorityStateSnapshotSchema>;
+export declare function buildRecordedEvaluationInput(actionInput: CanonicalAction, stateInput: AuthorityStateSnapshot, nowEpochMs: number): RecordedAuthorityEvaluationInput;