@auth-gate/core 0.1.0 → 0.4.0

package/README.md

@@ -0,0 +1,210 @@
+# @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
+});
+```
+
+## 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 |
+| `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/dist/index.cjs

@@ -301,17 +301,11 @@ var InvalidStateError = class extends AuthGateError {
 var AuthGateClient = class {
   /**
    * @param config - Client configuration. See {@link AuthGateConfig}.
-   * @throws {@link AuthGateError} if `sessionSecret` is shorter than 32 characters.
    */
   constructor(config) {
     this.encryptionKey = null;
     this.stateKey = null;
     var _a, _b, _c;
-    if (!config.sessionSecret || config.sessionSecret.length < 32) {
-      throw new AuthGateError(
-        "sessionSecret must be at least 32 characters long"
-      );
-    }
     this.config = __spreadProps(__spreadValues({}, config), {
       cookieName: (_a = config.cookieName) != null ? _a : DEFAULT_COOKIE_NAME,
       sessionMaxAge: (_b = config.sessionMaxAge) != null ? _b : SESSION_MAX_AGE,
@@ -321,8 +315,8 @@ var AuthGateClient = class {
   }
   async deriveKeys() {
     const [encKey, stKey] = await Promise.all([
-      deriveEncryptionKey(this.config.sessionSecret),
-      deriveStateKey(this.config.sessionSecret)
+      deriveEncryptionKey(this.config.apiKey),
+      deriveStateKey(this.config.apiKey)
     ]);
     this.encryptionKey = encKey;
     this.stateKey = stKey;

package/dist/index.d.cts

@@ -49,7 +49,6 @@ interface TokenVerifyResult {
  *   apiKey: process.env.AUTHGATE_API_KEY!,
  *   projectId: process.env.AUTHGATE_PROJECT_ID!,
  *   baseUrl: "https://authgate.dev",
- *   sessionSecret: process.env.SESSION_SECRET!, // min 32 chars
  * });
  * ```
  */
@@ -60,11 +59,6 @@ interface AuthGateConfig {
     projectId: string;
     /** Base URL of the AuthGate service (e.g. `"https://authgate.dev"`). */
     baseUrl: string;
-    /**
-     * Secret used to derive encryption keys for session cookies and OAuth state.
-     * Must be at least 32 characters. Use a cryptographically random string.
-     */
-    sessionSecret: string;
     /**
      * Name of the session cookie.
      * @defaultValue `"__authgate"`
@@ -180,7 +174,6 @@ interface BackupCodesResponse {
  *   apiKey: process.env.AUTHGATE_API_KEY!,
  *   projectId: process.env.AUTHGATE_PROJECT_ID!,
  *   baseUrl: "https://authgate.dev",
- *   sessionSecret: process.env.SESSION_SECRET!,
  * });
  * ```
  */
@@ -191,7 +184,6 @@ declare class AuthGateClient {
     private keysReady;
     /**
      * @param config - Client configuration. See {@link AuthGateConfig}.
-     * @throws {@link AuthGateError} if `sessionSecret` is shorter than 32 characters.
      */
     constructor(config: AuthGateConfig);
     private deriveKeys;

package/dist/index.d.ts

@@ -49,7 +49,6 @@ interface TokenVerifyResult {
  *   apiKey: process.env.AUTHGATE_API_KEY!,
  *   projectId: process.env.AUTHGATE_PROJECT_ID!,
  *   baseUrl: "https://authgate.dev",
- *   sessionSecret: process.env.SESSION_SECRET!, // min 32 chars
  * });
  * ```
  */
@@ -60,11 +59,6 @@ interface AuthGateConfig {
     projectId: string;
     /** Base URL of the AuthGate service (e.g. `"https://authgate.dev"`). */
     baseUrl: string;
-    /**
-     * Secret used to derive encryption keys for session cookies and OAuth state.
-     * Must be at least 32 characters. Use a cryptographically random string.
-     */
-    sessionSecret: string;
     /**
      * Name of the session cookie.
      * @defaultValue `"__authgate"`
@@ -180,7 +174,6 @@ interface BackupCodesResponse {
  *   apiKey: process.env.AUTHGATE_API_KEY!,
  *   projectId: process.env.AUTHGATE_PROJECT_ID!,
  *   baseUrl: "https://authgate.dev",
- *   sessionSecret: process.env.SESSION_SECRET!,
  * });
  * ```
  */
@@ -191,7 +184,6 @@ declare class AuthGateClient {
     private keysReady;
     /**
      * @param config - Client configuration. See {@link AuthGateConfig}.
-     * @throws {@link AuthGateError} if `sessionSecret` is shorter than 32 characters.
      */
     constructor(config: AuthGateConfig);
     private deriveKeys;

package/dist/index.mjs

@@ -267,17 +267,11 @@ var InvalidStateError = class extends AuthGateError {
 var AuthGateClient = class {
   /**
    * @param config - Client configuration. See {@link AuthGateConfig}.
-   * @throws {@link AuthGateError} if `sessionSecret` is shorter than 32 characters.
    */
   constructor(config) {
     this.encryptionKey = null;
     this.stateKey = null;
     var _a, _b, _c;
-    if (!config.sessionSecret || config.sessionSecret.length < 32) {
-      throw new AuthGateError(
-        "sessionSecret must be at least 32 characters long"
-      );
-    }
     this.config = __spreadProps(__spreadValues({}, config), {
       cookieName: (_a = config.cookieName) != null ? _a : DEFAULT_COOKIE_NAME,
       sessionMaxAge: (_b = config.sessionMaxAge) != null ? _b : SESSION_MAX_AGE,
@@ -287,8 +281,8 @@ var AuthGateClient = class {
   }
   async deriveKeys() {
     const [encKey, stKey] = await Promise.all([
-      deriveEncryptionKey(this.config.sessionSecret),
-      deriveStateKey(this.config.sessionSecret)
+      deriveEncryptionKey(this.config.apiKey),
+      deriveStateKey(this.config.apiKey)
     ]);
     this.encryptionKey = encKey;
     this.stateKey = stKey;

package/package.json

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