@reauth-dev/sdk 0.1.0

package/dist/server.mjs

@@ -0,0 +1,356 @@
+// src/server.ts
+import { hkdf } from "crypto";
+import * as jose from "jose";
+async function deriveJwtSecret(apiKey, domainId) {
+  const salt = Buffer.from(domainId.replace(/-/g, ""), "hex");
+  const info = Buffer.from("reauth-jwt-v1");
+  return new Promise((resolve, reject) => {
+    hkdf("sha256", apiKey, salt, info, 32, (err, derivedKey) => {
+      if (err) reject(err);
+      else resolve(Buffer.from(derivedKey).toString("hex"));
+    });
+  });
+}
+function transformSubscription(sub) {
+  return {
+    status: sub.status,
+    planCode: sub.plan_code,
+    planName: sub.plan_name,
+    currentPeriodEnd: sub.current_period_end,
+    cancelAtPeriodEnd: sub.cancel_at_period_end,
+    trialEndsAt: sub.trial_ends_at
+  };
+}
+function parseCookies(cookieHeader) {
+  const cookies = {};
+  for (const cookie of cookieHeader.split(";")) {
+    const [key, ...valueParts] = cookie.trim().split("=");
+    if (key) {
+      try {
+        cookies[key] = decodeURIComponent(valueParts.join("="));
+      } catch {
+        cookies[key] = valueParts.join("=");
+      }
+    }
+  }
+  return cookies;
+}
+function createServerClient(config) {
+  const { domain, apiKey } = config;
+  if (!apiKey) {
+    throw new Error(
+      "apiKey is required for createServerClient. Get one from the Reauth dashboard."
+    );
+  }
+  const developerBaseUrl = `https://reauth.${domain}/api/developer`;
+  return {
+    /**
+     * Verify a JWT token locally using HKDF-derived secret.
+     * No network call required - fast and reliable.
+     *
+     * The domain_id is extracted from the token claims automatically.
+     *
+     * @param token - The JWT token to verify
+     * @returns AuthResult with user info from claims
+     *
+     * @example
+     * ```typescript
+     * const result = await reauth.verifyToken(token);
+     * if (result.valid && result.user) {
+     *   console.log('User ID:', result.user.id);
+     *   console.log('Roles:', result.user.roles);
+     *   console.log('Subscription:', result.user.subscription);
+     * }
+     * ```
+     */
+    async verifyToken(token) {
+      try {
+        const unverified = jose.decodeJwt(token);
+        const domainId = unverified.domain_id;
+        const unverifiedDomain = unverified.domain;
+        if (!domainId) {
+          return { valid: false, user: null, claims: null, error: "Missing domain_id in token" };
+        }
+        if (unverifiedDomain !== domain) {
+          return { valid: false, user: null, claims: null, error: "Domain mismatch" };
+        }
+        const secret = await deriveJwtSecret(apiKey, domainId);
+        const { payload } = await jose.jwtVerify(
+          token,
+          new TextEncoder().encode(secret),
+          {
+            algorithms: ["HS256"],
+            clockTolerance: 60
+            // 60 seconds clock skew tolerance
+          }
+        );
+        const claims = payload;
+        if (claims.domain !== domain) {
+          return { valid: false, user: null, claims: null, error: "Domain mismatch" };
+        }
+        return {
+          valid: true,
+          user: {
+            id: claims.sub,
+            roles: claims.roles,
+            subscription: transformSubscription(claims.subscription)
+          },
+          claims
+        };
+      } catch (err) {
+        const error = err instanceof Error ? err.message : "Unknown error";
+        return { valid: false, user: null, claims: null, error };
+      }
+    },
+    /**
+     * Extract a token from a request object.
+     * Tries Authorization: Bearer header first, then falls back to cookies.
+     *
+     * @param request - Object with headers (authorization and/or cookie)
+     * @returns The token string or null if not found
+     *
+     * @example
+     * ```typescript
+     * const token = reauth.extractToken({
+     *   headers: {
+     *     authorization: req.headers.authorization,
+     *     cookie: req.headers.cookie,
+     *   },
+     * });
+     * ```
+     */
+    extractToken(request) {
+      const authHeader = request.headers?.authorization;
+      if (authHeader?.startsWith("Bearer ")) {
+        return authHeader.slice(7);
+      }
+      const cookieHeader = request.headers?.cookie;
+      if (cookieHeader) {
+        const cookies = parseCookies(cookieHeader);
+        if (cookies["end_user_access_token"]) {
+          return cookies["end_user_access_token"];
+        }
+      }
+      return null;
+    },
+    /**
+     * Authenticate a request by extracting and verifying the token.
+     * This is a convenience method combining extractToken and verifyToken.
+     *
+     * @param request - Object with headers (authorization and/or cookie)
+     * @returns AuthResult with user info from claims
+     *
+     * @example
+     * ```typescript
+     * // Express/Node.js
+     * async function authMiddleware(req, res, next) {
+     *   const result = await reauth.authenticate({
+     *     headers: {
+     *       authorization: req.headers.authorization,
+     *       cookie: req.headers.cookie,
+     *     },
+     *   });
+     *
+     *   if (!result.valid || !result.user) {
+     *     res.status(401).json({ error: result.error || 'Unauthorized' });
+     *     return;
+     *   }
+     *
+     *   req.user = result.user;
+     *   next();
+     * }
+     *
+     * // Next.js App Router
+     * export async function GET(request: NextRequest) {
+     *   const result = await reauth.authenticate({
+     *     headers: {
+     *       authorization: request.headers.get('authorization') ?? undefined,
+     *       cookie: request.headers.get('cookie') ?? undefined,
+     *     },
+     *   });
+     *
+     *   if (!result.valid) {
+     *     return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+     *   }
+     *
+     *   return NextResponse.json({ user: result.user });
+     * }
+     * ```
+     */
+    async authenticate(request) {
+      const token = this.extractToken(request);
+      if (!token) {
+        return { valid: false, user: null, claims: null, error: "No token provided" };
+      }
+      return this.verifyToken(token);
+    },
+    /**
+     * Get user details by ID from the backend.
+     * Use this when you need full user info like email, frozen status, etc.
+     * that isn't available in the JWT claims.
+     *
+     * @param userId - The user ID to fetch
+     * @returns UserDetails or null if not found
+     *
+     * @example
+     * ```typescript
+     * // After verifying token, fetch full user details if needed
+     * const result = await reauth.authenticate(request);
+     * if (result.valid && result.user) {
+     *   // If you need email or other details not in JWT
+     *   const details = await reauth.getUserById(result.user.id);
+     *   if (details) {
+     *     console.log('Email:', details.email);
+     *     console.log('Frozen:', details.isFrozen);
+     *   }
+     * }
+     * ```
+     */
+    async getUserById(userId) {
+      const res = await fetch(`${developerBaseUrl}/users/${userId}`, {
+        headers: {
+          Authorization: `Bearer ${apiKey}`
+        }
+      });
+      if (!res.ok) {
+        if (res.status === 401) {
+          throw new Error("Invalid API key");
+        }
+        if (res.status === 404) {
+          return null;
+        }
+        throw new Error(`Failed to get user: ${res.status}`);
+      }
+      const data = await res.json();
+      return {
+        id: data.id,
+        email: data.email,
+        roles: data.roles,
+        emailVerifiedAt: data.email_verified_at,
+        lastLoginAt: data.last_login_at,
+        isFrozen: data.is_frozen,
+        isWhitelisted: data.is_whitelisted,
+        createdAt: data.created_at
+      };
+    },
+    // ========================================================================
+    // Balance Methods
+    // ========================================================================
+    /**
+     * Get a user's current balance.
+     *
+     * @param userId - The user ID to check
+     * @returns Object with the current balance
+     */
+    async getBalance(userId) {
+      const res = await fetch(`${developerBaseUrl}/users/${userId}/balance`, {
+        headers: {
+          Authorization: `Bearer ${apiKey}`
+        }
+      });
+      if (!res.ok) {
+        if (res.status === 401) throw new Error("Invalid API key");
+        throw new Error(`Failed to get balance: ${res.status}`);
+      }
+      return res.json();
+    },
+    /**
+     * Charge (deduct) credits from a user's balance.
+     *
+     * @param userId - The user ID to charge
+     * @param opts - Charge options (amount, requestUuid for idempotency, optional note)
+     * @returns Object with the new balance after charge
+     * @throws Error with status 402 if insufficient balance, 400 if invalid amount
+     */
+    async charge(userId, opts) {
+      const res = await fetch(`${developerBaseUrl}/users/${userId}/charge`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${apiKey}`
+        },
+        body: JSON.stringify({
+          amount: opts.amount,
+          request_uuid: opts.requestUuid,
+          note: opts.note
+        })
+      });
+      if (!res.ok) {
+        if (res.status === 401) throw new Error("Invalid API key");
+        if (res.status === 402) throw new Error("Insufficient balance");
+        if (res.status === 400) throw new Error("Invalid amount");
+        throw new Error(`Failed to charge balance: ${res.status}`);
+      }
+      const data = await res.json();
+      return { newBalance: data.new_balance };
+    },
+    /**
+     * Deposit (add) credits to a user's balance.
+     *
+     * @param userId - The user ID to deposit to
+     * @param opts - Deposit options (amount, requestUuid for idempotency, optional note)
+     * @returns Object with the new balance after deposit
+     */
+    async deposit(userId, opts) {
+      const res = await fetch(`${developerBaseUrl}/users/${userId}/deposit`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${apiKey}`
+        },
+        body: JSON.stringify({
+          amount: opts.amount,
+          request_uuid: opts.requestUuid,
+          note: opts.note
+        })
+      });
+      if (!res.ok) {
+        if (res.status === 401) throw new Error("Invalid API key");
+        if (res.status === 400) throw new Error("Invalid amount");
+        throw new Error(`Failed to deposit balance: ${res.status}`);
+      }
+      const data = await res.json();
+      return { newBalance: data.new_balance };
+    },
+    /**
+     * Get a user's balance transaction history.
+     *
+     * @param userId - The user ID to get transactions for
+     * @param opts - Optional pagination (limit, offset)
+     * @returns Object with array of transactions (newest first)
+     */
+    async getTransactions(userId, opts) {
+      const params = new URLSearchParams();
+      if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
+      if (opts?.offset !== void 0) params.set("offset", String(opts.offset));
+      const qs = params.toString();
+      const res = await fetch(
+        `${developerBaseUrl}/users/${userId}/balance/transactions${qs ? `?${qs}` : ""}`,
+        {
+          headers: {
+            Authorization: `Bearer ${apiKey}`
+          }
+        }
+      );
+      if (!res.ok) {
+        if (res.status === 401) throw new Error("Invalid API key");
+        throw new Error(`Failed to get transactions: ${res.status}`);
+      }
+      const data = await res.json();
+      return {
+        transactions: data.transactions.map(
+          (t) => ({
+            id: t.id,
+            amountDelta: t.amount_delta,
+            reason: t.reason,
+            balanceAfter: t.balance_after,
+            createdAt: t.created_at
+          })
+        )
+      };
+    }
+  };
+}
+export {
+  createServerClient
+};

