@nullsquare/agent-authority 0.4.0

package/docs/task-leases.md

@@ -0,0 +1,253 @@
+# Task Leases and Derived Authority
+
+Agent Authority's current product thesis is simple:
+
+> Give an agent a task, not standing account permissions.
+
+A **Task Lease** is a temporary enforcement context around an existing mission. The mission remains the maximum authority ceiling. The lease can only narrow that authority as the task discovers concrete resources.
+
+## Why this exists
+
+A human request often does not contain every resource identifier the agent will need.
+
+Example:
+
+> Handle the demo request in this email thread.
+
+At task start the runtime may know only the Gmail thread ID. During authorized execution it discovers the sender email. That sender may then become the only attendee the agent is allowed to use when creating a calendar event.
+
+Without a task-aware authority layer, the application usually chooses between two bad options:
+
+1. give the agent broad `calendar.write` / `mail.send` permissions; or
+2. ask the human to approve every individual tool call.
+
+Task Leases aim for a third option: **task-bounded autonomy**.
+
+## Core model
+
+```text
+Human-approved task
+        |
+        v
+  authority roots
+        |
+ authorized execution
+        |
+        v
+  derived facts
+        |
+ exact action bindings
+        |
+        v
+      effect
+```
+
+### Authority root
+
+A value explicitly trusted at task entry.
+
+Examples:
+
+- `gmail.thread = thread:91`
+- `github.issue = 42`
+- `invoice.id = INV-2026-18`
+
+Roots do not require a prior execution receipt because they come from the task's trusted entry boundary.
+
+### Derived fact
+
+A value learned while performing the task.
+
+Examples:
+
+- sender email discovered from an authorized Gmail thread read;
+- customer ID discovered from an authorized support-ticket lookup;
+- order ID discovered from an authorized customer lookup.
+
+In v0.4, a derived fact must reference an `ALLOW` receipt from the same mission. It may also reference existing parent facts.
+
+### Binding
+
+A binding narrows an otherwise permitted action to the exact value held by an authority fact.
+
+```js
+{
+  service: 'calendar',
+  action: 'event.create',
+  context_field: 'attendee',
+  fact_id: 'fact:requester-email'
+}
+```
+
+If `fact:requester-email` has not been established, the action is denied.
+
+If it has value `customer@example.com`, this request can proceed:
+
+```js
+{
+  service: 'calendar',
+  action: 'event.create',
+  context: { attendee: 'customer@example.com' }
+}
+```
+
+This request does not proceed automatically:
+
+```js
+{
+  service: 'calendar',
+  action: 'event.create',
+  context: { attendee: 'other@example.com' }
+}
+```
+
+It returns `REQUIRE_APPROVAL` with `authority_delta_required`.
+
+## Non-amplification rule
+
+A Task Lease is not a second policy engine and cannot grant a new action class.
+
+The existing mission is always evaluated first.
+
+```text
+mission says DENY
+      |
+      v
+Task Lease cannot override it
+```
+
+The lease can only add restrictions to an action that the mission already allows.
+
+This is the key invariant:
+
+```text
+lease authority <= mission authority
+```
+
+Authority may stay the same or shrink. It must never grow silently.
+
+## Example
+
+```js
+import { AuthorityRuntime } from '@nullsquare/agent-authority';
+import { createTaskLease } from '@nullsquare/agent-authority/task-lease';
+import { createTaskLeaseGuard } from '@nullsquare/agent-authority/guard';
+
+const lease = createTaskLease({
+  mission,
+  request: 'Handle the demo request in thread:demo-91',
+  roots: [
+    { fact_id: 'fact:thread', kind: 'gmail.thread', value: 'thread:demo-91' }
+  ],
+  bindings: [
+    {
+      service: 'calendar',
+      action: 'event.create',
+      context_field: 'attendee',
+      fact_id: 'fact:sender-email'
+    }
+  ]
+});
+
+const guard = createTaskLeaseGuard({
+  lease,
+  runtime: new AuthorityRuntime()
+});
+
+const read = await guard.run({
+  service: 'gmail',
+  action: 'thread.read',
+  context: { thread: 'thread:demo-91' }
+}, () => gmail.readThread('thread:demo-91'));
+
+lease.derive({
+  fact_id: 'fact:sender-email',
+  kind: 'email.address',
+  value: read.output.sender,
+  from: ['fact:thread'],
+  receipt: read.receipt,
+  selector: 'output.sender'
+});
+
+await guard.run({
+  service: 'calendar',
+  action: 'event.create',
+  context: { attendee: read.output.sender }
+}, () => calendar.createEvent({ attendee: read.output.sender }));
+```
+
+Run the self-contained example:
+
+```bash
+npm run demo:task-lease
+```
+
+## Task completion
+
+Task authority should not outlive the task.
+
+```js
+lease.complete('demo request handled');
+```
+
+After completion, every guarded action returns `DENY` with `task_lease_completed` even if the underlying OAuth token or provider connection still exists.
+
+A lease may also have its own `expires_at` independent of provider credential expiry.
+
+## Authority delta
+
+When the agent asks to use a concrete value outside an established binding, Agent Authority returns a step-up signal rather than silently broadening the lease.
+
+```text
+current task authority
+        +
+requested new resource
+        |
+        v
+authority_delta_required
+```
+
+The existing approval store can handle the human decision. Automatically applying approved deltas to a live Task Lease is a later milestone; v0.4 deliberately stops at the safe enforcement signal.
+
+## Current security properties
+
+The v0.4 implementation tests that:
+
+- a bound action cannot run before its fact exists;
+- derived facts require an `ALLOW` receipt;
+- the receipt must belong to the same mission;
+- explicit mission denies cannot be overridden by lease bindings;
+- an exact derived resource can execute;
+- a different resource becomes an authority delta and the effect does not run;
+- completed and expired leases stop execution;
+- Task Lease receipts include the lease ID and lease hash.
+
+## Current limitations
+
+This is still a validation implementation.
+
+1. **Extraction trust:** the trusted host/adapter supplies the derived value and selector. Agent Authority records lineage but does not yet cryptographically prove that the selected output field contained that value.
+2. **In-memory lease state:** TaskLease instances are currently process-local. Durable lease persistence/recovery is not implemented yet.
+3. **Top-level binding fields:** v0.4 binds top-level request context fields only. Nested JSON-path policy is intentionally deferred.
+4. **Step-up application:** authority deltas are surfaced but approved deltas are not yet automatically applied back into the lease.
+5. **Adapter semantics:** providers still need trustworthy mappings from an external operation to `service`, `action`, and resource context fields.
+
+These constraints are deliberate. The next work should be driven by real integrations rather than by adding a general policy language.
+
+## Validation target
+
+The product thesis is validated when the same Task Lease can safely govern a real multi-step workflow across more than one execution transport, for example:
+
+```text
+one human task
+     |
+     +--> ordinary SDK through guard.run()
+     |
+     +--> MCP tool through Agent Authority gateway
+     |
+     +--> brokered provider execution
+
+same authority lineage
+same non-amplification rule
+same completion boundary
+```

