@terminal3/t3n-sdk 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 T3n Team
+
+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.OIDC.md

@@ -0,0 +1,216 @@
+# OIDC Authentication Guide
+
+## Quick Start
+
+### 1. Setup Google OAuth Client
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project or select existing one
+3. Enable "Google Sign-In" API
+4. Go to **Credentials** → **Create Credentials** → **OAuth 2.0 Client ID**
+5. Application type: **Web application**
+6. Authorized JavaScript origins:
+   ```
+   http://localhost:8081
+   ```
+   (Port 8081 is what the demo uses)
+7. Copy your **Client ID**
+
+### 2. Update the HTML File
+
+Edit `oidc-login.html` and replace:
+
+```html
+data-client_id="PUT_YOUR_WEB_CLIENT_ID_HERE"
+```
+
+With your actual Client ID:
+
+```html
+data-client_id="YOUR_ACTUAL_CLIENT_ID.apps.googleusercontent.com"
+```
+
+### 3. Get ID Token
+
+#### Option A: Using the Helper Script (Recommended)
+
+```bash
+npx tsx get-oidc-token.ts
+```
+
+This will:
+1. Open the browser with Google Sign-In
+2. Display your ID token after sign-in
+3. Provide code examples
+
+#### Option B: Manual (No CLI needed)
+
+1. Open `oidc-login.html` in your browser:
+   ```bash
+   open oidc-login.html  # macOS
+   # or
+   xdg-open oidc-login.html  # Linux
+   # or just double-click the file
+   ```
+
+2. Click "Sign in with Google"
+
+3. Copy the ID token displayed
+
+4. Use it in your code:
+   ```typescript
+   const authenticator = {
+     provider: "google",
+     id_token: "eyJhbGciOiJS..." // Your copied token
+   };
+   
+   await client.performAuthentication(authenticator);
+   ```
+
+### 4. Use in Demo
+
+```typescript
+// In demo.ts
+import * as readline from 'readline';
+
+async function getOidcToken(): Promise<string> {
+  console.log('\n🔐 OIDC Authentication');
+  console.log('1. Open oidc-login.html in your browser');
+  console.log('2. Sign in with Google');
+  console.log('3. Copy the ID token\n');
+  
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  
+  return new Promise((resolve) => {
+    rl.question('Paste your ID token: ', (token) => {
+      rl.close();
+      resolve(token.trim());
+    });
+  });
+}
+
+// Usage
+const idToken = await getOidcToken();
+const authenticator = {
+  provider: "google",
+  id_token: idToken
+};
+
+await client.performAuthentication(authenticator);
+```
+
+## Supported Providers
+
+| Provider     | Status          | Setup Guide                                        |
+| ------------ | --------------- | -------------------------------------------------- |
+| **Google**   | ✅ Ready        | [Google OAuth Setup](https://developers.google.com/identity/sign-in/web/sign-in) |
+| **Microsoft** | ✅ Ready        | [Azure AD Setup](https://learn.microsoft.com/en-us/azure/active-directory/) |
+| **Apple**    | ✅ Ready        | [Sign in with Apple](https://developer.apple.com/sign-in-with-apple/) |
+| **GitHub**   | ✅ Ready        | [GitHub OAuth](https://docs.github.com/en/developers/apps/building-oauth-apps) |
+| **Facebook** | ✅ Ready        | [Facebook Login](https://developers.facebook.com/docs/facebook-login/) |
+
+## Architecture
+
+### Frontend-Driven PKCE Flow
+
+```
+┌─────────────┐         ┌──────────────┐         ┌─────────────┐
+│   Browser   │         │   T3n    │         │   Google    │
+│  (Popup)    │         │   Backend    │         │   OAuth     │
+└──────┬──────┘         └──────┬───────┘         └──────┬──────┘
+       │                       │                        │
+       │  1. Generate PKCE     │                        │
+       ├──────────────────────►│                        │
+       │  (code_verifier)      │                        │
+       │                       │                        │
+       │  2. Redirect to OAuth │                        │
+       ├───────────────────────┼───────────────────────►│
+       │  (with code_challenge)│                        │
+       │                       │                        │
+       │  3. User signs in     │                        │
+       │◄──────────────────────┼────────────────────────┤
+       │                       │                        │
+       │  4. Exchange code     │                        │
+       │  (with code_verifier) │                        │
+       ├───────────────────────┼───────────────────────►│
+       │                       │                        │
+       │  5. Receive ID token  │                        │
+       │◄──────────────────────┼────────────────────────┤
+       │                       │                        │
+       │  6. Send ID token     │                        │
+       ├──────────────────────►│                        │
+       │                       │                        │
+       │                       │  7. Verify token       │
+       │                       │  (fetch JWKS & validate)
+       │                       │                        │
+       │  8. Session created   │                        │
+       │◄──────────────────────┤                        │
+       │                       │                        │
+```
+
+### Key Benefits
+
+- ✅ **No Backend PKCE**: Frontend handles PKCE entirely
+- ✅ **Stateless Backend**: No session storage for PKCE
+- ✅ **Secure**: Backend independently verifies tokens
+- ✅ **Simple CLI**: Just paste the token, no complex flow
+- ✅ **Works Everywhere**: Browser handles OAuth, CLI gets result
+
+## Token Format
+
+The ID token is a JWT with three parts:
+
+```
+eyJhbGciOiJSUzI1NiIsImtpZCI6Ijc...  (header)
+.
+eyJpc3MiOiJodHRwczovL2FjY291bnR...  (payload)
+.
+SflKxwRJSMeKKF2QT4fwpMeJf36POk6...  (signature)
+```
+
+### Payload Example
+
+```json
+{
+  "iss": "https://accounts.google.com",
+  "sub": "1234567890",
+  "email": "user@example.com",
+  "email_verified": true,
+  "name": "John Doe",
+  "picture": "https://...",
+  "iat": 1700000000,
+  "exp": 1700003600
+}
+```
+
+## Security Notes
+
+1. **Token Expiration**: ID tokens are short-lived (typically 1 hour)
+2. **Verification**: Backend always verifies token signature with JWKS
+3. **Email Verified**: Backend checks `email_verified` claim
+4. **CSRF Protection**: State parameter prevents CSRF attacks
+5. **PKCE**: Code verifier prevents authorization code interception
+
+## Troubleshooting
+
+### Token Already Expired
+
+ID tokens expire quickly. If you get an error:
+1. Get a fresh token from the browser
+2. Use it immediately
+
+### Invalid Token Format
+
+Make sure you copied the entire token (it's quite long!). Should have 3 parts separated by dots.
+
+### Provider Not Found
+
+Make sure `provider` matches exactly: `"google"`, `"microsoft"`, `"apple"`, etc. (lowercase)
+
+### CORS Errors in Browser
+
+For production, add your domain to OAuth client's authorized origins in Google Cloud Console.
+