@noy-db/hub 0.3.0-pre.9 → 0.4.0-pre.0

package/dist/kernel/util/discriminant.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Type-guard helper for narrowing discriminated-union records.
+ *
+ * `Collection<T>` correctly threads `T` through `get` / `query` / `scan`, but
+ * accessing member-specific fields after reading from a `Collection<Union>`
+ * still requires a narrowing step in application code. In regular `.ts` files
+ * a simple `if (r.kind === 'IV')` block narrows correctly; in vue-tsc /
+ * template contexts the inline comparison is sometimes not enough, and the
+ * helper below makes the guard portable and avoids `as unknown as …` casts.
+ *
+ * **Usage with Collection<T>**
+ *
+ * ```ts
+ * import { isDiscriminant } from '@noy-db/hub'
+ *
+ * type IV = { kind: 'IV'; invoiceNo: string; amount: number }
+ * type RE = { kind: 'RE'; receiptNo: string; paidAt: string }
+ * type Receipt = IV | RE | ...
+ *
+ * const receipts = await vault.collection<Receipt>('receipts').query().toArray()
+ *
+ * // Filter approach — result is IV[], invoiceNo accessible without cast:
+ * const ivs = receipts.filter(r => isDiscriminant(r, 'kind', 'IV'))
+ * console.log(ivs[0].invoiceNo)
+ *
+ * // Branch approach:
+ * for (const r of receipts) {
+ *   if (isDiscriminant(r, 'kind', 'IV')) {
+ *     console.log(r.invoiceNo)  // r: IV here
+ *   }
+ * }
+ * ```
+ *
+ * @module
+ */
+/**
+ * Type-guard for narrowing a discriminated-union record by its discriminant.
+ *
+ * Returns `true` when `record[key] === value`, and narrows `record` to
+ * `Extract<T, Record<K, V>>` — the exact union member(s) that carry that
+ * discriminant value.
+ *
+ * The discriminant key is a parameter (not hardcoded to `'kind'`), so this
+ * works with any field name: `'kind'`, `'type'`, `'tag'`, etc.
+ *
+ * @example
+ *   const ivs = receipts.filter(r => isDiscriminant(r, 'kind', 'IV'))
+ *   // ivs: IV[]  — invoiceNo accessible, no cast needed
+ *
+ * @typeParam T - The union type of the record (e.g. `Receipt`). Both type-alias
+ *   unions and interface-extended unions work; use a `type` alias (`type Receipt = IV | RE`) for best
+ *   results.
+ * @typeParam K - The discriminant key (must be a key of `T`).
+ * @typeParam V - The discriminant value to match. The `const` modifier ensures
+ *   TypeScript infers the string literal (e.g. `'IV'`), not the full union
+ *   `T[K]`, so the predicate resolves to the exact member type.
+ */
+export declare function isDiscriminant<T, K extends keyof T, const V extends T[K]>(record: T, key: K, value: V): record is Extract<T, Record<K, V>>;

