safehands-pharos 1.4.0 → 2.6.0

package/dist/lib/policy/actionPolicyEngine.d.ts

@@ -1,54 +1,90 @@
-export type SafeHandsActionType = "send_payment" | "approve_token" | "execute_swap" | "x402_pay_and_fetch" | "publish_risk_score" | "custom_contract_call";
-export type PolicyDecision = "ALLOW" | "WARN" | "BLOCK" | "REQUIRE_CONFIRMATION" | "REQUIRE_FUNDING" | "REQUIRE_TOKEN_REVIEW";
-export type PolicyRiskLevel = "LOW" | "MEDIUM" | "HIGH" | "CRITICAL" | "UNKNOWN";
-export interface PolicyCheck {
-    name: string;
-    status: "pass" | "warn" | "fail" | "unknown";
-    message: string;
-}
-export interface ActionPolicyInput {
-    actionType: SafeHandsActionType;
-    environment?: string;
-    chainId?: number;
-    isMainnet?: boolean;
-    amount?: string;
-    amountUnit?: "PHRS" | "USDC" | "USD" | "TOKEN";
-    token?: string;
-    tokenAddress?: string;
-    tokenIn?: string;
-    tokenOut?: string;
-    recipient?: string;
-    spender?: string;
-    approvalAmount?: string;
-    approvalToken?: string;
-    approvalUnlimited?: boolean;
-    url?: string;
-    paymentAmountUsdc?: string;
-    paymentTokenAddress?: string;
-    walletAddress?: string;
-    walletBalancePhs?: string;
-    signerAvailable?: boolean;
-    tokenSecurityStatus?: "ok" | "unavailable" | "unknown";
-    tokenRegistryStatus?: string;
-    recipientVerified?: boolean;
-    spenderVerified?: boolean;
-    allowUnlimitedApproval?: boolean;
-    writeToolsEnabled?: boolean;
-    requiresSigner?: boolean;
-}
-export interface ActionPolicyResult {
-    decision: PolicyDecision;
-    riskLevel: PolicyRiskLevel;
-    safeToExecute: boolean;
-    reasons: string[];
-    requiredActions: string[];
-    checks: PolicyCheck[];
-    environment: string;
-    chainId: number;
-    isMainnet: boolean;
-}
-export declare function isUnlimitedApprovalAmount(value: string | undefined): boolean;
-export declare function evaluateActionPolicy(input: ActionPolicyInput): ActionPolicyResult;
-export declare function explainPolicyResult(result: ActionPolicyResult): string;
-export declare function parseTokenAmountToUnits(amount: string, decimals?: number): bigint | null;
+import { type AgentPolicy } from "./agentPolicy.js";
+import type { RiskAssessment } from "../riskEngine.js";
+export type SafeHandsActionType = "send_payment" | "approve_token" | "execute_swap" | "x402_pay_and_fetch" | "publish_risk_score" | "custom_contract_call";
+export type PolicyDecision = "ALLOW" | "WARN" | "BLOCK" | "REQUIRE_CONFIRMATION" | "REQUIRE_FUNDING" | "REQUIRE_TOKEN_REVIEW";
+export type PolicyRiskLevel = "LOW" | "MEDIUM" | "HIGH" | "CRITICAL" | "UNKNOWN";
+export interface PolicyCheck {
+    name: string;
+    status: "pass" | "warn" | "fail" | "unknown";
+    message: string;
+}
+/**
+ * Advisory risk-engine output passed to the policy engine as EVIDENCE. The
+ * policy engine, not the risk engine, decides (see docs/DECISION_CONTRACT.md).
+ * Check names derived from this evidence are `risk_*` — deliberately containing
+ * neither "token" nor "funding" so the decision remap below never applies.
+ */
+export interface PolicyRiskEvidence {
+    /** 0-100 weighted risk score. */
+    score: number;
+    /** Critical risk signal could not be evaluated: never sign silently. */
+    degraded: boolean;
+    degradedReasons?: string[];
+    /** Counterparty breakdown dimension (0-100). */
+    counterpartyRisk?: number;
+    /** Structural SWAP_LIQUIDITY_NOT_CONFIGURED state (permanent, not transient). */
+    swapProviderNotConfigured?: boolean;
+}
+/** Projects a RiskAssessment into the policy-evidence shape. Single mapper — write tools must use this rather than hand-rolling the projection. */
+export declare function riskEvidenceFromAssessment(a: RiskAssessment): PolicyRiskEvidence;
+export interface ActionPolicyInput {
+    actionType: SafeHandsActionType;
+    environment?: string;
+    chainId?: number;
+    isMainnet?: boolean;
+    amount?: string;
+    amountUnit?: "PROS" | "USDC" | "USD" | "TOKEN";
+    token?: string;
+    tokenAddress?: string;
+    tokenIn?: string;
+    tokenOut?: string;
+    recipient?: string;
+    spender?: string;
+    targetContract?: string;
+    approvalAmount?: string;
+    approvalToken?: string;
+    approvalUnlimited?: boolean;
+    url?: string;
+    paymentAmountUsdc?: string;
+    paymentTokenAddress?: string;
+    walletAddress?: string;
+    walletBalancePhs?: string;
+    signerAvailable?: boolean;
+    tokenSecurityStatus?: "ok" | "unavailable" | "unknown";
+    tokenRegistryStatus?: string;
+    /**
+     * Caller CLAIM that the recipient was verified — never independently confirmed
+     * by this engine. Omitted = treated as unverified (fail-closed), never as safe.
+     */
+    recipientVerified?: boolean;
+    /** Caller CLAIM (same semantics as recipientVerified). */
+    spenderVerified?: boolean;
+    allowUnlimitedApproval?: boolean;
+    writeToolsEnabled?: boolean;
+    requiresSigner?: boolean;
+    agentId?: string;
+    agentPolicy?: AgentPolicy;
+    /**
+     * Advisory risk-engine output passed as EVIDENCE (riskEvidenceFromAssessment).
+     * Write tools MUST provide this and gate with `requireRiskEvidence: true` —
+     * never gate on riskEngine output directly. Omitted by structural/preflight
+     * callers, which then get no risk_* checks.
+     */
+    risk?: PolicyRiskEvidence;
+}
+export interface ActionPolicyResult {
+    decision: PolicyDecision;
+    riskLevel: PolicyRiskLevel;
+    safeToExecute: boolean;
+    reasons: string[];
+    requiredActions: string[];
+    checks: PolicyCheck[];
+    environment: string;
+    chainId: number;
+    isMainnet: boolean;
+}
+export declare function isUnlimitedApprovalAmount(value: string | undefined): boolean;
+export declare function evaluateActionPolicy(input: ActionPolicyInput): ActionPolicyResult;
+export declare function explainPolicyResult(result: ActionPolicyResult): string;
+export declare function parseTokenAmountToUnits(amount: string, decimals?: number): bigint | null;
 //# sourceMappingURL=actionPolicyEngine.d.ts.map

