Authentication

The tinykit-cli CLI uses a secure OAuth-based authentication flow to verify your TinyKit account and product access.

OAuth Flow Overview

When you run tinykit login or attempt to download a product, the CLI initiates a device-based OAuth flow:

┌─────────────┐     1. Start local server     ┌──────────────┐
│   CLI       │ ───────────────────────────── │  Localhost   │
│             │     (random port)             │  :PORT       │
└─────────────┘                               └──────────────┘
       │
       │  2. Open browser
       ▼
┌─────────────────────────────────────────────────────────┐
│  Browser: tinykit.dev/auth/cli?port=PORT                │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │  Sign in with GitHub / Google / Email            │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
       │
       │  3. After auth, redirect to localhost:PORT
       ▼
┌──────────────┐     4. Receive token          ┌─────────────┐
│  Localhost   │ ─────────────────────────────▶│   CLI       │
│  :PORT       │     (token, email, name)      │             │
└──────────────┘                               └─────────────┘
       │
       │  5. Store token securely
       ▼
┌─────────────────────────────────────────────────────────┐
│  OS Keychain (primary) or ~/.tinykit/credentials.json   │
└─────────────────────────────────────────────────────────┘

Flow Steps

1. Start Callback Server: CLI starts an HTTP server on a random available port
2. Open Browser: Opens your default browser to tinykit.dev/auth/cli?port=PORT
3. User Authenticates: You sign in using GitHub, Google, or email
4. Callback: TinyKit redirects to localhost:PORT/callback with your token
5. Store Token: CLI stores the token securely and closes the server

Token Storage

The CLI stores authentication tokens using a two-tier storage system for maximum security and compatibility.

Primary: OS Keychain

By default, tokens are stored in your operating system's secure credential storage:

The keychain is the most secure option as it:

• Encrypts tokens at rest
• Requires system authentication to access
• Integrates with your OS security model

Fallback: File Storage

If keychain access fails (e.g., in CI environments or headless systems), the CLI falls back to file-based storage:

~/.tinykit/credentials.json

The file is created with restricted permissions:

• Directory: 0700 (owner read/write/execute only)
• File: 0600 (owner read/write only)

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "storedAt": 1706054400000
}

Security Note: File-based storage is less secure than the OS keychain. Avoid using it on shared systems.

Re-Authentication

Use the --force flag to re-authenticate even when already logged in:

npx tinykit-cli login --force

This is useful when:

• Switching to a different TinyKit account
• Your token has expired or become invalid
• You need to refresh your product access

Token Expiration

Tokens remain valid until:

• You explicitly log out with tinykit logout
• Your TinyKit account is deactivated
• Your subscription or license expires

The CLI automatically checks token validity before making API requests and will prompt you to re-authenticate if needed.

Troubleshooting

Browser Doesn't Open

If the browser doesn't open automatically:

1. Check terminal output for the authentication URL
2. Copy and paste the URL into your browser manually
3. Complete the sign-in process
4. The CLI will detect the callback automatically

Keychain Access Denied

On macOS, you may see a system prompt asking to allow keychain access:

1. Click Allow or Always Allow
2. If you clicked Deny, run tinykit login --force to retry
3. Check System Preferences > Security & Privacy > Privacy > Full Disk Access

Token Not Persisting

If you need to re-authenticate frequently:

1. Check if keychain service is running
2. Verify file permissions on ~/.tinykit/
3. Ensure you have write access to your home directory

# Check file storage location
ls -la ~/.tinykit/

# Verify credentials file exists and has content
test -s ~/.tinykit/credentials.json && echo "✓ Credentials file exists" || echo "✗ No credentials found"

Authentication Timeout

The callback server has a 5-minute timeout. If authentication takes too long:

1. The CLI will show a timeout error
2. Run tinykit login to start a fresh authentication
3. Complete the sign-in process within 5 minutes

CI/CD Environments

For headless environments without a browser:

1. Authenticate locally first: tinykit login
2. Copy the token from ~/.tinykit/credentials.json
3. Set it as an environment variable in your CI:

# In your CI configuration
export TINYKIT_TOKEN="your-token-here"

Note: CI token support requires CLI version 1.1.0 or later.

Security Best Practices

1. Never share your token - Treat it like a password
2. Use keychain when possible - Prefer OS-level security
3. Log out on shared systems - Run tinykit logout before leaving
4. Rotate tokens periodically - Re-authenticate occasionally with --force
5. Monitor account activity - Check your TinyKit account for unauthorized access