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.
- package/.qoder/docs/spec/viz-dns-nameserver-spec.md +982 -0
- package/.qoder/docs/viz-cpp-node-docs/data-types.md +322 -0
- package/.qoder/docs/viz-cpp-node-docs/index.md +160 -0
- package/.qoder/docs/viz-cpp-node-docs/op-account-market.md +236 -0
- package/.qoder/docs/viz-cpp-node-docs/op-account.md +199 -0
- package/.qoder/docs/viz-cpp-node-docs/op-award.md +162 -0
- package/.qoder/docs/viz-cpp-node-docs/op-committee.md +193 -0
- package/.qoder/docs/viz-cpp-node-docs/op-content.md +157 -0
- package/.qoder/docs/viz-cpp-node-docs/op-escrow.md +224 -0
- package/.qoder/docs/viz-cpp-node-docs/op-invite.md +219 -0
- package/.qoder/docs/viz-cpp-node-docs/op-proposal.md +229 -0
- package/.qoder/docs/viz-cpp-node-docs/op-recovery.md +188 -0
- package/.qoder/docs/viz-cpp-node-docs/op-subscription.md +146 -0
- package/.qoder/docs/viz-cpp-node-docs/op-transfer-vesting.md +224 -0
- package/.qoder/docs/viz-cpp-node-docs/op-witness.md +252 -0
- package/.qoder/docs/viz-cpp-node-docs/plugins.md +887 -0
- package/.qoder/docs/viz-cpp-node-docs/virtual-operations.md +513 -0
- package/.qoder/repowiki/en/content/API Reference/API Reference.md +724 -0
- package/.qoder/repowiki/en/content/API Reference/Configuration Options.md +410 -0
- package/.qoder/repowiki/en/content/API Reference/Core API Methods.md +547 -0
- package/.qoder/repowiki/en/content/API Reference/Streaming APIs.md +380 -0
- package/.qoder/repowiki/en/content/API Reference/Transport Layer.md +341 -0
- package/.qoder/repowiki/en/content/API Reference/VIZ Blockchain Operations Coverage Status.md +427 -0
- package/.qoder/repowiki/en/content/Authentication & Cryptography/Authentication & Cryptography.md +430 -0
- package/.qoder/repowiki/en/content/Authentication & Cryptography/Digital Signatures.md +462 -0
- package/.qoder/repowiki/en/content/Authentication & Cryptography/Key Management.md +456 -0
- package/.qoder/repowiki/en/content/Authentication & Cryptography/Memo Encryption.md +331 -0
- package/.qoder/repowiki/en/content/Authentication & Cryptography/Security Practices.md +488 -0
- package/.qoder/repowiki/en/content/Broadcast Transactions/Broadcast Transactions.md +432 -0
- package/.qoder/repowiki/en/content/Broadcast Transactions/Network Broadcasting.md +418 -0
- package/.qoder/repowiki/en/content/Broadcast Transactions/Operation Construction.md +352 -0
- package/.qoder/repowiki/en/content/Broadcast Transactions/Transaction Preparation.md +353 -0
- package/.qoder/repowiki/en/content/Broadcast Transactions/Transaction Signing.md +404 -0
- package/.qoder/repowiki/en/content/Data Serialization/Data Serialization.md +540 -0
- package/.qoder/repowiki/en/content/Data Serialization/Encoding & Decoding.md +463 -0
- package/.qoder/repowiki/en/content/Data Serialization/Object Templates.md +413 -0
- package/.qoder/repowiki/en/content/Data Serialization/Type System.md +514 -0
- package/.qoder/repowiki/en/content/Data Serialization/Validation Rules.md +439 -0
- package/.qoder/repowiki/en/content/Examples & Tutorials.md +485 -0
- package/.qoder/repowiki/en/content/Getting Started.md +345 -0
- package/.qoder/repowiki/en/content/Testing & Development.md +637 -0
- package/.qoder/repowiki/en/content/Utilities & Helpers.md +557 -0
- package/.qoder/repowiki/en/meta/repowiki-metadata.json +1 -0
- package/VIZ-JS-LIB-COVERAGE-STATUS.md +356 -0
- package/config.json +3 -1
- package/dist/statistics.html +1 -1
- package/dist/viz-tests.min.js +32 -42
- package/dist/viz-tests.min.js.gz +0 -0
- package/dist/viz.min.js +8 -18
- package/dist/viz.min.js.gz +0 -0
- package/lib/api/methods.js +24 -0
- package/lib/auth/serializer/src/ChainTypes.js +2 -1
- package/lib/auth/serializer/src/operations.js +35 -2
- package/lib/broadcast/index.js +29 -15
- package/lib/broadcast/operations.js +4 -0
- package/lib/dns.js +658 -0
- package/lib/index.js +3 -1
- package/package.json +3 -2
- package/test/dns.test.js +395 -0
- 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)
|