@nullsquare/agent-authority 0.4.0 → 0.4.2

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-![Agent Authority](docs/assets/agent-authority-cover.svg)
+![Agent Authority](docs/assets/agent-authority-cover-editorial-v2.png)
 
 # Agent Authority
 
@@ -8,12 +8,20 @@
 
 **Agent Authority turns a human-approved task into temporary execution authority, then keeps that authority bounded as the agent discovers resources, crosses tools, and performs side effects.**
 
-[Task Leases](docs/task-leases.md) · [Validate](docs/validation.md) · [Integration contract](docs/integration-contract.md) · [CLI](docs/cli.md) · [Architecture](docs/architecture.md) · [Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md)
+[Task Leases](docs/task-leases.md) · [Validate](docs/validation.md) · [Google proof](docs/live-google-validation.md) · [Integration contract](docs/integration-contract.md) · [CLI](docs/cli.md) · [Architecture](docs/architecture.md) · [Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md)
 
-> **Status: public pre-alpha / v0.4 validation candidate.** The repository has a working policy runtime, protocol-neutral guard, Task Lease prototype with provenance-bound derived facts, approvals, revocation, idempotency, credential isolation, MCP v2 gateway, GitHub brokered execution, CI and CodeQL. It is not production-ready yet.
+> **Status: public pre-alpha / v0.4.1 Developer Preview.** Published on npm as `@nullsquare/agent-authority`. The repository has a working policy runtime, protocol-neutral guard, Task Lease prototype with provenance-bound derived facts, approvals, revocation, idempotency, credential isolation, MCP v2 gateway, GitHub and Google provider integrations, CI and CodeQL. It is not production-ready yet.
 
 </div>
 
+## Install
+
+Requires Node.js 20+.
+
+```bash
+npm install @nullsquare/agent-authority
+```
+
 ## The problem
 
 AI agents increasingly receive broad provider permissions so they can complete narrow human tasks.
@@ -144,6 +152,8 @@ The demo performs this flow without provider credentials:
 
 The side-effect callbacks for blocked actions never run.
 