package/docs/validation.md

@@ -0,0 +1,124 @@
+# Validate Agent Authority in 5 minutes
+
+The goal of this validation is deliberately narrow:
+
+> A real MCP host should only be able to call the tool + resource allowed by a human mission, while the upstream provider/tool remains unaware of Agent Authority.
+
+This is a product-layer test, not a benchmark and not a claim of production readiness.
+
+## What this proves
+
+The repository includes:
+
+- an Agent Authority MCP gateway (`aauth mcp proxy`)
+- a tiny validation upstream with one real read-only GitHub metadata tool
+- one fake write-capable tool that must never pass the gateway in read-only mode
+- a canonical mission restricted to `Null-Square/agent-authority`
+- wire-level tests using the official MCP v2 client SDK
+
+The path is:
+
+```text
+MCP host
+  -> Agent Authority
+       -> mission policy
+            -> allowed read-only tool
+                 -> validation MCP upstream
+                      -> public GitHub API
+```
+
+## 1. Install and initialize
+
+```bash
+npm install
+npm link
+
+aauth setup --principal user:local
+aauth doctor
+```
+
+## 2. Run the tiny validation upstream
+
+Terminal A:
+
+```bash
+npm run demo:mcp-upstream
+```
+
+It listens on `http://127.0.0.1:8791/mcp` and advertises two tools:
+
+- `github_repo_metadata` — explicitly read-only; reads public GitHub repository metadata
+- `dangerous_demo_write` — harmless fake mutation used only to prove the gateway blocks write-capable tools
+
+## 3. Put Agent Authority in front of it
+
+Terminal B:
+
+```bash
+aauth mcp proxy \
+  --upstream http://127.0.0.1:8791/mcp \
+  --mission examples/missions/chatgpt-web-validation.json \
+  --service mcp:validation-upstream
+```
+
+The gateway listens on `http://127.0.0.1:8790/mcp`.
+
+It intentionally binds loopback only and refuses a public bind in this release.
+
+## Expected behavior
+
+A client connected to the Agent Authority gateway should:
+
+1. see `github_repo_metadata`
+2. not see the fake write-capable tool in read-only mode
+3. succeed for:
+
+```json
+{
+  "name": "github_repo_metadata",
+  "arguments": {
+    "repository": "Null-Square/agent-authority"
+  }
+}
+```
+
+4. be denied if it changes the repository to another value
+5. be denied if it tries to call the write-capable tool directly even if it knows the upstream tool name
+
+The key property is #5: hiding a tool is UX; enforcing `tools/call` is the security boundary.
+
+## Automated proof
+
+Run:
+
+```bash
+npm test
+```
+
+The MCP tests cover the gateway policy directly and use the official MCP v2 client against the actual Agent Authority handler. No external provider credentials are required.
+
+## ChatGPT / hosted OpenAI validation
+
+ChatGPT cannot connect directly to a localhost MCP server. OpenAI supports Secure MCP Tunnel for connecting local/private MCP servers to supported OpenAI products without exposing the server publicly.
+
+Use the official `openai/tunnel-client` quickstart (`tunnel-client help quickstart`) and point the tunnel at:
+
+```text
+http://127.0.0.1:8790/mcp
+```
+
+Then configure the resulting tunnel-backed MCP endpoint/app in the supported OpenAI product.
+
+Product/plan availability for custom MCP apps changes over time; if the ChatGPT workspace does not expose custom MCP app creation, the same tunnel endpoint can be validated from another supported OpenAI surface or any MCP v2 client. Do not weaken Agent Authority security merely to work around a UI/plan limitation.
+
+## Pass/fail criterion
+
+The validation passes only if all of these are true:
+
+- the host discovers the authorized read-only tool
+- the authorized repository read succeeds
+- an out-of-mission repository is rejected before reaching the upstream tool
+- a write-capable tool is rejected before reaching the upstream tool
+- changing the host does not require changing the mission semantics
+
+If those conditions hold from ChatGPT and from at least one non-OpenAI MCP client, we have useful validation that Agent Authority is the policy layer rather than an OpenAI-specific connector.