package/dist/kernel/util/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@noy-db/hub/util` — pure helpers that don't belong to any single
+ * service and have no dependency on the keyring, ledger, or stores.
+ *
+ * Currently:
+ *   - {@link sanitizeFilename} — target-profile aware filename safety
+ *     for export-blobs sites and any other place where adopters write
+ *     a record-supplied filename to a real storage destination.
+ *
+ * @module
+ */
+export { sanitizeFilename } from './sanitize-filename.js';
+export type { FilenameProfile, SanitizeFilenameOptions, } from './sanitize-filename.js';
+export { isDiscriminant } from './discriminant.js';

package/dist/kernel/util/sanitize-filename.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Target-profile aware filename sanitizer.
+ *
+ * Pure string in / string out. No filesystem access, no I/O. Use this
+ * at the boundary where a user-supplied filename meets a storage
+ * destination — local FS, ZIP archive, S3 key, URL path, SMB share —
+ * to defuse the canonical 14-class footgun before it reaches that
+ * destination.
+ *
+ * ## Threat model
+ *
+ *   1. Path injection — `..`, NUL bytes, `\` on POSIX, absolute paths.
+ *   2. Windows reserved names — `CON`, `PRN`, `AUX`, `NUL`,
+ *      `COM1-9`, `LPT1-9`, with or without an extension.
+ *   3. Windows reserved chars — `< > : " / \ | ? *` plus ASCII 0-31.
+ *   4. Trailing `.` and ` ` on Windows / SMB.
+ *   5. Unicode normalization drift — same display, different bytes →
+ *      "two files with the same name" sync ghosts.
+ *   6. Bidi override spoofing — U+202E reversing `harmless.exe.txt`
+ *      into `harmless.txt.exe`.
+ *   7. URL `+` ambiguity in S3 presigned URLs.
+ *   8. ZIP general-purpose-flag bit 11 (UTF-8 filename) optional in
+ *      pre-2006 readers.
+ *   9-14. Length caps, leading/trailing whitespace + controls,
+ *      `.DS_Store`-style hidden noise, etc.
+ *
+ * ## Always-on transforms (every profile)
+ *
+ *   - NFC normalize (`String.prototype.normalize('NFC')`).
+ *   - Reject NUL — hard fail, not strip. Silent strip enables a
+ *     classic truncation bypass (`safe.txt\0.exe` → `safe.txt`).
+ *   - Strip bidi overrides (`U+202A..U+202E`, `U+2066..U+2069`).
+ *   - Trim leading/trailing whitespace and ASCII control chars.
+ *
+ * ## Non-goals (i18n boundary policy, )
+ *
+ *   - No transliteration.
+ *   - No locale-aware slugging.
+ *   - No script-specific segmentation.
+ *
+ * @module
+ */
+/**
+ * One of seven storage destinations the sanitizer knows how to defang
+ * for. Pick the most restrictive that covers your write site:
+ * `'macos-smb'` is the safe default for "I don't know where these
+ * files end up but they're going to a real filesystem somewhere."
+ */
+export type FilenameProfile = 'posix' | 'windows' | 'macos-smb' | 'zip' | 'url-path' | 's3-key' | 'opaque';
+export interface SanitizeFilenameOptions {
+    /** Target-destination profile. */
+    readonly profile: FilenameProfile;
+    /**
+     * Override the per-profile length cap. Useful when leaving headroom
+     * for a collision suffix — e.g. `maxBytes: 240` on a `posix` write
+     * site that wants 15 bytes of slack for `-1`, `-2`, …
+     */
+    readonly maxBytes?: number;
+    /**
+     * Required when `profile === 'opaque'`. The opaque profile replaces
+     * the entire input with `${opaqueId}.${ext}` (extension preserved
+     * from the input when present).
+     */
+    readonly opaqueId?: string;
+}
+/**
+ * Sanitize a filename for a target-destination profile. Pure: same
+ * input + options always returns the same output, no I/O.
+ *
+ * Returns the sanitized name. Throws {@link FilenameSanitizationError}
+ * when the input cannot be made safe at all (NUL byte, empty after
+ * normalization, missing `opaqueId` for the opaque profile,
+ * `..` segment that would fall out of any reasonable target).
+ */
+export declare function sanitizeFilename(name: string, opts: SanitizeFilenameOptions): string;

