@odingard/guardian-sdk 0.1.0 → 0.2.0

package/dist-dts/embedded.d.ts

@@ -0,0 +1,58 @@
+/**
+ * WO-019 — embedded approval primitives for partner apps (extends the WO-015
+ * SDK). A partner embeds Guardian authority by driving the human's approval
+ * surface through this client; the calls hit `/v1/embedded/approvals`, which
+ * runs the identical approval-service methods as the first-party route, so
+ * the decision semantics, receipts and evidence are identical.
+ *
+ * The partner supplies the human's own Guardian session token — the partner
+ * never handles agent credentials and cannot widen what the human may see or
+ * decide.
+ */
+export type EmbeddedApprovalConfig = Readonly<{
+    /** e.g. https://guardian-api-staging.odingard.com */
+    baseUrl: string;
+    /** The human's Guardian session token presented through the partner app. */
+    sessionToken: string;
+    fetch?: typeof fetch;
+}>;
+export type EmbeddedApprovalSummary = Readonly<{
+    approvalId: string;
+    state: string;
+    version: number;
+    headline: string;
+    expiresAtEpochMs: number;
+}>;
+export type EmbeddedApprovalView = Readonly<{
+    display: unknown;
+    challenge: unknown | null;
+}>;
+export type EmbeddedDecisionResult = Readonly<{
+    receipt: unknown;
+    changed: boolean;
+}>;
+export type EmbeddedResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    reasonCode: string;
+};
+export declare function isHumanSessionToken(token: unknown): token is string;
+export declare function createEmbeddedApprovalClient(config: EmbeddedApprovalConfig): {
+    listApprovals(): Promise<EmbeddedResult<{
+        approvals: readonly EmbeddedApprovalSummary[];
+    }>>;
+    viewApproval(approvalId: string): Promise<EmbeddedResult<EmbeddedApprovalView>>;
+    decideApproval(approvalId: string, input: {
+        expectedVersion: number;
+        decision: "approve" | "deny";
+        presentationDigest: string;
+        /** WO-019 step-up factor: tap (default), passkey, biometric, second-device. */
+        factor?: "tap" | "passkey" | "biometric" | "second-device";
+    }): Promise<EmbeddedResult<EmbeddedDecisionResult>>;
+    revokeApproval(approvalId: string, input: {
+        expectedVersion: number;
+    }): Promise<EmbeddedResult<EmbeddedDecisionResult>>;
+};
+export type EmbeddedApprovalClient = ReturnType<typeof createEmbeddedApprovalClient>;

package/dist-dts/evidence/evidence.d.ts

@@ -0,0 +1,25 @@
+import { type EvidenceEvent, type EvidenceChainContext, type EvidenceRecord, type EvidenceRecordCore } from "../contracts/index.js";
+export type AppendEvidenceFailure = "MALFORMED_CHAIN" | "MALFORMED_DRAFT" | "CHAIN_INVALID" | "DUPLICATE_EVIDENCE_ID" | "APPEND_CONTEXT_MISMATCH" | "NON_MONOTONIC_EVENT_TIME" | "CHAIN_LIMIT_EXCEEDED";
+export type AppendEvidenceResult = {
+    ok: true;
+    record: EvidenceRecord;
+    chain: EvidenceRecord[];
+} | {
+    ok: false;
+    reasonCode: AppendEvidenceFailure;
+};
+export type EvidenceVerificationFailure = "MALFORMED_CHAIN" | "INVALID_GENESIS" | "DUPLICATE_EVIDENCE_ID" | "DUPLICATE_SEQUENCE" | "SEQUENCE_GAP" | "RECORD_REORDERED" | "CONTEXT_MISMATCH" | "ACTION_DIGEST_MISMATCH" | "INVALID_EVENT_ORDER" | "PAYLOAD_DIGEST_MISMATCH" | "BROKEN_LINK" | "NON_MONOTONIC_EVENT_TIME" | "RECORD_HASH_MISMATCH";
+export type EvidenceVerificationResult = {
+    valid: true;
+    count: number;
+    lastRecordHash: string | null;
+    context: EvidenceChainContext | null;
+} | {
+    valid: false;
+    reasonCode: EvidenceVerificationFailure;
+    recordIndex: number | null;
+};
+export declare function hashEvidencePayload(event: EvidenceEvent): string;
+export declare function hashEvidenceRecordCore(core: EvidenceRecordCore): string;
+export declare function verifyEvidenceChain(chainInput: unknown, expectedContextInput?: unknown): EvidenceVerificationResult;
+export declare function appendEvidenceRecord(chainInput: unknown, draftInput: unknown): AppendEvidenceResult;

