@auth-gate/core 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,212 @@
+# @auth-gate/core
+
+Core client library for [AuthGate](https://authgate.dev) — the OAuth proxy that handles provider configuration, token exchange, and user normalization so you don't have to.
+
+## Installation
+
+```bash
+npm install @auth-gate/core
+```
+
+## Setup
+
+```ts
+import { createAuthGateClient } from "@auth-gate/core";
+
+const client = createAuthGateClient({
+  apiKey: process.env.AUTHGATE_API_KEY!,
+  projectId: process.env.AUTHGATE_PROJECT_ID!,
+  baseUrl: "https://authgate.dev", // or your self-hosted instance
+  sessionSecret: process.env.SESSION_SECRET!, // min 32 characters
+});
+```
+
+## Features
+
+### OAuth Authentication
+
+Supports Google, GitHub, Discord, Azure (Microsoft), and Apple.
+
+```ts
+// Generate the authorization URL
+const url = client.getOAuthUrl("google", "https://yourapp.com/auth/callback");
+
+// After callback, verify the JWT token from AuthGate
+const result = await client.verifyToken(token);
+if (result.valid) {
+  console.log(result.user); // { id, email, name, picture, provider }
+}
+```
+
+### Session Encryption
+
+Sessions are encrypted with AES-256-GCM using keys derived via HKDF-SHA256.
+
+```ts
+// Encrypt a user into a session cookie value
+const cookieValue = await client.encryptSession(user);
+
+// Decrypt a session cookie back to a user
+const user = await client.decryptSession(cookieValue);
+
+// Get full payload with timestamps
+const payload = await client.decryptSessionPayload(cookieValue);
+// { user, iat, exp }
+```
+
+### CSRF / OAuth State
+
+```ts
+// Before redirect: create state + nonce
+const { state, nonce } = await client.createState();
+// Store nonce in a cookie, pass state in the OAuth URL
+
+// After callback: verify state against nonce
+const valid = await client.verifyState(state, nonce);
+```
+
+### Email Authentication
+
+```ts
+// Sign up
+await client.emailSignup({ email, password, name });
+
+// Sign in
+const result = await client.emailSignin({ email, password });
+
+// Verify email with OTP code
+await client.emailVerifyCode({ email, code });
+
+// Password reset
+await client.emailForgotPassword({ email });
+await client.emailResetPassword({ token, password });
+
+// Magic link
+await client.magicLinkSend({ email, callbackUrl });
+```
+
+### SMS Authentication
+
+```ts
+// Send verification code
+await client.smsSendCode({ phone }); // E.164 format: +15551234567
+
+// Verify code
+const result = await client.smsVerifyCode({ phone, code });
+```
+
+### Multi-Factor Authentication (MFA)
+
+```ts
+// TOTP setup
+const setup = await client.mfaTotpSetup(jwt);
+// { secret, qr_code, uri }
+
+// Verify TOTP setup
+await client.mfaTotpVerifySetup(jwt, { code });
+
+// Complete MFA challenge during sign-in
+const result = await client.mfaVerify({ mfa_challenge, code, method: "totp" });
+
+// SMS-based MFA
+await client.mfaSmsSendCode({ mfa_challenge });
+await client.mfaVerify({ mfa_challenge, code, method: "sms" });
+
+// Backup codes
+const codes = await client.mfaBackupCodesGenerate(jwt);
+```
+
+### Session Management
+
+```ts
+// Refresh an expired token
+const result = await client.refreshToken(refreshToken);
+
+// Revoke a session
+await client.revokeSession(refreshToken);
+```
+
+### Cookie Helpers
+
+```ts
+client.cookieName;              // "__authgate"
+client.nonceCookieName;         // "__authgate_nonce"
+client.refreshTokenCookieName;  // "__authgate_refresh"
+client.sessionMaxAge;           // 604800 (7 days)
+
+client.getSessionCookieOptions();
+// { httpOnly: true, secure: true, sameSite: "lax", maxAge: 604800, path: "/" }
+
+client.getNonceCookieOptions();
+// { httpOnly: true, secure: true, sameSite: "lax", maxAge: 600, path: "/" }
+```
+
+## Configuration
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `apiKey` | `string` | Yes | Your AuthGate API key |
+| `projectId` | `string` | Yes | Your AuthGate project ID |
+| `baseUrl` | `string` | Yes | AuthGate instance URL |
+| `sessionSecret` | `string` | Yes | Encryption secret (min 32 chars) |
+| `cookieName` | `string` | No | Session cookie name (default: `__authgate`) |
+| `sessionMaxAge` | `number` | No | Session TTL in seconds (default: `604800` / 7 days) |
+| `callbackPath` | `string` | No | OAuth callback path (default: `/api/auth/callback`) |
+
+## Types
+
+```ts
+import type {
+  AuthGateUser,
+  AuthGateConfig,
+  OAuthProvider,
+  TokenVerifyResult,
+  SessionPayload,
+  CookieOptions,
+  MfaChallengeResponse,
+  MfaStatus,
+  TotpSetupResponse,
+  BackupCodesResponse,
+} from "@auth-gate/core";
+```
+
+### `AuthGateUser`
+
+```ts
+interface AuthGateUser {
+  id: string;
+  email: string;
+  phone?: string;
+  name?: string;
+  picture?: string;
+  provider: string;
+}
+```
+
+### `OAuthProvider`
+
+```ts
+type OAuthProvider = "google" | "github" | "discord" | "azure" | "apple";
+```
+
+## Error Handling
+
+```ts
+import {
+  AuthGateError,
+  TokenVerificationError,
+  SessionDecryptionError,
+  InvalidStateError,
+} from "@auth-gate/core";
+```
+
+## Framework SDKs
+
+For framework-specific integrations with built-in route handlers, session helpers, and middleware:
+
+- **Next.js** — [`@auth-gate/nextjs`](https://www.npmjs.com/package/@auth-gate/nextjs)
+- **React + Hono** — [`@auth-gate/react`](https://www.npmjs.com/package/@auth-gate/react)
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@auth-gate/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "exports": {
     ".": {