@nullsquare/agent-authority 0.4.0

package/docs/cli.md

@@ -0,0 +1,130 @@
+# Agent Authority CLI
+
+The CLI is the user-facing control surface for the local Agent Authority runtime.
+
+## Install from source
+
+```bash
+git clone https://github.com/Null-Square/agent-authority.git
+cd agent-authority
+npm install
+npm link
+```
+
+This exposes both `agent-authority` and the short alias `aauth`.
+
+## First-time setup
+
+```bash
+agent-authority setup
+agent-authority doctor
+agent-authority status
+```
+
+By default Agent Authority stores local state under:
+
+```text
+~/.agent-authority/
+  config.json
+  missions/
+  state/
+    connections.json
+    revocations.json
+    usage.json
+  vault/
+    master.key
+    secrets.enc.json
+  receipts/
+```
+
+Override the location with `AGENT_AUTHORITY_HOME` or `--home PATH`.
+
+## Connect GitHub
+
+The current native GitHub onboarding path accepts credentials only over stdin so secrets do not appear in shell history:
+
+```bash
+printf %s "$GITHUB_TOKEN" | agent-authority connect github --token-stdin
+```
+
+The CLI verifies the credential against GitHub by default, discovers the account login and stores the credential encrypted in the local vault. Use `--no-verify` only for offline development.
+
+Browser/device OAuth is the next onboarding milestone; manual tokens are intentionally an interim developer path rather than the final UX.
+
+List safe connection metadata:
+
+```bash
+agent-authority connections
+```
+
+Disconnect and delete the locally stored credential:
+
+```bash
+agent-authority disconnect github --account ACCOUNT_ID
+```
+
+## Run the authority daemon
+
+```bash
+agent-authority serve
+```
+
+Default bind address:
+
+```text
+127.0.0.1:8787
+```
+
+Override with:
+
+```bash
+agent-authority serve --host 127.0.0.1 --port 8787
+```
+
+or `AGENT_AUTHORITY_HOST` / `AGENT_AUTHORITY_PORT`.
+
+The loopback default is intentional. Do not expose the local daemon publicly without an authenticated transport layer in front of it.
+
+## Mission commands
+
+Validate a mission:
+
+```bash
+agent-authority mission validate examples/mission.json
+```
+
+Evaluate an action locally without executing it:
+
+```bash
+agent-authority mission evaluate examples/mission.json \
+  --service github \
+  --action repo.read \
+  --repository Null-Square/agent-authority
+```
+
+The command exits non-zero for denied actions, which makes it useful in scripts and CI.
+
+## Operational commands
+
+```bash
+agent-authority status
+agent-authority doctor
+agent-authority --version
+agent-authority --help
+```
+
+`doctor` checks the config, local encrypted vault, connection state and whether the configured daemon uses the safe loopback default.
+
+## Config principles
+
+- no credentials in `config.json`
+- no credentials in mission manifests
+- no credential command-line flags
+- provider credentials remain behind the broker
+- connection metadata is safe to show to agents; secret references are not
+- revocations and cumulative budget usage persist across daemon restarts
+- action receipts are written under `receipts/`
+
+## Current security boundary
+
+The local encrypted file vault uses AES-256-GCM and restrictive file permissions. Its master key is local to the same user account, so it protects against accidental plaintext exposure but is **not** a replacement for an OS keychain, hardware-backed key store, KMS/HSM, or remote enterprise vault. Production hardening will add pluggable key-store backends.

package/docs/evidence.md

