@zivis/mcp 0.1.8 → 0.1.10

package/dist/tools/get-started.js

@@ -0,0 +1,470 @@
+import * as fs from "node:fs/promises";
+import { z } from "zod";
+import { detectProjectBinding } from "../project-binding.js";
+import { loadActivePack, findRelevantCapsules, } from "../pattern-pack/index.js";
+import { locateLatestArtifact } from "../lib/inspect-cache.js";
+export const GET_STARTED_NAME = "zivis_get_started";
+export const GET_STARTED_DESCRIPTION = `Call this FIRST on any turn where the user asks about security, vulnerabilities, code review, deployment readiness, threat modeling, dependencies, or "what should I do next." Idempotent and safe to call repeatedly — detects prior inspect runs and never re-inspects unnecessarily. Prefer this over calling zivis_inspect directly.
+
+Use this when the user says any of:
+- "what should I do for security on this app"
+- "uhh, where do I start"
+- "is my app safe" / "is my chatbot safe"
+- "I need to do security stuff before launch"
+- "I have an audit / pen test / customer asking about security"
+- "check my dependencies / libraries / repos"
+- "how do I use ZIVIS"
+- "what can ZIVIS do for me"
+
+This tool inspects the current project state — binding, application, scans, findings —
+AND if a recent 'zivis inspect' artifact exists for this repo, evaluates the local
+threat library against it to surface architectural patterns ZIVIS thinks may apply
+(self-consistency without context isolation, late org filter, privilege separation, etc.).
+The 'relevant_threats' field in the response is what makes this tool different from a
+generic security menu: ZIVIS is reading the user's actual codebase via the graph
+artifact and naming threats by their architectural shape.
+
+Always speak to the user in threat-model language: components, flows, trust boundaries,
+attack scenarios. Even when they don't yet know those terms — that's how they learn.
+
+Output is a structured JSON object. Present recommended_next_steps as a numbered list
+to the user, in order, and ask them to pick one. If relevant_threats is non-empty, lead
+with that — it's the most concrete thing ZIVIS knows about their repo. Use the label
+and why fields verbatim; do not invent new steps. If the user is unsure which to pick,
+recommend the item flagged in if_user_unsure.`;
+export const GET_STARTED_SCHEMA = {
+    concern: z
+        .string()
+        .optional()
+        .describe("Free-form sentence describing what the user wants. " +
+        "Examples: 'is my chatbot safe', 'check the libraries we use', " +
+        "'audit coming up next month', 'just deployed a new API'. " +
+        "If omitted, returns a generic getting-started menu based on project state."),
+    cwd: z
+        .string()
+        .optional()
+        .describe("Working directory to inspect (defaults to server working directory)."),
+};
+const INTENT_MAP = [
+    {
+        patterns: /chatbot|llm|ai chat|assistant|agent|prompt injection|jailbreak|openai|anthropic|langchain|llamaindex|cohere|together/i,
+        intent: "ai_red_team",
+    },
+    {
+        patterns: /librar|dependenc|package|npm|pip|repo|crate|gem|module|import|third.?party/i,
+        intent: "dep_audit",
+    },
+    {
+        patterns: /audit|compliance|soc\s*2|iso\s*27001|fedramp|vendor questionnaire|customer ask|certif/i,
+        intent: "pre_audit",
+    },
+    {
+        patterns: /launch|deploy|release|production|go\s*live|prod|ship/i,
+        intent: "pre_launch",
+    },
+    {
+        patterns: /finding|issue|vulnerabilit|vuln|bug|report|result|scan result/i,
+        intent: "view_findings",
+    },
+];
+function detectIntent(concern) {
+    if (!concern)
+        return "generic";
+    for (const { patterns, intent } of INTENT_MAP) {
+        if (patterns.test(concern))
+            return intent;
+    }
+    return "generic";
+}
+function stepCheckDeps() {
+    return {
+        id: "check_dependencies",
+        label: "Check the open source libraries you depend on",
+        tool: "zivis_check_repo_trust",
+        why: "Free, no setup. Catches risky AI SDKs and known-bad dependencies before they cause problems.",
+        estimated_time: "1 minute per repo",
+        requires_auth: false,
+    };
+}
+function stepSetupAiTarget(hint) {
+    return {
+        id: "setup_ai_target",
+        label: "Tell ZIVIS about your chatbot or AI system so it can test it",
+        tool: "zivis_setup_red_team_target",
+        args_hint: { target_type: "ai_chat", ...hint },
+        why: "ZIVIS needs to know your endpoint to run prompt-injection, jailbreak, and PII-leakage tests.",
+        estimated_time: "2 minutes",
+        requires_auth: true,
+    };
+}
+function stepSetupWebTarget(hint) {
+    return {
+        id: "setup_web_target",
+        label: "Register your web app or API with ZIVIS for testing",
+        tool: "zivis_setup_red_team_target",
+        args_hint: { target_type: "web_app", ...hint },
+        why: "ZIVIS needs to know your app URL to run security tests against it.",
+        estimated_time: "2 minutes",
+        requires_auth: true,
+    };
+}
+function stepBrowseTests() {
+    return {
+        id: "browse_test_library",
+        label: "Browse what ZIVIS can test for",
+        tool: "zivis_list_test_scenarios",
+        why: "See the menu of attack categories (prompt injection, auth bypass, data leakage, etc.) before committing to a scan.",
+        estimated_time: "30 seconds",
+        requires_auth: true,
+    };
+}
+function stepViewFindings(count) {
+    return {
+        id: "view_open_findings",
+        label: count
+            ? `Review the ${count} open security issue${count === 1 ? "" : "s"} ZIVIS found`
+            : "Review open security issues ZIVIS found",
+        tool: "zivis_get_findings",
+        args_hint: { status: "open" },
+        why: "Look at what's been found already before starting new scans — no point duplicating work.",
+        estimated_time: "5 minutes",
+        requires_auth: true,
+    };
+}
+function stepRunSecurityReview() {
+    return {
+        id: "run_security_review",
+        label: "Get a security readiness summary before launch or audit",
+        tool: "zivis_security_review",
+        why: "Pulls together all open findings, past fixes, and known attack scenarios into one pre-launch checklist.",
+        estimated_time: "3 minutes",
+        requires_auth: true,
+    };
+}
+function stepSetupProject() {
+    return {
+        id: "setup_project",
+        label: "Connect this project to your ZIVIS org",
+        tool: "zivis_check_project",
+        why: "ZIVIS needs to know which org this project belongs to before it can run tests or store results.",
+        estimated_time: "2 minutes (run 'zivis auth init' in your terminal)",
+        requires_auth: false,
+    };
+}
+function stepInstallGitHubApp(installUrl) {
+    return {
+        id: "install_github_app",
+        label: "Install the ZIVIS GitHub App to enable continuous monitoring",
+        tool: "external_link",
+        args_hint: { url: installUrl },
+        why: "Linking a repo unlocks deeper analysis on every push — threat model updates automatically as architecture changes. Today this org has no GitHub App installation.",
+        estimated_time: "2 minutes",
+        requires_auth: false,
+    };
+}
+async function fetchState(apiClient, cwd) {
+    const detected = detectProjectBinding(cwd);
+    if (!detected) {
+        return {
+            bound: false,
+            has_application: false,
+            has_scans: false,
+            has_findings: false,
+            open_findings_count: 0,
+        };
+    }
+    const state = {
+        bound: true,
+        org_name: detected.binding.orgName,
+        has_application: false,
+        has_scans: false,
+        has_findings: false,
+        open_findings_count: 0,
+    };
+    try {
+        const appsResp = await apiClient.get("/api/rt/applications?limit=1");
+        if ((appsResp.applications?.length ?? 0) > 0 || (appsResp.total ?? 0) > 0) {
+            state.has_application = true;
+        }
+    }
+    catch {
+    }
+    try {
+        const scansResp = await apiClient.get("/api/rt/scans?limit=1");
+        if ((scansResp.scans?.length ?? 0) > 0) {
+            state.has_scans = true;
+        }
+    }
+    catch {
+    }
+    try {
+        const findingsResp = await apiClient.get("/api/findings/unified?status=open&limit=1");
+        const total = findingsResp.summary?.total ?? findingsResp.findings?.length ?? 0;
+        if (total > 0) {
+            state.has_findings = true;
+            state.open_findings_count = total;
+        }
+    }
+    catch {
+    }
+    try {
+        const gh = await apiClient.get("/api/github-app/status");
+        state.github_app_installed = gh.installed;
+        state.github_app_install_url = gh.installUrl;
+    }
+    catch {
+        state.github_app_installed = null;
+    }
+    return state;
+}
+function buildMenu(intent, state, concern) {
+    if (!state.bound) {
+        return {
+            headline: "Welcome to ZIVIS! First, let's connect this project to your organization so results are stored and tracked.",
+            recommended_next_steps: [
+                stepSetupProject(),
+                stepCheckDeps(),
+                stepBrowseTests(),
+            ],
+            guidance_for_assistant: "Present these as a numbered list. The user should run 'zivis auth init' in their terminal to complete step 1. " +
+                "Step 2 (check_dependencies) requires no auth and can be done immediately. " +
+                "If they ask 'why' something matters, expand on the 'why' field — do not make new claims.",
+            if_user_unsure: "Recommend option 2 (check_dependencies) — it requires no setup and gives immediate results.",
+        };
+    }
+    if (state.has_findings && intent !== "dep_audit") {
+        const steps = [
+            stepViewFindings(state.open_findings_count),
+            stepCheckDeps(),
+        ];
+        if (!state.has_application) {
+            steps.push(stepSetupWebTarget());
+        }
+        else {
+            steps.push(stepBrowseTests());
+        }
+        return {
+            headline: `ZIVIS sees your project (${state.org_name ?? "connected"}) and has found ${state.open_findings_count} open security issue${state.open_findings_count === 1 ? "" : "s"}.`,
+            recommended_next_steps: steps,
+            guidance_for_assistant: "Present these as a numbered list. Prioritize reviewing existing findings before starting new scans. " +
+                "If they ask 'why' something matters, expand on the 'why' field — do not make new claims.",
+            if_user_unsure: "Recommend option 1 (view_open_findings) — reviewing what's already known is the best first step.",
+        };
+    }
+    if (intent === "ai_red_team") {
+        const steps = [
+            stepSetupAiTarget(),
+            stepCheckDeps(),
+            stepBrowseTests(),
+        ];
+        return {
+            headline: state.has_application
+                ? `ZIVIS sees your project (${state.org_name ?? "connected"}) and has a target configured. Ready to test your AI system.`
+                : `ZIVIS sees your project (${state.org_name ?? "connected"}) but no security testing has run yet.`,
+            recommended_next_steps: steps,
+            guidance_for_assistant: "The user wants to test an AI/chatbot system. Present these as a numbered list. " +
+                "If they already have a target URL, include it in args_hint. " +
+                "If they ask 'why' something matters, expand on the 'why' field — do not make new claims.",
+            if_user_unsure: "Recommend option 1 (setup_ai_target) — setting up the chatbot as a test target is the fastest path to finding real issues.",
+        };
+    }
+    if (intent === "dep_audit") {
+        return {
+            headline: "Checking your dependencies is a great place to start — it's free, needs no setup, and often finds the most impactful issues.",
+            recommended_next_steps: [
+                stepCheckDeps(),
+                stepSetupWebTarget(),
+                stepBrowseTests(),
+            ],
+            guidance_for_assistant: "Present these as a numbered list. For step 1, ask the user to share which packages they want to check " +
+                "(the GitHub org/repo of the dependency, e.g. openai/openai-python). " +
+                "If they ask 'why' something matters, expand on the 'why' field — do not make new claims.",
+            if_user_unsure: "Recommend option 1 (check_dependencies) — it works right now with no setup.",
+        };
+    }
+    if (intent === "pre_audit" || intent === "pre_launch") {
+        const steps = [
+            stepRunSecurityReview(),
+            stepCheckDeps(),
+        ];
+        if (!state.has_application) {
+            steps.push(stepSetupWebTarget());
+        }
+        else {
+            steps.push(stepBrowseTests());
+        }
+        const headline = intent === "pre_audit"
+            ? `ZIVIS can help you prepare for an audit. Let's get a security readiness picture first.`
+            : `ZIVIS can help you check security before you go live.`;
+        return {
+            headline,
+            recommended_next_steps: steps,
+            guidance_for_assistant: "The user has a deadline (audit or launch). Start with a security review to understand the current state, " +
+                "then address the highest-severity issues first. " +
+                "If they ask 'why' something matters, expand on the 'why' field — do not make new claims.",
+            if_user_unsure: "Recommend option 1 (run_security_review) — it gives the fastest complete picture and shows what needs to be fixed before the deadline.",
+        };
+    }
+    if (intent === "view_findings") {
+        return {
+            headline: state.has_findings
+                ? `ZIVIS has ${state.open_findings_count} open finding${state.open_findings_count === 1 ? "" : "s"} for this project.`
+                : `No open findings found yet — ZIVIS may not have run a scan, or all issues are resolved.`,
+            recommended_next_steps: [
+                stepViewFindings(state.open_findings_count > 0 ? state.open_findings_count : undefined),
+                state.has_application ? stepBrowseTests() : stepSetupWebTarget(),
+                stepCheckDeps(),
+            ],
+            guidance_for_assistant: "Present these as a numbered list. If the user wants to see findings, call zivis_get_findings directly. " +
+                "If they ask 'why' something matters, expand on the 'why' field — do not make new claims.",
+            if_user_unsure: "Recommend option 1 (view_open_findings) — let's see what ZIVIS already knows.",
+        };
+    }
+    const steps = [];
+    if (!state.has_application) {
+        steps.push(stepSetupWebTarget());
+    }
+    steps.push(stepCheckDeps());
+    if (state.has_findings) {
+        steps.push(stepViewFindings(state.open_findings_count));
+    }
+    else {
+        steps.push(stepBrowseTests());
+    }
+    if (steps.length < 3)
+        steps.push(stepBrowseTests());
+    return {
+        headline: state.has_application
+            ? `ZIVIS is connected to your project (${state.org_name ?? "org"}). Here are the most useful things to do next.`
+            : `ZIVIS is connected to your project (${state.org_name ?? "org"}) but no app has been registered for testing yet.`,
+        recommended_next_steps: steps.slice(0, 4),
+        guidance_for_assistant: "Present these as a numbered list. Ask the user to pick one before taking any action. " +
+            "If they ask 'why' something matters, expand on the 'why' field — do not make new claims.",
+        if_user_unsure: "Recommend option 2 (check_dependencies) — it's free, fast, and shows value without setup.",
+    };
+}
+async function findRelevantThreats(cwd) {
+    const located = await locateLatestArtifact(cwd);
+    if (!located) {
+        return {
+            threats: [],
+            reason: "No 'zivis inspect' artifact found in user cache. Run 'zivis inspect' from the repo to populate the threat library against this codebase.",
+        };
+    }
+    const artifactPath = located.path;
+    let artifact;
+    try {
+        const raw = await fs.readFile(artifactPath, "utf8");
+        artifact = JSON.parse(raw);
+    }
+    catch {
+        return { threats: [], reason: `Failed to read artifact at ${artifactPath}.` };
+    }
+    let handle;
+    try {
+        handle = await loadActivePack();
+    }
+    catch {
+        return {
+            threats: [],
+            artifact_path: artifactPath,
+            reason: "Pattern pack not available — run 'pnpm build' to bundle the public pack.",
+        };
+    }
+    const relevant = await findRelevantCapsules(handle, artifact);
+    return {
+        threats: relevant.map((cap) => summarizeCapsule(cap, artifact)),
+        artifact_path: artifactPath,
+    };
+}
+function summarizeCapsule(cap, artifact) {
+    const matched = [];
+    const pkgs = new Set();
+    for (const node of artifact.nodes) {
+        if (node.type === "external_dependency" && node.attributes?.package) {
+            pkgs.add(node.attributes.package);
+        }
+    }
+    const langs = new Set(artifact.scope.languages ?? []);
+    const f = cap.relevance_filter;
+    if (f) {
+        for (const term of [...(f.any_of ?? []), ...(f.all_of ?? [])]) {
+            if (term.dependency && pkgs.has(term.dependency))
+                matched.push(`dep:${term.dependency}`);
+            if (term.language && langs.has(term.language))
+                matched.push(`language:${term.language}`);
+        }
+    }
+    if (matched.length === 0)
+        matched.push("language match only");
+    return {
+        pattern_id: cap.id,
+        title: cap.title,
+        category: cap.category,
+        safe_summary: cap.safe_summary,
+        matched_on: matched,
+        next_action_tool: "zivis_threat_run_matcher",
+    };
+}
+export function createGetStartedHandler(apiClient, _config) {
+    return async (params) => {
+        const cwd = params.cwd ?? process.cwd();
+        const intent = detectIntent(params.concern);
+        const state = await fetchState(apiClient, cwd);
+        const menu = buildMenu(intent, state, params.concern);
+        let threatHit = { threats: [] };
+        try {
+            threatHit = await findRelevantThreats(cwd);
+        }
+        catch (err) {
+            threatHit = {
+                threats: [],
+                reason: `threat-library lookup failed: ${err.message}`,
+            };
+        }
+        if (threatHit.threats.length > 0) {
+            menu.recommended_next_steps = [
+                {
+                    id: "review_relevant_threats",
+                    label: `Review the ${threatHit.threats.length} architectural pattern${threatHit.threats.length === 1 ? "" : "s"} ZIVIS sees in this repo`,
+                    tool: "zivis_threat_run_matcher",
+                    why: "ZIVIS read your codebase via the inspect artifact and identified threat-model patterns that match your architecture. Run the matcher to see exactly which lines fire each pattern.",
+                    estimated_time: "30 seconds",
+                    requires_auth: false,
+                },
+                ...menu.recommended_next_steps,
+            ];
+            menu.headline =
+                `ZIVIS read this repo's threat library and sees ${threatHit.threats.length} architectural pattern${threatHit.threats.length === 1 ? "" : "s"} that may apply. ` +
+                    menu.headline;
+            menu.if_user_unsure = `Recommend option 1 (review_relevant_threats) — that's the most repo-specific thing ZIVIS knows.`;
+        }
+        if (state.bound &&
+            state.github_app_installed === false &&
+            state.github_app_install_url) {
+            menu.recommended_next_steps = [
+                ...menu.recommended_next_steps,
+                stepInstallGitHubApp(state.github_app_install_url),
+            ];
+        }
+        const payload = {
+            current_state: state,
+            intent_detected: intent,
+            concern_received: params.concern ?? null,
+            ...menu,
+            relevant_threats: threatHit.threats,
+            threat_library: {
+                artifact_used: threatHit.artifact_path ?? null,
+                reason_no_threats: threatHit.threats.length === 0 ? threatHit.reason ?? null : null,
+            },
+        };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(payload, null, 2),
+                },
+            ],
+        };
+    };
+}

