A developer-friendly client for Portable Web Spaces (PWS) servers, with a database-driver-inspired navigational API over zcap-authorized HTTP.
- Background
- Install
- Usage
- Creating a client (signer + zcapClient)
- Service discovery
- The handle model
- Spaces
- Collections
- Resources: JSON and binary
- Delegation and sharing
- Revoking a capability
- Public sharing and access-control policies
- Resource metadata
- Collection metadata
- Conditional writes (optimistic concurrency)
- Storage introspection: backends and quotas
- Registering a Bring-Your-Own-Storage backend
- Replica registration
- Encrypted collections (EDV-over-PWS): pass-through encryption via the PWS client (recommended)
- Cross-replica sync
- Resource logs (co-managed key resources)
- Export and import
- The manual-request escape hatch
- Errors and the 404/null caveat
- Contribute
- License
The PWS protocol exposes a general purpose database-like container model --
SpacesRepository > Space > Collection > Resource -- over HTTP, authorized with
Authorization Capabilities (zcaps).
@interop/pws-client wraps that ZcapClient and exposes the containment model
through cheap, lazy navigational handles modeled on a document store's DX
(client > db > collection), using PWS-specific verbs
(add/get/put/list/delete) rather than insertOne/findOne (PWS has
no query-by-filter yet).
| Document db driver | PWS client |
|---|---|
new Client(url) |
new PwsClient({ baseServerUrl, zcapClient }) |
client.db('app') |
pws.spaceAt(spaceUrl) |
db.collection('users') |
space.collection(collectionId) |
collection.insertOne(doc) |
collection.add(doc) |
collection.findOne({ _id }) |
collection.get(resourceId) |
collection.replaceOne({ _id }, d) |
collection.put(resourceId, data) |
collection.find().toArray() |
collection.list() |
collection.deleteOne({ _id }) |
collection.resource(resourceId).delete() |
See also:
- CONTRIBUTING.md -- editor setup and code style conventions
- AGENTS.md -- toolchain, tests, and conventions for coding agents
- Node.js 24+ is recommended.
pnpm install @interop/pws-client
A PwsClient signs every request with a key you control. The key is held by an
ezcap ZcapClient, which you build from a did:key identity. You will need two
companion packages alongside this one (this library already depends on
@interop/ed25519-signature):
pnpm install @interop/ezcap @interop/did-method-key @interop/ed25519-verification-key
The primary form wraps a ZcapClient you build yourself. The did:key driver
generates a key pair and a matching DID document, wiring the signer's
id/controller correctly:
import { ZcapClient } from '@interop/ezcap'
import * as didKey from '@interop/did-method-key'
import { EddsaJcs2022 } from '@interop/ed25519-signature/eddsa-jcs-2022'
import { Ed25519VerificationKey } from '@interop/ed25519-verification-key'
import { PwsClient } from '@interop/pws-client'
// 1. Generate a did:key identity (didDocument + keyPairs).
const didKeyDriver = didKey.driver()
didKeyDriver.use({ keyPairClass: Ed25519VerificationKey })
const { didDocument, keyPairs } = await didKeyDriver.generate()
// 2. Build the ezcap ZcapClient (it holds the signer and signs every request).
const zcapClient = new ZcapClient({
didDocument,
keyPairs,
SuiteClass: EddsaJcs2022
})
// 3. Wrap it.
const pws = new PwsClient({
baseServerUrl: 'https://pws.example/',
zcapClient
})If you already have a single signer, PwsClient.fromSigner() builds the
ZcapClient internally (using the eddsa-jcs-2022 suite). A signer is any
object with { id, sign() }; here we get one from a generated key. The signer's
id must be a did:key so the server can resolve and verify it:
import { Ed25519VerificationKey } from '@interop/ed25519-verification-key'
import { PwsClient } from '@interop/pws-client'
// Pass a 32-byte `seed` for a deterministic key, or omit it for a random one.
const keyPair = await Ed25519VerificationKey.generate({ seed })
keyPair.controller = `did:key:${keyPair.fingerprint()}`
keyPair.id = `${keyPair.controller}#${keyPair.fingerprint()}`
const pws = PwsClient.fromSigner({
baseServerUrl: 'https://pws.example/',
signer: keyPair.signer()
})The seed is where a passphrase-, stored-secret-, or KMS-derived key plugs in:
deriving the same 32-byte seed yields the same DID, and therefore access to the
same spaces.
A client is built from the server's base server URL. The spec's Server Layout
places the server-level endpoints under it: {base}service is the service
description, {base}spaces/ is the Spaces Repository, and
{base}space/{space_id}/ is a Space. The base must be an absolute http(s) URL
with no query, fragment, or userinfo. A missing trailing slash is supplied.
Anything else is refused with ValidationError. The result is exposed as
pws.baseServerUrl.
pws.space(spaceId) opens a handle on {base}space/{spaceId}/, with no I/O.
pws.spaceAt(spaceUrl) opens a handle on a Space URL you hold, such as the
Location of a create response, a listing item's url, a linkset entry, a
stored pointer, a capability's target, or a self-locating DID. A received Space
URL is used as given. It is never checked against the base, because a grant or a
DID may name a Space on another server.
The ./paths entry exports the matching builders: canonicalBaseServerUrl,
serviceDescriptionUrl({ baseServerUrl }),
spacesRepositoryUrl({ baseServerUrl }) and
spaceUrlById({ baseServerUrl, spaceId }). baseServerUrlOf(url) is their
inverse. It accepts the service, Spaces Repository or Space URL and rejects
anything else. splitCollectionUrl(url) splits a Collection URL into its Space
URL and id.
@interop/pws-client/paths/layout exports these same functions and nothing
else, with no package behind them. Import it where one URL is validated and the
rest of ./paths (the reserved-id predicates, which read
@interop/storage-core's registry, and the root capability grammar from
@interop/zcap) is not wanted; under plain Node ESM ./paths evaluates both
packages on first import.
Some servers are one Space with no id and no base server URL, such as a personal
site whose Collections are https://alice.example/posts/ and
https://alice.example/images/. Open one with PwsClient.forSpace() and reach
a Collection directly with collectionAt():
const pws = PwsClient.forSpace({
spaceUrl: 'https://alice.example/',
signer: keyPair.didKeySigner()
})
const posts = pws.collectionAt('https://alice.example/posts/')
const post = await posts.get('hello')forSpace takes
{ spaceUrl, zcapClient | signer, encryption?, serviceDescription? }. The
client exposes pws.spaceUrl, and pws.baseServerUrl is undefined. It finds
the service description with an unsigned HEAD of the Space URL and the
Link: <...>; rel="service" header. space(id), createSpace() and
listSpaces() throw NotSupportedError.
collectionAt(collectionUrl) works on any client. The parent of the URL is the
Space URL and the last segment is the Collection id. A Space URL may be an
origin root, in which case Space.id is undefined. At an origin-root Space
the Collection ids service, spaces and space are reserved.
Apps with user accounts usually do not hold a did:key signer directly -- they
hold a passphrase, or a stored secret, and need to derive the same client from
it every time. The ./identity subpath does that derivation:
import { agentsFromSecret } from '@interop/pws-client/identity'
import { PwsClient } from '@interop/pws-client'
const agents = await agentsFromSecret({ secret: 'the account secret' })
const pws = PwsClient.fromSigner({
baseServerUrl: 'https://pws.example/',
signer: agents.keyAgent.getSigner()
})agents.zcapClient is the same client fromSigner builds, for callers that
need it directly.
The derivation is type-sensitive, so the secret is always a string: a
passphrase, or the base64url text of random bytes, not the decoded bytes. To
derive from an already-derived 32-byte seed instead, use
agentsFromSeed({ seed }).
The derivation is deterministic and permanent: the same secret, on any client,
derives the same did:key and joins the same account. agents.keyAgreementKey
and agents.keyResolver are the key-agreement key and resolver the ./edv
cipher takes, so a caller building an encrypted collection has both halves from
one call. The key is a ProfileKeyAgreementKey, which also carries its
publicKeyMultibase, the value a caller publishes as the key's verification
method.
Delegation proofs are signed with eddsa-jcs-2022. That cryptosuite
canonicalizes with JCS (RFC 8785), which is plain JSON, so delegating runs no
JSON-LD canonicalization and needs no document loader to serve the suite's
context at signing time. Invocations are unaffected -- those ride HTTP
signatures, not proofs.
zcapClientForSigner({ signer }), exported from the package root, is the one
ZcapClient construction site that hard-codes this suite; fromSigner() above
builds its client through it, and so does every ./identity derivation.
The server has to verify eddsa-jcs-2022 for grants from this client to be
accepted. A server that verifies both it and the older Ed25519Signature2020
accepts chains whose links mix the two, which is what a fleet upgrading at its
own pace produces.
Before its first signed request, the client reads the server's service
description. A client built from baseServerUrl reads {base}service with an
unsigned GET. A client built by forSpace first sends an unsigned HEAD to
the Space URL and follows the Link: <...>; rel="service" header on the
response, whatever its status, then reads the linked document with an unsigned
GET. The spec fixes no path for the document on a fixed-Space server, so that
client assumes none.
A client with a base checks that the document describes that base. Its url
must equal {base}service, and its spaces member, when present, must equal
{base}spaces/. Otherwise every signed request rejects with
IncompatibleServerError naming both values. The check also applies to a
caller-supplied serviceDescription. A client built by forSpace has no base
and is not checked. createSpace() and listSpaces() address {base}spaces/.
From the document the client selects the PWS specification version it speaks.
This client speaks only v0.5. It ignores specs keys other than
https://w3id.org/pws and entries without a version. If no entry names v0.5,
or the document is malformed, every signed request rejects with
IncompatibleServerError before anything is signed. A server whose responses
carry no service link predates v0.5 and is refused the same way. The client
does not fall back to the v0.4 layout.
Discovery runs once per client and is shared by every handle. A failure is not
memoized, so the next request retries. Unsigned public reads (publicRead,
publicListCollection, ...) take absolute URLs that may point at another
server, and do not wait on discovery.
pws.service() returns what discovery found:
const info = await pws.service()
info.version // '0.5'
info.entry // the chosen `PwsVersionEntry`
info.description // the whole `ServiceDescription`
info.spacesUrl // the Spaces Repository URL, or undefined
info.features // e.g. ['listing', 'collection-management', 'changes-query', ...]
info.hasFeature('quotas') // false when the token is absent
// Discover again, e.g. before relying on an affordance a host may have dropped.
await pws.service({ refresh: true })features is an open token list. A token this client does not know is carried
along and otherwise ignored, and an absent token means unsupported. The client
gates no behavior on the document's instance member.
A caller that already holds the document (from a cache, say) can pass it as the
serviceDescription constructor option. The client then selects a version from
that copy without fetching, and service({ refresh: true }) discovers afresh.
The client exposes the PWS containment model
(SpacesRepository > Space > Collection > Resource) as navigational handles.
Handles are lazy and synchronous to obtain -- only the verb methods hit the
network. A chain such as pws.spaceAt(url).collection(y) does no I/O and just
accumulates URL context; the only way it throws is ValidationError, on a URL
that cannot name a Space or an id on the reserved-segment registry. Existence is
checked on the first network verb.
const space = await pws.createSpace({ name: 'Home' })
const collection = await space.createCollection({
name: 'Verifiable Credentials'
})
await collection.put('vc-1', {
type: ['VerifiableCredential'],
name: 'Diploma'
})
const vc = await collection.get('vc-1') // parsed JSON object, or null on a miss
await collection.resource('vc-1').delete() // delete one resource by id
await space.delete() // delete the whole space (idempotent)delete() is uniform at every level, takes no argument, and always deletes the
thing the handle points at -- so there is no "delete the collection" vs "delete
one item" footgun. The next sections cover each level in turn.
A consumer that has to form a URL without a handle imports the builders from
./paths instead of assembling it by hand. Each one takes the Space URL and
owns the trailing-slash and percent-encoding rules that have to match the
server. Beneath a Space they are spaceMetaUrl, spacePolicyUrl,
spaceLinksetUrl, spaceBackendsUrl, spaceQuotasUrl, spaceExportUrl,
spaceImportUrl, spaceReplicasUrl and replicaRegistrationUrl. Beneath a
Collection they are collectionUrl, collectionMetaUrl, collectionLogUrl,
collectionQueryUrl, collectionPolicyUrl, collectionLinksetUrl,
collectionBackendUrl and collectionQuotaUrl. Beneath a Resource they are
resourceUrl, resourceMetaUrl, resourcePolicyUrl, resourceChunkUrl and
resourceChunksUrl. resourceChunkUrl throws a ValidationError on a
chunkIndex that is not a non-negative integer.
A Space is the top-level container, created from the spaces repository. The
server requires a name; controller defaults to the client's own DID, and the
server generates the id unless you pass one. createSpace() reads the
Location header of the response and returns a handle on that Space URL. A
response without Location throws PwsServerError. createSpace() and
listSpaces() address the Spaces Repository, {base}spaces/ (see
Service discovery). Against a server whose description has
no spaces URL, they throw NotSupportedError without sending anything.
const space = await pws.createSpace({ name: 'Home' }) // POST {base}spaces/
// A typed Space, e.g. an auxiliary one; `type` defaults to ['Space'].
const aux = await pws.createSpace({
name: 'Clients',
type: ['AuxiliarySpace', 'Space']
})
// Lazy handle to an existing space by its URL -- no I/O until a verb runs.
const same = pws.spaceAt(space.url)
const byId = pws.space('abc') // {base}space/abc/, no I/O
// Read the Space Metadata object (null if missing or not visible to you).
const desc = await space.describe() // { id, type: ['Space'], name, controller } | null
// Upsert: merges the given fields over the current Metadata object. The
// write is pinned to that read's ETag and re-merges on a lost race. It
// answers with the merged description and the write's own ETag, so a
// follow-on compare-and-swap needs no re-read.
await space.configure({ name: 'Home (renamed)' })
// { description: { id, type: ['Space'], name, controller }, etag? }
// Lost-update-safe writes: read the Metadata object with its ETag, then
// write it under `ifMatch` (412 `PreconditionFailedError` if it changed), or
// create-if-absent under `ifNoneMatch` (412 if the Space already exists).
// Nothing is read or merged on the client, so `controller` is required.
const read = await space.describeWithEtag() // { description, etag? } | null
await space.replaceDescription(
{ name: 'Home', controller: read!.description.controller },
{ ifMatch: read!.etag }
) // { etag? }
await pws
.spaceAt(freshSpaceUrl)
.replaceDescription(
{ name: 'Fresh', controller: 'did:key:z6Mk...' },
{ ifNoneMatch: true }
) // { description, etag? }: a create echoes the Metadata object
await space.delete() // idempotent
// Need to know whether the DELETE actually removed anything, rather than
// treating a 404 as success? `deleteWithOutcome()` reports
// `{ outcome: 'deleted' | 'not-found' }` -- 'not-found' means absent or
// refused, since the server answers 404 for both.
const { outcome } = await space.deleteWithOutcome()List the spaces in the repository visible to your signer with
pws.listSpaces(). It returns a { url, totalItems, items } listing holding
every space whose controller your invocation is authorized for, auxiliary spaces
included; an unauthorized caller gets an empty list rather than an error. Each
item carries the space's type array, the same value as its Space Metadata
object's type, so an auxiliary space (one whose type names AuxiliarySpace)
can be told apart without reading it. To enumerate what is inside a space, use
space.collections() (below).
const { totalItems, items } = await pws.listSpaces()
// items: [{ id, type, url, name? }, ...]
const userSpaces = items.filter(item => !item.type.includes('AuxiliarySpace'))A Collection lives inside a Space and holds resources. PWS does not auto-create
parents, so createCollection throws NotFoundError if the space does not
exist. The server generates the id unless you pass one (a handful of reserved
ids are rejected).
// Create.
const collection = await space.createCollection({
name: 'Verifiable Credentials'
})
// Lazy handle to an existing collection by id.
const same = space.collection(collection.id)
// Read the Collection Metadata object (null if missing or not visible).
const desc = await collection.describe() // { id, type: ['Collection'], name } | null
// Update (upsert; merges over the current Metadata object). Answers with the
// merged description and the write's own ETag, like `space.configure()`.
await collection.configure({ name: 'Credentials' }) // { description, etag? }
// List the collections in a space.
const collections = await space.collections()
// { url, totalItems, items: [{ id, name, url }, ...] } | null
// List the resources inside this collection. Transparently follows the
// server's `next` pagination links, buffering every page into one listing.
const resources = await collection.list()
// { id, url, totalItems, items: [{ id, url, contentType }, ...], ... } | null
// For a large collection, stream one page (or item) at a time instead of
// buffering the whole thing -- follows `next` on demand, stops early on `break`.
for await (const item of collection.listItems()) {
// item: { id, url, contentType, name? }
}
// `collection.listPages()` yields whole pages if you'd rather page yourself.
await collection.delete() // deletes the whole collection; idempotentTo delete a single resource instead of the whole collection, use
collection.resource(id).delete().
The Collection Metadata object's top-level name is server-visible plaintext.
An encrypted collection leaves it unpopulated by convention and carries its name
and tags on the same object's custom member instead,
where they are encrypted.
An application that provisions a collection can record who it was provisioned
for, with the optional generator object: the application's DID (id,
required), the Web origin that DID was bound to (origin), and the
application's canonical URL (url, which needs origin and must share it), and
its display label (name). It is accepted at create time and stays writable
afterwards, so an existing collection can be backfilled. A write carrying
generator replaces the stored object whole. It is a controller assertion the
server persists but does not verify.
await space.createCollection({
name: 'App Notes',
generator: {
id: 'did:key:z6Mk...',
origin: 'https://app.example',
url: 'https://app.example/notes',
name: 'Notes'
}
})
// Backfill an existing collection (other fields merge forward unchanged).
await space.collection('notes').configure({
generator: { id: 'did:key:z6Mk...', origin: 'https://app.example' }
})A Resource is a JSON object or binary blob keyed by id within a Collection. Use
add() for a server-generated id or put(id, ...) to create-or-replace at a
known id (both throw NotFoundError if the parent collection is missing):
// Server-generated id; returns { id, url, contentType? }.
const added = await collection.add({
type: ['VerifiableCredential'],
name: 'Diploma'
})
// Create or replace at a known id (upsert).
await collection.put('vc-1', {
type: ['VerifiableCredential'],
name: 'Diploma'
})
const vc = await collection.get('vc-1') // parsed JSON object, or null on a miss
await collection.resource('vc-1').delete() // idempotentWrites detect the payload: a plain object/array is sent as JSON; a
Blob/Uint8Array/Buffer is sent as binary, with the content-type taken from
options.contentType, the Blob.type, or application/octet-stream. A
ReadableStream<Uint8Array> is accepted only by an encrypted collection (see
Encrypted collections).
A plaintext collection refuses it with ValidationError. A plaintext resource
has no chunked representation, and a signed request carries a Digest of its
whole body. Buffer the stream into a Blob there.
// JSON
await collection.put('doc', { hello: 'world' })
// Binary
const bytes = new TextEncoder().encode('plain text body')
await collection.put('note.txt', bytes, { contentType: 'text/plain' })
const resource = collection.resource('note.txt')
await resource.get() // a Blob (whose .type carries the content-type)
await resource.getText() // 'plain text body'
await resource.getBytes() // Uint8ArrayReads auto-parse: get() returns a parsed object for a JSON content-type and a
Blob otherwise; getText() / getBytes() are explicit escape hatches.
getWithEtag() pairs the decoded value with its ETag validator, and
getWithEtag({ as: 'text' }) projects it to text (decrypting where getText()
would not). getStream() resolves { stream, contentType?, etag? }, or null
on a miss. It runs the codec like get(), so it decrypts on an encrypted
collection. A JSON body is re-serialized, so it is semantically identical JSON
but not guaranteed byte-identical.
A write value is a JSON object/array or binary (Blob/Uint8Array, or a
ReadableStream<Uint8Array> on an encrypted collection) -- the ResourceData
type. A top-level JSON primitive (a bare string, number, boolean, or
null) is not accepted; it is a compile-time error. To store one, either
wrap it in an object (put('greeting', { value: 'hello' })) or write it as
binary via a Blob:
await collection.put('greeting', new Blob(['hello'], { type: 'text/plain' }))pws.grant(...) is the general delegation primitive; space.grant(...) and
collection.grant(...) are sugar that prefill the grant target and spaceUrl
from the handle. A bare pws.grant(...) with no capability and no spaceUrl
is rooted at the target's own root capability. Passing spaceUrl roots it at
that Space instead, and throws ValidationError if target is not at or
beneath the Space. The recipient rebuilds access from the received zcap with
fromCapability(), which reads the Space off the capability's chain root. A
zcap whose chain starts at no root capability, or at one whose target cannot be
a Space URL, is refused with ValidationError, as is one whose
invocationTarget is not the canonical form of the URL the handle would
address. The server is the authority on whether the root names a Space.
// Alice grants Bob read access to a resource.
const added = await collection.add({ secret: 'value' })
const zcap = await pws.grant({
to: bobDid,
actions: ['GET'], // HTTP verbs: 'GET' | 'POST' | 'PUT' | 'DELETE'
target: added.url,
spaceUrl: space.url
})
// Bob, holding the zcap, rebuilds a handle at the right depth.
const handle = bobPws.fromCapability(zcap) // a Resource here
await handle.get() // succeeds; a write would be denied by the GET-only grantA resource-scoped grant does not cover the Collection Metadata object, so a
client constructed with an encryption provider cannot discover whether the
collection is encrypted and fails closed with EncryptionError. Pass the handle
an explicit override, as you would to collection.resource(id, options):
'plaintext' for a plaintext collection, or the collection's encryption
descriptor (shared out of band with the grant) for an encrypted one.
const handle = bobPws.fromCapability(zcap, { encryption: 'plaintext' })Actions are HTTP verbs (GET / PUT / POST / DELETE). The PWS server
authorizes on these case-sensitively (uppercase), but grant() also accepts the
lowercase forms and normalizes them to uppercase in the signed zcap -- so
actions: ['get'] still validates server-side. HEAD is not an action. A
HEAD request is authorized as a GET: the client signs it with action GET,
and a GET grant covers it.
space.revoke(zcap) undoes a grant(), so a leaked capability need not be
waited out to its expires. pws.revoke(zcap) is the same operation with the
Space read off the capability's delegation chain root.
const zcap = await collection.grant({ to: appDid, actions: ['GET', 'PUT'] })
// ... the capability leaks ...
await space.revoke(zcap) // from now on the capability is rejectedTwo parties may revoke: the Space's controller, and any controller in the
capability's own delegation chain -- so an application can revoke the capability
it holds, without being granted anything extra. Anyone else gets a
NotFoundError, PWS's mask for "not visible to you".
Three properties are easy to get wrong:
- Revocation is Space-scoped. There is no global or cross-Space revocation;
submitting a capability rooted in another Space throws
NotFoundError, the same mask as any other denied revocation. - It withdraws the capability, not a policy grant. Access-control policies
are permissive, so a
PublicCanReadtarget stays world-readable after you revoke a capability naming it. What dies is the capability: on such a target the revoked zcap's read still succeeds while its write does not. - It is prospective, and not idempotent. A revoked reader of an encrypted
Collection keeps the keys for ciphertext it already fetched. Once a rotation
leaves it out of the current key epoch, its writes that encrypt are refused
client-side with
NotCurrentRecipientError, whether or not its capability is revoked yet. Writes that seal nothing (delete,setPolicy, a plaintextconfigure({ name }),putHistoryLog) are not refused. Only revoking its capability stops those. And revoking an already-revoked capability throwsAlreadyRevokedError, aValidationErrorsubclass named for the server'scapability-already-revokedproblem type. A tampered or expired capability stays a plainValidationError, and the client swallows none of them. CatchAlreadyRevokedErrorif you want revoking twice to be a no-op.
A Space, Collection, or Resource can carry an access-control policy that grants read access beyond capabilities -- most commonly making it world-readable ("share via public link"). The policy methods live on all three handles:
// Make a whole collection world-readable (the "create public link" case).
await collection.setPublic() // sugar for setPolicy({ type: 'PublicCanRead' })
// Anyone (even unauthenticated) can now read its resources.
const link = added.url // hand this URL out; a plain GET resolves it
// Inspect or revoke.
const policy = await collection.getPolicy() // { type: 'PublicCanRead' } | null
const isPublic = await collection.isPublic() // true if its own policy is PublicCanRead
await collection.clearPolicy() // revert to capability-only access (idempotent)
// Conditional writes: the policy carries an ETag and a write stamp.
const read = await collection.getPolicyWithEtag() // { policy, etag } | null
// read.policy also carries updatedAt / updatedAtCounter / originId
const { etag } = await collection.setPolicy(
{ type: 'PublicCanRead' },
// 412 PreconditionFailedError if created or changed meanwhile
read === null ? { ifNoneMatch: true } : { ifMatch: read.etag }
)
await collection.clearPolicy({ ifMatch: etag }) // returns the tombstone's { etag }
// setPolicy() is the generic, forward-compatible primitive; setPublic() is sugar.
await space.setPolicy({ type: 'PublicCanRead' }) // inherited by all contents
await resource.setPublic() // a single public resourcePolicies are resolved most-specific-first (Resource over Collection over Space)
and are permissive-only -- they broaden access, never restrict a valid
capability holder. Managing a policy is a controller-level operation. Discover a
policy via space.linkset() / collection.linkset() (RFC9264) or the linkset
property on a description.
isPublic() is a read-only convenience that returns true when the Space,
Collection, or Resource has a { type: 'PublicCanRead' } policy -- that is,
when it has been made public via setPublic() (or an equivalent setPolicy()
call). It's meant to drive data-browser style UI, to show a "This
space(/collection/resource) has been shared publicly" type of icon.
The flip side of setPublic(): reading a PublicCanRead resource or collection
with no authorization, by its URL. These use an unsigned plain fetch (no
capability invocation), so they work for a consumer who only holds the link.
// Fetch a single public resource (auto-parses JSON, returns binary as a Blob).
const doc = await pws.publicRead({
resourceUrl: 'https://pws.example/space/s/c/r'
}) // Json | Blob | null
// List a public collection -- e.g. a blog published as a public-read collection.
const listing = await pws.publicListCollection({
collectionUrl: 'https://pws.example/space/s/c'
}) // ResourceListing | null
// Or stream a large public collection one item/page at a time:
for await (const item of pws.publicListCollectionItems({
collectionUrl: 'https://pws.example/space/s/c'
})) {
// item: { id, url, contentType, name? }
}
// (`pws.publicListCollectionPages(...)` yields whole pages.)Both follow the read-method 404/null caveat: a missing or non-public target
resolves to null.
Each Resource has a metadata object at its reserved /meta path: server-managed
properties (contentType, size, optional createdAt / updatedAt) plus a
user-writable custom object (name and tags).
const resource = collection.resource('vc-1')
const meta = await resource.meta() // ResourceMetadata | null (null on a miss)
// setMeta() is a full replacement of `custom`; omitted properties are cleared.
await resource.setMeta({ custom: { name: 'Diploma', tags: { year: '2026' } } })
// setName() / setTags() are read-modify-write sugar that preserve the other.
// The write is pinned to the /meta ETag the read returned; on a resource whose
// metadata has never been written (no ETag yet) it is a guarded create instead.
await resource.setName('Renamed diploma') // keeps existing tags
await resource.setTags({ status: 'verified' }) // keeps existing nameThe custom.name is the same value surfaced as a resource's name in
collection listings; updating one updates the other.
A Collection's configuration (name, backend, encryption, generator, read
by describe()) and its annotations live in one object at the
Collection's reserved /meta path: server-managed properties (createdAt /
updatedAt / createdBy / created) plus a user-writable custom object
(name and tags), under one ETag validator. meta() is that same object
with custom decoded through the codec; describe() does not resolve the codec
at all, so on an encrypted collection it reports custom as the opaque
envelope. A server without the endpoint surfaces its 501 as
NotImplementedError.
const meta = await collection.meta() // CollectionMetadata | null (null on a miss)
// setMeta() is a full replacement of `custom`; omitted properties are cleared.
await collection.setMeta({ custom: { name: 'Vault', tags: { app: 'wallet' } } })
// setName() / setTags() are read-modify-write sugar that preserve the other.
await collection.setName('Renamed vault') // keeps existing tags
await collection.setTags({ app: 'wallet' }) // keeps existing name
// Conditional metadata write.
await collection.setMeta({ custom: { name: 'Vault' } }, { ifMatch: meta?.etag })
// ...or create the Collection only if it does not exist yet:
await collection.setMeta({ custom: { name: 'Vault' } }, { ifNoneMatch: true })created is the write stamp of the write that created the Collection
({ updatedAt, updatedAtCounter, originId }), kept for the Collection's life. A
Collection deleted and created again carries the stamp of the later create. No
write sends it back. A Collection created before the server supported the stamp
may lack it.
A failed precondition throws PreconditionFailedError (412). This /meta ETag
is independent of every Resource's versions, but not of the configuration
members: one validator covers the whole Collection Metadata object, so
configure() and setMeta() advance the same validator.
The write is a full replacement of that one object, so an annotation write
re-sends the configuration members (and any member this client does not model)
as read, and configure() merges over the version it pins to. Two consequences
worth knowing. ifNoneMatch: true is the only annotation write that may create:
it means "create the Collection only if it does not exist", creates it with no
configuration, and encodes custom with the plaintext codec, since the body it
sends declares no encryption descriptor (pass a per-handle encryption override
to state one). Every other annotation write requires a readable current object
and throws NotFoundError when there is none -- a masked 404 cannot turn a
rename into a create.
On an encrypted collection custom is encrypted into an envelope before it is
sent, so name / tags are never stored as server-visible plaintext, and
meta() decrypts them back for a keyed reader. This is the encrypted
collection's name/tags surface: by convention the plaintext top-level name is
left unpopulated there.
Beside /meta, a Collection has a /meta/log sub-resource: its governing
history log (the backend's governed-history-logs feature), a JSON Lines body
the server derives the Collection's encryption descriptor from. The log is not
a Resource of the Collection (it is absent from listings, and the changes feed
carries it as a kind: 'log' entry named by URL) and not part of the /meta
object, and it carries its own ETag.
const log = await collection.getHistoryLog() // { body, etag } | null
// The guarded create declares the Collection log-governed.
await collection.putHistoryLog(genesisLine, { ifNoneMatch: true })
// An append is a compare-and-swap: the prior bytes verbatim plus one line.
await collection.putHistoryLog(log.body + nextLine, { ifMatch: log.etag })From the create on, describe() serves encryption as the log head's state
with history: { method, resource } stamped on, and a direct encryption write
on the Collection Metadata object throws ConflictError. The create is refused
the same way on a Collection whose Metadata object already carries a
client-written descriptor. A lost race throws PreconditionFailedError (412).
These are the raw transport methods; the /log subpath's
resourceLogStore({ collection }) (below) drives them as the resource-log store
port.
A reader that holds the descriptor but not the convention follows its history
pointer through the /edv subpath's logGovernedCollectionDescriptorStore, the
EncryptionDescriptorStore the recipient primitives run over. Its read()
refuses a history.method other than the profile's format identifier or a
history.resource other than collection.historyLogUrl before any fetch,
verifies the log through @interop/vh-resource-log under the controller port
and chain-head pin store you supply, and refuses a served descriptor that does
not match the verified head. Pass a signer to write; without one the store is
read-only.
import { logGovernedCollectionDescriptorStore } from '@interop/pws-client/edv'
import { memoryResourceLogPinStore } from '@interop/vh-resource-log'
const store = logGovernedCollectionDescriptorStore({
collection,
resolveController, // () => Promise<ResourceLogController>, your verified view
pinStore: memoryResourceLogPinStore(),
logId: 'space/s1/vault/meta/log' // the pin slot for this log
})
const { descriptor } = await store.read() // verified head state, `history` keptEvery Resource carries a strong ETag validator that changes on every write
(conditional writes are a baseline PWS server requirement). Use it to prevent
the lost-update problem -- two clients that both read version N and each write
N+1, the second silently clobbering the first.
const { etag } = await collection.put('doc', { v: 1 }) // writes return the ETag
const meta = await collection.resource('doc').meta() // meta().etag also carries it
// Update-if-unchanged: succeeds only if `doc` is still at `etag`, else throws
// PreconditionFailedError (HTTP 412).
await collection.put('doc', { v: 2 }, { ifMatch: etag })
// Create-if-absent: succeeds only if `doc` does not yet exist (else 412).
await collection.put('new-doc', { v: 1 }, { ifNoneMatch: true })
// Delete-if-unchanged.
await collection.resource('doc').delete({ ifMatch: someEtag })Recover from a PreconditionFailedError by re-reading the current etag,
re-applying your change on top of the new version, and retrying.
On an encrypted collection this is automatic: the EDV codec advances the
document sequence and pins each write to the current ETag for you, so a stale
write surfaces as a PreconditionFailedError (the EDV sequence becomes
enforced rather than advisory). The explicit ifMatch / ifNoneMatch options
above are for plaintext collections.
A Space can report the storage backends available to it and a per-backend usage
report. Both are optional server features (a server without them surfaces a
NotImplementedError); both follow the read-method 404/null caveat.
const backends = await space.backends() // BackendDescriptor[] | null
const report = await space.quotas() // SpaceQuotaReport | null
// report.backends[i]: { id, state, usageBytes, limit, restrictedActions, ... }A Collection can likewise report the backend it is stored on and its own usage, scoped to that backend (same optional-feature and 404/null caveats).
const backend = await collection.backend() // BackendDescriptor | null
const usage = await collection.quota() // BackendUsage | null
// usage: { id, state, usageBytes, limit, restrictedActions, measuredAt, ... }A BackendDescriptor says where a Collection's data lives; it advertises no
optional affordances. Server-wide affordances are read from the service
description instead:
const info = await pws.service()
if (info.hasFeature('changes-query')) {
// the server serves the replication change feed
}An absent token means the server makes no claim to it, so treat it as unsupported rather than assuming a default. (Client-side encryption is not a server affordance -- see below.)
Beyond the server's built-in default backend, the Space controller can
register an external ("Bring Your Own Storage") backend -- e.g. a wallet
connecting a user's own Google Drive. Registration is a controller-authorized
write: the body carries the secret-bearing connection material (an OAuth
authorization code or refresh token), and the server stores it and returns the
sanitized descriptor (never the secrets).
const descriptor = await space.registerBackend({
id: 'gdrive-personal', // unique within the Space
name: 'My Google Drive',
provider: 'google-drive', // selects the server-side adapter
connection: {
kind: 'oauth2-google',
authorizationCode: '4/0Ab...', // one-time PKCE code (or a refreshToken)
redirectUri: 'https://wallet.example/oauth/callback'
}
})
// descriptor.connection: { kind, status: 'registered', account?, scope?, ... }Once registered, select it on a Collection by id; reads of the backend reflect
its connection status (registered | connected | expired | revoked |
unreachable), which a storage-management UI uses to prompt re-consent:
await space.createCollection({
id: 'photos',
backend: { id: 'gdrive-personal' }
})
const [, gdrive] = (await space.backends()) ?? []
if (gdrive?.connection?.status === 'expired') {
// re-consent: swap in fresh connection material (create-or-replace by id)
await space.updateBackend({
id: 'gdrive-personal',
provider: 'google-drive',
connection: { kind: 'oauth2-google', authorizationCode: '4/0Cd...' }
})
}
// Deregister (idempotent): forgets the record and its stored connection.
await space.deregisterBackend('gdrive-personal')registerBackend() throws a ConflictError if the id already exists or the
server does not permit the provider; updateBackend() returns the descriptor
when it created a record and null when it replaced one in place (the server
sends no body on an in-place replace).
A registered backend's record exists immediately, but whether its connection can actually serve bytes depends on the server having a live provider adapter for it. Until then it is registered but inert (
status: 'registered').
A Space can pull from a copy of itself on another server. The Space controller registers that peer Space with this server, and this server then runs a pull loop against the peer. Replication is one-way. The peer receives nothing unless its own server holds a registration pointing back.
A registration is a directed edge. fromSpace is the peer Space's canonical
trailing-slash URL, and toSpace is this Space's. role is always source.
capability is the pull capability: a zcap the controller delegates to this
server's DID, rooted in the peer Space, with allowedAction of GET.
collections lists the Collections to pull. Leave it out to pull every
Collection.
// The DID of the server that will pull: the reference server discloses it
// as `instance.serverDid` in its service description. `instance` is an
// operator disclosure, so a deployment may leave it out; ask the operator
// for the DID then.
const { description } = await pws.service()
const serverDid = description.instance?.serverDid
if (serverDid === undefined) {
throw new Error('This server does not disclose its DID.')
}
// The pull capability: GET-only, rooted in the peer Space, delegated to that
// DID.
const capability = await peerPws.spaceAt(peerSpaceUrl).grant({
to: serverDid,
actions: ['GET']
})
const registration = await space.registerReplica({
id: 'peer-1', // client-chosen and URL-safe
fromSpace: peerSpaceUrl,
toSpace: space.url,
capability,
collections: [{ id: 'credentials' }], // omit to pull every Collection
role: 'source'
}) // the stored ReplicaRegistration
const listing = await space.replicas() // { url, totalItems, items } | null
const one = await space.replica('peer-1') // ReplicaRegistration | null
const status = await space.replicaStatus('peer-1') // ReplicaStatus | null
// status.state: 'idle' | 'pulling' | 'paused' | 'backing-off' | 'stalled'
for (const entry of status?.collections ?? []) {
if (entry.state === 'stalled') {
// entry.stall: { reason, since, detail? }
}
}
// Stop and restart the pull loop. The registration keeps its id and its
// checkpoint, and the data already pulled stays.
await space.pauseReplica('peer-1') // status.state reads 'paused'
await space.resumeReplica('peer-1')
// Swap the pull capability in place, before the signer that delegated the
// old one is withdrawn. Same id, same checkpoint.
await space.replaceReplicaCapability('peer-1', renewedCapability)
// The data already pulled under the registration stays. 'not-found' is the
// server's masked 404: absent, or the caller holds no authority on the route.
const { outcome } = await space.deregisterReplica('peer-1') // 'deleted' | 'not-found'pauseReplica(), resumeReplica() and replaceReplicaCapability() are each
one PUT of the registration at its URL, run as a compare-and-swap: the client
reads the stored record with its ETag, writes it back under If-Match, and
re-reads and re-applies the change on a 412, so a write that lands in between is
rebased on rather than clobbered. PreconditionFailedError (412) surfaces only
after the attempt limit. A pause sets pausedAt, which the server fills with
its own time and keeps while the registration stays paused, and a resume omits
it. Only capability and pausedAt may change on a stored registration. All
three throw NotFoundError on the masked 404, since a PUT at an absent
registration would register a new replica. A replacement capability is checked
against the peer the way registerReplica() checks one, so it can throw the
same ConflictError (replica-refused) and ValidationError.
replicaStatus() reports the pull loop's runtime state. The response is
uncacheable and is not part of the registration record. Each Collection entry
has its own state (synced, syncing, stalled, or skipped). A stalled
Collection keeps its checkpoint until the cause is removed, and the other
Collections continue. Its stall.reason is one of:
clock-bound-- a received write stamp is dated further ahead of local time than the server allows. It clears as local time catches up.fork-- a history log or an immutable Collection member differs from the local one in a way no write order resolves.quota-exceeded-- applying the change would exceed a local quota.unsupported-backend-- the Collection names abackendthis server has no registration for.container-refused-- the local Space or Collection refused the write.
Every replica method takes the controller's capability or a delegated one whose
chain roots in the Space's root capability, for GET, POST, PUT and
DELETE alike. A delegated POST may only name a fromSpace the Space already
has a registration for. Any other caller gets the masked 404, as does every
delegated caller on a server that still treats the route as controller-only.
replicas(), replica(), and replicaStatus() then return null, and
registerReplica() throws NotFoundError. deregisterReplica() reports it as
{ outcome: 'not-found' } rather than swallowing it, so such a caller can tell
that nothing was removed. The three reads reserve null for that 404. A 2xx
with no JSON body is a server fault and throws PwsServerError.
A grant on the route targets {spaceUrl}replicas, the bare URL with no trailing
slash. spaceReplicasUrl({ spaceUrl }) on the ./paths entry forms it, and
replicaRegistrationUrl({ spaceUrl, replicaId }) forms one registration beneath
it. fromCapability refuses that target as a reserved sub-resource, so the
holder opens the Space handle with pws.space(id, { capability }) (or
pws.spaceAt(url, { capability })) and calls the replica methods on it.
registerReplica() throws ValidationError (400 invalid-request-body) for a
malformed body. Each entry of the error's problems carries a pointer naming
the offending member. It throws ConflictError (409) for two refusals, told
apart by the error's type URI:
replica-refused(ProblemTypes.REPLICA_REFUSED) -- the server refuses the peer. For example, the peer Space'scontrollerortypediffers from this one, the peer advertises no replication, the capability's controller is not this server, or a listed Collection's immutable members differ. The cause is in the error'sdetails.id-conflict(ProblemTypes.ID_CONFLICT) -- a registration with thisidalready exists.
import { ProblemTypes } from '@interop/pws-client'
try {
await space.registerReplica(registration)
} catch (err) {
if (err instanceof ConflictError && err.type === ProblemTypes.ID_CONFLICT) {
// already registered under this id
} else {
throw err
}
}deregisterReplica() throws ConflictError (replica-refused) when the
registration is the one that maps this Space's did:webvh controller. Removing it
would leave the Space with no way to follow its controller's log.
A peer advertises replication in its service description, under
specs['https://w3id.org/pws/replication'] (version 0.1 on the reference
server). A registration is per-server state. It is not replicated, it is not
part of an export, and deleting the Space removes it. space.describe()
surfaces the Space's registrations as the read-only replicas member, one
{ fromSpace, toSpace, role } summary per peer, with no registration id and no
capability. The server ignores replicas in a write body.
This is the recommended way to use encrypted collections. For the low-level
alternative -- driving an EdvClientCore directly via PwsTransport, which is
also how to stream a blob you do not want to hold in memory -- see
docs/edv-client-core-usage.md.
Client-side end-to-end encryption is a per-collection concern -- not a backend feature (an encrypted document is opaque JSON any document backend stores faithfully). Two things drive it, kept separate:
- Policy (is this collection encrypted?) is declared on the collection
itself:
createCollection({ encryption: { scheme: 'edv' } })writes a non-secretencryptiondescriptor to the Collection Metadata object. Any authorized reader -- including a delegated consumer that did not create the collection -- discovers it by reading that object, so it knows to decrypt. - Keys come from an
encryptionprovider you pass toPwsClient(built from the opt-in@interop/pws-client/edvsubpath, so plaintext consumers never pull the crypto graph). It is a pure keystore:resolveKeysreturns the collection's keys, which live in your wallet. The server only ever stores opaque JWE envelopes.
The ordinary Collection/Resource handles then transparently encrypt on write
and decrypt on read for any collection the descriptor (or an override) declares
encrypted.
import { PwsClient } from '@interop/pws-client'
import { createEdvEncryption } from '@interop/pws-client/edv'
const encryption = createEdvEncryption({
// The keystore: return the collection's keys (from your wallet).
async resolveKeys({ spaceUrl, collectionId }) {
return { keyAgreementKey, keyResolver }
}
})
const pws = PwsClient.fromSigner({ baseServerUrl, signer, encryption })
// Declare the collection encrypted (writes the descriptor). The returned handle is
// pre-seeded, so the first write encrypts with no extra round-trip.
const vault = await pws
.spaceAt(spaceUrl)
.createCollection({ id: 'vault', encryption: { scheme: 'edv' } })
const { id } = await vault.add({ secret: 'hello' }) // encrypted; id is an EDV id
const back = await vault.get(id) // { secret: 'hello' } -- decrypted
// A consumer that did not create it discovers the descriptor and decrypts with its
// own keys -- no override needed; one cached read of the Collection Metadata
// object:
const same = pws.spaceAt(spaceUrl).collection('vault')
await same.get(id) // reads the descriptor, then decryptsThe switch is the descriptor: a handle encrypts a collection when its
Collection Metadata object declares encryption (resolution reads that object
once, then caches -- no round-trip for plaintext-only clients or when an
override is set). Keys are then required: if the collection is declared
encrypted but your keystore returns no keys, reads/writes throw
EncryptionError (fail-closed) instead of silently falling back to plaintext.
Per-handle override (escape hatch). Pass encryption in the handle options
to force the decision and skip the Collection Metadata read --
{ scheme: 'edv' } (keys from the keystore), { scheme: 'edv', keys } (keys
inline), or 'plaintext':
const vault = pws.spaceAt(spaceUrl).collection('vault', {
encryption: { scheme: 'edv' }
})Migrating a pre-descriptor vault (created before the descriptor existed,
keys-only): the descriptor is creation-only. A conforming server refuses a write
that adds it to an existing collection, and one that changes or clears it
(ConflictError, encryption-immutable). Create a new collection with the
descriptor and copy the resources into it. Until then, a per-handle override
reads the old collection correctly.
Encrypted collections are a stricter contract, not a drop-in (documents-only scope for now):
- Ids.
add()mints an EDV id (az-prefixed multibase value used verbatim as the PWS resource id).put(id, ...)accepts only an EDV-format id; a human-readable id is rejected (it would leak onto the URL) -- carry a human-readable label inside the encrypted content instead. By default the minted id is random (the classic mutable-document model); passcreateEdvEncryption({ idDerivation: 'content' })to derive it from the envelope's JWE ciphertext instead, making documents content-addressed -- the id is then stable across replicas (no mapping table), at the cost of immutability (an "update" is delete-old + add-new). - Metadata.
resource.setName()/setTags()/setMeta()work on an encrypted collection: the user-writablecustom(name/tags) is encrypted into an envelope before it is sent, so the server never sees the plaintext, andmeta()decrypts it back for a keyed reader. The/metaendpoint has its own ETag, independent of the content ETag. The same pair at Collection level (collection.setName()/setTags()/setMeta()/meta()) is where an encrypted collection carries its own name and tags, since the Collection Metadata object's plaintextnameis left unpopulated; the collection-level envelope binds no resource id, and a resource-bound envelope served into that slot is refused. - Binary. A
Blob/Uint8Arrayup tomaxBlobBytes(512 KiB by default) is encrypted as a single document. A larger one is routed automatically byadd()to the chunked-stream path: one document plus its chunk resources, read back transparently byget(). Serving the chunk endpoints is a conformance requirement of a server that offers encrypted collections, so there is no client-side gate -- one that does not answers501.put(id, bigBlob)takes the same route, creating the resource where none is stored atid(passifNoneMatch: trueto get a412when the id is taken) and replacing the document otherwise. Replacing a chunked document, with a blob of any size or a JSON value, reaps the chunks the new document does not cover once it is stored. One limit applies: a content-addressed collection (idDerivation: 'content') refuses a chunked write, since it stores the document twice and no single ciphertext derives its id. A chunked create that fails partway deletes what it wrote, and a507surfaces asQuotaExceededError. One that could not clean up, and a replace that fails partway, leave a pending stub, which every read refuses; the EDV doc cipher'sisPendingStubrecognizes it, the nextput()at the id replaces it, anddelete()removes it with its chunks. Tune the threshold and the chunk size withcreateEdvEncryption({ maxBlobBytes, chunkSize }). - Streams. A
ReadableStream<Uint8Array>has no known size, soadd()always routes it to the chunked-stream path, however short it is. It is encrypted and written as it is read, without buffering.put(id, stream)takes the same route, creating or replacing the document atid. A content-addressed collection refuses a stream for the reason it refuses a large blob. A write that fails midway cancels the stream, so the source behind it is released. The content type isoptions.contentType, then a guess from the id's extension, thenapplication/octet-stream. To read without buffering, callresource.getStream()orcollection.getStream(id). ItscontentTypeis the bare media type, with no parameters, on every collection. For a chunked document the stream fetches and decrypts each chunk as it is read. A missing chunk therefore errors the stream, withNotFoundError, rather than thegetStream()call; a tampered one errors it withEncryptionError.get()still returns aBlob. - Raw reads.
get()decrypts; thegetText()/getBytes()escape hatches do not (they return the stored representation).
Working offline. A consumer that only decrypts bytes it already holds --
opening an archived collection, say -- has no server to reach. Import
@interop/pws-client/edv/core instead of @interop/pws-client/edv: it is the
same codec, doc ciphers, key epochs, recipient operations, blinding keys,
resourceDescriptorStore, and the log-governed descriptor stores, with every
transport module left out of the import graph. collectionDescriptorStore stays
on ./edv, since it reads through a live Collection handle. The example below
leaves spaceUrl unset. A cipher told which Space its collection lives in loads
the transport factory for the chunked paths. A cipher with no Space still reads
a chunked envelope when decrypt is given a chunkSource, a function that
serves each chunk ({ docId, chunkIndex } to the parsed chunk, or undefined)
from bytes you already hold. A missing chunk throws NotFoundError, and
blobBytes (also on this entry) reads the resulting Blob on every platform,
React Native included.
import { createEdvDocCipher } from '@interop/pws-client/edv/core'
const cipher = await createEdvDocCipher({
keyAgreementKey,
keyResolver,
collectionId,
encryption // the archived collection's encryption descriptor
})
const data = await cipher.decrypt({ id, envelope })A consumer that also wants no resource-log dependency --
@interop/wallet-backup opening an archive with no log to verify, say --
imports @interop/pws-client/edv/cipher instead: the same codec, doc ciphers,
key epochs, recipient operations, blinding keys, and resourceDescriptorStore,
without ./edv/core's log-governed descriptor stores. Importing it evaluates no
@interop/vh-resource-log or @interop/did-method-webvh module, on top of no
transport module.
Online consumers keep importing @interop/pws-client/edv and nothing changes
for them: it re-exports everything ./edv/core does (which in turn re-exports
everything ./edv/cipher does) and adds the transport (PwsTransport,
createEdvEncryption, descriptor acquisition and refresh).
An encrypted collection can be searched by attribute without the server ever learning the attribute names or their values: the client blinds both into HMAC tokens (equal plaintext blinds to equal tokens, and nothing else), stores them alongside the ciphertext, and blinds the query the same way. The server compares opaque strings.
The blinding key is installed with the collection's first key epoch or never -- retro-fitting one would leave every already-written document unindexed -- so ask for it at provisioning time:
await ensureFirstEpoch({
collection: declared,
recipients: [ownerRecipient({ keyAgreementKey })],
blindedIndex: true // searchable: a property fixed at birth
})Then declare what is searchable and search it:
const vault = pws.spaceAt(spaceUrl).collection('vault')
await vault.declareIndex({ attribute: 'content.type' })
await vault.add({ type: 'note', title: 'alpha' })
const page = await vault.find({ equals: { 'content.type': 'note' } })
// { items: [{ id, data: { type: 'note', title: 'alpha' } }], hasMore: false }
const { count } = await vault.find({
equals: { 'content.type': 'note' },
count: true
})Attribute names are dotted paths rooted at content or meta (the document's
own meta, which carries the content type and encoding -- not the PWS /meta
name/tags, which live in a separate envelope and are deliberately not indexed).
Pass an array of names for a compound index, searchable by a leading prefix of
its attributes; unique: true makes the server answer a colliding write with
409. Give find() either equals (an array of objects is an OR of
alternatives) or has (attribute names a document must carry); page with
limit and the returned cursor.
Two properties are worth planning around:
- Declarations are collection state, not app state. The schema is persisted
inside the collection's encrypted metadata envelope, so any recipient
discovers it -- read it with
collection.indexes(). That is what lets an app granted access to an existing collection learn what is queryable; the stored tokens cannot teach it, being blinded. Concurrent declarations reconcile through the metadata ETag rather than overwriting each other. - Declarations are prospective. A document written before an attribute was
declared carries no token for it and does not match until it is rewritten
(each entry's
addedInrevision records when it became searchable). Searching an attribute the schema does not declare throwsValidationErrorrather than silently matching nothing.
Serving the blinded-index query profile is a conformance requirement of a server
that offers encrypted collections; one that does not answers 501
(NotImplementedError). find() / declareIndex() on a plaintext collection
throw -- there is no client-side index there.
collection.setMeta({ custom }) replaces the whole custom object, with one
exception: a custom that does not name indexSchema keeps the stored schema.
A custom that does name it is sent as given, so indexSchema: undefined drops
the stored schema. The setName() / setTags() sugar merges and leaves it
intact either way.
The opt-in @interop/pws-client/sync subpath supplies everything a wallet needs
to replicate one Space + Collection across devices, with PWS as the primary
copy. It is not a sync engine itself -- it provides the seams a change engine
plugs into:
createPwsSyncPort({ pws, spaceUrl, collectionId })builds aPwsSyncPort: paged pulls over the collection'schangesfeed (resumable via an opaque server-side checkpoint) and conditional pushes (putContent/deleteContent/putMeta) guarded by the server's contentETag. A pull hands back the feed's JSON Resources and their tombstones only, with the feed'sdeletedrenamed_deleted; the Collection's owncollection-metadataandlogentries, binary Resources, and any kind the client does not know are skipped, and the checkpoint still moves past them. The port moves stored bodies verbatim -- for an encrypted collection that means the opaque EDV envelope, never plaintext, and the port itself never touches keys. A rejected precondition throwsPwsSyncConflictError(412); a delete of an already-gone resource or aputMetaagainst one throwsPwsSyncNotFoundError(404) -- both catchable subtypes of the corePreconditionFailedError/NotFoundError; aquerywhose checkpoint the server did not issue throwsPwsSyncCheckpointError(400, aValidationErrorsubtype), and the pull restarts from the beginning. Every other failure arrives as the typedPwsErrorsubclass for its status, carrying the server'sproblem+jsonfields.isSyncConflictError/isSyncNotFoundError/isSyncCheckpointError/isSyncAuthError/isUnknownEpochError/isKeyUnwrapError/isNotCurrentRecipientError/isIntegrityErrorclassify those signals byerr.name. Use them rather thaninstanceof: the port and theDocCipherare seams your app injects, and a tree that resolves two copies of this package makes aninstanceofcheck quietly false. Read what you need off the matched value, such aserr.statuson an auth error to tell a 401 from the masked 404. The last two tell a decrypt's two no-key outcomes apart: an epoch the reader's descriptor does not list (a re-read may fix it) and an epoch it lists but this reader holds no key for (real data, permanently unreadable here, never garbage).isIntegrityErrormatches a stored body that does not verify against the resource id it was read under, a sealed envelope whose AEAD tag fails for a key this reader holds, or a descriptor recipient entry addressed to this reader whose wrapped epoch key fails its integrity check. Do not apply that row.SyncStatus('idle' | 'syncing' | 'synced' | 'error') is the closed vocabulary a replication driver reports one feed's state through.DocCipheris the per-collection encrypt/decrypt seam sitting above the port: it turns a JSON document into its stored body (minting the resource id) and back.decrypt({ id, envelope, context? })takes the resource id the replica read the body under (the feed row'sid, not the envelope's own) and throwsIntegrityErrorwhen the body was written for a different id. Passcollection.codecContext()ascontextto read a chunked encrypted blob, which then decrypts to aBlob.createPlaintextDocCipher(...)is the crypto-free identity implementation for a plaintext content-addressed collection;createEdvDocCipher(...)(from@interop/pws-client/edv) is the encrypting one, built from the collection's key-epoch descriptor (every encrypted collection carries one from birth; install epoch[0] at provision time withensureFirstEpoch). Build it with the collection'sspaceUrlto letdecryptfetch a chunked blob's chunks, or passdecryptachunkSourceto serve them from bytes you hold. On a searchable collection, also hand it the stored Collection/metavalue (themetainput, orapplyMetawhen the replica's copy changes) so pushed documents carry blinded index entries and stay visible tofind().createEdvEncryptOnlyDocCipher(...)is the write-only counterpart, built from the descriptor alone with no key-agreement secret (writes seal to the current epoch's public key, reconstructed from the epoch id);decrypton it refuses with the typedEncryptOnlyCipherError.createRefreshingEdvDocCipher(...)(from@interop/pws-client/edv) iscreateEdvDocCipherbound to descriptor acquisition and the unknown-epoch refresh rule: it acquires the collection's descriptor through theEncryptionDescriptorSource/EncryptionDescriptorCacheseams (pwsDescriptorSourceis the source over aPwsClient; the cache is a client-local get/put your app scopes to one Space), refuses fail-closed to build without one, and on anUnknownEpochErrordecrypt re-reads the descriptor, swaps itself, and retries exactly once per instance. A descriptor that carrieshistory(a log-governed collection) is refused withUnverifiedDescriptorErrorunless its source declaresverifiesHistory: true;pwsDescriptorSourcedoes not. An epoch rotation emits no Resource entry in the change feed, so this is how a replica meets an envelope sealed under an epoch it has never seen without a refetch per resource.acquireDescriptor/acquireDescriptorsare the acquisition alone (fetch, cache the success, fall back to the cache whenever the fetch yields no descriptor), andDescriptorRefreshPolicyis the once-per-collection-per-session guard for a host whose reads scan rows instead of going through a cipher.contentCid(doc)andderiveSpaceId(controllerDid)derive content-addressed ids --base64url(SHA-256(utf8(JCS-canonicalized JSON))), unpadded -- so the same logical document (and the same controller) lands on the same id on every replica, with no coordination or mapping table.ensureSpaceAndCollection(...)is idempotent provisioning: upsert the Space, configure the collection (edv,plaintext, orgoverned, optionally world-readable). Safe to re-run on every connect with the same mode. Agovernedcollection is created with noencryptionmember, the caller declaring governance afterwards through the history log's guarded create. A standing collection keeps the mode it was created in, becauseencryptionis creation-only. A call that asks for a different mode throwsValidationErrorand leaves the collection as it is. That includes theedvdefault over a collection with no descriptor, which is either plaintext (create a new collection and copy the resources into it) or governed with its log not created yet (provision it asgoverned). An optionalcapabilityis the invocation capability every request rides, for a client holding a delegated zcap rather than the Space's root authority. It resolves{ created }:truewhen its own guarded create made the collection, andfalsewhen the collection already stood or a rival won the create race.
import {
createPwsSyncPort,
createPlaintextDocCipher,
ensureSpaceAndCollection,
isSyncConflictError
} from '@interop/pws-client/sync'
// The Space URL is received, then stored: the same Space on every client.
const spaceUrl = storedSpaceUrl
await ensureSpaceAndCollection({
pws,
spaceUrl,
controllerDid,
collectionId: 'notes',
encryption: 'plaintext'
})
const port = createPwsSyncPort({ pws, spaceUrl, collectionId: 'notes' })
const cipher = createPlaintextDocCipher({ collectionId: 'notes' })
// Push: encrypt (mints the id), then write the stored body verbatim.
const { id, envelope } = await cipher.encrypt({ data: { note: 'hello' } })
try {
await port.putContent({ id, data: envelope, ifNoneMatch: true })
} catch (err) {
if (!isSyncConflictError(err)) {
throw err
}
// 412 on a content-addressed insert: another replica already wrote this
// exact document (same content id) -- a settled outcome, nothing to merge.
}
// Pull: page through the change feed, resuming from the last checkpoint.
let checkpoint
do {
const page = await port.query({ checkpoint, limit: 100 })
for (const doc of page.documents) {
if (doc._deleted) continue // tombstone
const data = await cipher.decrypt({ id: doc.id, envelope: doc.data })
// apply to the local replica, recording doc.etag for later pushes
}
checkpoint = page.checkpoint // null when the page pws empty (caught up)
} while (checkpoint)The subpath is crypto-free: importing it never pulls the ./edv dependency
graph. To sync an encrypted collection, keep the same port and swap in
createEdvDocCipher -- the change feed and the port ship the envelope bytes
unchanged either way, so the server never sees plaintext. If the collection
carries a blinded-index key, pass the cipher the stored /meta value
(meta: { custom }) so its writes emit the same blinded index tokens a
Collection-handle write does; a cipher built without it writes documents
find() cannot see until they are rewritten.
collection.changes() reads one page of the raw feed, and sends the query as a
POST by default. Pass method: 'GET' for the read-only form,
GET .../query?profile=changes&checkpoint=...&limit=.... The server verifies it
under the GET action and answers the same ChangesPage. A caller holding a
GET-only capability, such as a pull capability, reads the feed this way. The
POST form refuses that capability with NotFoundError.
const page = await collection.changes({ method: 'GET', checkpoint, limit: 100 })The opt-in @interop/pws-client/log subpath is the PWS binding of
@interop/vh-resource-log's store port. Resource logs -- the hash-linked, JSON
Lines log format (the encrypted-collections spec's Resource Log Profile)
governing key resources co-managed between a wallet's clients and the storage
server, such as encryption descriptors and key rosters -- otherwise live in that
library: the JSON Lines codec, the ResourceLogStore port, the read-back
confirmAppend, chain verification, and the chain-head pin. The wire types
(ResourceLogEntry et al.) live in @interop/storage-core. This subpath
re-exports none of them.
resourceLogStore({ resource })/resourceLogStore({ collection })-- the port over one of the two places a PWS server keeps a log, stored astext/jsonleither way: a PWS Resource whose whole body is the log (a key roster), or a Collection's governing history log at its/meta/logsub-resource (the descriptor the server derivesencryptionfrom; see "The governing history log" above). The store does read-with-etag of the full log, compare-and-swap append conditioned on that etag, and the guarded create of a genesis entry. Appends carry the prior lines' bytes forward verbatim. Both writes ride the server's conditional writes, which the profile requires; a lost race rethrows the library'sResourceLogConflictErrorwith the transport'sPreconditionFailedErrorascause.
const archive = await space.export() // Uint8Array (application/x-tar)
const stats = await otherSpace.import(archive)
// { collectionsCreated, collectionsSkipped, resourcesCreated, resourcesSkipped,
// policiesCreated, policiesSkipped }export() buffers the whole tar archive into memory, which is the simplest
shape for small spaces. Two additive companions cover the large-space and
container cases:
// Constant memory: pipe the archive straight to a file / upload / compressor,
// without buffering the whole space into RAM. The stream must be consumed or
// cancelled (an abandoned stream holds the connection open).
const stream = await space.exportStream() // ReadableStream<Uint8Array>
// A Blob typed `application/x-tar`, the direct companion to import(). Copying a
// space is a one-liner:
const stats = await otherSpace.import(await space.exportBlob())Pick by size: exportStream() for a large space, exportBlob() when you want
the import() companion or a browser download, and export() for a small space
or when you need the bytes anyway. (In Node a Blob is memory-backed, so
exportBlob() does not lower peak memory versus export(); browsers may spill
large Blobs to disk.)
pws.request(...) mirrors ezcap's generic request() for hand-built calls. It
takes an absolute url. As a deliberate escape hatch it returns the raw
HttpResponse and throws raw ezcap/ky errors -- it does not apply the
null-on-404 or typed-error conveniences. It still waits on service discovery, so
against an incompatible server it rejects with IncompatibleServerError.
const response = await pws.request({ url: space.url, method: 'GET' })Read methods (describe/get/list) return null on a 404, following
MongoDB's findOne semantics. PWS returns 404 for both not-found and
unauthorized, so null means "not visible to you" rather than strictly "does
not exist". Write/delete methods throw a typed error instead.
| Status | Read methods | Write / delete methods |
|---|---|---|
| 404 | null |
NotFoundError |
| 400 | ValidationError |
ValidationError |
| 401 | AuthRequiredError |
AuthRequiredError |
| 409 | ConflictError |
ConflictError |
| 422 | ValidationError |
ValidationError |
| 413 | PayloadTooLargeError |
PayloadTooLargeError |
| 501 | NotImplementedError |
NotImplementedError |
| 507 | QuotaExceededError |
QuotaExceededError |
| 5xx | PwsServerError |
PwsServerError |
All error classes extend PwsError (carrying status, the problem-kind type
URI, title, details, and requestUrl). When the server sends a
problem+json type (the spec's Error Type Registry), mapError() dispatches
on that kind first and falls back to the HTTP status -- so, for example, a 409
id-conflict from createSpace({ id }) is catchable as a ConflictError, and
a 507 quota-exceeded (a client-actionable storage-full condition, not a server
fault) as a QuotaExceededError. delete() additionally treats a 404 as
success, so it is idempotent; Space.deleteWithOutcome() reports that outcome
instead, as { outcome: 'not-found' }, rather than swallowing it.
Spec endpoints a given server has not yet implemented surface as
NotImplementedError (the server's 501).
The client-side errors (EncryptionError and its subtypes, NotSupportedError,
UnknownEpochError) are PwsErrors too; they carry no status. An
UnknownEpochError carries the collectionId whose descriptor to re-read and
the envelope's unroutable kids. A NotCurrentRecipientError (an
EncryptionError) is a refused write: this reader is named in older key epochs
of the Collection and not in the current one, so it still reads and no longer
encrypts. It is thrown before any request is sent. Writes that seal nothing are
not refused. After a current recipient re-adds the reader, the same handle
writes again. A createEdvDocCipher cipher must be rebuilt, and a
createRefreshingEdvDocCipher cipher retries once on its own.
IncompatibleServerError comes from service discovery, not from a response
status. Any signed method, read methods included, throws it when the server
speaks no PWS version this client understands (see
Service discovery). It carries no status, so a read
method does not mistake it for a 404.
PRs accepted. See CONTRIBUTING.md for editor setup (Prettier, ESLint, and EditorConfig) and how it maps to CI.
MIT License © 2026 Interop Alliance.