package/dist-dts/evidence/receipt.d.ts

@@ -0,0 +1,61 @@
+import { type ApprovalRecord, type CanonicalAction, type CapabilityClaims, type EvidenceRecord, type ExecutionRecord, type PortableAuthorityReceipt, type PortableReceiptBody, type ReceiptVerificationJwk } from "../contracts/index.js";
+export type ReceiptSigner = Readonly<{
+    keyId: string;
+    verificationJwk: ReceiptVerificationJwk;
+    sign(body: PortableReceiptBody): PortableAuthorityReceipt;
+}>;
+/** Deterministic receipt key id: rkey_<first-16-hex of sha256(x)>. */
+export declare function receiptKeyIdFromX(x: string): string;
+/**
+ * Builds a receipt signer from an Ed25519 signing JWK (`{x, d}` as stored in
+ * the `receipt-signing-jwk` secret). Throws on malformed key material.
+ */
+export declare function createReceiptSignerFromJwk(input: unknown): ReceiptSigner;
+/** Generates an ephemeral signer — development and tests only. */
+export declare function createEphemeralReceiptSigner(): ReceiptSigner;
+export type BuildPortableReceiptInput = Readonly<{
+    receiptId: string;
+    issuedAtEpochMs: number;
+    /** The complete evidence chain for the request, in sequence order. */
+    chain: readonly EvidenceRecord[];
+    /**
+     * The canonical action the kernel evaluated (from the private
+     * materialized-action store). The chain binds it via its material digest.
+     */
+    action?: CanonicalAction | null;
+    /** Latest stored approval record, when the request required one. */
+    approval?: ApprovalRecord | null;
+    /** The issued capability's claims (never the token). */
+    capabilityClaims?: CapabilityClaims | null;
+    capabilityState?: "issued" | "used" | "expired" | "revoked" | null;
+    /** Latest execution ledger record, when execution was attempted. */
+    execution?: ExecutionRecord | null;
+}>;
+export type BuildPortableReceiptResult = {
+    ok: true;
+    body: PortableReceiptBody;
+} | {
+    ok: false;
+    reasonCode: "CHAIN_INVALID" | "ACTION_UNAVAILABLE" | "DECISION_MISSING" | "APPROVAL_INCONSISTENT" | "CAPABILITY_INCONSISTENT" | "EXECUTION_INCONSISTENT";
+};
+export declare function buildPortableReceipt(input: BuildPortableReceiptInput): BuildPortableReceiptResult;
+/** Recomputes the capability claims digest (same domain as the broker). */
+export declare function capabilityClaimsDigest(claims: CapabilityClaims): string;
+export type PortableReceiptVerificationFailure = "MALFORMED_RECEIPT" | "UNKNOWN_KEY" | "SIGNATURE_INVALID" | "EVIDENCE_CHAIN_INVALID" | "SUBJECT_MISMATCH" | "ACTION_MISMATCH" | "DECISION_MISMATCH" | "APPROVAL_MISMATCH" | "CAPABILITY_MISMATCH" | "EXECUTION_MISMATCH" | "EFFECT_MISMATCH" | "EVIDENCE_HEAD_MISMATCH";
+export type PortableReceiptVerificationResult = {
+    valid: true;
+    subject: PortableReceiptBody["subject"];
+    decision: PortableReceiptBody["decision"]["decision"];
+    effect: PortableReceiptBody["effect"]["kind"];
+} | {
+    valid: false;
+    reasonCode: PortableReceiptVerificationFailure;
+};
+/**
+ * Self-contained portable receipt verification. The caller supplies only the
+ * receipt and the published verification key set — no Guardian credential,
+ * database, or service is required. Every embedded object is re-digested and
+ * cross-checked against the embedded evidence chain, and the Ed25519 proof is
+ * verified over the canonical receipt body.
+ */
+export declare function verifyPortableAuthorityReceipt(receiptInput: unknown, keysInput: unknown): PortableReceiptVerificationResult;

