@forthtilliath/ts-kit 0.14.0 → 0.16.0

package/README.md

@@ -68,6 +68,8 @@ Importing them is harmless anywhere: the DOM is only touched when called.
 - `rankByNameMatch(items, query, getName)` — ranks `items` by relevance to
   `query`: earlier match position first, then shorter name — for a
   search-as-you-type list.
+- `pickRandom(array, random?)` — one element picked at random, or
+  `undefined` for an empty array; same `random` as `shuffle`.
 - `shuffle(array, random?)` — shuffled copy (Fisher–Yates); `random`
   (default `Math.random`) can be swapped for a seeded generator in tests.
 - `sortUpcomingFirst(items, getDates, { now? })` — upcoming items first
@@ -252,6 +254,22 @@ Building blocks for writing an iCalendar (`.ics`, RFC 5545) file.
 - `formatDuration(ms)` — human-readable duration ("1d 1h 1m 1s").
 - `padNumber(n, total, minWidth?)` — zero-pads `n` to the width of `total`
   (at least `minWidth`, default 2) so numbered file names sort correctly.
+- `sanitizeIntegerInput(raw, { allowNegative? })` — cleans a whole-number
+  field keystroke by keystroke: digits only, plus a minus sign in first
+  position (`allowNegative`, default `true`). A lone `"-"` survives, so a
+  negative number types normally (Android's `number-pad` has no minus key:
+  use `keyboardType="numeric"`).
+- `parseIntegerInput(raw)` — the integer a field's text stands for, or `null`
+  while it isn't one yet (`""`, `"-"`, `"1-2"`, `"1.5"`, beyond
+  `Number.MAX_SAFE_INTEGER`): keep the last valid value instead of writing
+  `0` over the text.
+
+```ts
+const cleaned = sanitizeIntegerInput(text);
+const value = parseIntegerInput(cleaned);
+setDraft(cleaned);
+if (value !== null) onChange(value);
+```
 
 `sum` and `avg` used to live in `maths/`; those deep imports still work
 (deprecated).
@@ -266,6 +284,56 @@ Building blocks for writing an iCalendar (`.ics`, RFC 5545) file.
 - `deepEqual(a, b)` — recursive structural equality check.
 - `mapValues(obj, fn)` — maps every value of an object through `fn`.
 
