@interop/was-client 0.99.1 → 0.100.1

package/dist/WasClient.js

@@ -1,41 +1,46 @@
-import { baseUrlOfSpacesUrl, collectionItemsUrl, parseSpaceTarget, spacesUrl } from './internal/paths.js';
+import { isValidTarget } from '@interop/zcap';
+import { canonicalBaseServerUrl, canonicalContainerUrl, canonicalSpaceUrl, parseAbsoluteHttpUrl, parseSpaceTarget, serviceDescriptionUrl, spacesRepositoryUrl, spaceUrlById, splitCollectionUrl } from './internal/paths.js';
 import { send, rawRequest, unsignedRequest } from './internal/request.js';
-import { createdId, parseResource, readJsonData } from './internal/content.js';
+import { parseResource, readJsonData } from './internal/content.js';
 import { buildPageWalk, collectPages, collectWalk, signedPageWalk, walkItems, walkPagesOrEmpty } from './internal/pagination.js';
 import { delegateGrant } from './internal/grant.js';
-import { spaceIdOf, submitRevocation } from './internal/revoke.js';
+import { spaceUrlOf, submitRevocation } from './internal/revoke.js';
 import { Memo } from './internal/memo.js';
-import { discoverService, selectServiceVersion } from './internal/service.js';
+import { discoverService, readServiceDescription, selectServiceVersion } from './internal/service.js';
 import { IncompatibleServerError, NotSupportedError, ValidationError, WasServerError } from './errors.js';
 import { zcapClientForSigner } from './zcapClient.js';
 import { Space } from './Space.js';
 import { Collection } from './Collection.js';
 import { Resource } from './Resource.js';
