@wow-two-beta/ui-vue 0.0.2

package/dist/foundation/config/index.js

@@ -0,0 +1,186 @@
+function createField(typeName, parse, options) {
+  const hasDefault = options !== void 0 && "default" in options;
+  return {
+    typeName,
+    parse,
+    hasDefault,
+    defaultValue: hasDefault ? options.default : void 0,
+    // A field is required unless it carries a default or is explicitly opted out.
+    required: hasDefault ? false : options?.required ?? true,
+    secret: options?.secret ?? false
+  };
+}
+function str(options) {
+  return createField("string", (raw) => raw, options);
+}
+function num(options) {
+  return createField(
+    "number",
+    (raw) => {
+      const value = Number(raw);
+      if (!Number.isFinite(value)) throw `expected a number, got "${raw}"`;
+      return value;
+    },
+    options
+  );
+}
+const TRUE_TOKENS = /* @__PURE__ */ new Set(["true", "1", "yes", "on"]);
+const FALSE_TOKENS = /* @__PURE__ */ new Set(["false", "0", "no", "off"]);
+function bool(options) {
+  return createField(
+    "boolean",
+    (raw) => {
+      const token = raw.trim().toLowerCase();
+      if (TRUE_TOKENS.has(token)) return true;
+      if (FALSE_TOKENS.has(token)) return false;
+      throw `expected a boolean (true/false/1/0/yes/no/on/off), got "${raw}"`;
+    },
+    options
+  );
+}
+function oneOf(values, options) {
+  return createField(
+    `one of [${values.join(", ")}]`,
+    (raw) => {
+      if (values.includes(raw)) return raw;
+      throw `expected one of [${values.join(", ")}], got "${raw}"`;
+    },
+    options
+  );
+}
+function url(options) {
+  return createField(
+    "url",
+    (raw) => {
+      try {
+        void new URL(raw);
+        return raw;
+      } catch {
+        throw `expected a valid URL, got "${raw}"`;
+      }
+    },
+    options
+  );
+}
+function port(options) {
+  return createField(
+    "port",
+    (raw) => {
+      const value = Number(raw);
+      if (!Number.isInteger(value) || value < 1 || value > 65535) throw `expected a port in 1..65535, got "${raw}"`;
+      return value;
+    },
+    options
+  );
+}
+function json(options) {
+  return createField(
+    "json",
+    (raw) => {
+      try {
+        return JSON.parse(raw);
+      } catch {
+        throw `expected valid JSON, got "${raw}"`;
+      }
+    },
+    options
+  );
+}
+function list(options) {
+  const separator = options?.separator ?? ",";
+  return createField(
+    "list",
+    (raw) => raw.split(separator).map((item) => item.trim()).filter((item) => item.length > 0),
+    options
+  );
+}
+const DEFAULT_RUNTIME_CONFIG_KEY = "__APP_CONFIG__";
+function importMetaEnvSource() {
+  try {
+    const meta = import.meta;
+    return meta.env ?? {};
+  } catch {
+    return {};
+  }
+}
+function windowConfigSource(globalKey = DEFAULT_RUNTIME_CONFIG_KEY) {
+  if (typeof window === "undefined") return {};
+  const raw = window[globalKey];
+  return raw !== null && typeof raw === "object" ? raw : {};
+}
+function staticSource(values) {
+  return values;
+}
+function defaultSources() {
+  return [windowConfigSource(), importMetaEnvSource()];
+}
+function resolveRaw(sources, key) {
+  for (const source of sources) {
+    const hit = source[key];
+    if (hit === void 0 || hit === null) continue;
+    const asString = typeof hit === "string" ? hit : String(hit);
+    if (asString.length === 0) continue;
+    return asString;
+  }
+  return void 0;
+}
+class ConfigError extends Error {
+  /** Every resolution failure across the schema. */
+  issues;
+  constructor(issues) {
+    const lines = issues.map((issue) => `  - ${issue.lookupKey}: ${issue.message}`).join("\n");
+    super(`Invalid configuration (${issues.length} ${issues.length === 1 ? "issue" : "issues"}):
+${lines}`);
+    this.name = "ConfigError";
+    this.issues = issues;
+    Object.setPrototypeOf(this, ConfigError.prototype);
+  }
+}
+function defineConfig(schema, options) {
+  const sources = options?.sources ?? defaultSources();
+  const prefix = options?.prefix ?? "";
+  const resolved = {};
+  const issues = [];
+  for (const [key, field] of Object.entries(schema)) {
+    const lookupKey = `${prefix}${key}`;
+    const raw = resolveRaw(sources, lookupKey);
+    if (raw === void 0) {
+      if (field.hasDefault) {
+        resolved[key] = field.defaultValue;
+      } else if (!field.required) {
+        resolved[key] = void 0;
+      } else {
+        issues.push({ key, lookupKey, reason: "missing", message: `missing required ${field.typeName}` });
+      }
+      continue;
+    }
+    try {
+      resolved[key] = field.parse(raw);
+    } catch (error) {
+      const detail = typeof error === "string" ? error : `invalid ${field.typeName}`;
+      const message = field.secret ? `invalid ${field.typeName} (value redacted)` : detail;
+      issues.push({ key, lookupKey, reason: "invalid", message });
+    }
+  }
+  if (issues.length > 0) throw new ConfigError(issues);
+  return Object.freeze(resolved);
+}
+export {
+  ConfigError,
+  DEFAULT_RUNTIME_CONFIG_KEY,
+  bool,
+  defaultSources,
+  defineConfig,
+  importMetaEnvSource,
+  json,
+  list,
+  num,
+  oneOf,
+  port,
+  resolveRaw,
+  staticSource,
+  str,
+  url,
+  windowConfigSource
+};
+//# sourceMappingURL=index.js.map

