@nullsquare/agent-authority 0.4.4 → 0.4.6

package/docs/durable-task-leases.md

@@ -0,0 +1,336 @@
+# Durable Task Leases
+
+Agent Authority v0.4.x originally kept Task Lease state only in process memory. That was useful for proving task-bounded authority, but process restart could lose task completion, expiry state, bindings and provenance lineage.
+
+M2 now has three local-host durability layers:
+
+1. authenticated recovery of Task Lease authority state;
+2. transactional mutation with local serialization and stale-writer compare-and-swap protection;
+3. `DurableTaskLeaseSession`, which routes normal Task Lease mutations through that transaction boundary automatically.
+
+The core authority model is unchanged.
+
+## Security goal
+
+Restart or concurrent local workers must never increase authority by reconstructing, overwriting or racing durable state.
+
+```text
+live Task Lease
+      |
+      v
+atomic authenticated snapshot
+      |
+ process restart
+      |
+      v
+authenticate + validate + recover
+      |
+      v
+recovered Task Lease authority
+      <=
+pre-restart Task Lease authority
+```
+
+For updates:
+
+```text
+worker view @ hash H0
+        |
+        v
+acquire per-lease lock
+        |
+reload authenticated current state
+        |
+expected hash == current hash ?
+        |
+      yes
+        v
+apply one synchronous lease mutation
+        |
+validate complete authority snapshot
+        |
+atomic authenticated replacement -> H1
+```
+
+A stale worker that still expects `H0` after another worker committed `H1` receives `task_lease_state_conflict`. It does not overwrite `H1`.
+
+A state file is not authority merely because it contains plausible JSON.
+
+## Snapshot contents
+
+`TaskLease.snapshot()` preserves:
+
+- lease ID;
+- exact mission ID and mission hash;
+- principal and agent IDs;
+- original task request;
+- active/completed status;
+- creation, expiry and completion timestamps;
+- completion reason;
+- exact context bindings;
+- root authority facts;
+- derived facts and parent lineage;
+- strict execution-evidence provenance, including receipt, request, provider-output and evidence hashes.
+
+Snapshots do **not** contain provider credentials.
+
+## Recovery validation
+
+`TaskLease.restore()` / `restoreTaskLease()` validate the recovered state before reconstructing a lease.
+
+Recovery rejects:
+
+- a different mission ID;
+- the same mission ID paired with a different mission definition/hash;
+- a different principal or agent;
+- unsupported snapshot versions;
+- invalid active/completed state;
+- invalid timestamps;
+- duplicate authority fact IDs;
+- missing parent facts;
+- cyclic authority lineage;
+- derived facts claiming another Task Lease ID;
+- derived facts missing receipt/request/selector provenance;
+- `execution-evidence-v1` facts missing extractor/output/evidence hashes.
+
+`restoreTaskLease()` validates state structure and mission identity, but it does not authenticate where arbitrary caller-supplied JSON came from. Durable applications should load persisted authority through an authenticated store.
+
+## Authenticated local store
+
+`JsonFileTaskLeaseStore` is the first reference persistence backend.
+
+```js
+import { JsonFileTaskLeaseStore } from '@nullsquare/agent-authority/storage';
+
+const store = new JsonFileTaskLeaseStore({
+  dir: config.paths.task_leases,
+  keyPath: config.paths.master_key
+});
+
+const created = store.save(lease);
+
+// Later, after process restart:
+const recovered = store.load({
+  mission,
+  lease_id: leaseId
+});
+```
+
+The store snapshots the whole lease, records its hash, authenticates the envelope with HMAC-SHA256 using a purpose-derived local key, atomically writes it, then verifies identity/MAC/mission hash/fact graph/reconstructed lease hash before returning recovered authority.
+
+The default local configuration reserves:
+
+```text
+~/.agent-authority/state/task-leases/
+```
+
+## Save semantics
+
+`save()` is deliberately not last-writer-wins.
+
+For a lease that does not yet exist, `store.save(lease)` creates the authenticated durable state.
+
+For an existing lease:
+
+- saving an unchanged recovered state is idempotent;
+- replacing changed state requires `expected_lease_hash`;
+- attempting to replace changed state without an expected hash fails with `task_lease_state_conflict`.
+
+For normal authority mutations, prefer `transact()` or `DurableTaskLeaseSession` rather than mutating a recovered lease and then saving it.
+
+## Transactional mutation
+
+`store.transact()` is the low-level durable read-modify-write boundary.
+
+```js
+const view = store.load({ mission, lease_id });
+
+const committed = store.transact({
+  mission,
+  lease_id,
+  expected_lease_hash: view.hash(),
+  mutate: (lease) => {
+    lease.addRoot({
+      fact_id: 'fact:region',
+      kind: 'demo.region',
+      value: 'us-east'
+    });
+
+    lease.bind({
+      service: 'demo',
+      action: 'item.access',
+      context_field: 'region',
+      fact_id: 'fact:region'
+    });
+  }
+});
+```
+
+A transaction acquires a per-lease local lock, reloads/authenticates current state, checks the expected hash, applies one synchronous mutation, validates the full authority graph, atomically writes a new authenticated envelope, and returns the previous/new hashes. Throwing or async callbacks do not persist mutated state.
+
+The mutation callback should modify **Task Lease state only**. Provider calls, network requests and other external side effects do not belong inside this synchronous local transaction.
+
+## DurableTaskLeaseSession
+
+Most callers should not manually orchestrate `load()` + `transact()` for ordinary Task Lease changes. `DurableTaskLeaseSession` keeps the current recovered hash and applies normal Task Lease mutations through compare-and-swap automatically.
+
+```js
+import {
+  createDurableTaskLeaseSession,
+  openDurableTaskLeaseSession
+} from '@nullsquare/agent-authority/durable-task-lease';
+import { createTaskLeaseGuard } from '@nullsquare/agent-authority/guard';
+
+const session = createDurableTaskLeaseSession({
+  store,
+  lease
+});
+
+const guard = createTaskLeaseGuard({
+  lease: session,
+  runtime
+});
+
+const read = await guard.run(
+  {
+    service: 'gmail',
+    action: 'thread.read',
+    context: { thread_id: 'thread:demo-91' }
+  },
+  () => gmail.readThread('thread:demo-91')
+);
+
+session.deriveFromEvidence({
+  fact_id: 'fact:sender-email',
+  kind: 'email.address',
+  from: ['fact:thread'],
+  receipt: read.receipt,
+  evidence: read.evidence,
+  output: read.output,
+  extractor: gmailThreadSenderAuthorityExtractor
+});
+```
+
+The session exposes durable equivalents of the ordinary state-changing methods:
+
+- `addRoot()`;
+- legacy `derive()`;
+- `deriveFromEvidence()`;
+- `bind()`;
+- `complete()`.
+
+Each mutation uses the session's current lease hash as `expected_lease_hash`. On success the session adopts the committed lease and new hash. On conflict it does **not** auto-retry or replay the mutation. The caller must `refresh()` and reconsider the intended change against the newer authority state.
+
+The session does not expose its mutable internal `TaskLease`. `mission`, snapshots and facts are returned as detached values so mutating a caller-visible object does not mutate durable authority by reference.
+
+### Guard behavior
+
+`DurableTaskLeaseSession` implements `evaluate(runtime, request)`, so it can be passed anywhere a Task Lease is accepted by the current guard/MCP/broker interfaces.
+
+Security-critical `evaluate()` calls `refresh()` first. That means a stale worker which another worker has already completed or narrowed will observe the durable state before the next authority decision.
+
+Example:
+
+```text
+worker B cached active H0
+worker A complete() -> H1 completed
+worker B guard.run(...)
+    -> session.evaluate()
+    -> refresh H1
+    -> task_lease_completed
+    -> effect callback never runs
+```
+
+### Evidence race behavior
+
+Suppose worker B receives an ALLOW receipt and execution evidence at H0, but worker A changes durable Task Lease state to H1 before B calls `deriveFromEvidence()`.
+
+The session does not silently derive against H1:
+
+```text
+B guarded read @ H0 -> receipt + evidence
+A commits authority state H1
+B deriveFromEvidence(... expected H0 ...)
+    -> task_lease_state_conflict
+    -> no derived fact persisted
+```
+
+B must refresh and explicitly reconsider whether the old provider result still justifies a derived authority fact under H1.
+
+## Local worker concurrency
+
+The local lock prevents two cooperating Agent Authority processes from entering the same per-lease durable mutation window at the same time.
+
+If a worker observes an already-held lock, it fails closed with:
+
+```text
+task_lease_state_locked
+```
+
+The lock is intentionally local-filesystem scoped. A crashed process may leave a lock directory behind; this is an availability failure rather than an authority-expansion failure and should be repaired explicitly rather than silently deleting a lock that might still belong to a live worker.
+
+The expected lease hash adds optimistic stale-view protection:
+
+```text
+worker A loads H0
+worker B loads H0
+worker A transact(H0) -> H1
+worker B transact(H0) -> task_lease_state_conflict
+```
+
+Worker B must reload H1 and reconsider its intended mutation against the new authority state.
+
+## Properties under test
+
+`test/task-lease-persistence.test.js` and `test/durable-task-lease-session.test.js` prove that:
+
+- strict `execution-evidence-v1` facts survive recovery with provenance hashes unchanged;
+- unrelated resources still require step-up after restart;
+- completion and expiry survive restart;
+- disk tampering, changed mission definitions and malformed lineage fail closed;
+- fact+binding changes can commit as one authenticated snapshot;
+- stale worker views cannot overwrite newer authority;
+- raw changed saves cannot bypass compare-and-swap;
+- overlapping local transactions fail closed;
+- throwing or async transactions leave durable state unchanged;
+- a durable session can perform strict evidence derivation and reopen with identical authority behavior;
+- another worker's completion is observed before the stale session's next guarded effect;
+- stale semantic mutations are not automatically replayed;
+- evidence captured at H0 cannot be automatically derived after another worker commits H1;
+- caller-visible mission/snapshot objects do not expose mutable aliases to the session's internal authority state.
+
+## Trust boundary
+
+This persistence mechanism protects authority state on the **trusted local Agent Authority host** against accidental corruption, caller-controlled state-file modification without the authentication key, and stale cooperating local writers.
+
+It is not hostile-host containment. An attacker or malicious host process that can read the Agent Authority master key can authenticate modified local state and remains outside this guarantee.
+
+The HMAC does not make provider output cryptographically attested by the provider. The per-lease lock is local filesystem coordination, not distributed consensus.
+
+## Important remaining TOCTOU boundary
+
+Refreshing before `evaluate()` closes stale-state decisions, but it does **not** make an asynchronous external provider effect and Task Lease state transition one distributed transaction.
+
+There is still a possible sequence:
+
+```text
+worker B refresh/evaluate -> ALLOW
+worker A completes lease
+worker B provider effect begins
+```
+
+The ordinary guard correctly checks authority immediately before invoking its effect callback, but another process can change durable state after that decision. Agent Authority does not yet hold the local lease lock across a network/provider effect, and it should not do so casually.
+
+Crash-safe/provider-side coordination, idempotency and execution receipts need a dedicated design rather than pretending a filesystem transaction covers remote side effects.
+
+## What is not durable yet
+
+Still open:
+
+- crash-safe coupling between provider side effects, execution receipts and Task Lease state changes;
+- durable application of an explicitly approved authority delta;
+- a durable lineage query/index across many leases;
+- stronger multi-process stress tests and recovery tooling for abandoned local locks;
+- remote/KMS-backed persistence and distributed coordination where required.
+
+The next M2 work should tackle approved authority deltas and execution/effect coupling as separate explicit problems rather than broadening the persistence layer into a general database abstraction.

