@nullsquare/agent-authority 0.4.6 → 0.4.8

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');

package/examples/task-first-coding.js

@@ -0,0 +1,238 @@
+import { AuthorityApprovalRequiredError, AuthorityDeniedError } from '../src/guard.js';
+import {
+  githubGitRefShaAuthorityExtractor,
+  githubIssueListSelectedNumberAuthorityExtractor,
+  githubPullRequestCreateNumberAuthorityExtractor
+} from '../src/providers/github.js';
+import {
+  githubContentsWritePathAuthorityExtractor,
+  githubGitRefCreateBranchAuthorityExtractor
+} from '../src/providers/github-coding.js';
+import { createTask } from '../src/task.js';
+
+const repository = 'acme/app';
+const marker = 'coding-fixture-42';
+const baseBranch = 'main';
+const plannedBranch = 'agent/issue-42';
+const targetPath = 'src/auth.js';
+const baseSha = 'a'.repeat(40);
+
+const task = createTask({
+  principal: 'user:demo',
+  agent: 'agent:coder',
+  request: 'Fix the selected issue on one task branch, change only src/auth.js, and open a draft PR. Do not merge or deploy.',
+  permissions: {
+    github: {
+      allow: ['issue.list', 'git.ref.read', 'git.ref.create', 'repo.contents.write', 'pull_request.create'],
+      deny: ['pull_request.merge', 'repo.delete'],
+      constraints: {}
+    }
+  },
+  authority: {
+    repository: { kind: 'github.repository', value: repository },
+    fixture_marker: { kind: 'github.issue.marker', value: marker },
+    base_branch: { kind: 'github.git.branch', value: baseBranch },
+    planned_branch: { kind: 'github.git.branch.intent', value: plannedBranch },
+    target_path: { kind: 'github.repository.path.intent', value: targetPath }
+  },
+  bindings: [
+    { service: 'github', action: 'issue.list', field: 'repository', authority: 'repository' },
+    { service: 'github', action: 'issue.list', field: 'fixture_marker', authority: 'fixture_marker' },
+    { service: 'github', action: 'git.ref.read', field: 'repository', authority: 'repository' },
+    { service: 'github', action: 'git.ref.read', field: 'branch', authority: 'base_branch' },
+    { service: 'github', action: 'git.ref.create', field: 'repository', authority: 'repository' },
+    { service: 'github', action: 'git.ref.create', field: 'branch', authority: 'planned_branch' },
+    { service: 'github', action: 'git.ref.create', field: 'sha', authority: 'base_sha' },
+    { service: 'github', action: 'git.ref.create', field: 'issue_number', authority: 'issue' },
+    { service: 'github', action: 'repo.contents.write', field: 'repository', authority: 'repository' },
+    { service: 'github', action: 'repo.contents.write', field: 'branch', authority: 'task_branch' },
+    { service: 'github', action: 'repo.contents.write', field: 'path', authority: 'target_path' },
+    { service: 'github', action: 'repo.contents.write', field: 'issue_number', authority: 'issue' },
+    { service: 'github', action: 'pull_request.create', field: 'repository', authority: 'repository' },
+    { service: 'github', action: 'pull_request.create', field: 'head', authority: 'task_branch' },
+    { service: 'github', action: 'pull_request.create', field: 'base', authority: 'base_branch' },
+    { service: 'github', action: 'pull_request.create', field: 'issue_number', authority: 'issue' },
+    { service: 'github', action: 'pull_request.create', field: 'changed_path', authority: 'changed_file' }
+  ]
+});
+
+let reads = 0;
+let mutations = 0;
+
+const discovery = await task.run({
+  service: 'github',
+  action: 'issue.list',
+  context: { repository, fixture_marker: marker, state: 'open' }
+}, async () => {
+  reads += 1;
+  return {
+    provider: 'github',
+    selected_issue_number: 42,
+    selected_issue_title: 'Fix auth edge case',
+    selected_issue_match_count: 1,
+    selected_issue_marker: marker
+  };
+});
+const issue = task.authorityFrom(discovery, {
+  name: 'issue',
+  kind: 'github.issue.number',
+  from: ['repository', 'fixture_marker'],
+  extractor: githubIssueListSelectedNumberAuthorityExtractor
+});
+console.log(`DISCOVER -> issue #${issue.value} became task authority`);
+
+const base = await task.run({
+  service: 'github',
+  action: 'git.ref.read',
+  context: { repository, branch: baseBranch }
+}, async () => {
+  reads += 1;
+  return { provider: 'github', branch: baseBranch, ref: `refs/heads/${baseBranch}`, sha: baseSha };
+});
+const baseAuthority = task.authorityFrom(base, {
+  name: 'base_sha',
+  kind: 'github.git.sha',
+  from: ['repository', 'base_branch'],
+  extractor: githubGitRefShaAuthorityExtractor
+});
+
+const branch = await task.run({
+  service: 'github',
+  action: 'git.ref.create',
+  context: { repository, branch: plannedBranch, sha: baseAuthority.value, issue_number: issue.value }
+}, async () => {
+  mutations += 1;
+  return { provider: 'github', branch: plannedBranch, ref: `refs/heads/${plannedBranch}`, sha: baseSha };
+});
+const taskBranch = task.authorityFrom(branch, {
+  name: 'task_branch',
+  kind: 'github.git.branch',
+  from: ['planned_branch', 'issue', 'base_sha'],
+  extractor: githubGitRefCreateBranchAuthorityExtractor
+});
+console.log(`ALLOW -> created only task branch ${taskBranch.value}`);
+
+async function expectStepUp(request, label) {
+  const before = mutations;
+  try {
+    await task.run(request, async () => { mutations += 1; });
+    throw new Error(`${label} unexpectedly executed`);
+  } catch (error) {
+    if (!(error instanceof AuthorityApprovalRequiredError)) throw error;
+    if (mutations !== before) throw new Error(`${label} reached the provider callback`);
+    console.log(`STEP-UP -> ${label}: ${task.explain(error).summary}`);
+  }
+}
+
+await expectStepUp({
+  service: 'github',
+  action: 'repo.contents.write',
+  context: {
+    repository,
+    branch: baseBranch,
+    path: targetPath,
+    issue_number: issue.value,
+    message: 'wrong branch',
+    content_base64: 'd3Jvbmc='
+  }
+}, 'write directly to main');
+
+await expectStepUp({
+  service: 'github',
+  action: 'repo.contents.write',
+  context: {
+    repository,
+    branch: taskBranch.value,
+    path: 'src/admin.js',
+    issue_number: issue.value,
+    message: 'wrong file',
+    content_base64: 'd3Jvbmc='
+  }
+}, 'change an unrelated file');
+
+const write = await task.run({
+  service: 'github',
+  action: 'repo.contents.write',
+  context: {
+    repository,
+    branch: taskBranch.value,
+    path: targetPath,
+    issue_number: issue.value,
+    message: 'Fix issue #42',
+    content_base64: Buffer.from('export const fixed = true;\n').toString('base64')
+  }
+}, async () => {
+  mutations += 1;
+  return {
+    provider: 'github',
+    body: { content: { path: targetPath, sha: 'b'.repeat(40) }, commit: { sha: 'c'.repeat(40) } }
+  };
+});
+const changedFile = task.authorityFrom(write, {
+  name: 'changed_file',
+  kind: 'github.repository.path',
+  from: ['task_branch', 'issue', 'target_path'],
+  extractor: githubContentsWritePathAuthorityExtractor
+});
+console.log(`ALLOW -> changed only ${changedFile.value} on ${taskBranch.value}`);
+
+await expectStepUp({
+  service: 'github',
+  action: 'pull_request.create',
+  context: {
+    repository,
+    head: 'agent/unrelated',
+    base: baseBranch,
+    issue_number: issue.value,
+    changed_path: changedFile.value,
+    title: 'Wrong PR head',
+    draft: true
+  }
+}, 'open PR from another branch');
+
+const pr = await task.run({
+  service: 'github',
+  action: 'pull_request.create',
+  context: {
+    repository,
+    head: taskBranch.value,
+    base: baseBranch,
+    issue_number: issue.value,
+    changed_path: changedFile.value,
+    title: 'Fix issue #42',
+    draft: true
+  }
+}, async () => {
+  mutations += 1;
+  return {
+    provider: 'github',
+    pull_request_number: 77,
+    head: taskBranch.value,
+    base: baseBranch,
+    draft: true
+  };
+});
+const pullRequest = task.authorityFrom(pr, {
+  name: 'pull_request',
+  kind: 'github.pull_request.number',
+  from: ['issue', 'task_branch', 'changed_file'],
+  extractor: githubPullRequestCreateNumberAuthorityExtractor
+});
+console.log(`ALLOW -> opened draft PR #${pullRequest.value}`);
+
+const beforeMerge = mutations;
+try {
+  await task.run({
+    service: 'github',
+    action: 'pull_request.merge',
+    context: { repository, pull_request_number: pullRequest.value }
+  }, async () => { mutations += 1; });
+  throw new Error('merge unexpectedly executed');
+} catch (error) {
+  if (!(error instanceof AuthorityDeniedError)) throw error;
+  if (mutations !== beforeMerge) throw new Error('merge reached provider callback');
+  console.log('DENY -> merge remains outside task authority');
+}
+
+task.complete('draft PR opened');
+console.log(`PASS -> reads=${reads}, authorized mutations=${mutations}; unrelated writes/PRs and merge executed zero callbacks`);

