@hadoku/worker-utils 0.0.0-stage → 1.6.19

package/dist/masking.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Data masking utilities for sensitive information logging
+ *
+ * Provides functions to safely mask keys, session IDs, and other
+ * sensitive data before logging to prevent exposure.
+ *
+ * @example
+ * ```typescript
+ * import { maskKey, maskSessionId } from '../util';
+ *
+ * const key = 'admin-secret-key-12345';
+ * console.log(maskKey(key)); // "admin-secre" (first 50%)
+ *
+ * const sessionId = '1a2b3c4d5e6f7g8h9i0j1k2l';
+ * console.log(maskSessionId(sessionId)); // "1a2b3c4d5e6f7g8h" (first 16 chars)
+ * ```
+ */
+/**
+ * Masking configuration constants
+ */
+declare const MASKING: {
+    /** Percentage of key to show (default: 50%) */
+    readonly KEY_PERCENTAGE: 0.5;
+    /** Minimum characters to show for keys */
+    readonly KEY_MIN_LENGTH: 4;
+    /** Number of characters to show for session IDs (default: 16) */
+    readonly SESSION_ID_PREFIX_LENGTH: 16;
+};
+/**
+ * Mask a key for logging (show first 50% of characters)
+ *
+ * Shows the first half of the key to allow identification while
+ * protecting the full key from exposure in logs/dashboards.
+ * No suffix is added - just the raw truncated key.
+ *
+ * @param key - Key to mask
+ * @param percentage - Percentage of key to show (default: 50%)
+ * @returns Masked key (e.g., "N7RZK2YW" for a 16-char key)
+ *
+ * @example
+ * ```typescript
+ * maskKey('N7RZK2YWABCD1234'); // "N7RZK2YW"
+ * maskKey('short'); // "sh"
+ * maskKey('ab'); // "ab"
+ * ```
+ */
+declare function maskKey(key: string, percentage?: number): string;
+/**
+ * Mask a session ID for logging (show first 16 characters)
+ *
+ * @param id - Session ID to mask
+ * @returns Masked session ID (e.g., "1a2b3c4d5e6f7g8h")
+ *
+ * @example
+ * ```typescript
+ * maskSessionId('1a2b3c4d5e6f7g8h9i0j'); // "1a2b3c4d5e6f7g8h"
+ * maskSessionId('short-id'); // "short-id"
+ * ```
+ */
+declare function maskSessionId(id: string): string;
+/**
+ * Mask an IP address for logging (show first 3 octets, replace last with *)
+ *
+ * @param ip - IP address to mask
+ * @returns Masked IP (e.g., "203.0.113.*")
+ *
+ * @example
+ * ```typescript
+ * maskIpAddress('203.0.113.45'); // "203.0.113.*"
+ * maskIpAddress('2001:db8::1'); // "2001:db8::*"
+ * maskIpAddress(null); // undefined
+ * ```
+ */
+declare function maskIpAddress(ip: string | null | undefined): string | undefined;
+/**
+ * Mask an email address for logging (show first character and domain)
+ *
+ * @param email - Email to mask
+ * @returns Masked email (e.g., "j***@example.com")
+ *
+ * @example
+ * ```typescript
+ * maskEmail('john@example.com'); // "j***@example.com"
+ * maskEmail('invalid-email'); // "invalid-email"
+ * ```
+ */
+declare function maskEmail(email: string): string;
+/**
+ * Redact multiple sensitive fields from an object
+ *
+ * @param obj - Object to redact
+ * @param fields - Field names to redact
+ * @returns New object with redacted fields
+ *
+ * @example
+ * ```typescript
+ * const data = { username: 'john', password: 'secret123', email: 'john@example.com' };
+ * redactFields(data, ['password']);
+ * // { username: 'john', password: '[REDACTED]', email: 'john@example.com' }
+ * ```
+ */
+declare function redactFields<T extends Record<string, any>>(obj: T, fields: string[]): T;
+/**
+ * Common sensitive field names to redact
+ */
+declare const SENSITIVE_FIELDS: readonly ["password", "token", "secret", "apiKey", "api_key", "accessToken", "access_token", "refreshToken", "refresh_token", "privateKey", "private_key", "authKey", "auth_key"];
+
+export { MASKING, SENSITIVE_FIELDS, maskEmail, maskIpAddress, maskKey, maskSessionId, redactFields };

package/dist/masking.js