package/dist/foundation/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/foundation/config/ConfigField.ts","../../../src/foundation/config/ConfigSource.ts","../../../src/foundation/config/DefineConfig.ts"],"sourcesContent":["// Typed-env field specs. A `ConfigField<T>` describes how one configuration key is parsed from its raw\n// string form, whether it is required, and its fallback — the atoms `defineConfig` reads a source through.\n// Each builder (`str`, `num`, `bool`, `oneOf`, `url`, `port`, `json`, `list`) returns a field whose `parse`\n// handles only a *present* raw string and throws a human-readable message on an invalid value; the engine\n// owns the missing / default / required decision centrally, so a field never re-implements that policy.\n\n/** Tunes one field's presence policy and fallback. A `default` (or `required: false`) makes the field optional. */\nexport interface ConfigFieldOptions<T> {\n  /** Marks the field required. Defaults to `true` unless a `default` is supplied. */\n  readonly required?: boolean;\n\n  /** The value used when the key is absent or empty. Supplying it makes the field optional. */\n  readonly default?: T;\n\n  /** Redacts the raw value from `ConfigError` messages — set for tokens, keys, and passwords. */\n  readonly secret?: boolean;\n}\n\n/**\n * Describes a single configuration key: its scalar type, presence policy, and how to parse a present raw\n * string into `T`. `Optional` is a phantom flag the schema inference reads to widen the output to `T | undefined`\n * for a field that is `required: false` with no `default`.\n */\nexport interface ConfigField<T, Optional extends boolean = false> {\n  /** The human-facing type name used in error messages (`string`, `number`, `one of [...]`, …). */\n  readonly typeName: string;\n\n  /** Whether a missing key is an error. `false` when a `default` is present or `required: false`. */\n  readonly required: boolean;\n\n  /** Whether an explicit `default` was supplied. */\n  readonly hasDefault: boolean;\n\n  /** The configured fallback, meaningful only when `hasDefault` is `true`. */\n  readonly defaultValue?: T;\n\n  /** Whether the raw value is redacted from error output. */\n  readonly secret: boolean;\n\n  /** Phantom marker: `true` widens the inferred output type to `T | undefined`. Never read at runtime. */\n  readonly __optional?: Optional;\n\n  /** Parses a present, non-empty raw string into `T`; throws a `string` message describing the failure. */\n  parse(raw: string): T;\n}\n\n/** Computes a field's phantom optionality from its options literal — optional iff no `default` and `required: false`. */\ntype Optionality<O> = O extends { default: unknown } ? false : O extends { required: false } ? true : false;\n\n/** The upper bound for a field of unknown scalar type — every concrete `ConfigField<T, …>` is assignable to it. */\nexport type AnyConfigField = ConfigField<unknown, boolean>;\n\n/** Shared field constructor — folds the options into the runtime presence policy around a scalar `parse`. */\nfunction createField<T>(\n  typeName: string,\n  parse: (raw: string) => T,\n  options: ConfigFieldOptions<T> | undefined,\n): ConfigField<T, boolean> {\n  const hasDefault = options !== undefined && 'default' in options;\n  return {\n    typeName,\n    parse,\n    hasDefault,\n    defaultValue: hasDefault ? options.default : undefined,\n    // A field is required unless it carries a default or is explicitly opted out.\n    required: hasDefault ? false : options?.required ?? true,\n    secret: options?.secret ?? false,\n  };\n}\n\n/** A string field — the raw value is trimmed and rejected when empty (empty already reads as \"missing\"). */\nexport function str<const O extends ConfigFieldOptions<string> = ConfigFieldOptions<string>>(\n  options?: O,\n): ConfigField<string, Optionality<O>> {\n  return createField('string', (raw) => raw, options) as ConfigField<string, Optionality<O>>;\n}\n\n/** A finite-number field — rejects any raw string that does not parse to a finite JS number. */\nexport function num<const O extends ConfigFieldOptions<number> = ConfigFieldOptions<number>>(\n  options?: O,\n): ConfigField<number, Optionality<O>> {\n  return createField(\n    'number',\n    (raw) => {\n      const value = Number(raw);\n      if (!Number.isFinite(value)) throw `expected a number, got \"${raw}\"`;\n      return value;\n    },\n    options,\n  ) as ConfigField<number, Optionality<O>>;\n}\n\n/** The raw spellings each boolean side accepts, case-insensitively. */\nconst TRUE_TOKENS = new Set(['true', '1', 'yes', 'on']);\nconst FALSE_TOKENS = new Set(['false', '0', 'no', 'off']);\n\n/** A boolean field — accepts `true/1/yes/on` and `false/0/no/off` (case-insensitive); rejects anything else. */\nexport function bool<const O extends ConfigFieldOptions<boolean> = ConfigFieldOptions<boolean>>(\n  options?: O,\n): ConfigField<boolean, Optionality<O>> {\n  return createField(\n    'boolean',\n    (raw) => {\n      const token = raw.trim().toLowerCase();\n      if (TRUE_TOKENS.has(token)) return true;\n      if (FALSE_TOKENS.has(token)) return false;\n      throw `expected a boolean (true/false/1/0/yes/no/on/off), got \"${raw}\"`;\n    },\n    options,\n  ) as ConfigField<boolean, Optionality<O>>;\n}\n\n/** An enum field — the value must be one of `values`; the output type narrows to that literal union. */\nexport function oneOf<const V extends readonly string[], const O extends ConfigFieldOptions<V[number]> = ConfigFieldOptions<V[number]>>(\n  values: V,\n  options?: O,\n): ConfigField<V[number], Optionality<O>> {\n  return createField(\n    `one of [${values.join(', ')}]`,\n    (raw) => {\n      if ((values as readonly string[]).includes(raw)) return raw as V[number];\n      throw `expected one of [${values.join(', ')}], got \"${raw}\"`;\n    },\n    options,\n  ) as ConfigField<V[number], Optionality<O>>;\n}\n\n/** A URL field — validated with the `URL` constructor; the parsed string is returned unchanged. */\nexport function url<const O extends ConfigFieldOptions<string> = ConfigFieldOptions<string>>(\n  options?: O,\n): ConfigField<string, Optionality<O>> {\n  return createField(\n    'url',\n    (raw) => {\n      try {\n        // Construct-and-discard: `URL` throws on a malformed value; we keep the caller's original string.\n        void new URL(raw);\n        return raw;\n      } catch {\n        throw `expected a valid URL, got \"${raw}\"`;\n      }\n    },\n    options,\n  ) as ConfigField<string, Optionality<O>>;\n}\n\n/** A TCP-port field — a finite integer in `1..65535`. */\nexport function port<const O extends ConfigFieldOptions<number> = ConfigFieldOptions<number>>(\n  options?: O,\n): ConfigField<number, Optionality<O>> {\n  return createField(\n    'port',\n    (raw) => {\n      const value = Number(raw);\n      if (!Number.isInteger(value) || value < 1 || value > 65535) throw `expected a port in 1..65535, got \"${raw}\"`;\n      return value;\n    },\n    options,\n  ) as ConfigField<number, Optionality<O>>;\n}\n\n/** A JSON field — `JSON.parse`d into `T`; a malformed document is rejected. */\nexport function json<T, const O extends ConfigFieldOptions<T> = ConfigFieldOptions<T>>(\n  options?: O,\n): ConfigField<T, Optionality<O>> {\n  return createField(\n    'json',\n    (raw) => {\n      try {\n        return JSON.parse(raw) as T;\n      } catch {\n        throw `expected valid JSON, got \"${raw}\"`;\n      }\n    },\n    options,\n  ) as ConfigField<T, Optionality<O>>;\n}\n\n/** Tunes how a `list` field splits its raw value. */\nexport interface ListFieldOptions extends ConfigFieldOptions<readonly string[]> {\n  /** The item separator. Defaults to a comma. */\n  readonly separator?: string;\n}\n\n/** A string-list field — splits on `separator` (default `,`), trims each item, and drops empty items. */\nexport function list<const O extends ListFieldOptions = ListFieldOptions>(\n  options?: O,\n): ConfigField<readonly string[], Optionality<O>> {\n  const separator = options?.separator ?? ',';\n  return createField<readonly string[]>(\n    'list',\n    (raw) =>\n      raw\n        .split(separator)\n        .map((item) => item.trim())\n        .filter((item) => item.length > 0),\n    options,\n  ) as ConfigField<readonly string[], Optionality<O>>;\n}\n","// Configuration sources — the raw key/value stores `defineConfig` reads through. Two ship by default: the\n// build-time `import.meta.env` (Vite inlines it at build) and the runtime `window.__APP_CONFIG__` global an ops\n// team can inject per-environment without a rebuild (12-factor runtime config). A source is a flat record of\n// string values; `defineConfig` merges an ordered list where the *earlier* source wins, so runtime config is\n// layered ahead of build-time env by default. Reading a source never throws — an unavailable one yields `{}`.\n\n/** A flat, read-only key/value store of raw configuration strings. */\nexport type ConfigSource = Readonly<Record<string, string | undefined>>;\n\n/** The default runtime-config global — `window.__APP_CONFIG__`, injected per-environment ahead of build-time env. */\nexport const DEFAULT_RUNTIME_CONFIG_KEY = '__APP_CONFIG__';\n\n/**\n * The build-time source — Vite's `import.meta.env`, inlined at build. Returns `{}` outside a bundler context\n * (e.g. a plain Node test) where `import.meta.env` is absent, so it is always safe to include.\n */\nexport function importMetaEnvSource(): ConfigSource {\n  try {\n    const meta = import.meta as unknown as { env?: Record<string, string | undefined> };\n    return meta.env ?? {};\n  } catch {\n    return {};\n  }\n}\n\n/**\n * The runtime source — a global object (default `window.__APP_CONFIG__`) a deployment injects before the app\n * boots. Returns `{}` when there is no `window` (SSR / Node) or the global is absent or not an object.\n */\nexport function windowConfigSource(globalKey: string = DEFAULT_RUNTIME_CONFIG_KEY): ConfigSource {\n  if (typeof window === 'undefined') return {};\n  const raw = (window as unknown as Record<string, unknown>)[globalKey];\n  return raw !== null && typeof raw === 'object' ? (raw as ConfigSource) : {};\n}\n\n/** An explicit source over a plain record — the injection seam for tests and for values resolved elsewhere. */\nexport function staticSource(values: Record<string, string | undefined>): ConfigSource {\n  return values;\n}\n\n/** The default source order: runtime `window.__APP_CONFIG__` layered ahead of build-time `import.meta.env`. */\nexport function defaultSources(): readonly ConfigSource[] {\n  return [windowConfigSource(), importMetaEnvSource()];\n}\n\n/**\n * Resolves `key` across an ordered source list, first non-empty match wins (earlier source = higher priority).\n * A non-string hit (e.g. `import.meta.env.DEV` is a boolean) is coerced to its string form; an empty string is\n * treated as absent so an unset-but-declared env var falls through to the next source or the field default.\n */\nexport function resolveRaw(sources: readonly ConfigSource[], key: string): string | undefined {\n  for (const source of sources) {\n    const hit = (source as Record<string, unknown>)[key];\n    if (hit === undefined || hit === null) continue;\n    const asString = typeof hit === 'string' ? hit : String(hit);\n    if (asString.length === 0) continue;\n    return asString;\n  }\n  return undefined;\n}\n","// The typed-env engine. `defineConfig(schema, options)` reads each declared key from an ordered source list,\n// parses it through its `ConfigField`, applies defaults, and returns a frozen, fully-typed config object. Unlike\n// storage (which degrades silently), config fails LOUD: every missing-required and invalid-value problem is\n// collected across the whole schema and thrown together as one `ConfigError` at startup — so a misconfigured\n// deploy surfaces all its problems at once, not one boot-crash at a time.\n\nimport type { AnyConfigField, ConfigField } from './ConfigField';\nimport { defaultSources, resolveRaw, type ConfigSource } from './ConfigSource';\n\n/** A schema: a map from output key to its field spec. */\nexport type ConfigSchema = Readonly<Record<string, AnyConfigField>>;\n\n/** Widens an optional field's output to include `undefined`; a required / defaulted field stays `T`. */\ntype InferField<F> = F extends ConfigField<infer T, infer Optional> ? (Optional extends true ? T | undefined : T) : never;\n\n/** The resolved, typed config object inferred from a schema. */\nexport type InferConfig<S extends ConfigSchema> = { readonly [K in keyof S]: InferField<S[K]> };\n\n/** Tunes where `defineConfig` reads from and how keys are namespaced. */\nexport interface DefineConfigOptions {\n  /** The ordered source list; earlier wins. Defaults to `[window.__APP_CONFIG__, import.meta.env]`. */\n  readonly sources?: readonly ConfigSource[];\n\n  /** A prefix prepended to every schema key on lookup (e.g. `'VITE_'` → key `API_URL` reads `VITE_API_URL`). */\n  readonly prefix?: string;\n}\n\n/** One resolution failure — a missing required key or a value that failed its field's `parse`. */\nexport interface ConfigIssue {\n  /** The schema key (output name, without the lookup prefix). */\n  readonly key: string;\n\n  /** The full source key looked up (with prefix). */\n  readonly lookupKey: string;\n\n  /** Why it failed. */\n  readonly reason: 'missing' | 'invalid';\n\n  /** A human-readable description; a `secret` field's raw value is never included. */\n  readonly message: string;\n}\n\n/** Thrown by `defineConfig` when one or more keys are missing or invalid — aggregates every issue found. */\nexport class ConfigError extends Error {\n  /** Every resolution failure across the schema. */\n  readonly issues: readonly ConfigIssue[];\n\n  constructor(issues: readonly ConfigIssue[]) {\n    const lines = issues.map((issue) => `  - ${issue.lookupKey}: ${issue.message}`).join('\\n');\n    super(`Invalid configuration (${issues.length} ${issues.length === 1 ? 'issue' : 'issues'}):\\n${lines}`);\n    this.name = 'ConfigError';\n    this.issues = issues;\n    // Restore the prototype chain across the ES5 `Error` transpilation target so `instanceof` holds.\n    Object.setPrototypeOf(this, ConfigError.prototype);\n  }\n}\n\n/**\n * Resolves a typed configuration object from `schema`. Each key is looked up across the source list (prefix\n * applied), parsed through its field, and defaulted when absent. Empty strings count as absent. All missing /\n * invalid problems are aggregated and thrown together as a single {@link ConfigError}; on success the returned\n * object is frozen. Pass an explicit `sources` (e.g. `[staticSource({...})]`) to make resolution deterministic\n * in tests.\n */\nexport function defineConfig<const S extends ConfigSchema>(schema: S, options?: DefineConfigOptions): InferConfig<S> {\n  const sources = options?.sources ?? defaultSources();\n  const prefix = options?.prefix ?? '';\n\n  const resolved: Record<string, unknown> = {};\n  const issues: ConfigIssue[] = [];\n\n  for (const [key, field] of Object.entries(schema) as [string, AnyConfigField][]) {\n    const lookupKey = `${prefix}${key}`;\n    const raw = resolveRaw(sources, lookupKey);\n\n    if (raw === undefined) {\n      if (field.hasDefault) {\n        resolved[key] = field.defaultValue;\n      } else if (!field.required) {\n        resolved[key] = undefined;\n      } else {\n        issues.push({ key, lookupKey, reason: 'missing', message: `missing required ${field.typeName}` });\n      }\n      continue;\n    }\n\n    try {\n      resolved[key] = field.parse(raw);\n    } catch (error) {\n      // A field's `parse` throws a `string` describing the failure; anything else is coerced defensively.\n      const detail = typeof error === 'string' ? error : `invalid ${field.typeName}`;\n      // Never leak a secret's raw value — the field's own message may quote it, so replace it wholesale.\n      const message = field.secret ? `invalid ${field.typeName} (value redacted)` : detail;\n      issues.push({ key, lookupKey, reason: 'invalid', message });\n    }\n  }\n\n  if (issues.length > 0) throw new ConfigError(issues);\n\n  return Object.freeze(resolved) as InferConfig<S>;\n}\n"],"names":[],"mappings":"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"}

