@wowok/agent-mcp 2.4.3 → 2.5.0

package/dist/knowledge/permission-confirm.js

@@ -0,0 +1,426 @@
+import { USER_DEFINED_PERM_INDEX_START, MAX_ENTITY_COUNT, MAX_PERM_FOR_ENTITY, MAX_ADMIN_COUNT, } from "@wowok/wowok";
+import { isBuiltinPermission, findSceneByPermissionIndex, } from "./permission-ledger.js";
+import { assessPermissionRisks, } from "./permission-risk.js";
+export const PERMISSION_PUBLISH_CHECKLIST = [
+    { id: "C-P-01", description: "Custom permissionIndex >= 1000 (USER_DEFINED_PERM_INDEX_START)", passed: false, message: "" },
+    { id: "C-P-02", description: "Entity count <= MAX_ENTITY_COUNT (1000)", passed: false, message: "" },
+    { id: "C-P-03", description: "Per-entity permission count <= MAX_PERM_FOR_ENTITY (1000)", passed: false, message: "" },
+    { id: "C-P-04", description: "Admin count <= MAX_ADMIN_COUNT (500)", passed: false, message: "" },
+    { id: "C-P-05", description: "Owner address valid (if transfer)", passed: false, message: "" },
+    { id: "C-P-06", description: "Admin addresses valid", passed: false, message: "" },
+    { id: "C-P-07", description: "Entity addresses valid", passed: false, message: "" },
+    { id: "C-P-08", description: "UM address valid (Contact object) or null", passed: false, message: "" },
+    { id: "C-P-09", description: "apply object types match permission indexes", passed: false, message: "" },
+    { id: "C-P-10", description: "All custom permissions (>= 1000) have remark", passed: false, message: "" },
+    { id: "C-P-11", description: "Ownership transfer double-confirmed", passed: false, message: "" },
+];
+function runStaticChecklist(input) {
+    const items = PERMISSION_PUBLISH_CHECKLIST.map(c => ({ ...c }));
+    const data = input.permission_json;
+    if (data.table && "index" in data.table && typeof data.table.index === "number") {
+        const idx = data.table.index;
+        const valid = idx < USER_DEFINED_PERM_INDEX_START ? isBuiltinPermission(idx) : true;
+        const item = items.find(i => i.id === "C-P-01");
+        item.passed = valid;
+        item.message = valid ? "" : `Permission index ${idx} is < ${USER_DEFINED_PERM_INDEX_START} and not builtin`;
+    }
+    else {
+        items.find(i => i.id === "C-P-01").passed = true;
+    }
+    const entityCount = input.current_entity_count ?? 0;
+    const cp02 = items.find(i => i.id === "C-P-02");
+    cp02.passed = entityCount <= MAX_ENTITY_COUNT;
+    cp02.message = cp02.passed ? "" : `Entity count ${entityCount} > ${MAX_ENTITY_COUNT}`;
+    if (data.table && "index" in data.table && Array.isArray(data.table.index)) {
+        const valid = data.table.index.length <= MAX_PERM_FOR_ENTITY;
+        const cp03 = items.find(i => i.id === "C-P-03");
+        cp03.passed = valid;
+        cp03.message = valid ? "" : `Per-entity perm count ${data.table.index.length} > ${MAX_PERM_FOR_ENTITY}`;
+    }
+    else {
+        items.find(i => i.id === "C-P-03").passed = true;
+    }
+    if (data.admin) {
+        const count = data.admin.op === "set" ? data.admin.addresses.length : (input.current_admin_count ?? 0);
+        const valid = count <= MAX_ADMIN_COUNT;
+        const cp04 = items.find(i => i.id === "C-P-04");
+        cp04.passed = valid;
+        cp04.message = valid ? "" : `Admin count ${count} > ${MAX_ADMIN_COUNT}`;
+    }
+    else {
+        items.find(i => i.id === "C-P-04").passed = true;
+    }
+    if (data.builder) {
+        const valid = data.builder.startsWith("0x") && data.builder.length >= 40;
+        const cp05 = items.find(i => i.id === "C-P-05");
+        cp05.passed = valid;
+        cp05.message = valid ? "" : `New owner address ${data.builder} invalid`;
+    }
+    else {
+        items.find(i => i.id === "C-P-05").passed = true;
+    }
+    if (data.admin) {
+        const valid = data.admin.addresses.every(a => a.startsWith("0x") && a.length >= 40);
+        const cp06 = items.find(i => i.id === "C-P-06");
+        cp06.passed = valid;
+        cp06.message = valid ? "" : `Some admin address invalid`;
+    }
+    else {
+        items.find(i => i.id === "C-P-06").passed = true;
+    }
+    if (data.table) {
+        const entities = "entity" in data.table
+            ? (Array.isArray(data.table.entity) ? data.table.entity : [data.table.entity])
+            : [];
+        const valid = entities.every(a => a.startsWith("0x") && a.length >= 40);
+        const cp07 = items.find(i => i.id === "C-P-07");
+        cp07.passed = valid;
+        cp07.message = valid ? "" : `Some entity address invalid`;
+    }
+    else {
+        items.find(i => i.id === "C-P-07").passed = true;
+    }
+    if (data.um !== undefined) {
+        const valid = data.um === null || (data.um.startsWith("0x") && data.um.length >= 40);
+        const cp08 = items.find(i => i.id === "C-P-08");
+        cp08.passed = valid;
+        cp08.message = valid ? "" : `UM address ${data.um} invalid`;
+    }
+    else {
+        items.find(i => i.id === "C-P-08").passed = true;
+    }
+    if (data.apply && data.apply.length > 0 && data.table && "index" in data.table && typeof data.table.index === "number") {
+        const scene = findSceneByPermissionIndex(data.table.index);
+        if (scene && input.target_objects_types) {
+            const mismatched = input.target_objects_types.filter(t => t !== scene.host_object);
+            const cp09 = items.find(i => i.id === "C-P-09");
+            cp09.passed = mismatched.length === 0;
+            cp09.message = mismatched.length === 0 ? "" : `Index ${data.table.index} expects ${scene.host_object}, got ${mismatched.join(",")}`;
+        }
+        else {
+            items.find(i => i.id === "C-P-09").passed = true;
+        }
+    }
+    else {
+        items.find(i => i.id === "C-P-09").passed = true;
+    }
+    if (data.table && "index" in data.table && typeof data.table.index === "number" && data.table.index >= USER_DEFINED_PERM_INDEX_START) {
+        const hasRemark = data.remark && "remark" in data.remark && data.remark.index === data.table.index;
+        const cp10 = items.find(i => i.id === "C-P-10");
+        cp10.passed = !!hasRemark;
+        cp10.message = hasRemark ? "" : `Custom permission ${data.table.index} has no remark`;
+    }
+    else {
+        items.find(i => i.id === "C-P-10").passed = true;
+    }
+    if (data.builder) {
+        items.find(i => i.id === "C-P-11").passed = false;
+        items.find(i => i.id === "C-P-11").message = "Pending user confirmation in Layer 3";
+    }
+    else {
+        items.find(i => i.id === "C-P-11").passed = true;
+    }
+    return {
+        all_passed: items.filter(i => i.id !== "C-P-11").every(i => i.passed),
+        items,
+    };
+}
+function adaptRiskAssessment(input, checklist) {
+    const ctx = {
+        object: input.permission_json.object,
+        description: input.permission_json.description,
+        admin: input.permission_json.admin,
+        table: input.permission_json.table,
+        entity: input.permission_json.entity,
+        remark: input.permission_json.remark,
+        apply: input.permission_json.apply,
+        builder: input.permission_json.builder,
+        um: input.permission_json.um,
+        current_admin_count: input.current_admin_count,
+        current_entity_count: input.current_entity_count,
+        target_objects_types: input.target_objects_types,
+    };
+    return assessPermissionRisks(ctx);
+}
+export const PERMISSION_CONFIRMATION_QUESTIONS = [
+    {
+        id: "QP1",
+        question: "Are all admin addresses correctly verified as trusted parties?",
+        requires_explicit_yes: true,
+    },
+    {
+        id: "QP2",
+        question: "Are all entity addresses (users/Guards) correctly assigned to their intended permission indexes?",
+        requires_explicit_yes: true,
+    },
+    {
+        id: "QP3",
+        question: "If using custom permission indexes (>= 1000), are all remarks documented?",
+        requires_explicit_yes: true,
+    },
+    {
+        id: "QP4",
+        question: "If applying to target objects, have you verified the target object types match the permission indexes used?",
+        requires_explicit_yes: true,
+    },
+    {
+        id: "QP5",
+        question: "⚠️ If transferring ownership: do you confirm the new owner address is correct? This operation is IRREVERSIBLE.",
+        requires_explicit_yes: true,
+        related_risk_ids: ["R-P-4-01"],
+    },
+    {
+        id: "QP6",
+        question: "Have you exported the current Permission JSON as a backup before this operation?",
+        requires_explicit_yes: false,
+    },
+];
+function processUserConfirmation(input, assessment) {
+    const questions = [...PERMISSION_CONFIRMATION_QUESTIONS];
+    if (!input.permission_json.builder) {
+        const idx = questions.findIndex(q => q.id === "QP5");
+        if (idx >= 0)
+            questions.splice(idx, 1);
+    }
+    if (input.skip_user_confirmation) {
+        return {
+            questions_asked: questions,
+            responses: questions.map(q => ({ question_id: q.id, response: "yes" })),
+            all_confirmed: true,
+        };
+    }
+    return {
+        questions_asked: questions,
+        responses: [],
+        all_confirmed: false,
+    };
+}
+function verifyEnvironment(input) {
+    const checks = [];
+    if (input.permission_json.object) {
+        checks.push({
+            name: "object_exists",
+            passed: true,
+            message: `Permission object ${input.permission_json.object} assumed to exist`,
+        });
+    }
+    if (input.permission_json.builder || input.permission_json.um !== undefined) {
+        checks.push({
+            name: "signer_is_owner",
+            passed: true,
+            message: "Signer must be owner for transfer/um_set operations",
+        });
+    }
+    else if (input.permission_json.admin || input.permission_json.table || input.permission_json.remark) {
+        checks.push({
+            name: "signer_is_admin",
+            passed: true,
+            message: "Signer must be admin for table/remark/admin operations",
+        });
+    }
+    if (input.permission_json.apply && input.permission_json.apply.length > 0) {
+        checks.push({
+            name: "apply_targets_exist_and_owned",
+            passed: true,
+            message: `Signer must be owner of ${input.permission_json.apply.length} target object(s)`,
+        });
+    }
+    const allPassed = checks.every(c => c.passed);
+    return { passed: allPassed, checks };
+}
+export const PERMISSION_CONFIRM_VERSION = "1.0.0";
+export function runPermissionConfirmGate(input) {
+    const layersPassed = [];
+    const layersFailed = [];
+    const checklist = runStaticChecklist(input);
+    if (!checklist.all_passed) {
+        layersFailed.push("L1_checklist");
+        return {
+            status: "blocked_checklist",
+            checklist_result: checklist,
+            confirmation_text: generateConfirmationText(input, checklist),
+            block_reason: `Checklist failed: ${checklist.items.filter(i => !i.passed).map(i => i.id).join(", ")}`,
+            decision_record: {
+                timestamp: new Date().toISOString(),
+                gate_version: PERMISSION_CONFIRM_VERSION,
+                final_status: "blocked_checklist",
+                layers_passed: layersPassed,
+                layers_failed: layersFailed,
+            },
+        };
+    }
+    layersPassed.push("L1_checklist");
+    const assessment = adaptRiskAssessment(input, checklist);
+    const hasCritical = assessment.risks.some(r => r.level === "CRITICAL");
+    if (hasCritical) {
+        layersFailed.push("L2_risk");
+        return {
+            status: "blocked_risk",
+            checklist_result: checklist,
+            risk_result: assessment,
+            confirmation_text: generateConfirmationText(input, checklist, assessment),
+            block_reason: `CRITICAL risks: ${assessment.risks.filter(r => r.level === "CRITICAL").map(r => r.id).join(", ")}`,
+            decision_record: {
+                timestamp: new Date().toISOString(),
+                gate_version: PERMISSION_CONFIRM_VERSION,
+                final_status: "blocked_risk",
+                layers_passed: layersPassed,
+                layers_failed: layersFailed,
+            },
+        };
+    }
+    layersPassed.push("L2_risk");
+    const userConf = processUserConfirmation(input, assessment);
+    if (!userConf.all_confirmed) {
+        if (input.permission_json.builder) {
+            const cp11 = checklist.items.find(i => i.id === "C-P-11");
+            if (cp11) {
+                const qp5 = userConf.responses.find(r => r.question_id === "QP5");
+                cp11.passed = qp5?.response === "yes";
+                cp11.message = cp11.passed ? "" : "Transfer not confirmed by user";
+            }
+        }
+        if (!checklist.all_passed && input.permission_json.builder) {
+            const cp11 = checklist.items.find(i => i.id === "C-P-11");
+            if (cp11 && !cp11.passed) {
+                layersFailed.push("L3_user");
+                return {
+                    status: "blocked_user",
+                    checklist_result: checklist,
+                    risk_result: assessment,
+                    user_confirmation: userConf,
+                    confirmation_text: generateConfirmationText(input, checklist, assessment),
+                    block_reason: "User did not confirm ownership transfer",
+                    decision_record: {
+                        timestamp: new Date().toISOString(),
+                        gate_version: PERMISSION_CONFIRM_VERSION,
+                        final_status: "blocked_user",
+                        layers_passed: layersPassed,
+                        layers_failed: layersFailed,
+                    },
+                };
+            }
+        }
+    }
+    layersPassed.push("L3_user");
+    if (input.skip_environment_check) {
+        layersPassed.push("L4_environment");
+    }
+    else {
+        const env = verifyEnvironment(input);
+        if (!env.passed) {
+            layersFailed.push("L4_environment");
+            return {
+                status: "blocked_environment",
+                checklist_result: checklist,
+                risk_result: assessment,
+                user_confirmation: userConf,
+                environment_result: env,
+                confirmation_text: generateConfirmationText(input, checklist, assessment),
+                block_reason: `Environment check failed: ${env.checks.filter(c => !c.passed).map(c => c.name).join(", ")}`,
+                decision_record: {
+                    timestamp: new Date().toISOString(),
+                    gate_version: PERMISSION_CONFIRM_VERSION,
+                    final_status: "blocked_environment",
+                    layers_passed: layersPassed,
+                    layers_failed: layersFailed,
+                },
+            };
+        }
+        layersPassed.push("L4_environment");
+    }
+    return {
+        status: "approved",
+        checklist_result: checklist,
+        risk_result: assessment,
+        user_confirmation: userConf,
+        confirmation_text: generateConfirmationText(input, checklist, assessment),
+        decision_record: {
+            timestamp: new Date().toISOString(),
+            gate_version: PERMISSION_CONFIRM_VERSION,
+            final_status: "approved",
+            layers_passed: layersPassed,
+            layers_failed: layersFailed,
+        },
+    };
+}
+function generateConfirmationText(input, checklist, assessment) {
+    const lines = [];
+    const data = input.permission_json;
+    lines.push("═══ Permission Confirmation ═══");
+    lines.push("");
+    if (data.object) {
+        lines.push(`Permission: ${data.object}`);
+    }
+    else {
+        lines.push("Permission: NEW (to be created)");
+    }
+    if (data.description)
+        lines.push(`Description: ${data.description}`);
+    lines.push("");
+    lines.push("─ Checklist ──────────────────");
+    for (const item of checklist.items) {
+        const mark = item.passed ? "✓" : "✗";
+        lines.push(`  ${mark} ${item.id}: ${item.description}${item.message ? " — " + item.message : ""}`);
+    }
+    lines.push("");
+    if (assessment) {
+        lines.push("─ Risk Assessment ──────────────────");
+        lines.push(`Overall: ${assessment.overall_risk}`);
+        lines.push(`Detected: ${assessment.risks.length} risk(s)`);
+        for (const r of assessment.risks) {
+            lines.push(`  [${r.level}] ${r.id}: ${r.title}`);
+        }
+        lines.push("");
+    }
+    lines.push("─ Operations ──────────────────");
+    if (data.admin)
+        lines.push(`- Admin ${data.admin.op}: ${data.admin.addresses.length} address(es)`);
+    if (data.table)
+        lines.push(`- Table op: ${data.table.op}`);
+    if (data.entity)
+        lines.push(`- Entity op: ${data.entity.op}`);
+    if (data.remark)
+        lines.push(`- Remark op: ${data.remark.op}`);
+    if (data.apply)
+        lines.push(`- Apply to: ${data.apply.length} object(s)`);
+    if (data.builder)
+        lines.push(`- ⚠️ TRANSFER to: ${data.builder}`);
+    if (data.um !== undefined)
+        lines.push(`- UM: ${data.um ?? "(revoke)"}`);
+    lines.push("");
+    return lines.join("\n");
+}
+export function progressivePermissionCheck(input) {
+    const checklist = runStaticChecklist(input);
+    if (!checklist.all_passed) {
+        return {
+            stage: "checklist",
+            status: "fail",
+            message: `Checklist failed: ${checklist.items.filter(i => !i.passed).map(i => i.id).join(", ")}`,
+            next_action: "Fix failing checklist items",
+        };
+    }
+    const assessment = adaptRiskAssessment(input, checklist);
+    if (assessment.risks.some(r => r.level === "CRITICAL")) {
+        return {
+            stage: "risk",
+            status: "fail",
+            message: `CRITICAL risks: ${assessment.risks.filter(r => r.level === "CRITICAL").map(r => r.id).join(", ")}`,
+            next_action: "Resolve CRITICAL risks before proceeding",
+        };
+    }
+    if (assessment.needs_human_review) {
+        return {
+            stage: "confirmation",
+            status: "pending",
+            message: "Human review required for HIGH risks",
+            next_action: "Confirm risk acceptance",
+        };
+    }
+    return {
+        stage: "complete",
+        status: "pass",
+        message: "All checks passed",
+    };
+}

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

