@nullsquare/agent-authority 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CONTRIBUTING.md +93 -0
- package/LICENSE +201 -0
- package/README.md +390 -0
- package/ROADMAP.md +149 -0
- package/SECURITY.md +116 -0
- package/docs/account-connections.md +173 -0
- package/docs/announcement-draft.md +13 -0
- package/docs/architecture.md +106 -0
- package/docs/assets/agent-authority-cover.svg +41 -0
- package/docs/clear-path.md +53 -0
- package/docs/cli.md +130 -0
- package/docs/evidence.md +143 -0
- package/docs/harness-bridge-mode.md +136 -0
- package/docs/harness-integration.md +223 -0
- package/docs/integration-contract.md +132 -0
- package/docs/integrations/vercel-ai-sdk.md +161 -0
- package/docs/launch-checklist.md +29 -0
- package/docs/npm-release.md +19 -0
- package/docs/openclaw-integration.md +97 -0
- package/docs/package-consumer-validation.md +18 -0
- package/docs/release-candidate-status.md +3 -0
- package/docs/release-guardrails.md +8 -0
- package/docs/release-notes-v0.4.md +26 -0
- package/docs/release-scope.md +3 -0
- package/docs/ship-criteria.md +3 -0
- package/docs/task-leases.md +253 -0
- package/docs/validation.md +124 -0
- package/examples/demo.js +19 -0
- package/examples/direct-guard.js +50 -0
- package/examples/harness-managed-connectors.js +72 -0
- package/examples/live-github-derived-mutation.js +208 -0
- package/examples/live-github-task-lease.js +80 -0
- package/examples/mission.json +20 -0
- package/examples/missions/chatgpt-web-validation.json +33 -0
- package/examples/openclaw-tool-wrapper.js +49 -0
- package/examples/task-lease-demo.js +98 -0
- package/examples/validation-mcp-upstream.js +112 -0
- package/package.json +80 -0
- package/src/agent-auth.js +135 -0
- package/src/approvals.js +157 -0
- package/src/cli.js +335 -0
- package/src/connections.js +203 -0
- package/src/execution.js +174 -0
- package/src/guard.js +79 -0
- package/src/harness-bridge.js +131 -0
- package/src/idempotency.js +118 -0
- package/src/index.js +291 -0
- package/src/integrations/ai-sdk.js +59 -0
- package/src/keys.js +15 -0
- package/src/mcp-gateway.js +142 -0
- package/src/mcp-remote.js +102 -0
- package/src/mcp-server.js +102 -0
- package/src/providers/github.js +149 -0
- package/src/runtime-env.js +53 -0
- package/src/sdk.js +75 -0
- package/src/server.js +146 -0
- package/src/storage.js +213 -0
- package/src/task-lease.js +266 -0
package/ROADMAP.md
ADDED
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
# Agent Authority Roadmap
|
|
2
|
+
|
|
3
|
+
Agent Authority is implementation-first. We are not trying to invent a new authentication protocol or policy language.
|
|
4
|
+
|
|
5
|
+
The product thesis we are validating is:
|
|
6
|
+
|
|
7
|
+
> **Give an agent a task, not standing account permissions.**
|
|
8
|
+
|
|
9
|
+
A human-approved task becomes temporary execution authority. As the agent discovers concrete resources through authorized work, authority may follow those resources through provenance-bound facts, but it may never silently broaden.
|
|
10
|
+
|
|
11
|
+
## Current invariant
|
|
12
|
+
|
|
13
|
+
```text
|
|
14
|
+
Task Lease authority <= Mission authority
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Across delegation and integrations:
|
|
18
|
+
|
|
19
|
+
```text
|
|
20
|
+
authority may stay the same or shrink
|
|
21
|
+
never silently grow
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## M0 — Enforcement foundation — complete
|
|
25
|
+
|
|
26
|
+
- [x] mission validation
|
|
27
|
+
- [x] allow / deny / require-approval outcomes
|
|
28
|
+
- [x] explicit deny precedence
|
|
29
|
+
- [x] resource constraints
|
|
30
|
+
- [x] expiry and budgets
|
|
31
|
+
- [x] delegation attenuation
|
|
32
|
+
- [x] mission revocation
|
|
33
|
+
- [x] action receipts and request hashes
|
|
34
|
+
- [x] protocol-neutral `guard.run()` enforcement
|
|
35
|
+
- [x] one-time approvals
|
|
36
|
+
- [x] mutation idempotency
|
|
37
|
+
- [x] short-lived local agent-instance auth
|
|
38
|
+
- [x] encrypted development credential vault
|
|
39
|
+
- [x] GitHub brokered execution
|
|
40
|
+
- [x] MCP v2 gateway proof
|
|
41
|
+
- [x] harness-managed connector grant proof
|
|
42
|
+
- [x] Node 20/22 CI, coverage, package checks and CodeQL
|
|
43
|
+
|
|
44
|
+
## M1 — Task Lease / derived-authority proof — current
|
|
45
|
+
|
|
46
|
+
- [x] Task Lease object around an existing mission
|
|
47
|
+
- [x] explicit authority roots
|
|
48
|
+
- [x] derived facts anchored to same-mission `ALLOW` receipts
|
|
49
|
+
- [x] parent-fact lineage
|
|
50
|
+
- [x] exact context-field bindings
|
|
51
|
+
- [x] unresolved facts fail closed
|
|
52
|
+
- [x] resource mismatch becomes an authority-delta step-up signal
|
|
53
|
+
- [x] explicit mission deny remains the ceiling
|
|
54
|
+
- [x] task completion immediately removes authority
|
|
55
|
+
- [x] independent task-lease expiry
|
|
56
|
+
- [x] task-lease ID/hash in receipts
|
|
57
|
+
- [x] self-contained cross-system demo: Gmail-thread fact -> Calendar attendee
|
|
58
|
+
- [ ] exercise the same pattern against two real provider operations
|
|
59
|
+
|
|
60
|
+
**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.
|
|
61
|
+
|
|
62
|
+
## M2 — Durable task execution
|
|
63
|
+
|
|
64
|
+
Build only what the real M1 workflow proves necessary.
|
|
65
|
+
|
|
66
|
+
- [ ] durable Task Lease persistence/recovery
|
|
67
|
+
- [ ] atomic fact/binding updates
|
|
68
|
+
- [ ] approved authority delta can safely attenuate/update a live lease
|
|
69
|
+
- [ ] completion state survives process restart
|
|
70
|
+
- [ ] durable lineage query: why was this exact action authorized?
|
|
71
|
+
- [ ] concurrency tests for multiple agent workers operating under one lease
|
|
72
|
+
|
|
73
|
+
**Success criterion:** a Task Lease survives daemon/process restarts without gaining authority or losing its provenance lineage.
|
|
74
|
+
|
|
75
|
+
## M3 — Trustworthy derived facts
|
|
76
|
+
|
|
77
|
+
Today the trusted host/adapter supplies the derived value and selector. This is an explicit v0.4 limitation.
|
|
78
|
+
|
|
79
|
+
- [ ] define a small adapter contract for extracting authority-relevant fields from provider results
|
|
80
|
+
- [ ] bind derived fact records to provider/result evidence where practical
|
|
81
|
+
- [ ] adversarial tests for forged extraction, confused-deputy mappings and stale facts
|
|
82
|
+
- [ ] conformance fixture for operation -> resource-context mappings
|
|
83
|
+
- [ ] define invalidation rules when a source resource changes
|
|
84
|
+
|
|
85
|
+
Do **not** build a general semantic policy language unless real integrations require it.
|
|
86
|
+
|
|
87
|
+
**Success criterion:** an adapter cannot claim a value was derived from an authorized operation without satisfying the documented extraction/evidence contract.
|
|
88
|
+
|
|
89
|
+
## M4 — Same task, multiple transports
|
|
90
|
+
|
|
91
|
+
Prove Agent Authority is not an MCP product or SDK wrapper.
|
|
92
|
+
|
|
93
|
+
- [ ] same Task Lease through ordinary `guard.run()` SDK call
|
|
94
|
+
- [ ] same Task Lease through MCP gateway
|
|
95
|
+
- [ ] same Task Lease through brokered provider execution
|
|
96
|
+
- [ ] at least one non-bypassable harness/tool-middleware integration
|
|
97
|
+
- [ ] interoperability test vectors across transports
|
|
98
|
+
|
|
99
|
+
**Success criterion:** changing transport or harness does not expand the task's authority.
|
|
100
|
+
|
|
101
|
+
## M5 — Production credential and approval UX
|
|
102
|
+
|
|
103
|
+
Only after the task-bound enforcement model is validated.
|
|
104
|
+
|
|
105
|
+
- [ ] GitHub browser/App onboarding instead of token-stdin
|
|
106
|
+
- [ ] reusable OAuth/OIDC connection engine
|
|
107
|
+
- [ ] OS keychain / KMS-backed secret backend
|
|
108
|
+
- [ ] automatic short-lived agent session bootstrap
|
|
109
|
+
- [ ] compact approval UI showing the exact authority delta
|
|
110
|
+
- [ ] signed receipt experiment
|
|
111
|
+
|
|
112
|
+
**Success criterion:** an external developer can install Agent Authority, connect one real provider, authorize one task, and complete it without exposing a long-lived credential to the model.
|
|
113
|
+
|
|
114
|
+
## M6 — Ecosystem and contribution layer
|
|
115
|
+
|
|
116
|
+
- [ ] adapter/conformance starter template
|
|
117
|
+
- [ ] framework integration examples
|
|
118
|
+
- [ ] `good first issue` tasks based on real mappings/tests
|
|
119
|
+
- [ ] independent contributor implementation of one adapter
|
|
120
|
+
- [ ] release packaging and npm publication
|
|
121
|
+
- [ ] documentation site only when README/docs become too large
|
|
122
|
+
|
|
123
|
+
## M7 — Standards interoperability
|
|
124
|
+
|
|
125
|
+
Only after operational evidence.
|
|
126
|
+
|
|
127
|
+
- [ ] map Task Lease concepts to emerging task/intent authorization work
|
|
128
|
+
- [ ] accept external authorization envelopes where useful
|
|
129
|
+
- [ ] avoid creating a competing identity/token standard
|
|
130
|
+
- [ ] publish stable test vectors for non-amplification and authority lineage
|
|
131
|
+
- [ ] evaluate an appropriate standards venue only if multiple independent implementations exist
|
|
132
|
+
|
|
133
|
+
## What we are not prioritizing
|
|
134
|
+
|
|
135
|
+
- another agent harness
|
|
136
|
+
- a new OAuth replacement
|
|
137
|
+
- an MCP replacement
|
|
138
|
+
- a giant connector marketplace
|
|
139
|
+
- a proprietary universal policy DSL
|
|
140
|
+
- a dashboard-first enterprise product
|
|
141
|
+
- A2A support before task-bound tool execution is validated
|
|
142
|
+
|
|
143
|
+
## Research questions
|
|
144
|
+
|
|
145
|
+
1. What is the smallest trustworthy representation of an authority-relevant derived fact?
|
|
146
|
+
2. How should an approved authority delta update a running task without opening a broader wildcard permission?
|
|
147
|
+
3. How should source-data changes invalidate downstream derived authority?
|
|
148
|
+
4. What provider/tool metadata is required to map operations to resource context reliably?
|
|
149
|
+
5. Can the same non-amplification conformance suite work across SDK, MCP, CLI and brokered execution?
|
package/SECURITY.md
ADDED
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
# Security Policy
|
|
2
|
+
|
|
3
|
+
Agent Authority sits on a security-critical side-effect boundary. Please treat vulnerabilities that could bypass policy, expand task/delegated authority, substitute request parameters, forge approvals/receipts, defeat revocation, cross Task Lease boundaries, or leak credentials as sensitive.
|
|
4
|
+
|
|
5
|
+
## Reporting
|
|
6
|
+
|
|
7
|
+
For non-sensitive hardening ideas, open a GitHub issue.
|
|
8
|
+
|
|
9
|
+
For exploitable vulnerabilities, use GitHub private vulnerability reporting / Security Advisory flow when available rather than publishing exploit details in a public issue.
|
|
10
|
+
|
|
11
|
+
Never include real passwords, OAuth refresh tokens, API keys, session cookies, customer data, or production secrets in reports, screenshots, logs, or reproductions.
|
|
12
|
+
|
|
13
|
+
## Current status
|
|
14
|
+
|
|
15
|
+
Agent Authority is a public pre-alpha validation implementation. It has live provider-boundary evidence, but it is **not production-ready** and should not yet be treated as a complete credential broker, IAM replacement, or hardened sandbox.
|
|
16
|
+
|
|
17
|
+
See [`docs/evidence.md`](docs/evidence.md) for executable proof and current limitations.
|
|
18
|
+
|
|
19
|
+
## Security claim
|
|
20
|
+
|
|
21
|
+
The narrow claim of the current runtime is:
|
|
22
|
+
|
|
23
|
+
> If an effect is reachable only through an Agent Authority enforcement boundary, the effect callback is not invoked unless the mission and Task Lease authorize that exact semantic request (or a required approval has completed).
|
|
24
|
+
|
|
25
|
+
A Task Lease may narrow mission authority around concrete resources discovered during an authorized task. It cannot grant an action the mission does not already permit.
|
|
26
|
+
|
|
27
|
+
```text
|
|
28
|
+
Task Lease authority <= Mission authority
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Critical trust boundary
|
|
32
|
+
|
|
33
|
+
Agent Authority cannot secure a provider path it does not control.
|
|
34
|
+
|
|
35
|
+
This is bypassable:
|
|
36
|
+
|
|
37
|
+
```text
|
|
38
|
+
agent ----> Agent Authority ----> provider
|
|
39
|
+
\
|
|
40
|
+
+---------------------------> provider (unguarded)
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
This is the intended boundary:
|
|
44
|
+
|
|
45
|
+
```text
|
|
46
|
+
agent
|
|
47
|
+
|
|
|
48
|
+
v
|
|
49
|
+
Agent Authority
|
|
50
|
+
|
|
|
51
|
+
v
|
|
52
|
+
provider
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
If the agent itself possesses a provider credential and can call the provider through another path, application architecture must remove or isolate that path before claiming non-bypassable enforcement.
|
|
56
|
+
|
|
57
|
+
## Task Lease invariants
|
|
58
|
+
|
|
59
|
+
1. **Mission is the ceiling.** A Task Lease cannot override explicit deny or create a new action class.
|
|
60
|
+
2. **No side effect before authorization.** `DENY` and `REQUIRE_APPROVAL` do not invoke the guarded effect.
|
|
61
|
+
3. **Same request.** The semantic request evaluated must be the request executed.
|
|
62
|
+
4. **Same task lineage.** Derived authority must be anchored to an `ALLOW` receipt from the same Task Lease.
|
|
63
|
+
5. **Parent authority exists.** Derived facts must descend from at least one existing task authority fact.
|
|
64
|
+
6. **No silent resource expansion.** A different concrete bound resource produces an authority delta instead of inheriting authority.
|
|
65
|
+
7. **Task completion removes authority.** Completion and expiry are independent of provider credential lifetime.
|
|
66
|
+
8. **Delegation attenuates.** Child authority may stay equal or shrink; it must not exceed parent authority.
|
|
67
|
+
9. **Revocation survives later calls.** A revoked mission must stop subsequent actions.
|
|
68
|
+
10. **Mutation retries are conservative.** Idempotency handling must not silently duplicate external side effects.
|
|
69
|
+
|
|
70
|
+
## Derived-fact trust assumption
|
|
71
|
+
|
|
72
|
+
The v0.4 implementation records:
|
|
73
|
+
|
|
74
|
+
- parent fact IDs;
|
|
75
|
+
- source receipt ID/hash;
|
|
76
|
+
- source service/action/request hash;
|
|
77
|
+
- Task Lease ID;
|
|
78
|
+
- trusted extraction selector.
|
|
79
|
+
|
|
80
|
+
The trusted host or adapter currently supplies the extracted value. Agent Authority does **not** yet cryptographically prove that a value such as `output.number` was actually extracted from the provider response described by the receipt.
|
|
81
|
+
|
|
82
|
+
Do not present recorded provenance as cryptographic data-lineage proof.
|
|
83
|
+
|
|
84
|
+
## Credentials
|
|
85
|
+
|
|
86
|
+
When Agent Authority owns/brokers a provider credential, the design goal is to keep long-lived credentials out of model context. The current encrypted-file vault is a pre-alpha local backend, not equivalent to an OS keychain, KMS, HSM, or enterprise secret manager.
|
|
87
|
+
|
|
88
|
+
For in-process guard integrations, the host application may continue to own its provider credential. In that mode Agent Authority controls guarded execution; it does not isolate the host's credential by itself.
|
|
89
|
+
|
|
90
|
+
## Current non-goals / incomplete protections
|
|
91
|
+
|
|
92
|
+
The current release does not yet guarantee:
|
|
93
|
+
|
|
94
|
+
- durable Task Lease recovery after process failure;
|
|
95
|
+
- cryptographically verified provider-output extraction;
|
|
96
|
+
- non-bypassability when the agent has another provider path;
|
|
97
|
+
- production OAuth onboarding;
|
|
98
|
+
- OS keychain/KMS/HSM-backed credential storage;
|
|
99
|
+
- hardened remote multi-tenant deployment;
|
|
100
|
+
- automatic safe application of approved authority deltas;
|
|
101
|
+
- complete concurrency-safe multi-agent budget/accounting semantics.
|
|
102
|
+
|
|
103
|
+
These limitations are intentional and should remain visible in documentation and demos.
|
|
104
|
+
|
|
105
|
+
## Security review contributions
|
|
106
|
+
|
|
107
|
+
Especially valuable reports/tests include:
|
|
108
|
+
|
|
109
|
+
- direct-path bypasses;
|
|
110
|
+
- request substitution between evaluation and execution;
|
|
111
|
+
- cross-lease provenance substitution;
|
|
112
|
+
- confused-deputy behavior across adapters;
|
|
113
|
+
- approval replay or authority-delta replay;
|
|
114
|
+
- revocation races;
|
|
115
|
+
- concurrent budget/idempotency races;
|
|
116
|
+
- provider-output extraction attacks.
|
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
# Account Connections: authorize once, reuse across agents
|
|
2
|
+
|
|
3
|
+
The user experience goal is simple:
|
|
4
|
+
|
|
5
|
+
> Connect each account once to Agent Authority. Reuse that connection from any authorized agent or harness without handing the agent the long-lived credential.
|
|
6
|
+
|
|
7
|
+
Agent Authority cannot literally authenticate every internet service with one universal login: GitHub, Google, Microsoft, Slack, AWS, and legacy systems each control their own authorization. The abstraction therefore separates **provider consent** from **agent authority**.
|
|
8
|
+
|
|
9
|
+
## User setup flow
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
1. Install / open Agent Authority
|
|
13
|
+
|
|
|
14
|
+
v
|
|
15
|
+
2. Create local or cloud Authority identity
|
|
16
|
+
|
|
|
17
|
+
v
|
|
18
|
+
3. Connect accounts once
|
|
19
|
+
GitHub [Connect]
|
|
20
|
+
Google [Connect]
|
|
21
|
+
Slack [Connect]
|
|
22
|
+
Cloudflare [Connect]
|
|
23
|
+
|
|
|
24
|
+
v
|
|
25
|
+
4. Provider OAuth / credential setup happens once
|
|
26
|
+
|
|
|
27
|
+
v
|
|
28
|
+
5. Agent Authority stores only a connection record + vault reference
|
|
29
|
+
|
|
|
30
|
+
v
|
|
31
|
+
6. Any approved agent/harness can request actions through Agent Authority
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Later sessions should not repeat provider login. Reauthorization is needed only when the provider revokes/expires the grant, the user disconnects the account, or the requested action needs scopes that were never granted.
|
|
35
|
+
|
|
36
|
+
## Runtime flow
|
|
37
|
+
|
|
38
|
+
```text
|
|
39
|
+
Agent / harness
|
|
40
|
+
|
|
|
41
|
+
| service=github, action=repo.read
|
|
42
|
+
v
|
|
43
|
+
Agent Authority
|
|
44
|
+
|
|
|
45
|
+
+-- 1. identify principal + agent + mission
|
|
46
|
+
+-- 2. evaluate mission policy
|
|
47
|
+
+-- 3. resolve connected account
|
|
48
|
+
+-- 4. refresh/exchange credential if needed
|
|
49
|
+
+-- 5. execute through provider adapter
|
|
50
|
+
+-- 6. sanitize response
|
|
51
|
+
+-- 7. emit receipt
|
|
52
|
+
v
|
|
53
|
+
Agent receives result, not credential
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
The credential broker must live outside model context. A prompt-injected agent should not be able to ask the system to print its GitHub refresh token or Google session cookie because those objects are never tool outputs.
|
|
57
|
+
|
|
58
|
+
## We do not build every integration from scratch
|
|
59
|
+
|
|
60
|
+
Coverage is layered.
|
|
61
|
+
|
|
62
|
+
### 1. Generic auth engines
|
|
63
|
+
|
|
64
|
+
One implementation can serve many providers:
|
|
65
|
+
|
|
66
|
+
- OAuth/OIDC Authorization Code + PKCE
|
|
67
|
+
- OAuth device flow where appropriate
|
|
68
|
+
- API key / PAT vault storage
|
|
69
|
+
- cloud STS / workload-identity exchange
|
|
70
|
+
- CLI credential helpers
|
|
71
|
+
- isolated browser-session brokerage
|
|
72
|
+
|
|
73
|
+
Providers then supply thin profiles: endpoints, scopes, refresh behavior, account discovery, and capability mappings.
|
|
74
|
+
|
|
75
|
+
### 2. Native provider adapters
|
|
76
|
+
|
|
77
|
+
We should build native adapters for strategically important services where security and UX justify direct support, initially GitHub, Google, Cloudflare, and one enterprise identity/cloud platform.
|
|
78
|
+
|
|
79
|
+
### 3. MCP compatibility
|
|
80
|
+
|
|
81
|
+
An authority-aware MCP proxy can wrap existing MCP servers. The MCP server keeps using its normal OAuth/authentication mechanism; Agent Authority adds mission policy, approval, delegation and receipts before forwarding the call.
|
|
82
|
+
|
|
83
|
+
### 4. Connector networks
|
|
84
|
+
|
|
85
|
+
Existing connector platforms can sit behind an Agent Authority adapter:
|
|
86
|
+
|
|
87
|
+
```text
|
|
88
|
+
agent -> Agent Authority -> connector network -> SaaS API
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
This can provide broad early coverage without making the authority project maintain hundreds of unrelated SaaS SDKs.
|
|
92
|
+
|
|
93
|
+
## Connection object
|
|
94
|
+
|
|
95
|
+
A safe connection record contains metadata and a vault reference, never the secret itself:
|
|
96
|
+
|
|
97
|
+
```json
|
|
98
|
+
{
|
|
99
|
+
"connection_id": "connection:...",
|
|
100
|
+
"principal_id": "user:123",
|
|
101
|
+
"service": "github",
|
|
102
|
+
"account_id": "octocat",
|
|
103
|
+
"auth_kind": "oauth",
|
|
104
|
+
"credential_ref": "vault:...",
|
|
105
|
+
"scopes": ["repo", "read:user"],
|
|
106
|
+
"status": "active"
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
The model-facing API should omit `credential_ref` as well.
|
|
111
|
+
|
|
112
|
+
## Scope step-up
|
|
113
|
+
|
|
114
|
+
A user might initially connect Google with calendar read permission. Months later an agent mission may require Gmail send. The correct behavior is not to grant a giant permanent scope during onboarding.
|
|
115
|
+
|
|
116
|
+
Instead:
|
|
117
|
+
|
|
118
|
+
```text
|
|
119
|
+
requested capability
|
|
120
|
+
|
|
|
121
|
+
v
|
|
122
|
+
existing connection sufficient? -- yes --> continue
|
|
123
|
+
|
|
|
124
|
+
no
|
|
125
|
+
v
|
|
126
|
+
request provider scope step-up + human approval
|
|
127
|
+
|
|
|
128
|
+
v
|
|
129
|
+
update connection grant
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
This keeps the initial consent small while allowing smooth expansion.
|
|
133
|
+
|
|
134
|
+
## Mission consent vs provider consent
|
|
135
|
+
|
|
136
|
+
These are intentionally different events.
|
|
137
|
+
|
|
138
|
+
**Provider consent**: “Agent Authority may access my GitHub account under these provider scopes.” This is normally done once and reused.
|
|
139
|
+
|
|
140
|
+
**Mission consent**: “This coding agent may maintain repository X for the next two hours, but may not delete repositories or change billing.” This can be short-lived and task-specific.
|
|
141
|
+
|
|
142
|
+
The provider connection is durable. The mission authority is bounded.
|
|
143
|
+
|
|
144
|
+
## Multiple accounts
|
|
145
|
+
|
|
146
|
+
The same principal may connect multiple accounts or organizations:
|
|
147
|
+
|
|
148
|
+
```text
|
|
149
|
+
github/personal
|
|
150
|
+
github/null-square
|
|
151
|
+
google/personal
|
|
152
|
+
google/work
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
A mission can select an `account_id`, and organization policy can restrict which account a given agent is allowed to use.
|
|
156
|
+
|
|
157
|
+
## Future protocols
|
|
158
|
+
|
|
159
|
+
New agent-auth protocols should plug into the connection/credential boundary rather than replacing Mission Manifests. OAuth Rich Authorization Requests can carry fine-grained authorization details, and OAuth Token Exchange already defines delegation/impersonation token exchange primitives. Agent Authority should map to such standards when providers support them rather than inventing incompatible token mechanics.
|
|
160
|
+
|
|
161
|
+
## Production security requirements
|
|
162
|
+
|
|
163
|
+
The current in-memory secret store is explicitly development-only. Production versions need:
|
|
164
|
+
|
|
165
|
+
- encrypted at-rest credentials
|
|
166
|
+
- OS keychain, HSM/KMS, or dedicated vault backing
|
|
167
|
+
- refresh-token rotation support
|
|
168
|
+
- provider revocation handling
|
|
169
|
+
- no secret values in logs/receipts/errors
|
|
170
|
+
- process/IPC authentication between harness and sidecar
|
|
171
|
+
- anti-confused-deputy resource binding
|
|
172
|
+
- explicit capability-to-provider-operation mappings
|
|
173
|
+
- audit trail for connection creation, scope changes, use, and revocation
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# Announcement draft — hold until registry verification
|
|
2
|
+
|
|
3
|
+
NullSquare is open-sourcing **Agent Authority**, an experimental runtime for task-bounded AI agent side effects.
|
|
4
|
+
|
|
5
|
+
AI agents often inherit account permissions much broader than the task a user approved. Agent Authority keeps the existing identity, OAuth, SDK, MCP server, or agent framework, but places a Task Lease immediately before consequential effects.
|
|
6
|
+
|
|
7
|
+
A Task Lease can follow resources discovered through authorized execution without silently broadening to unrelated resources. In the public validation suite, Agent Authority discovers a live GitHub issue, derives that issue number as task authority, performs one real comment mutation, blocks a different issue before the provider call, then blocks the previously authorized issue after the task completes.
|
|
8
|
+
|
|
9
|
+
The developer preview also includes a Vercel AI SDK integration that wraps ordinary `ToolLoopAgent` tools at their existing `execute` boundary.
|
|
10
|
+
|
|
11
|
+
**Give your agent a task, not your account.**
|
|
12
|
+
|
|
13
|
+
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.
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
# Architecture
|
|
2
|
+
|
|
3
|
+
Agent Authority is a **mission-scoped authority control plane** for AI agents. It sits above authentication mechanisms and below agent intent/tool execution.
|
|
4
|
+
|
|
5
|
+
## Placement
|
|
6
|
+
|
|
7
|
+
```text
|
|
8
|
+
Human / organization
|
|
9
|
+
|
|
|
10
|
+
| approves mission
|
|
11
|
+
v
|
|
12
|
+
Mission Manifest
|
|
13
|
+
|
|
|
14
|
+
v
|
|
15
|
+
Authority Runtime <---- policy / approvals / revocation / receipts
|
|
16
|
+
|
|
|
17
|
+
| only after ALLOW
|
|
18
|
+
v
|
|
19
|
+
Credential + transport adapters
|
|
20
|
+
OAuth | MCP | API key | cloud IAM | CLI | browser/legacy | future protocols
|
|
21
|
+
|
|
|
22
|
+
v
|
|
23
|
+
Services and tools
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
The model or agent should not be trusted with permanent root credentials. The preferred enforcement point is outside the model process: tool middleware, local sidecar, connector wrapper, MCP proxy, or remote control plane.
|
|
27
|
+
|
|
28
|
+
## Core primitives
|
|
29
|
+
|
|
30
|
+
### Principal
|
|
31
|
+
The human or organization that owns the authority.
|
|
32
|
+
|
|
33
|
+
### Agent
|
|
34
|
+
The runtime identity acting under delegated authority. This may be a coding-agent session, autonomous workflow, subagent, CI job, MCP client, or future workload identity.
|
|
35
|
+
|
|
36
|
+
### Mission
|
|
37
|
+
A durable statement of *why* the agent is acting and the authority granted for that objective.
|
|
38
|
+
|
|
39
|
+
### Capability
|
|
40
|
+
A normalized service/action pair such as `github:repo.write` or `cloudflare:workers.deploy`.
|
|
41
|
+
|
|
42
|
+
### Constraint
|
|
43
|
+
Limits such as expiration, monetary budget, resource boundary, rate, environment, delegation depth, or execution window.
|
|
44
|
+
|
|
45
|
+
### Approval
|
|
46
|
+
A policy outcome requiring the runtime to return to a human before execution.
|
|
47
|
+
|
|
48
|
+
### Receipt
|
|
49
|
+
A tamper-evident record of the mission, requested action, decision, and delegation context. The MVP hashes receipts; signatures and append-only persistence are roadmap items.
|
|
50
|
+
|
|
51
|
+
## Decision pipeline
|
|
52
|
+
|
|
53
|
+
1. Validate mission structure.
|
|
54
|
+
2. Check mission revocation and expiry.
|
|
55
|
+
3. Check delegation depth and contextual constraints.
|
|
56
|
+
4. Resolve service/resource policy.
|
|
57
|
+
5. Apply explicit deny rules before broad allows.
|
|
58
|
+
6. Determine whether human approval is required.
|
|
59
|
+
7. Emit an action receipt.
|
|
60
|
+
8. Only on `allow`, resolve a credential/transport adapter.
|
|
61
|
+
9. Adapter obtains or injects the minimum practical credential for the requested action.
|
|
62
|
+
10. Service call occurs outside or behind the authority boundary.
|
|
63
|
+
|
|
64
|
+
## Why adapters matter
|
|
65
|
+
|
|
66
|
+
The authority model must not depend on every service adopting a new protocol. Existing OAuth, API-key, CLI, cloud IAM, MCP, enterprise SSO, and browser-session systems can be hidden behind adapters. A future agent-native auth standard should be implemented as another adapter.
|
|
67
|
+
|
|
68
|
+
This lets the project solve a different problem from authentication itself: **portable bounded authority over heterogeneous authentication systems**.
|
|
69
|
+
|
|
70
|
+
## Security invariants
|
|
71
|
+
|
|
72
|
+
- explicit deny overrides allow
|
|
73
|
+
- child missions may only attenuate parent authority
|
|
74
|
+
- revoked/expired missions fail closed
|
|
75
|
+
- root credentials stay outside the mission manifest and model context
|
|
76
|
+
- approval is evaluated before credential dispatch
|
|
77
|
+
- receipts identify the principal, agent, mission, service, action, and decision
|
|
78
|
+
- unknown services/actions fail closed
|
|
79
|
+
|
|
80
|
+
## Deployment modes
|
|
81
|
+
|
|
82
|
+
### Embedded middleware
|
|
83
|
+
Best when the application controls tool execution.
|
|
84
|
+
|
|
85
|
+
### Local sidecar
|
|
86
|
+
Best for coding agents and developer harnesses. Agent calls a localhost authority API before sensitive operations.
|
|
87
|
+
|
|
88
|
+
### MCP proxy
|
|
89
|
+
Best for MCP-compatible clients. The proxy evaluates mission policy before forwarding tool calls and can broker upstream OAuth.
|
|
90
|
+
|
|
91
|
+
### Connector platform
|
|
92
|
+
Best for a provider with many SaaS integrations. Existing connectors become credential/transport adapters behind the authority layer.
|
|
93
|
+
|
|
94
|
+
### Hosted enterprise control plane
|
|
95
|
+
Best for shared policy, centralized approvals, audit, revocation, compliance, and workload identity.
|
|
96
|
+
|
|
97
|
+
## What is deliberately not decided yet
|
|
98
|
+
|
|
99
|
+
- canonical signed mission token format
|
|
100
|
+
- universal capability vocabulary
|
|
101
|
+
- agent runtime identity standard
|
|
102
|
+
- receipt signature/log format
|
|
103
|
+
- browser-session isolation design
|
|
104
|
+
- how mission semantics map into emerging IETF agent authorization work
|
|
105
|
+
|
|
106
|
+
These should be validated through implementations and interoperability tests before being frozen into a protocol.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="640" viewBox="0 0 1600 640" role="img" aria-label="Agent Authority — mission scoped authorization for AI agents">
|
|
2
|
+
<defs>
|
|
3
|
+
<linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
|
|
4
|
+
<stop offset="0" stop-color="#07111f"/><stop offset="1" stop-color="#121a36"/>
|
|
5
|
+
</linearGradient>
|
|
6
|
+
<linearGradient id="accent" x1="0" y1="0" x2="1" y2="0">
|
|
7
|
+
<stop offset="0" stop-color="#7c5cff"/><stop offset="1" stop-color="#4ecbff"/>
|
|
8
|
+
</linearGradient>
|
|
9
|
+
</defs>
|
|
10
|
+
<rect width="1600" height="640" rx="36" fill="url(#bg)"/>
|
|
11
|
+
<g font-family="Arial, Helvetica, sans-serif" fill="#fff">
|
|
12
|
+
<text x="100" y="120" font-size="28" font-weight="700" letter-spacing="3">NULLSQUARE / OPEN SOURCE</text>
|
|
13
|
+
<text x="100" y="220" font-size="78" font-weight="800">Agent Authority</text>
|
|
14
|
+
<text x="100" y="285" font-size="34" fill="#b9c7e6">Mission-scoped authorization for AI agents</text>
|
|
15
|
+
<text x="100" y="355" font-size="27" fill="#8fe1ff">One mission · Any agent · Any auth system</text>
|
|
16
|
+
</g>
|
|
17
|
+
<g transform="translate(930 95)" font-family="Arial, Helvetica, sans-serif">
|
|
18
|
+
<rect x="120" y="0" width="330" height="72" rx="16" fill="#111c34" stroke="#6d85ff"/>
|
|
19
|
+
<text x="285" y="44" text-anchor="middle" font-size="24" fill="#fff">Human-approved mission</text>
|
|
20
|
+
<path d="M285 72 V120" stroke="#7786a8" stroke-width="3"/>
|
|
21
|
+
<rect x="80" y="120" width="410" height="90" rx="18" fill="#171842" stroke="#8b67ff" stroke-width="2"/>
|
|
22
|
+
<text x="285" y="158" text-anchor="middle" font-size="25" font-weight="700" fill="#fff">AUTHORITY RUNTIME</text>
|
|
23
|
+
<text x="285" y="190" text-anchor="middle" font-size="20" fill="#b9c7e6">allow · deny · approve · revoke</text>
|
|
24
|
+
<path d="M285 210 V260" stroke="#7786a8" stroke-width="3"/>
|
|
25
|
+
<rect x="80" y="260" width="410" height="72" rx="16" fill="#101b30" stroke="#4ecbff"/>
|
|
26
|
+
<text x="285" y="304" text-anchor="middle" font-size="23" fill="#fff">Adapters / connectors</text>
|
|
27
|
+
<path d="M285 332 V382" stroke="#7786a8" stroke-width="3"/>
|
|
28
|
+
<g fill="#101b30" stroke="#4b628c">
|
|
29
|
+
<rect x="0" y="382" width="135" height="64" rx="14"/><rect x="145" y="382" width="135" height="64" rx="14"/>
|
|
30
|
+
<rect x="290" y="382" width="135" height="64" rx="14"/><rect x="435" y="382" width="135" height="64" rx="14"/>
|
|
31
|
+
</g>
|
|
32
|
+
<g font-size="20" fill="#fff" text-anchor="middle">
|
|
33
|
+
<text x="67" y="422">OAuth</text><text x="212" y="422">MCP</text><text x="357" y="422">API / CLI</text><text x="502" y="422">Legacy</text>
|
|
34
|
+
</g>
|
|
35
|
+
</g>
|
|
36
|
+
<rect x="100" y="430" width="690" height="2" fill="url(#accent)"/>
|
|
37
|
+
<g font-family="Arial, Helvetica, sans-serif" font-size="22" fill="#b9c7e6">
|
|
38
|
+
<text x="100" y="485">Delegation attenuation</text><text x="330" y="485">Human approvals</text><text x="555" y="485">Action receipts</text>
|
|
39
|
+
<text x="100" y="530">Credential isolation</text><text x="330" y="530">Legacy compatibility</text><text x="555" y="530">Protocol neutral</text>
|
|
40
|
+
</g>
|
|
41
|
+
</svg>
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# v0.4 clear path
|
|
2
|
+
|
|
3
|
+
This milestone intentionally validates one thing:
|
|
4
|
+
|
|
5
|
+
> A normal agent application can keep its existing provider credentials and SDKs while Agent Authority gives each task narrower, temporary resource authority.
|
|
6
|
+
|
|
7
|
+
## Primary path
|
|
8
|
+
|
|
9
|
+
```text
|
|
10
|
+
human task
|
|
11
|
+
-> Task Lease
|
|
12
|
+
-> guard.run(action, effect)
|
|
13
|
+
-> ALLOW / DENY / authority delta
|
|
14
|
+
-> existing SDK or API
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Validation scenario
|
|
18
|
+
|
|
19
|
+
```text
|
|
20
|
+
"Handle this demo request"
|
|
21
|
+
-> root: one Gmail thread
|
|
22
|
+
-> authorized read
|
|
23
|
+
-> derive sender from the same Task Lease receipt
|
|
24
|
+
-> bind Calendar attendee to that sender
|
|
25
|
+
-> exact attendee succeeds
|
|
26
|
+
-> another attendee requires step-up
|
|
27
|
+
-> complete task
|
|
28
|
+
-> later calls fail
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Must be true
|
|
32
|
+
|
|
33
|
+
- Mission policy remains the ceiling.
|
|
34
|
+
- Derived authority cannot cross Task Leases.
|
|
35
|
+
- Derived authority must descend from an existing task fact.
|
|
36
|
+
- The trusted extraction selector is recorded.
|
|
37
|
+
- Denied and step-up actions never invoke the side-effect callback.
|
|
38
|
+
- Task completion removes task authority independently of provider credentials.
|
|
39
|
+
|
|
40
|
+
## Deliberately deferred
|
|
41
|
+
|
|
42
|
+
Do not expand v0.4 to solve these until the primary path has external validation:
|
|
43
|
+
|
|
44
|
+
- persistent Task Lease storage;
|
|
45
|
+
- automatic application of approved authority deltas;
|
|
46
|
+
- cryptographic proof of output extraction;
|
|
47
|
+
- browser OAuth onboarding;
|
|
48
|
+
- remote ChatGPT app UX;
|
|
49
|
+
- broad connector coverage;
|
|
50
|
+
- multi-agent delegation UI;
|
|
51
|
+
- a new authorization protocol or policy language.
|
|
52
|
+
|
|
53
|
+
Those are follow-on questions, not requirements for proving the developer primitive.
|