functionalscript 0.43.1 → 0.44.0

package/fjs/common/monoid/types.js

@@ -0,0 +1,6 @@
+/**
+ * The `Monoid<T>` algebraic structure.
+ *
+ * @module
+ */
+export {};

package/fjs/crypto/hmac/module.f.d.mts

@@ -0,0 +1,32 @@
+/**
+ * Provides an implementation of HMAC (Hash-based Message Authentication Code).
+ *
+ * https://en.wikipedia.org/wiki/HMAC
+ * https://www.rfc-editor.org/rfc/rfc2104
+ *
+ * @module
+ *
+ * @example
+ *
+ * ```ts
+ * import { vec } from '../../types/bit_vec/module.f.mjs'
+ * import { msbUtf8 } from '../../text/module.f.mjs'
+ * import { sha256 } from '../sha2/module.f.mjs'
+ *
+ * const r = hmac(sha256)(msbUtf8('key'))(msbUtf8('The quick brown fox jumps over the lazy dog'))
+ * if (r !== vec(256n)(0xf7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8n)) { throw r }
+ * ```
+ *
+ * @import { Vec, Reduce } from '../../types/bit_vec/types.ts'
+ * @import { Sha2 } from '../sha2/types.ts'
+ */
+import type { Reduce } from '../../types/bit_vec/types.ts';
+import type { Sha2 } from '../sha2/types.ts';
+/**
+ * Generates an HMAC (Hash-based Message Authentication Code) using the specified hash function.
+ *
+ * @param {Sha2} hashFunc - The hash function implementation to use.
+ * @returns {Reduce} A function that takes a key and returns another function
+ * that takes a message and computes the HMAC.
+ */
+export declare const hmac: (hashFunc: Sha2) => Reduce;

package/fjs/crypto/hmac/module.f.mjs

@@ -0,0 +1,65 @@
+/**
+ * Provides an implementation of HMAC (Hash-based Message Authentication Code).
+ *
+ * https://en.wikipedia.org/wiki/HMAC
+ * https://www.rfc-editor.org/rfc/rfc2104
+ *
+ * @module
+ *
+ * @example
+ *
+ * ```ts
+ * import { vec } from '../../types/bit_vec/module.f.mjs'
+ * import { msbUtf8 } from '../../text/module.f.mjs'
+ * import { sha256 } from '../sha2/module.f.mjs'
+ *
+ * const r = hmac(sha256)(msbUtf8('key'))(msbUtf8('The quick brown fox jumps over the lazy dog'))
+ * if (r !== vec(256n)(0xf7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8n)) { throw r }
+ * ```
+ *
+ * @import { Vec, Reduce } from '../../types/bit_vec/types.ts'
+ * @import { Sha2 } from '../sha2/types.ts'
+ */
+
+import { length, msb, vec, vec8, repeat } from '../../types/bit_vec/module.f.mjs'
+import { computeSync } from '../sha2/module.f.mjs'
+
+const { concat, xor } = msb
+
+/**
+ * Outer padding.
+ */
+const oPad = vec8(0x5cn)
+
+/**
+ * Inner padding.
+ */
+const iPad = vec8(0x36n)
+
+/**
+ * Generates an HMAC (Hash-based Message Authentication Code) using the specified hash function.
+ *
+ * @param {Sha2} hashFunc - The hash function implementation to use.
+ * @returns {Reduce} A function that takes a key and returns another function
+ * that takes a message and computes the HMAC.
+ */
+export const hmac = hashFunc => {
+    const { blockLength } = hashFunc
+    const p = repeat(blockLength >> 3n)
+    const ip = p(iPad)
+    const op = p(oPad)
+    const c = computeSync(hashFunc)
+    return k => {
+        const k1 = length(k) > blockLength ? c([k]) : k
+        const k2 = concat(k1)(vec(blockLength - length(k1))(0n))
+        const xk2 = xor(k2)
+        /** @type {(p: Vec) => (msg: Vec) => Vec} */
+        const f = p => {
+            const x = xk2(p)
+            return msg => c([x, msg])
+        }
+        const fip = f(ip)
+        const fop = f(op)
+        return m => fop(fip(m))
+    }
+}

package/fjs/crypto/hmac/proof.f.mjs