package/dist/foundation/crypto/Digest.d.ts

@@ -0,0 +1,25 @@
+/** Accepted digest input: a UTF-8-encoded string, a raw `ArrayBuffer`, or an existing byte view. */
+export type BinaryInput = string | ArrayBuffer | Uint8Array;
+/** A hash algorithm `crypto.subtle.digest` implements. SHA-256 is the default choice; SHA-1 is checksum/interop only. */
+export type DigestAlgorithm = 'SHA-1' | 'SHA-256' | 'SHA-384' | 'SHA-512';
+/** Normalizes any {@link BinaryInput} to bytes; strings become UTF-8. Internal — not exported from the barrel. */
+export declare function toBytes(data: BinaryInput): Uint8Array;
+/**
+ * Hashes `data` with the named algorithm and resolves to the raw digest bytes — the general form the named
+ * helpers below wrap. **Throws** synchronously when `crypto.subtle` is unavailable (insecure context).
+ */
+export declare function digest(algorithm: DigestAlgorithm, data: BinaryInput): Promise<Uint8Array>;
+/** Computes the SHA-256 digest of `data` (32 bytes) — the default hash for cache keys, ETags, and content addressing. */
+export declare function sha256(data: BinaryInput): Promise<Uint8Array>;
+/**
+ * Computes the SHA-1 digest of `data` (20 bytes). **Not collision-resistant** — use it only for
+ * non-adversarial checksums or to interoperate with a system that already speaks SHA-1 (git, legacy ETags).
+ * Reach for {@link sha256} everywhere else.
+ */
+export declare function sha1(data: BinaryInput): Promise<Uint8Array>;
+/** Computes the SHA-384 digest of `data` (48 bytes) — the truncated SHA-512 variant used by subresource integrity. */
+export declare function sha384(data: BinaryInput): Promise<Uint8Array>;
+/** Computes the SHA-512 digest of `data` (64 bytes) — wider margin than SHA-256, and faster on 64-bit hardware. */
+export declare function sha512(data: BinaryInput): Promise<Uint8Array>;
+/** Computes the SHA-256 digest of `data` as a lowercase 64-char hex string — the ready-to-print form for an ETag or cache key. */
+export declare function sha256Hex(data: BinaryInput): Promise<string>;

