ai-kit-python 1.4.2__py3-none-any.whl

aikit/template/ai-kit/router/providers/openai.json

@@ -0,0 +1,48 @@
+{
+  "verified_documentation_date": "2026-10-08",
+  "roles": {
+    "cheap": {
+      "model": "gpt-6-luna",
+      "effort": "low"
+    },
+    "work": {
+      "model": "gpt-6.1-sol",
+      "effort": "medium"
+    },
+    "escalation": {
+      "model": "gpt-6-astra",
+      "effort": "high"
+    }
+  },
+  "reasoning_mode": "standard",
+  "service_tier_policy": "standard",
+  "supported_efforts": {
+    "cheap": [
+      "none",
+      "low",
+      "medium",
+      "high",
+      "xhigh",
+      "max"
+    ],
+    "work": [
+      "low",
+      "medium",
+      "high",
+      "xhigh",
+      "max"
+    ],
+    "escalation": [
+      "low",
+      "medium",
+      "high",
+      "xhigh",
+      "max"
+    ]
+  },
+  "sources": [
+    "https://developers.openai.com/api/docs/models/gpt-6-luna",
+    "https://developers.openai.com/api/docs/models/gpt-6.1-sol",
+    "https://developers.openai.com/api/docs/models/gpt-6-astra"
+  ]
+}

aikit/template/ai-kit/router/providers/openai.md

