@nullsquare/agent-authority 0.4.0

package/CONTRIBUTING.md

@@ -0,0 +1,93 @@
+# Contributing to Agent Authority
+
+Agent Authority is being developed in public. The current goal is deliberately narrow:
+
+> Give an agent only the authority required for the task the human approved, and prevent that authority from silently expanding as the agent crosses tools or discovers new resources.
+
+The best contributions make that claim easier to prove in real agent stacks.
+
+## Start here
+
+1. Read `README.md` and `docs/task-leases.md`.
+2. Run the Task Lease demo.
+3. Search existing issues before opening a new one.
+4. Keep architectural changes tied to a concrete failure mode or integration need.
+
+```bash
+git clone https://github.com/Null-Square/agent-authority.git
+cd agent-authority
+npm install
+npm test
+npm run demo:task-lease
+```
+
+Node.js 20+ is required.
+
+## What we especially want now
+
+- integrations around `guard.run()` or Task Leases in real agent frameworks;
+- trustworthy mappings from provider/tool outputs into resource facts;
+- adversarial tests for authority expansion, provenance substitution and confused-deputy behavior;
+- examples where one task safely crosses two or more systems;
+- simple persistence designs for Task Lease state;
+- MCP and non-MCP conformance cases that preserve the same task authority;
+- approval UX for a genuine authority delta rather than approval on every tool call.
+
+We are **not** prioritizing new identity protocols, a large policy DSL, a connector marketplace, or another agent harness.
+
+## Core invariants
+
+A contribution must not weaken these properties:
+
+1. The mission is the ceiling. A Task Lease cannot grant an action the mission does not permit.
+2. A blocked or step-up action cannot execute its side effect.
+3. A derived fact must descend from existing task authority.
+4. A derived fact must be anchored to an `ALLOW` receipt from the same Task Lease.
+5. A request for a different concrete resource cannot silently inherit authority.
+6. Completing or expiring a Task Lease removes its task authority even if provider credentials still exist.
+7. Switching SDK, MCP, broker or harness transport must not broaden authority.
+
+If a proposed feature cannot preserve these rules, explain why before implementing it.
+
+## Derived-authority trust boundary
+
+The v0.4 prototype records:
+
+- parent fact IDs;
+- source receipt ID/hash;
+- source service/action/request hash;
+- the trusted extraction selector.
+
+The trusted host or adapter still supplies the extracted value. Do not describe this as cryptographic proof that the value came from the provider response. Designs that strengthen this boundary without adding a large semantic policy engine are especially valuable.
+
+## Pull requests
+
+Please include:
+
+- the user/developer problem being solved;
+- the authority boundary affected;
+- an adversarial test showing what must remain impossible;
+- the smallest implementation that solves the problem;
+- documentation when observable behavior changes.
+
+Run:
+
+```bash
+npm run check
+```
+
+before opening a PR.
+
+## Security rule
+
+Do not hide trust assumptions. If an adapter cannot prevent credential exfiltration, if an extraction is trusted rather than verified, or if enforcement can be bypassed outside the wrapper, document that limitation explicitly.
+
+Never commit passwords, API keys, OAuth refresh tokens, session cookies, customer data, or private production configuration.
+
+## Protocol proposals
+
+Do not add a new wire format simply because it is elegant. Agent Authority should consume existing OAuth/OIDC, MCP and workload-identity mechanisms where they already solve the transport or authentication problem.
+
+A new protocol concept needs evidence from multiple real integrations that the existing mechanisms cannot represent the required task-authority behavior.
+
+Disagreement is useful. Critique designs and assumptions, not contributors.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 NullSquare
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,390 @@
+<div align="center">
+
+![Agent Authority](docs/assets/agent-authority-cover.svg)
+
+# Agent Authority
+
+### Give your agent a task, not your account.
+
+**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)
+
+> **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.
+
+</div>
+
+## The problem
+
+AI agents increasingly receive broad provider permissions so they can complete narrow human tasks.
+
+A user says:
+
+> **Handle the demo request in this email thread.**
+
+The agent may need to:
+
+```text
+Gmail -> read one thread
+          |
+          v
+       discover sender
+          |
+          v
+Calendar -> create one meeting with that sender
+          |
+          v
+Gmail -> reply in the originating thread
+```
+
+The underlying OAuth connections may permit reading every email, creating meetings with anyone, or sending mail to anyone.
+
+Traditional authorization answers:
+
+> Can this application use Calendar?
+
+Agent Authority asks a narrower question immediately before the side effect:
+
+> **Is this exact effect justified by the task the human authorized?**
+
+## Task-bounded autonomy
+
+Agent Authority is trying to make this trade-off unnecessary:
+
+```text
+broad standing permissions
+        OR
+approve every tool call
+```
+
+The target is:
+
+```text
+one meaningful task approval
+        |
+        v
+temporary bounded authority
+        |
+        +--> safe task actions proceed
+        +--> unrelated resources are blocked
+        +--> real authority expansion requires step-up
+        |
+        v
+task completes -> authority disappears
+```
+
+The provider credential may continue to exist. The **task authority does not**.
+
+## The key idea: authority can follow trusted task data
+
+Many resources do not exist in the original prompt. The agent discovers them while working.
+
+Agent Authority models this with a **Task Lease**:
+
+```text
+Human-approved task
+        |
+        v
+  authority root
+  Gmail thread #91
+        |
+ authorized read
+        |
+        v
+ derived fact
+ customer@example.com
+        |
+        v
+ exact binding
+ Calendar attendee must equal that sender
+```
+
+A request for `customer@example.com` can proceed.
+
+A request for `other@example.com` does not silently inherit the same authority. It becomes an **authority delta** and requires step-up.
+
+This is **derived authority**: authority follows a resource discovered through authorized execution, but never broadens into a standing wildcard permission.
+
+See [Task Leases and Derived Authority](docs/task-leases.md).
+
+## Core invariant
+
+```text
+Task Lease authority <= Mission authority
+```
+
+The mission remains the ceiling. A Task Lease may narrow an action to resources discovered during the task, but it cannot grant an action that the mission already denies or never allowed.
+
+More generally:
+
+> **Authority may stay the same or shrink as it moves through agents, tools and transports. It must never silently grow.**
+
+## Run the derived-authority demo
+
+Requirements: Node.js 20+.
+
+```bash
+git clone https://github.com/Null-Square/agent-authority.git
+cd agent-authority
+npm install
+npm test
+npm run demo:task-lease
+```
+
+The demo performs this flow without provider credentials:
+
+```text
+1. ALLOW read of one task-authorized Gmail thread
+2. derive sender email from that same Task Lease receipt
+3. ALLOW Calendar event for that sender
+4. REQUIRE_APPROVAL for a different attendee
+5. complete task
+6. DENY subsequent actions
+```
+
+The side-effect callbacks for blocked actions never run.
+
+## Minimal developer API
+
+```js
+import { AuthorityRuntime } from '@nullsquare/agent-authority';
+import { createTaskLease } from '@nullsquare/agent-authority/task-lease';
+import { createTaskLeaseGuard } from '@nullsquare/agent-authority/guard';
+
+const lease = createTaskLease({
+  mission,
+  request: 'Handle the demo request in thread:demo-91',
+  roots: [
+    { fact_id: 'fact:thread', kind: 'gmail.thread', value: 'thread:demo-91' }
+  ],
+  bindings: [
+    {
+      service: 'calendar',
+      action: 'event.create',
+      context_field: 'attendee',
+      fact_id: 'fact:sender-email'
+    }
+  ]
+});
+
+const guard = createTaskLeaseGuard({
+  lease,
+  runtime: new AuthorityRuntime()
+});
+
+const read = await guard.run({
+  service: 'gmail',
+  action: 'thread.read',
+  context: { thread: 'thread:demo-91' }
+}, () => gmail.readThread('thread:demo-91'));
+
+lease.derive({
+  fact_id: 'fact:sender-email',
+  kind: 'email.address',
+  value: read.output.sender,
+  from: ['fact:thread'],
+  receipt: read.receipt,
+  selector: 'output.sender'
+});
+
+await guard.run({
+  service: 'calendar',
+  action: 'event.create',
+  context: { attendee: read.output.sender }
+}, () => calendar.createEvent({ attendee: read.output.sender }));
+```
+
+The host keeps its existing SDK, connector and authentication. Agent Authority controls whether the effect may happen.
+
+## Three integration modes, one authority model
+
+Agent Authority is deliberately **not tied to MCP, OAuth, or one agent framework**.
+
+### 1. In-process guard
+
+```text
+agent code -> guard.run() -> existing SDK / API
+```
+
+Best when the application already owns the provider connection. This is the primary v0.4 adoption path.
+
+### 2. MCP gateway
+
+```text
+MCP host -> Agent Authority -> existing MCP server
+```
+
+Best when the harness already speaks MCP. MCP is an integration transport, not the product identity.
+
+### 3. Brokered execution
+
+```text
+agent -> Agent Authority -> isolated credential -> provider
+```
+
+Best when the agent should not receive the provider credential at all.
+
+The long-term validation target is the **same Task Lease and authority lineage across all three paths**.
+
+## What is implemented
+
+### Task authority
+
+- mission validation and deterministic `ALLOW / DENY / REQUIRE_APPROVAL`
+- explicit deny precedence
+- resource/context constraints
+- expiry and cumulative budgets
+- delegation attenuation
+- durable mission revocation
+- Task Lease prototype
+- explicit authority roots
+- same-lease provenance-bound derived facts
+- required parent lineage and trusted extraction selector
+- exact context-field bindings
+- authority-delta step-up signal
+- immediate task completion/expiry enforcement
+- Task Lease IDs/hashes in decision receipts
+
+### Enforcement
+
+- protocol-neutral `guard.run()` wrapper
+- blocked side effects never invoke their callback
+- one-time human approvals bound to exact request
+- mutation idempotency
+- conservative uncertain-state handling
+- signed harness action grants
+- MCP v2 read-only gateway/proxy
+
+### Credentials and runtime
+
+- persistent connection metadata
+- AES-256-GCM local encrypted secret store
+- safe reconnect cleanup
+- GitHub brokered execution without returning the token to the agent
+- short-lived signed local agent-instance tokens
+- local CLI/daemon
+
+### Engineering quality
+
+- adversarial authorization tests
+- Node 20 and Node 22 CI
+- coverage run
+- package checks
+- CodeQL
+
+## What is different from OAuth, IAM and MCP authorization?
+
+Agent Authority is **not trying to replace them**.
+
+OAuth/IAM answer who or what may access a provider and with which standing scopes. MCP authorization protects an MCP transport. Agent Authority operates at a different boundary:
+
+```text
+human task
+    |
+    v
+temporary task authority
+    |
+    v
+exact agent-originated effect
+    |
+    +--> existing OAuth / IAM / MCP / SDK / CLI
+```
+
+The project should consume existing identity/authentication mechanisms and emerging standards rather than invent another login or token format.
+
+The contribution we are testing is operational: **make task-scoped, provenance-aware least privilege usable inside ordinary agent stacks.**
+
+## Example use cases
+
+### Support / sales
+
+> Handle this customer request.
+
+Bind later actions to the customer, thread, ticket or meeting discovered from the authorized task path.
+
+### Finance
+
+> Refund the customer from this ticket, but never more than the original charge.
+
+Discover customer -> order -> charge through authorized reads, then bind the refund to those concrete facts and amount ceiling.
+
+### Coding / operations
+
+> Fix issue #42, open a PR, do not merge or deploy production.
+
+Keep repo/issue/branch authority bounded as subagents and tools change.
+
+### Personal / company operating agents
+
+> Handle this email.
+
+Allow a natural workflow across mail, calendar, CRM and internal systems without turning every connected account into ambient agent authority.
+
+## Security principles
+
+1. **Task before credential.** A provider token is not task authority.
+2. **Mission is the ceiling.** Task Leases cannot override explicit denies.
+3. **No side effect before authorization.** Denied and step-up actions never execute.
+4. **Authority lineage matters.** Derived facts require an authorized receipt from the same Task Lease, at least one existing parent fact, and a recorded extraction selector.
+5. **No silent resource expansion.** A different concrete resource becomes an authority delta.
+6. **Task authority ends with the task.** Completion and expiry are independent from provider credential lifetime.
+7. **Authority may shrink, never silently grow.** Delegation and transport changes must preserve non-amplification.
+8. **The evaluated request must be the executed request.** Request hashes, grants and idempotency protect the boundary.
+9. **Credentials stay out of model context where Agent Authority owns them.**
+10. **Security gaps are documented, not marketed away.**
+
+See [SECURITY.md](SECURITY.md).
+
+## Current limitations
+
+This is still a validation implementation.
+
+- Task Lease state is currently process-local.
+- Derived-value extraction is trusted to the host/adapter; v0.4 records the source receipt and selector but does not yet cryptographically prove extraction from the provider response.
+- Bindings currently target top-level request context fields.
+- Approved authority deltas are surfaced but not automatically applied back into a live lease.
+- GitHub token-stdin is a developer bridge, not final browser OAuth onboarding.
+- The encrypted local vault is not an OS keychain/KMS/HSM backend.
+- Remote authenticated deployment and a production approval UX are not complete.
+
+These are follow-on validation problems. We are intentionally not solving them with a giant policy language or another agent framework.
+
+## What we are deliberately not building
+
+- another agent harness
+- another OAuth or identity protocol
+- an MCP replacement
+- a connector marketplace
+- a giant proprietary policy DSL
+- an enterprise dashboard before the enforcement primitive proves adoption
+
+## Contributing
+
+The best contribution is not another abstract feature. It is a real integration or adversarial case that answers:
+
+> **Can this agent complete the intended task while being technically unable to use the same underlying account authority for an unrelated effect?**
+
+We especially want:
+
+- framework integrations around `guard.run()`;
+- trustworthy operation -> resource-context mappings;
+- Task Lease examples from real workflows;
+- derived-authority / provenance attacks;
+- MCP and non-MCP conformance cases;
+- secure persistence and extraction-verification designs that stay simple.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+Apache-2.0.
+
+---
+
+<div align="center">
+
+Built in public by **NullSquare**.
+
+**Give your agent a task, not your account.**
+
+</div>