package/docs/npm-release.md

@@ -6,31 +6,37 @@ Before any publication:
 
 1. the release commit must pass CI, CodeQL, live GitHub validation, current AI SDK integration validation, and packed-consumer validation;
 2. `npm pack` must contain the documented public exports;
-3. a fresh Node.js 20 consumer must install the tarball and run the core Task Lease smoke test;
+3. a fresh Node.js 20 consumer must install the tarball and run the current public behavior smoke test;
 4. the optional AI SDK integration must import without making `ai` a production dependency;
 5. the registry package must be public and its repository metadata must point to `https://github.com/Null-Square/agent-authority`.
 
 After publication, verify from a fresh project with:
 
 ```bash
-npm install @nullsquare/agent-authority@0.4.3
+npm install @nullsquare/agent-authority@0.4.5
 ```
 
 Then run the same consumer smoke flow through the registry-installed package. Registry verification is part of the release gate; a successful `npm publish` command alone is not sufficient.
 
-The repository also includes `.github/workflows/verify-npm-registry.yml`, which verifies registry visibility and a clean consumer install. For v0.4.3 it additionally verifies the public `@nullsquare/agent-authority/authority-evidence` API plus both reviewed provider authority extractors:
+The repository includes `.github/workflows/verify-npm-registry.yml`, which verifies registry visibility, a clean Node.js 20 install, and the current public behavior from the registry artifact. For v0.4.5 the consumer exercises:
 
