@venizia/ignis-helpers 0.4.8-1 → 0.4.8-3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -72,6 +72,7 @@ A helper that imports an optional peer as a value lives only on its own sub-path
72
72
  | `./kafka` | `KafkaProducerHelper`, `KafkaConsumerHelper`, `KafkaAdminHelper`, schema registry, bundler plugins | `@platformatic/kafka` |
73
73
  | `./bun-s3` | `BunS3Helper` | none - Bun's native S3 client (Bun only) |
74
74
  | `./socket-io` | `SocketIOServerHelper`, `SocketIOClientHelper` | `socket.io`, `@socket.io/redis-adapter`, `@socket.io/redis-emitter`; `socket.io-client` for the client |
75
+ | `./socket-io/client` | The browser-safe client: `SocketIOClientHelper` with nothing from node in its graph, and the event names and option types it speaks | none - you pass `{ io }` from `socket.io-client` |
75
76
  | `./axios` | `AxiosFetcher`, `AxiosNetworkRequest` | `axios` |
76
77
  | `./cron` | `CronHelper` | `cron` |
77
78
  | `./hashicorp-vault` | `HashiCorpVaultHelper` | `node-vault` |
@@ -10,20 +10,28 @@ export declare class RedactUtility {
10
10
  * `Infinity` for callers that really do want the whole graph, but the logger passes its own bound:
11
11
  * rendering only inspects a handful of levels, so walking to `Infinity` did work whose result was
12
12
  * thrown away - 12x on a deep graph, and a `RangeError` on a very deep chain.
13
+ *
14
+ * `force: true` masks secret-looking KEYS even when `APP_ENV_LOGGER_DO_REDACT=false`. The result is still the
15
+ * log-shaped copy: long strings are capped, a second reference to one object reads `[Circular]`, binary is
16
+ * summarized, and a key is masked by name only (a card number under `number` is not). It is not a faithful
17
+ * redacted document. The logger never sets it.
13
18
  */
14
19
  static redactSecrets(opts: {
15
20
  value: unknown;
16
21
  seen?: WeakSet<object>;
17
22
  depth?: number;
23
+ force?: boolean;
18
24
  }): unknown;
19
- /** Projects a value into something `JSON.stringify` can render: it answers `[Circular]` for the WHOLE payload when one cycle sits anywhere inside it, so cycles must be broken per-branch first. `depth` bounds the walk the way `util.inspect` does - a log argument may hold a live connector or request context, whose graph is effectively unbounded. The projection itself is unconditional: `APP_ENV_LOGGER_DO_REDACT=false` turns off the key masking, never the structural pass. */
25
+ /** Projects a value into something `JSON.stringify` can render: it answers `[Circular]` for the WHOLE payload when one cycle sits anywhere inside it, so cycles must be broken per-branch first. `depth` bounds the walk the way `util.inspect` does - a log argument may hold a live connector or request context, whose graph is effectively unbounded. The projection itself is unconditional: `APP_ENV_LOGGER_DO_REDACT=false` turns off the key masking, never the structural pass. `force: true` keeps the key masking on whatever the switch says; the projection stays lossy, as in {@link RedactUtility.redactSecrets}. */
20
26
  static toJsonSafe(opts: {
21
27
  value: unknown;
22
28
  depth?: number;
29
+ force?: boolean;
23
30
  }): unknown;
24
- /** Strips credentials from a connection URL's authority section (`user:hunter2@host` -> `user:[REDACTED]@host`) - {@link RedactUtility.redactSecrets} matches on KEY names and can't see them there. A value that fails to parse as a URL is returned unchanged. */
31
+ /** Strips credentials from a connection URL's authority section (`user:hunter2@host` -> `user:[REDACTED]@host`) - {@link RedactUtility.redactSecrets} matches on KEY names and can't see them there. A value that fails to parse as a URL is returned unchanged. `force: true` strips even when `APP_ENV_LOGGER_DO_REDACT=false`. */
25
32
  static redactUrlCredentials(opts: {
26
33
  url: string;
34
+ force?: boolean;
27
35
  }): string;
28
36
  }
29
37
  //# sourceMappingURL=redact.d.ts.map
@@ -20,8 +20,8 @@ const SECRET_KEY_PATTERN = new RegExp([
20
20
  ].join(''), 'i');
21
21
  /** The placeholder that replaces a secret value in redacted output. */
22
22
  export const REDACTED = '[REDACTED]';
23
- /** Kill-switch for local debugging: only the literal `false` disables redaction (fail-closed); read per call so it can be flipped at runtime. Never disable in production. */
24
- const isRedactionEnabled = () => globalThis.process?.env?.APP_ENV_LOGGER_DO_REDACT !== 'false';
23
+ /** Kill-switch for local debugging: only the literal `false` disables redaction (fail-closed); read per call so it can be flipped at runtime. Never disable in production. `force` is the caller opting out of the switch: it always masks. */
24
+ const isRedactionEnabled = (force) => force === true || globalThis.process?.env?.APP_ENV_LOGGER_DO_REDACT !== 'false';
25
25
  /** Longest string a log line carries whole. `APP_ENV_LOGGER_MAX_STRING_LENGTH=0` turns capping off. */
26
26
  const DEFAULT_MAX_STRING_LENGTH = 2048;