package/dist/foundation/crypto/Encoding.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Renders bytes as a lowercase hex string (2 chars per byte, no separator) — the canonical way to show a
+ * digest, an ETag, or a checksum. Inverse of {@link hexToBytes}.
+ */
+export declare function bytesToHex(bytes: Uint8Array): string;
+/**
+ * Parses a hex string into bytes, accepting either case. **Throws a `TypeError`** when the input has an odd
+ * length or contains a non-hex character — a half-parsed digest is never returned. Inverse of
+ * {@link bytesToHex}.
+ */
+export declare function hexToBytes(hex: string): Uint8Array;
+/**
+ * Encodes bytes as standard, padded base64 (`+`, `/`, `=`). Safe for arbitrarily large inputs — the source
+ * is walked in chunks. Inverse of {@link base64ToBytes}; for URL or JWT contexts use
+ * {@link bytesToBase64Url}.
+ */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+/**
+ * Decodes standard base64 into bytes. Padding may be present or omitted, but the string must otherwise be
+ * canonical: **throws a `TypeError`** on any character outside `A-Za-z0-9+/=` (whitespace and the base64url
+ * `-_` included), on over-padding, and on an impossible length. Inverse of {@link bytesToBase64}.
+ */
+export declare function base64ToBytes(base64: string): Uint8Array;
+/**
+ * Encodes bytes as **unpadded** base64url (RFC 4648 §5) — `-_` in place of `+/`, no `=`. This is the form a
+ * JWT segment, a URL query value, and a filename-safe cache key all require. Inverse of
+ * {@link base64UrlToBytes}.
+ */
+export declare function bytesToBase64Url(bytes: Uint8Array): string;
+/**
+ * Decodes base64url into bytes, tolerating the padding that {@link bytesToBase64Url} never emits (some
+ * producers add it). **Throws a `TypeError`** on any character outside `A-Za-z0-9-_=` — notably on the
+ * standard-base64 `+` and `/`, which signal that {@link base64ToBytes} was the intended decoder.
+ */
+export declare function base64UrlToBytes(base64Url: string): Uint8Array;
+/** Encodes a string to its UTF-8 bytes — the normalization every digest of a string goes through. Inverse of {@link bytesToUtf8}. */
+export declare function utf8ToBytes(text: string): Uint8Array;
+/**
+ * Decodes UTF-8 bytes back to a string. **Lenient**: an invalid sequence becomes U+FFFD rather than
+ * throwing, so this is lossy for arbitrary binary — render digest bytes with {@link bytesToHex} or
+ * {@link bytesToBase64} instead. Inverse of {@link utf8ToBytes} for any real text.
+ */
+export declare function bytesToUtf8(bytes: Uint8Array): string;