@@ -0,0 +1,90 @@
+// masking.ts
+var MASKING = {
+  /** Percentage of key to show (default: 50%) */
+  KEY_PERCENTAGE: 0.5,
+  /** Minimum characters to show for keys */
+  KEY_MIN_LENGTH: 4,
+  /** Number of characters to show for session IDs (default: 16) */
+  SESSION_ID_PREFIX_LENGTH: 16
+};
+function maskKey(key, percentage = MASKING.KEY_PERCENTAGE) {
+  if (!key) {
+    return key;
+  }
+  const showLength = Math.max(MASKING.KEY_MIN_LENGTH, Math.floor(key.length * percentage));
+  if (key.length <= showLength) {
+    return key;
+  }
+  return key.substring(0, showLength);
+}
+function maskSessionId(id) {
+  if (!id) {
+    return id;
+  }
+  const length = MASKING.SESSION_ID_PREFIX_LENGTH;
+  if (id.length <= length) {
+    return id;
+  }
+  return id.substring(0, length);
+}
+function maskIpAddress(ip) {
+  if (!ip) {
+    return void 0;
+  }
+  if (ip.includes(".")) {
+    const parts = ip.split(".");
+    if (parts.length === 4) {
+      return `${parts[0]}.${parts[1]}.${parts[2]}.*`;
+    }
+  }
+  if (ip.includes(":")) {
+    const lastColon = ip.lastIndexOf(":");
+    if (lastColon > 0) {
+      return ip.substring(0, lastColon + 1) + "*";
+    }
+  }
+  return ip;
+}
+function maskEmail(email) {
+  if (!email?.includes("@")) {
+    return email;
+  }
+  const [username, domain] = email.split("@");
+  if (!username || !domain) {
+    return email;
+  }
+  return `${username[0]}***@${domain}`;
+}
+function redactFields(obj, fields) {
+  const redacted = { ...obj };
+  for (const field of fields) {
+    if (field in redacted) {
+      redacted[field] = "[REDACTED]";
+    }
+  }
+  return redacted;
+}
+var SENSITIVE_FIELDS = [
+  "password",
+  "token",
+  "secret",
+  "apiKey",
+  "api_key",
+  "accessToken",
+  "access_token",
+  "refreshToken",
+  "refresh_token",
+  "privateKey",
+  "private_key",
+  "authKey",
+  "auth_key"
+];
+export {
+  MASKING,
+  SENSITIVE_FIELDS,
+  maskEmail,
+  maskIpAddress,
+  maskKey,
+  maskSessionId,
+  redactFields
+};

package/dist/openapi-config.d.ts