+### `security`
+
+- `createAttemptLimiter({ storage, key, freeAttempts?, delaysMs?, now? })` —
+  growing delays between attempts at a secret (a PIN…): 4 free failures,
+  then 30 s, 1 min, 5 min, 15 min for each one after. `attempt(verify)`
+  returns `{ ok: true }` or `{ ok: false, lockedUntil }` (0 when no delay
+  is running) and doesn't call `verify` while locked; `getLockedUntil()`,
+  `reset()`. The counter lives in the injected `storage` (e.g.
+  expo-secure-store's `getItemAsync`/`setItemAsync`/`deleteItemAsync`); an
+  unreadable or tampered value counts as used up, not as zero, a clock set
+  back restarts the delay from now, and parallel attempts are serialized.
+  Limit: the delay is measured with the device clock, so setting it forward
+  ends the wait early — the failure count still grows, and each new failure
+  imposes the longest delay again. Keep the secret itself out of reach
+  (stored hashed, in the Android Keystore through expo-secure-store).
+- `parseUntrustedJson(text, schema, { maxLength?, locale?, messages?, describePath? })`
+  — reads JSON that comes from outside the app (imported file, pasted text,
+  QR code…) **all or nothing**: the first problem rejects the whole text.
+  Checks, in order: empty → longer than `maxLength` (1,000,000 characters by
+  default, checked _before_ `JSON.parse`) → malformed → drops every
+  `__proto__` / `constructor` / `prototype` key → validates with `schema`,
+  any [Standard Schema](https://standardschema.dev) (zod 3.24+/4, Valibot,
+  ArkType — no dependency added). Returns `{ ok: true, data }` or
+  `{ ok: false, reason, error, path?, issues?, raw? }`: `reason` is
+  `"empty" | "too-long" | "malformed" | "invalid"`, `error` a French message
+  ready to show (`locale: "en"` for English, `messages` to override each
+  one), `path` the first issue's path (`["players", 2, "name"]`, shown as
+  « players › n° 3 › name »; `describePath` to name fields), `raw` the
+  parsed but unvalidated value (to read a `version` and say "update the
+  app" — never use it as data). Synchronous schemas only.
+
+```ts
+import { parseUntrustedJson } from "@forthtilliath/ts-kit/security/parseUntrustedJson";
+import { z } from "zod";
+
+// Bound everything: lengths, ranges, enums, array sizes.
+const gameSchema = z.object({
+  name: z.string().trim().min(1).max(60),
+  players: z.array(z.string().max(30)).min(1).max(12),
+  rounds: z.number().int().min(1).max(50),
+});
+
+const result = parseUntrustedJson(text, gameSchema, {
+  maxLength: 50_000, // a real game weighs a few KB
+  describePath: (path) => FIELD_NAMES[String(path.at(-1))] ?? path.join(" › "),
+});
+if (!result.ok) return Alert.alert("Import impossible", result.error);
+addGame(result.data); // typed as z.infer<typeof gameSchema>
+```
+
 ### `string`
 
 - `capitalize(str)` — uppercases the first letter, lowercases the rest.

package/dist/array/index.d.ts

@@ -5,6 +5,7 @@ export * from "./getMostRecentIds.js";
 export * from "./indexById.js";
 export * from "./moveItem.js";
 export * from "./nextInCycle.js";
+export * from "./pickRandom.js";
 export * from "./rankByNameMatch.js";
 export * from "./shuffle.js";
 export * from "./sortUpcomingFirst.js";

package/dist/array/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/array/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/array/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,gBAAgB,CAAC"}

package/dist/array/index.js

@@ -5,6 +5,7 @@ export * from "./getMostRecentIds.js";
 export * from "./indexById.js";
 export * from "./moveItem.js";
 export * from "./nextInCycle.js";
+export * from "./pickRandom.js";
 export * from "./rankByNameMatch.js";
 export * from "./shuffle.js";
 export * from "./sortUpcomingFirst.js";

package/dist/array/pickRandom.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Returns one element of an array, picked at random (each equally likely).
+ *
+ * @param array - The array to pick from.
+ * @param random - Returns a number in `[0, 1)`. Defaults to `Math.random`;
+ * pass a seeded generator for deterministic tests.
+ * @returns The picked element, or `undefined` if `array` is empty.
+ * @example
+ * pickRandom(["rock", "paper", "scissors"]); // => e.g. "paper"
+ * pickRandom([1, 2, 3], () => 0.99); // => 3
+ * pickRandom([]); // => undefined
+ */
+export declare function pickRandom<T>(array: readonly T[], random?: () => number): T | undefined;
+//# sourceMappingURL=pickRandom.d.ts.map

package/dist/array/pickRandom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pickRandom.d.ts","sourceRoot":"","sources":["../../src/array/pickRandom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,MAAM,GAAE,MAAM,MAAoB,GACjC,CAAC,GAAG,SAAS,CAEf"}

package/dist/array/pickRandom.js

@@ -0,0 +1,15 @@
+/**
+ * Returns one element of an array, picked at random (each equally likely).
+ *
+ * @param array - The array to pick from.
+ * @param random - Returns a number in `[0, 1)`. Defaults to `Math.random`;
+ * pass a seeded generator for deterministic tests.
+ * @returns The picked element, or `undefined` if `array` is empty.
+ * @example
+ * pickRandom(["rock", "paper", "scissors"]); // => e.g. "paper"
+ * pickRandom([1, 2, 3], () => 0.99); // => 3
+ * pickRandom([]); // => undefined
+ */
+export function pickRandom(array, random = Math.random) {
+    return array[Math.floor(random() * array.length)];
+}

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export * from "./image/index.js";
 export * from "./markdown/index.js";
 export * from "./number/index.js";
 export * from "./object/index.js";
+export * from "./security/index.js";
 export * from "./string/index.js";
 export * from "./version/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -17,5 +17,6 @@ export * from "./image/index.js";
 export * from "./markdown/index.js";
 export * from "./number/index.js";
 export * from "./object/index.js";
+export * from "./security/index.js";
 export * from "./string/index.js";
 export * from "./version/index.js";

package/dist/number/index.d.ts

@@ -4,6 +4,8 @@ export * from "./formatBytes.js";
 export * from "./formatCsvNumber.js";
 export * from "./formatDuration.js";
 export * from "./padNumber.js";
+export * from "./parseIntegerInput.js";
 export * from "./round.js";
+export * from "./sanitizeIntegerInput.js";
 export * from "./sum.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/number/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/number/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/number/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,YAAY,CAAC;AAC3B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,UAAU,CAAC"}