package/dist/tools/get-trust-keys.d.ts

@@ -1,8 +1,3 @@
-/**
- * zivis_get_trust_keys — Retrieve JWKS public keys for signature verification
- *
- * Maps to: GET /.well-known/jwks.json (public, no auth required)
- */
 import type { ZivisConfig } from "../types.js";
 export declare const GET_TRUST_KEYS_NAME = "zivis_get_trust_keys";
 export declare const GET_TRUST_KEYS_DESCRIPTION = "Retrieve the ZIVIS public signing keys (JWKS) for independent cryptographic verification of trust marks and ZATs.\n\nReturns a JWKS (JSON Web Key Set) containing two keys:\n\n1. **ML-DSA-65 key** (post-quantum, FIPS-204):\n   - Algorithm: CRYSTALS-Dilithium Level 3\n   - NIST Security Category 3 (128-bit quantum security)\n   - Used to verify the full digital signature on ZATs and trust marks\n   - Key type: \"PQ-LWE\" (proposed post-quantum JWK key type)\n   - The \"x\" field is the base64url-encoded public key bytes\n\n2. **Ed25519 key** (RFC 8032):\n   - Used to verify compact trust tokens (shorter, URL-safe format)\n   - Standard JWK format (kty: \"OKP\", crv: \"Ed25519\")\n\nThese keys enable third-party, offline verification without trusting ZIVIS infrastructure.\nThis is critical for ATNP (Agent Trust Negotiation Protocol) where agents must independently verify trust marks.\n\nVerification workflow:\n1. Get a ZAT (from zivis_get_oss_zat or zivis_get_org_zat)\n2. Get the public keys (this tool)\n3. Verify the signature using ML-DSA-65 or Ed25519 library of your choice\n4. Check expiration and claims\n\nNo parameters required. No authentication required.";

