@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.
Files changed (111) hide show
  1. package/README.md +127 -69
  2. package/dist/Collection.d.ts +17 -9
  3. package/dist/Collection.d.ts.map +1 -1
  4. package/dist/Collection.js +85 -70
  5. package/dist/Collection.js.map +1 -1
  6. package/dist/Resource.d.ts +11 -4
  7. package/dist/Resource.d.ts.map +1 -1
  8. package/dist/Resource.js +34 -28
  9. package/dist/Resource.js.map +1 -1
  10. package/dist/Space.d.ts +20 -5
  11. package/dist/Space.d.ts.map +1 -1
  12. package/dist/Space.js +69 -65
  13. package/dist/Space.js.map +1 -1
  14. package/dist/WasClient.d.ts +185 -57
  15. package/dist/WasClient.d.ts.map +1 -1
  16. package/dist/WasClient.js +340 -140
  17. package/dist/WasClient.js.map +1 -1
  18. package/dist/codec.d.ts +3 -2
  19. package/dist/codec.d.ts.map +1 -1
  20. package/dist/edv/EdvCodec.js +1 -1
  21. package/dist/edv/EdvCodec.js.map +1 -1
  22. package/dist/edv/WasTransport.d.ts +7 -4
  23. package/dist/edv/WasTransport.d.ts.map +1 -1
  24. package/dist/edv/WasTransport.js +39 -20
  25. package/dist/edv/WasTransport.js.map +1 -1
  26. package/dist/edv/acquire.d.ts +3 -3
  27. package/dist/edv/acquire.d.ts.map +1 -1
  28. package/dist/edv/acquire.js +3 -3
  29. package/dist/edv/acquire.js.map +1 -1
  30. package/dist/edv/cipher.d.ts +1 -1
  31. package/dist/edv/cipher.js +1 -1
  32. package/dist/edv/docCipher.d.ts +6 -5
  33. package/dist/edv/docCipher.d.ts.map +1 -1
  34. package/dist/edv/docCipher.js +6 -5
  35. package/dist/edv/docCipher.js.map +1 -1
  36. package/dist/edv/encryption.d.ts +2 -2
  37. package/dist/edv/encryption.d.ts.map +1 -1
  38. package/dist/edv/encryption.js +8 -6
  39. package/dist/edv/encryption.js.map +1 -1
  40. package/dist/edv/refreshingDocCipher.d.ts +3 -3
  41. package/dist/edv/refreshingDocCipher.d.ts.map +1 -1
  42. package/dist/edv/refreshingDocCipher.js +3 -3
  43. package/dist/edv/refreshingDocCipher.js.map +1 -1
  44. package/dist/edv/transportFactory.d.ts +3 -3
  45. package/dist/edv/transportFactory.d.ts.map +1 -1
  46. package/dist/edv/transportFactory.js +3 -3
  47. package/dist/edv/transportFactory.js.map +1 -1
  48. package/dist/index.d.ts +1 -1
  49. package/dist/index.d.ts.map +1 -1
  50. package/dist/index.js +1 -1
  51. package/dist/index.js.map +1 -1
  52. package/dist/internal/codec.d.ts +7 -7
  53. package/dist/internal/codec.d.ts.map +1 -1
  54. package/dist/internal/codec.js +19 -18
  55. package/dist/internal/codec.js.map +1 -1
  56. package/dist/internal/conditional.d.ts +3 -3
  57. package/dist/internal/conditional.d.ts.map +1 -1
  58. package/dist/internal/conditional.js +5 -5
  59. package/dist/internal/conditional.js.map +1 -1
  60. package/dist/internal/grant.d.ts +15 -26
  61. package/dist/internal/grant.d.ts.map +1 -1
  62. package/dist/internal/grant.js +95 -29
  63. package/dist/internal/grant.js.map +1 -1
  64. package/dist/internal/meta.d.ts +8 -8
  65. package/dist/internal/meta.d.ts.map +1 -1
  66. package/dist/internal/meta.js +13 -10
  67. package/dist/internal/meta.js.map +1 -1
  68. package/dist/internal/paths.d.ts +423 -195
  69. package/dist/internal/paths.d.ts.map +1 -1
  70. package/dist/internal/paths.js +582 -369
  71. package/dist/internal/paths.js.map +1 -1
  72. package/dist/internal/policy.d.ts +23 -23
  73. package/dist/internal/policy.d.ts.map +1 -1
  74. package/dist/internal/policy.js +20 -20
  75. package/dist/internal/policy.js.map +1 -1
  76. package/dist/internal/request.d.ts +17 -21
  77. package/dist/internal/request.d.ts.map +1 -1
  78. package/dist/internal/request.js +10 -21
  79. package/dist/internal/request.js.map +1 -1
  80. package/dist/internal/reserved.d.ts +15 -3
  81. package/dist/internal/reserved.d.ts.map +1 -1
  82. package/dist/internal/reserved.js +37 -8
  83. package/dist/internal/reserved.js.map +1 -1
  84. package/dist/internal/revoke.d.ts +34 -13
  85. package/dist/internal/revoke.d.ts.map +1 -1
  86. package/dist/internal/revoke.js +97 -28
  87. package/dist/internal/revoke.js.map +1 -1
  88. package/dist/internal/service.d.ts +27 -7
  89. package/dist/internal/service.d.ts.map +1 -1
  90. package/dist/internal/service.js +51 -45
  91. package/dist/internal/service.js.map +1 -1
  92. package/dist/internal/write.d.ts +18 -18
  93. package/dist/internal/write.d.ts.map +1 -1
  94. package/dist/internal/write.js +27 -27
  95. package/dist/internal/write.js.map +1 -1
  96. package/dist/paths.d.ts +32 -25
  97. package/dist/paths.d.ts.map +1 -1
  98. package/dist/paths.js +32 -25
  99. package/dist/paths.js.map +1 -1
  100. package/dist/sync/port.d.ts +3 -3
  101. package/dist/sync/port.d.ts.map +1 -1
  102. package/dist/sync/port.js +12 -12
  103. package/dist/sync/port.js.map +1 -1
  104. package/dist/sync/provisioning.d.ts +10 -9
  105. package/dist/sync/provisioning.d.ts.map +1 -1
  106. package/dist/sync/provisioning.js +19 -18
  107. package/dist/sync/provisioning.js.map +1 -1
  108. package/dist/sync/types.d.ts +2 -2
  109. package/dist/types.d.ts +13 -5
  110. package/dist/types.d.ts.map +1 -1
  111. package/package.json +3 -3
