@nullsquare/agent-authority 0.4.0 → 0.4.2

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/google.js

@@ -0,0 +1,238 @@
+import { brokeredProviderAdapter } from '../connections.js';
+
+const MUTATING_ACTIONS = new Set(['event.create', 'event.delete']);
+const SEND_UPDATES = new Set(['all', 'externalOnly', 'none']);
+
+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 fromHeader(message) {
+  const headers = message?.payload?.headers;
+  if (!Array.isArray(headers)) return null;
+  const header = headers.find((item) => String(item?.name || '').toLowerCase() === 'from');
+  return typeof header?.value === 'string' ? header.value : null;
+}
+
+export function extractEmailAddress(value) {
+  if (typeof value !== 'string') return null;
+  const match = value.match(/([A-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[A-Z0-9.-]+\.[A-Z]{2,})/i);
+  return match ? match[1].trim().toLowerCase() : null;
+}
+
+export function gmailThreadSenderEmail(thread) {
+  const messages = thread?.messages;
+  if (!Array.isArray(messages) || messages.length === 0) {
+    throw providerError('gmail_thread_empty', 'Gmail thread does not contain any messages');
+  }
+
+  for (const message of messages) {
+    const raw = fromHeader(message);
+    const email = extractEmailAddress(raw);
+    if (email) return { email, raw, message_id: message.id || null };
+  }
+
+  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)) {
+    throw providerError('invalid_send_updates', 'context.send_updates must be all, externalOnly, or none');
+  }
+  return normalized;
+}
+
+function buildOperation(request, {
+  gmailBaseUrl = 'https://gmail.googleapis.com',
+  calendarBaseUrl = 'https://www.googleapis.com/calendar/v3'
+} = {}) {
+  const context = request?.context || {};
+
+  if (request?.service === 'gmail' && request?.action === 'thread.read') {
+    const threadId = required(context.thread_id, 'context.thread_id');
+    const query = new URLSearchParams({ format: 'metadata' });
+    query.append('metadataHeaders', 'From');
+    return {
+      method: 'GET',
+      url: `${gmailBaseUrl}/gmail/v1/users/me/threads/${encodeURIComponent(threadId)}?${query}`
+    };
+  }
+
+  if (request?.service === 'calendar' && request?.action === 'event.create') {
+    const calendarId = context.calendar_id || 'primary';
+    const attendeeEmail = required(context.attendee_email, 'context.attendee_email');
+    const startTime = required(context.start_time, 'context.start_time');
+    const endTime = required(context.end_time, 'context.end_time');
+    const sendUpdates = validateSendUpdates(context.send_updates);
+
+    return {
+      method: 'POST',
+      url: `${calendarBaseUrl}/calendars/${encodeURIComponent(calendarId)}/events?sendUpdates=${encodeURIComponent(sendUpdates)}`,
+      body: {
+        summary: context.summary || 'Agent Authority task event',
+        description: context.description || undefined,
+        start: { dateTime: startTime },
+        end: { dateTime: endTime },
+        attendees: [{ email: attendeeEmail }],
+        transparency: context.transparency || undefined,
+        visibility: context.visibility || undefined
+      }
+    };
+  }
+
+  if (request?.service === 'calendar' && request?.action === 'event.delete') {
+    const calendarId = context.calendar_id || 'primary';
+    const eventId = required(context.event_id, 'context.event_id');
+    const sendUpdates = validateSendUpdates(context.send_updates);
+    return {
+      method: 'DELETE',
+      url: `${calendarBaseUrl}/calendars/${encodeURIComponent(calendarId)}/events/${encodeURIComponent(eventId)}?sendUpdates=${encodeURIComponent(sendUpdates)}`
+    };
+  }
+
+  throw providerError(
+    'unsupported_action',
+    `Google action ${request?.service || 'unknown'}:${request?.action || 'unknown'} has no provider operation mapping`
+  );
+}
+
+function accessToken(credential) {
+  const token = typeof credential === 'string' ? credential : credential?.access_token;
+  if (!token) throw providerError('credential_invalid', 'Google credential does not contain an access token');
+  return token;
+}
+
+async function responseBody(response) {
+  const text = await response.text();
+  if (!text) return null;
+  try { return JSON.parse(text); } catch { return text; }
+}
+
+function normalizedOutput(request, response, body) {
+  const common = {
+    provider: request.service,
+    status: response.status,
+    ok: response.ok,
+    request_id: response.headers?.get?.('x-request-id') || null
+  };
+
+  if (request.service === 'gmail' && request.action === 'thread.read') {
+    const sender = gmailThreadSenderEmail(body);
+    return {
+      ...common,
+      thread_id: body?.id || request.context?.thread_id || null,
+      message_count: Array.isArray(body?.messages) ? body.messages.length : 0,
+      sender_email: sender.email,
+      sender_raw: sender.raw,
+      sender_message_id: sender.message_id
+    };
+  }
+
+  if (request.service === 'calendar' && request.action === 'event.create') {
+    return {
+      ...common,
+      event_id: body?.id || null,
+      html_link: body?.htmlLink || null,
+      attendees: Array.isArray(body?.attendees)
+        ? body.attendees.map((item) => item?.email).filter(Boolean)
+        : []
+    };
+  }
+
+  if (request.service === 'calendar' && request.action === 'event.delete') {
+    return { ...common, deleted: response.ok };
+  }
+
+  return { ...common, body };
+}
+
+export function createGoogleProviderAdapter({
+  broker,
+  fetchImpl = globalThis.fetch,
+  gmailBaseUrl = 'https://gmail.googleapis.com',
+  calendarBaseUrl = 'https://www.googleapis.com/calendar/v3'
+} = {}) {
+  if (!broker) throw new Error('credential broker is required');
+  if (typeof fetchImpl !== 'function') throw new Error('fetch implementation is required');
+
+  const operationFor = (request) => buildOperation(request, { gmailBaseUrl, calendarBaseUrl });
+
+  const adapter = brokeredProviderAdapter({
+    kind: 'google-rest',
+    services: ['gmail', 'calendar'],
+    broker,
+    async execute({ request, credential }) {
+      const operation = operationFor(request);
+      const response = await fetchImpl(operation.url, {
+        method: operation.method,
+        headers: {
+          accept: 'application/json',
+          authorization: `Bearer ${accessToken(credential)}`,
+          'content-type': 'application/json',
+          'user-agent': 'nullsquare-agent-authority/0.4'
+        },
+        body: operation.body ? JSON.stringify(operation.body) : undefined
+      });
+
+      const body = await responseBody(response);
+      const output = normalizedOutput(request, response, body);
+
+      if (!response.ok) {
+        const error = providerError('provider_error', `${request.service} API ${response.status}`);
+        error.provider_output = output;
+        throw error;
+      }
+
+      return output;
+    }
+  });
+
+  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);