@@ -0,0 +1,34 @@
+import { assertEq } from '../../asserts/module.f.mjs'
+import { utf8 } from '../../text/module.f.mjs'
+import { uint, vec } from '../../types/bit_vec/module.f.mjs'
+import { sha256, sha384, sha512 } from '../sha2/module.f.mjs'
+import { hmac } from './module.f.mjs'
+
+export const proof = {
+    example: () => {
+        const r = hmac(sha256)(utf8('key'))(utf8('The quick brown fox jumps over the lazy dog'))
+        assertEq(r, vec(256n)(0xf7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8n))
+    },
+    sha256: () => {
+        const r = hmac(sha256)(utf8('key'))(utf8('The quick brown fox jumps over the lazy dog'))
+        assertEq(uint(r), 0xf7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8n, r)
+    },
+    sha384: () => {
+        const k = vec(384n)(0n)
+        const m = vec(904n)(
+             0x0101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010069c7548c21d0dfea6b9a51c9ead4e27c33d3b3f180316e5bcab92c933f0e4dbc9a9083505bc92276aec4be312696ef7bf3bf603f4bbd381196a029f340585312n)
+        const r = hmac(sha384)(k)(m)
+        assertEq(r, vec(384n)(0x8F858157CE005CD52FD8E8F1A46B55E6CFAE21C8C183D9C2F7504BEDF450609EDD7D3C6171DC0BDD2D2444FAA28F18BAn), uint(r).toString(16))
+    },
+    sha512: () => {
+        const r = hmac(sha512)(utf8('key'))(utf8('The quick brown fox jumps over the lazy dog'))
+        assertEq(r, vec(512n)(0xb42af09057bac1e2d41708e48a902e09b5ff7f12ab428a4fe86653c73dd248fb82f948a549f7b791a5b41915ee4d1ec3935357e4e2317250d0372afa2ebeeb3an))
+    },
+    // RFC 4231 Test Case 6: key (131 bytes of 0xaa = 1048 bits) exceeds SHA-256 block size (512 bits),
+    // so the key is first compressed via the hash function before use.
+    longKey: () => {
+        const key = vec(1048n)(BigInt('0x' + 'aa'.repeat(131)))
+        const r = hmac(sha256)(key)(utf8('Test Using Larger Than Block-Size Key - Hash Key First'))
+        assertEq(uint(r), 0x60e431591ee0b67f0d8a26aacbf5b77f8e0bc6213728c5140546040f0ee37f54n)
+    }
+}

package/fjs/crypto/pow/module.f.d.mts

@@ -0,0 +1,43 @@
+/**
+ * Bitcoin-style proof-of-work: compact **nBits** target decoding and
+ * hash-vs-target verification using an injected SHA-2 hash.
+ *
+ * @module
+ *
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ * @import { Nullable } from '../../types/nullable/types.ts'
+ * @import { Sha2 } from '../sha2/types.ts'
+ * @import { Pow } from './types.ts'
+ */
+import type { Nullable } from '../../types/nullable/types.ts';
+import type { Sha2 } from '../sha2/types.ts';
+import type { Pow } from './types.ts';
+/** Genesis-block compact target (`0x1d00ffff`). */
+export declare const genesisNBits = 486604799n;
+/** Genesis-block uint256 target decoded from {@link genesisNBits}. */
+export declare const genesisTarget = 26959535291011309493156476344723991336010898738574164086137773096960n;
+/**
+ * Decodes compact **nBits** (32-bit block-header "bits") to a uint256 target:
+ *
+ * - `exponent = nBits >> 24`
+ * - `mantissa = nBits & 0xffffff`
+ * - `target = mantissa × 2^(8 × (exponent − 3))`
+ *
+ * Returns `null` for malformed encodings per Bitcoin `SetCompact` rules (negative
+ * sign bit, overflow, target wider than 256 bits).
+ *
+ * @param {bigint} nBits Compact target encoding.
+ * @returns {Nullable<bigint>} Decoded target, or `null` when **nBits** is invalid.
+ */
+export declare const targetFromNBits: (nBits: bigint) => Nullable<bigint>;
+/**
+ * Builds PoW helpers for a hash function (typical consumer: {@link sha256}).
+ *
+ * @param {Sha2} hash SHA-2 configuration whose digest is compared as uint256.
+ * @returns {Pow}
+ */
+export declare const pow: (hash: Sha2) => Pow;
+/** SHA-256 proof-of-work (`pow(sha256)`). */
+export declare const sha256Pow: Pow;
+/** Bitcoin block-header PoW; same as {@link sha256Pow}. */
+export declare const bitcoinPow: Pow;