package/dist/foundation/crypto/HashObject.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Serializes `value` to JSON with object keys sorted at every depth, so two structurally equal values
+ * always produce the same string regardless of property insertion order. Array order is preserved.
+ *
+ * Pure and synchronous — usable under SSR and as an in-memory `Map` key without hashing. Returns the
+ * literal `'undefined'` for an input `JSON.stringify` would drop entirely (`undefined`, a function, a
+ * symbol), so the result is always a string. **Throws a `TypeError`** on a circular reference.
+ */
+export declare function stableStringify(value: unknown): string;
+/**
+ * Hashes any JSON-serializable value to a lowercase 64-char SHA-256 hex string, order-independently:
+ * `{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` produce the same hash at any nesting depth. The canonical cache key
+ * for a params object, a filter set, or a request body.
+ *
+ * Async and requires a secure context — see {@link stableStringify} for the pure, sync alternative, and
+ * `isSubtleAvailable()` to probe before calling.
+ */
+export declare function hashObject(value: unknown): Promise<string>;

package/dist/foundation/crypto/Random.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Default alphabet: URL-safe base62 (`A-Z`, `a-z`, `0-9`). No `+/=~`, so a generated string is safe in a
+ * path segment, a query value, a filename, and an HTML attribute without escaping.
+ */
+export declare const URL_SAFE_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+/**
+ * Returns the exclusive upper bound for an unbiased byte: the largest multiple of `size` that fits in 256.
+ * Bytes at or above it must be discarded — see the file header. Internal — not exported from the barrel.
+ */
+export declare function rejectionLimit(size: number): number;
+/**
+ * Fills `length` cryptographically secure random bytes. Requests above the platform's 65536-byte per-call
+ * ceiling are filled in successive passes. **Throws** a `RangeError` on a negative or non-integer length,
+ * and an `Error` when Web Crypto is unavailable — never falls back to `Math.random`.
+ */
+export declare function randomBytes(length: number): Uint8Array;
+/**
+ * Builds a random string of `length` characters from `chars` using the byte stream `nextBytes`, discarding
+ * biased bytes (see the file header). The injected source is what makes rejection testable. Internal — not
+ * exported from the barrel; call {@link randomString} instead.
+ */
+export declare function randomStringFrom(length: number, chars: readonly string[], nextBytes: (count: number) => Uint8Array): string;
+/**
+ * Generates a random string of `length` characters, drawn uniformly from `alphabet` (default
+ * {@link URL_SAFE_ALPHABET}) with rejection sampling — no modulo bias. Use it for opaque tokens, nonces, and
+ * collision-resistant suffixes; use `Guid` from `foundation/identifiers` for entity identifiers.
+ *
+ * The alphabet is split by code point, so an emoji or astral-plane character counts as one character and is
+ * never torn into surrogate halves. It must hold 1..256 code points; duplicated characters skew the result
+ * proportionally and are the caller's responsibility.
+ */
+export declare function randomString(length: number, alphabet?: string): string;

