nextjs-hasura-auth 0.1.0

package/README.md

@@ -0,0 +1,154 @@
+# Next.js Hasura Authentication Boilerplate
+
+This project provides a robust starting point for building applications using Next.js (App Router), Hasura, and strong authentication patterns. It features JWT-based authentication with NextAuth.js, a secure GraphQL proxy to Hasura, direct WebSocket support for subscriptions, and a powerful dynamic query generator.
+
+[![Generator Documentation](https://img.shields.io/badge/Generator%20Docs-MD-blue)](GENERATOR.md) [![Apollo Client Documentation](https://img.shields.io/badge/Apollo%20Client%20Docs-MD-orange)](APOLLO.md)
+
+See [`GENERATOR.md`](GENERATOR.md) for detailed documentation on the dynamic GraphQL query generator, which simplifies creating queries, mutations, and subscriptions based on your Hasura schema.
+
+See [`APOLLO.md`](APOLLO.md) for details on the configured Apollo Client instance and how it handles authenticated requests and subscriptions.
+
+## ✨ Features Checklist
+
+**Implemented:**
+
+*   [x] **Secure Hasura Proxy:** An integrated API route acts as a proxy to Hasura, securely handling requests using the user's session JWT while hiding the Hasura Admin Secret from the client.
+*   [x] **Credentials Authentication:** User authentication implemented using NextAuth.js with a login/password (Credentials) provider.
+*   [x] **Unified Apollo Client:** A configured Apollo Client instance handles both authenticated HTTP requests (via the proxy) and direct, authenticated WebSocket connections for subscriptions.
+*   [x] **Dynamic Query Generator:** A versatile query generator (`lib/generator.ts`) allows dynamic creation of GraphQL operations based on options and schema, suitable for client/server use.
+*   [x] **WebSocket Authentication:** Real-time subscriptions connect directly to Hasura via WebSockets, authenticated using the user's session JWT.
+
+**Planned / Future Ideas:**
+
+*   [ ] **Convenience Hooks:** Create easy-to-use React hooks (`useQuery`, `useSubscription`, potentially a `useCRUD` hook/class) that integrate the `Generator` with Apollo Client for streamlined data fetching in components.
+*   [ ] **Multi-Platform Builds:** Native builders for Android, iOS, MacOS, Windows, Linux, Oculus (e.g., using Tauri, Capacitor, or Electron).
+*   [ ] **Unique Environment Builders:** Specific builds for Chrome Extensions, Firefox Extensions, and VSCode Extensions (including custom UI elements).
+*   [ ] Additional Authentication Providers (OAuth: Google, GitHub, etc.).
+*   [ ] Role-based access control examples.
+*   [ ] Advanced caching strategies.
+*   [ ] Comprehensive end-to-end testing setup.
+
+## 🚀 Core Concepts
+
+### 1. Authentication (NextAuth.js)
+
+*   Uses `NextAuth.js` for handling authentication flow.
+*   Configured with the **Credentials provider** for email/password login (see `pages/api/auth/[...nextauth].ts` or `app/api/auth/[...nextauth]/route.ts`).
+*   Manages sessions using **JWT**. The JWT contains essential user information and Hasura claims.
+*   Provides standard pages/routes for login, logout, and potentially signup.
+
+### 2. Hasura Integration
+
+Interaction with the Hasura GraphQL Engine is handled in two primary ways:
+
+*   **HTTP Requests (Queries/Mutations via Proxy):**
+    *   Client-side GraphQL queries and mutations are sent to a Next.js API route (`/api/graphql-proxy` or similar).
+    *   This proxy route retrieves the user's JWT from their session.
+    *   It then forwards the GraphQL request to the actual Hasura endpoint (`HASURA_GRAPHQL_URL`).
+    *   Crucially, the proxy uses the **`HASURA_ADMIN_SECRET`** to communicate with Hasura but includes the user's details (like `x-hasura-user-id`, `x-hasura-default-role` derived from the JWT) as session variables in the request headers.
+    *   This ensures Hasura applies the correct permissions for the logged-in user while keeping the powerful `admin_secret` completely hidden from the browser.
+*   **WebSocket Connections (Subscriptions):**
+    *   For real-time data via GraphQL Subscriptions, the client establishes a direct WebSocket connection to the Hasura endpoint (`wss://...`).
+    *   Authentication for the WebSocket connection is handled by passing the user's session JWT within the `connectionParams`. Hasura verifies this token to authorize the subscription.
+    *   The `components/auth/SocketAuthStatus.tsx` component likely demonstrates checking the status of this authenticated connection.
+
+### 3. Apollo Client
+
+*   A pre-configured Apollo Client instance (`lib/apolloClient.ts` or similar) is set up to manage GraphQL data fetching.
+*   It intelligently handles both:
+    *   **HTTP Link:** Points to the Next.js GraphQL proxy (`/api/graphql-proxy`) for queries and mutations.
+    *   **WebSocket Link:** Connects directly to Hasura's WebSocket endpoint for subscriptions, including logic to pass the authentication token.
+*   The client can be used both client-side (with React hooks) and server-side (for SSR/SSG data fetching).
+
+### 4. Dynamic Query Generation (`GENERATOR.md`)
+
+*   The core `Generator` function in `lib/generator.ts` allows you to build complex GraphQL operations dynamically based on a simple options object and your `schema.json`.
+*   This avoids writing lengthy GraphQL query strings manually.
+*   See [`GENERATOR.md`](GENERATOR.md) for full usage details and examples.
+*   *Convenience hooks (like `useQuery`, `useSubscription`, `useCRUD`) are planned to further simplify using the generator within React components.*
+
+## 📁 Project Structure (Key Directories)
+
+```
+.
+├── app/                  # Next.js App Router (Pages, Layouts, API Routes)
+│   ├── api/              # API routes (e.g., auth, graphql-proxy)
+│   └── (main)/           # Main application pages/routes
+├── components/           # Shared React components
+│   ├── auth/             # Authentication-related components
+│   └── ui/               # UI primitives (likely shadcn/ui)
+├── lib/                  # Core logic, utilities, client configurations
+│   ├── apolloClient.ts   # Apollo Client setup
+│   ├── auth.ts           # Authentication utilities/configs
+│   ├── generator.ts      # GraphQL Query Generator
+│   ├── debug.ts          # Debug utility
+│   └── ...
+├── public/               # Static assets
+├── styles/               # Global styles
+├── .env.local            # Environment variables (Gitignored)
+├── GENERATOR.md          # Query Generator Documentation
+├── schema.json           # Hasura GraphQL schema (for Generator)
+├── next.config.js        # Next.js configuration
+├── package.json          # Project dependencies and scripts
+└── tsconfig.json         # TypeScript configuration
+```
+
+## 🛠️ Getting Started
+
+1.  **Clone the repository:**
+    ```bash
+    git clone <repository-url>
+    cd <repository-directory>
+    ```
+
+2.  **Install dependencies:**
+    ```bash
+    npm install
+    # or
+    yarn install
+    # or
+    pnpm install
+    ```
+
+3.  **Set up Environment Variables:**
+    Create a `.env.local` file in the root directory and add the following variables:
+
+    ```env
+    # Hasura Configuration
+    NEXT_PUBLIC_HASURA_GRAPHQL_ENDPOINT="<your-hasura-graphql-url>" # e.g., https://your-project.hasura.app/v1/graphql
+    NEXT_PUBLIC_HASURA_WS_ENDPOINT="<your-hasura-websocket-url>" # e.g., wss://your-project.hasura.app/v1/graphql
+    HASURA_ADMIN_SECRET="<your-hasura-admin-secret>"
+
+    # NextAuth.js Configuration
+    NEXTAUTH_URL="<your-deployment-url>" # e.g., http://localhost:3000 for local dev
+    NEXTAUTH_SECRET="<generate-a-strong-secret>" # Generate with: openssl rand -base64 32
+
+    # Other (if needed by your setup)
+    # DATABASE_URL="..."
+    ```
+    *   Replace `<...>` with your actual Hasura credentials and secrets.
+    *   Ensure `NEXTAUTH_URL` points to your application's base URL.
+
+4.  **Update Hasura Schema:**
+    Make sure the `schema.json` file in the root is up-to-date with your Hasura instance's schema. You might need to fetch this from Hasura if you've made changes.
+
+5.  **Run the development server:**
+    ```bash
+    npm run dev
+    # or
+    yarn dev
+    # or
+    pnpm dev
+    ```
+
+6.  Open [http://localhost:3000](http://localhost:3000) (or your `NEXTAUTH_URL`) in your browser.
+
+## Environment Variables Summary
+
+*   `NEXT_PUBLIC_HASURA_GRAPHQL_ENDPOINT`: Public URL for Hasura GraphQL HTTP endpoint.
+*   `NEXT_PUBLIC_HASURA_WS_ENDPOINT`: Public URL for Hasura GraphQL WebSocket endpoint.
+*   `HASURA_ADMIN_SECRET`: Your Hasura admin secret (kept server-side).
+*   `NEXTAUTH_URL`: The canonical URL of your Next.js application.
+*   `NEXTAUTH_SECRET`: A secret key used by NextAuth.js to sign JWTs, etc.
+
+Let me know what you think!

package/dist/lib/apollo.d.ts

@@ -0,0 +1,45 @@
+import { ApolloClient } from '@apollo/client';
+/**
+ * Get JWT secret from environment variables
+ * @returns {Uint8Array} Secret key for JWT signing
+ */
+export declare const getJwtSecret: () => Uint8Array;
+interface ApolloOptions {
+    url?: string;
+    ws?: boolean;
+    token?: string;
+    secret?: string;
+}
+/**
+ * Create Apollo Client
+ *
+ * @param {Object} options - Options for creating the client
+ * @param {boolean} options.ws - Use WebSocket connection
+ * @param {string} options.token - JWT token for authorization
+ * @param {string} options.secret - Admin secret for Hasura
+ * @returns {ApolloClient} Apollo Client
+ */
+export declare function createClient(options?: ApolloOptions): ApolloClient<import("@apollo/client").NormalizedCacheObject>;
+/**
+ * Get or create Apollo client instance
+ * @param options Client options
+ * @returns Apollo client instance
+ */
+export declare function getClient(options?: {}): ApolloClient<any>;
+/**
+ * React hook to get Apollo client instance
+ * @returns Apollo client instance
+ */
+export declare function useClient(options: ApolloOptions): ApolloClient<import("@apollo/client").NormalizedCacheObject>;
+/**
+ * Check connection to Hasura GraphQL endpoint
+ * @returns {Promise<boolean>} True if connection is successful
+ */
+export declare function checkConnection(client?: ApolloClient<any>): Promise<boolean>;
+declare const _default: {
+    createClient: typeof createClient;
+    getClient: typeof getClient;
+    getJwtSecret: () => Uint8Array;
+    checkConnection: typeof checkConnection;
+};
+export default _default;

package/dist/lib/apollo.js

@@ -0,0 +1,206 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getJwtSecret = void 0;
+exports.createClient = createClient;
+exports.getClient = getClient;
+exports.useClient = useClient;
+exports.checkConnection = checkConnection;
+const client_1 = require("@apollo/client");
+const context_1 = require("@apollo/client/link/context");
+const utilities_1 = require("@apollo/client/utilities");
+const subscriptions_1 = require("@apollo/client/link/subscriptions");
+const graphql_ws_1 = require("graphql-ws");
+const cross_fetch_1 = __importDefault(require("cross-fetch"));
+const debug_1 = __importDefault(require("./debug"));
+const react_1 = require("react");
+// Create a debug logger for this module
+const debug = (0, debug_1.default)('apollo');
+// Determine if running on client
+const isClient = typeof window !== 'undefined';
+/**
+ * Get JWT secret from environment variables
+ * @returns {Uint8Array} Secret key for JWT signing
+ */
+const getJwtSecret = () => {
+    try {
+        const jwtSecret = process.env.HASURA_JWT_SECRET || '{"type":"HS256","key":"your-secret-key"}';
+        // Parse JWT configuration (may be in JSON format)
+        let secretKey;
+        try {
+            const jwtConfig = typeof jwtSecret === 'string' ? JSON.parse(jwtSecret) : jwtSecret;
+            secretKey = jwtConfig.key;
+            if (!secretKey) {
+                throw new Error('JWT key not found in configuration');
+            }
+        }
+        catch (e) {
+            // If failed to parse as JSON, use as string
+            secretKey = jwtSecret;
+        }
+        // Convert key to Uint8Array (required for jose)
+        return new TextEncoder().encode(secretKey);
+    }
+    catch (error) {
+        debug('apollo', '❌ Error getting JWT secret:', error);
+        throw error;
+    }
+};
+exports.getJwtSecret = getJwtSecret;
+/**
+ * Create Apollo Client
+ *
+ * @param {Object} options - Options for creating the client
+ * @param {boolean} options.ws - Use WebSocket connection
+ * @param {string} options.token - JWT token for authorization
+ * @param {string} options.secret - Admin secret for Hasura
+ * @returns {ApolloClient} Apollo Client
+ */
+function createClient(options = {}) {
+    // Default values
+    const { url = process.env.NEXT_PUBLIC_HASURA_GRAPHQL_URL, ws = false, token = undefined, secret = process.env.HASURA_ADMIN_SECRET } = options;
+    if (!url) {
+        throw new Error('❌ options.url or NEXT_PUBLIC_HASURA_GRAPHQL_URL not defined');
+    }
+    debug('apollo', '🔌 Creating Apollo client with endpoint:', url);
+    // HTTP connection without authorization
+    const publicHttpLink = new client_1.HttpLink({
+        uri: url,
+        fetch: cross_fetch_1.default,
+    });
+    // Create auth link with JWT token
+    const authLink = token
+        ? (0, context_1.setContext)((_, { headers }) => {
+            return {
+                headers: Object.assign(Object.assign({}, headers), { Authorization: `Bearer ${token}` })
+            };
+        })
+        : client_1.ApolloLink.from([]);
+    // Choose link based on token or secret availability
+    let httpLink;
+    if (token) {
+        // If token provided, use it for authorization
+        httpLink = client_1.ApolloLink.from([authLink, publicHttpLink]);
+    }
+    else if (secret) {
+        // If no token but admin secret exists, use it
+        httpLink = new client_1.HttpLink({
+            uri: url,
+            fetch: cross_fetch_1.default,
+            headers: {
+                'x-hasura-admin-secret': secret || ''
+            }
+        });
+        ;
+    }
+    else {
+        // If neither token nor secret, use public access
+        httpLink = publicHttpLink;
+    }
+    // Create link splitter for queries
+    let splitLink = httpLink;
+    // If WebSocket connection needed and we're in browser
+    if (ws && isClient) {
+        const wsEndpoint = url.replace('http', 'ws').replace('https', 'wss');
+        // Configure connection parameters
+        const connectionParams = {};
+        if (token) {
+            // If token provided, use it for WebSocket authorization
+            connectionParams.headers = {
+                Authorization: `Bearer ${token}`,
+            };
+        }
+        else if (secret) {
+            // If no token but admin secret exists, use it
+            connectionParams.headers = {
+                'x-hasura-admin-secret': secret,
+            };
+        }
+        // Create WebSocket client
+        const wsLink = new subscriptions_1.GraphQLWsLink((0, graphql_ws_1.createClient)({
+            url: wsEndpoint,
+            connectionParams: () => connectionParams
+        }));
+        // Split requests: WebSocket for subscriptions, HTTP for others
+        splitLink = (0, client_1.split)(({ query }) => {
+            const definition = (0, utilities_1.getMainDefinition)(query);
+            return (definition.kind === 'OperationDefinition' &&
+                definition.operation === 'subscription');
+        }, wsLink, httpLink);
+    }
+    // Create Apollo Client
+    return new client_1.ApolloClient({
+        link: splitLink,
+        cache: new client_1.InMemoryCache(),
+        defaultOptions: {
+            watchQuery: {
+                fetchPolicy: 'network-only',
+                errorPolicy: 'all',
+            },
+            query: {
+                fetchPolicy: 'network-only',
+                errorPolicy: 'all',
+            },
+            mutate: {
+                errorPolicy: 'all',
+            },
+        }
+    });
+}
+// Default client instance
+let clientInstance = null;
+/**
+ * Get or create Apollo client instance
+ * @param options Client options
+ * @returns Apollo client instance
+ */
+function getClient(options = {}) {
+    if (!clientInstance) {
+        clientInstance = createClient(options);
+    }
+    return clientInstance;
+}
+/**
+ * React hook to get Apollo client instance
+ * @returns Apollo client instance
+ */
+function useClient(options) {
+    return (0, react_1.useMemo)(() => createClient(options), [options]);
+}
+const CHECK_CONNECTION = (0, client_1.gql) `
+query CheckConnection {
+  __schema {
+    queryType {
+      name
+    }
+  }
+}
+`;
+/**
+ * Check connection to Hasura GraphQL endpoint
+ * @returns {Promise<boolean>} True if connection is successful
+ */
+function checkConnection() {
+    return __awaiter(this, arguments, void 0, function* (client = getClient()) {
+        var _a, _b, _c;
+        const result = yield client.query({ query: CHECK_CONNECTION });
+        return !!((_c = (_b = (_a = result.data) === null || _a === void 0 ? void 0 : _a.__schema) === null || _b === void 0 ? void 0 : _b.queryType) === null || _c === void 0 ? void 0 : _c.name);
+    });
+}
+exports.default = {
+    createClient,
+    getClient,
+    getJwtSecret: exports.getJwtSecret,
+    checkConnection
+};

package/dist/lib/debug.d.ts

@@ -0,0 +1,12 @@
+export type DebuggerFunction = (...args: any[]) => void;
+/**
+ * Debug utility factory.
+ *
+ * Always returns a debugger function for the specified namespace.
+ * If no namespace is provided, uses 'app' as the default.
+ *
+ * @param namespace - Namespace for the debugger.
+ * @returns A debugger function for the specified namespace.
+ */
+declare function Debug(namespace?: string): DebuggerFunction;
+export default Debug;

package/dist/lib/debug.js

@@ -0,0 +1,24 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const debug_1 = __importDefault(require("debug"));
+// @ts-ignore
+const package_json_1 = __importDefault(require("../package.json")); // Using relative path
+// Initialize root debugger using package name
+const rootDebug = (0, debug_1.default)(package_json_1.default.shortName || package_json_1.default.name);
+/**
+ * Debug utility factory.
+ *
+ * Always returns a debugger function for the specified namespace.
+ * If no namespace is provided, uses 'app' as the default.
+ *
+ * @param namespace - Namespace for the debugger.
+ * @returns A debugger function for the specified namespace.
+ */
+function Debug(namespace) {
+    // Return the debugger function for that namespace, defaulting to 'app'
+    return rootDebug.extend(namespace || 'app');
+}
+exports.default = Debug;

package/dist/lib/generator.d.ts

@@ -0,0 +1,33 @@
+import { DocumentNode } from '@apollo/client/core';
+export type GenerateOperation = 'query' | 'subscription' | 'insert' | 'update' | 'delete';
+export interface GenerateOptions {
+    operation: GenerateOperation;
+    table: string;
+    where?: Record<string, any>;
+    returning?: (string | Record<string, any>)[] | Record<string, any> | string;
+    aggregate?: Record<string, any>;
+    object?: Record<string, any>;
+    objects?: Record<string, any>[];
+    pk_columns?: Record<string, any>;
+    _set?: Record<string, any>;
+    limit?: number;
+    offset?: number;
+    order_by?: Record<string, any>[] | Record<string, any>;
+    fragments?: string[];
+    variables?: Record<string, any>;
+    varCounter?: number;
+}
+export interface GenerateResult {
+    queryString: string;
+    query: DocumentNode;
+    variables: Record<string, any>;
+    varCounter: number;
+}
+/**
+ * Creates a GraphQL query generator based on the provided schema.
+ *
+ * @param schema - The GraphQL schema in schema.json format.
+ * @returns A function to generate queries.
+ */
+export declare function Generator(schema: any): (opts: GenerateOptions) => GenerateResult;
+export default Generator;