package/examples/task-first-finance.js

@@ -0,0 +1,223 @@
+import { AuthorityApprovalRequiredError, AuthorityDeniedError } from '../src/guard.js';
+import { createTask } from '../src/task.js';
+
+const ticketId = 'ticket:4821';
+
+function operationExtractor({ service, action, selector, extractorId, validate }) {
+  return ({ receipt, output } = {}) => {
+    if (receipt?.service !== service || receipt?.action !== action) {
+      const error = new Error(`${extractorId} received the wrong operation`);
+      error.code = 'trusted_extractor_operation_mismatch';
+      throw error;
+    }
+    const value = selector.split('.').slice(1).reduce((current, key) => current?.[key], output);
+    if (!validate(value)) {
+      const error = new Error(`${extractorId} received invalid normalized output`);
+      error.code = 'trusted_extractor_output_invalid';
+      throw error;
+    }
+    return { extractor_id: extractorId, selector };
+  };
+}
+
+const orderIdExtractor = operationExtractor({
+  service: 'helpdesk',
+  action: 'ticket.read',
+  selector: 'output.order_id',
+  extractorId: 'demo.helpdesk.ticket.order-id.v1',
+  validate: (value) => typeof value === 'string' && value.startsWith('order:')
+});
+
+const paymentIdExtractor = operationExtractor({
+  service: 'commerce',
+  action: 'order.read',
+  selector: 'output.payment_id',
+  extractorId: 'demo.commerce.order.payment-id.v1',
+  validate: (value) => typeof value === 'string' && value.startsWith('payment:')
+});
+
+const paymentAmountExtractor = operationExtractor({
+  service: 'payments',
+  action: 'payment.read',
+  selector: 'output.amount_minor',
+  extractorId: 'demo.payments.payment.amount-minor.v1',
+  validate: (value) => Number.isSafeInteger(value) && value >= 0
+});
+
+const paymentCurrencyExtractor = operationExtractor({
+  service: 'payments',
+  action: 'payment.read',
+  selector: 'output.currency',
+  extractorId: 'demo.payments.payment.currency.v1',
+  validate: (value) => typeof value === 'string' && /^[A-Z]{3}$/.test(value)
+});
+
+const task = createTask({
+  principal: 'user:finance-demo',
+  agent: 'agent:finance-demo',
+  request: 'Resolve this support ticket by refunding only its affected payment',
+  permissions: {
+    helpdesk: {
+      allow: ['ticket.read'],
+      constraints: { ticket_id: [ticketId] }
+    },
+    commerce: {
+      allow: ['order.read'],
+      constraints: {}
+    },
+    payments: {
+      allow: ['payment.read', 'refund.create'],
+      deny: ['payment.capture', 'refund.delete'],
+      constraints: {}
+    }
+  },
+  authority: {
+    ticket: { kind: 'helpdesk.ticket', value: ticketId }
+  },
+  bindings: [
+    { service: 'helpdesk', action: 'ticket.read', field: 'ticket_id', authority: 'ticket' },
+    { service: 'commerce', action: 'order.read', field: 'order_id', authority: 'order' },
+    { service: 'payments', action: 'payment.read', field: 'payment_id', authority: 'payment' },
+    { service: 'payments', action: 'refund.create', field: 'payment_id', authority: 'payment' },
+    { service: 'payments', action: 'refund.create', field: 'amount_minor', authority: 'paymentAmount' },
+    { service: 'payments', action: 'refund.create', field: 'currency', authority: 'paymentCurrency' }
+  ]
+});
+
+let ticketReads = 0;
+let orderReads = 0;
+let paymentReads = 0;
+let refunds = 0;
+
+console.log('Task: Resolve one support ticket by refunding only the payment discovered through that ticket');
+
+console.log('1. Read the exact authorized ticket');
+const ticket = await task.run({
+  service: 'helpdesk',
+  action: 'ticket.read',
+  context: { ticket_id: ticketId }
+}, async () => {
+  ticketReads += 1;
+  return { ticket_id: ticketId, customer_id: 'customer:77', order_id: 'order:991' };
+});
+
+const order = task.authorityFrom(ticket, {
+  name: 'order',
+  kind: 'commerce.order',
+  from: 'ticket',
+  extractor: orderIdExtractor
+});
+console.log(`   authority -> ${order.value}`);
+
+console.log('2. Read only the order established by the ticket');
+const orderRead = await task.run({
+  service: 'commerce',
+  action: 'order.read',
+  context: { order_id: order.value }
+}, async () => {
+  orderReads += 1;
+  return { order_id: order.value, payment_id: 'payment:abc123' };
+});
+
+const payment = task.authorityFrom(orderRead, {
+  name: 'payment',
+  kind: 'payments.payment',
+  from: 'order',
+  extractor: paymentIdExtractor
+});
+console.log(`   authority -> ${payment.value}`);
+
+console.log('3. Read only the payment established by the order');
+const paymentRead = await task.run({
+  service: 'payments',
+  action: 'payment.read',
+  context: { payment_id: payment.value }
+}, async () => {
+  paymentReads += 1;
+  return { payment_id: payment.value, amount_minor: 12500, currency: 'USD' };
+});
+
+const amount = task.authorityFrom(paymentRead, {
+  name: 'paymentAmount',
+  kind: 'money.minor-units',
+  from: 'payment',
+  extractor: paymentAmountExtractor
+});
+const currency = task.authorityFrom(paymentRead, {
+  name: 'paymentCurrency',
+  kind: 'money.currency',
+  from: 'payment',
+  extractor: paymentCurrencyExtractor
+});
+console.log(`   authority -> ${amount.value} minor units ${currency.value}`);
+
+console.log('4. Refund exactly the payment established by the authorized chain');
+await task.run({
+  service: 'payments',
+  action: 'refund.create',
+  context: {
+    payment_id: payment.value,
+    amount_minor: amount.value,
+    currency: currency.value
+  }
+}, async () => {
+  refunds += 1;
+  return { refund_id: 'refund:full-1', status: 'succeeded' };
+});
+console.log('   ALLOW -> exact full refund executed');
+
+async function proveRefundBlocked(label, context) {
+  try {
+    await task.run({ service: 'payments', action: 'refund.create', context }, async () => {
+      refunds += 1;
+      return { refund_id: 'must-not-exist' };
+    });
+    throw new Error(`${label} unexpectedly executed`);
+  } catch (error) {
+    if (!(error instanceof AuthorityApprovalRequiredError) || error.code !== 'authority_delta_required') {
+      throw error;
+    }
+    console.log(`   STEP-UP -> ${label} blocked before refund callback`);
+    console.log(`   ${task.explain(error).summary}`);
+  }
+}
+
+console.log('5. Prove unrelated payment and amount changes do not inherit the task authority');
+await proveRefundBlocked('unrelated payment', {
+  payment_id: 'payment:other',
+  amount_minor: amount.value,
+  currency: currency.value
+});
+await proveRefundBlocked('over-refund', {
+  payment_id: payment.value,
+  amount_minor: 15000,
+  currency: currency.value
+});
+await proveRefundBlocked('partial refund under the current exact-binding model', {
+  payment_id: payment.value,
+  amount_minor: 5000,
+  currency: currency.value
+});
+
+if (refunds !== 1) throw new Error(`expected exactly one refund callback, got ${refunds}`);
+
+console.log('6. Complete the task and remove the remaining refund authority');
+task.complete('ticket refund completed');
+try {
+  await task.run({
+    service: 'payments',
+    action: 'refund.create',
+    context: { payment_id: payment.value, amount_minor: amount.value, currency: currency.value }
+  }, async () => {
+    refunds += 1;
+    return { refund_id: 'must-not-run-after-completion' };
+  });
+  throw new Error('post-completion refund unexpectedly executed');
+} catch (error) {
+  if (!(error instanceof AuthorityDeniedError) || error.code !== 'task_lease_completed') throw error;
+  console.log('   DENY -> completed task cannot refund again');
+}
+
+console.log(`Provider-shaped callbacks: tickets=${ticketReads}, orders=${orderReads}, payments=${paymentReads}, refunds=${refunds}`);
+console.log('PASS -> ticket -> order -> payment -> exact refund authority stayed on one evidence-derived lineage');
+console.log('PRODUCT GAP -> partial refunds currently step up because Task Lease bindings are exact equality; derived numeric <= is intentionally not implemented yet');