@interop/was-client 0.9.1 → 0.10.0

package/dist/edv/index.d.ts

@@ -18,5 +18,5 @@
  */
 export { createEdvEncryption, EdvCodec } from './EdvCodec.js';
 export type { EdvKeys } from './EdvCodec.js';
-export { WasTransport, EDV_CONTENT_TYPE } from './WasTransport.js';
+export { WasTransport, JOSE_CONTENT_TYPE } from './WasTransport.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/edv/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/edv/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7D,YAAY,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/edv/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7D,YAAY,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/edv/index.js

@@ -17,5 +17,5 @@
  *   transport, for driving an `EdvClient` directly against WAS.
  */
 export { createEdvEncryption, EdvCodec } from './EdvCodec.js';
-export { WasTransport, EDV_CONTENT_TYPE } from './WasTransport.js';
+export { WasTransport, JOSE_CONTENT_TYPE } from './WasTransport.js';
 //# sourceMappingURL=index.js.map

package/dist/edv/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/edv/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAE7D,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/edv/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAE7D,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/errors.d.ts

@@ -40,7 +40,9 @@ export declare class ValidationError extends WasError {
     constructor(message: string, options?: WasErrorOptions);
 }
 /**
- * Authorization headers were missing or could not be verified (HTTP 401).
+ * Authorization headers were missing or could not be verified (HTTP 401), or
+ * the caller is authenticated but not permitted to act on the target (HTTP
+ * 403).
  */
 export declare class AuthRequiredError extends WasError {
     constructor(message: string, options?: WasErrorOptions);

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAWA;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAA;gBAEP,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAU3D;AAED;;;;GAIG;AACH,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAI3D;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;gBAC/B,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAI3D;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,QAAQ;gBACjC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAI3D;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,QAAQ;gBACnC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAI3D;AAED;;;;;GAKG;AACH,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAI3D;AAED;;;;;;;GAOG;AACH,qBAAa,uBAAwB,SAAQ,QAAQ;gBACvC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAI3D;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,QAAQ;gBACpC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAI3D;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;gBAClC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAI3D;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;gBAC/B,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAI3D;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,QAAQ;gBAC9B,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAI3D;AA+ED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAG3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CA+C/C"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAWA;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAA;gBAEP,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAU3D;AAED;;;;GAIG;AACH,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAI3D;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;gBAC/B,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAI3D;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,QAAQ;gBACjC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAI3D;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,QAAQ;gBACnC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAI3D;AAED;;;;;GAKG;AACH,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAI3D;AAED;;;;;;;GAOG;AACH,qBAAa,uBAAwB,SAAQ,QAAQ;gBACvC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAI3D;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,QAAQ;gBACpC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAI3D;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;gBAClC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAI3D;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;gBAC/B,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAI3D;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,QAAQ;gBAC9B,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAI3D;AA+ED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAG3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAuD/C"}

package/dist/errors.js

