@wowok/agent-mcp 2.4.1 → 2.5.0

package/dist/knowledge/personal-risk.d.ts

@@ -0,0 +1,36 @@
+export type PersonalRiskLevel = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "INFO";
+export type PersonalRiskCategory = "structural" | "semantic" | "lifecycle" | "cross_object" | "knowledge";
+export type PersonalStakeholder = "user" | "consumer" | "system";
+export interface PersonalRisk {
+    id: string;
+    level: PersonalRiskLevel;
+    category: PersonalRiskCategory;
+    title: string;
+    description: string;
+    affected_stakeholders: PersonalStakeholder[];
+    scenario: string;
+    mitigation: string;
+    evidence?: string;
+    related_move_error?: string;
+    auto_fixable: boolean;
+}
+export interface PersonalRiskCheckContext {
+    information_entries?: Array<{
+        name: string;
+        value: unknown;
+    }>;
+    is_mark_destroy?: boolean;
+    has_referrer?: boolean;
+    is_mark_transfer?: boolean;
+    information_count?: number;
+    expects_dedicated_move_struct?: boolean;
+    singleton_enforced?: boolean;
+    constants_synced?: boolean;
+}
+export declare const PERSONAL_RISK_RULES: {
+    rule: PersonalRisk;
+    check: (ctx: PersonalRiskCheckContext) => PersonalRisk | null;
+}[];
+export declare const PERSONAL_RISK_VERSION = "1.0.0";
+export declare function checkPersonalRisks(ctx: PersonalRiskCheckContext): PersonalRisk[];
+export declare function getPersonalRiskById(id: string): PersonalRisk | undefined;

package/dist/knowledge/personal-risk.js

