@hkdigital/lib-core 0.4.56 → 0.4.58

package/dist/auth/jwt/README.md

@@ -0,0 +1,275 @@
+# JWT Utilities
+
+A comprehensive JSON Web Token (JWT) library for signing, verifying, and 
+decoding JWT tokens with proper error handling and type safety.
+
+## Features
+
+- **Sign tokens** with customizable algorithms and expiration
+- **Verify tokens** with signature validation and expiration checks
+- **Decode payloads** without verification for inspection purposes
+- **Generate secret keys** for HMAC algorithms
+- **Error handling** with specific error types for different failure modes
+- **Type safety** with JSDoc type annotations
+
+## Quick Start
+
+```javascript
+import { sign, verify, decodePayload, expiresAtUTC } from '$lib/auth/jwt.js';
+
+// Create a token
+const payload = { userId: 123, username: 'john' };
+const secret = 'your-secret-key';
+const token = sign(payload, secret);
+
+// Verify and decode
+const decoded = verify(token, secret);
+console.log(decoded.userId); // 123
+
+// Decode without verification (for inspection)
+const payload = decodePayload(token);
+console.log(payload.exp); // expiration timestamp
+
+// Get human-readable expiration
+const expiresAt = expiresAtUTC(payload);
+console.log(expiresAt); // "Sun, 01 Jan 2023 00:00:00 GMT"
+```
+
+## API Reference
+
+### sign(claims, secretOrPrivateKey, options?)
+
+Creates a JSON Web Token with the specified claims.
+
+**Parameters:**
+- `claims` (object) - JWT payload/claims
+- `secretOrPrivateKey` (string|Buffer) - Secret for HMAC or private key
+- `options` (object, optional) - Signing options
+
+**Options:**
+- `algorithm` (string) - Algorithm to use (default: 'HS512')
+- `expiresIn` (string|number) - Token expiration (default: '24h')
+- `issuer` (string) - Token issuer
+- `audience` (string) - Token audience
+- `subject` (string) - Token subject
+
+**Returns:** `string` - JWT token
+
+**Example:**
+```javascript
+const token = sign(
+  { userId: 123, role: 'admin' },
+  'secret-key',
+  { 
+    algorithm: 'HS256',
+    expiresIn: '1h',
+    issuer: 'my-app'
+  }
+);
+```
+
+### verify(token, secretOrPrivateKey, options?)
+
+Verifies and decodes a JWT token.
+
+**Parameters:**
+- `token` (string) - JWT token to verify
+- `secretOrPrivateKey` (string|Buffer) - Secret for HMAC or public key
+- `options` (object, optional) - Verification options
+
+**Options:**
+- `algorithms` (string[]) - Allowed algorithms (default: ['HS512'])
+- `issuer` (string) - Expected issuer
+- `audience` (string) - Expected audience
+- `ignoreExpiration` (boolean) - Skip expiration validation
+
+**Returns:** `object` - Decoded JWT payload
+
+**Throws:**
+- `TokenExpiredError` - Token has expired
+- `InvalidSignatureError` - Invalid signature
+- `JsonWebTokenError` - Other JWT validation errors
+- `NotBeforeError` - Token not yet valid
+
+**Example:**
+```javascript
+try {
+  const decoded = verify(token, 'secret-key');
+  console.log('User ID:', decoded.userId);
+} catch (error) {
+  if (error instanceof TokenExpiredError) {
+    console.log('Token expired at:', error.expiredAt);
+  }
+}
+```
+
+### decodePayload(token)
+
+Decodes JWT payload without verification. Useful for inspecting token claims
+before verification or when verification is not required.
+
+**Parameters:**
+- `token` (string) - JWT token to decode
+
+**Returns:** `object` - Decoded JWT payload
+
+**Throws:**
+- `Error` - Invalid token format or malformed payload
+
+**Example:**
+```javascript
+// Inspect token without verification
+const payload = decodePayload(token);
+console.log('Token expires:', payload.exp);
+console.log('Issued at:', payload.iat);
+
+// Check if token is expired before verification
+if (payload.exp && payload.exp < Date.now() / 1000) {
+  console.log('Token is expired');
+}
+```
+
+### expiresAtUTC(token)
+
+Converts the `exp` claim of a decoded token to a human-readable UTC string.
+
+**Parameters:**
+- `token` (object) - Decoded JWT payload with optional `exp` claim
+
+**Returns:** `string|null` - UTC string or null if no expiration
+
+**Example:**
+```javascript
+const payload = decodePayload(token);
+const expiresAt = expiresAtUTC(payload);
+
+if (expiresAt) {
+  console.log('Token expires at:', expiresAt);
+  // "Sun, 01 Jan 2023 00:00:00 GMT"
+} else {
+  console.log('Token never expires');
+}
+```
+
+## Error Types
+
+The library provides specific error types for different failure modes:
+
+### TokenExpiredError
+Thrown when a token has expired.
+- `message` - Error description
+- `expiredAt` - Date when token expired
+
+### InvalidSignatureError  
+Thrown when token signature is invalid.
+- `message` - Error description
+
+### JsonWebTokenError
+Thrown for general JWT validation errors.
+- `message` - Error description
+
+### NotBeforeError
+Thrown when token is not yet valid (nbf claim).
+- `message` - Error description
+- `date` - Date when token becomes valid
+
+## Security Best Practices
+
+### Secret Key Management
+- Use cryptographically strong secrets (256+ bits for HMAC)
+- Store secrets securely (environment variables, key management services)
+- Rotate secrets regularly
+- Never commit secrets to version control
+
+```javascript
+import { generateSecretKeyForHmacBase58 } from '$lib/auth/jwt.js';
+
+// Generate a secure secret
+const secret = generateSecretKeyForHmacBase58();
+```
+
+### Token Validation
+- Always verify tokens before trusting claims
+- Use specific algorithm allowlists in verification
+- Validate issuer, audience, and other claims as needed
+- Handle expiration appropriately for your use case
+
+```javascript
+const decoded = verify(token, secret, {
+  algorithms: ['HS256'], // Only allow specific algorithms
+  issuer: 'trusted-issuer',
+  audience: 'my-app'
+});
+```
+
+### Token Storage
+- Store tokens securely (httpOnly cookies, secure storage)
+- Use short expiration times when possible
+- Implement token refresh mechanisms
+- Clear tokens on logout
+
+## Common Patterns
+
+### Token Inspection Middleware
+```javascript
+function inspectToken(token) {
+  try {
+    const payload = decodePayload(token);
+    const expiresAt = expiresAtUTC(payload);
+    
+    return {
+      isExpired: payload.exp && payload.exp < Date.now() / 1000,
+      expiresAt,
+      userId: payload.userId,
+      role: payload.role
+    };
+  } catch (error) {
+    return { isValid: false, error: error.message };
+  }
+}
+```
+
+### Token Refresh Check
+```javascript
+function shouldRefreshToken(token) {
+  const payload = decodePayload(token);
+  if (!payload.exp) return false;
+  
+  const now = Date.now() / 1000;
+  const timeUntilExpiry = payload.exp - now;
+  const refreshThreshold = 5 * 60; // 5 minutes
+  
+  return timeUntilExpiry < refreshThreshold && timeUntilExpiry > 0;
+}
+```
+
+### Safe Token Verification
+```javascript
+function safeVerifyToken(token, secret) {
+  try {
+    return { success: true, payload: verify(token, secret) };
+  } catch (error) {
+    return { 
+      success: false, 
+      error: error.constructor.name,
+      message: error.message 
+    };
+  }
+}
+```
+
+## Testing
+
+Run the JWT tests:
+
+```bash
+pnpm test:file src/lib/auth/jwt/
+```
+
+The test suite covers:
+- Token signing with various options
+- Token verification with different scenarios
+- Error handling for expired/invalid tokens
+- Payload decoding without verification
+- UTC time conversion
+- Edge cases and error conditions

