@nullsquare/agent-authority 0.4.3 → 0.4.4

package/README.md

@@ -8,9 +8,9 @@
 
 **Agent Authority turns a human-approved task into temporary execution authority, then keeps that authority bounded as the agent discovers resources, crosses tools, and performs side effects.**
 
-[Task Leases](docs/task-leases.md) · [Validate](docs/validation.md) · [Google proof](docs/live-google-validation.md) · [Integration contract](docs/integration-contract.md) · [CLI](docs/cli.md) · [Architecture](docs/architecture.md) · [Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md)
+[Task Leases](docs/task-leases.md) · [Executable evidence](docs/evidence.md) · [Extractor conformance](docs/authority-extractor-conformance.md) · [Google proof](docs/live-google-validation.md) · [Integration contract](docs/integration-contract.md) · [CLI](docs/cli.md) · [Architecture](docs/architecture.md) · [Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md)
 
-> **Status: public pre-alpha / v0.4.2 Developer Preview.** Published on npm as `@nullsquare/agent-authority`. The repository has a working policy runtime, protocol-neutral guard, Task Lease prototype, execution-bound derived facts, approvals, revocation, idempotency, credential isolation, MCP v2 gateway, GitHub and Google provider integrations, CI and CodeQL. It is not production-ready yet.
+> **Status: public pre-alpha / v0.4.3 Developer Preview.** Published on npm as `@nullsquare/agent-authority`. The repository has a working policy runtime, protocol-neutral guard, Task Lease prototype, execution-bound derived facts, reviewed Google and GitHub authority extractors, two-provider conformance tests, approvals, revocation, idempotency, credential isolation, MCP v2 gateway, live GitHub proofs, CI and CodeQL. It is not production-ready yet.
 
 </div>
 
@@ -158,7 +158,9 @@ The demo performs this flow without provider credentials:
 
 The side-effect callbacks for blocked actions never run.
 
-The repository also includes a real Gmail → Calendar validation path and a reusable Google provider adapter. The stricter v0.4.2 path binds the derived sender to the exact guarded output before it becomes authority. See [Live Gmail → Calendar validation](docs/live-google-validation.md) and [Executable Evidence](docs/evidence.md).
+The repository also includes a real Gmail → Calendar validation path and a reusable Google provider adapter. The strict path binds the derived sender to the exact guarded output before it becomes authority. See [Live Gmail → Calendar validation](docs/live-google-validation.md) and [Executable Evidence](docs/evidence.md).
+
+v0.4.3 applies the **same primitive to GitHub**: a root-bound repository + fixture marker are used by the reviewed GitHub adapter to select one issue from a real `issue.list` response; `deriveFromEvidence()` establishes that exact issue number as downstream authority; one real comment mutation succeeds; unrelated and post-completion issue mutations never reach the provider. Google and GitHub are now exercised by the same [authority extractor conformance contract](docs/authority-extractor-conformance.md).
 
 ## Minimal developer API
 
@@ -264,6 +266,8 @@ The long-term validation target is the **same Task Lease and authority lineage a
 - execution evidence binding an allowed receipt, request and exact output hash
 - strict `deriveFromEvidence()` path where the caller cannot provide the authority value
 - reviewed Gmail sender authority extractor bound to `gmail:thread.read`
+- reviewed GitHub selected-issue-number extractor bound to marker-scoped `github:issue.list`
+- shared Google/GitHub authority-extractor conformance suite
 - legacy host-trusted `derive()` compatibility path
 - required parent lineage and extraction selector
 - exact context-field bindings
@@ -288,6 +292,7 @@ The long-term validation target is the **same Task Lease and authority lineage a
 - AES-256-GCM local encrypted secret store
 - safe reconnect cleanup
 - GitHub brokered execution without returning the token to the agent
+- GitHub REST mappings for repository access plus evidence-derived `issue.list` / `issue.comment`
 - Google REST provider mappings for Gmail thread reads and Calendar event mutations
 - short-lived signed local agent-instance tokens
 - local CLI/daemon
@@ -296,11 +301,12 @@ The long-term validation target is the **same Task Lease and authority lineage a
 
 - adversarial authorization tests
 - execution-evidence substitution, tampering, replay, cross-lease and selector tests
+- the same provider-derived-authority conformance attacks against Google and GitHub
 - Node 20 and Node 22 CI
 - coverage run
 - package checks
 - clean-consumer npm registry verification