package/dist/number/index.js

@@ -4,5 +4,7 @@ export * from "./formatBytes.js";
 export * from "./formatCsvNumber.js";
 export * from "./formatDuration.js";
 export * from "./padNumber.js";
+export * from "./parseIntegerInput.js";
 export * from "./round.js";
+export * from "./sanitizeIntegerInput.js";
 export * from "./sum.js";

package/dist/number/parseIntegerInput.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The whole number a field's text stands for, or `null` while it isn't one
+ * yet: empty field, a lone `"-"` before the digits of a negative number,
+ * `"1-2"`, a decimal, or a number too large to be represented exactly (beyond
+ * `Number.MAX_SAFE_INTEGER`). The caller then keeps its last valid value
+ * instead of replacing the text with `0`.
+ *
+ * @param raw - The field's text, ideally cleaned by `sanitizeIntegerInput`.
+ * @returns The integer, or `null`.
+ * @example
+ * parseIntegerInput("-12"); // => -12
+ * parseIntegerInput("-"); // => null
+ * parseIntegerInput(""); // => null
+ * parseIntegerInput("99999999999999999999"); // => null
+ */
+export declare function parseIntegerInput(raw: string): number | null;
+//# sourceMappingURL=parseIntegerInput.d.ts.map

package/dist/number/parseIntegerInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseIntegerInput.d.ts","sourceRoot":"","sources":["../../src/number/parseIntegerInput.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO5D"}

package/dist/number/parseIntegerInput.js

@@ -0,0 +1,25 @@
+/**
+ * The whole number a field's text stands for, or `null` while it isn't one
+ * yet: empty field, a lone `"-"` before the digits of a negative number,
+ * `"1-2"`, a decimal, or a number too large to be represented exactly (beyond
+ * `Number.MAX_SAFE_INTEGER`). The caller then keeps its last valid value
+ * instead of replacing the text with `0`.
+ *
+ * @param raw - The field's text, ideally cleaned by `sanitizeIntegerInput`.
+ * @returns The integer, or `null`.
+ * @example
+ * parseIntegerInput("-12"); // => -12
+ * parseIntegerInput("-"); // => null
+ * parseIntegerInput(""); // => null
+ * parseIntegerInput("99999999999999999999"); // => null
+ */
+export function parseIntegerInput(raw) {
+    if (!/^-?\d+$/.test(raw))
+        return null;
+    const value = Number.parseInt(raw, 10);
+    if (!Number.isSafeInteger(value))
+        return null;
+    // "-0" would otherwise give a negative zero, shown back as "0" but unequal
+    // to 0 under Object.is (React's state comparison).
+    return Object.is(value, -0) ? 0 : value;
+}

package/dist/number/sanitizeIntegerInput.d.ts

@@ -0,0 +1,26 @@
+export interface SanitizeIntegerInputOptions {
+    /**
+     * Keep a leading minus sign.
+     *
+     * @defaultValue true
+     */
+    allowNegative?: boolean;
+}
+/**
+ * Cleans what the user is typing in a whole-number field: drops every
+ * character that is neither a digit nor a leading minus sign (spaces, commas,
+ * dots, pasted text…), keystroke by keystroke. A lone `"-"` survives, so a
+ * negative number can be typed normally — {@link parseIntegerInput} then tells
+ * whether the text is a number yet.
+ *
+ * @param raw - The field's text, as `onChangeText` gives it.
+ * @param options - See {@link SanitizeIntegerInputOptions}.
+ * @returns The text with only digits, and a minus sign in first position if allowed.
+ * @example
+ * sanitizeIntegerInput("1 250"); // => "1250"
+ * sanitizeIntegerInput("-"); // => "-"
+ * sanitizeIntegerInput("12-3"); // => "123"
+ * sanitizeIntegerInput("-4", { allowNegative: false }); // => "4"
+ */
+export declare function sanitizeIntegerInput(raw: string, { allowNegative }?: SanitizeIntegerInputOptions): string;
+//# sourceMappingURL=sanitizeIntegerInput.d.ts.map