-- `gmailThreadSenderAuthorityExtractor` from `@nullsquare/agent-authority/providers/google`;
-- `githubIssueListSelectedNumberAuthorityExtractor` from `@nullsquare/agent-authority/providers/github`.
+- execution evidence and the reviewed Google/GitHub authority extractors;
+- `ExecutingAuthorityRuntime.executeTaskLease()` and `MissionMcpGateway` transport surfaces;
+- `JsonFileTaskLeaseStore` from `@nullsquare/agent-authority/storage`;
+- `DurableTaskLeaseSession` and `createDurableTaskLeaseSession()` from `@nullsquare/agent-authority/durable-task-lease`;
+- durable allow / `authority_delta_required` / completion behavior;
+- the requirement that the optional `ai` package is not installed as a production dependency.
 
-This makes the registry artifact verification cover the same two-provider execution-evidence surface exercised by the repository conformance suite.
+This makes the registry artifact verification cover the same public durability, evidence and transport surfaces exercised by the repository tests rather than checking export names alone.
+
+The v0.4.5 independent registry verification passed after publication: npm visibility succeeded and the fresh registry-installed consumer completed the durable Task Lease smoke.
 
 ## npm vs GitHub release surfaces
 
 Publishing to the public npm registry does not automatically create either a GitHub Release or a GitHub Packages entry.
 
 - **npm registry** — `npm publish --access public` publishes `@nullsquare/agent-authority` to `registry.npmjs.org` / npmjs.com. This is the package users install with `npm install`.