package/dist/foundation/crypto/TimingSafeEqual.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Compares two byte arrays in (best-effort) constant time — no early exit on the first mismatch, and no
+ * separate fast path for a length mismatch. Returns true only when both length and every byte match.
+ *
+ * Use it whenever one side is secret: a digest, an HMAC, a CSRF or session token, a signed URL parameter.
+ * For plain non-secret data `===` on the hex form is fine and faster.
+ *
+ * To compare strings, encode both with `utf8ToBytes` first — a `string` overload is deliberately absent
+ * because the encoding step's own timing would need the same care and hiding it here would suggest a
+ * guarantee this cannot make. See the file header on what JS can and cannot promise.
+ */
+export declare function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean;

package/dist/foundation/crypto/WebCrypto.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Reports whether `crypto.getRandomValues` can be called — i.e. whether {@link randomBytes} and
+ * {@link randomString} will succeed. True in every browser and in Node 19+, including insecure contexts.
+ */
+export declare function isCryptoAvailable(): boolean;
+/**
+ * Reports whether `crypto.subtle` can be called — i.e. whether the digest helpers will succeed. False
+ * outside a **secure context** (plain `http://` on a non-localhost host) even when {@link isCryptoAvailable}
+ * is true. Probe this before offering a hash-dependent feature rather than catching the throw.
+ */
+export declare function isSubtleAvailable(): boolean;
+/** Returns the ambient `Crypto`, throwing a diagnostic `Error` when unavailable. Internal — not exported from the barrel. */
+export declare function requireCrypto(): Crypto;
+/** Returns the ambient `SubtleCrypto`, throwing a diagnostic `Error` when unavailable. Internal — not exported from the barrel. */
+export declare function requireSubtle(): SubtleCrypto;