@@ -0,0 +1,212 @@
+import { MAX_ADDRESS_COUNT, MAX_RECORD_COUNT_REGISTRAR, MAX_RECORD_LENGTH, MAX_TAGS_COUNT, } from "@wowok/wowok";
+function detectSensitiveInformation(entries) {
+    const hits = [];
+    for (const e of entries) {
+        const v = typeof e.value === "string" ? e.value : String(e.value ?? "");
+        const lower = v.toLowerCase();
+        if (/^\+?\d{10,15}$/.test(v))
+            hits.push(`${e.name}=phone-like`);
+        if (/[^\s@]+@[^\s@]+\.[^\s@]+/.test(v))
+            hits.push(`${e.name}=email-like`);
+        if (/^(0x)?[0-9a-fA-F]{64}$/.test(v))
+            hits.push(`${e.name}=private-key-like`);
+        if (/^([a-z]{3,8}\s){11,23}[a-z]{3,8}$/.test(v.trim()))
+            hits.push(`${e.name}=mnemonic-like`);
+        if (/private[_-]?key|secret|mnemonic|seed/i.test(e.name))
+            hits.push(`${e.name}=secret-named`);
+        void lower;
+    }
+    return hits;
+}
+const R_PE_01 = {
+    rule: {
+        id: "R-PERSONAL-01",
+        level: "HIGH",
+        category: "semantic",
+        title: "Sensitive information leakage — on-chain data is permanent",
+        description: "information is stored via Entity.info_add as on-chain Records. The schema description " +
+            "warns 'NEVER: phone, address, private keys' but the Move layer does not validate " +
+            "content. Once a phone number, physical address, email, or private key is written " +
+            "on-chain, it is permanent and publicly readable — there is no delete (info_remove " +
+            "only removes the named entry from the user's record; the data remains in the " +
+            "transaction history).",
+        affected_stakeholders: ["user"],
+        scenario: "User adds information {name: 'phone', value: '+8613800000000'}; number is public forever",
+        mitigation: "MCP schema description MUST warn. AI agents MUST re-confirm before adding any " +
+            "information entry. Business layer should run a sensitive-data regex (phone/email/" +
+            "private-key/mnemonic) and reject matches. Use the 'local' tool for private data.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.information_entries || ctx.information_entries.length === 0)
+            return null;
+        const hits = detectSensitiveInformation(ctx.information_entries);
+        if (hits.length === 0)
+            return null;
+        return { ...R_PE_01.rule, evidence: `sensitive patterns: ${hits.join("; ")}` };
+    },
+};
+const R_PE_02 = {
+    rule: {
+        id: "R-PERSONAL-02",
+        level: "MEDIUM",
+        category: "lifecycle",
+        title: "mark destroy is irreversible — identity mark permanently lost",
+        description: "The 'destroy' mark op permanently deletes the Resource object backing the user's " +
+            "identity mark. There is no archive, no event, and no rollback. After destroy, the " +
+            "user has no on-chain identity mark until they create a new one, and any external " +
+            "system keyed on the old Resource address breaks.",
+        affected_stakeholders: ["user", "consumer"],
+        scenario: "User destroys their mark; downstream services keyed on the old Resource address fail",
+        mitigation: "Require explicit confirmation before destroy. SDK should refuse destroy if any " +
+            "live consumer still references the mark. Provide a 'replace' alternative that " +
+            "swaps the underlying Resource without losing continuity.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.is_mark_destroy)
+            return null;
+        return { ...R_PE_02.rule, evidence: "is_mark_destroy=true (irreversible)" };
+    },
+};
+const R_PE_03 = {
+    rule: {
+        id: "R-PERSONAL-03",
+        level: "MEDIUM",
+        category: "semantic",
+        title: "referrer chain can be abused to fabricate trust signals",
+        description: "When registering, a user may specify any referrer address. There is no on-chain " +
+            "verification that the referrer actually invited the user. A sybil attacker can " +
+            "register many accounts chained to a reputable address, fabricating an affiliation " +
+            "to borrow trust. The Registrar records referrer but does not validate consent.",
+        affected_stakeholders: ["user", "consumer"],
+        scenario: "Attacker registers 100 accounts all citing a reputable merchant as referrer",
+        mitigation: "Business layer should treat referrer as a self-attested hint, not a verified trust " +
+            "signal. Audit referrer chains off-chain; require the referrer to co-sign if used for " +
+            "trust scoring.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.has_referrer)
+            return null;
+        return { ...R_PE_03.rule, evidence: "has_referrer=true (self-attested, unverified)" };
+    },
+};
+const R_PE_04 = {
+    rule: {
+        id: "R-PERSONAL-04",
+        level: "LOW",
+        category: "structural",
+        title: `information inherits MAX_RECORD_COUNT_REGISTRAR=${MAX_RECORD_COUNT_REGISTRAR} — permissive`,
+        description: `Personal does not define its own record cap; it inherits Entity's ` +
+            `MAX_RECORD_COUNT_REGISTRAR=${MAX_RECORD_COUNT_REGISTRAR} (registrar.move) and ` +
+            `MAX_RECORD_LENGTH=${MAX_RECORD_LENGTH} per record. ${MAX_RECORD_COUNT_REGISTRAR} records ` +
+            `per user is generous and can bloat on-chain storage if users add many entries. ` +
+            `MAX_ADDRESS_COUNT=${MAX_ADDRESS_COUNT} and MAX_TAGS_COUNT=${MAX_TAGS_COUNT} also apply via Entity/Resource.`,
+        affected_stakeholders: ["user", "system"],
+        scenario: "User adds 1000 information entries; Entity record storage is heavy and slow to read",
+        mitigation: "Business layer should self-limit information count (e.g. ≤50). For bulk profile data, " +
+            "store off-chain and reference via a Repository or Proof.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (ctx.information_count === undefined)
+            return null;
+        if (ctx.information_count < MAX_RECORD_COUNT_REGISTRAR)
+            return null;
+        return {
+            ...R_PE_04.rule,
+            evidence: `information_count=${ctx.information_count}, limit=${MAX_RECORD_COUNT_REGISTRAR}`,
+        };
+    },
+};
+const R_PE_05 = {
+    rule: {
+        id: "R-PERSONAL-05",
+        level: "MEDIUM",
+        category: "lifecycle",
+        title: "mark transfer loses identity mark at the source address",
+        description: "The 'transfer' mark op moves the Resource backing the identity mark to a new address. " +
+            "After transfer, the source address has no mark — any service that keyed identity on " +
+            "the source address loses the binding. There is no automatic forwarding stub left behind.",
+        affected_stakeholders: ["user", "consumer"],
+        scenario: "User transfers mark to a new wallet; old-wallet-based logins all break",
+        mitigation: "Surface a 'transfer will detach the mark from this address' warning. Consumers should " +
+            "track marks by Resource address, not by user address. Provide a migration window " +
+            "where both addresses are valid.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.is_mark_transfer)
+            return null;
+        return { ...R_PE_05.rule, evidence: "is_mark_transfer=true (source loses mark)" };
+    },
+};
+const R_PE_06 = {
+    rule: {
+        id: "R-PERSONAL-06",
+        level: "LOW",
+        category: "cross_object",
+        title: "Personal has no dedicated Move struct — depends entirely on Entity + Resource",
+        description: "Personal is an SDK-layer construct: there is no personal.move. The SDK composes " +
+            "Entity (information/description) and Resource (mark) on behalf of the user. Any " +
+            "breaking change in Entity or Resource directly affects Personal. The MCP layer " +
+            "cannot fix Personal bugs without touching Entity/Resource.",
+        affected_stakeholders: ["system"],
+        scenario: "Entity schema changes; Personal.information silently breaks",
+        mitigation: "Track Entity and Resource changelogs as first-order dependencies of Personal. Add " +
+            "integration tests that exercise Personal flows whenever Entity/Resource change.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.expects_dedicated_move_struct)
+            return null;
+        return { ...R_PE_06.rule, evidence: "expects_dedicated_move_struct=true (none exists)" };
+    },
+};
+const R_PE_07 = {
+    rule: {
+        id: "R-PERSONAL-07",
+        level: "MEDIUM",
+        category: "lifecycle",
+        title: "Singleton assumption — if violated, multiple Personal instances conflict",
+        description: "Personal assumes each account has exactly one Entity record (and one Resource mark). " +
+            "The Move layer enforces this via entity_register's idempotency (returns the existing " +
+            "Resource for already-registered users). But if the SDK ever bypasses entity_register " +
+            "and creates duplicates (e.g. via entity_register_with_resource_forced), downstream " +
+            "code that assumes a singleton would see inconsistent state.",
+        affected_stakeholders: ["user", "consumer"],
+        scenario: "SDK calls entity_register_with_resource_forced; user now has two Resource marks",
+        mitigation: "SDK MUST enforce the singleton invariant: refuse to call entity_register_with_resource_forced " +
+            "unless the user explicitly opts in. Document that forced re-registration invalidates " +
+            "the old Resource address.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (ctx.singleton_enforced)
+            return null;
+        return { ...R_PE_07.rule, evidence: "singleton_enforced=false (needs SDK guard)" };
+    },
+};
+export const PERSONAL_RISK_RULES = [
+    R_PE_01,
+    R_PE_02,
+    R_PE_03,
+    R_PE_04,
+    R_PE_05,
+    R_PE_06,
+    R_PE_07,
+];
+export const PERSONAL_RISK_VERSION = "1.0.0";
+export function checkPersonalRisks(ctx) {
+    const risks = [];
+    for (const rule of PERSONAL_RISK_RULES) {
+        const r = rule.check(ctx);
+        if (r)
+            risks.push(r);
+    }
+    return risks;
+}
+export function getPersonalRiskById(id) {
+    return PERSONAL_RISK_RULES.find(r => r.rule.id === id)?.rule;
+}

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

