@nullsquare/agent-authority 0.4.5 → 0.4.7

package/docs/release-v0.4.7.md

@@ -0,0 +1,29 @@
+# v0.4.7 connected-execution candidate
+
+This candidate closes a concrete adoption gap between the task-first API and the existing credential broker/provider runtime.
+
+## Candidate changes
+
+- `task.execute(request)` executes through an `ExecutingAuthorityRuntime` while preserving the current Task Lease as the narrowest authority object.
+- connected deny/step-up outcomes use the same public error classes as `task.run()`.
+- successful connected execution returns sanitized provider output, receipt and execution evidence that can feed `task.authorityFrom()`.
+- `@nullsquare/agent-authority/runtime-env` exposes the existing local encrypted runtime composition for developer onboarding.
+- a sole active provider account can be resolved when requests omit `account_id`; multiple active accounts remain ambiguous and fail closed.
+- default disconnect can remove that sole connection without requiring the caller to know an auto-detected provider account ID.
+- the connected GitHub quickstart proves the local encrypted vault + credential broker + live provider path without copying credentials into task/model context.
+
+## Security boundary
+
+This does not create a GitHub token, OAuth flow, GitHub App, KMS, or new identity format. Provider-side least privilege still comes from GitHub. Agent Authority adds a task boundary underneath that connected account authority.
+
+The local encrypted vault remains a trusted-local-host developer reference backend.
+
+## Release gate
+
+Before version publication:
+
+- unit/adversarial tests must prove credential isolation and zero provider execution on task authority delta;
+- packed consumer must import and execute the new public surfaces;
+- live connected GitHub workflow must pass through the encrypted local runtime;
+- Node 20/22, coverage, AI SDK, existing live GitHub proofs and CodeQL must remain green;
+- registry verification must be performed after npm publication before the public release marker is updated.

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

@@ -1,12 +1,10 @@
 import { CredentialBroker } from '../src/connections.js';
-import { AuthorityRuntime } from '../src/index.js';
 import {
   AuthorityApprovalRequiredError,
-  AuthorityDeniedError,
-  createTaskLeaseGuard
+  AuthorityDeniedError
 } from '../src/guard.js';
 import { createGitHubProviderAdapter } from '../src/providers/github.js';
-import { createTaskLease } from '../src/task-lease.js';
+import { createTask } from '../src/task.js';
 
 const repository = process.env.AA_VALIDATION_REPOSITORY || 'Null-Square/agent-authority';
 const marker = process.env.AA_VALIDATION_MARKER || 'agent-authority-live-fixture-v1';