package/fjs/crypto/pow/module.f.mjs

@@ -0,0 +1,93 @@
+/**
+ * Bitcoin-style proof-of-work: compact **nBits** target decoding and
+ * hash-vs-target verification using an injected SHA-2 hash.
+ *
+ * @module
+ *
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ * @import { Nullable } from '../../types/nullable/types.ts'
+ * @import { Sha2 } from '../sha2/types.ts'
+ * @import { Pow } from './types.ts'
+ */
+
+import { mask } from '../../types/bigint/module.f.mjs'
+import { uint } from '../../types/bit_vec/module.f.mjs'
+import { computeSync, sha256 } from '../sha2/module.f.mjs'
+
+const nBitsMantissa = mask(24n)
+const mantissaSign = 0x00800000n
+const mantissaBody = 0x007fffffn
+const exponentShift = 24n
+const uint256Mask = mask(256n)
+
+/** Genesis-block compact target (`0x1d00ffff`). */
+export const genesisNBits = 0x1d00ffffn
+
+/** Genesis-block uint256 target decoded from {@link genesisNBits}. */
+export const genesisTarget =
+    0x00000000ffff0000000000000000000000000000000000000000000000000000n
+
+/** @type {(exponent: bigint) => bigint} */
+const decodeShift = exponent => 8n * (exponent - 3n)
+
+/** @type {(exponent: bigint) => (mantissa: bigint) => bigint} */
+const compactTarget = exponent => mantissa => {
+    const shift = decodeShift(exponent)
+    return shift >= 0n ? mantissa << shift : mantissa >> -shift
+}
+
+/** @type {(mantissa: bigint) => boolean} */
+const negativeNBits = mantissa =>
+    mantissa !== 0n && (mantissa & mantissaSign) !== 0n
+
+/** @type {(exponent: bigint) => (mantissa: bigint) => (target: bigint) => boolean} */
+const overflowNBits = exponent => mantissa => target =>
+    target !== 0n &&
+    (exponent > 34n || (mantissa !== 0n && (mantissa & mantissaBody) === 0n))
+
+/**
+ * Decodes compact **nBits** (32-bit block-header "bits") to a uint256 target:
+ *
+ * - `exponent = nBits >> 24`
+ * - `mantissa = nBits & 0xffffff`
+ * - `target = mantissa × 2^(8 × (exponent − 3))`
+ *
+ * Returns `null` for malformed encodings per Bitcoin `SetCompact` rules (negative
+ * sign bit, overflow, target wider than 256 bits).
+ *
+ * @param {bigint} nBits Compact target encoding.
+ * @returns {Nullable<bigint>} Decoded target, or `null` when **nBits** is invalid.
+ */
+export const targetFromNBits = nBits => {
+    const exponent = nBits >> exponentShift
+    const mantissa = nBits & nBitsMantissa
+    if (negativeNBits(mantissa)) { return null }
+    const target = compactTarget(exponent)(mantissa)
+    if (overflowNBits(exponent)(mantissa)(target)) { return null }
+    if (target > uint256Mask) { return null }
+    return target
+}
+
+/**
+ * Builds PoW helpers for a hash function (typical consumer: {@link sha256}).
+ *
+ * @param {Sha2} hash SHA-2 configuration whose digest is compared as uint256.
+ * @returns {Pow}
+ */
+export const pow = hash => {
+    const c = computeSync(hash)
+    /** @type {(data: Vec) => bigint} */
+    const hashInt = data => uint(c([data]))
+    /** @type {(nBits: bigint) => (data: Vec) => boolean} */
+    const meets = nBits => data => {
+        const target = targetFromNBits(nBits)
+        return target !== null && hashInt(data) <= target
+    }
+    return { hashInt, meets }
+}
+
+/** SHA-256 proof-of-work (`pow(sha256)`). */
+export const sha256Pow = pow(sha256)
+
+/** Bitcoin block-header PoW; same as {@link sha256Pow}. */
+export const bitcoinPow = sha256Pow