package/dist/number/sanitizeIntegerInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitizeIntegerInput.d.ts","sourceRoot":"","sources":["../../src/number/sanitizeIntegerInput.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,EACX,EAAE,aAAoB,EAAE,GAAE,2BAAgC,GACzD,MAAM,CAKR"}

package/dist/number/sanitizeIntegerInput.js

@@ -0,0 +1,22 @@
+/**
+ * Cleans what the user is typing in a whole-number field: drops every
+ * character that is neither a digit nor a leading minus sign (spaces, commas,
+ * dots, pasted text…), keystroke by keystroke. A lone `"-"` survives, so a
+ * negative number can be typed normally — {@link parseIntegerInput} then tells
+ * whether the text is a number yet.
+ *
+ * @param raw - The field's text, as `onChangeText` gives it.
+ * @param options - See {@link SanitizeIntegerInputOptions}.
+ * @returns The text with only digits, and a minus sign in first position if allowed.
+ * @example
+ * sanitizeIntegerInput("1 250"); // => "1250"
+ * sanitizeIntegerInput("-"); // => "-"
+ * sanitizeIntegerInput("12-3"); // => "123"
+ * sanitizeIntegerInput("-4", { allowNegative: false }); // => "4"
+ */
+export function sanitizeIntegerInput(raw, { allowNegative = true } = {}) {
+    const digits = raw.replace(/\D/g, "");
+    return allowNegative && raw.trimStart().startsWith("-")
+        ? `-${digits}`
+        : digits;
+}

package/dist/security/createAttemptLimiter.d.ts

@@ -0,0 +1,65 @@
+/** Where the failure counter is kept — e.g. expo-secure-store on Android. */
+export interface AttemptLimiterStorage {
+    getItem: (key: string) => Promise<string | null>;
+    setItem: (key: string, value: string) => Promise<void>;
+    deleteItem: (key: string) => Promise<void>;
+}
+export interface AttemptLimiterOptions {
+    storage: AttemptLimiterStorage;
+    /** Storage key of the failure counter. */
+    key: string;
+    /** Failures allowed before any delay. @defaultValue 4 */
+    freeAttempts?: number;
+    /**
+     * Delay imposed after the first failure past `freeAttempts`, the second…
+     * the last one repeating for every failure after.
+     * @defaultValue 30 s, 1 min, 5 min, 15 min
+     */
+    delaysMs?: readonly number[];
+    /** @defaultValue `Date.now` */
+    now?: () => number;
+}
+export type AttemptResult = {
+    ok: true;
+} | {
+    ok: false;
+    lockedUntil: number;
+};
+export interface AttemptLimiter {
+    /**
+     * Runs `verify` (e.g. compares a PIN) unless a delay is running, and
+     * updates the counter: reset on success, one more failure otherwise.
+     * `lockedUntil` is the end of the delay now imposed (0 for none). Attempts
+     * run one at a time, so parallel ones can't lose a failure.
+     */
+    attempt: (verify: () => boolean | Promise<boolean>) => Promise<AttemptResult>;
+    /** End of the running delay (a timestamp), or 0 if an attempt is allowed. */
+    getLockedUntil: () => Promise<number>;
+    /** Forgets every failure (e.g. once the PIN is reset another way). */
+    reset: () => Promise<void>;
+    /** The delay imposed after `count` consecutive failures (0 for none). */
+    delayAfter: (count: number) => number;
+}
+/**
+ * Limits attempts at a secret (a PIN, a passphrase) with growing delays:
+ * after `freeAttempts` failures, each new one imposes a wait. The counter is
+ * persisted through `storage`, so closing the app doesn't reset it, and an
+ * unreadable value is never taken as "no failure" (tampering with it would
+ * otherwise lift the limit): the next failure is then delayed at once. A
+ * last failure dated in the future (the clock was set back) restarts the
+ * delay from now instead of locking until that date.
+ *
+ * @example
+ * const pinLock = createAttemptLimiter({
+ *   storage: {
+ *     getItem: SecureStore.getItemAsync,
+ *     setItem: SecureStore.setItemAsync,
+ *     deleteItem: SecureStore.deleteItemAsync,
+ *   },
+ *   key: "pin-failures",
+ * });
+ * const result = await pinLock.attempt(() => isPinCorrect(typedPin));
+ * if (!result.ok && result.lockedUntil) showWaitUntil(result.lockedUntil);
+ */
+export declare function createAttemptLimiter({ storage, key, freeAttempts, delaysMs, now, }: AttemptLimiterOptions): AttemptLimiter;
+//# sourceMappingURL=createAttemptLimiter.d.ts.map

