# SNS Auth — CLI Identity Gateway (Future Project)

**Status**: Research / Pre-development
**Target market**: Small to mid-size businesses
**Concept**: A terminal-based authentication tool that issues short-lived credentials after hardware/passkey verification. One login → all internal tools authenticated. The `mwinit` pattern, productized for SMBs.

---

## Problem Statement

Small companies use: static API keys in `.env` files, long-lived SSH keys, shared passwords, maybe 2FA on a web UI. There is no turnkey CLI-first auth system aimed at small businesses who want to secure internal tooling (scripts, APIs, CI, servers) without a bloated web portal.

---

## Product Shape

```
sns-auth                    <- single Go binary, ~15MB
├── login                   <- FIDO2/passkey tap (or TOTP fallback)
├── status                  <- session info, expiry, scopes
├── token [--scope X]       <- mint a scoped short-lived token
├── exec -- <cmd>           <- run command with creds injected (env vars)
├── secret get/set <name>   <- encrypted secret store (age or bw-backed)
├── enroll                  <- first-time device registration
├── revoke [--all]          <- kill sessions
├── audit                   <- recent auth events
└── admin                   <- user/device/scope management (server-side)

sns-auth-server             <- lightweight daemon (systemd socket-activated)
├── /auth/begin, /auth/finish  <- WebAuthn ceremony
├── /token/issue               <- scoped token mint
├── /token/revoke              <- revocation
├── /audit/log                 <- append-only event log
├── /admin/*                   <- user/device CRUD
└── SQLite backend             <- zero external deps
```

---

## Feature Set

### Authentication
- Passwordless primary auth — FIDO2/WebAuthn hardware key or passkey
- Short-lived session tokens — 8-24hr expiry, auto-refresh, forced re-auth after expiry
- Device binding — token locked to machine fingerprint (hostname + MAC + machine-id)
- TOTP fallback — for environments without hardware keys
- Offline grace period — cached credential works N minutes without server contact

### Authorization
- Role-based scopes — each token carries explicit scopes (e.g. `infra:read`, `deploy:write`)
- Service-specific sub-tokens — `sns-auth token --scope git` mints narrow token for one service
- Deny-by-default — no scope = no access

### Credential Management
- Secrets vault integration — `sns-auth secret get <name>` fetches from encrypted store
- Automatic credential injection — `sns-auth exec -- docker push ...` injects env vars
- Rotation enforcement — tracks long-lived token expiry, warns/blocks when overdue

### Audit & Security
- Append-only audit log — every auth event logged with timestamp + device + IP
- Session revocation — `sns-auth revoke --all` kills all active sessions instantly
- Tamper detection — CLI binary checks its own integrity on launch
- Lockout policy — brute-force protection (irrelevant with FIDO2 but defense-in-depth)

### Operations
- Single binary — one Go binary, zero runtime deps
- Lightweight server — SQLite backend, runs on any Linux box
- Mesh-aware — works over private networks (NetBird, Tailscale, WireGuard)
- Graceful degradation — cached sessions survive server downtime until expiry
- Bootstrap mode — first-run device enrollment with one-time code

---

## Competitive Advantage Over Current SMB Options

| What they have now | What sns-auth provides |
|---|---|
| Shared `.env` files with API keys | Zero standing credentials — everything expires |
| Password manager + hope | Hardware key / passkey required for any credential |
| No audit trail | Every token issuance, secret access, session logged |
| SSH keys that never rotate | Short-lived SSH certs (8hr), auto-expire |
| "Who has access?" = guessing | `sns-auth admin list` shows all active sessions/devices |
| Each tool has its own login | One `sns-auth login` → all tools authenticated |

---

## Open Source Foundations (build from, not fork)

### Recommended: Clean-room build using permissive libraries

All BSD/Apache/MIT — fully closeable source:

| Library | Purpose | License |
|---------|---------|---------|
| `github.com/go-webauthn/webauthn` | WebAuthn/FIDO2 ceremonies | BSD-3 |
| `github.com/lestrrat-go/jwx` | JWT/JWE/JWK token handling | MIT |
| `github.com/mattn/go-sqlite3` | Storage (users, sessions, audit) | MIT |
| `github.com/spf13/cobra` | CLI framework | Apache-2.0 |
| `golang.org/x/crypto` | Crypto primitives (age, argon2) | BSD-3 |

### Reference implementations (study, don't fork directly)

| Project | What to steal | URL | License |
|---------|--------------|-----|---------|
| **Vouch** (vouch.sh) | UX flow: YubiKey tap → 8hr session → SSH/AWS/Git creds. Scoped token issuance, credential helper pattern. | vouch.sh | Apache-2.0/MIT (CLI) |
| **Smallstep CLI** | Command structure, browser-callback OAuth flow, cert renewal logic, shell integration. | github.com/smallstep/cli | Apache-2.0 |
| **Hanko** | Passkey auth engine, user management, JWT session handling. Go backend with clean API. | github.com/teamhanko/hanko | AGPL-3.0 (caution — study only) |
| **Passwordless-Auth-Rust** | WebAuthn + TOTP + magic link flow, JWT revocation, SQLite backend. Architecture reference. | github.com/hoangsonww/Passwordless-Auth-Rust | Check repo |

### Pieces to steal from specific projects

| Project | Steal what |
|---------|-----------|
| Kefmat/zero-trust-token-authority | Merkle tree audit log, DPoP proof-of-possession binding |
| kontext-security/kontext-cli | Credential injection pattern (`exec -- command`), scoped access model |
| kanidm/webauthn-rs | Battle-tested WebAuthn implementation (Rust reference if ever needed) |

---

## Tech Decisions

- **Language**: Go (single static binary, cross-compile, same ecosystem as Smallstep/Hanko)
- **Storage**: SQLite (zero-dependency, embedded, good enough for 10k+ users)
- **Crypto**: Ed25519 for signing, AES-256-GCM for secrets at rest, Argon2id for any key derivation
- **Transport**: HTTPS (TLS 1.3) between CLI and server; mTLS optional for high-security deployments
- **Distribution**: Single binary download, Docker image for server, systemd unit file

---

## Development Phases

| Phase | What | Estimated effort |
|-------|------|------------------|
| **1 - MVP** | Passkey auth + JWT minting, CLI client (`login`/`status`/`token`/`exec`), SQLite audit | 4-5 weekends |
| **2 - Polish** | Device enrollment, TOTP fallback, `secret` command (age-backed), branding, docs | 3-4 weekends |
| **3 - Productize** | Install script, Docker compose for server, admin TUI, pricing page, landing site | 3-4 weekends |
| **4 - Harden** | Security audit, pen-test, binary tamper detection, key ceremony documentation | Ongoing |

---

## Business Model Options

- **Open-core**: CLI + single-user server free; multi-user, team management, SSO bridge = paid
- **Per-seat**: Free for 1-3 users, paid per seat after (standard SMB model)
- **Appliance**: Ship a pre-configured LXC/VM image customers drop into their infra

---

## Notes

- Research date: 2026-08-04
- This tool does NOT compete with Okta/Auth0 (those are web-app identity providers). This is CLI-first infra auth — closer to HashiCorp Vault's auth methods but simpler and standalone.
- Potential name candidates: sns-auth, gate, sentinel, keypost (TBD)