/**
 * Pack-as-remediation type definitions — PR-5a
 *
 * Defines the PackRemediation schema that pack authors use to declare
 * auto-fix actions. These are consumed by the remediation runner at
 * `scanner --fix` time.
 *
 * Security model (Shield H-3):
 *   - Codemod payloads ship as embedded strings (NOT file paths).
 *   - All payloads are signature-verified before execution.
 *   - Codemods execute inside vm.runInNewContext() with a restricted
 *     module allowlist (no child_process, no fs.unlink, no os, etc.).
 *   - Dry-run is mandatory: customer sees a diff before any file is written.
 *
 * @connexum/ai-governance PR-5a
 */
/**
 * Canonical finding codes from the OWASP Agentic scanner.
 * Packs declare which finding code(s) a remediation addresses.
 */
export type FindingCode = 'UNGOVERNED_PHI_TOOL_CALL' | 'HOOK_NOT_WIRED' | 'DECLARATION_MISSING' | 'CLAUDE_MD_MISSING_PHI_POSTURE' | string;
export type RemediationKind = 'codemod' | 'config-patch' | 'doc-insert' | 'wrapper-import';
/**
 * config-patch: JSON-merge into a target config file (e.g. .claude/settings.json).
 * Idempotent — duplicate hook entries are not added.
 */
export interface ConfigPatchPayload {
    kind: 'config-patch';
    /** Target file path relative to the agent directory (e.g. ".claude/settings.json") */
    targetFile: string;
    /** JSON value to deep-merge into the target. Must be a plain object. */
    patch: Record<string, unknown>;
}
/**
 * doc-insert: Markdown section upsert.
 * If the section header already exists the content is replaced.
 * If missing, the header + content is appended.
 * If the target file does not exist it is created.
 */
export interface DocInsertPayload {
    kind: 'doc-insert';
    /** Target file path relative to the agent directory (e.g. "CLAUDE.md") */
    targetFile: string;
    /** Markdown H2 section header (without the ## prefix — added by the handler) */
    sectionHeader: string;
    /** Full markdown content of the section body */
    sectionContent: string;
}
/**
 * wrapper-import: Insert an import / require statement at the top of a source file.
 * Idempotent — checks for an existing import of the same module before inserting.
 */
export interface WrapperImportPayload {
    kind: 'wrapper-import';
    /** Target file path relative to the agent directory */
    targetFile: string;
    /** Language of the target file */
    language: 'typescript' | 'javascript' | 'python';
    /**
     * The import statement to insert.
     * For TS/JS: e.g. "import { GovernedToolExecutor } from '@connexum/ai-governance';"
     * For Python: e.g. "from connexum.pii_shield import shield"
     *
     * The handler checks for an existing import of the same module/package
     * and skips insertion if already present (idempotent).
     */
    importStatement: string;
    /**
     * Field mutations to apply to the agent's capability bundle declaration.
     * Each entry: { fieldName, fieldValue } inserted as a property.
     * Optional — used for wrapper-import remediations that also need to
     * patch a capability bundle (e.g. adding phiHandling: 'tokenized').
     */
    bundlePatch?: Array<{
        /** The field name to insert/update */
        fieldName: string;
        /** The TypeScript value expression as a string (e.g. "'tokenized'") */
        fieldValue: string;
        /**
         * An identifier that appears near the bundle so we can locate it.
         * If absent, patch is applied to the first object literal in the file.
         */
        nearIdentifier?: string;
    }>;
}
/**
 * codemod: AST mutation via ts-morph (TS/JS) or a sandboxed script (Python).
 *
 * Security model (Shield H-3):
 *   - The transform function is an EMBEDDED STRING (not a file path reference).
 *   - It is executed in vm.runInNewContext() with a restricted module allow-list.
 *   - The pack author signs the payload; runtime verifies before execution.
 *   - Write access goes through a controlled API — raw fs.writeFile is not
 *     exposed to the transform. The handler writes the mutated code.
 */