package/dist/foundation/crypto/index.d.ts

@@ -0,0 +1,6 @@
+export { isCryptoAvailable, isSubtleAvailable } from './WebCrypto';
+export { bytesToHex, hexToBytes, bytesToBase64, base64ToBytes, bytesToBase64Url, base64UrlToBytes, utf8ToBytes, bytesToUtf8, } from './Encoding';
+export { type BinaryInput, type DigestAlgorithm, digest, sha1, sha256, sha384, sha512, sha256Hex, } from './Digest';
+export { URL_SAFE_ALPHABET, randomBytes, randomString } from './Random';
+export { timingSafeEqual } from './TimingSafeEqual';
+export { stableStringify, hashObject } from './HashObject';

package/dist/foundation/crypto/index.js

@@ -0,0 +1,226 @@
+function resolveCrypto() {
+  return globalThis.crypto;
+}
+function resolveSubtle() {
+  const source = resolveCrypto();
+  if (source === void 0) return void 0;
+  return source.subtle;
+}
+function isCryptoAvailable() {
+  return typeof resolveCrypto()?.getRandomValues === "function";
+}
+function isSubtleAvailable() {
+  return typeof resolveSubtle()?.digest === "function";
+}
+function requireCrypto() {
+  const source = resolveCrypto();
+  if (source === void 0 || typeof source.getRandomValues !== "function") {
+    throw new Error(
+      "Web Crypto is unavailable: `globalThis.crypto.getRandomValues` is not a function. This runtime cannot produce cryptographically secure bytes — guard the call with `isCryptoAvailable()`."
+    );
+  }
+  return source;
+}
+function requireSubtle() {
+  const subtle = resolveSubtle();
+  if (subtle === void 0 || typeof subtle.digest !== "function") {
+    throw new Error(
+      "Web Crypto `subtle` is unavailable: `globalThis.crypto.subtle` is undefined. `crypto.subtle` is exposed only in a secure context (https, localhost, or a file/extension origin) — an `http://` page on a LAN host has `crypto.getRandomValues` but no `subtle`. Guard with `isSubtleAvailable()`."
+    );
+  }
+  return subtle;
+}
+const HEX_BY_BYTE = Array.from({ length: 256 }, (_, i) => i.toString(16).padStart(2, "0"));
+const HEX_STRING = /^(?:[0-9a-fA-F]{2})*$/;
+const BASE64_STRING = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}(?:==)?|[A-Za-z0-9+/]{3}=?)?$/;
+const BASE64URL_STRING = /^(?:[A-Za-z0-9_-]{4})*(?:[A-Za-z0-9_-]{2}(?:==)?|[A-Za-z0-9_-]{3}=?)?$/;
+const FROM_CHAR_CODE_CHUNK = 32768;
+const UTF8_ENCODER = new TextEncoder();
+const UTF8_DECODER = new TextDecoder();
+function bytesToHex(bytes) {
+  let hex = "";
+  for (const byte of bytes) hex += HEX_BY_BYTE[byte];
+  return hex;
+}
+function hexToBytes(hex) {
+  if (!HEX_STRING.test(hex)) {
+    throw new TypeError(
+      `hexToBytes: expected an even-length string of hex digits, got "${hex}" (length ${hex.length}).`
+    );
+  }
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+function bytesToBase64(bytes) {
+  let binary = "";
+  for (let offset = 0; offset < bytes.length; offset += FROM_CHAR_CODE_CHUNK) {
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + FROM_CHAR_CODE_CHUNK));
+  }
+  return btoa(binary);
+}
+function base64ToBytes(base64) {
+  if (!BASE64_STRING.test(base64)) {
+    throw new TypeError(
+      `base64ToBytes: expected a canonical standard-base64 string (alphabet A-Za-z0-9+/ with optional = padding), got "${base64}".`
+    );
+  }
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < bytes.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+function bytesToBase64Url(bytes) {
+  return bytesToBase64(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlToBytes(base64Url) {
+  if (!BASE64URL_STRING.test(base64Url)) {
+    throw new TypeError(
+      `base64UrlToBytes: expected a base64url string (alphabet A-Za-z0-9-_ with optional = padding), got "${base64Url}".`
+    );
+  }
+  const standard = base64Url.replace(/-/g, "+").replace(/_/g, "/");
+  const padding = standard.length % 4 === 0 ? "" : "=".repeat(4 - standard.length % 4);
+  return base64ToBytes(standard + padding);
+}
+function utf8ToBytes(text) {
+  return UTF8_ENCODER.encode(text);
+}
+function bytesToUtf8(bytes) {
+  return UTF8_DECODER.decode(bytes);
+}
+function toBytes(data) {
+  if (typeof data === "string") return utf8ToBytes(data);
+  if (data instanceof Uint8Array) return data;
+  return new Uint8Array(data);
+}
+async function digest(algorithm, data) {
+  const subtle = requireSubtle();
+  const hashed = await subtle.digest(algorithm, toBytes(data));
+  return new Uint8Array(hashed);
+}
+function sha256(data) {
+  return digest("SHA-256", data);
+}
+function sha1(data) {
+  return digest("SHA-1", data);
+}
+function sha384(data) {
+  return digest("SHA-384", data);
+}
+function sha512(data) {
+  return digest("SHA-512", data);
+}
+async function sha256Hex(data) {
+  return bytesToHex(await sha256(data));
+}
+const URL_SAFE_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+const MAX_BYTES_PER_CALL = 65536;
+function rejectionLimit(size) {
+  return 256 - 256 % size;
+}
+function randomBytes(length) {
+  if (!Number.isInteger(length) || length < 0) {
+    throw new RangeError(`randomBytes: length must be a non-negative integer, got ${length}.`);
+  }
+  const source = requireCrypto();
+  const bytes = new Uint8Array(length);
+  for (let offset = 0; offset < length; offset += MAX_BYTES_PER_CALL) {
+    source.getRandomValues(bytes.subarray(offset, Math.min(offset + MAX_BYTES_PER_CALL, length)));
+  }
+  return bytes;
+}
+function randomStringFrom(length, chars, nextBytes) {
+  if (!Number.isInteger(length) || length < 0) {
+    throw new RangeError(`randomStringFrom: length must be a non-negative integer, got ${length}.`);
+  }
+  if (chars.length === 0 || chars.length > 256) {
+    throw new RangeError(
+      `randomStringFrom: alphabet must hold 1..256 characters, got ${chars.length}. A larger alphabet cannot be sampled unbiasedly from a single byte.`
+    );
+  }
+  if (length === 0) return "";
+  const size = chars.length;
+  const limit = rejectionLimit(size);
+  const picked = [];
+  while (picked.length < length) {
+    const needed = length - picked.length;
+    const bytes = nextBytes(needed + Math.ceil(needed / 4) + 8);
+    if (bytes.length === 0) {
+      throw new RangeError("randomStringFrom: the byte source returned no bytes.");
+    }
+    for (const byte of bytes) {
+      if (byte >= limit) continue;
+      picked.push(chars[byte % size]);
+      if (picked.length === length) break;
+    }
+  }
+  return picked.join("");
+}
+function randomString(length, alphabet = URL_SAFE_ALPHABET) {
+  return randomStringFrom(length, [...alphabet], randomBytes);
+}
+function timingSafeEqual(a, b) {
+  let difference = a.length ^ b.length;
+  const span = Math.max(a.length, b.length);
+  for (let i = 0; i < span; i++) {
+    difference |= (a[i] ?? 0) ^ (b[i] ?? 0);
+  }
+  return difference === 0;
+}
+function canonicalize(value, seen) {
+  if (value === null || typeof value !== "object") return value;
+  if (seen.has(value)) {
+    throw new TypeError("stableStringify: circular reference — a value cannot contain itself.");
+  }
+  seen.add(value);
+  const canonical = canonicalizeObject(value, seen);
+  seen.delete(value);
+  return canonical;
+}
+function canonicalizeObject(value, seen) {
+  const serializable = value;
+  if (typeof serializable.toJSON === "function") {
+    return canonicalize(serializable.toJSON(), seen);
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => canonicalize(item, seen));
+  }
+  const record = value;
+  return Object.fromEntries(
+    Object.keys(record).sort().map((key) => [key, canonicalize(record[key], seen)])
+  );
+}
+function stableStringify(value) {
+  return JSON.stringify(canonicalize(value, /* @__PURE__ */ new WeakSet())) ?? "undefined";
+}
+function hashObject(value) {
+  return sha256Hex(stableStringify(value));
+}
+export {
+  URL_SAFE_ALPHABET,
+  base64ToBytes,
+  base64UrlToBytes,
+  bytesToBase64,
+  bytesToBase64Url,
+  bytesToHex,
+  bytesToUtf8,
+  digest,
+  hashObject,
+  hexToBytes,
+  isCryptoAvailable,
+  isSubtleAvailable,
+  randomBytes,
+  randomString,
+  sha1,
+  sha256,
+  sha256Hex,
+  sha384,
+  sha512,
+  stableStringify,
+  timingSafeEqual,
+  utf8ToBytes
+};
+//# sourceMappingURL=index.js.map