@markwharton/pwa-core 1.2.0 → 1.3.0

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/__tests__/storage/client.test.d.ts

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

package/dist/__tests__/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('../../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('../../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('../../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('../../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('../../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('../../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('../../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('../../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('../../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('../../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('../../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('../../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('../../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('../../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__/storage/keys.test.d.ts

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

package/dist/__tests__/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("../../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__/types.test.d.ts

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

package/dist/__tests__/types.test.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const types_1 = require("../types");
+(0, vitest_1.describe)('Result helpers', () => {
+    (0, vitest_1.describe)('ok', () => {
+        (0, vitest_1.it)('creates success result with data', () => {
+            const result = (0, types_1.ok)({ name: 'test' });
+            (0, vitest_1.expect)(result.ok).toBe(true);
+            (0, vitest_1.expect)(result.data).toEqual({ name: 'test' });
+            (0, vitest_1.expect)(result.error).toBeUndefined();
+        });
+        (0, vitest_1.it)('works with primitive values', () => {
+            (0, vitest_1.expect)((0, types_1.ok)(42).data).toBe(42);
+            (0, vitest_1.expect)((0, types_1.ok)('hello').data).toBe('hello');
+            (0, vitest_1.expect)((0, types_1.ok)(true).data).toBe(true);
+        });
+        (0, vitest_1.it)('works with null', () => {
+            const result = (0, types_1.ok)(null);
+            (0, vitest_1.expect)(result.ok).toBe(true);
+            (0, vitest_1.expect)(result.data).toBeNull();
+        });
+    });
+    (0, vitest_1.describe)('okVoid', () => {
+        (0, vitest_1.it)('creates success result without data', () => {
+            const result = (0, types_1.okVoid)();
+            (0, vitest_1.expect)(result.ok).toBe(true);
+            (0, vitest_1.expect)(result.data).toBeUndefined();
+            (0, vitest_1.expect)(result.error).toBeUndefined();
+        });
+    });
+    (0, vitest_1.describe)('err', () => {
+        (0, vitest_1.it)('creates failure result with error message', () => {
+            const result = (0, types_1.err)('Something went wrong');
+            (0, vitest_1.expect)(result.ok).toBe(false);
+            (0, vitest_1.expect)(result.error).toBe('Something went wrong');
+            (0, vitest_1.expect)(result.data).toBeUndefined();
+            (0, vitest_1.expect)(result.statusCode).toBeUndefined();
+        });
+        (0, vitest_1.it)('creates failure result with status code', () => {
+            const result = (0, types_1.err)('Not found', 404);
+            (0, vitest_1.expect)(result.ok).toBe(false);
+            (0, vitest_1.expect)(result.error).toBe('Not found');
+            (0, vitest_1.expect)(result.statusCode).toBe(404);
+        });
+        (0, vitest_1.it)('excludes statusCode when not provided', () => {
+            const result = (0, types_1.err)('Error');
+            (0, vitest_1.expect)('statusCode' in result).toBe(false);
+        });
+        (0, vitest_1.it)('includes statusCode when provided', () => {
+            const result = (0, types_1.err)('Error', 500);
+            (0, vitest_1.expect)('statusCode' in result).toBe(true);
+            (0, vitest_1.expect)(result.statusCode).toBe(500);
+        });
+    });
+});

package/dist/auth/apiKey.d.ts

@@ -3,7 +3,11 @@ import { Result } from '../types';
  * API Key utilities for machine-to-machine authentication
  */
 /**
- * Extract API key from X-API-Key header
+ * 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: {
@@ -11,17 +15,30 @@ export declare function extractApiKey(request: {
     };
 }): string | null;
 /**
- * Hash an API key for secure storage
- * Store this hash, not the raw 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 });
  */
 export declare function hashApiKey(apiKey: string): string;
 /**
- * Validate API key against stored hash
- *
- * @returns Result indicating success or failure with error message
+ * 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>;
 /**
- * Generate a new API key (random 32-byte hex string)
+ * 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/auth/apiKey.js

@@ -10,22 +10,35 @@ const types_1 = require("../types");
  * API Key utilities for machine-to-machine authentication
  */
 /**
- * Extract API key from X-API-Key header
+ * 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');
 }
 /**
- * Hash an API key for secure storage
- * Store this hash, not the raw 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');
 }
 /**
- * Validate API key against stored hash
- *
- * @returns Result indicating success or failure with error message
+ * 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);
@@ -35,7 +48,11 @@ function validateApiKey(apiKey, storedHash) {
     return (0, types_1.err)('Invalid API key');
 }
 /**
- * Generate a new API key (random 32-byte hex string)
+ * 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/auth/token.d.ts

@@ -1,29 +1,56 @@
 import { Result } from '../types';
 /**
- * Initialize JWT secret - call once at startup
- * Fails fast if secret is missing or too short
+ * 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;
 /**
- * Get the JWT secret (throws if not initialized)
+ * Gets the configured JWT secret.
+ * @returns The JWT secret string
+ * @throws Error if initAuth() has not been called
  */
 export declare function getJwtSecret(): string;
 /**
- * Extract Bearer token from Authorization header
+ * 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;
 /**
- * Validate and decode a JWT token
- * Generic type allows project-specific payload shapes
- *
- * @returns Result with decoded payload or error message
+ * 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>;
 /**
- * Generate a JWT token with custom payload
+ * 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;
 /**
- * Generate a long-lived token (e.g., for machine/API access)
+ * 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/auth/token.js

@@ -17,8 +17,12 @@ const types_1 = require("../types");
  */
 let jwtSecret = null;
 /**
- * Initialize JWT secret - call once at startup
- * Fails fast if secret is missing or too short
+ * 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) {
@@ -27,7 +31,9 @@ function initAuth(secret, minLength = 32) {
     jwtSecret = secret;
 }
 /**
- * Get the JWT secret (throws if not initialized)
+ * Gets the configured JWT secret.
+ * @returns The JWT secret string
+ * @throws Error if initAuth() has not been called
  */
 function getJwtSecret() {
     if (!jwtSecret) {
@@ -36,7 +42,11 @@ function getJwtSecret() {
     return jwtSecret;
 }
 /**
- * Extract Bearer token from Authorization header
+ * 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 ')) {
@@ -45,10 +55,15 @@ function extractToken(authHeader) {
     return authHeader.slice(7);
 }
 /**
- * Validate and decode a JWT token
- * Generic type allows project-specific payload shapes
- *
- * @returns Result with decoded payload or error message
+ * 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 {
@@ -64,13 +79,25 @@ function validateToken(token) {
     }
 }
 /**
- * Generate a JWT token with custom payload
+ * 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 });
 }
 /**
- * Generate a long-lived token (e.g., for machine/API access)
+ * 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/auth/types.d.ts

@@ -32,14 +32,32 @@ export interface RoleTokenPayload extends BaseJwtPayload {
     viewerTokenId?: string;
 }
 /**
- * Type guard to check if payload has a username
+ * Type guard to check if a JWT payload contains a username field.
+ * @param payload - The JWT payload to check
+ * @returns True if payload has a string username field
+ * @example
+ * if (hasUsername(payload)) {
+ *   console.log(payload.username); // TypeScript knows username exists
+ * }
  */
 export declare function hasUsername(payload: BaseJwtPayload): payload is UsernameTokenPayload;
 /**
- * Type guard to check if payload has a role
+ * Type guard to check if a JWT payload contains a role field.
+ * @param payload - The JWT payload to check
+ * @returns True if payload has a role field
+ * @example
+ * if (hasRole(payload)) {
+ *   console.log(payload.role); // 'admin' | 'viewer'
+ * }
  */
 export declare function hasRole(payload: BaseJwtPayload): payload is RoleTokenPayload;
 /**
- * Type guard to check if payload is admin
+ * Checks if a JWT payload represents an admin user.
+ * @param payload - The JWT payload to check
+ * @returns True if payload has role='admin'
+ * @example
+ * if (!isAdmin(payload)) {
+ *   return httpForbidden('Admin access required');
+ * }
  */
 export declare function isAdmin(payload: BaseJwtPayload): boolean;

package/dist/auth/types.js

@@ -4,19 +4,37 @@ exports.hasUsername = hasUsername;
 exports.hasRole = hasRole;
 exports.isAdmin = isAdmin;
 /**
- * Type guard to check if payload has a username
+ * Type guard to check if a JWT payload contains a username field.
+ * @param payload - The JWT payload to check
+ * @returns True if payload has a string username field
+ * @example
+ * if (hasUsername(payload)) {
+ *   console.log(payload.username); // TypeScript knows username exists
+ * }
  */
 function hasUsername(payload) {
     return 'username' in payload && typeof payload.username === 'string';
 }
 /**
- * Type guard to check if payload has a role
+ * Type guard to check if a JWT payload contains a role field.
+ * @param payload - The JWT payload to check
+ * @returns True if payload has a role field
+ * @example
+ * if (hasRole(payload)) {
+ *   console.log(payload.role); // 'admin' | 'viewer'
+ * }
  */
 function hasRole(payload) {
     return 'role' in payload;
 }
 /**
- * Type guard to check if payload is admin
+ * Checks if a JWT payload represents an admin user.
+ * @param payload - The JWT payload to check
+ * @returns True if payload has role='admin'
+ * @example
+ * if (!isAdmin(payload)) {
+ *   return httpForbidden('Admin access required');
+ * }
  */
 function isAdmin(payload) {
     return hasRole(payload) && payload.role === 'admin';