Security Policy

Reporting contact, supported versions, threat model summary, and capability boundaries for aidokit. The canonical, long-form threat model lives at .docs/docs/specs/security-model.md; this file is the short, repo-root surface required by GitHub and by standard supply-chain hygiene.

1. Reporting a vulnerability

Email george@aicenter.ae with the details below. Do not open a public GitHub issue, discussion, or pull request that describes an unpatched vulnerability.

A useful report includes:

• Affected component (aidokit CLI, a specific @aidokit/* package, the MCP catalog, etc.) and the affected version(s).
• A minimal reproducer — commands, sample project, screenshots, or a small repo. Synthetic projects are preferred over real ones.
• Impact in plain language: what an attacker could accomplish, against what trust boundary.
• Suggested severity (High / Medium / Low / Info) per .docs/docs/specs/security-model.md §2.2.
• Whether the issue has been disclosed publicly anywhere else.

Please do not:

• Run exploits against shared infrastructure, the npm registry, or third-party services.
• Test against other users' projects, CI environments, or machines you do not own.
• File public issues, post to social media, or share write-ups before the coordinated disclosure date.

1.1 Disclosure window

We aim for coordinated disclosure within 90 days of an acknowledged report. The per-severity targets in .docs/docs/specs/security-model.md §15 are tighter for High-severity issues; the 90-day window is the outer bound across all severities and the public commitment.

Expected response cadence:

• 24 hours: initial acknowledgment of receipt.
• 72 hours: severity assessment and a first technical response.
• Per §15 of the security model spec: patch timeline and disclosure date.

Reporters are credited in the resulting advisory unless they request anonymity.

2. Supported versions

aidokit is pre-1.0 and pre-alpha at the time of writing. The policy below takes effect once published versions exist.

2.1 Pre-1.0 (current)

Only the latest minor receives security fixes. Older minors will not be back-patched. Users on an older minor should upgrade to receive fixes.

2.2 Post-1.0

Once aidokit reaches v1.0:

• The latest two minors of the current major receive security fixes.
• The last minor of the previous major receives security fixes for 6 months after the new major's GA, then drops to best-effort.
• Older lines are end-of-life.

3. Threat model summary

aidokit is a deterministic scaffolder. It writes files into a project directory and, when invoked by the user, prints shell commands the user's AI coding CLI or package manager will run. It does not:

• Call any LLM or model API.
• Send telemetry, analytics, or version-check pings.
• Run as a daemon, background watcher, or network service.
• Auto-install prerequisites (Node, Git, Claude Code, Beads). It detects and reports; the user installs (per ADR-0008).
• Read or transmit project source code beyond the manifest files needed for stack detection (package.json etc.).

3.1 Trust boundaries

Anything aidokit emits to disk inherits the user's own filesystem permissions. Adapter and stack-pack packages run with full Node.js privileges at install and emit time — the same as any other dependency in the user's project. There is no sandbox.

For the full threat enumeration (T01–T17) and per-threat mitigations, see .docs/docs/specs/security-model.md §6–§7.

4. Capability boundaries

These are the boundaries aidokit enforces today, and the ones it will enforce at v1.0.

4.1 Filesystem

• Reads and writes only under the project root supplied by --cwd (default: process CWD).
• Never writes above the project root or to unrelated locations in $HOME. The single exception is $AIDO_HOME (default ~/.aido/), used only for user-scoped cache and state that the user explicitly opted into.
• Path-guard tests in packages/core verify that every emitted path resolves inside the project root via path.relative (no .., no absolute escapes).
• Writes are staged to <projectRoot>/.aido-staging/ and atomically moved into place. A failure during stage leaves the project unchanged.

4.2 Shell execution

• All child_process use goes through the single shared exec helper in @aidokit/core. Direct child_process.spawn/exec outside that helper is a code-review red flag (see AGENTS.md §7.3).
• The helper uses array-form invocation (no shell interpolation) and bounded timeouts.
• --dry-run never executes shell commands, including postInstall and prereq-install hints.

4.3 Network

• aidokit init, aidokit sync, and aidokit doctor make no network calls in v0.1 or v0.5. The only network traffic during normal use comes from npm install (during package installation) and from shell commands declared in an adapter manifest that the user has confirmed.
• v1.0 introduces aidokit search adapter|stack-pack, which queries the public npm registry read-only. No authenticated endpoints, no telemetry.

4.4 Prerequisites

• Node.js, Git, Claude Code, and Beads are checked for presence and minimum version. They are never auto-installed, even with --yes. The CLI prints an OS-appropriate install command and waits for the user to run it (ADR-0008).

4.5 Confirmation bypass

--yes skips routine prompts but must not bypass:

• MCPs marked securitySensitive: true.
• Custom MCPs added via --custom-url.
• Tracked-file deletions.
• Prerequisite installations.

See .docs/docs/specs/security-model.md §7.7.

5. Capability declarations (v1.0)

v1.0 requires every adapter manifest to declare, ahead of time, via the capabilities field (see CapabilitiesSchema in packages/core/src/schema.ts):

• shellCommands — command prefixes the adapter invokes.
• writesOutsideEngine — paths the adapter writes outside its declared engine directory and agent-rules file.
• networkEndpoints — hostnames or URL prefixes the adapter contacts.
• backgroundProcesses — whether the adapter relies on a background process or daemon (MUST be false for first-party adapters per ARCHITECTURE §1).

The conformance harness verifies presence and shape via AD-MIN-13 (see packages/core/src/conformance/adapter-checks.ts). A missing or malformed capabilities field is a Minimum-level conformance failure that blocks publication.

The legacy capabilityDeclarations field remains in the manifest schema for v0.5 compatibility; both fields are present in first-party adapters and report the same surface from different angles.

First-party adapters covered by these declarations:

• @aidokit/adapter-claude-code (Strict conformance)
• @aidokit/adapter-codex (Minimum conformance — watchdog enforcement is prompt-level; Codex CLI has no hook mechanism)
• @aidokit/adapter-copilot (Minimum conformance — watchdog enforcement is prompt-level; GitHub Copilot CLI has no hook mechanism). See ADR-0016 for the v1.0 scope-expansion rationale.

6. Dependency hygiene

• @aidokit/core has zero runtime dependencies on other @aidokit/* packages. Third-party adapter and stack-pack authors can depend on @aidokit/core standalone.
• Adapters and stack packs may add external dependencies. New external runtime dependencies require either an ADR or explicit justification in the PR description. Dev dependencies are looser; new transitive runtime deps are reviewed at PR time via the lockfile diff.
• All packages target Node.js 20+ and ship as ESM (per ADR-0001).
• pnpm-lock.yaml is committed and CI runs with --frozen-lockfile once Phase 0 lands.
• npm audit / pnpm audit is run before each tagged release; High-severity advisories block the release.

7. Supply chain

• npm provenance / Sigstore signing is a v1.0 exit criterion (.docs/docs/specs/security-model.md Appendix A.1). Until v1.0, packages are published without provenance attestations.
• Until provenance lands, users SHOULD verify the GitHub source matches the npm tarball before relying on aidokit in automated pipelines. For internal CI use, prefer pinning to an exact version and committing the lockfile.
• The @aidokit/* npm scope is reserved for first-party packages. Squatting is enforced by npm scope ownership; third-party adapters publish under their own scope.
• From v1.0 onward, @aidokit/* releases will be published with npm publish --provenance --access public via GitHub Actions OIDC. Users will be able to verify with npm audit signatures.

8. Hardening checklist for adapter authors

If you are building a third-party adapter, the short version is:

• [ ] Declare your capability surface honestly — every path you write, every shell command prefix you invoke, every network endpoint you contact. Under-declaration is a conformance failure, not a feature.
• [ ] Use the shared exec helper in @aidokit/core for every child_process call. Do not call spawn/exec/execSync directly.
• [ ] Never use dynamic code execution (the eval-family primitives, dynamic require(), or the Function constructor) on adapter input, user-supplied strings, or template variables.
• [ ] Use path.relative checks for any user-supplied path. Reject paths that resolve outside the engine directory or project root.
• [ ] Treat template variables as untrusted input, even though they originate from the user's own package.json or prompts. They are strings of unknown shape from aidokit's perspective; do not concatenate them into shell commands without escaping.
• [ ] Don't read or transmit credentials, environment variables containing secrets, or SSH keys.
• [ ] Don't phone home. No telemetry, no version-check pings, no anonymous metrics.
• [ ] Pass the conformance harness in CI on every published version.
• [ ] Sign packages with npm provenance from v1.0 onward.

The long version, with rationale and per-mistake guidance, is at .docs/docs/specs/security-model.md §11.

9. See also

• Full threat model and mitigations: .docs/docs/specs/security-model.md.
• Error envelope (AidoError) and reserved codes: .docs/ARCHITECTURE.md §16.
• Conformance levels and security-relevant checks: .docs/docs/specs/conformance-levels.md.
• MCP catalog security model: .docs/docs/specs/mcp-catalog.md §10.
• ADR-0008 — Prereq install policy (no auto-install): .docs/docs/architecture/decisions/0008-prereq-install-policy.md.
• Repo agent rules and anti-patterns: AGENTS.md §6, §8.