@@ -0,0 +1,143 @@
+# Executable Evidence
+
+Agent Authority is an experimental security runtime. Claims in this project should be backed by executable evidence, not architecture diagrams alone.
+
+This page records the strongest properties the repository currently demonstrates.
+
+## Core claim under test
+
+> An effect placed behind an Agent Authority Task Lease cannot use the host's broader provider access for a different concrete resource unless the task authority expands explicitly.
+
+The guarantee applies to effects that actually pass through the Agent Authority enforcement boundary. A separate unguarded provider path is outside this guarantee.
+
+## Live derived-authority mutation — GitHub
+
+Public fixture: [issue #9](https://github.com/Null-Square/agent-authority/issues/9)
+
+Validation workflow: CI job `live-derived-github-mutation`
+
+Passing run: [CI run 136](https://github.com/Null-Square/agent-authority/actions/runs/32517381668)
+
+The job uses a GitHub Actions token with:
+
+```text
+contents: read
+issues: write
+```
+
+The Task Lease itself starts with only the repository as an authority root.
+
+### Executed path
+
+```text
+Task root
+Null-Square/agent-authority
+        |
+        v
+ALLOW live issue-list request
+        |
+        v
+discover issue #9 from GitHub response
+        |
+        v
+derive fact: issue_number = 9
+        |
+        v
+ALLOW one real comment mutation on #9
+        |
+        +--> attempt comment on #1
+        |      -> authority_delta_required
+        |      -> provider mutation callback does not run
+        |
+        v
+complete Task Lease
+        |
+        +--> attempt comment on #9 again
+               -> task_lease_completed
+               -> provider mutation callback does not run
+```
+
+The passing job recorded:
+
+```text
+ALLOW -> discovered issue #9
+Derived authority -> issue #9
+ALLOW -> real GitHub comment mutation executed
+STEP-UP -> unrelated issue #1 blocked before provider mutation
+DENY -> post-completion mutation blocked for issue #9
+Provider calls observed before cleanup: reads=1, task_mutations=1
+```
+
+The temporary validation comment is deleted by test-harness cleanup after the proof. Cleanup is intentionally outside the agent authority path and counted separately.
+
+### What this proves
+
+- a concrete resource can be discovered from a real provider response during authorized execution;
+- that resource can become same-lease derived authority;
+- a real provider mutation can be limited to the derived resource;
+- asking for another resource does not silently inherit the same authority;
+- a blocked resource causes zero additional task-side provider mutation calls;
+- completing the Task Lease prevents reuse of the previously authorized resource;
+- the provider credential can still exist after task authority disappears.
+
+### What this does not prove
+
+- the host/adapter's extraction of `output.number` is cryptographically verified;
+- an agent cannot bypass Agent Authority if it independently possesses the provider credential or another unguarded provider path;
+- Task Lease state is durable across process failure;
+- the current prototype is ready for adversarial production use.
+
+## Live provider read boundary — GitHub
+
+CI also runs `demo:live-github` against the public GitHub API.
+
+It proves that one repository permitted by the Task Lease causes one live `fetch()` while another repository produces `authority_delta_required` before a second fetch occurs.
+
+## Network-boundary integration test
+
+`test/guard-network.test.js` uses an ordinary local HTTP provider with a deliberately broad bearer credential.
+
+The server itself observes that:
+
+- the authorized resource reaches the provider once;
+- an unrelated resource produces no additional request;
+- task completion produces no additional request;
+- the broad provider credential remains present throughout the test.
+
+## Adversarial Task Lease tests
+
+The test suite also covers:
+
+- unresolved derived facts fail closed;
+- derived authority requires an `ALLOW` receipt;
+- receipts from another mission are rejected;
+- receipts from another Task Lease are rejected;
+- parent lineage is required;
+- a trusted extraction selector must be recorded;
+- explicit mission deny rules remain the ceiling;
+- lease expiry and mission expiry are enforced against a consistent evaluation clock.
+
+## Continuous checks
+
+Current pull requests run:
+
+- Node.js 20 tests;
+- Node.js 22 tests;
+- Task Lease runnable demo;
+- syntax checks;
+- package checks;
+- coverage;
+- live GitHub read validation;
+- live derived GitHub mutation validation for trusted in-repository branches;
+- CodeQL.
+
+## Evidence standard for new claims
+
+A new security claim should ideally include all four:
+
+1. a positive path that performs the intended effect;
+2. an adversarial path that attempts to exceed authority;
+3. observation at or immediately before the real provider boundary;
+4. a public CI result that can be rerun.
+
+The project should prefer a smaller claim with strong evidence over a broader claim that depends on trust in the model or prompt.

package/docs/harness-bridge-mode.md

@@ -0,0 +1,136 @@
+# Harness-Managed Connector Mode
+
+Agent Authority supports two complementary execution modes.
+
+## 1. Brokered execution
+
+Agent Authority owns the provider connection and executes the provider request itself.
+
+```text
+agent -> Agent Authority -> provider adapter -> provider
+```
+
+The agent never sees the long-lived provider credential.
+
+This is the preferred mode when Agent Authority can safely own or exchange the credential.
+
+## 2. Harness-managed connector execution
+
+Some agent platforms already own provider authentication internally and do not expose their OAuth tokens to plugins or models. Examples include hosted agent products, IDE connectors, enterprise harnesses, and ChatGPT-style connected apps.
+
+In that environment the boundary becomes:
+
+```text
+model / planner
+     |
+     | proposes exact action
+     v
+Agent Authority
+     |
+     | signed short-lived Action Grant
+     v
+trusted harness connector middleware
+     |
+     | verifies grant + exact request hash
+     v
+platform-managed connector
+     |
+     v
+provider
+```
+
+Agent Authority does **not** need the provider secret in this mode.
+
+The harness must be trusted to enforce the grant. The model should not be able to bypass the connector middleware and invoke the privileged connector directly.
+
+## Action Grant
+
+`issueHarnessActionGrant()` creates a short-lived signed token containing only authority metadata and a hash of the exact operation:
+
+- principal ID
+- agent ID
+- mission ID
+- service
+- action
+- exact request fingerprint
+- issued-at time
+- expiration time
+- grant ID
+
+The raw provider credential is never present in the grant.
+
+Default integrations should keep grants very short-lived (for example 15-30 seconds). The implementation rejects TTL values greater than five minutes.
+
+## Exact-request binding
+
+A grant for:
+
+```text
+github.repo.read
+repository = Null-Square/agent-authority
+```
+
+must not authorize:
+
+```text
+github.repo.read
+repository = Null-Square/another-repository
+```
+
+Changing any request field changes the request fingerprint and verification fails.
+
+The same applies to mission, principal and agent substitution.
+
+## Recommended connector wrapper
+
+A harness integration should place grant verification in trusted middleware immediately before its platform-managed connector:
+
+```js
+import { createHarnessConnectorGate } from '@nullsquare/agent-authority/harness-bridge';
+
+const gate = createHarnessConnectorGate({ key: trustedGrantVerificationKey });
+
+async function githubConnector(args, authorityContext) {
+  gate.verify({
+    grant: authorityContext.grant,
+    mission: authorityContext.mission,
+    request: authorityContext.request
+  });
+
+  return platformGitHubConnector(args);
+}
+```
+
+Do not perform verification inside the LLM prompt, model tool description, or other model-controlled context.
+
+## Hosted-harness proof of concept
+
+A hosted harness can therefore use Agent Authority even if it cannot export its internal OAuth tokens:
+
+```text
+ChatGPT / OpenClaw / IDE / enterprise agent
+              |
+              v
+       Agent Authority policy
+              |
+              v
+        signed Action Grant
+              |
+              v
+     harness-owned connector
+```
+
+This mode is intentionally provider-neutral. The same authority runtime can govern a GitHub connector, Gmail connector, Drive connector, Calendar connector, CRM connector or any future platform connector, provided the harness exposes a trustworthy interception point before execution.
+
+## Security requirements
+
+A production harness bridge should also implement:
+
+1. one-time grant consumption or a connector-side replay ledger for mutations;
+2. idempotency for side-effecting operations;
+3. result receipts posted back to the authority audit ledger;
+4. independent harness identity binding;
+5. provider/account/resource normalization before request hashing;
+6. connector middleware that cannot be bypassed by the model.
+
+Harness mode is not a weaker policy model; it is a different credential-ownership model.

package/docs/harness-integration.md

@@ -0,0 +1,223 @@
+# Agent Harness Integration
+
+Agent Authority is designed to work with many agent runtimes without requiring the model provider to adopt a new protocol first.
+
+## Where Agent Authority sits
+
+Agent Authority is **not a model provider and not an agent harness**. It is an authority/control plane between an agent's proposed sensitive action and the system that can actually perform that action.
+
+```text
+User
+  |
+  | connect accounts once + approve missions
+  v
+Agent Authority Wallet / Control Plane
+  |
+  +----------------------+----------------------+
+  |                      |                      |
+Codex                 Claude Code            OpenClaw
+  |                      |                      |
+  +----------- proposed tool/action -----------+
+                         |
+                         v
+                 Agent Authority Runtime
+                 policy / approval / audit
+                         |
+                allow / deny / approve
+                         |
+                         v
+                  Connection Fabric
+            OAuth | MCP | API | CLI | browser
+                         |
+                         v
+                    External service
+```
+
+The **default integration** should be a local sidecar or hosted control-plane API. This makes Agent Authority usable by almost any harness without requiring the harness author to redesign their runtime.
+
+When a harness exposes a trusted pre-tool execution hook, a native plugin can provide a stronger integration by routing all sensitive tool calls through Agent Authority automatically. The authority semantics remain the same in both modes.
+
+### Integration modes
+
+1. **Universal sidecar/API — default.** Any agent or harness calls Agent Authority before sensitive actions. Lowest adoption friction.
+2. **Native harness/plugin middleware — preferred when available.** A trusted plugin intercepts tool actions before execution and sends them through Agent Authority. Harder for an agent to bypass accidentally.
+3. **MCP authority proxy.** Existing MCP clients and servers work through an authority-aware proxy without every server adopting the mission format.
+4. **CLI credential helper.** Commands receive temporary credentials only inside the authorized child process.
+5. **Hosted authority service.** Multiple machines and agents share the same user/org connection wallet, policy, approval and audit layer.
+
+A harness should not need to become "an Agent Authority harness." It should merely know how to ask Agent Authority to authorize/execute a sensitive action.
+
+## Recommended boundary
+
+```text
+LLM / planner
+     |
+     v
+Agent harness
+     |
+     | proposed tool action
+     v
+Agent Authority
+     |
+     +--> deny
+     +--> require human approval
+     |
+     +--> allow
+            |
+            v
+      credential adapter
+            |
+            v
+          tool/service
+```
+
+The authority runtime should ideally execute **outside the model context** so a prompt-injected or compromised agent cannot simply rewrite its own permissions.
+
+## 1. Tool middleware
+
+For a custom agent harness, wrap each sensitive tool:
+
+```js
+const decision = authority.evaluate(mission, {
+  service: 'github',
+  action: 'repo.write',
+  context: { repository: 'Null-Square/example' }
+});
+
+if (decision.result.decision === 'deny') throw new Error(decision.result.reason);
+if (decision.result.decision === 'require_approval') return requestHumanApproval(decision);
+return authority.execute(mission, request);
+```
+
+The preferred production form is `authority.execute(...)`: the provider credential remains inside Agent Authority rather than being returned to the agent process.
+
+## 2. Local sidecar for coding agents
+
+Run `npm start` next to the coding-agent process and call:
+
+- `GET /health`
+- `GET /v1/connections`
+- `POST /v1/evaluate`
+- `POST /v1/prepare`
+- `POST /v1/execute`
+- `POST /v1/revoke`
+
+A harness can use localhost IPC/HTTP even when it cannot embed the JavaScript library directly.
+
+Good targets for early experiments include Codex, Claude Code, Cursor, IDE agents, CI agents, desktop agents, and autonomous terminal workflows.
+
+## 3. OpenClaw
+
+OpenClaw should integrate with Agent Authority **around tools, not by replacing OpenClaw's agent harness**.
+
+OpenClaw defines an agent harness as the low-level executor for a prepared agent turn. Its native Codex harness, for example, owns Codex-native thread execution while OpenClaw continues to own channels, visible transcript state, tool policy and approvals. Agent Authority solves a different problem: whether a tool/service action is authorized under a human-approved mission.
+
+Recommended OpenClaw topology:
+
+```text
+OpenClaw
+  |
+  | Codex / Claude / ACP / embedded runtime
+  v
+proposed sensitive tool call
+  |
+  v
+Agent Authority plugin or sidecar
+  |
+  +--> deny
+  +--> require approval
+  +--> execute through connected account
+  |
+  v
+GitHub / Google / Cloudflare / MCP / other service
+```
+
+Two practical OpenClaw integration paths:
+
+### A. Sidecar first
+
+An OpenClaw tool/plugin calls the local Agent Authority HTTP API. This requires the least coupling and lets us ship immediately.
+
+### B. Trusted native plugin later
+
+Where OpenClaw exposes a suitable pre-execution tool/policy seam, a trusted Agent Authority plugin should automatically wrap sensitive tools. The plugin should still delegate policy, connections, credentials, receipts and revocation to the external Agent Authority control plane rather than duplicating them inside OpenClaw.
+
+OpenClaw can also run external coding harnesses through ACP. Agent Authority should remain outside those harnesses as the common service-authority layer so a Codex ACP session and a Claude Code ACP session can reuse the same connected accounts and mission semantics.
+
+Important distinction: **model-provider login and service authorization are separate concerns.** OpenClaw/Codex/Claude may still need their own model/subscription authentication. Agent Authority's first target is the GitHub/Google/Cloudflare/SaaS/cloud credentials that agents use to perform work. Provider-model authentication can be bridged later where safe and useful.
+
+## 4. MCP proxy
+
+```text
+MCP client
+    |
+    v
+Agent Authority MCP proxy
+    |      |
+    |      +--> mission evaluation
+    |      +--> approval callback
+    |      +--> upstream credential brokerage
+    |      +--> receipt
+    v
+Upstream MCP server
+```
+
+The proxy lets existing MCP clients gain mission-scoped controls without requiring every MCP server to understand Agent Authority.
+
+## 5. Connector/plugin platform
+
+Connector providers already know how to call hundreds of SaaS APIs. Agent Authority can wrap those connectors rather than rebuilding every integration.
+
+```text
+agent -> authority -> connector adapter -> SaaS
+```
+
+This is especially important for OAuth and API-key services: the connector holds or exchanges credentials while the authority layer decides whether the specific mission can invoke the action.
+
+## 6. CLI credential helper
+
+A future helper should support flows conceptually like:
+
+```bash
+agent-authority exec \
+  --mission mission.json \
+  --service github \
+  --action repo.write \
+  -- git push
+```
+
+The helper should expose an ephemeral token/environment only to the child process, not to the LLM prompt or durable agent memory.
+
+## 7. Browser-only legacy applications
+
+For services with no API or usable OAuth integration, the adapter may need an isolated browser/session broker. The preferred model is:
+
+```text
+agent -> high-level browser action -> authority -> isolated authenticated browser
+```
+
+The agent should not receive raw passwords, long-lived cookies, or unrestricted browser access. This area is high risk and should remain experimental until isolation and anti-exfiltration boundaries are well tested.
+
+## Human approval UX
+
+Approval must be portable across harnesses. A decision should include enough data for terminal, IDE, mobile, or web approval surfaces to explain:
+
+- mission objective
+- agent identity
+- requested service/action
+- resource being affected
+- financial or destructive impact
+- expiration/delegation context
+
+The human approves the **action under the mission**, not a generic permanent permission.
+
+## Integration acceptance test
+
+A harness integration is successful when the same mission can:
+
+1. allow a safe action,
+2. deny a forbidden action,
+3. pause for approval,
+4. revoke the mission and stop future actions,
+5. use a credential mechanism without exposing a permanent root secret to the model,
+6. move between at least two harnesses without reconnecting the user's provider account.