27
27
  const resolveMaxStringLength = () => {
@@ -115,10 +115,15 @@ export class RedactUtility {
115
115
  * `Infinity` for callers that really do want the whole graph, but the logger passes its own bound:
116
116
  * rendering only inspects a handful of levels, so walking to `Infinity` did work whose result was
117
117
  * thrown away - 12x on a deep graph, and a `RangeError` on a very deep chain.
118
+ *
119
+ * `force: true` masks secret-looking KEYS even when `APP_ENV_LOGGER_DO_REDACT=false`. The result is still the
120
+ * log-shaped copy: long strings are capped, a second reference to one object reads `[Circular]`, binary is
121
+ * summarized, and a key is masked by name only (a card number under `number` is not). It is not a faithful
122
+ * redacted document. The logger never sets it.
118
123
  */
119
124
  static redactSecrets(opts) {
120
- const { value, seen, depth = Infinity } = opts;
121
- if (!isRedactionEnabled()) {
125
+ const { value, seen, depth = Infinity, force } = opts;
126
+ if (!isRedactionEnabled(force)) {
122
127
  return value;
123
128
  }
124
129
  return deepSanitize(value, {
@@ -128,21 +133,21 @@ export class RedactUtility {
128
133
  maxStringLength: resolveMaxStringLength(),
129
134
  });
130
135
  }
131
- /** Projects a value into something `JSON.stringify` can render: it answers `[Circular]` for the WHOLE payload when one cycle sits anywhere inside it, so cycles must be broken per-branch first. `depth` bounds the walk the way `util.inspect` does - a log argument may hold a live connector or request context, whose graph is effectively unbounded. The projection itself is unconditional: `APP_ENV_LOGGER_DO_REDACT=false` turns off the key masking, never the structural pass. */
136
+ /** Projects a value into something `JSON.stringify` can render: it answers `[Circular]` for the WHOLE payload when one cycle sits anywhere inside it, so cycles must be broken per-branch first. `depth` bounds the walk the way `util.inspect` does - a log argument may hold a live connector or request context, whose graph is effectively unbounded. The projection itself is unconditional: `APP_ENV_LOGGER_DO_REDACT=false` turns off the key masking, never the structural pass. `force: true` keeps the key masking on whatever the switch says; the projection stays lossy, as in {@link RedactUtility.redactSecrets}. */
132
137
  static toJsonSafe(opts) {
133
138
  return deepSanitize(opts.value, {
134
139
  seen: new WeakSet(),
135
- doRedact: isRedactionEnabled(),
140
+ doRedact: isRedactionEnabled(opts.force),
136
141
  depth: opts.depth ?? Infinity,
137
142
  // Capping is STRUCTURAL, like the projection itself: turning redaction off is about key masking,
138
143
  // never about letting a 300 KB base64 field through.
139
144
  maxStringLength: resolveMaxStringLength(),
140
145
  });
141
146
  }
142
- /** Strips credentials from a connection URL's authority section (`user:hunter2@host` -> `user:[REDACTED]@host`) - {@link RedactUtility.redactSecrets} matches on KEY names and can't see them there. A value that fails to parse as a URL is returned unchanged. */
147
+ /** Strips credentials from a connection URL's authority section (`user:hunter2@host` -> `user:[REDACTED]@host`) - {@link RedactUtility.redactSecrets} matches on KEY names and can't see them there. A value that fails to parse as a URL is returned unchanged. `force: true` strips even when `APP_ENV_LOGGER_DO_REDACT=false`. */
143
148
  static redactUrlCredentials(opts) {
144
- const { url } = opts;
145
- if (!isRedactionEnabled()) {
149
+ const { url, force } = opts;
150
+ if (!isRedactionEnabled(force)) {
146
151
  return url;
147
152
  }
148
153
  let parsed;
@@ -1 +1 @@
1
- {"version":3,"file":"redact.js","sourceRoot":"","sources":["../../../src/common/redact.ts"],"names":[],"mappings":"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","sourcesContent":["import { type AnyObject } from './types';\n\n/** Keys whose VALUES must never reach a log line - matched case-insensitively on the key name, at any depth. */\nconst SECRET_KEY_PATTERN = new RegExp(\n [\n // Options-object spellings (camelCase / snake_case).\n '^(pass|password|passphrase|secret|token|apiKey|api_key|accessKey|access_key',\n '|secretKey|secret_key|privateKey|private_key|key|cert|ca|pfx|credentials',\n '|authorization|auth|jwtSecret|applicationSecret|connectionString)$',\n\n // Vault wire spellings (snake_case): node-vault's AppRole login/response bodies carry these exact keys, and none are matched by the anchored options list above.\n '|^(client_token|secret_id|role_id)$',\n\n // Any `*_token` (snake_case) or `*Token` (camelCase) key; a preceding character is required so the bare word `token` (already covered above) is not the whole match, and so ordinary words are not swallowed.\n '|_token$|[a-z0-9]token$',\n\n // The `*Secret` counterpart the `*Token` rule always lacked. `clientSecret` / `client_secret` is the RFC 6749 parameter name and a live field on the search connector's model options, and `webhookSecret` is the standard spelling everywhere; none of them matched the anchored list above.\n '|_secret$|[a-z0-9]secret$',\n\n // Connection descriptors: `connectionString` was anchored above but its snake_case twin was not, and `dsn` is the third common spelling for the same thing.\n '|^(connection_string|dsn|database_url|databaseUrl)$',\n\n // Any `*_password` / `*Password` key - `dbPassword`, `admin_password`. The bare word is anchored above; this catches the prefixed forms.\n '|_password$|[a-z0-9]password$',\n\n // HTTP HEADER spellings: header names are kebab-case and often `x-`-prefixed, none of which the camelCase list above matches; `vault` is included so `X-Vault-Token` (node-vault's auth header) is caught.\n '|^(x-)?(api|auth|access|secret|session|csrf|xsrf|vault)-(key|token|secret|id)$',\n '|^(cookie|set-cookie|proxy-authorization|www-authenticate)$',\n ].join(''),\n 'i',\n);\n\n/** The placeholder that replaces a secret value in redacted output. */\nexport const REDACTED = '[REDACTED]';\n\n/** Kill-switch for local debugging: only the literal `false` disables redaction (fail-closed); read per call so it can be flipped at runtime. Never disable in production. */\nconst isRedactionEnabled = (): boolean =>\n globalThis.process?.env?.APP_ENV_LOGGER_DO_REDACT !== 'false';\n\n/** Longest string a log line carries whole. `APP_ENV_LOGGER_MAX_STRING_LENGTH=0` turns capping off. */\nconst DEFAULT_MAX_STRING_LENGTH = 2048;\n\nconst resolveMaxStringLength = (): number => {\n const configured = Number(globalThis.process?.env?.APP_ENV_LOGGER_MAX_STRING_LENGTH);\n\n return Number.isFinite(configured) && configured >= 0 ? configured : DEFAULT_MAX_STRING_LENGTH;\n};\n\n/**\n * Keys whose value is long BY NATURE and useless truncated. A stack trace is the whole reason you\n * are reading the line.\n */\nconst UNCAPPED_KEYS = new Set(['stack', 'stacktrace', 'stack_trace']);\n\n/**\n * Caps a long string, keeping the ORIGINAL LENGTH in the marker - that number is what tells you the\n * payload was a 300 KB image rather than a truncated sentence.\n *\n * A base64 body is the case this exists for: one `data:image/png;base64,...` field turns a request\n * log into hundreds of kilobytes, and nothing about it is readable.\n */\nconst capString = (opts: { value: string; key?: string; limit: number }): string => {\n const { value, key, limit } = opts;\n\n if (limit === 0 || value.length <= limit || (key && UNCAPPED_KEYS.has(key.toLowerCase()))) {\n return value;\n }\n\n return `${value.slice(0, limit)}... [truncated, ${value.length} chars total]`;\n};\n\ntype TSanitizeContext = {\n seen: WeakSet<object>;\n doRedact: boolean;\n /** Levels still allowed BELOW the current one; `Infinity` walks the whole graph. */\n depth: number;\n /** Longest string kept whole; 0 keeps every string. */\n maxStringLength: number;\n /** The key this value was found under, so a stack trace can be exempted from capping. */\n key?: string;\n};\n\nconst deepSanitize = (value: unknown, context: TSanitizeContext): unknown => {\n const { seen, doRedact, depth } = context;\n\n if (typeof value === 'string') {\n return capString({ value, key: context.key, limit: context.maxStringLength });\n }\n\n if (value === null || typeof value !== 'object') {\n return value;\n }\n\n // A Date holds its value in an internal slot, so the generic branch below - which reads Object.keys() - would flatten it to `{}`. Checked BEFORE `seen`: a Date cannot carry a cycle, and entering the set would make a second reference to the same instance read as `[Circular]`.\n if (value instanceof Date) {\n return value;\n }\n\n if (seen.has(value)) {\n return '[Circular]';\n }\n\n if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {\n return `[Binary ${(value as ArrayBufferView).byteLength ?? 0} bytes]`;\n }\n\n if (depth <= 0) {\n return Array.isArray(value) ? '[Array]' : '[Object]';\n }\n\n seen.add(value);\n const nested: TSanitizeContext = {\n seen,\n doRedact,\n depth: depth - 1,\n maxStringLength: context.maxStringLength,\n };\n\n // Error keeps name/message/stack NON-enumerable, so Object.keys() skips them and naive redaction would drop the message - reproject into a plain object carrying those fields plus its redacted enumerable own-props.\n if (value instanceof Error) {\n const source = value;\n const result: AnyObject = {\n name: value.name,\n message: value.message,\n stack: value.stack,\n };\n\n for (const [key, entry] of Object.entries(source)) {\n result[key] =\n doRedact && SECRET_KEY_PATTERN.test(key)\n ? REDACTED\n : deepSanitize(entry, { ...nested, key });\n }\n\n return result;\n }\n\n if (Array.isArray(value)) {\n return value.map((entry) => deepSanitize(entry, nested));\n }\n\n const source = value;\n const result: AnyObject = {};\n\n for (const [key, entry] of Object.entries(source)) {\n if (doRedact && SECRET_KEY_PATTERN.test(key)) {\n result[key] = REDACTED;\n continue;\n }\n\n result[key] = deepSanitize(entry, { ...nested, key });\n }\n\n return result;\n};\n\n/** Makes a log argument safe to print: masks secret-looking keys, breaks cycles, caps long strings and strips URL credentials. `APP_ENV_LOGGER_DO_REDACT=false` turns off the key masking only. */\nexport class RedactUtility {\n /**\n * Redacts every secret-looking KEY (not value shape - buffers/typed arrays are summarized, not\n * serialized). `APP_ENV_LOGGER_DO_REDACT=false` makes this the identity function.\n *\n * `depth` bounds the walk, exactly as {@link RedactUtility.toJsonSafe} already does. It defaults to\n * `Infinity` for callers that really do want the whole graph, but the logger passes its own bound:\n * rendering only inspects a handful of levels, so walking to `Infinity` did work whose result was\n * thrown away - 12x on a deep graph, and a `RangeError` on a very deep chain.\n */\n static redactSecrets(opts: { value: unknown; seen?: WeakSet<object>; depth?: number }): unknown {\n const { value, seen, depth = Infinity } = opts;\n\n if (!isRedactionEnabled()) {\n return value;\n }\n\n return deepSanitize(value, {\n seen: seen ?? new WeakSet<object>(),\n doRedact: true,\n depth,\n maxStringLength: resolveMaxStringLength(),\n });\n }\n\n /** Projects a value into something `JSON.stringify` can render: it answers `[Circular]` for the WHOLE payload when one cycle sits anywhere inside it, so cycles must be broken per-branch first. `depth` bounds the walk the way `util.inspect` does - a log argument may hold a live connector or request context, whose graph is effectively unbounded. The projection itself is unconditional: `APP_ENV_LOGGER_DO_REDACT=false` turns off the key masking, never the structural pass. */\n static toJsonSafe(opts: { value: unknown; depth?: number }): unknown {\n return deepSanitize(opts.value, {\n seen: new WeakSet<object>(),\n doRedact: isRedactionEnabled(),\n depth: opts.depth ?? Infinity,\n // Capping is STRUCTURAL, like the projection itself: turning redaction off is about key masking,\n // never about letting a 300 KB base64 field through.\n maxStringLength: resolveMaxStringLength(),\n });\n }\n\n /** Strips credentials from a connection URL's authority section (`user:hunter2@host` -> `user:[REDACTED]@host`) - {@link RedactUtility.redactSecrets} matches on KEY names and can't see them there. A value that fails to parse as a URL is returned unchanged. */\n static redactUrlCredentials(opts: { url: string }): string {\n const { url } = opts;\n\n if (!isRedactionEnabled()) {\n return url;\n }\n\n let parsed: URL;\n\n try {\n parsed = new URL(url);\n } catch {\n return url;\n }\n\n if (!parsed.password) {\n return url;\n }\n\n parsed.password = REDACTED;\n\n return decodeURIComponent(parsed.toString());\n }\n}\n"]}
1
+ {"version":3,"file":"redact.js","sourceRoot":"","sources":["../../../src/common/redact.ts"],"names":[],"mappings":"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","sourcesContent":["import { type AnyObject } from './types';\n\n/** Keys whose VALUES must never reach a log line - matched case-insensitively on the key name, at any depth. */\nconst SECRET_KEY_PATTERN = new RegExp(\n [\n // Options-object spellings (camelCase / snake_case).\n '^(pass|password|passphrase|secret|token|apiKey|api_key|accessKey|access_key',\n '|secretKey|secret_key|privateKey|private_key|key|cert|ca|pfx|credentials',\n '|authorization|auth|jwtSecret|applicationSecret|connectionString)$',\n\n // Vault wire spellings (snake_case): node-vault's AppRole login/response bodies carry these exact keys, and none are matched by the anchored options list above.\n '|^(client_token|secret_id|role_id)$',\n\n // Any `*_token` (snake_case) or `*Token` (camelCase) key; a preceding character is required so the bare word `token` (already covered above) is not the whole match, and so ordinary words are not swallowed.\n '|_token$|[a-z0-9]token$',\n\n // The `*Secret` counterpart the `*Token` rule always lacked. `clientSecret` / `client_secret` is the RFC 6749 parameter name and a live field on the search connector's model options, and `webhookSecret` is the standard spelling everywhere; none of them matched the anchored list above.\n '|_secret$|[a-z0-9]secret$',\n\n // Connection descriptors: `connectionString` was anchored above but its snake_case twin was not, and `dsn` is the third common spelling for the same thing.\n '|^(connection_string|dsn|database_url|databaseUrl)$',\n\n // Any `*_password` / `*Password` key - `dbPassword`, `admin_password`. The bare word is anchored above; this catches the prefixed forms.\n '|_password$|[a-z0-9]password$',\n\n // HTTP HEADER spellings: header names are kebab-case and often `x-`-prefixed, none of which the camelCase list above matches; `vault` is included so `X-Vault-Token` (node-vault's auth header) is caught.\n '|^(x-)?(api|auth|access|secret|session|csrf|xsrf|vault)-(key|token|secret|id)$',\n '|^(cookie|set-cookie|proxy-authorization|www-authenticate)$',\n ].join(''),\n 'i',\n);\n\n/** The placeholder that replaces a secret value in redacted output. */\nexport const REDACTED = '[REDACTED]';\n\n/** Kill-switch for local debugging: only the literal `false` disables redaction (fail-closed); read per call so it can be flipped at runtime. Never disable in production. `force` is the caller opting out of the switch: it always masks. */\nconst isRedactionEnabled = (force?: boolean): boolean =>\n force === true || globalThis.process?.env?.APP_ENV_LOGGER_DO_REDACT !== 'false';\n\n/** Longest string a log line carries whole. `APP_ENV_LOGGER_MAX_STRING_LENGTH=0` turns capping off. */\nconst DEFAULT_MAX_STRING_LENGTH = 2048;\n\nconst resolveMaxStringLength = (): number => {\n const configured = Number(globalThis.process?.env?.APP_ENV_LOGGER_MAX_STRING_LENGTH);\n\n return Number.isFinite(configured) && configured >= 0 ? configured : DEFAULT_MAX_STRING_LENGTH;\n};\n\n/**\n * Keys whose value is long BY NATURE and useless truncated. A stack trace is the whole reason you\n * are reading the line.\n */\nconst UNCAPPED_KEYS = new Set(['stack', 'stacktrace', 'stack_trace']);\n\n/**\n * Caps a long string, keeping the ORIGINAL LENGTH in the marker - that number is what tells you the\n * payload was a 300 KB image rather than a truncated sentence.\n *\n * A base64 body is the case this exists for: one `data:image/png;base64,...` field turns a request\n * log into hundreds of kilobytes, and nothing about it is readable.\n */\nconst capString = (opts: { value: string; key?: string; limit: number }): string => {\n const { value, key, limit } = opts;\n\n if (limit === 0 || value.length <= limit || (key && UNCAPPED_KEYS.has(key.toLowerCase()))) {\n return value;\n }\n\n return `${value.slice(0, limit)}... [truncated, ${value.length} chars total]`;\n};\n\ntype TSanitizeContext = {\n seen: WeakSet<object>;\n doRedact: boolean;\n /** Levels still allowed BELOW the current one; `Infinity` walks the whole graph. */\n depth: number;\n /** Longest string kept whole; 0 keeps every string. */\n maxStringLength: number;\n /** The key this value was found under, so a stack trace can be exempted from capping. */\n key?: string;\n};\n\nconst deepSanitize = (value: unknown, context: TSanitizeContext): unknown => {\n const { seen, doRedact, depth } = context;\n\n if (typeof value === 'string') {\n return capString({ value, key: context.key, limit: context.maxStringLength });\n }\n\n if (value === null || typeof value !== 'object') {\n return value;\n }\n\n // A Date holds its value in an internal slot, so the generic branch below - which reads Object.keys() - would flatten it to `{}`. Checked BEFORE `seen`: a Date cannot carry a cycle, and entering the set would make a second reference to the same instance read as `[Circular]`.\n if (value instanceof Date) {\n return value;\n }\n\n if (seen.has(value)) {\n return '[Circular]';\n }\n\n if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {\n return `[Binary ${(value as ArrayBufferView).byteLength ?? 0} bytes]`;\n }\n\n if (depth <= 0) {\n return Array.isArray(value) ? '[Array]' : '[Object]';\n }\n\n seen.add(value);\n const nested: TSanitizeContext = {\n seen,\n doRedact,\n depth: depth - 1,\n maxStringLength: context.maxStringLength,\n };\n\n // Error keeps name/message/stack NON-enumerable, so Object.keys() skips them and naive redaction would drop the message - reproject into a plain object carrying those fields plus its redacted enumerable own-props.\n if (value instanceof Error) {\n const source = value;\n const result: AnyObject = {\n name: value.name,\n message: value.message,\n stack: value.stack,\n };\n\n for (const [key, entry] of Object.entries(source)) {\n result[key] =\n doRedact && SECRET_KEY_PATTERN.test(key)\n ? REDACTED\n : deepSanitize(entry, { ...nested, key });\n }\n\n return result;\n }\n\n if (Array.isArray(value)) {\n return value.map((entry) => deepSanitize(entry, nested));\n }\n\n const source = value;\n const result: AnyObject = {};\n\n for (const [key, entry] of Object.entries(source)) {\n if (doRedact && SECRET_KEY_PATTERN.test(key)) {\n result[key] = REDACTED;\n continue;\n }\n\n result[key] = deepSanitize(entry, { ...nested, key });\n }\n\n return result;\n};\n\n/** Makes a log argument safe to print: masks secret-looking keys, breaks cycles, caps long strings and strips URL credentials. `APP_ENV_LOGGER_DO_REDACT=false` turns off the key masking only. */\nexport class RedactUtility {\n /**\n * Redacts every secret-looking KEY (not value shape - buffers/typed arrays are summarized, not\n * serialized). `APP_ENV_LOGGER_DO_REDACT=false` makes this the identity function.\n *\n * `depth` bounds the walk, exactly as {@link RedactUtility.toJsonSafe} already does. It defaults to\n * `Infinity` for callers that really do want the whole graph, but the logger passes its own bound:\n * rendering only inspects a handful of levels, so walking to `Infinity` did work whose result was\n * thrown away - 12x on a deep graph, and a `RangeError` on a very deep chain.\n *\n * `force: true` masks secret-looking KEYS even when `APP_ENV_LOGGER_DO_REDACT=false`. The result is still the\n * log-shaped copy: long strings are capped, a second reference to one object reads `[Circular]`, binary is\n * summarized, and a key is masked by name only (a card number under `number` is not). It is not a faithful\n * redacted document. The logger never sets it.\n */\n static redactSecrets(opts: {\n value: unknown;\n seen?: WeakSet<object>;\n depth?: number;\n force?: boolean;\n }): unknown {\n const { value, seen, depth = Infinity, force } = opts;\n\n if (!isRedactionEnabled(force)) {\n return value;\n }\n\n return deepSanitize(value, {\n seen: seen ?? new WeakSet<object>(),\n doRedact: true,\n depth,\n maxStringLength: resolveMaxStringLength(),\n });\n }\n\n /** Projects a value into something `JSON.stringify` can render: it answers `[Circular]` for the WHOLE payload when one cycle sits anywhere inside it, so cycles must be broken per-branch first. `depth` bounds the walk the way `util.inspect` does - a log argument may hold a live connector or request context, whose graph is effectively unbounded. The projection itself is unconditional: `APP_ENV_LOGGER_DO_REDACT=false` turns off the key masking, never the structural pass. `force: true` keeps the key masking on whatever the switch says; the projection stays lossy, as in {@link RedactUtility.redactSecrets}. */\n static toJsonSafe(opts: { value: unknown; depth?: number; force?: boolean }): unknown {\n return deepSanitize(opts.value, {\n seen: new WeakSet<object>(),\n doRedact: isRedactionEnabled(opts.force),\n depth: opts.depth ?? Infinity,\n // Capping is STRUCTURAL, like the projection itself: turning redaction off is about key masking,\n // never about letting a 300 KB base64 field through.\n maxStringLength: resolveMaxStringLength(),\n });\n }\n\n /** Strips credentials from a connection URL's authority section (`user:hunter2@host` -> `user:[REDACTED]@host`) - {@link RedactUtility.redactSecrets} matches on KEY names and can't see them there. A value that fails to parse as a URL is returned unchanged. `force: true` strips even when `APP_ENV_LOGGER_DO_REDACT=false`. */\n static redactUrlCredentials(opts: { url: string; force?: boolean }): string {\n const { url, force } = opts;\n\n if (!isRedactionEnabled(force)) {\n return url;\n }\n\n let parsed: URL;\n\n try {\n parsed = new URL(url);\n } catch {\n return url;\n }\n\n if (!parsed.password) {\n return url;\n }\n\n parsed.password = REDACTED;\n\n return decodeURIComponent(parsed.toString());\n }\n}\n"]}
@@ -28,6 +28,7 @@ export { BuildInfoRegistry } from './utilities/build-info.utility.js';
28
28
  export type { IBuildInfo, TBuildInfoRecord } from './utilities/build-info.utility.js';
29
29
  export { ParseUtility } from './utilities/parse.utility.js';
30
30
  export { PerformanceUtility } from './utilities/performance.utility.js';
31
+ export { RecordUtility } from './utilities/record.utility.js';
31
32
  export { FormBodyUtility, RequestBodyErrors } from './utilities/form-body.utility.js';
32
33
  export { ProjectRootRegistry } from './utilities/project-root.utility.js';
33
34
  export { AbstractCryptoAlgorithm } from './modules/crypto/algorithms/abstract.algorithm.js';
package/dist/esm/core.js CHANGED
@@ -35,6 +35,7 @@ export { TreeWalker } from './modules/tree/walk.js';
35
35
  export { BuildInfoRegistry } from './utilities/build-info.utility.js';
36
36
  export { ParseUtility } from './utilities/parse.utility.js';
37
37
  export { PerformanceUtility } from './utilities/performance.utility.js';
38
+ export { RecordUtility } from './utilities/record.utility.js';
38
39
  export { FormBodyUtility, RequestBodyErrors } from './utilities/form-body.utility.js';
39
40
  export { ProjectRootRegistry } from './utilities/project-root.utility.js';
40
41
  // `ECDH` is the one crypto algorithm that is browser-pure: it runs over `crypto.subtle`, `btoa` and `atob`. It and its
@@ -1 +1 @@
1
- {"version":3,"file":"core.js","sourceRoot":"","sources":["../../src/core.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,6FAA6F;AAC7F,8DAA8D;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE1D,6HAA6H;AAC7H,iHAAiH;AACjH,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,cAAc,qDAAqD,CAAC;AACpE,qGAAqG;AACrG,4FAA4F;AAC5F,oBAAoB;AACpB,cAAc,qDAAqD,CAAC;AACpE,cAAc,4DAA4D,CAAC;AAC3E,cAAc,gBAAgB,CAAC;AAC/B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,iGAAiG;AACjG,yFAAyF;AACzF,cAAc,yDAAyD,CAAC;AAExE,cAAc,+CAA+C,CAAC;AAC9D,cAAc,0CAA0C,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAG5F,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAcrD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjD,gGAAgG;AAChG,6FAA6F;AAC7F,iGAAiG;AACjG,0DAA0D;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAEnE,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACnF,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAEvE,uHAAuH;AACvH,gGAAgG;AAChG,0EAA0E;AAC1E,OAAO,EAAE,uBAAuB,EAAE,MAAM,gDAAgD,CAAC;AACzF,OAAO,EAAE,IAAI,EAAE,MAAM,4CAA4C,CAAC;AAOlE,+FAA+F;AAC/F,6GAA6G;AAC7G,wCAAwC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,2CAA2C,CAAC","sourcesContent":["export { BaseHelper } from './modules/base';\n// By name, never `export *` from `./modules/env`: that barrel also carries `Environment` and\n// `applicationEnvironment`, both of which read `process.env`.\nexport { EnvironmentNames } from './modules/env/names';\nexport * from './modules/error';\nexport { LogLevels } from './modules/logger/common/types';\nexport type { ILogger, ILoggerProvider, TLogLevel } from './modules/logger/common/types';\n// The one way to get a logger, the same in the browser and on the server: `LoggerFactory` imports nothing from node, and its\n// default provider is the console. An application chooses another with `LoggerFactory.use({ provider, level })`.\nexport { ConsoleLogger } from './modules/logger/base/console';\nexport { LoggerFactory } from './modules/logger/factory';\nexport * from './modules/network/http-request/fetcher/base-fetcher';\n// The node fetcher carries no node builtin - its one `querystring.stringify` is written out - so the\n// framework HTTP layer is reachable from a browser bundle, and a connector on HTTP need not\n// re-implement one.\nexport * from './modules/network/http-request/fetcher/node-fetcher';\nexport * from './modules/network/http-request/base-network-request.helper';\nexport * from './modules/pool';\nexport * from './modules/queue/internal/hf';\nexport * from './modules/temporal';\nexport * from './modules/uid';\n// The url guard, pure half only: `UrlPolicy` decides a url and a literal address with string and\n// number work. Its sibling `UrlIngest` reaches `node:dns` and stays out of this subpath.\nexport * from './modules/network/utilities/url-safety/common/constants';\nexport type { IUrlSafetyPolicy } from './modules/network/utilities/url-safety/common/types';\nexport * from './modules/network/utilities/url-safety/policy';\nexport * from './modules/network/utilities/query-string';\nexport { RetryBackoffStrategies, RetryJitterModes } from './modules/retry/common/constants';\nexport type { TRetryBackoffStrategy, TRetryJitterMode } from './modules/retry/common/constants';\nexport type { IRetryBackoffOptions, IRetryContext } from './modules/retry/common/types';\nexport { RetryHelper } from './modules/retry/helper';\nexport { SlugHelper } from './modules/slug/helper';\nexport { TreeBuilder } from './modules/tree/builder';\nexport type {\n IBuildOptions,\n IHeightWhereOptions,\n ILeavesOptions,\n INodeWithPath,\n IPrintOptions,\n ITreeNode,\n IWalkAsyncOptions,\n IWalkOptions,\n TNodePredicate,\n TOnVisit,\n TOnVisitAsync,\n} from './modules/tree/common/types';\nexport { TreeWalker } from './modules/tree/walk';\n\n// Pure value/type utilities that already live under the root barrel's `./utilities` re-export -\n// that barrel also carries node-only siblings (module.utility.ts, request.utility.ts), so it\n// cannot itself become a subpath. Named one at a time here instead of widening the barrel: every\n// symbol below is verified free of node builtins/globals.\nexport { BuildInfoRegistry } from './utilities/build-info.utility';\nexport type { IBuildInfo, TBuildInfoRecord } from './utilities/build-info.utility';\nexport { ParseUtility } from './utilities/parse.utility';\nexport { PerformanceUtility } from './utilities/performance.utility';\nexport { FormBodyUtility, RequestBodyErrors } from './utilities/form-body.utility';\nexport { ProjectRootRegistry } from './utilities/project-root.utility';\n\n// `ECDH` is the one crypto algorithm that is browser-pure: it runs over `crypto.subtle`, `btoa` and `atob`. It and its\n// base class come by leaf path, never the algorithms barrel, which also carries `AES` and `RSA`\n// (server code: they use `Buffer`, and `AES` reads files with `node:fs`).\nexport { AbstractCryptoAlgorithm } from './modules/crypto/algorithms/abstract.algorithm';\nexport { ECDH } from './modules/crypto/algorithms/ecdh.algorithm';\nexport type {\n ECDHAlgorithmType,\n IECDHEncryptedPayload,\n IECDHExtraOptions,\n} from './modules/crypto/algorithms/ecdh.algorithm';\n\n// Type-only: erased at compile time, so re-exporting these carries no runtime/bundle cost even\n// though the concrete classes they describe (the other crypto algorithms, the ioredis-backed helper) are not\n// themselves part of this pure surface.\nexport { AESAlgorithms } from './modules/crypto/algorithms/aes.constants';\nexport type { AESAlgorithmType } from './modules/crypto/algorithms/aes.constants';\nexport type { IRedisHelper } from './modules/redis/common/interfaces';\n"]}
1
+ {"version":3,"file":"core.js","sourceRoot":"","sources":["../../src/core.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,6FAA6F;AAC7F,8DAA8D;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE1D,6HAA6H;AAC7H,iHAAiH;AACjH,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,cAAc,qDAAqD,CAAC;AACpE,qGAAqG;AACrG,4FAA4F;AAC5F,oBAAoB;AACpB,cAAc,qDAAqD,CAAC;AACpE,cAAc,4DAA4D,CAAC;AAC3E,cAAc,gBAAgB,CAAC;AAC/B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,iGAAiG;AACjG,yFAAyF;AACzF,cAAc,yDAAyD,CAAC;AAExE,cAAc,+CAA+C,CAAC;AAC9D,cAAc,0CAA0C,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAG5F,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAcrD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjD,gGAAgG;AAChG,6FAA6F;AAC7F,iGAAiG;AACjG,0DAA0D;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAEnE,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACnF,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAEvE,uHAAuH;AACvH,gGAAgG;AAChG,0EAA0E;AAC1E,OAAO,EAAE,uBAAuB,EAAE,MAAM,gDAAgD,CAAC;AACzF,OAAO,EAAE,IAAI,EAAE,MAAM,4CAA4C,CAAC;AAOlE,+FAA+F;AAC/F,6GAA6G;AAC7G,wCAAwC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,2CAA2C,CAAC","sourcesContent":["export { BaseHelper } from './modules/base';\n// By name, never `export *` from `./modules/env`: that barrel also carries `Environment` and\n// `applicationEnvironment`, both of which read `process.env`.\nexport { EnvironmentNames } from './modules/env/names';\nexport * from './modules/error';\nexport { LogLevels } from './modules/logger/common/types';\nexport type { ILogger, ILoggerProvider, TLogLevel } from './modules/logger/common/types';\n// The one way to get a logger, the same in the browser and on the server: `LoggerFactory` imports nothing from node, and its\n// default provider is the console. An application chooses another with `LoggerFactory.use({ provider, level })`.\nexport { ConsoleLogger } from './modules/logger/base/console';\nexport { LoggerFactory } from './modules/logger/factory';\nexport * from './modules/network/http-request/fetcher/base-fetcher';\n// The node fetcher carries no node builtin - its one `querystring.stringify` is written out - so the\n// framework HTTP layer is reachable from a browser bundle, and a connector on HTTP need not\n// re-implement one.\nexport * from './modules/network/http-request/fetcher/node-fetcher';\nexport * from './modules/network/http-request/base-network-request.helper';\nexport * from './modules/pool';\nexport * from './modules/queue/internal/hf';\nexport * from './modules/temporal';\nexport * from './modules/uid';\n// The url guard, pure half only: `UrlPolicy` decides a url and a literal address with string and\n// number work. Its sibling `UrlIngest` reaches `node:dns` and stays out of this subpath.\nexport * from './modules/network/utilities/url-safety/common/constants';\nexport type { IUrlSafetyPolicy } from './modules/network/utilities/url-safety/common/types';\nexport * from './modules/network/utilities/url-safety/policy';\nexport * from './modules/network/utilities/query-string';\nexport { RetryBackoffStrategies, RetryJitterModes } from './modules/retry/common/constants';\nexport type { TRetryBackoffStrategy, TRetryJitterMode } from './modules/retry/common/constants';\nexport type { IRetryBackoffOptions, IRetryContext } from './modules/retry/common/types';\nexport { RetryHelper } from './modules/retry/helper';\nexport { SlugHelper } from './modules/slug/helper';\nexport { TreeBuilder } from './modules/tree/builder';\nexport type {\n IBuildOptions,\n IHeightWhereOptions,\n ILeavesOptions,\n INodeWithPath,\n IPrintOptions,\n ITreeNode,\n IWalkAsyncOptions,\n IWalkOptions,\n TNodePredicate,\n TOnVisit,\n TOnVisitAsync,\n} from './modules/tree/common/types';\nexport { TreeWalker } from './modules/tree/walk';\n\n// Pure value/type utilities that already live under the root barrel's `./utilities` re-export -\n// that barrel also carries node-only siblings (module.utility.ts, request.utility.ts), so it\n// cannot itself become a subpath. Named one at a time here instead of widening the barrel: every\n// symbol below is verified free of node builtins/globals.\nexport { BuildInfoRegistry } from './utilities/build-info.utility';\nexport type { IBuildInfo, TBuildInfoRecord } from './utilities/build-info.utility';\nexport { ParseUtility } from './utilities/parse.utility';\nexport { PerformanceUtility } from './utilities/performance.utility';\nexport { RecordUtility } from './utilities/record.utility';\nexport { FormBodyUtility, RequestBodyErrors } from './utilities/form-body.utility';\nexport { ProjectRootRegistry } from './utilities/project-root.utility';\n\n// `ECDH` is the one crypto algorithm that is browser-pure: it runs over `crypto.subtle`, `btoa` and `atob`. It and its\n// base class come by leaf path, never the algorithms barrel, which also carries `AES` and `RSA`\n// (server code: they use `Buffer`, and `AES` reads files with `node:fs`).\nexport { AbstractCryptoAlgorithm } from './modules/crypto/algorithms/abstract.algorithm';\nexport { ECDH } from './modules/crypto/algorithms/ecdh.algorithm';\nexport type {\n ECDHAlgorithmType,\n IECDHEncryptedPayload,\n IECDHExtraOptions,\n} from './modules/crypto/algorithms/ecdh.algorithm';\n\n// Type-only: erased at compile time, so re-exporting these carries no runtime/bundle cost even\n// though the concrete classes they describe (the other crypto algorithms, the ioredis-backed helper) are not\n// themselves part of this pure surface.\nexport { AESAlgorithms } from './modules/crypto/algorithms/aes.constants';\nexport type { AESAlgorithmType } from './modules/crypto/algorithms/aes.constants';\nexport type { IRedisHelper } from './modules/redis/common/interfaces';\n"]}
@@ -39,6 +39,22 @@ export declare class Hash extends BaseHelper {
39
39
  secret: THashInput;
40
40
  opts?: IHashExtraOptions;
41
41
  }): string;
42
+ /**
43
+ * Checks a received digest against the one `value` produces, in constant time. Use it for a webhook signature or a
44
+ * payment callback instead of `===`, which stops at the first differing character and so tells an attacker how many
45
+ * leading characters of a forged value were right.
46
+ *
47
+ * `value` is hashed the way {@link Hash.digest} does, or keyed with `secret` the way {@link Hash.hmac} does, then
48
+ * written in `outputEncoding` (hex by default) and compared with `expected` as text. A different length answers
49
+ * `false` without comparing, and the answer is `false`, never a throw, for any mismatch. The text must match exactly:
50
+ * hex in upper case does not equal hex in lower case.
51
+ */
52
+ verify(opts: {
53
+ value: THashInput;
54
+ expected: string;
55
+ secret?: THashInput;
56
+ opts?: IHashExtraOptions;
57
+ }): boolean;
42
58
  }
43
59
  export {};
44
60
  //# sourceMappingURL=hash.algorithm.d.ts.map
@@ -1,3 +1,4 @@
1
+ import crypto from 'node:crypto';
1
2
  import { BaseHelper } from '../../base.js';
2
3
  import { getError } from '../../error/index.js';
3
4
  import { DEFAULT_HASH_OUTPUT_ENCODING, HashAlgorithms, } from '../common/index.js';
@@ -59,5 +60,24 @@ export class Hash extends BaseHelper {
59
60
  }
60
61
  return new Bun.CryptoHasher(this.algorithm, secret).update(message).digest(outputEncoding);
61
62
  }
63
+ /**
64
+ * Checks a received digest against the one `value` produces, in constant time. Use it for a webhook signature or a
65
+ * payment callback instead of `===`, which stops at the first differing character and so tells an attacker how many
66
+ * leading characters of a forged value were right.
67
+ *
68
+ * `value` is hashed the way {@link Hash.digest} does, or keyed with `secret` the way {@link Hash.hmac} does, then
69
+ * written in `outputEncoding` (hex by default) and compared with `expected` as text. A different length answers
70
+ * `false` without comparing, and the answer is `false`, never a throw, for any mismatch. The text must match exactly:
71
+ * hex in upper case does not equal hex in lower case.
72
+ */
73
+ verify(opts) {
74
+ const { value, expected, secret } = opts;
75
+ const computed = Buffer.from(secret === undefined
76
+ ? this.digest({ message: value, opts: opts.opts })
77
+ : this.hmac({ message: value, secret, opts: opts.opts }));
78
+ const given = Buffer.from(expected);
79
+ // Length-checked first: `timingSafeEqual` throws on a length mismatch instead of answering false.
80
+ return computed.length === given.length && crypto.timingSafeEqual(computed, given);
81
+ }
62
82
  }
63
83
  //# sourceMappingURL=hash.algorithm.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"hash.algorithm.js","sourceRoot":"","sources":["../../../../../src/modules/crypto/algorithms/hash.algorithm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EACL,4BAA4B,EAC5B,cAAc,GAGf,MAAM,WAAW,CAAC;AASnB;;;GAGG;AACH,MAAM,OAAO,IAAK,SAAQ,UAAU;IAGlC,YAAY,IAAmC;QAC7C,KAAK,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;QACxD,IAAI,CAAC,qBAAqB,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;QAE1D,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IAClC,CAAC;IAED,wJAAwJ;aAChI,cAAS,GAAG,IAAI,GAAG,EAAwB,CAAC;IAEpE,MAAM,CAAC,aAAa,CAAC,SAAyB;QAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAE7C,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC;QACxC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAEvC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,qBAAqB,CAAC,IAAmC;QACvD,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;QAE3B,IAAI,CAAC,SAAS,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;YACrD,MAAM,QAAQ,CAAC;gBACb,OAAO,EAAE,qEAAqE,SAAS,EAAE;aAC1F,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,IAGN;QACC,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;QACzB,MAAM,EAAE,cAAc,GAAG,4BAA4B,EAAE,GAAG,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;QAC1E,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAElD,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;YAChE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;QAED,OAAO,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IACrC,CAAC;IAED;;;;OAIG;IACH,IAAI,CAAC,IAA2E;QAC9E,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QACjC,MAAM,EAAE,cAAc,GAAG,4BAA4B,EAAE,GAAG,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;QAE1E,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,MAAM,QAAQ,CAAC;gBACb,OAAO,EAAE,wCAAwC,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,EAAE;aAChF,CAAC,CAAC;QACL,CAAC;QAED,OAAO,IAAI,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IAC7F,CAAC","sourcesContent":["import { BaseHelper } from '@/modules/base';\nimport { getError } from '@/modules/error';\nimport {\n DEFAULT_HASH_OUTPUT_ENCODING,\n HashAlgorithms,\n type THashAlgorithm,\n type THashOutputEncoding,\n} from '../common';\n\ninterface IHashExtraOptions {\n outputEncoding?: THashOutputEncoding;\n}\n\n/** Text is hashed as UTF-8, bytes as they are. */\ntype THashInput = string | Uint8Array;\n\n/**\n * One-way message digests and keyed HMACs. Unlike `AES`/`RSA` this has no `decrypt` - a digest\n * cannot be reversed, so `digest`/`hmac` are the only operations, not `ICryptoAlgorithm`.\n */\nexport class Hash extends BaseHelper {\n algorithm: THashAlgorithm;\n\n constructor(opts: { algorithm: THashAlgorithm }) {\n super({ scope: Hash.name, identifier: opts.algorithm });\n this.validateAlgorithmName({ algorithm: opts.algorithm });\n\n this.algorithm = opts.algorithm;\n }\n\n /** Memoized - `BaseHelper`'s constructor resolves a logger on every allocation (~50ns), and downstream token code calls `withAlgorithm` per request. */\n private static readonly instances = new Map<THashAlgorithm, Hash>();\n\n static withAlgorithm(algorithm: THashAlgorithm) {\n const cached = Hash.instances.get(algorithm);\n\n if (cached) {\n return cached;\n }\n\n const created = new Hash({ algorithm });\n Hash.instances.set(algorithm, created);\n\n return created;\n }\n\n validateAlgorithmName(opts: { algorithm: THashAlgorithm }) {\n const { algorithm } = opts;\n\n if (!algorithm || !HashAlgorithms.isValid(algorithm)) {\n throw getError({\n message: `[Hash][validateAlgorithmName] Invalid algorithm name | algorithm: ${algorithm}`,\n });\n }\n }\n\n /**\n * Plain digest, no secret. `message` is text (UTF-8), bytes, or several parts hashed in order as ONE message: a git\n * blob is the header text \"blob <size>\" and a NUL byte, then the bytes, so its parts are the header and the bytes. MD5/SHA1\n * are broken/weak - see {@link HashAlgorithms} - never use for security decisions.\n */\n digest(opts: {\n message: THashInput | ReadonlyArray<THashInput>;\n opts?: IHashExtraOptions;\n }): string {\n const { message } = opts;\n const { outputEncoding = DEFAULT_HASH_OUTPUT_ENCODING } = opts.opts ?? {};\n const hash = new Bun.CryptoHasher(this.algorithm);\n\n for (const part of Array.isArray(message) ? message : [message]) {\n hash.update(part);\n }\n\n return hash.digest(outputEncoding);\n }\n\n /**\n * Keyed HMAC. `message` and `secret` are text (UTF-8) or bytes: a `Buffer` or `Uint8Array` key gives the same output\n * as the text of the same bytes, so a token printed with one keeps verifying with the other. `secret` is mandatory and\n * validated non-empty so a request for an HMAC never silently degrades into an unkeyed digest.\n */\n hmac(opts: { message: THashInput; secret: THashInput; opts?: IHashExtraOptions }): string {\n const { message, secret } = opts;\n const { outputEncoding = DEFAULT_HASH_OUTPUT_ENCODING } = opts.opts ?? {};\n\n if (secret.length === 0) {\n throw getError({\n message: `[Hash][hmac] Missing secret for HMAC-${this.algorithm.toUpperCase()}`,\n });\n }\n\n return new Bun.CryptoHasher(this.algorithm, secret).update(message).digest(outputEncoding);\n }\n}\n"]}
1
+ {"version":3,"file":"hash.algorithm.js","sourceRoot":"","sources":["../../../../../src/modules/crypto/algorithms/hash.algorithm.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAC;AAEjC,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EACL,4BAA4B,EAC5B,cAAc,GAGf,MAAM,WAAW,CAAC;AASnB;;;GAGG;AACH,MAAM,OAAO,IAAK,SAAQ,UAAU;IAGlC,YAAY,IAAmC;QAC7C,KAAK,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;QACxD,IAAI,CAAC,qBAAqB,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;QAE1D,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IAClC,CAAC;IAED,wJAAwJ;aAChI,cAAS,GAAG,IAAI,GAAG,EAAwB,CAAC;IAEpE,MAAM,CAAC,aAAa,CAAC,SAAyB;QAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAE7C,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC;QACxC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAEvC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,qBAAqB,CAAC,IAAmC;QACvD,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;QAE3B,IAAI,CAAC,SAAS,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;YACrD,MAAM,QAAQ,CAAC;gBACb,OAAO,EAAE,qEAAqE,SAAS,EAAE;aAC1F,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,IAGN;QACC,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;QACzB,MAAM,EAAE,cAAc,GAAG,4BAA4B,EAAE,GAAG,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;QAC1E,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAElD,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;YAChE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;QAED,OAAO,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IACrC,CAAC;IAED;;;;OAIG;IACH,IAAI,CAAC,IAA2E;QAC9E,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QACjC,MAAM,EAAE,cAAc,GAAG,4BAA4B,EAAE,GAAG,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;QAE1E,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,MAAM,QAAQ,CAAC;gBACb,OAAO,EAAE,wCAAwC,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,EAAE;aAChF,CAAC,CAAC;QACL,CAAC;QAED,OAAO,IAAI,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IAC7F,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,IAKN;QACC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QACzC,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAC1B,MAAM,KAAK,SAAS;YAClB,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;YAClD,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAC3D,CAAC;QACF,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAEpC,kGAAkG;QAClG,OAAO,QAAQ,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM,IAAI,MAAM,CAAC,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACrF,CAAC","sourcesContent":["import crypto from 'node:crypto';\n\nimport { BaseHelper } from '@/modules/base';\nimport { getError } from '@/modules/error';\nimport {\n DEFAULT_HASH_OUTPUT_ENCODING,\n HashAlgorithms,\n type THashAlgorithm,\n type THashOutputEncoding,\n} from '../common';\n\ninterface IHashExtraOptions {\n outputEncoding?: THashOutputEncoding;\n}\n\n/** Text is hashed as UTF-8, bytes as they are. */\ntype THashInput = string | Uint8Array;\n\n/**\n * One-way message digests and keyed HMACs. Unlike `AES`/`RSA` this has no `decrypt` - a digest\n * cannot be reversed, so `digest`/`hmac` are the only operations, not `ICryptoAlgorithm`.\n */\nexport class Hash extends BaseHelper {\n algorithm: THashAlgorithm;\n\n constructor(opts: { algorithm: THashAlgorithm }) {\n super({ scope: Hash.name, identifier: opts.algorithm });\n this.validateAlgorithmName({ algorithm: opts.algorithm });\n\n this.algorithm = opts.algorithm;\n }\n\n /** Memoized - `BaseHelper`'s constructor resolves a logger on every allocation (~50ns), and downstream token code calls `withAlgorithm` per request. */\n private static readonly instances = new Map<THashAlgorithm, Hash>();\n\n static withAlgorithm(algorithm: THashAlgorithm) {\n const cached = Hash.instances.get(algorithm);\n\n if (cached) {\n return cached;\n }\n\n const created = new Hash({ algorithm });\n Hash.instances.set(algorithm, created);\n\n return created;\n }\n\n validateAlgorithmName(opts: { algorithm: THashAlgorithm }) {\n const { algorithm } = opts;\n\n if (!algorithm || !HashAlgorithms.isValid(algorithm)) {\n throw getError({\n message: `[Hash][validateAlgorithmName] Invalid algorithm name | algorithm: ${algorithm}`,\n });\n }\n }\n\n /**\n * Plain digest, no secret. `message` is text (UTF-8), bytes, or several parts hashed in order as ONE message: a git\n * blob is the header text \"blob <size>\" and a NUL byte, then the bytes, so its parts are the header and the bytes. MD5/SHA1\n * are broken/weak - see {@link HashAlgorithms} - never use for security decisions.\n */\n digest(opts: {\n message: THashInput | ReadonlyArray<THashInput>;\n opts?: IHashExtraOptions;\n }): string {\n const { message } = opts;\n const { outputEncoding = DEFAULT_HASH_OUTPUT_ENCODING } = opts.opts ?? {};\n const hash = new Bun.CryptoHasher(this.algorithm);\n\n for (const part of Array.isArray(message) ? message : [message]) {\n hash.update(part);\n }\n\n return hash.digest(outputEncoding);\n }\n\n /**\n * Keyed HMAC. `message` and `secret` are text (UTF-8) or bytes: a `Buffer` or `Uint8Array` key gives the same output\n * as the text of the same bytes, so a token printed with one keeps verifying with the other. `secret` is mandatory and\n * validated non-empty so a request for an HMAC never silently degrades into an unkeyed digest.\n */\n hmac(opts: { message: THashInput; secret: THashInput; opts?: IHashExtraOptions }): string {\n const { message, secret } = opts;\n const { outputEncoding = DEFAULT_HASH_OUTPUT_ENCODING } = opts.opts ?? {};\n\n if (secret.length === 0) {\n throw getError({\n message: `[Hash][hmac] Missing secret for HMAC-${this.algorithm.toUpperCase()}`,\n });\n }\n\n return new Bun.CryptoHasher(this.algorithm, secret).update(message).digest(outputEncoding);\n }\n\n /**\n * Checks a received digest against the one `value` produces, in constant time. Use it for a webhook signature or a\n * payment callback instead of `===`, which stops at the first differing character and so tells an attacker how many\n * leading characters of a forged value were right.\n *\n * `value` is hashed the way {@link Hash.digest} does, or keyed with `secret` the way {@link Hash.hmac} does, then\n * written in `outputEncoding` (hex by default) and compared with `expected` as text. A different length answers\n * `false` without comparing, and the answer is `false`, never a throw, for any mismatch. The text must match exactly:\n * hex in upper case does not equal hex in lower case.\n */\n verify(opts: {\n value: THashInput;\n expected: string;\n secret?: THashInput;\n opts?: IHashExtraOptions;\n }): boolean {\n const { value, expected, secret } = opts;\n const computed = Buffer.from(\n secret === undefined\n ? this.digest({ message: value, opts: opts.opts })\n : this.hmac({ message: value, secret, opts: opts.opts }),\n );\n const given = Buffer.from(expected);\n\n // Length-checked first: `timingSafeEqual` throws on a length mismatch instead of answering false.\n return computed.length === given.length && crypto.timingSafeEqual(computed, given);\n }\n}\n"]}
@@ -6,5 +6,6 @@ export * from './module.utility.js';
6
6
  export * from './parse.utility.js';
7
7
  export * from './performance.utility.js';
8
8
  export * from './promise.utility.js';
9
+ export * from './record.utility.js';
9
10
  export * from './request.utility.js';
10
11
  //# sourceMappingURL=index.d.ts.map
@@ -7,5 +7,6 @@ export * from './module.utility.js';
7
7
  export * from './parse.utility.js';
8
8
  export * from './performance.utility.js';
9
9
  export * from './promise.utility.js';
10
+ export * from './record.utility.js';
10
11
  export * from './request.utility.js';
11
12
  //# sourceMappingURL=index.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utilities/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,gGAAgG;AAChG,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC","sourcesContent":["export * from './build-info.utility';\n// `RequestBodyErrors` stays on `/core`: consumers name it through the kernel's `RequestErrors`.\nexport { FormBodyUtility } from './form-body.utility';\nexport * from './error.utility';\nexport * from './hr-time.utility';\nexport * from './module.utility';\nexport * from './parse.utility';\nexport * from './performance.utility';\nexport * from './promise.utility';\nexport * from './request.utility';\n"]}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utilities/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,gGAAgG;AAChG,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC","sourcesContent":["export * from './build-info.utility';\n// `RequestBodyErrors` stays on `/core`: consumers name it through the kernel's `RequestErrors`.\nexport { FormBodyUtility } from './form-body.utility';\nexport * from './error.utility';\nexport * from './hr-time.utility';\nexport * from './module.utility';\nexport * from './parse.utility';\nexport * from './performance.utility';\nexport * from './promise.utility';\nexport * from './record.utility';\nexport * from './request.utility';\n"]}
@@ -0,0 +1,8 @@
1
+ /** Narrowing of an `unknown` value, such as a wire payload, to an object whose string keys can be read; no node import, so it ships on `/core`. */
2
+ export declare class RecordUtility {
3
+ /** A non-null object, arrays included: the narrowest check before reading string keys off an `unknown`. A type guard, so it keeps its positional `value`. */
4
+ static isRecord(value: unknown): value is Record<string, unknown>;
5
+ /** A non-null object that is not an array: `isRecord` without the arrays. A class instance (an `Error`, a `Date`) passes; there is no prototype check, so this is not lodash's `isPlainObject`. */
6
+ static isPlainRecord(value: unknown): value is Record<string, unknown>;
7
+ }
8
+ //# sourceMappingURL=record.utility.d.ts.map
@@ -0,0 +1,12 @@
1
+ /** Narrowing of an `unknown` value, such as a wire payload, to an object whose string keys can be read; no node import, so it ships on `/core`. */
2
+ export class RecordUtility {
3
+ /** A non-null object, arrays included: the narrowest check before reading string keys off an `unknown`. A type guard, so it keeps its positional `value`. */
4
+ static isRecord(value) {
5
+ return typeof value === 'object' && value !== null;
6
+ }
7
+ /** A non-null object that is not an array: `isRecord` without the arrays. A class instance (an `Error`, a `Date`) passes; there is no prototype check, so this is not lodash's `isPlainObject`. */
8
+ static isPlainRecord(value) {
9
+ return RecordUtility.isRecord(value) && !Array.isArray(value);
10
+ }
11
+ }
12
+ //# sourceMappingURL=record.utility.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"record.utility.js","sourceRoot":"","sources":["../../../src/utilities/record.utility.ts"],"names":[],"mappings":"AAAA,mJAAmJ;AACnJ,MAAM,OAAO,aAAa;IACxB,6JAA6J;IAC7J,MAAM,CAAC,QAAQ,CAAC,KAAc;QAC5B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;IACrD,CAAC;IAED,mMAAmM;IACnM,MAAM,CAAC,aAAa,CAAC,KAAc;QACjC,OAAO,aAAa,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAChE,CAAC;CACF","sourcesContent":["/** Narrowing of an `unknown` value, such as a wire payload, to an object whose string keys can be read; no node import, so it ships on `/core`. */\nexport class RecordUtility {\n /** A non-null object, arrays included: the narrowest check before reading string keys off an `unknown`. A type guard, so it keeps its positional `value`. */\n static isRecord(value: unknown): value is Record<string, unknown> {\n return typeof value === 'object' && value !== null;\n }\n\n /** A non-null object that is not an array: `isRecord` without the arrays. A class instance (an `Error`, a `Date`) passes; there is no prototype check, so this is not lodash's `isPlainObject`. */\n static isPlainRecord(value: unknown): value is Record<string, unknown> {\n return RecordUtility.isRecord(value) && !Array.isArray(value);\n }\n}\n"]}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/ignis-helpers",
3
- "version": "0.4.8-1",
3
+ "version": "0.4.8-3",
4
4
  "description": "Production-ready TypeScript utility library: pluggable logging (winston or pino behind one ILogger contract), Redis single/cluster/sentinel with pub/sub, BullMQ/MQTT/Kafka message queues, MinIO/Disk/Bun-S3 object storage, AES-256/RSA/ECDH cryptography, Snowflake UID generation, cron scheduling, Socket.IO/WebSocket, TCP/TLS/UDP networking, HTTP clients, secrets/Vault, worker thread pools, and environment management. Sub-path imports isolate optional peer dependencies so the root barrel never forces a peer into your bundle.",
5
5
  "keywords": [
6
6
  "aes",
@@ -176,7 +176,7 @@
176
176
  "force-update": "sh ../../scripts/build/force-update.sh"
177
177
  },
178
178
  "dependencies": {
179
- "@venizia/ignis-inversion": "0.4.7-1",
179
+ "@venizia/ignis-inversion": "0.4.7-2",
180
180
  "reflect-metadata": "^0.2.2",
181
181
  "zod": "^4.6.7"
182
182
  },
@@ -188,7 +188,7 @@
188
188
  "@socket.io/redis-emitter": "^5.1.0",
189
189
  "@types/bun": "^1.4.3",
190
190
  "@types/luxon": "^3.7.6",
191
- "@venizia/dev-configs": "0.4.8-1",
191
+ "@venizia/dev-configs": "0.4.8-2",
192
192
  "axios": "^1.20.0",
193
193
  "bullmq": "^6.4.0",
194
194
  "cron": "^4.4.0",