utils.d.ts 7.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161
  1. /**
  2. * Utilities for hex, bytes, CSPRNG.
  3. * @module
  4. */
  5. /*! noble-hashes - MIT License (c) 2022 Paul Miller (paulmillr.com) */
  6. /** Checks if something is Uint8Array. Be careful: nodejs Buffer will return true. */
  7. export declare function isBytes(a: unknown): a is Uint8Array;
  8. /** Asserts something is positive integer. */
  9. export declare function anumber(n: number): void;
  10. /** Asserts something is Uint8Array. */
  11. export declare function abytes(b: Uint8Array | undefined, ...lengths: number[]): void;
  12. /** Asserts something is hash */
  13. export declare function ahash(h: IHash): void;
  14. /** Asserts a hash instance has not been destroyed / finished */
  15. export declare function aexists(instance: any, checkFinished?: boolean): void;
  16. /** Asserts output is properly-sized byte array */
  17. export declare function aoutput(out: any, instance: any): void;
  18. /** Generic type encompassing 8/16/32-byte arrays - but not 64-byte. */
  19. export type TypedArray = Int8Array | Uint8ClampedArray | Uint8Array | Uint16Array | Int16Array | Uint32Array | Int32Array;
  20. /** Cast u8 / u16 / u32 to u8. */
  21. export declare function u8(arr: TypedArray): Uint8Array;
  22. /** Cast u8 / u16 / u32 to u32. */
  23. export declare function u32(arr: TypedArray): Uint32Array;
  24. /** Zeroize a byte array. Warning: JS provides no guarantees. */
  25. export declare function clean(...arrays: TypedArray[]): void;
  26. /** Create DataView of an array for easy byte-level manipulation. */
  27. export declare function createView(arr: TypedArray): DataView;
  28. /** The rotate right (circular right shift) operation for uint32 */
  29. export declare function rotr(word: number, shift: number): number;
  30. /** The rotate left (circular left shift) operation for uint32 */
  31. export declare function rotl(word: number, shift: number): number;
  32. /** Is current platform little-endian? Most are. Big-Endian platform: IBM */
  33. export declare const isLE: boolean;
  34. /** The byte swap operation for uint32 */
  35. export declare function byteSwap(word: number): number;
  36. /** Conditionally byte swap if on a big-endian platform */
  37. export declare const swap8IfBE: (n: number) => number;
  38. /** @deprecated */
  39. export declare const byteSwapIfBE: typeof swap8IfBE;
  40. /** In place byte swap for Uint32Array */
  41. export declare function byteSwap32(arr: Uint32Array): Uint32Array;
  42. export declare const swap32IfBE: (u: Uint32Array) => Uint32Array;
  43. /**
  44. * Convert byte array to hex string. Uses built-in function, when available.
  45. * @example bytesToHex(Uint8Array.from([0xca, 0xfe, 0x01, 0x23])) // 'cafe0123'
  46. */
  47. export declare function bytesToHex(bytes: Uint8Array): string;
  48. /**
  49. * Convert hex string to byte array. Uses built-in function, when available.
  50. * @example hexToBytes('cafe0123') // Uint8Array.from([0xca, 0xfe, 0x01, 0x23])
  51. */
  52. export declare function hexToBytes(hex: string): Uint8Array;
  53. /**
  54. * There is no setImmediate in browser and setTimeout is slow.
  55. * Call of async fn will return Promise, which will be fullfiled only on
  56. * next scheduler queue processing step and this is exactly what we need.
  57. */
  58. export declare const nextTick: () => Promise<void>;
  59. /** Returns control to thread each 'tick' ms to avoid blocking. */
  60. export declare function asyncLoop(iters: number, tick: number, cb: (i: number) => void): Promise<void>;
  61. /**
  62. * Converts string to bytes using UTF8 encoding.
  63. * @example utf8ToBytes('abc') // Uint8Array.from([97, 98, 99])
  64. */
  65. export declare function utf8ToBytes(str: string): Uint8Array;
  66. /**
  67. * Converts bytes to string using UTF8 encoding.
  68. * @example bytesToUtf8(Uint8Array.from([97, 98, 99])) // 'abc'
  69. */
  70. export declare function bytesToUtf8(bytes: Uint8Array): string;
  71. /** Accepted input of hash functions. Strings are converted to byte arrays. */
  72. export type Input = string | Uint8Array;
  73. /**
  74. * Normalizes (non-hex) string or Uint8Array to Uint8Array.
  75. * Warning: when Uint8Array is passed, it would NOT get copied.
  76. * Keep in mind for future mutable operations.
  77. */
  78. export declare function toBytes(data: Input): Uint8Array;
  79. /** KDFs can accept string or Uint8Array for user convenience. */
  80. export type KDFInput = string | Uint8Array;
  81. /**
  82. * Helper for KDFs: consumes uint8array or string.
  83. * When string is passed, does utf8 decoding, using TextDecoder.
  84. */
  85. export declare function kdfInputToBytes(data: KDFInput): Uint8Array;
  86. /** Copies several Uint8Arrays into one. */
  87. export declare function concatBytes(...arrays: Uint8Array[]): Uint8Array;
  88. type EmptyObj = {};
  89. export declare function checkOpts<T1 extends EmptyObj, T2 extends EmptyObj>(defaults: T1, opts?: T2): T1 & T2;
  90. /** Hash interface. */
  91. export type IHash = {
  92. (data: Uint8Array): Uint8Array;
  93. blockLen: number;
  94. outputLen: number;
  95. create: any;
  96. };
  97. /** For runtime check if class implements interface */
  98. export declare abstract class Hash<T extends Hash<T>> {
  99. abstract blockLen: number;
  100. abstract outputLen: number;
  101. abstract update(buf: Input): this;
  102. abstract digestInto(buf: Uint8Array): void;
  103. abstract digest(): Uint8Array;
  104. /**
  105. * Resets internal state. Makes Hash instance unusable.
  106. * Reset is impossible for keyed hashes if key is consumed into state. If digest is not consumed
  107. * by user, they will need to manually call `destroy()` when zeroing is necessary.
  108. */
  109. abstract destroy(): void;
  110. /**
  111. * Clones hash instance. Unsafe: doesn't check whether `to` is valid. Can be used as `clone()`
  112. * when no options are passed.
  113. * Reasons to use `_cloneInto` instead of clone: 1) performance 2) reuse instance => all internal
  114. * buffers are overwritten => causes buffer overwrite which is used for digest in some cases.
  115. * There are no guarantees for clean-up because it's impossible in JS.
  116. */
  117. abstract _cloneInto(to?: T): T;
  118. abstract clone(): T;
  119. }
  120. /**
  121. * XOF: streaming API to read digest in chunks.
  122. * Same as 'squeeze' in keccak/k12 and 'seek' in blake3, but more generic name.
  123. * When hash used in XOF mode it is up to user to call '.destroy' afterwards, since we cannot
  124. * destroy state, next call can require more bytes.
  125. */
  126. export type HashXOF<T extends Hash<T>> = Hash<T> & {
  127. xof(bytes: number): Uint8Array;
  128. xofInto(buf: Uint8Array): Uint8Array;
  129. };
  130. /** Hash function */
  131. export type CHash = ReturnType<typeof createHasher>;
  132. /** Hash function with output */
  133. export type CHashO = ReturnType<typeof createOptHasher>;
  134. /** XOF with output */
  135. export type CHashXO = ReturnType<typeof createXOFer>;
  136. /** Wraps hash function, creating an interface on top of it */
  137. export declare function createHasher<T extends Hash<T>>(hashCons: () => Hash<T>): {
  138. (msg: Input): Uint8Array;
  139. outputLen: number;
  140. blockLen: number;
  141. create(): Hash<T>;
  142. };
  143. export declare function createOptHasher<H extends Hash<H>, T extends Object>(hashCons: (opts?: T) => Hash<H>): {
  144. (msg: Input, opts?: T): Uint8Array;
  145. outputLen: number;
  146. blockLen: number;
  147. create(opts?: T): Hash<H>;
  148. };
  149. export declare function createXOFer<H extends HashXOF<H>, T extends Object>(hashCons: (opts?: T) => HashXOF<H>): {
  150. (msg: Input, opts?: T): Uint8Array;
  151. outputLen: number;
  152. blockLen: number;
  153. create(opts?: T): HashXOF<H>;
  154. };
  155. export declare const wrapConstructor: typeof createHasher;
  156. export declare const wrapConstructorWithOpts: typeof createOptHasher;
  157. export declare const wrapXOFConstructorWithOpts: typeof createXOFer;
  158. /** Cryptographically secure PRNG. Uses internal OS-level `crypto.getRandomValues`. */
  159. export declare function randomBytes(bytesLength?: number): Uint8Array;
  160. export {};
  161. //# sourceMappingURL=utils.d.ts.map