From b51eec554b648cef9b856d60da937b750cce00db Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 19 Nov 2026 22:44:16 +0000 Subject: [PATCH 1/3] space-conformance: filter the garbage-cursor listSpaces call to the probe type An unfiltered listSpaces needs a wildcard space grant, so an OAuth session scoped to the probe type was refused with InsufficientScope before the cursor was read. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01LZ7qcQNQoiA6a23woGC7tB --- packages/space-conformance/src/checks/records.ts | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/packages/space-conformance/src/checks/records.ts b/packages/space-conformance/src/checks/records.ts index 88870deb..40d5eb1a 100644 --- a/packages/space-conformance/src/checks/records.ts +++ b/packages/space-conformance/src/checks/records.ts @@ -16,6 +16,7 @@ import { fail, pass, type Check, type CheckContext } from "../model.js"; import { bytesEqual, lexBytes, rawCid, sha256 } from "../encoding.js"; import { POST, + PROBE_TYPE, createProbeSpace, deleteProbeSpace, describe, @@ -761,7 +762,11 @@ const garbageCursor = defineCheck({ for (const [name, params] of [ ["com.atproto.space.listRecords", base], ["com.atproto.space.listRepoOps", base], - ["com.atproto.space.listSpaces", { cursor }], + // Filtered to the probe type, so a session scoped to it may list. + [ + "com.atproto.space.listSpaces", + { cursor, spaceType: PROBE_TYPE, spaceDid: ctx.target.did }, + ], ["com.atproto.memberspace.listMembers", { space: space.uri, cursor }], ] as const) { const res = await xrpcGet(op(ctx), name, params); From 81e7619ea36217c6fd15471fef19f132f26f1924 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 19 Nov 2026 22:48:27 +0000 Subject: [PATCH 2/3] docs(spaces): spell out the KEM key in the upgrade notes The 1112 changeset gains an upgrade checklist: reset, create the #atproto_kem key, publish it on did:plc (running pds rotation-keys first if the PDS can't sign PLC operations), and check with pds spaces status. Without the key, credentialed reads fail with 503 KemKeyUnavailable. The guide and pds spaces kem point at pds rotation-keys too, and the command narrows the PLC audit log entry to a plc_operation, as rotation-keys does. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01LZ7qcQNQoiA6a23woGC7tB --- .changeset/space-conformance-alpha-20261112.md | 1 + .changeset/spaces-alpha-20261112.md | 8 ++++++++ docs/src/content/docs/guides/enable-spaces.md | 4 +++- packages/pds/src/cli/commands/spaces.ts | 11 ++++++----- 4 files changed, 18 insertions(+), 6 deletions(-) diff --git a/.changeset/space-conformance-alpha-20261112.md b/.changeset/space-conformance-alpha-20261112.md index 94bc58c5..6b1606d0 100644 --- a/.changeset/space-conformance-alpha-20261112.md +++ b/.changeset/space-conformance-alpha-20261112.md @@ -10,3 +10,4 @@ Port the conformance suite to the 2026-11-12 spaces protocol, pinned to the 2026 - New checks cover `RegistrationNotConfirmed`, the `spaceRev` returned on authorisation, announced writer removals, `listRepoOps` commits on every page, the STAR content type, `InvalidRepoFile`, `RepoMismatch` and `InvalidSpaceMeta`. A slow check covers `registrationExpired`. - Proposal 0016 citations are checked against its section anchors. The read methods' `SpaceNotFound` and every `InvalidCursor` are exempted from coverage with reasons, since nothing in the spec defines them. - The probe space type declaration uses `title` in place of `name`. +- `request.garbage-cursor-rejected` filters its `listSpaces` call to the probe type, so it runs under an OAuth session scoped to that type instead of failing with `InsufficientScope`. diff --git a/.changeset/spaces-alpha-20261112.md b/.changeset/spaces-alpha-20261112.md index 3cf324d7..8d0accc0 100644 --- a/.changeset/spaces-alpha-20261112.md +++ b/.changeset/spaces-alpha-20261112.md @@ -6,6 +6,14 @@ Update atproto spaces to the 2026-11-17 alpha (`0.0.0-spaces-alpha-20261117141222`), which carries the 2026-11-12 protocol changes. This is a breaking alpha change: the space schema moves to version 3, so existing space data refuses to open until you run `pds spaces reset`, and apps and syncers built against the 2026-11-05 alpha need updating. +To upgrade a PDS with spaces enabled: + +1. Deploy, then run `pds spaces reset`. Space endpoints answer 503 until you do. +2. If you haven't already, create the `#atproto_kem` key with `pds spaces kem`. Without it, every credentialed read that needs a MAC (`getRecord`, `getLatestCommit`, `getRepo`, `listRepoOps`) fails with `503 KemKeyUnavailable`, so other apps and syncers can't read your spaces. The command stores the private key as the `SPACES_KEM_KEY` secret and the public key as `SPACES_KEM_KEY_PUBLIC`; then redeploy. +3. On did:plc, publish the key in your DID document with `pds spaces kem --publish`. Your PDS signs the PLC operation, so its signing key must be one of your DID's rotation keys: if it isn't, run `pds rotation-keys` first. On did:web, the redeploy publishes it. +4. Run `pds spaces status` to check that the key your PDS holds is the one your DID document publishes. +5. A managed space's managing app must now be named as `did#service`. + - Renamed methods: `getSpaceCredential` is now `authorizeSpaceSync` (taking `credentialKey`), `listRepos` is `listWriters`, `notifyWrite` is `notifyRepoUpdate`, `notifyCredentialRevoked` is `notifyCredentialsRevoked` and the managing app's `checkUserAccess` is `checkAccess`. `putMember` / `removeMember` are replaced by batched `putMembers` / `removeMembers` (up to 100 at a time, in one commit). - Syncers register for notifications by passing a webhook endpoint and token to `authorizeSpaceSync`, which the space host confirms with the syncer's `confirmRegistration` before issuing. Updates go to its `notifySpaceUpdate`; a lapsed registration gets one `registrationExpired` notice, and deleting a space tells every registered syncer, retried for up to 72 hours. `registerNotify`, `unregisterNotify` and `notifySpaceDeleted` are gone. - Removing a writer is sequenced and announced, and `listWriters` lists removals. diff --git a/docs/src/content/docs/guides/enable-spaces.md b/docs/src/content/docs/guides/enable-spaces.md index 3ec95de4..087163ce 100644 --- a/docs/src/content/docs/guides/enable-spaces.md +++ b/docs/src/content/docs/guides/enable-spaces.md @@ -75,7 +75,9 @@ pds spaces kem This stores the private key as the `SPACES_KEM_KEY` secret and its public half as the `SPACES_KEM_KEY_PUBLIC` var in `wrangler.jsonc`. Then: - **did:web**: redeploy. Your PDS serves your DID document, which now includes `#atproto_kem`. -- **did:plc**: redeploy, then run `pds spaces kem --publish`. It asks your PDS to sign a PLC operation adding the key, which works when the PDS's signing key is one of your DID's rotation keys (true if you migrated with Cirrus). Otherwise, add the `atproto_kem` verification method with whoever holds your rotation key. +- **did:plc**: redeploy, then run `pds spaces kem --publish`. It asks your PDS to sign a PLC operation adding the key, which works when the PDS's signing key is one of your DID's rotation keys. If it isn't, run `pds rotation-keys` first, or add the `atproto_kem` verification method with whoever holds your rotation key. + +Until the key is configured, credentialed reads that need a MAC fail with `503 KemKeyUnavailable`, so other apps and syncers can't read your spaces. `pds spaces status` checks that the key your PDS holds is the one your DID document publishes. diff --git a/packages/pds/src/cli/commands/spaces.ts b/packages/pds/src/cli/commands/spaces.ts index 8440fceb..b4366085 100644 --- a/packages/pds/src/cli/commands/spaces.ts +++ b/packages/pds/src/cli/commands/spaces.ts @@ -606,8 +606,8 @@ const kemCommand = defineCommand({ " pds spaces kem --publish", "", "That asks your PDS to sign the PLC operation, which works when its", - "signing key is one of your DID's rotation keys (true after migrating", - "with Cirrus). Otherwise, add it with whoever holds your rotation key.", + "signing key is one of your DID's rotation keys. If it isn't, run", + "'pds rotation-keys' first, or add it with whoever holds your rotation key.", ].join("\n"), "Publish the key", ); @@ -620,8 +620,9 @@ const kemCommand = defineCommand({ spinner.start("Fetching the current PLC operation..."); const log = await new PlcDirectoryClient().getAuditLog(did); const current = log.filter((entry) => !entry.nullified).pop(); - if (!current) { - spinner.stop("Could not read the PLC audit log"); + if (!current || current.operation.type !== "plc_operation") { + // A tombstoned DID, or one still on a legacy create operation. + spinner.stop("Could not read a current PLC operation for this DID"); process.exit(1); } const verificationMethods = { @@ -649,7 +650,7 @@ const kemCommand = defineCommand({ spinner.stop("The PLC directory refused the operation"); p.log.error(err instanceof Error ? err.message : String(err)); p.log.info( - "This PDS's signing key is probably not a rotation key for your DID. Add the atproto_kem verification method with whoever holds it.", + "If this PDS's signing key is not a rotation key for your DID, run 'pds rotation-keys' to give it control, or add the atproto_kem verification method with whoever holds a rotation key.", ); process.exit(1); } From 72cbdd7f0ff65cbff9bc5e1dd11a25e497374b5f Mon Sep 17 00:00:00 2001 From: Matt Kane Date: Thu, 19 Nov 2026 22:57:02 +0000 Subject: [PATCH 3/3] Add kem public key to demo --- demos/pds/wrangler.jsonc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/demos/pds/wrangler.jsonc b/demos/pds/wrangler.jsonc index f07c7753..b8d02f7a 100644 --- a/demos/pds/wrangler.jsonc +++ b/demos/pds/wrangler.jsonc @@ -59,7 +59,8 @@ // Atproto spaces (ALPHA). Breaking upstream changes are absorbed by // `pds spaces reset`, which wipes space data and nothing else. // `pds spaces kem` sets SPACES_KEM_KEY and SPACES_KEM_KEY_PUBLIC. - "SPACES_ENABLED": "true" + "SPACES_ENABLED": "true", + "SPACES_KEM_KEY_PUBLIC": "zDnaeYeM75iQkR6hidmbVWhwdZ42hoyk7iaXrQJ1oZYJqBTSn" }, // Secrets (set via `pds init` or `pds secret `): // - AUTH_TOKEN: Bearer token for API write operations