@sylphx/sdk 0.15.2 → 0.15.3

package/dist/nextjs/index.d.ts

@@ -2,34 +2,247 @@ import { NextResponse, NextRequest } from 'next/server';
 import { AuthTokensResponse } from '@sylphx/contract';
 
 /**
- * Sylphx Unified Middleware — State of the Art
+ * Auth Functions
  *
- * ONE middleware function handles EVERYTHING:
- * - Auth routes (mounted automatically, zero manual API routes)
- * - BaaS routes (same-origin proxy, no browser bearer-token exposure)
- * - Token refresh (automatic, every request)
- * - Route protection
- * - Cookie management
+ * Pure functions for authentication - no hidden state.
+ * Each function takes config as the first parameter.
  *
- * This follows Auth0 v4 / Clerk / Supabase patterns where middleware
- * handles all auth concerns. Apps don't need to create any /api/auth/* routes.
+ * Uses REST API at /api/sdk/auth/* for all operations.
+ *
+ * Types are re-exported from `@sylphx/contract` (ADR-084). The contract is
+ * the single source of truth for every wire shape — this module only adds
+ * SDK-specific ergonomics (User brand swap, introspection result, invite
+ * envelopes, org-token claims).
+ */
+
+/**
+ * Token response — contract's `AuthTokensResponse.user` (optional `AuthUser`)
+ * is re-mapped to the SDK's broader `User` type so legacy callers keep the
+ * familiar brand. `AuthUser` and `User` are structurally identical, but
+ * the SDK surface has wider reach (cookies, middleware, React hooks) and
+ * renaming is out of scope for ADR-084 cleanup.
+ */
+type TokenResponse = Omit<AuthTokensResponse, 'user'> & {
+    user: User;
+};
+
+/**
+ * SDK-specific types — cross-layer helpers and server-first configuration.
+ *
+ * Wire-shape types (API request/response envelopes) live in
+ * `@sylphx/contract` and are re-exported per namespace from their SDK
+ * module (e.g. `Plan` / `Subscription` from `./billing`, `ConsentType`
+ * from `./consent`, `TokenResponse` from `./auth`). React-hook wrapper
+ * shapes live in `./react/types` (tRPC-like convenience shapes that
+ * are not part of the platform wire).
+ *
+ * History: pre-ADR-084 this file mirrored every wire shape the SDK
+ * exposed; those aliases now come directly from `@sylphx/contract`.
+ */
+
+/** SDK cookie/token shape. Richer authenticated surfaces live in `./react/types` `UserProfile`. */
+interface User {
+    id: string;
+    email: string;
+    name: string | null;
+    image?: string | null;
+    emailVerified?: boolean;
+    role?: string;
+    createdAt?: string;
+}
+interface UserCookieData {
+    user: User;
+    /** Epoch ms when the session expires (client-side expiry check). */
+    expiresAt: number;
+}
+
+/**
+ * Cookie Management for Next.js — Single Source of Truth
+ *
+ * Architecture: Cookie-Centric Auth (Clerk Pattern)
+ * ================================================
+ *
+ * ALL auth state lives in cookies. Zero localStorage for auth.
+ *
+ * Cookie Structure:
+ * - __sylphx_{namespace}_session  — HttpOnly JWT, 5 min (access token)
+ * - __sylphx_{namespace}_refresh  — HttpOnly, 30 days (refresh token)
+ * - __sylphx_{namespace}_user     — JS-readable, 5 min (user data for client hydration)
+ *
+ * Benefits:
+ * 1. Single Source of Truth — no server/client state divergence
+ * 2. XSS-safe — tokens never accessible to JavaScript
+ * 3. Cross-tab sync — cookies shared across tabs automatically
+ * 4. SSR works — auth() in Server Components reads cookies directly
+ *
+ * Security:
+ * - Short token lifetime (5 min) like Clerk
+ * - Server-side refresh in middleware
+ * - SameSite=Lax for CSRF protection
+ */
+
+/**
+ * Get cookie names for a given namespace
+ *
+ * Namespace is derived from the secret key environment (dev/stg/prod).
+ * This prevents cookies from different environments colliding.
  *
  * @example
- * ```typescript
- * // middleware.ts (or proxy.ts for Next.js 16)
- * import { createSylphxMiddleware } from '@sylphx/sdk/nextjs'
+ * getCookieNames('sylphx_prod')
+ * // Returns:
+ * // {
+ * //   SESSION: '__sylphx_prod_session',
+ * //   REFRESH: '__sylphx_prod_refresh',
+ * //   USER: '__sylphx_prod_user',
+ * // }
+ */
+declare function getCookieNames(namespace: string): {
+    /** HttpOnly JWT access token (5 min) */
+    SESSION: string;
+    /** HttpOnly refresh token (30 days) */
+    REFRESH: string;
+    /** JS-readable user data for client hydration (5 min) */
+    USER: string;
+    /** HttpOnly active organization ID used to preserve org-scoped sessions */
+    ACTIVE_ORG_ID: string;
+    /** HttpOnly active organization slug used to preserve org-scoped sessions */
+    ACTIVE_ORG_SLUG: string;
+};
+/**
+ * Session token lifetime (5 minutes like Clerk)
+ */
+declare const SESSION_TOKEN_LIFETIME: number;
+/**
+ * Refresh token lifetime (30 days)
+ */
+declare const REFRESH_TOKEN_LIFETIME: number;
+/**
+ * Active organization context lifetime (30 days).
  *
- * export default createSylphxMiddleware({
- *   publicRoutes: ['/', '/about', '/pricing'],
- * })
+ * This matches refresh-token lifetime: the org preference is session-scoped
+ * state, not a permanent user preference. Clearing auth clears this too.
+ */
+declare const ACTIVE_ORG_LIFETIME: number;
+/**
+ * Cookie options for HttpOnly tokens (session, refresh)
  *
- * export const config = {
- *   matcher: ['/((?!_next|.*\\..*).*)', '/'],
- * }
- * ```
+ * Security features:
+ * - httpOnly: true — Not accessible via JavaScript (XSS protection)
+ * - secure: true in production — Only sent over HTTPS
+ * - sameSite: 'lax' — CSRF protection while allowing navigation
+ */
+declare const SECURE_COOKIE_OPTIONS: {
+    httpOnly: boolean;
+    secure: boolean;
+    sameSite: "lax";
+    path: string;
+};
+/**
+ * Cookie options for JS-readable user cookie
  *
- * That's it. No /api/auth/* routes needed.
+ * This cookie contains only user info (no tokens) and enables:
+ * - Client-side hydration without loading states
+ * - Cross-tab sync via cookie visibility
+ */
+declare const USER_COOKIE_OPTIONS: {
+    httpOnly: boolean;
+    secure: boolean;
+    sameSite: "lax";
+    path: string;
+};
+/**
+ * Cookie options for active organization context.
+ *
+ * Active org is not a secret, but it controls which org-scoped JWT the SDK
+ * restores after refresh. Keep it HttpOnly so browser JavaScript cannot
+ * silently steer server-side auth context outside the official switch-org
+ * route.
+ */
+declare const ACTIVE_ORG_COOKIE_OPTIONS: {
+    httpOnly: boolean;
+    secure: boolean;
+    sameSite: "lax";
+    path: string;
+};
+/**
+ * Auth cookies data returned by getAuthCookies
+ */
+interface AuthCookiesData {
+    /** Access token from SESSION cookie (HttpOnly) */
+    sessionToken: string | null;
+    /** Refresh token from REFRESH cookie (HttpOnly) */
+    refreshToken: string | null;
+    /** User data from USER cookie (JS-readable) */
+    user: User | null;
+    /** Expiry timestamp from USER cookie */
+    expiresAt: number | null;
+}
+/**
+ * Decode a cookie value without throwing on malformed percent-encoding.
  */