package/dist/types-D8oOYbeC.d.mts

@@ -0,0 +1,169 @@
+/** Response from GET /api/public/auth/session */
+type ReauthSession = {
+    valid: boolean;
+    end_user_id: string | null;
+    email: string | null;
+    roles: string[] | null;
+    waitlist_position: number | null;
+    error: string | null;
+    error_code: "ACCOUNT_SUSPENDED" | null;
+    /** Subscription information (if billing is configured) */
+    subscription?: {
+        status: string;
+        plan_code: string | null;
+        plan_name: string | null;
+        current_period_end: number | null;
+        cancel_at_period_end: boolean | null;
+        trial_ends_at: number | null;
+    };
+};
+/** Authenticated user object (basic) */
+type User = {
+    id: string;
+    email: string;
+    roles: string[];
+};
+/** Full user details (from Developer API) */
+type UserDetails = {
+    id: string;
+    email: string;
+    roles: string[];
+    emailVerifiedAt: string | null;
+    lastLoginAt: string | null;
+    isFrozen: boolean;
+    isWhitelisted: boolean;
+    createdAt: string | null;
+};
+/** JWT claims for domain end-user tokens */
+type DomainEndUserClaims = {
+    /** User ID (subject) */
+    sub: string;
+    /** Domain ID */
+    domain_id: string;
+    /** Root domain (e.g., "example.com") */
+    domain: string;
+    /** User roles */
+    roles: string[];
+    /** Subscription information */
+    subscription: {
+        status: string;
+        plan_code: string | null;
+        plan_name: string | null;
+        current_period_end: number | null;
+        cancel_at_period_end: boolean | null;
+        trial_ends_at: number | null;
+    };
+    /** Token expiration (Unix timestamp) */
+    exp: number;
+    /** Token issued at (Unix timestamp) */
+    iat: number;
+};
+/** Configuration for browser-side reauth client */
+type ReauthConfig = {
+    /** Your verified domain (e.g., "yourdomain.com") */
+    domain: string;
+};
+/** Configuration for server-side reauth client */
+type ReauthServerConfig = ReauthConfig & {
+    /** API key for server-to-server authentication (required, e.g., "sk_live_...") */
+    apiKey: string;
+};
+/** Subscription status values */
+type SubscriptionStatus = "active" | "past_due" | "canceled" | "trialing" | "incomplete" | "incomplete_expired" | "unpaid" | "paused" | "none";
+/** Subscription info included in JWT claims */
+type SubscriptionInfo = {
+    /** Current subscription status */
+    status: SubscriptionStatus;
+    /** Machine-readable plan identifier (e.g., "pro") */
+    planCode: string | null;
+    /** Human-readable plan name (e.g., "Pro Plan") */
+    planName: string | null;
+    /** Unix timestamp when current period ends */
+    currentPeriodEnd: number | null;
+    /** Whether subscription will cancel at period end */
+    cancelAtPeriodEnd: boolean | null;
+    /** Unix timestamp when trial ends (if applicable) */
+    trialEndsAt: number | null;
+};
+/** Authentication result from verifyToken/authenticate */
+type AuthResult = {
+    valid: boolean;
+    user: {
+        id: string;
+        roles: string[];
+        subscription: SubscriptionInfo;
+    } | null;
+    claims: DomainEndUserClaims | null;
+    error?: string;
+};
+/** Request-like object for extractToken/authenticate */
+type RequestLike = {
+    headers?: {
+        authorization?: string;
+        cookie?: string;
+    };
+};
+/** Response from GET /auth/token endpoint */
+type TokenResponse = {
+    /** The JWT access token */
+    accessToken: string;
+    /** Token expiration time in seconds */
+    expiresIn: number;
+    /** Token type (always "Bearer") */
+    tokenType: string;
+};
+/** Subscription plan available for purchase */
+type SubscriptionPlan = {
+    id: string;
+    code: string;
+    name: string;
+    description: string | null;
+    priceCents: number;
+    currency: string;
+    interval: "monthly" | "yearly" | "custom";
+    intervalCount: number;
+    trialDays: number;
+    features: string[];
+    displayOrder: number;
+};
+/** User's current subscription details */
+type UserSubscription = {
+    id: string | null;
+    planCode: string | null;
+    planName: string | null;
+    status: SubscriptionStatus;
+    currentPeriodEnd: number | null;
+    trialEnd: number | null;
+    cancelAtPeriodEnd: boolean | null;
+};
+/** Checkout session response */
+type CheckoutSession = {
+    checkoutUrl: string;
+};
+/** A single balance transaction record */
+type BalanceTransaction = {
+    id: string;
+    amountDelta: number;
+    reason: Record<string, unknown>;
+    balanceAfter: number;
+    createdAt: string;
+};
+/** Options for charging a user's balance */
+type ChargeOptions = {
+    amount: number;
+    requestUuid: string;
+    note?: string;
+};
+/** Options for depositing to a user's balance */
+type DepositOptions = {
+    amount: number;
+    requestUuid: string;
+    note?: string;
+};
+/** Pagination options for transaction queries */
+type TransactionsPaginationOptions = {
+    limit?: number;
+    offset?: number;
+};
+
+export type { AuthResult as A, BalanceTransaction as B, CheckoutSession as C, DomainEndUserClaims as D, ReauthConfig as R, SubscriptionPlan as S, TokenResponse as T, UserSubscription as U, ReauthSession as a, TransactionsPaginationOptions as b, User as c, UserDetails as d, ReauthServerConfig as e, RequestLike as f, SubscriptionInfo as g, ChargeOptions as h, DepositOptions as i };

