@markwharton/pwa-core 1.2.1 → 1.4.0

package/dist/__tests__/server/storage/client.test.js

@@ -0,0 +1,173 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+// Create mock functions
+const mockCreateTable = vitest_1.vi.fn();
+const mockFromConnectionString = vitest_1.vi.fn();
+// Mock @azure/data-tables
+vitest_1.vi.mock('@azure/data-tables', () => {
+    class MockTableClient {
+        constructor() {
+            this.createTable = mockCreateTable;
+        }
+    }
+    MockTableClient.fromConnectionString = mockFromConnectionString;
+    return {
+        TableClient: MockTableClient,
+        TableServiceClient: class MockTableServiceClient {
+        }
+    };
+});
+// Mock @azure/identity
+vitest_1.vi.mock('@azure/identity', () => ({
+    DefaultAzureCredential: class MockDefaultAzureCredential {
+    }
+}));
+(0, vitest_1.describe)('Storage client', () => {
+    (0, vitest_1.beforeEach)(() => {
+        vitest_1.vi.resetModules();
+        vitest_1.vi.clearAllMocks();
+        mockCreateTable.mockResolvedValue(undefined);
+        mockFromConnectionString.mockReturnValue({
+            createTable: vitest_1.vi.fn().mockResolvedValue(undefined)
+        });
+        // Reset environment
+        delete process.env.STORAGE_ACCOUNT_NAME;
+        delete process.env.AzureWebJobsStorage;
+    });
+    (0, vitest_1.describe)('initStorage', () => {
+        (0, vitest_1.it)('accepts configuration object', async () => {
+            const { initStorage, useManagedIdentity } = await Promise.resolve().then(() => __importStar(require('../../../server/storage/client')));
+            initStorage({ accountName: 'myaccount' });
+            (0, vitest_1.expect)(useManagedIdentity()).toBe(true);
+        });
+        (0, vitest_1.it)('accepts connection string', async () => {
+            const { initStorage, useManagedIdentity } = await Promise.resolve().then(() => __importStar(require('../../../server/storage/client')));
+            initStorage({ connectionString: 'DefaultEndpointsProtocol=https;AccountName=test' });
+            (0, vitest_1.expect)(useManagedIdentity()).toBe(false);
+        });
+    });
+    (0, vitest_1.describe)('initStorageFromEnv', () => {
+        (0, vitest_1.it)('reads STORAGE_ACCOUNT_NAME', async () => {
+            process.env.STORAGE_ACCOUNT_NAME = 'testaccount';
+            const { initStorageFromEnv, useManagedIdentity } = await Promise.resolve().then(() => __importStar(require('../../../server/storage/client')));
+            initStorageFromEnv();
+            (0, vitest_1.expect)(useManagedIdentity()).toBe(true);
+        });
+        (0, vitest_1.it)('reads AzureWebJobsStorage', async () => {
+            process.env.AzureWebJobsStorage = 'UseDevelopmentStorage=true';
+            const { initStorageFromEnv, useManagedIdentity } = await Promise.resolve().then(() => __importStar(require('../../../server/storage/client')));
+            initStorageFromEnv();
+            (0, vitest_1.expect)(useManagedIdentity()).toBe(false);
+        });
+    });
+    (0, vitest_1.describe)('useManagedIdentity', () => {
+        (0, vitest_1.it)('returns true when accountName is set without development storage', async () => {
+            const { initStorage, useManagedIdentity } = await Promise.resolve().then(() => __importStar(require('../../../server/storage/client')));
+            initStorage({ accountName: 'prodaccount' });
+            (0, vitest_1.expect)(useManagedIdentity()).toBe(true);
+        });
+        (0, vitest_1.it)('returns false when using development storage', async () => {
+            const { initStorage, useManagedIdentity } = await Promise.resolve().then(() => __importStar(require('../../../server/storage/client')));
+            initStorage({
+                accountName: 'devaccount',
+                connectionString: 'UseDevelopmentStorage=true'
+            });
+            (0, vitest_1.expect)(useManagedIdentity()).toBe(false);
+        });
+        (0, vitest_1.it)('returns false when only connection string is set', async () => {
+            const { initStorage, useManagedIdentity } = await Promise.resolve().then(() => __importStar(require('../../../server/storage/client')));
+            initStorage({ connectionString: 'DefaultEndpointsProtocol=https' });
+            (0, vitest_1.expect)(useManagedIdentity()).toBe(false);
+        });
+    });
+    (0, vitest_1.describe)('getTableClient', () => {
+        (0, vitest_1.it)('throws if storage not configured', async () => {
+            const { getTableClient } = await Promise.resolve().then(() => __importStar(require('../../../server/storage/client')));
+            await (0, vitest_1.expect)(getTableClient('test')).rejects.toThrow('Storage not configured. Set STORAGE_ACCOUNT_NAME or AzureWebJobsStorage.');
+        });
+        (0, vitest_1.it)('creates table client with managed identity', async () => {
+            const { initStorage, getTableClient, clearTableClientCache } = await Promise.resolve().then(() => __importStar(require('../../../server/storage/client')));
+            initStorage({ accountName: 'testaccount' });
+            clearTableClientCache();
+            const client = await getTableClient('mytable');
+            (0, vitest_1.expect)(client).toBeDefined();
+        });
+        (0, vitest_1.it)('creates table client with connection string', async () => {
+            const { initStorage, getTableClient, clearTableClientCache } = await Promise.resolve().then(() => __importStar(require('../../../server/storage/client')));
+            initStorage({ connectionString: 'DefaultEndpointsProtocol=https;AccountName=test' });
+            clearTableClientCache();
+            await getTableClient('mytable');
+            (0, vitest_1.expect)(mockFromConnectionString).toHaveBeenCalledWith('DefaultEndpointsProtocol=https;AccountName=test', 'mytable');
+        });
+        (0, vitest_1.it)('caches table client', async () => {
+            const { initStorage, getTableClient, clearTableClientCache } = await Promise.resolve().then(() => __importStar(require('../../../server/storage/client')));
+            initStorage({ accountName: 'testaccount' });
+            clearTableClientCache();
+            const client1 = await getTableClient('mytable');
+            const client2 = await getTableClient('mytable');
+            (0, vitest_1.expect)(client1).toBe(client2);
+        });
+        (0, vitest_1.it)('handles 409 conflict (table exists)', async () => {
+            mockCreateTable.mockRejectedValue({ statusCode: 409 });
+            const { initStorage, getTableClient, clearTableClientCache } = await Promise.resolve().then(() => __importStar(require('../../../server/storage/client')));
+            initStorage({ accountName: 'testaccount' });
+            clearTableClientCache();
+            // Should not throw
+            const client = await getTableClient('existingtable');
+            (0, vitest_1.expect)(client).toBeDefined();
+        });
+        (0, vitest_1.it)('throws on other errors', async () => {
+            mockCreateTable.mockRejectedValue({ statusCode: 500, message: 'Server error' });
+            const { initStorage, getTableClient, clearTableClientCache } = await Promise.resolve().then(() => __importStar(require('../../../server/storage/client')));
+            initStorage({ accountName: 'testaccount' });
+            clearTableClientCache();
+            await (0, vitest_1.expect)(getTableClient('mytable')).rejects.toMatchObject({ statusCode: 500 });
+        });
+    });
+    (0, vitest_1.describe)('clearTableClientCache', () => {
+        (0, vitest_1.it)('clears cached clients', async () => {
+            const { initStorage, getTableClient, clearTableClientCache } = await Promise.resolve().then(() => __importStar(require('../../../server/storage/client')));
+            initStorage({ accountName: 'testaccount' });
+            clearTableClientCache();
+            await getTableClient('mytable');
+            clearTableClientCache();
+            // After clearing, a new call should create a new client
+            const client2 = await getTableClient('mytable');
+            (0, vitest_1.expect)(client2).toBeDefined();
+        });
+    });
+});