-- live GitHub read and mutation proofs
+- live GitHub read and evidence-derived mutation proofs
 - CodeQL
 
 ## What is different from OAuth, IAM and MCP authorization?

package/ROADMAP.md

@@ -97,17 +97,21 @@ Do **not** build a general semantic policy language unless real integrations req
 
 **Success criterion:** provider-derived authority cannot be established through the strict path unless the exact guarded output, ALLOW receipt and reviewed extractor contract agree on the selected value. This behavior is now exercised across two provider mappings. Stronger provider attestation and source invalidation remain separate follow-on problems.
 
-## M4 — Same task, multiple transports
+## M4 — Same task, multiple transports — first proof established
 
 Prove Agent Authority is not an MCP product or SDK wrapper.
 
-- [ ] same Task Lease through ordinary `guard.run()` SDK call
-- [ ] same Task Lease through MCP gateway
-- [ ] same Task Lease through brokered provider execution
+- [x] same Task Lease through ordinary `guard.run()` SDK call
+- [x] same Task Lease through MCP gateway
+- [x] same Task Lease through brokered provider execution
 - [ ] at least one non-bypassable harness/tool-middleware integration
-- [ ] interoperability test vectors across transports
+- [x] interoperability test vectors across transports
 
-**Success criterion:** changing transport or harness does not expand the task's authority.
+`test/transport-invariance.test.js` establishes one `execution-evidence-v1` derived fact from brokered execution, then reuses that exact Task Lease and fact through direct SDK, MCP and brokered execution. The three paths produce the same `allow`, `authority_delta_required` and `task_lease_completed` outcomes, and blocked attempts execute zero host callbacks, MCP upstream calls or brokered provider operations.
+
+Brokered Task Lease execution deliberately does not consume mission-level one-time approval to override a lease-level authority delta. Updating a live Task Lease after explicit approval remains separate M2 work.
+
+**Success criterion:** changing transport or harness does not expand the task's authority. The SDK/MCP/broker portion is now demonstrated in-process; an external non-bypassable harness/tool-middleware integration remains the final M4 proof.
 
 ## M5 — Production credential and approval UX
 

package/docs/npm-release.md

@@ -13,19 +13,24 @@ Before any publication:
 After publication, verify from a fresh project with:
 
 ```bash
-npm install @nullsquare/agent-authority@0.4.2
+npm install @nullsquare/agent-authority@0.4.3
 ```
 
 Then run the same consumer smoke flow through the registry-installed package. Registry verification is part of the release gate; a successful `npm publish` command alone is not sufficient.
 
-The repository also includes `.github/workflows/verify-npm-registry.yml`, which verifies registry visibility and a clean consumer install. For v0.4.2 it additionally verifies the public `@nullsquare/agent-authority/authority-evidence` export plus the Google provider and Gmail authority-extractor exports.
+The repository also includes `.github/workflows/verify-npm-registry.yml`, which verifies registry visibility and a clean consumer install. For v0.4.3 it additionally verifies the public `@nullsquare/agent-authority/authority-evidence` API plus both reviewed provider authority extractors:
+
+- `gmailThreadSenderAuthorityExtractor` from `@nullsquare/agent-authority/providers/google`;
+- `githubIssueListSelectedNumberAuthorityExtractor` from `@nullsquare/agent-authority/providers/github`.
+
+This makes the registry artifact verification cover the same two-provider execution-evidence surface exercised by the repository conformance suite.
 
 ## npm vs GitHub release surfaces
 
 Publishing to the public npm registry does not automatically create either a GitHub Release or a GitHub Packages entry.
 
 - **npm registry** — `npm publish --access public` publishes `@nullsquare/agent-authority` to `registry.npmjs.org` / npmjs.com. This is the package users install with `npm install`.
-- **GitHub Releases** — a separate GitHub object, normally backed by a Git tag such as `v0.4.2`. A release must be created explicitly or by release automation.
+- **GitHub Releases** — a separate GitHub object, normally backed by a Git tag such as `v0.4.3`. A release must be created explicitly or by release automation.
 - **GitHub Packages** — a separate package registry. It only appears when the package is published to GitHub's npm registry (`npm.pkg.github.com`); publishing to npmjs.com does not populate it.
 
 Agent Authority currently uses npmjs.com as its public package registry. Therefore an empty GitHub **Packages** section is expected unless the project intentionally adopts dual publication. A GitHub **Release** is still useful for source-release discoverability and should track published versions, but it is independent from npm publication.

