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/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 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); } 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);