@mindpeeker/entropy 0.1.0

package/dist/strategies/race.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"race.js","sourceRoot":"","sources":["../../src/strategies/race.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,EACL,YAAY,EACZ,UAAU,EACV,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,GACf,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAGxD;;;GAGG;AACH,MAAM,UAAU,IAAI,CAAC,SAA4B;IAC/C,gBAAgB,CAAC,SAAS,EAAE,MAAM,CAAC,CAAA;IACnC,MAAM,OAAO,GAAG,CAAC,GAAG,SAAS,CAAC,CAAA;IAC9B,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAE3C,OAAO,cAAc,CAAC;QACpB,IAAI;QACJ,IAAI,EAAE,UAAU,CAAC,OAAO,CAAC;QACzB,OAAO,EAAE,kBAAkB,CAAC,OAAO,CAAC;QAEpC,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO;YAC5B,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAA;YACxC,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM;gBAC5B,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;gBACtD,CAAC,CAAC,UAAU,CAAC,MAAM,CAAA;YAErB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CACnC,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;gBACjF,MAAM,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,CAAA;YAC1C,CAAC,CAAC,CACH,CAAA;YACD,IAAI,CAAC;gBACH,OAAO,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;YACjC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,OAAO,EAAE,MAAM,EAAE,OAAO;oBAAE,MAAM,YAAY,CAAC,IAAI,CAAC,CAAA;gBACtD,MAAM,IAAI,YAAY,CACpB,sBAAsB,EACtB,OAAO,OAAO,CAAC,MAAM,wBAAwB,IAAI,EAAE,EACnD;oBACE,QAAQ,EAAE,IAAI;oBACd,KAAK,EAAE,KAAK;iBACb,CACF,CAAA;YACH,CAAC;oBAAS,CAAC;gBACT,UAAU,CAAC,KAAK,EAAE,CAAA,CAAC,kDAAkD;YACvE,CAAC;QACH,CAAC;KACF,CAAC,CAAA;AACJ,CAAC"}

package/dist/strategies/xor.d.ts

@@ -0,0 +1,9 @@
+import type { EntropyProvider } from '../types.js';
+/**
+ * Fetch from ALL members in parallel and XOR the results — the output is as
+ * strong as the strongest independent input. Fails closed: any member failure
+ * fails the whole call (compose inside `fallback` if you want degradation).
+ * Attribution lists every member's sources.
+ */
+export declare function xorMix(providers: EntropyProvider[]): EntropyProvider;
+//# sourceMappingURL=xor.d.ts.map

package/dist/strategies/xor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xor.d.ts","sourceRoot":"","sources":["../../src/strategies/xor.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,aAAa,CAAA;AAEjE;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,SAAS,EAAE,eAAe,EAAE,GAAG,eAAe,CAqDpE"}

package/dist/strategies/xor.js

@@ -0,0 +1,56 @@
+import { EntropyError } from '../errors.js';
+import { xorBytes } from '../internal/bytes.js';
+import { abortedError, anyPrivatePrivacy, commonKind, compositeName, requireProviders, toEntropyError, } from '../internal/composite.js';
+import { defineProvider } from '../internal/provider.js';
+/**
+ * Fetch from ALL members in parallel and XOR the results — the output is as
+ * strong as the strongest independent input. Fails closed: any member failure
+ * fails the whole call (compose inside `fallback` if you want degradation).
+ * Attribution lists every member's sources.
+ */
+export function xorMix(providers) {
+    requireProviders(providers, 'xor');
+    const members = [...providers];
+    const name = compositeName('xor', members);
+    return defineProvider({
+        name,
+        kind: commonKind(members),
+        privacy: anyPrivatePrivacy(members),
+        async getBytes(length, reqOpts) {
+            const controller = new AbortController();
+            const signal = reqOpts?.signal
+                ? AbortSignal.any([reqOpts.signal, controller.signal])
+                : controller.signal;
+            const tasks = members.map((member) => member.getBytes(length, { signal, timeoutMs: reqOpts?.timeoutMs }).catch((error) => {
+                controller.abort(); // fail fast: stop the remaining in-flight requests
+                throw toEntropyError(error, member.name);
+            }));
+            const settled = await Promise.allSettled(tasks);
+            const failures = settled
+                .filter((s) => s.status === 'rejected')
+                .map((s) => toEntropyError(s.reason, name));
+            if (failures.length > 0) {
+                if (reqOpts?.signal?.aborted)
+                    throw abortedError(name);
+                const primary = failures.filter((f) => f.code !== 'aborted');
+                throw new EntropyError('insufficient_entropy', `${failures.length}/${members.length} providers failed in ${name}`, {
+                    provider: name,
+                    cause: new AggregateError(primary.length > 0 ? primary : failures),
+                });
+            }
+            const results = settled.map((s) => s.value);
+            let bytes;
+            try {
+                bytes = xorBytes(results.map((r) => r.bytes));
+            }
+            catch (error) {
+                throw new EntropyError('bad_response', 'a member returned the wrong byte count', {
+                    provider: name,
+                    cause: error,
+                });
+            }
+            return { bytes, sources: results.flatMap((r) => [...r.sources]) };
+        },
+    });
+}
+//# sourceMappingURL=xor.js.map