-- **GitHub Releases** — a separate GitHub object, normally backed by a Git tag such as `v0.4.3`. A release must be created explicitly or by release automation.
+- **GitHub Releases** — a separate GitHub object, normally backed by a Git tag such as `v0.4.5`. A release must be created explicitly or by release automation.
 - **GitHub Packages** — a separate package registry. It only appears when the package is published to GitHub's npm registry (`npm.pkg.github.com`); publishing to npmjs.com does not populate it.
 
 Agent Authority currently uses npmjs.com as its public package registry. Therefore an empty GitHub **Packages** section is expected unless the project intentionally adopts dual publication. A GitHub **Release** is still useful for source-release discoverability and should track published versions, but it is independent from npm publication.

package/docs/product-proof.md

@@ -0,0 +1,185 @@
+# Product proof gate
+
+Agent Authority has enough security machinery to validate its core thesis. The next risk is no longer "can we make the invariant stronger?" It is "will an agent developer actually install and keep this layer?"
+
+The product thesis is:
+
+> **Your agent may use the permissions it already has only for the task the user actually gave it.**
+
+The differentiated mechanism is narrower:
+
+> **Authority may follow exact resources discovered through already-authorized execution, without turning those resources into standing account permissions.**
+
+Everything else in the repository exists to make those two statements true.
+
+## Developer mental model
+
+The preferred public experience should stay close to three concepts:
+
+```text
+Task -> Effect -> Authority
+```
+
+A developer should not need to understand Mission internals, Task Lease hashing, execution evidence envelopes, CAS persistence or transport adapters before getting value.
+
+Those primitives remain available for advanced integrations and audits.
+
+## Product-facing API
+
+The task-first facade intentionally composes the existing primitives instead of replacing them:
+
+```js
+import { createTask } from '@nullsquare/agent-authority/task';
+
+const task = createTask({
+  principal: 'user:me',
+  agent: 'agent:assistant',
+  request: 'Handle issue #42',
+  permissions: {
+    github: {
+      allow: ['issue.list', 'issue.comment'],
+      deny: ['repo.delete'],
+      constraints: { repository: ['acme/app'] }
+    }
+  },
+  authority: {
+    repository: { kind: 'github.repository', value: 'acme/app' }
+  }
+});
+
+const discovery = await task.run(request, () => github.listIssues());
+const issue = task.authorityFrom(discovery, {
+  name: 'issue',
+  kind: 'github.issue.number',
+  from: 'repository',
+  extractor
+});
+
+task.bind({
+  service: 'github',
+  action: 'issue.comment',
+  field: 'issue_number',
+  authority: 'issue'
+});
+```
+
+The low-level Mission and Task Lease APIs remain the source of truth. The facade must never add authority that those lower layers would reject.
+
+## Adoption gate
+
+Do not prioritize another deep authorization subsystem until the following are demonstrated:
+
+- [ ] a new developer can run a meaningful task-first example in under 10 minutes;
+- [ ] at least three real workflow examples exist: coding, support/communications, and operations/finance;
+- [ ] the same task-first API works in-memory and with durable local state;
+- [ ] useful-task completion stays high under the product benchmark;
+- [ ] normal task actions do not trigger unnecessary approvals;
+- [ ] unrelated-resource effects execute zero provider callbacks;
+- [ ] approval/step-up output explains the established authority and requested delta clearly;
+- [ ] at least one external developer uses the package without project-author assistance.
+
+## Utility metrics
+
+Security tests remain required, but product work should additionally track:
+
+```text
+normal task completion rate
+false approval rate
+true authority-delta step-up rate
+unauthorized effect rate
+provider effects per completed task
+integration lines required for a representative workflow
+```
+
+`npm run benchmark:task` is the first deterministic fixture for these metrics. It is not a real-world benchmark and must not be marketed as one. Its purpose is to make utility regressions visible alongside security regressions.
+
+The current fixture target is:
+
+```text
+normal task completion rate = 100%
+false approval rate = 0%
+true authority-delta step-up rate = 100%
+unauthorized effect rate = 0%
+```
+
+Real provider/harness benchmarks should replace or supplement the fixture as the product matures.
+
+## Three product proofs
+
+### Coding agent
+
+Task:
+
+> Fix issue #42 and open a PR. Do not merge or deploy.
+
+Desired authority lineage:
+
+```text
+repository -> issue -> task branch -> changed files -> pull request
+```
+
+Unrelated repositories, issues, merge and deploy remain outside the task.
+
+### Support / communications agent
+
+Task:
+
+> Handle this customer email.
+
+Desired authority lineage:
+
+```text
+email thread -> customer -> meeting / CRM record / reply target
+```
+
+The underlying connected account may have broad access; task authority follows only the customer/resource discovered through the authorized thread.
+
+### Operations / finance agent
+
+Task:
+
+> Resolve this ticket and refund the affected order.
+
+Desired authority lineage:
+
+```text
+ticket -> customer -> order -> payment -> refund <= original payment
+```
+
+This is the strongest long-term proof because it combines resource lineage with an amount ceiling.
+
+## Freeze list
+
+Until the adoption gate moves, the following remain research backlog unless a real workflow proves they are blocking adoption or safety:
+
+- distributed Task Lease databases;
+- generic storage abstraction layers;
+- provider-signed attestation protocols;
+- another token or identity format;
+- a general delegation standard;
+- a proprietary policy DSL;
+- broad OAuth/OIDC platform work;
+- another MCP control plane;
+- A2A protocol implementation;
+- large connector-count expansion;
+- full distributed transaction semantics across arbitrary remote providers.
+
+The existing durability, evidence, transport and credential primitives should be reused rather than deepened by default.
+
+## Boundary discipline
+
+Agent Authority should integrate with identity providers, OAuth systems, MCP gateways, policy engines and agent frameworks rather than compete with all of them.
+
+The intended position is:
+
+```text
+agent reasoning
+      |
+      v
+Agent Authority
+      |
+      v
+existing SDK / MCP / gateway / OAuth / provider
+```
+
+The product wins if that middle layer is small to adopt, preserves useful autonomy, and technically prevents the same standing account permission from becoming unrelated task authority.

