Skip to Content
DocumentationCompanion MemoryPortable Web Spaces alongside KERI

Portable Web Spaces alongside KERI

Portable Web Spaces  (PWS) is a draft from the W3C Credentials Community Group (a community draft, not a W3C Recommendation; this page calls it “the standard” for short) for keeping data in a space that you control. It was called Wallet Attached Storage until September 2026. A Space holds Collections, and a Collection holds Resources: files, JSON documents, anything. Everything is private until the Space’s owner says otherwise. A request is allowed only if it carries proof that the owner, or someone the owner delegated to, authorized it. Anyone else is told “not found”, the same answer as for something that does not exist, so the answer does not tell a stranger what is there (creating a Space under a chosen name is the one exception, below).

Status. The Portable Web Spaces server is fully implemented and mounted in Companion Memory at /pws/* (PwsModule / PwsController). It is kept off by default behind the ENABLE_PWS_STORAGE=true feature flag. When disabled, all routes return 404 Not Found.

The implementation passes 203 of 305 checks in the Interop Alliance’s conformance suite (the remaining failures are unbuilt extensions such as Encrypted Collections) and reproduces published reference vectors byte-for-byte.

Why Companion Memory cares

Companion Memory holds a person’s archive. Four goals or properties of the standard fit what that needs.

  • Data in a space you control. A Space has one owner, called its controller, named by an identifier (a DID) whose key the owner holds. Whoever hosts the Space is not the root of trust.
  • Moving without breaking shares. Moving to another provider while the links and permissions you already handed out keep working, even if the old provider has disappeared, is a stated goal of the standard. Companion Memory already exports and imports your data as an archive for backups and for moving to a new Hub; a Space is a candidate standard form for that. The standard states the goal but does not yet say how a capability that names one host keeps working on another, and its own export format is still a draft proposal, so none of this is built.
  • Sharing with a narrow, expiring capability. Instead of an account, you hand someone a signed note: this key may read this Collection until this date. They can pass on a narrower one. They can never widen it.
  • Private by default. Reading is authorized exactly like writing, and a request that is not authorized gets “not found”.

How it sits next to KERI

Decentralized trust (KERI and ToIP) is about one Companion recognising another. Portable Web Spaces answers a neighbouring question: where does data live, and who may touch it? Both need an identifier and a way to say “this key may act”.

Companion Memory does not build this on top of its KERI code, for three reasons.

  • The Companion Hub froze its KERI code on 30 October 2026, because it writes identifiers in a shape other KERI software cannot read.
  • Companion Memory’s peer key id, written did:keri:D<key>, is its own convention and not a CESR identifier.
  • The standard already says what a server does with an identifier it does not support.

A Space’s controller is a DID. The standard makes did:key (an Ed25519 key written as an identifier) the one method every server must support, lists every other method as optional, and says a server must refuse a controller whose method it does not support, with a 400 error. Companion Memory therefore refuses did:keri. That is the refusal the standard prescribes, not an extra rule, and it includes Companion Memory’s own did:keri:D form. A test covers it.

The place a KERI resolver would plug in is explicit: a short list of the DID methods the server can resolve. A KERI resolver that implements the published KERI specifications would be added there when one exists. Nothing here claims that it does.

KERI conceptPortable Web Spaces counterpartStatus here
AID (did:keri:…)The Space’s controller DIDdid:key only. did:keri is refused
KEL, rotation, pre-rotationThe “current key set” rule, and did:webvh pre-rotationDormant. It needs a method with a verifiable key history
ACDC grant (consent, expiry)A delegated capability, narrowed by target, actions and expiryBuilt and tested. Not yet tied to Companion Memory’s grants
TEL revocationCapability revocationThe standard does not define it yet. Only a hook exists
SAID (self-addressing digest)The Digest header, a hash of the request body, and the ETag versionThe digest is built. The ETag is an opaque version number, not a hash of the content
OOBI (/.well-known/keri/oobi/)A service description, found through a Link header on every responseBuilt. The closest counterpart, not an equivalent
Witnesses and watchersNoneNone

Keys are looked up on every request

The standard checks a signer’s key against the signer’s current DID document each time. A key that has been removed from the document stops working at once, together with everything that key delegated, with no revocation list involved. That is the standard’s rule, not KERI’s. A KERI rotation changes who may sign from then on, but what the old key signed or granted earlier stays valid against the keys in force at the time, and a grant is withdrawn by a revocation event in its log.

With did:key the document never changes, so today the rule has nothing to act on. A did:key cannot be rotated, and a stolen key can only be outlived by keeping capabilities short.

What a request looks like

Every request that is not a public read is signed with an Ed25519 key. Besides the usual headers it carries a Capability-Invocation header, which names the capability being used and the action, and a Digest header whenever there is a body. The signature covers those headers, so neither can be swapped afterwards. Line breaks inside Authorization are for display only.

1. The owner creates a Space. The zcap id= value names a root capability: the owner’s own authority over an address. Nobody issues it and the server derives it, so the header carries only its name.

POST /spaces/ HTTP/1.1 Host: example.com Content-Type: application/json Digest: mh=uEiC… Capability-Invocation: zcap id="urn:zcap:root:https%3A%2F%2Fexample.com%2Fspaces%2F",action="POST" Authorization: Signature keyId="did:key:z6Mk…alice…#z6Mk…alice…", headers="(key-id) (created) (expires) (request-target) host capability-invocation content-type digest", signature="…",created="1793880000",expires="1793880600" {"id":"family","name":"Family archive","controller":"did:key:z6Mk…alice…"}
HTTP/1.1 201 Created Location: https://example.com/space/family/ ETag: "4fq8za.1" Link: <https://example.com/service>; rel="service"

The created and expires values are Unix times in seconds. A signature is accepted for at most an hour, and a clock difference of up to five minutes is tolerated (the same tolerance applies to a capability’s expiry).

2. The owner writes a Resource, in a Collection called notes that was created the same way with a POST to /space/family/.

PUT /space/family/notes/hello HTTP/1.1 Host: example.com Content-Type: application/json Digest: mh=uEiCtvZgrj-… Capability-Invocation: zcap id="urn:zcap:root:https%3A%2F%2Fexample.com%2Fspace%2Ffamily%2F",action="PUT" Authorization: Signature keyId="did:key:z6Mk…alice…#z6Mk…alice…", headers="(key-id) (created) (expires) (request-target) host capability-invocation content-type digest", signature="…",created="1793880060",expires="1793880660" {"message":"hi"}
HTTP/1.1 204 No Content ETag: "9d2lqc.1"

3. The owner delegates read access. This is a document, not a request. It names who may use it (controller), what it covers (invocationTarget), what it allows (allowedAction) and when it ends (expires). The owner signs it, and the signature is the proof. The order of the members does not matter.

{ "@context": [ "https://w3id.org/zcap/v1", "https://w3id.org/security/data-integrity/v2" ], "id": "urn:uuid:6c9f3a1e-2b4d-4f8a-9c1e-7d2b3a4c5e6f", "parentCapability": "urn:zcap:root:https%3A%2F%2Fexample.com%2Fspace%2Ffamily%2F", "invocationTarget": "https://example.com/space/family/notes/", "controller": "did:key:z6Mk…bob…", "expires": "2026-12-05T12:00:00Z", "allowedAction": ["GET"], "proof": { "type": "DataIntegrityProof", "cryptosuite": "eddsa-jcs-2022", "created": "2026-11-05T12:00:00Z", "verificationMethod": "did:key:z6Mk…alice…#z6Mk…alice…", "proofPurpose": "capabilityDelegation", "capabilityChain": [ "urn:zcap:root:https%3A%2F%2Fexample.com%2Fspace%2Ffamily%2F" ], "@context": [ "https://w3id.org/zcap/v1", "https://w3id.org/security/data-integrity/v2" ], "proofValue": "z…" } }

4. The friend reads with it. The friend signs with their own key and attaches the capability, compressed and base64url-encoded, in Capability-Invocation. There is no body, so there is no Content-Type and no Digest.

GET /space/family/notes/hello HTTP/1.1 Host: example.com Capability-Invocation: zcap capability="H4sIAAAA…",action="GET" Authorization: Signature keyId="did:key:z6Mk…bob…#z6Mk…bob…", headers="(key-id) (created) (expires) (request-target) host capability-invocation", signature="…",created="1793880120",expires="1793880720"

What the server checks

A request is served only when every one of these holds.

  1. The HTTP signature is well formed, covers the headers the standard requires, and is inside its time window.
  2. The signing key is listed for invoking capabilities in its owner’s DID document today.
  3. The body matches its signed Digest.
  4. The capability traces back, link by link, to the Space’s controller. Each link was signed by the previous link’s controller, no link widens its parent in target, actions or lifetime, nothing has expired (with the same five-minute clock tolerance), and the chain has at most 10 capabilities counting the root, so nine delegations.
  5. The capability covers this URL and this action, and its controller is the key holder who signed the request.
  6. Only if the capability does not authorize, and only for a read, does the server look for a public-read policy.

A failure in steps 1 to 3 describes the request itself, so it is reported precisely as a 400. A failure in steps 4 to 6 gets the same “not found” a stranger gets. Creating a Space is the one exception, because there is no existing target to protect: a chain that fails there is reported as controller-mismatch, also a 400.

Controller-only operations

A capability for a container covers everything beneath it, so nothing about its target tells “delete this Collection” from “delete a Resource inside it”. Four operations are therefore reserved for the controller’s own key: rewriting a Space’s description, deleting a Space, rewriting a Collection’s settings and deleting a Collection. A delegated capability is refused for them, with two narrow exceptions:

  • A capability aimed at exactly the Space’s address whose only action is DELETE may delete the Space.
  • A capability aimed at exactly the Space’s address, or exactly the Collection’s address, may rewrite that Collection’s settings. It still cannot delete the Collection.

Adding a Collection with a POST, and everything inside a Collection, stays delegable.

What a stranger sees

  • A read with no credential, a request with a valid credential that does not authorize it, and a request for something that does not exist all get the same 404 with the same text. A write with no credential at all gets 401 (“sign in”) whatever the target, before the server looks at what exists, so it reveals nothing. (A credential that is itself malformed, or whose signature fails, is a different case: it describes the request, and gets a precise 400.)
  • A capability that has expired is called expired (still 404, with the kind capability-expired), but only to the one who holds it and signed with its key, after everything else about the request has checked out. Anyone else gets the plain “not found”.
  • Errors about a Space are not reported before the caller is authorized. A stranger who asks to create a Collection with an existing name gets 404. The owner gets 409.
  • Public sharing is a policy on a Space, a Collection or a Resource: PublicCanRead lets anyone read what is beneath it. It never allows a write: a write with no credential gets the 401 above even on something public. The policy itself is never public.
  • Creating a Space is the exception: anyone who can sign a request can learn whether an id is taken, whether by creating a Space with a POST or by writing to a Space’s description at an unused id, and a probe that succeeds creates the Space.

What is built and what is not

CapabilityStatus
Create, read, update and delete Spaces, Collections and Resources, with listing and pagingBuilt as a library
Verify signed requests: HTTP signature, body digest, capability invocationBuilt as a library
Delegate narrower capabilities, in chains of at most 10 capabilities, each with an expiryBuilt as a library
Public-read policy, linksets, the service description, metadata and ETag conditional writesBuilt as a library
A clock-ordered stamp (updatedAt, updatedAtCounter, originId) on every Space, Collection and ResourceBuilt, as an extension: the draft defines only an optional updatedAt, the conformance suite requires all three
Controllers written as did:keyBuilt
Controllers written as did:keriRefused on purpose
Controllers written as did:webvhNot built
Durable storageNot built. The store is in memory and holds contents in RAM
A route in the API, a setting or a screenNot built
Revoking a capability before it expiresNot built. Only a hook exists: the standard defines no revocation yet
Encrypted Collections, chunked uploads, search and change feeds, quotas, storage backendsNot built
Uploads from an HTML form (multipart/form-data)Not built. They are refused with 501; send the file as the raw body
Export and import of a SpaceNot built. The standard’s format is still a proposal
Copying a Space between serversNot built
Turning Companion Memory’s consent grants into capabilitiesNot built

A request to one of the endpoints of an unbuilt optional group gets 501 from an authorized caller and 404 from a stranger. A Collection that declares encryption is refused with 400.

What has and has not been checked

Done.

  • The building blocks are tested against the published test vectors of the standards they use: JSON canonicalization (RFC 8785), the Ed25519 signature scheme (RFC 8032), Base58 and Base64 encoding, SHA-256, and the W3C Data Integrity EdDSA example, whose proof value is reproduced from the published key.
  • More than 500 automated tests run the whole request path, including a round trip over a real network socket.
  • Defects were planted on purpose to prove the tests notice them. All 14 in the cryptographic building blocks were caught. In the access-control, request-handling and hardening code 78 of 80 were caught; the two that were not cannot be observed (one matters only once a second storage backend exists, the other duplicates a check that is already there).
  • An independent review before this page was published found defects in the access checks and in the documentation. The real ones are fixed, and each now has a test.
  • The reference libraries’ output was reproduced. The Interop Alliance’s libraries were run once, outside the repository, to produce signed requests and delegations for fixed inputs. This code produces the same headers, signatures and delegation proofs byte for byte, and verifies theirs.
  • The Interop Alliance conformance suite was run against it: 203 checks pass, 55 fail and 47 are skipped, out of 305. Whole groups pass: conditional requests, the rule about who may change a container, public-read policy, the service description, the body digest, method handling, and creating and listing Spaces and Collections. The first run failed 80: 55 are the failures below and 25 were this code’s to fix, and are fixed. All 55 that remain fail because a feature is not built: Encrypted Collections (39), storage backends, quotas and export or import (14) and the older Ed25519Signature2020 delegations (2). Seventeen of them never ran: the suite creates an Encrypted Collection first, so its checks that a stranger learns nothing did not execute here, and this project’s own tests cover that instead. The skipped checks are for features the code does not advertise.
  • The code imports nothing from Companion Memory’s peer or KERI code.

Not done: UNVERIFIED.

  • This code’s own client against the reference server. The reference client works against this server, and the reference libraries’ output reproduces here. The other direction, requests made by this code’s own client helpers being accepted by the reference server, has not been run. That server was read for behaviour and never executed.
  • The standard’s printed example. The signature in the standard’s own worked example of a signed request does not verify under the key it names, so it is treated as illustrative and was used only to check the layout of a request.
  • Delegations in the older Ed25519Signature2020 format. Only eddsa-jcs-2022 proofs are accepted, so two of the conformance suite’s checks for the older format fail.

Where it departs from the draft’s text.

  • Deleting a Space that does not exist answers 404, not the idempotent 204 the draft describes, because with no Space there is no controller to authorize against.
  • For changing a Collection’s settings, the draft’s operation text allows a capability aimed at the Space’s address, “rather than” one aimed at the Collection’s own address. The conformance suite expects the Collection’s own address to work too, and this code follows the suite. A holder of a write capability for one Collection can therefore rewrite that Collection’s settings.
  • The (key-id) pseudo-header in the signature is not defined by the HTTP Signatures draft the standard cites, but the reference libraries define it and the standard’s own example uses it, so it is what this code writes.
  • Every Space, Collection and Resource carries a clock-ordered stamp (updatedAt, updatedAtCounter, originId). The draft defines only an optional updatedAt on Collections and Resources (replication is an open proposal); the counter, the origin id and the millisecond precision are an extension that the reference server emits and the conformance suite checks for. Clients cannot set them.
  • A write with no credential is always 401. The draft says a request with no authorization at all must get 404, and lists 401 only for creating a Space; the conformance suite requires 401, and this code follows the suite.
  • A PUT that creates a Space or Collection answers with the object it created, as the suite and the reference client expect.

Security notes

  • User content cannot run as a web page on the API’s address. Resource content is served with Content-Security-Policy: sandbox and X-Content-Type-Options: nosniff. The cost is that a Collection cannot yet serve a working website.
  • A captured request can be replayed until its signature expires, at most an hour plus five minutes of clock tolerance. The standard has no one-time number, and If-Match and If-None-Match do not stop a replay, because the signature does not cover them. Keep signatures and capabilities short.
  • A did:key never rotates. A stolen key cannot be withdrawn, only outlived, so capabilities should be short-lived until a method with a key history is supported.
  • Using one identifier for several Spaces links them.
  • Nothing is encrypted. Whoever runs the server can read every Resource and all metadata, including who created each item and the optional writer label a client sends. Encrypted Collections are not built.
  • Response timing for requests that are not authorized has not been measured.
  • Nothing survives a restart. The only store is in memory.

What would connect it

None of this has started, and nothing here is scheduled. If it goes ahead, roughly in this order:

  1. Run this code’s own client against the reference server, the one direction of the interoperability check that is still open.
  2. Keep Spaces in the database.
  3. Put it behind a feature flag that defaults to off, the way Companion Memory’s existing Solid adapter is, with a security review before any route exists.
  4. Turn consent grants into capabilities, and revoke them through the revocation hook.
  5. Use a Space as a target for the data export and import.
  6. Support did:webvh controllers, and a KERI bridge only if a KERI resolver that implements the published specifications ever ships.
  7. Add encrypted Collections and copying between servers.

Standards used

Last updated on