@@ -0,0 +1,58 @@
+import { type PermissionScene, type BuiltinPermissionEntry } from "./permission-ledger.js";
+import { type PermissionTemplate } from "./permission-templates.js";
+import { type SemanticToSchemaRule } from "./permission-translation.js";
+import { type RiskRule, type PermissionRiskAssessment, type PermissionStakeholder } from "./permission-risk.js";
+import { type PermissionPuzzle, type PuzzleCompleteness } from "./permission-puzzle.js";
+import { PERMISSION_PUBLISH_CHECKLIST, PERMISSION_CONFIRMATION_QUESTIONS, type PermissionJsonForConfirm } from "./permission-confirm.js";
+export declare const PERMISSION_CONTEXT_VERSION = "1.0.0";
+export type PermissionInjectionMode = "initial_design" | "mid_design_review" | "pre_publish" | "post_publish_modify" | "stakeholder_review" | "apply_check";
+export type PermissionStakeholderPerspective = PermissionStakeholder | "system";
+export interface PermissionContextBundle {
+    version: string;
+    mode: PermissionInjectionMode;
+    stakeholder_perspective?: PermissionStakeholderPerspective;
+    matched_scene?: PermissionScene;
+    matched_template?: PermissionTemplate;
+    matched_pattern?: SemanticToSchemaRule;
+    puzzle_state?: PermissionPuzzle;
+    puzzle_completeness?: PuzzleCompleteness;
+    relevant_risks: RiskRule[];
+    risk_assessment?: PermissionRiskAssessment;
+    relevant_checklist: typeof PERMISSION_PUBLISH_CHECKLIST;
+    relevant_questions: typeof PERMISSION_CONFIRMATION_QUESTIONS;
+    relevant_builtin_permissions: BuiltinPermissionEntry[];
+    cross_object_refs: PermissionCrossObjectRef[];
+    onchain_constraints: PermissionOnchainConstraint[];
+    rendering_hints: PermissionRenderingHints;
+}
+export interface PermissionCrossObjectRef {
+    object: "Service" | "Machine" | "Treasury" | "Arbitration" | "Repository" | "Reward" | "Progress" | "Demand" | "Contact" | "Allocation";
+    field: string;
+    scene_id: string;
+    description: string;
+}
+export interface PermissionOnchainConstraint {
+    name: string;
+    value: string | number;
+    description: string;
+}
+export interface PermissionRenderingHints {
+    include_puzzle_template: boolean;
+    include_risk_details: boolean;
+    include_questions: boolean;
+    include_immutability_warning: boolean;
+    include_transfer_warning: boolean;
+    max_length: number;
+}
+export interface BuildPermissionContextInput {
+    mode: PermissionInjectionMode;
+    intent?: string;
+    permission_json?: PermissionJsonForConfirm;
+    stakeholder?: PermissionStakeholderPerspective;
+    target_host_object?: PermissionScene["host_object"];
+    target_permission_index?: number;
+    max_length?: number;
+}
+export declare function buildPermissionContext(input: BuildPermissionContextInput): PermissionContextBundle;
+export declare function buildPromptFromPermissionContext(bundle: PermissionContextBundle): string;
+export declare function getPermissionContextSummary(bundle: PermissionContextBundle): string;