@kalutskii/foundation 0.7.18 → 0.7.20

package/README.md

@@ -29,6 +29,7 @@ The package contains several deliberately isolated areas:
 | `zod-search`     | Reusable search and pagination contracts composed from lower-level Zod primitives.        |
 | `zod-bulk`       | Include/exclude selection contracts shared by frontend and backend bulk operations.       |
 | `hono`           | Hono-specific response, file response, error handling, and request logging adapters.      |
+| `hmac`           | Web Crypto HMAC signing, verification, algorithms, and signature encoding.                |
 | `drizzle`        | Drizzle-specific SQL composition that must not leak into generic contract modules.        |
 | `zod-jwt`        | JWT service integration with optional Zod validation of decoded payloads.                 |
 
@@ -87,6 +88,7 @@ Otherwise, create a dedicated module instead of growing an unrelated file with a
 ```text
 src/
 ├── drizzle/
+├── hmac/
 ├── hono/
 ├── http/
 ├── upload/

package/dist/index.d.ts

@@ -76,6 +76,107 @@ declare function respond<T extends object = Record<string, never>, S extends Suc
  */
 declare function fileRespond<S extends SuccessStatusCode>(c: Context, options: HonoFileRespondOptions<S>): Response;
 
+/**
+ * Default digest algorithm used by `HMACService` when none is configured.
+ * SHA-256 provides broad Web Crypto support and a 256-bit authentication tag.
+ */
+declare const DEFAULT_HMAC_ALGORITHM: "SHA-256";
+/**
+ * Default textual encoding used for signatures returned by `HMACService`.
+ * Hex output remains deterministic, portable, and independent of padding rules.
+ */
+declare const DEFAULT_HMAC_ENCODING: "hex";
+
+declare const hmacAlgorithmsArray: readonly ["SHA-256", "SHA-384", "SHA-512"];
+type HMACAlgorithm = (typeof hmacAlgorithmsArray)[number];
+declare const hmacAlgorithmsRecord: Readonly<{
+    SHA_256: "SHA-256";
+    SHA_384: "SHA-384";
+    SHA_512: "SHA-512";
+}>;
+declare const hmacAlgorithm: Readonly<{
+    SHA_256: "SHA-256";
+    SHA_384: "SHA-384";
+    SHA_512: "SHA-512";
+}>;
+declare const hmacEncodingsArray: readonly ["hex", "base64", "base64url"];
+type HMACEncoding = (typeof hmacEncodingsArray)[number];
+declare const hmacEncodingsRecord: Readonly<{
+    HEX: "hex";
+    BASE64: "base64";
+    BASE64URL: "base64url";
+}>;
+declare const hmacEncoding: Readonly<{
+    HEX: "hex";
+    BASE64: "base64";
+    BASE64URL: "base64url";
+}>;
+
+/**
+ * Binary-safe input accepted as either an HMAC payload or a secret key.
+ * Strings use UTF-8 encoding while byte arrays preserve their exact contents.
+ */
+type HMACInput = string | Uint8Array;
+/**
+ * Configures the digest algorithm and textual signature encoding for one service.
+ * Omitted values select SHA-256 and lowercase hexadecimal output by default.
+ */
+type HMACServiceOptions = Readonly<{
+    /**
+     * Web Crypto digest algorithm used to authenticate every payload.
+     * The service defaults to `SHA-256` when this option is omitted.
+     */
+    algorithm?: HMACAlgorithm;
+    /**
+     * Text encoding applied to generated and verified signatures.
+     * The service defaults to `hex` when this option is omitted.
+     */
+    encoding?: HMACEncoding;
+}>;
+
+/**
+ * Creates and verifies keyed message authentication codes through Web Crypto.
+ * Each instance preserves its digest algorithm and textual encoding configuration.
+ */
+declare class HMACService {
+    readonly algorithm: HMACAlgorithm;
+    readonly encoding: HMACEncoding;
+    constructor(options?: HMACServiceOptions);
+    /**
+     * Authenticates a payload with a secret and returns the encoded signature.
+     * String inputs use UTF-8 while byte arrays preserve their exact byte sequence.
+     *
+     * @example
+     * const signature = await hmacService.sign('payload', 'shared-secret');
+     */
+    sign(payload: HMACInput, secret: HMACInput): Promise<string>;
+    /**
+     * Verifies an encoded signature without requiring a manual equality comparison.
+     * Invalid encodings, incorrect secrets, and altered payloads all resolve to `false`.
+     *
+     * @example
+     * const verified = await hmacService.verify('payload', signature, 'shared-secret');
+     */
+    verify(payload: HMACInput, signature: string, secret: HMACInput): Promise<boolean>;
+    private importSecret;
+}
+
+/**
+ * Converts an HMAC payload or secret into an isolated byte array representation.
+ * Strings use UTF-8 while supplied bytes are copied to prevent later mutation.
+ */
+declare function toHMACBytes(input: HMACInput): Uint8Array<ArrayBuffer>;
+/**
+ * Encodes binary HMAC output with one supported transport-safe representation.
+ * Hex output remains lowercase while Base64 URL output omits conventional padding.
+ */
+declare function encodeHMACSignature(signature: Uint8Array, encoding: HMACEncoding): string;
+/**
+ * Decodes a textual HMAC signature into bytes for cryptographic verification.
+ * Malformed alphabets, lengths, or padding combinations reject with `TypeError`.
+ */
+declare function decodeHMACSignature(signature: string, encoding: HMACEncoding): Uint8Array<ArrayBuffer>;
+
 /**
  * Creates a successful API envelope without cloning its data.
  * Generic inference preserves the exact supplied payload type.
@@ -531,6 +632,17 @@ declare function formatTime(time: Date, { locale, tz }?: {
     tz?: string;
 }): string;
 
+/**
+ * Encodes arbitrary binary bytes into their canonical Base64 representation.
+ * Chunked conversion avoids the argument limit imposed by `String.fromCharCode`.
+ */
+declare function encodeBase64(bytes: Uint8Array): string;
+/**
+ * Decodes a canonical or padded Base64 string into its original binary bytes.
+ * Invalid input preserves the native `atob` failure instead of returning partial data.
+ */
+declare function decodeBase64(value: string): Uint8Array<ArrayBuffer>;
+
 /**
  * Recursively replaces dots in a string literal with underscores.
  * Every other character remains unchanged in the resulting literal type.
@@ -923,4 +1035,4 @@ declare function stringifyPayloadValues<TValue>(value: TValue): StringifiedPaylo
  */
 declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;
 
-export { type APIContractData, type APIContractError, type APIContractResult, type APIError, type APISuccess, type AtLeastOne, DEFAULT_UPLOAD_MAX_FILE_SIZE, EXCEPTION_STATUS_CODES, type ExceptionStatusCode, type FetchResult, type FileFormat, type FileFormatConfig, type HonoFileRespondOptions, type HonoRespondOptions, type JWTServiceOptions, type JWTSignOptions, type LogLevel, type MeasuredExecution, type Payload, type PayloadSchema, REDACTED_LOG_VALUE, type ReplaceDotsWithUnderscores, type ReplaceHyphensWithUnderscores, SUCCESS_STATUS_CODES, type Simplify, type StringEnumRecord, type StringifiedPayload, type SuccessStatusCode, type UploadFilesValidationOptions, type UploadFilesValidationResult, type UploadPreset, type UploadValidationError, type ZodBulkExcludeSelection, type ZodBulkIncludeSelection, type ZodBulkSelection, ZodJWTService, type ZodPaginationOptions, type ZodSearchSchemaOptions, type ZodUploadFileSchemaOptions, asQuery, createStringEnumRecord, createUploadAccept, createZodSearchWhereSchema, defineUploadPreset, documentUploadPreset, failure, fetchAndThrow, fetchSafely, fileFormat, fileFormatsArray, fileFormatsConfig, fileFormatsRecord, fileRespond, formatTime, generateRandomString, getColoredHTTPStatus, getFileExtension, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, httpStatusColors, imageTransparentUploadPreset, imageUploadPreset, isFileExtensionSupported, isFileFormatSupported, isFileMimeTypeSupported, isPlainObject, log, logLevel, logLevelColors, logLevelsArray, logLevelsRecord, loggingMiddleware, matchesMimeType, measureExecutionTime, normalizeFileExtension, onHandlerError, parseQueryValue, redactSensitiveJSON, redactSensitiveSearchParams, respond, safeExecute, sensitiveLogKeyParts, sqlWhere, stringifyPayloadValues, success, uploadValidationError, uploadValidationErrorsArray, uploadValidationErrorsRecord, validateUploadFile, validateUploadFiles, zodAtLeastOne, zodBulkSelectionSchema, zodPaginationSchema, zodPaginationShape, zodSearchQuerySchema, zodSearchSchema, zodUploadFileSchema };
+export { type APIContractData, type APIContractError, type APIContractResult, type APIError, type APISuccess, type AtLeastOne, DEFAULT_HMAC_ALGORITHM, DEFAULT_HMAC_ENCODING, DEFAULT_UPLOAD_MAX_FILE_SIZE, EXCEPTION_STATUS_CODES, type ExceptionStatusCode, type FetchResult, type FileFormat, type FileFormatConfig, type HMACAlgorithm, type HMACEncoding, type HMACInput, HMACService, type HMACServiceOptions, type HonoFileRespondOptions, type HonoRespondOptions, type JWTServiceOptions, type JWTSignOptions, type LogLevel, type MeasuredExecution, type Payload, type PayloadSchema, REDACTED_LOG_VALUE, type ReplaceDotsWithUnderscores, type ReplaceHyphensWithUnderscores, SUCCESS_STATUS_CODES, type Simplify, type StringEnumRecord, type StringifiedPayload, type SuccessStatusCode, type UploadFilesValidationOptions, type UploadFilesValidationResult, type UploadPreset, type UploadValidationError, type ZodBulkExcludeSelection, type ZodBulkIncludeSelection, type ZodBulkSelection, ZodJWTService, type ZodPaginationOptions, type ZodSearchSchemaOptions, type ZodUploadFileSchemaOptions, asQuery, createStringEnumRecord, createUploadAccept, createZodSearchWhereSchema, decodeBase64, decodeHMACSignature, defineUploadPreset, documentUploadPreset, encodeBase64, encodeHMACSignature, failure, fetchAndThrow, fetchSafely, fileFormat, fileFormatsArray, fileFormatsConfig, fileFormatsRecord, fileRespond, formatTime, generateRandomString, getColoredHTTPStatus, getFileExtension, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, hmacAlgorithm, hmacAlgorithmsArray, hmacAlgorithmsRecord, hmacEncoding, hmacEncodingsArray, hmacEncodingsRecord, httpStatusColors, imageTransparentUploadPreset, imageUploadPreset, isFileExtensionSupported, isFileFormatSupported, isFileMimeTypeSupported, isPlainObject, log, logLevel, logLevelColors, logLevelsArray, logLevelsRecord, loggingMiddleware, matchesMimeType, measureExecutionTime, normalizeFileExtension, onHandlerError, parseQueryValue, redactSensitiveJSON, redactSensitiveSearchParams, respond, safeExecute, sensitiveLogKeyParts, sqlWhere, stringifyPayloadValues, success, toHMACBytes, uploadValidationError, uploadValidationErrorsArray, uploadValidationErrorsRecord, validateUploadFile, validateUploadFiles, zodAtLeastOne, zodBulkSelectionSchema, zodPaginationSchema, zodPaginationShape, zodSearchQuerySchema, zodSearchSchema, zodUploadFileSchema };

package/dist/index.js

@@ -156,6 +156,115 @@ function fileRespond(c, options) {
   return c.body(options.content, options.status);
 }
 
+// src/hmac/hmac.enums.ts
+var hmacAlgorithmsArray = ["SHA-256", "SHA-384", "SHA-512"];
+var hmacAlgorithmsRecord = createStringEnumRecord(hmacAlgorithmsArray);
+var hmacAlgorithm = hmacAlgorithmsRecord;
+var hmacEncodingsArray = ["hex", "base64", "base64url"];
+var hmacEncodingsRecord = createStringEnumRecord(hmacEncodingsArray);
+var hmacEncoding = hmacEncodingsRecord;
+
+// src/hmac/hmac.constants.ts
+var DEFAULT_HMAC_ALGORITHM = hmacAlgorithm.SHA_256;
+var DEFAULT_HMAC_ENCODING = hmacEncoding.HEX;
+
+// src/utilities/encoding.utilities.ts
+var BASE64_BYTE_CHUNK_SIZE = 32768;
+function encodeBase64(bytes) {
+  let binary = "";
+  for (let offset = 0; offset < bytes.length; offset += BASE64_BYTE_CHUNK_SIZE) {
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + BASE64_BYTE_CHUNK_SIZE));
+  }
+  return btoa(binary);
+}
+function decodeBase64(value) {
+  const binary = atob(value);
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+
+// src/hmac/hmac.utilities.ts
+var textEncoder = new TextEncoder();
+function toHMACBytes(input) {
+  if (typeof input === "string")
+    return textEncoder.encode(input);
+  const bytes = new Uint8Array(input.length);
+  bytes.set(input);
+  return bytes;
+}
+function encodeHMACSignature(signature, encoding) {
+  if (encoding === "hex") {
+    return Array.from(signature, (byte) => byte.toString(16).padStart(2, "0")).join("");
+  }
+  const base64 = encodeBase64(signature);
+  if (encoding === "base64")
+    return base64;
+  return base64.replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+function decodeHMACSignature(signature, encoding) {
+  if (encoding === "hex") {
+    if (signature.length % 2 !== 0 || !/^[0-9a-f]*$/i.test(signature)) {
+      throw new TypeError("Invalid hexadecimal HMAC signature");
+    }
+    return Uint8Array.from(signature.match(/.{2}/g) ?? [], (byte) => Number.parseInt(byte, 16));
+  }
+  if (encoding === "base64") {
+    if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(signature)) {
+      throw new TypeError("Invalid Base64 HMAC signature");
+    }
+    return decodeBase64(signature);
+  }
+  if (!/^[A-Za-z0-9_-]*$/.test(signature) || signature.length % 4 === 1) {
+    throw new TypeError("Invalid Base64 URL HMAC signature");
+  }
+  const base64 = signature.replaceAll("-", "+").replaceAll("_", "/").padEnd(Math.ceil(signature.length / 4) * 4, "=");
+  return decodeBase64(base64);
+}
+
+// src/hmac/hmac.services.ts
+var HMACService = class {
+  algorithm;
+  encoding;
+  constructor(options = {}) {
+    this.algorithm = options.algorithm ?? DEFAULT_HMAC_ALGORITHM;
+    this.encoding = options.encoding ?? DEFAULT_HMAC_ENCODING;
+  }
+  /**
+   * Authenticates a payload with a secret and returns the encoded signature.
+   * String inputs use UTF-8 while byte arrays preserve their exact byte sequence.
+   *
+   * @example
+   * const signature = await hmacService.sign('payload', 'shared-secret');
+   */
+  async sign(payload, secret) {
+    const key = await this.importSecret(secret);
+    const signature = await crypto.subtle.sign("HMAC", key, toHMACBytes(payload));
+    return encodeHMACSignature(new Uint8Array(signature), this.encoding);
+  }
+  /**
+   * Verifies an encoded signature without requiring a manual equality comparison.
+   * Invalid encodings, incorrect secrets, and altered payloads all resolve to `false`.
+   *
+   * @example
+   * const verified = await hmacService.verify('payload', signature, 'shared-secret');
+   */
+  async verify(payload, signature, secret) {
+    let signatureBytes;
+    try {
+      signatureBytes = decodeHMACSignature(signature, this.encoding);
+    } catch {
+      return false;
+    }
+    const key = await this.importSecret(secret);
+    return crypto.subtle.verify("HMAC", key, signatureBytes, toHMACBytes(payload));
+  }
+  async importSecret(secret) {
+    const secretBytes = toHMACBytes(secret);
+    const algorithm = { name: "HMAC", hash: this.algorithm };
+    const keyUsages = ["sign", "verify"];
+    return crypto.subtle.importKey("raw", secretBytes, algorithm, false, keyUsages);
+  }
+};
+
 // src/http/http.constants.ts
 var SUCCESS_STATUS_CODES = [200, 201, 202, 307];
 var EXCEPTION_STATUS_CODES = [400, 401, 403, 404, 405, 409, 500];
@@ -467,7 +576,7 @@ var zodPaginationSchema = z3.object({
    * Positive maximum number of records returned in a single result page.
    * String values are coerced to support validation of URL query input.
    */
-  limit: z3.coerce.number().int().positive().default(10)
+  limit: z3.coerce.number().int().positive().max(256).default(10)
 });
 var zodPaginationShape = zodPaginationSchema.shape;
 
@@ -539,8 +648,11 @@ function stringifyPayloadValues(value) {
   return String(value);
 }
 export {
+  DEFAULT_HMAC_ALGORITHM,
+  DEFAULT_HMAC_ENCODING,
   DEFAULT_UPLOAD_MAX_FILE_SIZE,
   EXCEPTION_STATUS_CODES,
+  HMACService,
   REDACTED_LOG_VALUE,
   SUCCESS_STATUS_CODES,
   ZodJWTService,
@@ -548,8 +660,12 @@ export {
   createStringEnumRecord,
   createUploadAccept,
   createZodSearchWhereSchema,
+  decodeBase64,
+  decodeHMACSignature,
   defineUploadPreset,
   documentUploadPreset,
+  encodeBase64,
+  encodeHMACSignature,
   failure,
   fetchAndThrow,
   fetchSafely,
@@ -566,6 +682,12 @@ export {
   getFormattedTime,
   getUTCOffset,
   getZonedTime,
+  hmacAlgorithm,
+  hmacAlgorithmsArray,
+  hmacAlgorithmsRecord,
+  hmacEncoding,
+  hmacEncodingsArray,
+  hmacEncodingsRecord,
   httpStatusColors,
   imageTransparentUploadPreset,
   imageUploadPreset,
@@ -592,6 +714,7 @@ export {
   sqlWhere,
   stringifyPayloadValues,
   success,
+  toHMACBytes,
   uploadValidationError,
   uploadValidationErrorsArray,
   uploadValidationErrorsRecord,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kalutskii/foundation",
-  "version": "0.7.18",
+  "version": "0.7.20",
   "description": "Typescript collection of most common utilities, schemas and functions among private projects.",
   "license": "MIT",
   "type": "module",