Skip to content

Commit 15253b5

Browse files
Amp AIclaude
Amp AI
and
claude
committed
Restore detailed docs, move simplified versions to codex
- Restore README.md, ARCHITECTURE.md, INTERFACES.md, ROADMAP.md to detailed v0.2.0 versions (with diagrams, Rust traits, examples) - Move simplified "conceptual" docs to docs/codex/ for reference The v0.2.0 docs contain implementation-ready details: - Full Rust trait definitions with async_trait - OAuth flow diagrams and token lifecycle charts - JSON-RPC API examples - Detailed workspace layout 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
1 parent 1a644a9 commit 15253b5

File tree

8 files changed

+2050
-522
lines changed

8 files changed

+2050
-522
lines changed

‎README.md‎

Lines changed: 174 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,181 @@
11
# Sigilforge
22

3-
Sigilforge is a local **auth and credential manager** for the raibid-labs
4-
ecosystem. It acts as a small, personal "vault + token service" that:
3+
**Central authentication and credentials manager for the raibid-labs ecosystem.**
54

6-
- Manages API keys, OAuth tokens, and other sensitive values.
7-
- Runs OAuth flows (device code, PKCE, etc.) on behalf of client apps.
8-
- Stores and refreshes OAuth tokens securely.
9-
- Provides a **reference-based interface** for requesting tokens and secrets.
10-
- Can integrate with multiple secret backends (OS keyring, encrypted files,
11-
vals-style references, etc.).
5+
Sigilforge is a local daemon + library that provides unified secret storage, OAuth flow management, and credential resolution for applications in the raibid-labs family (Scarab, Hibana, Tolaria, Phage, Fusabi, Scryforge).
126

13-
Sigilforge is designed to be used by:
7+
## What It Does
148

15-
- **Scryforge** — the information rolodex TUI/daemon.
16-
- **Phage** and other processing tools.
17-
- Future Fusabi-based applications in the raibid-labs ecosystem.
9+
Sigilforge acts as a **small, local "vault + token service"** that:
1810

19-
The core goals are:
11+
- **Stores credentials securely**: API keys, OAuth refresh tokens, and other sensitive values are stored in the OS keyring at runtime, with optional encrypted file storage (SOPS/ROPS) for Git-friendly configuration.
2012