package/dist/auth/jwt/util.d.ts

@@ -42,3 +42,19 @@ export function verify(token: string, secretOrPrivateKey: import("./typedef.js")
  * @returns {Error} - The corresponding internal error
  */
 export function castJwtError(error: Error): Error;
+/**
+ * Decodes the payload of a JSON Web Token without verification
+ *
+ * @param {string} token - A JSON Web Token
+ *
+ * @returns {object} claims - The decoded JWT payload
+ */
+export function decodePayload(token: string): object;
+/**
+ * Returns the "exp" (expiresAt) property of a token as UTC string
+ *
+ * @param {object} token - Decoded JWT payload/claims
+ *
+ * @returns {string|null} "expires at" as UTC string or null if no exp claim
+ */
+export function expiresAtUTC(token: object): string | null;

package/dist/auth/jwt/util.js

@@ -144,3 +144,51 @@ export function castJwtError(error) {
   // Return original error if not a known JWT error
   return error;
 }
+
+/**
+ * Decodes the payload of a JSON Web Token without verification
+ *
+ * @param {string} token - A JSON Web Token
+ *
+ * @returns {object} claims - The decoded JWT payload
+ */
+export function decodePayload(token) {
+  expect.notEmptyString(token);
+
+  const firstDot = token.indexOf('.');
+
+  if (firstDot === -1) {
+    throw new Error(
+      'Invalid token, missing [.] token as payload start indicator'
+    );
+  }
+
+  const lastDot = token.lastIndexOf('.');
+
+  if (lastDot === firstDot) {
+    throw new Error(
+      'Invalid token, missing second [.] token as payload end indicator'
+    );
+  }
+
+  const payload = token.slice(firstDot + 1, lastDot);
+
+  return JSON.parse(atob(payload));
+}
+
+/**
+ * Returns the "exp" (expiresAt) property of a token as UTC string
+ *
+ * @param {object} token - Decoded JWT payload/claims
+ *
+ * @returns {string|null} "expires at" as UTC string or null if no exp claim
+ */
+export function expiresAtUTC(token) {
+  expect.object(token);
+
+  if ('exp' in token) {
+    return new Date(1000 * token.exp).toUTCString();
+  }
+
+  return null;
+}

package/dist/auth/jwt.js

@@ -3,7 +3,7 @@
  *
  * @description
  * This module provides a clean API for JWT operations including signing,
- * verifying tokens, and generating secret keys.
+ * verifying tokens, decoding payloads, and generating secret keys.
  */
 
 export * from './jwt/util.js';

package/dist/generic/data/typedef.d.ts

@@ -1,3 +1,4 @@
+export * from "./util/typedef.js";
 declare const _default: {};
 export default _default;
 export type IterableTreeOptions = {

package/dist/generic/data/typedef.js

@@ -6,4 +6,6 @@
  * @property {boolean} outputIntermediateNodes
  */
 
+export * from './util/typedef.js';
+
 export default {};

package/dist/generic/data/util/README.md

@@ -0,0 +1,252 @@
+# Flat Tree Utilities
+
+Tree serialization and deserialization utilities that convert between 
+hierarchical tree structures and flat tree format (ft1).
+
+## Overview
+
+The flat tree utilities provide bidirectional conversion between:
+- **Hierarchical Trees**: Standard nested object structures with children
+- **Flat Tree Format (ft1)**: Compact serialized format with separate 
+  nodes and edges
+
+## Key Features
+
+- **Format Versioning**: ft1 format with forward compatibility
+- **Property Preservation**: Maintains original property names 
+  (`children`, `items`, etc.)
+- **Shared Reference Handling**: Uses WeakMap to track objects that 
+  appear multiple times
+- **ID Collision Avoidance**: No conflicts between user IDs and tree 
+  structure IDs
+- **Efficient Serialization**: Compact flat edge array format
+
+## API Reference
+
+### `buildTree(flatTree, options)`
+
+Converts ft1 flat tree format to hierarchical tree structure.
+
+**Parameters:**
+- `flatTree` - FlatTree object in ft1 format
+- `options` - Optional configuration object
+
+**Returns:** Reconstructed hierarchical tree or null
+
+**Example:**
+```javascript
+import { buildTree } from '$lib/generic/data/util/flat-tree.js';
+
+const flatTree = {
+  format: 'ft1',
+  properties: ['children'],
+  nodes: [
+    { id: 'root', name: 'Root' },
+    { id: 'child1', name: 'Child 1' }
+  ],
+  edges: [0, 0, 1]  // root->children->child1
+};
+
+const hierarchical = buildTree(flatTree);
+// Result: { id: 'root', name: 'Root', children: [{ id: 'child1', name: 'Child 1' }] }
+```
+
+### `flattenTree(hierarchicalTree, options)`
+
+Converts hierarchical tree to ft1 flat tree format.
+
+**Parameters:**
+- `hierarchicalTree` - Nested object structure with children
+- `options` - Optional configuration object
+  - `childrenKey` (default: 'children') - Primary children property name
+
+**Returns:** FlatTree object in ft1 format
+
+**Example:**
+```javascript
+import { flattenTree } from '$lib/generic/data/util/flat-tree.js';
+
+const hierarchical = {
+  id: 'root',
+  name: 'Root',
+  children: [
+    { id: 'child1', name: 'Child 1' }
+  ]
+};
+
+const flatTree = flattenTree(hierarchical);
+// Result: { format: 'ft1', properties: ['children'], nodes: [...], edges: [...] }
+```
+
+## ft1 Format Specification
+
+The ft1 format consists of four main components:
+
+### Format Structure
+
+```javascript
+{
+  format: 'ft1',           // Format version identifier
+  properties: string[],    // Array of property names used in edges
+  nodes: object[],         // Array of node objects (index 0 = root)
+  edges: number[]          // Flat array: [from, prop, to, from, prop, to, ...]
+}
+```
+
+### Properties Array
+
+Maps property indices to names for edge decoding:
+```javascript
+properties: ['children', 'items', 'metadata']
+//           index: 0      1       2
+```
+
+### Nodes Array
+
+Contains node data with children properties removed:
+```javascript
+nodes: [
+  { id: 'root', name: 'Root' },      // index 0 (always root)
+  { id: 'child1', name: 'Child 1' }, // index 1
+  { id: 'item1', name: 'Item 1' }    // index 2
+]
+```
+
+### Edges Array
+
+Flat array in groups of 3: `[from_index, property_index, to_index]`
+```javascript
+edges: [
+  0, 0, 1,  // root(0) -children(0)-> child1(1)
+  0, 1, 2   // root(0) -items(1)-> item1(2)
+]
+```
+
+## Shared Object References
+
+Objects that appear multiple times in the tree are automatically 
+handled using WeakMap tracking:
+
+```javascript
+const sharedNode = { id: 'shared', name: 'Shared' };
+
+const hierarchical = {
+  id: 'root',
+  children: [
+    { id: 'left', children: [sharedNode] },
+    { id: 'right', children: [sharedNode] }  // Same object reference
+  ]
+};
+
+const flattened = flattenTree(hierarchical);
+const rebuilt = buildTree(flattened);
+
+// Shared reference is preserved
+console.log(rebuilt.children[0].children[0] === rebuilt.children[1].children[0]); // true
+```
+
+## Property Detection
+
+The flattening process automatically detects child-containing properties:
+
+```javascript
+const tree = {
+  id: 'root',
+  children: [{ id: 'child1' }],  // Detected as child property
+  items: [{ id: 'item1' }],      // Detected as child property
+  metadata: 'string value'       // Not a child property (ignored)
+};
+```
+
+## Roundtrip Conversion
+
+The utilities maintain data integrity across roundtrip conversions:
+
+```javascript
+const original = { /* complex tree */ };
+const flattened = flattenTree(original);
+const rebuilt = buildTree(flattened);
+const reflattened = flattenTree(rebuilt);
+
+// Data integrity preserved
+console.log(JSON.stringify(flattened) === JSON.stringify(reflattened)); // true
+```
+
+## Error Handling
+
+The utilities provide clear error messages for invalid data:
+
+- **Unsupported format**: When format is not 'ft1'
+- **Invalid edges**: When edges array length is not multiple of 3
+- **Invalid indices**: When node or property indices are out of bounds
+- **Missing data**: When required fields are missing
+
+## Performance Considerations
+
+- **WeakMap Usage**: Efficient object reference tracking
+- **Flat Edge Array**: Compact memory usage for large trees
+- **Property Index Mapping**: Fast property name lookup
+- **No Deep Cloning**: Shallow copies preserve performance
+
+## Use Cases
+
+### Configuration Trees
+```javascript
+const config = {
+  server: {
+    children: [
+      { name: 'port', value: 3000 },
+      { name: 'host', value: 'localhost' }
+    ]
+  }
+};
+```
+
+### File System Trees
+```javascript
+const fileTree = {
+  path: '/',
+  children: [
+    { path: '/src', children: [{ path: '/src/index.js' }] },
+    { path: '/package.json' }
+  ]
+};
+```
+
+### Menu Structures
+```javascript
+const menu = {
+  title: 'Main',
+  items: [
+    { title: 'File', items: [{ title: 'New' }, { title: 'Open' }] },
+    { title: 'Edit', items: [{ title: 'Copy' }, { title: 'Paste' }] }
+  ]
+};
+```
+
+## Migration Guide
+
+### From Legacy Formats
+
+If migrating from older tree formats, ensure your data structure 
+follows these patterns:
+
+1. **Root Object**: Single root node with child properties
+2. **Array Children**: Child properties should be arrays of objects
+3. **Object Structure**: Each node should be a plain object
+4. **No Circular References**: Avoid circular references (use shared 
+   objects instead)
+
+### Type Safety
+
+Use JSDoc type annotations for better development experience:
+
+```javascript
+/**
+ * @param {import('./typedef.js').FlatTree<MyNodeType>} flatTree
+ * @returns {MyNodeType|null}
+ */
+function processTree(flatTree) {
+  return buildTree(flatTree);
+}
+```

package/dist/generic/data/util/flat-tree.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Build a hierarchical tree from ft1 flat tree format
+ *
+ * @template {object} T
+ * @param {import('./typedef.js').FlatTree<T>} flatTree - Flat tree data
+ *
+ * @returns {T|null} reconstructed hierarchical tree or null
+ */
+export function buildTree<T extends object>(flatTree: import("./typedef.js").FlatTree<T>): T | null;
+/**
+ * Flatten a hierarchical tree into ft1 flat tree format
+ *
+ * @template {object} T
+ * @param {T} hierarchicalTree - Hierarchical tree with nested children
+ *
+ * @returns {import('./typedef.js').FlatTree<T>} flat tree data
+ */
+export function flattenTree<T extends object>(hierarchicalTree: T): import("./typedef.js").FlatTree<T>;