viz-js-lib 0.11.0 → 0.12.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/.qoder/docs/spec/viz-dns-nameserver-spec.md +982 -0
  2. package/.qoder/docs/viz-cpp-node-docs/data-types.md +322 -0
  3. package/.qoder/docs/viz-cpp-node-docs/index.md +160 -0
  4. package/.qoder/docs/viz-cpp-node-docs/op-account-market.md +236 -0
  5. package/.qoder/docs/viz-cpp-node-docs/op-account.md +199 -0
  6. package/.qoder/docs/viz-cpp-node-docs/op-award.md +162 -0
  7. package/.qoder/docs/viz-cpp-node-docs/op-committee.md +193 -0
  8. package/.qoder/docs/viz-cpp-node-docs/op-content.md +157 -0
  9. package/.qoder/docs/viz-cpp-node-docs/op-escrow.md +224 -0
  10. package/.qoder/docs/viz-cpp-node-docs/op-invite.md +219 -0
  11. package/.qoder/docs/viz-cpp-node-docs/op-proposal.md +229 -0
  12. package/.qoder/docs/viz-cpp-node-docs/op-recovery.md +188 -0
  13. package/.qoder/docs/viz-cpp-node-docs/op-subscription.md +146 -0
  14. package/.qoder/docs/viz-cpp-node-docs/op-transfer-vesting.md +224 -0
  15. package/.qoder/docs/viz-cpp-node-docs/op-witness.md +252 -0
  16. package/.qoder/docs/viz-cpp-node-docs/plugins.md +887 -0
  17. package/.qoder/docs/viz-cpp-node-docs/virtual-operations.md +513 -0
  18. package/.qoder/repowiki/en/content/API Reference/API Reference.md +724 -0
  19. package/.qoder/repowiki/en/content/API Reference/Configuration Options.md +410 -0
  20. package/.qoder/repowiki/en/content/API Reference/Core API Methods.md +547 -0
  21. package/.qoder/repowiki/en/content/API Reference/Streaming APIs.md +380 -0
  22. package/.qoder/repowiki/en/content/API Reference/Transport Layer.md +341 -0
  23. package/.qoder/repowiki/en/content/API Reference/VIZ Blockchain Operations Coverage Status.md +427 -0
  24. package/.qoder/repowiki/en/content/Authentication & Cryptography/Authentication & Cryptography.md +430 -0
  25. package/.qoder/repowiki/en/content/Authentication & Cryptography/Digital Signatures.md +462 -0
  26. package/.qoder/repowiki/en/content/Authentication & Cryptography/Key Management.md +456 -0
  27. package/.qoder/repowiki/en/content/Authentication & Cryptography/Memo Encryption.md +331 -0
  28. package/.qoder/repowiki/en/content/Authentication & Cryptography/Security Practices.md +488 -0
  29. package/.qoder/repowiki/en/content/Broadcast Transactions/Broadcast Transactions.md +432 -0
  30. package/.qoder/repowiki/en/content/Broadcast Transactions/Network Broadcasting.md +418 -0
  31. package/.qoder/repowiki/en/content/Broadcast Transactions/Operation Construction.md +352 -0
  32. package/.qoder/repowiki/en/content/Broadcast Transactions/Transaction Preparation.md +353 -0
  33. package/.qoder/repowiki/en/content/Broadcast Transactions/Transaction Signing.md +404 -0
  34. package/.qoder/repowiki/en/content/Data Serialization/Data Serialization.md +540 -0
  35. package/.qoder/repowiki/en/content/Data Serialization/Encoding & Decoding.md +463 -0
  36. package/.qoder/repowiki/en/content/Data Serialization/Object Templates.md +413 -0
  37. package/.qoder/repowiki/en/content/Data Serialization/Type System.md +514 -0
  38. package/.qoder/repowiki/en/content/Data Serialization/Validation Rules.md +439 -0
  39. package/.qoder/repowiki/en/content/Examples & Tutorials.md +485 -0
  40. package/.qoder/repowiki/en/content/Getting Started.md +345 -0
  41. package/.qoder/repowiki/en/content/Testing & Development.md +637 -0
  42. package/.qoder/repowiki/en/content/Utilities & Helpers.md +557 -0
  43. package/.qoder/repowiki/en/meta/repowiki-metadata.json +1 -0
  44. package/VIZ-JS-LIB-COVERAGE-STATUS.md +356 -0
  45. package/config.json +3 -1
  46. package/dist/statistics.html +1 -1
  47. package/dist/viz-tests.min.js +32 -42
  48. package/dist/viz-tests.min.js.gz +0 -0
  49. package/dist/viz.min.js +8 -18
  50. package/dist/viz.min.js.gz +0 -0
  51. package/lib/api/methods.js +24 -0
  52. package/lib/auth/serializer/src/ChainTypes.js +2 -1
  53. package/lib/auth/serializer/src/operations.js +35 -2
  54. package/lib/broadcast/index.js +29 -15
  55. package/lib/broadcast/operations.js +4 -0
  56. package/lib/dns.js +658 -0
  57. package/lib/index.js +3 -1
  58. package/package.json +3 -2
  59. package/test/dns.test.js +395 -0
  60. package/webpack/makeConfig.js +3 -0