package/dist/types-D8oOYbeC.d.ts

@@ -0,0 +1,169 @@
+/** Response from GET /api/public/auth/session */
+type ReauthSession = {
+    valid: boolean;
+    end_user_id: string | null;
+    email: string | null;
+    roles: string[] | null;
+    waitlist_position: number | null;
+    error: string | null;
+    error_code: "ACCOUNT_SUSPENDED" | null;
+    /** Subscription information (if billing is configured) */
+    subscription?: {
+        status: string;
+        plan_code: string | null;
+        plan_name: string | null;
+        current_period_end: number | null;
+        cancel_at_period_end: boolean | null;
+        trial_ends_at: number | null;
+    };
+};
+/** Authenticated user object (basic) */
+type User = {
+    id: string;
+    email: string;
+    roles: string[];
+};
+/** Full user details (from Developer API) */
+type UserDetails = {
+    id: string;
+    email: string;
+    roles: string[];
+    emailVerifiedAt: string | null;
+    lastLoginAt: string | null;
+    isFrozen: boolean;
+    isWhitelisted: boolean;
+    createdAt: string | null;
+};
+/** JWT claims for domain end-user tokens */
+type DomainEndUserClaims = {
+    /** User ID (subject) */
+    sub: string;
+    /** Domain ID */
+    domain_id: string;
+    /** Root domain (e.g., "example.com") */
+    domain: string;
+    /** User roles */
+    roles: string[];
+    /** Subscription information */
+    subscription: {
+        status: string;
+        plan_code: string | null;
+        plan_name: string | null;
+        current_period_end: number | null;
+        cancel_at_period_end: boolean | null;
+        trial_ends_at: number | null;
+    };
+    /** Token expiration (Unix timestamp) */
+    exp: number;
+    /** Token issued at (Unix timestamp) */
+    iat: number;
+};
+/** Configuration for browser-side reauth client */
+type ReauthConfig = {
+    /** Your verified domain (e.g., "yourdomain.com") */
+    domain: string;
+};
+/** Configuration for server-side reauth client */
+type ReauthServerConfig = ReauthConfig & {
+    /** API key for server-to-server authentication (required, e.g., "sk_live_...") */
+    apiKey: string;
+};
+/** Subscription status values */
+type SubscriptionStatus = "active" | "past_due" | "canceled" | "trialing" | "incomplete" | "incomplete_expired" | "unpaid" | "paused" | "none";
+/** Subscription info included in JWT claims */
+type SubscriptionInfo = {
+    /** Current subscription status */
+    status: SubscriptionStatus;
+    /** Machine-readable plan identifier (e.g., "pro") */
+    planCode: string | null;
+    /** Human-readable plan name (e.g., "Pro Plan") */
+    planName: string | null;
+    /** Unix timestamp when current period ends */
+    currentPeriodEnd: number | null;
+    /** Whether subscription will cancel at period end */
+    cancelAtPeriodEnd: boolean | null;
+    /** Unix timestamp when trial ends (if applicable) */
+    trialEndsAt: number | null;
+};
+/** Authentication result from verifyToken/authenticate */
+type AuthResult = {
+    valid: boolean;
+    user: {
+        id: string;
+        roles: string[];
+        subscription: SubscriptionInfo;
+    } | null;
+    claims: DomainEndUserClaims | null;
+    error?: string;
+};
+/** Request-like object for extractToken/authenticate */
+type RequestLike = {
+    headers?: {
+        authorization?: string;
+        cookie?: string;
+    };
+};
+/** Response from GET /auth/token endpoint */
+type TokenResponse = {
+    /** The JWT access token */
+    accessToken: string;
+    /** Token expiration time in seconds */
+    expiresIn: number;
+    /** Token type (always "Bearer") */
+    tokenType: string;
+};
+/** Subscription plan available for purchase */
+type SubscriptionPlan = {
+    id: string;
+    code: string;
+    name: string;
+    description: string | null;
+    priceCents: number;
+    currency: string;
+    interval: "monthly" | "yearly" | "custom";
+    intervalCount: number;
+    trialDays: number;
+    features: string[];
+    displayOrder: number;
+};
+/** User's current subscription details */
+type UserSubscription = {
+    id: string | null;
+    planCode: string | null;
+    planName: string | null;
+    status: SubscriptionStatus;
+    currentPeriodEnd: number | null;
+    trialEnd: number | null;
+    cancelAtPeriodEnd: boolean | null;
+};
+/** Checkout session response */
+type CheckoutSession = {
+    checkoutUrl: string;
+};
+/** A single balance transaction record */
+type BalanceTransaction = {
+    id: string;
+    amountDelta: number;
+    reason: Record<string, unknown>;
+    balanceAfter: number;
+    createdAt: string;
+};
+/** Options for charging a user's balance */
+type ChargeOptions = {
+    amount: number;
+    requestUuid: string;
+    note?: string;
+};
+/** Options for depositing to a user's balance */
+type DepositOptions = {
+    amount: number;
+    requestUuid: string;
+    note?: string;
+};
+/** Pagination options for transaction queries */
+type TransactionsPaginationOptions = {
+    limit?: number;
+    offset?: number;
+};
+
+export type { AuthResult as A, BalanceTransaction as B, CheckoutSession as C, DomainEndUserClaims as D, ReauthConfig as R, SubscriptionPlan as S, TokenResponse as T, UserSubscription as U, ReauthSession as a, TransactionsPaginationOptions as b, User as c, UserDetails as d, ReauthServerConfig as e, RequestLike as f, SubscriptionInfo as g, ChargeOptions as h, DepositOptions as i };