Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
177 lines (134 loc) · 6.42 KB

CONTRIBUTING.md

File metadata and controls

177 lines (134 loc) · 6.42 KB
Raw

Contributing to SecureToolKit

Thank you for helping improve SecureToolKit. This project treats public API and documentation changes as security-relevant work: a model proposal never grants authority, Validation never performs Consumption or Execution, and the Host owns every side effect.

The repository is currently a pre-1.0 Phase 7 RC1 candidate. Phase 8 has not begun. Contributions must not introduce later-phase behavior or alter frozen protocol semantics without an explicitly accepted decision.

Choose your contribution path

The required context should match the risk of the change. Fixing a typo does not require reading the full protocol.

Quick documentation contribution

Use this path for a typo, broken link, formatting defect, or wording clarification that does not change a security claim, lifecycle, API sequence, status, or normative meaning.

Read:

  1. the affected document;
  2. the applicable engineering rules; and
  3. this contribution guide.

Keep the patch narrow, verify every changed link and Markdown fence, and run git diff --check. If the wording touches Authorization, Validation, Consumption, Execution, Host authority, release status, or another security term, use the normal or protocol/security path instead.

Normal contribution

Use this path for ordinary source, test, example, or non-normative documentation work that stays within accepted behavior.

Read:

  1. Engineering rules
  2. Project overview, including the Host responsibility matrix
  3. Security model
  4. Security invariants
  5. Architecture
  6. Documentation and ADRs directly relevant to the affected component

Run the complete applicable build, test, formatter, and structural checks.

Protocol or security contribution

Use this path for a trust-boundary, authority, canonicalization, policy, controlled-artifact, confirmation, Consumption, Execution, public API, or normative security change. Such work requires explicit authorization and an accepted decision before implementation.

Read these documents in order:

  1. Engineering rules
  2. Vision
  3. Security model
  4. Security invariants
  5. Architecture
  6. Public API design
  7. Threat model
  8. Documentation index
  9. Relevant architecture decisions and protocol records

Security vulnerabilities follow SECURITY.md, not any ordinary contribution path or public issue workflow.

Development setup

Documentation-only validation

For a quick documentation contribution, verify changed local links, balanced Markdown fences, terminology in the surrounding section, and:

git diff --check

The complete Swift suite is not required for a prose-only typo or link fix that cannot affect generated artifacts, code snippets, package behavior, or security meaning. Follow any stricter instructions in the affected subtree.

Code and test validation

Requirements:

  • Swift 6.0 or newer
  • Swift Package Manager
  • Python 3 for structural checks

Validate a checkout with:

swift package describe
swift build
swift test
swift test --verbose
swift format lint --recursive --strict Package.swift Sources Tests
python3 Scripts/check_phase1_structure.py
python3 Scripts/check_phase2_structure.py
python3 Scripts/check_phase3_structure.py
python3 Scripts/check_phase4_structure.py
python3 Scripts/check_phase5_structure.py
python3 Scripts/check_phase6_structure.py
git diff --check

Use swift format --in-place --recursive Package.swift Sources Tests before submitting Swift changes.

Change discipline

  • Work on one explicitly approved scope at a time.
  • State the security objective, scope, non-goals, and affected invariants.
  • Treat model output, retrieved content, tool output, and missing provenance as untrusted.
  • Treat every new public field, enum case, default, schema, initializer, and conversion as a security decision.
  • Keep the core deterministic and dependency-free unless an accepted ADR says otherwise.
  • Prefer immutable Sendable values and explicit dependencies.
  • Never introduce a hidden clock, hidden global state, implicit authority, default policy, or permissive fallback.
  • Do not weaken or remove a test solely to make a change pass.
  • Add negative coverage for each applicable invariant and threat.
  • Keep credentials, secrets, personal data, customer records, raw prompts, and sensitive arguments out of code, tests, examples, issues, and logs.

Architecture decisions

A new or superseding ADR is required before changing a trust boundary, authority source, canonical representation, policy meaning, controlled artifact, provenance semantics, confirmation semantics, single-use contract, audit integrity, public module boundary, or executor boundary.

Accepted ADRs and frozen protocol records take precedence over examples and historical evidence. A contradiction is a release defect, not permission to use the more permissive interpretation.

Pull requests

Keep pull requests narrow and include:

  • the problem and security impact;
  • files and public APIs affected;
  • invariants and threat-model entries reviewed;
  • positive and negative tests added or changed;
  • exact validation commands and results;
  • migration or compatibility impact;
  • confirmation that Execution remains outside SecureToolKit; and
  • confirmation that unrelated worktree changes were not included.

Reviewers should be able to reproduce the result from one commit without private context.

Review checklist

  • Can model-controlled content create, infer, or broaden authority?
  • Do unknown, missing, stale, malformed, duplicate, or unverifiable values fail closed?
  • Are tool identity, schema, arguments, subject, tenant, session, delegation, policy, Host boundary, capabilities, and resources bound exactly?
  • Are capabilities and resources intersected rather than unioned?
  • Can authentication substitute for human confirmation?
  • Are Validation, Consumption, and Execution still separate?
  • Are errors deterministic and privacy-safe?
  • Are time, replay, substitution, concurrency, and boundary negatives covered?
  • Do all applicable tests, format checks, and structural checks pass?

Community standards

Participation is governed by CODE_OF_CONDUCT.md. General questions and non-security support follow SUPPORT.md.