auramaxx 0.0.20 → 0.1.1

package/skills/auramaxx/docs/security.md

@@ -1,227 +0,0 @@
-# Security
-
-This document reflects the current security model implemented in the codebase.
-
-## Security Overview (why the model is safe)
-
-AuraMaxx uses a **three-layer model**:
-
-1. **Profile-based issuance** (how a token is created)
-2. **Permission-based runtime enforcement** (what a token can do)
-3. **Granular credential access policy** (which secrets and fields can be touched)
-
-The result: tokens are easy to issue, strict to scope, and hard to overscope.
-
-### The model in one pass
-
-- Agents usually start with an **agent profile** (`POST /auth`) that defines:
-  - base permissions
-  - credential read/write scopes (agents/tags/ids)
-  - TTL and read limits
-  - field redaction policies
-- Issuance is intentionally **human-approved** and not self-service by default.
-- Every API request is still validated again using runtime permission checks.
-- Secret access is additionally constrained by selector checks and read budgets.
-- Tokens are short-lived and can be revoked proactively.
-
-### What “least privilege” means here
-
-- Profiles give sensible defaults, but they are not blanket trust.
-- Every request is still gated by permissions + scope.
-- Agent callers can only operate on explicitly authorized agents and fields.
-- If a profile must be tighter, overrides must be **tighten-only**.
-
----
-
-## Core Principles
-
-1. **Memory-rooted auth/session state** — in-memory SIGNING_KEY, sessions, and revocation state drive runtime trust boundaries.
-2. **Restart invalidates all tokens** — new SIGNING_KEY is generated each restart.
-3. **Minimal permissions** — tokens carry exactly the permissions needed.
-4. **Encrypted secrets at rest** — credential fields are encrypted in local DB with agent-derived keys.
-5. **Encrypted credential transport** — secret reads are encrypted to the caller's RSA pubkey.
-6. **Human-controlled unlocks** — privileged operations require explicit human action.
-7. **Scoped ownership** — credential access requires explicit credential selectors + permission checks.
-
-## Current Security Model
-
-AuraMaxx is **profile-first** for issuance, but **permission- and scope-enforced at runtime**.
-
-- Issuance determines token payload (permissions, TTL, credential selectors, exclusions).
-- Middleware enforces per-route permissions on every call.
-- Credential read/write governance adds extra controls:
-  - selector checks
-  - per-token read budgets
-  - max read/window throttles
-  - excluded field minimization
-
-Auth/session truth source is still memory-first:
-
-- Tokens are signed in memory (`SIGNING_KEY`).
-- Session counters/tracking are memory-backed.
-- Revocations are memory-backed (`revokedTokens`).
-- DB is authoritative for UI/audit views, not for runtime auth decisions.
-
-## Agent Token Paths
-
-> For quickstart usage and CLI examples, see [AUTH.md](AUTH.md). This section describes the security enforcement model for each path.
-
-### 1) `POST /auth` (profile-only request + human approval)
-
-Standard agent onboarding path.
-
-- Required: `agentId`, `profile`, `pubkey`.
-- Rejects raw issuance (`permissions`, `ttl`, `credentialAccess`) on `/auth`.
-- Resolves profile policy and stores approval request in memory.
-- After approval, claim via `GET /auth/:requestId?secret=...`.
-
-### 2) `POST /actions` + `/actions/:id/resolve` (internal — strategy engine only)
-
-> **Note**: `/actions` routes are internal. Agents should use `POST /auth` with an optional `action` field for one-off escalation with auto-execute.
-
-- Used internally by the strategy engine's `request_human_action` tool.
-- Caller needs `action:create` to submit.
-- Payload is permission-based.
-- Self-escalation is blocked for `admin:*` and `action:create`.
-- Approved request gets a scoped token and escrowed claim path.
-
-### 3) `POST /actions/token` (admin direct issuance)
-
-Admin-only endpoint with XOR mode:
-
-- `profile` mode: profile + optional tighten-only overrides
-- `permissions` mode: explicit permissions
-
-Exactly one mode must be supplied.
-
-### 4) Validation and revocation
-
-- `POST /auth/validate` validates token status, expiry, and revocation.
-- `POST /actions/tokens/revoke` forcibly removes active token trust.
-
-## Profile-Based Security (Current)
-
-Built-in profile IDs (`v1`): `strict`, `dev`, `admin`.
-
-See [AUTH.md — Built-in Profiles](AUTH.md#built-in-profiles-v1) for the full breakdown of permissions, scopes, excluded fields, TTL, and max reads per profile.
-
-Profile resolution (`resolveProfileToEffectivePolicy`) produces:
-
-- expanded permissions
-- `credentialAccess.read` / `credentialAccess.write`
-- `excludeFields`
-- `ttlSeconds`
-- `maxReads`
-- `effectivePolicyHash`
-
-### Tighten-only overrides
-
-Overrides are only allowed to reduce privilege:
-
-- shorter TTL / fewer reads
-- narrower permission scope
-- narrower credential selectors
-- stronger field exclusions
-
-## Permission Enforcement (Runtime)
-
-Runtime enforcement always applies:
-
-- route middleware validates signature, expiry, revocation
-- permission checks (`requirePermission`, `hasAnyPermission`) gate capabilities
-- `admin:*` remains privileged bypass flag where explicitly required
-
-Profile is issuance; permission enforcement is the live guardrail.
-
-## Granular credential access controls
-
-AuraMaxx supports fine-grained secret governance:
-
-- `secret:read` and `secret:write` route gating
-- credential selectors:
-  - `agent:agent`, `agent:primary`, `agent:*`, `*`
-  - `tag:<label>`
-  - `cred-xxxxx`
-- policy TTL and `maxReads`
-- per-credential/minute rate limits
-- field minimization via `excludeFields`
-
-This means permissions can say “can read secrets,” and selectors define **where** and **what field-level data** is reachable.
-
-### Recommended mental model
-
-- Permissions say **action** (`read`/`write`/`totp`),
-- selectors say **scope** (agent/field scope),
-- TTL/limits say **time/volume**.
-
-## Encrypted transport boundaries
-
-- `GET /auth/connect` returns a short-lived server public key.
-- `/setup` and `/unlock` accept encrypted payloads.
-- Agent token claim endpoints return `encryptedToken`.
-- Secret reads return ciphertext suitable to caller key material.
-
-This prevents plaintext secrets in transit for normal operations.
-
-## Strict mode and local auto-approve
-
-Strict posture is preferred for high-trust environments.
-
-Set strict local defaults:
-
-- `trust.localProfile = strict`
-- `trust.localAutoApprove = false`
-
-Quick commands:
-
-```bash
-curl -sS -X PATCH http://localhost:4242/defaults/trust.localProfile \
-  -H "Authorization: Bearer <admin_token>" \
-  -H "Content-Type: application/json" \
-  -d '{"value":"strict"}'
-
-curl -sS -X PATCH http://localhost:4242/defaults/trust.localAutoApprove \
-  -H "Authorization: Bearer <admin_token>" \
-  -H "Content-Type: application/json" \
-  -d '{"value":false}'
-```
-
-## Profile creation and validation
-
-Profiles are derived from built-ins + tighten-only overrides.
-
-Supported override keys:
-
-- `ttlSeconds`
-- `maxReads`
-- `scope`
-- `readScopes`
-- `writeScopes`
-- `excludeFields`
-
-Prefer preview before issuing:
-
-- `POST /actions/token/preview`
-- `auramaxx token preview --profile <id> [--profile-version v1] [--overrides '{...}']`
-
-## Endpoint Cheat Sheet
-
-| Endpoint | Style | Typical use |
-|---|---|---|
-| `POST /auth` | Profile onboarding | Standard agent setup (human approval) |
-| `GET /auth/:requestId?secret=...` | Profile claim | Agent retrieves encrypted token |
-| `POST /auth/validate` | Validation | Verify token validity before use |
-| `POST /actions` | Internal (strategy engine) | Temporary action request |
-| `POST /actions/:id/resolve` | Internal (approval) | Human approves action request |
-| `POST /actions/token` | Admin direct issue | Admin direct token issuance |
-| `POST /actions/tokens/revoke` | Revocation | Immediate invalidate token |
-| `POST /actions/token/preview` | Preview | Validate effective policy before issue |
-| `POST /unlock` / `POST /setup` | Session bootstrap | Human local admin access |
-
-## Related Docs
-
-- [Auth](AUTH.md)
-- [API Authentication](./api/authentication.md)
-- [API System](./api/system.md)
-- [CLI](CLI.md)
-- [Best Practices](./BEST-PRACTICES.md)

package/skills/task-lifecycle/SKILL.md

@@ -1,366 +0,0 @@
-# Task Lifecycle — Agent PM System
-
-Manage the task pipeline. All commands use `$TASKCTL` from the project root.
-
-```bash
-TASKCTL="node --import tsx scripts/taskctl.ts"
-```
-
----
-
-## How It Works
-
-Agents work in **isolated task folders** — never touching source code directly. Changes flow through automated validation and human approval before landing in the codebase.
-
-```
-QUEUED ──→ IN_PROGRESS ──→ REVIEW ──→ DONE
-               │               │
-          (gate fail)    (reject/test fail)
-               │               │
-               ▼               ▼
-           QUEUED ◄────────────┘   (attempts < 3, retry)
-           FROZEN ◄────────────┘   (attempts >= 3, human intervenes)
-```
-
-### Pipeline Flow
-
-1. **Provision** — Task transitions to IN_PROGRESS, system copies allowed files into `{project_root}/tasks/task-{id}/changes/` and creates `/new/`
-2. **Agent works** — Modifies files in the task folder only, within spec constraints
-3. **Gate check** — Validates against allowlists, line limits, forbidden paths, dependency rules
-4. **Review** — Human reviews via dashboard or CLI preview
-5. **Swap** — Git savepoint → copy to source → run tests → commit or rollback
-6. **Conflict resolution** — After swap, other tasks touching same files get invalidated and requeued
-
----
-
-## Statuses
-
-| Status | Meaning |
-|--------|---------|
-| `OPEN` | Created, not yet queued for agents |
-| `QUEUED` | Ready for agent pickup |
-| `IN_PROGRESS` | Agent working in task folder |
-| `REVIEW` | Gate check passed, awaiting human approval |
-| `DONE` | Approved, swapped into source, archived |
-| `FROZEN` | 3+ failures, needs human investigation |
-| `HUMAN` | Reserved for human-only work |
-| `CANCELED` | Abandoned or superseded |
-
----
-
-## Task Folder Rules
-
-```
-{project_root}/tasks/task-{id}/
-  /changes/     ← copies of allowed source files to modify
-  /new/         ← new files the agent creates
-```
-
-**Agents MUST:**
-- Only modify files in `changes/` that are listed in `allowed_modify`
-- Only create files in `new/` matching `allowed_create` patterns
-- Stay under `max_lines_changed` (default: 200)
-
-**Agents MUST NOT:**
-- Touch source code directly
-- Modify files outside `allowed_modify`
-- Touch `forbidden` paths (global or per-project)
-- Add dependencies unless `can_add_dependencies` is true
-
-### Task Spec Fields
-
-| Field | Type | Purpose |
-|-------|------|---------|
-| `allowed_modify` | JSON array | Files the agent may edit |
-| `allowed_create` | JSON array | Glob patterns for new files |
-| `max_lines_changed` | integer | Max total line diff |
-| `can_add_dependencies` | boolean | Allow package.json changes |
-| `module` | string | Module this task touches |
-| `attempts` | integer | Rejection count |
-| `last_error` | string | Last rejection reason |
-
----
-
-## Gate Check
-
-Automated validation that runs before a task reaches REVIEW. **Auto-rejects** if:
-
-1. Modified file not in `allowed_modify`
-2. Created file not matching `allowed_create` patterns
-3. File matches `forbidden` globs (global + per-project merged)
-4. Lines changed exceeds `max_lines_changed`
-5. package.json/lock file changed and `can_add_dependencies` is false
-
-```bash
-$TASKCTL gate-check --task N [--json]     # Exit 0 = pass, Exit 2 = fail
-```
-
-API: `POST /api/tasks/{N}/gate-check` → `{ ok, passed, violations[], filesChanged[], filesCreated[], linesChanged }`
-
----
-
-## Circuit Breaker
-
-On rejection (gate fail, test failure, human reject):
-
-- `attempts` increments by 1, `last_error` records reason
-- **attempts < 3** → QUEUED (agent retries)
-- **attempts >= 3** → FROZEN (human must investigate)
-
-Frozen tasks require human intervention: rewrite spec + reset attempts, or kill.
-
----
-
-## Swap
-
-Applies an approved REVIEW task into the source tree:
-
-1. Creates git savepoint
-2. Copies `changes/` files into source
-3. Copies `new/` files into project
-4. Runs test command (per-project `test_command` config, 120s timeout)
-5. **Tests pass** → commit, release file locks, archive task folder → DONE
-6. **Tests fail** → rollback to savepoint, circuit breaker handles retry/freeze
-
-```bash
-$TASKCTL swap --task N [--json]            # Execute swap
-$TASKCTL swap --task N --dry-run [--json]  # Preview without committing
-```
-
-API: `POST /api/tasks/{N}/swap` (body: `{ dryRun?: boolean }`) → 200 success, 422 test failure, 409 not in REVIEW
-
----
-
-## File Locks
-
-Tracks file ownership across concurrent tasks. First task to swap wins — conflicting tasks get invalidated and requeued.
-
-- **Acquire** — Atomic all-or-nothing; returns conflicts if file already locked
-- **Release** — Marks locks as released after swap
-- **Invalidate** — After swap, other tasks on same files get requeued via circuit breaker
-
-```bash
-$TASKCTL file-locks --task N [--json]       # List active locks
-$TASKCTL file-conflicts --task N [--json]   # Check for overlapping locks
-```
-
-API: `GET /api/tasks/{N}/file-locks`, `GET /api/tasks/{N}/file-conflicts`
-
----
-
-## Preview
-
-Temporarily copy task files into source for visual review. One preview at a time. No git operations — clean restore guaranteed.
-
-```bash
-$TASKCTL preview-start --task N [--json]   # Copy task files to source
-$TASKCTL preview-stop [--json]             # Restore source to original state
-```
-
----
-
-## Context Builder
-
-Assembles the agent prompt when a task starts. Total must stay under 4000 lines.
-
-Assembly order:
-1. **Framing** — Per-project `project_framing` config + task description + allowed files
-2. **ARCHITECTURE.md** — Truncated to 100 lines
-3. **Modified files** — Full content from task folder
-4. **Adjacent interfaces** — Export signatures from related files
-5. **Similar feature example** — From completed task with same module (optional)
-
-Truncation order if over limit: example first, then adjacent interfaces.
-
----
-
----
-
-## CLI Reference
-
-### Quick Workflow
-
-```bash
-# Pick next task, claim it, and start
-$TASKCTL pick-and-claim --owner my-agent [--tag TAG] [--json]
-$TASKCTL update-task-status --task N --owner my-agent --status IN_PROGRESS [--json]
-
-# Or use the shortcut
-$TASKCTL next --owner my-agent [--json]
-
-# When done
-$TASKCTL done --task N --owner my-agent [--json]
-
-# Approve a REVIEW task (swap + cascade-unblock)
-$TASKCTL approve --task N [--json]
-
-# On failure
-$TASKCTL fail --task N --owner my-agent --error "reason" [--json]
-```
-
-### Task Management
-
-```bash
-# List and view
-$TASKCTL list-tasks [--status S] [--tag TAG] [--json]
-$TASKCTL show-task --task N [--json]
-$TASKCTL my-tasks --owner O [--json]
-$TASKCTL stats [--json]
-
-# Create and edit
-$TASKCTL create-task --title "..." --slug "..." [--priority P0|P1|P2] [--json]
-$TASKCTL quick-create --title "..." [--json]
-$TASKCTL update-task --task N --title "..." [--json]
-
-# Status transitions
-$TASKCTL update-task-status --task N --owner O --status S [--json]
-$TASKCTL pick-task [--tag TAG] [--json]
-$TASKCTL pick-and-claim [--tag TAG] --owner O [--json]
-$TASKCTL claim-lock --task N --owner O [--json]
-$TASKCTL release-lock --task N --owner O [--json]
-$TASKCTL reap-stale-locks [--json]
-
-# Tags
-$TASKCTL add-tag --task N --tag T [--json]
-$TASKCTL remove-tag --task N --tag T [--json]
-$TASKCTL list-tags [--task N] [--json]
-
-# Dependencies
-$TASKCTL add-dep --task N --depends-on M [--json]
-$TASKCTL remove-dep --task N --depends-on M [--json]
-$TASKCTL list-deps --task N [--json]
-
-# Hierarchy
-$TASKCTL set-parent --task N --parent M [--json]
-$TASKCTL remove-parent --task N [--json]
-$TASKCTL list-subtasks --task N [--json]
-
-# Comments
-$TASKCTL comment --task N --author A --body "..." [--json]
-$TASKCTL list-comments --task N [--json]
-
-# Config (global)
-$TASKCTL config-get --key K [--json]
-$TASKCTL config-set --key K --value V [--json]
-$TASKCTL config-list [--json]
-
-# Templates
-$TASKCTL list-templates [--json]
-$TASKCTL show-template --name N [--json]
-```
-
-### Pipeline Commands
-
-```bash
-# Gate check
-$TASKCTL gate-check --task N [--json]
-
-# Swap
-$TASKCTL swap --task N [--dry-run] [--json]
-
-# Approve (swap + cascade-unblock dependents)
-$TASKCTL approve --task N [--json]
-
-# File locks
-$TASKCTL file-locks --task N [--json]
-$TASKCTL file-conflicts --task N [--json]
-
-# Preview
-$TASKCTL preview-start --task N [--json]
-$TASKCTL preview-stop [--json]
-
-# Backlog
-$TASKCTL backlog-status [--json]
-```
-
----
-
-## Config
-
-Config is layered: **per-task spec > per-project config > global config**. Per-project can only further restrict, never loosen global rules.
-
-### Global Config
-
-Set once, applies to all projects.
-
-| Key | Default | Purpose |
-|-----|---------|---------|
-| `global_forbidden` | `["core/*"]` | Glob patterns no agent may touch |
-| `max_concurrent_tasks` | `5` | Max tasks in IN_PROGRESS at once |
-| `default_max_lines_changed` | `200` | Default line limit per task |
-| `default_can_add_dependencies` | `false` | Default dependency policy |
-
-### Per-Project Config
-
-Stored in `project_config` table. Overrides global for tasks scoped to that project. Falls back to global when unset.
-
-| Key | Purpose |
-|-----|---------|
-| `global_forbidden` | Additional forbidden globs (merged with global) |
-| `test_command` | Test runner command (e.g. `npx vitest run`, `npm test`, `pytest`) |
-| `project_framing` | Context builder framing text for this project |
-| `source_dir` | Source directory name (default: `src`) |
-| `dashboard_port` | Dev server port for preview |
-
-```bash
-# Set per-project config
-$TASKCTL config-set --project P --key test_command --value "npm test"
-$TASKCTL config-set --project P --key global_forbidden --value '["core/*","migrations/*"]'
-
-# View merged config for a project
-$TASKCTL config-list --project P
-```
-
-### Adding a New Project
-
-```bash
-# Register project
-$TASKCTL create-project --name "my-app" --root /path/to/my-app
-
-# Set project-specific config
-$TASKCTL config-set --project 1 --key test_command --value "npm test"
-$TASKCTL config-set --project 1 --key global_forbidden --value '["core/*","db/migrations/*"]'
-$TASKCTL config-set --project 1 --key project_framing --value "You are modifying a React dashboard app."
-```
-
----
-
-## API Endpoints
-
-| Method | Endpoint | Purpose |
-|--------|----------|---------|
-| GET | `/api/tasks` | List tasks (query: `status`, `q`, `limit`, `offset`) |
-| GET | `/api/tasks/pick` | Pick next queued task |
-| POST | `/api/tasks/create` | Create task |
-| GET | `/api/tasks/{N}` | Task detail |
-| POST | `/api/tasks/{N}/claim` | Acquire lock |
-| POST | `/api/tasks/{N}/release` | Release lock |
-| POST | `/api/tasks/{N}/transition` | Transition status |
-| POST | `/api/tasks/{N}/gate-check` | Run gate check |
-| POST | `/api/tasks/{N}/swap` | Execute swap |
-| GET | `/api/tasks/{N}/file-locks` | List active file locks |
-| GET | `/api/tasks/{N}/file-conflicts` | Check file conflicts |
-| POST | `/api/tasks/{N}/tags` | Add tag |
-| DELETE | `/api/tasks/{N}/tags` | Remove tag |
-| GET | `/api/tasks/{N}/comments` | List comments |
-| POST | `/api/tasks/{N}/comments` | Add comment |
-| GET | `/api/config` | List global config |
-| POST | `/api/config` | Set global config |
-
----
-
-## Services Reference
-
-| Service | File | Function |
-|---------|------|----------|
-| Task Folder | `src/core/task-folder-service.ts` | `provisionTaskFolder(dbFile, taskNum)` |
-| Gate Check | `src/core/gate-check-service.ts` | `runGateCheck(dbFile, taskNum)` |
-| Circuit Breaker | `src/core/circuit-breaker.ts` | `handleRejection(dbFile, taskNum, reason)` |
-| Swap | `src/core/swap-service.ts` | `swapTaskIntoSrc(dbFile, taskNum, opts?)` |
-| File Locks | `src/core/file-lock-service.ts` | `acquireFileLocks()`, `releaseFileLocks()`, `invalidateConflicts()` |
-| Preview | `src/core/preview-service.ts` | `startPreview(dbFile, taskNum)`, `stopPreview(dbFile)` |
-| Context Builder | `src/core/context-builder.ts` | `buildAgentContext(dbFile, taskNum)` |
-| Global Config | `src/core/global-config-service.ts` | `getConfig()`, `setConfig()`, `listConfig()` |
-| Project Config | `src/core/project-service.ts` | `getProjectConfig()`, `setProjectConfig()`, `listProjectConfig()` |
-
-Full spec: `public/agent-project-management.md`