@@ -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's Spaces Repository URL, in canonical trailing-slash form
25
- * (`https://host/spaces/`). Service discovery starts here.
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 serverUrl: string;
49
+ readonly baseServerUrl?: string;
28
50
  /**
29
- * The server base URL every Space path hangs off, without a trailing slash:
30
- * the parent of {@link serverUrl} (`https://host`, or `https://host/was` on
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 baseUrl: string;
54
+ readonly spaceUrl?: string;
34
55
  readonly zcapClient: ZcapClient;
35
56
  readonly encryption?: EncryptionProvider;
36
57
  /**
37
58
  * @param options {object}
38
- * @param options.serverUrl {string} the server's Spaces Repository URL
39
- * (`https://host/spaces/`, or `https://host/was/spaces/` on a sub-path
40
- * mount). The base URL for Space paths and zcap `invocationTarget`s is
41
- * its parent. Service discovery starts from this URL rather than from the
42
- * base, which is often a landing page with no `service` link. The value
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
- * from `serverUrl`, and still refuses it with `IncompatibleServerError` if
59
- * it names no version this client speaks or advertises a Spaces Repository
60
- * other than `serverUrl`. `service({ refresh: true })` discards it and
61
- * discovers afresh.
62
- * @throws {ValidationError} when `serverUrl` is not a Spaces Repository URL
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({ serverUrl, zcapClient, encryption, serviceDescription }: {
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.serverUrl {string}
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({ serverUrl, signer, encryption, serviceDescription }: {
88
- serverUrl: string;
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
- * Discovers the server's service description and the WAS version this
102
- * client speaks with it. Follows the `rel="service"` link on the response to
103
- * an unsigned `HEAD` of `serverUrl` (the Spaces Repository URL), then reads
104
- * the linked document with an unsigned `GET`. No capability is invoked. The
105
- * result is memoized for the life of the client and shared by every handle;
106
- * concurrent callers share one discovery, and a failure is not memoized, so
107
- * the next call retries.
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 server's responses carry no
124
- * `service` link (it predates v0.5), the document is malformed, it lists
125
- * no version this client speaks, or it advertises a Spaces Repository URL
126
- * other than `serverUrl`
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 space by id. No I/O.
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 spaceId {string}
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 URL the service description names.
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) and
273
- * `capability` (a parent capability to attenuate) make this a superset of the
274
- * `space`/`collection` grant sugar.
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}. Derives
282
- * the owning space from the capability's `invocationTarget` (which a
283
- * Space-rooted capability always addresses at or beneath) and submits it to
284
- * that space's revocation endpoint. Equivalent to
285
- * `was.space(id).revoke(zcap)`.
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()`. Resolves
297
- * `path` against `baseUrl`, defaults `action` to `method`, uppercases both
298
- * (as {@link grant} does, so `'put'` signs `PUT`), and signs via the wrapped
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
@@ -1 +1 @@
1
- {"version":3,"file":"WasClient.d.ts","sourceRoot":"","sources":["../src/WasClient.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"WasClient.d.ts","sourceRoot":"","sources":["../src/WasClient.ts"],"names":[],"mappings":"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"}