package/docs/transport-invariance.md

@@ -0,0 +1,117 @@
+# Task Lease transport invariance
+
+Agent Authority treats SDK calls, MCP calls and brokered provider execution as execution paths, not separate authority models.
+
+The property under test is:
+
+```text
+same Task Lease + same established authority fact
+                     |
+          +----------+----------+
+          |          |          |
+       direct       MCP      brokered
+       guard.run()  gateway   provider
+          |          |          |
+          +----------+----------+
+                     |
+              same authority
+```
+
+Changing the transport must not broaden task authority.
+
+## Executable proof
+
+`test/transport-invariance.test.js` creates one Task Lease and one derived authority fact.
+
+The fact is first established from a brokered provider result using the strict evidence path:
+
+```text
+Task Lease root
+    |
+    v
+brokered item.discover
+    |
+    +--> Task-Lease ALLOW receipt
+    +--> exact output hash evidence
+    |
+    v
+reviewed test extractor
+    |
+    v
+deriveFromEvidence()
+    |
+    v
+fact:selected-item = alpha
+```
+
+That exact Task Lease and fact are then used through three execution paths:
+
+1. ordinary in-process `guard.run()`;
+2. `MissionMcpGateway` configured with the Task Lease;
+3. `ExecutingAuthorityRuntime.executeTaskLease()` with a brokered provider adapter.
+
+For `item = alpha`, every path allows execution.
+
+For `item = beta`, every path returns the same task-level authority delta:
+
+```text
+authority_delta_required
+```
+
+The blocked direct callback, MCP upstream call and brokered provider operation all remain unexecuted.
+
+After the Task Lease is completed, all three paths return:
+
+```text
+task_lease_completed
+```
+
+Again, no blocked execution reaches the host callback or provider boundary.
+
+## Broker behavior
+
+`ExecutingAuthorityRuntime.executeTaskLease()` evaluates the Task Lease before adapter readiness or provider execution.
+
+A lease-level `require_approval` result is returned as-is. Brokered execution does not consume a mission-level one-time approval to bypass the narrower Task Lease. Applying an explicitly approved authority delta back into a live Task Lease is separate roadmap work.
+
+Successful brokered Task Lease execution returns execution evidence bound to the Task-Lease receipt and exact provider output, so strict derived authority can originate from brokered execution as well as from `guard.run()`.
+
+## MCP behavior
+
+`MissionMcpGateway` remains backward-compatible with Mission-only use, but now accepts exactly one authority source:
+
+```text
+mission OR lease
+```
+
+When configured with a Task Lease, each tool call is evaluated through that lease before `upstream.callTool()` can run.
+
+MCP result metadata includes:
+
+```text
+io.nullsquare.agent-authority/decision
+io.nullsquare.agent-authority/code
+io.nullsquare.agent-authority/receipt_hash
+io.nullsquare.agent-authority/task_lease_id
+```
+
+The remote MCP handler and loopback proxy can pass the same Task Lease into the gateway.
+
+## What this proves
+
+- Task-Lease narrowing is no longer specific to the direct SDK guard;
+- MCP cannot silently fall back to Mission-only authority when explicitly configured with a Task Lease;
+- brokered provider execution can enforce the same Task Lease before credential-backed execution;
+- one derived fact can constrain all three execution paths;
+- task completion invalidates the same authority across all three paths;
+- broker credentials may remain connected after task authority disappears.
+
+## What this does not prove yet
+
+- a hostile harness cannot bypass Agent Authority through an entirely separate unguarded tool path;
+- Task Lease state survives process restart;
+- the same lease is serialized and recovered across separate processes or hosts;
+- an approved authority delta is durably applied back into a running lease;
+- provider outputs are cryptographically attested by providers.
+
+The remaining M4 target is at least one real harness/tool-middleware integration where executable tool calls cannot bypass the Task Lease boundary.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nullsquare/agent-authority",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "Task-bounded authority runtime for AI agents: give agents tasks, not standing account permissions.",
   "license": "Apache-2.0",
   "type": "module",

package/src/execution.js

@@ -1,4 +1,5 @@
 import { AuthorityRuntime, createReceipt } from './index.js';
+import { createExecutionEvidence } from './authority-evidence.js';
 
 function executionFailure(mission, request, code, reason, extra = {}) {
   const result = { decision: 'deny', code, reason, ...extra };
@@ -115,10 +116,39 @@ export class ExecutingAuthorityRuntime extends AuthorityRuntime {
     }
   }
 