+/**
+ * The module-private key under which {@link WasClient.forSpace} hands the
+ * constructor a Space URL in place of a base server URL. A `unique symbol`
+ * keeps that arm off the public constructor: a caller holding a Space URL goes
+ * through `forSpace`, which documents what such a client can and cannot do.
+ */
+const fixedSpace = Symbol('WasClient.forSpace');
 export class WasClient {
     /**
-     * The server's Spaces Repository URL, in canonical trailing-slash form
-     * (`https://host/spaces/`). Service discovery starts here.
+     * The base server URL the client was built from, in canonical form
+     * (trailing slash supplied): the URL under which the server lays out
+     * `service`, `spaces/` and `space/{space_id}/`. `undefined` for a client
+     * built by {@link WasClient.forSpace}, which has none.
      */
-    serverUrl;
+    baseServerUrl;
     /**
-     * The server base URL every Space path hangs off, without a trailing slash:
-     * the parent of {@link serverUrl} (`https://host`, or `https://host/was` on
-     * a sub-path mount). Zcap `invocationTarget`s are built beneath it.
+     * The Space URL a client built by {@link WasClient.forSpace} was opened on,
+     * in canonical form. `undefined` for a client built from a base server URL.
      */
-    baseUrl;
+    spaceUrl;
     zcapClient;
     encryption;
     /**
      * @param options {object}
-     * @param options.serverUrl {string}    the server's Spaces Repository URL
-     *   (`https://host/spaces/`, or `https://host/was/spaces/` on a sub-path
-     *   mount). The base URL for Space paths and zcap `invocationTarget`s is
-     *   its parent. Service discovery starts from this URL rather than from the
-     *   base, which is often a landing page with no `service` link. The value
-     *   is normalized to canonical form; `baseUrlOfSpacesUrl` in `./paths`
-     *   states what is accepted. The client is built from this URL only: a
-     *   server with no Spaces Repository (the spec leaves the endpoint
-     *   optional) has no URL this constructor accepts and is not supported.
+     * @param options.baseServerUrl {string}   the server's base server URL: an
+     *   absolute http(s) URL with no query or fragment, under which the server
+     *   serves `service`, `spaces/` and `space/{space_id}/`. A missing trailing
+     *   slash is supplied. For a server that is one fixed Space with no base,
+     *   use {@link WasClient.forSpace} instead
      * @param options.zcapClient {ZcapClient}   an ezcap client holding the signer
      * @param [options.encryption] {EncryptionProvider}   the keystore that
      *   supplies keys for collections declared encrypted (by their `encryption`
@@ -46,25 +51,65 @@ export class WasClient {
      *   closed rather than silently downgrading to plaintext.
      * @param [options.serviceDescription] {ServiceDescription}   a service
      *   description the caller already holds (from a cache, say). The client
-     *   selects its version from this copy instead of discovering the document
-     *   from `serverUrl`, and still refuses it with `IncompatibleServerError` if
-     *   it names no version this client speaks or advertises a Spaces Repository
-     *   other than `serverUrl`. `service({ refresh: true })` discards it and
-     *   discovers afresh.
-     * @throws {ValidationError}   when `serverUrl` is not a Spaces Repository URL
+     *   selects its version from this copy instead of discovering the document,
+     *   and still refuses it with `IncompatibleServerError` if it names no
+     *   version this client speaks, or (for a client built from a base server
+     *   URL) if it describes another server (see {@link service}).
+     *   `service({ refresh: true })` discards it and discovers afresh.
+     * @throws {ValidationError}   when `baseServerUrl` is not an absolute
+     *   http(s) URL, or carries a query or fragment
      */
-    constructor({ serverUrl, zcapClient, encryption, serviceDescription }) {
-        const baseUrl = baseUrlOfSpacesUrl(serverUrl);
-        if (baseUrl === null) {
-            throw new ValidationError(`serverUrl "${serverUrl}" is not a Spaces Repository URL. Pass the ` +
-                "server's `/spaces/` URL as an absolute URL, for example " +
-                '"https://host/spaces/".');
+    constructor(options) {
+        if (fixedSpace in options) {
+            this.spaceUrl = canonicalSpaceUrl(options[fixedSpace]);
         }
-        this.serverUrl = spacesUrl({ baseUrl });
-        this.baseUrl = baseUrl;
-        this.zcapClient = zcapClient;
-        this.encryption = encryption;
-        this.#serviceDescription = serviceDescription;
+        else {
+            this.baseServerUrl = canonicalBaseServerUrl(options.baseServerUrl);
+        }
+        this.zcapClient = options.zcapClient;
+        this.encryption = options.encryption;
+        this.#serviceDescription = options.serviceDescription;
+    }
+    /**
+     * Opens a client on a single fixed Space: a server that is one Space with
+     * no Space id and no base server URL (a personal site whose Collections are
+     * `https://alice.example/posts/`, `https://alice.example/images/`, ...).
+     * The service description is found by following the `service` link on an
+     * unsigned `HEAD` of the Space URL. The Space itself is
+     * `was.spaceAt(was.spaceUrl)`, and `collectionAt(url)` opens one of its
+     * Collections directly.
+     *
+     * Such a client has no base server URL, so `space(id)`, `createSpace()` and
+     * `listSpaces()` throw `NotSupportedError`. Everything Space-scoped
+     * (`spaceAt`, `collectionAt`, `fromCapability`, `grant`, `revoke`, the
+     * public reads) works as on any client. Whether the server lets a client
+     * create Collections is read from its `collection-management` feature
+     * token, as for every server.
+     *
+     * @param options {object}
+     * @param options.spaceUrl {string}   the Space's absolute URL, which may be
+     *   an origin root
+     * @param [options.zcapClient] {ZcapClient}   an ezcap client holding the
+     *   signer; one of `zcapClient` and `signer` is given
+     * @param [options.signer] {ISigner}   a signer to build the `ZcapClient`
+     *   from, as {@link fromSigner} does
+     * @param [options.encryption] {EncryptionProvider}   see the constructor
+     * @param [options.serviceDescription] {ServiceDescription}   see the
+     *   constructor; not checked against the Space URL, which names no server
+     * @returns {WasClient}
+     * @throws {ValidationError}   when `spaceUrl` is not a Space URL, or neither
+     *   or both of `zcapClient` and `signer` are given
+     */
+    static forSpace({ spaceUrl, zcapClient, signer, encryption, serviceDescription }) {
+        if ((zcapClient === undefined) === (signer === undefined)) {
+            throw new ValidationError('WasClient.forSpace takes exactly one of `zcapClient` and `signer`.');
+        }
+        return new WasClient({
+            [fixedSpace]: spaceUrl,
+            zcapClient: zcapClient ?? zcapClientForSigner({ signer: signer }),
+            encryption,
+            serviceDescription
+        });
     }
     /**
      * Convenience constructor that builds the ezcap `ZcapClient` internally from
@@ -76,16 +121,16 @@ export class WasClient {
      * and never needs a JSON-LD document loader to serve the suite's context.
      *
      * @param options {object}
-     * @param options.serverUrl {string}
+     * @param options.baseServerUrl {string}   see the constructor
      * @param options.signer {ISigner}
      * @param [options.encryption] {EncryptionProvider}   see the constructor
      * @param [options.serviceDescription] {ServiceDescription}   see the
      *   constructor
      * @returns {WasClient}
      */
-    static fromSigner({ serverUrl, signer, encryption, serviceDescription }) {
+    static fromSigner({ baseServerUrl, signer, encryption, serviceDescription }) {
         return new WasClient({
-            serverUrl,
+            baseServerUrl,
             zcapClient: zcapClientForSigner({ signer }),
             encryption,
             serviceDescription
@@ -106,35 +151,71 @@ export class WasClient {
     }
     #serviceDescription;
     #service = new Memo(async () => {
-        const info = this.#serviceDescription === undefined
-            ? await discoverService({ url: this.serverUrl })
-            : selectServiceVersion(this.#serviceDescription);
-        // Every Space path is built beneath the parent of `serverUrl`, so a server
-        // that advertises its Spaces Repository elsewhere would be addressed at
-        // the wrong mount. Refuse it by name rather than misroute. Both sides are
-        // compared in canonical base-URL form, so an advertised value that differs
-        // only in serialization (host case, default port, trailing slash) passes.
-        if (info.spacesUrl !== undefined) {
-            const advertisedBase = baseUrlOfSpacesUrl(info.spacesUrl);
-            if (advertisedBase !== this.baseUrl) {
-                const why = advertisedBase === null
-                    ? `which is not a Spaces Repository URL (an absolute http(s) ` +
-                        `URL ending in a "spaces" segment, with no query or fragment).`
-                    : `but this client was given "${this.serverUrl}".`;
-                throw new IncompatibleServerError(`The server advertises its Spaces Repository at ` +
-                    `"${info.spacesUrl}", ${why}`, { requestUrl: this.serverUrl });
-            }
+        let info;
+        if (this.#serviceDescription !== undefined) {
+            info = selectServiceVersion(this.#serviceDescription);
         }
+        else if (this.baseServerUrl !== undefined) {
+            info = await readServiceDescription({
+                serviceUrl: serviceDescriptionUrl({
+                    baseServerUrl: this.baseServerUrl
+                })
+            });
+        }
+        else {
+            info = await discoverService({ url: this.spaceUrl });
+        }
+        this.#assertDescribesThisServer(info);
         return info;
     });
     /**
-     * Discovers the server's service description and the WAS version this
-     * client speaks with it. Follows the `rel="service"` link on the response to
-     * an unsigned `HEAD` of `serverUrl` (the Spaces Repository URL), then reads
-     * the linked document with an unsigned `GET`. No capability is invoked. The
-     * result is memoized for the life of the client and shared by every handle;
-     * concurrent callers share one discovery, and a failure is not memoized, so
-     * the next call retries.
+     * Refuses a service description that does not describe the server at this
+     * client's base server URL: its `url` must be `{base}service` and its
+     * `spaces` member, when present, `{base}spaces/`. A caller-supplied copy
+     * keyed wrongly or kept across deployments, or a base that names a
+     * different mount than the server's, would otherwise fail later with a 404
+     * deep in a Space; refusing here names both values. A client built by
+     * {@link forSpace} has no base and is not checked.
+     *
+     * @param info {ServiceInfo}
+     * @throws {IncompatibleServerError}
+     */
+    #assertDescribesThisServer(info) {
+        if (this.baseServerUrl === undefined) {
+            return;
+        }
+        const expectedUrl = serviceDescriptionUrl({
+            baseServerUrl: this.baseServerUrl
+        });
+        const describedUrl = parseAbsoluteHttpUrl(info.description.url)?.toString();
+        if (describedUrl !== expectedUrl) {
+            throw new IncompatibleServerError(`The service description names itself "${info.description.url}", ` +
+                `but the base server URL "${this.baseServerUrl}" places it at ` +
+                `"${expectedUrl}".`);
+        }
+        if (info.spacesUrl === undefined) {
+            return;
+        }
+        const expectedSpaces = spacesRepositoryUrl({
+            baseServerUrl: this.baseServerUrl
+        });
+        // `selectServiceVersion` stores `spacesUrl` in canonical container form.
+        if (info.spacesUrl !== expectedSpaces) {
+            throw new IncompatibleServerError(`The service description names the Spaces Repository ` +
+                `"${info.spacesUrl}", but the base server URL ` +
+                `"${this.baseServerUrl}" places it at "${expectedSpaces}".`);
+        }
+    }
+    /**
+     * Reads the server's service description and selects the WAS version this
+     * client speaks with it. A client built from a base server URL reads
+     * `{base}service` with an unsigned `GET` and checks that the document
+     * describes that base (its `url` and `spaces` members agree with the
+     * layout); one built by {@link forSpace} follows the `rel="service"` link on
+     * the response to an unsigned `HEAD` of the Space URL. No capability is
+     * invoked. The result is memoized for the life of the client and shared by
+     * every handle; concurrent callers share one discovery, and a failure is
+     * not memoized, so the next call retries.
      *
      * Every signed request waits on this discovery, so a caller rarely needs to
      * call it first. It is the way to read the server-wide affordances:
@@ -150,10 +231,10 @@ export class WasClient {
      *   caller about to rely on an affordance the server may have stopped
      *   advertising
      * @returns {Promise<ServiceInfo>}
-     * @throws {IncompatibleServerError}   when the server's responses carry no
-     *   `service` link (it predates v0.5), the document is malformed, it lists
-     *   no version this client speaks, or it advertises a Spaces Repository URL
-     *   other than `serverUrl`
+     * @throws {IncompatibleServerError}   when the probed response carries no
+     *   `service` link (the server predates v0.5), the document is malformed,
+     *   it lists no version this client speaks, or it does not describe the
+     *   server at this client's base server URL
      */
     async service(options = {}) {
         if (options.refresh) {
@@ -163,31 +244,48 @@ export class WasClient {
         return this.#service.get();
     }
     /**
-     * Waits for discovery and refuses a server whose service description has no
-     * Spaces Repository. Discovery has already checked that an advertised
-     * `spaces` URL names `serverUrl`, so callers address `serverUrl` directly.
+     * The base server URL, or the `NotSupportedError` a client built by
+     * {@link forSpace} throws from every id-addressed operation.
      *
-     * @returns {Promise<void>}
-     * @throws {NotSupportedError}   when the server does not implement the
-     *   Spaces Repository
+     * @param operation {string}   the operation's name, for the error
+     * @returns {string}
+     * @throws {NotSupportedError}
+     */
+    #requireBase(operation) {
+        if (this.baseServerUrl === undefined) {
+            throw new NotSupportedError(`${operation} needs a base server URL, and this client was opened ` +
+                `on the single fixed Space "${this.spaceUrl}", which has none.`);
+        }
+        return this.baseServerUrl;
+    }
+    /**
+     * The Spaces Repository URL the service description names, which the
+     * layout check in discovery has already confirmed is `{base}spaces/`
+     * (every signed request waits on discovery anyway).
+     *
+     * @param operation {string}   the operation's name, for the error
+     * @returns {Promise<string>}
+     * @throws {NotSupportedError}   when the client has no base server URL, or
+     *   the server does not implement the Spaces Repository
      */
-    async #assertSpacesRepository() {
-        const { spacesUrl, version } = await this.service();
+    async #spacesRepositoryUrl(operation) {
+        this.#requireBase(operation);
+        const { spacesUrl, version, description } = await this.service();
         if (spacesUrl === undefined) {
-            throw new NotSupportedError(`The server at "${this.baseUrl}" does not implement the Spaces ` +
+            throw new NotSupportedError(`The server at "${description.url}" does not implement the Spaces ` +
                 `Repository: its WAS ${version} service description entry has no ` +
                 '`spaces` URL.');
         }
+        return spacesUrl;
     }
     #cachedContext;
     get #context() {
-        // `baseUrl`, `zcapClient` and `encryption` are all constructor-fixed, so
-        // the context is derived once and reused rather than reallocating the
-        // object on every handle access.
+        // `zcapClient` and `encryption` are constructor-fixed, so the context is
+        // derived once and reused rather than reallocating the object on every
+        // handle access.
         if (this.#cachedContext === undefined) {
             const readControllerDid = () => this.controllerDid;
             this.#cachedContext = {
-                baseUrl: this.baseUrl,
                 zcapClient: this.zcapClient,
                 // Read lazily, so building a handle costs nothing and a
                 // delegation-only client (a `ZcapClient` with a delegation signer and
@@ -204,9 +302,13 @@ export class WasClient {
         return this.#cachedContext;
     }
     /**
-     * Returns a lazy handle to a space by id. No I/O.
+     * Returns a lazy handle to a Space by its absolute URL, as the server
+     * named it (the `Location` of the create response, a listing item's `url`,
+     * a stored pointer, or the URL a self-locating DID resolves to). No I/O.
+     * The URL is canonicalized (see `canonicalSpaceUrl` on the `./paths`
+     * entry), and every Collection and Resource URL derives from it.
      *
-     * @param spaceId {string}
+     * @param spaceUrl {string}
      * @param options {object}
      * @param [options.capability] {IZcap}
      * @param [options.encryption] {EncryptionOverride}   the default encryption
@@ -214,20 +316,81 @@ export class WasClient {
      *   `EncryptionOverride`); `space.collection(id, { encryption })` overrides
      *   it per collection
      * @returns {Space}
+     * @throws {ValidationError}   when `spaceUrl` is not a Space URL
      */
-    space(spaceId, options = {}) {
+    spaceAt(spaceUrl, options = {}) {
         return new Space({
             context: this.#context,
-            spaceId,
+            spaceUrl,
             capability: options.capability,
             encryption: options.encryption
         });
     }
+    /**
+     * Returns a lazy handle to the Space with id `spaceId` on this client's
+     * server, at `{base}space/{spaceId}/` as the spec's Server Layout places
+     * it. No I/O. The same handle as `spaceAt` opened on that URL; the Space
+     * need not exist yet (`space.configure(...)` with `ifNoneMatch` creates it
+     * by id).
+     *
+     * @param spaceId {string}
+     * @param options {object}
+     * @param [options.capability] {IZcap}
+     * @param [options.encryption] {EncryptionOverride}   see {@link spaceAt}
+     * @returns {Space}
+     * @throws {NotSupportedError}   on a client built by {@link forSpace}, which
+     *   has no base server URL
+     * @throws {ValidationError}   when `spaceId` is empty or a dot segment
+     */
+    space(spaceId, options = {}) {
+        const baseServerUrl = this.#requireBase('space(id)');
+        return this.spaceAt(spaceUrlById({ baseServerUrl, spaceId }), options);
+    }
+    /**
+     * Returns a lazy handle to a Collection by its absolute URL: the parent
+     * container is its Space and the last segment its id, so the handle is
+     * what `spaceAt(parent).collection(id)` would produce. No I/O. The direct
+     * route for a single fixed Space, where a caller typically holds the
+     * Collection URLs (`https://alice.example/posts/`) and nothing else.
+     *
+     * @param collectionUrl {string}
+     * @param options {object}
+     * @param [options.capability] {IZcap}
+     * @param [options.encryption] {EncryptionOverride}
+     * @returns {Collection}
+     * @throws {ValidationError}   when `collectionUrl` is not a Collection URL
+     *   (no path segment beneath its origin, a query or fragment), its last
+     *   segment is a reserved Collection id, or it is not in canonical form
+     *   (so the handle's requests would address a different URL)
+     */
+    collectionAt(collectionUrl, options = {}) {
+        const { spaceUrl, collectionId } = splitCollectionUrl(collectionUrl);
+        const handle = new Collection({
+            context: this.#context,
+            spaceUrl,
+            collectionId,
+            capability: options.capability,
+            encryption: options.encryption
+        });
+        // The handle re-encodes the decoded id, so a URL whose last segment is
+        // serialized differently (`%21` for `!`, lower-case hex) would build a
+        // handle at another URL: one a bound capability does not cover, and
+        // whose root capability id the server never minted. Refuse it, by name,
+        // as `fromCapability` does for a non-canonical target.
+        const expected = canonicalContainerUrl(collectionUrl);
+        if (handle.url !== expected) {
+            throw new ValidationError(`"${collectionUrl}" is not in canonical form: the handle would ` +
+                `address "${handle.url}" instead.`);
+        }
+        return handle;
+    }
     /**
      * Creates a space (server-generated id unless `id` is given). `name` is
      * optional (both in the spec and on the reference server); `controller` must
      * match the wrapped signer's DID (which is the default). The request goes
-     * to the Spaces Repository URL the service description names.
+     * to the Spaces Repository, `{base}spaces/`, and the returned handle is
+     * opened on the Space URL the response's `Location` names, as the server
+     * states it.
      *
      * @param desc {object}
      * @param [desc.id] {string}
@@ -238,7 +401,9 @@ export class WasClient {
      *   'Space']`). The server defaults it to `['Space']` and treats it as
      *   immutable after creation
      * @returns {Promise<Space>}
-     * @throws {NotSupportedError}   when the server has no Spaces Repository
+     * @throws {NotSupportedError}   when the server has no Spaces Repository, or
+     *   the client was built by {@link forSpace}
+     * @throws {WasServerError}   when the create response carries no `Location`
      */
     async createSpace(desc = {}) {
         const controller = desc.controller ?? this.controllerDid;
@@ -248,13 +413,22 @@ export class WasClient {
             ...(desc.name !== undefined && { name: desc.name }),
             ...(desc.type !== undefined && { type: desc.type })
         };
-        await this.#assertSpacesRepository();
+        const spacesUrl = await this.#spacesRepositoryUrl('createSpace');
         const response = await send(this.#context, {
-            url: this.serverUrl,
+            url: spacesUrl,
             method: 'POST',
             json: body
         });
-        return this.space(createdId(response));
+        // Only the `Location` is needed here: the Space id is read off the Space
+        // URL by the handle, so the response body's `id` goes unread.
+        const location = response?.headers.get('location');
+        if (!location) {
+            throw new WasServerError(`The Create Space response from "${spacesUrl}" carries no ` +
+                '`Location` header, so the new Space cannot be located.');
+        }
+        // RFC 9110 permits a relative `Location`; resolve it against the request
+        // URL so the handle is opened on an absolute Space URL.
+        return this.spaceAt(new URL(location, spacesUrl).toString());
     }
     /**
      * Lists the spaces in the repository visible to the wrapped signer, as a
@@ -263,7 +437,8 @@ export class WasClient {
      * authorized for, auxiliary spaces included. Each item carries the space's
      * `type` array, the same value as its Space Metadata object's `type`, so a
      * caller can tell an auxiliary space (one whose `type` names
-     * `AuxiliarySpace`) from a user-data one without reading each space.
+     * `AuxiliarySpace`) from a user-data one without reading each space, and
+     * its `url`, the Space URL to open a handle on with {@link spaceAt}.
      * An unauthorized caller is not an error -- the server
      * returns an empty `items` list (the spec's explicit exception to 404
      * masking), so nothing is revealed about which spaces exist.
@@ -273,13 +448,14 @@ export class WasClient {
      * `totalItems` counts the collected items.
      *
      * @returns {Promise<SpaceListing>}
-     * @throws {NotSupportedError}   when the server has no Spaces Repository
+     * @throws {NotSupportedError}   when the server has no Spaces Repository, or
+     *   the client was built by {@link forSpace}
      * @throws {WasServerError}   when the listing cannot be read in full
      */
     async listSpaces() {
-        await this.#assertSpacesRepository();
+        const spacesUrl = await this.#spacesRepositoryUrl('listSpaces');
         const walk = await signedPageWalk(this.#context, {
-            firstUrl: this.serverUrl
+            firstUrl: spacesUrl
         });
         // The first page always carries the listing body (an unauthorized caller
         // still gets an empty `items` list, not an error), so a `null` walk is a
@@ -287,7 +463,7 @@ export class WasClient {
         // body did not parse as JSON. Report it as one, rather than as a
         // `TypeError` from destructuring `null`.
         if (walk === null) {
-            throw new WasServerError(`The space listing at "${this.serverUrl}" answered with no JSON body.`);
+            throw new WasServerError(`The space listing at "${spacesUrl}" answered with no JSON body.`);
         }
         return collectPages(walk);
     }
@@ -321,7 +497,7 @@ export class WasClient {
     async #publicListWalk(collectionUrl) {
         return buildPageWalk({
             // The collection listing endpoint is the trailing-slash items URL.
-            firstUrl: collectionItemsUrl(collectionUrl),
+            firstUrl: canonicalContainerUrl(collectionUrl),
             fetchPage: async (pageUrl) => {
                 const pageResponse = await unsignedRequest({
                     url: pageUrl,
@@ -384,7 +560,15 @@ export class WasClient {
     /**
      * Rebuilds an access handle from a received capability, returning a handle at
      * the depth implied by the capability's `invocationTarget` (space /
-     * collection / resource), pre-bound with that capability.
+     * collection / resource), pre-bound with that capability. The Space is read
+     * off the capability's delegation chain, which starts at the Space's root
+     * capability (whose id encodes the Space URL), so a capability from any
+     * server locates its own Space with no out-of-band base. The root's target
+     * is taken to be the Space URL: a Space URL has no shape of its own, so a
+     * chain rooted elsewhere (a bare `was.grant({ target })` for a server with
+     * no Space hierarchy roots at its target) is read as if that target were
+     * the Space, and the server refuses the handle's requests. See `spaceUrlOf`
+     * on the `./paths` entry.
      *
      * A resource-scoped capability cannot read the Collection Metadata object, so
      * an encryption-capable client cannot discover whether the collection is
@@ -401,28 +585,26 @@ export class WasClient {
      * @param [options.encryption] {EncryptionOverride}   per-handle encryption
      *   override for the returned handle (see `EncryptionOverride`)
      * @returns {Space | Collection | Resource}
+     * @throws {ValidationError}   when the capability's chain starts at no root
+     *   capability or at one whose target cannot be a Space URL, or its
+     *   `invocationTarget` is not at or beneath that Space, addresses a
+     *   reserved sub-resource with no navigational handle, or is not in
+     *   canonical form (so the handle's requests would fall outside it)
      */
     fromCapability(zcap, { encryption } = {}) {
         const target = zcap.invocationTarget;
-        try {
-            new URL(target);
-        }
-        catch (err) {
-            throw new ValidationError(`invocationTarget "${target}" is not a valid absolute URL.`, { cause: err });
-        }
-        // `parseSpaceTarget` owns the path grammar: it strips `baseUrl`'s path
-        // first (so a WAS mounted under a sub-path -- `https://host/was/` --
-        // classifies just as a bare-origin deployment does, which `parseSpacePath`
-        // alone cannot) and percent-decodes each segment, since the path builders
-        // re-encode every id. Classifying the full segment list -- rather than
-        // destructuring the first three ids -- keeps a sub-resource target
-        // (`/space/s/policy`, `/space/s/c/r/meta`, ...) from being silently
-        // truncated to the nearest containment handle, whose derived URLs would
-        // mismatch the capability's invocation target.
-        const parsed = parseSpaceTarget({ baseUrl: this.baseUrl, target });
+        const spaceUrl = spaceUrlOf(zcap);
+        // `parseSpaceTarget` owns the grammar beneath a Space: it percent-decodes
+        // each segment (the builders re-encode every id) and classifies the full
+        // segment list, so a sub-resource target (`{s}policy`, `{s}{c}/{r}/meta`,
+        // ...) is refused rather than silently truncated to the nearest
+        // containment handle, whose derived URLs would mismatch the capability's
+        // invocation target.
+        const parsed = parseSpaceTarget({ spaceUrl, target });
         if (parsed === null) {
             throw new ValidationError(`Cannot derive a handle from invocationTarget "${target}": it does ` +
-                `not address a resource on "${this.baseUrl}".`);
+                `not address anything at or beneath the Space "${spaceUrl}" the ` +
+                'capability is rooted in.');
         }
         if (parsed.kind === 'sub-resource') {
             throw new ValidationError(`invocationTarget "${target}" addresses a reserved ` +
@@ -431,37 +613,53 @@ export class WasClient {
                 '`resource.meta()`), or use the `was.request()` escape hatch.');
         }
         const context = this.#context;
+        let handle;
         if (parsed.kind === 'resource') {
-            return new Resource({
+            handle = new Resource({
                 context,
-                spaceId: parsed.spaceId,
+                spaceUrl,
                 collectionId: parsed.collectionId,
                 resourceId: parsed.resourceId,
                 capability: zcap,
                 encryption
             });
         }
-        if (parsed.kind === 'collection') {
-            return new Collection({
+        else if (parsed.kind === 'collection') {
+            handle = new Collection({
                 context,
-                spaceId: parsed.spaceId,
+                spaceUrl,
                 collectionId: parsed.collectionId,
                 capability: zcap,
                 encryption
             });
         }
-        return new Space({
-            context,
-            spaceId: parsed.spaceId,
-            capability: zcap,
-            encryption
-        });
+        else {
+            handle = new Space({ context, spaceUrl, capability: zcap, encryption });
+        }
+        // `send` matches every request URL against the capability's target by
+        // string prefix, so a target in a non-canonical serialization (upper-case
+        // host, explicit default port) would let the handle be built and then
+        // refuse every request from it. Refuse it here, by name.
+        if (!isValidTarget({
+            invocationTarget: handle.url,
+            baseInvocationTarget: target,
+            allowTargetAttenuation: true
+        })) {
+            throw new ValidationError(`invocationTarget "${target}" is not in canonical form: the handle ` +
+                `would address "${handle.url}", which the capability does not cover.`);
+        }
+        return handle;
     }
     /**
      * The general delegation primitive. Delegates a capability per `GrantOptions`
-     * and returns the signed zcap to hand off out-of-band. `target` (any URL) and
-     * `capability` (a parent capability to attenuate) make this a superset of the
-     * `space`/`collection` grant sugar.
+     * and returns the signed zcap to hand off out-of-band. `target` (any URL),
+     * `spaceUrl` (the Space to root a revocable grant in) and `capability` (a
+     * parent capability to attenuate) make this a superset of the
+     * `space`/`collection` grant sugar, which fills the first two from the
+     * handle. Without `spaceUrl` or `capability`, the grant is rooted at the
+     * target's own root capability: the shape for a server with no Space
+     * hierarchy (fixed collections, or resources alone), where there is no
+     * Space to root a chain in. Such a grant is not Space-revocable.
      *
      * @param options {GrantOptions}
      * @returns {Promise<IDelegatedZcap>}
@@ -470,11 +668,12 @@ export class WasClient {
         return delegateGrant(this.#context, options);
     }
     /**
-     * The general revocation primitive -- the inverse of {@link grant}. Derives
-     * the owning space from the capability's `invocationTarget` (which a
-     * Space-rooted capability always addresses at or beneath) and submits it to
-     * that space's revocation endpoint. Equivalent to
-     * `was.space(id).revoke(zcap)`.
+     * The general revocation primitive -- the inverse of {@link grant}. Reads
+     * the owning Space off the capability's delegation chain (a Space-rooted
+     * chain starts at the Space's root capability) and submits it to that
+     * Space's revocation endpoint. Equivalent to `was.spaceAt(url).revoke(zcap)`.
+     * The chain root's target is taken to be the Space (see `spaceUrlOf` on the
+     * `./paths` entry); the server refuses a chain not rooted exactly in it.
      *
      * Revocation is scoped to one space: there is no cross-space or global
      * revocation. See {@link Space.revoke} for who may call it, what it does and
@@ -482,18 +681,19 @@ export class WasClient {
      *
      * @param zcap {IDelegatedZcap}   the delegated capability to revoke
      * @returns {Promise<void>}
+     * @throws {ValidationError}   when the capability's chain starts at no root
+     *   capability, or at one whose target cannot be a Space URL
      */
     async revoke(zcap) {
-        const context = this.#context;
-        return submitRevocation(context, {
-            spaceId: spaceIdOf(context, zcap),
+        return submitRevocation(this.#context, {
+            spaceUrl: spaceUrlOf(zcap),
             zcap
         });
     }
     /**
-     * The signed escape hatch, mirroring ezcap's generic `request()`. Resolves
-     * `path` against `baseUrl`, defaults `action` to `method`, uppercases both
-     * (as {@link grant} does, so `'put'` signs `PUT`), and signs via the wrapped
+     * The signed escape hatch, mirroring ezcap's generic `request()`. Takes an
+     * absolute `url`, defaults `action` to `method`, uppercases both (as
+     * {@link grant} does, so `'put'` signs `PUT`), and signs via the wrapped
      * client. Returns the raw `HttpResponse` and throws raw ky/ezcap
      * errors -- it does not apply the null-on-404 or typed-error conveniences.
      * Like every signed request it waits on {@link service} first, and rejects