@@ -0,0 +1,252 @@
+import * as hono_utils_types from 'hono/utils/types';
+import * as hono from 'hono';
+import { Context } from 'hono';
+
+interface ValidationHookResult {
+    success: false;
+    error: {
+        issues: {
+            path: PropertyKey[];
+            message: string;
+        }[];
+    };
+}
+/**
+ * Error response format type
+ * - 'simple': { error, message } - Used by task-api
+ * - 'wrapped': { success: false, error, message } - Used by prompt-api, oss-recon-api
+ */
+type ErrorResponseFormat = 'simple' | 'wrapped';
+/**
+ * Creates a validation hook for OpenAPIHono that formats Zod validation errors.
+ *
+ * @param format - The error response format to use
+ * @returns A defaultHook function for OpenAPIHono
+ *
+ * @example
+ * ```typescript
+ * const app = new OpenAPIHono({
+ *   defaultHook: createValidationHook('simple'),
+ * });
+ * ```
+ */
+declare function createValidationHook(format?: ErrorResponseFormat): (result: ValidationHookResult | {
+    success: true;
+}, c: Context) => (Response & hono.TypedResponse<{
+    error: string;
+    message: string;
+}, 400, "json">) | undefined;
+/**
+ * Pre-built validation hook for simple error format (task-api style)
+ */
+declare const simpleValidationHook: (result: ValidationHookResult | {
+    success: true;
+}, c: Context) => (Response & hono.TypedResponse<{
+    error: string;
+    message: string;
+}, 400, "json">) | undefined;
+/**
+ * Pre-built validation hook for wrapped error format (prompt-api style)
+ */
+declare const wrappedValidationHook: (result: ValidationHookResult | {
+    success: true;
+}, c: Context) => (Response & hono.TypedResponse<{
+    error: string;
+    message: string;
+}, 400, "json">) | undefined;
+/**
+ * Creates 404 and error handlers with consistent response format.
+ *
+ * @param format - The error response format to use
+ * @returns Object with notFoundHandler and errorHandler functions
+ *
+ * @example
+ * ```typescript
+ * const { notFoundHandler, errorHandler } = createErrorHandlers('wrapped');
+ * app.notFound(notFoundHandler);
+ * app.onError(errorHandler);
+ * ```
+ */
+declare function createErrorHandlers(format?: ErrorResponseFormat): {
+    notFoundHandler: (c: Context) => Response & hono.TypedResponse<{
+        error: string;
+        message: string;
+    }, 404, "json">;
+    errorHandler: (err: Error, c: Context) => Response & hono.TypedResponse<{
+        error: string;
+        message: string;
+    }, 500, "json">;
+};
+interface OpenAPIDocOptions {
+    /** API title */
+    title: string;
+    /** API version */
+    version: string;
+    /** API description (supports markdown) */
+    description: string;
+    /** Base path for production URL (e.g., '/api' or '/task/api') */
+    basePath?: string;
+    /** Production server URL */
+    production: string;
+    /** Local development port (default: 8787) */
+    localPort?: number;
+    /** OpenAPI tags */
+    tags?: {
+        name: string;
+        description: string;
+    }[];
+}
+/**
+ * Creates a standardized OpenAPI doc configuration.
+ *
+ * @param options - Configuration options
+ * @returns OpenAPI doc configuration object for app.doc()
+ *
+ * @example
+ * ```typescript
+ * app.doc('/api/openapi.json', createOpenAPIDocConfig({
+ *   title: 'Task API',
+ *   version: '1.0.0',
+ *   description: 'API for managing tasks',
+ *   production: 'https://task-api.hadoku.workers.dev',
+ *   tags: [
+ *     { name: 'Tasks', description: 'Task operations' },
+ *   ],
+ * }));
+ * ```
+ */
+declare function createOpenAPIDocConfig(options: OpenAPIDocOptions): {
+    openapi: "3.0.0";
+    info: {
+        title: string;
+        version: string;
+        description: string;
+    };
+    servers: {
+        url: string;
+        description: string;
+    }[];
+    tags: {
+        name: string;
+        description: string;
+    }[];
+};
+/**
+ * Common OpenAPI tags used across multiple APIs
+ */
+declare const CommonTags: {
+    readonly Health: {
+        readonly name: "Health";
+        readonly description: "Health check endpoints";
+    };
+    readonly Admin: {
+        readonly name: "Admin";
+        readonly description: "Admin operations (requires authentication)";
+    };
+};
+/**
+ * Success response helper with wrapped format { success: true, data }
+ * Used by: prompt-api, oss-recon-api
+ *
+ * @example
+ * ```typescript
+ * return okWrapped(c, { categories: [...] });
+ * ```
+ */
+declare function okWrapped<T>(c: Context, data: T): Response & hono.TypedResponse<true | T extends bigint | readonly bigint[] ? never : { [K in keyof {
+    success: true;
+    data: T;
+} as ({
+    success: true;
+    data: T;
+}[K] extends infer T_1 ? T_1 extends {
+    success: true;
+    data: T;
+}[K] ? T_1 extends hono_utils_types.InvalidJSONValue ? true : false : never : never) extends true ? never : K]: boolean extends ({
+    success: true;
+    data: T;
+}[K] extends infer T_2 ? T_2 extends {
+    success: true;
+    data: T;
+}[K] ? T_2 extends hono_utils_types.InvalidJSONValue ? true : false : never : never) ? hono_utils_types.JSONParsed<{
+    success: true;
+    data: T;
+}[K], bigint | readonly bigint[]> | undefined : hono_utils_types.JSONParsed<{
+    success: true;
+    data: T;
+}[K], bigint | readonly bigint[]>; }, 200, "json">;
+/**
+ * Created response helper with wrapped format { success: true, data }
+ * Used by: prompt-api admin routes
+ *
+ * @example
+ * ```typescript
+ * return createdWrapped(c, { category });
+ * ```
+ */
+declare function createdWrapped<T>(c: Context, data: T): Response & hono.TypedResponse<true | T extends bigint | readonly bigint[] ? never : { [K in keyof {
+    success: true;
+    data: T;
+} as ({
+    success: true;
+    data: T;
+}[K] extends infer T_1 ? T_1 extends {
+    success: true;
+    data: T;
+}[K] ? T_1 extends hono_utils_types.InvalidJSONValue ? true : false : never : never) extends true ? never : K]: boolean extends ({
+    success: true;
+    data: T;
+}[K] extends infer T_2 ? T_2 extends {
+    success: true;
+    data: T;
+}[K] ? T_2 extends hono_utils_types.InvalidJSONValue ? true : false : never : never) ? hono_utils_types.JSONParsed<{
+    success: true;
+    data: T;
+}[K], bigint | readonly bigint[]> | undefined : hono_utils_types.JSONParsed<{
+    success: true;
+    data: T;
+}[K], bigint | readonly bigint[]>; }, 201, "json">;
+/**
+ * Bad request response helper with wrapped format { success: false, error, message }
+ * Use in openapi() handlers where the route declares DetailedErrorResponseSchema for 400.
+ *
+ * @example
+ * ```typescript
+ * return badRequestWrapped(c, 'Missing required field: id');
+ * ```
+ */
+declare function badRequestWrapped(c: Context, message: string): Response & hono.TypedResponse<{
+    success: false;
+    error: string;
+    message: string;
+}, 400, "json">;
+/**
+ * Not found response helper with wrapped format { success: false, error, message }
+ * Use in openapi() handlers where the route declares DetailedErrorResponseSchema for 404.
+ *
+ * @example
+ * ```typescript
+ * return notFoundWrapped(c, 'Category');
+ * ```
+ */
+declare function notFoundWrapped(c: Context, resource?: string): Response & hono.TypedResponse<{
+    success: false;
+    error: string;
+    message: string;
+}, 404, "json">;
+/**
+ * Server error response helper with wrapped format { success: false, error, message }
+ * Use in openapi() handlers where the route declares DetailedErrorResponseSchema for 500.
+ *
+ * @example
+ * ```typescript
+ * return serverErrorWrapped(c, 'Failed to fetch categories');
+ * ```
+ */
+declare function serverErrorWrapped(c: Context, message?: string): Response & hono.TypedResponse<{
+    success: false;
+    error: string;
+    message: string;
+}, 500, "json">;
+
+export { CommonTags, type ErrorResponseFormat, badRequestWrapped, createErrorHandlers, createOpenAPIDocConfig, createValidationHook, createdWrapped, notFoundWrapped, okWrapped, serverErrorWrapped, simpleValidationHook, wrappedValidationHook };