package/dist/tools/get-trust-keys.js

@@ -1,8 +1,3 @@
-/**
- * zivis_get_trust_keys — Retrieve JWKS public keys for signature verification
- *
- * Maps to: GET /.well-known/jwks.json (public, no auth required)
- */
 export const GET_TRUST_KEYS_NAME = "zivis_get_trust_keys";
 export const GET_TRUST_KEYS_DESCRIPTION = `Retrieve the ZIVIS public signing keys (JWKS) for independent cryptographic verification of trust marks and ZATs.
 
@@ -64,4 +59,3 @@ export function createGetTrustKeysHandler(config) {
         }
     };
 }
-//# sourceMappingURL=get-trust-keys.js.map

package/dist/tools/import-openapi-endpoints.d.ts

@@ -1,8 +1,3 @@
-/**
- * zivis_import_openapi_endpoints — Import endpoints from an OpenAPI/Swagger spec
- *
- * Maps to: POST /api/rt/applications/:id/endpoints/import-openapi
- */
 import { z } from "zod";
 import type { ApiClient } from "../api-client.js";
 export declare const IMPORT_OPENAPI_ENDPOINTS_NAME = "zivis_import_openapi_endpoints";

package/dist/tools/import-openapi-endpoints.js

@@ -1,8 +1,3 @@
-/**
- * zivis_import_openapi_endpoints — Import endpoints from an OpenAPI/Swagger spec
- *
- * Maps to: POST /api/rt/applications/:id/endpoints/import-openapi
- */
 import { z } from "zod";
 import { requireApplicationId } from "../resolve-application-id.js";
 import { sanitizeResponse } from "../sanitize.js";
@@ -90,4 +85,3 @@ export function createImportOpenApiEndpointsHandler(apiClient) {
         }
     };
 }
-//# sourceMappingURL=import-openapi-endpoints.js.map

package/dist/tools/inspect-zat.d.ts

@@ -1,8 +1,3 @@
-/**
- * zivis_inspect_zat — Parse and explain a ZAT token
- *
- * No API call — client-side parsing and human-readable interpretation.
- */
 import { z } from "zod";
 export declare const INSPECT_ZAT_NAME = "zivis_inspect_zat";
 export declare const INSPECT_ZAT_DESCRIPTION = "Parse a ZIVIS Attestation Token (ZAT) JSON and produce a human-readable explanation of all fields.\n\nThis tool does NOT make any API calls \u2014 it parses the ZAT locally and explains what each field means.\n\nUse this after retrieving a ZAT from zivis_get_oss_zat or zivis_get_org_zat to understand:\n- What the claims mean (Z-Score, trust tiers, coverage, findings)\n- Whether signatures are present and which algorithms were used\n- Token validity and expiration\n- Evidence manifest integrity\n- Framework and methodology details\n- Lens-level scores (for OSS ZATs)\n\nAccepts either:\n- A JSON string (the raw ZAT output)\n- A JSON object with a \"zat\" field (the wrapper returned by the API)\n\nZAT Field Reference:\n- **iss**: Issuer (always \"zivis.ai\")\n- **sub**: Subject \u2014 \"org:<slug>\" for enterprise, \"github:<owner>/<repo>\" for OSS\n- **mark_id**: Unique identifier (ztm_...) \u2014 references the trust mark\n- **issued_at / expires_at**: ISO 8601 timestamps \u2014 ZATs are short-lived (48h)\n- **frameworks[]**: Which security frameworks were assessed (NIST IR 8596, ISO 42001, OWASP LLM Top 10, etc.)\n  - basis: \"tested\" | \"mapped\" | \"self-attested\" | \"third-party\" \u2014 how the assessment was performed\n  - csf_version: Present if framework is NIST CSF 2.0 derived (enables cross-framework comparison)\n- **claims**: The actual trust posture\n  - For enterprise: z_score_raw (0-1), z_score_display (0-1000), tier (0-3), tier_label, coverage_pct, mapped_outcomes\n  - For OSS: score (0-100), grade (A+ to F), check_types, findings by severity, commit SHA\n  - Tier meanings: 0=Commitment, 1=Foundational Trust (600+), 2=Operational Trust (700+), 3=Systemic Trust (800+)\n- **evidence_manifest**: SHA-256 hash of the evidence bundle \u2014 proves the assessment data hasn't been tampered with\n- **methodology**: How the assessment was performed (model version, scoring algorithm, evaluator type)\n- **sig**: Cryptographic signatures\n  - alg: \"ML-DSA-65\" (FIPS-204, post-quantum CRYSTALS-Dilithium Level 3)\n  - compact: Ed25519 (RFC 8032) compact token for lightweight verification\n- **ver**: ZAT spec version (e.g., \"0.3.0\")";

package/dist/tools/inspect-zat.js

@@ -1,8 +1,3 @@
-/**
- * zivis_inspect_zat — Parse and explain a ZAT token
- *
- * No API call — client-side parsing and human-readable interpretation.
- */
 import { z } from "zod";
 export const INSPECT_ZAT_NAME = "zivis_inspect_zat";
 export const INSPECT_ZAT_DESCRIPTION = `Parse a ZIVIS Attestation Token (ZAT) JSON and produce a human-readable explanation of all fields.