package/dist-dts/index.d.ts

@@ -1 +1,5 @@
-export { createGuardianClient, type GuardianClient, type GuardianClientConfig, type GuardianRequestResult, type GuardianToolInvocation, type GuardianMcpInvocation, } from "./client.js";
+export { createGuardianClient, type GuardianClient, type GuardianClientConfig, type GuardianGovernedInvocation, type GuardianInvocation, type GuardianRequestResult, type GuardianToolInvocation, type GuardianMcpInvocation, } from "./client.js";
+export { createEmbeddedApprovalClient, isHumanSessionToken, type EmbeddedApprovalClient, type EmbeddedApprovalConfig, type EmbeddedApprovalSummary, type EmbeddedApprovalView, type EmbeddedDecisionResult, type EmbeddedResult, } from "./embedded.js";
+export { classifyRequestResult, type GuardianDecision } from "./lifecycle.js";
+export { fetchReceiptVerificationKeys, verifyReceiptOffline, verifyReceiptOnline, type ReceiptKeySetResult, type ReceiptVerification, } from "./receipts.js";
+export { findAgentSystem, guardianCatalog, verticalsForAction, type GuardianCatalogAgentSystem, type GuardianCatalogVertical, type GuardianPublicCatalog, } from "./catalog.js";

package/dist-dts/lifecycle.d.ts

@@ -0,0 +1,25 @@
+import type { GuardianRequestResult } from "./client.js";
+/**
+ * WO-042 — the single, fail-closed reading of a Guardian request result.
+ *
+ *   ALLOW — a capability token was issued; `execute` redeems it.
+ *   ASK   — held for a human; keep `requestId`, then `claim(requestId)`
+ *           after the human decides. The gateway reports a held ASK as
+ *           `{ ok: false, reasonCode: "APPROVAL_REQUIRED", requestId }`.
+ *   DENY  — everything else, including ambiguity (ALLOW without a token),
+ *           an unknown shape, or Guardian being unreachable.
+ */
+export type GuardianDecision = {
+    decision: "ALLOW";
+    requestId: string;
+    capabilityToken: string;
+} | {
+    decision: "ASK";
+    requestId: string;
+    reasonCode: string;
+} | {
+    decision: "DENY";
+    reasonCode: string;
+    requestId?: string;
+};
+export declare function classifyRequestResult(result: GuardianRequestResult): GuardianDecision;

package/dist-dts/proposal.d.ts