+The repository also includes a real Gmail → Calendar validation path and a reusable Google provider adapter. See [Live Gmail → Calendar validation](docs/live-google-validation.md).
+
 ## Minimal developer API
 
 ```js
@@ -261,6 +271,7 @@ The long-term validation target is the **same Task Lease and authority lineage a
 - AES-256-GCM local encrypted secret store
 - safe reconnect cleanup
 - GitHub brokered execution without returning the token to the agent
+- Google REST provider mappings for Gmail thread reads and Calendar event mutations
 - short-lived signed local agent-instance tokens
 - local CLI/daemon
 
@@ -270,6 +281,7 @@ The long-term validation target is the **same Task Lease and authority lineage a
 - Node 20 and Node 22 CI
 - coverage run
 - package checks
+- clean-consumer npm registry verification
 - CodeQL
 
 ## What is different from OAuth, IAM and MCP authorization?

package/ROADMAP.md

@@ -55,10 +55,15 @@ never silently grow
 - [x] independent task-lease expiry
 - [x] task-lease ID/hash in receipts
 - [x] self-contained cross-system demo: Gmail-thread fact -> Calendar attendee
-- [ ] exercise the same pattern against two real provider operations
+- [x] reusable Google REST adapter for Gmail thread reads and Calendar event mutations
+- [x] adversarial Gmail -> Calendar test proving unrelated and post-completion effects never invoke provider callbacks
+- [x] real connected-account smoke: Gmail self-test fixture -> exact attendee -> temporary Calendar event -> cleanup
+- [ ] rerun the same proof as a public GitHub Actions job after repository Google OAuth secrets are configured
 
 **Success criterion:** a real multi-step agent workflow discovers a resource during an authorized read and can use exactly that resource in a later side effect, while an unrelated resource is technically blocked without requiring approval for every normal task step.
 
+The core cross-provider behavior is now implemented and exercised against connected Gmail and Calendar accounts. Public Actions reproducibility remains the final M1 evidence gate because GitHub cannot reuse an interactive ChatGPT connector credential; the manual workflow is committed and expects a refresh token stored only as repository secrets.
+
 ## M2 — Durable task execution
 
 Build only what the real M1 workflow proves necessary.
@@ -72,19 +77,22 @@ Build only what the real M1 workflow proves necessary.
 
 **Success criterion:** a Task Lease survives daemon/process restarts without gaining authority or losing its provenance lineage.
 
-## M3 — Trustworthy derived facts
+## M3 — Trustworthy derived facts — first slice in progress
 
-Today the trusted host/adapter supplies the derived value and selector. This is an explicit v0.4 limitation.
+The first real Gmail -> Calendar integration showed that recording a host-supplied value plus selector was too weak for the strongest derived-authority claim. The compatibility `derive()` path remains host-trusted; new provider work should prefer execution-bound evidence and reviewed adapter extractors.
 
-- [ ] define a small adapter contract for extracting authority-relevant fields from provider results
-- [ ] bind derived fact records to provider/result evidence where practical
-- [ ] adversarial tests for forged extraction, confused-deputy mappings and stale facts
-- [ ] conformance fixture for operation -> resource-context mappings
-- [ ] define invalidation rules when a source resource changes
+- [x] define a small trusted-adapter extractor contract for authority-relevant normalized provider fields
+- [x] bind successful guarded outputs to the exact ALLOW receipt, request and output hash
+- [x] add `TaskLease.deriveFromEvidence()` so the caller cannot provide the authority value
+- [x] migrate Gmail sender -> Calendar attendee derivation to the evidence-verified path
+- [x] adversarial tests for value substitution, output/evidence tampering, receipt replay, cross-lease reuse, wrong-operation extraction and dangerous selectors
+- [ ] define provider/result attestation stronger than a trusted host output hash where practical
+- [ ] conformance fixtures for reviewed operation -> authority-field mappings across multiple providers
+- [ ] define freshness/invalidation rules when a source resource changes
 
 Do **not** build a general semantic policy language unless real integrations require it.
 
-**Success criterion:** an adapter cannot claim a value was derived from an authorized operation without satisfying the documented extraction/evidence contract.
+**Success criterion:** provider-derived authority cannot be established through the strict path unless the exact guarded output, ALLOW receipt and reviewed extractor contract agree on the selected value. Stronger provider attestation and source invalidation remain separate follow-on problems.
 
 ## M4 — Same task, multiple transports
 
@@ -117,7 +125,7 @@ Only after the task-bound enforcement model is validated.
 - [ ] framework integration examples
 - [ ] `good first issue` tasks based on real mappings/tests
 - [ ] independent contributor implementation of one adapter
-- [ ] release packaging and npm publication
+- [x] release packaging and npm publication
 - [ ] documentation site only when README/docs become too large
 
 ## M7 — Standards interoperability
@@ -142,7 +150,7 @@ Only after operational evidence.
 
 ## Research questions
 
-1. What is the smallest trustworthy representation of an authority-relevant derived fact?
+1. What provider-side or transport-side evidence can strengthen output integrity without turning Agent Authority into an attestation protocol?
 2. How should an approved authority delta update a running task without opening a broader wildcard permission?
 3. How should source-data changes invalidate downstream derived authority?
 4. What provider/tool metadata is required to map operations to resource context reliably?

package/docs/announcement-draft.md

@@ -1,4 +1,4 @@
-# Announcement draft — hold until registry verification
+# Announcement draft — v0.4.0 Developer Preview
 
 NullSquare is open-sourcing **Agent Authority**, an experimental runtime for task-bounded AI agent side effects.
 
@@ -8,6 +8,12 @@ A Task Lease can follow resources discovered through authorized execution withou
 
 The developer preview also includes a Vercel AI SDK integration that wraps ordinary `ToolLoopAgent` tools at their existing `execute` boundary.
 
+Install the published developer preview with:
+
+```bash
+npm install @nullsquare/agent-authority@0.4.0
+```
+
 **Give your agent a task, not your account.**
 
 This is a developer preview, not a claim that NullSquare invented task-scoped authorization and not a production-ready security control. The repository documents the current trust assumptions and bypass boundaries explicitly.

package/docs/evidence.md

@@ -10,6 +10,154 @@ This page records the strongest properties the repository currently demonstrates
 
 The guarantee applies to effects that actually pass through the Agent Authority enforcement boundary. A separate unguarded provider path is outside this guarantee.
 
+## Execution-bound derived authority
+
+The strict derived-authority path now binds provider-derived authority to the exact output returned by an authorized `guard.run()` effect.
+
+A successful guarded effect returns three relevant records:
+
+```text
+ALLOW receipt
+    +
+exact effect output
+    |
+    v
+execution evidence
+(receipt + request + output hash)
+    |
+    v
+reviewed adapter extractor
+(selector only, no value)
+    |
+    v
+TaskLease.deriveFromEvidence()
+    |
+    v
+derived authority fact
+```
+
+`deriveFromEvidence()` does not accept the derived authority value. The trusted adapter extractor chooses a reviewed selector, and Task Lease resolves that selector itself only after verifying the execution evidence.
+
+`test/authority-evidence.test.js` attacks this boundary directly and proves that:
+
+- caller-supplied value substitution does not control the resulting fact;
+- modified provider output is rejected with `evidence_output_mismatch`;
+- modified execution-evidence contents are rejected;
+- evidence cannot be replayed under a second ALLOW receipt;
+- a receipt/evidence chain from another Task Lease is rejected;
+- the Gmail sender extractor rejects the wrong provider operation;
+- dangerous selector paths such as `__proto__` fail closed.
+
+The legacy `TaskLease.derive()` API remains for compatibility and records `derivation_mode: host-trusted`. New provider-derived authority should prefer `deriveFromEvidence()`, which records `derivation_mode: execution-evidence-v1`, extractor ID, source output hash, and execution-evidence hash.
+
+### Boundary of this claim
+
+Execution evidence is an integrity mechanism inside the trusted host/runtime boundary. It proves that the value selected for strict derivation came from the exact output object bound to that Agent Authority receipt.
+
+It does **not** prove that Gmail, GitHub, or another provider cryptographically signed that output, and it does not protect a malicious host that bypasses or replaces the Agent Authority enforcement path. Stronger provider/transport attestation remains open M3 work.
+
+## Cross-provider derived authority — Gmail → Calendar
+
+Agent Authority includes a real Google provider mapping, an adversarial cross-provider test, a live validation script, and an opt-in GitHub Actions workflow.
+
+The task shape is:
+
+```text
+Task root
+one Gmail thread
+        |
+        v
+ALLOW Gmail thread.read
+        |
+        +--> output-bound execution evidence
+        |
+        v
+trusted Gmail sender extractor
+        |
+        v
+derive fact: sender_email
+        |
+        v
+ALLOW Calendar event.create
+attendee == derived sender
+        |
+        +--> different attendee
+        |      -> authority_delta_required
+        |      -> Calendar mutation callback does not run
+        |
+        v
+complete Task Lease
+        |
+        +--> same attendee again
+               -> task_lease_completed
+               -> Calendar mutation callback does not run
+```
+
+### Connected-account smoke — 2026-08-22
+
+A controlled self-test was exercised against the connected NullSquare Gmail and Google Calendar accounts:
+
+1. a temporary validation message was sent from the validation account to itself;
+2. Gmail returned the self-test message with sender `null@nullsquare.net`;
+3. one private, transparent Calendar event was created with exactly `null@nullsquare.net` as attendee;
+4. the temporary Calendar event was deleted immediately after the proof;
+5. the validation email was moved to Trash after cleanup.
+
+No unrelated external person was invited. The smoke test establishes that the concrete Gmail and Calendar operations used by the validation are available and compatible with the intended data shape.
+
+The live connected-account smoke is not presented as a public CI proof of the repository script. The Task Lease zero-call and execution-evidence assertions are separately executable in `test/google-cross-provider.test.js` and `test/authority-evidence.test.js`, and `.github/workflows/live-google-validation.yml` is provided for a rerunnable provider-backed proof once repository Google OAuth secrets are configured.
+
+### Executable local/CI assertions
+
+`test/google-cross-provider.test.js` proves deterministically that:
+
+- the approved Gmail thread callback runs exactly once;
+- its sender becomes a same-lease `execution-evidence-v1` authority fact;
+- one Calendar mutation for that sender runs exactly once;
+- a different attendee produces `authority_delta_required` and the Calendar callback is not invoked;
+- after lease completion, the previously valid attendee produces `task_lease_completed` and the Calendar callback is not invoked again.
+
+`test/google-provider.test.js` validates the Google REST mappings, metadata-only Gmail sender extraction, Calendar attendee body, default `sendUpdates=none`, credential redaction, unsupported-action failure, and mutation classification.
+
+`test/google-authority-extractor.test.js` separately verifies that the reviewed Gmail extractor only accepts canonical `gmail:thread.read` sender output and that the Google adapter advertises it only for the supported authority mapping.
+
+### Public workflow
+
+The manual workflow `Live Google cross-provider validation` mints a short-lived access token from repository secrets and runs `npm run demo:live-google`.
+
+It expects:
+
+```text
+AA_GOOGLE_OAUTH_CLIENT_ID
+AA_GOOGLE_OAUTH_CLIENT_SECRET
+AA_GOOGLE_OAUTH_REFRESH_TOKEN
+```
+
+The refresh token should be restricted to the practical Gmail read-only and Calendar event scopes documented in `docs/live-google-validation.md`.
+
+The connected GitHub tool does not expose repository Actions-secret management, so those secrets are intentionally not installed automatically from this development session.
+
+### What this proves
+
+Taken together, the deterministic Task Lease tests plus the controlled provider smoke show that:
+
+- the Gmail → Calendar derived-authority shape is implemented, not just diagrammed;
+- strict derivation binds the sender to the exact guarded Gmail output before it becomes authority;
+- the exact attendee binding is enforced before the Calendar mutation callback;
+- provider operations exist and work against real Gmail and Calendar accounts;
+- cleanup can keep the live proof reversible and self-contained.
+
+### What this does not prove yet
+
+- a public GitHub Actions run has executed the full repository live script;
+- `sender_email` is cryptographically attested by Gmail rather than integrity-bound to the trusted host's guarded output;
+- the agent cannot bypass Agent Authority if it independently holds a Google credential;
+- Task Lease state is durable across process failure;
+- source-data changes automatically invalidate downstream facts;
+- the refresh-token setup is production credential onboarding.
+
+See [Live Gmail → Calendar validation](live-google-validation.md).
+
 ## Live derived-authority mutation — GitHub
 
 Public fixture: [issue #9](https://github.com/Null-Square/agent-authority/issues/9)
@@ -82,7 +230,7 @@ The temporary validation comment is deleted by test-harness cleanup after the pr
 
 ### What this does not prove
 
-- the host/adapter's extraction of `output.number` is cryptographically verified;
+- the current GitHub example has migrated to a reviewed evidence extractor contract;
 - an agent cannot bypass Agent Authority if it independently possesses the provider credential or another unguarded provider path;
 - Task Lease state is durable across process failure;
 - the current prototype is ready for adversarial production use.
@@ -113,7 +261,8 @@ The test suite also covers:
 - receipts from another mission are rejected;
 - receipts from another Task Lease are rejected;
 - parent lineage is required;
-- a trusted extraction selector must be recorded;
+- legacy host-trusted derivation records its extraction selector;
+- strict execution-evidence derivation rejects substitution/replay/tampering cases;
 - explicit mission deny rules remain the ceiling;
 - lease expiry and mission expiry are enforced against a consistent evaluation clock.
 
@@ -129,8 +278,11 @@ Current pull requests run:
 - coverage;
 - live GitHub read validation;
 - live derived GitHub mutation validation for trusted in-repository branches;
+- Google provider, extractor, cross-provider and execution-evidence adversarial tests;
 - CodeQL.
 
+The live Google provider mutation workflow is manual because it requires repository-owned Google OAuth secrets. It should be added to the public evidence list after its first successful run.
+
 ## Evidence standard for new claims
 
 A new security claim should ideally include all four:

package/docs/live-google-validation.md

@@ -0,0 +1,100 @@
+# Live Gmail → Calendar validation
+
+This validation turns the README's Gmail → Calendar Task Lease example into a real cross-provider proof.
+
+The narrow claim is:
+
+> A sender discovered from one authorized Gmail thread can become exact Task Lease authority for one Calendar event attendee, while a different attendee and any post-completion retry are blocked before the Calendar mutation callback runs.
+
+It is intentionally not a general Google OAuth product or a production onboarding flow.
+
+## Safe fixture
+
+Use a one-message thread sent from the validation account to itself. This keeps the proof real without inviting an unrelated person.
+
+The live script:
+
+1. reads the approved Gmail thread through `users.threads.get` using metadata format and only the `From` header;
+2. derives `fact:sender-email` from the same-lease `ALLOW` receipt;
+3. creates one private, transparent Calendar event whose attendee is exactly that derived sender;
+4. attempts a different attendee and requires `authority_delta_required` before the provider callback;
+5. completes the Task Lease and proves the previously authorized attendee can no longer be used;
+6. deletes the temporary event as harness cleanup outside the agent-authority proof.
+
+The event uses `sendUpdates=none` and is deleted after validation. The cleanup call is counted separately from task-side provider mutations.
+
+## Required Google OAuth scopes
+
+The validation credential needs only the Google permissions required for the two provider operations:
+
+```text
+https://www.googleapis.com/auth/gmail.readonly
+https://www.googleapis.com/auth/calendar.events
+```
+
+Do not put an access token in the repository or workflow inputs.
+
+## GitHub Actions secrets
+
+The manual workflow `.github/workflows/live-google-validation.yml` mints a short-lived access token at runtime from these repository secrets:
+
+```text
+AA_GOOGLE_OAUTH_CLIENT_ID
+AA_GOOGLE_OAUTH_CLIENT_SECRET
+AA_GOOGLE_OAUTH_REFRESH_TOKEN
+```
+
+The refresh token should have been granted the Gmail read-only and Calendar event scopes above. The access token is masked and exists only for the workflow run.
+
+## Run from GitHub Actions
+
+Open **Actions → Live Google cross-provider validation → Run workflow** and provide:
+
+- `gmail_thread_id`: the approved self-test Gmail thread ID;
+- `calendar_id`: normally `primary`;
+- `expected_sender`: optional, but recommended for a deterministic fixture.
+
+A successful run should record the following shape:
+
+```text
+ALLOW -> Gmail returned sender <fixture account>
+Derived authority -> Calendar attendee <fixture account>
+ALLOW -> real Calendar event mutation executed
+STEP-UP -> unrelated attendee blocked before Calendar provider mutation
+DENY -> post-completion Calendar mutation blocked
+Provider calls observed before cleanup: gmail_reads=1, calendar_task_mutations=1
+Cleanup -> deleted temporary Calendar event
+```
+
+## Run locally with a short-lived token
+
+```bash
+export GOOGLE_ACCESS_TOKEN='...'
+export AA_GOOGLE_GMAIL_THREAD_ID='...'
+export AA_GOOGLE_CALENDAR_ID='primary'
+export AA_GOOGLE_EXPECTED_SENDER='validation@example.com'
+npm run demo:live-google
+```
+
+Prefer the refresh-token GitHub Actions workflow for repeatable validation. Do not persist the short-lived access token in shell history, source files, screenshots, or issue comments.
+
+## What this proves
+
+When the real provider calls are placed inside the Task Lease guard callbacks, the validation demonstrates:
+
+- cross-provider derived authority from Gmail to Calendar;
+- one exact derived attendee can be used for the real Calendar effect;
+- a different attendee does not silently inherit authority;
+- blocked attempts create zero additional task-side Calendar provider mutations;
+- task completion removes the previously valid derived authority;
+- the Google credential can remain broader than the Task Lease.
+
+## What this does not prove
+
+- the current host-side extraction of `sender_email` is cryptographically attested by Gmail;
+- Task Lease state survives process failure;
+- an agent holding an independent Google credential cannot bypass the guard;
+- the validation refresh-token setup is a production credential-onboarding design;
+- `sendUpdates=none` is a general invitation-delivery strategy for user-facing calendar workflows.
+
+The purpose of this proof is to close the real cross-provider M1 validation gap and expose the next implementation problem with evidence rather than speculation.

package/docs/npm-release.md

@@ -13,7 +13,19 @@ Before any publication:
 After publication, verify from a fresh project with:
 
 ```bash
-npm install @nullsquare/agent-authority@0.4.0
+npm install @nullsquare/agent-authority@0.4.1
 ```
 
 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.1 it additionally verifies the public `@nullsquare/agent-authority/providers/google` export.
+
+## 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.1`. 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.