@nullsquare/agent-authority 0.4.1 → 0.4.3

package/src/authority-evidence.js

@@ -0,0 +1,146 @@
+import { hashObject } from './index.js';
+
+const FORBIDDEN_SELECTOR_SEGMENTS = new Set(['__proto__', 'prototype', 'constructor']);
+
+function evidenceError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function requireReceipt(receipt) {
+  if (!receipt?.receipt_id) throw evidenceError('evidence_receipt_required', 'execution evidence requires a receipt');
+  if (!receipt?.receipt_hash) throw evidenceError('evidence_receipt_hash_required', 'execution evidence requires a receipt hash');
+  if (receipt.decision !== 'allow') {
+    throw evidenceError('evidence_receipt_not_authorized', 'execution evidence can only be created for an ALLOW receipt');
+  }
+  return receipt;
+}
+
+function unsignedEvidence(evidence = {}) {
+  const { evidence_hash: _evidenceHash, ...unsigned } = evidence;
+  return unsigned;
+}
+
+function hashExecutionOutput(output) {
+  return hashObject({
+    output_type: output === null ? 'null' : typeof output,
+    output
+  });
+}
+
+/**
+ * Bind the exact output returned by an authorized effect to its decision receipt.
+ *
+ * This is integrity evidence, not remote attestation. It prevents downstream code
+ * from silently swapping the output object while still claiming the original
+ * Agent Authority receipt as provenance.
+ */
+export function createExecutionEvidence({ receipt, output } = {}) {
+  requireReceipt(receipt);
+  const evidence = {
+    version: '0.1',
+    type: 'execution-output',
+    receipt_id: receipt.receipt_id,
+    receipt_hash: receipt.receipt_hash,
+    mission_id: receipt.mission_id,
+    task_lease_id: receipt.task_lease_id || null,
+    service: receipt.service,
+    action: receipt.action,
+    request_hash: receipt.request_hash,
+    output_hash: hashExecutionOutput(output)
+  };
+  return { ...evidence, evidence_hash: hashObject(evidence) };
+}
+
+export function verifyExecutionEvidence({ receipt, output, evidence } = {}) {
+  requireReceipt(receipt);
+  if (!evidence || typeof evidence !== 'object') {
+    throw evidenceError('execution_evidence_required', 'derived authority requires execution evidence');
+  }
+  if (evidence.type !== 'execution-output' || evidence.version !== '0.1') {
+    throw evidenceError('execution_evidence_invalid', 'unsupported execution evidence format');
+  }
+  if (hashObject(unsignedEvidence(evidence)) !== evidence.evidence_hash) {
+    throw evidenceError('execution_evidence_tampered', 'execution evidence hash does not match its contents');
+  }
+  if (evidence.receipt_id !== receipt.receipt_id || evidence.receipt_hash !== receipt.receipt_hash) {
+    throw evidenceError('evidence_receipt_mismatch', 'execution evidence belongs to another receipt');
+  }
+  if (evidence.mission_id !== receipt.mission_id) {
+    throw evidenceError('evidence_mission_mismatch', 'execution evidence belongs to another mission');
+  }
+  if ((evidence.task_lease_id || null) !== (receipt.task_lease_id || null)) {
+    throw evidenceError('evidence_lease_mismatch', 'execution evidence belongs to another task lease');
+  }
+  if (evidence.service !== receipt.service || evidence.action !== receipt.action) {
+    throw evidenceError('evidence_operation_mismatch', 'execution evidence operation does not match its receipt');
+  }
+  if (evidence.request_hash !== receipt.request_hash) {
+    throw evidenceError('evidence_request_mismatch', 'execution evidence request does not match its receipt');
+  }
+  if (hashExecutionOutput(output) !== evidence.output_hash) {
+    throw evidenceError('evidence_output_mismatch', 'provider output no longer matches the authorized execution evidence');
+  }
+  return evidence;
+}
+
+export function resolveEvidenceSelector(output, selector) {
+  if (typeof selector !== 'string' || selector.trim() === '') {
+    throw evidenceError('selector_required', 'trusted extractor must provide a selector');
+  }
+
+  let normalized = selector.trim();
+  if (normalized === 'output') return output;
+  if (normalized.startsWith('output.')) normalized = normalized.slice('output.'.length);
+
+  const segments = normalized.split('.');
+  if (segments.length === 0 || segments.some((segment) => !segment || FORBIDDEN_SELECTOR_SEGMENTS.has(segment))) {
+    throw evidenceError('selector_invalid', 'trusted extractor selector contains an invalid path segment');
+  }
+
+  let current = output;
+  for (const segment of segments) {
+    if (current === null || current === undefined || typeof current !== 'object') {
+      throw evidenceError('selector_unresolved', `trusted extractor selector ${selector} does not resolve against provider output`);
+    }
+    if (!Object.prototype.hasOwnProperty.call(current, segment)) {
+      throw evidenceError('selector_unresolved', `trusted extractor selector ${selector} does not resolve against provider output`);
+    }
+    current = current[segment];
+  }
+
+  if (current === undefined) {
+    throw evidenceError('selector_unresolved', `trusted extractor selector ${selector} resolved to undefined`);
+  }
+  return current;
+}
+
+/**
+ * Execute the small trusted-adapter extraction contract.
+ *
+ * Extractors choose which already-normalized output field is authority-relevant;
+ * they do not supply the value. TaskLease resolves the selector itself so the
+ * caller cannot substitute a different value while keeping the same evidence.
+ */
+export function runAuthorityExtractor({ extractor, receipt, output } = {}) {
+  if (typeof extractor !== 'function') {
+    throw evidenceError('trusted_extractor_required', 'deriveFromEvidence requires a trusted adapter extractor');
+  }
+
+  const descriptor = extractor({ receipt, output: structuredClone(output) });
+  if (!descriptor || typeof descriptor !== 'object') {
+    throw evidenceError('trusted_extractor_invalid', 'trusted adapter extractor must return a descriptor');
+  }
+  if (typeof descriptor.extractor_id !== 'string' || descriptor.extractor_id.trim() === '') {
+    throw evidenceError('trusted_extractor_id_required', 'trusted adapter extractor must provide extractor_id');
+  }
+  if (typeof descriptor.selector !== 'string' || descriptor.selector.trim() === '') {
+    throw evidenceError('selector_required', 'trusted adapter extractor must provide selector');
+  }
+
+  return {
+    extractor_id: descriptor.extractor_id.trim(),
+    selector: descriptor.selector.trim()
+  };
+}

