@wowok/agent-mcp 2.4.1 → 2.5.0

package/dist/knowledge/payment-risk.js

@@ -0,0 +1,182 @@
+import { MAX_RECIPIENT_COUNT } from "@wowok/wowok";
+const R_P_01 = {
+    rule: {
+        id: "R-PAYMENT-01",
+        level: "HIGH",
+        category: "permission",
+        title: "unwrap() performs no Payment match check — may unwrap wrong CoinWrapper",
+        description: "unwrap(wrapper, ctx) (payment.move:50) returns (Coin, payment_address) without " +
+            "verifying that wrapper.payment matches any expected Payment. Callers who use unwrap " +
+            "instead of unwrap_with_check can unwrap a CoinWrapper that was minted for a different " +
+            "Payment, leading to fund loss or accounting corruption. unwrap_with_check(payment_check) " +
+            "exists specifically to enforce the match (payment.move:54).",
+        affected_stakeholders: ["signer", "recipient"],
+        scenario: "Caller uses unwrap on a wrapper from a different Payment; funds are released anyway",
+        mitigation: "SDK should force callers to use unwrap_with_check and deprecate direct unwrap calls. " +
+            "The only safe use of unwrap is when the caller has already verified the match off-chain.",
+        related_move_error: "EPAYMENT_NOT_MATCH (3) — only raised by unwrap_with_check",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.uses_unsafe_unwrap)
+            return null;
+        return { ...R_P_01.rule, evidence: "uses_unsafe_unwrap=true (no Payment match check)" };
+    },
+};
+const R_P_02 = {
+    rule: {
+        id: "R-PAYMENT-02",
+        level: "MEDIUM",
+        category: "structural",
+        title: `MAX_RECIPIENT_COUNT=${MAX_RECIPIENT_COUNT} permissive — gas and confirmation cost`,
+        description: `A single Payment may carry up to MAX_RECIPIENT_COUNT=${MAX_RECIPIENT_COUNT} recipients ` +
+            `(payment.move:14). The limit aborts with ERECIPIENT_COUNT_EXCEEDED (1) only at the boundary. ` +
+            `200 recipients in one transaction inflates gas, slows finalization, and complicates ` +
+            `retry on partial failure.`,
+        affected_stakeholders: ["signer", "recipient"],
+        scenario: "Caller submits a Payment with 200 recipients; transaction is heavy and slow",
+        mitigation: "Business layer should self-limit recipient count (e.g. ≤50). For mass payouts, split " +
+            "across multiple Payment objects in separate transactions.",
+        related_move_error: "ERECIPIENT_COUNT_EXCEEDED (1)",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (ctx.recipient_count === undefined)
+            return null;
+        if (ctx.recipient_count < MAX_RECIPIENT_COUNT)
+            return null;
+        return { ...R_P_02.rule, evidence: `recipient_count=${ctx.recipient_count}, limit=${MAX_RECIPIENT_COUNT}` };
+    },
+};
+const R_P_03 = {
+    rule: {
+        id: "R-PAYMENT-03",
+        level: "LOW",
+        category: "lifecycle",
+        title: "Payment is immutable after create — errors cannot be corrected",
+        description: "create() calls transfer::freeze_object(payment) (payment.move:160). All fields " +
+            "(amount, time, info, from_object, signer, record) are permanently fixed. There is no " +
+            "update, refund, or void API on the Payment object itself — correction requires a new " +
+            "Payment (and off-chain reconciliation).",
+        affected_stakeholders: ["signer", "consumer"],
+        scenario: "Signer mistypes a recipient address; the Payment cannot be edited post-create",
+        mitigation: "Verify all fields before calling create. For refunds, create a new Payment in the " +
+            "opposite direction. Off-chain systems should treat Payment as an immutable receipt.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.expects_mutation)
+            return null;
+        return { ...R_P_03.rule, evidence: "expects_mutation=true (Payment is frozen at create)" };
+    },
+};
+const R_P_04 = {
+    rule: {
+        id: "R-PAYMENT-04",
+        level: "MEDIUM",
+        category: "structural",
+        title: "CoinWrapper suppresses coin_field lint — Balance<T> stored in a struct field",
+        description: "CoinWrapper<phantom T> stores Balance<T> directly in a struct field and uses " +
+            "#[allow(lint(coin_field))] to suppress the Wow lint (payment.move:43-48). The lint " +
+            "normally warns against storing Balance in arbitrary structs because of object " +
+            "lifecycle concerns. The suppression is intentional but should be reviewed whenever " +
+            "the Wow framework updates its coin_field rules.",
+        affected_stakeholders: ["system"],
+        scenario: "Wow framework tightens coin_field lint semantics; CoinWrapper becomes non-compliant",
+        mitigation: "Review the coin_field suppression on each Wow upgrade. Confirm that Balance<T> " +
+            "ownership transfer in unwrap/unwrap_with_check is correct.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (ctx.coin_field_lint_reviewed)
+            return null;
+        return { ...R_P_04.rule, evidence: "coin_field_lint_reviewed=false (needs review)" };
+    },
+};
+const R_P_05 = {
+    rule: {
+        id: "R-PAYMENT-05",
+        level: "LOW",
+        category: "semantic",
+        title: "PaymentInfo has 4 constructor variants — caller may pick the wrong one",
+        description: "PaymentInfo can be built via payment_info (for_object+remark+index), payment_info2 " +
+            "(remark+index, no for_object), payment_info_with_guard (for_object+for_guard+remark+index), " +
+            "or payment_info2_with_guard (for_guard+remark+index, no for_object). Selecting the " +
+            "wrong variant leaves for_object/for_guard as None, breaking downstream lookups.",
+        affected_stakeholders: ["signer", "consumer"],
+        scenario: "Caller uses payment_info2 when they meant payment_info_with_guard; for_object is lost",
+        mitigation: "Document each variant's use case clearly. SDK should pick the variant automatically " +
+            "based on which optional fields the caller provides.",
+        auto_fixable: true,
+    },
+    check: (ctx) => null,
+};
+const R_P_06 = {
+    rule: {
+        id: "R-PAYMENT-06",
+        level: "MEDIUM",
+        category: "cross_object",
+        title: "Registrar registration filters recipients by is_object_address — user addresses skipped",
+        description: "create() iterates recipients and only calls registrar.affiliation for addresses that " +
+            "pass util::is_object_address (payment.move:147-161). User addresses (EOAs) are not " +
+            "registered in the Registrar dependency graph. Callers who expect every recipient to " +
+            "appear in affiliation queries will miss EOA recipients.",
+        affected_stakeholders: ["signer", "consumer"],
+        scenario: "Caller queries Registrar for all Payment recipients; EOA recipients are missing",
+        mitigation: "Document that affiliation is registered only for object-address recipients. Off-chain " +
+            "systems should track EOA recipients via the NewPaymentEvent record, not via Registrar.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.expects_user_recipient_registered)
+            return null;
+        return { ...R_P_06.rule, evidence: "expects_user_recipient_registered=true (EOAs are skipped)" };
+    },
+};
+const R_P_07 = {
+    rule: {
+        id: "R-PAYMENT-07",
+        level: "LOW",
+        category: "semantic",
+        title: "Payment.signer records payer — useful for provenance but not authorization",
+        description: "Payment.signer is set to ctx.sender() at creation (payment.move). It can be read via " +
+            "payment_signer<T>(payment) for provenance (e.g. 'who paid for this order'). It is " +
+            "purely informational — it does NOT authorize any later operation. Consumers must not " +
+            "treat signer as a permission grant.",
+        affected_stakeholders: ["consumer"],
+        scenario: "Consumer treats Payment.signer as authorizing a refund; signer is just provenance",
+        mitigation: "Use Payment.signer only for audit/provenance. Authorization must come from the " +
+            "referencing object's own Permission, not from Payment.signer.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.uses_signer_for_provenance)
+            return null;
+        return { ...R_P_07.rule, evidence: "uses_signer_for_provenance=true (informational only)" };
+    },
+};
+export const PAYMENT_RISK_RULES = [
+    R_P_01,
+    R_P_02,
+    R_P_03,
+    R_P_04,
+    R_P_05,
+    R_P_06,
+    R_P_07,
+];
+export const PAYMENT_RISK_VERSION = "1.0.0";
+export function checkPaymentRisks(ctx) {
+    const risks = [];
+    for (const rule of PAYMENT_RISK_RULES) {
+        const r = rule.check(ctx);
+        if (r)
+            risks.push(r);
+    }
+    if (!risks.find(r => r.id === "R-PAYMENT-05")) {
+        risks.push(R_P_05.rule);
+    }
+    return risks;
+}
+export function getPaymentRiskById(id) {
+    return PAYMENT_RISK_RULES.find(r => r.rule.id === id)?.rule;
+}