package/dist/lib/policy/actionPolicyEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actionPolicyEngine.d.ts","sourceRoot":"","sources":["../../../src/lib/policy/actionPolicyEngine.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,mBAAmB,GAC3B,cAAc,GACd,eAAe,GACf,cAAc,GACd,oBAAoB,GACpB,oBAAoB,GACpB,sBAAsB,CAAC;AAE3B,MAAM,MAAM,cAAc,GACtB,OAAO,GACP,MAAM,GACN,OAAO,GACP,sBAAsB,GACtB,iBAAiB,GACjB,sBAAsB,CAAC;AAE3B,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;AAEjF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC7C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,mBAAmB,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,CAAC;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,mBAAmB,CAAC,EAAE,IAAI,GAAG,aAAa,GAAG,SAAS,CAAC;IACvD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,cAAc,CAAC;IACzB,SAAS,EAAE,eAAe,CAAC;IAC3B,aAAa,EAAE,OAAO,CAAC;IACvB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;CACpB;AAuBD,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAS5E;AAsCD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,iBAAiB,GAAG,kBAAkB,CA4HjF;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAQtE;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,GAAG,IAAI,CAMnF"}
+{"version":3,"file":"actionPolicyEngine.d.ts","sourceRoot":"","sources":["../../../src/lib/policy/actionPolicyEngine.ts"],"names":[],"mappings":"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"}