package/dist/security/createAttemptLimiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createAttemptLimiter.d.ts","sourceRoot":"","sources":["../../src/security/createAttemptLimiter.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACjD,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,qBAAqB,CAAC;IAC/B,0CAA0C;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,yDAAyD;IACzD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,+BAA+B;IAC/B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,aAAa,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9E,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IAC9E,6EAA6E;IAC7E,cAAc,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACtC,sEAAsE;IACtE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,yEAAyE;IACzE,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;CACvC;AAUD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,OAAO,EACP,GAAG,EACH,YAAgB,EAChB,QAA4B,EAC5B,GAAc,GACf,EAAE,qBAAqB,GAAG,cAAc,CA6ExC"}

package/dist/security/createAttemptLimiter.js

@@ -0,0 +1,96 @@
+const DEFAULT_DELAYS_MS = [30_000, 60_000, 5 * 60_000, 15 * 60_000];
+const MAX_COUNT = 1_000_000;
+/**
+ * Limits attempts at a secret (a PIN, a passphrase) with growing delays:
+ * after `freeAttempts` failures, each new one imposes a wait. The counter is
+ * persisted through `storage`, so closing the app doesn't reset it, and an
+ * unreadable value is never taken as "no failure" (tampering with it would
+ * otherwise lift the limit): the next failure is then delayed at once. A
+ * last failure dated in the future (the clock was set back) restarts the
+ * delay from now instead of locking until that date.
+ *
+ * @example
+ * const pinLock = createAttemptLimiter({
+ *   storage: {
+ *     getItem: SecureStore.getItemAsync,
+ *     setItem: SecureStore.setItemAsync,
+ *     deleteItem: SecureStore.deleteItemAsync,
+ *   },
+ *   key: "pin-failures",
+ * });
+ * const result = await pinLock.attempt(() => isPinCorrect(typedPin));
+ * if (!result.ok && result.lockedUntil) showWaitUntil(result.lockedUntil);
+ */
+export function createAttemptLimiter({ storage, key, freeAttempts = 4, delaysMs = DEFAULT_DELAYS_MS, now = Date.now, }) {
+    let queue = Promise.resolve();
+    function delayAfter(count) {
+        if (count <= freeAttempts || delaysMs.length === 0)
+            return 0;
+        const index = Math.min(count - freeAttempts - 1, delaysMs.length - 1);
+        return delaysMs[index] ?? 0;
+    }
+    async function readFailures() {
+        const raw = await storage.getItem(key);
+        if (raw === null || raw === "")
+            return { count: 0, lastFailureAt: 0 };
+        try {
+            const { count, lastFailureAt } = JSON.parse(raw);
+            if (typeof count === "number" &&
+                Number.isInteger(count) &&
+                count >= 0 &&
+                count <= MAX_COUNT &&
+                typeof lastFailureAt === "number" &&
+                Number.isFinite(lastFailureAt) &&
+                lastFailureAt >= 0) {
+                return { count, lastFailureAt };
+            }
+        }
+        catch {
+            // Unreadable: handled below.
+        }
+        return { count: freeAttempts, lastFailureAt: 0 };
+    }
+    async function writeFailures(failures) {
+        await storage.setItem(key, JSON.stringify(failures));
+    }
+    async function lockedUntil() {
+        const failures = await readFailures();
+        const current = now();
+        if (failures.lastFailureAt > current) {
+            failures.lastFailureAt = current;
+            await writeFailures(failures);
+        }
+        const until = failures.lastFailureAt + delayAfter(failures.count);
+        return until > current ? until : 0;
+    }
+    function serialized(task) {
+        const run = queue.then(task, task);
+        queue = run.catch(() => undefined);
+        return run;
+    }
+    return {
+        delayAfter,
+        getLockedUntil: () => serialized(lockedUntil),
+        reset: () => serialized(() => storage.deleteItem(key)),
+        attempt: (verify) => serialized(async () => {
+            const locked = await lockedUntil();
+            if (locked)
+                return { ok: false, lockedUntil: locked };
+            if (await verify()) {
+                await storage.deleteItem(key);
+                return { ok: true };
+            }
+            const { count } = await readFailures();
+            const failures = {
+                count: Math.min(count + 1, MAX_COUNT),
+                lastFailureAt: now(),
+            };
+            await writeFailures(failures);
+            const delay = delayAfter(failures.count);
+            return {
+                ok: false,
+                lockedUntil: delay ? failures.lastFailureAt + delay : 0,
+            };
+        }),
+    };
+}