package/docs/assets/agent-authority-cover.svg

@@ -1,41 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="640" viewBox="0 0 1600 640" role="img" aria-label="Agent Authority — mission scoped authorization for AI agents">
-  <defs>
-    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
-      <stop offset="0" stop-color="#07111f"/><stop offset="1" stop-color="#121a36"/>
-    </linearGradient>
-    <linearGradient id="accent" x1="0" y1="0" x2="1" y2="0">
-      <stop offset="0" stop-color="#7c5cff"/><stop offset="1" stop-color="#4ecbff"/>
-    </linearGradient>
-  </defs>
-  <rect width="1600" height="640" rx="36" fill="url(#bg)"/>
-  <g font-family="Arial, Helvetica, sans-serif" fill="#fff">
-    <text x="100" y="120" font-size="28" font-weight="700" letter-spacing="3">NULLSQUARE / OPEN SOURCE</text>
-    <text x="100" y="220" font-size="78" font-weight="800">Agent Authority</text>
-    <text x="100" y="285" font-size="34" fill="#b9c7e6">Mission-scoped authorization for AI agents</text>
-    <text x="100" y="355" font-size="27" fill="#8fe1ff">One mission · Any agent · Any auth system</text>
-  </g>
-  <g transform="translate(930 95)" font-family="Arial, Helvetica, sans-serif">
-    <rect x="120" y="0" width="330" height="72" rx="16" fill="#111c34" stroke="#6d85ff"/>
-    <text x="285" y="44" text-anchor="middle" font-size="24" fill="#fff">Human-approved mission</text>
-    <path d="M285 72 V120" stroke="#7786a8" stroke-width="3"/>
-    <rect x="80" y="120" width="410" height="90" rx="18" fill="#171842" stroke="#8b67ff" stroke-width="2"/>
-    <text x="285" y="158" text-anchor="middle" font-size="25" font-weight="700" fill="#fff">AUTHORITY RUNTIME</text>
-    <text x="285" y="190" text-anchor="middle" font-size="20" fill="#b9c7e6">allow · deny · approve · revoke</text>
-    <path d="M285 210 V260" stroke="#7786a8" stroke-width="3"/>
-    <rect x="80" y="260" width="410" height="72" rx="16" fill="#101b30" stroke="#4ecbff"/>
-    <text x="285" y="304" text-anchor="middle" font-size="23" fill="#fff">Adapters / connectors</text>
-    <path d="M285 332 V382" stroke="#7786a8" stroke-width="3"/>
-    <g fill="#101b30" stroke="#4b628c">
-      <rect x="0" y="382" width="135" height="64" rx="14"/><rect x="145" y="382" width="135" height="64" rx="14"/>
-      <rect x="290" y="382" width="135" height="64" rx="14"/><rect x="435" y="382" width="135" height="64" rx="14"/>
-    </g>
-    <g font-size="20" fill="#fff" text-anchor="middle">
-      <text x="67" y="422">OAuth</text><text x="212" y="422">MCP</text><text x="357" y="422">API / CLI</text><text x="502" y="422">Legacy</text>
-    </g>
-  </g>
-  <rect x="100" y="430" width="690" height="2" fill="url(#accent)"/>
-  <g font-family="Arial, Helvetica, sans-serif" font-size="22" fill="#b9c7e6">
-    <text x="100" y="485">Delegation attenuation</text><text x="330" y="485">Human approvals</text><text x="555" y="485">Action receipts</text>
-    <text x="100" y="530">Credential isolation</text><text x="330" y="530">Legacy compatibility</text><text x="555" y="530">Protocol neutral</text>
-  </g>
-</svg>