package/docs/transport-invariance.md

@@ -19,7 +19,7 @@ same Task Lease + same established authority fact
 
 Changing the transport must not broaden task authority.
 
-## Executable proof
+## Executable transport proof
 
 `test/transport-invariance.test.js` creates one Task Lease and one derived authority fact.
 
@@ -97,21 +97,57 @@ io.nullsquare.agent-authority/task_lease_id
 
 The remote MCP handler and loopback proxy can pass the same Task Lease into the gateway.
 
+## AI SDK harness proof
+
+`test/integrations/ai-sdk.integration.mjs` drives the current Vercel AI SDK `ToolLoopAgent` with the output of `protectAiSdkTools()` as its executable tool set.
+
+The positive path asks the model to use the task-bound GitHub issue. The protected tool executes exactly once.
+
+The same real agent loop then exercises three adversarial paths:
+
+```text
+unrelated issue
+    -> AuthorityApprovalRequiredError
+    -> authority_delta_required
+    -> underlying effect count remains 0
+
+executable tool with no Agent Authority mapping
+    -> UnmappedAiSdkToolError
+    -> ai_sdk_tool_unmapped
+    -> underlying effect count remains 0
+
+completed Task Lease
+    -> AuthorityDeniedError
+    -> task_lease_completed
+    -> underlying effect count remains 0
+```
+
+The AI SDK represents tool execution failures in the generated result as `tool-error` content parts rather than requiring `agent.generate()` itself to reject. The proof therefore checks both sides of the boundary: the harness records the exact Agent Authority error and the protected underlying side effect never runs.
+
+This matters because the model is not calling the wrapped function directly in these cases. The real `ToolLoopAgent` selects and invokes the tool through its normal tool loop, and the Agent Authority wrapper remains the executable boundary.
+
 ## What this proves
 