package/dist/security/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./createAttemptLimiter.js";
+export * from "./parseUntrustedJson.js";
+export type * from "./standardSchema.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/security/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/security/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,mBAAmB,qBAAqB,CAAC"}

package/dist/security/index.js

@@ -0,0 +1,2 @@
+export * from "./createAttemptLimiter.js";
+export * from "./parseUntrustedJson.js";

package/dist/security/parseUntrustedJson.d.ts

@@ -0,0 +1,70 @@
+import type { StandardSchemaIssue, StandardSchemaV1 } from "./standardSchema.js";
+/** Why {@link parseUntrustedJson} refused a text. */
+export type UntrustedJsonFailure = "empty" | "too-long" | "malformed" | "invalid";
+export type UntrustedJsonResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    reason: UntrustedJsonFailure;
+    /** A message ready to show the user (French by default). */
+    error: string;
+    /** First schema issue's path, keys as given (`["players", 2, "name"]`). */
+    path?: PropertyKey[];
+    /** Every issue the schema reported (`reason: "invalid"` only). */
+    issues?: readonly StandardSchemaIssue[];
+    /**
+     * The parsed but **unvalidated** value (`reason: "invalid"` only) — e.g.
+     * to read a `version` field and say "update the app". Never use it as data.
+     */
+    raw?: unknown;
+};
+export interface UntrustedJsonMessages {
+    empty: string;
+    tooLong: string;
+    malformed: string;
+    /** `where` is the described path, `""` for the root value. */
+    invalid: (where: string) => string;
+}
+export interface ParseUntrustedJsonOptions {
+    /**
+     * Longest text accepted, in characters, checked **before** `JSON.parse`: a
+     * huge file is refused without being parsed. Set it a little above the
+     * largest legitimate content.
+     *
+     * @defaultValue 1_000_000
+     */
+    maxLength?: number;
+    /** Language of the default messages. @defaultValue "fr" */
+    locale?: "fr" | "en";
+    /** Overrides some or all of the messages. */
+    messages?: Partial<UntrustedJsonMessages>;
+    /**
+     * Turns an issue path into words for `messages.invalid`, e.g. with a map of
+     * field names. Default: keys joined with " › ", indexes counted from 1.
+     */
+    describePath?: (path: PropertyKey[]) => string;
+}
+/**
+ * Reads JSON that came from outside the app (an imported file, pasted text, a
+ * QR code…) and validates it with a schema, all or nothing: the first problem
+ * rejects the whole text, so nothing is ever half-imported.
+ *
+ * In order: empty text → too long (before parsing, so a huge file costs
+ * nothing) → malformed JSON → `__proto__` / `constructor` / `prototype` keys
+ * dropped → schema. With zod, unknown keys are also stripped by `z.object`
+ * (use bounded types: `.max()` on strings and arrays, `.int().min().max()` on
+ * numbers, enums). Synchronous schemas only.
+ *
+ * @param text - The untrusted text.
+ * @param schema - Any Standard Schema (zod, Valibot, ArkType…).
+ * @param options - See {@link ParseUntrustedJsonOptions}.
+ * @returns `{ ok: true, data }`, or `{ ok: false, reason, error, … }` with a
+ * message ready to show.
+ * @example
+ * const result = parseUntrustedJson(text, backupSchema, { maxLength: 200_000 });
+ * if (!result.ok) return Alert.alert("Import impossible", result.error);
+ * restore(result.data);
+ */
+export declare function parseUntrustedJson<T>(text: string, schema: StandardSchemaV1<T>, options?: ParseUntrustedJsonOptions): UntrustedJsonResult<T>;
+//# sourceMappingURL=parseUntrustedJson.d.ts.map

