@nullsquare/agent-authority 0.4.1 → 0.4.3

package/docs/task-leases.md

@@ -32,6 +32,12 @@ Human-approved task
   authority roots
         |
  authorized execution
+        |
+        +--> ALLOW receipt
+        +--> exact output hash evidence
+        |
+        v
+ trusted adapter extractor
         |
         v
   derived facts
@@ -64,7 +70,60 @@ Examples:
 - 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.
+A derived fact must reference an `ALLOW` receipt from the same Task Lease and at least one parent authority fact.
+
+Agent Authority now exposes two derivation modes:
+
+- `derive()` — compatibility path where the trusted host supplies both `value` and `selector`;
+- `deriveFromEvidence()` — stricter path where the host does **not** supply the authority value.
+
+For provider-derived authority, prefer `deriveFromEvidence()`.
+
+### Execution evidence
+
+After an allowed `guard.run()` effect succeeds, the guard returns:
+
+```js
+{
+  output,
+  receipt,
+  evidence
+}
+```
+
+The execution-evidence record binds:
+
+- the receipt ID and receipt hash;
+- mission and Task Lease identity;
+- service and action;
+- request hash;
+- a hash of the exact returned output.
+
+If downstream code changes the output and tries to reuse the original evidence, derivation fails with `evidence_output_mismatch`.
+
+This is an integrity mechanism inside the trusted host/runtime boundary. It is **not** provider-signed remote attestation.
+
+### Trusted adapter extractor
+
+The adapter extractor identifies which normalized provider-output field may become authority.
+
+For Gmail, the current extractor accepts only a `gmail:thread.read` receipt and selects:
+
+```text
+output.sender_email
+```
+
+The extractor returns only an ID and selector. It does not return the authority value.
+
+Task Lease resolves the selector itself after checking the execution evidence. This prevents ordinary host code from doing this:
+
+```text
+Gmail returned customer@example.com
+host claims attacker@example.com
+while reusing the original Gmail receipt
+```
+
+The stricter path rejects output/evidence substitution rather than recording the host's claimed value.
 
 ### Binding
 
@@ -74,7 +133,7 @@ A binding narrows an otherwise permitted action to the exact value held by an au
 {
   service: 'calendar',
   action: 'event.create',
-  context_field: 'attendee',
+  context_field: 'attendee_email',
   fact_id: 'fact:requester-email'
 }
 ```
@@ -87,7 +146,7 @@ If it has value `customer@example.com`, this request can proceed:
 {
   service: 'calendar',
   action: 'event.create',
-  context: { attendee: 'customer@example.com' }
+  context: { attendee_email: 'customer@example.com' }
 }
 ```
 
@@ -97,7 +156,7 @@ This request does not proceed automatically:
 {
   service: 'calendar',
   action: 'event.create',
-  context: { attendee: 'other@example.com' }
+  context: { attendee_email: 'other@example.com' }
 }
 ```
 
@@ -126,12 +185,13 @@ lease authority <= mission authority
 
 Authority may stay the same or shrink. It must never grow silently.
 
-## Example
+## Evidence-verified Gmail -> Calendar example
 
 ```js
 import { AuthorityRuntime } from '@nullsquare/agent-authority';
 import { createTaskLease } from '@nullsquare/agent-authority/task-lease';
 import { createTaskLeaseGuard } from '@nullsquare/agent-authority/guard';