package/dist/kernel/validation.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Passphrase validation — phrase format (per the three-tier session-tiers
+ * design, locked 2026-05-04).
+ *
+ * Passphrases are **phrases**: multiple simple words, easy to remember,
+ * structurally constrained so a weak choice cannot silently collapse the
+ * security floor. The format is intentionally narrow: lowercase letters
+ * and single spaces only, no punctuation, no symbols, no digits.
+ *
+ * - Default minimum: 6 words (~77 bits with the 7,776-word EFF list).
+ * - Strict minimum: 8 words (~103 bits).
+ * - Per-word minimum: 3 characters (excludes "a", "is", "of").
+ * - Adjacent repeats rejected ("the the").
+ *
+ * The hub runs validation default-on at every passphrase ingress
+ * (`createOwnerKeyring`, `grant`, `rotatePassphrase`); test fixtures and
+ * CLI scripts override via `{ allowWeakPassphrase: true }`.
+ *
+ * @module
+ */
+import { NoydbError } from './errors.js';
+/** All reasons a phrase can be rejected. */
+export type WeakPassphraseReason = 'empty' | 'invalid-chars' | 'leading-or-trailing-space' | 'double-space' | 'too-few-words' | 'word-too-short' | 'repeated-adjacent';
+/** Per-vault knobs. Aligns with `VaultPolicy.passphrase`. */
+export interface PassphrasePolicy {
+    /** Minimum number of words. Default 6. Strict policy uses 8. */
+    readonly minWords?: number;
+    /** Minimum characters per word. Default 3. */
+    readonly minWordLength?: number;
+    /** Reject adjacent identical words ("the the"). Default true. */
+    readonly rejectRepeatedAdjacent?: boolean;
+    /**
+     * Override the default character-class rule (`/^[a-z]+( [a-z]+)*$/`).
+     *
+     * The hub's strict default is lowercase-letters-and-single-spaces
+     * because that's what the EFF wordlist generator emits and what
+     * most attacker password lists are keyed on. Use this knob to allow
+     * digits, uppercase, hyphens, or non-Latin scripts when the
+     * consumer's audience needs them — e.g.:
+     *
+     * ```ts
+     * // Thai + English mix with digits permitted
+     * pattern: /^[\p{L}0-9 ]+( [\p{L}0-9 ]+)*$/u
+     *
+     * // Allow uppercase + hyphens (passphrase-with-hyphens style)
+     * pattern: /^[A-Za-z]+([- ][A-Za-z]+)*$/
+     * ```
+     *
+     * The OTHER structural rules still apply (min-words split by space,
+     * min-word-length, repeated-adjacent, leading/trailing whitespace,
+     * double-space). For non-space-delimited word semantics, use
+     * {@link customValidator} instead.
+     *
+     */
+    readonly pattern?: RegExp;
+    /**
+     * Replace ALL validation entirely with a custom function. When set,
+     * none of the other PassphrasePolicy fields apply — the consumer
+     * owns every rule (word splitting, character classes, entropy
+     * thresholds, allowlist/denylist). Use sparingly; this is the
+     * escape hatch for domain-specific phrase formats:
+     *
+     *   - Localized wordlists with non-space word boundaries
+     *   - BIP-39 seed phrases (24 words, fixed wordlist, etc.)
+     *   - Organization-specific HR password policies
+     *
+     * The returned `PassphraseValidationResult` is what
+     * {@link assertStrongPassphrase} dispatches on — `ok: true` accepts;
+     * `ok: false` throws `WeakPassphraseError` with the supplied reason.
+     *
+     */
+    readonly customValidator?: (phrase: string) => PassphraseValidationResult;
+}
+/** Result of a check. Discriminated union — compile-time exhaustive. */
+export type PassphraseValidationResult = {
+    readonly ok: true;
+    readonly words: number;
+} | {
+    readonly ok: false;
+    readonly reason: WeakPassphraseReason;
+    readonly minimum?: number;
+    readonly got?: number;
+};
+/**
+ * Thrown by `assertStrongPassphrase()` and by every hub ingress
+ * point (`createOwnerKeyring`, `grant`, `rotatePassphrase`) when a
+ * supplied phrase fails the structural rules above.
+ */
+export declare class WeakPassphraseError extends NoydbError {
+    readonly reason: WeakPassphraseReason;
+    readonly suggestion: string;
+    constructor(reason: WeakPassphraseReason, suggestion: string);
+}
+/**
+ * Inspect a phrase against the format rules and return a structured
+ * verdict. Never throws — callers either branch on `ok` or pass the
+ * result to {@link assertStrongPassphrase} for the throwing flavour.
+ */
+export declare function validatePassphrase(s: string, opts?: PassphrasePolicy): PassphraseValidationResult;
+/**
+ * Throw {@link WeakPassphraseError} when the phrase fails. Used by
+ * `createOwnerKeyring`, `grant`, and `rotatePassphrase` at ingress.
+ *
+ * Pass `{ allowWeakPassphrase: true }` to bypass — intended for test
+ * fixtures, CLI scripts, and dev environments. The override never
+ * loosens the cryptographic key derivation; it only relaxes the
+ * structural-strength gate.
+ */
+export declare function assertStrongPassphrase(s: string, opts?: PassphrasePolicy & {
+    allowWeakPassphrase?: boolean;
+}): void;
+/**
+ * Estimate the entropy of a phrase, given the EFF 7,776-word list as
+ * the assumed wordlist. ~12.9 bits per word.
+ *
+ * Returns 0 for any input that fails the phrase format — character-class
+ * estimates aren't comparable to phrase entropy, and surfacing 0 makes
+ * weak inputs visible in any UI that displays an entropy meter.
+ */
+export declare function estimateEntropy(passphrase: string): number;
+/**
+ * Internal compatibility shim. Older code paths used the throwing
+ * `validatePassphrase(s)` directly; some still do via re-exports. Routes
+ * to the new `assertStrongPassphrase` so the contract holds for both
+ * shapes during the transition. New code should call
+ * {@link assertStrongPassphrase} directly.
+ *
+ * @internal
+ */
+export declare function legacyAssertPassphrase(s: string): void;