@@ -62,23 +57,19 @@ export function createInspectZatHandler() {
                     isError: true,
                 };
             }
-            // Unwrap if the API returned { zat: {...}, ... }
             const zat = (parsed.zat && typeof parsed.zat === "object" ? parsed.zat : parsed);
             const lines = [];
             lines.push("# ZAT Inspection Report");
             lines.push("");
-            // Identity
             lines.push("## Identity");
             lines.push(`- **Issuer**: ${zat.iss || "unknown"}`);
             lines.push(`- **Subject**: ${zat.sub || "unknown"}`);
             lines.push(`- **Mark ID**: ${zat.mark_id || "none"}`);
             if (zat.ver)
                 lines.push(`- **Spec Version**: ${zat.ver}`);
-            // Determine ZAT type
             const isOss = typeof zat.sub === "string" && zat.sub.startsWith("github:");
             lines.push(`- **Type**: ${isOss ? "OSS Repository" : "Enterprise Organization"}`);
             lines.push("");
-            // Validity
             lines.push("## Validity");
             const issuedAt = zat.issued_at;
             const expiresAt = zat.expires_at;
@@ -93,12 +84,10 @@ export function createInspectZatHandler() {
                 lines.push(`- **Status**: ${now > exp ? "EXPIRED" : now < iss ? "NOT YET VALID" : "ACTIVE"}`);
             }
             lines.push("");
