|
1 | 1 | # Agentic Secrets |
2 | 2 |
|
3 | | -Version: `0.1.0 alpha` |
| 3 | +Agentic Secrets protects runtime secrets on macOS developer machines. |
4 | 4 |
|
5 | | -Agentic Secrets is a macOS self-build tool for lower-leakage secret delivery on developer machines. Its core job is controlled delivery at runtime: deciding when, how, and to which local tool a stored secret may be released, with local approval through Touch ID or the local account password. |
| 5 | +It keeps long-lived provider tokens out of ambient places like `.env` files, shell startup files, MCP configs, and native CLI config files. Secrets are stored locally, released only for an approved runtime request, and tied to a specific tool, target binary identity, delivery context, and local authentication event. |
6 | 6 |
|
7 | | -It keeps provider tokens out of `.env` files, shell startup files, MCP configs, and native CLI config files such as `hcloud`'s `cli.toml`. It does not make arbitrary command execution safe; it makes secret delivery explicit, narrow, locally approved, auditable, and fail-closed. |
| 7 | +Agentic Secrets does not sandbox commands or make target tools trustworthy. It protects the secret delivery boundary: when a secret may be released, to which local tool, through which mechanism, under which policy, and with what audit trail. |
8 | 8 |
|
9 | | -This is an alpha release: expect breaking changes while the CLI, storage format, and trust model settle. |
| 9 | +## Why |
| 10 | + |
| 11 | +Developer tools often expect credentials to be present before they run. That pushes secrets into broad, sticky locations: |
| 12 | + |
| 13 | +- shell environments inherited by unrelated processes |
| 14 | +- `.env` files and shell rc files |
| 15 | +- MCP server configuration files |
| 16 | +- native CLI config files |
| 17 | +- ad hoc scripts and logs |
| 18 | + |
| 19 | +Agentic Secrets replaces ambient secret presence with explicit runtime delivery. |
10 | 20 |
|
11 | 21 | ## How It Works |
12 | 22 |
|
13 | | -- You register a CLI app once, for example `hcloud`, and pass the token through stdin. |
14 | | -- Agentic Secrets stores the secret in a local encrypted store and keeps non-secret CLI metadata in its registry. |
15 | | -- Each run validates the registered target binary identity before resolving the secret. |
16 | | -- macOS LocalAuthentication is required before secret delivery. Depending on system state, macOS may ask for Touch ID, Apple Watch, or the local account password. |
17 | | -- Successful CLI authentication creates a scoped authorization grant for matching runs. The default mode is `always`; `remember-24h`, `short`, and `once` are available per run. Persistent grants are signed with a device-local macOS Keychain key and are bound to the CLI, target identity, workspace, config context, untrusted origin hint, provenance confidence, delivery mode, and secret alias. Each command is still policy-checked before secret delivery, and destructive commands require fresh approval. |
18 | | -- Trust changes, such as `trust-refresh` after a CLI upgrade, also require LocalAuthentication. |
19 | | -- Registry tampering and target replacement fail closed before any secret is read. |
| 23 | +- Register a local tool and the secret bindings it may receive. |
| 24 | +- Store secret material in an owner-only encrypted local store. |
| 25 | +- Validate the target binary identity before each delivery. |
| 26 | +- Require macOS LocalAuthentication before secret release. |
| 27 | +- Reuse narrowly scoped delivery grants only when policy allows. |
| 28 | +- Fail closed on registry, policy, grant, or target identity tampering. |
| 29 | +- Write structured audit records without secret values. |
20 | 30 |
|
21 | | -## Quick Install |
| 31 | +## Install |
22 | 32 |
|
23 | | -Requirements: macOS Tahoe 26.x, SwiftPM, Xcode Command Line Tools or Xcode with the macOS 26 SDK. |
| 33 | +Requirements: macOS Tahoe 26.x, SwiftPM, and Xcode Command Line Tools or Xcode with the macOS 26 SDK. |
24 | 34 |
|
25 | 35 | ```sh |
26 | 36 | git clone https://github.com/CodeAlive-AI/agentic-secrets.git |
27 | 37 | cd agentic-secrets |
28 | 38 | ./scripts/install_local.sh --load --configure-shell |
29 | 39 | ``` |
30 | 40 |
|
31 | | -Open a new terminal, or load the PATH change in the current one: |
| 41 | +Open a new terminal, then verify: |
32 | 42 |
|
33 | 43 | ```sh |
34 | | -source "$HOME/.zshrc" |
35 | 44 | command -v agentic-secrets |
36 | | -``` |
37 | | - |
38 | | -Verify the local build: |
39 | | - |
40 | | -```sh |
41 | 45 | agentic-secrets release-gates |
42 | 46 | ``` |
43 | 47 |
|
44 | | -## hcloud Example |
45 | | - |
46 | | -Register `hcloud` without writing the token to `cli.toml`: |
47 | | - |
48 | | -```sh |
49 | | -agentic-secrets cli register hcloud \ |
50 | | - --env HCLOUD_TOKEN \ |
51 | | - --secret-prompt |
52 | | -``` |
53 | | - |
54 | | -Run `hcloud` through Agentic Secrets: |
55 | | - |
56 | | -```sh |
57 | | -agentic-secrets cli run hcloud -- server list |
58 | | -``` |
59 | | - |
60 | | -Choose authorization mode for one run: |
61 | | - |
62 | | -```sh |
63 | | -agentic-secrets cli run hcloud --authorization-mode remember-24h -- server list |
64 | | -agentic-secrets cli run hcloud --authorization-mode short --delivery-grant-ttl-seconds 300 -- server list |
65 | | -agentic-secrets cli run hcloud --delivery-grant-ttl-seconds 0 -- server list |
66 | | -``` |
67 | | - |
68 | | -Optional: install a shim so `hcloud ...` itself routes through Agentic Secrets. This does not replace the Homebrew binary; it creates an Agentic Secrets shim directory that is placed before the native CLI on `PATH`. |
69 | | - |
70 | | -```sh |
71 | | -agentic-secrets cli shim install hcloud --configure-shell |
72 | | -``` |
73 | | - |
74 | | -Open a new terminal, then use: |
75 | | - |
76 | | -```sh |
77 | | -hcloud server list |
78 | | -hcloud version |
79 | | -``` |
80 | | - |
81 | | -Normal commands go through Agentic Secrets secret delivery. Global help/version commands pass through without secret delivery. |
82 | | - |
83 | | -After a Homebrew upgrade of `hcloud`, verify the new binary and refresh trust: |
84 | | - |
85 | | -```sh |
86 | | -agentic-secrets cli trust-refresh hcloud |
87 | | -``` |
88 | | - |
89 | | -### Codex App |
90 | | - |
91 | | -Codex App may not inherit the same shell startup environment as Terminal. Do not |
92 | | -put `HCLOUD_TOKEN` into `~/.codex/.env`; that bypasses Agentic Secrets secret |
93 | | -delivery. Instead, install the Agentic Secrets shim and make sure Codex resolves |
94 | | -`hcloud` to the local shim path: |
95 | | - |
96 | | -```sh |
97 | | -agentic-secrets cli shim install hcloud --force |
98 | | -command -v hcloud |
99 | | -``` |
100 | | - |
101 | | -Expected path: |
102 | | - |
103 | | -```text |
104 | | -~/Library/Application Support/AgenticSecrets/LocalInstall/shims/hcloud |
105 | | -``` |
106 | | - |
107 | | -## More |
| 48 | +## Documentation |
108 | 49 |
|
109 | | -- Full install and troubleshooting: [Docs/INSTALLATION.md](Docs/INSTALLATION.md) |
110 | | -- Operations guide: [Docs/OPERATIONS.md](Docs/OPERATIONS.md) |
111 | | -- Acceptance criteria: [Docs/ACCEPTANCE_CRITERIA.md](Docs/ACCEPTANCE_CRITERIA.md) |
112 | | -- Threat model: [Docs/THREAT_MODEL.md](Docs/THREAT_MODEL.md) |
113 | | -- Developer/agent notes: [AGENTS.md](AGENTS.md) |
| 50 | +- [Installation](Docs/INSTALLATION.md) |
| 51 | +- [Operations](Docs/OPERATIONS.md) |
| 52 | +- [Threat model](Docs/THREAT_MODEL.md) |
| 53 | +- [Acceptance criteria](Docs/ACCEPTANCE_CRITERIA.md) |
| 54 | +- [Implementation map](Docs/IMPLEMENTATION_MAP.md) |
| 55 | +- [Ubiquitous language](Docs/THESAURUS.md) |
| 56 | +- [Contributing](CONTRIBUTING.md) |
| 57 | +- [Security policy](SECURITY.md) |
0 commit comments