@auth-gate/core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,569 @@
+/**
+ * The authenticated user object returned after successful authentication.
+ *
+ * This is the primary data structure stored in the encrypted session cookie
+ * and returned by session helpers like `getSession()`.
+ *
+ * Fields are nullable because different auth providers populate different
+ * fields — e.g. SMS auth only provides `phone`, OAuth provides `email`
+ * and `picture`, etc.
+ */
+interface AuthGateUser {
+    /** Unique user identifier assigned by AuthGate. */
+    id: string;
+    /** User's email address. Present for email/OAuth flows, `null` for SMS-only users. */
+    email: string | null;
+    /** User's phone number in E.164 format. Present for SMS flows, `null` otherwise. */
+    phone: string | null;
+    /** User's display name from the OAuth provider or signup form. */
+    name: string | null;
+    /** URL to the user's profile picture from the OAuth provider. */
+    picture: string | null;
+    /** The authentication provider used (e.g. `"google"`, `"github"`, `"email"`, `"sms"`). */
+    provider: string;
+}
+/**
+ * Result of verifying a JWT token against the AuthGate API.
+ *
+ * When `valid` is `true`, the `user` and `expiresAt` fields are populated.
+ * When `valid` is `false`, `error` describes why verification failed.
+ */
+interface TokenVerifyResult {
+    /** Whether the token is valid and not expired. */
+    valid: boolean;
+    /** The authenticated user, present when `valid` is `true`. */
+    user?: AuthGateUser;
+    /** ISO 8601 timestamp when the token expires, present when `valid` is `true`. */
+    expiresAt?: string;
+    /** Human-readable error message, present when `valid` is `false`. */
+    error?: string;
+}
+/**
+ * Configuration for initializing an {@link AuthGateClient}.
+ *
+ * @example
+ * ```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",
+ *   sessionSecret: process.env.SESSION_SECRET!, // min 32 chars
+ * });
+ * ```
+ */
+interface AuthGateConfig {
+    /** Server-side API key for your AuthGate project. Found in the dashboard under API Keys. */
+    apiKey: string;
+    /** The project ID from your AuthGate dashboard. */
+    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"`
+     */
+    cookieName?: string;
+    /**
+     * Session lifetime in seconds. Controls how long the encrypted session cookie
+     * and refresh token remain valid.
+     * @defaultValue `604800` (7 days)
+     */
+    sessionMaxAge?: number;
+    /**
+     * Path where the OAuth callback handler is mounted.
+     * @defaultValue `"/api/auth/callback"`
+     */
+    callbackPath?: string;
+}
+/**
+ * Internal payload structure stored inside the encrypted session cookie.
+ * Contains the user data plus issued-at and expiration timestamps.
+ */
+interface SessionPayload {
+    /** The authenticated user data. */
+    user: AuthGateUser;
+    /** Unix timestamp (seconds) when the session was created. */
+    iat: number;
+    /** Unix timestamp (seconds) when the session expires. */
+    exp: number;
+}
+/**
+ * Options for configuring HTTP cookies set by AuthGate.
+ * Maps directly to standard `Set-Cookie` attributes.
+ */
+interface CookieOptions {
+    /** Prevents client-side JavaScript from reading the cookie. */
+    httpOnly: boolean;
+    /** Only send the cookie over HTTPS connections. */
+    secure: boolean;
+    /** Controls when the cookie is sent with cross-site requests. */
+    sameSite: "lax" | "strict" | "none";
+    /** Cookie lifetime in seconds. */
+    maxAge: number;
+    /** URL path the cookie is valid for. */
+    path: string;
+}
+/**
+ * Supported OAuth provider identifiers.
+ *
+ * Pass one of these to {@link AuthGateClient.getOAuthUrl} to initiate an OAuth flow.
+ */
+type OAuthProvider = "google" | "github" | "discord" | "azure" | "apple";
+/**
+ * Response returned when MFA verification is required during sign-in.
+ *
+ * The client should redirect the user to an MFA verification page,
+ * passing the `mfa_challenge` token and available `mfa_methods`.
+ */
+interface MfaChallengeResponse {
+    /** Always `true` — indicates MFA is required to complete authentication. */
+    mfa_required: true;
+    /** Opaque challenge token to pass to the MFA verify endpoint. */
+    mfa_challenge: string;
+    /** List of MFA methods the user has enrolled (e.g. `["totp", "sms"]`). */
+    mfa_methods: string[];
+}
+/**
+ * Current MFA enrollment status for a user.
+ * Returned by the `/api/proxy/mfa/status` endpoint.
+ */
+interface MfaStatus {
+    /** Whether the user has any MFA method enrolled. */
+    enrolled: boolean;
+    /** List of enrolled MFA methods (e.g. `["totp"]`, `["sms", "totp"]`). */
+    methods: string[];
+    /** Whether MFA is required by the project's policy. */
+    required: boolean;
+}
+/**
+ * Response from TOTP setup containing the secret and QR code.
+ * Returned by the `/api/proxy/mfa/totp/setup` endpoint.
+ */
+interface TotpSetupResponse {
+    /** Base32-encoded TOTP secret for manual entry. */
+    secret: string;
+    /** Data URL of the QR code image (PNG) for scanning with an authenticator app. */
+    qr_code: string;
+    /** `otpauth://` URI for the TOTP secret. */
+    uri: string;
+}
+/**
+ * Response from generating new MFA backup codes.
+ * Returned by the `/api/proxy/mfa/backup-codes/generate` endpoint.
+ *
+ * Each code can only be used once. Generating new codes invalidates all previous ones.
+ */
+interface BackupCodesResponse {
+    /** Array of single-use backup codes. Store these securely — they are shown only once. */
+    codes: string[];
+}
+
+/**
+ * Core client for interacting with the AuthGate authentication proxy.
+ *
+ * Handles token verification, session cookie encryption/decryption,
+ * OAuth state management, and all proxy API calls (email, SMS, MFA).
+ *
+ * Use {@link createAuthGateClient} for a convenient factory function,
+ * or instantiate directly with `new AuthGateClient(config)`.
+ *
+ * @example
+ * ```ts
+ * const client = new AuthGateClient({
+ *   apiKey: process.env.AUTHGATE_API_KEY!,
+ *   projectId: process.env.AUTHGATE_PROJECT_ID!,
+ *   baseUrl: "https://authgate.dev",
+ *   sessionSecret: process.env.SESSION_SECRET!,
+ * });
+ * ```
+ */
+declare class AuthGateClient {
+    private readonly config;
+    private encryptionKey;
+    private stateKey;
+    private keysReady;
+    /**
+     * @param config - Client configuration. See {@link AuthGateConfig}.
+     * @throws {@link AuthGateError} if `sessionSecret` is shorter than 32 characters.
+     */
+    constructor(config: AuthGateConfig);
+    private deriveKeys;
+    private getEncryptionKey;
+    private getStateKey;
+    /**
+     * Verify a JWT token against the AuthGate API.
+     *
+     * Makes a server-side `POST /api/v1/token/verify` call using your API key.
+     * Times out after 5 seconds.
+     *
+     * @param token - The JWT token string from the OAuth callback or email/SMS flow.
+     * @returns A {@link TokenVerifyResult} with the user data if valid.
+     * @throws {@link TokenVerificationError} if the request times out.
+     */
+    verifyToken(token: string): Promise<TokenVerifyResult>;
+    /**
+     * Encrypt user data into a session cookie value.
+     *
+     * Uses AES-256-GCM with a key derived from your session secret.
+     * The returned string is safe to store in an httpOnly cookie.
+     *
+     * @param user - The authenticated user to store.
+     * @returns Base64url-encoded encrypted session string.
+     */
+    encryptSession(user: AuthGateUser): Promise<string>;
+    /**
+     * Decrypt a session cookie and return the user if the session is valid.
+     *
+     * Returns `null` if the cookie is expired, tampered with, or encrypted
+     * with a different secret. All failure modes return `null` to prevent
+     * oracle attacks.
+     *
+     * @param cookieValue - The encrypted cookie string.
+     * @returns The user, or `null` if the session is invalid.
+     */
+    decryptSession(cookieValue: string): Promise<AuthGateUser | null>;
+    /**
+     * Decrypt a session cookie and return the full payload (user + timestamps).
+     *
+     * Used internally by middleware to check `iat` for session revalidation.
+     *
+     * @param cookieValue - The encrypted cookie string.
+     * @returns The full session payload, or `null` if invalid.
+     * @internal
+     */
+    decryptSessionPayload(cookieValue: string): Promise<SessionPayload | null>;
+    /**
+     * Create a signed OAuth state parameter and nonce for CSRF protection.
+     *
+     * Store the `nonce` in a short-lived httpOnly cookie and pass `state`
+     * as a query parameter in the OAuth authorization URL.
+     *
+     * @returns `{ state, nonce }` — the state string and its corresponding nonce.
+     */
+    createState(): Promise<{
+        state: string;
+        nonce: string;
+    }>;
+    /**
+     * Verify an OAuth state parameter returned in the callback.
+     *
+     * @param state - The `state` query parameter from the callback.
+     * @param nonce - The nonce from the httpOnly cookie.
+     * @returns `true` if the state is valid and not expired.
+     */
+    verifyState(state: string, nonce: string): Promise<boolean>;
+    /**
+     * Build the OAuth authorization URL for a given provider.
+     *
+     * @param provider - The OAuth provider (e.g. `"google"`, `"github"`).
+     * @param callbackUrl - Your app's callback URL where the user is redirected after auth.
+     * @param options - Optional parameters.
+     * @param options.linkTo - An existing user ID to link this OAuth account to.
+     * @returns The full authorization URL to redirect the user to.
+     * @throws {@link AuthGateError} if the provider is not in {@link SUPPORTED_PROVIDERS}.
+     */
+    getOAuthUrl(provider: OAuthProvider, callbackUrl: string, options?: {
+        linkTo?: string;
+    }): string;
+    /**
+     * Register a new user with email and password.
+     *
+     * @param data - Signup data including email, password, optional name, and callback URL.
+     * @returns The raw `Response` from the AuthGate proxy.
+     */
+    emailSignup(data: {
+        email: string;
+        password: string;
+        name?: string;
+        callbackUrl: string;
+    }): Promise<Response>;
+    /**
+     * Sign in an existing user with email and password.
+     *
+     * The response may include `mfa_required: true` if the user has MFA enabled,
+     * in which case you should redirect to an MFA verification page.
+     *
+     * @param data - Sign-in data including email, password, and callback URL.
+     * @returns The raw `Response` from the AuthGate proxy.
+     */
+    emailSignin(data: {
+        email: string;
+        password: string;
+        callbackUrl: string;
+    }): Promise<Response>;
+    /**
+     * Send a password reset email to the user.
+     *
+     * @param data - The user's email and the URL to redirect to after clicking the reset link.
+     * @returns The raw `Response` from the AuthGate proxy.
+     */
+    emailForgotPassword(data: {
+        email: string;
+        callbackUrl: string;
+    }): Promise<Response>;
+    /**
+     * Confirm a password reset with the token from the reset email.
+     *
+     * @param data - The reset token and the new password.
+     * @returns The raw `Response` from the AuthGate proxy.
+     */
+    emailResetPassword(data: {
+        token: string;
+        password: string;
+    }): Promise<Response>;
+    /**
+     * Send a magic link email for passwordless authentication.
+     *
+     * @param data - The user's email and callback URL.
+     * @returns The raw `Response` from the AuthGate proxy.
+     */
+    magicLinkSend(data: {
+        email: string;
+        callbackUrl: string;
+    }): Promise<Response>;
+    /**
+     * Verify an email address using a one-time code.
+     *
+     * @param data - The user's email and the verification code.
+     * @returns The raw `Response` from the AuthGate proxy.
+     */
+    emailVerifyCode(data: {
+        email: string;
+        code: string;
+    }): Promise<Response>;
+    /**
+     * Send an SMS verification code to the user's phone number.
+     *
+     * @param data - The phone number (E.164 format) and callback URL.
+     * @returns The raw `Response` from the AuthGate proxy.
+     */
+    smsSendCode(data: {
+        phone: string;
+        callbackUrl: string;
+    }): Promise<Response>;
+    /**
+     * Verify an SMS code and authenticate the user.
+     *
+     * @param data - The phone number, verification code, and callback URL.
+     * @returns The raw `Response` from the AuthGate proxy.
+     */
+    smsVerifyCode(data: {
+        phone: string;
+        code: string;
+        callbackUrl: string;
+    }): Promise<Response>;
+    /**
+     * Exchange a refresh token for a new JWT.
+     *
+     * Refresh tokens are single-use — each call returns a new JWT and
+     * invalidates the previous refresh token (rotation).
+     *
+     * @param refreshToken - The opaque refresh token.
+     * @returns A new JWT and its `expires_in` (seconds), or `null` if the refresh token is invalid.
+     */
+    refreshToken(refreshToken: string): Promise<{
+        token: string;
+        expires_in: number;
+    } | null>;
+    /**
+     * Revoke a session by its refresh token.
+     *
+     * After revocation, the refresh token can no longer be used to obtain
+     * new JWTs. The user will need to re-authenticate.
+     *
+     * @param refreshToken - The opaque refresh token to revoke.
+     * @returns `true` if the session was revoked, `false` on failure.
+     */
+    revokeSession(refreshToken: string): Promise<boolean>;
+    /**
+     * Verify an MFA code to complete authentication.
+     *
+     * Called after a sign-in response includes `mfa_required: true`.
+     *
+     * @param data - The MFA challenge token, verification code, and method.
+     * @returns The raw `Response` — includes a JWT on success.
+     */
+    mfaVerify(data: {
+        challenge: string;
+        code: string;
+        method: "totp" | "sms" | "backup_code";
+    }): Promise<Response>;
+    /**
+     * Begin TOTP (authenticator app) setup for the authenticated user.
+     *
+     * Requires a valid JWT in the `Authorization: Bearer` header.
+     *
+     * @param token - The user's current JWT.
+     * @returns The raw `Response` with TOTP secret, QR code, and URI.
+     */
+    mfaTotpSetup(token: string): Promise<Response>;
+    /**
+     * Confirm TOTP setup by verifying a code from the authenticator app.
+     *
+     * @param token - The user's current JWT.
+     * @param code - The 6-digit TOTP code from the authenticator app.
+     * @returns The raw `Response` — confirms enrollment on success.
+     */
+    mfaTotpVerifySetup(token: string, code: string): Promise<Response>;
+    /**
+     * Disable TOTP for the authenticated user.
+     *
+     * @param token - The user's current JWT.
+     * @param code - A valid TOTP code to confirm the action.
+     * @returns The raw `Response`.
+     */
+    mfaTotpDisable(token: string, code: string): Promise<Response>;
+    /**
+     * Enable SMS-based MFA for the authenticated user.
+     *
+     * Uses the phone number already associated with the user's account.
+     *
+     * @param token - The user's current JWT.
+     * @returns The raw `Response`.
+     */
+    mfaSmsEnable(token: string): Promise<Response>;
+    /**
+     * Disable SMS-based MFA for the authenticated user.
+     *
+     * @param token - The user's current JWT.
+     * @returns The raw `Response`.
+     */
+    mfaSmsDisable(token: string): Promise<Response>;
+    /**
+     * Generate a new set of single-use MFA backup codes.
+     *
+     * Generating new codes invalidates all previously issued backup codes.
+     *
+     * @param token - The user's current JWT.
+     * @returns The raw `Response` with an array of backup codes.
+     */
+    mfaBackupCodesGenerate(token: string): Promise<Response>;
+    /**
+     * Get the current MFA enrollment status for the authenticated user.
+     *
+     * @param token - The user's current JWT.
+     * @returns The raw `Response` with {@link MfaStatus} data.
+     */
+    mfaStatus(token: string): Promise<Response>;
+    /**
+     * Send an SMS code for MFA verification during the challenge flow.
+     *
+     * @param challenge - The MFA challenge token from the sign-in response.
+     * @returns The raw `Response`.
+     */
+    mfaSmsSendCode(challenge: string): Promise<Response>;
+    /** The name of the session cookie (default: `"__authgate"`). */
+    get cookieName(): string;
+    /** The name of the OAuth nonce cookie (`"__authgate_nonce"`). */
+    get nonceCookieName(): string;
+    /** The name of the refresh token cookie (`"__authgate_refresh"`). */
+    get refreshTokenCookieName(): string;
+    /** The callback path where OAuth redirects are handled (default: `"/api/auth/callback"`). */
+    get callbackPath(): string;
+    /** The AuthGate project ID. */
+    get projectId(): string;
+    /** The AuthGate service base URL. */
+    get baseUrl(): string;
+    /** Session lifetime in seconds. */
+    get sessionMaxAge(): number;
+    /**
+     * Get cookie options for the session cookie.
+     *
+     * Returns `secure: true` in production, `httpOnly: true` always.
+     */
+    getSessionCookieOptions(): CookieOptions;
+    /**
+     * Get cookie options for the OAuth nonce cookie.
+     *
+     * Short-lived (10 minutes) to match the state TTL.
+     */
+    getNonceCookieOptions(): CookieOptions;
+}
+/**
+ * Create an {@link AuthGateClient} instance.
+ *
+ * Convenience factory — equivalent to `new AuthGateClient(config)`.
+ *
+ * @param config - Client configuration. See {@link AuthGateConfig}.
+ * @returns A configured {@link AuthGateClient}.
+ */
+declare function createAuthGateClient(config: AuthGateConfig): AuthGateClient;
+
+/** Default name for the encrypted session cookie. */
+declare const DEFAULT_COOKIE_NAME = "__authgate";
+/** Cookie name used to store the OAuth CSRF nonce during the authorization flow. */
+declare const NONCE_COOKIE_NAME = "__authgate_nonce";
+/** Cookie name used to store the opaque refresh token. */
+declare const REFRESH_TOKEN_COOKIE_NAME = "__authgate_refresh";
+/**
+ * Default session lifetime in seconds (7 days).
+ *
+ * Can be overridden per-client via {@link AuthGateConfig.sessionMaxAge}
+ * or per-project in the AuthGate dashboard under Settings > Session Duration.
+ */
+declare const SESSION_MAX_AGE = 604800;
+/** Maximum age of an OAuth state parameter before it is considered expired (10 minutes). */
+declare const STATE_TTL_MS = 600000;
+/**
+ * List of OAuth providers supported by AuthGate.
+ *
+ * Configure provider credentials in the AuthGate dashboard under Providers.
+ */
+declare const SUPPORTED_PROVIDERS: OAuthProvider[];
+
+/**
+ * Base error class for all AuthGate errors.
+ *
+ * All errors thrown by the `@auth-gate/*` packages extend this class,
+ * so you can catch `AuthGateError` to handle any AuthGate-specific failure.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.verifyToken(token);
+ * } catch (err) {
+ *   if (err instanceof AuthGateError) {
+ *     console.error("AuthGate error:", err.message);
+ *   }
+ * }
+ * ```
+ */
+declare class AuthGateError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when JWT token verification fails or times out.
+ *
+ * This can occur when the token is malformed, expired, or the
+ * AuthGate API is unreachable within the 5-second timeout.
+ */
+declare class TokenVerificationError extends AuthGateError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when an encrypted session cookie cannot be decrypted.
+ *
+ * Common causes: the session secret was rotated, the cookie was
+ * tampered with, or the cookie format version is unsupported.
+ */
+declare class SessionDecryptionError extends AuthGateError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when OAuth state verification fails.
+ *
+ * This indicates a potential CSRF attack, an expired state parameter
+ * (older than 10 minutes), or a nonce mismatch.
+ */
+declare class InvalidStateError extends AuthGateError {
+    constructor(message?: string);
+}
+
+export { AuthGateClient, type AuthGateConfig, AuthGateError, type AuthGateUser, type BackupCodesResponse, type CookieOptions, DEFAULT_COOKIE_NAME, InvalidStateError, type MfaChallengeResponse, type MfaStatus, NONCE_COOKIE_NAME, type OAuthProvider, REFRESH_TOKEN_COOKIE_NAME, SESSION_MAX_AGE, STATE_TTL_MS, SUPPORTED_PROVIDERS, SessionDecryptionError, type SessionPayload, TokenVerificationError, type TokenVerifyResult, type TotpSetupResponse, createAuthGateClient };