@getaegis/cli 0.8.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Samuel Warren
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,604 @@
+# Aegis
+
+**Credential isolation for AI agents.**
+
+Aegis sits between your AI agent and the APIs it calls. The agent never sees, stores, or transmits real credentials — Aegis injects them at the network boundary.
+
+```
+┌──────────┐       ┌────────────────────────────┐       ┌──────────────┐
+│ AI Agent │──────▶│         Aegis Gate         │──────▶│  Slack API   │
+│          │       │  localhost:3100/slack/...  │       │              │
+│ (no keys)│◀──────│  inject creds + audit log  │◀──────│ api.slack.com│
+└──────────┘       └────────────────────────────┘       └──────────────┘
+                          │            │
+                   ┌──────┘            └──────┐
+              ┌────▼────┐           ┌─────────▼──┐
+              │  Vault  │           │   Ledger   │
+              │ AES-256 │           │  Audit Log │
+              │ encrypt │           │   SQLite   │
+              └─────────┘           └────────────┘
+```
+
+## Why?
+
+AI agents (Claude, GPT, Cursor, custom bots) increasingly need to call APIs — Slack, GitHub, databases, internal tools. The current pattern is dangerous:
+
+1. **Agents see raw API keys** — one prompt injection exfiltrates them
+2. **No domain guard** — a compromised agent can send your Slack token to `evil.com`
+3. **No audit trail** — you can't see what an agent did with your credentials
+4. **No access control** — every agent can use every credential
+
+Aegis solves all four. Your agent makes HTTP calls through a local proxy. Aegis handles authentication, enforces domain restrictions, and logs everything.
+
+## Prerequisites
+
+- **Node.js ≥ 20** — check with `node -v`
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g @getaegis/cli
+
+# Initialize — generates master key, config file, and encrypted vault
+aegis init --write-secrets
+```
+
+`aegis init` prints a master key. Without `--write-secrets`, you must export it yourself:
+
+```bash
+export AEGIS_MASTER_KEY=<key from init>
+```
+
+With `--write-secrets`, the key is saved to `aegis.config.yaml` automatically (convenient for local dev, not recommended for production).
+
+```bash
+# Add a credential
+aegis vault add \
+  --name slack-bot \
+  --service slack \
+  --secret "xoxb-your-token-here" \
+  --domains api.slack.com
+
+# Start the proxy
+aegis gate
+```
+
+Your agent now calls `http://localhost:3100/slack/api/chat.postMessage` — Aegis injects the Bearer token and forwards to `https://api.slack.com`. The agent never sees the token. The request is logged.
+
+```bash
+# Verify it works
+curl http://localhost:3100/slack/api/auth.test \
+  -H "X-Target-Host: api.slack.com"
+```
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Encrypted Vault** | AES-256-GCM encrypted credential storage with PBKDF2 key derivation |
+| **HTTP Proxy (Gate)** | Transparent credential injection — agent hits `localhost:3100/{service}/path` |
+| **Domain Guard** | Every outbound request checked against credential allowlists. No bypass. |
+| **Audit Ledger** | Every request (allowed and blocked) logged to SQLite with full context |
+| **Agent Identity** | Per-agent tokens, credential scoping, and rate limits |
+| **Policy Engine** | Declarative YAML policies — method, path, rate-limit, time-of-day restrictions |
+| **Body Inspector** | Outbound request bodies scanned for credential-like patterns |
+| **MCP Server** | Native Model Context Protocol integration for Claude, Cursor, VS Code |
+| **Web Dashboard** | Real-time monitoring UI with WebSocket live feed |
+| **Prometheus Metrics** | `/_aegis/metrics` endpoint for Grafana dashboards |
+| **Webhook Alerts** | HMAC-signed notifications for blocked requests, expiring credentials |
+| **RBAC** | Admin, operator, viewer roles with 16 granular permissions |
+| **Multi-Vault** | Separate vaults for dev/staging/prod with isolated encryption keys |
+| **Shamir's Secret Sharing** | M-of-N key splitting for team master key management |
+| **TLS Support** | Optional HTTPS on Gate with cert/key configuration |
+| **Configuration File** | `aegis.config.yaml` with env var overrides and CLI flag overrides |
+
+## MCP Integration
+
+Aegis is a first-class [MCP](https://modelcontextprotocol.io) server. Any MCP-compatible AI agent (Claude Desktop, Cursor, VS Code Copilot) can use Aegis natively — no HTTP calls needed.
+
+```bash
+# Generate config for your AI host
+aegis mcp config claude   # Claude Desktop
+aegis mcp config cursor   # Cursor
+aegis mcp config vscode   # VS Code
+```
+
+Copy the printed JSON into your AI host's MCP config file. The MCP server exposes three tools:
+
+| Tool | Description |
+|------|-------------|
+| `aegis_proxy_request` | Make an authenticated API call (provide service + path, Aegis injects credentials) |
+| `aegis_list_services` | List available services (names only, never secrets) |
+| `aegis_health` | Check Aegis status |
+
+The MCP server replicates the full Gate security pipeline: domain guard, agent auth, body inspection, rate limiting, audit logging.
+
+## Agent Identity & Scoping
+
+Without agent auth, any process on localhost can use any credential. Enable agent auth to restrict access:
+
+```bash
+# Register an agent — token is printed once, save it
+aegis agent add --name "research-bot"
+
+# Grant access to specific credentials only
+aegis agent grant --agent "research-bot" --credential "slack-bot"
+
+# Set per-agent rate limits
+aegis agent set-rate-limit --agent "research-bot" --limit 50/min
+
+# Start Gate with agent auth required
+aegis gate --require-agent-auth
+
+# Agent must include its token in every request
+curl http://localhost:3100/slack/api/auth.test \
+  -H "X-Target-Host: api.slack.com" \
+  -H "X-Aegis-Agent: aegis_a1b2c3d4..."
+```
+
+Tokens are SHA-256 hashed for storage — they cannot be recovered, only regenerated:
+
+```bash
+aegis agent regenerate --name "research-bot"
+# Old token stops working immediately. New token printed once.
+```
+
+## Policy Engine
+
+Declarative YAML policies control what each agent can do:
+
+```yaml
+# policies/research-bot.yaml
+agent: research-bot
+rules:
+  - service: slack
+    methods: [GET]
+    paths:
+      - /api/conversations.*
+      - /api/users.*
+    rate_limit: 100/hour
+    time_window:
+      start: "09:00"
+      end: "18:00"
+      timezone: "UTC"
+  - service: github
+    methods: [GET, POST]
+    paths:
+      - /repos/myorg/.*
+    rate_limit: 200/hour
+```
+
+```bash
+# Validate policies without starting Gate
+aegis policy validate --policies-dir ./policies
+
+# Dry-run: see what would be allowed/blocked without enforcing
+aegis gate --policies-dir ./policies --policy-mode dry-run
+
+# Enforce policies
+aegis gate --policies-dir ./policies --policy-mode enforce
+```
+
+## Credential Options
+
+When adding a credential, you can configure TTL, scopes, rate limits, and body inspection:
+
+```bash
+aegis vault add \
+  --name github-bot \
+  --service github \
+  --secret "ghp_xxxxxxxxxxxxxxxxxxxx" \
+  --domains api.github.com \
+  --auth-type bearer \
+  --scopes read,write \
+  --ttl 90 \
+  --rate-limit 100/min \
+  --body-inspection block
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--auth-type` | `bearer` | How Aegis injects the credential (see Auth Types below) |
+| `--scopes` | `*` | Comma-separated: `read` (GET/HEAD/OPTIONS), `write` (POST/PUT/PATCH/DELETE), `*` (all) |
+| `--ttl <days>` | *(none)* | Credential expires after this many days |
+| `--rate-limit` | *(none)* | Rate limit: `100/min`, `1000/hour`, `10/sec` |
+| `--body-inspection` | `block` | Scan outbound bodies for credential patterns: `off`, `warn`, `block` |
+| `--header-name` | — | Custom header name (only for `--auth-type header`) |
+
+Update any field later:
+
+```bash
+aegis vault update --name github-bot --rate-limit 200/min --body-inspection warn
+```
+
+## Auth Types
+
+Aegis supports four credential injection methods:
+
+| Type | Flag | What Aegis Injects |
+|------|------|--------------------|
+| `bearer` | `--auth-type bearer` (default) | `Authorization: Bearer <secret>` |
+| `header` | `--auth-type header --header-name X-API-Key` | `X-API-Key: <secret>` |
+| `basic` | `--auth-type basic` | `Authorization: Basic <base64(secret)>` |
+| `query` | `--auth-type query` | Appends `?key=<secret>` to the URL |
+
+## Configuration
+
+Aegis uses a layered configuration model: **CLI flags** > **environment variables** > **config file** > **built-in defaults**.
+
+```yaml
+# aegis.config.yaml
+gate:
+  port: 3100
+  tls:
+    cert: ./certs/aegis.crt
+    key: ./certs/aegis.key
+  require_agent_auth: true
+  policy_mode: enforce
+  policies_dir: ./policies
+
+vault:
+  name: default
+  data_dir: ./.aegis
+
+observability:
+  log_level: info
+  log_format: json
+  metrics: true
+  dashboard:
+    enabled: true
+    port: 3200
+
+mcp:
+  transport: stdio
+  port: 3300
+
+webhooks:
+  - url: https://your-webhook-endpoint.com/aegis
+    events: [blocked_request, credential_expiry]
+    secret: your-hmac-secret
+```
+
+```bash
+# Validate your config file
+aegis config validate
+
+# Show resolved config (with all overrides applied)
+aegis config show
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `AEGIS_MASTER_KEY` | Master encryption key (from `aegis init`) |
+| `AEGIS_SALT` | Vault encryption salt (auto-generated, stored in `.aegis/vaults.json`) |
+| `AEGIS_VAULT` | Active vault name (default: `default`) |
+| `AEGIS_USER_TOKEN` | RBAC user token for CLI authentication |
+
+## Webhooks
+
+Get real-time notifications when security events occur:
+
+```bash
+# Add a webhook for blocked requests and expiring credentials
+aegis webhook add \
+  --url https://your-endpoint.com/aegis \
+  --events blocked_request,credential_expiry \
+  --secret your-hmac-signing-secret
+
+# Test delivery
+aegis webhook test --id <webhook-id>
+
+# Check for credentials expiring within 7 days
+aegis webhook check-expiry
+
+# Manage
+aegis webhook list
+aegis webhook remove --id <webhook-id>
+```
+
+Webhook payloads are signed with HMAC-SHA256. Verify the `X-Aegis-Signature` header to authenticate delivery. Five event types: `blocked_request`, `credential_expiry`, `rate_limit_exceeded`, `agent_auth_failure`, `body_inspection`.
+
+## Web Dashboard
+
+```bash
+# Start the dashboard (launches Gate automatically)
+aegis dashboard
+# → Dashboard: http://localhost:3200
+# → Gate:      http://localhost:3100
+```
+
+Six views: **Overview** (health + stats), **Request Feed** (WebSocket live updates), **Credentials**, **Agents**, **Users** (RBAC), **Blocked Requests**. Dark theme.
+
+## RBAC (Role-Based Access Control)
+
+Aegis has a built-in user registry with three roles and 16 granular permissions. Once the first user is created, **every CLI command requires authentication** via `AEGIS_USER_TOKEN`.
+
+### Bootstrap Mode
+
+Before any users exist, all commands are unrestricted — this lets you run `aegis init` and `aegis user add` to create the first admin. Once at least one user exists, RBAC locks in.
+
+```bash
+# Create the first admin user (no auth required — bootstrap mode)
+aegis user add --name admin --role admin
+
+# ✓ User added to Aegis
+#   Name:   admin
+#   Role:   admin
+#   API Key (shown ONCE — save it now):
+#   aegis_user_xxxxxxxx-xxxx_xxxxxxxxxxxxxxxx
+#
+#   Use AEGIS_USER_TOKEN=<key> to authenticate CLI commands.
+```
+
+> **Save the token immediately.** Tokens are SHA-256 hashed for storage and **cannot be recovered**. If lost, an admin must regenerate it.
+
+### Authenticating
+
+Set `AEGIS_USER_TOKEN` in your environment:
+
+```bash
+export AEGIS_USER_TOKEN=aegis_user_xxxxxxxx-xxxx_xxxxxxxxxxxxxxxx
+
+# Now all commands authenticate against this token
+aegis vault list
+aegis agent list
+aegis ledger show
+```
+
+### Roles & Permissions
+
+| Permission | Admin | Operator | Viewer |
+|------------|:-----:|:--------:|:------:|
+| `vault:read` — list credentials | ✓ | ✓ | ✓ |
+| `vault:write` — add/remove/rotate credentials | ✓ | | |
+| `vault:manage` — create/destroy vaults | ✓ | | |
+| `agent:read` — list agents | ✓ | ✓ | |
+| `agent:write` — add/remove/grant agents | ✓ | ✓ | |
+| `ledger:read` — view audit logs | ✓ | ✓ | ✓ |
+| `ledger:export` — export audit logs | ✓ | ✓ | |
+| `gate:start` — start the proxy | ✓ | ✓ | |
+| `policy:read` — view policies | ✓ | ✓ | |
+| `policy:write` — manage policies | ✓ | | |
+| `webhook:read` — list webhooks | ✓ | ✓ | |
+| `webhook:write` — add/remove webhooks | ✓ | | |
+| `user:read` — list users | ✓ | | |
+| `user:write` — add/remove users | ✓ | | |
+| `dashboard:view` — access the dashboard | ✓ | ✓ | ✓ |
+| `doctor:run` — run health checks | ✓ | ✓ | ✓ |
+
+### Managing Users
+
+```bash
+# Add more users (requires admin role)
+aegis user add --name alice --role operator
+aegis user add --name bob --role viewer
+
+# Change a user's role
+aegis user role --name alice --role admin
+
+# Regenerate a lost token (invalidates the old one immediately)
+aegis user regenerate-token --name alice
+
+# Remove a user
+aegis user remove --name bob --confirm
+
+# List all users
+aegis user list
+```
+
+## Multi-Vault
+
+Isolate credentials across environments:
+
+```bash
+aegis vault create --name staging
+aegis vault create --name production
+
+# Add credentials to a specific vault
+AEGIS_VAULT=staging aegis vault add --name slack --service slack ...
+
+# List vaults
+aegis vault vaults
+
+# Destroy a vault and all its credentials
+aegis vault destroy --name staging
+```
+
+Each vault has its own database and encryption salt. Credentials encrypted in one vault cannot be decrypted by another.
+
+## Shamir's Secret Sharing
+
+Split the master key across team members so no single person can unlock the vault alone:
+
+```bash
+# Split into 5 shares, requiring any 3 to reconstruct
+aegis vault split --shares 5 --threshold 3
+
+# Seal the vault (removes the reconstructed key)
+aegis vault seal
+
+# Unseal with 3 shares
+aegis vault unseal \
+  --key-share <share-1> \
+  --key-share <share-2> \
+  --key-share <share-3>
+```
+
+## Audit Ledger
+
+Every request through Gate is logged — allowed and blocked.
+
+```bash
+# View recent entries (default: last 20)
+aegis ledger show
+
+# Filter by service, agent, or status
+aegis ledger show --service slack --limit 50
+aegis ledger show --agent research-bot
+aegis ledger show --blocked
+aegis ledger show --system          # Startup/shutdown events
+aegis ledger show --since 2026-03-01
+
+# Request statistics
+aegis ledger stats
+aegis ledger stats --agent research-bot
+aegis ledger stats --since 2026-03-01
+
+# Export (CSV, JSON, or JSON Lines)
+aegis ledger export -f csv
+aegis ledger export -f json -o audit.json
+aegis ledger export -f jsonl --service slack --since 2026-03-01
+```
+
+## Health Checks
+
+```bash
+aegis doctor
+```
+
+Runs diagnostics on your Aegis installation:
+- Config file validation
+- Database accessibility and schema
+- Master key correctness (test decrypt)
+- Expired or expiring-soon credentials
+
+Returns pass/warn/fail for each check.
+
+## Security Model
+
+- **Encryption at rest** — AES-256-GCM with PBKDF2 key derivation (100k iterations, SHA-512, random per-deployment salt)
+- **Domain guard** — enforced on every outbound request. No bypass, no override. Wildcards supported (`*.slack.com`)
+- **Credential scopes** — `read` (GET/HEAD/OPTIONS), `write` (POST/PUT/PATCH/DELETE), `*` (all). Enforced at the Gate before any request is forwarded
+- **Header stripping** — agent-supplied `Authorization`, `X-API-Key`, `Proxy-Authorization` headers are removed before injection
+- **Body inspection** — outbound request bodies scanned for credential-like patterns (configurable per credential: `off`, `warn`, `block`)
+- **Hash-only token storage** — agent tokens stored as SHA-256 hashes. Lost tokens are regenerated, never recovered
+- **Audit logging** — every request (allowed and blocked) recorded with full context. Export with `aegis ledger export -f csv`
+- **TLS support** — optional HTTPS on Gate (`aegis gate --tls --cert <path> --key <path>`)
+- **Graceful shutdown** — drains in-flight requests on SIGINT/SIGTERM
+
+See [SECURITY_ARCHITECTURE.md](docs/SECURITY_ARCHITECTURE.md) for the full security design, threat model, and trust boundaries.
+
+## CLI Reference
+
+```
+aegis init [--write-secrets]              Initialize Aegis (master key + config)
+aegis gate [--port] [--tls] [--require-agent-auth] [--policies-dir] [--policy-mode]
+                                          Start the HTTP proxy
+aegis dashboard [--port] [--gate-port]    Start the web dashboard + Gate
+
+aegis vault add [--name] [--service] [--secret] [--domains] [--auth-type]
+               [--header-name] [--scopes] [--ttl] [--rate-limit] [--body-inspection]
+                                          Add a credential
+aegis vault list                          List credentials (secrets never shown)
+aegis vault remove --name <name>          Remove a credential
+aegis vault rotate --name <name> --secret <new>
+                                          Rotate a credential's secret
+aegis vault update --name <name> [--domains] [--auth-type] [--header-name]
+               [--scopes] [--rate-limit] [--body-inspection]
+                                          Update credential metadata
+aegis vault create --name <name>          Create a new named vault
+aegis vault vaults                        List all vaults
+aegis vault destroy --name <name>         Delete a vault and its credentials
+aegis vault split [--shares] [--threshold]
+                                          Split master key (Shamir)
+aegis vault seal                          Seal the vault
+aegis vault unseal --key-share <share>... Unseal (provide threshold shares)
+
+aegis agent add --name <name>             Register agent, print token (one-time)
+aegis agent list                          List agents (no tokens shown)
+aegis agent remove --name <name>          Remove agent + cascade-delete grants
+aegis agent regenerate --name <name>      Regenerate token (old one invalidated)
+aegis agent grant --agent <a> --credential <c>
+                                          Grant credential access
+aegis agent revoke --agent <a> --credential <c>
+                                          Revoke credential access
+aegis agent set-rate-limit --agent <a> --limit <rate>
+                                          Set per-agent rate limit
+
+aegis policy validate [--policies-dir]    Validate policy files
+aegis policy test --agent <a> --service <s> --method <m> --path <p>
+                                          Test a request against policies
+aegis policy list [--policies-dir]        List loaded policies
+
+aegis ledger show [--service] [--agent] [--blocked] [--system] [--since] [--limit]
+                                          View audit logs
+aegis ledger stats [--agent] [--since]    Request statistics
+aegis ledger export -f <csv|json|jsonl> [-o file] [--service] [--since]
+                                          Export audit log
+
+aegis webhook add --url <url> --events <types>
+                                          Add a webhook endpoint
+aegis webhook list                        List webhooks
+aegis webhook remove --id <id>            Remove a webhook
+aegis webhook test --id <id>              Send a test payload
+aegis webhook check-expiry                Check for expiring credentials
+
+aegis user add --name <name> --role <role>
+                                          Add RBAC user (admin/operator/viewer)
+aegis user list                           List users
+aegis user remove --name <name>           Remove user
+aegis user role --name <name> --role <role>
+                                          Change user role
+aegis user regenerate-token --name <name> Regenerate user token
+
+aegis mcp serve [--transport] [--port]    Start the MCP server
+aegis mcp config <claude|cursor|vscode>   Generate MCP host config
+
+aegis config validate                     Validate config file
+aegis config show                         Show resolved configuration
+aegis doctor                              Health check diagnostics
+```
+
+## Troubleshooting
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `AEGIS_MASTER_KEY is not set` | No master key in config or env | `export AEGIS_MASTER_KEY=<key>` or use `aegis init --write-secrets` |
+| `Invalid master key` | Wrong key for this vault | Check `AEGIS_MASTER_KEY` matches the key from `aegis init` |
+| `Port 3100 is already in use` | Another process on that port | Use `aegis gate --port 3200` or stop the other process |
+| `Database file is corrupted` | SQLite file damaged | Back up `.aegis/` and re-run `aegis init` |
+| `Domain guard: blocked` | Target domain not in credential allowlist | Update domains: `aegis vault update --name <n> --domains <d>` |
+| `Body inspection: blocked` | Request body contains credential-like patterns | Remove sensitive patterns from the body, or set `--body-inspection warn` on the credential |
+| `Authentication required` | RBAC is active (users exist) but no token set | `export AEGIS_USER_TOKEN=<key>` — get a key from your admin or `aegis user regenerate-token` |
+| `Permission denied` | Your RBAC role lacks the required permission | Ask an admin to upgrade your role with `aegis user role` |
+
+## Development
+
+```bash
+git clone https://github.com/getaegis/aegis.git
+cd aegis
+yarn install
+yarn build
+yarn test        
+yarn lint        # Biome linter
+yarn verify      # Biome check + TypeScript typecheck
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for code style, PR process, and architecture overview.
+
+### Tech Stack
+
+| Layer | Technology |
+|-------|------------|
+| Language | TypeScript (ES2022, native ESM) |
+| Runtime | Node.js ≥ 20 |
+| Database | SQLite via better-sqlite3 (WAL mode) |
+| Encryption | AES-256-GCM, PBKDF2 |
+| Logging | pino (structured JSON, field-level redaction) |
+| Metrics | prom-client (Prometheus) |
+| CLI | Commander.js |
+| MCP | @modelcontextprotocol/sdk |
+| Dashboard | Vite + React 19 + Tailwind CSS v4 |
+| Testing | Vitest |
+| Linting | Biome |
+
+## Roadmap
+
+See [ROADMAP.md](docs/ROADMAP.md) for the full plan from v0.1 to v1.0.
+
+## License
+
+[Apache 2.0](LICENSE)

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@getaegis/cli",
+  "version": "0.8.0",
+  "description": "Credential isolation for AI agents. Store, guard, and record — your agent never sees your API keys.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "aegis": "dist/cli.js"
+  },
+  "files": [
+    "dist/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getaegis/aegis.git"
+  },
+  "homepage": "https://github.com/getaegis/aegis#readme",
+  "bugs": {
+    "url": "https://github.com/getaegis/aegis/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && cd dashboard && yarn build && rm -rf ../dist/dashboard/public && cp -r dist ../dist/dashboard/public",
+    "dev": "tsx src/cli.ts",
+    "start": "node dist/cli.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome check src/ tests/",
+    "lint:fix": "biome check --write src/ tests/",
+    "format": "biome format --write src/ tests/",
+    "typecheck": "tsc --noEmit",
+    "verify": "biome check src/ tests/ && tsc --noEmit",
+    "prepublishOnly": "yarn build && yarn test",
+    "prepare": "husky"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx}": [
+      "biome check --write --no-errors-on-unmatched"
+    ]
+  },
+  "keywords": [
+    "ai-agent",
+    "credential-isolation",
+    "security",
+    "secrets-management",
+    "ai-security",
+    "agent-governance"
+  ],
+  "author": "Samuel Warren <getaegis.npm@gmail.com>",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@types/ws": "^8.18.1",
+    "better-sqlite3": "^11.8.0",
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "pino": "^10.3.1",
+    "prom-client": "^15.1.3",
+    "table": "^6.9.0",
+    "ws": "^8.19.0",
+    "yaml": "^2.8.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.4",
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/node": "^22.13.0",
+    "@types/pino": "^7.0.5",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "pino-pretty": "^13.1.3",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "packageManager": "yarn@4.12.0+sha512.f45ab632439a67f8bc759bf32ead036a1f413287b9042726b7cc4818b7b49e14e9423ba49b18f9e06ea4941c1ad062385b1d8760a8d5091a1a31e5f6219afca8"
+}