unotoken 0.1.0

package/README.md

@@ -0,0 +1,360 @@
+# unotoken
+
+**yokotoken + cloud features.**
+
+unotoken is a private extension of [yokotoken](https://github.com/indigoai-us/yokotoken), the agent-native encrypted credential vault. It adds cloud features on top of the open-source MIT core:
+
+- **OAuth unlock** -- Sign in with Google or GitHub to unlock your vault (no passphrase needed)
+- **Device signatures** -- New devices must be approved via email code before accessing the vault
+- **Team vaults** -- Share encrypted vaults across a team (coming soon)
+- **Key escrow** -- Recovery keys held by your organization (coming soon)
+
+## How it works
+
+unotoken depends on `yokotoken` as an npm package. All of yokotoken's public API is re-exported, so unotoken is a drop-in replacement:
+
+```ts
+// Before
+import { getSecret } from 'yokotoken/sdk';
+import { NetworkVaultClient } from 'yokotoken/client';
+
+// After (identical API)
+import { getSecret } from 'unotoken/sdk';
+import { NetworkVaultClient } from 'unotoken/client';
+```
+
+The CLI wraps yokotoken and adds new commands:
+
+```bash
+# All yokotoken commands work as-is
+unotoken init
+unotoken serve
+unotoken unlock
+unotoken set my/secret "value"
+unotoken get my/secret
+
+# New: OAuth commands
+unotoken auth link google      # Link Google account for passwordless unlock
+unotoken auth link github      # Link GitHub account
+unotoken auth list             # Show linked providers
+unotoken auth unlink google    # Remove a linked provider
+unotoken auth config --show    # View OAuth configuration
+```
+
+## Installation
+
+```bash
+npm install unotoken
+```
+
+Or for CLI usage:
+
+```bash
+npm install -g unotoken
+```
+
+## Package exports
+
+| Import path | Description |
+|-------------|-------------|
+| `unotoken` | Full vault API (re-exports `yokotoken`) |
+| `unotoken/sdk` | Worker SDK for agent access (re-exports `yokotoken/sdk`) |
+| `unotoken/client` | Network client for remote vaults (re-exports `yokotoken/client`) |
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+```
+
+## Build-Time Env Injection
+
+unotoken replaces `.env` files with vault-backed secrets. Two modes:
+
+### exec -- inject secrets into a child process
+
+No `.env` file needed. Secrets are injected as environment variables directly:
+
+```bash
+# Run your app with vault secrets injected
+unotoken exec --prefix myapp/ -- npm run dev
+
+# In package.json:
+"scripts": {
+  "dev": "unotoken exec --prefix myapp/ -- next dev",
+  "build": "unotoken exec --prefix myapp/ -- next build"
+}
+```
+
+Path mapping: `myapp/stripe/secret/key` becomes `STRIPE_SECRET_KEY`.
+
+### dotenv -- generate .env files from vault
+
+For tools that require a `.env` file on disk:
+
+```bash
+# Generate .env.local from vault
+unotoken dotenv --prefix myapp/ --out .env.local
+
+# Clean up after build (CI/CD)
+unotoken dotenv --clean .env.local
+```
+
+### Scoped tokens
+
+Create tokens that only access specific prefixes:
+
+```bash
+# Create a token restricted to myapp/* secrets
+unotoken token create --name myapp-ci --prefix myapp/
+
+# Multi-prefix tokens
+unotoken token create --name shared --prefix myapp/ --prefix common/
+```
+
+### Real-app demo (levelfit)
+
+A hands-on demo script walks through the complete flow using real secrets:
+
+```bash
+bash scripts/demo-levelfit.sh
+```
+
+The demo covers:
+1. **Scoped token creation** -- create a token restricted to `levelfit/*`
+2. **Access verification** -- confirm the token can access `levelfit/` but not other prefixes
+3. **exec injection** -- run a process with vault secrets as env vars (no file on disk)
+4. **dotenv generation** -- produce a `.env` file equivalent to a hand-maintained `.env.local`
+5. **Cleanup** -- remove generated files and revoke demo tokens
+
+Prerequisites: vault running (`unotoken serve`), vault unlocked (`unotoken unlock`), secrets stored under `levelfit/` prefix.
+
+## Package.json Scripts Integration
+
+Replace `.env` files with vault-backed secrets in your npm scripts. Here are before/after patterns for common setups.
+
+### Next.js
+
+**Before (.env.local on disk):**
+
+```json
+{
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  }
+}
+```
+
+**After (vault-backed):**
+
+```json
+{
+  "scripts": {
+    "dev": "unotoken exec --prefix myapp/ -- next dev",
+    "build": "unotoken exec --prefix myapp/ -- next build",
+    "start": "unotoken exec --prefix myapp/ -- next start"
+  }
+}
+```
+
+### Vite
+
+**Before:**
+
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  }
+}
+```
+
+**After:**
+
+```json
+{
+  "scripts": {
+    "dev": "unotoken exec --prefix myapp/ -- vite",
+    "build": "unotoken exec --prefix myapp/ -- vite build",
+    "preview": "unotoken exec --prefix myapp/ -- vite preview"
+  }
+}
+```
+
+### Node.js API Server
+
+**Before:**
+
+```json
+{
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "start": "node dist/server.js"
+  }
+}
+```
+
+**After:**
+
+```json
+{
+  "scripts": {
+    "dev": "unotoken exec --prefix myapi/ -- tsx watch src/server.ts",
+    "start": "unotoken exec --prefix myapi/ -- node dist/server.js"
+  }
+}
+```
+
+### CI/CD (GitHub Actions)
+
+Use `UNOTOKEN_TOKEN` and `UNOTOKEN_URL` environment variables for remote vault access:
+
+```yaml
+# .github/workflows/deploy.yml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm ci
+      - name: Build with vault secrets
+        env:
+          UNOTOKEN_TOKEN: ${{ secrets.VAULT_TOKEN }}
+          UNOTOKEN_URL: https://vault.example.com:13100
+        run: unotoken exec --prefix myapp/ -- npm run build
+```
+
+Or as a single inline command:
+
+```bash
+UNOTOKEN_TOKEN=${{ secrets.VAULT_TOKEN }} UNOTOKEN_URL=https://vault.example.com unotoken exec --prefix myapp/ -- npm run build
+```
+
+### Fallback Pattern
+
+If the vault might be unavailable (e.g., a new team member who hasn't set up the vault yet), use a fallback to `.env.local`:
+
+```json
+{
+  "scripts": {
+    "dev": "unotoken exec --prefix myapp/ -- next dev || (echo 'Vault unavailable, using .env.local fallback' && next dev)",
+    "build": "unotoken exec --prefix myapp/ -- next build || (echo 'Vault unavailable, using .env.local fallback' && next build)"
+  }
+}
+```
+
+This runs with vault secrets when available, and falls back to any `.env.local` file on disk when the vault is locked or unreachable.
+
+## Moving from .env to unotoken
+
+A step-by-step migration guide for replacing hand-maintained `.env` files with vault-backed secrets.
+
+### Step 1: Import existing secrets into the vault
+
+```bash
+# Start the vault if not running
+unotoken serve &
+unotoken unlock
+
+# Import each secret from your .env.local
+unotoken set myapp/database/url "postgresql://user:pass@host/db"
+unotoken set myapp/stripe/secret/key "sk_live_..."
+unotoken set myapp/next/public/stripe/publishable/key "pk_live_..."
+
+# Or bulk-import from a .env file (one per line)
+while IFS='=' read -r key value; do
+  # Convert KEY_NAME to key/name path format
+  path=$(echo "$key" | tr '[:upper:]' '[:lower:]' | tr '_' '/')
+  unotoken set "myapp/$path" "$value"
+done < .env.local
+```
+
+### Step 2: Create a scoped token
+
+```bash
+# Create a token restricted to your app's prefix
+unotoken token create --name myapp-dev --prefix myapp/
+
+# Save the displayed token -- it's only shown once
+# For CI/CD, store it as a GitHub Actions secret (VAULT_TOKEN)
+```
+
+### Step 3: Update package.json scripts
+
+Replace direct commands with `unotoken exec`:
+
+```diff
+ {
+   "scripts": {
+-    "dev": "next dev",
+-    "build": "next build"
++    "dev": "unotoken exec --prefix myapp/ -- next dev",
++    "build": "unotoken exec --prefix myapp/ -- next build"
+   }
+ }
+```
+
+### Step 4: Update .gitignore
+
+If using `dotenv` mode (generating `.env.local` from the vault), add the generated file to `.gitignore` since it's now a build artifact:
+
+```gitignore
+# Generated by unotoken (vault-backed, not hand-maintained)
+.env.local
+```
+
+### Step 5: Remove .env.local
+
+Once you've verified everything works with vault-backed secrets:
+
+```bash
+# Verify vault injection works
+npm run dev  # should start with all env vars injected
+
+# Remove the old .env.local
+rm .env.local
+```
+
+### Path-to-Variable Mapping Reference
+
+Vault paths are converted to environment variable names by:
+1. Stripping the prefix (e.g., `myapp/`)
+2. Replacing `/` with `_`
+3. Uppercasing the result
+
+| Vault Path | Env Variable |
+|------------|-------------|
+| `myapp/stripe/secret/key` | `STRIPE_SECRET_KEY` |
+| `myapp/database/url` | `DATABASE_URL` |
+| `myapp/next/public/stripe/publishable/key` | `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` |
+| `myapp/resend/api/key` | `RESEND_API_KEY` |
+
+## Architecture
+
+```
+yokotoken (MIT, public)
+  |
+  +-- unotoken (private, cloud add-on)
+        |-- Re-exports all yokotoken API
+        |-- OAuth PKCE browser flow engine
+        |-- Google + GitHub OIDC/OAuth providers
+        |-- Wrapped key storage for OAuth-derived unlock
+        |-- Device signatures (email-verified device approval)
+        |-- CLI extensions (auth link, auth unlink, auth list, auth config)
+```
+
+Upstream updates are clean: just bump the `yokotoken` version in `package.json`.
+
+## License
+
+UNLICENSED (private)

package/dist/cli.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * unotoken CLI — yokotoken + cloud features.
+ *
+ * Wraps the yokotoken CLI and extends it with OAuth-related commands:
+ * - auth link <provider>    Link an OAuth identity for passwordless unlock
+ * - auth unlink <provider>  Remove an OAuth identity link
+ * - auth list               List linked OAuth providers
+ * - auth config             Configure custom OAuth client credentials
+ * - unlock --oauth          Unlock the vault using linked OAuth identity
+ * - config email <address>  Register and verify email for device signatures
+ * - device guard check on all vault operations (unlock, get, set, list)
+ *
+ * All other commands are delegated to the underlying yokotoken CLI.
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;GAaG"}