package/dist/openapi-config.js

@@ -0,0 +1,131 @@
+// openapi-config.ts
+function createValidationHook(format = "simple") {
+  return (result, c) => {
+    if (!result.success) {
+      const issues = result.error.issues;
+      const message = issues.map((i) => `${i.path.join(".")}: ${i.message}`).join(", ");
+      if (format === "wrapped") {
+        return c.json(
+          {
+            success: false,
+            error: "Validation Error",
+            message
+          },
+          400
+        );
+      }
+      return c.json(
+        {
+          error: "Validation Error",
+          message
+        },
+        400
+      );
+    }
+  };
+}
+var simpleValidationHook = createValidationHook("simple");
+var wrappedValidationHook = createValidationHook("wrapped");
+function createErrorHandlers(format = "simple") {
+  const notFoundHandler = (c) => {
+    if (format === "wrapped") {
+      return c.json(
+        {
+          success: false,
+          error: "Not found",
+          message: "The requested endpoint does not exist"
+        },
+        404
+      );
+    }
+    return c.json(
+      {
+        error: "Not found",
+        message: "The requested endpoint does not exist"
+      },
+      404
+    );
+  };
+  const errorHandler = (err, c) => {
+    console.error("Unhandled error:", err);
+    if (format === "wrapped") {
+      return c.json(
+        {
+          success: false,
+          error: "Internal server error",
+          message: "An unexpected error occurred"
+        },
+        500
+      );
+    }
+    return c.json(
+      {
+        error: "Internal server error",
+        message: "An unexpected error occurred"
+      },
+      500
+    );
+  };
+  return { notFoundHandler, errorHandler };
+}
+function createOpenAPIDocConfig(options) {
+  const { title, version, description, production, localPort = 8787, tags = [] } = options;
+  return {
+    openapi: "3.0.0",
+    info: {
+      title,
+      version,
+      description: description.trim()
+    },
+    servers: [
+      {
+        url: production,
+        description: "Production"
+      },
+      {
+        url: `http://localhost:${localPort}`,
+        description: "Local development"
+      }
+    ],
+    tags
+  };
+}
+var CommonTags = {
+  Health: { name: "Health", description: "Health check endpoints" },
+  Admin: { name: "Admin", description: "Admin operations (requires authentication)" }
+};
+function okWrapped(c, data) {
+  return c.json({ success: true, data }, 200);
+}
+function createdWrapped(c, data) {
+  return c.json({ success: true, data }, 201);
+}
+function badRequestWrapped(c, message) {
+  return c.json({ success: false, error: "Bad Request", message }, 400);
+}
+function notFoundWrapped(c, resource = "Resource") {
+  return c.json(
+    {
+      success: false,
+      error: "Not Found",
+      message: `${resource} not found`
+    },
+    404
+  );
+}
+function serverErrorWrapped(c, message = "Internal server error") {
+  return c.json({ success: false, error: "Internal Server Error", message }, 500);
+}
+export {
+  CommonTags,
+  badRequestWrapped,
+  createErrorHandlers,
+  createOpenAPIDocConfig,
+  createValidationHook,
+  createdWrapped,
+  notFoundWrapped,
+  okWrapped,
+  serverErrorWrapped,
+  simpleValidationHook,
+  wrappedValidationHook
+};