@superfunctions/auth 0.1.0

package/README.md

@@ -0,0 +1,156 @@
+# @superfunctions/auth
+
+Framework-agnostic authentication abstraction layer for Superfunctions libraries.
+
+## Overview
+
+`@superfunctions/auth` provides a standardized interface for authentication that works across any HTTP framework. Libraries can accept any auth provider conforming to this abstraction, and auth library authors can build implementations that work everywhere.
+
+## Installation
+
+```bash
+npm install @superfunctions/auth
+```
+
+## Core Concepts
+
+### AuthProvider Interface
+
+All auth implementations must implement the `AuthProvider` interface:
+
+```typescript
+interface AuthProvider<TSession extends AuthSession = AuthSession> {
+  authenticate(request: Request): Promise<TSession | null>;
+  authorize?(session: TSession, resourceId: string): Promise<boolean>;
+  revoke?(sessionId: string): Promise<void>;
+}
+```
+
+### AuthSession
+
+Authentication results return an `AuthSession`:
+
+```typescript
+interface AuthSession {
+  id: string;              // Unique identifier
+  type: string;            // Auth type: 'api-key', 'jwt', 'oauth', etc.
+  resourceIds: string[];   // Resources this session can access
+  scopes?: string[];       // Optional permissions
+  expiresAt?: Date;        // Optional expiration
+  metadata?: any;          // Optional additional data
+}
+```
+
+## Usage
+
+### For Library Authors
+
+Accept auth providers in your library:
+
+```typescript
+import { createRouter } from '@superfunctions/http';
+import { createAuthMiddleware, type AuthProvider } from '@superfunctions/auth';
+
+export function createMyLibrary(config: {
+  auth?: AuthProvider;
+  // ... other config
+}) {
+  const middleware = config.auth 
+    ? [createAuthMiddleware(config.auth)]
+    : [];
+
+  return createRouter({
+    middleware,
+    routes: [...]
+  });
+}
+```
+
+### For Auth Library Authors
+
+Implement the `AuthProvider` interface:
+
+```typescript
+import type { AuthProvider, AuthSession } from '@superfunctions/auth';
+
+export function createMyAuth(config: MyAuthConfig): AuthProvider {
+  return {
+    async authenticate(request: Request): Promise<AuthSession | null> {
+      const token = request.headers.get('authorization');
+      // Validate token and return session
+      return {
+        id: 'user_123',
+        type: 'jwt',
+        resourceIds: ['project_abc'],
+      };
+    },
+    
+    async authorize(session: AuthSession, resourceId: string): Promise<boolean> {
+      return session.resourceIds.includes(resourceId);
+    },
+  };
+}
+```
+
+### For Application Developers
+
+Use any conforming auth library:
+
+```typescript
+import { createMyLibrary } from 'some-library';
+import { createAuthFn } from 'authfn'; // or any other auth library
+
+const auth = createAuthFn({
+  database: adapter,
+  // ... auth config
+});
+
+const library = createMyLibrary({
+  auth,
+  // ... other config
+});
+```
+
+## Middleware Helpers
+
+### createAuthMiddleware
+
+Creates middleware for `@superfunctions/http` routers:
+
+```typescript
+import { createAuthMiddleware } from '@superfunctions/auth';
+
+const authMiddleware = createAuthMiddleware(authProvider, {
+  skipPaths: ['/health', '/public'],
+  contextKey: 'auth', // default
+});
+```
+
+### createResourceAuthMiddleware
+
+Creates middleware for resource-level authorization:
+
+```typescript
+import { createResourceAuthMiddleware } from '@superfunctions/auth';
+
+const resourceAuth = createResourceAuthMiddleware(authProvider, {
+  resourceHeader: 'x-project-id',
+  contextKey: 'auth',
+});
+```
+
+## Error Types
+
+- `AuthError` - Base error class
+- `AuthenticationError` - Authentication failed (401)
+- `AuthorizationError` - Access denied (403)
+- `InvalidCredentialsError` - Invalid credentials (401)
+- `ExpiredCredentialsError` - Credentials expired (401)
+
+## Examples
+
+See the [authfn](../../authfn) library for a complete reference implementation.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@superfunctions/auth",
+  "version": "0.1.0",
+  "description": "Framework-agnostic authentication abstraction layer for Superfunctions libraries",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "lint": "echo 'lint not configured'",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "auth",
+    "authentication",
+    "authorization",
+    "framework-agnostic",
+    "api-keys",
+    "superfunctions"
+  ],
+  "author": "21n",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/21nCo/super-functions/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/21nCo/super-functions.git",
+    "directory": "packages/auth"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.2.4"
+  }
+}