Skip to content

kollorg/facere-optio

Repository files navigation

@kollorg/facere-optio

A lean, zero dependency library to provide a useful base for your project. Checksums, cryptography, codecs, date-times, error-checking-codes, logging, pseudorandom number generation. The tools you need for any project. Secure build pipeline, provenance signed and typed.

CI NPM ver install size deps LoC

Installation

This module is available through NPM. There are no install scripts, decrease your risk by explicitly preventing (--ignore-scripts)

(pnpm|npm) install @kollorg/facere-optio --ignore-scripts

To verify provenance:

npm audit signatures

Details

Augmented Backus-Naur Form /rfc5234

Algorithms

Checksum/Hash

A checksum; can be used to prevent/identify accidental changes. A hash; maps some data to another, often used for hash tables, or to speed up comparison.

Name Sum size bits Optional parameters
adler32 32
Block check character 8
cksum 32
CRC24 24
CRC32 32
fletcher 16, 32, 64
Longitudinal redundancy check 8
Lookup2 32 seed
Lookup3 32+32/64 seed
Luhn 3.5
MD5Sum 128
Murmur3 32 seed
SHA1Sum 160
Spooky v2 128 seed
xxHash 32, 64 seed

Command Line Interface (cli)

  • Argument and option parsing
  • Foreground, background color (8 color, 213 color, 16M colors)
  • Underline, bold, faint, italic, blink, invert, hide, strike-through, overline text styles
  • Terminal controls & style (cursor move, screen/line clear)

Codec

Crypto

Block

CBC or CTR are recommended by Niels Ferguson and Bruce Schneier. ECB should not be used.

Padding

Symmetric

Name Block size Key size Nonce size Features
Advanced Encryption Standard (AES) 16 16, 24, 32 0
Ascon-128 8 16 16 AEAD
Ascon-128a 16 16 16 AEAD
Ascon-80pq 8 20 16 AEAD, Resistance to quantum adversary
Blowfish 8 4-56 0
ChaCha20 64 16, 32 12
ChaCha20-Poly1305 64 32 12 AEAD
Rabbit 16 16 0, 8
Salsa20 64 16, 32 8
Salsa20-Poly1305 64 32 12 AEAD
Twofish 16 16, 24, 32 0
XChaCha20 64 32 24
XChaCha20-Poly1305 64 32 24 AEAD
XSalsa20 64 16, 32 24
XSalsa20-Poly1305 64 32 24 AEAD

Secure Hash

Cryptography hash functions that have the properties:

  • Finding an input string that matches a hash value (pre-image) is hard
  • Finding a pair of messages that generate the same hash value (collision) is hard
Name Digest sizes Optional parameters
Ascon-Hash, Ascon-HashA 256 -
Blake 256, 512 salt
Blake2b 8-512, 256, 384, 512 key, salt, personalization
Blake2s 8-256, 224, 256 key, salt, personalization
Keccak 8-512, 224, 256, 384, 512 capacity
MD4† 128† -
MD5† 128† -
ParallelHash (128,256) 8-512 block size, customization
RipeMD† 128†, 160†, 256, 320 -
SHA-1† 160† -
SHA-2 224, 256, 384, 512, 512/224, 512/256 -
SHA-3 224, 256, 384, 512 -
TupleHash (128, 256) 8-512 customization
Whirlpool 512 -

† No longer considered cryptographically safe

Key Derivation Function (KDF)

A cryptographic algorithm that derives one or more secret keys from a secret value. Can be used to stretch keys (make them longer), or obtain a key in a particular format (eg making a key a fixed length)

  • HKDF
  • PBKDF2 pbkdf2_hmac_sha1, pbkdf2_hmac_sha256, pbkdf2_hmac_sha512

Message Authentication Code (MAC)

Also known as an authentication tag, a short piece of information to authenticate a message. Protect integrity, and authenticity.

Name Tag Size
CMAC 16 (AES)
HMAC Depends on hash (Blake, Blake2, cShake, Keccak, MD4, MD5, RipeMD, Sha1, Sha2, Sha3, Shake, Whirlpool)
HopMAC 16 (Kangaroo Twelve)
KMAC 16, 32 (Keccak)
Poly1305 16

EXtendable-Output Function (XOF)

A secure hash that can produce output of any desired length.

Name Capacities Optional parameters
Ascon-Xof, Ascon-XofA 256 digest size
cShake 128, 256 digest size, function name, customization
KangarooTwelve 128 digest size, customization
KmacXof 128, 256 digest size, key, customization
ParallelHashXof 128, 256 block size, digest size, customization
Shake 128, 256 digest size
TupleHashXof 128, 256 digest size, customization
TurboSHAKE 128, 256 digest size, customization

DateTime

  • Year, Month, Day
  • Hour, Minute, Second, Millisecond, Microsecond
  • DateTimeLocal, DateTimeUtc, DateOnly, TimeOnly
  • Duration, DurationExact
  • DateTime*.lt|lte|eq|gt|gte|neq - Compare two date-times
  • DateTime*.add|sub - Add or subtract Duration|DurationExact from a date-time
  • DateTime*.diff|diffExact - Get the difference between two dates in y/m/d/h/* or d/h/*

Error Correction Codes

Endian

Net

Primitive

  • Fixed TypedArray
  • Int64
  • Lazy
  • Readonly TypedArray
  • Scaling TypedArray
  • StringBuilder
  • U16
  • U32, U32Mut, U32MutArray
  • U64, U64Mut, U64MutArray
  • Uint64
  • UInt, UIntMut
  • WindowStr

Extensions:

  • Bit
  • Int
  • String
  • Uint8Array

Pseudorandom number generators (PRNG)

  • Marsaglia - possible to calculate in your head
  • Middle-Square - in practice flawed since the period is often short and will converge towards the same number or loop after repeated times
  • MSVC
  • RANDU - a famously bad PRNG

RegExp

  • RegExp escape string

RunTime

  • Configuration (including collecting from environment variables)
  • Structured logging
  • Normalize stack entries, and stack traces across engines, with colors

License

MPL-1.1