diff --git a/.github/workflows/dco.yml b/.github/workflows/dco.yml new file mode 100644 index 00000000..937774b4 --- /dev/null +++ b/.github/workflows/dco.yml @@ -0,0 +1,51 @@ +name: DCO + +on: + pull_request: + types: [opened, edited, synchronize, reopened] + branches: + - main + +permissions: + contents: read + pull-requests: read + +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +jobs: + dco: + name: DCO Sign-off Check + runs-on: ubuntu-latest + timeout-minutes: 5 + if: github.event_name != 'pull_request' || github.event.pull_request.draft == false + steps: + - name: Checkout code + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 + with: + fetch-depth: 0 + + - name: Check DCO sign-off + run: | + base="${{ github.event.pull_request.base.sha }}" + head="${{ github.event.pull_request.head.sha }}" + failed=0 + + for sha in $(git rev-list "$base".."$head"); do + if ! git log -1 --format='%B' "$sha" | grep -qiE '^Signed-off-by: .+ <.+>'; then + echo "::error::Commit $sha is missing a DCO Signed-off-by line." + echo " $(git log -1 --format='%s' "$sha")" + failed=1 + fi + done + + if [ "$failed" -eq 1 ]; then + echo "" + echo "All commits must include a Signed-off-by line." + echo "Use 'git commit -s' to sign, or 'git rebase --signoff HEAD~N' to fix existing commits." + echo "See: https://developercertificate.org/" + exit 1 + fi + + echo "All commits are signed off." diff --git a/ASSURANCE-CASE.md b/ASSURANCE-CASE.md new file mode 100644 index 00000000..71060e31 --- /dev/null +++ b/ASSURANCE-CASE.md @@ -0,0 +1,188 @@ +# Security Assurance Case + +This document provides an assurance case for the Archgate CLI, justifying why the project's security requirements are met. It covers the threat model, trust boundaries, application of secure design principles, and countermeasures against common implementation weaknesses. + +> **Scope:** This assurance case covers the Archgate CLI (`archgate` npm package and standalone binary) as of v0.30.x. The plugin distribution service and marketing website are out of scope. + +## 1. Threat Model + +### 1.1 What Archgate Does + +Archgate is a CLI tool that enforces Architecture Decision Records (ADRs) as executable TypeScript rules. It: + +- **Reads** `.rules.ts` files from the project directory and executes them to validate code compliance +- **Reads** project source files through a sandboxed `RuleContext` API +- **Outputs** violation reports to stdout/stderr (console, JSON, or GitHub Actions annotations) +- **Downloads** platform binaries from GitHub Releases (during install/upgrade) +- **Authenticates** users via the operating system's credential manager for plugin installation (optional) + +Archgate does **not**: + +- Modify source code or project files during checks +- Store credentials on disk — authentication tokens are managed by the OS credential manager (macOS Keychain, Windows Credential Manager, Linux secret service) +- Send telemetry or source code to external servers (telemetry is opt-in, anonymized, and contains only usage counts — see [Telemetry docs](https://cli.archgate.dev/reference/telemetry/)) +- Require network access for core functionality (`archgate check` is fully offline) + +### 1.2 Threat Categories + +| ID | Threat | Severity | Likelihood | Description | +| --- | -------------------------------------- | -------- | ---------- | -------------------------------------------------------------------------------------------------------------- | +| T1 | Malicious `.rules.ts` files | High | Medium | A rule file could attempt to access the filesystem, network, or execute arbitrary commands | +| T2 | Supply chain attack via dependencies | High | Low | A compromised dependency could inject malicious code into the CLI binary | +| T3 | Tampered binary during install/upgrade | High | Low | A man-in-the-middle attack could serve a modified binary | +| T4 | Credential theft | Medium | Low | An attacker with local access could attempt to extract the authentication token from the OS credential manager | +| T5 | Path traversal in rule context | Medium | Medium | A rule could attempt to read files outside the project directory | +| T6 | Denial of service via rules | Low | Medium | A rule could consume excessive resources (CPU, memory, time) | +| T7 | Injection via ADR content | Low | Low | Malformed ADR frontmatter could cause unexpected behavior during parsing | + +### 1.3 Threat Actors + +- **Untrusted contributors** submitting pull requests with malicious `.rules.ts` files (most likely) +- **Compromised upstream dependencies** in the npm/Bun ecosystem +- **Network attackers** intercepting binary downloads or plugin installations + +## 2. Trust Boundaries + +``` +┌──────────────────────────────────────────────────────────┐ +│ USER'S MACHINE │ +│ │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ ARCHGATE CLI PROCESS │ │ +│ │ │ │ +│ │ ┌─────────────────────────────────────────────┐ │ │ +│ │ │ RULE EXECUTION SANDBOX │ │ │ +│ │ │ │ │ │ +│ │ │ .rules.ts files execute here with: │ │ │ +│ │ │ - RuleContext API (read-only, path-scoped) │ │ │ +│ │ │ - 30-second timeout │ │ │ +│ │ │ - Static analysis pre-scan │ │ │ +│ │ │ - No fs/net/child_process/eval access │ │ │ +│ │ │ │ │ │ +│ │ └──────────────── BOUNDARY 1 ─────────────────┘ │ │ +│ │ │ │ +│ │ CLI core (commands, engine, helpers) │ │ +│ │ - Full Bun runtime access │ │ +│ │ - Reads/writes ~/.archgate/ (cache) │ │ +│ │ - Credentials via OS credential manager │ │ +│ │ - Reads .archgate/adrs/ (project ADRs) │ │ +│ │ │ │ +│ └──────────────────── BOUNDARY 2 ────────────────────┘ │ +│ │ +│ Project files (source code, configs) │ +│ - Read by rules via RuleContext │ +│ - Never modified by archgate check │ +│ │ +└────────────────────── BOUNDARY 3 ────────────────────────┘ + │ + ┌──────┴──────┐ + │ NETWORK │ + │ │ + │ GitHub Releases (binary downloads) + │ plugins.archgate.dev (plugin auth) + └─────────────┘ +``` + +**Boundary 1 — Rule Sandbox:** `.rules.ts` files are untrusted code. They execute within a restricted context that blocks dangerous APIs and scopes file access to the project root. + +**Boundary 2 — CLI Process:** The CLI itself runs with the user's permissions. It reads project files and manages its own cache directory (`~/.archgate/`). Authentication tokens are delegated to the OS credential manager. It does not require elevated privileges. + +**Boundary 3 — Network:** Network access is only used for binary downloads (install/upgrade), plugin installation (authenticated), and optional anonymized telemetry. No analytics services are contacted. Core functionality (`archgate check`) is fully offline. + +## 3. Secure Design Principles Applied + +### 3.1 Least Privilege + +- **Rule sandbox is read-only.** The `RuleContext` API exposes `readFile`, `readJSON`, `grep`, `grepFiles`, and `glob` — all read-only operations. Rules cannot write files, spawn processes, or access the network. +- **CI jobs use minimal permissions.** The documented CI configuration requests only `contents: read` — no secrets, deployment keys, or write permissions ([Security guide](https://cli.archgate.dev/guides/security/)). +- **Credentials are delegated to the OS.** Authentication tokens are stored in the operating system's credential manager (macOS Keychain, Windows Credential Manager, Linux secret service) — never written to disk as plain-text files. + +### 3.2 Defense in Depth + +Two independent layers protect against malicious rules: + +1. **Static analysis security scanner** — Before any `.rules.ts` file is executed, the CLI parses its AST and rejects files containing dangerous patterns: + - Imports of `node:fs`, `child_process`, `net`, `http`, `vm`, and other system modules + - Bun-specific APIs: `Bun.spawn()`, `Bun.write()`, `Bun.file()`, `Bun.$` + - Network access: `fetch()` + - Code generation: `eval()`, `new Function()` + - Obfuscation patterns: computed property access (`Bun[variable]`), `globalThis` assignment, dynamic `import()` + +2. **Runtime sandbox** — Even if a pattern bypasses the static scanner, the `RuleContext` API enforces path scoping (blocks `../`, absolute paths, and symlinks) and a 30-second timeout per rule. + +### 3.3 Input Validation + +- **ADR frontmatter** is validated using [Zod](https://zod.dev/) schemas (`src/formats/adr.ts`). Malformed YAML is rejected with structured error messages. +- **CLI arguments** are validated by Commander.js with strict type checking (`@commander-js/extra-typings`). +- **File paths** in the `RuleContext` API are validated against path traversal before any read operation. + +### 3.4 Fail-Safe Defaults + +- **Telemetry is opt-in.** The `ARCHGATE_TELEMETRY` environment variable must be explicitly set to enable it. CI templates set it to `"0"` (disabled). +- **Strict TypeScript.** The project compiles with `strict: true`, catching null/undefined errors at compile time. +- **Exit codes are meaningful.** `0` = success, `1` = violations found, `2` = internal error. CI pipelines fail on any non-zero exit. + +### 3.5 Minimal Attack Surface + +- **Minimal dependencies.** The project follows [ARCH-006 (Dependency Policy)](/.archgate/adrs/ARCH-006-dependency-policy.md): prefer Bun built-ins over third-party packages. All runtime dependencies are bundled into the compiled binary — the npm package has zero runtime `dependencies`. +- **No daemon or server mode.** The CLI runs as a short-lived process. The MCP server uses stdio transport (no network listener). +- **No shell execution.** The CLI never spawns shell commands. Git operations use `git ls-files` via Bun's process API with explicit arguments (no shell interpolation). + +## 4. Common Implementation Weaknesses Countered + +### 4.1 Injection Attacks + +| Vector | Countermeasure | +| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| Command injection | No shell execution. Process spawning uses explicit argument arrays, not string concatenation. | +| Path traversal | `RuleContext` rejects `../`, absolute paths, and symlinks before any file read. | +| YAML injection | ADR frontmatter is parsed by a YAML library and validated through Zod schemas. No `eval` or template interpolation on YAML content. | +| Regex denial of service (ReDoS) | User-provided patterns in `grep`/`grepFiles` are passed to Bun's native regex engine with the 30-second rule timeout as a backstop. | + +### 4.2 Supply Chain Risks + +| Risk | Countermeasure | +| -------------------------- | -------------------------------------------------------------------------------------------------------------------- | +| Compromised npm dependency | Minimal dependency tree. All dependencies are `devDependencies` bundled at build time. `bun.lock` pinned. | +| Tampered binary download | `archgate upgrade` verifies SHA256 checksums of downloaded binaries before extraction. Mismatches abort the upgrade. | +| Malicious GitHub Actions | All Actions in CI workflows use pinned commit SHAs (not floating tags). OpenSSF Scorecard runs weekly. | +| Typosquatting | The `archgate` npm package name is registered and controlled by the project. | + +### 4.3 Information Disclosure + +| Risk | Countermeasure | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Credential leakage | Authentication tokens are stored in the OS credential manager (macOS Keychain, Windows Credential Manager, Linux secret service) — never written to disk as plain text. Tokens are never logged. Plugin install passes credentials via authenticated git URLs (not command-line arguments visible in `ps`). | +| Source code exposure | Rules are read-only. `archgate check` output contains only violation messages (file paths and line numbers), not file contents. | +| Error messages | Error output uses `logError()` (ARCH-002) which writes structured messages to stderr. Stack traces are only shown with `--verbose`. | + +### 4.4 Availability + +| Risk | Countermeasure | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| Runaway rules | 30-second wall-clock timeout per rule. Rules from different ADRs run in parallel but share no mutable state. | +| Large file processing | `RuleContext.readFile()` operates on individual files within the project scope. Glob patterns respect `.gitignore`. | +| Binary download failures | The npm thin shim retries downloads and falls back to cached binaries in `~/.archgate/bin/`. | + +## 5. Verification + +### 5.1 Automated Verification + +- **CI pipeline** runs on every pull request: lint (Oxlint), typecheck (tsc --build), format check (Oxfmt), test suite (Bun test), ADR compliance check (`archgate check`), and build verification. +- **OpenSSF Scorecard** runs weekly via GitHub Actions, publishing results to the GitHub Security tab. +- **GitHub Security Advisories** are enabled for responsible vulnerability disclosure. +- **Pinned dependencies** — all GitHub Actions use commit SHA pins, not mutable tags. + +### 5.2 Manual Verification + +- All pull requests require review before merging. +- `.rules.ts` file changes are treated as security-sensitive in code review. +- The security guide at [cli.archgate.dev/guides/security](https://cli.archgate.dev/guides/security/) documents the trust model for contributors and users. + +## 6. References + +- [SECURITY.md](SECURITY.md) — Vulnerability reporting policy +- [Security Guide](https://cli.archgate.dev/guides/security/) — Full trust model and CI best practices +- [OpenSSF Scorecard](https://securityscorecards.dev/viewer/?uri=github.com/archgate/cli) — Automated security analysis +- [ARCH-006: Dependency Policy](/.archgate/adrs/ARCH-006-dependency-policy.md) — Minimal dependency governance +- [CII Best Practices Badge](https://www.bestpractices.dev/projects/9981) — OpenSSF Best Practices compliance diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e5fba9f0..c0d9b562 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -156,9 +156,51 @@ git push origin feature/your-feature-name 7. **Submit a pull request** to the main repository +## Developer Certificate of Origin (DCO) + +This project uses the [Developer Certificate of Origin (DCO)](https://developercertificate.org/) to ensure that contributors have the right to submit their contributions under the project's [Apache 2.0 license](LICENSE.md). + +**All commits must include a `Signed-off-by` line** with your real name and email address, certifying that you have the right to submit the work under the project's license: + +``` +Signed-off-by: Your Name +``` + +### How to sign off + +Add the `-s` (or `--signoff`) flag to your `git commit` command: + +```bash +git commit -s -m "feat: your feature description" +``` + +This automatically appends the `Signed-off-by` line using the name and email from your git configuration. To set these: + +```bash +git config user.name "Your Name" +git config user.email "your.email@example.com" +``` + +### Fixing unsigned commits + +If you forget to sign off, you can amend your most recent commit: + +```bash +git commit --amend -s --no-edit +``` + +For multiple unsigned commits, use an interactive rebase: + +```bash +git rebase --signoff HEAD~N # where N is the number of commits to sign +``` + +**Pull requests with unsigned commits will fail the DCO check in CI and cannot be merged.** + ## Guidelines - **Read the ADRs first** — all code changes must comply with the project's Architecture Decision Records +- **Sign your commits** — all commits must include a `Signed-off-by` line (see DCO section above) - Follow the existing code style and conventions - Write clear, descriptive commit messages using [Conventional Commits](https://www.conventionalcommits.org/) - Add tests for new functionality when applicable diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 00000000..175f245d --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,56 @@ +# Maintainers + +This document lists the maintainers of the Archgate CLI project and describes the access continuity plan to ensure the project can continue with minimal interruption if any single contributor becomes unavailable. + +## Current Maintainers + +| Name | GitHub | Role | Scope | +| ------------- | ------------------------------------------------ | --------------- | --------------------------------------------------------- | +| Rhuan Barreto | [@rhuanbarreto](https://github.com/rhuanbarreto) | Lead Maintainer | Full project access (code, releases, infrastructure, DNS) | + +## Becoming a Maintainer + +We welcome new maintainers. To be considered, a contributor should: + +1. Have a history of meaningful contributions (code, docs, reviews, or community support) +2. Demonstrate understanding of the project's ADR governance model +3. Be nominated by an existing maintainer +4. Agree to follow the project's [Code of Conduct](CODE_OF_CONDUCT.md) and [Contributing Guidelines](CONTRIBUTING.md) + +If you are interested in becoming a maintainer, open a discussion in [GitHub Discussions](https://github.com/archgate/cli/discussions) or reach out to an existing maintainer. + +## Access Continuity Plan + +The project maintains the following access continuity measures to ensure it can create and close issues, accept proposed changes, and release new versions within a week of any single contributor becoming unavailable: + +### Critical Access Points + +| Resource | Access Level | Backup Mechanism | +| ---------------------------------------------------- | --------------- | ---------------------------------------------------- | +| GitHub repository (admin) | Lead Maintainer | GitHub organization ownership with recovery contacts | +| npm publishing (`archgate` package) | Lead Maintainer | npm organization with granular access tokens | +| Domain (`archgate.dev`, `cli.archgate.dev`) | Lead Maintainer | Domain registrar account with recovery email | +| Cloudflare Pages (docs hosting) | Lead Maintainer | Cloudflare account with recovery mechanisms | +| Plugin distribution service (`plugins.archgate.dev`) | Lead Maintainer | Infrastructure documented in internal runbooks | +| GitHub Actions secrets | Lead Maintainer | Documented in internal access registry | + +### Continuity Measures + +1. **GitHub Organization:** The `archgate` GitHub organization has recovery contacts configured. Organization ownership can be transferred through GitHub's account recovery process. + +2. **npm Access:** The `archgate` npm package is published under an npm organization, enabling additional maintainers to be granted publish access without sharing individual credentials. + +3. **Release Process:** The release workflow (`.github/workflows/release.yml` and `.github/workflows/release-binaries.yml`) is fully automated via GitHub Actions. Any maintainer with write access can trigger a release by pushing a version tag. + +4. **Documentation:** The documentation site builds and deploys automatically from the `main` branch. No manual intervention is required for docs updates. + +5. **Secrets and Credentials:** All project secrets (API keys, tokens, signing keys) are stored in GitHub Actions secrets and a secure credential vault. Access procedures are documented internally and can be transferred to a successor maintainer. + +6. **Bus Factor Improvement:** The project is actively working to onboard additional maintainers to increase the bus factor above 1. This includes: + - Comprehensive documentation of all processes in this file and [CONTRIBUTING.md](CONTRIBUTING.md) + - Automated CI/CD pipelines that require minimal manual intervention + - Self-governance via ADRs that document architectural decisions independently of any individual + +### Emergency Contact + +For urgent access or continuity concerns, contact: **hello@archgate.dev** diff --git a/README.md b/README.md index f814063a..bf7af08e 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,7 @@ [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE.md) [![Release](https://github.com/archgate/cli/actions/workflows/release.yml/badge.svg)](https://github.com/archgate/cli/actions/workflows/release.yml) [![Docs](https://img.shields.io/badge/docs-cli.archgate.dev-blue)](https://cli.archgate.dev) +[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/12659/badge)](https://www.bestpractices.dev/projects/12659) diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 00000000..44928969 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,74 @@ +# Archgate CLI Roadmap + +> **Last updated:** April 2026 | **Current version:** v0.30.1 + +This document describes what Archgate intends to build, improve, and explicitly _not_ pursue over the next 12 months. It is reviewed quarterly. + +## Vision + +Archgate becomes the standard governance layer for AI-assisted development. ADRs are the universal format for expressing architectural decisions, and Archgate enforces them automatically — across AI tools, CI systems, and teams. + +## What's Done (Phases 0–2.5) + +These phases are complete and stable: + +- **ADR format & lifecycle** — create, list, show, update ADRs with YAML frontmatter and companion `.rules.ts` files +- **Check engine** — fast, deterministic ADR compliance validation (`archgate check`) with CI annotations, `--staged` support, and JSON output +- **AI integration** — MCP server exposing tools and resources for AI agents to consume ADR context +- **Editor plugins** — Claude Code, VS Code, Cursor, Copilot CLI, and opencode integrations +- **Documentation site** — [cli.archgate.dev](https://cli.archgate.dev) with i18n (English + Brazilian Portuguese) +- **Binary distribution** — macOS ARM, Linux x64, Windows x64 via GitHub Releases with npm thin shim, install script, and proto plugin +- **GitHub Actions** — `archgate/check-action@v1` and `archgate/setup-action@v1` published +- **Self-governance** — the CLI dogfoods 17+ ADRs with executable rules + +## In Progress: Ecosystem Growth (Phase 3) + +**Timeline:** Q2 2026 – Q1 2027 + +### ADR Marketplace + +- Community-contributed ADR repository at [`archgate/awesome-adrs`](https://github.com/archgate/awesome-adrs) +- `archgate adr import ` command to import ADRs from the marketplace or any git URL +- Curated ADR sets: TypeScript, Testing, API Design (with companion `.rules.ts` files) +- Contribution guidelines and review process for community ADRs + +### Pre-commit Hook Integration + +- Package `archgate check --staged` for husky, lefthook, and pre-commit ecosystems +- Lower the adoption barrier for teams with existing git hook workflows +- Documentation and examples for each hook system + +### Starter ADR Sets + +- **TypeScript** — strict tsconfig rules, no `any`, naming conventions +- **Testing** — test file co-location, coverage thresholds, fixture patterns +- **API Design** — REST naming, error response format, OpenAPI requirements + +### Documentation & Community + +- Expand rule examples library (target: 30+ patterns) +- Contributor onboarding guide +- Case studies from early adopters + +## What We Will NOT Do + +These are explicit non-goals for the foreseeable future: + +- **Become a linter.** Archgate orchestrates enforcement (including linting) but will not compete with ESLint, Biome, or Oxlint on code style rules. +- **Lock into a single AI tool.** The MCP server and ADR format are tool-agnostic. We will not build features that only work with one AI vendor. +- **Dictate technology stacks.** Archgate governs how you build, not what you build with. ADRs are stack-agnostic by design. +- **Build a code generation tool.** Archgate governs AI-generated code — it does not generate code itself. +- **Support pre-1.0 API stability guarantees.** The ADR format and Rule API may have breaking changes before 1.0. We version clearly and document migrations. + +## Release Cadence + +- **Patch releases** (bug fixes, docs): as needed +- **Minor releases** (features, non-breaking): roughly bi-weekly +- **Major milestones** are tracked in [GitHub Issues](https://github.com/archgate/cli/issues) and this roadmap + +## How to Influence the Roadmap + +- **Feature requests:** [Open an issue](https://github.com/archgate/cli/issues/new) with the `enhancement` label +- **Bug reports:** [Open an issue](https://github.com/archgate/cli/issues/new) with the `bug` label +- **Discussions:** [GitHub Discussions](https://github.com/archgate/cli/discussions) for broader ideas and feedback +- **Contributions:** See [CONTRIBUTING.md](CONTRIBUTING.md) for how to get involved diff --git a/docs/public/llms-full.txt b/docs/public/llms-full.txt index e7bf8e6b..6ae258d3 100644 --- a/docs/public/llms-full.txt +++ b/docs/public/llms-full.txt @@ -1219,7 +1219,7 @@ Authenticate with your GitHub account to obtain a plugin token: archgate login ``` -This starts a GitHub Device Flow. The CLI displays a one-time code and URL -- open the URL in your browser, enter the code, and authorize. Once complete, credentials are stored in `~/.archgate/credentials`. +This starts a GitHub Device Flow. The CLI displays a one-time code and URL -- open the URL in your browser, enter the code, and authorize. Once complete, credentials are stored securely in your OS credential manager via `git credential approve`. ### 2. Initialize your project with the plugin @@ -1355,7 +1355,7 @@ Authenticate with your GitHub account to obtain a plugin token: archgate login ``` -This starts a GitHub Device Flow. The CLI displays a one-time code and URL -- open the URL in your browser, enter the code, and authorize. Once complete, credentials are stored in `~/.archgate/credentials`. +This starts a GitHub Device Flow. The CLI displays a one-time code and URL -- open the URL in your browser, enter the code, and authorize. Once complete, credentials are stored securely in your OS credential manager via `git credential approve`. ### 2. Initialize your project with the plugin @@ -1397,7 +1397,7 @@ If the `copilot` CLI is not found during `archgate init`, you can install the pl copilot plugin install https://:@plugins.archgate.dev/archgate.git ``` -You can find your authenticated URL by running `archgate login` and checking `~/.archgate/credentials`. +You can find your authenticated URL by running `archgate plugin url copilot`. ## What the plugin provides @@ -1984,11 +1984,10 @@ When cloning or forking a repository that uses Archgate, the security scanner au ### Credentials -The `archgate login` command stores an authentication token at `~/.archgate/credentials` with owner-only file permissions (`0600` on Unix). This token is used for plugin installation and is never sent to third parties beyond the Archgate plugins service. +The `archgate login` command stores your authentication token in the operating system's credential manager (macOS Keychain, Windows Credential Manager, or Linux libsecret) via `git credential approve`. No credentials are written to disk as plain-text files. The token is used for plugin installation and is never sent to third parties beyond the Archgate plugins service. -- Do not commit `~/.archgate/credentials` to version control. - Do not share the token in CI logs. Plugin installation commands pass credentials via authenticated URLs to git, which may appear in process listings. Avoid running `archgate plugin install` with verbose logging in shared CI environments. -- To revoke access, run `archgate logout` or delete `~/.archgate/credentials`. +- To revoke access, run `archgate login logout`. ### Self-update integrity @@ -2026,7 +2025,7 @@ Authenticate with your GitHub account to obtain a plugin token: archgate login ``` -This starts a GitHub Device Flow. The CLI displays a one-time code and URL -- open the URL in your browser, enter the code, and authorize. Once complete, credentials are stored in `~/.archgate/credentials`. +This starts a GitHub Device Flow. The CLI displays a one-time code and URL -- open the URL in your browser, enter the code, and authorize. Once complete, credentials are stored securely in your OS credential manager via `git credential approve`. ### 2. Initialize your project with the plugin @@ -2089,7 +2088,7 @@ The user-level marketplace setting (added to your `settings.json`): If you prefer not to let the CLI modify your user settings, you can set things up manually: -**Marketplace URL:** Open VS Code's user settings JSON (`Ctrl+Shift+P` → "Preferences: Open User Settings (JSON)") and add the `chat.plugins.marketplaces` entry shown above. You can find your authenticated URL by running `archgate login` and checking `~/.archgate/credentials`. +**Marketplace URL:** Open VS Code's user settings JSON (`Ctrl+Shift+P` → "Preferences: Open User Settings (JSON)") and add the `chat.plugins.marketplaces` entry shown above. You can find your authenticated URL by running `archgate plugin url vscode`. **Extension:** Download and install the `.vsix` file directly: @@ -2099,7 +2098,7 @@ code --install-extension archgate.vsix rm archgate.vsix ``` -Replace `` with your archgate token from `~/.archgate/credentials`. +Replace `` with your archgate token (retrieve it via `archgate plugin url vscode`). ## What the plugin provides @@ -3610,7 +3609,7 @@ Authenticate with GitHub to access Archgate editor plugins. If you are not regis archgate login ``` -Starts a GitHub Device Flow (OAuth). The CLI displays a one-time code and a URL. Open the URL in your browser, enter the code, and authorize the Archgate GitHub OAuth App. Once authorized, the CLI exchanges your GitHub identity for an Archgate plugin token and stores it securely in your OS credential manager (macOS Keychain, Windows Credential Manager, or Linux libsecret) via `git credential approve`. Non-sensitive metadata (username, date) is saved to `~/.archgate/credentials`. +Starts a GitHub Device Flow (OAuth). The CLI displays a one-time code and a URL. Open the URL in your browser, enter the code, and authorize the Archgate GitHub OAuth App. Once authorized, the CLI exchanges your GitHub identity for an Archgate plugin token and stores it securely in your OS credential manager (macOS Keychain, Windows Credential Manager, or Linux libsecret) via `git credential approve`. No credentials are written to disk as plain-text files. If your GitHub account is not yet registered, the CLI prompts for your email, preferred editor, and use case, then signs you up automatically. diff --git a/docs/src/content/docs/guides/claude-code-plugin.mdx b/docs/src/content/docs/guides/claude-code-plugin.mdx index 02b03641..28ed70e0 100644 --- a/docs/src/content/docs/guides/claude-code-plugin.mdx +++ b/docs/src/content/docs/guides/claude-code-plugin.mdx @@ -40,7 +40,7 @@ Authenticate with your GitHub account to obtain a plugin token: archgate login ``` -This starts a GitHub Device Flow. The CLI displays a one-time code and URL -- open the URL in your browser, enter the code, and authorize. Once complete, credentials are stored in `~/.archgate/credentials`. +This starts a GitHub Device Flow. The CLI displays a one-time code and URL -- open the URL in your browser, enter the code, and authorize. Once complete, credentials are stored securely in your OS credential manager via `git credential approve`. ### 2. Initialize your project with the plugin diff --git a/docs/src/content/docs/guides/copilot-cli-plugin.mdx b/docs/src/content/docs/guides/copilot-cli-plugin.mdx index 31d6f207..932e62da 100644 --- a/docs/src/content/docs/guides/copilot-cli-plugin.mdx +++ b/docs/src/content/docs/guides/copilot-cli-plugin.mdx @@ -23,7 +23,7 @@ Authenticate with your GitHub account to obtain a plugin token: archgate login ``` -This starts a GitHub Device Flow. The CLI displays a one-time code and URL -- open the URL in your browser, enter the code, and authorize. Once complete, credentials are stored in `~/.archgate/credentials`. +This starts a GitHub Device Flow. The CLI displays a one-time code and URL -- open the URL in your browser, enter the code, and authorize. Once complete, credentials are stored securely in your OS credential manager via `git credential approve`. ### 2. Initialize your project with the plugin @@ -65,7 +65,7 @@ If the `copilot` CLI is not found during `archgate init`, you can install the pl copilot plugin install https://:@plugins.archgate.dev/archgate.git ``` -You can find your authenticated URL by running `archgate login` and checking `~/.archgate/credentials`. +You can find your authenticated URL by running `archgate plugin url copilot`. ## What the plugin provides diff --git a/docs/src/content/docs/guides/security.mdx b/docs/src/content/docs/guides/security.mdx index f98fff0e..1b6f8870 100644 --- a/docs/src/content/docs/guides/security.mdx +++ b/docs/src/content/docs/guides/security.mdx @@ -130,11 +130,10 @@ When cloning or forking a repository that uses Archgate, the security scanner au ### Credentials -The `archgate login` command stores an authentication token at `~/.archgate/credentials` with owner-only file permissions (`0600` on Unix). This token is used for plugin installation and is never sent to third parties beyond the Archgate plugins service. +The `archgate login` command stores your authentication token in the operating system's credential manager (macOS Keychain, Windows Credential Manager, or Linux libsecret) via `git credential approve`. No credentials are written to disk as plain-text files. The token is used for plugin installation and is never sent to third parties beyond the Archgate plugins service. -- Do not commit `~/.archgate/credentials` to version control. - Do not share the token in CI logs. Plugin installation commands pass credentials via authenticated URLs to git, which may appear in process listings. Avoid running `archgate plugin install` with verbose logging in shared CI environments. -- To revoke access, run `archgate logout` or delete `~/.archgate/credentials`. +- To revoke access, run `archgate login logout`. ### Self-update integrity diff --git a/docs/src/content/docs/guides/vscode-plugin.mdx b/docs/src/content/docs/guides/vscode-plugin.mdx index 62e10ca1..13f1035a 100644 --- a/docs/src/content/docs/guides/vscode-plugin.mdx +++ b/docs/src/content/docs/guides/vscode-plugin.mdx @@ -29,7 +29,7 @@ Authenticate with your GitHub account to obtain a plugin token: archgate login ``` -This starts a GitHub Device Flow. The CLI displays a one-time code and URL -- open the URL in your browser, enter the code, and authorize. Once complete, credentials are stored in `~/.archgate/credentials`. +This starts a GitHub Device Flow. The CLI displays a one-time code and URL -- open the URL in your browser, enter the code, and authorize. Once complete, credentials are stored securely in your OS credential manager via `git credential approve`. ### 2. Initialize your project with the plugin @@ -92,7 +92,7 @@ The user-level marketplace setting (added to your `settings.json`): If you prefer not to let the CLI modify your user settings, you can set things up manually: -**Marketplace URL:** Open VS Code's user settings JSON (`Ctrl+Shift+P` → "Preferences: Open User Settings (JSON)") and add the `chat.plugins.marketplaces` entry shown above. You can find your authenticated URL by running `archgate login` and checking `~/.archgate/credentials`. +**Marketplace URL:** Open VS Code's user settings JSON (`Ctrl+Shift+P` → "Preferences: Open User Settings (JSON)") and add the `chat.plugins.marketplaces` entry shown above. You can find your authenticated URL by running `archgate plugin url vscode`. **Extension:** Download and install the `.vsix` file directly: @@ -102,7 +102,7 @@ code --install-extension archgate.vsix rm archgate.vsix ``` -Replace `` with your archgate token from `~/.archgate/credentials`. +Replace `` with your archgate token (retrieve it via `archgate plugin url vscode`). ## What the plugin provides diff --git a/docs/src/content/docs/pt-br/guides/claude-code-plugin.mdx b/docs/src/content/docs/pt-br/guides/claude-code-plugin.mdx index e7b252cc..3d3a1753 100644 --- a/docs/src/content/docs/pt-br/guides/claude-code-plugin.mdx +++ b/docs/src/content/docs/pt-br/guides/claude-code-plugin.mdx @@ -40,7 +40,7 @@ Autentique-se com sua conta do GitHub para obter um token do plugin: archgate login ``` -Isso inicia um GitHub Device Flow. O CLI exibe um código único e uma URL -- abra a URL no seu navegador, insira o código e autorize. Ao concluir, as credenciais são armazenadas em `~/.archgate/credentials`. +Isso inicia um GitHub Device Flow. O CLI exibe um código único e uma URL -- abra a URL no seu navegador, insira o código e autorize. Ao concluir, as credenciais são armazenadas de forma segura no gerenciador de credenciais do sistema operacional via `git credential approve`. ### 2. Inicialize seu projeto com o plugin diff --git a/docs/src/content/docs/pt-br/guides/copilot-cli-plugin.mdx b/docs/src/content/docs/pt-br/guides/copilot-cli-plugin.mdx index beb7013b..5bb7d33d 100644 --- a/docs/src/content/docs/pt-br/guides/copilot-cli-plugin.mdx +++ b/docs/src/content/docs/pt-br/guides/copilot-cli-plugin.mdx @@ -23,7 +23,7 @@ Autentique-se com sua conta do GitHub para obter um token do plugin: archgate login ``` -Isso inicia um GitHub Device Flow. O CLI exibe um código único e uma URL -- abra a URL no seu navegador, insira o código e autorize. Ao concluir, as credenciais são armazenadas em `~/.archgate/credentials`. +Isso inicia um GitHub Device Flow. O CLI exibe um código único e uma URL -- abra a URL no seu navegador, insira o código e autorize. Ao concluir, as credenciais são armazenadas de forma segura no gerenciador de credenciais do sistema operacional via `git credential approve`. ### 2. Inicialize seu projeto com o plugin @@ -65,7 +65,7 @@ Se o CLI `copilot` não for encontrado durante `archgate init`, você pode insta copilot plugin install https://:@plugins.archgate.dev/archgate.git ``` -Você pode encontrar sua URL autenticada executando `archgate login` e verificando `~/.archgate/credentials`. +Você pode encontrar sua URL autenticada executando `archgate plugin url copilot`. ## O que o plugin oferece diff --git a/docs/src/content/docs/pt-br/guides/security.mdx b/docs/src/content/docs/pt-br/guides/security.mdx index 239e3b70..9d80ea17 100644 --- a/docs/src/content/docs/pt-br/guides/security.mdx +++ b/docs/src/content/docs/pt-br/guides/security.mdx @@ -130,11 +130,10 @@ Ao clonar ou fazer fork de um repositório que usa Archgate, o scanner de segura ### Credenciais -O comando `archgate login` armazena um token de autenticação em `~/.archgate/credentials` com permissões de arquivo somente para o proprietário (`0600` em Unix). Este token é usado para instalação de plugins e nunca é enviado a terceiros além do serviço de plugins do Archgate. +O comando `archgate login` armazena seu token de autenticação no gerenciador de credenciais do sistema operacional (macOS Keychain, Windows Credential Manager ou libsecret no Linux) via `git credential approve`. Nenhuma credencial é gravada em disco como arquivo de texto. O token é usado para instalação de plugins e nunca é enviado a terceiros além do serviço de plugins do Archgate. -- Não commite `~/.archgate/credentials` no controle de versão. - Não exponha o token em logs de CI. Comandos de instalação de plugins passam credenciais via URLs autenticadas para o git, que podem aparecer em listagens de processos. Evite rodar `archgate plugin install` com logging verbose em ambientes de CI compartilhados. -- Para revogar acesso, rode `archgate logout` ou delete `~/.archgate/credentials`. +- Para revogar acesso, rode `archgate login logout`. ### Integridade da atualização diff --git a/docs/src/content/docs/pt-br/guides/vscode-plugin.mdx b/docs/src/content/docs/pt-br/guides/vscode-plugin.mdx index a39a701f..0c6de1dd 100644 --- a/docs/src/content/docs/pt-br/guides/vscode-plugin.mdx +++ b/docs/src/content/docs/pt-br/guides/vscode-plugin.mdx @@ -29,7 +29,7 @@ Autentique-se com sua conta do GitHub para obter um token do plugin: archgate login ``` -Isso inicia um GitHub Device Flow. O CLI exibe um código único e uma URL -- abra a URL no seu navegador, insira o código e autorize. Ao concluir, as credenciais são armazenadas em `~/.archgate/credentials`. +Isso inicia um GitHub Device Flow. O CLI exibe um código único e uma URL -- abra a URL no seu navegador, insira o código e autorize. Ao concluir, as credenciais são armazenadas de forma segura no gerenciador de credenciais do sistema operacional via `git credential approve`. ### 2. Inicialize seu projeto com o plugin @@ -92,7 +92,7 @@ A configuração do marketplace no nível de usuário (adicionada ao seu `settin Se preferir não deixar o CLI modificar suas configurações, você pode configurar manualmente: -**URL do marketplace:** Abra o JSON de configurações de usuário do VS Code (`Ctrl+Shift+P` → "Preferences: Open User Settings (JSON)") e adicione a entrada `chat.plugins.marketplaces` mostrada acima. Você pode encontrar sua URL autenticada executando `archgate login` e verificando `~/.archgate/credentials`. +**URL do marketplace:** Abra o JSON de configurações de usuário do VS Code (`Ctrl+Shift+P` → "Preferences: Open User Settings (JSON)") e adicione a entrada `chat.plugins.marketplaces` mostrada acima. Você pode encontrar sua URL autenticada executando `archgate plugin url vscode`. **Extensão:** Baixe e instale o arquivo `.vsix` diretamente: @@ -102,7 +102,7 @@ code --install-extension archgate.vsix rm archgate.vsix ``` -Substitua `` pelo seu token archgate de `~/.archgate/credentials`. +Substitua `` pelo seu token archgate (obtenha-o via `archgate plugin url vscode`). ## O que o plugin oferece diff --git a/docs/src/content/docs/pt-br/reference/cli/login.mdx b/docs/src/content/docs/pt-br/reference/cli/login.mdx index 32faa0ca..b5301857 100644 --- a/docs/src/content/docs/pt-br/reference/cli/login.mdx +++ b/docs/src/content/docs/pt-br/reference/cli/login.mdx @@ -9,7 +9,7 @@ Autentique-se com o GitHub para acessar os plugins de editor do Archgate. Se voc archgate login ``` -Inicia um GitHub Device Flow (OAuth). A CLI exibe um código de uso único e uma URL. Abra a URL no seu navegador, insira o código e autorize o Archgate GitHub OAuth App. Após a autorização, a CLI troca sua identidade do GitHub por um token de plugin do Archgate e armazena ambos em `~/.archgate/credentials`. +Inicia um GitHub Device Flow (OAuth). A CLI exibe um código de uso único e uma URL. Abra a URL no seu navegador, insira o código e autorize o Archgate GitHub OAuth App. Após a autorização, a CLI troca sua identidade do GitHub por um token de plugin do Archgate e armazena-o de forma segura no gerenciador de credenciais do sistema operacional (macOS Keychain, Windows Credential Manager ou libsecret no Linux) via `git credential approve`. Nenhuma credencial é gravada em disco como arquivo de texto. Se sua conta do GitHub ainda não estiver cadastrada, a CLI solicita seu email, editor preferido e caso de uso, e realiza o cadastro automaticamente. diff --git a/docs/src/content/docs/reference/cli/login.mdx b/docs/src/content/docs/reference/cli/login.mdx index fcaef0e2..b04caae0 100644 --- a/docs/src/content/docs/reference/cli/login.mdx +++ b/docs/src/content/docs/reference/cli/login.mdx @@ -9,7 +9,7 @@ Authenticate with GitHub to access Archgate editor plugins. If you are not regis archgate login ``` -Starts a GitHub Device Flow (OAuth). The CLI displays a one-time code and a URL. Open the URL in your browser, enter the code, and authorize the Archgate GitHub OAuth App. Once authorized, the CLI exchanges your GitHub identity for an Archgate plugin token and stores it securely in your OS credential manager (macOS Keychain, Windows Credential Manager, or Linux libsecret) via `git credential approve`. Non-sensitive metadata (username, date) is saved to `~/.archgate/credentials`. +Starts a GitHub Device Flow (OAuth). The CLI displays a one-time code and a URL. Open the URL in your browser, enter the code, and authorize the Archgate GitHub OAuth App. Once authorized, the CLI exchanges your GitHub identity for an Archgate plugin token and stores it securely in your OS credential manager (macOS Keychain, Windows Credential Manager, or Linux libsecret) via `git credential approve`. No credentials are written to disk as plain-text files. If your GitHub account is not yet registered, the CLI prompts for your email, preferred editor, and use case, then signs you up automatically.