@integrity-labs/cloud-broker 0.2.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/README.md +85 -0
- package/dist/index.js +21258 -0
- package/package.json +41 -0
package/README.md
ADDED
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# `@integrity-labs/cloud-broker`
|
|
2
|
+
|
|
3
|
+
MCP server for the Augmented ephemeral cloud-access broker. Exposes the agent-facing tools (`request_access`, `poll_grant`, `release_access`, `describe_scope`, `preview_request`) that mint, poll, and release scoped, TTL-bounded cloud credentials for a single task.
|
|
4
|
+
|
|
5
|
+
**v1 ships AWS support** (STS AssumeRole under the hood; pair with the `aws-cli` toolkit or any AWS SDK as the consumer). GCP, Azure, and Cloudflare land in this same package as the broker grows; the AWS-shaped tools below are the v1 contract and per-cloud namespacing arrives with the second cloud.
|
|
6
|
+
|
|
7
|
+
See the [PRD](../../docs/prds/aws-ephemeral-access.md) and the [toolkit doc](../../docs/toolkits/aws.md) for the full design.
|
|
8
|
+
|
|
9
|
+
## Tools
|
|
10
|
+
|
|
11
|
+
| Tool | Purpose |
|
|
12
|
+
|---|---|
|
|
13
|
+
| `describe_scope` | Returns the team's resolved policy ceiling for an account — what the agent is allowed to ask for. Free, idempotent. |
|
|
14
|
+
| `preview_request` | Dry-run a candidate request: `auto_approve` / `route_to_approver` / `hard_deny`. Writes nothing. |
|
|
15
|
+
| `request_access` | Mint or queue a grant. On `auto_approve` you get `secret_ref`; on `route_to_approver` you get `pending` and a grant_id to poll. |
|
|
16
|
+
| `poll_grant` | Single-shot status check. Back-off ~10s between polls. |
|
|
17
|
+
| `release_access` | Voluntarily release a grant before TTL. Idempotent. |
|
|
18
|
+
|
|
19
|
+
## Environment
|
|
20
|
+
|
|
21
|
+
| Var | Purpose |
|
|
22
|
+
|---|---|
|
|
23
|
+
| `AGT_HOST` | Augmented API base URL (e.g. `https://api.augmented.example`). |
|
|
24
|
+
| `AGT_TEAM_SLUG` | Team slug for the `X-Team-Slug` header. |
|
|
25
|
+
| `AGT_TOKEN` | Pre-provisioned JWT (preferred). If set, used until expiry. |
|
|
26
|
+
| `AGT_API_KEY` | Host API key (`tlk_…`). Used to refresh the JWT via `/host/exchange` when `AGT_TOKEN` is missing or expired. |
|
|
27
|
+
|
|
28
|
+
At least one of `AGT_TOKEN` or `AGT_API_KEY` is required.
|
|
29
|
+
|
|
30
|
+
## Worked example
|
|
31
|
+
|
|
32
|
+
An agent that needs to read one S3 object:
|
|
33
|
+
|
|
34
|
+
```jsonc
|
|
35
|
+
// 1. Optional: inspect the envelope before guessing.
|
|
36
|
+
describe_scope({ account_id: "123456789012" })
|
|
37
|
+
|
|
38
|
+
// 2. Optional: dry-run.
|
|
39
|
+
preview_request({
|
|
40
|
+
account_id: "123456789012",
|
|
41
|
+
actions: ["s3:GetObject", "s3:ListBucket"],
|
|
42
|
+
resources: ["arn:aws:s3:::reports/*", "arn:aws:s3:::reports"],
|
|
43
|
+
regions: ["us-east-1"],
|
|
44
|
+
ttl_seconds: 900
|
|
45
|
+
})
|
|
46
|
+
// → { "would": "auto_approve", "reason": null }
|
|
47
|
+
|
|
48
|
+
// 3. Mint.
|
|
49
|
+
request_access({
|
|
50
|
+
agent_id: "11111111-1111-4111-8111-111111111111",
|
|
51
|
+
run_id: "22222222-2222-4222-8222-222222222222",
|
|
52
|
+
account_id: "123456789012",
|
|
53
|
+
actions: ["s3:GetObject", "s3:ListBucket"],
|
|
54
|
+
resources: ["arn:aws:s3:::reports/*", "arn:aws:s3:::reports"],
|
|
55
|
+
regions: ["us-east-1"],
|
|
56
|
+
ttl_seconds: 900,
|
|
57
|
+
reason: "fetch the daily reports CSV for the user"
|
|
58
|
+
})
|
|
59
|
+
// → { "grant_id": "...", "status": "active", "secret_ref": "secret_ref://aws/runs/<run_id>/<grant_id>", "expires_at": "..." }
|
|
60
|
+
|
|
61
|
+
// 4. Use the AWS CLI / SDK as normal — the runtime resolves the secret_ref to env vars at exec time.
|
|
62
|
+
// Bash: aws s3 cp s3://reports/today.csv -
|
|
63
|
+
|
|
64
|
+
// 5. (Optional) release early.
|
|
65
|
+
release_access({ grant_id: "..." })
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
If `request_access` returns `status: "pending"`, a human approver was paged. Call `poll_grant` every ~10s until status leaves `pending`. On `denied`, the `denial_reason` field explains why.
|
|
69
|
+
|
|
70
|
+
## Running locally
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
pnpm --filter @integrity-labs/cloud-broker build
|
|
74
|
+
AGT_HOST=http://api.agt.localhost:1355 \
|
|
75
|
+
AGT_TEAM_SLUG=demo \
|
|
76
|
+
AGT_TOKEN=$YOUR_JWT \
|
|
77
|
+
node packages/cloud-broker/dist/index.js
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
The server speaks MCP over stdio. Wire it into your runtime adapter's `.mcp.json` — the toolkit ID is `cloud-broker` (registered in `packages/supabase/seeds/toolkit-definitions.json`).
|
|
81
|
+
|
|
82
|
+
## Notes
|
|
83
|
+
|
|
84
|
+
- The MCP response strips inline credentials from `request_access` — only the `secret_ref` pointer reaches the LLM. The runtime adapter resolves the pointer at AWS-SDK call time so credentials never enter the agent's transcript.
|
|
85
|
+
- Per PRD §6.3 v1 ships TTL-bounded revocation only. `release_access` marks the grant `revoked` in the broker DB and tears down the `secret_ref`, but in-flight STS sessions remain valid in AWS until their TTL. v1.1 closes that gap with the `aws:TokenIssueTime` hard-revoke pattern.
|