package/examples/demo.js

@@ -0,0 +1,19 @@
+import fs from 'node:fs';
+import { AdapterRegistry, AuthorityRuntime, descriptorAdapter } from '../src/index.js';
+
+const mission = JSON.parse(fs.readFileSync(new URL('./mission.json', import.meta.url)));
+const adapters = new AdapterRegistry()
+  .register(descriptorAdapter('oauth', ['github', 'google']))
+  .register(descriptorAdapter('api-key', ['cloudflare']));
+const runtime = new AuthorityRuntime({ adapters });
+
+for (const request of [
+  { service: 'github', action: 'repo.write' },
+  { service: 'github', action: 'repo.delete' },
+  { service: 'google', action: 'gmail.send' },
+  { service: 'cloudflare', action: 'workers.deploy' },
+  { service: 'stripe', action: 'payment.create' }
+]) {
+  const output = await runtime.prepare(mission, request);
+  console.log(`${request.service}:${request.action} -> ${output.result.decision}`);
+}

package/examples/direct-guard.js

@@ -0,0 +1,50 @@
+import { AuthorityRuntime } from '../src/index.js';
+import { createAuthorityGuard } from '../src/guard.js';
+
+const mission = {
+  version: '0.1',
+  mission_id: 'mission:direct-guard-demo',
+  principal: { id: 'user:demo' },
+  agent: { id: 'agent:demo' },
+  objective: 'Inspect only the Agent Authority public repository',
+  resources: [{
+    service: 'github',
+    allow: ['repo.read'],
+    deny: ['repo.delete', 'repo.write'],
+    constraints: { repository: ['Null-Square/agent-authority'] }
+  }]
+};
+
+const guard = createAuthorityGuard({
+  mission,
+  runtime: new AuthorityRuntime(),
+  onDecision: ({ result, receipt }, request) => {
+    console.log(`${result.decision.toUpperCase()} ${request.service}:${request.action} receipt=${receipt.receipt_hash}`);
+  }
+});
+
+const repository = process.argv[2] || 'Null-Square/agent-authority';
+
+try {
+  const { output } = await guard.run({
+    service: 'github',
+    action: 'repo.read',
+    context: { repository }
+  }, async () => {
+    const response = await fetch(`https://api.github.com/repos/${repository}`, {
+      headers: { accept: 'application/vnd.github+json', 'user-agent': 'agent-authority-direct-guard-demo' }
+    });
+    if (!response.ok) throw new Error(`GitHub returned ${response.status}`);
+    const repo = await response.json();
+    return {
+      full_name: repo.full_name,
+      visibility: repo.visibility,
+      default_branch: repo.default_branch
+    };
+  });
+
+  console.log(JSON.stringify(output, null, 2));
+} catch (error) {
+  console.error(`${error.name}: ${error.message}`);
+  process.exitCode = 2;
+}

