example app

Author: izadoesdev

biome.jsonc

@@ -1,45 +1,45 @@
 {
-  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
-  "extends": ["ultracite"],
-  "files": {
-    "includes": ["!benchmark.ts"]
-  },
-  "formatter": {
-    "enabled": true,
-    "indentWidth": 2,
-    "indentStyle": "tab"
-  },
-  "linter": {
-    "rules": {
-      "complexity": {
-        "noExcessiveCognitiveComplexity": {
-          "level": "warn",
-          "options": {
-            "maxAllowedComplexity": 50
-          }
-        }
-      }
-    }
-  },
-  "overrides": [
-    {
-      "linter": {
-        "rules": {
-          "suspicious": {
-            "noConsole": "off",
-            "noExplicitAny": "off"
-          },
-          "style": {
-            "noMagicNumbers": "off"
-          },
-          "complexity": {
-            "useLiteralKeys": "off"
-          },
-          "correctness": {
-            "noUnusedVariables": "off"
-          }
-        }
-      }
-    }
-  ]
+	"$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
+	"extends": ["ultracite"],
+	"files": {
+		"includes": ["!benchmark.ts"]
+	},
+	"formatter": {
+		"enabled": true,
+		"indentWidth": 2,
+		"indentStyle": "tab"
+	},
+	"linter": {
+		"rules": {
+			"complexity": {
+				"noExcessiveCognitiveComplexity": {
+					"level": "warn",
+					"options": {
+						"maxAllowedComplexity": 50
+					}
+				}
+			}
+		}
+	},
+	"overrides": [
+		{
+			"linter": {
+				"rules": {
+					"suspicious": {
+						"noConsole": "off",
+						"noExplicitAny": "off"
+					},
+					"style": {
+						"noMagicNumbers": "off"
+					},
+					"complexity": {
+						"useLiteralKeys": "off"
+					},
+					"correctness": {
+						"noUnusedVariables": "off"
+					}
+				}
+			}
+		}
+	]
 }

bun.lock

@@ -0,0 +1,41 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

example/.gitignore

@@ -0,0 +1,52 @@
+# Keypal Example App
+
+A comprehensive Next.js example application demonstrating [keypal](https://github.com/izadoesdev/keypal) - a TypeScript library for secure API key management.
+
+## Features Demonstrated
+
+This example showcases all major features of keypal:
+
+- **API Key Management**: Create, list, enable/disable, rotate, and revoke API keys
+- **Key Verification**: Automatic key extraction from headers and verification
+- **Scope-based Permissions**: Fine-grained access control with scopes
+- **Usage Tracking**: Monitor when and how keys are used
+- **Audit Logging**: Track all key operations with full context
+- **Multiple Storage Backends**: Memory, Redis, and Drizzle ORM adapters
+- **Resource-level Permissions**: Granular permissions for specific resources
+
+## Getting Started
+
+### Prerequisites
+
+- [Bun](https://bun.sh) (recommended) or Node.js 18+
+- Redis (optional, for Redis storage example)
+- PostgreSQL (optional, for Drizzle ORM example)
+
+### Installation
+
+```bash
+# Install dependencies
+bun install
+
+# Run the development server
+bun dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to see the example app.
+
+## Pages
+
+- **Home** (`/`) - Overview and getting started
+- **API Keys** (`/api-keys`) - Manage API keys
+- **Create Key** (`/api-keys/create`) - Create new API keys
+- **Key Details** (`/api-keys/[id]`) - View and manage individual keys
+- **Verify Keys** (`/verify`) - Test key verification
+- **Scopes** (`/scopes`) - Demonstrate scope-based permissions
+- **Audit Logs** (`/audit-logs`) - View audit trail
+- **Storage Examples** (`/storage`) - Compare different storage backends
+
+## Learn More
+
+- [Keypal Documentation](../README.md) - Full API documentation
+- [Keypal GitHub](https://github.com/izadoesdev/keypal) - Source code and issues
+- [Next.js Documentation](https://nextjs.org/docs) - Next.js features and API

example/README.md

@@ -0,0 +1,122 @@
+"use server";
+
+import { memoryKeys } from "@/lib/keys";
+import type { PermissionScope } from "../../src/types/permissions-types";
+
+export async function createApiKey(options: {
+	ownerId: string;
+	name?: string;
+	scopes?: PermissionScope[];
+	resources?: Record<string, string[]>;
+	expiresAt?: string;
+}) {
+	try {
+		const { key, record } = await memoryKeys.create({
+			ownerId: options.ownerId,
+			name: options.name,
+			scopes: options.scopes ?? ["read"],
+			resources: options.resources,
+			expiresAt: options.expiresAt || null,
+		});
+
+		return { success: true, key, record };
+	} catch (error) {
+		return { success: false, error: String(error) };
+	}
+}
+
+export async function listApiKeys(ownerId: string) {
+	try {
+		const keys = await memoryKeys.list(ownerId);
+		return { success: true, keys };
+	} catch (error) {
+		return { success: false, error: String(error) };
+	}
+}
+
+export async function verifyApiKey(key: string) {
+	try {
+		const result = await memoryKeys.verify(key);
+		return result;
+	} catch (error) {
+		return { valid: false, error: String(error) };
+	}
+}
+
+export async function revokeApiKey(id: string) {
+	try {
+		await memoryKeys.revoke(id);
+		return { success: true };
+	} catch (error) {
+		return { success: false, error: String(error) };
+	}
+}
+
+export async function enableApiKey(id: string) {
+	try {
+		await memoryKeys.enable(id);
+		return { success: true };
+	} catch (error) {
+		return { success: false, error: String(error) };
+	}
+}
+
+export async function disableApiKey(id: string) {
+	try {
+		await memoryKeys.disable(id);
+		return { success: true };
+	} catch (error) {
+		return { success: false, error: String(error) };
+	}
+}
+
+export async function getAuditLogs(keyId?: string, ownerId?: string) {
+	try {
+		const logs = await memoryKeys.getLogs({ keyId, ownerId, limit: 50 });
+		return { success: true, logs };
+	} catch (error) {
+		return { success: false, error: String(error) };
+	}
+}
+
+export async function rotateApiKey(id: string) {
+	try {
+		const result = await memoryKeys.rotate(id);
+		return { success: true, ...result };
+	} catch (error) {
+		return { success: false, error: String(error) };
+	}
+}
+
+export async function verifyApiKeyWithScopes(
+	key: string,
+	requiredScopes?: PermissionScope[],
+	resource?: string
+) {
+	try {
+		const result = await memoryKeys.verify(key);
+		if (!(result.valid && result.record)) {
+			return result;
+		}
+
+		// Check scopes if required
+		if (requiredScopes && requiredScopes.length > 0) {
+			const hasAllScopes = memoryKeys.hasAllScopes(
+				result.record,
+				requiredScopes,
+				resource ? { resource } : undefined
+			);
+			if (!hasAllScopes) {
+				return {
+					valid: false,
+					error: "Insufficient permissions",
+					errorCode: "INSUFFICIENT_PERMISSIONS",
+				};
+			}
+		}
+
+		return result;
+	} catch (error) {
+		return { valid: false, error: String(error) };
+	}
+}