package/src/guard.js

@@ -1,3 +1,5 @@
+import { createExecutionEvidence } from './authority-evidence.js';
+
 export class AuthorityDeniedError extends Error {
   constructor({ result, receipt }) {
     super(result?.reason || 'action denied by Agent Authority');
@@ -25,6 +27,10 @@ export class AuthorityApprovalRequiredError extends Error {
  * authority boundary returns ALLOW. A guard can use either a static mission or
  * a TaskLease. Task leases add provenance-bound restrictions without changing
  * the host application's credential ownership.
+ *
+ * Successful effects also return execution evidence binding the exact output
+ * hash to the ALLOW receipt. TaskLease.deriveFromEvidence() can use that record
+ * with a trusted adapter extractor so callers do not provide derived values.
  */
 export class AuthorityGuard {
   constructor({ mission, lease, runtime, onDecision } = {}) {
@@ -66,7 +72,8 @@ export class AuthorityGuard {
     }
 
     const output = await effect();
-    return { output, result: evaluation.result, receipt: evaluation.receipt };
+    const evidence = createExecutionEvidence({ receipt: evaluation.receipt, output });
+    return { output, result: evaluation.result, receipt: evaluation.receipt, evidence };
   }
 }
 

package/src/providers/github.js

@@ -1,12 +1,19 @@
 import { brokeredProviderAdapter } from '../connections.js';
 
-const MUTATING_ACTIONS = new Set(['issue.create', 'pull_request.create', 'repo.contents.write']);
+const MUTATING_ACTIONS = new Set(['issue.create', 'issue.comment', 'pull_request.create', 'repo.contents.write']);
+const ISSUE_STATES = new Set(['open', 'closed', 'all']);
 
 function required(value, name) {
   if (value === undefined || value === null || value === '') throw new Error(`${name} is required`);
   return value;
 }
 
+function providerError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
 function repoParts(context = {}) {
   const repository = required(context.repository, 'context.repository');
   const [owner, repo, ...extra] = String(repository).split('/');
@@ -22,6 +29,26 @@ function encodedPath(path) {
     .join('/');
 }
 
+function issueNumber(value) {
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number <= 0) {
+    throw providerError('invalid_issue_number', 'context.issue_number must be a positive integer');
+  }
+  return number;
+}
+
+function issueListQuery(context = {}) {
+  const state = context.state || 'open';
+  if (!ISSUE_STATES.has(state)) {
+    throw providerError('invalid_issue_state', 'context.state must be open, closed, or all');
+  }
+  const perPage = context.per_page === undefined ? 100 : Number(context.per_page);
+  if (!Number.isSafeInteger(perPage) || perPage < 1 || perPage > 100) {
+    throw providerError('invalid_issue_page_size', 'context.per_page must be an integer between 1 and 100');
+  }
+  return new URLSearchParams({ state, per_page: String(perPage) }).toString();
+}
+
 function buildOperation(request) {
   const context = request.context || {};
   const { owner, repo } = repoParts(context);
@@ -37,6 +64,9 @@ function buildOperation(request) {
       return { method: 'GET', path: `${root}/contents/${encodedPath(path)}${query}` };
     }
 
+    case 'issue.list':
+      return { method: 'GET', path: `${root}/issues?${issueListQuery(context)}` };
+
     case 'issue.create':
       return {
         method: 'POST',
@@ -49,6 +79,13 @@ function buildOperation(request) {
         }
       };
 
+    case 'issue.comment':
+      return {
+        method: 'POST',
+        path: `${root}/issues/${issueNumber(context.issue_number)}/comments`,
+        body: { body: required(context.body, 'context.body') }
+      };
+
     case 'pull_request.create':
       return {
         method: 'POST',
@@ -77,11 +114,8 @@ function buildOperation(request) {
       };
     }
 
-    default: {
-      const error = new Error(`GitHub action ${request.action} has no provider operation mapping`);
-      error.code = 'unsupported_action';
-      throw error;
-    }
+    default:
+      throw providerError('unsupported_action', `GitHub action ${request.action} has no provider operation mapping`);
   }
 }
 
@@ -94,6 +128,91 @@ function sanitizeBody(body) {
   return clone;
 }
 
+function normalizeIssueList(request, body) {
+  if (!Array.isArray(body)) {
+    throw providerError('github_issue_list_invalid', 'GitHub issue.list response must be an array');
+  }
+
+  const issues = body.map((issue) => ({
+    number: issueNumber(issue?.number),
+    title: typeof issue?.title === 'string' ? issue.title : null,
+    is_pull_request: Boolean(issue?.pull_request)
+  }));
+
+  const marker = request.context?.fixture_marker;
+  if (typeof marker !== 'string' || marker.trim() === '') {
+    return { issues, selected_issue_number: null, selected_issue_title: null, selected_issue_match_count: 0, selected_issue_marker: null };
+  }
+
+  const matches = body
+    .map((issue, index) => ({ issue, index }))
+    .filter(({ issue }) => !issue?.pull_request && typeof issue?.body === 'string' && issue.body.includes(marker));
+
+  const selected = matches.length === 1 ? issues[matches[0].index] : null;
+  return {
+    issues,
+    selected_issue_number: selected?.number || null,
+    selected_issue_title: selected?.title || null,
+    selected_issue_match_count: matches.length,
+    selected_issue_marker: marker
+  };
+}
+
+function normalizedOutput(request, response, body) {
+  const common = {
+    provider: 'github',
+    status: response.status,
+    ok: response.ok,
+    request_id: response.headers?.get?.('x-github-request-id') || null
+  };
+
+  if (request.action === 'issue.list') {
+    return { ...common, ...normalizeIssueList(request, body) };
+  }
+
+  if (request.action === 'issue.comment') {
+    return {
+      ...common,
+      comment_id: body?.id || null,
+      html_url: body?.html_url || null,
+      issue_number: issueNumber(request.context?.issue_number)
+    };
+  }
+
+  return { ...common, body: sanitizeBody(body) };
+}
+
+/**
+ * Reviewed authority extractor for an issue selected by the normalized
+ * issue.list mapping using the request's root-bound fixture_marker.
+ *
+ * The extractor returns a selector only. TaskLease resolves the issue number
+ * from the evidence-bound output after verifying the ALLOW receipt.
+ */
+export function githubIssueListSelectedNumberAuthorityExtractor({ receipt, output } = {}) {
+  if (receipt?.service !== 'github' || receipt?.action !== 'issue.list') {
+    throw providerError(
+      'trusted_extractor_operation_mismatch',
+      'GitHub issue-number authority extractor only accepts github:issue.list receipts'
+    );
+  }
+  if (output?.provider !== 'github' || output?.selected_issue_match_count !== 1) {
+    throw providerError(
+      'trusted_extractor_output_invalid',
+      'normalized GitHub output must contain exactly one selected issue'
+    );
+  }
+  issueNumber(output.selected_issue_number);
+  if (typeof output.selected_issue_marker !== 'string' || output.selected_issue_marker.trim() === '') {
+    throw providerError('trusted_extractor_output_invalid', 'normalized GitHub output is missing the selection marker');
+  }
+
+  return {
+    extractor_id: 'github.issue.list.selected-number.v1',
+    selector: 'output.selected_issue_number'
+  };
+}
+
 export function createGitHubProviderAdapter({ broker, fetchImpl = globalThis.fetch, baseUrl = 'https://api.github.com' } = {}) {
   if (!broker) throw new Error('credential broker is required');
   if (typeof fetchImpl !== 'function') throw new Error('fetch implementation is required');
@@ -114,7 +233,7 @@ export function createGitHubProviderAdapter({ broker, fetchImpl = globalThis.fet
           authorization: `Bearer ${token}`,
           'content-type': 'application/json',
           'x-github-api-version': '2022-11-28',
-          'user-agent': 'nullsquare-agent-authority/0.3'
+          'user-agent': 'nullsquare-agent-authority/0.4'
         },
         body: operation.body ? JSON.stringify(operation.body) : undefined
       });
@@ -125,25 +244,36 @@ export function createGitHubProviderAdapter({ broker, fetchImpl = globalThis.fet
         try { body = JSON.parse(text); } catch { /* preserve text */ }
       }
 
-      const output = {
-        provider: 'github',
-        status: response.status,
-        ok: response.ok,
-        body: sanitizeBody(body),
-        request_id: response.headers?.get?.('x-github-request-id') || null
-      };
-
       if (!response.ok) {
-        const error = new Error(`GitHub API ${response.status}`);
-        error.code = 'provider_error';
+        const output = {
+          provider: 'github',
+          status: response.status,
+          ok: false,
+          body: sanitizeBody(body),
+          request_id: response.headers?.get?.('x-github-request-id') || null
+        };
+        const error = providerError('provider_error', `GitHub API ${response.status}`);
         error.provider_output = output;
         throw error;
       }
 
-      return output;
+      return normalizedOutput(request, response, body);
     }
   });
 