package/dist/knowledge/permission-confirm.d.ts

@@ -0,0 +1,110 @@
+import { type PermissionRiskAssessment } from "./permission-risk.js";
+export type ConfirmGateStatus = "approved" | "blocked_checklist" | "blocked_risk" | "blocked_user" | "blocked_environment";
+export interface ConfirmGateResult {
+    status: ConfirmGateStatus;
+    checklist_result: ChecklistResult;
+    risk_result?: PermissionRiskAssessment;
+    user_confirmation?: UserConfirmation;
+    environment_result?: EnvironmentResult;
+    confirmation_text?: string;
+    block_reason?: string;
+    decision_record: DecisionRecord;
+}
+export interface ChecklistResult {
+    all_passed: boolean;
+    items: ChecklistItem[];
+}
+export interface ChecklistItem {
+    id: string;
+    description: string;
+    passed: boolean;
+    message: string;
+}
+export interface UserConfirmation {
+    questions_asked: ConfirmationQuestion[];
+    responses: ConfirmationResponse[];
+    all_confirmed: boolean;
+}
+export interface ConfirmationQuestion {
+    id: string;
+    question: string;
+    requires_explicit_yes: boolean;
+    related_risk_ids?: string[];
+}
+export interface ConfirmationResponse {
+    question_id: string;
+    response: "yes" | "no" | "skip";
+}
+export interface EnvironmentResult {
+    passed: boolean;
+    checks: {
+        name: string;
+        passed: boolean;
+        message: string;
+    }[];
+}
+export interface DecisionRecord {
+    timestamp: string;
+    gate_version: string;
+    final_status: ConfirmGateStatus;
+    layers_passed: string[];
+    layers_failed: string[];
+}
+export interface PermissionJsonForConfirm {
+    object?: string | null;
+    description?: string;
+    admin?: {
+        op: string;
+        addresses: string[];
+    };
+    table?: {
+        op: string;
+        index: number;
+        entity: string[];
+    } | {
+        op: string;
+        entity: string;
+        index: number[];
+    };
+    entity?: {
+        op: string;
+        entity1: string;
+        entity2: string;
+    } | {
+        op: string;
+        entity: string;
+    };
+    remark?: {
+        op: string;
+        index: number;
+        remark: string;
+    } | {
+        op: string;
+        index: number;
+    } | {
+        op: string;
+    };
+    apply?: string[];
+    builder?: string;
+    um?: string | null;
+}
+export interface ConfirmGateInput {
+    permission_json: PermissionJsonForConfirm;
+    intent?: string;
+    target_objects_types?: string[];
+    current_admin_count?: number;
+    current_entity_count?: number;
+    skip_user_confirmation?: boolean;
+    skip_environment_check?: boolean;
+}
+export declare const PERMISSION_PUBLISH_CHECKLIST: ChecklistItem[];
+export declare const PERMISSION_CONFIRMATION_QUESTIONS: ConfirmationQuestion[];
+export declare const PERMISSION_CONFIRM_VERSION = "1.0.0";
+export declare function runPermissionConfirmGate(input: ConfirmGateInput): ConfirmGateResult;
+export interface ProgressiveCheckResult {
+    stage: "checklist" | "risk" | "confirmation" | "environment" | "complete";
+    status: "pass" | "fail" | "pending";
+    message: string;
+    next_action?: string;
+}
+export declare function progressivePermissionCheck(input: ConfirmGateInput): ProgressiveCheckResult;