@interop/bnid 6.0.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/CHANGELOG.md +88 -0
- package/LICENSE +27 -0
- package/README.md +329 -0
- package/dist/baseX.d.ts +2 -0
- package/dist/baseX.d.ts.map +1 -0
- package/dist/baseX.js +3 -0
- package/dist/baseX.js.map +1 -0
- package/dist/index.d.ts +192 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +450 -0
- package/dist/index.js.map +1 -0
- package/dist/util-browser.d.ts +4 -0
- package/dist/util-browser.d.ts.map +1 -0
- package/dist/util-browser.js +20 -0
- package/dist/util-browser.js.map +1 -0
- package/dist/util-reactnative.d.ts +4 -0
- package/dist/util-reactnative.d.ts.map +1 -0
- package/dist/util-reactnative.js +24 -0
- package/dist/util-reactnative.js.map +1 -0
- package/dist/util.d.ts +4 -0
- package/dist/util.d.ts.map +1 -0
- package/dist/util.js +14 -0
- package/dist/util.js.map +1 -0
- package/package.json +103 -0
- package/src/baseX.ts +3 -0
- package/src/index.ts +560 -0
- package/src/util-browser.ts +23 -0
- package/src/util-reactnative.ts +27 -0
- package/src/util.ts +17 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# bnid ChangeLog
|
|
2
|
+
|
|
3
|
+
## 6.0.0 - 2026-06-08
|
|
4
|
+
|
|
5
|
+
### Changed
|
|
6
|
+
|
|
7
|
+
- **BREAKING**: Fork to `@interop/bnid`.
|
|
8
|
+
- **BREAKING**: Replace `base-x` dependency with `@scure/base` (`base58`).
|
|
9
|
+
- **BREAKING**: React Native now uses the Web Crypto `crypto.getRandomValues()`
|
|
10
|
+
API instead of `react-native-securerandom`. Consumers must install the
|
|
11
|
+
`react-native-get-random-values` polyfill (declared as an optional
|
|
12
|
+
`peerDependency`) and import it once at their app entry. See the README.
|
|
13
|
+
|
|
14
|
+
### Removed
|
|
15
|
+
|
|
16
|
+
- Remove `react-native-securerandom` dependency.
|
|
17
|
+
|
|
18
|
+
## 5.0.0 - 2026-05-24
|
|
19
|
+
|
|
20
|
+
### Changed
|
|
21
|
+
|
|
22
|
+
- Bump `base-x` dependency to latest (v5.0.0).
|
|
23
|
+
|
|
24
|
+
## 4.0.0 - 2025-05-16
|
|
25
|
+
|
|
26
|
+
### Changed
|
|
27
|
+
|
|
28
|
+
- **BREAKING**: Convert to Typescript (still also exports Javascript).
|
|
29
|
+
|
|
30
|
+
## 3.0.1 - 2024-01-23
|
|
31
|
+
|
|
32
|
+
### Changed
|
|
33
|
+
|
|
34
|
+
- Replace `@digitalcredentials/base58-universal` with `base-x` dependency.
|
|
35
|
+
|
|
36
|
+
## 3.0.0 - 2024-01-23
|
|
37
|
+
|
|
38
|
+
### Removed
|
|
39
|
+
|
|
40
|
+
- **BREAKING**: Move command line client into
|
|
41
|
+
[`bnid-cli`](https://github.com/digitalbazaar/bnid-cli). The primary reason is
|
|
42
|
+
to reduce `bnid` dependencies.
|
|
43
|
+
|
|
44
|
+
## 2.1.2 - 2022-01-28
|
|
45
|
+
|
|
46
|
+
### Changed
|
|
47
|
+
|
|
48
|
+
- Fix Rollup config for React Native.
|
|
49
|
+
|
|
50
|
+
## 2.1.1 - 2022-01-26
|
|
51
|
+
|
|
52
|
+
### Changed
|
|
53
|
+
|
|
54
|
+
- Remove runtime `esm` transpiler usage, add support for Typescript and React
|
|
55
|
+
Native.
|
|
56
|
+
|
|
57
|
+
## 2.1.0 - 2021-11-18
|
|
58
|
+
|
|
59
|
+
### Added
|
|
60
|
+
|
|
61
|
+
- Add `generateSecretKeySeed()` and `decodeSecretKeySeed()`.
|
|
62
|
+
- Add `multihash` boolean parameter to IdEncoder and IdDecoder. A
|
|
63
|
+
multihash-encoded identifier will use the `identity` multicodec tag (`0x00`).
|
|
64
|
+
Using multihash has the advantage of including the size of the identifier
|
|
65
|
+
which can then be verified to have not changed when decoding.
|
|
66
|
+
- Add `expectedSize` optional parameter to IdDecoder for multihash-encoded ID
|
|
67
|
+
bytes. (default: 32).
|
|
68
|
+
|
|
69
|
+
## 2.0.0 - 2020-05-22
|
|
70
|
+
|
|
71
|
+
### Changed
|
|
72
|
+
|
|
73
|
+
- **BREAKING**: `multibase` now defaults to `true` for all APIs.
|
|
74
|
+
- Remove travis-ci testing in favor of GitHub Actions.
|
|
75
|
+
|
|
76
|
+
### Added
|
|
77
|
+
|
|
78
|
+
- Command line tool `bnid`.
|
|
79
|
+
- `min/maxEncodedIdBytes` utiltiies. Useful for variable length encodings such
|
|
80
|
+
as `base58`.
|
|
81
|
+
|
|
82
|
+
## 1.0.0 - 2020-05-07
|
|
83
|
+
|
|
84
|
+
### Added
|
|
85
|
+
|
|
86
|
+
- Add core files.
|
|
87
|
+
|
|
88
|
+
- See git history for changes previous to this release.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
Copyright (c) 2020, Digital Bazaar, Inc.
|
|
2
|
+
All rights reserved.
|
|
3
|
+
|
|
4
|
+
Redistribution and use in source and binary forms, with or without
|
|
5
|
+
modification, are permitted provided that the following conditions are met:
|
|
6
|
+
|
|
7
|
+
* Redistributions of source code must retain the above copyright notice, this
|
|
8
|
+
list of conditions and the following disclaimer.
|
|
9
|
+
|
|
10
|
+
* Redistributions in binary form must reproduce the above copyright notice,
|
|
11
|
+
this list of conditions and the following disclaimer in the documentation
|
|
12
|
+
and/or other materials provided with the distribution.
|
|
13
|
+
|
|
14
|
+
* Neither the name of the copyright holder nor the names of its
|
|
15
|
+
contributors may be used to endorse or promote products derived from
|
|
16
|
+
this software without specific prior written permission.
|
|
17
|
+
|
|
18
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
19
|
+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
20
|
+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
21
|
+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
|
22
|
+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
23
|
+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
24
|
+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
|
25
|
+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
26
|
+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
27
|
+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
package/README.md
ADDED
|
@@ -0,0 +1,329 @@
|
|
|
1
|
+
# JS/TS Base-N Id Generator _(@interop/bnid)_
|
|
2
|
+
|
|
3
|
+
[](https://github.com/interop-alliance/bnid/actions/workflows/ci.yml)
|
|
4
|
+
[](https://npm.im/@interop/bnid)
|
|
5
|
+
|
|
6
|
+
> A Typescript/JavaScript library for Web browsers, React Native, and Node.js
|
|
7
|
+
> apps to generate random ids and encode and decode them using various base-N
|
|
8
|
+
> encodings.
|
|
9
|
+
|
|
10
|
+
## Table of Contents
|
|
11
|
+
|
|
12
|
+
- [Background](#background)
|
|
13
|
+
- [Install](#install)
|
|
14
|
+
- [Usage](#usage)
|
|
15
|
+
- [API](#api)
|
|
16
|
+
- [CLI](#cli)
|
|
17
|
+
- [Contribute](#contribute)
|
|
18
|
+
- [Commercial Support](#commercial-support)
|
|
19
|
+
- [License](#license)
|
|
20
|
+
|
|
21
|
+
## Background
|
|
22
|
+
|
|
23
|
+
This library provides tools for Web browsers, React Native, and Node.js apps to
|
|
24
|
+
generate random ids and encode and decode them in various base-N encodings.
|
|
25
|
+
|
|
26
|
+
## Install
|
|
27
|
+
|
|
28
|
+
### NPM
|
|
29
|
+
|
|
30
|
+
```
|
|
31
|
+
npm install @interop/bnid
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
### Git
|
|
35
|
+
|
|
36
|
+
To install locally (for development):
|
|
37
|
+
|
|
38
|
+
```
|
|
39
|
+
git clone https://github.com/interop-alliance/bnid.git
|
|
40
|
+
cd bnid
|
|
41
|
+
pnpm install
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
### React Native
|
|
45
|
+
|
|
46
|
+
This library is isomorphic and runs on React Native, with one environment
|
|
47
|
+
requirement: it uses the Web Crypto `crypto.getRandomValues()` API to generate
|
|
48
|
+
random id material, which React Native does not provide natively. Consumers must
|
|
49
|
+
install the [`react-native-get-random-values`][] polyfill and import it
|
|
50
|
+
**once**, before any `@interop/bnid` code runs (typically at the very
|
|
51
|
+
top of your app entry, e.g. `index.js`):
|
|
52
|
+
|
|
53
|
+
```sh
|
|
54
|
+
npm install react-native-get-random-values
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
```js
|
|
58
|
+
// must be the first import in your app entry
|
|
59
|
+
import 'react-native-get-random-values'
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
It is declared as an optional `peerDependency`.
|
|
63
|
+
|
|
64
|
+
[`react-native-get-random-values`]:
|
|
65
|
+
https://github.com/LinusU/react-native-get-random-values
|
|
66
|
+
|
|
67
|
+
## Usage
|
|
68
|
+
|
|
69
|
+
The interface follows the [TextEncoder][]/[TextDecoder][] interfaces and
|
|
70
|
+
provides [IdEncoder](#idencoder) and [IdDecoder](#iddecoder) classes. Instances
|
|
71
|
+
can be configured with reusable encodings and other parameters. The encoder
|
|
72
|
+
operates on a `Uint8Array` of input bytes. A [IdGenerator](#idgenerator) class
|
|
73
|
+
is provided that can be used to generate random ids with selectable bit lengths,
|
|
74
|
+
but any id data can be used.
|
|
75
|
+
|
|
76
|
+
The encoder and decoder support various encodings and options:
|
|
77
|
+
|
|
78
|
+
- `base16`/`hex`, `base16upper`: The simple [Base16][].
|
|
79
|
+
- `base58`/`base58btc`: The [Base58][] Bitcoin alphabet.
|
|
80
|
+
- Optional [multibase][] type prefix.
|
|
81
|
+
- Fixed bit length. This is useful to ensure the output id length is constant
|
|
82
|
+
even when the id starts with an arbitrary number of zeros.
|
|
83
|
+
|
|
84
|
+
The fixed length options can be important when using encodings that have
|
|
85
|
+
variable length outputs depending on the input length. `base58btc` is and
|
|
86
|
+
example. When encoding, the `fixedLength` or `fixedBitLength` options can be
|
|
87
|
+
used to force the output to be a constant length. When decoding, the
|
|
88
|
+
`fixedBitLength` options can be used to ensure a constant length array of bytes.
|
|
89
|
+
|
|
90
|
+
### Generate an ID
|
|
91
|
+
|
|
92
|
+
To generate a default [Base58][], 128 bit, non-fixed-length, multibase encoded
|
|
93
|
+
id:
|
|
94
|
+
|
|
95
|
+
```js
|
|
96
|
+
import { generateId } from '@interop/bnid'
|
|
97
|
+
|
|
98
|
+
const id = await generateId()
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
To generate a [Base58][], 128 bit, fixed-length id:
|
|
102
|
+
|
|
103
|
+
```js
|
|
104
|
+
import { generateId } from '@interop/bnid'
|
|
105
|
+
|
|
106
|
+
const id = await generateId({
|
|
107
|
+
fixedLength: true
|
|
108
|
+
})
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### Reusable Components
|
|
112
|
+
|
|
113
|
+
Some setup overhead can be avoided by using the component `IdGenerator` and
|
|
114
|
+
`IdEncoder` classes.
|
|
115
|
+
|
|
116
|
+
```js
|
|
117
|
+
import { IdGenerator, IdEncoder } from '@interop/bnid'
|
|
118
|
+
|
|
119
|
+
// 64 bit random id generator
|
|
120
|
+
const generator = new IdGenerator({
|
|
121
|
+
bitLength: 64
|
|
122
|
+
})
|
|
123
|
+
// base58, multibase, fixed-length encoder
|
|
124
|
+
const encoder = new IdEncoder({
|
|
125
|
+
encoding: 'base58',
|
|
126
|
+
fixedLength: true,
|
|
127
|
+
multibase: true
|
|
128
|
+
})
|
|
129
|
+
const id1 = encoder.encode(await generator.generate())
|
|
130
|
+
const id2 = encoder.encode(await generator.generate())
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### Reusable Components
|
|
134
|
+
|
|
135
|
+
Some setup overhead can be avoided by using the component `IdGenerator` and
|
|
136
|
+
`IdEncoder` classes.
|
|
137
|
+
|
|
138
|
+
```js
|
|
139
|
+
import { IdGenerator, IdEncoder, IdDecoder } from '@interop/bnid'
|
|
140
|
+
|
|
141
|
+
// 64 bit random id generator
|
|
142
|
+
const generator = new IdGenerator({
|
|
143
|
+
bitLength: 64
|
|
144
|
+
})
|
|
145
|
+
// base58, multibase, fixed-length encoder
|
|
146
|
+
const encoder = new IdEncoder({
|
|
147
|
+
encoding: 'base58',
|
|
148
|
+
fixedLength: true,
|
|
149
|
+
multibase: true
|
|
150
|
+
})
|
|
151
|
+
const id1 = encoder.encode(await generator.generate())
|
|
152
|
+
// => "z..."
|
|
153
|
+
const id2 = encoder.encode(await generator.generate())
|
|
154
|
+
// => "z..."
|
|
155
|
+
|
|
156
|
+
const decoder = new IdDecoder({
|
|
157
|
+
fixedBitLength: 64,
|
|
158
|
+
multibase: true
|
|
159
|
+
})
|
|
160
|
+
const id1bytes = decoder.decode(id1)
|
|
161
|
+
// => Uint8Array([...])
|
|
162
|
+
const id2bytes = decoder.decode(id2)
|
|
163
|
+
// => Uint8Array([...])
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
## API
|
|
167
|
+
|
|
168
|
+
### `generateId(options)`
|
|
169
|
+
|
|
170
|
+
Generate a string id. See `IdGenerator` and `IdEncoder` for options.
|
|
171
|
+
|
|
172
|
+
### `decodeId(options)`
|
|
173
|
+
|
|
174
|
+
Decode the options.id string. See `IdDecoder` for other options.
|
|
175
|
+
|
|
176
|
+
### `IdGenerator`
|
|
177
|
+
|
|
178
|
+
An `IdGenerator` generates an array of id bytes.
|
|
179
|
+
|
|
180
|
+
#### `constuctor(options)` / `constructor(bitLength)`
|
|
181
|
+
|
|
182
|
+
Options:
|
|
183
|
+
|
|
184
|
+
- `bitLength`: Number of id bits. Must be multiple of 8. (default: 128)
|
|
185
|
+
|
|
186
|
+
#### `generate()`
|
|
187
|
+
|
|
188
|
+
Generate random id bytes.
|
|
189
|
+
|
|
190
|
+
### `IdEncoder`
|
|
191
|
+
|
|
192
|
+
An `IdEncoder` encodes an array of id bytes into a specific encoding.
|
|
193
|
+
|
|
194
|
+
#### `constuctor(options)`
|
|
195
|
+
|
|
196
|
+
Options:
|
|
197
|
+
|
|
198
|
+
- `encoding`: Output encoding. (default: `base58`)
|
|
199
|
+
- `base16`/`base16upper`/`hex`: base16 encoded string.
|
|
200
|
+
- `base58`/`base58btc`: base58btc encoded string.
|
|
201
|
+
- `fixedLength`: `true` to ensure fixed output length. (default: false)
|
|
202
|
+
- `fixedBitLength`: fixed output bit length or 0 to base on input byte size.
|
|
203
|
+
(default: 0)
|
|
204
|
+
- `multibase`: `true` to use multibase encoding. (default: `true`)
|
|
205
|
+
- `multihash`: `true` to use multihash encoding. (default: `false`)
|
|
206
|
+
|
|
207
|
+
#### `encode(bytes)`
|
|
208
|
+
|
|
209
|
+
Encode id bytes into a string.
|
|
210
|
+
|
|
211
|
+
### `IdDecoder`
|
|
212
|
+
|
|
213
|
+
An `IdDecoder` decodes a specific encoding into an array of bytes representing
|
|
214
|
+
an ID.
|
|
215
|
+
|
|
216
|
+
#### `constuctor(options)`
|
|
217
|
+
|
|
218
|
+
Options:
|
|
219
|
+
|
|
220
|
+
- `encoding`: Input encoding. Ignored if `multibase` is `true`. (default:
|
|
221
|
+
`base58`)
|
|
222
|
+
- Same options as for `IdEncoder`.
|
|
223
|
+
- `fixedBitLength`: fixed output bit length. (default: none)
|
|
224
|
+
- `multibase`: `true` to use multibase encoding to detect id format. (default:
|
|
225
|
+
`true`)
|
|
226
|
+
- `multihash`: `true` to use multihash encoding. (default: `false`)
|
|
227
|
+
- `expectedSize`: Expected size for multihash-encoded ID bytes. Use `0` to
|
|
228
|
+
disable size check. (default: 32)
|
|
229
|
+
|
|
230
|
+
#### `decode(id)`
|
|
231
|
+
|
|
232
|
+
Decode id string into bytes.
|
|
233
|
+
|
|
234
|
+
### `minEncodedIdBytes(options)`
|
|
235
|
+
|
|
236
|
+
Minimum number of bytes needed to encode an id of a given bit length.
|
|
237
|
+
|
|
238
|
+
Options:
|
|
239
|
+
|
|
240
|
+
- `encoding`: Encoding. (default: `base58`)
|
|
241
|
+
- `bitLength`: Number of id bits. (default: 128)
|
|
242
|
+
- `multibase`: Account for multibase encoding. (default: true)
|
|
243
|
+
|
|
244
|
+
### `maxEncodedIdBytes(options)`
|
|
245
|
+
|
|
246
|
+
Maximum number of bytes needed to encode an id of a given bit length.
|
|
247
|
+
|
|
248
|
+
Options:
|
|
249
|
+
|
|
250
|
+
- `encoding`: Encoding. (default: `base58`)
|
|
251
|
+
- `bitLength`: Number of id bits. (default: 128)
|
|
252
|
+
- `multibase`: Account for multibase encoding. (default: true)
|
|
253
|
+
|
|
254
|
+
### `generateSecretKeySeed(options)`
|
|
255
|
+
|
|
256
|
+
`generateSecretKeySeed()` and `decodeSecretKeySeed()` methods are for creating
|
|
257
|
+
and decoding secret key pair seeds which can be used to generate public key
|
|
258
|
+
based identifiers.
|
|
259
|
+
|
|
260
|
+
`generateSecretKeySeed()` generates a secret key seed encoded as a string that
|
|
261
|
+
can be stored and later used to generate a key pair. The public key from the key
|
|
262
|
+
pair can be used as an identifier. The encoded key seed MUST be kept secret.
|
|
263
|
+
|
|
264
|
+
```js
|
|
265
|
+
import { generateSecretKeySeed } from '@interop/bnid'
|
|
266
|
+
|
|
267
|
+
const secretKeySeed = await generateSecretKeySeed()
|
|
268
|
+
// Example secretKeySeed: z1Aaj5A4UCsdMpXwdYAReXa4bxWYiKJtdAvB1zMzCHtCbtD
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
Options:
|
|
272
|
+
|
|
273
|
+
- `encoding`: Encoding. (default: `base58`)
|
|
274
|
+
- `bitLength`: Number of id bits. (default: 32 \* 8)
|
|
275
|
+
- `multibase`: Account for multibase encoding. (default: true)
|
|
276
|
+
- `multihash`: Account for multihash encoding. (default: true)
|
|
277
|
+
|
|
278
|
+
### `decodeSecretKeySeed(options)`
|
|
279
|
+
|
|
280
|
+
Decodes an encoded secret key seed into an array of secret key seed bytes
|
|
281
|
+
(default size: 32 bytes). Both the encoded key seed and the decoded bytes MUST
|
|
282
|
+
be kept secret.
|
|
283
|
+
|
|
284
|
+
```js
|
|
285
|
+
import { decodeSecretKeySeed } from '@interop/bnid'
|
|
286
|
+
|
|
287
|
+
const secretKeySeed = 'z1Aaj5A4UCsdMpXwdYAReXa4bxWYiKJtdAvB1zMzCHtCbtD'
|
|
288
|
+
decoded = decodeSecretKeySeed({ secretKeySeed })
|
|
289
|
+
// Example decoded:
|
|
290
|
+
// Uint8Array(32) [
|
|
291
|
+
// 80, 174, 15, 131, 124, 59, 9, 51,
|
|
292
|
+
// 145, 129, 92, 157, 157, 172, 161, 79,
|
|
293
|
+
// 74, 61, 152, 152, 48, 151, 20, 89,
|
|
294
|
+
// 225, 169, 71, 34, 49, 61, 21, 215
|
|
295
|
+
// ]
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
Options:
|
|
299
|
+
|
|
300
|
+
- `secretKeySeed`: The secret key seed to be decoded.
|
|
301
|
+
- `multibase`: Account for multibase encoding. (default: true)
|
|
302
|
+
- `multihash`: Account for multihash encoding. (default: true)
|
|
303
|
+
- `expectedSize`: Expected size for multihash-encoded ID bytes. Use `0` to
|
|
304
|
+
disable size check. (default: 32)
|
|
305
|
+
|
|
306
|
+
## CLI
|
|
307
|
+
|
|
308
|
+
A command line interface tool to generate and encode ids is provided in
|
|
309
|
+
[`bnid-cli`](https://github.com/digitalbazaar/bnid-cli).
|
|
310
|
+
|
|
311
|
+
## Contribute
|
|
312
|
+
|
|
313
|
+
Please follow the existing code style.
|
|
314
|
+
|
|
315
|
+
PRs accepted.
|
|
316
|
+
|
|
317
|
+
If editing the README, please conform to the
|
|
318
|
+
[standard-readme](https://github.com/RichardLitt/standard-readme) specification.
|
|
319
|
+
|
|
320
|
+
## License
|
|
321
|
+
|
|
322
|
+
- MIT License - DCC - TypeScript and ReactNative compatibility.
|
|
323
|
+
- [BSD-3-Clause](LICENSE.md) © Digital Bazaar
|
|
324
|
+
|
|
325
|
+
[Base16]: https://en.wikipedia.org/wiki/Base16
|
|
326
|
+
[Base58]: https://en.wikipedia.org/wiki/Base58
|
|
327
|
+
[TextDecoder]: https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder
|
|
328
|
+
[TextEncoder]: https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder
|
|
329
|
+
[multibase]: https://github.com/multiformats/multibase
|
package/dist/baseX.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"baseX.d.ts","sourceRoot":"","sources":["../src/baseX.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,SAAS,kCAAS,CAAA"}
|
package/dist/baseX.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"baseX.js","sourceRoot":"","sources":["../src/baseX.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEpC,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAA"}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
export interface IEncoder {
|
|
2
|
+
bytes: Uint8Array;
|
|
3
|
+
idEncoder: IdEncoder;
|
|
4
|
+
}
|
|
5
|
+
export declare class IdGenerator {
|
|
6
|
+
bitLength: number;
|
|
7
|
+
/**
|
|
8
|
+
* Creates a new IdGenerator instance.
|
|
9
|
+
*
|
|
10
|
+
* An IdGenerator generates an array of id bytes.
|
|
11
|
+
*
|
|
12
|
+
* @param {object} [options] - The options to use.
|
|
13
|
+
* @param {number} [options.bitLength=128] - Number of bits to generate.
|
|
14
|
+
*
|
|
15
|
+
* @returns {IdGenerator} - New IdGenerator.
|
|
16
|
+
*/
|
|
17
|
+
constructor({ bitLength }?: {
|
|
18
|
+
bitLength?: number;
|
|
19
|
+
});
|
|
20
|
+
/**
|
|
21
|
+
* Generate random id bytes.
|
|
22
|
+
*
|
|
23
|
+
* @returns {Uint8Array} - Array of random id bytes.
|
|
24
|
+
*/
|
|
25
|
+
generate(): Promise<Uint8Array>;
|
|
26
|
+
}
|
|
27
|
+
export interface IIdEncoder {
|
|
28
|
+
encoding?: string;
|
|
29
|
+
fixedLength?: boolean;
|
|
30
|
+
fixedBitLength?: number;
|
|
31
|
+
bitLength?: number;
|
|
32
|
+
multibase?: boolean;
|
|
33
|
+
multihash?: boolean;
|
|
34
|
+
}
|
|
35
|
+
export declare class IdEncoder {
|
|
36
|
+
encoder: ({ bytes, idEncoder }: IEncoder) => string;
|
|
37
|
+
encoding: string;
|
|
38
|
+
multibasePrefix: string;
|
|
39
|
+
fixedLength: boolean;
|
|
40
|
+
fixedBitLength?: number;
|
|
41
|
+
multibase: boolean;
|
|
42
|
+
multihash: boolean;
|
|
43
|
+
/**
|
|
44
|
+
* Creates a new IdEncoder instance.
|
|
45
|
+
*
|
|
46
|
+
* An IdEncoder encodes an array of id bytes into a specific encoding.
|
|
47
|
+
*
|
|
48
|
+
* @param {object} [options] - The options to use.
|
|
49
|
+
* @param {string} [options.encoding='base58'] - Encoding format.
|
|
50
|
+
* @param {boolean} [options.fixedLength=false] - `true` to ensure fixed
|
|
51
|
+
* output length.
|
|
52
|
+
* @param {number} [options.fixedBitLength] - Fixed output bit length or 0 to
|
|
53
|
+
* base on input byte size.
|
|
54
|
+
* @param {boolean} [options.multibase=true] - Use multibase encoding.
|
|
55
|
+
* @param {boolean} [options.multihash=false] - Use multihash encoding.
|
|
56
|
+
*
|
|
57
|
+
* @returns {IdEncoder} - New IdEncoder.
|
|
58
|
+
*/
|
|
59
|
+
constructor({ encoding, fixedLength, fixedBitLength, multibase, multihash }?: IIdEncoder);
|
|
60
|
+
/**
|
|
61
|
+
* Encode id bytes into a string.
|
|
62
|
+
*
|
|
63
|
+
* @param {Uint8Array} bytes - Bytes to encode.
|
|
64
|
+
*
|
|
65
|
+
* @returns {string} - Encoded string.
|
|
66
|
+
*/
|
|
67
|
+
encode(bytes: Uint8Array): string;
|
|
68
|
+
}
|
|
69
|
+
export interface IIdDecoder {
|
|
70
|
+
encoding?: string;
|
|
71
|
+
fixedBitLength?: number;
|
|
72
|
+
multibase?: boolean;
|
|
73
|
+
multihash?: boolean;
|
|
74
|
+
expectedSize?: number;
|
|
75
|
+
}
|
|
76
|
+
export declare class IdDecoder {
|
|
77
|
+
encoding: string;
|
|
78
|
+
fixedBitLength?: number;
|
|
79
|
+
multibase: boolean;
|
|
80
|
+
multihash: boolean;
|
|
81
|
+
expectedSize: number;
|
|
82
|
+
/**
|
|
83
|
+
* Creates a new IdDecoder instance.
|
|
84
|
+
*
|
|
85
|
+
* An IdDecoder decodes an id string into a byte array. It is recommended to
|
|
86
|
+
* use the fixedBitLength option to avoid padding ids resulting in a larger
|
|
87
|
+
* than expected byte length.
|
|
88
|
+
*
|
|
89
|
+
* @param {object} [options] - The options to use.
|
|
90
|
+
* @param {string} [options.encoding='base58'] - Encoding format. Ignored if
|
|
91
|
+
* multibase is true.
|
|
92
|
+
* @param {number} [options.fixedBitLength] - Fixed output bit length. Values
|
|
93
|
+
* with leading non-zero data will error.
|
|
94
|
+
* @param {boolean} [options.multibase=true] - Use multibase encoding to
|
|
95
|
+
* detect the id format.
|
|
96
|
+
* @param {boolean} [options.multihash=false] - Use multihash encoding to
|
|
97
|
+
* detect the id format.
|
|
98
|
+
* @param {number} [options.expectedSize=32] - Optional expected identifier
|
|
99
|
+
* size in bytes (only for multihash encoding). Use `0` to disable size
|
|
100
|
+
* check.
|
|
101
|
+
* @returns {IdDecoder} - New IdDecoder.
|
|
102
|
+
*/
|
|
103
|
+
constructor({ encoding, fixedBitLength, multibase, multihash, expectedSize }?: IIdDecoder);
|
|
104
|
+
/**
|
|
105
|
+
* Decode id string into bytes.
|
|
106
|
+
*
|
|
107
|
+
* @param {string} id - Id to decode.
|
|
108
|
+
*
|
|
109
|
+
* @returns {Uint8Array} - Array of decoded id bytes.
|
|
110
|
+
*/
|
|
111
|
+
decode(id: string): Uint8Array;
|
|
112
|
+
}
|
|
113
|
+
/**
|
|
114
|
+
* Generates an encoded id string from random bits.
|
|
115
|
+
*
|
|
116
|
+
* @param {object} [options] - The options to use. See `IdEncoder` and
|
|
117
|
+
* `IdGenerator` for available options.
|
|
118
|
+
*
|
|
119
|
+
* @returns {string} - Encoded string id.
|
|
120
|
+
*/
|
|
121
|
+
export declare function generateId(options: IIdEncoder): Promise<string>;
|
|
122
|
+
/**
|
|
123
|
+
* Decodes an encoded id string to an array of bytes.
|
|
124
|
+
*
|
|
125
|
+
* @param {object} options - The options to use. See `IdDecoder` for available
|
|
126
|
+
* options.
|
|
127
|
+
* @param {string} options.id - Id to decode.
|
|
128
|
+
*
|
|
129
|
+
* @returns {Uint8Array} - Decoded array of id bytes.
|
|
130
|
+
*/
|
|
131
|
+
export declare function decodeId(options: IIdDecoder & {
|
|
132
|
+
id: string;
|
|
133
|
+
}): Uint8Array;
|
|
134
|
+
/**
|
|
135
|
+
* Minimum number of bytes needed to encode an id of a given bit length.
|
|
136
|
+
*
|
|
137
|
+
* @param {object} options - The options to use.
|
|
138
|
+
* @param {string} [options.encoding='base58'] - Encoding format.
|
|
139
|
+
* @param {number} [options.bitLength=128] - Number of id bits.
|
|
140
|
+
* @param {boolean} [options.multibase=true] - Account for multibase encoding.
|
|
141
|
+
*
|
|
142
|
+
* @returns {number} - The minimum number of encoded bytes.
|
|
143
|
+
*/
|
|
144
|
+
export declare function minEncodedIdBytes({ encoding, bitLength, multibase }?: IIdEncoder): number;
|
|
145
|
+
/**
|
|
146
|
+
* Maximum number of bytes needed to encode an id of a given bit length.
|
|
147
|
+
*
|
|
148
|
+
* @param {object} options - The options to use.
|
|
149
|
+
* @param {string} [options.encoding='base58'] - Encoding format.
|
|
150
|
+
* @param {number} [options.bitLength=128] - Number of id bits.
|
|
151
|
+
* @param {boolean} [options.multibase=true] - Account for multibase encoding.
|
|
152
|
+
*
|
|
153
|
+
* @returns {number} - The maximum number of encoded bytes.
|
|
154
|
+
*/
|
|
155
|
+
export declare function maxEncodedIdBytes({ encoding, bitLength, multibase }?: IIdEncoder): number;
|
|
156
|
+
/**
|
|
157
|
+
* Generates a secret key seed encoded as a string that can be stored and later
|
|
158
|
+
* used to generate a key pair. The public key from the key pair can be used as
|
|
159
|
+
* an identifier. The key seed (both raw and encoded form) MUST be kept secret.
|
|
160
|
+
*
|
|
161
|
+
* @param {object} [options] - The options to use.
|
|
162
|
+
* @param {string} [options.encoding='base58'] - Encoding format.
|
|
163
|
+
* @param {number} [options.bitLength=32 * 8] - Number of bits to generate.
|
|
164
|
+
* @param {boolean} [options.multibase=true] - Use multibase encoding.
|
|
165
|
+
* @param {boolean} [options.multihash=true] - Use multihash encoding.
|
|
166
|
+
|
|
167
|
+
* @returns {string} - Secret key seed encoded as a string.
|
|
168
|
+
*/
|
|
169
|
+
export declare function generateSecretKeySeed({ bitLength, encoding, multibase, multihash }?: IIdEncoder): Promise<string>;
|
|
170
|
+
/**
|
|
171
|
+
* Decodes an encoded secret key seed into an array of secret key seed bytes.
|
|
172
|
+
* The key seed bytes MUST be kept secret.
|
|
173
|
+
*
|
|
174
|
+
* @param {object} options - The options to use.
|
|
175
|
+
* @param {boolean} [options.multibase=true] - Use multibase encoding to detect
|
|
176
|
+
* the id format.
|
|
177
|
+
* @param {boolean} [options.multihash=true] - Use multihash encoding to detect
|
|
178
|
+
* the id format.
|
|
179
|
+
* @param {number} [options.expectedSize] - Optional expected identifier size
|
|
180
|
+
* in bytes (only for multihash encoding). Use `0` to disable size check.
|
|
181
|
+
* @param {string} options.secretKeySeed - The secret key seed to be decoded.
|
|
182
|
+
*
|
|
183
|
+
* @returns {Uint8Array} - An array of secret key seed bytes (default size:
|
|
184
|
+
* 32 bytes).
|
|
185
|
+
*/
|
|
186
|
+
export declare function decodeSecretKeySeed({ multibase, multihash, expectedSize, secretKeySeed }: {
|
|
187
|
+
multibase?: boolean;
|
|
188
|
+
multihash?: boolean;
|
|
189
|
+
expectedSize?: number;
|
|
190
|
+
secretKeySeed: string;
|
|
191
|
+
}): Uint8Array;
|
|
192
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|