-  async execute(missionInput, request) {
-    let evaluation = this.evaluate(missionInput, request);
+  /**
+   * Execute through the broker while preserving Task Lease narrowing.
+   *
+   * A lease-level REQUIRE_APPROVAL is returned before adapter readiness or
+   * provider execution. It is not converted into a mission-level one-time
+   * approval because applying an authority delta back into a live lease is a
+   * separate, not-yet-implemented capability.
+   */
+  async executeTaskLease(lease, request) {
+    if (!lease || typeof lease.evaluate !== 'function' || !lease.mission) {
+      throw new Error('task lease with mission and evaluate() is required');
+    }
+    return this.execute(lease.mission, request, { lease });
+  }
+
+  async execute(missionInput, request, { lease = null } = {}) {
+    if (lease && lease.mission?.mission_id !== missionInput?.mission_id) {
+      throw new Error('task lease mission does not match execution mission');
+    }
+
+    let evaluation = lease
+      ? lease.evaluate(this, request)
+      : this.evaluate(missionInput, request);
+
     if (evaluation.result.decision === 'deny') return { ...evaluation, output: null };
 
+    // A Task Lease is the narrowest authority object. Do not let brokered
+    // execution reinterpret a lease-level authority delta as a broader mission
+    // approval. This keeps broker behavior aligned with guard.run() and MCP.
+    if (lease && evaluation.result.decision !== 'allow') {
+      return { ...evaluation, output: null };
+    }
+
     const adapter = this.adapters.resolve(request.service);
     if (!adapter) {
       return executionFailure(missionInput, request, 'adapter_unavailable', `no adapter is registered for ${request.service}`);
@@ -148,6 +178,7 @@ export class ExecutingAuthorityRuntime extends AuthorityRuntime {
 
     try {
       const output = await adapter.execute({ mission: missionInput, request });
+      const evidence = createExecutionEvidence({ receipt: evaluation.receipt, output });
       let usage = null;
       if (budgetCheck && !budgetCheck.result) {
         const spent = this.usage.record(missionInput.mission_id, budgetCheck.currency, budgetCheck.amount);
@@ -160,7 +191,7 @@ export class ExecutingAuthorityRuntime extends AuthorityRuntime {
       if (executionRecord && this.executions) {
         this.executions.complete({ mission: missionInput, request, receipt_id: evaluation.receipt?.receipt_id || null });
       }
-      return { ...evaluation, output, usage, execution: executionRecord || null };
+      return { ...evaluation, output, evidence, usage, execution: executionRecord || null };
     } catch (error) {
       if (executionRecord && this.executions) {
         this.executions.uncertain({ mission: missionInput, request, error_code: error.code || 'provider_error' });

package/src/mcp-gateway.js

@@ -31,6 +31,15 @@ export function isDeclaredReadOnlyTool(tool) {
   return tool?.annotations?.readOnlyHint === true;
 }
 
+function authorityMeta(evaluation = {}) {
+  return {
+    'io.nullsquare.agent-authority/decision': evaluation.result?.decision || 'deny',
+    'io.nullsquare.agent-authority/code': evaluation.result?.code || null,
+    'io.nullsquare.agent-authority/receipt_hash': evaluation.receipt?.receipt_hash || null,
+    'io.nullsquare.agent-authority/task_lease_id': evaluation.receipt?.task_lease_id || null
+  };
+}
+
 function deniedToolResult(result, extra = {}) {
   return {
     content: [{
@@ -47,32 +56,43 @@ function deniedToolResult(result, extra = {}) {
 }
 
 /**
- * Small, transport-neutral policy gateway for MCP tools.
+ * Small policy gateway for MCP tools.
  *
  * The upstream object only needs two methods:
  *   listTools(params?) -> { tools: [...] }
  *   callTool(params)   -> MCP CallToolResult
  *
- * v0.1 deliberately defaults to read-only enforcement. A tool is considered
+ * The gateway accepts either a Mission or a Task Lease. When a Task Lease is
+ * supplied, every MCP tool call is evaluated through that exact lease before
+ * the upstream callback can run. This keeps transport changes from bypassing
+ * task-level narrowing.
+ *
+ * The gateway still defaults to read-only enforcement. A tool is considered
  * read-only only when its MCP annotations explicitly set readOnlyHint=true.
- * Write support belongs behind the existing approval + idempotency runtime and
- * is intentionally not inferred from tool names.
+ * Write support must be enabled deliberately; it is never inferred from names.
  */
 export class MissionMcpGateway {
   constructor({
     mission,
+    lease,
     runtime,
     upstream,
     service = 'mcp:upstream',
     readOnly = true,
     contextMapper = contextFromToolArguments
   } = {}) {
-    if (!mission) throw new Error('mission is required');
+    if ((mission && lease) || (!mission && !lease)) {
+      throw new Error('provide exactly one of mission or lease');
+    }
+    if (lease && (typeof lease.evaluate !== 'function' || !lease.mission)) {
+      throw new Error('lease must provide mission and evaluate(runtime, request)');
+    }
     if (!runtime || typeof runtime.evaluate !== 'function') throw new Error('authority runtime is required');
     if (!upstream || typeof upstream.listTools !== 'function' || typeof upstream.callTool !== 'function') {
       throw new Error('upstream MCP client must implement listTools() and callTool()');
     }
-    this.mission = mission;
+    this.mission = mission || lease.mission;
+    this.lease = lease || null;
     this.runtime = runtime;
     this.upstream = upstream;
     this.service = service;
@@ -81,6 +101,12 @@ export class MissionMcpGateway {
     this.tools = new Map();
   }
 
+  evaluate(request) {
+    return this.lease
+      ? this.lease.evaluate(this.runtime, request)
+      : this.runtime.evaluate(this.mission, request);
+  }
+
   async refreshTools(params = undefined) {
     const listed = await this.upstream.listTools(params);
     for (const tool of listed.tools || []) this.tools.set(tool.name, tool);
@@ -122,11 +148,9 @@ export class MissionMcpGateway {
       action: mcpToolAction(toolName),
       context
     };
-    const evaluation = this.runtime.evaluate(this.mission, request);
+    const evaluation = this.evaluate(request);
     if (evaluation.result.decision !== 'allow') {
-      return deniedToolResult(evaluation.result, {
-        'io.nullsquare.agent-authority/receipt_hash': evaluation.receipt?.receipt_hash || null
-      });
+      return deniedToolResult(evaluation.result, authorityMeta(evaluation));
     }
 
     const output = await this.upstream.callTool(params);
@@ -134,8 +158,7 @@ export class MissionMcpGateway {
       ...output,
       _meta: {
         ...(output?._meta || {}),
-        'io.nullsquare.agent-authority/decision': 'allow',
-        'io.nullsquare.agent-authority/receipt_hash': evaluation.receipt?.receipt_hash || null
+        ...authorityMeta(evaluation)
       }
     };
   }

package/src/mcp-remote.js

@@ -54,6 +54,7 @@ export class RemoteMcpUpstream {
 
 export function createMcpGatewayHandler({
   mission,
+  lease,
   runtime,
   upstream,
   upstreamUrl,
@@ -63,6 +64,7 @@ export function createMcpGatewayHandler({
   const resolvedUpstream = upstream || new RemoteMcpUpstream({ url: upstreamUrl });
   const gateway = new MissionMcpGateway({
     mission,
+    lease,
     runtime,
     upstream: resolvedUpstream,
     service,
@@ -74,7 +76,9 @@ export function createMcpGatewayHandler({
       {
         name: 'agent-authority-gateway',
         version: '0.3.0',
-        description: 'Mission-aware policy gateway for MCP tools'
+        description: lease
+          ? 'Task-Lease-aware policy gateway for MCP tools'
+          : 'Mission-aware policy gateway for MCP tools'
       },
       { capabilities: { tools: {} } }
     );

package/src/mcp-server.js

@@ -30,6 +30,7 @@ function sendJson(res, status, value) {
  */
 export function createMcpProxyServer({
   mission,
+  lease,
   runtime,
   upstream,
   upstreamUrl,
@@ -43,6 +44,7 @@ export function createMcpProxyServer({
 
   const gateway = createMcpGatewayHandler({
     mission,
+    lease,
     runtime,
     upstream,
     upstreamUrl,
@@ -64,6 +66,7 @@ export function createMcpProxyServer({
           ok: true,
           service: 'agent-authority-mcp-gateway',
           mode: 'read-only',
+          authority: lease ? 'task-lease' : 'mission',
           upstream: upstreamUrl || 'injected'
         });
       }