+import { gmailThreadSenderAuthorityExtractor } from '@nullsquare/agent-authority/providers/google';
 
 const lease = createTaskLease({
   mission,
@@ -143,7 +203,7 @@ const lease = createTaskLease({
     {
       service: 'calendar',
       action: 'event.create',
-      context_field: 'attendee',
+      context_field: 'attendee_email',
       fact_id: 'fact:sender-email'
     }
   ]
@@ -157,30 +217,29 @@ const guard = createTaskLeaseGuard({
 const read = await guard.run({
   service: 'gmail',
   action: 'thread.read',
-  context: { thread: 'thread:demo-91' }
+  context: { thread_id: 'thread:demo-91' }
 }, () => gmail.readThread('thread:demo-91'));
 
-lease.derive({
+const senderFact = lease.deriveFromEvidence({
   fact_id: 'fact:sender-email',
   kind: 'email.address',
-  value: read.output.sender,
   from: ['fact:thread'],
   receipt: read.receipt,
-  selector: 'output.sender'
+  evidence: read.evidence,
+  output: read.output,
+  extractor: gmailThreadSenderAuthorityExtractor
 });
 
 await guard.run({
   service: 'calendar',
   action: 'event.create',
-  context: { attendee: read.output.sender }
-}, () => calendar.createEvent({ attendee: read.output.sender }));
+  context: { attendee_email: senderFact.value }
+}, () => calendar.createEvent({ attendee: senderFact.value }));
 ```
 
-Run the self-contained example:
+Notice that `deriveFromEvidence()` has no `value` argument. The fact value comes from the exact output already bound to the authorized read.
 
-```bash
-npm run demo:task-lease
-```
+The older `derive()` API remains available for integrations that have not adopted the evidence contract yet. Facts created through that API record `derivation_mode: host-trusted` so audit code can distinguish the weaker path.
 
 ## Task completion
 
@@ -207,36 +266,44 @@ requested new resource
 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.
+The existing approval store can handle the human decision. Automatically applying approved deltas to a live Task Lease is a later milestone; the current implementation deliberately stops at the safe enforcement signal.
 
 ## Current security properties
 
-The v0.4 implementation tests that:
+The 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;
+- derived facts require an `ALLOW` receipt from the same mission and Task Lease;
 - 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.
+- Task Lease receipts include the lease ID and lease hash;
+- successful guarded effects produce output-bound execution evidence;
+- `deriveFromEvidence()` ignores any caller-supplied `value` and resolves the trusted selector itself;
+- modified provider output is rejected;
+- modified execution evidence is rejected;
+- execution evidence cannot be replayed under another receipt or Task Lease;
+- the Gmail extractor rejects the wrong service/action;
+- dangerous selector paths such as `__proto__` fail closed.
 
 ## 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.
+1. **Trusted host/adapter boundary:** execution evidence is produced by Agent Authority around the host effect, not signed by Gmail, Calendar, or another provider. A malicious host that can bypass or replace Agent Authority remains outside the guarantee.
+2. **Provider attestation:** output hashes prove consistency with what the guarded effect returned; they do not cryptographically prove what the remote provider emitted on the wire.
+3. **Source invalidation:** a source resource changing later does not yet invalidate already-derived facts automatically.
+4. **In-memory lease state:** TaskLease instances are currently process-local. Durable lease persistence/recovery is not implemented yet.
+5. **Top-level binding fields:** bindings target top-level request context fields. A general nested policy language is intentionally deferred.
+6. **Step-up application:** authority deltas are surfaced but approved deltas are not yet automatically applied back into the lease.
+7. **Adapter semantics:** each provider still needs a reviewed operation -> authority-field mapping. The Google sender extractor is the first concrete contract.
 
-These constraints are deliberate. The next work should be driven by real integrations rather than by adding a general policy language.
+These constraints are deliberate. The project should improve the evidence contract from real provider cases rather than build a universal semantic 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:
+The longer-term 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

package/examples/live-github-derived-mutation.js

@@ -1,9 +1,11 @@
+import { CredentialBroker } from '../src/connections.js';
 import { AuthorityRuntime } from '../src/index.js';
 import {
   AuthorityApprovalRequiredError,
   AuthorityDeniedError,
   createTaskLeaseGuard
 } from '../src/guard.js';
+import { createGitHubProviderAdapter } from '../src/providers/github.js';
 import { createTaskLease } from '../src/task-lease.js';
 
 const repository = process.env.AA_VALIDATION_REPOSITORY || 'Null-Square/agent-authority';
@@ -43,6 +45,12 @@ const lease = createTaskLease({
       kind: 'github.repository',
       value: repository,
       source: 'validation-task'
+    },
+    {
+      fact_id: 'fact:fixture-marker',
+      kind: 'github.issue.marker',
+      value: marker,
+      source: 'validation-task'
     }
   ],
   bindings: [
@@ -52,6 +60,12 @@ const lease = createTaskLease({
       context_field: 'repository',
       fact_id: 'fact:repository'
     },
+    {
+      service: 'github',
+      action: 'issue.list',
+      context_field: 'fixture_marker',
+      fact_id: 'fact:fixture-marker'
+    },
     {
       service: 'github',
       action: 'issue.comment',
@@ -68,10 +82,20 @@ const lease = createTaskLease({
 });
 
 const guard = createTaskLeaseGuard({ lease, runtime: new AuthorityRuntime() });
-const headers = {
+const broker = new CredentialBroker();
+broker.connect({
+  principal_id: mission.principal.id,
+  service: 'github',
+  auth_kind: 'github-actions-token',
+  credential: { access_token: token },
+  scopes: ['contents:read', 'issues:write']
+});
+const adapter = createGitHubProviderAdapter({ broker });
+
+const cleanupHeaders = {
   accept: 'application/vnd.github+json',
   authorization: `Bearer ${token}`,
-  'user-agent': 'agent-authority-derived-mutation-validation',
+  'user-agent': 'agent-authority-derived-mutation-validation-cleanup',
   'x-github-api-version': '2022-11-28'
 };
 
@@ -80,90 +104,83 @@ let providerMutationCalls = 0;
 let cleanupCalls = 0;
 let createdCommentId = null;
 
-async function githubJson(url, options = {}) {
-  const response = await fetch(url, {
-    ...options,
-    headers: { ...headers, ...(options.headers || {}) }
-  });
-  if (!response.ok) {
-    const body = await response.text();
-    throw new Error(`GitHub ${response.status}: ${body.slice(0, 300)}`);
-  }
-  if (response.status === 204) return null;
-  return response.json();
+function discoveryRequest() {
+  return {
+    service: 'github',
+    action: 'issue.list',
+    context: {
+      repository,
+      fixture_marker: marker,
+      state: 'open',
+      per_page: 100
+    }
+  };
 }
 
 async function discoverFixtureIssue() {
-  return guard.run(
-    {
-      service: 'github',
-      action: 'issue.list',
-      context: { repository }
-    },
-    async () => {
-      providerReadCalls += 1;
-      const issues = await githubJson(
-        `https://api.github.com/repos/${owner}/${repo}/issues?state=open&per_page=100`
-      );
-      const fixture = issues.find((issue) => !issue.pull_request && issue.body?.includes(marker));
-      if (!fixture) throw new Error(`validation fixture with marker ${marker} was not found`);
-      return { number: fixture.number, title: fixture.title };
-    }
-  );
+  const request = discoveryRequest();
+  return guard.run(request, async () => {
+    providerReadCalls += 1;
+    return adapter.execute({ mission, request });
+  });
 }
 
 async function commentOnIssue(issueNumber, body) {
-  return guard.run(
-    {
-      service: 'github',
-      action: 'issue.comment',
-      context: { repository, issue_number: issueNumber }
-    },
-    async () => {
-      providerMutationCalls += 1;
-      const comment = await githubJson(
-        `https://api.github.com/repos/${owner}/${repo}/issues/${issueNumber}/comments`,
-        {
-          method: 'POST',
-          headers: { 'content-type': 'application/json' },
-          body: JSON.stringify({ body })
-        }
-      );
-      return { id: comment.id, html_url: comment.html_url };
-    }
-  );
+  const request = {
+    service: 'github',
+    action: 'issue.comment',
+    context: { repository, issue_number: issueNumber, body }
+  };
+
+  return guard.run(request, async () => {
+    providerMutationCalls += 1;
+    return adapter.execute({ mission, request });
+  });
 }
 
 async function cleanupComment(commentId) {
   cleanupCalls += 1;
-  await githubJson(
+  const response = await fetch(
     `https://api.github.com/repos/${owner}/${repo}/issues/comments/${commentId}`,
-    { method: 'DELETE' }
+    { method: 'DELETE', headers: cleanupHeaders }
   );
+  if (!response.ok && response.status !== 404) {
+    const body = await response.text();
+    throw new Error(`GitHub cleanup ${response.status}: ${body.slice(0, 300)}`);
+  }
 }
 
 try {
   console.log(`Task root repository: ${repository}`);
-  console.log('1. Discover fixture through an authorized live GitHub issue-list call');
+  console.log(`Task root fixture marker: ${marker}`);
+  console.log('1. Discover fixture through the reviewed GitHub provider adapter');
   const discovered = await discoverFixtureIssue();
-  console.log(`   ALLOW -> discovered issue #${discovered.output.number}: ${discovered.output.title}`);
 
-  lease.derive({
+  if (discovered.output.selected_issue_match_count !== 1) {
+    throw new Error(`expected exactly one fixture marker match, got ${discovered.output.selected_issue_match_count}`);
+  }
+  console.log(`   ALLOW -> selected issue #${discovered.output.selected_issue_number}: ${discovered.output.selected_issue_title}`);
+
+  const extractor = adapter.authorityExtractor(discoveryRequest(), 'github.issue.number');
+  if (!extractor) throw new Error('GitHub provider did not advertise the issue-number authority extractor');
+
+  const issueFact = lease.deriveFromEvidence({
     fact_id: 'fact:discovered-issue-number',
     kind: 'github.issue.number',
-    value: discovered.output.number,
-    from: ['fact:repository'],
+    from: ['fact:repository', 'fact:fixture-marker'],
     receipt: discovered.receipt,
-    selector: 'output.number'
+    evidence: discovered.evidence,
+    output: discovered.output,
+    extractor
   });
-  console.log(`2. Derived authority -> issue #${discovered.output.number}`);
+  console.log(`2. Evidence-verified authority -> issue #${issueFact.value}`);
 
-  const validationBody = `Agent Authority live derived-authority validation (${new Date().toISOString()}). Temporary comment; CI removes it after the proof.`;
-  const allowedMutation = await commentOnIssue(discovered.output.number, validationBody);
-  createdCommentId = allowedMutation.output.id;
+  const validationBody = `Agent Authority live evidence-derived authorization validation (${new Date().toISOString()}). Temporary comment; CI removes it after the proof.`;
+  const allowedMutation = await commentOnIssue(issueFact.value, validationBody);
+  createdCommentId = allowedMutation.output.comment_id;
   console.log(`3. ALLOW -> real GitHub comment mutation executed (comment ${createdCommentId})`);
 
-  const unrelatedIssue = discovered.output.number === 1 ? 2 : 1;
+  const unrelatedIssue = issueFact.value === 1 ? 2 : 1;
   try {
     await commentOnIssue(unrelatedIssue, 'THIS MUST NEVER REACH GITHUB');
     throw new Error('unrelated issue mutation unexpectedly executed');
@@ -178,15 +195,15 @@ try {
     throw new Error(`expected exactly one task-side provider mutation before completion, got ${providerMutationCalls}`);
   }
 
-  lease.complete('live derived-mutation validation complete');
+  lease.complete('live evidence-derived mutation validation complete');
   try {
-    await commentOnIssue(discovered.output.number, 'THIS MUST NOT RUN AFTER TASK COMPLETION');
+    await commentOnIssue(issueFact.value, 'THIS MUST NOT RUN AFTER TASK COMPLETION');
     throw new Error('post-completion mutation unexpectedly executed');
   } catch (error) {
     if (!(error instanceof AuthorityDeniedError) || error.code !== 'task_lease_completed') {
       throw error;
     }
-    console.log(`5. DENY -> post-completion mutation blocked for issue #${discovered.output.number}`);
+    console.log(`5. DENY -> post-completion mutation blocked for issue #${issueFact.value}`);
   }
 
   if (providerReadCalls !== 1) {
@@ -196,7 +213,7 @@ try {
     throw new Error(`expected exactly one provider mutation after blocked attempts, got ${providerMutationCalls}`);
   }
 
-  console.log('PASS -> dynamic resource was discovered from GitHub, derived into the Task Lease, and mutated exactly once');
+  console.log('PASS -> GitHub provider output became downstream authority only through execution evidence and a reviewed extractor');
   console.log('PASS -> unrelated and post-completion mutations produced zero additional provider mutation calls');
 } finally {
   if (createdCommentId) {

package/examples/live-google-cross-provider.js

@@ -4,7 +4,10 @@ import {
   AuthorityDeniedError,
   createTaskLeaseGuard
 } from '../src/guard.js';
-import { gmailThreadSenderEmail } from '../src/providers/google.js';
+import {
+  gmailThreadSenderAuthorityExtractor,
+  gmailThreadSenderEmail
+} from '../src/providers/google.js';
 import { createTaskLease } from '../src/task-lease.js';
 
 const token = process.env.GOOGLE_ACCESS_TOKEN;
@@ -128,6 +131,7 @@ async function readAuthorizedThread() {
       );
       const sender = gmailThreadSenderEmail(thread);
       return {
+        provider: 'gmail',
         thread_id: thread.id,
         sender_email: sender.email,
         sender_raw: sender.raw,
@@ -198,17 +202,18 @@ try {
     throw new Error(`expected sender ${expectedSender}, got ${discovered.output.sender_email}`);
   }
 
-  lease.derive({
+  const senderFact = lease.deriveFromEvidence({
     fact_id: 'fact:sender-email',
     kind: 'email.address',
-    value: discovered.output.sender_email,
     from: ['fact:gmail-thread'],
     receipt: discovered.receipt,
-    selector: 'output.sender_email'
+    evidence: discovered.evidence,
+    output: discovered.output,
+    extractor: gmailThreadSenderAuthorityExtractor
   });
-  console.log(`2. Derived authority -> Calendar attendee ${discovered.output.sender_email}`);
+  console.log(`2. Evidence-verified authority -> Calendar attendee ${senderFact.value}`);
 
-  const allowed = await createCalendarEvent(discovered.output.sender_email, 'authorized');
+  const allowed = await createCalendarEvent(senderFact.value, 'authorized');
   createdEventId = allowed.output.event_id;
   console.log(`3. ALLOW -> real Calendar event mutation executed (${createdEventId})`);
 
@@ -228,7 +233,7 @@ try {
 
   lease.complete('live Gmail to Calendar validation complete');
   try {
-    await createCalendarEvent(discovered.output.sender_email, 'must-not-run-after-completion');
+    await createCalendarEvent(senderFact.value, 'must-not-run-after-completion');
     throw new Error('post-completion Calendar mutation unexpectedly executed');
   } catch (error) {
     if (!(error instanceof AuthorityDeniedError) || error.code !== 'task_lease_completed') {
@@ -244,7 +249,7 @@ try {
     throw new Error(`expected exactly one Calendar provider mutation after blocked attempts, got ${providerMutationCalls}`);
   }
 
-  console.log('PASS -> a sender discovered from real Gmail became exact derived authority for one real Calendar mutation');
+  console.log('PASS -> a sender discovered from real Gmail became evidence-verified exact authority for one real Calendar mutation');
   console.log('PASS -> unrelated and post-completion attempts caused zero additional Calendar provider mutations');
 } finally {
   if (createdEventId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nullsquare/agent-authority",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Task-bounded authority runtime for AI agents: give agents tasks, not standing account permissions.",
   "license": "Apache-2.0",
   "type": "module",
@@ -41,7 +41,7 @@
     "test": "node --test test/*.test.js",
     "test:ai-sdk": "node --test test/integrations/ai-sdk.integration.mjs",
     "test:coverage": "node --experimental-test-coverage --test test/*.test.js",
-    "check:syntax": "node --check src/index.js && node --check src/connections.js && node --check src/execution.js && node --check src/providers/github.js && node --check src/providers/google.js && node --check src/storage.js && node --check src/runtime-env.js && node --check src/sdk.js && node --check src/server.js && node --check src/cli.js && node --check src/agent-auth.js && node --check src/approvals.js && node --check src/idempotency.js && node --check src/keys.js && node --check src/harness-bridge.js && node --check src/guard.js && node --check src/task-lease.js && node --check src/mcp-gateway.js && node --check src/mcp-remote.js && node --check src/mcp-server.js && node --check src/integrations/ai-sdk.js && node --check examples/validation-mcp-upstream.js && node --check examples/direct-guard.js && node --check examples/task-lease-demo.js && node --check examples/live-github-task-lease.js && node --check examples/live-github-derived-mutation.js && node --check examples/live-google-cross-provider.js",
+    "check:syntax": "node --check src/index.js && node --check src/authority-evidence.js && node --check src/connections.js && node --check src/execution.js && node --check src/providers/github.js && node --check src/providers/google.js && node --check src/storage.js && node --check src/runtime-env.js && node --check src/sdk.js && node --check src/server.js && node --check src/cli.js && node --check src/agent-auth.js && node --check src/approvals.js && node --check src/idempotency.js && node --check src/keys.js && node --check src/harness-bridge.js && node --check src/guard.js && node --check src/task-lease.js && node --check src/mcp-gateway.js && node --check src/mcp-remote.js && node --check src/mcp-server.js && node --check src/integrations/ai-sdk.js && node --check examples/validation-mcp-upstream.js && node --check examples/direct-guard.js && node --check examples/task-lease-demo.js && node --check examples/live-github-task-lease.js && node --check examples/live-github-derived-mutation.js && node --check examples/live-google-cross-provider.js",
     "check:package": "npm pack --dry-run",
     "check": "npm run check:syntax && npm test && npm run demo:task-lease && npm run check:package"
   },
@@ -60,6 +60,7 @@
     ".": "./src/index.js",
     "./agent-auth": "./src/agent-auth.js",
     "./approvals": "./src/approvals.js",
+    "./authority-evidence": "./src/authority-evidence.js",
     "./connections": "./src/connections.js",
     "./execution": "./src/execution.js",
     "./guard": "./src/guard.js",