package/dist/strategies/xor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xor.js","sourceRoot":"","sources":["../../src/strategies/xor.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,36 @@
+/** What kind of physical (or algorithmic) process the randomness comes from. */
+export type EntropyKind = 'qrng' | 'trng' | 'beacon' | 'csprng' | 'mixed';
+/**
+ * Whether the randomness is served privately to the caller or published for
+ * everyone. `public` sources (beacons) must NEVER seed secrets on their own —
+ * everyone in the world sees the same bytes.
+ */
+export type EntropyPrivacy = 'private' | 'public';
+/** Static identity + classification of an entropy source. */
+export interface EntropySourceInfo {
+    readonly name: string;
+    readonly kind: EntropyKind;
+    readonly privacy: EntropyPrivacy;
+}
+export interface EntropyRequestOptions {
+    signal?: AbortSignal;
+    /** Budget for the whole call including internal chunking/retries. Default 10_000. */
+    timeoutMs?: number;
+}
+export interface EntropyResult {
+    /** Exactly as many bytes as requested. */
+    bytes: Uint8Array;
+    /** Provider(s) that actually contributed bytes to this result. */
+    sources: readonly EntropySourceInfo[];
+}
+export interface EntropyStreamOptions extends EntropyRequestOptions {
+    /** Desired chunk size in bytes. Default: the provider's natural chunk size. */
+    chunkBytes?: number;
+}
+export interface EntropyProvider extends EntropySourceInfo {
+    /** Resolve with exactly `length` bytes or throw `EntropyError`. Never partial. */
+    getBytes(length: number, opts?: EntropyRequestOptions): Promise<EntropyResult>;
+    /** Lazy, pull-based. No I/O before the first `next()`. Ends via `return()`/abort. */
+    stream(opts?: EntropyStreamOptions): AsyncIterable<Uint8Array>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAA;AAEzE;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,QAAQ,CAAA;AAEjD,6DAA6D;AAC7D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;CACjC;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,0CAA0C;IAC1C,KAAK,EAAE,UAAU,CAAA;IACjB,kEAAkE;IAClE,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAA;CACtC;AAED,MAAM,WAAW,oBAAqB,SAAQ,qBAAqB;IACjE,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,eAAgB,SAAQ,iBAAiB;IACxD,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;IAC9E,qFAAqF;IACrF,MAAM,CAAC,IAAI,CAAC,EAAE,oBAAoB,GAAG,aAAa,CAAC,UAAU,CAAC,CAAA;CAC/D"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@mindpeeker/entropy",
+  "version": "0.1.0",
+  "description": "Provider-pluggable quantum (QRNG) and true (TRNG) randomness for web and Node — ANU, RANDOM.ORG, drand, NIST beacon and more, with composable fallback/xor/race strategies and streaming.",
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.3"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./providers": {
+      "types": "./dist/providers/index.d.ts",
+      "default": "./dist/providers/index.js"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "node": "./dist/node/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.build.node.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "bun test",
+    "bench": "bun scripts/bench.ts",
+    "bench:stream": "bun scripts/stream-bench.ts",
+    "quality": "bun scripts/quality.ts",
+    "demo:negentropy": "bun scripts/negentropy-demo.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "qrng",
+    "trng",
+    "entropy",
+    "random",
+    "quantum",
+    "randomness",
+    "drand",
+    "csprng",
+    "anu",
+    "random.org"
+  ]
+}