package/dist/security/parseUntrustedJson.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseUntrustedJson.d.ts","sourceRoot":"","sources":["../../src/security/parseUntrustedJson.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EAEnB,gBAAgB,EACjB,MAAM,qBAAqB,CAAC;AAE7B,qDAAqD;AACrD,MAAM,MAAM,oBAAoB,GAC9B,OAAO,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,CAAC;AAEjD,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GACrB;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,oBAAoB,CAAC;IAC7B,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,IAAI,CAAC,EAAE,WAAW,EAAE,CAAC;IACrB,kEAAkE;IAClE,MAAM,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACxC;;;OAGG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;CACf,CAAC;AAEN,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,yBAAyB;IACxC;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACrB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC1C;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,MAAM,CAAC;CAChD;AAqDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC3B,OAAO,GAAE,yBAA8B,GACtC,mBAAmB,CAAC,CAAC,CAAC,CAyCxB"}

package/dist/security/parseUntrustedJson.js

@@ -0,0 +1,93 @@
+const DEFAULT_MAX_LENGTH = 1_000_000;
+const MESSAGES = {
+    fr: {
+        empty: "Le contenu est vide.",
+        tooLong: "Le contenu est trop volumineux. Rien n'a été importé.",
+        malformed: "Le contenu est illisible (JSON invalide). Rien n'a été importé.",
+        invalid: (where) => where
+            ? `Contenu invalide : « ${where} » incorrect. Rien n'a été importé.`
+            : "Contenu invalide. Rien n'a été importé.",
+    },
+    en: {
+        empty: "The content is empty.",
+        tooLong: "The content is too large. Nothing was imported.",
+        malformed: "The content can't be read (invalid JSON). Nothing was imported.",
+        invalid: (where) => where
+            ? `Invalid content: "${where}" is incorrect. Nothing was imported.`
+            : "Invalid content. Nothing was imported.",
+    },
+};
+// Own properties with these names are harmless after JSON.parse, but turn
+// into prototype changes once merged with `Object.assign` or a deep-merge
+// helper: dropped while parsing, whatever the schema does next.
+const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+function stripForbiddenKeys(key, value) {
+    return FORBIDDEN_KEYS.has(key) ? undefined : value;
+}
+function toKey(segment) {
+    return typeof segment === "object" ? segment.key : segment;
+}
+function defaultDescribePath(locale) {
+    return (path) => path
+        .map((key) => typeof key === "number"
+        ? locale === "fr"
+            ? `n° ${key + 1}`
+            : `#${key + 1}`
+        : String(key))
+        .join(" › ");
+}
+/**
+ * Reads JSON that came from outside the app (an imported file, pasted text, a
+ * QR code…) and validates it with a schema, all or nothing: the first problem
+ * rejects the whole text, so nothing is ever half-imported.
+ *
+ * In order: empty text → too long (before parsing, so a huge file costs
+ * nothing) → malformed JSON → `__proto__` / `constructor` / `prototype` keys
+ * dropped → schema. With zod, unknown keys are also stripped by `z.object`
+ * (use bounded types: `.max()` on strings and arrays, `.int().min().max()` on
+ * numbers, enums). Synchronous schemas only.
+ *
+ * @param text - The untrusted text.
+ * @param schema - Any Standard Schema (zod, Valibot, ArkType…).
+ * @param options - See {@link ParseUntrustedJsonOptions}.
+ * @returns `{ ok: true, data }`, or `{ ok: false, reason, error, … }` with a
+ * message ready to show.
+ * @example
+ * const result = parseUntrustedJson(text, backupSchema, { maxLength: 200_000 });
+ * if (!result.ok) return Alert.alert("Import impossible", result.error);
+ * restore(result.data);
+ */
+export function parseUntrustedJson(text, schema, options = {}) {
+    const { maxLength = DEFAULT_MAX_LENGTH, locale = "fr", describePath = defaultDescribePath(locale), } = options;
+    const messages = { ...MESSAGES[locale], ...options.messages };
+    if (text.length > maxLength) {
+        return { ok: false, reason: "too-long", error: messages.tooLong };
+    }
+    const trimmed = text.trim();
+    if (trimmed.length === 0) {
+        return { ok: false, reason: "empty", error: messages.empty };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(trimmed, stripForbiddenKeys);
+    }
+    catch {
+        return { ok: false, reason: "malformed", error: messages.malformed };
+    }
+    const result = schema["~standard"].validate(raw);
+    if (result instanceof Promise) {
+        throw new TypeError("parseUntrustedJson only supports synchronous schemas (no async refinements).");
+    }
+    if (result.issues) {
+        const path = (result.issues[0]?.path ?? []).map(toKey);
+        return {
+            ok: false,
+            reason: "invalid",
+            error: messages.invalid(describePath(path)),
+            path,
+            issues: result.issues,
+            raw,
+        };
+    }
+    return { ok: true, data: result.value };
+}

