Skip to content

Commit 1a644a9

Browse files
author
Amp AI
committed
init docs
1 parent 25d4341 commit 1a644a9

File tree

4 files changed

+522
-1409
lines changed

4 files changed

+522
-1409
lines changed

‎README.md‎

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

3-
**Central authentication and credentials manager for the raibid-labs ecosystem.**
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:
45

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).
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.).
612

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

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

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.
19+
The core goals are:
1220

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.
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.

0 commit comments

Comments
 (0)