From d8f627ff59e3b3334246b10c614edbe96e558315 Mon Sep 17 00:00:00 2001 From: Evelyn Osman Date: Mon, 9 Nov 2026 18:30:43 +0100 Subject: [PATCH 01/13] feat: authorize public handoff and provision destinations Verify source authority and journal the signed handoff before publishing, then create, deactivate and bind the destination without handing out raw sessions or claiming readiness. --- .changeset/incoming-handoff-provisioning.md | 38 + .../arrival-lifecycle.test.mjs | 771 ++++++++++++++++++ .../incoming-authorization.ts | 149 ++++ .../external-migration/prepare-arrival.ts | 140 ++++ .../external-migration/provision-arrival.ts | 316 +++++++ .../external-migration/submit-handoff.ts | 114 +++ src/pds/arrival-client.ts | 176 ++++ src/plc/policy.ts | 72 ++ src/plc/signing.ts | 58 +- tests/contracts/incoming-handoff.test.mjs | 460 +++++++++++ 10 files changed, 2293 insertions(+), 1 deletion(-) create mode 100644 .changeset/incoming-handoff-provisioning.md create mode 100644 src/features/external-migration/arrival-lifecycle.test.mjs create mode 100644 src/features/external-migration/incoming-authorization.ts create mode 100644 src/features/external-migration/prepare-arrival.ts create mode 100644 src/features/external-migration/provision-arrival.ts create mode 100644 src/features/external-migration/submit-handoff.ts create mode 100644 src/pds/arrival-client.ts create mode 100644 tests/contracts/incoming-handoff.test.mjs diff --git a/.changeset/incoming-handoff-provisioning.md b/.changeset/incoming-handoff-provisioning.md new file mode 100644 index 00000000..4bfde605 --- /dev/null +++ b/.changeset/incoming-handoff-provisioning.md @@ -0,0 +1,38 @@ +--- +"hypercerts-entryway": minor +--- + +Incoming migration now has the code that turns a prepared arrival into a +provisioned, still-pending destination. It reserves the destination repository +key, accepts the source-signed authority handoff, and creates the destination +account ahead of data transfer. Nothing here is reachable yet: no route is +mounted, so an operator sees no behaviour change until the public API is +assembled. + +What this will mean once it is wired: + +- The destination PDS is asked for a public repository key without any Entryway + credential. Only the public key is stored; the private key stays on that PDS. + Early cutover, separate deactivation and retained recovery obligations are what + this flow claims — it is **not** an independent interoperability claim. +- The arrival is journaled before the destination PDS is contacted, so an + interrupted preparation leaves a recorded obligation instead of a silent retry + on a different host. +- The source-signed handoff is checked against the expected predecessor, the + approved key order and the unchanged source service, verification key and + aliases. A full key list is rejected rather than truncated, and removing or + reordering keys is refused. The accepted operation is stored before it is sent + directly to the configured PLC directory, and publication is only claimed once + canonical history shows it. +- Destination creation requires a fresh source credential scoped to account + creation; a handoff-scoped credential cannot authorize it. Account creation + publishes Entryway's destination move, so the account is briefly active before + it is deactivated. The two steps stay distinct, and the result is a pending + arrival rather than a usable account. +- Every unresolved step — an unobserved handoff, a creation whose response was + lost, a deactivation that did not take effect — keeps the arrival pending with + a stable recovery code. None of these are repaired by signing a different + identity operation. + +Until the remaining readiness work lands, no transfer credentials are issued and +no arrival becomes active. diff --git a/src/features/external-migration/arrival-lifecycle.test.mjs b/src/features/external-migration/arrival-lifecycle.test.mjs new file mode 100644 index 00000000..253f9459 --- /dev/null +++ b/src/features/external-migration/arrival-lifecycle.test.mjs @@ -0,0 +1,771 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { cidForCbor } from "@atproto/common"; +import { Secp256k1Keypair } from "@atproto/crypto"; +import { createServiceJwt } from "@atproto/xrpc-server"; +import * as plc from "@did-plc/lib"; +import { + openTestDatabase, + query, + verifiedUser, +} from "../../../tests/support/database-fixture.mjs"; +import { createAccountStorage } from "../../../dist/src/database/drizzle/account-storage.js"; +import { createArrivalStorage } from "../../../dist/src/database/drizzle/migration-arrival.js"; +import { createOperationOwnershipStore } from "../../../dist/src/database/drizzle/operation-ownership.js"; +import { Secp256k1MigrationPlcSigner } from "../../../dist/src/plc/signing.js"; +import { validateIncomingHandoff } from "../../../dist/src/plc/policy.js"; +import { createIncomingAuthorization } from "../../../dist/src/features/external-migration/incoming-authorization.js"; +import { + createArrivalPreparation, + generateArrivalCode, +} from "../../../dist/src/features/external-migration/prepare-arrival.js"; +import { createHandoffSubmission } from "../../../dist/src/features/external-migration/submit-handoff.js"; +import { createArrivalProvisioning } from "../../../dist/src/features/external-migration/provision-arrival.js"; +import { DomainError } from "../../../dist/src/accounts/errors.js"; + +const hosts = [ + { id: "pds1", url: "https://pds1.example.test" }, + { id: "pds2", url: "https://pds2.example.test" }, +]; +const endpoint = hosts[0].url; +const sourceEndpoint = "https://source.example.test"; +const did = `did:plc:${"a".repeat(24)}`; +const handle = "dest.entryway.test"; +const email = "dest@example.test"; +const day = 86_400_000; +const serviceDid = "did:web:entryway.example.test"; +const userId = "user-a"; +const hash = (char) => char.repeat(64); + +/** One real source identity: an approved ordered rotation list, the source + * repository key and the Entryway rotation authority appended last. */ +async function sourceAuthority() { + const recovery = await Secp256k1Keypair.create({ exportable: true }); + const source = await Secp256k1Keypair.create({ exportable: true }); + const entryway = await Secp256k1Keypair.create({ exportable: true }); + const predecessor = await plc.signOperation( + plc.formatAtprotoOp({ + signingKey: source.did(), + handle, + pds: sourceEndpoint, + rotationKeys: [recovery.did(), source.did()], + prev: null, + }), + recovery, + ); + const approved = [recovery.did(), source.did(), entryway.did()]; + const { sig: _source, ...sourceFacts } = plc.normalizeOp(predecessor); + const handoffFacts = { + ...sourceFacts, + rotationKeys: approved, + prev: String(await cidForCbor(predecessor)), + }; + /** Untrusted submission: the normalized public facts with the source signature. */ + const handoffOperation = await plc.addSignature(handoffFacts, source); + return { + recovery, + source, + entryway, + approved, + predecessor, + handoffFacts, + handoffOperation, + sourceFacts: { + services: handoffFacts.services, + verificationMethods: handoffFacts.verificationMethods, + alsoKnownAs: handoffFacts.alsoKnownAs, + }, + }; +} + +async function fixture() { + const db = await openTestDatabase(":memory:"); + const accounts = createAccountStorage(db, hosts); + const arrivals = createArrivalStorage(db, hosts, { + readAccount: (value) => accounts.getByDid(value), + readBinding: (value) => accounts.getVerifiedBinding(value), + reserveEmailClaim: (value, boundDid, purpose, boundUser) => + accounts.reserveEmail(value, boundDid, purpose, boundUser), + reserveHandleClaim: (value, boundDid) => + accounts.reserveHandle(value, boundDid), + recordSavedUserBinding: (value, boundUser) => + db.insert( + "account_bindings", + { did: value, user_id: boundUser }, + { ignoreConflict: true }, + ), + insertPlacedAccount: (input) => + accounts.insertAccount( + { + did: input.did, + email: input.email, + emailVerified: true, + handle: input.handle, + pdsId: input.pdsId, + pdsUrl: input.pdsUrl, + status: "provisioning", + createdAt: new Date().toISOString(), + }, + input.userId, + ), + }); + const ownership = createOperationOwnershipStore(db); + await verifiedUser(db, userId, email); + const authority = await sourceAuthority(); + const signer = await Secp256k1MigrationPlcSigner.fromHex( + Buffer.from(await authority.entryway.export()).toString("hex"), + ); + const code = generateArrivalCode(); + const arrival = await arrivals.createArrival({ + operationId: "op-1", + did, + userId, + email, + handle, + pdsId: "pds1", + endpoint, + sourcePlcHead: String(await cidForCbor(authority.predecessor)), + codeHash: code.hash, + codeExpiresAt: Date.now() + day, + }); + const claim = await ownership.acquire({ + resource: userId, + kind: "public-arrival", + requestDigest: hash("c"), + workerId: "worker-1", + leaseMs: 120_000, + }); + return { db, arrivals, ownership, authority, signer, code, arrival, claim }; +} + +test("preparation journals the allocation intent before reserving and persists the public key", async () => { + const { db, arrivals, arrival, claim } = await fixture(); + const calls = []; + const preparation = createArrivalPreparation({ + arrivals, + reserveSigningKey: async (request) => { + calls.push(request); + assert.deepEqual( + await query(db, "SELECT signing_key FROM arrival_reservations"), + [{ signing_key: null }], + ); + return (await Secp256k1Keypair.create({ exportable: true })).did(); + }, + }); + const reserved = await preparation.reserve(claim, arrival.version, arrival); + assert.equal(reserved.version, arrival.version + 2); + assert.deepEqual(calls, [{ did, pdsId: "pds1", endpoint }]); + assert.equal( + (await query(db, "SELECT signing_key FROM arrival_reservations"))[0] + .signing_key, + reserved.signingKey, + ); + // An accepted key is consumed as saved and never replaced by a second call. + const reused = await preparation.reserve(claim, reserved.version, { + ...arrival, + signingKey: reserved.signingKey, + }); + assert.equal(reused.signingKey, reserved.signingKey); + assert.equal(calls.length, 1); +}); + +test("a failed reservation response retains the saved intent and dispatches no placement change", async () => { + const { db, arrivals, arrival, claim } = await fixture(); + let calls = 0; + const preparation = createArrivalPreparation({ + arrivals, + reserveSigningKey: async () => { + calls += 1; + throw new Error("lost reservation response"); + }, + }); + await assert.rejects( + preparation.reserve(claim, arrival.version, arrival), + /lost reservation response/, + ); + // The durable intent survives the lost response without a saved key. + assert.deepEqual( + await query(db, "SELECT signing_key FROM arrival_reservations"), + [{ signing_key: null }], + ); + // The saved tuple cannot be re-placed on another host. + await assert.rejects( + arrivals.recordAllocationIntent(claim, arrival.version + 1, { + operationId: "op-1", + did, + pdsId: "pds2", + endpoint: hosts[1].url, + }), + { code: "OperationConflict" }, + ); + assert.equal(calls, 1); +}); + +test("incoming authorization is scope-, audience-, issuer- and time-bound and consumes nothing", async () => { + const { authority } = await fixture(); + const now = Math.floor(Date.now() / 1000); + const verify = createIncomingAuthorization({ + serviceDid, + readDirectory: async () => ({ + "@context": ["https://www.w3.org/ns/did/v1"], + id: did, + verificationMethod: [ + { + id: `${did}#atproto`, + type: "EcdsaSecp256k1VerificationKey2019", + controller: did, + publicKeyMultibase: authority.source.did(), + }, + ], + }), + }); + const token = async (overrides = {}) => + `Bearer ${await createServiceJwt({ + iss: did, + aud: serviceDid, + lxm: "com.atproto.server.createAccount", + iat: now, + exp: now + 120, + keypair: authority.source, + ...overrides, + })}`; + const accepted = await verify({ + presentation: await token(), + method: "com.atproto.server.createAccount", + operationId: "op-1", + requestDigest: hash("d"), + expectedDid: did, + }); + assert.deepEqual(accepted.replayFacts, { + operationId: "op-1", + did, + method: "com.atproto.server.createAccount", + requestDigest: hash("d"), + }); + const rejects = async (input) => + await assert.rejects(verify(input), { code: "AccountMismatch" }); + await rejects({ + presentation: await token(), + method: "com.atproto.identity.submitPlcOperation", + operationId: "op-1", + requestDigest: hash("d"), + }); + await rejects({ + presentation: await token({ aud: "did:web:other.example.test" }), + method: "com.atproto.server.createAccount", + operationId: "op-1", + requestDigest: hash("d"), + }); + await rejects({ + presentation: await token({ + lxm: "com.atproto.identity.submitPlcOperation", + }), + method: "com.atproto.server.createAccount", + operationId: "op-1", + requestDigest: hash("d"), + }); + // An already-expired credential never authorizes, whatever its signature says. + const expired = await createServiceJwt({ + iss: did, + aud: serviceDid, + lxm: "com.atproto.server.createAccount", + iat: now - 120, + exp: now - 60, + keypair: authority.source, + }); + await rejects({ + presentation: `Bearer ${expired}`, + method: "com.atproto.server.createAccount", + operationId: "op-1", + requestDigest: hash("d"), + }); + await rejects({ + presentation: await token(), + method: "com.atproto.server.createAccount", + operationId: "op-1", + requestDigest: hash("d"), + expectedDid: `did:plc:${"b".repeat(24)}`, + }); + // Another identity's credential never authorizes this arrival's DID. + await rejects({ + presentation: `Bearer ${await createServiceJwt({ + iss: `did:plc:${"b".repeat(24)}`, + aud: serviceDid, + lxm: "com.atproto.server.createAccount", + iat: now, + exp: now + 120, + keypair: authority.source, + })}`, + method: "com.atproto.server.createAccount", + operationId: "op-1", + requestDigest: hash("d"), + expectedDid: did, + }); + await rejects({ + presentation: await token(), + method: "com.atproto.server.createAccount", + operationId: "op-1", + requestDigest: "not-a-digest", + }); + await assert.rejects( + verify({ + presentation: `Bearer ${await createServiceJwt({ + iss: did, + aud: serviceDid, + lxm: "com.atproto.server.createAccount", + iat: now, + exp: now + 120, + keypair: authority.recovery, + })}`, + method: "com.atproto.server.createAccount", + operationId: "op-1", + requestDigest: hash("d"), + }), + { code: "AccountMismatch" }, + ); +}); + +test("handoff validation rejects changed source facts, overfull and reordered authority", async () => { + const { authority } = await fixture(); + const validate = (overrides = {}) => + validateIncomingHandoff({ + operation: authority.handoffOperation, + expectedPredecessor: authority.predecessor, + approvedRotationKeys: authority.approved, + source: authority.sourceFacts, + ...overrides, + }); + assert.ok(await validate()); + // A fourth distinct key stays within the protocol limit but is not the approved + // list, so it is rejected rather than truncated or silently accepted. + const fourth = (await Secp256k1Keypair.create({ exportable: true })).did(); + const overfull = plc.addSignature( + { + ...authority.handoffFacts, + rotationKeys: [...authority.approved, fourth], + }, + authority.source, + ); + await assert.rejects( + validate({ + operation: overfull, + approvedRotationKeys: [...authority.approved, fourth], + }), + { code: "InvalidPlcOperation" }, + ); + await assert.rejects( + validate({ + approvedRotationKeys: [authority.source.did(), ...authority.approved], + }), + { code: "InvalidPlcOperation" }, + ); + await assert.rejects( + validate({ + approvedRotationKeys: [ + authority.recovery.did(), + authority.entryway.did(), + authority.source.did(), + ], + }), + { code: "InvalidPlcOperation" }, + ); + await assert.rejects( + validate({ approvedRotationKeys: authority.approved.slice(1) }), + { code: "InvalidPlcOperation" }, + ); + await assert.rejects( + validate({ + source: { ...authority.sourceFacts, alsoKnownAs: ["at://changed.test"] }, + }), + { code: "InvalidPlcOperation" }, + ); + await assert.rejects( + validate({ + source: { + ...authority.sourceFacts, + services: { + atproto_pds: { + type: "AtprotoPersonalDataServer", + endpoint: "https://moved.example.test", + }, + }, + }, + }), + { code: "InvalidPlcOperation" }, + ); + const reordered = plc.addSignature( + { + ...authority.handoffFacts, + rotationKeys: [...authority.approved].reverse(), + }, + authority.source, + ); + await assert.rejects(validate({ operation: reordered }), { + code: "InvalidPlcOperation", + }); +}); + +test("a crash before the handoff commit dispatches nothing and reuses no baseline", async () => { + const { db, authority, claim, arrival } = await fixture(); + const { sig: _sourceSignature, ...publicFacts } = authority.handoffOperation; + const cid = String(await cidForCbor(publicFacts)); + let dispatches = 0; + let observations = 0; + const submission = createHandoffSubmission({ + arrivals: { + recordSignedOperation: async () => { + throw new Error("fault before commit"); + }, + }, + directory: { + validate: async () => ({ operation: publicFacts, cid }), + submit: async () => { + dispatches += 1; + }, + observe: async () => { + observations += 1; + return { applied: true, tombstone: false, diverged: false }; + }, + }, + }); + await assert.rejects( + submission.submit(claim, savedHandoff(arrival, authority), { + operation: authority.handoffOperation, + }), + /fault before commit/, + ); + assert.equal(dispatches, 0); + assert.equal(observations, 0); + assert.deepEqual( + await query(db, "SELECT * FROM arrival_signed_operations"), + [], + ); +}); + +test("a crash after the handoff commit reuses the saved bytes without re-signing", async () => { + const { db, arrivals, authority, claim, arrival } = await fixture(); + const { sig: _sourceSignature, ...publicFacts } = authority.handoffOperation; + const cid = String(await cidForCbor(publicFacts)); + const published = []; + const directory = { + validate: async () => ({ operation: publicFacts, cid }), + submit: async (input) => { + published.push(input); + throw new Error("lost publication response"); + }, + observe: async () => ({ applied: true, tombstone: false, diverged: false }), + }; + const submission = createHandoffSubmission({ arrivals, directory }); + const outcome = await submission.submit( + claim, + savedHandoff(arrival, authority), + { operation: authority.handoffOperation }, + ); + assert.equal(outcome.state, "published"); + assert.equal(published.length, 1); + assert.deepEqual(published[0].operation, publicFacts); + const saved = await query( + db, + "SELECT kind, cid, operation FROM arrival_signed_operations", + ); + assert.equal(saved.length, 1); + assert.equal(saved[0].kind, "handoff"); + assert.equal(saved[0].cid, cid); + // An exact repeat is idempotent and never advances the arrival version. + const version = ( + await query(db, "SELECT version FROM arrivals WHERE operation_id = 'op-1'") + )[0].version; + const repeat = await submission.submit( + claim, + { ...savedHandoff(arrival, authority), version }, + { operation: authority.handoffOperation }, + ); + assert.equal(repeat.state, "published"); + assert.equal( + ( + await query( + db, + "SELECT version FROM arrivals WHERE operation_id = 'op-1'", + ) + )[0].version, + version, + ); + const changed = await plc.signOperation( + { + ...authority.handoffFacts, + alsoKnownAs: [...authority.handoffFacts.alsoKnownAs], + }, + authority.source, + ); + let changedDispatches = 0; + const conflicting = createHandoffSubmission({ + arrivals, + directory: { + ...directory, + validate: async () => { + // Saved bytes are immutable: a differently encoded retry conflicts before + // it can be journaled or dispatched. + throw new DomainError("OperationConflict", 409, "changed handoff"); + }, + submit: async () => { + changedDispatches += 1; + }, + }, + }); + await assert.rejects( + conflicting.submit( + claim, + { ...savedHandoff(arrival, authority), version: arrival.version }, + { operation: changed }, + ), + { code: "OperationConflict" }, + ); + assert.equal(changedDispatches, 0); +}); + +function publicHandoff(authority) { + const { sig: _signature, ...facts } = authority.handoffOperation; + return facts; +} + +function savedHandoff(arrival, authority) { + return { + operationId: arrival.operationId, + did, + version: arrival.version, + expectedPredecessor: authority.predecessor, + approvedRotationKeys: authority.approved, + source: authority.sourceFacts, + }; +} + +test("provisioning refuses a submit-scoped credential and never creates a destination account", async () => { + const { db, arrivals, authority, claim, code } = await fixture(); + const now = Math.floor(Date.now() / 1000); + const store = createOperationOwnershipStore(db); + const created = []; + const verify = createIncomingAuthorization({ + serviceDid, + readDirectory: async () => ({ + "@context": ["https://www.w3.org/ns/did/v1"], + id: did, + verificationMethod: [ + { + id: `${did}#atproto`, + type: "EcdsaSecp256k1VerificationKey2019", + controller: did, + publicKeyMultibase: authority.source.did(), + }, + ], + }), + }); + const preparation = createArrivalPreparation({ + arrivals, + reserveSigningKey: async () => + (await Secp256k1Keypair.create({ exportable: true })).did(), + }); + const reserved = await preparation.reserve(claim, 1, { + operationId: "op-1", + did, + pdsId: "pds1", + endpoint, + signingKey: null, + }); + const provisioning = createArrivalProvisioning({ + arrivals, + verifyIncomingAuthorization: verify, + invitation: { + reserve: async () => {}, + complete: async () => {}, + }, + plc: { + signMove: async () => { + throw new Error("must not sign"); + }, + observe: async () => ({ headCid: "", tombstone: false }), + }, + backend: { + createAccount: async (input) => { + created.push(input); + return { did: input.did, handle: input.handle }; + }, + checkAccountStatus: async () => ({ activated: true }), + deactivateAccount: async () => {}, + }, + }); + void store; + const submitScoped = `Bearer ${await createServiceJwt({ + iss: did, + aud: serviceDid, + lxm: "com.atproto.identity.submitPlcOperation", + iat: now, + exp: now + 120, + keypair: authority.source, + })}`; + await assert.rejects( + provisioning.provision(claim, { + operationId: "op-1", + admission: submitScoped, + arrivalCode: code.code, + invitationCode: undefined, + handle, + requestDigest: hash("e"), + observedHandoff: { + did, + operation: authority.handoffFacts, + cid: "bafyreiaaaa", + }, + }), + { code: "AccountMismatch" }, + ); + assert.equal(reserved.version, 3); + assert.deepEqual(created, []); + assert.deepEqual( + await query(db, "SELECT * FROM arrival_signed_operations"), + [], + ); +}); + +test("watched arrival access stays pending until a binding exists", async () => { + const { db, arrivals, authority, claim, code } = await fixture(); + const now = Math.floor(Date.now() / 1000); + const handoff = authority.handoffOperation; + // Canonical observation evidence supplies the full surviving operation, whose + // signature the destination move must chain from; the journal keeps only facts. + const handoffCid = String(await cidForCbor(publicHandoff(authority))); + const preparation = createArrivalPreparation({ + arrivals, + reserveSigningKey: async () => + (await Secp256k1Keypair.create({ exportable: true })).did(), + }); + const reserved = await preparation.reserve(claim, 1, { + operationId: "op-1", + did, + pdsId: "pds1", + endpoint, + signingKey: null, + }); + // The destination move is refused until the source handoff is recorded, so the + // handoff is published first and its canonical head is the observed predecessor. + const handoffSubmission = createHandoffSubmission({ + arrivals, + directory: { + validate: async () => ({ + operation: publicHandoff(authority), + cid: handoffCid, + }), + submit: async () => {}, + observe: async () => ({ + applied: true, + tombstone: false, + diverged: false, + }), + }, + }); + const handoffOutcome = await handoffSubmission.submit( + claim, + { + ...savedHandoff({ operationId: "op-1" }, authority), + version: reserved.version, + }, + { operation: handoff }, + ); + assert.equal(handoffOutcome.state, "published"); + const repositoryKey = ( + await query(db, "SELECT signing_key FROM arrival_reservations") + )[0].signing_key; + const signer = await Secp256k1MigrationPlcSigner.fromHex( + Buffer.from(await authority.entryway.export()).toString("hex"), + ); + const verify = createIncomingAuthorization({ + serviceDid, + readDirectory: async () => ({ + "@context": ["https://www.w3.org/ns/did/v1"], + id: did, + verificationMethod: [ + { + id: `${did}#atproto`, + type: "EcdsaSecp256k1VerificationKey2019", + controller: did, + publicKeyMultibase: authority.source.did(), + }, + ], + }), + }); + const calls = []; + const provisioning = createArrivalProvisioning({ + arrivals, + verifyIncomingAuthorization: verify, + invitation: { + reserve: async () => calls.push("invite-reserve"), + complete: async () => calls.push("invite-complete"), + }, + plc: { + signMove: async (input, persist) => { + // Wrap the signer so the recorded bytes are the normalized public facts, + // which is exactly what the stock PDS receives as `plcOp`. + return await signer.signArrivalMove(input, persist); + }, + observe: async () => ({ headCid: handoffCid, tombstone: false }), + }, + backend: { + createAccount: async (input) => { + calls.push("create"); + assert.equal(input.did, did); + return { did, handle }; + }, + checkAccountStatus: async () => ({ + activated: calls.includes("deactivate") === false, + }), + deactivateAccount: async () => { + calls.push("deactivate"); + }, + }, + }); + const result = await provisioning.provision(claim, { + admission: `Bearer ${await createServiceJwt({ + iss: did, + aud: serviceDid, + lxm: "com.atproto.server.createAccount", + iat: now, + exp: now + 120, + keypair: authority.source, + })}`, + operationId: "op-1", + arrivalCode: code.code, + invitationCode: undefined, + handle, + requestDigest: hash("f"), + observedHandoff: { did, operation: handoff, cid: handoffCid }, + }); + assert.equal(result.state, "pending"); + assert.deepEqual(calls, [ + "invite-reserve", + "create", + "deactivate", + "invite-complete", + ]); + const signed = await query( + db, + "SELECT kind, cid FROM arrival_signed_operations ORDER BY kind", + ); + assert.deepEqual( + signed.map((row) => row.kind), + ["destination-move", "handoff"], + ); + // The move was signed over the saved reservation's public key, never a new one. + const savedMove = await query( + db, + "SELECT operation FROM arrival_signed_operations WHERE kind = 'destination-move'", + ); + assert.equal( + JSON.parse(savedMove[0].operation).verificationMethods.atproto, + repositoryKey, + ); + const projection = await arrivals.readArrivalAccess(did); + assert.equal(projection.provisioned, true); + assert.equal(projection.deactivationObserved, true); + assert.equal(projection.bound, true); + assert.equal(projection.complete, false); + assert.ok(!JSON.stringify(result).includes("accessJwt")); +}); diff --git a/src/features/external-migration/incoming-authorization.ts b/src/features/external-migration/incoming-authorization.ts new file mode 100644 index 00000000..31e91861 --- /dev/null +++ b/src/features/external-migration/incoming-authorization.ts @@ -0,0 +1,149 @@ +import { getVerificationMaterial } from "@atproto/common"; +import { getDidKeyFromMultibase } from "@atproto/identity"; +import type { DidDocument } from "@atproto/identity"; +import { verifyJwt } from "@atproto/xrpc-server"; +import { DomainError } from "../../accounts/errors.js"; +import type { ArrivalReplayFacts } from "./arrival-types.js"; + +/** Incoming source credentials authorize one Entryway method for one DID. They + * are never hosted-account authorization and never mint a local account. */ +export const incomingHandoffMethod = + "com.atproto.identity.submitPlcOperation" as const; +export const incomingCreationMethod = + "com.atproto.server.createAccount" as const; + +export type IncomingMethod = + | typeof incomingHandoffMethod + | typeof incomingCreationMethod; + +/** Verified, secret-free facts. Replay admission of these facts stays with the + * caller's fenced storage transaction; this verifier consumes nothing. */ +export interface IncomingAuthorization { + readonly did: string; + readonly method: IncomingMethod; + readonly replayFacts: ArrivalReplayFacts; +} + +const rejected = (): never => { + throw new DomainError( + "AccountMismatch", + 403, + "The source credential does not authorize this arrival", + ); +}; + +/** Accept only a bearer credential; cookies and query parameters never authorize. */ +const presentation = (value: unknown): string => { + if (typeof value !== "string") return rejected(); + const match = /^Bearer ([A-Za-z0-9._~+/-]+=*)$/.exec(value.trim()); + if (!match) return rejected(); + const token = match[1]; + if (!token) return rejected(); + return token; +}; + +/** Verify source credentials without touching hosted-account authentication. + * `readDirectory` is the configured concrete directory reader; this layer never + * follows a caller-supplied origin or plaintext discovery. */ +export function createIncomingAuthorization({ + serviceDid, + readDirectory, +}: { + readonly serviceDid: string; + readonly readDirectory: (did: string) => Promise; +}) { + /** A source service JWT names its own DID or a key fragment of it; either way + * the repository verification key is what proves the signature. Legacy + * `did:key` verification methods are authoritative references, so the key is + * resolved through the configured directory and never from the token itself. */ + const signingKey = async (issuer: string): Promise => { + const did = issuer.split("#")[0]; + if (!did) return rejected(); + const document = await readDirectory(did); + const material = getVerificationMaterial(document, "atproto"); + if (!material || !material.type || !material.publicKeyMultibase) + return rejected(); + if (material.publicKeyMultibase.startsWith("did:key:")) + return material.publicKeyMultibase; + const didKey = getDidKeyFromMultibase(material); + if (!didKey) return rejected(); + return didKey; + }; + return async function verifyIncomingAuthorization(input: { + readonly presentation: unknown; + readonly method: IncomingMethod; + readonly operationId: string; + readonly requestDigest: string; + readonly expectedDid?: string; + }): Promise { + const token = presentation(input.presentation); + if (!/^[a-f0-9]{64}$/.test(input.requestDigest)) return rejected(); + let subject: string; + try { + const payload: unknown = await verifyJwt( + token, + serviceDid, + input.method, + async (issuer) => await signingKey(issuer), + ); + const claims = payload as Record; + const issuer = claims.iss; + if (typeof issuer !== "string") return rejected(); + subject = String(issuer).split("#")[0] ?? ""; + const now = Math.floor(Date.now() / 1000); + if ( + claims.aud !== serviceDid || + claims.lxm !== input.method || + typeof claims.jti !== "string" || + !claims.jti + ) + return rejected(); + const issuedAt = claims.iat; + const expiresAt = claims.exp; + if ( + typeof issuedAt !== "number" || + !Number.isInteger(issuedAt) || + typeof expiresAt !== "number" || + !Number.isInteger(expiresAt) || + expiresAt <= now || + expiresAt <= issuedAt || + issuedAt > now + 60 + ) + return rejected(); + } catch { + return rejected(); + } + if (!/^did:plc:[a-z2-7]{24}$/.test(subject)) return rejected(); + if (input.expectedDid !== undefined && subject !== input.expectedDid) + return rejected(); + return { + did: subject, + method: input.method, + replayFacts: { + operationId: input.operationId, + did: subject, + method: input.method, + requestDigest: input.requestDigest, + }, + }; + }; +} + +export type VerifyIncomingAuthorization = ReturnType< + typeof createIncomingAuthorization +>; + +/** A submit-scoped credential cannot authorize destination creation. */ +export function requireCreationScope( + authorization: IncomingAuthorization, +): IncomingAuthorization { + if (authorization.method !== incomingCreationMethod) return rejected(); + return authorization; +} + +export function requireHandoffScope( + authorization: IncomingAuthorization, +): IncomingAuthorization { + if (authorization.method !== incomingHandoffMethod) return rejected(); + return authorization; +} diff --git a/src/features/external-migration/prepare-arrival.ts b/src/features/external-migration/prepare-arrival.ts new file mode 100644 index 00000000..3d9d23de --- /dev/null +++ b/src/features/external-migration/prepare-arrival.ts @@ -0,0 +1,140 @@ +import { createHash, randomBytes } from "node:crypto"; +import { DomainError } from "../../accounts/errors.js"; +import type { ArrivalTransactor } from "../../database/migration-journal.port.js"; +import type { OperationClaim } from "../../database/operation-ownership.port.js"; +import type { ArrivalOutcome } from "./arrival-types.js"; + +/** Preparation records the verified destination owner and one reservation only + * after a fresh origin-validated proof. The code is returned once and stored as + * a hash, so nothing here can recover or log it. */ +export interface ArrivalPreparation { + readonly operationId: string; + readonly did: string; + readonly handle: string; + readonly userId: string; + readonly email: string; + readonly expectedPlcHead: string; + readonly approvedRotationKeys: readonly string[]; +} + +export interface ArrivalHandoffFacts { + readonly services: Record; + readonly verificationMethods: Record; + readonly alsoKnownAs: string[]; +} + +/** Stable refusal: the arrival must be reconciled before another reservation. */ +const recoveryRequired = (): never => { + throw new DomainError( + "OperationRecoveryRequired", + 409, + "The saved arrival allocation is uncertain. Keep the arrival pending for verified recovery.", + ); +}; + +/** A reservation belongs to no operator: the configured ID and endpoint both + * select the same enrolled host, and the DID is the admitted incoming DID. */ +export interface ReservationRequest { + readonly did: string; + readonly pdsId: string; + readonly endpoint: string; +} + +export function createArrivalPreparation({ + arrivals, + reserveSigningKey, +}: { + readonly arrivals: Pick< + ArrivalTransactor, + "recordAllocationIntent" | "recordReservationResult" + >; + readonly reserveSigningKey: (request: ReservationRequest) => Promise; +}) { + const settle = ( + outcome: ArrivalOutcome, + reservedKey: string, + ): { readonly version: number; readonly signingKey: string } => { + switch (outcome.kind) { + case "applied": + return { version: outcome.version, signingKey: reservedKey }; + case "already-settled": + // An exact repeat never advances the version, so its value is not a new + // baseline for later conditional writes. + return { version: outcome.version, signingKey: reservedKey }; + case "reconciliation-required": + return recoveryRequired(); + } + }; + return { + /** Journal the obligation, then reserve, then persist conditionally. A lost + * reservation response retains the intent and never silently re-places it. */ + async reserve( + owner: OperationClaim, + expectedVersion: number, + saved: { + readonly operationId: string; + readonly did: string; + readonly pdsId: string; + readonly endpoint: string; + readonly signingKey: string | null; + }, + ): Promise<{ readonly version: number; readonly signingKey: string }> { + // An accepted key is consumed as saved, never replaced by a second call. + if (saved.signingKey !== null) + return { + version: expectedVersion, + signingKey: saved.signingKey, + }; + const intent = await arrivals.recordAllocationIntent( + owner, + expectedVersion, + { + operationId: saved.operationId, + did: saved.did, + pdsId: saved.pdsId, + endpoint: saved.endpoint, + }, + ); + if (intent.kind === "reconciliation-required") return recoveryRequired(); + // The durable intent survives a failed or lost reservation response: the + // saved tuple member stays, and no retry may re-place it elsewhere. + const reservedKey = await reserveSigningKey({ + did: saved.did, + pdsId: saved.pdsId, + endpoint: saved.endpoint, + }); + const result = await arrivals.recordReservationResult( + owner, + intent.version, + { + operationId: saved.operationId, + did: saved.did, + pdsId: saved.pdsId, + endpoint: saved.endpoint, + signingKey: reservedKey, + }, + ); + return settle(result, reservedKey); + }, + }; +} + +/** One-time displayed arrival code. Only its hash and expiry are persisted. */ +export function generateArrivalCode(): { + readonly code: string; + readonly hash: string; + readonly expiresAt: number; +} { + const code = randomBytes(24).toString("base64url"); + return { + code, + hash: arrivalCodeHash(code), + expiresAt: Date.now() + 86_400_000, + }; +} + +export function arrivalCodeHash(code: string): string { + return createHash("sha256") + .update(`entryway-arrival-code/v1:${code}`) + .digest("hex"); +} diff --git a/src/features/external-migration/provision-arrival.ts b/src/features/external-migration/provision-arrival.ts new file mode 100644 index 00000000..a5c19089 --- /dev/null +++ b/src/features/external-migration/provision-arrival.ts @@ -0,0 +1,316 @@ +import { cidForCbor } from "@atproto/common"; +import { DomainError } from "../../accounts/errors.js"; +import type { ArrivalTransactor } from "../../database/migration-journal.port.js"; +import type { ArrivalRecord } from "./arrival-types.js"; +import type { OperationClaim } from "../../database/operation-ownership.port.js"; +import type { VerifyIncomingAuthorization } from "./incoming-authorization.js"; +import { incomingCreationMethod } from "./incoming-authorization.js"; +import { arrivalCodeHash } from "./prepare-arrival.js"; + +/** Destination creation runs only after the canonical handoff is observed, so the + * observed operation is the predecessor Entryway signs the move over. */ +export interface ObservedHandoff { + readonly did: string; + readonly operation: Record; + readonly cid: string; +} + +export interface ProvisioningInput { + readonly admission: unknown; + readonly arrivalCode: string; + readonly invitationCode: unknown; + /** The saved arrival the caller is resuming; the caller's own user selects it. */ + readonly operationId: string; + readonly handle: string; + readonly requestDigest: string; + readonly observedHandoff: ObservedHandoff; +} + +export interface ProvisioningResult { + readonly state: "pending"; + readonly operationId: string; + readonly version: number; +} + +/** Stable recovery: the destination stays pending for the exact accepted retry or + * an operator-reconciled attempt, never a fresh remote write. */ +const pending = (message: string): never => { + throw new DomainError("OperationRecoveryRequired", 409, message); +}; + +const conflict = (message: string): never => { + throw new DomainError("OperationConflict", 409, message); +}; + +/** Public facts of a signed operation; the signature proves authority, not facts. */ +const signedOperation = ( + operation: Record, +): Record => { + const { sig: _signature, ...facts } = operation; + return facts; +}; + +/** The authority-only handoff retains source hosting, so the endpoint the + * destination move leaves in place comes from that observed operation. */ +const observedEndpoint = ( + operation: Record, +): string | null => { + const services = operation.services; + if (typeof services !== "object" || services === null) return null; + const service = (services as Record).atproto_pds; + if (typeof service !== "object" || service === null) return null; + const endpoint = (service as Record).endpoint; + return typeof endpoint === "string" && endpoint.startsWith("https://") + ? endpoint + : null; +}; + +/** Ordinary destination creation with a separate observed deactivation. This is + * not atomic inactive creation: stock creation publishes the move and returns an + * active account, so deactivation is its own retained obligation. */ +export function createArrivalProvisioning({ + arrivals, + verifyIncomingAuthorization, + invitation, + plc, + backend, +}: { + readonly arrivals: Pick< + ArrivalTransactor, + | "readArrival" + | "readArrivalAccess" + | "consumeArrivalCode" + | "recordSignedOperation" + | "recordArrivalReplay" + | "bindProvisionedArrival" + >; + readonly verifyIncomingAuthorization: VerifyIncomingAuthorization; + /** Existing registration invitation producer; it already accepts atomically. */ + readonly invitation: { + reserve(code: unknown, email: string): Promise; + complete(account: { + readonly email: string; + readonly did: string; + }): Promise; + }; + readonly plc: { + signMove( + input: { + readonly handoffOperation: unknown; + readonly repositoryKey: string; + readonly endpoint: string; + }, + persist: ( + operation: Readonly>, + facts: Readonly>, + cid: string, + ) => Promise, + ): Promise<{ + readonly operation: Record; + readonly cid: string; + }>; + observe(did: string): Promise<{ + readonly headCid: string; + readonly tombstone: boolean; + }>; + }; + readonly backend: { + createAccount(input: { + readonly did: string; + readonly handle: string; + readonly operation: unknown; + }): Promise<{ readonly did: string; readonly handle: string }>; + checkAccountStatus(did: string): Promise<{ readonly activated: boolean }>; + deactivateAccount(did: string): Promise; + }; +}) { + /** The caller selects the saved operation and its own user. The ownership claim + * identity is a separate identifier, so it is never assumed equal to the arrival + * operation ID; another user reads as not found. */ + const savedArrival = async ( + owner: OperationClaim, + input: ProvisioningInput, + ): Promise<{ + readonly arrival: ArrivalRecord; + readonly signingKey: string; + }> => { + const arrival = await arrivals.readArrival( + input.operationId, + owner.resource, + ); + if (!arrival) + throw new DomainError("AccountNotFound", 404, "Arrival not found"); + if (arrival.handle !== input.handle) + conflict("The supplied handle differs from the saved arrival"); + if (arrival.cancelledAt !== null) + conflict("This arrival is no longer actionable"); + // A bound arrival already has its destination; re-sending creation would ask + // the stock PDS to create a second account for the same DID. + const access = await arrivals.readArrivalAccess(arrival.did); + if (access?.bound) + conflict("This arrival is already provisioned and bound"); + if (!arrival.signingKey) + return pending( + "The saved reserved repository key is required before creation", + ); + return { arrival, signingKey: arrival.signingKey }; + }; + return { + async provision( + owner: OperationClaim, + input: ProvisioningInput, + ): Promise { + const { arrival, signingKey } = await savedArrival(owner, input); + // Creation requires a createAccount-scoped source credential. Its replay + // facts are admitted atomically with this accepted work. + const authorization = await verifyIncomingAuthorization({ + presentation: input.admission, + method: incomingCreationMethod, + operationId: arrival.operationId, + requestDigest: input.requestDigest, + expectedDid: arrival.did, + }); + const replay = await arrivals.recordArrivalReplay( + owner, + arrival.version, + authorization.replayFacts, + ); + if (replay.operationId !== arrival.operationId) + pending("The saved replay binding does not belong to this arrival"); + const current = ( + await arrivals.readArrival(input.operationId, owner.resource) + )?.version; + if (current === undefined) + return pending("The saved arrival is no longer readable"); + const admitted = await arrivals.consumeArrivalCode({ + codeHash: arrivalCodeHash(input.arrivalCode), + did: arrival.did, + method: incomingCreationMethod, + }); + if (!admitted) + throw new DomainError( + "AccountMismatch", + 403, + "The arrival code is invalid, expired or already used", + ); + // Invitations are rejected before any backend effect and accepted once for + // these exact facts. + await invitation.reserve(input.invitationCode, arrival.email); + // Only an observed canonical handoff may be signed over, and only for this + // DID: signing over an unpublished predecessor would fork authority. + if (input.observedHandoff.did !== arrival.did) + pending("The canonical handoff is not observed for this arrival"); + // The observed operation is the full surviving signed predecessor, so the + // journaled public CID identifies it without stripping its signature. + if ( + String( + await cidForCbor(signedOperation(input.observedHandoff.operation)), + ) !== input.observedHandoff.cid + ) + conflict("The observed handoff does not match its CID"); + const canonical = await plc.observe(arrival.did); + if (canonical.tombstone) pending("The identity is tombstoned"); + if (canonical.headCid !== input.observedHandoff.cid) + pending("Canonical identity changed after the observed handoff"); + const observedSource = observedEndpoint(input.observedHandoff.operation); + if (observedSource === null) + return pending("The observed handoff retains no source endpoint"); + + // The replay admission may have advanced the arrival; the move and its later + // binding chain off the re-read version rather than the stale one. + let version = current; + let recordedVersion: number | null = null; + let move: { + readonly operation: Record; + readonly cid: string; + }; + try { + move = await plc.signMove( + { + handoffOperation: input.observedHandoff.operation, + repositoryKey: signingKey, + endpoint: observedSource, + }, + async (_signed, facts, cid) => { + // The normalized public facts and their CID are recorded unmodified; the + // signature wrapper is never persisted. + const recorded = await arrivals.recordSignedOperation( + owner, + version, + { + kind: "destination-move", + operationId: arrival.operationId, + did: arrival.did, + repositoryKey: signingKey, + operation: facts as Record, + cid, + }, + ); + if (recorded.kind === "reconciliation-required") + return pending( + "The destination move requires verified reconciliation", + ); + recordedVersion = recorded.version; + // An already-settled repeat does not advance the version, so only an + // applied record may become the next conditional baseline. + if (recorded.kind === "applied") version = recorded.version; + }, + ); + } catch (error) { + if (error instanceof DomainError) throw error; + return pending("The destination move could not be signed"); + } + // The move is durable before this write. A failure here leaves a published + // move without a backend, which stays pending; it is never repaired by + // signing a different operation. + try { + await backend.createAccount({ + did: arrival.did, + handle: arrival.handle, + operation: move.operation, + }); + } catch { + pending("Destination creation is unresolved; keep the arrival pending"); + } + const created = await backend + .checkAccountStatus(arrival.did) + .catch(() => null); + if (created === null) pending("Destination account state is unobserved"); + await backend + .deactivateAccount(arrival.did) + .catch(() => pending("Destination deactivation is unresolved")); + const deactivated = await backend + .checkAccountStatus(arrival.did) + .catch(() => null); + if (deactivated === null || deactivated.activated) + pending("Destination deactivation is not observed"); + await invitation.complete({ email: arrival.email, did: arrival.did }); + // Only a committed move record authorizes the pending binding, and the + // binding presents that record's own version as its conditional baseline. + const baseline = recordedVersion; + if (baseline === null) + return pending("The destination move was not recorded before creation"); + const bound = await arrivals.bindProvisionedArrival({ + owner, + expectedVersion: baseline, + operationId: arrival.operationId, + did: arrival.did, + userId: arrival.userId, + email: arrival.email, + handle: arrival.handle, + pdsId: arrival.pdsId, + placement: { provisioned: true, deactivationObserved: true }, + }); + if (bound.kind === "reconciliation-required") + return pending("The pending binding requires verified reconciliation"); + // A pending result only. Credential issuance belongs to plan 011; no raw + // backend session or ordinary active access is returned here. An exact + // repeat of the binding reports its saved version unchanged. + return { + state: "pending", + operationId: arrival.operationId, + version: bound.version, + }; + }, + }; +} diff --git a/src/features/external-migration/submit-handoff.ts b/src/features/external-migration/submit-handoff.ts new file mode 100644 index 00000000..1a7f809a --- /dev/null +++ b/src/features/external-migration/submit-handoff.ts @@ -0,0 +1,114 @@ +import { DomainError } from "../../accounts/errors.js"; +import type { ArrivalTransactor } from "../../database/migration-journal.port.js"; +import type { OperationClaim } from "../../database/operation-ownership.port.js"; +import type { ArrivalHandoffFacts } from "./prepare-arrival.js"; + +/** Public observation of one DID's canonical history. This is the only accepted + * evidence of publication: a dispatch receipt or a signature proves nothing. */ +export interface HandoffObservation { + /** True only when the saved signed operation survives in the canonical chain. */ + readonly applied: boolean; + readonly tombstone: boolean; + /** True when canonical history diverged without nullifying the saved operation. */ + readonly diverged: boolean; +} + +export type HandoffOutcome = + | { readonly state: "published"; readonly cid: string } + | { readonly state: "diverged"; readonly cid: string } + | { readonly state: "uncertain"; readonly cid: string }; + +export interface HandoffSaved { + readonly operationId: string; + readonly did: string; + readonly version: number; + readonly expectedPredecessor: unknown; + readonly approvedRotationKeys: readonly string[]; + readonly source: ArrivalHandoffFacts; +} + +/** Untrusted source bytes are validated by the pinned library before anything is + * recorded. Validation never re-signs: the source signature is the authorization. */ +export function createHandoffSubmission({ + arrivals, + directory, +}: { + readonly arrivals: Pick; + readonly directory: { + validate(input: { + readonly operation: unknown; + readonly expectedPredecessor: unknown; + readonly approvedRotationKeys: readonly string[]; + readonly source: ArrivalHandoffFacts; + }): Promise<{ + readonly operation: Record; + readonly cid: string; + }>; + submit(input: { + readonly did: string; + readonly operation: Record; + readonly cid: string; + }): Promise; + observe(did: string): Promise; + }; +}) { + /** Dispatch the saved facts directly to the configured directory, then let + * observation decide the outcome. A lost response is not a failed publication. */ + const dispatch = async ( + did: string, + operation: Record, + cid: string, + ): Promise => { + try { + await directory.submit({ did, operation, cid }); + } catch { + // Classify by canonical observation below, never by the transport result. + } + const observed = await directory.observe(did); + if (observed.tombstone) + throw new DomainError( + "OperationConflict", + 409, + "The identity is tombstoned; this handoff cannot be published", + ); + if (observed.applied) return { state: "published", cid }; + return { + state: observed.diverged ? "diverged" : "uncertain", + cid, + }; + }; + return { + async submit( + owner: OperationClaim, + saved: HandoffSaved, + presented: unknown, + ): Promise { + const validated = await directory.validate({ + operation: presented, + expectedPredecessor: saved.expectedPredecessor, + approvedRotationKeys: saved.approvedRotationKeys, + source: saved.source, + }); + const recorded = await arrivals.recordSignedOperation( + owner, + saved.version, + { + kind: "handoff", + operationId: saved.operationId, + did: saved.did, + operation: validated.operation, + cid: validated.cid, + }, + ); + if (recorded.kind === "reconciliation-required") + throw new DomainError( + "OperationRecoveryRequired", + 409, + "The saved handoff requires verified reconciliation", + ); + // Committed bytes only: an accepted or already-settled record both mean the + // exact signed operation is durable, and a retry submits those same bytes. + return await dispatch(saved.did, validated.operation, validated.cid); + }, + }; +} diff --git a/src/pds/arrival-client.ts b/src/pds/arrival-client.ts new file mode 100644 index 00000000..5fb278ae --- /dev/null +++ b/src/pds/arrival-client.ts @@ -0,0 +1,176 @@ +import { randomBytes } from "node:crypto"; +import { parseDidKey } from "@atproto/crypto"; +import { importJWK, SignJWT } from "jose"; +import type { JWK } from "jose"; +import { DomainError } from "../accounts/errors.js"; + +/** A stock PDS holds the reserved repository private key. This client only ever + * receives public key material and never persists a returned session. */ +const responseLimit = 1_000_000; + +const upstreamFailure = (method: string, status: number): DomainError => + new DomainError( + "AccountUnavailable", + 502, + `The selected PDS failed ${method} with status ${status}`, + ); + +const invalidResponse = (method: string): DomainError => + new DomainError( + "AccountUnavailable", + 502, + `The selected PDS returned an invalid ${method} response`, + ); + +const isRecord = (value: unknown): value is Record => + typeof value === "object" && value !== null && !Array.isArray(value); + +const supportedRepositoryKey = /^did:key:zQ3sh[1-9A-HJ-NP-Za-km-z]{44}$/; + +/** Validate a reservation result as a supported public secp256k1 did:key. */ +export function reservationSigningKey(value: unknown): string { + const method = "com.atproto.server.reserveSigningKey"; + if (!isRecord(value) || typeof value.signingKey !== "string") + throw invalidResponse(method); + if (!supportedRepositoryKey.test(value.signingKey)) + throw invalidResponse(method); + try { + parseDidKey(value.signingKey); + } catch { + throw invalidResponse(method); + } + return value.signingKey; +} + +async function readPublicJson( + response: Response, + method: string, +): Promise { + const content = await response.text().catch(() => ""); + if (!response.ok) throw upstreamFailure(method, response.status); + if (content.length > responseLimit) throw invalidResponse(method); + if (!content.trim()) return {}; + try { + return JSON.parse(content) as unknown; + } catch { + throw invalidResponse(method); + } +} + +/** Concrete stock PDS transport for one selected destination. It carries no + * lifecycle-hook or administration credential: ordinary `createAccount` with a + * caller-signed move, then self-deactivation with the account credential. */ +export class ArrivalPdsClient { + readonly #jwtKey: Promise>>; + public constructor( + private readonly options: { + readonly endpoint: string; + readonly did: string; + readonly jwtJwk: JWK; + }, + ) { + this.#jwtKey = importJWK(options.jwtJwk, "ES256K"); + } + #url(method: string): URL { + return new URL(`/xrpc/${method}`, this.options.endpoint); + } + async #accountAccess(did: string): Promise { + const key = await this.#jwtKey; + return await new SignJWT({ scope: "com.atproto.access" }) + .setProtectedHeader({ alg: "ES256K", typ: "at+jwt" }) + .setSubject(did) + .setAudience(did) + .setIssuedAt() + .setExpirationTime("30s") + .setJti(randomBytes(16).toString("hex")) + .sign(key); + } + /** Stock reservation is unauthenticated and echoes neither DID nor host: the + * caller binds the result through its own durable intent, not this response. */ + public async reserveSigningKey(did: string): Promise { + const method = "com.atproto.server.reserveSigningKey"; + const response = await fetch(this.#url(method), { + method: "POST", + headers: { "content-type": "application/json" }, + body: JSON.stringify({ did }), + redirect: "error", + signal: AbortSignal.timeout(15_000), + }); + return reservationSigningKey(await readPublicJson(response, method)); + } + /** Stock creation consumes the PDS-local reservation, publishes the supplied + * move and returns an active session. Only the public facts are retained. */ + public async createAccount(input: { + did: string; + handle: string; + operation: unknown; + }): Promise<{ did: string; handle: string }> { + const method = "com.atproto.server.createAccount"; + const response = await fetch(this.#url(method), { + method: "POST", + headers: { "content-type": "application/json" }, + body: JSON.stringify({ + did: input.did, + handle: input.handle, + plcOp: input.operation, + }), + redirect: "error", + signal: AbortSignal.timeout(60_000), + }); + const value = await readPublicJson(response, method); + if ( + !isRecord(value) || + value.did !== input.did || + value.handle !== input.handle || + typeof value.accessJwt !== "string" || + typeof value.refreshJwt !== "string" + ) + throw invalidResponse(method); + return { did: value.did, handle: value.handle }; + } + /** Status requires the account's own credential and describes only itself. */ + public async checkAccountStatus( + did: string, + ): Promise<{ activated: boolean }> { + const method = "com.atproto.server.checkAccountStatus"; + const response = await fetch(this.#url(method), { + method: "GET", + headers: { authorization: `Bearer ${await this.#accountAccess(did)}` }, + redirect: "error", + signal: AbortSignal.timeout(15_000), + }); + const value = await readPublicJson(response, method); + if (!isRecord(value) || typeof value.activated !== "boolean") + throw invalidResponse(method); + return { activated: value.activated }; + } + private async deactivationObserved(did: string): Promise { + try { + return !(await this.checkAccountStatus(did)).activated; + } catch { + return false; + } + } + /** Ordinary self-deactivation with the account's own credential, followed by a + * status read. Callers treat any failure as an unresolved obligation. */ + public async deactivateAccount(did: string): Promise { + const method = "com.atproto.server.deactivateAccount"; + const response = await fetch(this.#url(method), { + method: "POST", + headers: { + "content-type": "application/json", + authorization: `Bearer ${await this.#accountAccess(did)}`, + }, + body: JSON.stringify({}), + redirect: "error", + signal: AbortSignal.timeout(30_000), + }); + await readPublicJson(response, method); + if (!(await this.deactivationObserved(did))) + throw new DomainError( + "AccountUnavailable", + 502, + "Destination deactivation is not yet observed", + ); + } +} diff --git a/src/plc/policy.ts b/src/plc/policy.ts index 42d52b1c..b3b0a8af 100644 --- a/src/plc/policy.ts +++ b/src/plc/policy.ts @@ -111,6 +111,78 @@ export function validateUnsignedOperation( return op; } +/** Source facts an authority-only handoff must not alter. Comparison is exact + * and order-sensitive: a reordered rotation list is a different approved list. */ +export interface IncomingSourceFacts { + readonly services: plc.UnsignedOperation["services"]; + readonly verificationMethods: plc.UnsignedOperation["verificationMethods"]; + readonly alsoKnownAs: plc.UnsignedOperation["alsoKnownAs"]; +} + +/** Validate a source-signed authority-only handoff in its original encoding. + * The signature must prove the expected source predecessor, and the only change + * to the approved ordered rotation list may be adding the Entryway rotation key, + * within the protocol limit. Overfull lists, removals, reordering, unexpected + * keys, changed source facts and tombstones are rejected rather than truncated. */ +export async function validateIncomingHandoff(input: { + readonly operation: unknown; + readonly expectedPredecessor: unknown; + readonly approvedRotationKeys: readonly string[]; + readonly source: IncomingSourceFacts; +}): Promise { + const approved = [...input.approvedRotationKeys]; + if ( + approved.length < 2 || + approved.length > 5 || + new Set(approved).size !== approved.length + ) + return invalid(); + let candidate: plc.CompatibleOp; + let predecessor: plc.UnsignedOperation; + try { + approved.forEach(publicRotationKey); + predecessor = plc.normalizeOp( + plc.def.operation.parse(structuredClone(input.expectedPredecessor)), + ); + // The handoff is always the current signed operation form, never legacy v1. + candidate = plc.def.operation.parse(structuredClone(input.operation)); + if (candidate.prev !== String(await cidForCbor(predecessor))) + return invalid(); + await plc.assureValidSig([...predecessor.rotationKeys], candidate); + } catch (error) { + if (error instanceof PlcError) throw error; + return invalid(); + } + const facts = plc.normalizeOp(candidate); + if (facts.rotationKeys.length !== approved.length) return invalid(); + for (let index = 0; index < approved.length; index += 1) + if (facts.rotationKeys[index] !== approved[index]) return invalid(); + if ( + JSON.stringify(facts.alsoKnownAs) !== + JSON.stringify(input.source.alsoKnownAs) || + JSON.stringify(facts.verificationMethods) !== + JSON.stringify(input.source.verificationMethods) || + JSON.stringify(facts.services) !== JSON.stringify(input.source.services) + ) + return invalid(); + return candidate; +} + +/** A retried handoff resumes the saved bytes or conflicts; it never re-signs. */ +export function sameSignedOperation(left: unknown, right: unknown): boolean { + const canonical = (value: unknown): unknown => { + if (Array.isArray(value)) return value.map(canonical); + if (record(value)) + return Object.fromEntries( + Object.entries(value) + .sort(([first], [second]) => (first < second ? -1 : 1)) + .map(([key, item]) => [key, canonical(item)]), + ); + return value; + }; + return JSON.stringify(canonical(left)) === JSON.stringify(canonical(right)); +} + export async function publicUpdateCandidate( current: unknown, replacement: unknown, diff --git a/src/plc/signing.ts b/src/plc/signing.ts index c97e7aea..ab802285 100644 --- a/src/plc/signing.ts +++ b/src/plc/signing.ts @@ -2,7 +2,11 @@ import { cidForCbor } from "@atproto/common"; import { Secp256k1Keypair } from "@atproto/crypto"; import * as plc from "@did-plc/lib"; import { PlcError } from "./errors.js"; -import { publicUpdateCandidate, validateUnsignedOperation } from "./policy.js"; +import { + publicUpdateCandidate, + validateHistoryOperation, + validateUnsignedOperation, +} from "./policy.js"; /** The private rotation key is received only at composition. */ export class Secp256k1MigrationPlcSigner { @@ -179,6 +183,58 @@ export class Secp256k1MigrationPlcSigner { persist, ); } + /** Public arrival move: the observed handoff's own facts are replaced only by + * the reserved public repository key and destination endpoint. Entryway signs + * with its rotation authority; the PDS repository private key never enters here. + * `persist` journals the public facts and their CID before any dispatch. */ + public async signArrivalMove( + input: { + handoffOperation: unknown; + repositoryKey: string; + endpoint: string; + }, + persist: ( + operation: Readonly, + facts: Readonly, + cid: string, + ) => Promise, + ): Promise<{ + operation: plc.UnsignedOperation; + cid: string; + }> { + const previous = this.#previous(input.handoffOperation); + const facts = plc.normalizeOp(previous); + let saved: { operation: plc.UnsignedOperation; cid: string } | undefined; + await this.#signAuthorizedUpdate( + previous, + { + verificationMethods: { + ...facts.verificationMethods, + atproto: input.repositoryKey, + }, + services: { + ...facts.services, + atproto_pds: { + type: "AtprotoPersonalDataServer", + endpoint: input.endpoint, + }, + }, + }, + async (signed, unsigned) => { + // The signed CID covers the signature; the journaled CID covers exactly the + // public bytes this method returns, so the caller journals and dispatches + // one consistent operation. + const { sig: _signature, ...publicFacts } = signed; + const operation: plc.UnsignedOperation = + validateHistoryOperation(publicFacts); + const cid = String(await cidForCbor(operation)); + saved = { operation, cid }; + await persist(signed, unsigned, cid); + }, + ); + if (!saved) throw new PlcError("InvalidPlcOperation", "Move not signed"); + return saved; + } public async signMigrationMove( input: { workflowId: string; diff --git a/tests/contracts/incoming-handoff.test.mjs b/tests/contracts/incoming-handoff.test.mjs new file mode 100644 index 00000000..d9d901b5 --- /dev/null +++ b/tests/contracts/incoming-handoff.test.mjs @@ -0,0 +1,460 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { createHash, generateKeyPairSync } from "node:crypto"; +import { cidForCbor } from "@atproto/common"; +import { Secp256k1Keypair } from "@atproto/crypto"; +import { createServiceJwt } from "@atproto/xrpc-server"; +import * as plc from "@did-plc/lib"; +import { + openTestDatabase, + query, + verifiedUser, +} from "../support/database-fixture.mjs"; +import { createAccountStorage } from "../../dist/src/database/drizzle/account-storage.js"; +import { createArrivalStorage } from "../../dist/src/database/drizzle/migration-arrival.js"; +import { createOperationOwnershipStore } from "../../dist/src/database/drizzle/operation-ownership.js"; +import { Secp256k1MigrationPlcSigner } from "../../dist/src/plc/signing.js"; +import { + ArrivalPdsClient, + reservationSigningKey, +} from "../../dist/src/pds/arrival-client.js"; +import { createIncomingAuthorization } from "../../dist/src/features/external-migration/incoming-authorization.js"; +import { createArrivalProvisioning } from "../../dist/src/features/external-migration/provision-arrival.js"; + +const hosts = [ + { id: "pds1", url: "https://pds1.example.test" }, + { id: "pds2", url: "https://pds2.example.test" }, +]; +const endpoint = hosts[0].url; +const sourceEndpoint = "https://source.example.test"; +const did = `did:plc:${"a".repeat(24)}`; +const handle = "dest.entryway.test"; +const email = "dest@example.test"; +const serviceDid = "did:web:entryway.example.test"; +const userId = "user-a"; +const day = 86_400_000; +const hash = (char) => char.repeat(64); + +/** Replace fetch for the duration of one observation and always restore it. */ +async function serving(handler, observe) { + const original = globalThis.fetch; + const requests = []; + globalThis.fetch = async (input, init) => { + const url = input instanceof URL ? input : new URL(String(input)); + requests.push({ url: String(url), init }); + return await handler(url, init ?? {}); + }; + try { + return { result: await observe(), requests }; + } finally { + globalThis.fetch = original; + } +} + +const jwk = () => { + const { privateKey } = generateKeyPairSync("ec", { namedCurve: "secp256k1" }); + return { ...privateKey.export({ format: "jwk" }), alg: "ES256K" }; +}; + +test("stock reservation is unauthenticated, sends only the DID and never echoes binding facts", async () => { + const reservationKey = ( + await Secp256k1Keypair.create({ exportable: true }) + ).did(); + const client = new ArrivalPdsClient({ endpoint, did, jwtJwk: jwk() }); + const { result, requests } = await serving( + async () => + new Response(JSON.stringify({ signingKey: reservationKey }), { + status: 200, + headers: { "content-type": "application/json" }, + }), + () => client.reserveSigningKey(did), + ); + assert.equal(result, reservationKey); + assert.equal(requests.length, 1); + assert.equal( + requests[0].url, + "https://pds1.example.test/xrpc/com.atproto.server.reserveSigningKey", + ); + const headers = new Headers(requests[0].init.headers); + assert.equal(headers.get("authorization"), null); + assert.deepEqual(JSON.parse(requests[0].init.body), { did }); +}); + +test("a stock reservation HTTP error, malformed body or unsupported key is refused", async () => { + const client = new ArrivalPdsClient({ endpoint, did, jwtJwk: jwk() }); + const respond = (status, body) => async () => + new Response(body, { + status, + headers: { "content-type": "application/json" }, + }); + for (const handler of [ + respond(503, JSON.stringify({ error: "ServiceUnavailable" })), + respond(200, "not json"), + respond(200, JSON.stringify({ signingKey: 42 })), + respond(200, JSON.stringify({ signingKey: "did:key:zDnae-invalid" })), + respond( + 200, + JSON.stringify({ signingKey: `did:key:z6Mk${"a".repeat(44)}` }), + ), + ]) + await serving(handler, async () => { + await assert.rejects(client.reserveSigningKey(did), { + code: "AccountUnavailable", + }); + }); + // The stock contract echoes no DID or host; extra fields cannot become binding + // facts, and only the validated public key survives. + const reservationKey = ( + await Secp256k1Keypair.create({ exportable: true }) + ).did(); + const echoed = await serving( + respond( + 200, + JSON.stringify({ + signingKey: reservationKey, + did: "did:plc:other", + endpoint, + }), + ), + () => client.reserveSigningKey(did), + ); + assert.equal(echoed.result, reservationKey); + // A validated public key is returned as-is; anything else is not a reservation. + assert.equal( + reservationSigningKey({ + signingKey: `did:key:zQ3sh${"a".repeat(44)}`, + }), + `did:key:zQ3sh${"a".repeat(44)}`, + ); +}); + +test("destination creation sends only the exact move and returns no session to callers", async () => { + const client = new ArrivalPdsClient({ endpoint, did, jwtJwk: jwk() }); + const operation = { type: "plc_operation", prev: `bafyrei${"a".repeat(52)}` }; + const { result, requests } = await serving( + async () => + new Response( + JSON.stringify({ + did, + handle, + accessJwt: "access", + refreshJwt: "refresh", + didDoc: {}, + }), + { status: 200, headers: { "content-type": "application/json" } }, + ), + () => client.createAccount({ did, handle, operation }), + ); + assert.deepEqual(result, { did, handle }); + assert.ok(!JSON.stringify(result).includes("access")); + assert.deepEqual(JSON.parse(requests[0].init.body), { + did, + handle, + plcOp: operation, + }); +}); + +test("deactivation is observed through the account's own status read", async () => { + const client = new ArrivalPdsClient({ endpoint, did, jwtJwk: jwk() }); + let activated = true; + await serving( + async (url) => { + if (url.pathname.endsWith("deactivateAccount")) { + activated = false; + return new Response("", { status: 200 }); + } + return new Response(JSON.stringify({ activated }), { + status: 200, + headers: { "content-type": "application/json" }, + }); + }, + async () => await client.deactivateAccount(did), + ); + await serving( + async () => + new Response(JSON.stringify({ activated: true }), { + status: 200, + headers: { "content-type": "application/json" }, + }), + async () => + await assert.rejects(client.deactivateAccount(did), { + code: "AccountUnavailable", + }), + ); +}); + +async function provisioningFixture() { + const db = await openTestDatabase(":memory:"); + const accounts = createAccountStorage(db, hosts); + const arrivals = createArrivalStorage(db, hosts, { + readAccount: (value) => accounts.getByDid(value), + readBinding: (value) => accounts.getVerifiedBinding(value), + reserveEmailClaim: (value, boundDid, purpose, boundUser) => + accounts.reserveEmail(value, boundDid, purpose, boundUser), + reserveHandleClaim: (value, boundDid) => + accounts.reserveHandle(value, boundDid), + recordSavedUserBinding: (value, boundUser) => + db.insert( + "account_bindings", + { did: value, user_id: boundUser }, + { ignoreConflict: true }, + ), + insertPlacedAccount: (input) => + accounts.insertAccount( + { + did: input.did, + email: input.email, + emailVerified: true, + handle: input.handle, + pdsId: input.pdsId, + pdsUrl: input.pdsUrl, + status: "provisioning", + createdAt: new Date().toISOString(), + }, + input.userId, + ), + }); + const ownership = createOperationOwnershipStore(db); + await verifiedUser(db, userId, email); + const recovery = await Secp256k1Keypair.create({ exportable: true }); + const source = await Secp256k1Keypair.create({ exportable: true }); + const entryway = await Secp256k1Keypair.create({ exportable: true }); + const predecessor = await plc.signOperation( + plc.formatAtprotoOp({ + signingKey: source.did(), + handle, + pds: sourceEndpoint, + rotationKeys: [recovery.did(), source.did()], + prev: null, + }), + recovery, + ); + const predecessorCid = String(await cidForCbor(predecessor)); + const signedSource = plc.normalizeOp(predecessor); + const sourceFacts = { + verificationMethods: signedSource.verificationMethods, + alsoKnownAs: signedSource.alsoKnownAs, + services: signedSource.services, + }; + const handoff = await plc.addSignature( + { + type: signedSource.type, + ...sourceFacts, + rotationKeys: [recovery.did(), source.did(), entryway.did()], + prev: predecessorCid, + }, + source, + ); + // The journaled entry keeps the schema discriminator but never the signature. + const handoffFacts = { + type: signedSource.type, + ...sourceFacts, + rotationKeys: [recovery.did(), source.did(), entryway.did()], + prev: predecessorCid, + }; + // The stored CID covers the normalized public entry, which carries no signature. + const handoffCid = String(await cidForCbor(handoffFacts)); + const reservationKey = ( + await Secp256k1Keypair.create({ exportable: true }) + ).did(); + const code = "arrival-code"; + await arrivals.createArrival({ + operationId: "op-1", + did, + userId, + email, + handle, + pdsId: "pds1", + endpoint, + sourcePlcHead: predecessorCid, + codeHash: createHash("sha256") + .update(`entryway-arrival-code/v1:${code}`) + .digest("hex"), + codeExpiresAt: Date.now() + day, + }); + const claim = await ownership.acquire({ + resource: userId, + kind: "public-arrival", + requestDigest: hash("c"), + workerId: "worker-1", + leaseMs: 120_000, + }); + const intent = await arrivals.recordAllocationIntent(claim, 1, { + operationId: "op-1", + did, + pdsId: "pds1", + endpoint, + }); + await arrivals.recordReservationResult(claim, intent.version, { + operationId: "op-1", + did, + pdsId: "pds1", + endpoint, + signingKey: reservationKey, + }); + await arrivals.recordSignedOperation(claim, intent.version + 1, { + kind: "handoff", + operationId: "op-1", + did, + operation: handoffFacts, + cid: handoffCid, + }); + const signer = await Secp256k1MigrationPlcSigner.fromHex( + Buffer.from(await entryway.export()).toString("hex"), + ); + const verify = createIncomingAuthorization({ + serviceDid, + readDirectory: async () => ({ + "@context": ["https://www.w3.org/ns/did/v1"], + id: did, + verificationMethod: [ + { + id: `${did}#atproto`, + type: "EcdsaSecp256k1VerificationKey2019", + controller: did, + publicKeyMultibase: source.did(), + }, + ], + }), + }); + const now = Math.floor(Date.now() / 1000); + const admission = `Bearer ${await createServiceJwt({ + iss: did, + aud: serviceDid, + lxm: "com.atproto.server.createAccount", + iat: now, + exp: now + 120, + keypair: source, + })}`; + const calls = []; + const state = { + createFailure: false, + createCommitted: false, + deactivateFailure: false, + }; + const provisioning = createArrivalProvisioning({ + arrivals, + verifyIncomingAuthorization: verify, + invitation: { + reserve: async () => calls.push("invite-reserve"), + complete: async () => calls.push("invite-complete"), + }, + plc: { + signMove: async (input, persist) => { + calls.push("sign-move"); + return await signer.signArrivalMove(input, persist); + }, + observe: async () => ({ headCid: handoffCid, tombstone: false }), + }, + backend: { + createAccount: async (input) => { + calls.push("create"); + if (state.createFailure) throw new Error("backend refused creation"); + state.createCommitted = true; + return { did: input.did, handle: input.handle }; + }, + checkAccountStatus: async () => ({ + activated: state.createCommitted && !calls.includes("deactivate"), + }), + deactivateAccount: async () => { + calls.push("deactivate"); + if (state.deactivateFailure) throw new Error("deactivation failed"); + calls.push("deactivated"); + }, + }, + }); + const input = { + operationId: "op-1", + admission, + arrivalCode: code, + invitationCode: undefined, + handle, + requestDigest: hash("d"), + observedHandoff: { did, operation: handoff, cid: handoffCid }, + }; + return { + db, + arrivals, + claim, + provisioning, + input, + calls, + state, + reservationKey, + }; +} + +test("a real signing pass journals the move before creation and returns only a pending result", async () => { + const fixture = await provisioningFixture(); + const result = await fixture.provisioning.provision( + fixture.claim, + fixture.input, + ); + assert.equal(result.state, "pending"); + assert.deepEqual(fixture.calls, [ + "invite-reserve", + "sign-move", + "create", + "deactivate", + "deactivated", + "invite-complete", + ]); + const move = await query( + fixture.db, + "SELECT operation, cid FROM arrival_signed_operations WHERE kind = 'destination-move'", + ); + assert.equal(move.length, 1); + const facts = JSON.parse(move[0].operation); + assert.equal(facts.verificationMethods.atproto, fixture.reservationKey); + assert.equal(facts.services.atproto_pds.endpoint, sourceEndpoint); + assert.equal(move[0].cid, String(await cidForCbor(facts))); + assert.ok(!("sig" in facts)); + assert.ok(!JSON.stringify(result).includes("Jwt")); + const projection = await fixture.arrivals.readArrivalAccess(did); + assert.equal(projection.bound, true); + assert.equal(projection.complete, false); +}); + +test("an early PLC write with a failed account creation stays pending without a binding", async () => { + const fixture = await provisioningFixture(); + fixture.state.createFailure = true; + await assert.rejects( + fixture.provisioning.provision(fixture.claim, fixture.input), + { code: "OperationRecoveryRequired" }, + ); + assert.deepEqual(fixture.calls, ["invite-reserve", "sign-move", "create"]); + const projection = await fixture.arrivals.readArrivalAccess(did); + assert.equal(projection.provisioned, false); + assert.equal(projection.bound, false); + // The exact move is durable, so a later attempt resumes rather than re-signs. + assert.equal( + (await query(fixture.db, "SELECT kind FROM arrival_signed_operations")) + .length, + 2, + ); +}); + +test("a failed deactivation keeps the arrival pending and never binds", async () => { + const fixture = await provisioningFixture(); + fixture.state.deactivateFailure = true; + await assert.rejects( + fixture.provisioning.provision(fixture.claim, fixture.input), + { code: "OperationRecoveryRequired" }, + ); + assert.ok(!fixture.calls.includes("invite-complete")); + const projection = await fixture.arrivals.readArrivalAccess(did); + assert.equal(projection.bound, false); + assert.equal(projection.deactivationObserved, false); +}); + +test("an already-created destination is not duplicated by a second creation", async () => { + const fixture = await provisioningFixture(); + await fixture.provisioning.provision(fixture.claim, fixture.input); + // A second attempt never re-creates: the saved binding refuses a second + // placement, so no additional backend creation or invitation use is admitted. + await assert.rejects( + fixture.provisioning.provision(fixture.claim, fixture.input), + { code: "OperationConflict" }, + ); + assert.equal(fixture.calls.filter((call) => call === "create").length, 1); +}); From 6f5804c6535c75b2d66bbab2215fa559afa40bd7 Mon Sep 17 00:00:00 2001 From: Evelyn Osman Date: Tue, 10 Nov 2026 10:25:39 +0100 Subject: [PATCH 02/13] fix: compare canonical identity against the signed handoff A directory head is the CID of the signed PLC operation, so provisioning compared it against the unsigned facts CID and always reported that the canonical identity had changed after the observed handoff. Compare it with the full signed operation instead and update the test observers to report a signed head. The rotation-key validation tests also awaited their signed operations, so they now reach the ordering and approved-list rules they name rather than passing on a rejected Promise. --- .../external-migration/arrival-lifecycle.test.mjs | 13 ++++++------- .../external-migration/provision-arrival.ts | 7 ++++++- tests/contracts/incoming-handoff.test.mjs | 4 +++- 3 files changed, 15 insertions(+), 9 deletions(-) diff --git a/src/features/external-migration/arrival-lifecycle.test.mjs b/src/features/external-migration/arrival-lifecycle.test.mjs index 253f9459..fcba2608 100644 --- a/src/features/external-migration/arrival-lifecycle.test.mjs +++ b/src/features/external-migration/arrival-lifecycle.test.mjs @@ -339,7 +339,7 @@ test("handoff validation rejects changed source facts, overfull and reordered au // A fourth distinct key stays within the protocol limit but is not the approved // list, so it is rejected rather than truncated or silently accepted. const fourth = (await Secp256k1Keypair.create({ exportable: true })).did(); - const overfull = plc.addSignature( + const overfull = await plc.addSignature( { ...authority.handoffFacts, rotationKeys: [...authority.approved, fourth], @@ -347,10 +347,7 @@ test("handoff validation rejects changed source facts, overfull and reordered au authority.source, ); await assert.rejects( - validate({ - operation: overfull, - approvedRotationKeys: [...authority.approved, fourth], - }), + validate({ operation: overfull, approvedRotationKeys: authority.approved }), { code: "InvalidPlcOperation" }, ); await assert.rejects( @@ -393,7 +390,7 @@ test("handoff validation rejects changed source facts, overfull and reordered au }), { code: "InvalidPlcOperation" }, ); - const reordered = plc.addSignature( + const reordered = await plc.addSignature( { ...authority.handoffFacts, rotationKeys: [...authority.approved].reverse(), @@ -633,6 +630,8 @@ test("watched arrival access stays pending until a binding exists", async () => // Canonical observation evidence supplies the full surviving operation, whose // signature the destination move must chain from; the journal keeps only facts. const handoffCid = String(await cidForCbor(publicHandoff(authority))); + // A directory head is the CID of the signed operation, not of its facts. + const signedHandoffCid = String(await cidForCbor(handoff)); const preparation = createArrivalPreparation({ arrivals, reserveSigningKey: async () => @@ -706,7 +705,7 @@ test("watched arrival access stays pending until a binding exists", async () => // which is exactly what the stock PDS receives as `plcOp`. return await signer.signArrivalMove(input, persist); }, - observe: async () => ({ headCid: handoffCid, tombstone: false }), + observe: async () => ({ headCid: signedHandoffCid, tombstone: false }), }, backend: { createAccount: async (input) => { diff --git a/src/features/external-migration/provision-arrival.ts b/src/features/external-migration/provision-arrival.ts index a5c19089..e82f555b 100644 --- a/src/features/external-migration/provision-arrival.ts +++ b/src/features/external-migration/provision-arrival.ts @@ -210,7 +210,12 @@ export function createArrivalProvisioning({ conflict("The observed handoff does not match its CID"); const canonical = await plc.observe(arrival.did); if (canonical.tombstone) pending("The identity is tombstoned"); - if (canonical.headCid !== input.observedHandoff.cid) + // A directory head is the CID of the signed operation, so it never equals + // the unsigned facts CID the caller supplied for the same handoff. + if ( + canonical.headCid !== + String(await cidForCbor(input.observedHandoff.operation)) + ) pending("Canonical identity changed after the observed handoff"); const observedSource = observedEndpoint(input.observedHandoff.operation); if (observedSource === null) diff --git a/tests/contracts/incoming-handoff.test.mjs b/tests/contracts/incoming-handoff.test.mjs index d9d901b5..ee4993d6 100644 --- a/tests/contracts/incoming-handoff.test.mjs +++ b/tests/contracts/incoming-handoff.test.mjs @@ -254,6 +254,8 @@ async function provisioningFixture() { }; // The stored CID covers the normalized public entry, which carries no signature. const handoffCid = String(await cidForCbor(handoffFacts)); + // The directory head covers the signed operation, which includes the signature. + const signedHandoffCid = String(await cidForCbor(handoff)); const reservationKey = ( await Secp256k1Keypair.create({ exportable: true }) ).did(); @@ -344,7 +346,7 @@ async function provisioningFixture() { calls.push("sign-move"); return await signer.signArrivalMove(input, persist); }, - observe: async () => ({ headCid: handoffCid, tombstone: false }), + observe: async () => ({ headCid: signedHandoffCid, tombstone: false }), }, backend: { createAccount: async (input) => { From 594c20300a6bf0adabd3a8c6204ce3e94a3104a9 Mon Sep 17 00:00:00 2001 From: Evelyn Osman Date: Tue, 10 Nov 2026 11:41:11 +0100 Subject: [PATCH 03/13] fix: send the destination PLC move with its signature The Entryway signed the destination move and then stripped the signature before sending it as plcOp, so a stock PDS in entryway mode refused account creation as an invalid operation. The journal also kept unsigned facts under a CID computed over those facts, which can never equal the directory head. Journal and dispatch the signed operation with the CID over those bytes, so an interrupted attempt can re-dispatch exactly what the directory publishes. A PLC signature is public data, so it is no longer treated as private material; the required signature is now validated in its place. --- .../incoming-signed-destination-move.md | 21 +++++ docs/incoming-migration.md | 4 +- src/database/drizzle/migration-arrival.ts | 21 +++-- .../arrival-lifecycle.test.mjs | 41 +++++---- .../external-migration/provision-arrival.ts | 8 +- src/plc/signing.ts | 25 ++---- .../incoming-arrival-storage.test.mjs | 87 ++++++++++++++++++- tests/contracts/incoming-handoff.test.mjs | 25 +++--- .../incoming-public-mechanisms.test.mjs | 86 ++++++++++++++++++ 9 files changed, 265 insertions(+), 53 deletions(-) create mode 100644 .changeset/incoming-signed-destination-move.md diff --git a/.changeset/incoming-signed-destination-move.md b/.changeset/incoming-signed-destination-move.md new file mode 100644 index 00000000..ea258a82 --- /dev/null +++ b/.changeset/incoming-signed-destination-move.md @@ -0,0 +1,21 @@ +--- +"hypercerts-entryway": patch +--- + +Incoming migration now sends the destination PLC move with its signature, so +destination account creation works against a stock entryway-mode PDS instead of +being refused as an invalid operation. + +What an operator can observe: + +- The destination move is journaled and dispatched as the signed operation the + PLC directory will publish. An interrupted attempt re-dispatches those exact + bytes rather than an unsigned variant of them. +- A journaled operation's CID now matches the directory head, because both cover + the signed bytes. Recorded bytes and their CID agree, so an exact retry remains + idempotent. +- A PLC signature is public data. It is no longer mistaken for private key + material, and a journaled operation must now carry one; private key material is + still refused. + +No schema change, public route or readiness claim is added by this change. diff --git a/docs/incoming-migration.md b/docs/incoming-migration.md index 4807daa0..9cff5d1f 100644 --- a/docs/incoming-migration.md +++ b/docs/incoming-migration.md @@ -571,7 +571,9 @@ normalized operation bytes, a destination move cannot be recorded before its handoff, and private key material is rejected. Repeating the same operation and CID for a kind is idempotent and does not advance the version; a different operation or CID for that kind is a conflict. A caller holding the pre-record version may receive -`already-settled`, so it must not treat that version as a fresh baseline. +`already-settled`, so it must not treat that version as a fresh baseline. The +retained bytes carry the operation signature, and the stored CID is computed over +those signed bytes, so it matches the value the PLC directory reports as the head. Binding rules these calls must enforce: diff --git a/src/database/drizzle/migration-arrival.ts b/src/database/drizzle/migration-arrival.ts index 48c970da..3ad72bd3 100644 --- a/src/database/drizzle/migration-arrival.ts +++ b/src/database/drizzle/migration-arrival.ts @@ -75,7 +75,7 @@ const canonicalFact = (value: unknown): string => { return JSON.stringify(value); }; const carriesPrivateMaterial = (value: Record): boolean => - ["sig", "signature", "privateKey", "privateKeys"].some((key) => key in value); + ["signature", "privateKey", "privateKeys"].some((key) => key in value); const sameTuple = ( saved: StoredRow<"arrival_signed_operations">, input: ArrivalSignedOperationRecord, @@ -526,9 +526,16 @@ export function createArrivalStorage( 400, "Signed public facts never carry private material", ); - let facts: unknown; + const { sig, ...facts } = input.operation; + if (typeof sig !== "string" || sig.length === 0) + throw new DomainError( + "InvalidAccount", + 400, + "A signed PLC operation is required", + ); + let validated: unknown; try { - facts = validateHistoryOperation(input.operation); + validated = validateHistoryOperation(facts); } catch (error) { if (!(error instanceof PlcError)) throw error; throw new DomainError( @@ -537,7 +544,11 @@ export function createArrivalStorage( "A normalized public PLC operation is required", ); } - if (input.cid !== String(await cidForCbor(facts))) + const signedOperation = { + ...(validated as Record), + sig, + }; + if (input.cid !== String(await cidForCbor(signedOperation))) throw new DomainError( "OperationConflict", 409, @@ -586,7 +597,7 @@ export function createArrivalStorage( kind: input.kind, did: input.did, cid: input.cid, - operation: JSON.stringify(facts), + operation: JSON.stringify(signedOperation), kind_operation_cid: `${input.kind}:${input.cid}`, recorded_at: await db.databaseTime(), }); diff --git a/src/features/external-migration/arrival-lifecycle.test.mjs b/src/features/external-migration/arrival-lifecycle.test.mjs index fcba2608..8cb2a968 100644 --- a/src/features/external-migration/arrival-lifecycle.test.mjs +++ b/src/features/external-migration/arrival-lifecycle.test.mjs @@ -404,8 +404,8 @@ test("handoff validation rejects changed source facts, overfull and reordered au test("a crash before the handoff commit dispatches nothing and reuses no baseline", async () => { const { db, authority, claim, arrival } = await fixture(); - const { sig: _sourceSignature, ...publicFacts } = authority.handoffOperation; - const cid = String(await cidForCbor(publicFacts)); + const signedHandoff = authority.handoffOperation; + const cid = String(await cidForCbor(signedHandoff)); let dispatches = 0; let observations = 0; const submission = createHandoffSubmission({ @@ -415,7 +415,7 @@ test("a crash before the handoff commit dispatches nothing and reuses no baselin }, }, directory: { - validate: async () => ({ operation: publicFacts, cid }), + validate: async () => ({ operation: signedHandoff, cid }), submit: async () => { dispatches += 1; }, @@ -441,11 +441,11 @@ test("a crash before the handoff commit dispatches nothing and reuses no baselin test("a crash after the handoff commit reuses the saved bytes without re-signing", async () => { const { db, arrivals, authority, claim, arrival } = await fixture(); - const { sig: _sourceSignature, ...publicFacts } = authority.handoffOperation; - const cid = String(await cidForCbor(publicFacts)); + const signedHandoff = authority.handoffOperation; + const cid = String(await cidForCbor(signedHandoff)); const published = []; const directory = { - validate: async () => ({ operation: publicFacts, cid }), + validate: async () => ({ operation: signedHandoff, cid }), submit: async (input) => { published.push(input); throw new Error("lost publication response"); @@ -460,7 +460,7 @@ test("a crash after the handoff commit reuses the saved bytes without re-signing ); assert.equal(outcome.state, "published"); assert.equal(published.length, 1); - assert.deepEqual(published[0].operation, publicFacts); + assert.deepEqual(published[0].operation, signedHandoff); const saved = await query( db, "SELECT kind, cid, operation FROM arrival_signed_operations", @@ -628,7 +628,8 @@ test("watched arrival access stays pending until a binding exists", async () => const now = Math.floor(Date.now() / 1000); const handoff = authority.handoffOperation; // Canonical observation evidence supplies the full surviving operation, whose - // signature the destination move must chain from; the journal keeps only facts. + // signature the destination move must chain from; the journal keeps the signed + // bytes, while the caller's own observed CID names the unsigned facts. const handoffCid = String(await cidForCbor(publicHandoff(authority))); // A directory head is the CID of the signed operation, not of its facts. const signedHandoffCid = String(await cidForCbor(handoff)); @@ -649,10 +650,7 @@ test("watched arrival access stays pending until a binding exists", async () => const handoffSubmission = createHandoffSubmission({ arrivals, directory: { - validate: async () => ({ - operation: publicHandoff(authority), - cid: handoffCid, - }), + validate: async () => ({ operation: handoff, cid: signedHandoffCid }), submit: async () => {}, observe: async () => ({ applied: true, @@ -692,6 +690,7 @@ test("watched arrival access stays pending until a binding exists", async () => }), }); const calls = []; + let dispatched; const provisioning = createArrivalProvisioning({ arrivals, verifyIncomingAuthorization: verify, @@ -701,8 +700,8 @@ test("watched arrival access stays pending until a binding exists", async () => }, plc: { signMove: async (input, persist) => { - // Wrap the signer so the recorded bytes are the normalized public facts, - // which is exactly what the stock PDS receives as `plcOp`. + // Wrap the signer so the recorded bytes are the signed operation, which + // is exactly what the stock PDS receives as `plcOp`. return await signer.signArrivalMove(input, persist); }, observe: async () => ({ headCid: signedHandoffCid, tombstone: false }), @@ -711,6 +710,7 @@ test("watched arrival access stays pending until a binding exists", async () => createAccount: async (input) => { calls.push("create"); assert.equal(input.did, did); + dispatched = input.operation; return { did, handle }; }, checkAccountStatus: async () => ({ @@ -755,12 +755,23 @@ test("watched arrival access stays pending until a binding exists", async () => // The move was signed over the saved reservation's public key, never a new one. const savedMove = await query( db, - "SELECT operation FROM arrival_signed_operations WHERE kind = 'destination-move'", + "SELECT operation, cid FROM arrival_signed_operations WHERE kind = 'destination-move'", ); assert.equal( JSON.parse(savedMove[0].operation).verificationMethods.atproto, repositoryKey, ); + // The journaled move carries its signature and its CID covers those signed bytes. + const journaledMove = JSON.parse(savedMove[0].operation); + assert.equal(typeof journaledMove.sig, "string"); + assert.ok(journaledMove.sig.length > 0); + assert.equal( + savedMove[0].cid, + String(await cidForCbor(journaledMove)), + "the journaled CID covers the signed operation, not its unsigned facts", + ); + // The destination receives exactly the signed bytes the journal retains. + assert.deepEqual(dispatched, journaledMove); const projection = await arrivals.readArrivalAccess(did); assert.equal(projection.provisioned, true); assert.equal(projection.deactivationObserved, true); diff --git a/src/features/external-migration/provision-arrival.ts b/src/features/external-migration/provision-arrival.ts index e82f555b..701c3d96 100644 --- a/src/features/external-migration/provision-arrival.ts +++ b/src/features/external-migration/provision-arrival.ts @@ -236,9 +236,9 @@ export function createArrivalProvisioning({ repositoryKey: signingKey, endpoint: observedSource, }, - async (_signed, facts, cid) => { - // The normalized public facts and their CID are recorded unmodified; the - // signature wrapper is never persisted. + async (signed, _facts, cid) => { + // The signed bytes and their CID are recorded together, so a retry + // re-dispatches exactly what the destination will publish. const recorded = await arrivals.recordSignedOperation( owner, version, @@ -247,7 +247,7 @@ export function createArrivalProvisioning({ operationId: arrival.operationId, did: arrival.did, repositoryKey: signingKey, - operation: facts as Record, + operation: signed as Record, cid, }, ); diff --git a/src/plc/signing.ts b/src/plc/signing.ts index ab802285..01ea0863 100644 --- a/src/plc/signing.ts +++ b/src/plc/signing.ts @@ -2,11 +2,7 @@ import { cidForCbor } from "@atproto/common"; import { Secp256k1Keypair } from "@atproto/crypto"; import * as plc from "@did-plc/lib"; import { PlcError } from "./errors.js"; -import { - publicUpdateCandidate, - validateHistoryOperation, - validateUnsignedOperation, -} from "./policy.js"; +import { publicUpdateCandidate, validateUnsignedOperation } from "./policy.js"; /** The private rotation key is received only at composition. */ export class Secp256k1MigrationPlcSigner { @@ -186,7 +182,7 @@ export class Secp256k1MigrationPlcSigner { /** Public arrival move: the observed handoff's own facts are replaced only by * the reserved public repository key and destination endpoint. Entryway signs * with its rotation authority; the PDS repository private key never enters here. - * `persist` journals the public facts and their CID before any dispatch. */ + * `persist` journals the signed operation and its CID before any dispatch. */ public async signArrivalMove( input: { handoffOperation: unknown; @@ -199,12 +195,12 @@ export class Secp256k1MigrationPlcSigner { cid: string, ) => Promise, ): Promise<{ - operation: plc.UnsignedOperation; + operation: plc.Operation; cid: string; }> { const previous = this.#previous(input.handoffOperation); const facts = plc.normalizeOp(previous); - let saved: { operation: plc.UnsignedOperation; cid: string } | undefined; + let saved: { operation: plc.Operation; cid: string } | undefined; await this.#signAuthorizedUpdate( previous, { @@ -220,15 +216,10 @@ export class Secp256k1MigrationPlcSigner { }, }, }, - async (signed, unsigned) => { - // The signed CID covers the signature; the journaled CID covers exactly the - // public bytes this method returns, so the caller journals and dispatches - // one consistent operation. - const { sig: _signature, ...publicFacts } = signed; - const operation: plc.UnsignedOperation = - validateHistoryOperation(publicFacts); - const cid = String(await cidForCbor(operation)); - saved = { operation, cid }; + async (signed, unsigned, cid) => { + // The signed CID covers the signature, matching the directory head the + // destination publishes; the caller journals and dispatches these bytes. + saved = { operation: signed, cid }; await persist(signed, unsigned, cid); }, ); diff --git a/tests/contracts/incoming-arrival-storage.test.mjs b/tests/contracts/incoming-arrival-storage.test.mjs index d5138ec0..1144ff6c 100644 --- a/tests/contracts/incoming-arrival-storage.test.mjs +++ b/tests/contracts/incoming-arrival-storage.test.mjs @@ -53,7 +53,12 @@ const signFacts = async (tag, overrides = {}) => ({ ...overrides, }); const signed = async (tag = "a", overrides = {}) => { - const operation = await signFacts(tag, overrides); + // A PLC signature is public bytes. The journal checks only that a non-empty + // string is present; it never verifies the signature cryptographically. + const operation = { + ...(await signFacts(tag, overrides)), + sig: `sig-${tag}`.padEnd(64, "0"), + }; return { operation, cid: String(await cidForCbor(operation)) }; }; @@ -1732,6 +1737,86 @@ test("a changed handoff CID or operation is a conflict and never overwrites the } }); +test("a signed handoff journals its signed bytes and a CID over those bytes", async () => { + const { db, arrivals, claim, prepare, allocate } = await fixture(); + try { + const prepared = await prepare(); + const version = await allocate(prepared.version); + const handoff = await signed(); + const recorded = await arrivals.recordSignedOperation(claim, version, { + kind: "handoff", + operationId: "op-1", + did, + ...handoff, + }); + assert.deepEqual(recorded, { kind: "applied", version: version + 1 }); + const saved = await query( + db, + "SELECT cid, operation FROM arrival_signed_operations WHERE operation_id = ?", + ["op-1"], + ); + assert.equal(saved[0].cid, handoff.cid); + const journaled = JSON.parse(saved[0].operation); + assert.equal(journaled.sig, handoff.operation.sig); + // The stored CID covers the signed bytes, so it can equal a directory head. + assert.equal(saved[0].cid, String(await cidForCbor(journaled))); + } finally { + await db.close(); + } +}); + +test("a journaled operation without a signature is refused", async () => { + const { db, arrivals, claim, prepare, allocate } = await fixture(); + try { + const prepared = await prepare(); + const version = await allocate(prepared.version); + const { sig: _signature, ...facts } = (await signed()).operation; + await assert.rejects( + arrivals.recordSignedOperation(claim, version, { + kind: "handoff", + operationId: "op-1", + did, + operation: facts, + cid: String(await cidForCbor(facts)), + }), + { code: "InvalidAccount" }, + ); + assert.equal( + (await query(db, "SELECT cid FROM arrival_signed_operations")).length, + 0, + ); + assert.equal(await persistedVersion(db, "op-1"), version); + } finally { + await db.close(); + } +}); + +test("a signed operation whose CID covers only its unsigned facts is a conflict", async () => { + const { db, arrivals, claim, prepare, allocate } = await fixture(); + try { + const prepared = await prepare(); + const version = await allocate(prepared.version); + const { sig: _signature, ...facts } = (await signed()).operation; + await assert.rejects( + arrivals.recordSignedOperation(claim, version, { + kind: "handoff", + operationId: "op-1", + did, + operation: (await signed()).operation, + cid: String(await cidForCbor(facts)), + }), + { code: "OperationConflict" }, + ); + assert.equal( + (await query(db, "SELECT cid FROM arrival_signed_operations")).length, + 0, + ); + assert.equal(await persistedVersion(db, "op-1"), version); + } finally { + await db.close(); + } +}); + test("a stale owner records no signed operation and leaves the arrival version unchanged", async () => { const { db, arrivals, claim, prepare, allocate } = await fixture(); try { diff --git a/tests/contracts/incoming-handoff.test.mjs b/tests/contracts/incoming-handoff.test.mjs index ee4993d6..84cc068c 100644 --- a/tests/contracts/incoming-handoff.test.mjs +++ b/tests/contracts/incoming-handoff.test.mjs @@ -245,16 +245,16 @@ async function provisioningFixture() { }, source, ); - // The journaled entry keeps the schema discriminator but never the signature. + // The caller's observed CID names the unsigned facts of the handoff, while the + // journaled bytes are the signed operation the directory head covers. const handoffFacts = { type: signedSource.type, ...sourceFacts, rotationKeys: [recovery.did(), source.did(), entryway.did()], prev: predecessorCid, }; - // The stored CID covers the normalized public entry, which carries no signature. const handoffCid = String(await cidForCbor(handoffFacts)); - // The directory head covers the signed operation, which includes the signature. + // The directory head and the journaled CID both cover the signed operation. const signedHandoffCid = String(await cidForCbor(handoff)); const reservationKey = ( await Secp256k1Keypair.create({ exportable: true }) @@ -298,8 +298,8 @@ async function provisioningFixture() { kind: "handoff", operationId: "op-1", did, - operation: handoffFacts, - cid: handoffCid, + operation: handoff, + cid: signedHandoffCid, }); const signer = await Secp256k1MigrationPlcSigner.fromHex( Buffer.from(await entryway.export()).toString("hex"), @@ -333,6 +333,7 @@ async function provisioningFixture() { createFailure: false, createCommitted: false, deactivateFailure: false, + dispatched: null, }; const provisioning = createArrivalProvisioning({ arrivals, @@ -351,6 +352,7 @@ async function provisioningFixture() { backend: { createAccount: async (input) => { calls.push("create"); + state.dispatched = input.operation; if (state.createFailure) throw new Error("backend refused creation"); state.createCommitted = true; return { did: input.did, handle: input.handle }; @@ -406,11 +408,14 @@ test("a real signing pass journals the move before creation and returns only a p "SELECT operation, cid FROM arrival_signed_operations WHERE kind = 'destination-move'", ); assert.equal(move.length, 1); - const facts = JSON.parse(move[0].operation); - assert.equal(facts.verificationMethods.atproto, fixture.reservationKey); - assert.equal(facts.services.atproto_pds.endpoint, sourceEndpoint); - assert.equal(move[0].cid, String(await cidForCbor(facts))); - assert.ok(!("sig" in facts)); + const journaled = JSON.parse(move[0].operation); + assert.equal(journaled.verificationMethods.atproto, fixture.reservationKey); + assert.equal(journaled.services.atproto_pds.endpoint, sourceEndpoint); + assert.equal(move[0].cid, String(await cidForCbor(journaled))); + assert.equal(typeof journaled.sig, "string"); + assert.ok(journaled.sig.length > 0); + // The destination receives exactly the journaled signed bytes as its `plcOp`. + assert.deepEqual(fixture.state.dispatched, journaled); assert.ok(!JSON.stringify(result).includes("Jwt")); const projection = await fixture.arrivals.readArrivalAccess(did); assert.equal(projection.bound, true); diff --git a/tests/contracts/incoming-public-mechanisms.test.mjs b/tests/contracts/incoming-public-mechanisms.test.mjs index fa53795b..b36e0c54 100644 --- a/tests/contracts/incoming-public-mechanisms.test.mjs +++ b/tests/contracts/incoming-public-mechanisms.test.mjs @@ -1254,3 +1254,89 @@ test( ); }, ); + +test( + "entryway-mode destination refuses an operation without the service rotation key", + { + skip: !process.env.INCOMING_PUBLIC_MECHANISMS, + timeout: reservationBudgetMs + settleTimeoutMs, + }, + async (t) => { + const access = await readProjection(); + const { Secp256k1Keypair } = await import("@atproto/crypto"); + const phaseBudget = createPhaseBudget(t, { + deadlineMs: reservationBudgetMs, + }); + const inbound = createIncomingPublicIo({ + timeoutMs: requestTimeoutMs, + signal: phaseBudget.signal, + }); + t.after(async () => { + await inbound.close({ settleTimeoutMs }); + await phaseBudget.settle(); + }); + const baseUrl = access.destinationUrls[0]; + const xrpc = (method) => `${baseUrl}/xrpc/${method}`; + const attempt = async (method, options = {}) => { + try { + return { + status: 200, + body: await inbound.call(xrpc(method), { + ...options, + signal: phaseBudget.child().signal, + }), + }; + } catch (error) { + if (!(error instanceof ResponseStatusError)) throw error; + return { status: error.status, body: error.body }; + } + }; + // The reservation names the DID; nothing else about the operation is + // trusted, so a locally generated rotation key is enough to sign with. + const did = `did:plc:${"c".repeat(24)}`; + const handle = `unsigned-${did.slice(-8)}.test`; + const reserved = await attempt("com.atproto.server.reserveSigningKey", { + json: { did }, + }); + assert.equal(reserved.status, 200); + const repositoryKey = reserved.body.signingKey; + assert.match(repositoryKey, /^did:key:/); + const rotation = await Secp256k1Keypair.create({ exportable: true }); + const operations = await plc.signOperation( + plc.formatAtprotoOp({ + signingKey: repositoryKey, + handle, + pds: baseUrl, + rotationKeys: [rotation.did()], + prev: null, + }), + rotation, + ); + assert.equal(typeof operations.sig, "string"); + await plc.assureValidSig([rotation.did()], operations); + const { sig: _stripped, ...unsigned } = operations; + const signed = await attempt("com.atproto.server.createAccount", { + json: { did, handle, plcOp: operations }, + }); + const missing = await attempt("com.atproto.server.createAccount", { + json: { did, handle, plcOp: unsigned }, + }); + // Control: the properly signed operation is refused as well, because a test + // mints its own rotation key and can never hold the PDS's configured + // `entryway.plcRotationKey`. The refusal proves the request reaches operation + // validation and its 400 is not a transport or routing failure, so this case + // is a negative control and proves nothing about accepting Entryway's bytes. + assert.equal(signed.status, 400); + assert.equal(signed.body?.error, "IncompatibleDidDoc"); + assert.match(String(signed.body?.message), /rotation key/i); + // The unsigned bytes share that refusal, so this case cannot distinguish them + // from the signed operation at a stock destination. + assert.equal( + missing.status, + 400, + "Entryway mode refuses an operation carrying no signature", + ); + assert.equal(missing.body?.error, "IncompatibleDidDoc"); + assert.match(String(missing.body?.message), /invalid plc operation/i); + }, +); From 14baa6152336675e709903bec646c12267eb6f11 Mon Sep 17 00:00:00 2001 From: Evelyn Osman Date: Tue, 10 Nov 2026 13:20:33 +0100 Subject: [PATCH 04/13] fix: address destination access tokens to the PDS audience Access tokens for destination status and deactivation named the account DID as their audience, which the destination PDS rejects because it accepts only its own service DID on that path. The client now takes the destination service DID and the issuer as configuration and mints tokens through the existing access-token signer instead of hand-rolling a second copy of the same claims. --- src/pds/arrival-client.ts | 41 ++++++++----- tests/contracts/incoming-handoff.test.mjs | 71 +++++++++++++++++++++-- 2 files changed, 92 insertions(+), 20 deletions(-) diff --git a/src/pds/arrival-client.ts b/src/pds/arrival-client.ts index 5fb278ae..2b97fe29 100644 --- a/src/pds/arrival-client.ts +++ b/src/pds/arrival-client.ts @@ -1,8 +1,7 @@ -import { randomBytes } from "node:crypto"; import { parseDidKey } from "@atproto/crypto"; -import { importJWK, SignJWT } from "jose"; import type { JWK } from "jose"; import { DomainError } from "../accounts/errors.js"; +import { createTargetAccessTokenSigner } from "./access-token.js"; /** A stock PDS holds the reserved repository private key. This client only ever * receives public key material and never persists a returned session. */ @@ -61,29 +60,39 @@ async function readPublicJson( * lifecycle-hook or administration credential: ordinary `createAccount` with a * caller-signed move, then self-deactivation with the account credential. */ export class ArrivalPdsClient { - readonly #jwtKey: Promise>>; + readonly #accountAccess: Promise<{ + sign: (did: string) => Promise; + }>; public constructor( private readonly options: { readonly endpoint: string; readonly did: string; + readonly pdsDid: string; + readonly issuer: string; readonly jwtJwk: JWK; }, ) { - this.#jwtKey = importJWK(options.jwtJwk, "ES256K"); + for (const did of [options.pdsDid, options.issuer]) + if (!did.startsWith("did:")) + throw new TypeError( + "A destination service DID and issuer are required", + ); + this.#accountAccess = createTargetAccessTokenSigner({ + privateJwk: options.jwtJwk, + issuer: options.issuer, + audience: options.pdsDid, + }); } #url(method: string): URL { return new URL(`/xrpc/${method}`, this.options.endpoint); } - async #accountAccess(did: string): Promise { - const key = await this.#jwtKey; - return await new SignJWT({ scope: "com.atproto.access" }) - .setProtectedHeader({ alg: "ES256K", typ: "at+jwt" }) - .setSubject(did) - .setAudience(did) - .setIssuedAt() - .setExpirationTime("30s") - .setJti(randomBytes(16).toString("hex")) - .sign(key); + /** These two methods reach the destination's `authVerifier.access()` through + * `authorization()`, which pins `typ: "at+jwt"` and requires the audience to be + * the destination PDS's own DID, with no Entryway fallback. It is a different + * verifier from `verifyEntrywayServiceJwt`, which serves `createAccount` and + * `reserveSigningKey` and requires `typ: "JWT"`; those rules do not apply here. */ + async #accessToken(did: string): Promise { + return await (await this.#accountAccess).sign(did); } /** Stock reservation is unauthenticated and echoes neither DID nor host: the * caller binds the result through its own durable intent, not this response. */ @@ -135,7 +144,7 @@ export class ArrivalPdsClient { const method = "com.atproto.server.checkAccountStatus"; const response = await fetch(this.#url(method), { method: "GET", - headers: { authorization: `Bearer ${await this.#accountAccess(did)}` }, + headers: { authorization: `Bearer ${await this.#accessToken(did)}` }, redirect: "error", signal: AbortSignal.timeout(15_000), }); @@ -159,7 +168,7 @@ export class ArrivalPdsClient { method: "POST", headers: { "content-type": "application/json", - authorization: `Bearer ${await this.#accountAccess(did)}`, + authorization: `Bearer ${await this.#accessToken(did)}`, }, body: JSON.stringify({}), redirect: "error", diff --git a/tests/contracts/incoming-handoff.test.mjs b/tests/contracts/incoming-handoff.test.mjs index 84cc068c..6dc7bcec 100644 --- a/tests/contracts/incoming-handoff.test.mjs +++ b/tests/contracts/incoming-handoff.test.mjs @@ -4,6 +4,7 @@ import { createHash, generateKeyPairSync } from "node:crypto"; import { cidForCbor } from "@atproto/common"; import { Secp256k1Keypair } from "@atproto/crypto"; import { createServiceJwt } from "@atproto/xrpc-server"; +import { decodeJwt, decodeProtectedHeader } from "jose"; import * as plc from "@did-plc/lib"; import { openTestDatabase, @@ -31,6 +32,9 @@ const did = `did:plc:${"a".repeat(24)}`; const handle = "dest.entryway.test"; const email = "dest@example.test"; const serviceDid = "did:web:entryway.example.test"; +/** A destination names itself in `did:web`, derived from its public endpoint. */ +const destinationDid = (url) => + `did:web:${new URL(url).host.replaceAll(":", "%3A")}`; const userId = "user-a"; const day = 86_400_000; const hash = (char) => char.repeat(64); @@ -60,7 +64,13 @@ test("stock reservation is unauthenticated, sends only the DID and never echoes const reservationKey = ( await Secp256k1Keypair.create({ exportable: true }) ).did(); - const client = new ArrivalPdsClient({ endpoint, did, jwtJwk: jwk() }); + const client = new ArrivalPdsClient({ + endpoint, + did, + pdsDid: destinationDid(endpoint), + issuer: serviceDid, + jwtJwk: jwk(), + }); const { result, requests } = await serving( async () => new Response(JSON.stringify({ signingKey: reservationKey }), { @@ -80,8 +90,49 @@ test("stock reservation is unauthenticated, sends only the DID and never echoes assert.deepEqual(JSON.parse(requests[0].init.body), { did }); }); +test("destination access tokens name the PDS as audience and keep the at+jwt type", async () => { + const client = new ArrivalPdsClient({ + endpoint, + did, + pdsDid: destinationDid(endpoint), + issuer: serviceDid, + jwtJwk: jwk(), + }); + const { requests } = await serving( + async () => + new Response(JSON.stringify({ activated: false }), { + status: 200, + headers: { "content-type": "application/json" }, + }), + () => client.checkAccountStatus(did), + ); + assert.equal(requests.length, 1); + const [scheme, token] = new Headers(requests[0].init.headers) + .get("authorization") + .split(" "); + assert.equal(scheme, "Bearer"); + const header = decodeProtectedHeader(token); + const claims = decodeJwt(token); + // The destination's own access() verifier pins both of these. + assert.equal(header.typ, "at+jwt"); + assert.equal(header.alg, "ES256K"); + assert.equal(claims.aud, destinationDid(endpoint)); + assert.notEqual(claims.aud, did); + // The credential speaks for the account, never for the service taking it. + assert.equal(claims.sub, did); + assert.notEqual(claims.sub, destinationDid(endpoint)); + assert.equal(claims.iss, serviceDid); + assert.equal(claims.exp - claims.iat, 60); +}); + test("a stock reservation HTTP error, malformed body or unsupported key is refused", async () => { - const client = new ArrivalPdsClient({ endpoint, did, jwtJwk: jwk() }); + const client = new ArrivalPdsClient({ + endpoint, + did, + pdsDid: destinationDid(endpoint), + issuer: serviceDid, + jwtJwk: jwk(), + }); const respond = (status, body) => async () => new Response(body, { status, @@ -129,7 +180,13 @@ test("a stock reservation HTTP error, malformed body or unsupported key is refus }); test("destination creation sends only the exact move and returns no session to callers", async () => { - const client = new ArrivalPdsClient({ endpoint, did, jwtJwk: jwk() }); + const client = new ArrivalPdsClient({ + endpoint, + did, + pdsDid: destinationDid(endpoint), + issuer: serviceDid, + jwtJwk: jwk(), + }); const operation = { type: "plc_operation", prev: `bafyrei${"a".repeat(52)}` }; const { result, requests } = await serving( async () => @@ -155,7 +212,13 @@ test("destination creation sends only the exact move and returns no session to c }); test("deactivation is observed through the account's own status read", async () => { - const client = new ArrivalPdsClient({ endpoint, did, jwtJwk: jwk() }); + const client = new ArrivalPdsClient({ + endpoint, + did, + pdsDid: destinationDid(endpoint), + issuer: serviceDid, + jwtJwk: jwk(), + }); let activated = true; await serving( async (url) => { From 7af2ca42d7b8ebad05b4e5ee66404c84e4d4b659 Mon Sep 17 00:00:00 2001 From: Evelyn Osman Date: Tue, 10 Nov 2026 14:48:30 +0100 Subject: [PATCH 05/13] fix: point the destination move at the destination PDS The signed move named the source PDS in atproto_pds. A stock PDS in entryway mode compares that endpoint with its own public URL before publishing during account creation, so an operation naming any other host is refused. Source-endpoint retention belongs to the authority handoff, which leaves the account where it is; the destination move is what names the selected PDS. That helper and its guard existed only to supply the move, so both are removed. --- .../arrival-lifecycle.test.mjs | 13 ++++++++++++ .../external-migration/provision-arrival.ts | 21 +------------------ 2 files changed, 14 insertions(+), 20 deletions(-) diff --git a/src/features/external-migration/arrival-lifecycle.test.mjs b/src/features/external-migration/arrival-lifecycle.test.mjs index 8cb2a968..015cc667 100644 --- a/src/features/external-migration/arrival-lifecycle.test.mjs +++ b/src/features/external-migration/arrival-lifecycle.test.mjs @@ -772,6 +772,19 @@ test("watched arrival access stays pending until a binding exists", async () => ); // The destination receives exactly the signed bytes the journal retains. assert.deepEqual(dispatched, journaledMove); + // A stock entryway-mode PDS compares the move's `atproto_pds.endpoint` to its + // own public URL (validateAtprotoData) and refuses an operation naming any + // other host. The move must therefore name the destination, not the source. + assert.equal( + journaledMove.services.atproto_pds.endpoint, + endpoint, + "the destination move names the selected destination PDS", + ); + assert.notEqual( + journaledMove.services.atproto_pds.endpoint, + sourceEndpoint, + "the destination move must not retain the source endpoint", + ); const projection = await arrivals.readArrivalAccess(did); assert.equal(projection.provisioned, true); assert.equal(projection.deactivationObserved, true); diff --git a/src/features/external-migration/provision-arrival.ts b/src/features/external-migration/provision-arrival.ts index 701c3d96..8733d67a 100644 --- a/src/features/external-migration/provision-arrival.ts +++ b/src/features/external-migration/provision-arrival.ts @@ -50,21 +50,6 @@ const signedOperation = ( return facts; }; -/** The authority-only handoff retains source hosting, so the endpoint the - * destination move leaves in place comes from that observed operation. */ -const observedEndpoint = ( - operation: Record, -): string | null => { - const services = operation.services; - if (typeof services !== "object" || services === null) return null; - const service = (services as Record).atproto_pds; - if (typeof service !== "object" || service === null) return null; - const endpoint = (service as Record).endpoint; - return typeof endpoint === "string" && endpoint.startsWith("https://") - ? endpoint - : null; -}; - /** Ordinary destination creation with a separate observed deactivation. This is * not atomic inactive creation: stock creation publishes the move and returns an * active account, so deactivation is its own retained obligation. */ @@ -217,10 +202,6 @@ export function createArrivalProvisioning({ String(await cidForCbor(input.observedHandoff.operation)) ) pending("Canonical identity changed after the observed handoff"); - const observedSource = observedEndpoint(input.observedHandoff.operation); - if (observedSource === null) - return pending("The observed handoff retains no source endpoint"); - // The replay admission may have advanced the arrival; the move and its later // binding chain off the re-read version rather than the stale one. let version = current; @@ -234,7 +215,7 @@ export function createArrivalProvisioning({ { handoffOperation: input.observedHandoff.operation, repositoryKey: signingKey, - endpoint: observedSource, + endpoint: arrival.endpoint, }, async (signed, _facts, cid) => { // The signed bytes and their CID are recorded together, so a retry From ec5c545bd783dedd0b74061cde6f0ff4b35fbd77 Mon Sep 17 00:00:00 2001 From: Evelyn Osman Date: Wed, 11 Nov 2026 11:15:26 +0100 Subject: [PATCH 06/13] refactor: test incoming provisioning through its durable path --- .../arrival-lifecycle.test.mjs | 257 +-------------- .../external-migration/provision-arrival.ts | 290 ---------------- .../incoming-arrival-composition.test.mjs | 76 +++++ tests/contracts/incoming-handoff.test.mjs | 309 +----------------- 4 files changed, 78 insertions(+), 854 deletions(-) diff --git a/src/features/external-migration/arrival-lifecycle.test.mjs b/src/features/external-migration/arrival-lifecycle.test.mjs index 4e1b13f4..d718247e 100644 --- a/src/features/external-migration/arrival-lifecycle.test.mjs +++ b/src/features/external-migration/arrival-lifecycle.test.mjs @@ -12,14 +12,12 @@ import { import { createAccountStorage } from "../../../dist/src/database/drizzle/account-storage.js"; import { createArrivalStorage } from "../../../dist/src/database/drizzle/migration-arrival.js"; import { createOperationOwnershipStore } from "../../../dist/src/database/drizzle/operation-ownership.js"; -import { Secp256k1MigrationPlcSigner } from "../../../dist/src/plc/signing.js"; import { validateIncomingHandoff } from "../../../dist/src/plc/policy.js"; import { createIncomingAuthorization } from "../../../dist/src/features/external-migration/incoming-authorization.js"; import { createArrivalPreparation, generateArrivalCode, } from "../../../dist/src/features/external-migration/prepare-arrival.js"; -import { createArrivalProvisioning } from "../../../dist/src/features/external-migration/provision-arrival.js"; const hosts = [ { id: "pds1", url: "https://pds1.example.test" }, @@ -110,9 +108,6 @@ async function fixture() { const ownership = createOperationOwnershipStore(db); await verifiedUser(db, userId, email); const authority = await sourceAuthority(); - const signer = await Secp256k1MigrationPlcSigner.fromHex( - Buffer.from(await authority.entryway.export()).toString("hex"), - ); const code = generateArrivalCode(); const arrival = await arrivals.createArrival({ operationId: "op-1", @@ -137,7 +132,7 @@ async function fixture() { leaseMs: 120_000, }); await ownership.bindResource(claim, `arrival:${did}`); - return { db, arrivals, ownership, authority, signer, code, arrival, claim }; + return { db, arrivals, ownership, authority, code, arrival, claim }; } test("preparation journals the allocation intent before reserving and persists the public key", async () => { @@ -455,253 +450,3 @@ test("handoff validation rejects changed source facts, overfull and reordered au code: "InvalidPlcOperation", }); }); - -function publicHandoff(authority) { - const { sig: _signature, ...facts } = authority.handoffOperation; - return facts; -} - -test("provisioning refuses a submit-scoped credential and never creates a destination account", async () => { - const { db, arrivals, authority, claim, code } = await fixture(); - const now = Math.floor(Date.now() / 1000); - const store = createOperationOwnershipStore(db); - const created = []; - const verify = createIncomingAuthorization({ - serviceDid, - readDirectory: async () => ({ - "@context": ["https://www.w3.org/ns/did/v1"], - id: did, - verificationMethod: [ - { - id: `${did}#atproto`, - type: "EcdsaSecp256k1VerificationKey2019", - controller: did, - publicKeyMultibase: authority.source.did(), - }, - ], - }), - }); - const preparation = createArrivalPreparation({ - arrivals, - reserveSigningKey: async () => - (await Secp256k1Keypair.create({ exportable: true })).did(), - }); - const reserved = await preparation.reserve(claim, 1, { - operationId: "op-1", - did, - pdsId: "pds1", - endpoint, - signingKey: null, - }); - const provisioning = createArrivalProvisioning({ - arrivals, - verifyIncomingAuthorization: verify, - invitation: { - reserve: async () => {}, - complete: async () => {}, - }, - plc: { - signMove: async () => { - throw new Error("must not sign"); - }, - observe: async () => ({ headCid: "", tombstone: false }), - }, - backend: { - createAccount: async (input) => { - created.push(input); - return { did: input.did, handle: input.handle }; - }, - checkAccountStatus: async () => ({ activated: true }), - deactivateAccount: async () => {}, - }, - }); - void store; - const submitScoped = `Bearer ${await createServiceJwt({ - iss: did, - aud: serviceDid, - lxm: "com.atproto.identity.submitPlcOperation", - iat: now, - exp: now + 120, - keypair: authority.source, - })}`; - await assert.rejects( - provisioning.provision(claim, { - operationId: "op-1", - admission: submitScoped, - arrivalCode: code.code, - invitationCode: undefined, - handle, - requestDigest: hash("e"), - observedHandoff: { - did, - operation: authority.handoffFacts, - cid: "bafyreiaaaa", - }, - }), - { code: "AccountMismatch" }, - ); - assert.equal(reserved.version, 3); - assert.deepEqual(created, []); - assert.deepEqual( - await query(db, "SELECT * FROM arrival_signed_operations"), - [], - ); -}); - -test("watched arrival access stays pending until a binding exists", async () => { - const { db, arrivals, authority, claim, code } = await fixture(); - const now = Math.floor(Date.now() / 1000); - const handoff = authority.handoffOperation; - // Canonical observation evidence supplies the full surviving operation, whose - // signature the destination move must chain from; the journal keeps the signed - // bytes, while the caller's own observed CID names the unsigned facts. - const handoffCid = String(await cidForCbor(publicHandoff(authority))); - // A directory head is the CID of the signed operation, not of its facts. - const signedHandoffCid = String(await cidForCbor(handoff)); - const preparation = createArrivalPreparation({ - arrivals, - reserveSigningKey: async () => - (await Secp256k1Keypair.create({ exportable: true })).did(), - }); - const reserved = await preparation.reserve(claim, 1, { - operationId: "op-1", - did, - pdsId: "pds1", - endpoint, - signingKey: null, - }); - // The destination move is refused until the source handoff is recorded, so the - // handoff is published first and its canonical head is the observed predecessor. - // Storage-only lifecycle fixture. Concrete authenticated publication and crash - // recovery are exercised by incoming-arrival-composition.test.mjs. - await arrivals.recordSignedOperation(claim, reserved.version, { - kind: "handoff", - operationId: "op-1", - did, - operation: handoff, - cid: signedHandoffCid, - }); - const repositoryKey = ( - await query(db, "SELECT signing_key FROM arrival_reservations") - )[0].signing_key; - const signer = await Secp256k1MigrationPlcSigner.fromHex( - Buffer.from(await authority.entryway.export()).toString("hex"), - ); - const verify = createIncomingAuthorization({ - serviceDid, - readDirectory: async () => ({ - "@context": ["https://www.w3.org/ns/did/v1"], - id: did, - verificationMethod: [ - { - id: `${did}#atproto`, - type: "EcdsaSecp256k1VerificationKey2019", - controller: did, - publicKeyMultibase: authority.source.did(), - }, - ], - }), - }); - const calls = []; - let dispatched; - const provisioning = createArrivalProvisioning({ - arrivals, - verifyIncomingAuthorization: verify, - invitation: { - reserve: async () => calls.push("invite-reserve"), - complete: async () => calls.push("invite-complete"), - }, - plc: { - signMove: async (input, persist) => { - // Wrap the signer so the recorded bytes are the signed operation, which - // is exactly what the stock PDS receives as `plcOp`. - return await signer.signArrivalMove(input, persist); - }, - observe: async () => ({ headCid: signedHandoffCid, tombstone: false }), - }, - backend: { - createAccount: async (input) => { - calls.push("create"); - assert.equal(input.did, did); - dispatched = input.operation; - return { did, handle }; - }, - checkAccountStatus: async () => ({ - activated: calls.includes("deactivate") === false, - }), - deactivateAccount: async () => { - calls.push("deactivate"); - }, - }, - }); - const result = await provisioning.provision(claim, { - admission: `Bearer ${await createServiceJwt({ - iss: did, - aud: serviceDid, - lxm: "com.atproto.server.createAccount", - iat: now, - exp: now + 120, - keypair: authority.source, - })}`, - operationId: "op-1", - arrivalCode: code.code, - invitationCode: undefined, - handle, - requestDigest: hash("f"), - observedHandoff: { did, operation: handoff, cid: handoffCid }, - }); - assert.equal(result.state, "pending"); - assert.deepEqual(calls, [ - "invite-reserve", - "create", - "deactivate", - "invite-complete", - ]); - const signed = await query( - db, - "SELECT kind, cid FROM arrival_signed_operations ORDER BY kind", - ); - assert.deepEqual( - signed.map((row) => row.kind), - ["destination-move", "handoff"], - ); - // The move was signed over the saved reservation's public key, never a new one. - const savedMove = await query( - db, - "SELECT operation, cid FROM arrival_signed_operations WHERE kind = 'destination-move'", - ); - assert.equal( - JSON.parse(savedMove[0].operation).verificationMethods.atproto, - repositoryKey, - ); - // The journaled move carries its signature and its CID covers those signed bytes. - const journaledMove = JSON.parse(savedMove[0].operation); - assert.equal(typeof journaledMove.sig, "string"); - assert.ok(journaledMove.sig.length > 0); - assert.equal( - savedMove[0].cid, - String(await cidForCbor(journaledMove)), - "the journaled CID covers the signed operation, not its unsigned facts", - ); - // The destination receives exactly the signed bytes the journal retains. - assert.deepEqual(dispatched, journaledMove); - // A stock entryway-mode PDS compares the move's `atproto_pds.endpoint` to its - // own public URL (validateAtprotoData) and refuses an operation naming any - // other host. The move must therefore name the destination, not the source. - assert.equal( - journaledMove.services.atproto_pds.endpoint, - endpoint, - "the destination move names the selected destination PDS", - ); - assert.notEqual( - journaledMove.services.atproto_pds.endpoint, - sourceEndpoint, - "the destination move must not retain the source endpoint", - ); - const projection = await arrivals.readArrivalAccess(did); - assert.equal(projection.provisioned, true); - assert.equal(projection.deactivationObserved, true); - assert.equal(projection.bound, true); - assert.equal(projection.complete, false); - assert.ok(!JSON.stringify(result).includes("accessJwt")); -}); diff --git a/src/features/external-migration/provision-arrival.ts b/src/features/external-migration/provision-arrival.ts index ceb59c18..1958e30b 100644 --- a/src/features/external-migration/provision-arrival.ts +++ b/src/features/external-migration/provision-arrival.ts @@ -4,9 +4,7 @@ import { DomainError } from "../../accounts/errors.js"; import type { ArrivalTransactor } from "../../database/migration-journal.port.js"; import type { ArrivalRecord } from "./arrival-types.js"; import type { OperationClaim } from "../../database/operation-ownership.port.js"; -import type { VerifyIncomingAuthorization } from "./incoming-authorization.js"; import { incomingCreationMethod } from "./incoming-authorization.js"; -import { arrivalCodeHash } from "./prepare-arrival.js"; import type { OperationOwnership } from "../../accounts/operation-ownership.js"; import type { OperationOwnershipStore } from "../../database/operation-ownership.port.js"; import type { ArrivalAggregate } from "./arrival-types.js"; @@ -15,31 +13,6 @@ import * as Plc from "@did-plc/lib"; import { validateIncomingHandoff } from "../../plc/policy.js"; import { readIncomingObservation } from "../../plc/incoming-observation.js"; -/** Destination creation runs only after the canonical handoff is observed, so the - * observed operation is the predecessor Entryway signs the move over. */ -export interface ObservedHandoff { - readonly did: string; - readonly operation: Record; - readonly cid: string; -} - -export interface ProvisioningInput { - readonly admission: unknown; - readonly arrivalCode: string; - readonly invitationCode: unknown; - /** The saved arrival the caller is resuming; the caller's own user selects it. */ - readonly operationId: string; - readonly handle: string; - readonly requestDigest: string; - readonly observedHandoff: ObservedHandoff; -} - -export interface ProvisioningResult { - readonly state: "pending"; - readonly operationId: string; - readonly version: number; -} - /** Stable recovery: the destination stays pending for the exact accepted retry or * an operator-reconciled attempt, never a fresh remote write. */ const pending = (message: string): never => { @@ -50,269 +23,6 @@ const conflict = (message: string): never => { throw new DomainError("OperationConflict", 409, message); }; -/** Public facts of a signed operation; the signature proves authority, not facts. */ -const signedOperation = ( - operation: Record, -): Record => { - const { sig: _signature, ...facts } = operation; - return facts; -}; - -/** Ordinary destination creation with a separate observed deactivation. This is - * not atomic inactive creation: stock creation publishes the move and returns an - * active account, so deactivation is its own retained obligation. */ -export function createArrivalProvisioning({ - arrivals, - verifyIncomingAuthorization, - invitation, - plc, - backend, -}: { - readonly arrivals: Pick< - ArrivalTransactor, - | "readArrival" - | "readArrivalAccess" - | "consumeArrivalCode" - | "recordSignedOperation" - | "recordArrivalReplay" - | "bindProvisionedArrival" - >; - readonly verifyIncomingAuthorization: VerifyIncomingAuthorization; - /** Existing registration invitation producer; it already accepts atomically. */ - readonly invitation: { - reserve(code: unknown, email: string): Promise; - complete(account: { - readonly email: string; - readonly did: string; - }): Promise; - }; - readonly plc: { - signMove( - input: { - readonly handoffOperation: unknown; - readonly repositoryKey: string; - readonly endpoint: string; - }, - persist: ( - operation: Readonly>, - facts: Readonly>, - cid: string, - ) => Promise, - ): Promise<{ - readonly operation: Record; - readonly cid: string; - }>; - observe(did: string): Promise<{ - readonly headCid: string; - readonly tombstone: boolean; - }>; - }; - readonly backend: { - createAccount(input: { - readonly did: string; - readonly handle: string; - readonly operation: unknown; - }): Promise<{ readonly did: string; readonly handle: string }>; - checkAccountStatus(did: string): Promise<{ readonly activated: boolean }>; - deactivateAccount(did: string): Promise; - }; -}) { - /** The caller selects the saved operation and its own user. The ownership claim - * identity is a separate identifier, so it is never assumed equal to the arrival - * operation ID; another user reads as not found. */ - const savedArrival = async ( - owner: OperationClaim, - input: ProvisioningInput, - ): Promise<{ - readonly arrival: ArrivalRecord; - readonly signingKey: string; - }> => { - const arrival = await arrivals.readArrival( - input.operationId, - owner.resource, - ); - if (!arrival) - throw new DomainError("AccountNotFound", 404, "Arrival not found"); - if (arrival.handle !== input.handle) - conflict("The supplied handle differs from the saved arrival"); - if (arrival.cancelledAt !== null) - conflict("This arrival is no longer actionable"); - // A bound arrival already has its destination; re-sending creation would ask - // the stock PDS to create a second account for the same DID. - const access = await arrivals.readArrivalAccess(arrival.did); - if (access?.bound) - conflict("This arrival is already provisioned and bound"); - if (!arrival.signingKey) - return pending( - "The saved reserved repository key is required before creation", - ); - return { arrival, signingKey: arrival.signingKey }; - }; - return { - async provision( - owner: OperationClaim, - input: ProvisioningInput, - ): Promise { - const { arrival, signingKey } = await savedArrival(owner, input); - // Creation requires a createAccount-scoped source credential. Its replay - // facts are admitted atomically with this accepted work. - const authorization = await verifyIncomingAuthorization({ - presentation: input.admission, - method: incomingCreationMethod, - operationId: arrival.operationId, - requestDigest: input.requestDigest, - expectedDid: arrival.did, - }); - const replay = await arrivals.recordArrivalReplay( - owner, - arrival.version, - authorization.replayFacts, - { - codeHash: arrivalCodeHash(input.arrivalCode), - codeGeneration: arrival.codeGeneration, - }, - ); - if (replay.operationId !== arrival.operationId) - pending("The saved replay binding does not belong to this arrival"); - const current = ( - await arrivals.readArrival(input.operationId, owner.resource) - )?.version; - if (current === undefined) - return pending("The saved arrival is no longer readable"); - const admitted = await arrivals.consumeArrivalCode({ - codeHash: arrivalCodeHash(input.arrivalCode), - did: arrival.did, - method: incomingCreationMethod, - }); - if (!admitted) - throw new DomainError( - "AccountMismatch", - 403, - "The arrival code is invalid, expired or already used", - ); - // Invitations are rejected before any backend effect and accepted once for - // these exact facts. - await invitation.reserve(input.invitationCode, arrival.email); - // Only an observed canonical handoff may be signed over, and only for this - // DID: signing over an unpublished predecessor would fork authority. - if (input.observedHandoff.did !== arrival.did) - pending("The canonical handoff is not observed for this arrival"); - // The observed operation is the full surviving signed predecessor, so the - // journaled public CID identifies it without stripping its signature. - if ( - String( - await cidForCbor(signedOperation(input.observedHandoff.operation)), - ) !== input.observedHandoff.cid - ) - conflict("The observed handoff does not match its CID"); - const canonical = await plc.observe(arrival.did); - if (canonical.tombstone) pending("The identity is tombstoned"); - // A directory head is the CID of the signed operation, so it never equals - // the unsigned facts CID the caller supplied for the same handoff. - if ( - canonical.headCid !== - String(await cidForCbor(input.observedHandoff.operation)) - ) - pending("Canonical identity changed after the observed handoff"); - // The replay admission may have advanced the arrival; the move and its later - // binding chain off the re-read version rather than the stale one. - let version = current; - let recordedVersion: number | null = null; - let move: { - readonly operation: Record; - readonly cid: string; - }; - try { - move = await plc.signMove( - { - handoffOperation: input.observedHandoff.operation, - repositoryKey: signingKey, - endpoint: arrival.endpoint, - }, - async (signed, _facts, cid) => { - // The signed bytes and their CID are recorded together, so a retry - // re-dispatches exactly what the destination will publish. - const recorded = await arrivals.recordSignedOperation( - owner, - version, - { - kind: "destination-move", - operationId: arrival.operationId, - did: arrival.did, - repositoryKey: signingKey, - operation: signed as Record, - cid, - }, - ); - if (recorded.kind === "reconciliation-required") - return pending( - "The destination move requires verified reconciliation", - ); - recordedVersion = recorded.version; - // An already-settled repeat does not advance the version, so only an - // applied record may become the next conditional baseline. - if (recorded.kind === "applied") version = recorded.version; - }, - ); - } catch (error) { - if (error instanceof DomainError) throw error; - return pending("The destination move could not be signed"); - } - // The move is durable before this write. A failure here leaves a published - // move without a backend, which stays pending; it is never repaired by - // signing a different operation. - try { - await backend.createAccount({ - did: arrival.did, - handle: arrival.handle, - operation: move.operation, - }); - } catch { - pending("Destination creation is unresolved; keep the arrival pending"); - } - const created = await backend - .checkAccountStatus(arrival.did) - .catch(() => null); - if (created === null) pending("Destination account state is unobserved"); - await backend - .deactivateAccount(arrival.did) - .catch(() => pending("Destination deactivation is unresolved")); - const deactivated = await backend - .checkAccountStatus(arrival.did) - .catch(() => null); - if (deactivated === null || deactivated.activated) - pending("Destination deactivation is not observed"); - await invitation.complete({ email: arrival.email, did: arrival.did }); - // Only a committed move record authorizes the pending binding, and the - // binding presents that record's own version as its conditional baseline. - const baseline = recordedVersion; - if (baseline === null) - return pending("The destination move was not recorded before creation"); - const bound = await arrivals.bindProvisionedArrival({ - owner, - expectedVersion: baseline, - operationId: arrival.operationId, - did: arrival.did, - userId: arrival.userId, - email: arrival.email, - handle: arrival.handle, - pdsId: arrival.pdsId, - placement: { provisioned: true, deactivationObserved: true }, - }); - if (bound.kind === "reconciliation-required") - return pending("The pending binding requires verified reconciliation"); - // A pending result only. Credential issuance belongs to plan 011; no raw - // backend session or ordinary active access is returned here. An exact - // repeat of the binding reports its saved version unchanged. - return { - state: "pending", - operationId: arrival.operationId, - version: bound.version, - }; - }, - }; -} - /** For internal composition: saved creation admission is the authority for every * continuation. Network work never runs inside an arrival transaction. */ export function createDurableArrivalProvisioning({ diff --git a/tests/contracts/incoming-arrival-composition.test.mjs b/tests/contracts/incoming-arrival-composition.test.mjs index c0a6018f..c7ba91ec 100644 --- a/tests/contracts/incoming-arrival-composition.test.mjs +++ b/tests/contracts/incoming-arrival-composition.test.mjs @@ -300,7 +300,16 @@ async function fixture(t, mode = "modern", mutation = "", fault = "") { ) )[0]; assert.deepEqual(body.plcOp, JSON.parse(recorded.operation)); + assert.equal((await arrivals.readArrivalAccess(did)).bound, false); + assert.equal(body.handle, handle); + assert.equal(body.did, did); + assert.equal(body.plcOp.verificationMethods.atproto, repository.did()); + assert.equal(body.plcOp.services.atproto_pds.endpoint, endpoint); + assert.equal(typeof body.plcOp.sig, "string"); + assert.ok(body.plcOp.sig.length > 0); backendState.exactMove = body.plcOp; + if (backendState.mode === "creation-rejected") + return Response.json({ error: "InvalidRequest" }, { status: 400 }); if (backendState.mode !== "unchanged-head") audit.push({ did, @@ -326,6 +335,9 @@ async function fixture(t, mode = "modern", mutation = "", fault = "") { subject: { $type: "com.atproto.admin.defs#repoRef", did }, deactivated: { applied: true }, }); + assert.equal((await arrivals.readArrivalAccess(did)).bound, false); + if (backendState.mode === "pause-rejected") + return Response.json({ error: "InvalidRequest" }, { status: 400 }); backendState.deactivated = true; if (backendState.mode === "pause-lost") throw new Error("pause response lost"); @@ -902,6 +914,35 @@ test("authenticated creation uses real invitation producer atomically without st ); }); +test("composed creation rejects a submit-scoped credential before admission or destination effects", async (t) => { + const f = await fixture(t); + const prepared = await f.prepare(); + const before = await f.arrivals.readArrivalAggregate( + prepared.operationId, + f.principal.userId, + ); + await assert.rejects( + f.composed.admitIncoming(f.request, { + operationId: prepared.operationId, + method: incomingCreationMethod, + body: { handle }, + presentation: await f.credential(incomingHandoffMethod), + arrivalCode: prepared.arrivalCode, + }), + { code: "AccountMismatch" }, + ); + assert.deepEqual( + await f.arrivals.readArrivalAggregate( + prepared.operationId, + f.principal.userId, + ), + before, + ); + assert.equal(f.backendState.creates, 0); + assert.equal(f.backendState.pauses, 0); + assert.equal(f.publicationAttempts.length, 0); +}); + test("handoff journal failure rolls admission back before any dispatch", async (t) => { const f = await fixture(t); const prepared = await f.prepare(); @@ -986,6 +1027,8 @@ for (const mode of [ "normal", "creation-lost", "pause-lost", + "creation-rejected", + "pause-rejected", "published-absent", "network", "malformed", @@ -1000,8 +1043,29 @@ for (const mode of [ f.composed.continueCreation(f.request, prepared.operationId); if (mode === "normal") { const result = await continuation(); + assert.deepEqual(Object.keys(result).sort(), [ + "operationId", + "state", + "version", + ]); assert.equal(result.state, "pending"); + assert.equal((await f.arrivals.readArrivalAccess(f.did)).complete, false); + const aggregate = await f.arrivals.readArrivalAggregate( + prepared.operationId, + f.principal.userId, + ); + const move = aggregate.signedOperations.find( + (item) => item.kind === "destination-move", + ); + assert.deepEqual(move.operation, f.backendState.exactMove); + assert.equal(move.cid, String(await cidForCbor(move.operation))); + assert.equal( + move.operation.prev, + aggregate.signedOperations.find((item) => item.kind === "handoff").cid, + ); + assert.equal(f.audit.at(-1).cid, move.cid); assert.deepEqual(await continuation(), result); + assert.equal(f.reservations(), 1); assert.equal(f.backendState.creates, 1); assert.equal(f.backendState.pauses, 1); assert.equal(f.backendState.exactMove.alsoKnownAs[0], `at://${handle}`); @@ -1022,6 +1086,18 @@ for (const mode of [ ).reservation.uncertainReason, null, ); + if (["creation-rejected", "pause-rejected"].includes(mode)) { + const projection = await f.arrivals.readArrivalAccess(f.did); + assert.equal(projection.provisioned, false); + assert.equal(projection.deactivationObserved, false); + const aggregate = await f.arrivals.readArrivalAggregate( + prepared.operationId, + f.principal.userId, + ); + assert.equal(aggregate.signedOperations.length, 2); + assert.equal(f.backendState.creates, 1); + assert.equal(f.backendState.pauses, mode === "pause-rejected" ? 1 : 0); + } if (["creation-lost", "pause-lost"].includes(mode)) { await assert.rejects(continuation(), { code: "OperationRecoveryRequired", diff --git a/tests/contracts/incoming-handoff.test.mjs b/tests/contracts/incoming-handoff.test.mjs index 667b060c..55c58f7b 100644 --- a/tests/contracts/incoming-handoff.test.mjs +++ b/tests/contracts/incoming-handoff.test.mjs @@ -1,43 +1,23 @@ import assert from "node:assert/strict"; import test from "node:test"; -import { createHash, generateKeyPairSync } from "node:crypto"; -import { cidForCbor } from "@atproto/common"; +import { generateKeyPairSync } from "node:crypto"; import { Secp256k1Keypair } from "@atproto/crypto"; -import { createServiceJwt } from "@atproto/xrpc-server"; import { decodeJwt, decodeProtectedHeader } from "jose"; -import * as plc from "@did-plc/lib"; -import { - openTestDatabase, - query, - verifiedUser, -} from "../support/database-fixture.mjs"; -import { createAccountStorage } from "../../dist/src/database/drizzle/account-storage.js"; -import { createArrivalStorage } from "../../dist/src/database/drizzle/migration-arrival.js"; -import { createOperationOwnershipStore } from "../../dist/src/database/drizzle/operation-ownership.js"; -import { Secp256k1MigrationPlcSigner } from "../../dist/src/plc/signing.js"; import { ArrivalPdsClient, reservationSigningKey, } from "../../dist/src/pds/arrival-client.js"; -import { createIncomingAuthorization } from "../../dist/src/features/external-migration/incoming-authorization.js"; -import { createArrivalProvisioning } from "../../dist/src/features/external-migration/provision-arrival.js"; - const hosts = [ { id: "pds1", url: "https://pds1.example.test" }, { id: "pds2", url: "https://pds2.example.test" }, ]; const endpoint = hosts[0].url; -const sourceEndpoint = "https://source.example.test"; const did = `did:plc:${"a".repeat(24)}`; const handle = "dest.entryway.test"; -const email = "dest@example.test"; const serviceDid = "did:web:entryway.example.test"; /** A destination names itself in `did:web`, derived from its public endpoint. */ const destinationDid = (url) => `did:web:${new URL(url).host.replaceAll(":", "%3A")}`; -const userId = "user-a"; -const day = 86_400_000; -const hash = (char) => char.repeat(64); /** Replace fetch for the duration of one observation and always restore it. */ async function serving(handler, observe) { @@ -245,290 +225,3 @@ test("deactivation is observed through the account's own status read", async () }), ); }); - -async function provisioningFixture() { - const db = await openTestDatabase(":memory:"); - const accounts = createAccountStorage(db, hosts); - const arrivals = createArrivalStorage(db, hosts, { - readAccount: (value) => accounts.getByDid(value), - readBinding: (value) => accounts.getVerifiedBinding(value), - reserveEmailClaim: (value, boundDid, purpose, boundUser) => - accounts.reserveEmail(value, boundDid, purpose, boundUser), - reserveHandleClaim: (value, boundDid) => - accounts.reserveHandle(value, boundDid), - recordSavedUserBinding: (value, boundUser) => - db.insert( - "account_bindings", - { did: value, user_id: boundUser }, - { ignoreConflict: true }, - ), - insertPlacedAccount: (input) => - accounts.insertAccount( - { - did: input.did, - email: input.email, - emailVerified: true, - handle: input.handle, - pdsId: input.pdsId, - pdsUrl: input.pdsUrl, - status: "provisioning", - createdAt: new Date().toISOString(), - }, - input.userId, - ), - }); - const ownership = createOperationOwnershipStore(db); - await verifiedUser(db, userId, email); - const recovery = await Secp256k1Keypair.create({ exportable: true }); - const source = await Secp256k1Keypair.create({ exportable: true }); - const entryway = await Secp256k1Keypair.create({ exportable: true }); - const predecessor = await plc.signOperation( - plc.formatAtprotoOp({ - signingKey: source.did(), - handle, - pds: sourceEndpoint, - rotationKeys: [recovery.did(), source.did()], - prev: null, - }), - recovery, - ); - const predecessorCid = String(await cidForCbor(predecessor)); - const signedSource = plc.normalizeOp(predecessor); - const sourceFacts = { - verificationMethods: signedSource.verificationMethods, - alsoKnownAs: signedSource.alsoKnownAs, - services: signedSource.services, - }; - const handoff = await plc.addSignature( - { - type: signedSource.type, - ...sourceFacts, - rotationKeys: [recovery.did(), source.did(), entryway.did()], - prev: predecessorCid, - }, - source, - ); - // The caller's observed CID names the unsigned facts of the handoff, while the - // journaled bytes are the signed operation the directory head covers. - const handoffFacts = { - type: signedSource.type, - ...sourceFacts, - rotationKeys: [recovery.did(), source.did(), entryway.did()], - prev: predecessorCid, - }; - const handoffCid = String(await cidForCbor(handoffFacts)); - // The directory head and the journaled CID both cover the signed operation. - const signedHandoffCid = String(await cidForCbor(handoff)); - const reservationKey = ( - await Secp256k1Keypair.create({ exportable: true }) - ).did(); - const code = "arrival-code"; - await arrivals.createArrival({ - operationId: "op-1", - did, - userId, - email, - handle, - pdsId: "pds1", - endpoint, - sourcePlcHead: predecessorCid, - sourcePredecessor: predecessor, - source: sourceFacts, - approvedRotationKeys: handoff.rotationKeys, - codeHash: createHash("sha256") - .update(`entryway-arrival-code/v1:${code}`) - .digest("hex"), - codeExpiresAt: Date.now() + day, - }); - const claim = await ownership.acquire({ - resource: userId, - kind: "public-arrival", - requestDigest: hash("c"), - workerId: "worker-1", - leaseMs: 120_000, - }); - await ownership.bindResource(claim, `arrival:${did}`); - const intent = await arrivals.recordAllocationIntent(claim, 1, { - operationId: "op-1", - did, - pdsId: "pds1", - endpoint, - }); - await arrivals.recordReservationResult(claim, intent.version, { - operationId: "op-1", - did, - pdsId: "pds1", - endpoint, - signingKey: reservationKey, - }); - await arrivals.recordSignedOperation(claim, intent.version + 1, { - kind: "handoff", - operationId: "op-1", - did, - operation: handoff, - cid: signedHandoffCid, - }); - const signer = await Secp256k1MigrationPlcSigner.fromHex( - Buffer.from(await entryway.export()).toString("hex"), - ); - const verify = createIncomingAuthorization({ - serviceDid, - readDirectory: async () => ({ - "@context": ["https://www.w3.org/ns/did/v1"], - id: did, - verificationMethod: [ - { - id: `${did}#atproto`, - type: "EcdsaSecp256k1VerificationKey2019", - controller: did, - publicKeyMultibase: source.did(), - }, - ], - }), - }); - const now = Math.floor(Date.now() / 1000); - const admission = `Bearer ${await createServiceJwt({ - iss: did, - aud: serviceDid, - lxm: "com.atproto.server.createAccount", - iat: now, - exp: now + 120, - keypair: source, - })}`; - const calls = []; - const state = { - createFailure: false, - createCommitted: false, - deactivateFailure: false, - dispatched: null, - }; - const provisioning = createArrivalProvisioning({ - arrivals, - verifyIncomingAuthorization: verify, - invitation: { - reserve: async () => calls.push("invite-reserve"), - complete: async () => calls.push("invite-complete"), - }, - plc: { - signMove: async (input, persist) => { - calls.push("sign-move"); - return await signer.signArrivalMove(input, persist); - }, - observe: async () => ({ headCid: signedHandoffCid, tombstone: false }), - }, - backend: { - createAccount: async (input) => { - calls.push("create"); - state.dispatched = input.operation; - if (state.createFailure) throw new Error("backend refused creation"); - state.createCommitted = true; - return { did: input.did, handle: input.handle }; - }, - checkAccountStatus: async () => ({ - activated: state.createCommitted && !calls.includes("deactivate"), - }), - deactivateAccount: async () => { - calls.push("deactivate"); - if (state.deactivateFailure) throw new Error("deactivation failed"); - calls.push("deactivated"); - }, - }, - }); - const input = { - operationId: "op-1", - admission, - arrivalCode: code, - invitationCode: undefined, - handle, - requestDigest: hash("d"), - observedHandoff: { did, operation: handoff, cid: handoffCid }, - }; - return { - db, - arrivals, - claim, - provisioning, - input, - calls, - state, - reservationKey, - }; -} - -test("a real signing pass journals the move before creation and returns only a pending result", async () => { - const fixture = await provisioningFixture(); - const result = await fixture.provisioning.provision( - fixture.claim, - fixture.input, - ); - assert.equal(result.state, "pending"); - assert.deepEqual(fixture.calls, [ - "invite-reserve", - "sign-move", - "create", - "deactivate", - "deactivated", - "invite-complete", - ]); - const move = await query( - fixture.db, - "SELECT operation, cid FROM arrival_signed_operations WHERE kind = 'destination-move'", - ); - assert.equal(move.length, 1); - const journaled = JSON.parse(move[0].operation); - assert.equal(journaled.verificationMethods.atproto, fixture.reservationKey); - assert.equal(journaled.services.atproto_pds.endpoint, endpoint); - assert.equal(move[0].cid, String(await cidForCbor(journaled))); - assert.equal(typeof journaled.sig, "string"); - assert.ok(journaled.sig.length > 0); - // The destination receives exactly the journaled signed bytes as its `plcOp`. - assert.deepEqual(fixture.state.dispatched, journaled); - assert.ok(!JSON.stringify(result).includes("Jwt")); - const projection = await fixture.arrivals.readArrivalAccess(did); - assert.equal(projection.bound, true); - assert.equal(projection.complete, false); -}); - -test("an early PLC write with a failed account creation stays pending without a binding", async () => { - const fixture = await provisioningFixture(); - fixture.state.createFailure = true; - await assert.rejects( - fixture.provisioning.provision(fixture.claim, fixture.input), - { code: "OperationRecoveryRequired" }, - ); - assert.deepEqual(fixture.calls, ["invite-reserve", "sign-move", "create"]); - const projection = await fixture.arrivals.readArrivalAccess(did); - assert.equal(projection.provisioned, false); - assert.equal(projection.bound, false); - // The exact move is durable, so a later attempt resumes rather than re-signs. - assert.equal( - (await query(fixture.db, "SELECT kind FROM arrival_signed_operations")) - .length, - 2, - ); -}); - -test("a failed deactivation keeps the arrival pending and never binds", async () => { - const fixture = await provisioningFixture(); - fixture.state.deactivateFailure = true; - await assert.rejects( - fixture.provisioning.provision(fixture.claim, fixture.input), - { code: "OperationRecoveryRequired" }, - ); - assert.ok(!fixture.calls.includes("invite-complete")); - const projection = await fixture.arrivals.readArrivalAccess(did); - assert.equal(projection.bound, false); - assert.equal(projection.deactivationObserved, false); -}); - -test("an already-created destination is not duplicated by a second creation", async () => { - const fixture = await provisioningFixture(); - await fixture.provisioning.provision(fixture.claim, fixture.input); - // A second attempt never re-creates: the saved binding refuses a second - // placement, so no additional backend creation or invitation use is admitted. - await assert.rejects( - fixture.provisioning.provision(fixture.claim, fixture.input), - { code: "OperationConflict" }, - ); - assert.equal(fixture.calls.filter((call) => call === "create").length, 1); -}); From 79868a82437df8e80e6f256860e30963dc5ee926 Mon Sep 17 00:00:00 2001 From: Evelyn Osman Date: Wed, 11 Nov 2026 12:06:31 +0100 Subject: [PATCH 07/13] fix: safely initialize incoming migration account signing Keep request digests byte-stable with explicit ordinal ordering and preserve applied-response fault controls with native regression tests. --- .changeset/lazy-incoming-account-signing.md | 5 ++ .../external-migration/arrival-request.ts | 2 +- src/pds/arrival-client.ts | 18 +++-- .../incoming-arrival-composition.test.mjs | 32 ++++++++ .../contracts/incoming-arrival-live.test.mjs | 52 +++++++++++- tests/contracts/incoming-handoff.test.mjs | 81 +++++++++++++++++++ .../support/helpers/incoming-arrival-live.mjs | 33 +++++--- 7 files changed, 204 insertions(+), 19 deletions(-) create mode 100644 .changeset/lazy-incoming-account-signing.md diff --git a/.changeset/lazy-incoming-account-signing.md b/.changeset/lazy-incoming-account-signing.md new file mode 100644 index 00000000..49fde867 --- /dev/null +++ b/.changeset/lazy-incoming-account-signing.md @@ -0,0 +1,5 @@ +--- +"hypercerts-entryway": patch +--- + +For operators using incoming account migration, destination reservation and administrator operations no longer initialize the account-token signing key unnecessarily. Invalid signing keys are reported through awaited account-token operations instead of causing an unhandled rejection during client construction. No configuration change is required. diff --git a/src/features/external-migration/arrival-request.ts b/src/features/external-migration/arrival-request.ts index 3d8bd4f4..32a2e563 100644 --- a/src/features/external-migration/arrival-request.ts +++ b/src/features/external-migration/arrival-request.ts @@ -28,7 +28,7 @@ export function canonicalArrivalValue(value: unknown): unknown { ) return Object.fromEntries( Object.keys(value) - .sort() + .sort((left, right) => (left < right ? -1 : left > right ? 1 : 0)) .map((key) => [ key, canonicalArrivalValue((value as Record)[key]), diff --git a/src/pds/arrival-client.ts b/src/pds/arrival-client.ts index 0bc4f863..adc36ac9 100644 --- a/src/pds/arrival-client.ts +++ b/src/pds/arrival-client.ts @@ -83,9 +83,11 @@ async function readPublicJson( * lifecycle-hook or administration credential: ordinary `createAccount` with a * caller-signed move, then self-deactivation with the account credential. */ export class ArrivalPdsClient { - readonly #accountAccess: Promise<{ - sign: (did: string) => Promise; - }>; + #accountAccess: + | Promise<{ + sign: (did: string) => Promise; + }> + | undefined; public constructor( private readonly options: { readonly endpoint: string; @@ -100,11 +102,6 @@ export class ArrivalPdsClient { throw new TypeError( "A destination service DID and issuer are required", ); - this.#accountAccess = createTargetAccessTokenSigner({ - privateJwk: options.jwtJwk, - issuer: options.issuer, - audience: options.pdsDid, - }); } /** Configured administrator credentials stay in composition's signing closure. */ public async getAccountInfo( @@ -173,6 +170,11 @@ export class ArrivalPdsClient { * verifier from `verifyEntrywayServiceJwt`, which serves `createAccount` and * `reserveSigningKey` and requires `typ: "JWT"`; those rules do not apply here. */ async #accessToken(did: string): Promise { + this.#accountAccess ??= createTargetAccessTokenSigner({ + privateJwk: this.options.jwtJwk, + issuer: this.options.issuer, + audience: this.options.pdsDid, + }); return await (await this.#accountAccess).sign(did); } /** Stock reservation is unauthenticated and echoes neither DID nor host: the diff --git a/tests/contracts/incoming-arrival-composition.test.mjs b/tests/contracts/incoming-arrival-composition.test.mjs index c7ba91ec..3767d55a 100644 --- a/tests/contracts/incoming-arrival-composition.test.mjs +++ b/tests/contracts/incoming-arrival-composition.test.mjs @@ -813,6 +813,38 @@ test("fresh bodies have semantic server digests and reject unsupported fields", parseArrivalRequest(saved, incomingHandoffMethod, { operation: candidate }) .requestDigest; assert.equal(digest(operation), digest(reversed)); + const keys = [ + "\uffff", + "\ue000", + "\ud800\udc00", + "\ud800", + "é", + "e\u0301", + "a", + "Z", + ]; + const nested = Object.fromEntries( + keys.map((key) => [key, ["first", "second"]]), + ); + const reordered = Object.fromEntries(Object.entries(nested).reverse()); + const parsed = parseArrivalRequest(saved, incomingHandoffMethod, { + operation: { nested }, + }); + assert.deepEqual(Object.keys(parsed.operation.nested), [ + "Z", + "a", + "e\u0301", + "é", + "\ud800", + "\ud800\udc00", + "\ue000", + "\uffff", + ]); + assert.equal(digest({ nested }), digest({ nested: reordered })); + assert.notEqual( + digest({ nested }), + digest({ nested: { ...nested, Z: ["second", "first"] } }), + ); assert.notEqual( digest(operation), digest({ diff --git a/tests/contracts/incoming-arrival-live.test.mjs b/tests/contracts/incoming-arrival-live.test.mjs index 8d11c914..2da6d4f2 100644 --- a/tests/contracts/incoming-arrival-live.test.mjs +++ b/tests/contracts/incoming-arrival-live.test.mjs @@ -1,5 +1,55 @@ +import assert from "node:assert/strict"; import test from "node:test"; -import { qualifyIncomingArrival } from "../support/helpers/incoming-arrival-live.mjs"; +import { + qualifyIncomingArrival, + discardAppliedArrivalResponse, +} from "../support/helpers/incoming-arrival-live.mjs"; + +test("arrival response discard drains only the first successful matching fault response", async () => { + for (const [fault, method] of [ + ["creation-lost", "com.atproto.server.createAccount"], + ["pause-lost", "com.atproto.admin.updateSubjectStatus"], + ]) { + const applied = new Response("applied"); + assert.equal( + await discardAppliedArrivalResponse({ + fault, + method, + response: applied, + discarded: false, + }), + true, + ); + assert.equal(applied.bodyUsed, true); + for (const overrides of [ + { fault: "normal" }, + { method: "com.atproto.server.reserveSigningKey" }, + { + method: + fault === "creation-lost" + ? "com.atproto.admin.updateSubjectStatus" + : "com.atproto.server.createAccount", + }, + { discarded: true }, + { status: 503 }, + ]) { + const response = new Response("untouched", { + status: overrides.status ?? 200, + }); + assert.equal( + await discardAppliedArrivalResponse({ + fault, + method, + discarded: false, + ...overrides, + response, + }), + false, + ); + assert.equal(response.bodyUsed, false); + } + } +}); test( "stock source reaches composed inactive pending arrival without fixture authority", diff --git a/tests/contracts/incoming-handoff.test.mjs b/tests/contracts/incoming-handoff.test.mjs index 55c58f7b..6952f099 100644 --- a/tests/contracts/incoming-handoff.test.mjs +++ b/tests/contracts/incoming-handoff.test.mjs @@ -105,6 +105,87 @@ test("destination access tokens name the PDS as audience and keep the at+jwt typ assert.equal(claims.exp - claims.iat, 60); }); +test("invalid signing keys stay unused by reservation and administrator calls", async () => { + const client = new ArrivalPdsClient({ + endpoint, + did, + pdsDid: destinationDid(endpoint), + issuer: serviceDid, + jwtJwk: {}, + }); + const reservationKey = (await Secp256k1Keypair.create()).did(); + await serving( + async (url) => { + if (url.pathname.endsWith("reserveSigningKey")) + return Response.json({ signingKey: reservationKey }); + if (url.pathname.endsWith("getAccountInfo")) + return Response.json({ + did, + handle, + indexedAt: new Date().toISOString(), + }); + return Response.json({}); + }, + async () => { + assert.equal(await client.reserveSigningKey(did), reservationKey); + assert.deepEqual(await client.getAccountInfo(() => "Basic admin"), { + did, + handle, + deactivated: false, + }); + await client.pauseAccount(() => "Basic admin"); + await new Promise((resolve) => setImmediate(resolve)); + }, + ); + const { requests } = await serving( + async () => assert.fail("Invalid signing key must not reach fetch"), + async () => { + const failures = await Promise.allSettled([ + client.checkAccountStatus(did), + client.deactivateAccount(did), + ]); + for (const failure of failures) { + assert.equal(failure.status, "rejected"); + assert.equal(failure.reason.message, "InvalidIssuerSigningKey"); + } + assert.equal(failures[0].reason, failures[1].reason); + await assert.rejects(client.checkAccountStatus(did), { + message: "InvalidIssuerSigningKey", + }); + await new Promise((resolve) => setImmediate(resolve)); + }, + ); + assert.equal(requests.length, 0); +}); + +test("account signer is cached across concurrent and subsequent token requests", async () => { + const signingJwk = jwk(); + const client = new ArrivalPdsClient({ + endpoint, + did, + pdsDid: destinationDid(endpoint), + issuer: serviceDid, + jwtJwk: signingJwk, + }); + const { requests } = await serving( + async () => Response.json({ activated: false }), + async () => { + await Promise.all([ + client.checkAccountStatus(did), + client.checkAccountStatus(did), + ]); + signingJwk.kty = "invalid"; + await client.checkAccountStatus(did); + }, + ); + assert.equal(requests.length, 3); + for (const { init } of requests) { + const token = new Headers(init.headers).get("authorization").slice(7); + assert.equal(decodeJwt(token).aud, destinationDid(endpoint)); + assert.equal(decodeJwt(token).iss, serviceDid); + } +}); + test("a stock reservation HTTP error, malformed body or unsupported key is refused", async () => { const client = new ArrivalPdsClient({ endpoint, diff --git a/tests/support/helpers/incoming-arrival-live.mjs b/tests/support/helpers/incoming-arrival-live.mjs index a6be7792..dc38525d 100644 --- a/tests/support/helpers/incoming-arrival-live.mjs +++ b/tests/support/helpers/incoming-arrival-live.mjs @@ -15,6 +15,22 @@ import { createSmtpMailTransport } from "../../../dist/src/mail/smtp.js"; import { waitForMailpitCode } from "./mailpit.mjs"; import { waitForStockPlcMessage } from "./stock-plc-mailpit.mjs"; +export async function discardAppliedArrivalResponse({ + fault, + method, + response, + discarded, +}) { + const matchesFault = + (fault === "creation-lost" && + method === "com.atproto.server.createAccount") || + (fault === "pause-lost" && + method === "com.atproto.admin.updateSubjectStatus"); + if (discarded || !response.ok || !matchesFault) return false; + await response.arrayBuffer(); + return true; +} + // Contributors qualifying dormant composition use normal proof producers here; // no identity, arrival, or authentication rows are inserted by the harness. export async function qualifyIncomingArrival(t, fault = "normal") { @@ -286,15 +302,14 @@ export async function qualifyIncomingArrival(t, fault = "normal") { if (String(url).startsWith(prepared.destinationEndpoint)) { const binding = await storage.getVerifiedBinding(source.did); calls.push({ method, status: response.status, bound: Boolean(binding) }); - const discardMethod = - fault === "creation-lost" - ? "com.atproto.server.createAccount" - : fault === "pause-lost" - ? "com.atproto.admin.updateSubjectStatus" - : null; - if (!discarded && method === discardMethod && response.ok) { - // Drain the real response before discarding it; preserve the remote effect. - await response.arrayBuffer(); + if ( + await discardAppliedArrivalResponse({ + fault, + method, + response, + discarded, + }) + ) { discarded = true; throw new Error("Controlled applied response discard"); } From 8a0f2e73b56135fe82105dba5fa90f029b85d924 Mon Sep 17 00:00:00 2001 From: Evelyn Osman Date: Wed, 11 Nov 2026 13:28:04 +0100 Subject: [PATCH 08/13] docs: adopt client-managed incoming migration Assign transfer completeness to the migration client while retaining Entryway identity, authorization and durable recovery gates. Replace the previous final-source certification requirement in downstream guidance. --- docs/architecture.md | 11 ++ docs/data-custody.md | 38 ++++--- docs/incoming-migration.md | 174 ++++++++++++++++++------------ docs/reuse-assessment.md | 35 +++++- docs/testing.md | 31 ++++-- tests/flows/external-migration.md | 14 ++- 6 files changed, 212 insertions(+), 91 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 6b54d9f6..dc1ade33 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -177,6 +177,17 @@ binds login and may use a different address from the source. Whole-PDS joining imports established DID/email associations. Neither route adds a bespoke ownership proof or permits email matching alone to establish DID authority. +The [incoming migration contract](incoming-migration.md#c4-client-managed-migration-contract-accepted) +was updated by user decision on 2026-11-11: the client owns record/blob transfer, +checking its chosen state and choosing when to request activation. Entryway guards +authorized activation using canonical identity/custody, placement, saved-user binding, +backend state and durable operation ownership. It does not certify a final source +head or full inventory, or provide a global verification-to-activation write barrier. +Concurrent/later source writes and missing blobs may not transfer. Early PLC cutover, +create-active then pause, pending-account guards and isolation/drain recovery remain +required. This is design acceptance, not completion of credentials, mounted public +routes or stock-PDS public journey/recovery qualification. + The architecture checker resolves real imports, including TS/MJS aliases, dynamic imports and require. It rejects extra ports, raw SQL/SMTP/Better Auth access outside owned boundaries, feature-internal imports, runtime cycles and impure rule modules. diff --git a/docs/data-custody.md b/docs/data-custody.md index 9f843ba5..f8418d45 100644 --- a/docs/data-custody.md +++ b/docs/data-custody.md @@ -1,7 +1,7 @@ # Data model, identity custody and migration Status: current storage facts plus accepted domain contracts and implementation gaps. -Incoming migration design updated: 2026-11-04. +Incoming migration design updated: 2026-11-11. See [architecture](architecture.md) for domain ownership and [delivery reference](delivery-plan.md) for delivery gates. ## 1. Account identity and ownership @@ -57,18 +57,18 @@ The table below records current storage, not the full approved target. Internal refactoring does not require upgrading existing databases; public account migration and existing ePDS deployment conversion remain separate requirements. -| State | Domain or system owner | Current representation | -| -------------------------------------- | ----------------------------------- | --------------------------------------------------------------------- | -| Account identity and status | Accounts | `accounts`, keyed by DID | -| Login identity binding | Accounts | `account_bindings`, unique DID and nonunique Better Auth user | +| State | Domain or system owner | Current representation | +| -------------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Account identity and status | Accounts | `accounts`, keyed by DID | +| Login identity binding | Accounts | `account_bindings`, unique DID and nonunique Better Auth user | | Email and handle claims | Accounts | Primary claims may repeat across DIDs and coexist with a pending primary-email change; backup claims cannot overlap primary claims, and backup and pending claims are mutually exclusive | -| Verified browser identity and sessions | Access / Better Auth adapter | Better Auth-owned tables | -| Device-to-account membership | Access | Indexed provider membership by DID and device ID | -| Clients, grants and protocol state | Access / OAuth provider adapter | Provider stores, partly using namespaced JSON storage | -| Current placement | PDS fleet, exposed through Accounts | `pds_id` in the account row; static configuration supplies hosts | -| Transfer progress | PDS fleet workflow | Legacy operation store and newer versioned workflow/checkpoint tables | -| Public custody evidence | Identity | Import-time custody inventory; not a complete key lifecycle registry | -| Repository, blobs and repository key | Hosting PDS | Reference PDS-managed storage | +| Verified browser identity and sessions | Access / Better Auth adapter | Better Auth-owned tables | +| Device-to-account membership | Access | Indexed provider membership by DID and device ID | +| Clients, grants and protocol state | Access / OAuth provider adapter | Provider stores, partly using namespaced JSON storage | +| Current placement | PDS fleet, exposed through Accounts | `pds_id` in the account row; static configuration supplies hosts | +| Transfer progress | PDS fleet workflow | Legacy operation store and newer versioned workflow/checkpoint tables | +| Public custody evidence | Identity | Import-time custody inventory; not a complete key lifecycle registry | +| Repository, blobs and repository key | Hosting PDS | Reference PDS-managed storage | The database boundary stores account authority, browser authentication, OAuth state, mail and workflow journals in one selected database: `account-authority.sqlite` @@ -382,6 +382,20 @@ cannot bypass guarded activation or ordinary-access restrictions. This differs from the current fixture's post-transfer binding and does not change existing signup activation semantics. Implementation and public qualification remain open. +The user accepted the [C4 client-managed contract](incoming-migration.md#c4-client-managed-migration-contract-accepted) +on 2026-11-11, replacing the former Entryway final-source/inventory certification +and global verification-to-activation write-barrier requirement. The client owns +record/blob transfer, checks its chosen transferred state and requests activation +when it chooses; concurrent/later source writes and unavailable blobs may be absent. +Counts, zero missing blobs and completion flags are diagnostics/intent, never +source ownership or independent completeness proof. Entryway still checks authorized +intent, canonical PLC endpoint/key/rotation custody/handle, expected placement, +saved-user binding, backend state and durable ownership on every pending activation +path. Uncertain writes retain isolation/drain recovery and idempotent journals. +Source deactivation follows confirmed destination activation as a client action. +This decision changes neither early cutover nor the access-JWT revocation gap; +credential lifecycle, public integration and runtime qualification remain pending. + Tools may implement an Entryway-specific public journey; no particular tool is mandatory or assumed compatible. Arrival-code expiry does not release uncertain operations or reverse published custody. No automatic destructive cleanup or diff --git a/docs/incoming-migration.md b/docs/incoming-migration.md index 9e6926a1..9ad9536e 100644 --- a/docs/incoming-migration.md +++ b/docs/incoming-migration.md @@ -1,11 +1,13 @@ # How incoming account migration works -**Status:** accepted design, November 4, 2026; not yet implemented or qualified. +**Status:** accepted design, updated November 11, 2026 for the client-managed +migration contract; implementation and public runtime qualification remain pending. Incoming migration moves an existing account from an external PDS to a PDS behind -Entryway. The account keeps its DID and data. Its hosting endpoint, repository -signing key and destination login binding change. The behavior described below is -the accepted design identified above. +Entryway. The account keeps its DID; the migration client transfers its records +and blobs and checks the transferred state. Entryway does not certify data +completeness. The hosting endpoint, repository signing key and destination login +binding change. The behavior described below is the accepted design identified above. ## Why Entryway migration differs from standalone PDS migration @@ -46,8 +48,8 @@ The protocol accounts for four considerations: - **Availability:** identity cutover precedes data import. The destination is briefly active before deactivation, so provisioning is not an atomic inactive operation. - **Data integrity:** the client retains the original source endpoint after cutover, - transfers a consistent repository snapshot and blobs, and catches up source changes. - Destination activation depends on verified completeness, not identity cutover alone. + exports/imports records and blobs, checks its chosen transferred state and decides + when to request activation. Entryway does not certify universal data completeness. - **Recovery:** PLC publication, backend creation and local binding are separate writes. Durable operation state preserves ownership and progress when responses are lost or only part of the sequence succeeds. @@ -66,8 +68,8 @@ The following stages describe observable account state, not database status valu | 2. Authority handed off | Source hosting remains unchanged; Entryway has authorized rotation authority | Destination creation is eligible after canonical PLC observation | | 3. Destination created | PLC points to the destination with its repository key | Backend account is initially active | | 4. Destination paused and bound | Destination is deactivated; verified user and DID are bound locally | Migration credentials allow transfer while ordinary Entryway access is restricted | -| 5. Data transferred | Repository and blobs are copied and source changes caught up | Account remains migration-pending until readiness checks pass | -| 6. Destination activated | Identity, binding and data checks pass; destination is active | Normal destination access becomes available; the client deactivates the source | +| 5. Data transferred | Client transfers and checks its chosen repository/blob state | Account remains pending until authorized activation and safety checks pass | +| 6. Destination activated | Authorized intent, identity, binding and backend checks pass; destination is active | Normal destination access becomes available; the client deactivates the source | ### Sequence diagram @@ -126,12 +128,11 @@ sequenceDiagram Source-->>Tool: Repository and blobs Tool->>Destination: Import directly using migration credentials Destination-->>Tool: Transfer status - Note over Tool,Destination: Catch up source changes using pinned PDS endpoints + Note over Tool,Destination: Client checks chosen transferred state; later source writes may be absent Tool->>Entryway: 6. Request guarded activation Entryway->>Entryway: Verify canonical identity, binding and backend readiness - Entryway->>Entryway: Verify final repository integrity and all missing-blob pages - Note over Entryway,Destination: Identity cutover alone does not establish data completeness + Note over Tool,Entryway: Authorized client chooses activation; Entryway does not certify final inventory Entryway->>Destination: Activate only after all readiness checks pass Destination-->>Entryway: Observe active state Entryway->>Entryway: Atomically complete activation checkpoint @@ -144,7 +145,7 @@ sequenceDiagram | Component | Responsibility | | --------------- | ------------------------------------------------------------------------------------------------------------------ | | Browser | Verify the destination email through OTP and hand arrival authorization to the tool | -| Migration tool | Obtain source authorization, coordinate public requests and transfer user data | +| Migration tool | Obtain source authorization, transfer/check chosen data and choose when to request activation | | Entryway | Admit arrivals, bind accounts, validate and publish PLC operations, provision the destination and guard activation | | Source PDS | Authenticate the source account, authorize PLC signing and serve source data | | Destination PDS | Store repository and blobs; keep its private repository signing key; apply supported lifecycle operations | @@ -308,10 +309,14 @@ Both data endpoints remain pinned for the transfer. DID resolution now points at the destination; retaining the original source endpoint keeps source exports addressed to the correct PDS. -The client maintains a consistent source snapshot and catches up changes as -necessary. Application preferences may use their own public endpoints; they do -not prove repository completeness. The flow relies on public transfer endpoints, -not private fixture freezing or access to source signing credentials. +The client owns export/import, record and blob transfer, checking its chosen +transferred state and deciding when to request activation. Concurrent or later +source writes and unavailable blobs may not be transferred. The client must make +these limits clear, without presenting activation as Entryway certification of a +final source head or full inventory. This decision adds no blanket loss +acknowledgement or new wizard policy. Application preferences may use their own +public endpoints; they do not prove repository completeness. Transfer uses public +endpoints, not private source freezing or access to source signing credentials. Backend deactivation and Entryway's pending-state guards restrict ordinary use. Pending accounts are blocked from ordinary Entryway OAuth authorization, account @@ -321,28 +326,30 @@ permissions of reachable backend endpoints remain an interoperability considerat ### 6. Readiness checks and activation -Before activation, Entryway independently verifies: - -- Canonical PLC state, destination endpoint and expected keys. -- Destination placement, binding, backend readiness and unresolved operation state. -- Repository contents against the agreed final source snapshot. -- Every page of missing-blob results. - -Counts, a client completion boolean, or zero missing blobs on an empty destination -are insufficient evidence. Valid empty and blob-free source repositories are -accepted when integrity checks agree. The exact public source/destination evidence -mechanism remains unresolved; synthetic snapshot assertions do not establish it. -[C4](#c4-completeness-contract-blocked) records the qualified behavior and its -limits, and the decision that stays open. - -All activation paths for pending arrivals share this readiness gate. Entryway -journals activation, invokes the lifecycle hook, observes the outcome and atomically -completes local activation with its checkpoint. Identity-only activation is -insufficient because cutover precedes data import. - -The client deactivates the source after the destination is ready. Source deletion -is separate and is not scheduled automatically. Post-move login, OAuth, refresh -and direct PDS access remain part of independent interoperability qualification. +Activation requires intent from an authorized client or the saved verified user +under the existing C1/C3 permissions, not an unauthenticated completion claim. +Entryway independently checks canonical PLC identity, destination endpoint, +reserved repository key, approved rotation custody and handle; expected placement, +saved-user binding, backend state and durable operation ownership must agree. +Unresolved external writes retain the C5 isolation/drain and recovery requirements. + +The client, not Entryway, checks the chosen transferred records and blobs. Counts, +zero missing blobs and a client completion flag can be diagnostics or intent, but +are neither independent completeness proof nor source-ownership/identity +authorization. Entryway provides no global verification-to-activation write barrier. +Valid empty and blob-free repositories remain supported. +[C4](#c4-client-managed-migration-contract-accepted) records this accepted replacement +for the former stronger completeness guarantee, not satisfaction of that guarantee. + +Every activation path for a pending arrival must share the same authorization and +safety gate. Entryway journals activation under current ownership, invokes the +lifecycle hook, observes the outcome and atomically completes its checkpoint. +Lost responses retain uncertain attempts until supported reconciliation is safe; +identity cutover or backend status alone cannot complete the operation. + +The client deactivates the source only after confirmed destination activation. +Source deletion is separate and is not scheduled automatically. Post-move login, +OAuth, refresh and direct PDS access remain independent interoperability work. ## Recovery and operation ownership @@ -439,7 +446,8 @@ response. Failed or lost allocation responses retain the saved placement and obligation. Replaying preparation cannot recover a stored code; continuation must use the saved arrival lifecycle rather than allocate another placement. These checks establish preparation state, not source DID ownership, repository finality -or activation readiness. C4 and public exposure remain deferred. +or activation readiness. C4 design is accepted; activation implementation and +public exposure remain deferred. ### Development: authenticated admission and saved continuation @@ -513,7 +521,7 @@ These associations do not mark or clear repository-allocation uncertainty. Binding the saved user and completing the invitation share one database transaction. A bound pending retry returns `{state: "pending", operationId, version}` without remote effects. No public route, transfer credential or activation is added. Exhaustive -crash/rehydration qualification, C4 finality and public migration qualification remain +crash/rehydration qualification, activation implementation and public migration qualification remain deferred. ## Contract qualification gates for implementers @@ -521,15 +529,16 @@ deferred. These are delivery contracts for implementers, not public APIs. The development sections above identify the dormant callables already produced; signatures below remain contract targets unless explicitly linked to those implementations. Accepted -C1, C2, C3 and C5 decisions do not imply public exposure or completed readiness. +C1–C5 decisions do not imply public exposure or completed readiness. Bounded stock-mechanism tests do not establish that Entryway exposes, accepts or gates a complete migration. Read each gate as a producer/consumer handoff. A contract becomes usable by downstream code only when this section states both the exact call shape and the -failure behavior, and a maintainer accepts it per case. C1, C2, C3 and C5 are -**ACCEPTED**; the maintainer decisions behind them are recorded inline as M1 to M4. -C4 remains **BLOCKED** on the named maintainer decision described below. +failure behavior, and a maintainer accepts it per case. C1–C5 are **ACCEPTED** +design contracts; M1–M4 retain their existing meanings. The user accepted the C4 +client-managed responsibility decision on 2026-11-11. Design acceptance does not +complete plan 011 credentials/activation or plan 012 public integration and qualification. Source and destination versions stay distinct. The upstream facts here are inspection of pinned PDS 0.5.36, and the standalone qualification source is the @@ -595,16 +604,16 @@ provisioned, and the caller resumes through `recover` from C3 instead. Errors. Each code is stable and mapped explicitly, and no message carries a secret. -| Condition | Error code | HTTP status | -| ------------------------------------------------ | --------------------------- | ----------- | -| Body fails schema | `InvalidRequest` | 400 | -| Missing or stale OTP proof | `ArrivalProofRequired` | 403 | +| Condition | Error code | HTTP status | +| -------------------------------------------------------- | --------------------------- | ----------- | +| Body fails schema | `InvalidRequest` | 400 | +| Missing or stale OTP proof | `ArrivalProofRequired` | 403 | | Unknown operation or verified principal is not its owner | `AccountNotFound` | 404 | -| Saved arrival is no longer actionable | `ArrivalExpired` | 409 | -| `expectedVersion` differs from the saved version | `OperationConflict` | 409 | -| Concurrent work for the DID is admitted | `OperationPending` | 409 | -| Per-IP or per-subject budget exhausted | `RateLimitExceeded` | 429 | -| Dispatch state makes cancellation unsafe | `OperationRecoveryRequired` | 409 | +| Saved arrival is no longer actionable | `ArrivalExpired` | 409 | +| `expectedVersion` differs from the saved version | `OperationConflict` | 409 | +| Concurrent work for the DID is admitted | `OperationPending` | 409 | +| Per-IP or per-subject budget exhausted | `RateLimitExceeded` | 429 | +| Dispatch state makes cancellation unsafe | `OperationRecoveryRequired` | 409 | Replay. `prepare` with the same verified user, DID and handle is idempotent and returns the same saved operation while that operation is still actionable. A changed @@ -811,13 +820,37 @@ it describes recovery rather than implying full revocation. The destination permission and callback runtime proof also remains unrun; authoring the guard contract does not qualify it. -### C4 completeness contract (BLOCKED) - -Plan 011 readiness and plan 012 exposure stay blocked. Named blocker: no supported -mechanism yet provides authenticated historical source key and head binding, a -complete source and destination inventory, all missing-blob pages, and a barrier that -prevents writes between verification and activation. The named maintainer decision is -which finality and mutation-serialization guarantee to adopt. +### C4 client-managed migration contract (ACCEPTED) + +Accepted user decision, 2026-11-11: adopt the Rust-like client-managed responsibility +contract. This explicitly replaces the former requirement for Entryway to certify +an agreed final source snapshot, exhaustive record/blob inventories and a global +verification-to-activation mutation barrier. It does not establish that the old +stronger guarantee was met. Implementation and runtime qualification are pending. + +The client/tool exports and imports, transfers records and blobs, checks its chosen +transferred state and chooses when to request activation. Concurrent or later source +writes and unavailable blobs may be absent from that transfer. Counts, a zero +missing-blob result or a client completion flag are diagnostics/intent only, not +independent proof or a replacement for source ownership and identity authorization. +No historical final-source attestation or source-admin freeze is a prerequisite. + +Entryway retains C1/C3 activation permissions and the identity, canonical PLC, +endpoint, reserved-key, rotation-custody, handle, placement, saved-user binding, +backend-state and current durable-owner checks described in +[activation](#6-readiness-checks-and-activation). All pending activation paths share +that gate. C5 journals, idempotent continuation, lost-response uncertainty and +isolation/drain recovery are unchanged; client-managed data does not excuse unsafe +external writes. Source deactivation is the client's action after confirmed +destination activation, never automatic deletion. + +Owners and handoffs: plan 008 maintains this policy and stock-mechanism qualification; +009 supplies existing durable arrival/projection/attempt APIs; 010 supplies the +actual dormant `composeIncomingArrival` preparation/admission/continuation flow; +011 must integrate tracked credentials and guarded activation; 012 must mount and +qualify the public consumers. This decision adds no wire field, namespace, fictional +source-attestation producer or optional future evidence schema. Any missing concrete +activation adapter contract must be declared by its owner before implementation. Bounded stock-mechanism evidence and its limits. The committed tests exercise the following source and inactive-destination behaviors within explicit byte and phase @@ -836,21 +869,26 @@ migration qualification; reproof requires a fresh managed sandbox run: client byte does not establish server receipt of the prefix or universal finality. - Reservation: sequential same-DID retry and placement isolation only. -What remains unqualified: blob retention across pages, pagination of a mutable +Limitations of those observations: blob retention across pages, pagination of a mutable missing-blob set, a consistent export under concurrent writes, and any write barrier between verification and activation. The stock export reads one root and then pages blocks (`node_modules/@atproto/pds/dist/actor-store/repo/sql-repo-reader.js:68-90`), so a read is not a consistent snapshot under writes, and the missing-blob set can change between pages. A callback guard alone does not fence an in-flight import or write. -Forbidden resolutions: a private freeze, trusting the client's completion summary, an -arbitrary quiet period, a PDS patch, or a data-plane proxy. Absence of a convenience -endpoint is not proof of impossibility. +These remain limitations, not blockers requiring the abandoned certification +mechanism. They do not change the client's responsibility for its chosen transfer. + +Release qualification still needs a full supported public client journey on stock +PDS: records and blobs, valid empty/blob-free repositories, integrity assertions for +the chosen transferred state, activation authorization across every entrypoint and +bounded interrupted/lost-response recovery. Sample assertions demonstrate those +scenarios; they do not certify all source data or all concurrent writes. -Inputs C4 must still define once the decision is made: how the final source snapshot -is agreed, how later source changes invalidate prior readiness, and whether source -availability or source-supplied authorization is required after cutover. Empty and -blob-free repositories remain valid inputs. +Only the responsibility contract is adopted from Rust. Entryway's accepted early +PLC cutover, create-active then pause, pending-backend guards and recovery ordering +remain unchanged. No Rust autoactivation timer, custom session-revocation endpoint, +forwarding proxy, lost-blob waiver, PDS fork or new wizard policy is adopted. ### C5 dispatch and recovery contract (ACCEPTED) diff --git a/docs/reuse-assessment.md b/docs/reuse-assessment.md index 4263216b..46dd9809 100644 --- a/docs/reuse-assessment.md +++ b/docs/reuse-assessment.md @@ -88,12 +88,43 @@ dispatched (request ordering only, not server-side overlap), an Entryway-hosted inactive destination accepting a streamed import, and sequential same-DID reservation with placement isolation. That run is bounded by its own committed byte and phase budgets and does not establish finality, blob pagination -or an activation barrier. C4 therefore stays blocked, while C1, C2, C3 and C5 are -accepted contracts with dormant preparation, admission and continuation callables, +or an activation barrier. C4 is now an accepted client-managed responsibility +contract, not a claim that those stronger guarantees were proved. C1–C5 are design contracts; existing +dormant producers cover preparation, admission and continuation only, not mounted public APIs or complete readiness; see the contract gates in [incoming migration](incoming-migration.md#contract-qualification-gates-for-implementers). +### Client-managed migration design reference + +For maintainers implementing incoming migration, the user accepted the Rust-like +responsibility contract on 2026-11-11: the client transfers and checks its chosen +records/blobs and chooses when to request activation. Entryway checks authorization, +identity, binding, backend state and durable ownership, not a final source head or +exhaustive inventory. Later source writes and missing blobs may not be transferred. +See [C4](incoming-migration.md#c4-client-managed-migration-contract-accepted) for the +retained gates and pending runtime qualification. + +This decision draws on the reviewed clean upstream revision +`d95d4993bba24fbf18d7851c24b3466258ae6e63` of +[atproto-crates](https://tangled.org/ngerakines.me/atproto-crates), not the older +custody-only pin below. In `crates/atproto-entryway`, `lifecycle.rs:204–289` performs +identity preflight without inventory certification; `ops/migrate_in` provisions a +deactivated account without PLC publication. Its client changes PLC after transfer. +That sequencing is **not** adopted: our unchanged reference PDS requires the +accepted early cutover, create-active then pause sequence and its recovery guards. + +The Rust PDS wizard's approximate count/revision checks and lost-blob acknowledgement +are client behavior, separate from its Entryway activation gate. Its +`portal_migrate:6487–6507` places source deactivation after destination activation. +We adopt client responsibility and that source-deactivation ordering, not a lost-blob +waiver, autoactivation timer, custom session-revocation endpoint or forwarding proxy. +The older `02421130930198fcc0c2636bcffd531c748ef9cf` pin was custody provenance only; +its `crates/atproto-entryway/src/server/accounts.rs:95–100` rejected incoming +migration and was never evidence of this newer behavior. No Rust runtime code is +imported by this policy decision; stock-PDS credential and public journey +qualification remain outstanding, including the existing access-JWT revocation gap. + ## Custody design reference The approved model follows [Rust Entryway in atproto-crates](https://tangled.org/ngerakines.me/atproto-crates) diff --git a/docs/testing.md b/docs/testing.md index 004fbc5b..3474dd5b 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -115,10 +115,15 @@ prove any public behavior, and no Entryway endpoint or route implements this migration: the contract test consumes stock PDS APIs, not Entryway handlers. The preflight verifies the signed PLC operation against the source's observed -rotation keys. The remaining contracts are still open in the -[contract gates](incoming-migration.md#contract-qualification-gates-for-implementers): -C4 finality and activation-race closure stay BLOCKED; C1, C2, C3 and C5 are accepted -contracts with dormant internal producers, not public route or readiness completion. +rotation keys. The [contract gates](incoming-migration.md#contract-qualification-gates-for-implementers) +record accepted C1–C5 design contracts, including the C4 client-managed decision +accepted on 2026-11-11. The client owns transfer, checks its chosen transferred +state and chooses when to request activation; Entryway does not certify a final +source snapshot, exhaustive inventories or a global verification-to-activation +write barrier. Counts, zero missing blobs and client intent do not replace source +ownership proof. Tracked credentials, guarded activation, public exposure and full +runtime qualification remain pending; dormant internal producers do not complete +those gates. Contributors qualifying the dormant incoming-arrival composition run `./tests/local.sh incoming-arrival-live` after `up`. This creates fresh stock @@ -135,8 +140,10 @@ exits, this command stops and restarts both owned destination PDS workers, then approves observe-only recovery in a new dispatcher. Recovery must bind pending without another creation or reservation. Run this disruptive phase alone: it restarts this project's destination services. This suite does not activate a public -migration route or close C4. Its private fixture databases and browser recovery -receipts remain in the owned artifact directory; never publish those receipts. +migration route or qualify the accepted C4 client-managed journey, tracked +credentials or guarded activation. Its private fixture databases and browser +recovery receipts remain in the owned artifact directory; never publish those +receipts. Use the owned-project cleanup procedure below, including after failures. @@ -350,8 +357,16 @@ test container with `CONTRACT_DATABASE_BACKEND=postgresql` and that sandbox's child fixture is SQLite-specific; it does not establish PostgreSQL restart coverage. Run `./tests/local.sh incoming-public-mechanisms` separately for stock runtime evidence. Do not invent a host database URL or report these -commands as executed from native CI alone. Full public journey/readiness remains -blocked by C4, independently of these checks. +commands as executed from native CI alone. Full public journey and guarded +activation qualification remain pending, independently of these checks. Follow the +[accepted C4 contract](incoming-migration.md#c4-client-managed-migration-contract-accepted) +and [public journey coverage](../tests/flows/external-migration.md#public-incoming-migration-shared-email-test-on-hold): +exercise records/blobs, valid empty and blob-free repositories, integrity of the +chosen transferred state, authorization and refusal across every pending-arrival +activation entrypoint, and interrupted/lost-response recovery. Preserve canonical +identity/custody, placement, saved-user binding, backend-state and durable-owner +checks; do not require the abandoned final-source certification or global write +barrier as a prerequisite. ## Feature tests and operational evidence diff --git a/tests/flows/external-migration.md b/tests/flows/external-migration.md index df3b0adc..c424acee 100644 --- a/tests/flows/external-migration.md +++ b/tests/flows/external-migration.md @@ -18,7 +18,19 @@ email for the eventual public journey. Established whole-server shared-primary-e associations remain a separate supported contract. Verify the incoming DID, records and blobs through public endpoints with normal ownership proofs. Do not substitute private fixture calls or negative controls for the full public migration journey. -C4 finality/readiness and public exposure remain deferred. +C4 is the accepted client-managed design as of 2026-11-11, not completed runtime +qualification. Public exposure, tracked credential lifecycle and guarded activation +remain unimplemented. For release, exercise a full stock-PDS client journey with +records/blobs, valid empty and blob-free repositories, integrity checks of the +chosen transferred state and interrupted/lost-response recovery. Test authorized +activation and refusals on every pending-arrival entrypoint, retaining canonical +identity/custody, placement, saved-user binding, backend and durable-owner gates. +Concurrent/later source writes and unavailable blobs may be absent; sample integrity +assertions are not Entryway certification of a final head or exhaustive inventory. +Counts, zero missing blobs and client intent never replace source ownership proof. +The client deactivates the source only after confirmed destination activation; +there is no automatic deletion or new blanket loss acknowledgement. The synthetic +freeze below remains fixture behavior, not a public migration prerequisite. ## Existing synthetic flow From b1639977062f91ab25c7e30b57b27b9b7c839b08 Mon Sep 17 00:00:00 2001 From: Evelyn Osman Date: Wed, 11 Nov 2026 15:06:33 +0100 Subject: [PATCH 09/13] fix: resume incoming handoffs before destination creation Preserve recovery fencing after the destination move and make composition tests independent of a pre-existing artifacts directory. --- .../incoming-arrival-reconciliation-order.md | 5 + src/compose-incoming-arrival.mjs | 29 +++- src/pds/arrival-client.ts | 6 +- .../incoming-arrival-composition.test.mjs | 157 +++++++++++++++++- 4 files changed, 189 insertions(+), 8 deletions(-) create mode 100644 .changeset/incoming-arrival-reconciliation-order.md diff --git a/.changeset/incoming-arrival-reconciliation-order.md b/.changeset/incoming-arrival-reconciliation-order.md new file mode 100644 index 00000000..c459020d --- /dev/null +++ b/.changeset/incoming-arrival-reconciliation-order.md @@ -0,0 +1,5 @@ +--- +"hypercerts-entryway": patch +--- + +For operators recovering pending incoming arrivals, internal reconciliation now resumes an accepted unpublished PLC handoff before destination creation when both admissions are saved. Recovery at the exact saved destination move continues without republishing the handoff or requiring a new source credential. Uncertain writes still require operator isolation and drain approval; this does not expose public migration routes or activate pending accounts. diff --git a/src/compose-incoming-arrival.mjs b/src/compose-incoming-arrival.mjs index 34326131..003b1a4e 100644 --- a/src/compose-incoming-arrival.mjs +++ b/src/compose-incoming-arrival.mjs @@ -9,6 +9,7 @@ import { createPdsAccountClient } from "./pds/account-client.mjs"; import { ArrivalPdsClient } from "./pds/arrival-client.js"; import { createIncomingAuthorization } from "./features/external-migration/incoming-authorization.js"; import { createAuthenticatedArrival } from "./features/external-migration/submit-handoff.js"; +import { readIncomingObservation } from "./plc/incoming-observation.js"; export async function composeIncomingArrival({ db, @@ -129,8 +130,34 @@ export async function composeIncomingArrival({ aggregate.admissions.some( (item) => item.method === "com.atproto.server.createAccount", ) - ) + ) { + const move = aggregate.signedOperations.find( + (item) => item.kind === "destination-move", + ); + if (aggregate.progress.canonicalHandoffCid === null && !move) { + const directory = await readIncomingObservation( + accounts.plcClient, + aggregate.arrival.did, + ); + const handoff = aggregate.signedOperations.find( + (item) => item.kind === "handoff", + ); + if ( + handoff && + [aggregate.arrival.sourcePlcHead, handoff.cid].includes( + directory.sourcePlcHead, + ) + ) { + const result = await authenticated.continueHandoff({ + operationId, + userId, + }); + if (result.state !== "published") + return { state: "pending", operationId }; + } + } return authenticated.continueCreation({ operationId, userId }); + } if ( aggregate.admissions.some( (item) => item.method === "com.atproto.identity.submitPlcOperation", diff --git a/src/pds/arrival-client.ts b/src/pds/arrival-client.ts index adc36ac9..1f634bf4 100644 --- a/src/pds/arrival-client.ts +++ b/src/pds/arrival-client.ts @@ -79,9 +79,9 @@ async function readPublicJson( } } -/** Concrete stock PDS transport for one selected destination. It carries no - * lifecycle-hook or administration credential: ordinary `createAccount` with a - * caller-signed move, then self-deactivation with the account credential. */ +/** For arrival maintainers: stock transport creates with the saved signed move, + * then inspects and pauses through composition's administrator authorization + * callbacks without storing an administrator secret on this client. */ export class ArrivalPdsClient { #accountAccess: | Promise<{ diff --git a/tests/contracts/incoming-arrival-composition.test.mjs b/tests/contracts/incoming-arrival-composition.test.mjs index 3767d55a..eb66e42a 100644 --- a/tests/contracts/incoming-arrival-composition.test.mjs +++ b/tests/contracts/incoming-arrival-composition.test.mjs @@ -10,6 +10,7 @@ import { import { parseArrivalRequest } from "../../dist/src/features/external-migration/arrival-request.js"; import { mkdtempSync, rmSync } from "node:fs"; import { join } from "node:path"; +import { tmpdir } from "node:os"; import { eq } from "drizzle-orm"; import { Secp256k1Keypair } from "@atproto/crypto"; import { cidForCbor } from "@atproto/common"; @@ -37,7 +38,7 @@ const email = "destination@example.test"; const handle = "destination.example.test"; async function fixture(t, mode = "modern", mutation = "", fault = "") { - const directory = mkdtempSync("tests/artifacts/arrival-preparation-"); + const directory = mkdtempSync(join(tmpdir(), "arrival-preparation-")); const path = join(directory, "authority.sqlite"); let db = await openTestDatabase(path); t.after(async () => { @@ -225,7 +226,11 @@ async function fixture(t, mode = "modern", mutation = "", fault = "") { db, "SELECT * FROM arrival_signed_operations", ); - assert.equal(admissions.length, 1); + assert.equal( + admissions.filter((item) => item.method === incomingHandoffMethod) + .length, + 1, + ); assert.equal(signed.length, 1); assert.deepEqual(JSON.parse(signed[0].operation), operation); publicationAttempts.push(structuredClone(operation)); @@ -1027,16 +1032,25 @@ test("verified credential jti cannot admit another incoming method", async (t) = assert.equal((await query(f.db, "SELECT * FROM arrival_replay")).length, 1); }); -async function admitProvisioning(f) { +async function admitProvisioning(f, interruptHandoff = false) { const prepared = await f.prepare(); const operation = await plc.signOperation(prepared.handoff, f.source); - await f.composed.admitIncoming(f.request, { + const dispatch = f.ownership.dispatch; + if (interruptHandoff) + f.ownership.dispatch = async () => { + throw new Error("interrupted before handoff dispatch"); + }; + const handoff = f.composed.admitIncoming(f.request, { operationId: prepared.operationId, method: incomingHandoffMethod, body: { operation }, presentation: await f.credential(), arrivalCode: prepared.arrivalCode, }); + if (interruptHandoff) + await assert.rejects(handoff, /interrupted before handoff dispatch/); + else await handoff; + f.ownership.dispatch = dispatch; const { createInvites } = await import("../../dist/src/features/account-registration/invites.mjs"); const invites = await createInvites({ @@ -1055,6 +1069,141 @@ async function admitProvisioning(f) { return prepared; } +test("reconciliation publishes the accepted unpublished handoff before admitted creation", async (t) => { + const f = await fixture(t); + const prepared = await admitProvisioning(f, true); + const before = await f.arrivals.readArrivalAggregate( + prepared.operationId, + f.principal.userId, + ); + assert.equal(before.admissions.length, 2); + assert.equal(before.progress.canonicalHandoffCid, null); + assert.equal(f.audit.at(-1).cid, f.head); + assert.equal(f.publicationAttempts.length, 0); + assert.equal( + (await f.composed.reconcileArrival(f.request, prepared.operationId)).state, + "pending", + ); + const after = await f.arrivals.readArrivalAggregate( + prepared.operationId, + f.principal.userId, + ); + assert.equal( + after.progress.canonicalHandoffCid, + before.signedOperations[0].cid, + ); + assert.ok(after.progress.provisionedAt); + assert.ok(after.progress.deactivatedAt); + assert.ok(after.progress.boundAt); + assert.deepEqual(after.admissions, before.admissions); + assert.deepEqual(f.publicationAttempts, [ + before.signedOperations[0].operation, + ]); + assert.equal(f.backendState.creates, 1); + assert.equal(f.backendState.pauses, 1); + assert.equal(f.reservations(), 1); + assert.equal(f.credentialsIssued(), 2); + assert.equal(after.signedOperations.length, 2); + assert.equal( + f.audit.at(-1).cid, + after.signedOperations.find((item) => item.kind === "destination-move").cid, + ); +}); + +for (const state of ["divergent", "tombstone", "unavailable"]) { + test(`reconciliation with both admissions retains unpublished work when identity is ${state}`, async (t) => { + const f = await fixture(t); + const prepared = await admitProvisioning(f, true); + const before = await f.arrivals.readArrivalAggregate( + prepared.operationId, + f.principal.userId, + ); + if (state === "unavailable") f.audit[0].cid = "invalid"; + else { + const operation = await plc.signOperation( + state === "tombstone" + ? { type: "plc_tombstone", prev: f.head } + : { + ...prepared.handoff, + alsoKnownAs: ["at://unrelated.example.test"], + }, + f.source, + ); + f.audit.push({ + did: f.did, + operation, + cid: String(await cidForCbor(operation)), + nullified: false, + createdAt: new Date().toISOString(), + }); + } + await assert.rejects( + f.composed.reconcileArrival(f.request, prepared.operationId), + ); + assert.deepEqual( + await f.arrivals.readArrivalAggregate( + prepared.operationId, + f.principal.userId, + ), + before, + ); + assert.equal(f.backendState.creates, 0); + assert.equal(f.backendState.pauses, 0); + assert.equal(f.publicationAttempts.length, 0); + assert.equal(f.reservations(), 1); + assert.equal(f.credentialsIssued(), 2); + }); +} + +for (const mode of ["creation-lost", "pause-lost"]) { + test(`reconciliation at the exact destination move preserves ${mode} recovery fencing`, async (t) => { + const f = await fixture(t); + const prepared = await admitProvisioning(f); + f.backendState.mode = mode; + await assert.rejects( + f.composed.continueCreation(f.request, prepared.operationId), + ); + const before = await f.arrivals.readArrivalAggregate( + prepared.operationId, + f.principal.userId, + ); + const move = before.signedOperations.find( + (item) => item.kind === "destination-move", + ); + assert.equal(f.audit.at(-1).cid, move.cid); + await assert.rejects( + f.composed.reconcileArrival(f.request, prepared.operationId), + { code: "OperationRecoveryRequired" }, + ); + const pending = await f.store.pendingExternal(`arrival:${f.did}`); + await f.store.approveRecovery({ + operationId: pending.operationId, + externalAttemptId: pending.id, + executionAttemptId: pending.executionAttemptId, + target: pending.target, + dispatcherIsolationReference: "test-dispatcher-isolated", + upstreamDrainReference: "test-upstream-drained", + action: "observe", + }); + f.backendState.mode = "normal"; + await f.composed.reconcileArrival(f.request, prepared.operationId); + const after = await f.arrivals.readArrivalAggregate( + prepared.operationId, + f.principal.userId, + ); + assert.ok(after.progress.boundAt); + assert.ok(after.progress.deactivatedAt); + assert.ok(after.progress.provisionedAt); + assert.deepEqual(after.signedOperations, before.signedOperations); + assert.equal(f.backendState.creates, 1); + assert.equal(f.backendState.pauses, 1); + assert.equal(f.publicationAttempts.length, 1); + assert.equal(f.reservations(), 1); + assert.equal(f.credentialsIssued(), 2); + assert.equal(await f.store.pendingExternal(`arrival:${f.did}`), null); + }); +} + for (const mode of [ "normal", "creation-lost", From 5bf2d322576379aa4388f2e79439794882e9a84f Mon Sep 17 00:00:00 2001 From: Evelyn Osman Date: Wed, 11 Nov 2026 15:52:59 +0100 Subject: [PATCH 10/13] fix: isolate restart reconciliation in full contract runs Run restart reconciliation with normal Node isolation so forked workers can report recovery evidence. Preserve failures from either test batch and keep native unit coverage separate without duplicate execution. --- tests/support/ci-lifecycle.test.py | 55 ++++++++++++++++++++++++++++++ tests/support/run-contracts.mjs | 50 +++++++++++++++++++-------- 2 files changed, 90 insertions(+), 15 deletions(-) diff --git a/tests/support/ci-lifecycle.test.py b/tests/support/ci-lifecycle.test.py index 501596af..942b5d8b 100644 --- a/tests/support/ci-lifecycle.test.py +++ b/tests/support/ci-lifecycle.test.py @@ -158,6 +158,61 @@ def test_incoming_native_coverage_is_explicit_and_unique(self): self.assertNotIn(helper, files) self.assertNotIn("tests/support/helpers/incoming-arrival-restart.mjs", files) + def test_contract_runner_isolates_reconciliation_and_preserves_failures(self): + source = Path(__file__).resolve().parents[2] + for directory in ["src", "tests/contracts"]: + (self.root / directory).mkdir(parents=True, exist_ok=True) + for filename in ["run-contracts.mjs", "discover-contracts.mjs"]: + shutil.copy(source / "tests/support" / filename, self.root / "tests/support" / filename) + (self.root / "tests/contracts/account-access.test.mjs").write_text(''' +import assert from 'node:assert/strict'; +import test from 'node:test'; +import {appendFileSync} from 'node:fs'; +test('shared batch', () => { + appendFileSync('executed', 'shared\\n'); + assert.ok(process.execArgv.includes('--test-isolation=none')); + assert.notEqual(process.env.FAIL_SUITE, 'shared'); +}); +''') + (self.root / "tests/contracts/incoming-arrival-reconciliation.test.mjs").write_text(''' +import assert from 'node:assert/strict'; +import test from 'node:test'; +import {appendFileSync} from 'node:fs'; +import {fork} from 'node:child_process'; +test('fresh batch', async () => { + appendFileSync('executed', 'fresh\\n'); + assert.ok(!process.execArgv.includes('--test-isolation=none')); + const flags = await new Promise((resolve, reject) => { + const child = fork('./worker.mjs', {silent: true}); + let received; + child.on('message', value => { received = value; }); + child.on('error', reject); + child.on('exit', code => code === 0 ? resolve(received) : reject(Error(`WorkerExit:${code}`))); + }); + assert.ok(!flags.includes('--test-isolation=none')); + assert.notEqual(process.env.FAIL_SUITE, 'fresh'); +}); +''') + (self.root / "worker.mjs").write_text('process.send(process.execArgv);') + for failed in ["", "shared", "fresh"]: + with self.subTest(failed=failed): + result = subprocess.run(["node", "tests/support/run-contracts.mjs"], cwd=self.root, + env={**self.env, "FAIL_SUITE": failed}, + capture_output=True, text=True, timeout=30) + self.assertEqual(result.returncode, 1 if failed else 0, result.stdout + result.stderr) + executed = self.root / "executed" + self.assertEqual(executed.read_text().splitlines(), ["shared", "fresh"]) + executed.unlink() + for report, title in [("contracts-junit.xml", "shared batch"), + ("contracts-reconciliation-junit.xml", "fresh batch")]: + self.assertIn(title, (self.root / "artifacts" / report).read_text()) + result = subprocess.run(["node", "tests/support/run-contracts.mjs", "--unit"], cwd=self.root, + env={**self.env, "FAIL_SUITE": "fresh"}, + capture_output=True, text=True, timeout=30) + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertEqual((self.root / "executed").read_text().splitlines(), ["shared"]) + self.assertIn('shared batch', (self.root / "artifacts/unit-junit.xml").read_text()) + def test_incoming_live_phase_uses_owned_access_and_real_suite(self): source = Path(__file__).resolve().parents[2] controller = (source / "tests/local.sh").read_text() diff --git a/tests/support/run-contracts.mjs b/tests/support/run-contracts.mjs index f71873e8..1cdf6d56 100644 --- a/tests/support/run-contracts.mjs +++ b/tests/support/run-contracts.mjs @@ -8,18 +8,38 @@ mkdirSync("artifacts", { recursive: true }); const report = unit ? "artifacts/unit-junit.xml" : "artifacts/contracts-junit.xml"; -const result = spawnSync( - process.execPath, - [ - "--test", - "--test-isolation=none", - "--test-reporter=spec", - "--test-reporter-destination=stdout", - "--test-reporter=junit", - `--test-reporter-destination=${report}`, - ...files, - ], - { stdio: "inherit" }, -); -if (result.error) throw result.error; -process.exit(result.status ?? 1); +// Reconciliation forks restart workers, which must not inherit isolation=none. +const reconciliation = + "tests/contracts/incoming-arrival-reconciliation.test.mjs"; +const suites = [ + { + files: files.filter((file) => file !== reconciliation), + flags: ["--test-isolation=none"], + report, + }, + { + files: files.filter((file) => file === reconciliation), + flags: [], + report: "artifacts/contracts-reconciliation-junit.xml", + }, +]; +let status = 0; +for (const suite of suites) { + if (!suite.files.length) continue; + const result = spawnSync( + process.execPath, + [ + "--test", + ...suite.flags, + "--test-reporter=spec", + "--test-reporter-destination=stdout", + "--test-reporter=junit", + `--test-reporter-destination=${suite.report}`, + ...suite.files, + ], + { stdio: "inherit" }, + ); + if (result.error) throw result.error; + if (result.status !== 0) status = result.status ?? 1; +} +process.exit(status); From 453f73171193b9126a0c3eff01c745215a162fd5 Mon Sep 17 00:00:00 2001 From: Evelyn Osman Date: Wed, 11 Nov 2026 16:12:06 +0100 Subject: [PATCH 11/13] fix: prevent recovery fixtures expiring on slower CI workers Keep active recovery within the normal lease budget and shorten only stopped owners through the ownership store. Exercise slow observations and prove fenced takeover of an owner killed during active creation. --- .../incoming-arrival-reconciliation.test.mjs | 32 ++++++++++---- .../helpers/incoming-arrival-restart.mjs | 44 +++++++++++++++---- 2 files changed, 60 insertions(+), 16 deletions(-) diff --git a/tests/contracts/incoming-arrival-reconciliation.test.mjs b/tests/contracts/incoming-arrival-reconciliation.test.mjs index 9f4f4fda..dfd204ec 100644 --- a/tests/contracts/incoming-arrival-reconciliation.test.mjs +++ b/tests/contracts/incoming-arrival-reconciliation.test.mjs @@ -33,11 +33,15 @@ const pendingCuts = new Set([ "tombstone", "uncertain", ]); -function worker(directory, phase, cut, kill = false) { +function worker(directory, phase, cut, kill = false, observationDelay = 0) { return new Promise((resolve, reject) => { - const child = fork(helper, [directory, phase, cut], { - stdio: ["ignore", "pipe", "pipe", "ipc"], - }); + const child = fork( + helper, + [directory, phase, cut, String(observationDelay)], + { + stdio: ["ignore", "pipe", "pipe", "ipc"], + }, + ); let message; let stderr = ""; const timer = setTimeout(() => { @@ -87,8 +91,6 @@ for (const cut of [...cases, "divergent", "tombstone", "uncertain"]) { }), { mode: 0o600 }, ); - // A bounded fixture lease expires naturally; no persisted lease edits. - await new Promise((resolve) => setTimeout(resolve, 350)); const inspected = await worker(directory, "inspect", cut); const checkpoint = inspected.snapshot; assert.ok(checkpoint.aggregate); @@ -157,7 +159,22 @@ for (const cut of [...cases, "divergent", "tombstone", "uncertain"]) { assert.ok(aggregate.progress.boundAt); assert.equal(checkpoint.bindings.length, 1); } - const recovered = await worker(directory, "resume", cut); + if (cut === "lease-takeover") { + const crashedOwner = checkpoint.operations.find( + (operation) => operation.id === checkpoint.claim.operationId, + ); + assert.equal(crashedOwner.state, "running"); + assert.equal(crashedOwner.worker_id, checkpoint.claim.workerId); + assert.equal(crashedOwner.fence, checkpoint.claim.fence); + } + // Regress the old 300 ms unrenewed lease under a controlled slow observation. + const recovered = await worker( + directory, + "resume", + cut, + false, + cut === "creation-response-lost" ? 400 : 0, + ); assert.notEqual(stopped.pid, recovered.pid); assert.notEqual(inspected.pid, recovered.pid); const after = recovered.snapshot; @@ -300,7 +317,6 @@ for (const [phase, cut, marker] of [ }), { mode: 0o600 }, ); - await new Promise((resolve) => setTimeout(resolve, 350)); await assert.rejects(worker(directory, phase, cut), (error) => { assert.match( error.message, diff --git a/tests/support/helpers/incoming-arrival-restart.mjs b/tests/support/helpers/incoming-arrival-restart.mjs index 51c940b9..72294689 100644 --- a/tests/support/helpers/incoming-arrival-restart.mjs +++ b/tests/support/helpers/incoming-arrival-restart.mjs @@ -24,7 +24,7 @@ import { verifiedUser, query } from "../database-inspection.mjs"; // Contributors testing recovery run this as a child, never as an application server. // Only generated fixture signing material is private to this temporary directory. -const [directory, phase, cut] = process.argv.slice(2); +const [directory, phase, cut, observationDelay = "0"] = process.argv.slice(2); const journalPath = join(directory, "remote.json"); const save = (value) => writeFileSync(journalPath, JSON.stringify(value), { mode: 0o600 }); @@ -35,8 +35,23 @@ const change = (work) => { save(value); return value; }; +let stopping = false; +let takeoverReady = false; const stop = async (boundary) => { - if (phase !== "initial" || cut !== boundary) return; + if (phase !== "initial" || cut !== boundary || stopping) return; + stopping = true; + const claim = load().lastClaim; + const operation = ( + await query(db, "SELECT * FROM authority_operations") + ).find((row) => row.id === claim.operationId); + // Contributors shorten only the stopped owner's lease through the real store. + // Active fixture work otherwise uses the production lease budget. + if (operation.state === "running" && operation.worker_id === claim.workerId) { + const expires = await store.renew(claim, 300); + change((remote) => { + remote.crashLeaseExpiresAt = expires; + }); + } process.send({ boundary, pid: process.pid }); await new Promise(() => {}); }; @@ -129,12 +144,12 @@ store.acquire = async (...args) => { change((remote) => { remote.lastClaim = claim; }); + if (takeoverReady) await stop("lease-takeover"); return claim; }; const ownership = createOperationOwnership({ store, heartbeatMs: 0, - leaseMs: 300, }); const signer = await Secp256k1MigrationPlcSigner.fromHex(initialRemote.hot); const originalSign = signer.signArrivalMove.bind(signer); @@ -194,6 +209,9 @@ class ControlledObservationOutage extends Error { const client = { url: "https://plc.example.test", getAuditableLog: async () => { + await new Promise((resolve) => + setTimeout(resolve, Number(observationDelay)), + ); if (phase === "resume-unexpected") throw new TypeError("UnexpectedObservationFailure"); if (phase === "resume-unexpected-coded") @@ -355,6 +373,13 @@ const snapshot = async () => { ?.atproto, }; }; +// Use the database's actual lease clock, including in the fresh recovery process. +// No persisted deadlines or fence checks are bypassed to make takeover possible. +if (phase !== "initial") { + const expires = load().crashLeaseExpiresAt; + while (expires && (await db.databaseTime()) <= expires) + await new Promise((resolve) => setTimeout(resolve, 25)); +} try { if (phase === "initial") { const prepared = await composed.prepareArrival({}, "fixture-proof", { @@ -419,12 +444,11 @@ try { }); } await stop( - cut === "lease-takeover" - ? "lease-takeover" - : ["divergent", "tombstone", "uncertain"].includes(cut) - ? cut - : "creation-admitted", + ["divergent", "tombstone", "uncertain"].includes(cut) + ? cut + : "creation-admitted", ); + takeoverReady = cut === "lease-takeover"; await composed.continueCreation({}, prepared.operationId); if (cut === "actor-during-sign") throw new Error("ActorRaceUnexpectedSuccess"); @@ -545,6 +569,10 @@ try { } if (cut === "lease-takeover") { const old = before.claim; + const replacement = load().lastClaim; + assert.equal(replacement.operationId, old.operationId); + assert.ok(replacement.fence > old.fence); + assert.notEqual(replacement.attemptId, old.attemptId); await assert.rejects(store.assertActive(old), { code: "OperationLeaseLost", }); From 0c638d3b2b9646ac11f5a670609603b493844f4b Mon Sep 17 00:00:00 2001 From: Evelyn Osman Date: Wed, 11 Nov 2026 16:27:31 +0100 Subject: [PATCH 12/13] ci: distinguish hosted package network failures before builds --- .github/workflows/ci.yml | 74 ++++++++++++++++++++++++++++++ tests/support/ci-lifecycle.test.py | 48 +++++++++++++++++++ 2 files changed, 122 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1aed971b..dca21f7f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -79,6 +79,72 @@ jobs: test "$DOCKER_CONTEXT" = default docker --context default compose version deno --version + - name: Diagnose hosted package network + continue-on-error: true + timeout-minutes: 3 + run: &package-network-diagnostics | + # CI maintainers: compare runner, container and fresh build networking. + python3 - <<'PYTHON' + import subprocess + import uuid + + probe = r""" + const dns = require('node:dns').promises; + const http = require('node:http'); + const https = require('node:https'); + (async () => { + for (const host of ['archive.ubuntu.com', 'security.ubuntu.com', 'deb.nodesource.com']) { + try { + await Promise.race([dns.lookup(host), new Promise((_, reject) => setTimeout(() => reject({code: 'DNS_TIMEOUT'}), 5000).unref())]); + console.log('dns host=' + host + ' status=resolved'); + } catch (error) { + console.log('dns host=' + host + ' code=' + (error.code || 'DNS_FAILED')); + process.exitCode = 1; + } + } + for (const url of ['http://archive.ubuntu.com/ubuntu/dists/noble/InRelease', 'https://archive.ubuntu.com/ubuntu/dists/noble/InRelease', 'http://security.ubuntu.com/ubuntu/dists/noble-security/InRelease', 'https://security.ubuntu.com/ubuntu/dists/noble-security/InRelease', 'https://deb.nodesource.com/node_24.x/dists/nodistro/InRelease']) { + await new Promise(resolve => { + const request = (url.startsWith('https:') ? https : http).request(url, {method: 'HEAD'}, response => { + console.log('http url=' + url + ' status=' + response.statusCode); + if (response.statusCode < 200 || response.statusCode >= 400) process.exitCode = 1; + response.destroy(); + resolve(); + }); + const timer = setTimeout(() => request.destroy(Object.assign(new Error(), {code: 'PROBE_TIMEOUT'})), 5000); + request.on('close', () => clearTimeout(timer)); + request.on('error', error => { + console.log('http url=' + url + ' code=' + (error.code || 'REQUEST_FAILED')); + process.exitCode = 1; + resolve(); + }); + request.end(); + }); + } + })(); + """ + image = 'mcr.microsoft.com/playwright:v1.58.2-noble' + probe = ' '.join(probe.splitlines()) + container = 'hypercerts-entryway-network-probe-' + uuid.uuid4().hex + commands = [ + ('runner', ['node', '-e', probe], None), + ('container', ['docker', '--context', 'default', 'run', '--rm', '--name', container, '--entrypoint', 'node', image, '-e', probe], None), + ('build', ['docker', '--context', 'default', 'build', '--no-cache', '--progress=plain', '-'], + 'FROM ' + image + '\nRUN node -e ' + "'" + probe.replace("'", "'\"'\"'") + "'\n"), + ] + failed = False + for label, command, dockerfile in commands: + print('network-probe context=' + label + ' status=started', flush=True) + try: + result = subprocess.run(command, input=dockerfile, text=True, timeout=55) + status = result.returncode + except subprocess.TimeoutExpired: + status = 124 + if label == 'container': + subprocess.run(['docker', '--context', 'default', 'rm', '--force', container], timeout=10, check=True) + print('network-probe context=' + label + ' exit=' + str(status), flush=True) + failed = failed or status != 0 + raise SystemExit(int(failed)) + PYTHON - name: Register owned project before provisioning run: | python3 scripts/ci-ownership.py init "$CI_OWNERSHIP_MANIFEST" @@ -151,6 +217,10 @@ jobs: test "$DOCKER_CONTEXT" = default docker --context default compose version deno --version + - name: Diagnose hosted package network + continue-on-error: true + timeout-minutes: 3 + run: *package-network-diagnostics - name: Register owned project before provisioning run: | python3 scripts/ci-ownership.py init "$CI_OWNERSHIP_MANIFEST" @@ -199,6 +269,10 @@ jobs: test "$DOCKER_CONTEXT" = default docker --context default compose version deno --version + - name: Diagnose hosted package network + continue-on-error: true + timeout-minutes: 3 + run: *package-network-diagnostics - name: Register owned project before provisioning run: | python3 scripts/ci-ownership.py init "$CI_OWNERSHIP_MANIFEST" diff --git a/tests/support/ci-lifecycle.test.py b/tests/support/ci-lifecycle.test.py index 942b5d8b..5790e474 100644 --- a/tests/support/ci-lifecycle.test.py +++ b/tests/support/ci-lifecycle.test.py @@ -48,6 +48,54 @@ def guard(self, **environment): "guard", str(self.root / "tests/support/rootless-docker.sh")], env={**self.env, **environment}, capture_output=True, timeout=15) + def test_hosted_network_diagnostics_are_bounded_and_payload_free(self): + from unittest.mock import patch + import contextlib + import io + import textwrap + + source = Path(__file__).resolve().parents[2] + workflow = (source / ".github/workflows/ci.yml").read_text() + block = workflow.split("run: &package-network-diagnostics |\n", 1)[1].split(" - name:", 1)[0] + shell = textwrap.dedent(block) + syntax = subprocess.run(["bash", "-n"], input=shell, text=True, capture_output=True) + self.assertEqual(syntax.returncode, 0, syntax.stderr) + script = shell.split("python3 - <<'PYTHON'\n", 1)[1].rsplit("PYTHON", 1)[0] + self.assertEqual(workflow.count("run: *package-network-diagnostics"), 2) + for failed_context in [None, "runner", "container", "build", "timeout"]: + calls = [] + + def run_probe(command, **options): + if command[3:5] == ["rm", "--force"]: + self.assertTrue(command[-1].startswith("hypercerts-entryway-network-probe-")) + return subprocess.CompletedProcess(command, 0) + calls.append((command, options)) + context = ["runner", "container", "build"][len(calls) - 1] + if failed_context == "timeout" and context == "container": + raise subprocess.TimeoutExpired(command, options["timeout"]) + return subprocess.CompletedProcess(command, 7 if context == failed_context else 0) + + output = io.StringIO() + with patch("subprocess.run", side_effect=run_probe), contextlib.redirect_stdout(output): + with self.assertRaises(SystemExit) as result: + exec(compile(script, "hosted-network-diagnostics", "exec"), {}) + self.assertEqual(result.exception.code, int(failed_context is not None)) + self.assertEqual(len(calls), 3) + for command, options in calls: + self.assertEqual(options["timeout"], 55) + self.assertNotIn("--network=host", command) + self.assertNotIn("--dns", command) + self.assertIn("--rm", calls[1][0]) + self.assertIn("--no-cache", calls[2][0]) + dockerfile = calls[2][1]["input"] + self.assertTrue(dockerfile.startswith("FROM mcr.microsoft.com/playwright:v1.58.2-noble\nRUN node -e ")) + self.assertNotIn("process.env", dockerfile) + self.assertNotIn("rejectUnauthorized", dockerfile) + self.assertIn("method: 'HEAD'", calls[0][0][2]) + if failed_context == "timeout": + self.assertIn("context=container exit=124", output.getvalue()) + self.assertIn("context=build exit=", output.getvalue()) + def test_repeated_scoped_cleanup(self): for _ in range(2): self.assertEqual(self.ownership("cleanup", COMPOSE_PROFILES="unrelated").returncode, 0) From f05c06e032d5125a84d0bd8cd3db6fa938ee58e9 Mon Sep 17 00:00:00 2001 From: Evelyn Osman Date: Wed, 11 Nov 2026 17:06:30 +0100 Subject: [PATCH 13/13] fix: make recovery test workers deterministic and bounded Keep crash checkpoints alive until killed and collect complete failure output. Bound lease polling without treating timeout as lease expiry. --- .../incoming-arrival-reconciliation.test.mjs | 96 +++++++++++++++++-- tests/support/ci-lifecycle.test.py | 3 +- .../helpers/incoming-arrival-restart.mjs | 15 ++- 3 files changed, 102 insertions(+), 12 deletions(-) diff --git a/tests/contracts/incoming-arrival-reconciliation.test.mjs b/tests/contracts/incoming-arrival-reconciliation.test.mjs index dfd204ec..89fc1e8f 100644 --- a/tests/contracts/incoming-arrival-reconciliation.test.mjs +++ b/tests/contracts/incoming-arrival-reconciliation.test.mjs @@ -4,6 +4,7 @@ import { fork } from "node:child_process"; import { mkdtempSync, readFileSync, writeFileSync, rmSync } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; +import { runInNewContext } from "node:vm"; const helper = new URL( "../support/helpers/incoming-arrival-restart.mjs", @@ -33,7 +34,14 @@ const pendingCuts = new Set([ "tombstone", "uncertain", ]); -function worker(directory, phase, cut, kill = false, observationDelay = 0) { +function worker( + directory, + phase, + cut, + kill = false, + observationDelay = 0, + killDelay = 0, +) { return new Promise((resolve, reject) => { const child = fork( helper, @@ -44,23 +52,45 @@ function worker(directory, phase, cut, kill = false, observationDelay = 0) { ); let message; let stderr = ""; + let killTimer; const timer = setTimeout(() => { child.kill("SIGKILL"); reject(new Error(`WorkerTimeout:${phase}:${cut}`)); }, 20000); - child.stderr.on("data", (chunk) => { + const onStderr = (chunk) => { stderr += chunk; - }); - child.on("error", reject); - child.on("message", (value) => { + }; + child.stderr.on("data", onStderr); + const onError = (error) => { + clearTimeout(timer); + clearTimeout(killTimer); + reject(error); + }; + child.once("error", onError); + const onMessage = (value) => { message = value; if (kill) { assert.equal(value.boundary, cut); - child.kill("SIGKILL"); + killTimer = setTimeout(() => { + try { + assert.equal(child.exitCode, null); + assert.equal(child.signalCode, null); + process.kill(child.pid, 0); + assert.equal(child.kill("SIGKILL"), true); + } catch (error) { + child.kill("SIGKILL"); + reject(error); + } + }, killDelay); } - }); - child.on("exit", (code, signal) => { + }; + child.on("message", onMessage); + child.once("close", (code, signal) => { clearTimeout(timer); + clearTimeout(killTimer); + child.removeListener("error", onError); + child.removeListener("message", onMessage); + child.stderr.removeListener("data", onStderr); if ((kill && signal !== "SIGKILL") || (!kill && code !== 0)) return reject( new Error( @@ -73,6 +103,54 @@ function worker(directory, phase, cut, kill = false, observationDelay = 0) { }); }); } +test("lease polling requires database expiry and bounds a stalled clock", async (t) => { + const source = readFileSync(helper, "utf8"); + const polling = source.slice( + source.indexOf('if (phase !== "initial") {'), + source.indexOf("\ntry {"), + ); + for (const advancing of [false, true]) { + await t.test(advancing ? "advancing clock" : "stalled clock", async () => { + let reads = 0; + let waits = 0; + let elapsed = 0; + const context = { + phase: "resume", + load: () => ({ crashLeaseExpiresAt: 100 }), + db: { + databaseTime: async () => { + reads++; + return advancing && reads === 3 ? 101 : 100; + }, + }, + performance: { now: () => elapsed }, + setTimeout: (resolve, milliseconds) => { + assert.equal(milliseconds, 25); + waits++; + elapsed += milliseconds; + resolve(); + }, + resumed: false, + }; + const result = runInNewContext( + `(async () => { ${polling}\nresumed = true; })()`, + context, + ); + if (advancing) { + await result; + assert.equal(context.resumed, true); + assert.equal(reads, 3); + assert.equal(waits, 2); + } else { + await assert.rejects(result, { message: "FixtureLeaseClockTimeout" }); + assert.equal(context.resumed, false); + assert.equal(reads, 400); + assert.equal(waits, 400); + assert.equal(elapsed, 10000); + } + }); + } +}); for (const cut of [...cases, "divergent", "tombstone", "uncertain"]) { test( `fresh-process arrival reconciliation after ${cut}`, @@ -80,7 +158,7 @@ for (const cut of [...cases, "divergent", "tombstone", "uncertain"]) { async (t) => { const directory = mkdtempSync(join(tmpdir(), "incoming-restart-")); t.after(() => rmSync(directory, { recursive: true, force: true })); - const stopped = await worker(directory, "initial", cut, true); + const stopped = await worker(directory, "initial", cut, true, 0, 250); writeFileSync( join(directory, "stopped.json"), JSON.stringify({ diff --git a/tests/support/ci-lifecycle.test.py b/tests/support/ci-lifecycle.test.py index 5790e474..a6c13419 100644 --- a/tests/support/ci-lifecycle.test.py +++ b/tests/support/ci-lifecycle.test.py @@ -61,6 +61,7 @@ def test_hosted_network_diagnostics_are_bounded_and_payload_free(self): syntax = subprocess.run(["bash", "-n"], input=shell, text=True, capture_output=True) self.assertEqual(syntax.returncode, 0, syntax.stderr) script = shell.split("python3 - <<'PYTHON'\n", 1)[1].rsplit("PYTHON", 1)[0] + compiled = compile(script, "hosted-network-diagnostics", "exec") self.assertEqual(workflow.count("run: *package-network-diagnostics"), 2) for failed_context in [None, "runner", "container", "build", "timeout"]: calls = [] @@ -78,7 +79,7 @@ def run_probe(command, **options): output = io.StringIO() with patch("subprocess.run", side_effect=run_probe), contextlib.redirect_stdout(output): with self.assertRaises(SystemExit) as result: - exec(compile(script, "hosted-network-diagnostics", "exec"), {}) + exec(compiled, {}) self.assertEqual(result.exception.code, int(failed_context is not None)) self.assertEqual(len(calls), 3) for command, options in calls: diff --git a/tests/support/helpers/incoming-arrival-restart.mjs b/tests/support/helpers/incoming-arrival-restart.mjs index 72294689..f604b3b2 100644 --- a/tests/support/helpers/incoming-arrival-restart.mjs +++ b/tests/support/helpers/incoming-arrival-restart.mjs @@ -52,6 +52,8 @@ const stop = async (boundary) => { remote.crashLeaseExpiresAt = expires; }); } + assert.ok(process.channel); + process.channel.ref(); process.send({ boundary, pid: process.pid }); await new Promise(() => {}); }; @@ -377,8 +379,17 @@ const snapshot = async () => { // No persisted deadlines or fence checks are bypassed to make takeover possible. if (phase !== "initial") { const expires = load().crashLeaseExpiresAt; - while (expires && (await db.databaseTime()) <= expires) - await new Promise((resolve) => setTimeout(resolve, 25)); + const deadline = performance.now() + 10000; + let expired = !expires; + for ( + let poll = 0; + poll < 400 && !expired && performance.now() < deadline; + poll++ + ) { + expired = (await db.databaseTime()) > expires; + if (!expired) await new Promise((resolve) => setTimeout(resolve, 25)); + } + if (!expired) throw new Error("FixtureLeaseClockTimeout"); } try { if (phase === "initial") {