package/examples/harness-managed-connectors.js

@@ -0,0 +1,72 @@
+import { randomBytes } from 'node:crypto';
+import { AuthorityRuntime } from '../src/index.js';
+import { issueHarnessActionGrant, createHarnessConnectorGate } from '../src/harness-bridge.js';
+
+const signingKey = randomBytes(32);
+const authority = new AuthorityRuntime();
+const gate = createHarnessConnectorGate({ key: signingKey });
+
+const mission = {
+  version: '0.1',
+  mission_id: 'mission:hosted-harness-demo',
+  principal: { id: 'user:example' },
+  agent: { id: 'agent:hosted-harness:session-1' },
+  objective: 'Read an approved GitHub repository through a harness-managed connector',
+  resources: [
+    {
+      service: 'github',
+      allow: ['repo.read'],
+      deny: ['repo.write', 'repo.delete'],
+      constraints: { repository: ['Null-Square/agent-authority'] }
+    }
+  ]
+};
+
+const request = {
+  service: 'github',
+  action: 'repo.read',
+  context: { repository: 'Null-Square/agent-authority' }
+};
+
+// 1. Agent Authority evaluates the human-approved mission.
+const evaluation = authority.evaluate(mission, request);
+if (evaluation.result.decision !== 'allow') {
+  console.error(evaluation.result);
+  process.exit(1);
+}
+
+// 2. Trusted authority code issues a short-lived grant for the exact request.
+const { token: grant } = issueHarnessActionGrant({
+  key: signingKey,
+  mission,
+  request,
+  ttl_seconds: 30
+});
+
+// 3. This represents trusted harness connector middleware. The provider token
+// stays inside the hosted platform; Agent Authority never needs to see it.
+async function harnessGitHubConnector({ grant, mission, request }) {
+  gate.verify({ grant, mission, request });
+
+  // Replace this stub with the harness-owned GitHub connector. For example,
+  // a hosted platform may already have the user's GitHub OAuth connection.
+  return {
+    provider: 'github',
+    repository: request.context.repository,
+    executed_by: 'harness-managed-connector',
+    provider_credential_exposed_to_agent_authority: false
+  };
+}
+
+console.log(await harnessGitHubConnector({ grant, mission, request }));
+
+// Changing the resource after authorization must fail verification.
+try {
+  await harnessGitHubConnector({
+    grant,
+    mission,
+    request: { ...request, context: { repository: 'Null-Square/other-repository' } }
+  });
+} catch (error) {
+  console.log(`blocked substitution: ${error.code}`);
+}