Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .changeset/space-conformance-alpha-20261112.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
8 changes: 8 additions & 0 deletions .changeset/spaces-alpha-20261112.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
3 changes: 2 additions & 1 deletion demos/pds/wrangler.jsonc
Original file line number Diff line number Diff line change
Expand Up @@ -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 <name>`):
// - AUTH_TOKEN: Bearer token for API write operations
Expand Down
4 changes: 3 additions & 1 deletion docs/src/content/docs/guides/enable-spaces.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
11 changes: 6 additions & 5 deletions packages/pds/src/cli/commands/spaces.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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",
);
Expand All @@ -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 = {
Expand Down Expand Up @@ -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);
}
Expand Down
7 changes: 6 additions & 1 deletion packages/space-conformance/src/checks/records.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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);
Expand Down
Loading