@@ -49,7 +49,9 @@ export class ValidationError extends WasError {
     }
 }
 /**
- * Authorization headers were missing or could not be verified (HTTP 401).
+ * Authorization headers were missing or could not be verified (HTTP 401), or
+ * the caller is authenticated but not permitted to act on the target (HTTP
+ * 403).
  */
 export class AuthRequiredError extends WasError {
     constructor(message, options = {}) {
@@ -217,13 +219,18 @@ export function mapError(err) {
     const data = httpError.data;
     const type = data?.type;
     const title = data?.title;
-    const details = data?.errors
-        ?.map(entry => entry.detail)
-        .filter((detail) => typeof detail === 'string');
+    // Guard with `Array.isArray`, not just optional chaining: a non-conformant
+    // `problem+json` body with `errors` as a non-array (e.g. `"boom"`) is truthy,
+    // so `?.map` would throw a `TypeError` and mask the real `WasError`.
+    const details = Array.isArray(data?.errors)
+        ? data.errors
+            .map(entry => entry.detail)
+            .filter((detail) => typeof detail === 'string')
+        : undefined;
     const requestUrl = httpError.requestUrl;
     const message = title ?? httpError.message ?? 'WAS request failed';
     const options = { status, type, title, details, requestUrl, cause: err };
-    const kind = typeof type === 'string' ? type.split('#')[1] : undefined;
+    const kind = typeof type === 'string' ? problemFragment(type) : undefined;
     const byKind = errorForKind(kind, message, options);
     if (byKind !== null) {
         return byKind;
@@ -232,9 +239,12 @@ export function mapError(err) {
         case 400:
             return new ValidationError(message, options);
         case 401:
+        case 403:
             return new AuthRequiredError(message, options);
         case 404:
             return new NotFoundError(message, options);
+        case 415:
+            return new ValidationError(message, options);
         case 409:
             return new ConflictError(message, options);
         case 412:

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -11,5 +11,5 @@ export { Collection } from './Collection.js';
 export { Resource } from './Resource.js';
 export { WasError, NotFoundError, ValidationError, AuthRequiredError, NotImplementedError, ConflictError, PreconditionFailedError, PayloadTooLargeError, QuotaExceededError, EncryptionError, WasServerError, mapError } from './errors.js';
 export type { ResourceCodec, EncryptionProvider, EncodedWrite } from './codec.js';
-export type { Json, JsonPrimitive, JsonObject, JsonArray, Action, ActionInput, SpaceDescription, CollectionDescription, CollectionEncryption, CollectionSummary, CollectionsList, SpaceSummary, SpaceListing, ResourceSummary, CollectionResourcesList, ResourceMetadata, ResourceMetadataCustom, AddResult, ImportStats, PolicyDocument, LinkSet, LinkSetEntry, HandleOptions, EncryptionOverride, BackendReference, BackendDescriptor, BackendRegistration, BackendConnectionInput, BackendConnectionPublic, StorageLimit, CollectionUsage, BackendUsage, SpaceQuotaReport, GrantOptions, RequestInput, IZcap, IDelegatedZcap, ISigner } from './types.js';
+export type { Json, JsonPrimitive, JsonObject, JsonArray, ResourceData, Action, ActionInput, SpaceDescription, CollectionDescription, CollectionEncryption, CollectionSummary, CollectionsList, SpaceSummary, SpaceListing, ResourceSummary, CollectionResourcesList, ResourceMetadata, ResourceMetadataCustom, AddResult, ImportStats, PolicyDocument, LinkSet, LinkSetEntry, HandleOptions, EncryptionOverride, BackendReference, BackendDescriptor, BackendRegistration, BackendConnectionInput, BackendConnectionPublic, StorageLimit, CollectionUsage, BackendUsage, SpaceQuotaReport, GrantOptions, RequestInput, IZcap, IDelegatedZcap, ISigner } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;GAGG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAExC,OAAO,EACL,QAAQ,EACR,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,EACb,uBAAuB,EACvB,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,QAAQ,EACT,MAAM,aAAa,CAAA;AAEpB,YAAY,EACV,aAAa,EACb,kBAAkB,EAClB,YAAY,EACb,MAAM,YAAY,CAAA;AAEnB,YAAY,EACV,IAAI,EACJ,aAAa,EACb,UAAU,EACV,SAAS,EACT,MAAM,EACN,WAAW,EACX,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,uBAAuB,EACvB,gBAAgB,EAChB,sBAAsB,EACtB,SAAS,EACT,WAAW,EACX,cAAc,EACd,OAAO,EACP,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EACvB,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,KAAK,EACL,cAAc,EACd,OAAO,EACR,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;GAGG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAExC,OAAO,EACL,QAAQ,EACR,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,EACb,uBAAuB,EACvB,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,QAAQ,EACT,MAAM,aAAa,CAAA;AAEpB,YAAY,EACV,aAAa,EACb,kBAAkB,EAClB,YAAY,EACb,MAAM,YAAY,CAAA;AAEnB,YAAY,EACV,IAAI,EACJ,aAAa,EACb,UAAU,EACV,SAAS,EACT,YAAY,EACZ,MAAM,EACN,WAAW,EACX,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,uBAAuB,EACvB,gBAAgB,EAChB,sBAAsB,EACtB,SAAS,EACT,WAAW,EACX,cAAc,EACd,OAAO,EACP,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EACvB,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,KAAK,EACL,cAAc,EACd,OAAO,EACR,MAAM,YAAY,CAAA"}

package/dist/internal/codec.d.ts

@@ -1,6 +1,70 @@
 import type { ResourceCodec } from '../codec.js';
 import type { ClientContext } from './request.js';
-import type { CollectionEncryption, EncryptionOverride } from '../types.js';
+import type { CollectionEncryption, EncryptionOverride, IZcap } from '../types.js';
+/**
+ * The outcome of a marker read. The distinction is load-bearing: `readable:
+ * false` means the Collection Description could not be read at all (a null/404,
+ * which WAS also returns for an *unauthorized* read -- e.g. a resource-scoped
+ * capability cannot GET the collection description), which is indistinguishable
+ * from "absent". That ambiguity must NOT be collapsed into "plaintext", or an
+ * encryption-capable client would fail open and write server-visible plaintext
+ * into an encrypted collection. `readable: true` means the description was read;
+ * its `encryption` is the declared marker (absent for a genuine plaintext
+ * collection).
+ */
+export type MarkerReadResult = {
+    readable: false;
+} | {
+    readable: true;
+    encryption?: CollectionEncryption;
+};
+/**
+ * Reads a Collection's declared `encryption` marker as a {@link MarkerReadResult},
+ * mapping an unreadable description (null/404 -- also what WAS returns for an
+ * unauthorized read) to `{ readable: false }`. The lazy `readMarker` thunk both
+ * the Collection and the standalone-Resource codec resolution pass to
+ * {@link resolveCodec}.
+ *
+ * @param context {ClientContext}
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}
+ * @param [options.capability] {IZcap}
+ * @returns {Promise<MarkerReadResult>}
+ */
+export declare function readCollectionMarker(context: ClientContext, { spaceId, collectionId, capability }: {
+    spaceId: string;
+    collectionId: string;
+    capability?: IZcap;
+}): Promise<MarkerReadResult>;
+/**
+ * A per-handle codec cache. Memoizes the in-flight resolution so concurrent
+ * callers share one round-trip, but drops it on rejection so a transient
+ * failure (e.g. a 500/network error during marker discovery) does not
+ * permanently poison the handle, and exposes `reset()` for when a handle's
+ * encryption state changes (e.g. `Collection.configure()` adds the marker).
+ */
+export declare class CodecHolder {
+    private _promise?;
+    private readonly _resolve;
+    /**
+     * @param resolve {function}   resolves a fresh codec; re-invoked after a
+     *   rejection or a `reset()`, else called at most once
+     */
+    constructor(resolve: () => Promise<ResourceCodec>);
+    /**
+     * Returns the memoized codec, resolving it on first use.
+     *
+     * @returns {Promise<ResourceCodec>}
+     */
+    get(): Promise<ResourceCodec>;
+    /**
+     * Drops any memoized codec so the next `get()` re-resolves.
+     *
+     * @returns {void}
+     */
+    reset(): void;
+}
 /**
  * The default codec: passes plaintext through unchanged. `encode` echoes the
  * caller's `id` (so `put(id, ...)` is a `PUT` and `add(...)`, with no id, stays
@@ -23,14 +87,15 @@ export declare const identityCodec: ResourceCodec;
  * @param [options.override] {EncryptionOverride}   per-handle override; wins
  *   over the marker and skips the marker read
  * @param options.readMarker {function}   lazily reads the Collection's declared
- *   `encryption` marker (resolves `undefined` for plaintext / missing); called
- *   only when there is no override and the client has a keystore
+ *   `encryption` marker, distinguishing a readable description (with or without
+ *   a marker) from an unreadable one (see {@link MarkerReadResult}); called only
+ *   when there is no override and the client has a keystore
  * @returns {Promise<ResourceCodec>}
  */
 export declare function resolveCodec(context: ClientContext, { spaceId, collectionId, override, readMarker }: {
     spaceId: string;
     collectionId: string;
     override?: EncryptionOverride;
-    readMarker: () => Promise<CollectionEncryption | undefined>;
+    readMarker: () => Promise<MarkerReadResult>;
 }): Promise<ResourceCodec>;
 //# sourceMappingURL=codec.d.ts.map

package/dist/internal/codec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/internal/codec.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAgB,aAAa,EAAE,MAAM,aAAa,CAAA;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAGjD,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EAEnB,MAAM,aAAa,CAAA;AAEpB;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EAAE,aAwB3B,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,aAAa,EACtB,EACE,OAAO,EACP,YAAY,EACZ,QAAQ,EACR,UAAU,EACX,EAAE;IACD,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IAC7B,UAAU,EAAE,MAAM,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAAA;CAC5D,GACA,OAAO,CAAC,aAAa,CAAC,CA2BxB"}
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/internal/codec.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAgB,aAAa,EAAE,MAAM,aAAa,CAAA;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAIjD,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EAClB,KAAK,EAGN,MAAM,aAAa,CAAA;AAEpB;;;;;;;;;;GAUG;AACH,MAAM,MAAM,gBAAgB,GAC1B;IAAE,QAAQ,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,UAAU,CAAC,EAAE,oBAAoB,CAAA;CAAE,CAAA;AAE7E;;;;;;;;;;;;;GAaG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,aAAa,EACtB,EACE,OAAO,EACP,YAAY,EACZ,UAAU,EACX,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAA;CAAE,GAC/D,OAAO,CAAC,gBAAgB,CAAC,CAS3B;AAED;;;;;;GAMG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,CAAwB;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8B;IAEvD;;;OAGG;gBACS,OAAO,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC;IAIjD;;;;OAIG;IACH,GAAG,IAAI,OAAO,CAAC,aAAa,CAAC;IAiB7B;;;;OAIG;IACH,KAAK,IAAI,IAAI;CAGd;AAED;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EAAE,aAwB3B,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,aAAa,EACtB,EACE,OAAO,EACP,YAAY,EACZ,QAAQ,EACR,UAAU,EACX,EAAE;IACD,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IAC7B,UAAU,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAA;CAC5C,GACA,OAAO,CAAC,aAAa,CAAC,CA4CxB"}

package/dist/internal/codec.js

@@ -1,5 +1,77 @@
 import { prepareBody, parseResource } from './content.js';
+import { describeCollection } from './describe.js';
 import { EncryptionError } from '../errors.js';
+/**
+ * Reads a Collection's declared `encryption` marker as a {@link MarkerReadResult},
+ * mapping an unreadable description (null/404 -- also what WAS returns for an
+ * unauthorized read) to `{ readable: false }`. The lazy `readMarker` thunk both
+ * the Collection and the standalone-Resource codec resolution pass to
+ * {@link resolveCodec}.
+ *
+ * @param context {ClientContext}
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}
+ * @param [options.capability] {IZcap}
+ * @returns {Promise<MarkerReadResult>}
+ */
+export async function readCollectionMarker(context, { spaceId, collectionId, capability }) {
+    const description = await describeCollection(context, {
+        spaceId,
+        collectionId,
+        capability
+    });
+    return description === null
+        ? { readable: false }
+        : { readable: true, encryption: description.encryption };
+}
+/**
+ * A per-handle codec cache. Memoizes the in-flight resolution so concurrent
+ * callers share one round-trip, but drops it on rejection so a transient
+ * failure (e.g. a 500/network error during marker discovery) does not
+ * permanently poison the handle, and exposes `reset()` for when a handle's
+ * encryption state changes (e.g. `Collection.configure()` adds the marker).
+ */
+export class CodecHolder {
+    _promise;
+    _resolve;
+    /**
+     * @param resolve {function}   resolves a fresh codec; re-invoked after a
+     *   rejection or a `reset()`, else called at most once
+     */
+    constructor(resolve) {
+        this._resolve = resolve;
+    }
+    /**
+     * Returns the memoized codec, resolving it on first use.
+     *
+     * @returns {Promise<ResourceCodec>}
+     */
+    get() {
+        if (this._promise) {
+            return this._promise;
+        }
+        const promise = this._resolve();
+        // Memoize the in-flight promise so concurrent callers share one round-trip,
+        // but drop it on rejection so a transient failure does not permanently
+        // poison the handle. The identity guard avoids clobbering a newer promise.
+        this._promise = promise;
+        promise.catch(() => {
+            if (this._promise === promise) {
+                this._promise = undefined;
+            }
+        });
+        return promise;
+    }
+    /**
+     * Drops any memoized codec so the next `get()` re-resolves.
+     *
+     * @returns {void}
+     */
+    reset() {
+        this._promise = undefined;
+    }
+}
 /**
  * The default codec: passes plaintext through unchanged. `encode` echoes the
  * caller's `id` (so `put(id, ...)` is a `PUT` and `add(...)`, with no id, stays
@@ -36,8 +108,9 @@ export const identityCodec = {
  * @param [options.override] {EncryptionOverride}   per-handle override; wins
  *   over the marker and skips the marker read
  * @param options.readMarker {function}   lazily reads the Collection's declared
- *   `encryption` marker (resolves `undefined` for plaintext / missing); called
- *   only when there is no override and the client has a keystore
+ *   `encryption` marker, distinguishing a readable description (with or without
+ *   a marker) from an unreadable one (see {@link MarkerReadResult}); called only
+ *   when there is no override and the client has a keystore
  * @returns {Promise<ResourceCodec>}
  */
 export async function resolveCodec(context, { spaceId, collectionId, override, readMarker }) {
@@ -57,15 +130,30 @@ export async function resolveCodec(context, { spaceId, collectionId, override, r
     if (!context.encryption) {
         return identityCodec;
     }
-    // 3. Otherwise the Collection's declared marker decides.
+    // 3. Otherwise the Collection's declared marker decides -- but only if we
+    // could actually read it. An unreadable description (a resource-scoped
+    // capability cannot GET the collection description, and WAS masks that as a
+    // 404) is ambiguous: it is indistinguishable from "absent", so an
+    // encryption-capable client fails closed rather than silently downgrading to
+    // plaintext and writing the caller's secret as server-visible plaintext into
+    // a possibly-encrypted collection.
     const marker = await readMarker();
-    if (!marker) {
+    if (!marker.readable) {
+        throw new EncryptionError(`Cannot determine whether collection ${spaceId}/${collectionId} is ` +
+            'encrypted: its description is not readable (a resource-scoped ' +
+            'capability cannot read the collection description, and WAS returns ' +
+            '404 for both not-found and unauthorized). Refusing to fall back to ' +
+            'plaintext. Pass an explicit per-handle encryption override -- ' +
+            "`{ encryption: 'plaintext' }` to write plaintext, or a scheme/keys " +
+            'override to encrypt.');
+    }
+    if (!marker.encryption) {
         return identityCodec;
     }
     return buildEncryptingCodec(context, {
         spaceId,
         collectionId,
-        scheme: marker.scheme
+        scheme: marker.encryption.scheme
     });
 }
 /**

package/dist/internal/codec.js.map

@@ -1 +1 @@
-{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../src/internal/codec.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAO9C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAkB;IAC1C,oBAAoB,EAAE,IAAI;IAE1B,KAAK,CAAC,MAAM,CAAC,EACX,EAAE,EACF,IAAI,EACJ,WAAW,EAKZ;QACC,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,EAAE,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAA;QACjE,OAAO;YACL,EAAE;YACF,IAAI,EAAE,QAAQ,CAAC,IAAI;YACnB,IAAI,EAAE,QAAQ,CAAC,IAAI;YACnB,WAAW,EAAE,QAAQ,CAAC,WAAW;SAClC,CAAA;IACH,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,QAAsB;QACjC,OAAO,CAAC,MAAM,aAAa,CAAC,QAAQ,CAAC,CAAgB,CAAA;IACvD,CAAC;CACF,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAsB,EACtB,EACE,OAAO,EACP,YAAY,EACZ,QAAQ,EACR,UAAU,EAMX;IAED,2DAA2D;IAC3D,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,IAAI,QAAQ,KAAK,WAAW,EAAE,CAAC;YAC7B,OAAO,aAAa,CAAA;QACtB,CAAC;QACD,OAAO,oBAAoB,CAAC,OAAO,EAAE;YACnC,OAAO;YACP,YAAY;YACZ,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,IAAI,EAAE,QAAQ,CAAC,IAAI;SACpB,CAAC,CAAA;IACJ,CAAC;IACD,0EAA0E;IAC1E,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;QACxB,OAAO,aAAa,CAAA;IACtB,CAAC;IACD,yDAAyD;IACzD,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAA;IACjC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,aAAa,CAAA;IACtB,CAAC;IACD,OAAO,oBAAoB,CAAC,OAAO,EAAE;QACnC,OAAO;QACP,YAAY;QACZ,MAAM,EAAE,MAAM,CAAC,MAAM;KACtB,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,KAAK,UAAU,oBAAoB,CACjC,OAAsB,EACtB,EACE,OAAO,EACP,YAAY,EACZ,MAAM,EACN,IAAI,EACsE;IAE5E,MAAM,KAAK,GAAG,GAAG,OAAO,IAAI,YAAY,EAAE,CAAA;IAC1C,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;QACxB,MAAM,IAAI,eAAe,CACvB,cAAc,KAAK,0BAA0B,MAAM,qBAAqB;YACtE,8DAA8D;YAC9D,sDAAsD,CACzD,CAAA;IACH,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC;QAC9C,OAAO;QACP,YAAY;QACZ,MAAM;QACN,IAAI;KACL,CAAC,CAAA;IACF,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,eAAe,CACvB,cAAc,KAAK,0BAA0B,MAAM,qBAAqB;YACtE,wEAAwE;YACxE,kEAAkE,CACrE,CAAA;IACH,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC"}
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../src/internal/codec.ts"],"names":[],"mappings":"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"}

package/dist/internal/content.d.ts

@@ -10,7 +10,35 @@
  * `application/octet-stream`.
  */
 import type { HttpResponse } from '@interop/http-client';
-import type { Json } from '../types.js';
+import type { Json, ResourceData } from '../types.js';
+/**
+ * Whether a content-type denotes JSON -- `application/json` or any
+ * `application/<prefix>+json` structured-suffix variant (e.g.
+ * `application/ld+json`, `application/jose+json`), each optionally followed by
+ * parameters (`; charset=utf-8`). The `json` token is anchored to the end of the
+ * media type, so a non-JSON type that merely contains the substring `json` --
+ * `application/jsonl`, `application/json-seq`, `application/json5` -- is NOT
+ * treated as JSON and is read back as binary (a `Blob`) instead of being
+ * JSON-parsed.
+ *
+ * @param contentType {string}
+ * @returns {boolean}
+ */
+export declare function isJsonContentType(contentType: string): boolean;
+/**
+ * Whether a content type denotes UTF-8-safe text that should be stored inline as
+ * a plain string (legible, no ~33% base64 inflation) rather than as opaque
+ * binary -- `text/*`, plus the XML/SVG family that is textual despite an
+ * `application/` or `image/` prefix (`application/xml`, any `+xml` structured
+ * suffix such as `image/svg+xml` / `application/atom+xml`). Kept deliberately
+ * narrow: an unlisted type is treated as binary (base64), which is always
+ * byte-safe, and the caller additionally gates on valid UTF-8 before choosing
+ * text. Any `; charset=…` parameter is ignored.
+ *
+ * @param contentType {string}
+ * @returns {boolean}
+ */
+export declare function isTextContentType(contentType: string): boolean;
 /**
  * Guesses a content-type from a resource id's file extension, limited to the
  * static-web types in `WEB_CONTENT_TYPES`. Returns `undefined` when the id has
@@ -31,6 +59,22 @@ export interface PreparedBody {
     body?: Uint8Array | Blob;
     contentType?: string;
 }
+/**
+ * Whether a value is a `Blob`, guarding for environments where `Blob` is
+ * undefined.
+ *
+ * @param value {unknown}
+ * @returns {boolean}
+ */
+export declare function isBlob(value: unknown): value is Blob;
+/**
+ * Coerces a `Uint8Array` (including a Node `Buffer`, which is a subclass) to a
+ * plain `Uint8Array` view, as ezcap's `body` type expects.
+ *
+ * @param bytes {Uint8Array}
+ * @returns {Uint8Array}
+ */
+export declare function toPlainBytes(bytes: Uint8Array): Uint8Array;
 /**
  * Inspects write data and resolves it to a JSON or binary payload.
  *
@@ -40,7 +84,7 @@ export interface PreparedBody {
  * with `||` rather than `??` so an empty-string `Blob.type` -- a typeless Blob
  * -- falls through to the guess instead of becoming an empty content-type.)
  *
- * @param data {Json | Blob | Uint8Array}   the resource content
+ * @param data {ResourceData}                the resource content
  * @param options {object}
  * @param [options.contentType] {string}    overrides the inferred content-type
  *   for binary data
@@ -48,14 +92,41 @@ export interface PreparedBody {
  *   content-type by extension when none is given (binary data only)
  * @returns {PreparedBody}
  */
-export declare function prepareBody(data: Json | Blob | Uint8Array, options?: {
+export declare function prepareBody(data: ResourceData, options?: {
     contentType?: string;
     filename?: string;
 }): PreparedBody;
+/**
+ * Extracts the id of a just-created resource from a create response. Prefers
+ * the response body's `id`; for a body-less 2xx falls back to the last path
+ * segment of the `Location` header (decoded, since the server emits a
+ * percent-encoded path). Throws a `WasServerError` when the response carries
+ * neither -- a malformed create response -- rather than letting an absent body
+ * surface as a raw `TypeError` on `data.id`.
+ *
+ * @param response {HttpResponse | null}
+ * @returns {string}
+ */
+export declare function createdId(response: HttpResponse | null): string;
+/**
+ * Unwraps a read response's pre-parsed JSON `data` as `T`, mapping a `null`
+ * response (a 404 that a `read` request resolved to `null`) to `null`. Captures
+ * the `response === null ? null : response.data as T` idiom shared across the
+ * handle read methods.
+ *
+ * @param response {HttpResponse | null}
+ * @returns {T | null}
+ */
+export declare function dataOrNull<T>(response: HttpResponse | null): T | null;
 /**
  * Reads a JSON response body, preferring the http-client's pre-parsed `data`
  * and falling back to `response.json()` when it is absent.
  *
+ * `@interop/http-client` pre-consumes the body into `.data` for JSON
+ * content-types, so a stored top-level `null` arrives as `.data === null`.
+ * Test for `undefined` rather than using `??`; otherwise the nullish fallback
+ * would re-invoke `.json()` on the already-consumed stream and throw.
+ *
  * @param response {HttpResponse}
  * @returns {Promise<unknown>}
  */

package/dist/internal/content.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../src/internal/content.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAExD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAgDvC;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOrE;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,CAAA;IACxB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAoBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,UAAU,EAC9B,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GACxD,YAAY,CA4Bd;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3E;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,YAAY,GAAG,IAAI,GAC5B,OAAO,CAAC,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC,CAS7B"}
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../src/internal/content.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAExD,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAIrD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAO9D;AA6BD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOrE;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,CAAA;IACxB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,IAAI,CAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAK1D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,YAAY,EAClB,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GACxD,YAAY,CA4Bd;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,GAAG,MAAM,CAqB/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,GAAG,CAAC,GAAG,IAAI,CAErE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3E;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,YAAY,GAAG,IAAI,GAC5B,OAAO,CAAC,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC,CAS7B"}

package/dist/internal/content.js

@@ -1,9 +1,9 @@
-import { ValidationError } from '../errors.js';
+import { ValidationError, WasServerError } from '../errors.js';
 const OCTET_STREAM = 'application/octet-stream';
 /**
  * Whether a content-type denotes JSON -- `application/json` or any
  * `application/<prefix>+json` structured-suffix variant (e.g.
- * `application/ld+json`, `application/edv+json`), each optionally followed by
+ * `application/ld+json`, `application/jose+json`), each optionally followed by
  * parameters (`; charset=utf-8`). The `json` token is anchored to the end of the
  * media type, so a non-JSON type that merely contains the substring `json` --
  * `application/jsonl`, `application/json-seq`, `application/json5` -- is NOT
@@ -13,9 +13,28 @@ const OCTET_STREAM = 'application/octet-stream';
  * @param contentType {string}
  * @returns {boolean}
  */
-function isJsonContentType(contentType) {
+export function isJsonContentType(contentType) {
     return /^application\/([^+\s;]+\+)?json\s*(;.*)?$/i.test(contentType);
 }
+/**
+ * Whether a content type denotes UTF-8-safe text that should be stored inline as
+ * a plain string (legible, no ~33% base64 inflation) rather than as opaque
+ * binary -- `text/*`, plus the XML/SVG family that is textual despite an
+ * `application/` or `image/` prefix (`application/xml`, any `+xml` structured
+ * suffix such as `image/svg+xml` / `application/atom+xml`). Kept deliberately
+ * narrow: an unlisted type is treated as binary (base64), which is always
+ * byte-safe, and the caller additionally gates on valid UTF-8 before choosing
+ * text. Any `; charset=…` parameter is ignored.
+ *
+ * @param contentType {string}
+ * @returns {boolean}
+ */
+export function isTextContentType(contentType) {
+    const type = (contentType.split(';')[0] ?? '').trim().toLowerCase();
+    return (type.startsWith('text/') ||
+        type === 'application/xml' ||
+        type.endsWith('+xml'));
+}
 /**
  * Extension-to-content-type fallbacks for the common static-web file types --
  * the only case where guessing a content-type from a resource id pays off
@@ -60,7 +79,14 @@ export function guessContentTypeFromId(id) {
     const extension = id.slice(lastDot + 1).toLowerCase();
     return WEB_CONTENT_TYPES[extension];
 }
-function isBlob(value) {
+/**
+ * Whether a value is a `Blob`, guarding for environments where `Blob` is
+ * undefined.
+ *
+ * @param value {unknown}
+ * @returns {boolean}
+ */
+export function isBlob(value) {
     return typeof Blob !== 'undefined' && value instanceof Blob;
 }
 /**
@@ -70,7 +96,7 @@ function isBlob(value) {
  * @param bytes {Uint8Array}
  * @returns {Uint8Array}
  */
-function toPlainBytes(bytes) {
+export function toPlainBytes(bytes) {
     if (bytes.constructor === Uint8Array) {
         return bytes;
     }
@@ -85,7 +111,7 @@ function toPlainBytes(bytes) {
  * with `||` rather than `??` so an empty-string `Blob.type` -- a typeless Blob
  * -- falls through to the guess instead of becoming an empty content-type.)
  *
- * @param data {Json | Blob | Uint8Array}   the resource content
+ * @param data {ResourceData}                the resource content
  * @param options {object}
  * @param [options.contentType] {string}    overrides the inferred content-type
  *   for binary data
@@ -116,15 +142,60 @@ export function prepareBody(data, options = {}) {
     throw new ValidationError('Resource data must be a plain object/array (JSON) or a ' +
         'Blob/Uint8Array (binary).');
 }
+/**
+ * Extracts the id of a just-created resource from a create response. Prefers
+ * the response body's `id`; for a body-less 2xx falls back to the last path
+ * segment of the `Location` header (decoded, since the server emits a
+ * percent-encoded path). Throws a `WasServerError` when the response carries
+ * neither -- a malformed create response -- rather than letting an absent body
+ * surface as a raw `TypeError` on `data.id`.
+ *
+ * @param response {HttpResponse | null}
+ * @returns {string}
+ */
+export function createdId(response) {
+    const data = response?.data;
+    if (data !== null &&
+        typeof data === 'object' &&
+        typeof data.id === 'string') {
+        return data.id;
+    }
+    const location = response?.headers.get('location');
+    const segment = location
+        ? location.split('/').filter(Boolean).pop()
+        : undefined;
+    if (segment) {
+        return decodeURIComponent(segment);
+    }
+    throw new WasServerError('Create response carried no resource id: the body has no `id` and there ' +
+        'is no `Location` header.');
+}
+/**
+ * Unwraps a read response's pre-parsed JSON `data` as `T`, mapping a `null`
+ * response (a 404 that a `read` request resolved to `null`) to `null`. Captures
+ * the `response === null ? null : response.data as T` idiom shared across the
+ * handle read methods.
+ *
+ * @param response {HttpResponse | null}
+ * @returns {T | null}
+ */
+export function dataOrNull(response) {
+    return response === null ? null : response.data;
+}
 /**
  * Reads a JSON response body, preferring the http-client's pre-parsed `data`
  * and falling back to `response.json()` when it is absent.
  *
+ * `@interop/http-client` pre-consumes the body into `.data` for JSON
+ * content-types, so a stored top-level `null` arrives as `.data === null`.
+ * Test for `undefined` rather than using `??`; otherwise the nullish fallback
+ * would re-invoke `.json()` on the already-consumed stream and throw.
+ *
  * @param response {HttpResponse}
  * @returns {Promise<unknown>}
  */
 export async function readJsonData(response) {
-    return response.data ?? (await response.json());
+    return response.data === undefined ? await response.json() : response.data;
 }
 /**
  * Parses a resource GET response: returns the parsed object when the stored