@interop/was-client 0.99.1 → 0.100.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/README.md +127 -69
- package/dist/Collection.d.ts +17 -9
- package/dist/Collection.d.ts.map +1 -1
- package/dist/Collection.js +85 -70
- package/dist/Collection.js.map +1 -1
- package/dist/Resource.d.ts +11 -4
- package/dist/Resource.d.ts.map +1 -1
- package/dist/Resource.js +34 -28
- package/dist/Resource.js.map +1 -1
- package/dist/Space.d.ts +20 -5
- package/dist/Space.d.ts.map +1 -1
- package/dist/Space.js +69 -65
- package/dist/Space.js.map +1 -1
- package/dist/WasClient.d.ts +185 -57
- package/dist/WasClient.d.ts.map +1 -1
- package/dist/WasClient.js +340 -140
- package/dist/WasClient.js.map +1 -1
- package/dist/codec.d.ts +3 -2
- package/dist/codec.d.ts.map +1 -1
- package/dist/edv/EdvCodec.js +1 -1
- package/dist/edv/EdvCodec.js.map +1 -1
- package/dist/edv/WasTransport.d.ts +7 -4
- package/dist/edv/WasTransport.d.ts.map +1 -1
- package/dist/edv/WasTransport.js +39 -20
- package/dist/edv/WasTransport.js.map +1 -1
- package/dist/edv/acquire.d.ts +3 -3
- package/dist/edv/acquire.d.ts.map +1 -1
- package/dist/edv/acquire.js +3 -3
- package/dist/edv/acquire.js.map +1 -1
- package/dist/edv/cipher.d.ts +1 -1
- package/dist/edv/cipher.js +1 -1
- package/dist/edv/docCipher.d.ts +6 -5
- package/dist/edv/docCipher.d.ts.map +1 -1
- package/dist/edv/docCipher.js +6 -5
- package/dist/edv/docCipher.js.map +1 -1
- package/dist/edv/encryption.d.ts +2 -2
- package/dist/edv/encryption.d.ts.map +1 -1
- package/dist/edv/encryption.js +8 -6
- package/dist/edv/encryption.js.map +1 -1
- package/dist/edv/refreshingDocCipher.d.ts +3 -3
- package/dist/edv/refreshingDocCipher.d.ts.map +1 -1
- package/dist/edv/refreshingDocCipher.js +3 -3
- package/dist/edv/refreshingDocCipher.js.map +1 -1
- package/dist/edv/transportFactory.d.ts +3 -3
- package/dist/edv/transportFactory.d.ts.map +1 -1
- package/dist/edv/transportFactory.js +3 -3
- package/dist/edv/transportFactory.js.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/internal/codec.d.ts +7 -7
- package/dist/internal/codec.d.ts.map +1 -1
- package/dist/internal/codec.js +19 -18
- package/dist/internal/codec.js.map +1 -1
- package/dist/internal/conditional.d.ts +3 -3
- package/dist/internal/conditional.d.ts.map +1 -1
- package/dist/internal/conditional.js +5 -5
- package/dist/internal/conditional.js.map +1 -1
- package/dist/internal/grant.d.ts +15 -26
- package/dist/internal/grant.d.ts.map +1 -1
- package/dist/internal/grant.js +95 -29
- package/dist/internal/grant.js.map +1 -1
- package/dist/internal/meta.d.ts +8 -8
- package/dist/internal/meta.d.ts.map +1 -1
- package/dist/internal/meta.js +13 -10
- package/dist/internal/meta.js.map +1 -1
- package/dist/internal/paths.d.ts +423 -195
- package/dist/internal/paths.d.ts.map +1 -1
- package/dist/internal/paths.js +582 -369
- package/dist/internal/paths.js.map +1 -1
- package/dist/internal/policy.d.ts +23 -23
- package/dist/internal/policy.d.ts.map +1 -1
- package/dist/internal/policy.js +20 -20
- package/dist/internal/policy.js.map +1 -1
- package/dist/internal/request.d.ts +17 -21
- package/dist/internal/request.d.ts.map +1 -1
- package/dist/internal/request.js +10 -21
- package/dist/internal/request.js.map +1 -1
- package/dist/internal/reserved.d.ts +15 -3
- package/dist/internal/reserved.d.ts.map +1 -1
- package/dist/internal/reserved.js +37 -8
- package/dist/internal/reserved.js.map +1 -1
- package/dist/internal/revoke.d.ts +34 -13
- package/dist/internal/revoke.d.ts.map +1 -1
- package/dist/internal/revoke.js +97 -28
- package/dist/internal/revoke.js.map +1 -1
- package/dist/internal/service.d.ts +27 -7
- package/dist/internal/service.d.ts.map +1 -1
- package/dist/internal/service.js +51 -45
- package/dist/internal/service.js.map +1 -1
- package/dist/internal/write.d.ts +18 -18
- package/dist/internal/write.d.ts.map +1 -1
- package/dist/internal/write.js +27 -27
- package/dist/internal/write.js.map +1 -1
- package/dist/paths.d.ts +32 -25
- package/dist/paths.d.ts.map +1 -1
- package/dist/paths.js +32 -25
- package/dist/paths.js.map +1 -1
- package/dist/sync/port.d.ts +3 -3
- package/dist/sync/port.d.ts.map +1 -1
- package/dist/sync/port.js +12 -12
- package/dist/sync/port.js.map +1 -1
- package/dist/sync/provisioning.d.ts +10 -9
- package/dist/sync/provisioning.d.ts.map +1 -1
- package/dist/sync/provisioning.js +19 -18
- package/dist/sync/provisioning.js.map +1 -1
- package/dist/sync/types.d.ts +2 -2
- package/dist/types.d.ts +13 -5
- package/dist/types.d.ts.map +1 -1
- package/package.json +3 -3
package/dist/WasClient.d.ts
CHANGED
|
@@ -9,6 +9,19 @@
|
|
|
9
9
|
* (`grant`), capability-rebuilding (`fromCapability`), the signed
|
|
10
10
|
* escape-hatch (`request`), and service discovery (`service`), which every
|
|
11
11
|
* signed request waits on.
|
|
12
|
+
*
|
|
13
|
+
* A server that addresses Spaces by id is identified by its base server URL,
|
|
14
|
+
* under which the spec's Server Layout fixes `{base}service`, `{base}spaces/`
|
|
15
|
+
* and `{base}space/{space_id}/`. The client is built from that base
|
|
16
|
+
* (`new WasClient({ baseServerUrl })`) and constructs the three itself;
|
|
17
|
+
* `space(id)` opens a Space by id. A Space URL the client is handed (the
|
|
18
|
+
* `Location` of the create response, a capability's target, a DID, a stored
|
|
19
|
+
* pointer) is authoritative as given: `spaceAt(url)` opens it, and nothing
|
|
20
|
+
* rewrites it to fit the base. A server that is one fixed Space, with no id
|
|
21
|
+
* and no base server URL, is opened from the Space URL alone
|
|
22
|
+
* (`WasClient.forSpace({ spaceUrl })`); that client finds the service
|
|
23
|
+
* description through the `service` link and refuses the id-addressed
|
|
24
|
+
* operations.
|
|
12
25
|
*/
|
|
13
26
|
import type { ZcapClient } from '@interop/ezcap';
|
|
14
27
|
import type { HttpResponse } from '@interop/http-client';
|
|
@@ -18,32 +31,36 @@ import { Space } from './Space.js';
|
|
|
18
31
|
import { Collection } from './Collection.js';
|
|
19
32
|
import { Resource } from './Resource.js';
|
|
20
33
|
import type { EncryptionOverride, GrantOptions, HandleOptions, IDelegatedZcap, ISigner, IZcap, Json, RequestInput, CollectionResourcesList, ResourceSummary, ServiceInfo, SpaceListing } from './types.js';
|
|
34
|
+
/**
|
|
35
|
+
* The module-private key under which {@link WasClient.forSpace} hands the
|
|
36
|
+
* constructor a Space URL in place of a base server URL. A `unique symbol`
|
|
37
|
+
* keeps that arm off the public constructor: a caller holding a Space URL goes
|
|
38
|
+
* through `forSpace`, which documents what such a client can and cannot do.
|
|
39
|
+
*/
|
|
40
|
+
declare const fixedSpace: unique symbol;
|
|
21
41
|
export declare class WasClient {
|
|
22
42
|
#private;
|
|
23
43
|
/**
|
|
24
|
-
* The server
|
|
25
|
-
* (
|
|
44
|
+
* The base server URL the client was built from, in canonical form
|
|
45
|
+
* (trailing slash supplied): the URL under which the server lays out
|
|
46
|
+
* `service`, `spaces/` and `space/{space_id}/`. `undefined` for a client
|
|
47
|
+
* built by {@link WasClient.forSpace}, which has none.
|
|
26
48
|
*/
|
|
27
|
-
readonly
|
|
49
|
+
readonly baseServerUrl?: string;
|
|
28
50
|
/**
|
|
29
|
-
* The
|
|
30
|
-
*
|
|
31
|
-
* a sub-path mount). Zcap `invocationTarget`s are built beneath it.
|
|
51
|
+
* The Space URL a client built by {@link WasClient.forSpace} was opened on,
|
|
52
|
+
* in canonical form. `undefined` for a client built from a base server URL.
|
|
32
53
|
*/
|
|
33
|
-
readonly
|
|
54
|
+
readonly spaceUrl?: string;
|
|
34
55
|
readonly zcapClient: ZcapClient;
|
|
35
56
|
readonly encryption?: EncryptionProvider;
|
|
36
57
|
/**
|
|
37
58
|
* @param options {object}
|
|
38
|
-
* @param options.
|
|
39
|
-
* (
|
|
40
|
-
*
|
|
41
|
-
*
|
|
42
|
-
*
|
|
43
|
-
* is normalized to canonical form; `baseUrlOfSpacesUrl` in `./paths`
|
|
44
|
-
* states what is accepted. The client is built from this URL only: a
|
|
45
|
-
* server with no Spaces Repository (the spec leaves the endpoint
|
|
46
|
-
* optional) has no URL this constructor accepts and is not supported.
|
|
59
|
+
* @param options.baseServerUrl {string} the server's base server URL: an
|
|
60
|
+
* absolute http(s) URL with no query or fragment, under which the server
|
|
61
|
+
* serves `service`, `spaces/` and `space/{space_id}/`. A missing trailing
|
|
62
|
+
* slash is supplied. For a server that is one fixed Space with no base,
|
|
63
|
+
* use {@link WasClient.forSpace} instead
|
|
47
64
|
* @param options.zcapClient {ZcapClient} an ezcap client holding the signer
|
|
48
65
|
* @param [options.encryption] {EncryptionProvider} the keystore that
|
|
49
66
|
* supplies keys for collections declared encrypted (by their `encryption`
|
|
@@ -54,19 +71,60 @@ export declare class WasClient {
|
|
|
54
71
|
* closed rather than silently downgrading to plaintext.
|
|
55
72
|
* @param [options.serviceDescription] {ServiceDescription} a service
|
|
56
73
|
* description the caller already holds (from a cache, say). The client
|
|
57
|
-
* selects its version from this copy instead of discovering the document
|
|
58
|
-
*
|
|
59
|
-
*
|
|
60
|
-
*
|
|
61
|
-
* discovers afresh.
|
|
62
|
-
* @throws {ValidationError} when `
|
|
74
|
+
* selects its version from this copy instead of discovering the document,
|
|
75
|
+
* and still refuses it with `IncompatibleServerError` if it names no
|
|
76
|
+
* version this client speaks, or (for a client built from a base server
|
|
77
|
+
* URL) if it describes another server (see {@link service}).
|
|
78
|
+
* `service({ refresh: true })` discards it and discovers afresh.
|
|
79
|
+
* @throws {ValidationError} when `baseServerUrl` is not an absolute
|
|
80
|
+
* http(s) URL, or carries a query or fragment
|
|
63
81
|
*/
|
|
64
|
-
constructor(
|
|
65
|
-
serverUrl: string;
|
|
82
|
+
constructor(options: {
|
|
66
83
|
zcapClient: ZcapClient;
|
|
67
84
|
encryption?: EncryptionProvider;
|
|
68
85
|
serviceDescription?: ServiceDescription;
|
|
69
|
-
}
|
|
86
|
+
} & ({
|
|
87
|
+
baseServerUrl: string;
|
|
88
|
+
} | {
|
|
89
|
+
[fixedSpace]: string;
|
|
90
|
+
}));
|
|
91
|
+
/**
|
|
92
|
+
* Opens a client on a single fixed Space: a server that is one Space with
|
|
93
|
+
* no Space id and no base server URL (a personal site whose Collections are
|
|
94
|
+
* `https://alice.example/posts/`, `https://alice.example/images/`, ...).
|
|
95
|
+
* The service description is found by following the `service` link on an
|
|
96
|
+
* unsigned `HEAD` of the Space URL. The Space itself is
|
|
97
|
+
* `was.spaceAt(was.spaceUrl)`, and `collectionAt(url)` opens one of its
|
|
98
|
+
* Collections directly.
|
|
99
|
+
*
|
|
100
|
+
* Such a client has no base server URL, so `space(id)`, `createSpace()` and
|
|
101
|
+
* `listSpaces()` throw `NotSupportedError`. Everything Space-scoped
|
|
102
|
+
* (`spaceAt`, `collectionAt`, `fromCapability`, `grant`, `revoke`, the
|
|
103
|
+
* public reads) works as on any client. Whether the server lets a client
|
|
104
|
+
* create Collections is read from its `collection-management` feature
|
|
105
|
+
* token, as for every server.
|
|
106
|
+
*
|
|
107
|
+
* @param options {object}
|
|
108
|
+
* @param options.spaceUrl {string} the Space's absolute URL, which may be
|
|
109
|
+
* an origin root
|
|
110
|
+
* @param [options.zcapClient] {ZcapClient} an ezcap client holding the
|
|
111
|
+
* signer; one of `zcapClient` and `signer` is given
|
|
112
|
+
* @param [options.signer] {ISigner} a signer to build the `ZcapClient`
|
|
113
|
+
* from, as {@link fromSigner} does
|
|
114
|
+
* @param [options.encryption] {EncryptionProvider} see the constructor
|
|
115
|
+
* @param [options.serviceDescription] {ServiceDescription} see the
|
|
116
|
+
* constructor; not checked against the Space URL, which names no server
|
|
117
|
+
* @returns {WasClient}
|
|
118
|
+
* @throws {ValidationError} when `spaceUrl` is not a Space URL, or neither
|
|
119
|
+
* or both of `zcapClient` and `signer` are given
|
|
120
|
+
*/
|
|
121
|
+
static forSpace({ spaceUrl, zcapClient, signer, encryption, serviceDescription }: {
|
|
122
|
+
spaceUrl: string;
|
|
123
|
+
zcapClient?: ZcapClient;
|
|
124
|
+
signer?: ISigner;
|
|
125
|
+
encryption?: EncryptionProvider;
|
|
126
|
+
serviceDescription?: ServiceDescription;
|
|
127
|
+
}): WasClient;
|
|
70
128
|
/**
|
|
71
129
|
* Convenience constructor that builds the ezcap `ZcapClient` internally from
|
|
72
130
|
* a signer, using the `eddsa-jcs-2022` suite for delegation proofs.
|
|
@@ -77,15 +135,15 @@ export declare class WasClient {
|
|
|
77
135
|
* and never needs a JSON-LD document loader to serve the suite's context.
|
|
78
136
|
*
|
|
79
137
|
* @param options {object}
|
|
80
|
-
* @param options.
|
|
138
|
+
* @param options.baseServerUrl {string} see the constructor
|
|
81
139
|
* @param options.signer {ISigner}
|
|
82
140
|
* @param [options.encryption] {EncryptionProvider} see the constructor
|
|
83
141
|
* @param [options.serviceDescription] {ServiceDescription} see the
|
|
84
142
|
* constructor
|
|
85
143
|
* @returns {WasClient}
|
|
86
144
|
*/
|
|
87
|
-
static fromSigner({
|
|
88
|
-
|
|
145
|
+
static fromSigner({ baseServerUrl, signer, encryption, serviceDescription }: {
|
|
146
|
+
baseServerUrl: string;
|
|
89
147
|
signer: ISigner;
|
|
90
148
|
encryption?: EncryptionProvider;
|
|
91
149
|
serviceDescription?: ServiceDescription;
|
|
@@ -98,13 +156,15 @@ export declare class WasClient {
|
|
|
98
156
|
*/
|
|
99
157
|
get controllerDid(): string;
|
|
100
158
|
/**
|
|
101
|
-
*
|
|
102
|
-
* client speaks with it.
|
|
103
|
-
* an unsigned `
|
|
104
|
-
*
|
|
105
|
-
*
|
|
106
|
-
*
|
|
107
|
-
* the
|
|
159
|
+
* Reads the server's service description and selects the WAS version this
|
|
160
|
+
* client speaks with it. A client built from a base server URL reads
|
|
161
|
+
* `{base}service` with an unsigned `GET` and checks that the document
|
|
162
|
+
* describes that base (its `url` and `spaces` members agree with the
|
|
163
|
+
* layout); one built by {@link forSpace} follows the `rel="service"` link on
|
|
164
|
+
* the response to an unsigned `HEAD` of the Space URL. No capability is
|
|
165
|
+
* invoked. The result is memoized for the life of the client and shared by
|
|
166
|
+
* every handle; concurrent callers share one discovery, and a failure is
|
|
167
|
+
* not memoized, so the next call retries.
|
|
108
168
|
*
|
|
109
169
|
* Every signed request waits on this discovery, so a caller rarely needs to
|
|
110
170
|
* call it first. It is the way to read the server-wide affordances:
|
|
@@ -120,18 +180,22 @@ export declare class WasClient {
|
|
|
120
180
|
* caller about to rely on an affordance the server may have stopped
|
|
121
181
|
* advertising
|
|
122
182
|
* @returns {Promise<ServiceInfo>}
|
|
123
|
-
* @throws {IncompatibleServerError} when the
|
|
124
|
-
* `service` link (
|
|
125
|
-
* no version this client speaks, or it
|
|
126
|
-
*
|
|
183
|
+
* @throws {IncompatibleServerError} when the probed response carries no
|
|
184
|
+
* `service` link (the server predates v0.5), the document is malformed,
|
|
185
|
+
* it lists no version this client speaks, or it does not describe the
|
|
186
|
+
* server at this client's base server URL
|
|
127
187
|
*/
|
|
128
188
|
service(options?: {
|
|
129
189
|
refresh?: boolean;
|
|
130
190
|
}): Promise<ServiceInfo>;
|
|
131
191
|
/**
|
|
132
|
-
* Returns a lazy handle to a
|
|
192
|
+
* Returns a lazy handle to a Space by its absolute URL, as the server
|
|
193
|
+
* named it (the `Location` of the create response, a listing item's `url`,
|
|
194
|
+
* a stored pointer, or the URL a self-locating DID resolves to). No I/O.
|
|
195
|
+
* The URL is canonicalized (see `canonicalSpaceUrl` on the `./paths`
|
|
196
|
+
* entry), and every Collection and Resource URL derives from it.
|
|
133
197
|
*
|
|
134
|
-
* @param
|
|
198
|
+
* @param spaceUrl {string}
|
|
135
199
|
* @param options {object}
|
|
136
200
|
* @param [options.capability] {IZcap}
|
|
137
201
|
* @param [options.encryption] {EncryptionOverride} the default encryption
|
|
@@ -139,13 +203,51 @@ export declare class WasClient {
|
|
|
139
203
|
* `EncryptionOverride`); `space.collection(id, { encryption })` overrides
|
|
140
204
|
* it per collection
|
|
141
205
|
* @returns {Space}
|
|
206
|
+
* @throws {ValidationError} when `spaceUrl` is not a Space URL
|
|
207
|
+
*/
|
|
208
|
+
spaceAt(spaceUrl: string, options?: HandleOptions): Space;
|
|
209
|
+
/**
|
|
210
|
+
* Returns a lazy handle to the Space with id `spaceId` on this client's
|
|
211
|
+
* server, at `{base}space/{spaceId}/` as the spec's Server Layout places
|
|
212
|
+
* it. No I/O. The same handle as `spaceAt` opened on that URL; the Space
|
|
213
|
+
* need not exist yet (`space.configure(...)` with `ifNoneMatch` creates it
|
|
214
|
+
* by id).
|
|
215
|
+
*
|
|
216
|
+
* @param spaceId {string}
|
|
217
|
+
* @param options {object}
|
|
218
|
+
* @param [options.capability] {IZcap}
|
|
219
|
+
* @param [options.encryption] {EncryptionOverride} see {@link spaceAt}
|
|
220
|
+
* @returns {Space}
|
|
221
|
+
* @throws {NotSupportedError} on a client built by {@link forSpace}, which
|
|
222
|
+
* has no base server URL
|
|
223
|
+
* @throws {ValidationError} when `spaceId` is empty or a dot segment
|
|
142
224
|
*/
|
|
143
225
|
space(spaceId: string, options?: HandleOptions): Space;
|
|
226
|
+
/**
|
|
227
|
+
* Returns a lazy handle to a Collection by its absolute URL: the parent
|
|
228
|
+
* container is its Space and the last segment its id, so the handle is
|
|
229
|
+
* what `spaceAt(parent).collection(id)` would produce. No I/O. The direct
|
|
230
|
+
* route for a single fixed Space, where a caller typically holds the
|
|
231
|
+
* Collection URLs (`https://alice.example/posts/`) and nothing else.
|
|
232
|
+
*
|
|
233
|
+
* @param collectionUrl {string}
|
|
234
|
+
* @param options {object}
|
|
235
|
+
* @param [options.capability] {IZcap}
|
|
236
|
+
* @param [options.encryption] {EncryptionOverride}
|
|
237
|
+
* @returns {Collection}
|
|
238
|
+
* @throws {ValidationError} when `collectionUrl` is not a Collection URL
|
|
239
|
+
* (no path segment beneath its origin, a query or fragment), its last
|
|
240
|
+
* segment is a reserved Collection id, or it is not in canonical form
|
|
241
|
+
* (so the handle's requests would address a different URL)
|
|
242
|
+
*/
|
|
243
|
+
collectionAt(collectionUrl: string, options?: HandleOptions): Collection;
|
|
144
244
|
/**
|
|
145
245
|
* Creates a space (server-generated id unless `id` is given). `name` is
|
|
146
246
|
* optional (both in the spec and on the reference server); `controller` must
|
|
147
247
|
* match the wrapped signer's DID (which is the default). The request goes
|
|
148
|
-
* to the Spaces Repository
|
|
248
|
+
* to the Spaces Repository, `{base}spaces/`, and the returned handle is
|
|
249
|
+
* opened on the Space URL the response's `Location` names, as the server
|
|
250
|
+
* states it.
|
|
149
251
|
*
|
|
150
252
|
* @param desc {object}
|
|
151
253
|
* @param [desc.id] {string}
|
|
@@ -156,7 +258,9 @@ export declare class WasClient {
|
|
|
156
258
|
* 'Space']`). The server defaults it to `['Space']` and treats it as
|
|
157
259
|
* immutable after creation
|
|
158
260
|
* @returns {Promise<Space>}
|
|
159
|
-
* @throws {NotSupportedError} when the server has no Spaces Repository
|
|
261
|
+
* @throws {NotSupportedError} when the server has no Spaces Repository, or
|
|
262
|
+
* the client was built by {@link forSpace}
|
|
263
|
+
* @throws {WasServerError} when the create response carries no `Location`
|
|
160
264
|
*/
|
|
161
265
|
createSpace(desc?: {
|
|
162
266
|
id?: string;
|
|
@@ -171,7 +275,8 @@ export declare class WasClient {
|
|
|
171
275
|
* authorized for, auxiliary spaces included. Each item carries the space's
|
|
172
276
|
* `type` array, the same value as its Space Metadata object's `type`, so a
|
|
173
277
|
* caller can tell an auxiliary space (one whose `type` names
|
|
174
|
-
* `AuxiliarySpace`) from a user-data one without reading each space
|
|
278
|
+
* `AuxiliarySpace`) from a user-data one without reading each space, and
|
|
279
|
+
* its `url`, the Space URL to open a handle on with {@link spaceAt}.
|
|
175
280
|
* An unauthorized caller is not an error -- the server
|
|
176
281
|
* returns an empty `items` list (the spec's explicit exception to 404
|
|
177
282
|
* masking), so nothing is revealed about which spaces exist.
|
|
@@ -181,7 +286,8 @@ export declare class WasClient {
|
|
|
181
286
|
* `totalItems` counts the collected items.
|
|
182
287
|
*
|
|
183
288
|
* @returns {Promise<SpaceListing>}
|
|
184
|
-
* @throws {NotSupportedError} when the server has no Spaces Repository
|
|
289
|
+
* @throws {NotSupportedError} when the server has no Spaces Repository, or
|
|
290
|
+
* the client was built by {@link forSpace}
|
|
185
291
|
* @throws {WasServerError} when the listing cannot be read in full
|
|
186
292
|
*/
|
|
187
293
|
listSpaces(): Promise<SpaceListing>;
|
|
@@ -246,7 +352,15 @@ export declare class WasClient {
|
|
|
246
352
|
/**
|
|
247
353
|
* Rebuilds an access handle from a received capability, returning a handle at
|
|
248
354
|
* the depth implied by the capability's `invocationTarget` (space /
|
|
249
|
-
* collection / resource), pre-bound with that capability.
|
|
355
|
+
* collection / resource), pre-bound with that capability. The Space is read
|
|
356
|
+
* off the capability's delegation chain, which starts at the Space's root
|
|
357
|
+
* capability (whose id encodes the Space URL), so a capability from any
|
|
358
|
+
* server locates its own Space with no out-of-band base. The root's target
|
|
359
|
+
* is taken to be the Space URL: a Space URL has no shape of its own, so a
|
|
360
|
+
* chain rooted elsewhere (a bare `was.grant({ target })` for a server with
|
|
361
|
+
* no Space hierarchy roots at its target) is read as if that target were
|
|
362
|
+
* the Space, and the server refuses the handle's requests. See `spaceUrlOf`
|
|
363
|
+
* on the `./paths` entry.
|
|
250
364
|
*
|
|
251
365
|
* A resource-scoped capability cannot read the Collection Metadata object, so
|
|
252
366
|
* an encryption-capable client cannot discover whether the collection is
|
|
@@ -263,26 +377,37 @@ export declare class WasClient {
|
|
|
263
377
|
* @param [options.encryption] {EncryptionOverride} per-handle encryption
|
|
264
378
|
* override for the returned handle (see `EncryptionOverride`)
|
|
265
379
|
* @returns {Space | Collection | Resource}
|
|
380
|
+
* @throws {ValidationError} when the capability's chain starts at no root
|
|
381
|
+
* capability or at one whose target cannot be a Space URL, or its
|
|
382
|
+
* `invocationTarget` is not at or beneath that Space, addresses a
|
|
383
|
+
* reserved sub-resource with no navigational handle, or is not in
|
|
384
|
+
* canonical form (so the handle's requests would fall outside it)
|
|
266
385
|
*/
|
|
267
386
|
fromCapability(zcap: IZcap, { encryption }?: {
|
|
268
387
|
encryption?: EncryptionOverride;
|
|
269
388
|
}): Space | Collection | Resource;
|
|
270
389
|
/**
|
|
271
390
|
* The general delegation primitive. Delegates a capability per `GrantOptions`
|
|
272
|
-
* and returns the signed zcap to hand off out-of-band. `target` (any URL)
|
|
273
|
-
* `
|
|
274
|
-
*
|
|
391
|
+
* and returns the signed zcap to hand off out-of-band. `target` (any URL),
|
|
392
|
+
* `spaceUrl` (the Space to root a revocable grant in) and `capability` (a
|
|
393
|
+
* parent capability to attenuate) make this a superset of the
|
|
394
|
+
* `space`/`collection` grant sugar, which fills the first two from the
|
|
395
|
+
* handle. Without `spaceUrl` or `capability`, the grant is rooted at the
|
|
396
|
+
* target's own root capability: the shape for a server with no Space
|
|
397
|
+
* hierarchy (fixed collections, or resources alone), where there is no
|
|
398
|
+
* Space to root a chain in. Such a grant is not Space-revocable.
|
|
275
399
|
*
|
|
276
400
|
* @param options {GrantOptions}
|
|
277
401
|
* @returns {Promise<IDelegatedZcap>}
|
|
278
402
|
*/
|
|
279
403
|
grant(options: GrantOptions): Promise<IDelegatedZcap>;
|
|
280
404
|
/**
|
|
281
|
-
* The general revocation primitive -- the inverse of {@link grant}.
|
|
282
|
-
* the owning
|
|
283
|
-
*
|
|
284
|
-
*
|
|
285
|
-
* `
|
|
405
|
+
* The general revocation primitive -- the inverse of {@link grant}. Reads
|
|
406
|
+
* the owning Space off the capability's delegation chain (a Space-rooted
|
|
407
|
+
* chain starts at the Space's root capability) and submits it to that
|
|
408
|
+
* Space's revocation endpoint. Equivalent to `was.spaceAt(url).revoke(zcap)`.
|
|
409
|
+
* The chain root's target is taken to be the Space (see `spaceUrlOf` on the
|
|
410
|
+
* `./paths` entry); the server refuses a chain not rooted exactly in it.
|
|
286
411
|
*
|
|
287
412
|
* Revocation is scoped to one space: there is no cross-space or global
|
|
288
413
|
* revocation. See {@link Space.revoke} for who may call it, what it does and
|
|
@@ -290,12 +415,14 @@ export declare class WasClient {
|
|
|
290
415
|
*
|
|
291
416
|
* @param zcap {IDelegatedZcap} the delegated capability to revoke
|
|
292
417
|
* @returns {Promise<void>}
|
|
418
|
+
* @throws {ValidationError} when the capability's chain starts at no root
|
|
419
|
+
* capability, or at one whose target cannot be a Space URL
|
|
293
420
|
*/
|
|
294
421
|
revoke(zcap: IDelegatedZcap): Promise<void>;
|
|
295
422
|
/**
|
|
296
|
-
* The signed escape hatch, mirroring ezcap's generic `request()`.
|
|
297
|
-
*
|
|
298
|
-
*
|
|
423
|
+
* The signed escape hatch, mirroring ezcap's generic `request()`. Takes an
|
|
424
|
+
* absolute `url`, defaults `action` to `method`, uppercases both (as
|
|
425
|
+
* {@link grant} does, so `'put'` signs `PUT`), and signs via the wrapped
|
|
299
426
|
* client. Returns the raw `HttpResponse` and throws raw ky/ezcap
|
|
300
427
|
* errors -- it does not apply the null-on-404 or typed-error conveniences.
|
|
301
428
|
* Like every signed request it waits on {@link service} first, and rejects
|
|
@@ -306,4 +433,5 @@ export declare class WasClient {
|
|
|
306
433
|
*/
|
|
307
434
|
request(options: RequestInput): Promise<HttpResponse>;
|
|
308
435
|
}
|
|
436
|
+
export {};
|
|
309
437
|
//# sourceMappingURL=WasClient.d.ts.map
|
package/dist/WasClient.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"WasClient.d.ts","sourceRoot":"","sources":["../src/WasClient.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH
|
|
1
|
+
{"version":3,"file":"WasClient.d.ts","sourceRoot":"","sources":["../src/WasClient.ts"],"names":[],"mappings":"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"}
|