package/fjs/crypto/pow/proof.f.mjs

@@ -0,0 +1,121 @@
+import { utf8 } from '../../text/module.f.mjs'
+import { empty, uint } from '../../types/bit_vec/module.f.mjs'
+import { computeSync, sha224, sha256 } from '../sha2/module.f.mjs'
+import { bitcoinPow, genesisNBits, genesisTarget, pow, sha256Pow, targetFromNBits } from './module.f.mjs'
+import { assert, assertEq, assertNotNullish } from '../../asserts/module.f.mjs'
+
+const p256 = sha256Pow
+const p224 = pow(sha224)
+const sample = utf8('functionalscript pow proof')
+const emptyData = empty
+
+/** Target large enough for {@link sample} under SHA-256 (`0x207fffff`). */
+const easyNBits = 0x207fffffn
+
+/** Compact encoding for target `1` (`0x03000001`). */
+const hardNBits = 0x03000001n
+
+/** SHA-256 of the empty message (NIST / Bitcoin block merkle uses this primitive). */
+const sha256EmptyHash =
+    0xe3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855n
+
+/** Bitcoin block #0 header hash as big-endian uint256. */
+const block0Hash =
+    0x000000000019d6689c085ae165831e934ff763ae46a2a6cffb388491c27dc990n
+
+/** @type {(nBits: bigint) => void} */
+const expectNull = nBits => {
+    assertEq(targetFromNBits(nBits), null, nBits)
+}
+
+export const proof = {
+    targetFromNBits: {
+        genesis: () => {
+            assertEq(targetFromNBits(genesisNBits), genesisTarget, 'genesis target')
+        },
+        block0HashWithinGenesisTarget: () => {
+            assert(!(block0Hash > genesisTarget), 'block0 hash exceeds genesis target')
+        },
+        exponent3: () => {
+            assertEq(targetFromNBits(0x030000ffn), 0xffn, 'exponent 3')
+        },
+        exponent2: () => {
+            assertEq(targetFromNBits(0x02008000n), 0x80n, 'exponent 2')
+        },
+        hardTargetOne: () => {
+            assertEq(targetFromNBits(hardNBits), 1n, 'hard target')
+        },
+        zero: () => {
+            assertEq(targetFromNBits(0n), 0n, 'zero nBits')
+        },
+        negative: () => {
+            expectNull(0x01800001n)
+        },
+        negativeHighMantissa: () => {
+            expectNull(0x22ffffffn)
+        },
+        overflowExponent: () => {
+            expectNull(0x23000001n)
+        },
+        exceeds256: () => {
+            expectNull(0x227fffffn)
+        },
+    },
+    meets: {
+        easy: () => {
+            assert(p256.meets(easyNBits)(sample), 'easy nBits should pass')
+        },
+        hard: () => {
+            assert(!(p256.meets(hardNBits)(sample)), 'target 1 should fail')
+        },
+        genesisFailsSample: () => {
+            assert(!(p256.meets(genesisNBits)(sample)), 'genesis target too hard for sample')
+        },
+        zeroTargetRejectsSample: () => {
+            assert(!(p256.meets(0n)(sample)), 'non-zero hash vs zero target')
+        },
+        invalidNBits: () => {
+            assert(!(p256.meets(0x01800001n)(sample)), 'invalid nBits should not pass')
+        },
+        hashLeqTarget: () => {
+            const h = p256.hashInt(sample)
+            const target = assertNotNullish(targetFromNBits(easyNBits), 'easy nBits decode')
+            assert(!(h > target), 'hash above easy target')
+            assert(h <= target, 'hash <= target')
+        },
+    },
+    hashInt: {
+        sha256Sample: () => {
+            const digest = computeSync(sha256)([sample])
+            assertEq(p256.hashInt(sample), uint(digest), 'sha256 sample')
+        },
+        sha256Empty: () => {
+            assertEq(p256.hashInt(emptyData), sha256EmptyHash, 'sha256 empty constant')
+            const digest = computeSync(sha256)([emptyData])
+            assertEq(p256.hashInt(emptyData), uint(digest), 'sha256 empty')
+        },
+        sha224: () => {
+            const digest = computeSync(sha224)([sample])
+            assertEq(p224.hashInt(sample), uint(digest), 'sha224')
+        },
+        stable: () => {
+            assertEq(p256.hashInt(sample), p256.hashInt(sample), 'stable')
+        },
+    },
+    pow: {
+        sha256Pow: () => {
+            const built = pow(sha256)
+            assertEq(sha256Pow.hashInt(sample), built.hashInt(sample), 'hashInt')
+            assertEq(sha256Pow.meets(easyNBits)(sample), built.meets(easyNBits)(sample), 'meets')
+        },
+        bitcoinPow: () => {
+            assertEq(bitcoinPow.hashInt(sample), sha256Pow.hashInt(sample), 'bitcoinPow')
+        },
+        independentInstances: () => {
+            const a = pow(sha256)
+            const b = pow(sha256)
+            assertEq(a.hashInt(sample), b.hashInt(sample), 'hashInt')
+            assertEq(a.meets(easyNBits)(sample), b.meets(easyNBits)(sample), 'meets')
+        },
+    },
+}

