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”.
flowchart TD
Controller["Controller<br/>a DID, such as did:key:z6Mk…"] -->|owns| Space["Space"]
Space --> C1["Collection: notes"]
Space --> C2["Collection: photos"]
C1 --> R1["Resource: hello"]
C1 --> R2["Resource: ideas"]
C2 --> R3["Resource: sunset.png"]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 concept | Portable Web Spaces counterpart | Status here |
|---|---|---|
AID (did:keri:…) | The Space’s controller DID | did:key only. did:keri is refused |
| KEL, rotation, pre-rotation | The “current key set” rule, and did:webvh pre-rotation | Dormant. It needs a method with a verifiable key history |
| ACDC grant (consent, expiry) | A delegated capability, narrowed by target, actions and expiry | Built and tested. Not yet tied to Companion Memory’s grants |
| TEL revocation | Capability revocation | The 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 version | The 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 response | Built. The closest counterpart, not an equivalent |
| Witnesses and watchers | None | None |
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"sequenceDiagram
autonumber
actor Owner as Owner
actor Friend as Friend
participant Server as Space server
Owner->>Owner: Sign a capability to read the notes Collection until 5 December
Owner-->>Friend: Hand over the capability
Friend->>Server: GET notes/hello, signed with the friend's own key,<br/>carrying the capability
Server->>Server: Check the signature, the chain back to the owner,<br/>the target, the action and the expiry
Server-->>Friend: 200 OK with the Resource
Friend->>Server: PUT notes/hello, which the capability does not allow
Server-->>Friend: 404 Not Found, the same answer a stranger getsWhat the server checks
A request is served only when every one of these holds.
- The HTTP signature is well formed, covers the headers the standard requires, and is inside its time window.
- The signing key is listed for invoking capabilities in its owner’s DID document today.
- The body matches its signed
Digest. - 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.
- The capability covers this URL and this action, and its controller is the key holder who signed the request.
- 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
DELETEmay 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
404with the same text. A write with no credential at all gets401(“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 precise400.) - A capability that has expired is called expired (still
404, with the kindcapability-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 gets409. - Public sharing is a policy on a Space, a Collection or a Resource:
PublicCanReadlets anyone read what is beneath it. It never allows a write: a write with no credential gets the401above 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
POSTor 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
| Capability | Status |
|---|---|
| Create, read, update and delete Spaces, Collections and Resources, with listing and paging | Built as a library |
| Verify signed requests: HTTP signature, body digest, capability invocation | Built as a library |
| Delegate narrower capabilities, in chains of at most 10 capabilities, each with an expiry | Built as a library |
Public-read policy, linksets, the service description, metadata and ETag conditional writes | Built as a library |
A clock-ordered stamp (updatedAt, updatedAtCounter, originId) on every Space, Collection and Resource | Built, as an extension: the draft defines only an optional updatedAt, the conformance suite requires all three |
Controllers written as did:key | Built |
Controllers written as did:keri | Refused on purpose |
Controllers written as did:webvh | Not built |
| Durable storage | Not built. The store is in memory and holds contents in RAM |
| A route in the API, a setting or a screen | Not built |
| Revoking a capability before it expires | Not built. Only a hook exists: the standard defines no revocation yet |
| Encrypted Collections, chunked uploads, search and change feeds, quotas, storage backends | Not 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 Space | Not built. The standard’s format is still a proposal |
| Copying a Space between servers | Not built |
| Turning Companion Memory’s consent grants into capabilities | Not 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
Ed25519Signature2020delegations (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
Ed25519Signature2020format. Onlyeddsa-jcs-2022proofs 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 idempotent204the 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 optionalupdatedAton 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 get404, and lists401only for creating a Space; the conformance suite requires401, and this code follows the suite. - A
PUTthat 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: sandboxandX-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-MatchandIf-None-Matchdo not stop a replay, because the signature does not cover them. Keep signatures and capabilities short. - A
did:keynever 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:
- Run this code’s own client against the reference server, the one direction of the interoperability check that is still open.
- Keep Spaces in the database.
- 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.
- Turn consent grants into capabilities, and revoke them through the revocation hook.
- Use a Space as a target for the data export and import.
- Support
did:webvhcontrollers, and a KERI bridge only if a KERI resolver that implements the published specifications ever ships. - Add encrypted Collections and copying between servers.
Standards used
- Portable Web Spaces , draft version 0.5
- Portable Web Spaces Authorization Profile , version 0.1: capabilities over HTTP Signatures, the root capability, delegation, the
Digestheader and thePublicCanReadpolicy
Related
- Decentralized trust (KERI and ToIP) — the identity design this sits beside, and what of it runs today
- Asking and sharing architecture — how grants and disclosure ceilings work
- Asking other Companions — the
/asksscreens