+  adapter.validateRequest = (request) => buildOperation(request);
   adapter.isMutation = (request) => MUTATING_ACTIONS.has(request?.action);
+  adapter.authorityExtractor = (request, kind = 'opaque') => {
+    if (
+      request?.service === 'github' &&
+      request?.action === 'issue.list' &&
+      kind === 'github.issue.number' &&
+      typeof request?.context?.fixture_marker === 'string' &&
+      request.context.fixture_marker.trim() !== ''
+    ) {
+      return githubIssueListSelectedNumberAuthorityExtractor;
+    }
+    return null;
+  };
   return adapter;
 }

package/src/providers/google.js

@@ -42,6 +42,37 @@ export function gmailThreadSenderEmail(thread) {
   throw providerError('gmail_sender_missing', 'Gmail thread does not contain a usable From header');
 }
 
+/**
+ * Trusted authority-extraction contract for the normalized Gmail thread output.
+ *
+ * The extractor chooses the authority-relevant selector only. It never returns
+ * the value itself; TaskLease resolves output.sender_email after verifying the
+ * guard's execution evidence. This prevents host code from substituting another
+ * email while retaining the original Gmail receipt/evidence chain.
+ */
+export function gmailThreadSenderAuthorityExtractor({ receipt, output } = {}) {
+  if (receipt?.service !== 'gmail' || receipt?.action !== 'thread.read') {
+    throw providerError(
+      'trusted_extractor_operation_mismatch',
+      'Gmail sender authority extractor only accepts gmail:thread.read receipts'
+    );
+  }
+
+  const raw = typeof output?.sender_email === 'string' ? output.sender_email.trim() : '';
+  const normalized = extractEmailAddress(raw);
+  if (!normalized || normalized !== raw) {
+    throw providerError(
+      'trusted_extractor_output_invalid',
+      'normalized Gmail output does not contain a canonical sender_email'
+    );
+  }
+
+  return {
+    extractor_id: 'google.gmail.thread.sender-email.v1',
+    selector: 'output.sender_email'
+  };
+}
+
 function validateSendUpdates(value) {
   const normalized = value || 'none';
   if (!SEND_UPDATES.has(normalized)) {
@@ -197,5 +228,11 @@ export function createGoogleProviderAdapter({
 
   adapter.validateRequest = (request) => operationFor(request);
   adapter.isMutation = (request) => MUTATING_ACTIONS.has(request?.action);
+  adapter.authorityExtractor = (request, kind = 'email.address') => {
+    if (request?.service === 'gmail' && request?.action === 'thread.read' && kind === 'email.address') {
+      return gmailThreadSenderAuthorityExtractor;
+    }
+    return null;
+  };
   return adapter;
 }

package/src/task-lease.js

@@ -1,5 +1,10 @@
 import { randomUUID } from 'node:crypto';
 import { assertMission, createReceipt, hashObject, matchPattern } from './index.js';
+import {
+  resolveEvidenceSelector,
+  runAuthorityExtractor,
+  verifyExecutionEvidence
+} from './authority-evidence.js';
 
 function authorityError(code, message) {
   const error = new Error(message);
@@ -95,6 +100,12 @@ export class TaskLease {
     return structuredClone(fact);
   }
 
+  /**
+   * Legacy host-trusted derivation path.
+   *
+   * The caller supplies both value and selector. Keep this API for compatibility,
+   * but prefer deriveFromEvidence() for authority-relevant provider outputs.
+   */
   derive({ fact_id, kind = 'opaque', value, from = [], receipt, selector } = {}) {
     if (!fact_id) throw new Error('derived fact_id is required');
     if (value === undefined) throw new Error('derived value is required');
@@ -125,6 +136,7 @@ export class TaskLease {
       value,
       provenance: {
         type: 'derived',
+        derivation_mode: 'host-trusted',
         from: parents,
         task_lease_id: this.lease_id,
         receipt_id: receipt.receipt_id,
@@ -140,6 +152,71 @@ export class TaskLease {
     return structuredClone(fact);
   }
 
+  /**
+   * Strict derivation path for provider data.
+   *
+   * The caller cannot supply the authority value. A trusted adapter extractor
+   * identifies one normalized output selector, TaskLease resolves that selector
+   * itself, and execution evidence proves the output still matches the exact
+   * ALLOW receipt returned by guard.run().
+   */
+  deriveFromEvidence({
+    fact_id,
+    kind = 'opaque',
+    from = [],
+    receipt,
+    evidence,
+    output,
+    extractor
+  } = {}) {
+    if (!fact_id) throw new Error('derived fact_id is required');
+    if (this.facts.has(fact_id)) throw authorityError('fact_exists', `authority fact ${fact_id} already exists`);
+    if (!receipt) throw authorityError('receipt_required', 'derived authority requires an authorized source receipt');
+    if (receipt.decision !== 'allow') throw authorityError('receipt_not_authorized', 'derived authority requires an ALLOW receipt');
+    if (receipt.mission_id !== this.mission.mission_id) {
+      throw authorityError('receipt_mission_mismatch', 'source receipt belongs to another mission');
+    }
+    if (receipt.task_lease_id !== this.lease_id) {
+      throw authorityError('receipt_lease_mismatch', 'source receipt belongs to another task lease');
+    }
+
+    const parents = [...new Set(from)];
+    if (parents.length === 0) {
+      throw authorityError('parent_fact_required', 'derived authority must descend from at least one existing task authority fact');
+    }
+    for (const parentId of parents) {
+      if (!this.facts.has(parentId)) throw authorityError('parent_fact_missing', `authority fact ${parentId} does not exist`);
+    }
+
+    verifyExecutionEvidence({ receipt, output, evidence });
+    const extraction = runAuthorityExtractor({ extractor, receipt, output });
+    const value = resolveEvidenceSelector(output, extraction.selector);
+
+    const fact = {
+      fact_id,
+      kind,
+      value,
+      provenance: {
+        type: 'derived',
+        derivation_mode: 'execution-evidence-v1',
+        from: parents,
+        task_lease_id: this.lease_id,
+        receipt_id: receipt.receipt_id,
+        receipt_hash: receipt.receipt_hash,
+        source_service: receipt.service,
+        source_action: receipt.action,
+        source_request_hash: receipt.request_hash,
+        selector: extraction.selector,
+        extractor_id: extraction.extractor_id,
+        source_output_hash: evidence.output_hash,
+        execution_evidence_hash: evidence.evidence_hash
+      },
+      created_at: new Date().toISOString()
+    };
+    this.facts.set(fact_id, fact);
+    return structuredClone(fact);
+  }
+
   bind(binding) {
     const normalized = validateBinding(binding);
     this.bindings.push(normalized);