package/fjs/crypto/pow/types.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Types for Bitcoin-style proof-of-work verification.
+ *
+ * @module
+ */
+import type { Vec } from '../../types/bit_vec/types.ts';
+/**
+ * @property hashInt
+ *
+ * Hash `data` with the configured `Sha2`; digest as big-endian uint256.
+ *
+ * @property meets
+ *
+ * Whether `hashInt(data) <= targetFromNBits(nBits)`; `false` when **nBits** is invalid.
+ */
+export type Pow = {
+    readonly hashInt: (data: Vec) => bigint;
+    readonly meets: (nBits: bigint) => (data: Vec) => boolean;
+};

package/fjs/crypto/pow/types.js

@@ -0,0 +1,6 @@
+/**
+ * Types for Bitcoin-style proof-of-work verification.
+ *
+ * @module
+ */
+export {};

package/fjs/crypto/secp/module.f.d.mts

@@ -0,0 +1,61 @@
+/**
+ * Short Weierstrass elliptic-curve arithmetic over a prime field: `curve`
+ * builds point negation, addition, and scalar multiplication for any
+ * `secp`-family curve from its `(p, a, g, n)` parameters.
+ *
+ * @module
+ *
+ * @import { Equal, Reduce } from '../../types/function/operator/types.ts'
+ * @import { Curve, Init, Point } from './types.ts'
+ */
+import type { Equal } from '../../types/function/operator/types.ts';
+import type { Curve, Init, Point } from './types.ts';
+/**
+ * Constructs an elliptic curve with the given initialization parameters.
+ *
+ * @param {Init} _
+ * @returns {Curve}
+ *
+ * @example
+ *
+ * ```js
+ * const curveParams = {
+ *     p: 23n,
+ *     a: [0n, 1n],
+ *     g: [1n, 1n],
+ *     n: 19n
+ * };
+ * const curveInstance = curve(curveParams);
+ *
+ * // Access curve operations
+ * const point = curveInstance.add([1n, 1n])([2n, 5n]); // Add two points
+ * const negPoint = curveInstance.neg([1n, 1n]); // Negate a point
+ * const mulPoint = curveInstance.mul([1n, 1n])(3n); // Multiply a point by 3
+ * ```
+ */
+export declare const curve: ({ p, a: [a0, a1], n, g }: Init) => Curve;
+/** @type {Equal<Point>} */
+export declare const eq: Equal<Point>;
+/**
+ * https://neuromancer.sk/std/secg/secp192r1
+ * NIST P-192
+ */
+export declare const secp192r1: Curve;
+/**
+ * https://en.bitcoin.it/wiki/Secp256k1
+ * https://neuromancer.sk/std/secg/secp256k1
+ */
+export declare const secp256k1: Curve;
+/**
+ * https://neuromancer.sk/std/secg/secp256r1
+ * NIST P-256
+ */
+export declare const secp256r1: Curve;
+/**
+ * https://neuromancer.sk/std/secg/secp384r1
+ */
+export declare const secp384r1: Curve;
+/**
+ * https://neuromancer.sk/std/secg/secp521r1
+ */
+export declare const secp521r1: Curve;