@@ -0,0 +1,108 @@
+import { type ProgressRiskAssessment } from "./progress-risk.js";
+export type ProgressConfirmGateStatus = "approved" | "blocked_checklist" | "blocked_risk" | "blocked_user" | "blocked_environment";
+export interface ProgressConfirmGateResult {
+    status: ProgressConfirmGateStatus;
+    checklist_result: ProgressChecklistResult;
+    risk_result?: ProgressRiskAssessment;
+    user_confirmation?: ProgressUserConfirmation;
+    environment_result?: ProgressEnvironmentResult;
+    confirmation_text?: string;
+    block_reason?: string;
+    decision_record: ProgressDecisionRecord;
+}
+export interface ProgressChecklistResult {
+    all_passed: boolean;
+    items: ProgressChecklistItem[];
+}
+export interface ProgressChecklistItem {
+    id: string;
+    description: string;
+    passed: boolean;
+    message: string;
+}
+export interface ProgressUserConfirmation {
+    questions_asked: ProgressConfirmationQuestion[];
+    responses: ProgressConfirmationResponse[];
+    all_confirmed: boolean;
+}
+export interface ProgressConfirmationQuestion {
+    id: string;
+    question: string;
+    requires_explicit_yes: boolean;
+    related_risk_ids?: string[];
+}
+export interface ProgressConfirmationResponse {
+    question_id: string;
+    response: "yes" | "no" | "skip";
+}
+export interface ProgressEnvironmentResult {
+    passed: boolean;
+    checks: {
+        name: string;
+        passed: boolean;
+        message: string;
+    }[];
+}
+export interface ProgressDecisionRecord {
+    timestamp: string;
+    gate_version: string;
+    final_status: ProgressConfirmGateStatus;
+    layers_passed: string[];
+    layers_failed: string[];
+}
+export interface ProgressJsonForConfirm {
+    object?: string | null;
+    task?: string;
+    repository?: {
+        op: "add" | "set";
+        objects: string[];
+    } | {
+        op: "remove";
+        objects: string[];
+    } | {
+        op: "clear";
+    };
+    progress_namedOperator?: {
+        op: "add" | "set" | "remove";
+        name: string;
+        operators: string[];
+    };
+    operate?: {
+        operation: {
+            next_node_name: string;
+            forward: string;
+        };
+        op?: "next" | "hold" | "unhold" | "adminUnhold";
+        message?: string;
+    };
+}
+export interface ProgressConfirmGateInput {
+    progress_json: ProgressJsonForConfirm;
+    intent?: string;
+    target_objects_types?: string[];
+    current_machine?: string;
+    machine_published?: boolean;
+    current_task?: string | null;
+    current_named_operator_count?: number;
+    current_context_repository_count?: number;
+    current_node?: string;
+    forward_already_accomplished?: boolean;
+    holder_address?: string | null;
+    signer?: string;
+    forward_named_operator?: string;
+    forward_permission_index?: number | null;
+    forward_has_guard?: boolean;
+    skip_user_confirmation?: boolean;
+    skip_environment_check?: boolean;
+}
+export declare const PROGRESS_OPERATION_CHECKLIST: ProgressChecklistItem[];
+export declare const PROGRESS_CONFIRMATION_QUESTIONS: ProgressConfirmationQuestion[];
+export declare const PROGRESS_CONFIRM_VERSION = "1.0.0";
+export declare function runProgressConfirmGate(input: ProgressConfirmGateInput): ProgressConfirmGateResult;
+export interface ProgressiveProgressCheckResult {
+    stage: "checklist" | "risk" | "confirmation" | "environment" | "complete";
+    status: "pass" | "fail" | "pending";
+    message: string;
+    next_action?: string;
+}
+export declare function progressiveProgressCheck(input: ProgressConfirmGateInput): ProgressiveProgressCheckResult;