@@ -19,69 +17,55 @@ if (!token) {
 const [owner, repo] = repository.split('/');
 if (!owner || !repo) throw new Error(`invalid repository: ${repository}`);
 
-const mission = {
-  version: '0.1',
+const task = createTask({
   mission_id: 'mission:live-derived-github-mutation',
-  principal: { id: 'user:validation' },
-  agent: { id: 'agent:github-actions-validation' },
+  principal: 'user:validation',
+  agent: 'agent:github-actions-validation',
+  request: 'Find the Agent Authority live validation fixture and leave one validation comment',
   objective: 'Discover the validation issue and comment only on that issue',
-  resources: [
-    {
-      service: 'github',
+  permissions: {
+    github: {
       allow: ['issue.list', 'issue.comment'],
       deny: ['issue.close', 'issue.delete', 'repo.write', 'repo.delete'],
       constraints: { repository: [repository] }
     }
-  ],
-  constraints: { expires_at: '2099-01-01T00:00:00Z' }
-};
-
-const lease = createTaskLease({
-  mission,
-  request: 'Find the Agent Authority live validation fixture and leave one validation comment',
-  roots: [
-    {
-      fact_id: 'fact:repository',
+  },
+  constraints: { expires_at: '2099-01-01T00:00:00Z' },
+  authority: {
+    repository: {
       kind: 'github.repository',
       value: repository,
       source: 'validation-task'
     },
-    {
-      fact_id: 'fact:fixture-marker',
+    fixtureMarker: {
       kind: 'github.issue.marker',
       value: marker,
       source: 'validation-task'
     }
-  ],
+  },
   bindings: [
     {
       service: 'github',
       action: 'issue.list',
-      context_field: 'repository',
-      fact_id: 'fact:repository'
+      field: 'repository',
+      authority: 'repository'
     },
     {
       service: 'github',
       action: 'issue.list',
-      context_field: 'fixture_marker',
-      fact_id: 'fact:fixture-marker'
+      field: 'fixture_marker',
+      authority: 'fixtureMarker'
     },
     {
       service: 'github',
       action: 'issue.comment',
-      context_field: 'repository',
-      fact_id: 'fact:repository'
-    },
-    {
-      service: 'github',
-      action: 'issue.comment',
-      context_field: 'issue_number',
-      fact_id: 'fact:discovered-issue-number'
+      field: 'repository',
+      authority: 'repository'
     }
   ]
 });
 
-const guard = createTaskLeaseGuard({ lease, runtime: new AuthorityRuntime() });
+const mission = task.mission;
 const broker = new CredentialBroker();
 broker.connect({
   principal_id: mission.principal.id,
@@ -95,7 +79,7 @@ const adapter = createGitHubProviderAdapter({ broker });
 const cleanupHeaders = {
   accept: 'application/vnd.github+json',
   authorization: `Bearer ${token}`,
-  'user-agent': 'agent-authority-derived-mutation-validation-cleanup',
+  'user-agent': 'agent-authority-task-first-derived-mutation-validation-cleanup',
   'x-github-api-version': '2022-11-28'
 };
 
@@ -119,7 +103,7 @@ function discoveryRequest() {
 
 async function discoverFixtureIssue() {
   const request = discoveryRequest();
-  return guard.run(request, async () => {
+  return task.run(request, async () => {
     providerReadCalls += 1;
     return adapter.execute({ mission, request });
   });
@@ -132,7 +116,7 @@ async function commentOnIssue(issueNumber, body) {
     context: { repository, issue_number: issueNumber, body }
   };
 
-  return guard.run(request, async () => {
+  return task.run(request, async () => {
     providerMutationCalls += 1;
     return adapter.execute({ mission, request });
   });
@@ -151,9 +135,10 @@ async function cleanupComment(commentId) {
 }
 
 try {
-  console.log(`Task root repository: ${repository}`);
-  console.log(`Task root fixture marker: ${marker}`);
-  console.log('1. Discover fixture through the reviewed GitHub provider adapter');
+  console.log('Task-first live workflow: discover one issue and comment only on that issue');
+  console.log(`Task root repository: ${task.authority('repository').value}`);
+  console.log(`Task root fixture marker: ${task.authority('fixtureMarker').value}`);
+  console.log('1. Discover fixture through task.run() and the reviewed GitHub provider adapter');
   const discovered = await discoverFixtureIssue();
 
   if (discovered.output.selected_issue_match_count !== 1) {
@@ -164,18 +149,21 @@ try {
   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',
+  const issueFact = task.authorityFrom(discovered, {
+    name: 'discoveredIssue',
     kind: 'github.issue.number',
-    from: ['fact:repository', 'fact:fixture-marker'],
-    receipt: discovered.receipt,
-    evidence: discovered.evidence,
-    output: discovered.output,
+    from: ['repository', 'fixtureMarker'],
     extractor
   });
-  console.log(`2. Evidence-verified authority -> issue #${issueFact.value}`);
+  task.bind({
+    service: 'github',
+    action: 'issue.comment',
+    field: 'issue_number',
+    authority: 'discoveredIssue'
+  });
+  console.log(`2. task.authorityFrom() -> issue #${issueFact.value}`);
 
-  const validationBody = `Agent Authority live evidence-derived authorization validation (${new Date().toISOString()}). Temporary comment; CI removes it after the proof.`;
+  const validationBody = `Agent Authority live task-first 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})`);
@@ -188,14 +176,19 @@ try {
     if (!(error instanceof AuthorityApprovalRequiredError) || error.code !== 'authority_delta_required') {
       throw error;
     }
+    const explanation = task.explain(error);
     console.log(`4. STEP-UP -> unrelated issue #${unrelatedIssue} blocked before provider mutation`);
+    console.log(`   ${explanation.summary}`);
+    if (explanation.established_authority?.value !== issueFact.value) {
+      throw new Error('task-first authority-delta explanation lost the established issue authority');
+    }
   }
 
   if (providerMutationCalls !== 1) {
     throw new Error(`expected exactly one task-side provider mutation before completion, got ${providerMutationCalls}`);
   }
 
-  lease.complete('live evidence-derived mutation validation complete');
+  task.complete('live task-first evidence-derived mutation validation complete');
   try {
     await commentOnIssue(issueFact.value, 'THIS MUST NOT RUN AFTER TASK COMPLETION');
     throw new Error('post-completion mutation unexpectedly executed');
@@ -213,8 +206,8 @@ try {
     throw new Error(`expected exactly one provider mutation after blocked attempts, got ${providerMutationCalls}`);
   }
 
-  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');
+  console.log('PASS -> real GitHub provider output became task-first downstream authority through execution evidence and the reviewed extractor');
+  console.log('PASS -> unrelated and post-completion task-first calls produced zero additional provider mutations');
 } finally {
   if (createdCommentId) {
     await cleanupComment(createdCommentId);

package/examples/quickstart-github-connected.mjs

@@ -0,0 +1,77 @@
+import { createTask } from '@nullsquare/agent-authority/task';
+import { AuthorityApprovalRequiredError } from '@nullsquare/agent-authority/guard';
+import { createRuntimeEnvironment } from '@nullsquare/agent-authority/runtime-env';
+
+const repository = process.argv[2] || process.env.GITHUB_REPOSITORY || 'Null-Square/agent-authority';
+const unrelatedRepository = process.argv[3] || 'octocat/Hello-World';
+const env = createRuntimeEnvironment({ home: process.env.AGENT_AUTHORITY_HOME });
+
+const connection = env.broker.getConnection({
+  principal_id: env.config.principal_id,
+  service: 'github'
+});
+
+if (!connection) {
+  throw new Error(
+    'No unambiguous GitHub connection. Run: printf %s "$GITHUB_TOKEN" | agent-authority connect github --token-stdin'
+  );
+}
+
+const task = createTask({
+  principal: env.config.principal_id,
+  agent: 'agent:connected-quickstart',
+  request: `Inspect only ${repository} through the connected GitHub account`,
+  permissions: {
+    github: {
+      allow: ['repo.read'],
+      deny: ['repo.write', 'repo.delete'],
+      constraints: {}
+    }
+  },
+  authority: {
+    repository: { kind: 'github.repository', value: repository }
+  },
+  bindings: [
+    { service: 'github', action: 'repo.read', field: 'repository', authority: 'repository' }
+  ],
+  runtime: env.runtime
+});
+
+console.log(`Connected account -> ${connection.metadata?.login || connection.account_id}`);
+console.log('Credential location -> Agent Authority broker/vault (not task context)');
+console.log('Standing GitHub permission -> repo.read');
+console.log(`Task authority -> ${repository}`);
+
+const allowed = await task.execute({
+  service: 'github',
+  action: 'repo.read',
+  context: { repository }
+});
+
+console.log(`ALLOW -> connected GitHub returned ${allowed.output.body.full_name}`);
+
+try {
+  await task.execute({
+    service: 'github',
+    action: 'repo.read',
+    context: { repository: unrelatedRepository }
+  });
+  throw new Error('unrelated repository unexpectedly executed');
+} catch (error) {
+  if (!(error instanceof AuthorityApprovalRequiredError) || error.code !== 'authority_delta_required') {
+    throw error;
+  }
+  console.log(`STEP-UP -> ${task.explain(error).summary}`);
+}
+
+const visibleState = JSON.stringify({
+  mission: task.mission,
+  authorities: task.authorities(),
+  connection: env.broker.listConnections(env.config.principal_id),
+  allowed_output: allowed.output
+});
+if (/github_pat_|gh[pousr]_|Bearer\s/i.test(visibleState)) {
+  throw new Error('credential-like value leaked into public task state');
+}
+
+console.log('PASS -> connected credential stayed broker-internal and unrelated repository stayed outside task authority');

package/examples/quickstart-github-live.mjs

@@ -0,0 +1,84 @@
+import { createTask } from '@nullsquare/agent-authority/task';
+import { AuthorityApprovalRequiredError } from '@nullsquare/agent-authority/guard';
+
+const allowedRepository = process.argv[2] || 'Null-Square/agent-authority';
+const blockedRepository = process.argv[3] || 'octocat/Hello-World';
+
+const task = createTask({
+  principal: 'user:quickstart',
+  agent: 'agent:quickstart',
+  request: `Inspect only ${allowedRepository}`,
+  permissions: {
+    github: {
+      // Model the standing account/app capability as broader than this task.
+      // The Task authority root below narrows repo.read to one repository.
+      allow: ['repo.read'],
+      deny: ['repo.write', 'repo.delete'],
+      constraints: {}
+    }
+  },
+  authority: {
+    repository: { kind: 'github.repository', value: allowedRepository }
+  },
+  bindings: [
+    { service: 'github', action: 'repo.read', field: 'repository', authority: 'repository' }
+  ]
+});
+
+let outboundCalls = 0;
+
+async function readRepository(repository) {
+  return task.run({
+    service: 'github',
+    action: 'repo.read',
+    context: { repository }
+  }, async () => {
+    outboundCalls += 1;
+
+    const headers = {
+      accept: 'application/vnd.github+json',
+      'user-agent': 'agent-authority-live-quickstart',
+      'x-github-api-version': '2022-11-28'
+    };
+    if (process.env.GITHUB_TOKEN) {
+      headers.authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+    }
+
+    const response = await fetch(`https://api.github.com/repos/${repository}`, { headers });
+    if (!response.ok) {
+      throw new Error(`GitHub returned ${response.status} for ${repository}`);
+    }
+
+    const body = await response.json();
+    return {
+      full_name: body.full_name,
+      private: body.private,
+      html_url: body.html_url
+    };
+  });
+}
+
+console.log(`Standing GitHub permission -> repo.read`);
+console.log(`Task authority -> ${allowedRepository}`);
+console.log(`GitHub mode -> ${process.env.GITHUB_TOKEN ? 'authenticated token' : 'public API; no credential required'}`);
+
+const allowed = await readRepository(allowedRepository);
+console.log(`ALLOW -> real GitHub returned ${allowed.output.full_name}`);
+
+try {
+  await readRepository(blockedRepository);
+  throw new Error('unrelated repository unexpectedly reached GitHub');
+} catch (error) {
+  if (!(error instanceof AuthorityApprovalRequiredError) || error.code !== 'authority_delta_required') {
+    throw error;
+  }
+
+  console.log(`STEP-UP -> ${task.explain(error).summary}`);
+}
+
+if (outboundCalls !== 1) {
+  throw new Error(`expected exactly one outbound GitHub call, observed ${outboundCalls}`);
+}
+
+task.complete('live GitHub quickstart complete');
+console.log('PASS -> broader standing repo.read permission could not reach an unrelated repository for this task');

package/examples/quickstart.mjs

@@ -0,0 +1,101 @@
+import { createTask } from '@nullsquare/agent-authority/task';
+import { AuthorityApprovalRequiredError } from '@nullsquare/agent-authority/guard';
+import { githubIssueListSelectedNumberAuthorityExtractor } from '@nullsquare/agent-authority/providers/github';
+
+const repository = 'acme/app';
+const marker = 'quickstart-selected-issue';
+
+const task = createTask({
+  principal: 'user:quickstart',
+  agent: 'agent:quickstart',
+  request: 'Handle the issue selected for this task and comment only on that issue',
+  permissions: {
+    github: {
+      allow: ['issue.list', 'issue.comment'],
+      deny: ['repo.delete'],
+      constraints: { repository: [repository] }
+    }
+  },
+  authority: {
+    repository: { kind: 'github.repository', value: repository },
+    marker: { kind: 'github.issue.marker', value: marker }
+  },
+  bindings: [
+    { service: 'github', action: 'issue.list', field: 'repository', authority: 'repository' },
+    { service: 'github', action: 'issue.list', field: 'fixture_marker', authority: 'marker' },
+    { service: 'github', action: 'issue.comment', field: 'repository', authority: 'repository' }
+  ]
+});
+
+let effects = 0;
+
+const discovery = await task.run({
+  service: 'github',
+  action: 'issue.list',
+  context: { repository, fixture_marker: marker }
+}, async () => {
+  effects += 1;
+
+  // This is provider-shaped fixture output so the quickstart needs no account.
+  // In a real app, replace only this callback with the SDK/provider call you already use.
+  return {
+    provider: 'github',
+    status: 200,
+    ok: true,
+    selected_issue_number: 42,
+    selected_issue_title: 'Quickstart issue',
+    selected_issue_match_count: 1,
+    selected_issue_marker: marker
+  };
+});
+
+const issue = task.authorityFrom(discovery, {
+  name: 'issue',
+  kind: 'github.issue.number',
+  from: ['repository', 'marker'],
+  extractor: githubIssueListSelectedNumberAuthorityExtractor
+});
+
+task.bind({
+  service: 'github',
+  action: 'issue.comment',
+  field: 'issue_number',
+  authority: 'issue'
+});
+
+await task.run({
+  service: 'github',
+  action: 'issue.comment',
+  context: { repository, issue_number: issue.value, body: 'Handled.' }
+}, async () => {
+  effects += 1;
+  return { comment_id: 1001 };
+});
+
+console.log(`ALLOW -> task discovered issue #${issue.value} and the exact comment effect ran`);
+
+try {
+  await task.run({
+    service: 'github',
+    action: 'issue.comment',
+    context: { repository, issue_number: 7, body: 'This must not run.' }
+  }, async () => {
+    effects += 1;
+    return { comment_id: 1002 };
+  });
+
+  throw new Error('unrelated issue unexpectedly executed');
+} catch (error) {
+  if (!(error instanceof AuthorityApprovalRequiredError) || error.code !== 'authority_delta_required') {
+    throw error;
+  }
+
+  console.log(`STEP-UP -> ${task.explain(error).summary}`);
+}
+
+if (effects !== 2) {
+  throw new Error(`expected exactly 2 provider-shaped effects, observed ${effects}`);
+}
+
+task.complete('quickstart complete');
+console.log('PASS -> useful task work ran; unrelated standing permission did not become task authority');