oauth.do 0.1.15 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 org.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,11 +1,59 @@
 # oauth.do
 
-OAuth authentication SDK and CLI for .do Platform.
+[![npm version](https://img.shields.io/npm/v/oauth.do.svg)](https://www.npmjs.com/package/oauth.do)
+[![license](https://img.shields.io/npm/l/oauth.do.svg)](https://github.com/dot-do/oauth.do/blob/main/LICENSE)
+[![tests](https://img.shields.io/github/actions/workflow/status/dot-do/oauth.do/test.yml?label=tests)](https://github.com/dot-do/oauth.do/actions)
 
-## Install
+OAuth authentication SDK and CLI for the .do Platform, wrapping [WorkOS AuthKit](https://workos.com/authkit) with pre-configured defaults and multiple entry points for different environments.
+
+**Why oauth.do?**
+- Pre-configured AuthKit settings for .do Platform - works out of the box
+- Multiple entry points: SDK, CLI, React components, Hono middleware
+- Built-in secure token storage with OS keychain support
+- GitHub Device Flow for CLI tools and headless environments
+
+```typescript
+import { auth } from 'oauth.do'
+
+const { user, token } = await auth()
+console.log(`Hello, ${user.firstName}!`)
+```
+
+## Entry Points
+
+oauth.do provides multiple entry points for different environments:
+
+| Import | Environment | Description |
+|--------|-------------|-------------|
+| `oauth.do` | Universal | Core auth functions (browser, Workers, Node.js) |
+| `oauth.do/node` | Node.js only | CLI helpers with keychain storage (uses `keytar`) |
+| `oauth.do/react` | React | React components and hooks |
+| `oauth.do/hono` | Hono/Workers | Cloudflare Workers middleware |
+| `oauth.do/session` | Universal | Session management utilities |
+
+**Important for Cloudflare Workers:** Import from the main `oauth.do` path or `oauth.do/hono`. The `/node` subpath uses native modules (`keytar`) that won't bundle for Workers.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18.0.0 or higher
+- WorkOS account (optional - for custom AuthKit configuration)
+
+### Installation
 
 ```bash
+# npm
 npm install oauth.do
+
+# pnpm
+pnpm add oauth.do
+
+# yarn
+yarn add oauth.do
+
+# bun
+bun add oauth.do
 ```
 
 ## CLI
@@ -22,14 +70,11 @@ npx oauth.do status    # Show auth status
 ## SDK
 
 ```typescript
-import { auth, login, logout, getToken, isAuthenticated } from 'oauth.do'
+import { auth, logout, getToken, isAuthenticated } from 'oauth.do'
 
 // Check authentication
 const { user, token } = await auth()
 
-// Login
-const result = await login({ email: '...', password: '...' })
-
 // Logout
 await logout(token)
 
@@ -56,7 +101,7 @@ const url = buildAuthUrl({
 For building CLIs that need authentication:
 
 ```typescript
-import { ensureLoggedIn } from 'oauth.do'
+import { ensureLoggedIn } from 'oauth.do/node'
 
 // Get token (prompts login if needed, auto-opens browser)
 const { token, isNewLogin } = await ensureLoggedIn()
@@ -79,12 +124,203 @@ console.log('Code:', auth.user_code)
 const tokens = await pollForTokens(auth.device_code, auth.interval, auth.expires_in)
 ```
 
+## GitHub Device Flow
+
+For CLI tools and headless environments that need GitHub authentication without a browser callback.
+
+```typescript
+import { startGitHubDeviceFlow, pollGitHubDeviceFlow, getGitHubUser } from 'oauth.do'
+
+// Step 1: Start the device flow
+const auth = await startGitHubDeviceFlow({
+  clientId: 'Ov23liABCDEFGHIJKLMN',
+  scope: 'user:email read:user'  // optional, this is the default
+})
+
+console.log(`Visit ${auth.verificationUri} and enter code: ${auth.userCode}`)
+
+// Step 2: Poll for token (blocks until user completes authorization)
+const token = await pollGitHubDeviceFlow(auth.deviceCode, {
+  clientId: 'Ov23liABCDEFGHIJKLMN',
+  interval: auth.interval,
+  expiresIn: auth.expiresIn
+})
+
+// Step 3: Get user information
+const user = await getGitHubUser(token.accessToken)
+console.log(`Logged in as ${user.login} (ID: ${user.id})`)
+```
+
+### GitHub Device Flow API
+
+#### `startGitHubDeviceFlow(options)`
+
+Initiates the device authorization flow by requesting device and user codes.
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `clientId` | `string` | Yes | GitHub OAuth App client ID |
+| `scope` | `string` | No | OAuth scopes (default: `'user:email read:user'`) |
+| `fetch` | `typeof fetch` | No | Custom fetch implementation |
+
+Returns `GitHubDeviceAuthResponse` with `deviceCode`, `userCode`, `verificationUri`, `expiresIn`, and `interval`.
+
+#### `pollGitHubDeviceFlow(deviceCode, options)`
+
+Polls GitHub's token endpoint until user completes authorization.
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `clientId` | `string` | Yes | GitHub OAuth App client ID |
+| `interval` | `number` | No | Polling interval in seconds (default: 5) |
+| `expiresIn` | `number` | No | Expiration time in seconds (default: 900) |
+| `fetch` | `typeof fetch` | No | Custom fetch implementation |
+
+Returns `GitHubTokenResponse` with `accessToken`, `tokenType`, and `scope`.
+
+#### `getGitHubUser(accessToken, options?)`
+
+Fetches the authenticated user's profile from GitHub API.
+
+Returns `GitHubUser` with `id`, `login`, `email`, `name`, and `avatarUrl`.
+
+## duckdb-auth Binary
+
+The `duckdb-auth` binary wraps DuckDB with automatic OAuth token injection for authenticated HTTP requests.
+
+```bash
+# Run DuckDB with oauth.do authentication
+duckdb-auth mydata.db
+
+# Execute authenticated queries
+duckdb-auth -c "SELECT * FROM read_json('https://api.example.com/protected/data')"
+```
+
+**How it works:**
+
+1. Retrieves your OAuth token from `oauth.do token`
+2. Creates DuckDB HTTP secrets with your bearer token
+3. Launches DuckDB with authentication pre-configured
+
+If you're not logged in, it will automatically start the login flow before launching DuckDB.
+
+## React Components
+
+Pre-configured React components for authentication, wrapping WorkOS AuthKit widgets.
+
+```tsx
+import { OAuthDoProvider, useAuth, SignInButton, SignOutButton } from 'oauth.do/react'
+
+// Wrap your app with the provider
+function App({ children }) {
+  return (
+    <OAuthDoProvider>
+      {children}
+    </OAuthDoProvider>
+  )
+}
+
+// Use the auth hook
+function UserGreeting() {
+  const { user, isLoading } = useAuth()
+
+  if (isLoading) return <span>Loading...</span>
+  if (!user) return <SignInButton>Sign In</SignInButton>
+
+  return (
+    <div>
+      <span>Hello, {user.firstName}!</span>
+      <SignOutButton>Sign Out</SignOutButton>
+    </div>
+  )
+}
+```
+
+### React Widgets
+
+```tsx
+import { ApiKeys, UsersManagement, UserProfile, useAuth } from 'oauth.do/react'
+
+function SettingsPage() {
+  const { user, getAccessToken } = useAuth()
+  if (!user) return <p>Please sign in</p>
+
+  return (
+    <div>
+      <h2>Profile</h2>
+      <UserProfile authToken={getAccessToken} />
+
+      <h2>API Keys</h2>
+      <ApiKeys authToken={getAccessToken} />
+
+      <h2>Team Members</h2>
+      <UsersManagement authToken={getAccessToken} />
+    </div>
+  )
+}
+```
+
+## Hono Middleware
+
+Lightweight JWT authentication middleware for Cloudflare Workers and Hono.
+
+```typescript
+import { Hono } from 'hono'
+import { auth, requireAuth, apiKey } from 'oauth.do/hono'
+
+const app = new Hono()
+
+// Add auth to all routes (populates c.var.user if authenticated)
+app.use('*', auth())
+
+// Public route - auth is optional
+app.get('/api/public', (c) => {
+  const user = c.var.user
+  return c.json({ message: 'Hello', user: user?.email || 'anonymous' })
+})
+
+// Protected route - requires authentication
+app.use('/api/protected/*', requireAuth())
+
+app.get('/api/protected/data', (c) => {
+  return c.json({ secret: 'data', user: c.var.user })
+})
+
+// Role-based access
+app.use('/api/admin/*', requireAuth({ roles: ['admin'] }))
+
+// Permission-based access
+app.use('/api/billing/*', requireAuth({ permissions: ['billing:read', 'billing:write'] }))
+```
+
+### API Key Authentication
+
+```typescript
+import { apiKey, combined } from 'oauth.do/hono'
+
+// API key only
+app.use('/api/v1/*', apiKey({
+  verify: async (key, c) => {
+    const user = await verifyApiKeyInDatabase(key)
+    return user // Return AuthUser or null
+  }
+}))
+
+// Combined: JWT or API key
+app.use('/api/*', combined({
+  auth: { cookieName: 'session' },
+  apiKey: {
+    verify: async (key) => verifyApiKey(key)
+  }
+}))
+```
+
 ## Token Storage
 
 ```typescript
 import { createSecureStorage, KeychainTokenStorage } from 'oauth.do'
 
-// Auto-select best storage (keychain → secure file)
+// Auto-select best storage (keychain -> secure file)
 const storage = createSecureStorage()
 
 // Or use keychain directly
@@ -114,7 +350,7 @@ configure({
 
 ## Environment Variables
 
-- `DO_TOKEN` - Authentication token
+- `ORG_AI_TOKEN` - Authentication token
 - `OAUTH_API_URL` - API base URL (default: `https://apis.do`)
 - `OAUTH_CLIENT_ID` - OAuth client ID
 - `OAUTH_AUTHKIT_DOMAIN` - AuthKit domain (default: `login.oauth.do`)

package/bin/duckdb-auth

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+#
+# duckdb-auth - DuckDB with oauth.do authentication
+#
+# This wrapper script gets an OAuth token from oauth.do and
+# configures DuckDB to use it for authenticated HTTP requests.
+#
+# Usage:
+#   duckdb-auth [duckdb-args...]
+#   duckdb-auth mydata.db
+#   duckdb-auth -c "SELECT * FROM read_json('https://api.example.com/data')"
+#
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Check if oauth.do CLI is available
+if ! command -v oauth.do &> /dev/null; then
+    echo -e "${RED}Error: oauth.do CLI not found${NC}"
+    echo "Install with: npm install -g oauth.do"
+    exit 1
+fi
+
+# Check if duckdb is available
+if ! command -v duckdb &> /dev/null; then
+    echo -e "${RED}Error: duckdb CLI not found${NC}"
+    echo "Install from: https://duckdb.org/docs/installation/"
+    exit 1
+fi
+
+# Get OAuth token
+TOKEN=$(oauth.do token 2>/dev/null || echo "")
+
+if [ -z "$TOKEN" ]; then
+    echo -e "${YELLOW}Not logged in to oauth.do${NC}"
+    echo "Starting login flow..."
+    oauth.do login
+    TOKEN=$(oauth.do token 2>/dev/null || echo "")
+
+    if [ -z "$TOKEN" ]; then
+        echo -e "${RED}Failed to get token after login${NC}"
+        exit 1
+    fi
+fi
+
+echo -e "${GREEN}✓ Authenticated with oauth.do${NC}"
+
+# Create init SQL to set up secrets
+INIT_SQL="
+-- oauth.do authentication setup
+CREATE OR REPLACE SECRET oauth_do (
+    TYPE http,
+    BEARER_TOKEN '${TOKEN}'
+);
+
+-- Also create with extra headers for flexibility
+CREATE OR REPLACE SECRET oauth_do_headers (
+    TYPE HTTP,
+    EXTRA_HTTP_HEADERS MAP {
+        'Authorization': 'Bearer ${TOKEN}'
+    }
+);
+"
+
+# Run DuckDB with init command
+exec duckdb -cmd "$INIT_SQL" "$@"