+declare function decodeCookieValue(value: string): string;
+/**
+ * Read the last value for a cookie name from a raw Cookie header.
+ *
+ * Browsers can legitimately send duplicate cookie names when an application
+ * has migrated between host-only and domain-scoped cookies. RFC 6265 orders
+ * same-path duplicates by creation time, so the most recently set cookie is the
+ * right value for auth session recovery.
+ */
+declare function readCookieValueFromHeader(cookieHeader: string | null | undefined, name: string): string | null;
+/**
+ * Get auth cookies from the request
+ *
+ * Used by auth() to read current auth state.
+ */
+declare function getAuthCookies(namespace: string): Promise<AuthCookiesData>;
+/**
+ * Set auth cookies from token response
+ *
+ * Sets all three cookies:
+ * - SESSION: HttpOnly access token (5 min)
+ * - REFRESH: HttpOnly refresh token (30 days)
+ * - USER: JS-readable user data (5 min)
+ *
+ * @param namespace - Cookie namespace (e.g., 'sylphx_prod')
+ * @param response - Token response from auth endpoint
+ * @param options - Optional: custom expiresIn override
+ */
+declare function setAuthCookies(namespace: string, response: TokenResponse, options?: {
+    sessionLifetime?: number;
+}): Promise<void>;
+/**
+ * Clear all auth cookies
+ *
+ * Call on sign out to remove all auth state.
+ */
+declare function clearAuthCookies(namespace: string): Promise<void>;
+/**
+ * Check if session is expired
+ *
+ * Uses a 30 second buffer to account for network latency.
+ */
+declare function isSessionExpired(namespace: string): Promise<boolean>;
+/**
+ * Check if we have a refresh token (can potentially refresh)
+ */
+declare function hasRefreshToken(namespace: string): Promise<boolean>;
+
+/**
+ * Set auth cookies on a NextResponse (for middleware use)
+ *
+ * Unlike setAuthCookies() which uses next/headers, this works with NextResponse.
+ * Use this in middleware where you need to modify cookies on the response.
+ */
+declare function setAuthCookiesMiddleware(response: NextResponse, namespace: string, tokens: TokenResponse): void;
+/**
+ * Clear auth cookies on a NextResponse (for middleware use)
+ */
+declare function clearAuthCookiesMiddleware(response: NextResponse, namespace: string): void;
+/**
+ * Parse user cookie value (for client-side use)
+ */
+declare function parseUserCookie(value: string): UserCookieData | null;
 
 interface SylphxMiddlewareConfig {
     /**
@@ -64,19 +277,19 @@ interface SylphxMiddlewareConfig {
     afterSignInUrl?: string;
     /**
      * Auth routes prefix. Routes are mounted at:
-     * - {prefix}/register — email/password registration handler
-     * - {prefix}/login — credentials login handler
-     * - {prefix}/verify-email — email verification handler
-     * - {prefix}/oauth-providers — enabled social login providers
-     * - {prefix}/oauth/authorize — social login start handler
-     * - {prefix}/callback — OAuth callback handler
-     * - {prefix}/passkey/options — passkey login challenge handler
-     * - {prefix}/passkey/authenticate — passkey login verification handler
-     * - {prefix}/verify-2fa — TOTP/backup-code verification handler
-     * - {prefix}/forgot-password — password reset email handler
-     * - {prefix}/reset-password — password reset verification handler
-     * - {prefix}/session — safe session metadata handler
-     * - {prefix}/signout — Sign out handler
+     * - {prefix}/register - email/password registration handler
+     * - {prefix}/login - credentials login handler
+     * - {prefix}/verify-email - email verification handler
+     * - {prefix}/oauth-providers - enabled social login providers
+     * - {prefix}/oauth/authorize - social login start handler
+     * - {prefix}/callback - OAuth callback handler
+     * - {prefix}/passkey/options - passkey login challenge handler
+     * - {prefix}/passkey/authenticate - passkey login verification handler
+     * - {prefix}/verify-2fa - TOTP/backup-code verification handler
+     * - {prefix}/forgot-password - password reset email handler
+     * - {prefix}/reset-password - password reset verification handler
+     * - {prefix}/session - safe session metadata handler
+     * - {prefix}/signout - Sign out handler
      *
      * @default '/auth'
      */
@@ -217,6 +430,37 @@ interface SylphxOrganizationContextConfig {
      */
     additionalOrgSlugCookies?: readonly string[];
 }
+
+/**
+ * Sylphx Unified Middleware — State of the Art
+ *
+ * ONE middleware function handles EVERYTHING:
+ * - Auth routes (mounted automatically, zero manual API routes)
+ * - BaaS routes (same-origin proxy, no browser bearer-token exposure)
+ * - Token refresh (automatic, every request)
+ * - Route protection
+ * - Cookie management
+ *
+ * This follows Auth0 v4 / Clerk / Supabase patterns where middleware
+ * handles all auth concerns. Apps don't need to create any /api/auth/* routes.
+ *
+ * @example
+ * ```typescript
+ * // middleware.ts (or proxy.ts for Next.js 16)
+ * import { createSylphxMiddleware } from '@sylphx/sdk/nextjs'
+ *
+ * export default createSylphxMiddleware({
+ *   publicRoutes: ['/', '/about', '/pricing'],
+ * })
+ *
+ * export const config = {
+ *   matcher: ['/((?!_next|.*\\..*).*)', '/'],
+ * }
+ * ```
+ *
+ * That's it. No /api/auth/* routes needed.
+ */
+
 /**
  * Create Sylphx middleware — State of the Art
  *
@@ -253,61 +497,6 @@ declare function createMatcher(): {
  */
 declare function getNamespace(secretKey: string): string;
 
-/**
- * Auth Functions
- *
- * Pure functions for authentication - no hidden state.
- * Each function takes config as the first parameter.
- *
- * Uses REST API at /api/sdk/auth/* for all operations.
- *
- * Types are re-exported from `@sylphx/contract` (ADR-084). The contract is
- * the single source of truth for every wire shape — this module only adds
- * SDK-specific ergonomics (User brand swap, introspection result, invite
- * envelopes, org-token claims).
- */
-
-/**
- * Token response — contract's `AuthTokensResponse.user` (optional `AuthUser`)
- * is re-mapped to the SDK's broader `User` type so legacy callers keep the
- * familiar brand. `AuthUser` and `User` are structurally identical, but
- * the SDK surface has wider reach (cookies, middleware, React hooks) and
- * renaming is out of scope for ADR-084 cleanup.
- */
-type TokenResponse = Omit<AuthTokensResponse, 'user'> & {
-    user: User;
-};
-
-/**
- * SDK-specific types — cross-layer helpers and server-first configuration.
- *
- * Wire-shape types (API request/response envelopes) live in
- * `@sylphx/contract` and are re-exported per namespace from their SDK
- * module (e.g. `Plan` / `Subscription` from `./billing`, `ConsentType`
- * from `./consent`, `TokenResponse` from `./auth`). React-hook wrapper
- * shapes live in `./react/types` (tRPC-like convenience shapes that
- * are not part of the platform wire).
- *
- * History: pre-ADR-084 this file mirrored every wire shape the SDK
- * exposed; those aliases now come directly from `@sylphx/contract`.
- */
-
-/** SDK cookie/token shape. Richer authenticated surfaces live in `./react/types` `UserProfile`. */
-interface User {
-    id: string;
-    email: string;
-    name: string | null;
-    image?: string | null;
-    emailVerified?: boolean;
-    role?: string;
-    createdAt?: string;
-}
-interface UserCookieData {
-    user: User;
-    /** Epoch ms when the session expires (client-side expiry check). */
-    expiresAt: number;
-}
-
 /**
  * Server-side Auth Helpers for Next.js
  *
@@ -528,192 +717,4 @@ declare function encodeUserId(uuid: string): string;
  */
 declare function decodeUserId(prefixedId: string): string | null;
 
-/**
- * Cookie Management for Next.js — Single Source of Truth
- *
- * Architecture: Cookie-Centric Auth (Clerk Pattern)
- * ================================================
- *
- * ALL auth state lives in cookies. Zero localStorage for auth.
- *
- * Cookie Structure:
- * - __sylphx_{namespace}_session  — HttpOnly JWT, 5 min (access token)
- * - __sylphx_{namespace}_refresh  — HttpOnly, 30 days (refresh token)
- * - __sylphx_{namespace}_user     — JS-readable, 5 min (user data for client hydration)
- *
- * Benefits:
- * 1. Single Source of Truth — no server/client state divergence
- * 2. XSS-safe — tokens never accessible to JavaScript
- * 3. Cross-tab sync — cookies shared across tabs automatically
- * 4. SSR works — auth() in Server Components reads cookies directly
- *
- * Security:
- * - Short token lifetime (5 min) like Clerk
- * - Server-side refresh in middleware
- * - SameSite=Lax for CSRF protection
- */
-
-/**
- * Get cookie names for a given namespace
- *
- * Namespace is derived from the secret key environment (dev/stg/prod).
- * This prevents cookies from different environments colliding.
- *
- * @example
- * getCookieNames('sylphx_prod')
- * // Returns:
- * // {
- * //   SESSION: '__sylphx_prod_session',
- * //   REFRESH: '__sylphx_prod_refresh',
- * //   USER: '__sylphx_prod_user',
- * // }
- */
-declare function getCookieNames(namespace: string): {
-    /** HttpOnly JWT access token (5 min) */
-    SESSION: string;
-    /** HttpOnly refresh token (30 days) */
-    REFRESH: string;
-    /** JS-readable user data for client hydration (5 min) */
-    USER: string;
-    /** HttpOnly active organization ID used to preserve org-scoped sessions */
-    ACTIVE_ORG_ID: string;
-    /** HttpOnly active organization slug used to preserve org-scoped sessions */
-    ACTIVE_ORG_SLUG: string;
-};
-/**
- * Session token lifetime (5 minutes like Clerk)
- */
-declare const SESSION_TOKEN_LIFETIME: number;
-/**
- * Refresh token lifetime (30 days)
- */
-declare const REFRESH_TOKEN_LIFETIME: number;
-/**
- * Active organization context lifetime (30 days).
- *
- * This matches refresh-token lifetime: the org preference is session-scoped
- * state, not a permanent user preference. Clearing auth clears this too.
- */
-declare const ACTIVE_ORG_LIFETIME: number;
-/**
- * Cookie options for HttpOnly tokens (session, refresh)
- *
- * Security features:
- * - httpOnly: true — Not accessible via JavaScript (XSS protection)
- * - secure: true in production — Only sent over HTTPS
- * - sameSite: 'lax' — CSRF protection while allowing navigation
- */
-declare const SECURE_COOKIE_OPTIONS: {
-    httpOnly: boolean;
-    secure: boolean;
-    sameSite: "lax";
-    path: string;
-};
-/**
- * Cookie options for JS-readable user cookie
- *
- * This cookie contains only user info (no tokens) and enables:
- * - Client-side hydration without loading states
- * - Cross-tab sync via cookie visibility
- */
-declare const USER_COOKIE_OPTIONS: {
-    httpOnly: boolean;
-    secure: boolean;
-    sameSite: "lax";
-    path: string;
-};
-/**
- * Cookie options for active organization context.
- *
- * Active org is not a secret, but it controls which org-scoped JWT the SDK
- * restores after refresh. Keep it HttpOnly so browser JavaScript cannot
- * silently steer server-side auth context outside the official switch-org
- * route.
- */
-declare const ACTIVE_ORG_COOKIE_OPTIONS: {
-    httpOnly: boolean;
-    secure: boolean;
-    sameSite: "lax";
-    path: string;
-};
-/**
- * Auth cookies data returned by getAuthCookies
- */
-interface AuthCookiesData {
-    /** Access token from SESSION cookie (HttpOnly) */
-    sessionToken: string | null;
-    /** Refresh token from REFRESH cookie (HttpOnly) */
-    refreshToken: string | null;
-    /** User data from USER cookie (JS-readable) */
-    user: User | null;
-    /** Expiry timestamp from USER cookie */
-    expiresAt: number | null;
-}
-/**
- * Decode a cookie value without throwing on malformed percent-encoding.
- */
-declare function decodeCookieValue(value: string): string;
-/**
- * Read the last value for a cookie name from a raw Cookie header.
- *
- * Browsers can legitimately send duplicate cookie names when an application
- * has migrated between host-only and domain-scoped cookies. RFC 6265 orders
- * same-path duplicates by creation time, so the most recently set cookie is the
- * right value for auth session recovery.
- */
-declare function readCookieValueFromHeader(cookieHeader: string | null | undefined, name: string): string | null;
-/**
- * Get auth cookies from the request
- *
- * Used by auth() to read current auth state.
- */
-declare function getAuthCookies(namespace: string): Promise<AuthCookiesData>;
-/**
- * Set auth cookies from token response
- *
- * Sets all three cookies:
- * - SESSION: HttpOnly access token (5 min)
- * - REFRESH: HttpOnly refresh token (30 days)
- * - USER: JS-readable user data (5 min)
- *
- * @param namespace - Cookie namespace (e.g., 'sylphx_prod')
- * @param response - Token response from auth endpoint
- * @param options - Optional: custom expiresIn override
- */
-declare function setAuthCookies(namespace: string, response: TokenResponse, options?: {
-    sessionLifetime?: number;
-}): Promise<void>;
-/**
- * Clear all auth cookies
- *
- * Call on sign out to remove all auth state.
- */
-declare function clearAuthCookies(namespace: string): Promise<void>;
-/**
- * Check if session is expired
- *
- * Uses a 30 second buffer to account for network latency.
- */
-declare function isSessionExpired(namespace: string): Promise<boolean>;
-/**
- * Check if we have a refresh token (can potentially refresh)
- */
-declare function hasRefreshToken(namespace: string): Promise<boolean>;
-
-/**
- * Set auth cookies on a NextResponse (for middleware use)
- *
- * Unlike setAuthCookies() which uses next/headers, this works with NextResponse.
- * Use this in middleware where you need to modify cookies on the response.
- */
-declare function setAuthCookiesMiddleware(response: NextResponse, namespace: string, tokens: TokenResponse): void;
-/**
- * Clear auth cookies on a NextResponse (for middleware use)
- */
-declare function clearAuthCookiesMiddleware(response: NextResponse, namespace: string): void;
-/**
- * Parse user cookie value (for client-side use)
- */
-declare function parseUserCookie(value: string): UserCookieData | null;
-
 export { ACTIVE_ORG_COOKIE_OPTIONS, ACTIVE_ORG_LIFETIME, type AuthCookiesData, type AuthResult, REFRESH_TOKEN_LIFETIME, SECURE_COOKIE_OPTIONS, SESSION_TOKEN_LIFETIME, SESSION_TOKEN_LIFETIME_MS, type SylphxMiddlewareConfig, type SylphxOrganizationContextConfig, TOKEN_EXPIRY_BUFFER_MS, USER_COOKIE_OPTIONS, type UserCookieData, auth, clearAuthCookies, clearAuthCookiesMiddleware, configureServer, createMatcher, createSylphxMiddleware, currentUser, currentUserId, decodeCookieValue, decodeUserId, encodeUserId, getAuthCookies, getAuthorizationUrl, getCookieNames, getNamespace, getSessionToken, handleCallback, hasRefreshToken, isSessionExpired, parseUserCookie, readCookieValueFromHeader, setAuthCookies, setAuthCookiesMiddleware, signOut, sylphxMiddleware, syncAuthToCookies };