package/dist/__tests__/server/storage/keys.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/server/storage/keys.test.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const keys_1 = require("../../../server/storage/keys");
+(0, vitest_1.describe)('generateRowKey', () => {
+    (0, vitest_1.it)('returns 32-character hex string', () => {
+        const key = (0, keys_1.generateRowKey)('test-identifier');
+        (0, vitest_1.expect)(key).toHaveLength(32);
+        (0, vitest_1.expect)(key).toMatch(/^[a-f0-9]+$/);
+    });
+    (0, vitest_1.it)('produces consistent hash for same input', () => {
+        const key1 = (0, keys_1.generateRowKey)('same-input');
+        const key2 = (0, keys_1.generateRowKey)('same-input');
+        (0, vitest_1.expect)(key1).toBe(key2);
+    });
+    (0, vitest_1.it)('produces different hashes for different inputs', () => {
+        const key1 = (0, keys_1.generateRowKey)('input-1');
+        const key2 = (0, keys_1.generateRowKey)('input-2');
+        (0, vitest_1.expect)(key1).not.toBe(key2);
+    });
+    (0, vitest_1.it)('handles empty string', () => {
+        const key = (0, keys_1.generateRowKey)('');
+        (0, vitest_1.expect)(key).toHaveLength(32);
+        (0, vitest_1.expect)(key).toMatch(/^[a-f0-9]+$/);
+    });
+    (0, vitest_1.it)('handles special characters', () => {
+        const key = (0, keys_1.generateRowKey)('https://example.com/path?query=value&foo=bar');
+        (0, vitest_1.expect)(key).toHaveLength(32);
+        (0, vitest_1.expect)(key).toMatch(/^[a-f0-9]+$/);
+    });
+    (0, vitest_1.it)('handles unicode characters', () => {
+        const key = (0, keys_1.generateRowKey)('日本語テスト');
+        (0, vitest_1.expect)(key).toHaveLength(32);
+        (0, vitest_1.expect)(key).toMatch(/^[a-f0-9]+$/);
+    });
+    (0, vitest_1.it)('handles long strings', () => {
+        const longString = 'x'.repeat(10000);
+        const key = (0, keys_1.generateRowKey)(longString);
+        (0, vitest_1.expect)(key).toHaveLength(32);
+        (0, vitest_1.expect)(key).toMatch(/^[a-f0-9]+$/);
+    });
+    (0, vitest_1.it)('produces URL-safe keys', () => {
+        const key = (0, keys_1.generateRowKey)('some-identifier');
+        // Row keys should not contain these characters
+        (0, vitest_1.expect)(key).not.toMatch(/[\/\\#?\s]/);
+    });
+});

package/dist/__tests__/shared/auth/types.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/shared/auth/types.test.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const types_1 = require("../../../shared/auth/types");
+(0, vitest_1.describe)('Auth type guards', () => {
+    const basePayload = {
+        iat: 1234567890,
+        exp: 1234567890 + 3600
+    };
+    (0, vitest_1.describe)('hasUsername', () => {
+        (0, vitest_1.it)('returns true for payload with username', () => {
+            const payload = { ...basePayload, username: 'testuser' };
+            (0, vitest_1.expect)((0, types_1.hasUsername)(payload)).toBe(true);
+        });
+        (0, vitest_1.it)('returns false for payload without username', () => {
+            (0, vitest_1.expect)((0, types_1.hasUsername)(basePayload)).toBe(false);
+        });
+        (0, vitest_1.it)('returns false for payload with non-string username', () => {
+            const payload = { ...basePayload, username: 123 };
+            (0, vitest_1.expect)((0, types_1.hasUsername)(payload)).toBe(false);
+        });
+        (0, vitest_1.it)('returns false for payload with empty string username', () => {
+            const payload = { ...basePayload, username: '' };
+            (0, vitest_1.expect)((0, types_1.hasUsername)(payload)).toBe(true); // Empty string is still a string
+        });
+    });
+    (0, vitest_1.describe)('hasRole', () => {
+        (0, vitest_1.it)('returns true for payload with role', () => {
+            const payload = {
+                ...basePayload,
+                authenticated: true,
+                tokenType: 'user',
+                role: 'admin'
+            };
+            (0, vitest_1.expect)((0, types_1.hasRole)(payload)).toBe(true);
+        });
+        (0, vitest_1.it)('returns false for payload without role', () => {
+            (0, vitest_1.expect)((0, types_1.hasRole)(basePayload)).toBe(false);
+        });
+        (0, vitest_1.it)('returns true for viewer role', () => {
+            const payload = {
+                ...basePayload,
+                authenticated: true,
+                tokenType: 'user',
+                role: 'viewer'
+            };
+            (0, vitest_1.expect)((0, types_1.hasRole)(payload)).toBe(true);
+        });
+    });
+    (0, vitest_1.describe)('isAdmin', () => {
+        (0, vitest_1.it)('returns true for admin role', () => {
+            const payload = {
+                ...basePayload,
+                authenticated: true,
+                tokenType: 'user',
+                role: 'admin'
+            };
+            (0, vitest_1.expect)((0, types_1.isAdmin)(payload)).toBe(true);
+        });
+        (0, vitest_1.it)('returns false for viewer role', () => {
+            const payload = {
+                ...basePayload,
+                authenticated: true,
+                tokenType: 'user',
+                role: 'viewer'
+            };
+            (0, vitest_1.expect)((0, types_1.isAdmin)(payload)).toBe(false);
+        });
+        (0, vitest_1.it)('returns false for payload without role', () => {
+            (0, vitest_1.expect)((0, types_1.isAdmin)(basePayload)).toBe(false);
+        });
+        (0, vitest_1.it)('returns false for payload with username but no role', () => {
+            const payload = { ...basePayload, username: 'testuser' };
+            (0, vitest_1.expect)((0, types_1.isAdmin)(payload)).toBe(false);
+        });
+    });
+});

package/dist/__tests__/shared/http/status.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/shared/http/status.test.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const status_1 = require("../../../shared/http/status");
+(0, vitest_1.describe)('HTTP_STATUS', () => {
+    (0, vitest_1.it)('has correct status codes', () => {
+        (0, vitest_1.expect)(status_1.HTTP_STATUS.OK).toBe(200);
+        (0, vitest_1.expect)(status_1.HTTP_STATUS.CREATED).toBe(201);
+        (0, vitest_1.expect)(status_1.HTTP_STATUS.NO_CONTENT).toBe(204);
+        (0, vitest_1.expect)(status_1.HTTP_STATUS.BAD_REQUEST).toBe(400);
+        (0, vitest_1.expect)(status_1.HTTP_STATUS.UNAUTHORIZED).toBe(401);
+        (0, vitest_1.expect)(status_1.HTTP_STATUS.FORBIDDEN).toBe(403);
+        (0, vitest_1.expect)(status_1.HTTP_STATUS.NOT_FOUND).toBe(404);
+        (0, vitest_1.expect)(status_1.HTTP_STATUS.CONFLICT).toBe(409);
+        (0, vitest_1.expect)(status_1.HTTP_STATUS.GONE).toBe(410);
+        (0, vitest_1.expect)(status_1.HTTP_STATUS.INTERNAL_ERROR).toBe(500);
+        (0, vitest_1.expect)(status_1.HTTP_STATUS.SERVICE_UNAVAILABLE).toBe(503);
+    });
+    (0, vitest_1.it)('is immutable (const assertion)', () => {
+        // TypeScript const assertion makes the object readonly
+        // This test verifies the values haven't been accidentally modified
+        const statusCodes = Object.values(status_1.HTTP_STATUS);
+        (0, vitest_1.expect)(statusCodes).toContain(200);
+        (0, vitest_1.expect)(statusCodes).toContain(404);
+        (0, vitest_1.expect)(statusCodes).toContain(500);
+    });
+});

package/dist/index.d.ts

@@ -1,5 +1,3 @@
 export * from './types';
-export * from './auth';
-export * from './http';
-export * from './storage';
-export * from './client';
+export * from './server';
+export * from './shared';

package/dist/index.js

@@ -14,9 +14,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-// Main entry point - re-export everything
+// Core types (universal)
 __exportStar(require("./types"), exports);
-__exportStar(require("./auth"), exports);
-__exportStar(require("./http"), exports);
-__exportStar(require("./storage"), exports);
-__exportStar(require("./client"), exports);
+// Server utilities (for convenience, but prefer ./server)
+__exportStar(require("./server"), exports);
+// Shared utilities
+__exportStar(require("./shared"), exports);
+// Note: Client utilities available via ./client subpath

package/dist/server/auth/apiKey.d.ts

@@ -0,0 +1,44 @@
+import { Result } from '../../types';
+/**
+ * API Key utilities for machine-to-machine authentication
+ */
+/**
+ * Extracts API key from the X-API-Key header.
+ * @param request - Request object with headers.get() method
+ * @returns The API key string, or null if not present
+ * @example
+ * const apiKey = extractApiKey(request);
+ */
+export declare function extractApiKey(request: {
+    headers: {
+        get(name: string): string | null;
+    };
+}): string | null;
+/**
+ * Hashes an API key using SHA-256 for secure storage.
+ * Store this hash in your database, never the raw key.
+ * @param apiKey - The raw API key to hash
+ * @returns The SHA-256 hash as a hex string
+ * @example
+ * const hash = hashApiKey(rawKey);
+ * await db.save({ apiKeyHash: hash });
+ */
+export declare function hashApiKey(apiKey: string): string;
+/**
+ * Validates an API key against a stored hash.
+ * @param apiKey - The API key from the request
+ * @param storedHash - The hash stored in your database
+ * @returns Result with ok=true if valid, or error message if invalid
+ * @example
+ * const result = validateApiKey(apiKey, user.apiKeyHash);
+ * if (!result.ok) return httpUnauthorized();
+ */
+export declare function validateApiKey(apiKey: string, storedHash: string): Result<void>;
+/**
+ * Generates a cryptographically secure API key.
+ * @returns A random 64-character hex string (32 bytes)
+ * @example
+ * const apiKey = generateApiKey();
+ * // Return to user once, store hash in database
+ */
+export declare function generateApiKey(): string;

package/dist/server/auth/apiKey.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractApiKey = extractApiKey;
+exports.hashApiKey = hashApiKey;
+exports.validateApiKey = validateApiKey;
+exports.generateApiKey = generateApiKey;
+const crypto_1 = require("crypto");
+const types_1 = require("../../types");
+/**
+ * API Key utilities for machine-to-machine authentication
+ */
+/**
+ * Extracts API key from the X-API-Key header.
+ * @param request - Request object with headers.get() method
+ * @returns The API key string, or null if not present
+ * @example
+ * const apiKey = extractApiKey(request);
+ */
+function extractApiKey(request) {
+    return request.headers.get('X-API-Key');
+}
+/**
+ * Hashes an API key using SHA-256 for secure storage.
+ * Store this hash in your database, never the raw key.
+ * @param apiKey - The raw API key to hash
+ * @returns The SHA-256 hash as a hex string
+ * @example
+ * const hash = hashApiKey(rawKey);
+ * await db.save({ apiKeyHash: hash });
+ */
+function hashApiKey(apiKey) {
+    return (0, crypto_1.createHash)('sha256').update(apiKey).digest('hex');
+}
+/**
+ * Validates an API key against a stored hash.
+ * @param apiKey - The API key from the request
+ * @param storedHash - The hash stored in your database
+ * @returns Result with ok=true if valid, or error message if invalid
+ * @example
+ * const result = validateApiKey(apiKey, user.apiKeyHash);
+ * if (!result.ok) return httpUnauthorized();
+ */
+function validateApiKey(apiKey, storedHash) {
+    const keyHash = hashApiKey(apiKey);
+    if (keyHash === storedHash) {
+        return (0, types_1.okVoid)();
+    }
+    return (0, types_1.err)('Invalid API key');
+}
+/**
+ * Generates a cryptographically secure API key.
+ * @returns A random 64-character hex string (32 bytes)
+ * @example
+ * const apiKey = generateApiKey();
+ * // Return to user once, store hash in database
+ */
+function generateApiKey() {
+    return (0, crypto_1.randomBytes)(32).toString('hex');
+}

package/dist/server/auth/index.d.ts

@@ -0,0 +1,2 @@
+export { initAuth, getJwtSecret, extractToken, validateToken, generateToken, generateLongLivedToken } from './token';
+export { extractApiKey, hashApiKey, validateApiKey, generateApiKey } from './apiKey';

package/dist/server/auth/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateApiKey = exports.validateApiKey = exports.hashApiKey = exports.extractApiKey = exports.generateLongLivedToken = exports.generateToken = exports.validateToken = exports.extractToken = exports.getJwtSecret = exports.initAuth = void 0;
+var token_1 = require("./token");
+Object.defineProperty(exports, "initAuth", { enumerable: true, get: function () { return token_1.initAuth; } });
+Object.defineProperty(exports, "getJwtSecret", { enumerable: true, get: function () { return token_1.getJwtSecret; } });
+Object.defineProperty(exports, "extractToken", { enumerable: true, get: function () { return token_1.extractToken; } });
+Object.defineProperty(exports, "validateToken", { enumerable: true, get: function () { return token_1.validateToken; } });
+Object.defineProperty(exports, "generateToken", { enumerable: true, get: function () { return token_1.generateToken; } });
+Object.defineProperty(exports, "generateLongLivedToken", { enumerable: true, get: function () { return token_1.generateLongLivedToken; } });
+var apiKey_1 = require("./apiKey");
+Object.defineProperty(exports, "extractApiKey", { enumerable: true, get: function () { return apiKey_1.extractApiKey; } });
+Object.defineProperty(exports, "hashApiKey", { enumerable: true, get: function () { return apiKey_1.hashApiKey; } });
+Object.defineProperty(exports, "validateApiKey", { enumerable: true, get: function () { return apiKey_1.validateApiKey; } });
+Object.defineProperty(exports, "generateApiKey", { enumerable: true, get: function () { return apiKey_1.generateApiKey; } });

package/dist/server/auth/token.d.ts

@@ -0,0 +1,56 @@
+import { Result } from '../../types';
+/**
+ * Initializes the JWT authentication system. Call once at application startup.
+ * @param secret - The JWT secret key (from environment variable)
+ * @param minLength - Minimum required secret length (default: 32)
+ * @throws Error if secret is missing or too short
+ * @example
+ * initAuth(process.env.JWT_SECRET);
+ */
+export declare function initAuth(secret: string | undefined, minLength?: number): void;
+/**
+ * Gets the configured JWT secret.
+ * @returns The JWT secret string
+ * @throws Error if initAuth() has not been called
+ */
+export declare function getJwtSecret(): string;
+/**
+ * Extracts the Bearer token from an Authorization header.
+ * @param authHeader - The Authorization header value
+ * @returns The token string, or null if not a valid Bearer token
+ * @example
+ * const token = extractToken(request.headers.get('Authorization'));
+ */
+export declare function extractToken(authHeader: string | null): string | null;
+/**
+ * Validates and decodes a JWT token.
+ * @typeParam T - The expected payload type (extends object)
+ * @param token - The JWT token string to validate
+ * @returns Result with decoded payload on success, or error message on failure
+ * @example
+ * const result = validateToken<UserPayload>(token);
+ * if (result.ok) {
+ *   console.log(result.data.username);
+ * }
+ */
+export declare function validateToken<T extends object>(token: string): Result<T>;
+/**
+ * Generates a signed JWT token with the given payload.
+ * @typeParam T - The payload type (extends object)
+ * @param payload - The data to encode in the token
+ * @param expiresIn - Token expiration time (default: '7d')
+ * @returns The signed JWT token string
+ * @example
+ * const token = generateToken({ userId: '123', role: 'admin' }, '1h');
+ */
+export declare function generateToken<T extends object>(payload: T, expiresIn?: string): string;
+/**
+ * Generates a long-lived JWT token for machine/API access.
+ * @typeParam T - The payload type (extends object)
+ * @param payload - The data to encode in the token
+ * @param expiresInDays - Token expiration in days (default: 3650 ≈ 10 years)
+ * @returns The signed JWT token string
+ * @example
+ * const apiToken = generateLongLivedToken({ machineId: 'server-1' });
+ */
+export declare function generateLongLivedToken<T extends object>(payload: T, expiresInDays?: number): string;

package/dist/server/auth/token.js

@@ -0,0 +1,104 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initAuth = initAuth;
+exports.getJwtSecret = getJwtSecret;
+exports.extractToken = extractToken;
+exports.validateToken = validateToken;
+exports.generateToken = generateToken;
+exports.generateLongLivedToken = generateLongLivedToken;
+const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
+const types_1 = require("../../types");
+/**
+ * JWT token utilities - works with any payload structure
+ * Use BaseJwtPayload or extend it for type safety
+ */
+let jwtSecret = null;
+/**
+ * Initializes the JWT authentication system. Call once at application startup.
+ * @param secret - The JWT secret key (from environment variable)
+ * @param minLength - Minimum required secret length (default: 32)
+ * @throws Error if secret is missing or too short
+ * @example
+ * initAuth(process.env.JWT_SECRET);
+ */
+function initAuth(secret, minLength = 32) {
+    if (!secret || secret.length < minLength) {
+        throw new Error(`JWT_SECRET must be at least ${minLength} characters`);
+    }
+    jwtSecret = secret;
+}
+/**
+ * Gets the configured JWT secret.
+ * @returns The JWT secret string
+ * @throws Error if initAuth() has not been called
+ */
+function getJwtSecret() {
+    if (!jwtSecret) {
+        throw new Error('Auth not initialized. Call initAuth() first.');
+    }
+    return jwtSecret;
+}
+/**
+ * Extracts the Bearer token from an Authorization header.
+ * @param authHeader - The Authorization header value
+ * @returns The token string, or null if not a valid Bearer token
+ * @example
+ * const token = extractToken(request.headers.get('Authorization'));
+ */
+function extractToken(authHeader) {
+    if (!authHeader?.startsWith('Bearer ')) {
+        return null;
+    }
+    return authHeader.slice(7);
+}
+/**
+ * Validates and decodes a JWT token.
+ * @typeParam T - The expected payload type (extends object)
+ * @param token - The JWT token string to validate
+ * @returns Result with decoded payload on success, or error message on failure
+ * @example
+ * const result = validateToken<UserPayload>(token);
+ * if (result.ok) {
+ *   console.log(result.data.username);
+ * }
+ */
+function validateToken(token) {
+    try {
+        const payload = jsonwebtoken_1.default.verify(token, getJwtSecret());
+        if (typeof payload === 'object' && payload !== null) {
+            return (0, types_1.ok)(payload);
+        }
+        return (0, types_1.err)('Invalid token payload');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Token validation failed';
+        return (0, types_1.err)(message);
+    }
+}
+/**
+ * Generates a signed JWT token with the given payload.
+ * @typeParam T - The payload type (extends object)
+ * @param payload - The data to encode in the token
+ * @param expiresIn - Token expiration time (default: '7d')
+ * @returns The signed JWT token string
+ * @example
+ * const token = generateToken({ userId: '123', role: 'admin' }, '1h');
+ */
+function generateToken(payload, expiresIn = '7d') {
+    return jsonwebtoken_1.default.sign(payload, getJwtSecret(), { expiresIn });
+}
+/**
+ * Generates a long-lived JWT token for machine/API access.
+ * @typeParam T - The payload type (extends object)
+ * @param payload - The data to encode in the token
+ * @param expiresInDays - Token expiration in days (default: 3650 ≈ 10 years)
+ * @returns The signed JWT token string
+ * @example
+ * const apiToken = generateLongLivedToken({ machineId: 'server-1' });
+ */
+function generateLongLivedToken(payload, expiresInDays = 3650) {
+    return jsonwebtoken_1.default.sign(payload, getJwtSecret(), { expiresIn: `${expiresInDays}d` });
+}

package/dist/server/http/index.d.ts

@@ -0,0 +1 @@
+export { badRequestResponse, unauthorizedResponse, forbiddenResponse, notFoundResponse, conflictResponse, handleFunctionError, isNotFoundError, isConflictError } from './responses';