-- Task-Lease narrowing is no longer specific to the direct SDK guard;
+- Task-Lease narrowing is not specific to the direct SDK guard;
 - MCP cannot silently fall back to Mission-only authority when explicitly configured with a Task Lease;
-- brokered provider execution can enforce the same Task Lease before credential-backed execution;
-- one derived fact can constrain all three execution paths;
-- task completion invalidates the same authority across all three paths;
-- broker credentials may remain connected after task authority disappears.
+- brokered provider execution enforces the same Task Lease before credential-backed execution;
+- one evidence-derived fact can constrain direct SDK, MCP and brokered execution;
+- task completion invalidates the same authority across those execution paths;
+- broker credentials may remain connected after task authority disappears;
+- a configured Vercel AI SDK `ToolLoopAgent` whose executable tool set is passed through `protectAiSdkTools()` cannot use its normal tool path to bypass Task-Lease narrowing;
+- executable AI SDK tools without an Agent Authority request mapping fail closed before their underlying effect executes.
+
+## Boundary of the claim
+
+This is an execution-boundary guarantee, not hostile-host containment.
+
+It does **not** prove that a malicious application host cannot deliberately give the model another unwrapped tool, direct provider credential, shell, network client or other execution channel outside Agent Authority.
 
-## What this does not prove yet
+It also does not yet prove that:
 
-- a hostile harness cannot bypass Agent Authority through an entirely separate unguarded tool path;
 - Task Lease state survives process restart;
-- the same lease is serialized and recovered across separate processes or hosts;
+- the same lease can be serialized and safely recovered across separate processes or hosts;
 - an approved authority delta is durably applied back into a running lease;
 - provider outputs are cryptographically attested by providers.
 
-The remaining M4 target is at least one real harness/tool-middleware integration where executable tool calls cannot bypass the Task Lease boundary.
+M4 is complete for configured Agent Authority execution boundaries: direct SDK, MCP, brokered execution and the Vercel AI SDK `ToolLoopAgent` protected-tool path now preserve task authority without silent expansion. Durability, cross-process recovery and hostile-host containment are separate problems.