21-
- Centralize authentication and secret handling.
22-
- Keep application code free of token storage and OAuth flow complexity.
23-
- Provide a reusable **library + daemon** that any tool can talk to.
13+
- **Runs OAuth flows**: Implements OAuth2 device-code and authorization-code+PKCE flows for common providers (Google, Microsoft, Spotify, Reddit, GitHub, etc.) so applications don't need to implement auth themselves.
14+
15+
- **Manages token lifecycles**: Automatically refreshes expired access tokens and persists updated credentials.
16+
17+
- **Resolves credential references**: Uses a URI scheme (`auth://service/account/token`) to provide tokens and secrets to consumers in a uniform way. Optionally supports `vals`-style references for external backends.
18+
19+
## How It Fits in the Ecosystem
20+
21+
```
22+
┌─────────────────────────────────────────────────────────────────┐
23+
│ Consumer Applications │
24+
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
25+
│ │ Scryforge │ │ Phage │ │ Fusabi │ │ Future CLI│ │
26+
│ │ │ │ │ │ Apps │ │ Tools │ │
27+
│ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ │
28+
│ │ │ │ │ │
29+
│ └──────────────┴──────────────┴──────────────┘ │
30+
│ │ │
31+
│ ┌─────────▼─────────┐ │
32+
│ │ Sigilforge │ │
33+
│ │ (daemon + lib) │ │
34+
│ └─────────┬─────────┘ │
35+
│ │ │
36+
│ ┌─────────────────────┼─────────────────────┐ │
37+
│ │ │ │ │
38+
│ ┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐ │
39+
│ │ OS Keyring│ │ Encrypted │ │ OAuth │ │
40+
│ │ │ │ Files │ │ Providers │ │
41+
│ └───────────┘ │(ROPS/SOPS)│ │ │ │
42+
│ └───────────┘ └───────────┘ │
43+
└─────────────────────────────────────────────────────────────────┘
44+
```
45+
46+
### Example Usage
47+
48+
**Scryforge** requesting a Gmail token:
49+
```
50+
auth://gmail/personal/token
51+
```
52+
53+
**Phage** using the same Spotify account:
54+
```
55+
auth://spotify/main/token
56+
```
57+
58+
**CLI** for manual management:
59+
```bash
60+
# Add a new account (starts OAuth flow)
61+
sigilforge add-account spotify personal
62+
63+
# List all configured accounts
64+
sigilforge list-accounts
65+
66+
# Get a fresh access token
67+
sigilforge get-token spotify personal
68+
```
69+
70+
## Problems It Solves
71+
72+
1. **Centralized Auth**: Applications don't re-implement OAuth flows; they ask Sigilforge for tokens.
73+
74+
2. **Secure Secret Storage**: Sensitive values live in the OS keyring or encrypted files, not plaintext configs.
75+
76+
3. **Token Lifecycle Management**: Access tokens are refreshed automatically; consumers always get valid tokens.
77+
78+
4. **Consistent Credential Model**: All apps use the same `service/account` model, making account sharing straightforward.
79+
80+
5. **Reference Resolution**: The `auth://` URI scheme and optional `vals`-style references provide a uniform way to access credentials from configs and code.
81+
82+
## Workspace Structure
83+
84+
```
85+
sigilforge/
86+
├── Cargo.toml # Workspace root
87+
├── sigilforge-core/ # Core types, traits, and logic
88+
├── sigilforge-daemon/ # Background service with local API
89+
├── sigilforge-cli/ # CLI tool for humans
90+
└── docs/
91+
├── STRUCTURE.md # Documentation organization guide
92+
├── ARCHITECTURE.md # System design and components
93+
├── ROADMAP.md # Development phases
94+
├── INTERFACES.md # Trait definitions and API contracts
95+
├── NEXT_STEPS.md # Concrete next tasks for development
96+
├── RELEASE.md # Release process and versioning
97+
└── versions/ # Versioned documentation snapshots
98+
└── v0.1.0/ # Documentation for v0.1.0
99+
```
100+
101+
## Getting Started
102+
103+
### Prerequisites
104+
105+
- Rust 1.85+ (2024 edition)
106+
- A system with keyring support (Linux with `libsecret`, macOS Keychain, Windows Credential Manager)
107+
108+
### Building
109+
110+
```bash
111+
cargo build --workspace
112+
```
113+
114+
### Running the Daemon
115+
116+
```bash
117+
cargo run -p sigilforge-daemon
118+
```
119+
120+
### Using the CLI
121+
122+
```bash
123+
cargo run -p sigilforge-cli -- --help
124+
```
125+
126+
## Configuration
127+
128+
Sigilforge stores its configuration in platform-appropriate directories:
129+
130+
- **Linux**: `~/.config/sigilforge/`
131+
- **macOS**: `~/Library/Application Support/sigilforge/`
132+
- **Windows**: `%APPDATA%\sigilforge\`
133+
134+
See `docs/ARCHITECTURE.md` for details on the configuration format and storage backends.
135+
136+
## Integration
137+
138+
### As a Library
139+
140+
Applications can link `sigilforge-core` directly:
141+
142+
```rust
143+
use sigilforge_core::{TokenManager, ServiceId, AccountId};
144+
145+
async fn get_spotify_token(manager: &impl TokenManager) -> Result<String, Error> {
146+
let service = ServiceId::new("spotify");
147+
let account = AccountId::new("personal");
148+
manager.ensure_access_token(&service, &account).await
149+
}
150+
```
151+
152+
### Via Daemon API
153+
154+
Applications can communicate with `sigilforge-daemon` over a Unix socket (Linux/macOS) or named pipe (Windows):
155+
156+
```json
157+
{"method": "get_token", "params": {"service": "spotify", "account": "personal"}}
158+
```
159+
160+
See `docs/INTERFACES.md` for the full API specification.
161+
162+
## Documentation
163+
164+
- **[STRUCTURE.md](docs/STRUCTURE.md)**: Documentation organization and versioning conventions
165+
- **[ARCHITECTURE.md](docs/ARCHITECTURE.md)**: System design and component details
166+
- **[INTERFACES.md](docs/INTERFACES.md)**: API contracts and trait definitions
167+
- **[ROADMAP.md](docs/ROADMAP.md)**: Development phases and future plans
168+
- **[NEXT_STEPS.md](docs/NEXT_STEPS.md)**: Current development tasks
169+
- **[RELEASE.md](docs/RELEASE.md)**: Release process and versioning workflow
170+
171+
For version-specific documentation, see [docs/versions/](docs/versions/).
172+
173+
## License
174+
175+
MIT
176+
177+
## Related Projects
178+
179+
- **Scryforge**: Multi-provider data synchronization built on Sigilforge for auth.
180+
- **Phage**: Task management and automation using Fusabi components.
181+
- **Fusabi**: TUI framework and common utilities for raibid-labs applications.

0 commit comments

Comments
 (0)