package/dist/security/standardSchema.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The subset of the [Standard Schema](https://standardschema.dev) interface
+ * this package reads: implemented by zod (3.24+ and 4), Valibot, ArkType… so
+ * {@link parseUntrustedJson} takes any of them without depending on one.
+ */
+export interface StandardSchemaV1<Output = unknown> {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+    };
+}
+/** A path segment as schemas report it: a key, or `{ key }`. */
+export type StandardSchemaPathSegment = PropertyKey | {
+    readonly key: PropertyKey;
+};
+export interface StandardSchemaIssue {
+    readonly message: string;
+    readonly path?: readonly StandardSchemaPathSegment[];
+}
+export type StandardSchemaResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: readonly StandardSchemaIssue[];
+};
+/** The output type of a Standard Schema (`z.infer` for a zod schema). */
+export type InferSchemaOutput<S> = S extends StandardSchemaV1<infer O> ? O : never;
+//# sourceMappingURL=standardSchema.d.ts.map

package/dist/security/standardSchema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standardSchema.d.ts","sourceRoot":"","sources":["../../src/security/standardSchema.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,gBAAgB,CAAC,MAAM,GAAG,OAAO;IAChD,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;QACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,QAAQ,EAAE,CACjB,KAAK,EAAE,OAAO,KACX,oBAAoB,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC;KAC3E,CAAC;CACH;AAED,gEAAgE;AAChE,MAAM,MAAM,yBAAyB,GACnC,WAAW,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAA;CAAE,CAAC;AAE9C,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,yBAAyB,EAAE,CAAC;CACtD;AAED,MAAM,MAAM,oBAAoB,CAAC,MAAM,IACnC;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,mBAAmB,EAAE,CAAA;CAAE,CAAC;AAExD,yEAAyE;AACzE,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAC7B,CAAC,SAAS,gBAAgB,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC"}

package/dist/security/standardSchema.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forthtilliath/ts-kit",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -22,13 +22,14 @@
     "./*": "./dist/*.js"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "5.0.2",
-    "eslint": "10.7.0",
-    "jsdom": "^30.1.1",
+    "@vitest/coverage-v8": "5.0.5",
+    "eslint": "10.14.0",
+    "jsdom": "^30.1.3",
     "typescript": "^5.9.3",
-    "vitest": "^5.0.2",
-    "@forthtilliath/typescript-config": "0.1.1",
-    "@forthtilliath/eslint-config": "0.9.0"
+    "vitest": "^5.0.5",
+    "zod": "^4.6.7",
+    "@forthtilliath/eslint-config": "0.10.1",
+    "@forthtilliath/typescript-config": "0.1.1"
   },
   "scripts": {
     "dev": "tsc --watch -p tsconfig.build.json",