@@ -0,0 +1,488 @@
1
+ # Security Practices
2
+
3
+ <cite>
4
+ **Referenced Files in This Document**
5
+ - [src/auth/index.js](file://src/auth/index.js)
6
+ - [src/auth/ecc/index.js](file://src/auth/ecc/index.js)
7
+ - [src/auth/ecc/src/key_private.js](file://src/auth/ecc/src/key_private.js)
8
+ - [src/auth/ecc/src/key_public.js](file://src/auth/ecc/src/key_public.js)
9
+ - [src/auth/ecc/src/hash.js](file://src/auth/ecc/src/hash.js)
10
+ - [src/auth/ecc/src/signature.js](file://src/auth/ecc/src/signature.js)
11
+ - [src/auth/ecc/src/ecdsa.js](file://src/auth/ecc/src/ecdsa.js)
12
+ - [src/auth/ecc/src/aes.js](file://src/auth/ecc/src/aes.js)
13
+ - [src/auth/memo.js](file://src/auth/memo.js)
14
+ - [src/auth/serializer/src/validation.js](file://src/auth/serializer/src/validation.js)
15
+ - [src/auth/serializer/src/serializer.js](file://src/auth/serializer/src/serializer.js)
16
+ - [src/auth/serializer/src/operations.js](file://src/auth/serializer/src/operations.js)
17
+ - [src/api/transports/ws.js](file://src/api/transports/ws.js)
18
+ - [src/api/transports/http.js](file://src/api/transports/http.js)
19
+ - [src/utils.js](file://src/utils.js)
20
+ - [src/config.js](file://src/config.js)
21
+ </cite>
22
+
23
+ ## Table of Contents
24
+ 1. [Introduction](#introduction)
25
+ 2. [Project Structure](#project-structure)
26
+ 3. [Core Components](#core-components)
27
+ 4. [Architecture Overview](#architecture-overview)
28
+ 5. [Detailed Component Analysis](#detailed-component-analysis)
29
+ 6. [Dependency Analysis](#dependency-analysis)
30
+ 7. [Performance Considerations](#performance-considerations)
31
+ 8. [Troubleshooting Guide](#troubleshooting-guide)
32
+ 9. [Conclusion](#conclusion)
33
+ 10. [Appendices](#appendices)
34
+
35
+ ## Introduction
36
+ This document defines comprehensive security practices for the VIZ JavaScript library authentication system. It explains secure key generation methodologies, entropy sources, cryptographic best practices, validation and sanitization procedures, protections against common attacks, secure storage and memory management recommendations, secure transmission practices, and operational guidance for secure application development, threat modeling, audits, incident response, and production deployment checklists.
37
+
38
+ ## Project Structure
39
+ The authentication system is organized around:
40
+ - Authentication orchestration and transaction signing
41
+ - Elliptic Curve Cryptography primitives (ECDSA, key derivation, hashing)
42
+ - AES-based memo encryption/decryption
43
+ - Transaction serialization and validation
44
+ - Transport layer for secure communication
45
+
46
+ ```mermaid
47
+ graph TB
48
+ subgraph "Auth Orchestration"
49
+ AUTH["src/auth/index.js"]
50
+ MEMO["src/auth/memo.js"]
51
+ end
52
+ subgraph "ECC Primitives"
53
+ ECCIDX["src/auth/ecc/index.js"]
54
+ PRIV["src/auth/ecc/src/key_private.js"]
55
+ PUB["src/auth/ecc/src/key_public.js"]
56
+ HASH["src/auth/ecc/src/hash.js"]
57
+ SIG["src/auth/ecc/src/signature.js"]
58
+ ECDSA["src/auth/ecc/src/ecdsa.js"]
59
+ AES["src/auth/ecc/src/aes.js"]
60
+ end
61
+ subgraph "Serialization & Validation"
62
+ VALID["src/auth/serializer/src/validation.js"]
63
+ SER["src/auth/serializer/src/serializer.js"]
64
+ OPS["src/auth/serializer/src/operations.js"]
65
+ end
66
+ subgraph "Transports"
67
+ WS["src/api/transports/ws.js"]
68
+ HTTP["src/api/transports/http.js"]
69
+ end
70
+ CFG["src/config.js"]
71
+ AUTH --> PRIV
72
+ AUTH --> PUB
73
+ AUTH --> SIG
74
+ AUTH --> HASH
75
+ AUTH --> OPS
76
+ AUTH --> SER
77
+ AUTH --> VALID
78
+ AUTH --> MEMO
79
+ MEMO --> AES
80
+ MEMO --> PRIV
81
+ MEMO --> PUB
82
+ WS --> CFG
83
+ HTTP --> CFG
84
+ ```
85
+
86
+ **Diagram sources**
87
+ - [src/auth/index.js](file://src/auth/index.js#L1-L133)
88
+ - [src/auth/memo.js](file://src/auth/memo.js#L1-L113)
89
+ - [src/auth/ecc/index.js](file://src/auth/ecc/index.js#L1-L13)
90
+ - [src/auth/ecc/src/key_private.js](file://src/auth/ecc/src/key_private.js#L1-L172)
91
+ - [src/auth/ecc/src/key_public.js](file://src/auth/ecc/src/key_public.js#L1-L170)
92
+ - [src/auth/ecc/src/hash.js](file://src/auth/ecc/src/hash.js#L1-L59)
93
+ - [src/auth/ecc/src/signature.js](file://src/auth/ecc/src/signature.js#L1-L163)
94
+ - [src/auth/ecc/src/ecdsa.js](file://src/auth/ecc/src/ecdsa.js#L1-L219)
95
+ - [src/auth/ecc/src/aes.js](file://src/auth/ecc/src/aes.js#L1-L181)
96
+ - [src/auth/serializer/src/validation.js](file://src/auth/serializer/src/validation.js#L1-L288)
97
+ - [src/auth/serializer/src/serializer.js](file://src/auth/serializer/src/serializer.js#L1-L195)
98
+ - [src/auth/serializer/src/operations.js](file://src/auth/serializer/src/operations.js#L1-L922)
99
+ - [src/api/transports/ws.js](file://src/api/transports/ws.js#L1-L136)
100
+ - [src/api/transports/http.js](file://src/api/transports/http.js#L1-L53)
101
+ - [src/config.js](file://src/config.js#L1-L10)
102
+
103
+ **Section sources**
104
+ - [src/auth/index.js](file://src/auth/index.js#L1-L133)
105
+ - [src/auth/ecc/index.js](file://src/auth/ecc/index.js#L1-L13)
106
+ - [src/auth/memo.js](file://src/auth/memo.js#L1-L113)
107
+ - [src/auth/serializer/src/validation.js](file://src/auth/serializer/src/validation.js#L1-L288)
108
+ - [src/auth/serializer/src/serializer.js](file://src/auth/serializer/src/serializer.js#L1-L195)
109
+ - [src/auth/serializer/src/operations.js](file://src/auth/serializer/src/operations.js#L1-L922)
110
+ - [src/api/transports/ws.js](file://src/api/transports/ws.js#L1-L136)
111
+ - [src/api/transports/http.js](file://src/api/transports/http.js#L1-L53)
112
+ - [src/config.js](file://src/config.js#L1-L10)
113
+
114
+ ## Core Components
115
+ - Authentication orchestration: key derivation, WIF conversion, verification, and transaction signing.
116
+ - ECC primitives: deterministic ECDSA signatures, key derivation, hashing, and public key operations.
117
+ - AES memo encryption: ephemeral shared secrets, nonces, and checksum validation.
118
+ - Serialization and validation: strict type checks and safe numeric conversions.
119
+ - Transports: WebSocket and HTTP transport with connection lifecycle and error handling.
120
+
121
+ Key security-relevant responsibilities:
122
+ - Secure key generation via deterministic seeds and SHA-256 hashing.
123
+ - Deterministic nonce generation for ECDSA and AES to avoid weak randomness.
124
+ - Strict validation of inputs and serialized structures.
125
+ - Secure transport configuration and error propagation.
126
+
127
+ **Section sources**
128
+ - [src/auth/index.js](file://src/auth/index.js#L19-L130)
129
+ - [src/auth/ecc/src/key_private.js](file://src/auth/ecc/src/key_private.js#L34-L81)
130
+ - [src/auth/ecc/src/signature.js](file://src/auth/ecc/src/signature.js#L62-L98)
131
+ - [src/auth/ecc/src/ecdsa.js](file://src/auth/ecc/src/ecdsa.js#L9-L63)
132
+ - [src/auth/ecc/src/aes.js](file://src/auth/ecc/src/aes.js#L23-L101)
133
+ - [src/auth/serializer/src/validation.js](file://src/auth/serializer/src/validation.js#L29-L287)
134
+ - [src/api/transports/ws.js](file://src/api/transports/ws.js#L27-L48)
135
+ - [src/api/transports/http.js](file://src/api/transports/http.js#L17-L41)
136
+
137
+ ## Architecture Overview
138
+ End-to-end signing and memo encryption pipeline:
139
+
140
+ ```mermaid
141
+ sequenceDiagram
142
+ participant App as "Application"
143
+ participant Auth as "Auth Module<br/>src/auth/index.js"
144
+ participant Priv as "PrivateKey<br/>src/auth/ecc/src/key_private.js"
145
+ participant Pub as "PublicKey<br/>src/auth/ecc/src/key_public.js"
146
+ participant Sig as "Signature<br/>src/auth/ecc/src/signature.js"
147
+ participant Ser as "Serializer<br/>src/auth/serializer/src/serializer.js"
148
+ participant Ops as "Operations<br/>src/auth/serializer/src/operations.js"
149
+ App->>Auth : "generateKeys(name, password, roles)"
150
+ Auth->>Priv : "fromSeed(seed)"
151
+ Priv-->>Auth : "PrivateKey"
152
+ Auth->>Pub : "toPublic()"
153
+ Pub-->>Auth : "PublicKey string"
154
+ App->>Auth : "signTransaction(trx, keys)"
155
+ Auth->>Ops : "transaction.toBuffer(trx)"
156
+ Ops-->>Auth : "Buffer"
157
+ Auth->>Ser : "Serializer.toBuffer(trx)"
158
+ Ser-->>Auth : "Buffer"
159
+ Auth->>Sig : "Signature.signBuffer(Buffer.concat([chain_id, buf]), key)"
160
+ Sig-->>Auth : "Signature"
161
+ Auth-->>App : "signed_transaction with signatures"
162
+ ```
163
+
164
+ **Diagram sources**
165
+ - [src/auth/index.js](file://src/auth/index.js#L34-L130)
166
+ - [src/auth/ecc/src/key_private.js](file://src/auth/ecc/src/key_private.js#L34-L81)
167
+ - [src/auth/ecc/src/key_public.js](file://src/auth/ecc/src/key_public.js#L96-L100)
168
+ - [src/auth/ecc/src/signature.js](file://src/auth/ecc/src/signature.js#L62-L98)
169
+ - [src/auth/serializer/src/serializer.js](file://src/auth/serializer/src/serializer.js#L184-L192)
170
+ - [src/auth/serializer/src/operations.js](file://src/auth/serializer/src/operations.js#L73-L81)
171
+
172
+ ## Detailed Component Analysis
173
+
174
+ ### Authentication Orchestration
175
+ - Key derivation: Uses a deterministic seed built from name, role, and password, hashed with SHA-256, then mapped to curve scalar to derive private keys. Public keys are derived from private keys and formatted with checksummed addresses.
176
+ - WIF handling: Validates WIF checksums and supports conversion to/from WIF and public keys.
177
+ - Transaction signing: Concatenates chain ID and serialized transaction buffer, signs with ECDSA, and returns a signed transaction with appended signatures.
178
+
179
+ Security considerations:
180
+ - Seed composition must avoid predictable patterns; ensure name and role are controlled inputs.
181
+ - WIF validation prevents malformed keys from being used.
182
+ - Transaction signing requires the correct chain ID to prevent cross-chain replay.
183
+
184
+ **Section sources**
185
+ - [src/auth/index.js](file://src/auth/index.js#L34-L130)
186
+
187
+ ### Elliptic Curve Digital Signature Algorithm (ECDSA)
188
+ - Deterministic nonce generation using HMAC-SHA256 with RFC6979-style K-value derivation.
189
+ - Canonical signature enforcement to reduce malleability.
190
+ - Recovery parameter calculation and public key recovery from signatures.
191
+
192
+ Security considerations:
193
+ - Nonce derivation ensures deterministic signatures without compromising security.
194
+ - Canonical S-values reduce signature malleability.
195
+ - Public key recovery avoids storing uncompressed points unnecessarily.
196
+
197
+ ```mermaid
198
+ flowchart TD
199
+ Start(["Sign Buffer"]) --> Hash["SHA-256 hash of buffer"]
200
+ Hash --> GenK["RFC6979-like K generation"]
201
+ GenK --> CheckSig{"Valid signature candidates?"}
202
+ CheckSig --> |No| Retry["Adjust nonce and retry"]
203
+ CheckSig --> |Yes| Canon["Enforce low-S canonical form"]
204
+ Canon --> Output(["Return Signature"])
205
+ ```
206
+
207
+ **Diagram sources**
208
+ - [src/auth/ecc/src/ecdsa.js](file://src/auth/ecc/src/ecdsa.js#L9-L63)
209
+ - [src/auth/ecc/src/signature.js](file://src/auth/ecc/src/signature.js#L72-L98)
210
+
211
+ **Section sources**
212
+ - [src/auth/ecc/src/ecdsa.js](file://src/auth/ecc/src/ecdsa.js#L65-L95)
213
+ - [src/auth/ecc/src/signature.js](file://src/auth/ecc/src/signature.js#L62-L98)
214
+
215
+ ### Private Key Management
216
+ - Seed-based key derivation using SHA-256.
217
+ - WIF import/export with version-byte and checksum validation.
218
+ - Shared secret computation for ECIES-style encryption.
219
+ - Child key derivation for hierarchical key management.
220
+
221
+ Security considerations:
222
+ - Private key buffers are handled as 32-byte values; ensure zeroization after use where applicable.
223
+ - WIF checksum validation prevents accidental corruption.
224
+ - Shared secret uses SHA-512 to derive a 512-bit key for AES-256-CBC.
225
+
226
+ **Section sources**
227
+ - [src/auth/ecc/src/key_private.js](file://src/auth/ecc/src/key_private.js#L21-L81)
228
+ - [src/auth/ecc/src/key_private.js](file://src/auth/ecc/src/key_private.js#L105-L119)
229
+
230
+ ### Public Key Operations
231
+ - Encoding/decoding of public keys in compressed/uncompressed forms.
232
+ - Blockchain address derivation using SHA-512 and RIPEMD-160.
233
+ - String representation with configurable address prefixes and checksum validation.
234
+
235
+ Security considerations:
236
+ - Address validation includes RIPEMD-160 checksum verification.
237
+ - Compressed encoding reduces size and improves performance.
238
+
239
+ **Section sources**
240
+ - [src/auth/ecc/src/key_public.js](file://src/auth/ecc/src/key_public.js#L22-L100)
241
+
242
+ ### Hash Functions and Utilities
243
+ - SHA-1, SHA-256, SHA-512, HMAC-SHA256, and RIPEMD-160.
244
+ - Used for key derivation, checksums, and shared secret computation.
245
+
246
+ Security considerations:
247
+ - SHA-256 is used for deterministic key derivation.
248
+ - RIPEMD-160 is used for address checksums.
249
+
250
+ **Section sources**
251
+ - [src/auth/ecc/src/hash.js](file://src/auth/ecc/src/hash.js#L8-L34)
252
+
253
+ ### AES Memo Encryption
254
+ - Ephemeral shared secret computed from private/public keys.
255
+ - Unique nonce generation using time + entropy to prevent reuse.
256
+ - Checksum validation to detect key mismatches during decryption.
257
+
258
+ Security considerations:
259
+ - Nonces are 64-bit unsigned integers constructed from current time and entropy.
260
+ - Decryption validates a checksum derived from the encryption key to detect tampering or wrong keys.
261
+
262
+ ```mermaid
263
+ sequenceDiagram
264
+ participant Sender as "Sender"
265
+ participant AES as "AES Module<br/>src/auth/ecc/src/aes.js"
266
+ participant Recv as "Receiver"
267
+ Sender->>AES : "encrypt(private_key, public_key, message, nonce)"
268
+ AES->>AES : "compute shared secret S"
269
+ AES->>AES : "derive key and IV from SHA-512(S || nonce)"
270
+ AES-->>Sender : "{nonce, encrypted, checksum}"
271
+ Recv->>AES : "decrypt(private_key, public_key, nonce, encrypted, checksum)"
272
+ AES->>AES : "recompute key and IV"
273
+ AES->>AES : "verify checksum"
274
+ AES-->>Recv : "plaintext message"
275
+ ```
276
+
277
+ **Diagram sources**
278
+ - [src/auth/ecc/src/aes.js](file://src/auth/ecc/src/aes.js#L23-L101)
279
+ - [src/auth/memo.js](file://src/auth/memo.js#L16-L84)
280
+
281
+ **Section sources**
282
+ - [src/auth/ecc/src/aes.js](file://src/auth/ecc/src/aes.js#L161-L173)
283
+ - [src/auth/memo.js](file://src/auth/memo.js#L92-L109)
284
+
285
+ ### Transaction Serialization and Validation
286
+ - Serializer converts typed objects to buffers and vice versa.
287
+ - Validation enforces types, ranges, and formats for operation fields.
288
+ - Operations define transaction and signed_transaction structures with explicit sizes.
289
+
290
+ Security considerations:
291
+ - Strict type validation prevents malformed data from entering the signing pipeline.
292
+ - Numeric overflow checks protect against unsafe conversions.
293
+
294
+ **Section sources**
295
+ - [src/auth/serializer/src/serializer.js](file://src/auth/serializer/src/serializer.js#L17-L192)
296
+ - [src/auth/serializer/src/validation.js](file://src/auth/serializer/src/validation.js#L29-L287)
297
+ - [src/auth/serializer/src/operations.js](file://src/auth/serializer/src/operations.js#L73-L125)
298
+
299
+ ### Transport Security
300
+ - WebSocket transport supports both Node.js and browser environments.
301
+ - HTTP transport uses cross-fetch with JSON-RPC semantics and error propagation.
302
+ - Both transports rely on configuration for endpoint selection.
303
+
304
+ Security considerations:
305
+ - Ensure endpoints use TLS (wss:// and https://) in production.
306
+ - Validate and sanitize any user-provided endpoint URLs.
307
+ - Handle connection errors and close events to avoid resource leaks.
308
+
309
+ **Section sources**
310
+ - [src/api/transports/ws.js](file://src/api/transports/ws.js#L7-L14)
311
+ - [src/api/transports/ws.js](file://src/api/transports/ws.js#L34-L46)
312
+ - [src/api/transports/http.js](file://src/api/transports/http.js#L17-L41)
313
+ - [src/config.js](file://src/config.js#L1-L10)
314
+
315
+ ## Dependency Analysis
316
+ ```mermaid
317
+ graph LR
318
+ AUTH["auth/index.js"] --> PRIV["ecc/src/key_private.js"]
319
+ AUTH --> PUB["ecc/src/key_public.js"]
320
+ AUTH --> SIG["ecc/src/signature.js"]
321
+ AUTH --> HASH["ecc/src/hash.js"]
322
+ AUTH --> OPS["serializer/src/operations.js"]
323
+ AUTH --> SER["serializer/src/serializer.js"]
324
+ AUTH --> VALID["serializer/src/validation.js"]
325
+ MEMO["auth/memo.js"] --> AES["ecc/src/aes.js"]
326
+ MEMO --> PRIV
327
+ MEMO --> PUB
328
+ WS["api/transports/ws.js"] --> CFG["config.js"]
329
+ HTTP["api/transports/http.js"] --> CFG
330
+ ```
331
+
332
+ **Diagram sources**
333
+ - [src/auth/index.js](file://src/auth/index.js#L1-L11)
334
+ - [src/auth/memo.js](file://src/auth/memo.js#L1-L7)
335
+ - [src/api/transports/ws.js](file://src/api/transports/ws.js#L1-L5)
336
+ - [src/api/transports/http.js](file://src/api/transports/http.js#L1-L5)
337
+ - [src/config.js](file://src/config.js#L1-L10)
338
+
339
+ **Section sources**
340
+ - [src/auth/index.js](file://src/auth/index.js#L1-L11)
341
+ - [src/auth/memo.js](file://src/auth/memo.js#L1-L7)
342
+ - [src/api/transports/ws.js](file://src/api/transports/ws.js#L1-L5)
343
+ - [src/api/transports/http.js](file://src/api/transports/http.js#L1-L5)
344
+ - [src/config.js](file://src/config.js#L1-L10)
345
+
346
+ ## Performance Considerations
347
+ - ECDSA signature generation uses deterministic nonce derivation; occasional retries are logged but bounded.
348
+ - AES encryption/decryption uses CBC mode with 256-bit keys; ensure hardware acceleration is available in browsers.
349
+ - Serialization performance benefits from preallocated ByteBuffer capacity; avoid excessive allocations in hot paths.
350
+ - Transport batching and connection reuse improve throughput; handle backpressure and timeouts.
351
+
352
+ [No sources needed since this section provides general guidance]
353
+
354
+ ## Troubleshooting Guide
355
+ Common issues and mitigations:
356
+ - Invalid WIF checksum: occurs when version byte or checksum mismatch is detected during WIF parsing.
357
+ - Transaction signing failures: verify chain ID matches network, and ensure transaction serialization is correct.
358
+ - Memo decryption errors: confirm correct private/public key pair and that the checksum matches the derived key.
359
+ - Transport errors: inspect WebSocket open/close/error events and HTTP status codes; ensure TLS endpoints.
360
+
361
+ Operational checks:
362
+ - Validate account names and operation fields using provided validators.
363
+ - Monitor logs for repeated nonce warnings during signature generation.
364
+ - Verify transport connectivity and error payloads.
365
+
366
+ **Section sources**
367
+ - [src/auth/ecc/src/key_private.js](file://src/auth/ecc/src/key_private.js#L55-L70)
368
+ - [src/auth/ecc/src/signature.js](file://src/auth/ecc/src/signature.js#L72-L98)
369
+ - [src/auth/ecc/src/aes.js](file://src/auth/ecc/src/aes.js#L93-L96)
370
+ - [src/api/transports/ws.js](file://src/api/transports/ws.js#L96-L101)
371
+ - [src/api/transports/http.js](file://src/api/transports/http.js#L27-L41)
372
+ - [src/auth/serializer/src/validation.js](file://src/auth/serializer/src/validation.js#L35-L40)
373
+
374
+ ## Conclusion
375
+ The VIZ JavaScript library’s authentication system integrates deterministic key derivation, secure ECDSA signatures, validated serialization, and AES-based memo encryption. By following the security practices outlined here—ensuring strong entropy, validating inputs, using secure transports, and managing keys carefully—applications can achieve robust security in production environments.
376
+
377
+ [No sources needed since this section summarizes without analyzing specific files]
378
+
379
+ ## Appendices
380
+
381
+ ### Secure Key Generation Methodologies
382
+ - Use deterministic seeds derived from strong secrets (name, role, password) hashed with SHA-256.
383
+ - Avoid predictable combinations; ensure role and password are sufficiently random.
384
+ - Store private keys only in memory during signing; export only as WIF when necessary.
385
+
386
+ **Section sources**
387
+ - [src/auth/index.js](file://src/auth/index.js#L34-L49)
388
+ - [src/auth/ecc/src/key_private.js](file://src/auth/ecc/src/key_private.js#L34-L40)
389
+
390
+ ### Entropy Sources and Nonces
391
+ - ECDSA nonce generation uses HMAC-SHA256 with iterative refinement to produce canonical signatures.
392
+ - AES memo nonce is a 64-bit value combining timestamp and entropy to prevent reuse.
393
+
394
+ **Section sources**
395
+ - [src/auth/ecc/src/ecdsa.js](file://src/auth/ecc/src/ecdsa.js#L9-L63)
396
+ - [src/auth/ecc/src/aes.js](file://src/auth/ecc/src/aes.js#L161-L173)
397
+
398
+ ### Cryptographic Best Practices
399
+ - Use SHA-256 for key derivation and RIPEMD-160 for address checksums.
400
+ - Enforce low-S canonical signatures to prevent malleability.
401
+ - Validate all inputs and serialized structures before signing.
402
+
403
+ **Section sources**
404
+ - [src/auth/ecc/src/hash.js](file://src/auth/ecc/src/hash.js#L16-L34)
405
+ - [src/auth/ecc/src/signature.js](file://src/auth/ecc/src/signature.js#L88-L98)
406
+ - [src/auth/serializer/src/validation.js](file://src/auth/serializer/src/validation.js#L29-L121)
407
+
408
+ ### Security Validation and Input Sanitization
409
+ - Validate required fields, types, and numeric ranges.
410
+ - Reject empty or malformed values early in the pipeline.
411
+ - Use serializers to ensure consistent binary representation.
412
+
413
+ **Section sources**
414
+ - [src/auth/serializer/src/validation.js](file://src/auth/serializer/src/validation.js#L35-L121)
415
+ - [src/auth/serializer/src/serializer.js](file://src/auth/serializer/src/serializer.js#L17-L77)
416
+
417
+ ### Protection Against Common Attacks
418
+ - Replay attack prevention: include chain ID in signed data.
419
+ - Malleability resistance: enforce low-S signatures.
420
+ - Key compromise detection: memo checksum validation and WIF checksum verification.
421
+
422
+ **Section sources**
423
+ - [src/auth/index.js](file://src/auth/index.js#L113-L127)
424
+ - [src/auth/ecc/src/signature.js](file://src/auth/ecc/src/signature.js#L88-L98)
425
+ - [src/auth/ecc/src/aes.js](file://src/auth/ecc/src/aes.js#L93-L96)
426
+ - [src/auth/ecc/src/key_private.js](file://src/auth/ecc/src/key_private.js#L55-L70)
427
+
428
+ ### Secure Key Storage and Memory Management
429
+ - Keep private keys in memory only during signing; avoid persisting raw secrets.
430
+ - Export only WIF when necessary; treat WIF as sensitive as private keys.
431
+ - Zeroize buffers after use where feasible.
432
+
433
+ **Section sources**
434
+ - [src/auth/ecc/src/key_private.js](file://src/auth/ecc/src/key_private.js#L72-L81)
435
+
436
+ ### Secure Transmission Practices
437
+ - Use TLS-enabled endpoints (wss:// and https://).
438
+ - Validate endpoint configuration and reject unexpected schemes.
439
+ - Handle transport errors and reconnections gracefully.
440
+
441
+ **Section sources**
442
+ - [src/api/transports/ws.js](file://src/api/transports/ws.js#L34-L46)
443
+ - [src/api/transports/http.js](file://src/api/transports/http.js#L17-L41)
444
+ - [src/config.js](file://src/config.js#L1-L10)
445
+
446
+ ### Secure Application Development Guidelines
447
+ - Threat model: assume attackers can observe traffic, modify messages, and inject malicious data.
448
+ - Defense-in-depth: combine input validation, signature verification, and transport security.
449
+ - Least privilege: derive keys per-role and limit exposure.
450
+
451
+ **Section sources**
452
+ - [src/auth/index.js](file://src/auth/index.js#L56-L63)
453
+ - [src/auth/serializer/src/validation.js](file://src/auth/serializer/src/validation.js#L29-L121)
454
+
455
+ ### Security Audit Procedures
456
+ - Review key derivation and WIF handling for correctness and error handling.
457
+ - Validate signature verification and memo decryption flows.
458
+ - Inspect transport configuration and error propagation.
459
+
460
+ **Section sources**
461
+ - [src/auth/ecc/src/key_private.js](file://src/auth/ecc/src/key_private.js#L55-L70)
462
+ - [src/auth/ecc/src/signature.js](file://src/auth/ecc/src/signature.js#L110-L121)
463
+ - [src/auth/ecc/src/aes.js](file://src/auth/ecc/src/aes.js#L93-L101)
464
+ - [src/api/transports/ws.js](file://src/api/transports/ws.js#L96-L101)
465
+ - [src/api/transports/http.js](file://src/api/transports/http.js#L27-L41)
466
+
467
+ ### Incident Response Protocols
468
+ - Detect replay attempts via chain ID mismatches.
469
+ - Investigate signature malleability or canonical form violations.
470
+ - Monitor memo decryption failures for key rotation needs.
471
+
472
+ **Section sources**
473
+ - [src/auth/index.js](file://src/auth/index.js#L113-L127)
474
+ - [src/auth/ecc/src/signature.js](file://src/auth/ecc/src/signature.js#L88-L98)
475
+ - [src/auth/ecc/src/aes.js](file://src/auth/ecc/src/aes.js#L93-L96)
476
+
477
+ ### Production Deployment Checklist
478
+ - Configure TLS endpoints and validate certificates.
479
+ - Enforce input validation and numeric overflow checks.
480
+ - Use deterministic seeds and secure nonces; log warnings for repeated attempts.
481
+ - Rotate keys per role and minimize exposure of private keys.
482
+ - Monitor transport health and error rates.
483
+
484
+ **Section sources**
485
+ - [src/api/transports/ws.js](file://src/api/transports/ws.js#L34-L46)
486
+ - [src/auth/serializer/src/validation.js](file://src/auth/serializer/src/validation.js#L227-L287)
487
+ - [src/auth/ecc/src/ecdsa.js](file://src/auth/ecc/src/ecdsa.js#L94-L95)
488
+ - [src/auth/index.js](file://src/auth/index.js#L56-L63)