-            // Claims
             const claims = zat.claims;
             if (claims) {
                 lines.push("## Claims");
                 if (isOss) {
-                    // OSS ZAT claims
                     lines.push(`- **Trust Score**: ${claims.score ?? "N/A"} / 100`);
                     lines.push(`- **Grade**: ${claims.grade ?? "N/A"}`);
                     lines.push(`- **Commit**: ${claims.commit || "unknown"}`);
@@ -110,7 +99,6 @@ export function createInspectZatHandler() {
                         const total = (findings.critical || 0) + (findings.high || 0) + (findings.medium || 0) + (findings.low || 0);
                         lines.push(`- **Findings**: ${total} total (${findings.critical || 0} critical, ${findings.high || 0} high, ${findings.medium || 0} medium, ${findings.low || 0} low)`);
                     }
-                    // Lens scores
                     const lensScores = claims.lens_scores;
                     if (lensScores && Object.keys(lensScores).length > 0) {
                         lines.push("");
@@ -121,12 +109,10 @@ export function createInspectZatHandler() {
                     }
                 }
                 else {
-                    // Enterprise ZAT claims
                     lines.push(`- **Z-Score**: ${claims.z_score_display ?? "N/A"} / 1000 (raw: ${claims.z_score_raw ?? "N/A"})`);
                     lines.push(`- **Trust Tier**: ${claims.tier ?? "N/A"} — ${claims.tier_label || "Unknown"}`);
                     lines.push(`- **Tier Score**: ${claims.tier_score ?? "N/A"}% (progress within current tier)`);
                     lines.push(`- **Coverage**: ${typeof claims.coverage_pct === "number" ? (claims.coverage_pct * 100).toFixed(1) + "%" : "N/A"}`);
-                    // Tier explanation
                     const tier = claims.tier;
                     if (typeof tier === "number") {
                         const tierExplanations = {
@@ -148,7 +134,6 @@ export function createInspectZatHandler() {
                 }
                 lines.push("");
             }
-            // Frameworks
             const frameworks = zat.frameworks;
             if (frameworks && frameworks.length > 0) {
                 lines.push("## Frameworks");
@@ -163,7 +148,6 @@ export function createInspectZatHandler() {
                 }
                 lines.push("");
             }
-            // Evidence
             const evidence = zat.evidence_manifest;
             if (evidence) {
                 lines.push("## Evidence Manifest");
@@ -174,7 +158,6 @@ export function createInspectZatHandler() {
                 lines.push("- *The bundle hash is a SHA-256 digest of all assessment evidence. If the underlying data changes, this hash will no longer match, indicating tampering.*");
                 lines.push("");
             }
-            // Methodology
             const methodology = zat.methodology;
             if (methodology) {
                 lines.push("## Methodology");
@@ -188,7 +171,6 @@ export function createInspectZatHandler() {
                 }
                 lines.push("");
             }
-            // Signatures
             const sig = zat.sig;
             if (sig) {
                 lines.push("## Cryptographic Signatures");
@@ -244,4 +226,3 @@ function formatKey(key) {
         .replace(/_/g, " ")
         .replace(/\b\w/g, (c) => c.toUpperCase());
 }
-//# sourceMappingURL=inspect-zat.js.map

package/dist/tools/inspect.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import type { ApiClient } from "../api-client.js";
+import type { ZivisConfig } from "../types.js";
+export declare const INSPECT_NAME = "zivis_inspect";
+export declare const INSPECT_DESCRIPTION = "Build a local repo graph and run the local pattern matcher to emit threat-model findings. The threat-model-first conversion event.\n\nPrefer zivis_get_started first \u2014 it reads the local inspect cache and only calls this tool when a fresh artifact is missing. Calling zivis_inspect directly always re-runs (no idempotency at this layer); reach for it when the user explicitly says \"re-inspect\" / \"rebuild the graph\" / \"/inspect\" or when an entry tool tells you to.\n\nUse this when the user says any of:\n- \"model this app\" / \"threat model this repo\"\n- \"what should we be worried about in this code\"\n- \"set up security for this project\" (after auth/binding is done)\n- \"/inspect\"\n\nWhat it does, all locally (no source code leaves the machine):\n  1. Spawns 'zivis inspect' to walk the repo and produce a typed graph artifact\n     (services, endpoints, external dependencies; auth boundaries + dataflow are Phase 1.5)\n  2. Runs the local matcher against the public pattern pack:\n     - AST strategies fire via @ast-grep/napi for TS/JS/Python/Go\n     - META strategies fire via the controls library (when no defending control is present)\n     - INFER strategies emit candidates the host LLM picks up via zivis_threat_get_inference_prompt\n  3. Returns normalized findings with lane (trusted/inferred), confidence, and evidence spans\n\nTrusted-lane findings are evidence-backed (deterministic strategies fired) and ready for the threat model. Inferred-lane findings need host-LLM confirmation via zivis_threat_get_inference_prompt before promotion. Proprietary platform-side eval (Phase 4 cloud upload) and trust-promoted aggregation are separate steps.\n\nThis is the conversion moment for the threat-model-first sidekick \u2014 the user sees specific patterns naming specific files in their repo, in their IDE, in under 30 seconds.";
+export declare const INSPECT_SCHEMA: {
+    cwd: z.ZodOptional<z.ZodString>;
+    application_id: z.ZodOptional<z.ZodString>;
+    skip_matcher: z.ZodOptional<z.ZodBoolean>;
+};
+export declare function createInspectHandler(_apiClient: ApiClient, _config: ZivisConfig): (params: {
+    cwd?: string;
+    application_id?: string;
+    skip_matcher?: boolean;
+}) => Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}>;