@owlmeans/basic-keys 0.1.0
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/LICENSE +21 -0
- package/README.md +474 -0
- package/build/.gitkeep +0 -0
- package/build/auth.d.ts +5 -0
- package/build/auth.d.ts.map +1 -0
- package/build/auth.js +45 -0
- package/build/auth.js.map +1 -0
- package/build/bin.d.ts +2 -0
- package/build/bin.d.ts.map +1 -0
- package/build/bin.js +9 -0
- package/build/bin.js.map +1 -0
- package/build/consts.d.ts +5 -0
- package/build/consts.d.ts.map +1 -0
- package/build/consts.js +6 -0
- package/build/consts.js.map +1 -0
- package/build/helper.d.ts +4 -0
- package/build/helper.d.ts.map +1 -0
- package/build/helper.js +22 -0
- package/build/helper.js.map +1 -0
- package/build/index.d.ts +8 -0
- package/build/index.d.ts.map +1 -0
- package/build/index.js +7 -0
- package/build/index.js.map +1 -0
- package/build/keypair.d.ts +3 -0
- package/build/keypair.d.ts.map +1 -0
- package/build/keypair.js +46 -0
- package/build/keypair.js.map +1 -0
- package/build/model.d.ts +3 -0
- package/build/model.d.ts.map +1 -0
- package/build/model.js +70 -0
- package/build/model.js.map +1 -0
- package/build/plugins/ed25519.d.ts +3 -0
- package/build/plugins/ed25519.d.ts.map +1 -0
- package/build/plugins/ed25519.js +15 -0
- package/build/plugins/ed25519.js.map +1 -0
- package/build/plugins/export.d.ts +5 -0
- package/build/plugins/export.d.ts.map +1 -0
- package/build/plugins/export.js +4 -0
- package/build/plugins/export.js.map +1 -0
- package/build/plugins/index.d.ts +3 -0
- package/build/plugins/index.d.ts.map +1 -0
- package/build/plugins/index.js +6 -0
- package/build/plugins/index.js.map +1 -0
- package/build/plugins/types.d.ts +13 -0
- package/build/plugins/types.d.ts.map +1 -0
- package/build/plugins/types.js +2 -0
- package/build/plugins/types.js.map +1 -0
- package/build/plugins/xchacha.d.ts +3 -0
- package/build/plugins/xchacha.d.ts.map +1 -0
- package/build/plugins/xchacha.js +14 -0
- package/build/plugins/xchacha.js.map +1 -0
- package/build/types.d.ts +35 -0
- package/build/types.d.ts.map +1 -0
- package/build/types.js +2 -0
- package/build/types.js.map +1 -0
- package/build/utils.d.ts +5 -0
- package/build/utils.d.ts.map +1 -0
- package/build/utils.js +29 -0
- package/build/utils.js.map +1 -0
- package/package.json +56 -0
- package/src/auth.ts +60 -0
- package/src/bin.ts +13 -0
- package/src/consts.ts +5 -0
- package/src/helper.ts +27 -0
- package/src/index.ts +8 -0
- package/src/keypair.ts +44 -0
- package/src/model.ts +113 -0
- package/src/plugins/ed25519.ts +23 -0
- package/src/plugins/export.ts +5 -0
- package/src/plugins/index.ts +8 -0
- package/src/plugins/types.ts +13 -0
- package/src/plugins/xchacha.ts +23 -0
- package/src/types.ts +41 -0
- package/src/utils.ts +35 -0
- package/tsconfig.json +14 -0
- package/tsconfig.tsbuildinfo +1 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 OwlMeans Common — Fullstack typescript framework
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,474 @@
|
|
|
1
|
+
# @owlmeans/basic-keys
|
|
2
|
+
|
|
3
|
+
A core cryptographic library for the OwlMeans Common ecosystem, providing key pair generation, digital signing, encryption, and authentication credential management.
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
The `@owlmeans/basic-keys` package implements the core cryptographic subsystem used primarily by the OwlMeans Authentication Subsystem. It provides a unified API for working with different cryptographic algorithms through an extensible plugin system.
|
|
8
|
+
|
|
9
|
+
## Features
|
|
10
|
+
|
|
11
|
+
- **Key Pair Management**: Generate, import, and export cryptographic key pairs
|
|
12
|
+
- **Digital Signatures**: Sign and verify data with ED25519
|
|
13
|
+
- **Encryption**: Encrypt and decrypt data with XChaCha20-Poly1305
|
|
14
|
+
- **Authentication**: Pack and unpack authentication credentials
|
|
15
|
+
- **Plugin System**: Extensible architecture for different cryptographic algorithms
|
|
16
|
+
- **CLI Tool**: Command-line interface for key generation
|
|
17
|
+
- **Multiple Export Formats**: Support for various key export formats
|
|
18
|
+
|
|
19
|
+
## Supported Algorithms
|
|
20
|
+
|
|
21
|
+
- **ED25519**: Digital signatures and key derivation
|
|
22
|
+
- **XChaCha20-Poly1305**: Symmetric encryption and decryption
|
|
23
|
+
|
|
24
|
+
## Installation
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
npm install @owlmeans/basic-keys
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Available Exports
|
|
31
|
+
|
|
32
|
+
The package provides three main export paths:
|
|
33
|
+
|
|
34
|
+
```typescript
|
|
35
|
+
// Main exports - core functionality
|
|
36
|
+
import { makeKeyPairModel, KeyType, fromPubKey, matchAddress, inputToKeyPair, packAuthCredentials, unpackAuthCredentials } from '@owlmeans/basic-keys'
|
|
37
|
+
|
|
38
|
+
// Plugin exports - cryptographic algorithm implementations
|
|
39
|
+
import { plugins, ed25519Plugin, xChahaPlugin, KeyPlugin } from '@owlmeans/basic-keys/plugins'
|
|
40
|
+
|
|
41
|
+
// Utility exports - low-level helper functions
|
|
42
|
+
import { prepareData, prepareKey, toAddress, assertType } from '@owlmeans/basic-keys/utils'
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## Quick Start
|
|
46
|
+
|
|
47
|
+
```typescript
|
|
48
|
+
import { makeKeyPairModel, KeyType } from '@owlmeans/basic-keys'
|
|
49
|
+
|
|
50
|
+
// Generate a new ED25519 key pair
|
|
51
|
+
const keyPair = makeKeyPairModel()
|
|
52
|
+
|
|
53
|
+
// Sign data
|
|
54
|
+
const signature = await keyPair.sign("Hello, World!")
|
|
55
|
+
|
|
56
|
+
// Verify signature
|
|
57
|
+
const isValid = await keyPair.verify("Hello, World!", signature)
|
|
58
|
+
|
|
59
|
+
// Export keys
|
|
60
|
+
const privateKey = keyPair.export() // "ed25519:base64privatekey"
|
|
61
|
+
const publicKey = keyPair.exportPublic() // "ed25519:base64publickey"
|
|
62
|
+
const address = keyPair.exportAddress() // "ed25519:base58address"
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## API Reference
|
|
66
|
+
|
|
67
|
+
### Core Types
|
|
68
|
+
|
|
69
|
+
#### KeyPair
|
|
70
|
+
|
|
71
|
+
Represents a cryptographic key pair with metadata.
|
|
72
|
+
|
|
73
|
+
```typescript
|
|
74
|
+
interface KeyPair {
|
|
75
|
+
privateKey: string // Base64-encoded private key
|
|
76
|
+
publicKey: string // Base64-encoded public key
|
|
77
|
+
address: string // Algorithm-specific address
|
|
78
|
+
type: string // Algorithm type (e.g., "ed25519", "xchacha")
|
|
79
|
+
}
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
#### KeyPairModel
|
|
83
|
+
|
|
84
|
+
A model object that wraps a KeyPair with cryptographic operations.
|
|
85
|
+
|
|
86
|
+
```typescript
|
|
87
|
+
interface KeyPairModel {
|
|
88
|
+
keyPair?: KeyPair
|
|
89
|
+
sign: (data: unknown) => Promise<string>
|
|
90
|
+
verify: (data: unknown, signature: string) => Promise<boolean>
|
|
91
|
+
export: () => string
|
|
92
|
+
exportPublic: () => string
|
|
93
|
+
exportAddress: () => string
|
|
94
|
+
encrypt: (data: unknown) => Promise<string>
|
|
95
|
+
decrypt: (data: unknown) => Promise<string>
|
|
96
|
+
dcrpt: (data: unknown) => Promise<Uint8Array>
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
### Key Functions
|
|
101
|
+
|
|
102
|
+
#### makeKeyPairModel(input?)
|
|
103
|
+
|
|
104
|
+
Creates a KeyPairModel instance.
|
|
105
|
+
|
|
106
|
+
```typescript
|
|
107
|
+
function makeKeyPairModel(input?: KeyPair | string): KeyPairModel
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
**Parameters:**
|
|
111
|
+
- `input` (optional):
|
|
112
|
+
- `KeyPair` object
|
|
113
|
+
- Algorithm type string (e.g., "ed25519", "xchacha")
|
|
114
|
+
- Encoded private key string (e.g., "ed25519:base64key")
|
|
115
|
+
|
|
116
|
+
**Returns:** `KeyPairModel` instance
|
|
117
|
+
|
|
118
|
+
**Examples:**
|
|
119
|
+
|
|
120
|
+
```typescript
|
|
121
|
+
// Generate new ED25519 key pair
|
|
122
|
+
const keyPair1 = makeKeyPairModel()
|
|
123
|
+
|
|
124
|
+
// Generate new XChaCha20 key pair
|
|
125
|
+
const keyPair2 = makeKeyPairModel(KeyType.XCHACHA)
|
|
126
|
+
|
|
127
|
+
// Import from private key
|
|
128
|
+
const keyPair3 = makeKeyPairModel("ed25519:abcd1234...")
|
|
129
|
+
|
|
130
|
+
// Import from KeyPair object
|
|
131
|
+
const keyPair4 = makeKeyPairModel({
|
|
132
|
+
privateKey: "abcd1234...",
|
|
133
|
+
publicKey: "efgh5678...",
|
|
134
|
+
address: "ijkl9012...",
|
|
135
|
+
type: "ed25519"
|
|
136
|
+
})
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
#### fromPubKey(pubKey, type?)
|
|
140
|
+
|
|
141
|
+
Creates a KeyPairModel from a public key (verification/encryption only).
|
|
142
|
+
|
|
143
|
+
```typescript
|
|
144
|
+
function fromPubKey(pubKey: string, type?: string): KeyPairModel
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
**Parameters:**
|
|
148
|
+
- `pubKey`: Public key string (with or without type prefix)
|
|
149
|
+
- `type` (optional): Algorithm type if not included in pubKey
|
|
150
|
+
|
|
151
|
+
**Returns:** `KeyPairModel` instance (without private key operations)
|
|
152
|
+
|
|
153
|
+
**Examples:**
|
|
154
|
+
|
|
155
|
+
```typescript
|
|
156
|
+
// With type prefix
|
|
157
|
+
const publicKeyModel = fromPubKey("ed25519:abcd1234...")
|
|
158
|
+
|
|
159
|
+
// Without type prefix (defaults to ED25519)
|
|
160
|
+
const publicKeyModel2 = fromPubKey("abcd1234...")
|
|
161
|
+
|
|
162
|
+
// Explicit type
|
|
163
|
+
const publicKeyModel3 = fromPubKey("abcd1234...", KeyType.ED25519)
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
#### matchAddress(address, pubKey)
|
|
167
|
+
|
|
168
|
+
Verifies if a public key matches an address.
|
|
169
|
+
|
|
170
|
+
```typescript
|
|
171
|
+
function matchAddress(address: string, pubKey: string): boolean
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
**Parameters:**
|
|
175
|
+
- `address`: Address string to verify
|
|
176
|
+
- `pubKey`: Public key string
|
|
177
|
+
|
|
178
|
+
**Returns:** `boolean` - true if the public key matches the address
|
|
179
|
+
|
|
180
|
+
#### inputToKeyPair(input?)
|
|
181
|
+
|
|
182
|
+
Converts various input formats to a KeyPair object.
|
|
183
|
+
|
|
184
|
+
```typescript
|
|
185
|
+
function inputToKeyPair(input?: KeyPair | string): KeyPair
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
**Parameters:**
|
|
189
|
+
- `input` (optional):
|
|
190
|
+
- `KeyPair` object
|
|
191
|
+
- Algorithm type string (generates new key)
|
|
192
|
+
- Encoded private key string (e.g., "ed25519:base64key")
|
|
193
|
+
|
|
194
|
+
**Returns:** `KeyPair` object
|
|
195
|
+
|
|
196
|
+
**Examples:**
|
|
197
|
+
|
|
198
|
+
```typescript
|
|
199
|
+
// Generate new ED25519 key pair
|
|
200
|
+
const keyPair1 = inputToKeyPair()
|
|
201
|
+
|
|
202
|
+
// Generate new XChaCha20 key pair
|
|
203
|
+
const keyPair2 = inputToKeyPair(KeyType.XCHACHA)
|
|
204
|
+
|
|
205
|
+
// Import from private key
|
|
206
|
+
const keyPair3 = inputToKeyPair("ed25519:abcd1234...")
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
### Authentication Helpers
|
|
210
|
+
|
|
211
|
+
#### packAuthCredentials(auth, extra, signer)
|
|
212
|
+
|
|
213
|
+
Packs authentication credentials with a signature.
|
|
214
|
+
|
|
215
|
+
```typescript
|
|
216
|
+
function packAuthCredentials<T>(
|
|
217
|
+
auth: UnsignedAuthCredentials,
|
|
218
|
+
extra: T,
|
|
219
|
+
signer: KeyPairModel | PayloadSigner
|
|
220
|
+
): Promise<AuthCredentials>
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
**Parameters:**
|
|
224
|
+
- `auth`: Unsigned authentication credentials
|
|
225
|
+
- `extra`: Additional data to include in credentials
|
|
226
|
+
- `signer`: KeyPairModel or custom signing function
|
|
227
|
+
|
|
228
|
+
**Returns:** Promise resolving to signed `AuthCredentials`
|
|
229
|
+
|
|
230
|
+
#### unpackAuthCredentials(auth, verifier?)
|
|
231
|
+
|
|
232
|
+
Unpacks and optionally verifies authentication credentials.
|
|
233
|
+
|
|
234
|
+
```typescript
|
|
235
|
+
function unpackAuthCredentials<T>(
|
|
236
|
+
auth: AuthCredentials,
|
|
237
|
+
verifier?: KeyPairModel | PayloadVerifier
|
|
238
|
+
): Promise<UnpackedAuthCredentials<T>>
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
**Parameters:**
|
|
242
|
+
- `auth`: Signed authentication credentials
|
|
243
|
+
- `verifier` (optional): KeyPairModel or custom verification function
|
|
244
|
+
|
|
245
|
+
**Returns:** Promise resolving to `UnpackedAuthCredentials<T>`
|
|
246
|
+
|
|
247
|
+
### Constants
|
|
248
|
+
|
|
249
|
+
#### KeyType
|
|
250
|
+
|
|
251
|
+
Enumeration of supported cryptographic algorithm types.
|
|
252
|
+
|
|
253
|
+
```typescript
|
|
254
|
+
enum KeyType {
|
|
255
|
+
ED25519 = 'ed25519',
|
|
256
|
+
XCHACHA = 'xchacha'
|
|
257
|
+
}
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
### Utility Functions
|
|
261
|
+
|
|
262
|
+
#### toAddress(publicKey)
|
|
263
|
+
|
|
264
|
+
Converts a public key to its corresponding address.
|
|
265
|
+
|
|
266
|
+
```typescript
|
|
267
|
+
function toAddress(publicKey: Uint8Array): Uint8Array
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
**Parameters:**
|
|
271
|
+
- `publicKey`: Public key as Uint8Array
|
|
272
|
+
|
|
273
|
+
**Returns:** `Uint8Array` - Address bytes (last 20 bytes of Keccak-256 hash)
|
|
274
|
+
|
|
275
|
+
#### prepareData(data)
|
|
276
|
+
|
|
277
|
+
Converts various data types to Uint8Array for cryptographic operations.
|
|
278
|
+
|
|
279
|
+
```typescript
|
|
280
|
+
function prepareData(data: unknown): Uint8Array
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
#### prepareKey(key)
|
|
284
|
+
|
|
285
|
+
Converts a base64-encoded key string to Uint8Array.
|
|
286
|
+
|
|
287
|
+
```typescript
|
|
288
|
+
function prepareKey(key: string): Uint8Array
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
#### assertType(type?)
|
|
292
|
+
|
|
293
|
+
Validates that a cryptographic algorithm type is supported.
|
|
294
|
+
|
|
295
|
+
```typescript
|
|
296
|
+
function assertType(type?: string): void
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
## Plugin System
|
|
300
|
+
|
|
301
|
+
The library uses a plugin architecture to support different cryptographic algorithms. Each plugin implements the `KeyPlugin` interface:
|
|
302
|
+
|
|
303
|
+
```typescript
|
|
304
|
+
interface KeyPlugin {
|
|
305
|
+
type: string
|
|
306
|
+
random: () => Uint8Array
|
|
307
|
+
fromSeed?: (seed: Uint8Array) => Uint8Array
|
|
308
|
+
derive?: (pk: Uint8Array, path: string) => Uint8Array
|
|
309
|
+
sign: (data: Uint8Array, pk: Uint8Array) => Uint8Array
|
|
310
|
+
verify: (data: Uint8Array, signature: Uint8Array, pub: Uint8Array) => boolean
|
|
311
|
+
toPublic: (pk: Uint8Array) => Uint8Array
|
|
312
|
+
toAdress: (pub: Uint8Array) => string
|
|
313
|
+
encrypt: (data: Uint8Array, pk: Uint8Array) => Uint8Array
|
|
314
|
+
decrypt: (data: Uint8Array, pk: Uint8Array) => Uint8Array
|
|
315
|
+
}
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
### Built-in Plugins
|
|
319
|
+
|
|
320
|
+
#### ED25519 Plugin
|
|
321
|
+
|
|
322
|
+
- **Type**: `ed25519`
|
|
323
|
+
- **Capabilities**: Digital signatures, key derivation
|
|
324
|
+
- **Address Format**: Base58-encoded Keccak-256 hash
|
|
325
|
+
- **Encryption**: Not supported (throws error)
|
|
326
|
+
|
|
327
|
+
#### XChaCha20-Poly1305 Plugin
|
|
328
|
+
|
|
329
|
+
- **Type**: `xchacha`
|
|
330
|
+
- **Capabilities**: Symmetric encryption and decryption
|
|
331
|
+
- **Address Format**: "no-address" (not applicable)
|
|
332
|
+
- **Signing**: Not supported (throws error)
|
|
333
|
+
|
|
334
|
+
### Using Plugins
|
|
335
|
+
|
|
336
|
+
```typescript
|
|
337
|
+
import { plugins } from '@owlmeans/basic-keys/plugins'
|
|
338
|
+
// Or import individual plugins
|
|
339
|
+
import { ed25519Plugin, xChahaPlugin } from '@owlmeans/basic-keys/plugins'
|
|
340
|
+
|
|
341
|
+
// Access plugin directly
|
|
342
|
+
const ed25519Plugin = plugins['ed25519']
|
|
343
|
+
|
|
344
|
+
// Generate random private key
|
|
345
|
+
const privateKey = ed25519Plugin.random()
|
|
346
|
+
|
|
347
|
+
// Convert to public key
|
|
348
|
+
const publicKey = ed25519Plugin.toPublic(privateKey)
|
|
349
|
+
|
|
350
|
+
// Sign data
|
|
351
|
+
const signature = ed25519Plugin.sign(data, privateKey)
|
|
352
|
+
|
|
353
|
+
// Verify signature
|
|
354
|
+
const isValid = ed25519Plugin.verify(data, signature, publicKey)
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
## CLI Tool
|
|
358
|
+
|
|
359
|
+
The package includes a command-line tool for key generation:
|
|
360
|
+
|
|
361
|
+
```bash
|
|
362
|
+
# Generate keys
|
|
363
|
+
npx owlkeys
|
|
364
|
+
|
|
365
|
+
# Or if installed globally
|
|
366
|
+
owlkeys
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
The CLI tool generates and displays:
|
|
370
|
+
- ED25519 private key export
|
|
371
|
+
- ED25519 public key export
|
|
372
|
+
- ED25519 address (DID format)
|
|
373
|
+
- XChaCha20 key export
|
|
374
|
+
|
|
375
|
+
## Advanced Usage
|
|
376
|
+
|
|
377
|
+
### Custom Signing and Verification
|
|
378
|
+
|
|
379
|
+
```typescript
|
|
380
|
+
import type { PayloadSigner, PayloadVerifier } from '@owlmeans/basic-keys'
|
|
381
|
+
|
|
382
|
+
// Custom signer function
|
|
383
|
+
const customSigner: PayloadSigner = async (payload) => {
|
|
384
|
+
// Custom signing logic
|
|
385
|
+
return signature
|
|
386
|
+
}
|
|
387
|
+
|
|
388
|
+
// Custom verifier function
|
|
389
|
+
const customVerifier: PayloadVerifier = async (payload, signature) => {
|
|
390
|
+
// Custom verification logic
|
|
391
|
+
return isValid
|
|
392
|
+
}
|
|
393
|
+
|
|
394
|
+
// Use with authentication helpers
|
|
395
|
+
const credentials = await packAuthCredentials(auth, extra, customSigner)
|
|
396
|
+
const unpacked = await unpackAuthCredentials(credentials, customVerifier)
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
### Working with Raw Data
|
|
400
|
+
|
|
401
|
+
```typescript
|
|
402
|
+
import { prepareData, prepareKey, toAddress, assertType } from '@owlmeans/basic-keys/utils'
|
|
403
|
+
|
|
404
|
+
// Prepare various data types for cryptographic operations
|
|
405
|
+
const data1 = prepareData("string data") // UTF-8 encoded
|
|
406
|
+
const data2 = prepareData({ key: "value" }) // JSON canonicalized
|
|
407
|
+
const data3 = prepareData(new Uint8Array([1, 2])) // As-is
|
|
408
|
+
|
|
409
|
+
// Prepare keys
|
|
410
|
+
const keyBytes = prepareKey("base64KeyString")
|
|
411
|
+
|
|
412
|
+
// Generate address from public key
|
|
413
|
+
const address = toAddress(publicKeyBytes)
|
|
414
|
+
|
|
415
|
+
// Assert algorithm type is supported
|
|
416
|
+
assertType("ed25519") // No error
|
|
417
|
+
assertType("unknown") // Throws error
|
|
418
|
+
```
|
|
419
|
+
|
|
420
|
+
### Encryption and Decryption
|
|
421
|
+
|
|
422
|
+
```typescript
|
|
423
|
+
// For encryption, use XChaCha20 keys
|
|
424
|
+
const encryptionKey = makeKeyPairModel(KeyType.XCHACHA)
|
|
425
|
+
|
|
426
|
+
// Encrypt data
|
|
427
|
+
const encrypted = await encryptionKey.encrypt("sensitive data")
|
|
428
|
+
|
|
429
|
+
// Decrypt data
|
|
430
|
+
const decrypted = await encryptionKey.decrypt(encrypted)
|
|
431
|
+
|
|
432
|
+
// Decrypt to raw bytes
|
|
433
|
+
const rawBytes = await encryptionKey.dcrpt(encrypted)
|
|
434
|
+
```
|
|
435
|
+
|
|
436
|
+
## Error Handling
|
|
437
|
+
|
|
438
|
+
The library throws descriptive errors for various failure conditions:
|
|
439
|
+
|
|
440
|
+
- `basic.keys:string-type-or-key` - Invalid key string format
|
|
441
|
+
- `basic.keys:missing-keypair` - KeyPair not available
|
|
442
|
+
- `basic.keys:missing-pk` - Private key not available
|
|
443
|
+
- `basic.keys:sign-data-type` - Invalid data type for signing
|
|
444
|
+
- `basic.keys:unknown-type` - Unsupported algorithm type
|
|
445
|
+
- `ed25519:encryption-support` - ED25519 doesn't support encryption
|
|
446
|
+
- `xchacha:signing` - XChaCha20 doesn't support signing
|
|
447
|
+
- `xchacha:verification` - XChaCha20 doesn't support verification
|
|
448
|
+
|
|
449
|
+
## Integration with OwlMeans Common
|
|
450
|
+
|
|
451
|
+
This package is designed to integrate seamlessly with other OwlMeans Common libraries:
|
|
452
|
+
|
|
453
|
+
- **@owlmeans/auth**: Authentication and authorization
|
|
454
|
+
- **@owlmeans/client-auth**: Client-side authentication
|
|
455
|
+
- **@owlmeans/server-auth**: Server-side authentication
|
|
456
|
+
|
|
457
|
+
## TypeScript Support
|
|
458
|
+
|
|
459
|
+
The library is written in TypeScript and provides comprehensive type definitions. All exports are properly typed for optimal developer experience.
|
|
460
|
+
|
|
461
|
+
## Security Considerations
|
|
462
|
+
|
|
463
|
+
- Private keys are stored as base64-encoded strings
|
|
464
|
+
- All cryptographic operations use well-established libraries (@noble/curves, @noble/ciphers)
|
|
465
|
+
- Data is canonicalized before signing to prevent signature malleability
|
|
466
|
+
- Key generation uses cryptographically secure random number generation
|
|
467
|
+
|
|
468
|
+
## Contributing
|
|
469
|
+
|
|
470
|
+
This package is part of the OwlMeans Common ecosystem. Please refer to the main repository for contribution guidelines.
|
|
471
|
+
|
|
472
|
+
## License
|
|
473
|
+
|
|
474
|
+
See the LICENSE file in the repository root for license information.
|
package/build/.gitkeep
ADDED
|
File without changes
|
package/build/auth.d.ts
ADDED
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import type { AuthCredentials } from '@owlmeans/auth';
|
|
2
|
+
import type { KeyPairModel, PayloadSigner, PayloadVerifier, UnpackedAuthCredentials, UnsignedAuthCredentials } from './types.js';
|
|
3
|
+
export declare const packAuthCredentials: <T extends {} | undefined>(auth: UnsignedAuthCredentials, extra: T, signer: KeyPairModel | PayloadSigner) => Promise<AuthCredentials>;
|
|
4
|
+
export declare const unpackAuthCredentials: <T extends {} | undefined>(auth: AuthCredentials, verifier?: KeyPairModel | PayloadVerifier) => Promise<UnpackedAuthCredentials<T>>;
|
|
5
|
+
//# sourceMappingURL=auth.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AAGhI,eAAO,MAAM,mBAAmB,GAAU,CAAC,SAAS,EAAE,GAAG,SAAS,QAC1D,uBAAuB,SACtB,CAAC,UACA,YAAY,GAAG,aAAa,KACnC,OAAO,CAAC,eAAe,CAiBzB,CAAA;AAED,eAAO,MAAM,qBAAqB,GAAU,CAAC,SAAS,EAAE,GAAG,SAAS,QAC5D,eAAe,aACV,YAAY,GAAG,eAAe,KACxC,OAAO,CAAC,uBAAuB,CAAC,CAAC,CAAC,CA6BpC,CAAA"}
|
package/build/auth.js
ADDED
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import canonicalize from 'canonicalize';
|
|
2
|
+
export const packAuthCredentials = async (auth, extra, signer) => {
|
|
3
|
+
const unsigned = {
|
|
4
|
+
...auth,
|
|
5
|
+
...(extra == null ? {} : { credential: canonicalize(extra) })
|
|
6
|
+
};
|
|
7
|
+
if (typeof signer !== 'function') {
|
|
8
|
+
const _signer = signer;
|
|
9
|
+
signer = async (payload) => await _signer.sign(payload);
|
|
10
|
+
}
|
|
11
|
+
const signature = await signer(unsigned);
|
|
12
|
+
return {
|
|
13
|
+
...auth,
|
|
14
|
+
credential: extra == null ? signature : canonicalize({ ...extra, signature }),
|
|
15
|
+
};
|
|
16
|
+
};
|
|
17
|
+
export const unpackAuthCredentials = async (auth, verifier) => {
|
|
18
|
+
let signature = '';
|
|
19
|
+
let extras;
|
|
20
|
+
try {
|
|
21
|
+
extras = JSON.parse(auth.credential);
|
|
22
|
+
if (typeof extras === 'object' && extras != null && "signature" in extras) {
|
|
23
|
+
signature = extras.signature;
|
|
24
|
+
delete extras.signature;
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
catch {
|
|
28
|
+
signature = auth.credential;
|
|
29
|
+
extras = undefined;
|
|
30
|
+
}
|
|
31
|
+
const unsigned = {
|
|
32
|
+
...auth,
|
|
33
|
+
...(extras == null ? {} : { credential: canonicalize(extras) })
|
|
34
|
+
};
|
|
35
|
+
let isValid = undefined;
|
|
36
|
+
if (verifier != null) {
|
|
37
|
+
if (typeof verifier !== 'function') {
|
|
38
|
+
const _verifier = verifier;
|
|
39
|
+
verifier = async (payload, signature) => await _verifier.verify(payload, signature);
|
|
40
|
+
}
|
|
41
|
+
isValid = await verifier(unsigned, signature);
|
|
42
|
+
}
|
|
43
|
+
return { unsigned, signature, isValid, extras };
|
|
44
|
+
};
|
|
45
|
+
//# sourceMappingURL=auth.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAEA,OAAO,YAAY,MAAM,cAAc,CAAA;AAEvC,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,EACtC,IAA6B,EAC7B,KAAQ,EACR,MAAoC,EACV,EAAE;IAC5B,MAAM,QAAQ,GAA4B;QACxC,GAAG,IAAI;QACP,GAAG,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,YAAY,CAAC,KAAK,CAAW,EAAE,CAAC;KACxE,CAAA;IAED,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;QACjC,MAAM,OAAO,GAAG,MAAM,CAAA;QACtB,MAAM,GAAG,KAAK,EAAC,OAAO,EAAC,EAAE,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IACvD,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAA;IAExC,OAAO;QACL,GAAG,IAAI;QACP,UAAU,EAAE,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,GAAG,KAAK,EAAE,SAAS,EAAE,CAAW;KACxF,CAAA;AACH,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,EACxC,IAAqB,EACrB,QAAyC,EACJ,EAAE;IACvC,IAAI,SAAS,GAAW,EAAE,CAAA;IAC1B,IAAI,MAAS,CAAA;IACb,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;QACpC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,IAAI,IAAI,IAAI,WAAW,IAAI,MAAM,EAAE,CAAC;YAC1E,SAAS,GAAG,MAAM,CAAC,SAAmB,CAAA;YACtC,OAAO,MAAM,CAAC,SAAS,CAAA;QACzB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,SAAS,GAAG,IAAI,CAAC,UAAU,CAAA;QAC3B,MAAM,GAAG,SAAc,CAAA;IACzB,CAAC;IACD,MAAM,QAAQ,GAA4B;QACxC,GAAG,IAAI;QACP,GAAG,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,YAAY,CAAC,MAAM,CAAW,EAAE,CAAC;KAC1E,CAAA;IACD,IAAI,OAAO,GAAwB,SAAS,CAAA;IAE5C,IAAI,QAAQ,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE,CAAC;YACnC,MAAM,SAAS,GAAG,QAAQ,CAAA;YAC1B,QAAQ,GAAG,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,CAAC,MAAM,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,CAAA;QACrF,CAAC;QAED,OAAO,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAA;IAC/C,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,CAAA;AACjD,CAAC,CAAA"}
|
package/build/bin.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}
|
package/build/bin.js
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import { KeyType } from './consts.js';
|
|
2
|
+
import { makeKeyPairModel } from './model.js';
|
|
3
|
+
const keyPair = makeKeyPairModel();
|
|
4
|
+
console.info('Private export: ', keyPair.export());
|
|
5
|
+
console.info('Public export: ', keyPair.exportPublic());
|
|
6
|
+
console.info('DID export: ', keyPair.exportAddress());
|
|
7
|
+
const xChachaKey = makeKeyPairModel(KeyType.XCHACHA);
|
|
8
|
+
console.info('XChaha key export: ', xChachaKey.export());
|
|
9
|
+
//# sourceMappingURL=bin.js.map
|
package/build/bin.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AACrC,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAE7C,MAAM,OAAO,GAAG,gBAAgB,EAAE,CAAA;AAElC,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;AAClD,OAAO,CAAC,IAAI,CAAC,iBAAiB,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC,CAAA;AACvD,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC,CAAA;AAGrD,MAAM,UAAU,GAAG,gBAAgB,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;AACpD,OAAO,CAAC,IAAI,CAAC,qBAAqB,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAA"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,oBAAY,OAAO;IACjB,OAAO,YAAY;IACnB,OAAO,YAAY;CACpB"}
|
package/build/consts.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,MAAM,CAAN,IAAY,OAGX;AAHD,WAAY,OAAO;IACjB,8BAAmB,CAAA;IACnB,8BAAmB,CAAA;AACrB,CAAC,EAHW,OAAO,KAAP,OAAO,QAGlB"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAW,YAAY,EAAE,MAAM,YAAY,CAAA;AAGvD,eAAO,MAAM,UAAU,WAAY,MAAM,SAAS,MAAM,KAAG,YAiB1D,CAAA;AAED,eAAO,MAAM,YAAY,YAAa,MAAM,UAAU,MAAM,KAAG,OACf,CAAA"}
|
package/build/helper.js
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { KeyType } from './consts.js';
|
|
2
|
+
import { makeKeyPairModel } from './model.js';
|
|
3
|
+
import { plugins } from './plugins/index.js';
|
|
4
|
+
import { prepareKey } from './utils.js';
|
|
5
|
+
export const fromPubKey = (pubKey, type) => {
|
|
6
|
+
if (type == null) {
|
|
7
|
+
[type, pubKey] = pubKey.includes(':') ? pubKey.split(':', 2) : [KeyType.ED25519, pubKey];
|
|
8
|
+
if (pubKey == null) {
|
|
9
|
+
pubKey = type;
|
|
10
|
+
type = KeyType.ED25519;
|
|
11
|
+
}
|
|
12
|
+
}
|
|
13
|
+
const keyPair = {
|
|
14
|
+
privateKey: '',
|
|
15
|
+
publicKey: pubKey,
|
|
16
|
+
type,
|
|
17
|
+
address: plugins[type].toAdress(prepareKey(pubKey))
|
|
18
|
+
};
|
|
19
|
+
return makeKeyPairModel(keyPair);
|
|
20
|
+
};
|
|
21
|
+
export const matchAddress = (address, pubKey) => address === fromPubKey(pubKey).exportAddress();
|
|
22
|
+
//# sourceMappingURL=helper.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"helper.js","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AACrC,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAA;AAE5C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAEvC,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,MAAc,EAAE,IAAa,EAAgB,EAAE;IACxE,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;QACjB,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;QACxF,IAAI,MAAM,IAAI,IAAI,EAAE,CAAC;YACnB,MAAM,GAAG,IAAI,CAAA;YACb,IAAI,GAAG,OAAO,CAAC,OAAO,CAAA;QACxB,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAY;QACvB,UAAU,EAAE,EAAE;QACd,SAAS,EAAE,MAAM;QACjB,IAAI;QACJ,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;KACpD,CAAA;IAED,OAAO,gBAAgB,CAAC,OAAO,CAAC,CAAA;AAClC,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,OAAe,EAAE,MAAc,EAAW,EAAE,CACvE,OAAO,KAAK,UAAU,CAAC,MAAM,CAAC,CAAC,aAAa,EAAE,CAAA"}
|
package/build/index.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAE/B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,oBAAoB,CAAA"}
|
package/build/index.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,oBAAoB,CAAA"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"keypair.d.ts","sourceRoot":"","sources":["../src/keypair.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAMzC,eAAO,MAAM,cAAc,WAAY,OAAO,GAAG,MAAM,KAAG,OAqCzD,CAAA"}
|