develock 0.0.0-stage → 0.3.1
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 +20 -0
- package/LICENSE +73 -0
- package/README.md +107 -2
- package/dist/ReleaseInfo.json +8 -0
- package/dist/THIRD-PARTY-NOTICES.txt +57 -0
- package/dist/cli.js +72 -0
- package/dist/index.d.ts +436 -0
- package/dist/index.js +59 -0
- package/package.json +66 -4
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,436 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* what went wrong in a call to the backend, so that a local app can tell the cases apart.
|
|
3
|
+
* - unreachable: no connection (refused, dns, tls, broken off); try later.
|
|
4
|
+
* - timeout: no complete answer within the deadline; try later.
|
|
5
|
+
* - invalidAnswer: an answer that is not one the lib api gives: too large, not json, not matching
|
|
6
|
+
* the route's schema, a redirect, an unknown route (404) or a status without the error body. a
|
|
7
|
+
* wrong backend url, a proxy or a broken server.
|
|
8
|
+
* - refused: 400, the request is malformed (a library too old or a bug); see detail.
|
|
9
|
+
* - notAuthorized: 401, signature, instance or key not accepted; serverCode tells why (clock: the system
|
|
10
|
+
* clock is off even after asking the server time).
|
|
11
|
+
* - rateLimited: 429; retryAfterSeconds if the backend said so. the library doesn't wait itself.
|
|
12
|
+
* - notImplemented: 501, the backend doesn't support this yet.
|
|
13
|
+
* - serverError: another 5xx with the error body of the lib api.
|
|
14
|
+
*/
|
|
15
|
+
declare const backendErrorCodes: readonly ["unreachable", "timeout", "invalidAnswer", "refused", "notAuthorized", "rateLimited", "notImplemented", "serverError"];
|
|
16
|
+
type BackendErrorCode = typeof backendErrorCodes[number];
|
|
17
|
+
/**
|
|
18
|
+
* the routes of the lib api a BackendError can name, written out: they are part of the public
|
|
19
|
+
* interface, whose declarations must not depend on core (a test checks they are the same).
|
|
20
|
+
*/
|
|
21
|
+
type BackendRouteName = "serverTime" | "registration" | "collectionFetch";
|
|
22
|
+
/**
|
|
23
|
+
* the details a BackendError may carry besides code and route.
|
|
24
|
+
* - status: the http status, if an answer came.
|
|
25
|
+
* - detail, serverCode: from the error body of the lib api ({ detail, code? }).
|
|
26
|
+
* - retryAfterSeconds: from retry-after (rateLimited only).
|
|
27
|
+
* - cause: the underlying error, if any.
|
|
28
|
+
*/
|
|
29
|
+
type BackendErrorDetails = {
|
|
30
|
+
status?: number;
|
|
31
|
+
detail?: string;
|
|
32
|
+
serverCode?: string;
|
|
33
|
+
retryAfterSeconds?: number;
|
|
34
|
+
cause?: unknown;
|
|
35
|
+
};
|
|
36
|
+
/**
|
|
37
|
+
* an error of a call to the backend: the only error BackendClient throws for a failed call.
|
|
38
|
+
*/
|
|
39
|
+
declare class BackendError extends Error {
|
|
40
|
+
readonly code: BackendErrorCode;
|
|
41
|
+
readonly route: BackendRouteName;
|
|
42
|
+
readonly status?: number;
|
|
43
|
+
readonly detail?: string;
|
|
44
|
+
readonly serverCode?: string;
|
|
45
|
+
readonly retryAfterSeconds?: number;
|
|
46
|
+
/**
|
|
47
|
+
* constructor.
|
|
48
|
+
* @param code what went wrong.
|
|
49
|
+
* @param route the route that was called.
|
|
50
|
+
* @param message the message (BackendClient names the route and the server's detail in it).
|
|
51
|
+
* @param details status, detail, serverCode, retryAfterSeconds and cause, where known.
|
|
52
|
+
*/
|
|
53
|
+
constructor(code: BackendErrorCode, route: BackendRouteName, message: string, details?: BackendErrorDetails);
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* what InstanceCreateOptionsSchema accepts, written out: it is part of the public interface,
|
|
58
|
+
* whose declarations must not depend on zod (a test checks that both are the same).
|
|
59
|
+
*/
|
|
60
|
+
type InstanceCreateOptions = {
|
|
61
|
+
server: string;
|
|
62
|
+
ca?: string;
|
|
63
|
+
} | {
|
|
64
|
+
offline: true;
|
|
65
|
+
};
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* the value of a secret, as given to develock.
|
|
69
|
+
* - a string (UTF-8 encoded) or bytes: develock copies it as soon as it is called, before the call
|
|
70
|
+
* returns its promise, and wipes its copy after use. the given value is never changed or kept,
|
|
71
|
+
* so given bytes may be wiped right after the call, without waiting for it to finish. getting
|
|
72
|
+
* the value safely and wiping it is up to the caller; a string cannot be wiped.
|
|
73
|
+
* - `{ ask: true }`: develock asks the person at the terminal. Ctrl+T shows or hides the input;
|
|
74
|
+
* input hidden when Enter is pressed is asked a second time to confirm it (for a value, Enter
|
|
75
|
+
* without input skips that).
|
|
76
|
+
* - `timeoutSeconds`: how long to wait for each prompt, 120 by default; 0 or less waits forever.
|
|
77
|
+
* - `visible`: whether the input is shown at first, false by default. visible input stays in
|
|
78
|
+
* the terminal's scrollback.
|
|
79
|
+
* - Ctrl+C or Ctrl+D cancels with an error; they do not raise SIGINT.
|
|
80
|
+
* - an open readline interface of the application echoes the input unless it is closed while
|
|
81
|
+
* develock asks.
|
|
82
|
+
* - without a terminal (e.g. piped stdin, CI) it fails.
|
|
83
|
+
*/
|
|
84
|
+
type SecretInput = string | Uint8Array | {
|
|
85
|
+
ask: true;
|
|
86
|
+
timeoutSeconds?: number;
|
|
87
|
+
visible?: boolean;
|
|
88
|
+
};
|
|
89
|
+
/**
|
|
90
|
+
* the passphrase of an instance, as given to develock.
|
|
91
|
+
* - a string or bytes, copied and wiped like a SecretInput.
|
|
92
|
+
* - `{ ask: true }`: develock asks the person at the terminal, only when needed, and twice when it
|
|
93
|
+
* creates the instance (once if the input was visible at Enter); otherwise like a SecretInput.
|
|
94
|
+
*/
|
|
95
|
+
type PassphraseInput = SecretInput;
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* how a user specifies a collection: "<ownerId>/<name>" (a server collection), "<name>" (an
|
|
99
|
+
* offline one), or another form parseCollectionSpecifier accepts. unchecked; parse it to check it.
|
|
100
|
+
*/
|
|
101
|
+
type CollectionSpecifier = string;
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* the changes to the secrets of a collection, collected for its next version.
|
|
105
|
+
* - it is handed to the function given to Collection.update, and ends with that function.
|
|
106
|
+
* - every value is encrypted as soon as it is set; no plain value waits for the commit.
|
|
107
|
+
* - versions of secrets are counted against the version the update is based on: setting a path
|
|
108
|
+
* several times counts once, and setting a value equal to the stored one is no change.
|
|
109
|
+
*/
|
|
110
|
+
interface CollectionUpdate {
|
|
111
|
+
/**
|
|
112
|
+
* sets the value of a secret, adding it or replacing its value.
|
|
113
|
+
* - the value is taken over before the first await, like a passphrase (cf. SecretInput); with
|
|
114
|
+
* `{ ask: true }` the person at the terminal types it twice.
|
|
115
|
+
* - a new path gets version 1, a changed value the stored version + 1; an equal value keeps the
|
|
116
|
+
* stored version.
|
|
117
|
+
* @param path the path of the secret inside the collection, e.g. "db/password".
|
|
118
|
+
* @param value the value: a string (UTF-8 encoded), bytes or { ask: true }.
|
|
119
|
+
* @throws if the update has ended, the path is invalid, the value is empty or too large, or
|
|
120
|
+
* asking fails.
|
|
121
|
+
*/
|
|
122
|
+
setSecret(path: string, value: SecretInput): Promise<void>;
|
|
123
|
+
/**
|
|
124
|
+
* deletes a secret.
|
|
125
|
+
* @param path the path of the secret inside the collection.
|
|
126
|
+
* @throws if the update has ended, the path is invalid, or there is no secret at the path.
|
|
127
|
+
*/
|
|
128
|
+
deleteSecret(path: string): Promise<void>;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* a secret fetched from a collection: its path, the version and creation time of its value, and
|
|
133
|
+
* the value itself.
|
|
134
|
+
* - get one with Collection.fetchSecret.
|
|
135
|
+
* - the value stays obfuscated until text() or bytes() is called.
|
|
136
|
+
* - call invalidate() when the value is not needed any longer.
|
|
137
|
+
*/
|
|
138
|
+
interface Secret {
|
|
139
|
+
/**
|
|
140
|
+
* the path of the secret inside its collection, e.g. "db/password".
|
|
141
|
+
*/
|
|
142
|
+
readonly path: string;
|
|
143
|
+
/**
|
|
144
|
+
* the version of the value.
|
|
145
|
+
*/
|
|
146
|
+
readonly version: number;
|
|
147
|
+
/**
|
|
148
|
+
* when the value was written (by the clock of the writer, for display only).
|
|
149
|
+
*/
|
|
150
|
+
readonly created: Date;
|
|
151
|
+
/**
|
|
152
|
+
* the value as text.
|
|
153
|
+
* - a string cannot be wiped; prefer bytes() where possible.
|
|
154
|
+
* @returns the value decoded as UTF-8.
|
|
155
|
+
* @throws if the value is no valid UTF-8 or the secret was invalidated.
|
|
156
|
+
*/
|
|
157
|
+
text(): string;
|
|
158
|
+
/**
|
|
159
|
+
* the value as bytes.
|
|
160
|
+
* @returns a new copy of the value; the caller may (and should) wipe it after use.
|
|
161
|
+
* @throws if the secret was invalidated.
|
|
162
|
+
*/
|
|
163
|
+
bytes(): Uint8Array;
|
|
164
|
+
/**
|
|
165
|
+
* wipes the value. calling it again does no harm.
|
|
166
|
+
*/
|
|
167
|
+
invalidate(): void;
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
/**
|
|
171
|
+
* develock collection, i.e. a container of secrets inside of an instance.
|
|
172
|
+
* - get one with Instance.fetchCollection or Instance.createCollection.
|
|
173
|
+
* - offline collections are generated locally and stored as file; their url is the file url.
|
|
174
|
+
* - server collections are provided by the backend and read-only; their url is the one of the
|
|
175
|
+
* lib api.
|
|
176
|
+
* - a collection object is one version of the collection and never changes; update() returns
|
|
177
|
+
* the next version as a new object. an older object can still be read, but not updated.
|
|
178
|
+
*/
|
|
179
|
+
interface Collection {
|
|
180
|
+
/**
|
|
181
|
+
* name of the collection, i.e. the last component of its url.
|
|
182
|
+
*/
|
|
183
|
+
readonly name: string;
|
|
184
|
+
/**
|
|
185
|
+
* the owner id of a server collection, "self" for an offline collection.
|
|
186
|
+
*/
|
|
187
|
+
readonly ownerId: string;
|
|
188
|
+
/**
|
|
189
|
+
* how the collection is specified (cf. CollectionSpecifier): "<name>" or "<ownerId>/<name>".
|
|
190
|
+
*/
|
|
191
|
+
readonly specifier: CollectionSpecifier;
|
|
192
|
+
/**
|
|
193
|
+
* where the collection comes from: the file url of an offline collection, the lib api url of a
|
|
194
|
+
* server collection.
|
|
195
|
+
*/
|
|
196
|
+
readonly url: string;
|
|
197
|
+
/**
|
|
198
|
+
* the version of the collection this object is.
|
|
199
|
+
*/
|
|
200
|
+
readonly version: number;
|
|
201
|
+
/**
|
|
202
|
+
* lists the paths of the secrets in this collection.
|
|
203
|
+
* @returns the paths, sorted.
|
|
204
|
+
*/
|
|
205
|
+
listSecretPaths(): string[];
|
|
206
|
+
/**
|
|
207
|
+
* checks whether a secret exists in this collection.
|
|
208
|
+
* @param path the path of the secret inside the collection, e.g. "db/password".
|
|
209
|
+
* @returns whether the secret exists.
|
|
210
|
+
* @throws if the path is invalid.
|
|
211
|
+
*/
|
|
212
|
+
existsSecret(path: string): boolean;
|
|
213
|
+
/**
|
|
214
|
+
* fetches a secret of this collection, decrypting its value.
|
|
215
|
+
* @param path the path of the secret inside the collection, e.g. "db/password".
|
|
216
|
+
* @returns the secret. please invalidate it when its value is not needed any longer.
|
|
217
|
+
* @throws if the path is invalid or there is no secret at the path.
|
|
218
|
+
*/
|
|
219
|
+
fetchSecret(path: string): Promise<Secret>;
|
|
220
|
+
/**
|
|
221
|
+
* changes the secrets of this collection, writing its next version.
|
|
222
|
+
* - the function gets a CollectionUpdate and makes the changes with it; await every call.
|
|
223
|
+
* - when the function resolves, the changes are written as one new version; when it throws,
|
|
224
|
+
* they are discarded. without changes nothing is written.
|
|
225
|
+
* - there is no retry: if the collection was changed meanwhile (e.g. by another process, or
|
|
226
|
+
* this object is not its latest version), the update fails and nothing is saved.
|
|
227
|
+
* @param fn the function making the changes.
|
|
228
|
+
* @returns the collection with the next version, or this collection if nothing changed.
|
|
229
|
+
* @throws what the function throws, or if the collection cannot be written (e.g. a server
|
|
230
|
+
* collection, which is read-only).
|
|
231
|
+
*/
|
|
232
|
+
update(fn: (update: CollectionUpdate) => Promise<void> | void): Promise<Collection>;
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
/**
|
|
236
|
+
* options of Instance.fetchCollection.
|
|
237
|
+
* - createIfNotExists: create an empty offline collection if it does not exist (refused for a
|
|
238
|
+
* server collection, which is created in the web app).
|
|
239
|
+
*/
|
|
240
|
+
type CollectionFetchOptions = {
|
|
241
|
+
createIfNotExists?: boolean;
|
|
242
|
+
};
|
|
243
|
+
/**
|
|
244
|
+
* what an instance holds of a collection (cf. Instance.listCollections).
|
|
245
|
+
* - ownerId: the owner id of a server collection, "self" for an offline collection.
|
|
246
|
+
* - version: the latest version the instance has (or had, if removed).
|
|
247
|
+
* - removed: why and when it was removed, null while it can be fetched. "deleted": a deleted
|
|
248
|
+
* offline collection, or the local copy of a server collection deleted in this instance;
|
|
249
|
+
* "retracted", "expired", "not-renewed": the local copy of a server collection.
|
|
250
|
+
*/
|
|
251
|
+
type CollectionSummary = {
|
|
252
|
+
specifier: CollectionSpecifier;
|
|
253
|
+
ownerId: string;
|
|
254
|
+
version: number;
|
|
255
|
+
removed: {
|
|
256
|
+
reason: "retracted" | "expired" | "not-renewed" | "deleted";
|
|
257
|
+
at: Date;
|
|
258
|
+
} | null;
|
|
259
|
+
};
|
|
260
|
+
/**
|
|
261
|
+
* develock instance which represents an instance folder inside of a configuration.
|
|
262
|
+
* - instances handle collections of secrets.
|
|
263
|
+
* - get one with Configuration.fetchInstance or Configuration.createInstance.
|
|
264
|
+
*
|
|
265
|
+
* a collection is specified (cf. CollectionSpecifier) as:
|
|
266
|
+
* - "<name>": an offline collection of the instance.
|
|
267
|
+
* - "<ownerId>/<name>": a server collection, provided by the instance's backend; read-only.
|
|
268
|
+
*/
|
|
269
|
+
interface Instance {
|
|
270
|
+
/**
|
|
271
|
+
* the name of the instance, i.e. the name of its folder in the configuration.
|
|
272
|
+
*/
|
|
273
|
+
readonly name: string;
|
|
274
|
+
/**
|
|
275
|
+
* the backend of the instance (the base url of its lib api and the id it assigned), or null for
|
|
276
|
+
* an offline-only instance.
|
|
277
|
+
*/
|
|
278
|
+
readonly server: {
|
|
279
|
+
url: string;
|
|
280
|
+
instanceId: string;
|
|
281
|
+
} | null;
|
|
282
|
+
/**
|
|
283
|
+
* lists the collections this instance can fetch without creating them: its offline collections
|
|
284
|
+
* and the server collections it has a local copy of (cf. existsCollection).
|
|
285
|
+
* @returns their specifiers, sorted.
|
|
286
|
+
*/
|
|
287
|
+
listCollectionSpecifiers(): Promise<CollectionSpecifier[]>;
|
|
288
|
+
/**
|
|
289
|
+
* lists what this instance holds of its collections, including removed ones.
|
|
290
|
+
* @returns the collections, sorted by their specifiers.
|
|
291
|
+
*/
|
|
292
|
+
listCollections(): Promise<CollectionSummary[]>;
|
|
293
|
+
/**
|
|
294
|
+
* retrieves a collection of this instance.
|
|
295
|
+
* - a server collection is fetched from the backend; while it can't be reached (or gives no
|
|
296
|
+
* valid answer), the local copy is used as long as it is valid.
|
|
297
|
+
* @param specifier the collection (cf. CollectionSpecifier).
|
|
298
|
+
* @param options cf. CollectionFetchOptions.
|
|
299
|
+
* @returns the retrieved collection.
|
|
300
|
+
*/
|
|
301
|
+
fetchCollection(specifier: CollectionSpecifier, options?: CollectionFetchOptions): Promise<Collection>;
|
|
302
|
+
/**
|
|
303
|
+
* creates a new empty offline collection in this instance.
|
|
304
|
+
* @param specifier the collection (cf. CollectionSpecifier).
|
|
305
|
+
* @returns the created collection.
|
|
306
|
+
* @throws for a server collection, which is created in the web app.
|
|
307
|
+
*/
|
|
308
|
+
createCollection(specifier: CollectionSpecifier): Promise<Collection>;
|
|
309
|
+
/**
|
|
310
|
+
* checks whether a collection of this instance exists: an offline collection that is not
|
|
311
|
+
* deleted, or a server collection with a local copy (the backend is not asked).
|
|
312
|
+
* @param specifier the collection (cf. CollectionSpecifier).
|
|
313
|
+
* @returns whether the collection exists.
|
|
314
|
+
*/
|
|
315
|
+
existsCollection(specifier: CollectionSpecifier): Promise<boolean>;
|
|
316
|
+
/**
|
|
317
|
+
* deletes a collection of this instance.
|
|
318
|
+
* - of a server collection, only the local copy is deleted; the next fetch asks the backend
|
|
319
|
+
* again.
|
|
320
|
+
* @param specifier the collection (cf. CollectionSpecifier).
|
|
321
|
+
* @returns whether there was something to delete: an offline collection that was not deleted
|
|
322
|
+
* yet, or the local copy of a server collection.
|
|
323
|
+
*/
|
|
324
|
+
deleteCollection(specifier: CollectionSpecifier): Promise<boolean>;
|
|
325
|
+
}
|
|
326
|
+
|
|
327
|
+
/**
|
|
328
|
+
* options of Configuration.fetch.
|
|
329
|
+
* - createIfNotExists: create the configuration if it does not exist (the root directory itself
|
|
330
|
+
* has to exist, cf. Configuration.create). always true without a root directory.
|
|
331
|
+
*/
|
|
332
|
+
type ConfigurationFetchOptions = {
|
|
333
|
+
createIfNotExists?: boolean;
|
|
334
|
+
};
|
|
335
|
+
/**
|
|
336
|
+
* develock configuration which represents a .develock folder
|
|
337
|
+
* - it contains sub-folders for the different instances.
|
|
338
|
+
*
|
|
339
|
+
* currently it is only made for ensuring the permissions in POSIX systems (Linux, macOS).
|
|
340
|
+
* using it on Windows is less safe when other users have access to the system.
|
|
341
|
+
*/
|
|
342
|
+
declare class Configuration {
|
|
343
|
+
readonly develockDir: string;
|
|
344
|
+
private constructor();
|
|
345
|
+
/**
|
|
346
|
+
* fetch the configuration for the specified root directory.
|
|
347
|
+
* @param rootDir root directory where the .develock configuration is located.
|
|
348
|
+
* - if undefined, the user's home directory will be used, and the configuration is created
|
|
349
|
+
* if it does not exist.
|
|
350
|
+
* @param options cf. ConfigurationFetchOptions.
|
|
351
|
+
* @throws if the configuration does not exist and is not to be created.
|
|
352
|
+
*/
|
|
353
|
+
static fetch(rootDir?: string | undefined, options?: ConfigurationFetchOptions): Promise<Configuration>;
|
|
354
|
+
/**
|
|
355
|
+
* creates a new configuration at the specified path.
|
|
356
|
+
* - only the .develock folder is created, never the root directory, since delete() would not
|
|
357
|
+
* remove it again.
|
|
358
|
+
* @param rootDir root directory where the .develock folder will be created.
|
|
359
|
+
* @returns the created Configuration instance.
|
|
360
|
+
* @throws if the configuration already exists.
|
|
361
|
+
* @throws if the root directory does not exist or is not a directory.
|
|
362
|
+
*/
|
|
363
|
+
static create(rootDir: string): Promise<Configuration>;
|
|
364
|
+
/**
|
|
365
|
+
* deletes a configuration at the specified root directory.
|
|
366
|
+
* - it does not check whether the configuration is properly configured but tries to
|
|
367
|
+
* to delete the path recursively.
|
|
368
|
+
* - existing Configuration instances will fail at the next operation.
|
|
369
|
+
* @param rootDir root directory where the .develock folder will be created.
|
|
370
|
+
*/
|
|
371
|
+
static delete(rootDir: string): Promise<void>;
|
|
372
|
+
/**
|
|
373
|
+
* checks whether a configuration exists at the specified root directory.
|
|
374
|
+
* @param rootDir root directory where the .develock folder would be located.
|
|
375
|
+
* @returns whether a configuration exists at the specified root directory.
|
|
376
|
+
*/
|
|
377
|
+
static exists(rootDir: string): Promise<boolean>;
|
|
378
|
+
/**
|
|
379
|
+
* checks whether the specified develock directory exists and is properly configured.
|
|
380
|
+
* @param develockDir the path to the develock directory to check.
|
|
381
|
+
* @returns whether a properly configured develock directory exists.
|
|
382
|
+
* @throws if the path exists but is not a properly configured develock directory.
|
|
383
|
+
*/
|
|
384
|
+
private static develockDirExists;
|
|
385
|
+
private static getDevelockDir;
|
|
386
|
+
/**
|
|
387
|
+
* root directory of the configuration.
|
|
388
|
+
*/
|
|
389
|
+
get rootDir(): string;
|
|
390
|
+
/**
|
|
391
|
+
* lists the names of the develock instances in this configuration.
|
|
392
|
+
* @returns array of instance names.
|
|
393
|
+
*/
|
|
394
|
+
listInstanceNames(): Promise<string[]>;
|
|
395
|
+
/**
|
|
396
|
+
* retrieves a develock instance from this configuration.
|
|
397
|
+
* - the passphrase is obtained only after checking the instance; when it is asked for, it is
|
|
398
|
+
* asked twice if the instance is created.
|
|
399
|
+
* @param instanceName name of the instance to retrieve.
|
|
400
|
+
* @param passphrase passphrase for the instance's private key (cf. PassphraseInput: it is
|
|
401
|
+
* copied before this returns its promise and never changed; wiping it is up to the caller).
|
|
402
|
+
* @param createWith how to create the instance if it does not exist (cf. InstanceCreateOptions);
|
|
403
|
+
* without it, a missing instance is an error. an existing instance must match it (offline-only,
|
|
404
|
+
* or the same server and CA), otherwise it is refused after loading.
|
|
405
|
+
* @returns the retrieved develock instance.
|
|
406
|
+
*/
|
|
407
|
+
fetchInstance(instanceName: string, passphrase: PassphraseInput, createWith?: InstanceCreateOptions): Promise<Instance>;
|
|
408
|
+
/**
|
|
409
|
+
* creates a new develock instance within this configuration.
|
|
410
|
+
* - with a server, the server is asked for its time before the passphrase is obtained (so a wrong
|
|
411
|
+
* url shows up at once), and the instance registers with it before anything is written; a
|
|
412
|
+
* backend that can't be reached or refuses fails the creation with a BackendError.
|
|
413
|
+
* - the options are checked and the instance is checked not to exist before the passphrase is
|
|
414
|
+
* obtained; when it is asked for, it is asked twice.
|
|
415
|
+
* @param instanceName name of the instance to create.
|
|
416
|
+
* @param passphrase passphrase for the instance's private key (cf. PassphraseInput: it is
|
|
417
|
+
* copied before this returns its promise and never changed; wiping it is up to the caller).
|
|
418
|
+
* @param options with a server or offline-only (cf. InstanceCreateOptions); there is no default.
|
|
419
|
+
* @returns the newly created develock instance.
|
|
420
|
+
*/
|
|
421
|
+
createInstance(instanceName: string, passphrase: PassphraseInput, options: InstanceCreateOptions): Promise<Instance>;
|
|
422
|
+
/**
|
|
423
|
+
* deletes a develock instance from this configuration.
|
|
424
|
+
* - this will try to remove the instance directory even if the instance is broken and not
|
|
425
|
+
* recognized as a valid instance.
|
|
426
|
+
* @param instanceName name of the instance to delete.
|
|
427
|
+
*/
|
|
428
|
+
deleteInstance(instanceName: string): Promise<void>;
|
|
429
|
+
existsInstance(instanceName: string): Promise<boolean>;
|
|
430
|
+
private instanceDir;
|
|
431
|
+
}
|
|
432
|
+
|
|
433
|
+
declare function version(): Promise<string>;
|
|
434
|
+
|
|
435
|
+
export { BackendError, Configuration, version };
|
|
436
|
+
export type { BackendErrorCode, BackendRouteName, Collection, CollectionFetchOptions, CollectionSpecifier, CollectionSummary, CollectionUpdate, ConfigurationFetchOptions, Instance, InstanceCreateOptions, PassphraseInput, Secret, SecretInput };
|