export interface CodemodPayload {
    kind: 'codemod';
    /** Target glob pattern relative to agent directory (e.g. "**\/*.ts", "agent.py") */
    fileGlob: string;
    /** Language / AST engine to use */
    language: 'typescript' | 'javascript' | 'python';
    /**
     * Framework hint — helps the codemod apply the correct wrapper style.
     * 'auto' instructs the engine to detect from imports.
     */
    framework: 'langchain' | 'claude-code' | 'crewai' | 'autogen' | 'raw-node' | 'raw-python' | 'auto';
    /**
     * The transform function as an EMBEDDED STRING.
     *
     * For TS/JS (ts-morph): the string must be valid TypeScript that exports a
     * default async function with signature:
     *   async function transform(sourceFile: SourceFile, helpers: CodemodHelpers): Promise<void>
     *
     * For Python (sandboxed exec): the string must define a top-level function
     * with signature:
     *   def transform(source_code: str, helpers: dict) -> str
     *
     * The `helpers` object exposes:
     *   - helpers.wrapToolCall(callExpression, wrapperStyle)
     *   - helpers.addImport(importStatement)
     *   - helpers.log(message)   (emits to dry-run diff, not stdout)
     *
     * SECURITY: Do NOT include file-system access, network calls, or
     * child_process invocations in this string. They will be blocked by
     * the vm sandbox and will throw RemediationSandboxViolation.
     */
    transformSource: string;
    /**
     * HMAC-SHA256 signature over transformSource.
     * Key: the pack author's signing key (see pack.authoringKey).
     * Verified by the runtime before execution.
     * Set to 'UNSIGNED' only in test fixtures (enforced by runtime in production).
     */
    signature: string;
}
export type RemediationPayload = ConfigPatchPayload | DocInsertPayload | WrapperImportPayload | CodemodPayload;
export interface PackRemediation {
    /** Which finding code(s) this remediation fixes */
    fixes: FindingCode | FindingCode[];
    /** File-level applicability filter */
    appliesTo: {
        /** Glob patterns (relative to agent dir) for files this remediation targets */
        fileMatchers: string[];
        /** Optional framework constraint — only apply when this framework is detected */
        framework?: string;
    };
    /** Which kind of transformation this is */
    kind: RemediationKind;
    /** Kind-specific payload */
    payload: RemediationPayload;
    /** Human-readable rationale cited back to the customer in CLAUDE.md insert */
    rationale: string;
    /** Which pack rule motivates this remediation */
    packRuleId: string;
}
export interface PackRemediations {
    /**
     * Auto-fix remediations for common compliance findings.
     * Applied by the CLI at `scanner --fix` time.
     * Each entry describes how to fix one finding code.
     */
    remediations?: PackRemediation[];
}
export interface RemediationDiff {
    filePath: string;
    before: string;
    after: string;
    /** Human-readable unified-diff string for display to customer */
    unifiedDiff: string;
}
export interface RemediationResult {
    remediation: PackRemediation;
    packId: string;
    packVersion: string;
    status: 'applied' | 'skipped' | 'error' | 'dry-run';
    /** Files that would be (or were) modified */
    filesAffected: string[];
    diffs: RemediationDiff[];
    error?: string;
}
/** Audit event emitted after each applied remediation (PR-5a §C) */
export interface PackRemediationAppliedEvent {
    event_type: 'PACK_REMEDIATION_APPLIED';
    pack_id: string;
    pack_version: string;
    /** Finding codes fixed by this remediation */
    fixes: FindingCode | FindingCode[];
    files_modified: string[];
    applied_by: string;
    applied_at: string;
}
/** Thrown when a codemod transform attempts a disallowed operation in the sandbox */
export declare class RemediationSandboxViolation extends Error {
    constructor(message: string);
}
/** Thrown when pack author signature verification fails */
export declare class RemediationSignatureError extends Error {
    constructor(message: string);
}
//# sourceMappingURL=types.d.ts.map