@yiaany/ghostapi 0.1.7 → 0.1.9

package/dist/actions/gateway.d.ts

@@ -0,0 +1,179 @@
+import { KeyObject } from "node:crypto";
+import { type LocalSafetyController } from "../safety/index.js";
+export type ActionRiskClass = "read" | "write" | "money_movement" | "external_communication" | "delete" | "deploy";
+export type ActionReversibility = "none" | "compensatable";
+export type ActionReceiptStatus = "requested" | "attempted" | "committed" | "verified" | "failed";
+export type ActionEnvelope = {
+    schemaVersion: 1;
+    kind: "ghostapi.action";
+    actionId: string;
+    idempotencyKey: string;
+    actor: {
+        id: string;
+        workloadId: string;
+        type: "agent" | "service";
+    };
+    project: {
+        id: string;
+        environment: "synthetic";
+    };
+    provider: "ghostapi-synthetic";
+    operation: string;
+    resource: {
+        type: "synthetic-world";
+        id: string;
+    };
+    arguments: {
+        worldId: string;
+    };
+    expectedSideEffects: readonly string[];
+    riskClass: ActionRiskClass;
+    reversibility: ActionReversibility;
+    policy: {
+        version: number;
+        hash: string;
+    };
+    evidence: {
+        hash: string;
+    };
+    expiresAt: string;
+    nonce: string;
+};
+export type ActionApproval = {
+    schemaVersion: 1;
+    kind: "ghostapi.action-approval";
+    approvalId: string;
+    actionHash: string;
+    approvedBy: string;
+    approvedAt: string;
+    expiresAt: string;
+    nonce: string;
+    provenance: {
+        kind: "ghostapi.ed25519-signature";
+        keyId: string;
+        signature: string;
+    };
+};
+export type UnsignedActionApproval = Omit<ActionApproval, "provenance">;
+export type ActionExecutionReceipt = {
+    receiptId: string;
+    actionId: string;
+    actionHash: string;
+    status: ActionReceiptStatus;
+    timestamp: string;
+    providerRequestId?: string;
+    result?: {
+        worldId: string;
+        subscriptionId: string;
+        syntheticReceiptId: string;
+    };
+    failure?: {
+        code: "execution_error" | "unknown_outcome" | "verification_failed";
+        retrySafe: false;
+    };
+    previousReceiptHash: string;
+    receiptHash: string;
+};
+export type StoredAction = {
+    schemaVersion: 1;
+    kind: "ghostapi.action-record";
+    envelope: ActionEnvelope;
+    actionHash: string;
+    approval: ActionApproval;
+    receipts: ActionExecutionReceipt[];
+};
+export type ActionExecutionIdentity = {
+    actorId: string;
+    workloadId: string;
+};
+export type ActionPolicyCheck = {
+    version: number;
+    hash: string;
+    allowed: boolean;
+};
+export type ActionApprovalVerificationContext = {
+    phase: "submit" | "execute";
+};
+export type ActionApprovalVerification = {
+    provenance: "verified";
+    approvalInboxRequestId?: string;
+};
+export interface ActionApprovalVerifier {
+    verify(action: ActionEnvelope, approval: unknown, context: ActionApprovalVerificationContext): Promise<ActionApprovalVerification>;
+}
+export interface ActionApprovalSigner {
+    issue(approval: UnsignedActionApproval): ActionApproval | Promise<ActionApproval>;
+}
+export type ActionExecutionAdapter = {
+    provider: ActionEnvelope["provider"];
+    supports(operation: string): boolean;
+    plan(action: ActionEnvelope): Promise<void>;
+    simulate(action: ActionEnvelope): Promise<void>;
+    execute(action: ActionEnvelope, controls?: {
+        commit<T>(operation: () => Promise<T>): Promise<T>;
+    }): Promise<{
+        outcome: "committed";
+        providerRequestId: string;
+        result: {
+            worldId: string;
+            subscriptionId: string;
+            syntheticReceiptId: string;
+        };
+    } | {
+        outcome: "unknown";
+    }>;
+    verify(action: ActionEnvelope): Promise<{
+        committed: boolean;
+        providerRequestId?: string;
+        result?: {
+            worldId: string;
+            subscriptionId: string;
+            syntheticReceiptId: string;
+        };
+    }>;
+    compensate?: (action: ActionEnvelope) => Promise<void>;
+};
+export type ActionGatewayOptions = {
+    now?: () => Date;
+    pathForAction?: (actionId: string) => string;
+    adapter?: ActionExecutionAdapter;
+    safetyController?: LocalSafetyController;
+    approvalVerifier?: ActionApprovalVerifier;
+};
+export declare class ActionGatewayError extends Error {
+    constructor(message: string);
+}
+export declare function canonicalizeActionEnvelope(value: unknown): string;
+export declare function actionHash(value: unknown): string;
+export declare function actionApprovalHash(value: unknown): string;
+export declare function validateActionEnvelope(value: unknown): ActionEnvelope;
+export declare function validateActionApproval(value: unknown): ActionApproval;
+export declare function createSyntheticActionAdapter(): ActionExecutionAdapter;
+export declare class LocalActionGateway {
+    private readonly now;
+    private readonly pathForAction;
+    private readonly adapter;
+    private readonly safetyController;
+    private readonly approvalVerifier;
+    constructor(options?: ActionGatewayOptions);
+    submit(actionValue: unknown, approvalValue: unknown, policy: ActionPolicyCheck): Promise<StoredAction>;
+    inspect(actionId: string): Promise<StoredAction>;
+    execute(actionValue: unknown, identity: ActionExecutionIdentity, policy: ActionPolicyCheck): Promise<ActionExecutionReceipt>;
+    compensate(actionId: string): Promise<never>;
+}
+export declare function createLocalActionGateway(options?: ActionGatewayOptions): LocalActionGateway;
+export declare function createDisabledActionApprovalVerifier(): ActionApprovalVerifier;
+export declare function createEd25519ActionApprovalSigner(options: {
+    keyId: string;
+    privateKey: string | Buffer | KeyObject;
+}): ActionApprovalSigner;
+export declare function createEd25519ActionApprovalVerifier(options: {
+    trustedKeys: Readonly<Record<string, string | Buffer | KeyObject>>;
+}): ActionApprovalVerifier;
+export declare function createTestActionApprovalVerifier(): {
+    verifier: ActionApprovalVerifier;
+    signer: ActionApprovalSigner;
+    issue<T extends UnsignedActionApproval>(approval: T): ActionApproval;
+};
+export declare function getActionPath(actionId: string): string;
+export declare function validateStoredAction(value: unknown): StoredAction;