@@ -10,6 +10,21 @@ export declare const AgentActionProposalSchema: z.ZodObject<{
     merchantCategory: z.ZodOptional<z.ZodString>;
     recurring: z.ZodOptional<z.ZodBoolean>;
     taskId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "TaskId", "out">>;
+    intentId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "IntentId", "out">>;
+    planId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "PlanId", "out">>;
+    parentActionId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "RequestId", "out">>;
+    sourceEffectId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "AttemptId", "out">>;
+    compensatesTransactionId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "TransactionId", "out">>;
+    physicalFacts: z.ZodOptional<z.ZodObject<{
+        zone: z.ZodOptional<z.ZodString>;
+        speed: z.ZodOptional<z.ZodNumber>;
+        force: z.ZodOptional<z.ZodNumber>;
+        payload: z.ZodOptional<z.ZodNumber>;
+        atEpochMs: z.ZodOptional<z.ZodNumber>;
+        humanDistance: z.ZodOptional<z.ZodNumber>;
+        environment: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        supervised: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
     uses: z.ZodLiteral<1>;
     materialParameters: z.ZodPipe<z.ZodUnknown, z.ZodTransform<Readonly<Record<string, import("./contracts/canonical-json.js").CanonicalJsonValue>>, unknown>>;
     purpose: z.ZodString;
@@ -21,5 +36,6 @@ export declare const AgentActionProposalSchema: z.ZodObject<{
     }>;
     requestedAdapterId: z.core.$ZodBranded<z.ZodString, "AdapterId", "out">;
     requestedTtlMs: z.ZodNumber;
+    runtime: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type AgentActionProposal = z.infer<typeof AgentActionProposalSchema>;

package/dist-dts/receipts.d.ts

@@ -0,0 +1,37 @@
+import { verifyPortableAuthorityReceipt } from "./evidence/receipt.js";
+/**
+ * WO-042 — portable receipt verification for developers and auditors.
+ *
+ * Offline verification needs only the receipt and Guardian's published
+ * Ed25519 verification keys: no agent credential, account, plan or Guardian
+ * service is involved once the keys are in hand. It checks the
+ * `guardian-canonical-json.v1` signature over the receipt body and
+ * re-derives every embedded record against the receipt's evidence chain.
+ * Verification is never billable (GUA-REVENUE-001).
+ */
+export type ReceiptVerification = ReturnType<typeof verifyPortableAuthorityReceipt>;
+export type ReceiptKeySetResult = {
+    ok: true;
+    keys: unknown;
+} | {
+    ok: false;
+    reasonCode: string;
+};
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+/** Fetch the published verification key set (public; no credential). */
+export declare function fetchReceiptVerificationKeys(baseUrl: string, options?: {
+    fetch?: FetchLike;
+}): Promise<ReceiptKeySetResult>;
+/** Verify a receipt locally against a key set. Pure; no network. */
+export declare function verifyReceiptOffline(receipt: unknown, keys: unknown): ReceiptVerification;
+/** Ask a Guardian deployment to verify a receipt (public endpoint). */
+export declare function verifyReceiptOnline(baseUrl: string, receipt: unknown, options?: {
+    fetch?: FetchLike;
+}): Promise<{
+    ok: true;
+    result: Record<string, unknown>;
+} | {
+    ok: false;
+    reasonCode: string;
+}>;
+export {};

package/package.json

@@ -1,14 +1,19 @@
 {
   "name": "@odingard/guardian-sdk",
-  "version": "0.1.0",
-  "description": "Guardian agent SDK — request governed capabilities and execute consequential actions under human authority.",
+  "version": "0.2.0",
+  "description": "Guardian agent SDK — Human Authority Infrastructure for Autonomous AI. Request governed capabilities and execute consequential actions under human authority.",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
     ".": {
       "types": "./dist-dts/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./contracts": {
+      "types": "./dist-dts/contracts-entry.d.ts",
+      "default": "./dist/contracts.js"
+    },
+    "./catalog.json": "./dist/public-catalog.v1.json"
   },
   "files": [
     "dist",
@@ -20,9 +25,10 @@
     "access": "public"
   },
   "scripts": {
-    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node22 --external:zod --outfile=dist/index.js && tsc -p tsconfig.build.json",
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node22 --external:zod --outfile=dist/index.js && esbuild src/contracts-entry.ts --bundle --platform=node --format=esm --target=node22 --external:zod --outfile=dist/contracts.js && cp src/catalog/public-catalog.v1.json dist/ && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
     "test": "vitest run",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build && npm test"
   },
   "dependencies": {
     "zod": "4.6.5"
@@ -34,7 +40,7 @@
     "vitest": "3.2.4"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "keywords": [
     "guardian",

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

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