@@ -0,0 +1,14 @@
+# OpenAI provider controls
+
+Load only with a routing/runtime task. [openai.json](openai.json) is the single owner of active model IDs and default role/effort mappings.
+Its documentation date is not proof of account access. Verify current runtime registry, endpoint, region, tool support, efforts, modes, context/output limits, prices, and actual served tier.
+
+- Prefer Responses for reasoning-enabled function/tool workflows. Some Chat Completions model combinations lack tool calling or require none effort.
+- reasoning.effort and reasoning.mode are separate controls. Default standard; pro adds billed work and needs a supported endpoint/model and justified expected benefit.
+- Policy standard tier maps to service_tier default; auto follows project settings. Flex/fast/priority/ultrafast availability varies by model/region/account. Observe the actual served tier.
+- For applicable models, check the large-input pricing boundary against current model documentation before a large call; do not put a fixed pricing threshold into universal policy.
+- max_output_tokens includes reasoning; a short visible reply can require a larger reasoning allowance.
+- Verify prompt caching eligibility and cached-token observations; a stable prefix alone is not a cache hit.
+
+Sources: [model catalog](https://developers.openai.com/api/docs/models), [reasoning](https://developers.openai.com/api/docs/guides/reasoning), [Responses create](https://developers.openai.com/api/reference/java/resources/responses/methods/create), [prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching).
+No model-switching runtime or API credentials are installed by this distribution.

aikit/template/ai-kit/router/routing.json

@@ -0,0 +1,11 @@
+{
+  "schema": 1,
+  "mode": "recommended",
+  "profile": "balanced",
+  "project_pin": null,
+  "task_pins": {},
+  "minimum_cases": 20,
+  "quality_floor": 0.8,
+  "context_bytes": {"economy": 16000, "balanced": 32000, "quality": 64000},
+  "orchestration": {"planner": "work", "executor": "work", "reviewer": "work", "escalation": "escalation"}
+}

aikit/template/ai-kit/router/selection.json

@@ -0,0 +1,14 @@
+{
+  "schema": 1,
+  "default_provider": null,
+  "roles": {
+    "cheap": null,
+    "work": null,
+    "escalation": null
+  },
+  "local_models": {
+    "cheap": null,
+    "work": null,
+    "escalation": null
+  }
+}

aikit/template/ai-kit/settings.json

@@ -0,0 +1,11 @@
+{
+  "project_language": "English",
+  "chat_language": "Russian",
+  "sharing_mode": "private",
+  "conventions": "owner",
+  "upstream": {
+    "url": "https://github.com/tigusigalpa/ai-kit",
+    "ref": "main",
+    "source_directory": "template"
+  }
+}

aikit/template/ai-kit/stacks/DOTNET.md

@@ -0,0 +1,13 @@
+# .NET
+
+Confirm target frameworks (global.json, *.csproj/*.fsproj), solution layout, and configured checks before editing.
+- Respect nullable reference types and the project's existing warning policy; do not silence nullable or analyzer warnings without a documented reason.
+- Use async/await for I/O end to end and propagate CancellationToken; avoid sync-over-async (Task.Result, .Wait) and unbounded parallelism.
+- Manage IDisposable/IAsyncDisposable with using/await using so handles and connections close deterministically.
+- Throw typed exceptions, preserve inner exceptions, and validate arguments at public boundaries (ArgumentNullException.ThrowIfNull and explicit messages).
+- Prefer records and LINQ where they clarify intent; keep hot paths allocation-conscious without premature optimization.
+- Use ILogger with structured properties and secret redaction; no secrets in exceptions or log output.
+- Test with the configured xUnit/NUnit/MSTest setup, covering async and error paths; use WebApplicationFactory/TestServer for HTTP contracts.
+- Run dotnet build/test plus the project's format and analyzer commands; pin SDKs with global.json when the repository does and review dependency upgrades.
+
+Sources: [C# language reference](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/), [nullable reference types](https://learn.microsoft.com/en-us/dotnet/csharp/nullable-references), [.NET CLI](https://learn.microsoft.com/en-us/dotnet/core/tools/).

aikit/template/ai-kit/stacks/FILAMENT.md

@@ -0,0 +1,18 @@
+# Filament
+
+Apply only to confirmed Filament work. Inspect composer.json and composer.lock for Filament, Laravel, PHP, Livewire, and plugins; inspect frontend locks when assets change. A detected dependency suggests this profile but does not establish panel usage or a supported runtime. Combine the [Laravel baseline](LARAVEL.md) with this profile for Laravel modules; apply [owner conventions](../profiles/OWNER.md) only when selected.
+
+## Version and structure
+
+- Match APIs and generators to the installed major version. Confirm compatibility before a new installation or upgrade; preserve an existing application's version and layout. The official [installation guide](https://filamentphp.com/docs/5.x/introduction/installation) covers panel and component installations; do not run a fresh-app scaffold over an existing project.
+- Follow the project's Resource, Page, RelationManager, Widget, and schema conventions. Keep forms, tables, filters, and actions focused on presentation; put reusable business operations in the existing application service layer. Avoid creating duplicate domain logic in UI callbacks.
+- Bound queries and loading: eager-load displayed relations, paginate large tables, and check reactive fields/widgets for repeated queries. Validate submitted data and uploads on the server. Review what public Livewire state exposes to the browser.
+
+## Authorization and verification
+
+- Enforce panel access, model policies, action authorization, and tenant scope on the server. Hidden navigation or controls do not protect a callable operation. Check related-owner access and additional model properties explicitly; never assume an extra property receives the resource record's checks.
+- Review the [resource authorization contract](https://filamentphp.com/docs/5.x/resources/overview#authorization) for single-record and bulk operations. Test mixed selections, denied records, and cross-tenant access. Do not remove query scopes or skip authorization to make a screen work.
+- Keep effects, retries, transactions, and money handling under the Laravel baseline. When owner conventions apply, verify public UUID URLs and bindings through Resources and relation pages.
+- Use the project's PHPUnit/Pest and Livewire setup. Test affected list/filter behavior, create/edit validation and persistence, direct denied requests, actions/bulk actions, and tenant isolation. A visible button or a successful page load alone is insufficient verification.
+
+Version-match the official [security guide](https://filamentphp.com/docs/5.x/advanced/security) and [resource tests](https://filamentphp.com/docs/5.x/testing/testing-resources). Report application checks that could not run; kit validation does not execute a Filament application.

aikit/template/ai-kit/stacks/FRONTEND.md

@@ -0,0 +1,9 @@
+# Frontend / JavaScript / TypeScript
+
+Confirm package.json, lockfile/package manager, Node version, bundler, and framework/module boundaries. Do not assume Vite/Inertia/Livewire solely from Laravel.
+- Honor the pinned package manager/Node version and use reproducible lock-based installation. Keep generated assets separate from source.
+- Run actual type/lint/unit/build commands; new TypeScript code should have a documented strictness baseline. Avoid unrelated tool migrations.
+- Check accessibility, keyboard/focus behavior, loading/error states, escaping, and server-side authorization boundaries.
+- Treat browser-exposed configuration as public; secrets belong on the server. Audit dependencies after relevant changes.
+- Test affected interactions with the project's tooling; distinguish a successful asset build from a verified browser interaction.
+- Preserve asset URL/cache behavior and generated manifest contracts with the backend. Bound fetch requests and cancel obsolete work.

aikit/template/ai-kit/stacks/GO.md

@@ -0,0 +1,19 @@
+# Go
+
+Confirm go.mod/toolchain, module boundaries, supported platforms, vendoring, and actual CI before editing.
+- Keep package boundaries simple; expose small interfaces at consumers. Do not force a speculative internal/pkg layout.
+- Propagate context.Context through I/O. Honor cancellation in handlers/workers; use configured http.Client and server timeouts, close response bodies, and bound payloads.
+- Wrap errors with %w when callers must inspect the cause; use errors.Is/As and keep errors actionable. Document nil/zero-value behavior for public types.
+- Make goroutine ownership/termination explicit. Use structured cancellation (such as errgroup when already appropriate), bounded concurrency, and clear synchronization.
+- Use log/slog or the established logger with structured fields and secret redaction.
+- Use table-driven tests and httptest for HTTP contracts; cover cancellation, timeout, race-sensitive scenarios, and errors.
+- Run gofmt, targeted tests, go test ./..., and go vet as appropriate; use the project's staticcheck/golangci-lint configuration. New CI should include supported -race scenarios and govulncheck.
+- Preserve go.mod/go.sum and deliberate vendor/modules.txt. Review go mod tidy diffs; do not add unrelated dependency churn.
+
+Example preserving a cause:
+
+~~~go
+return fmt.Errorf("load account: %w", err)
+~~~
+
+Sources: [HTTP client](https://pkg.go.dev/net/http#Client), [Go security](https://go.dev/doc/security/best-practices), [module reference](https://go.dev/doc/modules/gomod-ref).

aikit/template/ai-kit/stacks/INFRA.md

@@ -0,0 +1,12 @@
+# Infrastructure (Terraform/Helm)
+
+Confirm tool versions, state backend, environments/workspaces, and the apply/review workflow before editing.
+- Format and validate before plan: terraform fmt -check, terraform validate, then plan against the intended workspace; apply only after review and an explicit request.
+- Keep state remote, locked, and separated per environment; never commit state, .terraform/, or secrets. Supply values through variables/TF_VAR or a secrets manager, not literals in tracked .tf/.tfvars files.
+- Pin provider and module versions; review upgrade diffs and state-migration risk; keep modules small and composable with explicit variables and outputs.
+- Prefer data sources and remote state over duplicating values; document required inputs in descriptions or the module README.
+- Charts: lint and render before installing (helm lint, helm template with representative values); pin chart and image versions, set resource requests/limits, and honor values.schema.json where present.
+- Keep rendered Kubernetes manifests aligned with the container contract (non-root, probes, resource requests); wire secrets through existing secret mechanisms, never plain values.
+- Review plans and diffs for destructive changes (replace/destroy); protect production with approvals and, where configured, policy checks in CI.
+
+Sources: [Terraform CLI](https://developer.hashicorp.com/terraform/cli), [Terraform language](https://developer.hashicorp.com/terraform/language), [Helm documentation](https://helm.sh/docs/).

aikit/template/ai-kit/stacks/JAVA.md

@@ -0,0 +1,13 @@
+# Java (Maven/Gradle)
+
+Confirm the build tool and version (pom.xml, build.gradle(.kts), wrapper), language level, and configured checks before editing.
+- Build through the Maven/Gradle wrapper (mvnw/gradlew) so CI and contributors share one toolchain; never edit generated build output.
+- Keep packages cohesive and public APIs minimal; prefer composition and small interfaces over deep inheritance.
+- Use Optional as a return type only, never as fields or parameters; use streams where they clarify and loops where they perform.
+- Handle checked exceptions at boundaries, wrap with context, and preserve causes; validate arguments with Objects.requireNonNull and explicit messages.
+- Manage resources with try-with-resources so streams and connections close deterministically.
+- Use SLF4J (or the established logger) with secret redaction; no secrets in exceptions or logs.
+- Test with the configured JUnit 5/Mockito stack, covering error paths and concurrency; keep tests hermetic, repeatable, and free of real data.
+- Run the wrapper's test/verify plus the project's format/static analysis; keep plugin and dependency versions pinned and review upgrades.
+
+Sources: [Maven guides](https://maven.apache.org/guides/), [Gradle user manual](https://docs.gradle.org/current/userguide/userguide.html), [Java SE documentation](https://docs.oracle.com/en/java/javase/).

aikit/template/ai-kit/stacks/LARAVEL.md

@@ -0,0 +1,15 @@
+# Laravel
+
+Confirm installed Laravel/PHP/Filament versions and composer scripts. Apply the [PHP baseline](PHP.md) and, when conventions=owner, [owner rules](../profiles/OWNER.md).
+For confirmed Filament UI work also apply the [Filament profile](FILAMENT.md).
+- Read env() only from configuration files; use config() in application code so cached configuration works.
+- Validate request boundaries; policies/gates protect APIs, jobs, tenants, and admin UI. Hidden UI controls are not authorization.
+- Keep database transactions bounded. Dispatch dependent jobs/events after commit using supported framework configuration/APIs; rolled-back work must not escape.
+- Make business effects idempotent. Unique jobs/locks help coordination but do not guarantee exactly-once external effects; handle retry/replay explicitly.
+- Set outbound timeouts and retry predicates; do not blindly retry non-idempotent writes. Test remote errors with fakes.
+- Check N+1 queries, pagination, indexes, mass assignment, cache invalidation, and transaction/deletion races.
+- Use exact money representation. Factories create valid minimal records; seeders are safe to rerun. migrate:fresh is only for an isolated disposable database.
+- Use configured PHPUnit/Pest tests. For a new application prefer Pint, an explicitly chosen Larastan level, and a documented test runner; preserve existing tooling.
+- Test UUID route binding, policies, lifecycle, fresh/upgrade migrations, and factories/seeders when affected.
+
+Version-match the official [configuration](https://laravel.com/framework/docs/configuration), [queues](https://laravel.com/framework/docs/queues), [HTTP client](https://laravel.com/framework/docs/http-client), and [Eloquent](https://laravel.com/framework/docs/eloquent) docs to the installed major version.

aikit/template/ai-kit/stacks/LIBRARY.md

@@ -0,0 +1,9 @@
+# Reusable library / SDK
+
+Confirm package type, supported language versions, exported API, versioning policy, and publishing workflow.
+- Preserve public API/serialization/error contracts. Use semantic versioning where adopted; breaking changes require the policy's appropriate version and migration notes.
+- Document examples and compatibility requirements; test consumer use, including Go example tests or Composer autoload where appropriate.
+- Keep protocol numbers/IDs exact, distinguish retryable errors, and expose cancellation/timeouts without leaking provider credentials.
+- Review dependency additions for consumer impact. Check go mod tidy/Go compatibility or composer validate and a supported dependency matrix.
+- Track Go manifests/checksums; for PHP libraries follow the explicit lockfile policy. Keep source/tests/docs rather than unintentionally ignoring release artifacts.
+- Publishing, tags, releases, and external notifications need an explicit task. A passing test suite does not authorize release.

aikit/template/ai-kit/stacks/MOODLE.md

@@ -0,0 +1,12 @@
+# Moodle installation or plugin
+
+Confirm Moodle/PHP versions, plugin type, component, version.php, upgrade history, and actual PHPUnit/Behat commands.
+- Extend supported plugin APIs rather than editing core. Use Moodle data, forms, events, output, and language APIs.
+- Pair the correct context with require_capability/checks; protect state-changing requests with sesskey and avoid trusting client roles.
+- Use get_string and component lang files; escape output according to the renderer/data type. Keep authored project strings English unless explicitly requested otherwise.
+- For schema changes update install.xml, add version-gated upgrade.php steps/savepoints, and bump the plugin version appropriately. Test fresh and existing installations; batch large backfills and bound locks/reruns.
+- Audit personal data storage/export/deletion. Implement the applicable Privacy API provider; use a null provider only after establishing that no personal data is stored.
+- Use Moodle cache APIs with defined keys/invalidation; do not cache capabilities or personal content across contexts incorrectly.
+- Test role/context/capability combinations, migration paths, and privacy behavior. Avoid course/user data in diagnostics.
+
+Match the installed branch of [Privacy API](https://moodledev.io/docs/5.1/apis/subsystems/privacy) and [plugin upgrades](https://moodledev.io/docs/5.1/guides/upgrade).

aikit/template/ai-kit/stacks/PHP.md

@@ -0,0 +1,11 @@
+# PHP
+
+Confirm PHP versions/extensions, composer manifests/lock, autoload boundaries, and framework before edits. Laravel and Moodle add their own profiles.
+- Use Composer autoload/PSR conventions and the project's formatter/static analyzer. Do not impose a new directory layout or analyzer on an existing package.
+- Validate inputs, escape output by its context, parameterize SQL, and enforce authorization; use the shared security baseline.
+- Keep money/quantities exact (integer minor units or decimal/string contracts), not binary floats. Preserve protocol formats.
+- Bound HTTP/connect timeouts, response sizes, retries, and stream ownership. Retry writes only with proven idempotency.
+- Use narrow exceptions, preserve causes, and avoid logging secrets. Test failure paths and public contracts.
+- Run composer validate, configured unit/static/format checks, and dependency audit when applicable. Track application locks; honor deliberate library lock policy.
+
+Sources: [Composer](https://getcomposer.org/doc/03-cli.md), [PSR standards](https://www.php-fig.org/psr/).

aikit/template/ai-kit/stacks/PYTHON.md

@@ -0,0 +1,11 @@
+# Python scripts and packages
+
+Confirm supported Python version, entry points, pyproject/requirements/lock, and configured checks.
+- Separate I/O from core logic. Executables use main() and a __main__ guard; importing must not run the script's work.
+- Use argparse or the existing CLI library; document arguments, output, errors, and exit codes.
+- Use pathlib, explicit encodings, context managers, and streams for large inputs. Validate resolved paths before bulk changes; preview destructive operations.
+- Use subprocess argument lists without a shell; never interpolate untrusted input into commands, eval, or unsafe deserialization.
+- Annotate public/complex boundaries, catch expected exceptions, and preserve causes. Bound network timeouts.
+- Use an isolated environment and versioned manifests/locks. New packages may prefer uv, ruff, and a chosen mypy/pyright baseline; standalone standard-library scripts need no packaging framework.
+- Test success, invalid/boundary input, reruns, and file preservation with temporary directories and substituted external services.
+- Run configured tests/format/lint/type checks; audit trusted dependencies where applicable. Keep real data/secrets out of fixtures and reports.

aikit/template/ai-kit/stacks/RUST.md

@@ -0,0 +1,18 @@
+# Rust
+
+Confirm the toolchain (rust-toolchain.toml), workspace members, supported targets, and configured checks before editing.
+- Follow ownership and borrowing: prefer references over cloning, add explicit lifetimes only where inference fails, and reach for Rc/Arc/RefCell for a diagnosed need, not by default.
+- Keep `unsafe` behind a reviewed boundary: minimal blocks, a safety comment, and encapsulation behind a safe API; never add unsafe to silence the borrow checker.
+- Use Result<T, E> for recoverable failures with meaningful errors (thiserror for libraries, anyhow for applications when already used); panic only on programmer errors, never on user input.
+- Prefer exhaustive matches, iterators, and small focused functions; respect the edition and MSRV before adopting new syntax.
+- Use structured logging (tracing/log) with secret redaction; keep secrets out of panics and error text.
+- Write unit tests beside the code and integration tests under tests/; cover error paths and concurrency. Run cargo fmt, cargo clippy, and cargo test; deny warnings only when CI already does.
+- Keep Cargo.lock for binaries and applications; review dependency additions (cargo audit where configured) and preserve rust-toolchain.toml and the workspace layout.
+
+Example of an explicit error boundary:
+
+~~~rust
+return Err(BuildError::MissingManifest(path.display().to_string()));
+~~~
+
+Sources: [Cargo book](https://doc.rust-lang.org/cargo/), [Rust API guidelines](https://rust-lang.github.io/api-guidelines/), [Clippy](https://doc.rust-lang.org/clippy/).

aikit/template/ai-kit/vendor/security-audit/AI-AND-LLM.md

@@ -0,0 +1,83 @@
+# AI, LLM, and Agent Hunting
+
+#### When to use this file
+
+Reach for this file when a language model participates in a trust-sensitive decision: chatbots and assistants, RAG pipelines, persistent agent memory, agent/tool-calling loops, MCP servers and clients, code that builds prompts from untrusted input, or code that consumes model output and acts on it. The important data flow is *untrusted content → model or memory → capability, authority, or sink*.
+
+Use this alongside `ATTACK-CLASSES.md`, not instead of it. Transport, access control, query construction, filesystem use, and output rendering remain ordinary trust boundaries. This file covers the model-specific delegation layer. Split large targets by retrieval, memory, tool dispatch, MCP, and output handling.
+
+## Core discipline (include in every agent prompt for this domain)
+
+```
+- Prompt injection alone is not a finding. Require a code-level boundary failure: content reaches another principal's context, invokes authority the requester lacks, discloses data they cannot read, or drives a sink they cannot reach directly.
+- Model output, memory, tool descriptions, and MCP responses are untrusted inputs. Point to the code that grants authority, trusts output, writes durable state, or feeds a sink.
+- A guardrail prompt is not a security boundary. Count only deterministic checks, resource-scoped authorization, isolation, binding, and constrained credentials.
+- State the attacker, affected principal, effective execution identity, resource, exact action, authority used, and observable impact. An intentional direct request to use the requester's existing authority is not a delegation defect merely because a model executes it.
+- Authorization and action binding are separate controls. Attacker-controlled content that causes an action under an affected principal's valid authority is an action-binding failure when that principal did not intentionally request or approve the exact action.
+- Classify every candidate as `confirmed` only after source evidence and bounded local validation establish the boundary and result. Use `needs_validation` when a required provider, deployment, model, renderer, or identity behavior is not observable locally.
+```
+
+## Context, retrieval, and memory attack classes (subagent_type: `general`)
+
+**Indirect injection through retrieved or ingested content**
+An attacker can write a RAG document, indexed page, file, email, issue body, tool response, or metadata that enters a different principal's model context. Trace who can write each source, how retrieval scopes it, whose session consumes it, and what capability is enabled there. Check isolation, resource authorization, and binding to the consuming principal's intent separately. The defect is a missing deterministic control, not persuasive text by itself.
+
+**Cross-session or cross-tenant context bleed**
+Conversation history, embeddings, retrieval results, or prompt caches are keyed too broadly. Verify tenant and ACL filters in the query itself and every cache key. A tenant field stored on an object is not enforcement if an alternate query, shared cache, or batch path omits it.
+
+**Persistent memory poisoning**
+Attacker-controlled content or model summaries are written into memory that later shapes another task, user, or privileged session. Review who may create, update, merge, and delete memory; its provenance and tenant scope; whether low-trust observations become durable instructions or facts; and whether retrieval distinguishes user preferences from tool policy. Memory intentionally saved by a user and used only for that user's intentional, allowed requests is not a cross-boundary finding.
+
+**Prompt role and provenance confusion**
+Prompt assembly lets untrusted text impersonate a system message, prior turn, tool result, policy, or memory record. Look for string concatenation, untyped history, caller-controlled role fields, and serialization round trips that lose source labels. Confirm that the forged provenance changes a deterministic trust decision or reaches a meaningful capability.
+
+## Tool and action attack classes (subagent_type: `general`)
+
+**Tool-argument injection into a downstream sink**
+Model-produced arguments reach SQL, shell, file, URL-fetch, or privileged APIs without handler-side validation. Treat the tool schema as input parsing, then follow each field from decoded call to sink. Structured output narrows shape; it does not establish authorization, safe paths, safe URLs, or query semantics.
+
+**Excessive agency and confused-deputy authority**
+The agent uses a service identity or broad credential, while the tool handler does not re-check the requesting principal's permission on the named resource. Verify both the effective identity and whether the caller could perform that exact operation through the normal product interface. A shared credential with enforced per-user query scope is not a defect.
+
+**Action-confirmation and approval binding**
+A user approves one described action but execution can use changed arguments, a different resource, a different principal, or a later model turn. An action-binding defect also exists when attacker-controlled content causes a side effect under a victim's valid authority without the victim's intentional request or approval, even if generic authorization permits the victim to perform it. Review whether intent or confirmation binds the normalized tool name, complete argument object, requester, target, amount, expiry, and batch membership. Check retries and resumed sessions: an approval must not authorize a mutated or duplicate side effect.
+
+**Tool-schema and dispatcher disagreement**
+The schema accepts aliases, extra fields, duplicate keys, coercions, nested free-form objects, or out-of-range values that the dispatcher or handler interprets differently. Compare schema validation, canonicalization, generated bindings, and handler defaults. Validate again where values become resource selectors or security-relevant options.
+
+**Unbounded delegated action loops**
+A bounded request can enqueue repeated spend, send, mutation, or external API work without a per-request budget, per-action authorization, cancellation, or idempotency control. Confirm impact on shared cost, quotas, other users, or durable state. Do not test by exhausting a service; use code-level accounting and a locally bounded loop.
+
+## MCP and sub-agent trust classes (subagent_type: `general`)
+
+**Sub-agent and MCP trust inheritance**
+A delegated task receives the full session, credentials, memory, or capabilities rather than the least authority required. Check the principal and tenant carried into each call, capability narrowing, credential audience, and whether delegated results are treated as untrusted on return.
+
+**MCP server and tool identity confusion**
+Calls or results are routed by attacker-influenceable server names, tool names, request IDs, resource URIs, or model-selected aliases rather than the authenticated connection and outstanding request. Check whether two servers can claim the same tool or resource identity, whether reconnect changes the binding, and whether a response from one server can satisfy another server's pending call.
+
+**MCP metadata and schema as policy**
+Tool descriptions, resource metadata, prompts, completion hints, or schemas supplied by an MCP peer are trusted as policy or authorization. These fields can guide the model but cannot grant capability. Find the deterministic allowlist, server identity check, and handler authorization that remain authoritative when metadata conflicts.
+
+## Output and disclosure attack classes (subagent_type: `general`)
+
+**Insecure output rendering**
+Model output reaches an executing HTML, Markdown, template, URL, or command sink without the sink's required encoding and policy. For browser rendering, verify auto-loaded resources and CSP or sanitization in `CLIENT-SIDE.md`; renderer behavior outside the repository makes the candidate `needs_validation`.
+
+**Sensitive context extraction**
+The assembled context contains credentials, another user's data, private source, or policy values that themselves grant access, and user-influenced output exposes them. Read prompt assembly and data-fetch code. Disclosure of generic instructions or behavior that does not cross a data boundary is not a finding.
+
+## Universal moves (apply across the above)
+
+- Draw four maps first: each execution identity, each capability, every writable context or memory source, and each output destination. Then connect the principal at the start to the authority at the end.
+- Start at side-effecting tools and work backward through dispatcher, schema, confirmation, model context, retrieval, and ingestion. Start at durable memory reads and trace every writer.
+- Compare direct, queued, retry, resume, batch, and delegated paths for the same action. The strongest gate must apply after arguments are final and before every side effect.
+
+## Validation rules (apply before reporting ANY finding here)
+
+1. Name the crossed boundary and observable result: attacker, affected principal or shared resource, execution identity, target, and unauthorized or unrequested action or disclosure.
+2. For confused-deputy authority claims, prove the tool lacks requester-and-resource authorization and that the attacker cannot perform the same action normally. For action-binding claims, instead prove attacker-controlled content caused an action under the affected principal's authority that the principal did not intentionally request or approve. Valid generic authorization does not establish that intent.
+3. For memory or retrieval claims, cite both the attacker-controlled write and the later cross-principal read or privileged decision. A shared record without a reachable consumer is not enough.
+4. For action binding, establish the intentional request or normalized approved object, if any, and compare it with the object the handler uses. Confirm a locally observable unrequested action, mutation, duplicate, or authority change without extending the test into harmful execution. For schema disagreement, compare the normalized validated object with the handler's object.
+5. For MCP identity claims, verify the authenticated connection, request correlation, tool namespace, and effective credential. Mark `needs_validation` if external server identity or deployment routing is required.
+6. Return `confirmed` findings only with a complete source trace and meaningful result. Return `needs_validation` for a specific unresolved boundary fact and state the bounded local or owner-observed check needed to resolve it.

aikit/template/ai-kit/vendor/security-audit/ATTACK-CLASSES.md

@@ -0,0 +1,130 @@
+# Attack Classes
+
+#### Attack classes — choose and split based on Phase 1
+
+Select attack classes relevant to the application type. Not every class applies to every codebase. The list below is a starting point; add application-specific classes from Phase 1 and split large codebases per subsystem. Frame work as finding, validating, fixing, and prioritizing vulnerabilities. Keep validation to source review and bounded local fixtures; do not develop payload chains, test availability on live services, or take action in shared environments.
+
+Use `confirmed` only when source evidence and bounded validation establish the full boundary and meaningful result. Use `needs_validation` when a specific deployment, provider, platform, identity, or runtime fact is unavailable; state the missing fact and the safe owner-observed or local check that resolves it.
+
+> **Native / binary / kernel targets** (C/C++/Rust-unsafe, kernel modules, parsers and decoders, FFI, concurrent runtimes, binary loaders, JITs, firmware): use the memory-safety, integer/ABI, concurrency, binary-loader, and privileged-interface classes in [MEMORY-SAFETY-AND-BINARY.md](MEMORY-SAFETY-AND-BINARY.md).
+>
+> **AI / LLM / agent targets** (chatbots, RAG, persistent memory, tool-calling agents, MCP servers/clients, prompt assembly, or model-controlled actions): use the context, memory-poisoning, action-binding, tool-schema, MCP-identity, and output classes in [AI-AND-LLM.md](AI-AND-LLM.md).
+>
+> **HTTP, web, and identity targets** (ordinary web apps, APIs, reverse proxies, CDNs, gateways, custom HTTP parsers, sessions, CSRF, JWT, OAuth/OIDC, SAML, MFA, passkeys, account recovery/linking, API keys, or mTLS): use [WEB-PROTOCOL-AND-AUTH.md](WEB-PROTOCOL-AND-AUTH.md).
+>
+> **Client-side and browser targets** (SPAs, browser extensions, embedded webviews, service workers, browser storage, cross-window messaging, CORS, WebSockets, or DOM rendering): use [CLIENT-SIDE.md](CLIENT-SIDE.md).
+>
+> **Supply-chain and release targets** (dependency resolution, generated inputs, CI, release/signing/promotion, updates, plugins, or extensions): use [SUPPLY-CHAIN-AND-RELEASE.md](SUPPLY-CHAIN-AND-RELEASE.md).
+>
+> **Cloud and deployment targets** (IAM, infrastructure as code, containers/Kubernetes, service mesh, serverless/edge, ingress, provider events, or runtime configuration): use [CLOUD-AND-DEPLOYMENT.md](CLOUD-AND-DEPLOYMENT.md).
+>
+> **Protocol, RPC, and messaging targets** (gRPC, GraphQL transports, Protobuf/Cap'n Proto/Thrift, custom protocols, queues, brokers, pub/sub, webhooks, or streaming RPC): use [PROTOCOLS-RPC-AND-MESSAGING.md](PROTOCOLS-RPC-AND-MESSAGING.md).
+>
+> **Resource-exhaustion and availability targets** (untrusted work can consume shared CPU, memory, disk, connections, workers, queues, quotas, or operator-owned spend): use [RESOURCE-EXHAUSTION-AND-AVAILABILITY.md](RESOURCE-EXHAUSTION-AND-AVAILABILITY.md).
+>
+> **Data-isolation and lifecycle targets** (multi-tenant stores, caches/search, object links, analytics, export/backup, migration, deletion, retention, or restore): use [DATA-ISOLATION-AND-LIFECYCLE.md](DATA-ISOLATION-AND-LIFECYCLE.md).
+>
+> **Desktop, mobile, and local-IPC targets** (native apps, deep links, webview bridges, exported components, privileged helpers, local daemons, Unix sockets/XPC/Binder/D-Bus): use [DESKTOP-MOBILE-AND-LOCAL-IPC.md](DESKTOP-MOBILE-AND-LOCAL-IPC.md).
+
+**Injection** (subagent_type: `general`)
+Trace untrusted input from entry point to dangerous sink. What counts as a "dangerous sink" depends on the application:
+- Web apps: SQL queries, HTML output, shell commands, template engines, file paths, HTTP redirects, deserialization
+- Libraries: any function that processes caller-supplied data without validation — buffer operations, parsers, format strings
+- CLI tools: shell command construction, file path handling, environment variable interpolation
+- Services: query construction, message serialization, log injection, LDAP/XPATH queries
+- Client-side (browser/JS): DOM XSS, prototype pollution, `postMessage`/origin trust, and other browser-side classes — covered by the [CLIENT-SIDE.md](CLIENT-SIDE.md) companion blocks when selected
+
+Do not stop at the obvious direct paths. Look for indirect injection: data stored safely, then retrieved and used in a dangerous context by different code. Look for injection through field names, keys, headers, and metadata — not just values. Look for injection into secondary systems (logs, caches, search indexes, analytics).
+
+**Access control** (subagent_type: `general`)
+Verify that a caller cannot do something outside its authority. Go beyond checking whether permission checks exist — verify they check the *right* permission for the *right* resource via the *right* mechanism:
+- Is there a path to the same state change that checks a different (weaker) permission?
+- Can a field in the request body override what the permission system intended to restrict?
+- Are there endpoints that gate on authentication but forget authorization?
+- Does the same resource have multiple access paths with inconsistent checks?
+- What about bulk/batch/export/import operations — do they enforce per-item permissions?
+
+For complex access models, split into separate agents for auth bypass vs authorization logic.
+
+**Resource and file handling** (subagent_type: `general`)
+- Path traversal (reading/writing outside intended directories) — including through symlinks, encoded sequences, and null bytes
+- SSRF (making the application fetch attacker-controlled URLs) — including through redirects, DNS rebinding, and URL parser differentials
+- Unsafe deserialization, archive extraction (zip slip), temp file handling
+- Memory safety (if applicable): buffer overflows, use-after-free, integer overflow
+- Race conditions on file operations (TOCTOU between check and use)
+
+**Cryptography and secrets** (subagent_type: `general`)
+- Weak randomness for security-critical values (tokens, keys, nonces)
+- Hardcoded secrets, secrets in logs, error messages, URLs, or client-visible responses
+- Broken key derivation, missing HMAC verification, nonce reuse
+- Timing side-channels on secret comparison
+- Misuse of crypto primitives (ECB mode, unauthenticated encryption, static IVs, etc.)
+- What happens when crypto operations fail? Does the error path fall back to no-crypto?
+
+**Business logic** (subagent_type: `general`)
+Hunt logic errors by hand: standard scanners cannot find them, and they yield high-impact findings. For each major workflow:
+- **State machine violations**: Can you skip steps? Go backwards? Reach an invalid state? What happens if you replay a completed flow? What about partial failure — if step 2 of 3 fails, is step 1 rolled back?
+- **Race conditions with business impact**: Concurrent operations that produce invalid states (double-spend, double-approve, lost updates). Focus on operations that check-then-act non-atomically.
+- **Numeric/quantity manipulation**: Negative values, zero values, overflow, precision loss, type coercion between string and number.
+- **Access boundary violations**: Not "does the permission check exist" but "is it the right check for the business rule?" Can input to one operation bypass a restriction enforced on a different operation for the same effect?
+- **Implicit trust assumptions**: Data from storage, config, other components, or plugins assumed safe because "we validated it on the way in." What if a different code path wrote it?
+- **Time-based logic**: Expiry checks, scheduling, rate windows, clock skew. What happens at exact boundary moments? What about timezone differences between components?
+- **Default and fallback behavior**: What is the security posture when config is missing? When a feature flag is off? When a dependency is unavailable? When the system is mid-migration?
+
+**Feature abuse and data leakage** (subagent_type: `general`)
+Legitimate features used for unintended purposes. Look for bugs in the design, not only in the code:
+- **Export/backup as exfiltration**: Can a low-privilege user trigger an export, snapshot, or backup that includes data above their access level? Can they export other users' data? Does the export include deleted/draft/private content? Revision history that was supposed to be pruned?
+- **Import/restore as injection**: Can import overwrite existing data? Can it create records that bypass normal validation? Can it inject content into collections the user has no write access to? Does it respect the same permission model as the UI?
+- **Search/filter/sort as oracle**: Can search queries reveal whether content exists that the user cannot directly access? Do filter parameters let users probe statuses, roles, or fields they should not know about? Does sorting by a hidden field reveal its values through result ordering?
+- **Enumeration through side effects**: Do error messages differ between "does not exist" and "no access"? Do response times differ? Response sizes? HTTP status codes? Can you enumerate users through password reset, invite, or registration flows?
+- **Preview/draft/staging leakage**: Are preview tokens scoped to one item or do they unlock broader access? Can draft content be discovered through search, RSS feeds, sitemaps, or API listing endpoints? Can cache headers cause a CDN to serve private content publicly?
+- **Notification/webhook as SSRF**: Can a user set a notification URL, webhook URL, or callback URL that the server fetches? Is it validated against internal networks? What about after a redirect?
+
+**Chained vulnerabilities and trust boundaries** (subagent_type: `general`)
+Individually allowed or contained behavior can become a vulnerability when another component or lifecycle step relies on a stronger guarantee:
+- **Multi-step boundary failures**: Map what a low-privilege principal may read, write, invoke, and retain, then connect only concrete outputs to later trust decisions. Confirm each prerequisite and do not assume a downstream effect.
+- **Cross-component trust gaps**: Component A validates input and passes it to component B. Compare the exact guarantee A produces with what B assumes, including truncation, type coercion, normalization, tenant scope, and plugin/extension access.
+- **Second-order use**: Data safe when stored may become dangerous in a later context. A field name becomes a JSON path, a slug becomes a file path, escaped text enters raw rendering, or a stored string becomes a URL, regex, template, or policy expression.
+- **Scope and capability growth**: Token, API-key, plugin, OAuth, MCP, or AI capabilities become broader after delegation, refresh, caching, role change, or composition. Name the concrete operation the resulting principal should not have.
+- **Timing and ordering**: Review setup, migration, soft-delete, revoke/cache expiry, check/use, and validate/consume windows. Confirm stale state is accepted before reporting.
+- **Rollback and recovery**: Undelete, restore, revision rollback, and cancellation must apply current ownership, validation, and authorization. Confirm which invalid state is restored.
+
+**Wildcard** (subagent_type: `general`)
+You are not given a category. Find vulnerabilities outside the standard classes already assigned.
+
+Read code that looks boring or disconnected from security. Follow incomplete, experimental, compatibility, and fallback features, but retain the same concrete boundary and validation requirements as every other class.
+
+Use these starting points, but do not limit yourself to them:
+- What is the strangest code in the codebase? Why does it exist? What happens if it is abused?
+- Are there any features that feel half-finished, experimental, or bolted on? Those have the weakest security because they got the least review.
+- What happens if you use the API in a way the frontend never would? The UI constrains users, but the API does not. What API calls are possible but never made by the client?
+- Are there any hidden or undocumented endpoints, parameters, headers, or features? Look at route registrations, middleware, and config for things that are not in the docs.
+- What happens when you mix features that were not designed to work together? Localization + preview + caching. Import + plugins + webhooks. OAuth + impersonation + API keys.
+- Is there anything interesting in the git history? Reverted security fixes, commented-out auth checks, secrets that were committed then removed (still in history).
+- Which valid-account actions affect other users, shared integrity, availability, or operator-owned cost? Verify containment, quotas, authorization, and recovery around those actions.
+- Which operations are irreversible or require elevated confirmation? Bind authorization and approval to the final principal, action, and resource.
+- What assumptions does the code make about the environment? That the database is local, that the clock is accurate, that DNS is trustworthy, that the filesystem is case-sensitive?
+- Look at the test files — what are they **not** testing? Compare the edge cases the developer thought about (tests exist) with the ones they did not (no tests).
+
+Pursue anomalies inside your assigned scope until the invariant is settled. If something looks strange, read it until you can state whether it is safe. If a function has a comment explaining why it is safe, verify the explanation. If a variable is named `temp` or `hack` or `legacy`, read it closely.
+
+**Obvious things** (subagent_type: `general`)
+Other agents hunt subtle bugs. This agent checks the basic exposures that are easy to overlook because everyone assumes someone else already checked them:
+- Are there any hardcoded passwords, API keys, tokens, or secrets in the source? (grep for `password`, `secret`, `apikey`, `token`, `Bearer`, `-----BEGIN`, common default passwords)
+- Are there any TODO/FIXME/HACK/XXX comments that reference security? (`TODO: add auth`, `FIXME: validate input`, `HACK: skip permission check`)
+- Is debug mode / dev mode properly gated? Can it be enabled in production via environment variable, query parameter, or header?
+- Are there test/example/seed credentials that work in production?
+- Is there a `/debug`, `/admin`, `/test`, `/status`, `/health`, `/metrics`, `/env`, `/.env`, `/config` endpoint that is unprotected?
+- Are there any `.env`, `.env.local`, `credentials.json`, `*.pem`, `*.key` files checked into the repo?
+- Does the `.gitignore` actually cover secrets, uploads, and local config?
+- Are dependencies pinned? Are there known CVEs in the dependency tree? (check lockfiles)
+- Are there any `eval()`, `exec()`, `child_process`, `Function()`, `vm.runInContext`, `import()` with dynamic input?
+- Are CORS headers set to `*` or overly permissive? Is `Access-Control-Allow-Credentials` combined with a wildcard origin?
+- Are cookies missing `HttpOnly`, `Secure`, or `SameSite` attributes?
+- Are there any open redirects? (parameters named `redirect`, `return`, `next`, `url`, `goto`, `continue` that feed into redirects without validation)
+- Is TLS enforced? Are there any HTTP-only endpoints?
+- Are error responses in production returning stack traces, internal paths, or SQL errors?
+
+This agent does not need to be creative. It needs to be thorough and literal. Check every item. Report each result.
+
+**Important**: For any finding this agent reports, it must verify the full code path, not just surface appearance. If a cookie is missing `HttpOnly`, check whether the cookie contains security-sensitive data and whether JS needs to read it by design. If an error message contains a field name, check whether the field is ever actually populated with sensitive data. A flag is not a finding — trace the impact before reporting.