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/.changeset/incoming-handoff-provisioning.md b/.changeset/incoming-handoff-provisioning.md new file mode 100644 index 00000000..f5894377 --- /dev/null +++ b/.changeset/incoming-handoff-provisioning.md @@ -0,0 +1,62 @@ +--- +"hypercerts-entryway": minor +--- + +For maintainers assembling the still-dormant incoming flow, this adds 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. + +Dormant preparation now checks the destination browser session, origin/CSRF and +fresh OTP before reserving an enrolled destination. It validates the configured +PLC history and retains the exact signed predecessor and CID, including legacy +`create` identities. Existing rotation priority is preserved; the Entryway hot key +is added only within the protocol limit. This remains preparation evidence, not +source ownership or activation readiness. + +Dormant authenticated admission now verifies the source repository JWT's document +identity, controller, method, audience and replay identity, with a maximum +300-second lifetime. Handoff admission and signed public bytes commit together +before directory dispatch. Lost responses retain the existing isolation/drain +recovery requirement; saved-owner continuation reuses accepted bytes without a +new source credential after key cutover. Creation admission reuses registration's +real invitation producer atomically, without copying raw invite codes into incoming +journals. Supported creation fields are handle and optional DID, email and invite; +other stock optional fields are explicitly rejected. Dormant creation continuation +now uses the saved owner and admission without a new source JWT or arrival code. +It journals the exact destination move, observes and pauses the backend using +configured administrator credentials, and atomically binds the pending account +with invitation completion. Lost creation or pause responses still require +verified isolation/drain recovery. A published move without a backend stays +pending without blind creation or fresh key reservation. Public migration +qualification remains separate work. + +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/.changeset/incoming-signed-destination-move.md b/.changeset/incoming-signed-destination-move.md new file mode 100644 index 00000000..ad9ddfb8 --- /dev/null +++ b/.changeset/incoming-signed-destination-move.md @@ -0,0 +1,21 @@ +--- +"hypercerts-entryway": patch +--- + +For maintainers assembling dormant incoming migration, destination creation now +receives the signed PLC move rather than an unsigned variant. This fixes the +internal payload contract; it does not qualify full stock-PDS migration. + +Internal behavior before public wiring: + +- 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/.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/.github/workflows/ci.yml b/.github/workflows/ci.yml index c71d1edd..dca21f7f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -48,6 +48,8 @@ jobs: run: npm run build - name: test:unit run: npm run test:unit + - name: test:incoming-reconciliation + run: npm run test:incoming-reconciliation - name: test:incoming-helpers run: npm run test:incoming-helpers - name: test:ci-lifecycle @@ -77,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" @@ -149,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" @@ -197,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/docs/architecture.md b/docs/architecture.md index 2455ea39..cbc3a2e1 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 a4cb381a..4335318d 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 @@ -85,18 +85,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` @@ -410,6 +410,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 384e741c..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. @@ -60,14 +62,14 @@ preserve existing shared-email associations, and from internal fleet moves. The following stages describe observable account state, not database status values. -| Stage | Identity and hosting | Destination access | -| --- | --- | --- | -| 1. Arrival prepared | DID still points to the source; destination email, handle and repository key are reserved | Arrival authorization only; no account binding yet | -| 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 | +| Stage | Identity and hosting | Destination access | +| ------------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | +| 1. Arrival prepared | DID still points to the source; destination email, handle and repository key are reserved | Arrival authorization only; no account binding yet | +| 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 | 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 @@ -141,13 +142,13 @@ sequenceDiagram ### Participants -| 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 | -| 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 | +| Component | Responsibility | +| --------------- | ------------------------------------------------------------------------------------------------------------------ | +| Browser | Verify the destination email through OTP and hand arrival authorization to the tool | +| 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 | The migration tool follows an Entryway-specific journey through public APIs and unchanged PDS contracts. Compatibility depends on support for this sequence, not @@ -155,14 +156,14 @@ on a particular tool name or version. ## Admission proofs and credentials -| Proof or credential | Establishes | Does not establish | -| --- | --- | --- | -| Browser OTP/session | Destination login identity | Source DID or PLC authority | -| Operator invite code | Eligibility when invitations are configured | Email ownership or DID ownership | -| Arrival code | Access to one prepared destination arrival | Source DID authority by itself | -| Source service JWT | Incoming DID authorization for one Entryway method | Destination email ownership | -| Source PLC confirmation and signature | Authorization for the exact PLC handoff | Permission for every endpoint | -| Destination access/refresh credentials | Access to the admitted migration | Completion or ordinary active-account access | +| Proof or credential | Establishes | Does not establish | +| -------------------------------------- | -------------------------------------------------- | -------------------------------------------- | +| Browser OTP/session | Destination login identity | Source DID or PLC authority | +| Operator invite code | Eligibility when invitations are configured | Email ownership or DID ownership | +| Arrival code | Access to one prepared destination arrival | Source DID authority by itself | +| Source service JWT | Incoming DID authorization for one Entryway method | Destination email ownership | +| Source PLC confirmation and signature | Authorization for the exact PLC handoff | Permission for every endpoint | +| Destination access/refresh credentials | Access to the admitted migration | Completion or ordinary active-account access | ### Invitation policy @@ -298,20 +299,24 @@ The tool uses creation-response credentials rather than requiring a new destinat password. Entryway refreshes and recovers the tracked credentials. Access JWTs use the backend audience and scopes understood by stock PDS, not an invented scope. -| Request | Send to | -| --- | --- | -| Source exports and blob downloads | Explicit original source PDS | -| Repository imports, blob uploads and transfer status | Explicit selected destination PDS | -| Admission, credential recovery and guarded activation | Entryway | +| Request | Send to | +| ----------------------------------------------------- | --------------------------------- | +| Source exports and blob downloads | Explicit original source PDS | +| Repository imports, blob uploads and transfer status | Explicit selected destination PDS | +| Admission, credential recovery and guarded activation | Entryway | 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 @@ -395,7 +402,11 @@ checking for remote obligations and changed PLC state. Preparation persists the allocation intent before it asks the destination for a signing key, so an arrival that reached preparation already has a reservation row and cannot be released. Once publication is possible, observed or uncertain, the arrival and reservations remain -available for reconciliation. +available for reconciliation. The only safe local cancellation seam is an internal +pre-intent arrival with no persisted allocation or signed handoff. This is not an +abandonment endpoint for a prepared arrival. No remote-release or reversal procedure +is implemented here; operators retain the obligation and use only the documented +shared-operation recovery path, not deletion or an invented cleanup command. Deleting local state cannot remove published Entryway authority. Reversal requires an authorized PLC operation; it is not an expiry side effect. The @@ -415,19 +426,119 @@ and release of conflicting work. Recovery records retain public custody evidence and safe operation identifiers. Reports exclude OTPs, arrival codes, bearer tokens and private keys. +### Development: dormant preparation callable + +For contributors wiring the dormant incoming flow, `composeIncomingArrival` now +provides `prepareArrival(request, otp, {did, handle})` alongside admission. It loads +the existing normalized browser session, runs the existing origin/CSRF guard and +verifies a fresh destination OTP against that session's user ID and email. No +public preparation route is mounted. The configured PLC audit is cryptographically +validated and compared with the current head; the original signed modern operation +or legacy `create` encoding and its CID are retained unchanged. Normalization is +used only to inspect public facts. Preparation preserves the existing ordered +rotation authority and appends the Entryway hot key only when absent; invalid or +overfull lists fail rather than being reordered or truncated. + +The callable persists arrival authority and a pending `arrival:` ownership +checkpoint before allocation. The saved allocation intent precedes the fixed-PDS +reservation request, and its validated public result precedes the one-time code +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 design is accepted; activation implementation and +public exposure remain deferred. + +### Development: authenticated admission and saved continuation + +For contributors assembling incoming migration, the dormant composition also exposes: + +```text +admitIncoming(request, {operationId, method, body, presentation, arrivalCode}) +continueHandoff(request, operationId) +continueCreation(request, operationId) +``` + +These are internal callables, not mounted routes. Each loads the normalized verified +browser principal and checks origin/CSRF. Its saved user ID selects the arrival; +`claim.resource` is the separate `arrival:` ownership resource, never a user ID. +The same pending preparation ownership intent is reacquired and fenced before work. + +Fresh handoff bodies must be exactly `{operation}` with the signed object. Creation +admission supports stock `handle` plus optional `did`, `email` and `inviteCode`. +Omitted DID/email use the saved arrival; supplied values must match it. Handle case +and email whitespace/case normalize for comparison. Other stock optional fields +(`password`, `verificationCode`, `verificationPhone`, `recoveryKey`, `plcOp`) and +unknown fields are rejected, not stripped. Incoming admission does not implement +password registration, phone verification or caller-selected destination custody. +No caller digest is accepted. A version-1 server digest binds the saved tuple, +operation, method, DID and normalized semantic request, sorting object keys while +preserving array order. Invitation identity contributes a hash, not its raw code. + +Fresh source JWTs must verify against that DID document's unique `#atproto` method +and matching document ID/controller. Issuers may be the DID or its `#atproto` +fragment, not an arbitrary fragment. Audience, method, nonempty JTI, integer issued +and expiry times, positive lifetime of at most 300 seconds, unexpired status and +the existing 60-second future-issued clock allowance are checked. Only verified +issuer/JTI and the server digest enter replay storage. Valid public source history +is identity state, not ownership proof. + +The signed handoff is validated against saved predecessor, source facts and ordered +custody. Admission and immutable signed operation/CID commit together through the +same database before dispatch. Creation admission calls the existing real invitation +producer in that database transaction, passing its raw invite transiently. Existing +registration invitation inventory/reservation storage is unchanged; no raw invite, +arrival code or bearer is copied into new incoming durable DTOs or logs. + +`continueHandoff` uses the accepted admission and journal under live persisted +ownership, without another source JWT after expiry or repository-key cutover. +Publication uses generic `ownership.dispatch` and the configured PLC client. A lost +response remains an uncertain external attempt: trusted dispatcher isolation/drain +and recovery authorization are required before observe/retry. Retries submit only +journaled signed bytes. Publication is recorded only when validated directory +history and the current signed head agree on that exact CID; changed heads are +not caller-authorized replacements. + +For contributors continuing an admitted creation, `continueCreation` now provisions +from the saved browser owner and accepted creation admission. It does not require +another source JWT or arrival code. It validates the saved signed handoff and the +configured canonical head, signs the actual destination handle, endpoint and reserved +repository key, and persists the exact signed move before ordinary PDS creation. +Retries reuse that move rather than signing another. Only the exact saved handoff +or saved move is a permitted canonical head; an unrelated descendant stays pending. + +Destination observation uses configured administrator credentials with +`com.atproto.admin.getAccountInfo`, validating the returned DID, handle and timestamps. +Only an authenticated `NotFound` error means absent; malformed responses and transport +failures do not authorize creation. A published move without a backend remains pending, +without fresh reservation or blind creation. An existing backend is observed and paused +with `com.atproto.admin.updateSubjectStatus` using `repoRef` and `deactivated.applied` +set to true, not an account token. Generic creation and pause attempts are associated +under the persisted arrival resource and live fence. Lost responses still require +isolation/drain approval before observation can settle the acknowledged receipt. +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, activation implementation and public migration qualification remain +deferred. + ## Contract qualification gates for implementers -These are delivery contracts for implementers, not implemented APIs. Where a contract -names a callable signature, no such callable exists in the repository yet; the owning -plan must produce it. Where this guide says a behavior is qualified, that means a -bounded committed test observed the stated stock behavior. It does not mean Entryway -exposes, accepts or gates it. +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–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 @@ -438,15 +549,15 @@ separately pinned 0.5.34 image. No contract may treat the two as interchangeable Contracts below cite existing repository policy rather than inventing limits. A consumer must use these named producers, not restate the numbers. -| Policy | Existing producer | Limit | -| --- | --- | --- | -| Destination OTP proof | `src/authentication/better-auth.mjs:22-27` | Eight digits, 600-second code lifetime, five attempts, digest-only storage | -| Extra challenge proof and budget | `src/accounts/challenges.mjs:22-29,36-45` | Default five requests per 600-second bucket per purpose and subject; code digest expires after 600 seconds | -| Login rate limit | `src/features/email-login/xrpc-routes.mjs:28` | 60 requests per IP | -| Signup and create rate limits | `src/features/account-registration/xrpc-routes.mjs:61,68` | 30 requests per IP each | -| Reservation rate limit | `src/plc/xrpc-routes.mjs:7` | 30 requests per IP | -| Password-reset rate limit | `src/features/account-recovery/xrpc-routes.mjs:7` | 30 requests per IP | -| Pending-operation block | `src/accounts/primitives.mjs:78-87` | 409 `MigrationPending` while any migration is not complete | +| Policy | Existing producer | Limit | +| -------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | +| Destination OTP proof | `src/authentication/better-auth.mjs:22-27` | Eight digits, 600-second code lifetime, five attempts, digest-only storage | +| Extra challenge proof and budget | `src/accounts/challenges.mjs:22-29,36-45` | Default five requests per 600-second bucket per purpose and subject; code digest expires after 600 seconds | +| Login rate limit | `src/features/email-login/xrpc-routes.mjs:28` | 60 requests per IP | +| Signup and create rate limits | `src/features/account-registration/xrpc-routes.mjs:61,68` | 30 requests per IP each | +| Reservation rate limit | `src/plc/xrpc-routes.mjs:7` | 30 requests per IP | +| Password-reset rate limit | `src/features/account-recovery/xrpc-routes.mjs:7` | 30 requests per IP | +| Pending-operation block | `src/accounts/primitives.mjs:78-87` | 409 `MigrationPending` while any migration is not complete | The accepted 24-hour arrival code lifetime is a reservation lifetime for one arrival. It is not an OTP freshness window and does not extend any proof above. @@ -460,12 +571,12 @@ through the standard XRPC bodies. Proposed Entryway-only POST surfaces. These are Entryway extensions, not AT Protocol methods. They never accept or export browser cookies on behalf of a tool. -| Path | Request body | Response | -| --- | --- | --- | -| `/incoming/prepare` | `{did, handle}` | `{operationId, version, arrivalCode, expiresAt, entrywayDid, sourceEndpoint, destinationEndpoint, expectedPlcHead, handoff}` | -| `/incoming/renew` | `{operationId, expectedVersion}` | `{operationId, version, arrivalCode, expiresAt}` | -| `/incoming/cancel` | `{operationId, expectedVersion}` | `{operationId, version, state}` | -| `/incoming/recover` | `{operationId, expectedVersion}` | Standard tracked credential fields, only after C3 prerequisites | +| Path | Request body | Response | +| ------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| `/incoming/prepare` | `{did, handle}` | `{operationId, version, arrivalCode, expiresAt, entrywayDid, sourceEndpoint, destinationEndpoint, expectedPlcHead, handoff}` | +| `/incoming/renew` | `{operationId, expectedVersion}` | `{operationId, version, arrivalCode, expiresAt}` | +| `/incoming/cancel` | `{operationId, expectedVersion}` | `{operationId, version, state}` | +| `/incoming/recover` | `{operationId, expectedVersion}` | Standard tracked credential fields, only after C3 prerequisites | Authentication per surface: @@ -493,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 | -| Unknown arrival or verified principal does not own it | `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 | +| 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 | 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 @@ -571,7 +682,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: @@ -626,9 +739,9 @@ category. Account status values remain `provisioning`, `active`, `deactivated` a `deleted` as enforced at `src/accounts/rules.ts:19-39`; no new status value is added. Pending projection. `hasPendingExternalMigration` in -`src/database/drizzle/account-storage.ts` checks both incomplete migration -reservations and active incoming arrivals whose completion checkpoint is absent. -The richer arrival projection is owned by plan 009: +`src/database/drizzle/account-storage.ts` is true while either a migration +reservation is not complete or an incoming arrival for the DID is active. The richer projection is owned by +plan 009 and is implemented by arrival storage; public consumers remain deferred: ```text readArrivalAccess(did) -> {operationId, version, did, userId, pdsId, provisioned, @@ -687,9 +800,10 @@ recoverArrivalSession(principal, freshProof, arrivalId, expectedVersion) Rules: no issuance before observed provisioning, observed deactivation and saved-user binding. Token return follows the committed association and never precedes it. Existing refresh replay and revocation semantics remain: a replayed refresh -invalidates the family (`src/oauth/legacy-credentials.mjs:400-405`), and a family -bound to another PDS DID is rejected (`src/oauth/legacy-credentials.mjs:466-467`), -without revoking that family. +invalidates the family (`src/oauth/legacy-credentials.mjs:400-405`), and an access +credential whose DID, PDS audience or scope differs from its saved +family is rejected, not automatically revoked (`currentAccess` in +`src/oauth/legacy-credentials.mjs`). After cutover, recovery does not require a source-key JWT, and no contract may require one. @@ -706,20 +820,42 @@ 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. - -Historical qualification and its limits. An earlier bounded run, recorded as -`d29515b` in the original repair history rather than an ancestor of this stack, -reported the following stock source and inactive destination behaviors within its -explicit byte and phase budgets. These are historical observations, not a current -verification result or full migration qualification; reproof requires a fresh -managed sandbox run: +### 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 +budgets. Historical observations are not a current verification result or a full +migration qualification; reproof requires a fresh managed sandbox run: - Source CAR exports verified against the observed repository key, including a nonempty snapshot. Two export requests were started before a write was dispatched, @@ -733,21 +869,26 @@ 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 83ff2f03..3a87d46c 100644 --- a/docs/reuse-assessment.md +++ b/docs/reuse-assessment.md @@ -87,17 +87,49 @@ behavior rather than assuming full equivalence. The synthetic migration fixture and repository inventory comparison are reuse candidates, not public end-to-end qualification or proof of a historical source signature. -One bounded committed qualification run observed a real stock source CAR +Historical bounded stock-mechanism evidence observed a real stock source CAR verification, a nonempty snapshot, two export requests started before a write was 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 whose callables the downstream plans must still produce; see the +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 70b96318..3bdad0f9 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -48,7 +48,7 @@ and requires no host dependency install: | `./tests/local.sh resilience-profiles` | Run all three fresh deployment profiles and require complete bounded receipts; see [profile contract](deployment-profiles.md) | | `./tests/local.sh contracts` | Run imported contract scenarios in the test container after up | | `./tests/local.sh browser` | Run browser scenarios after up | -| `./tests/local.sh incoming-public-mechanisms` | Bounded stock public-mechanism contract test after up: standalone signup, Mailpit, PLC signing, inactive destination and reservation; 12 offline plus 5 live cases, not a migration qualification | +| `./tests/local.sh incoming-public-mechanisms` | Bounded stock public-mechanism contract test after up: standalone signup, Mailpit, PLC signing, inactive destination and reservation; offline checks plus live-gated cases, not a migration qualification | | `./tests/local.sh migration` | Fresh synthetic external-source migration, including two Entryway restarts | | `./tests/local.sh migration-resume` | Resume a reviewed interrupted fixture; inspect state before using | | `./tests/local.sh reverify` | Check an already completed migration fixture | @@ -100,11 +100,10 @@ read its recipient-bound message from Mailpit, use the token for public signing, observe the inactive destination and reservation behavior. The controller applies the repository-owned SMTP overlay to pds3 after startup. -Case counts and what they mean. One live-gated test runs two further subcases, so a -full opt-in run reports more cases than the file declares. The file declares fifteen -top-level tests: twelve offline and three live-gated. A full opt-in run reports 17 -cases, which is 12 offline plus 5 live. Only those 5 live cases form the public -qualification. +For contributors validating this phase, offline request-boundary checks and +live-gated stock-mechanism cases are separate evidence. A live-gated test may add +subcases, so report the executed runner's counts rather than treating a historical +count as a qualification. Negative controls alone do not prove a complete migration. `tests/local.sh incoming-public-mechanisms` always exports `INCOMING_PUBLIC_MECHANISMS=1` for the container, so unsetting the variable does not @@ -115,20 +114,44 @@ env -u INCOMING_PUBLIC_MECHANISMS -u INCOMING_ACCESS_PATH node --test \ tests/contracts/incoming-public-mechanisms.test.mjs ``` -That run reports the three live-gated tests skipped; those skips are not -qualification. At the time of writing, that native run reports 12 passed and 3 -skipped, which is the offline subset only. A live count is a claim about a sandbox run -and must not be reported from this document. +That run skips the live-gated tests; those skips are not qualification. Setting +`INCOMING_PUBLIC_MECHANISMS=0` still opts in because the gate tests presence; unset +it as shown. Report live results only from an executed managed sandbox run. The offline cases cover the managed request boundary and phase budgets. They do not 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 whose callables the downstream plans must still produce. +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 +source accounts with different source and destination handles, obtains source +service credentials and Mailpit-confirmed PLC signatures through public APIs, +and calls the internal preparation/admission/provisioning composition. Destination +browser proof uses the real Better Auth and mail producers; no identity or arrival +rows are seeded. The test asserts the saved signed move matches the directory +head, administrator inspection and deactivation succeed before binding, and the +destination remains inactive and bound-pending without repeated creation. +Applied-but-lost creation and deactivation controls first assert that automatic +retry stays blocked and the owner remains unbound. After the disposable dispatcher +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 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. @@ -249,6 +272,7 @@ npm run test:architecture npm run schema:check npm run build npm run test:unit +npm run test:incoming-reconciliation npm run test:ci-lifecycle ``` @@ -309,20 +333,49 @@ profile controllers are not filtered a second time. Raw reports are never upload private reports locally for detailed failures. Lifecycle fixtures use fake Docker natively; they do not establish hosted-runner compatibility. -### Development: native incoming helper checks +### Development: native incoming checks -Contributors changing incoming test infrastructure run the stock mail poller, -managed I/O helper and access-projection tests explicitly: +Contributors changing incoming test infrastructure run the same stock mail poller +used by the live phase, its managed I/O helper and the access-projection tests: ```sh npm run test:incoming-helpers +npm run build +npm run test:unit +npm run test:incoming-reconciliation +npm run test:ci-lifecycle ``` -This script runs `tests/support/helpers/stock-plc-mailpit.test.mjs`, -`tests/support/helpers/incoming-public-io.test.mjs` and -`tests/atmosphere/project-incoming-access.test.mjs`. Native CI runs the script in -its own step. Contract discovery does not include these helper files, and the -live stock-mechanism suite is not part of the native unit allowlist. +The explicit helper script covers `stock-plc-mailpit.test.mjs`, +`incoming-public-io.test.mjs` and `tests/atmosphere/project-incoming-access.test.mjs`. +The native CI checks job runs it separately: helper files are not contract-discovered. +The unit allowlist includes incoming storage, admission, handoff and composition. +The separate native CI script `test:incoming-reconciliation` runs fresh-process +reconciliation with normal Node isolation: the shared unit runner uses +`--test-isolation=none`, which forked workers inherit and cannot use. +Reconciliation invokes its child-worker fixture; +that fixture is not separately discovered or executed twice. No live stock test is +added to the native unit allowlist. + +PostgreSQL cases skipped unless `CONTRACT_DATABASE_BACKEND=postgresql` are an outstanding +managed validation gate, not a native pass. For the final managed phase, prepare +and start an owned sandbox, run `./tests/local.sh database-dialects`, then run the +incoming storage/admission/composition contracts inside its managed +test container with `CONTRACT_DATABASE_BACKEND=postgresql` and that sandbox's +`CONTRACT_DATABASE_URL` supplied through the managed environment. The restart +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 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/package.json b/package.json index c9865703..637b629e 100644 --- a/package.json +++ b/package.json @@ -30,6 +30,7 @@ "changeset": "changeset", "changeset:check": "changeset status", "version-packages": "changeset version && npm install --package-lock-only --ignore-scripts --offline --no-audit --no-fund", + "test:incoming-reconciliation": "node --test tests/contracts/incoming-arrival-reconciliation.test.mjs", "test:incoming-helpers": "node --test tests/support/helpers/stock-plc-mailpit.test.mjs tests/support/helpers/incoming-public-io.test.mjs tests/atmosphere/project-incoming-access.test.mjs", "test:ci-lifecycle": "python3 tests/support/ci-lifecycle.test.py" }, diff --git a/src/compose-incoming-arrival.mjs b/src/compose-incoming-arrival.mjs new file mode 100644 index 00000000..003b1a4e --- /dev/null +++ b/src/compose-incoming-arrival.mjs @@ -0,0 +1,182 @@ +import { createDurableArrivalProvisioning } from "./features/external-migration/provision-arrival.js"; +import { createOperationOwnershipStore } from "./database/drizzle/operation-ownership.js"; +import { DomainError } from "./accounts/errors.js"; +import { createArrivalAdmission } from "./database/arrival-admission.js"; +import { createInvites } from "./features/account-registration/invites.mjs"; +import { createIncomingPreparation } from "./features/external-migration/prepare-arrival.js"; +import { createProtocolChallenges } from "./accounts/challenges.mjs"; +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, + arrivals, + config, + accounts, + authentication, + browserFlow, +}) { + const invitation = await createInvites({ db, config, accounts }); + const { rateLimit } = await createProtocolChallenges({ + db, + config, + accounts, + }); + const { choosePds } = await createPdsAccountClient({ config, accounts }); + const prepareArrival = createIncomingPreparation({ + arrivals, + ownership: accounts.ownership, + transact: (operation) => db.transact(operation), + authentication, + checkCsrf: browserFlow.checkCsrf, + loadBrowser: browserFlow.loadBrowser, + rateLimit, + choosePds, + plcClient: accounts.plcClient, + entrywayKey: accounts.plcSigner.publicKey(), + entrywayDid: config.serviceDid, + reserveSigningKey: ({ did, pdsId, endpoint }) => { + const pds = choosePds(pdsId); + if (pds.url !== endpoint) throw new Error("Arrival placement changed"); + return new ArrivalPdsClient({ + endpoint, + did, + pdsDid: pds.did, + issuer: config.serviceDid, + jwtJwk: config.jwtJwk, + }).reserveSigningKey(did); + }, + }); + const admission = createArrivalAdmission({ db, arrivals, invitation }); + const authenticated = createAuthenticatedArrival({ + arrivals, + ownership: accounts.ownership, + transact: (work) => db.transact(work), + admitCreation: admission.admitCreation, + provision: createDurableArrivalProvisioning({ + arrivals, + ownership: accounts.ownership, + receipts: createOperationOwnershipStore(db), + client: accounts.plcClient, + signer: accounts.plcSigner, + bindPending: admission.bindPending, + backend: (saved) => { + const pds = choosePds(saved.pdsId); + if (pds.url !== saved.endpoint) + throw new Error("Arrival placement changed"); + const transport = new ArrivalPdsClient({ + endpoint: saved.endpoint, + did: saved.did, + pdsDid: pds.did, + issuer: config.serviceDid, + jwtJwk: config.jwtJwk, + }); + const authorization = () => + `Basic ${Buffer.from(`admin:${pds.adminPassword}`).toString("base64")}`; + return { + inspect: () => transport.getAccountInfo(authorization), + create: (operation) => + transport.createAccount({ + did: saved.did, + handle: saved.handle, + operation, + }), + pause: () => transport.pauseAccount(authorization), + }; + }, + }), + verify: createIncomingAuthorization({ + serviceDid: config.serviceDid, + readDirectory: (did) => accounts.plcClient.getDocument(did), + }), + client: accounts.plcClient, + }); + // Dormant internal callables: browser authentication supplies the saved user, + // never claim.resource or a user ID from the request body. + const savedUser = async (request) => { + const browser = await browserFlow.loadBrowser(request); + browserFlow.checkCsrf(request, browser); + const principal = await authentication.requireSession(request); + if (!principal?.emailVerified) + throw new DomainError( + "AccountMismatch", + 403, + "A verified saved browser owner is required", + ); + return principal.userId; + }; + return { + ...admission, + prepareArrival, + admitIncoming: async (request, input) => + authenticated.admit({ + ...input, + userId: await savedUser(request), + }), + // Internal recovery selects existing continuations from durable admission, + // never from the preparation response or a fresh source credential. + reconcileArrival: async (request, operationId) => { + const userId = await savedUser(request); + const aggregate = await arrivals.readArrivalAggregate( + operationId, + userId, + ); + if (!aggregate || aggregate.arrival.cancelledAt !== null) + throw new DomainError("AccountNotFound", 404, "Arrival not found"); + if ( + 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", + ) + ) + await authenticated.continueHandoff({ operationId, userId }); + // Missing reservation responses and creation admission cannot be invented. + // In particular, recovery must not reserve another repository key. + return { state: "pending", operationId }; + }, + continueCreation: async (request, operationId) => + authenticated.continueCreation({ + operationId, + userId: await savedUser(request), + }), + continueHandoff: async (request, operationId) => + authenticated.continueHandoff({ + operationId, + userId: await savedUser(request), + }), + }; +} diff --git a/src/database/arrival-admission.ts b/src/database/arrival-admission.ts new file mode 100644 index 00000000..634880cd --- /dev/null +++ b/src/database/arrival-admission.ts @@ -0,0 +1,99 @@ +import { DomainError } from "../accounts/errors.js"; +import type { + ArrivalAdmissionProof, + ArrivalReplayFacts, +} from "../features/external-migration/arrival-types.js"; +import type { DatabaseExecutor } from "./executor.js"; +import type { ArrivalTransactor } from "./migration-journal.port.js"; +import type { OperationClaim } from "./operation-ownership.port.js"; + +export function createArrivalAdmission({ + db, + arrivals, + invitation, +}: { + readonly db: DatabaseExecutor; + readonly arrivals: ArrivalTransactor; + readonly invitation: { + reserveInvite(code: unknown, email: string): Promise; + completeInvite(account: { email: string; did: string }): Promise; + }; +}) { + return { + async admitCreation( + owner: OperationClaim, + expectedVersion: number, + input: { + readonly ownerUserId: string; + readonly facts: ArrivalReplayFacts; + readonly proof: ArrivalAdmissionProof; + readonly inviteCode: unknown; + }, + ) { + return db.transact(async () => + db.withOperationFence(owner, async () => { + await db.assertOperationFence(owner); + const aggregate = await arrivals.readArrivalAggregate( + input.facts.operationId, + input.ownerUserId, + ); + if (!aggregate) + throw new DomainError("AccountNotFound", 404, "Arrival not found"); + if (input.facts.method !== "com.atproto.server.createAccount") + throw new DomainError( + "AccountMismatch", + 403, + "Creation scope is required", + ); + const accepted = aggregate.admissions.some( + (item) => item.method === input.facts.method, + ); + const result = await arrivals.recordArrivalReplay( + owner, + expectedVersion, + input.facts, + input.proof, + ); + if (!accepted) + await invitation.reserveInvite( + input.inviteCode, + aggregate.arrival.email, + ); + return result; + }), + ); + }, + async bindPending( + input: Parameters[0], + ) { + return db.transact(async () => + db.withOperationFence(input.owner, async () => { + await db.assertOperationFence(input.owner); + const aggregate = await arrivals.readArrivalAggregate( + input.operationId, + input.userId, + ); + if ( + !aggregate || + aggregate.arrival.did !== input.did || + !aggregate.admissions.some( + (item) => item.method === "com.atproto.server.createAccount", + ) + ) + throw new DomainError( + "AccountMismatch", + 403, + "An admitted saved destination owner is required", + ); + const result = await arrivals.bindProvisionedArrival(input); + if (result.kind === "applied") + await invitation.completeInvite({ + email: aggregate.arrival.email, + did: aggregate.arrival.did, + }); + return result; + }), + ); + }, + }; +} diff --git a/src/features/account-registration/invites.mjs b/src/features/account-registration/invites.mjs index 797a72bf..c97e8fd0 100644 --- a/src/features/account-registration/invites.mjs +++ b/src/features/account-registration/invites.mjs @@ -62,6 +62,7 @@ export async function createInvites({ db, config, accounts }) { return; } if (!code && !config.inviteCodeRequired) return; + if (!code) fail("InvalidInviteCode", "An invite code is required"); const row = await db.get("entryway:invites", code); if (!row || row.disabled) fail("InvalidInviteCode", "Invite code is invalid"); 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..d718247e --- /dev/null +++ b/src/features/external-migration/arrival-lifecycle.test.mjs @@ -0,0 +1,452 @@ +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 { 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"; + +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 code = generateArrivalCode(); + const arrival = await arrivals.createArrival({ + operationId: "op-1", + did, + userId, + email, + handle, + pdsId: "pds1", + endpoint, + sourcePlcHead: String(await cidForCbor(authority.predecessor)), + sourcePredecessor: authority.predecessor, + source: authority.sourceFacts, + approvedRotationKeys: authority.approved, + 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, + }); + await ownership.bindResource(claim, `arrival:${did}`); + return { db, arrivals, ownership, authority, 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, + })}`; + for (const overrides of [ + { exp: now + 365 * 86400 }, + { iat: now + 61, exp: now + 180 }, + { iss: `${did}#arbitrary` }, + { keypair: await Secp256k1Keypair.create() }, + ]) + await assert.rejects( + verify({ + presentation: await token(overrides), + method: "com.atproto.server.createAccount", + operationId: "op-1", + requestDigest: hash("d"), + expectedDid: did, + }), + { code: "AccountMismatch" }, + ); + for (const mutation of ["id", "controller", "method"]) { + const document = { + id: did, + verificationMethod: [ + { + id: `${did}#atproto`, + controller: did, + type: "EcdsaSecp256k1VerificationKey2019", + publicKeyMultibase: authority.source.did(), + }, + ], + }; + if (mutation === "id") document.id = `did:plc:${"b".repeat(24)}`; + if (mutation === "controller") + document.verificationMethod[0].controller = `did:plc:${"b".repeat(24)}`; + if (mutation === "method") + document.verificationMethod[0].id = `${did}#other`; + const invalidDocument = createIncomingAuthorization({ + serviceDid, + readDirectory: async () => document, + }); + await assert.rejects( + invalidDocument({ + presentation: await token(), + method: "com.atproto.server.createAccount", + operationId: "op-1", + requestDigest: hash("d"), + expectedDid: did, + }), + { code: "AccountMismatch" }, + ); + } + const accepted = await verify({ + presentation: await token(), + method: "com.atproto.server.createAccount", + operationId: "op-1", + requestDigest: hash("d"), + expectedDid: did, + }); + assert.equal(accepted.replayFacts.credentialIssuer, did); + assert.equal(typeof accepted.replayFacts.credentialJti, "string"); + assert.deepEqual(accepted.replayFacts, { + credentialIssuer: did, + credentialJti: accepted.replayFacts.credentialJti, + 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 = await plc.addSignature( + { + ...authority.handoffFacts, + rotationKeys: [...authority.approved, fourth], + }, + authority.source, + ); + await assert.rejects( + validate({ operation: overfull, approvedRotationKeys: authority.approved }), + { 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 = await plc.addSignature( + { + ...authority.handoffFacts, + rotationKeys: [...authority.approved].reverse(), + }, + authority.source, + ); + await assert.rejects(validate({ operation: reordered }), { + code: "InvalidPlcOperation", + }); +}); diff --git a/src/features/external-migration/arrival-request.ts b/src/features/external-migration/arrival-request.ts new file mode 100644 index 00000000..32a2e563 --- /dev/null +++ b/src/features/external-migration/arrival-request.ts @@ -0,0 +1,126 @@ +import { createHash } from "node:crypto"; +import { DomainError } from "../../accounts/errors.js"; +import type { ArrivalRecord } from "./arrival-types.js"; +import { + incomingCreationMethod, + incomingHandoffMethod, + type IncomingMethod, +} from "./incoming-authorization.js"; + +const invalid = (): never => { + throw new DomainError( + "InvalidAccount", + 400, + "Unsupported incoming request facts", + ); +}; + +/** Incoming request identity uses sorted object keys, never reordered arrays. */ +export function canonicalArrivalValue(value: unknown): unknown { + if (value === null || typeof value === "string" || typeof value === "boolean") + return value; + if (typeof value === "number" && Number.isFinite(value)) return value; + if (Array.isArray(value)) return value.map(canonicalArrivalValue); + if ( + value && + typeof value === "object" && + Object.getPrototypeOf(value) === Object.prototype + ) + return Object.fromEntries( + Object.keys(value) + .sort((left, right) => (left < right ? -1 : left > right ? 1 : 0)) + .map((key) => [ + key, + canonicalArrivalValue((value as Record)[key]), + ]), + ); + return invalid(); +} + +/** Parse a fresh standard body. Secrets remain transient; only this server digest + * crosses admission. Password/phone proof and caller PLC creation are unsupported. */ +export function parseArrivalRequest( + saved: ArrivalRecord, + method: IncomingMethod, + body: unknown, +) { + if (!body || typeof body !== "object" || Array.isArray(body)) + return invalid(); + const fields = body as Record; + let semantic: unknown; + let operation: Record | undefined; + let inviteCode: string | undefined; + if (method === incomingHandoffMethod) { + if ( + Object.keys(fields).length !== 1 || + !fields.operation || + typeof fields.operation !== "object" || + Array.isArray(fields.operation) + ) + return invalid(); + operation = canonicalArrivalValue(fields.operation) as Record< + string, + unknown + >; + semantic = { operation }; + } else if (method === incomingCreationMethod) { + // Stock createAccount fields supported by incoming admission. Other stock + // optional fields are explicitly rejected, not silently discarded. + if ( + Object.keys(fields).some( + (key) => !["did", "email", "handle", "inviteCode"].includes(key), + ) + ) + return invalid(); + if ( + typeof fields.handle !== "string" || + fields.handle.toLowerCase() !== saved.handle.toLowerCase() + ) + return invalid(); + if (fields.did !== undefined && fields.did !== saved.did) return invalid(); + if ( + fields.email !== undefined && + (typeof fields.email !== "string" || + fields.email.trim().toLowerCase() !== saved.email) + ) + return invalid(); + if ( + fields.inviteCode !== undefined && + typeof fields.inviteCode !== "string" + ) + return invalid(); + inviteCode = fields.inviteCode as string | undefined; + semantic = { + did: saved.did, + email: saved.email, + handle: saved.handle.toLowerCase(), + inviteHash: + inviteCode === undefined + ? null + : createHash("sha256").update(inviteCode).digest("hex"), + }; + } else return invalid(); + const requestDigest = createHash("sha256") + .update( + JSON.stringify( + canonicalArrivalValue({ + version: 1, + operationId: saved.operationId, + method, + did: saved.did, + tuple: { + userId: saved.userId, + email: saved.email, + handle: saved.handle, + pdsId: saved.pdsId, + endpoint: saved.endpoint, + sourcePlcHead: saved.sourcePlcHead, + generation: saved.generation, + }, + semantic, + }), + ), + ) + .digest("hex"); + return { requestDigest, operation, inviteCode }; +} diff --git a/src/features/external-migration/incoming-authorization.ts b/src/features/external-migration/incoming-authorization.ts new file mode 100644 index 00000000..5eafa659 --- /dev/null +++ b/src/features/external-migration/incoming-authorization.ts @@ -0,0 +1,151 @@ +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 its #atproto method; 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 || (issuer !== did && issuer !== `${did}#atproto`)) + return rejected(); + const document = await readDirectory(did); + const methods = document.verificationMethod?.filter( + (method) => method.id === `${did}#atproto` || method.id === "#atproto", + ); + if ( + document.id !== did || + methods?.length !== 1 || + methods[0]?.controller !== did + ) + return rejected(); + 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; + let credentialIssuer: string; + let credentialJti: 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(); + credentialIssuer = issuer; + credentialJti = claims.jti; + 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 || + expiresAt - issuedAt > 300 || + 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, + credentialIssuer, + credentialJti, + }, + }; + }; +} + +export type VerifyIncomingAuthorization = ReturnType< + typeof createIncomingAuthorization +>; diff --git a/src/features/external-migration/prepare-arrival.ts b/src/features/external-migration/prepare-arrival.ts new file mode 100644 index 00000000..aa2fcf6d --- /dev/null +++ b/src/features/external-migration/prepare-arrival.ts @@ -0,0 +1,285 @@ +import { createHash, randomBytes } from "node:crypto"; +import { ensureValidHandle } from "@atproto/syntax"; +import type { + BrowserAuthentication, + BrowserPrincipal, + BrowserRequest, +} from "../../authentication/port.js"; +import type { createOperationOwnership } from "../../accounts/operation-ownership.js"; +import { incomingRotationKeys } from "../../plc/policy.js"; +import { readIncomingObservation } from "../../plc/incoming-observation.js"; +import type * as plc from "@did-plc/lib"; +import { HttpError } from "../../http/http-error.mjs"; +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 { ArrivalPreparationAuthority } from "./arrival-types.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 extends ArrivalPreparationAuthority { + 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); + }, + }; +} + +export function createIncomingPreparation({ + arrivals, + ownership, + transact, + authentication, + checkCsrf, + loadBrowser, + rateLimit, + choosePds, + plcClient, + entrywayKey, + entrywayDid, + reserveSigningKey, +}: { + arrivals: ArrivalTransactor; + ownership: ReturnType; + transact: (operation: () => Promise) => Promise; + authentication: BrowserAuthentication; + checkCsrf: (request: BrowserRequest, browser: unknown) => void; + loadBrowser: (request: BrowserRequest) => Promise; + rateLimit: (subject: string) => Promise; + choosePds: () => { id: string; url: string }; + plcClient: plc.Client; + entrywayKey: string; + entrywayDid: string; + reserveSigningKey: (request: ReservationRequest) => Promise; +}) { + const reservation = createArrivalPreparation({ arrivals, reserveSigningKey }); + return async function prepareArrival( + request: BrowserRequest, + otp: string, + input: { did: string; handle: string }, + ) { + const browser = await loadBrowser(request); + checkCsrf(request, browser); + const principal: BrowserPrincipal | null = + await authentication.requireSession(request); + const proofRequired = () => + new HttpError( + 403, + "ArrivalProofRequired", + "Verify the destination email again", + ); + if (!principal?.emailVerified || !otp) throw proofRequired(); + await rateLimit(`incoming-prepare:${principal.userId}`); + const proof = await authentication.verifySignInCode({ + email: principal.email, + otp, + }); + const identity = proof.ok ? proof.principal : null; + if ( + !identity?.emailVerified || + identity.userId !== principal.userId || + identity.email !== principal.email + ) + throw proofRequired(); + if (!/^did:plc:[a-z2-7]{24}$/.test(input.did)) + throw new HttpError(400, "InvalidRequest", "A PLC DID is required"); + ensureValidHandle(input.handle); + const pds = choosePds(); + return ownership.run( + `arrival:${input.did}`, + { + kind: "public-arrival", + request: { + did: input.did, + handle: input.handle, + userId: principal.userId, + }, + }, + async () => { + const claim = ownership.currentClaim; + if (!claim) + throw new DomainError( + "OperationLeaseLost", + 409, + "Arrival owner unavailable", + ); + const observed = await readIncomingObservation(plcClient, input.did); + const approvedRotationKeys = incomingRotationKeys( + observed.rotationKeys, + entrywayKey, + ); + const code = generateArrivalCode(); + // The pending admission and arrival share one commit: neither release + // nor lease takeover may discard ownership of a persisted arrival. + const saved = await transact(async () => { + const prepared = await arrivals.createArrival({ + operationId: claim.operationId, + did: input.did, + handle: input.handle, + userId: identity.userId, + email: identity.email, + pdsId: pds.id, + endpoint: pds.url, + sourcePredecessor: observed.sourcePredecessor, + sourcePlcHead: observed.sourcePlcHead, + source: observed.source, + approvedRotationKeys, + codeHash: code.hash, + codeExpiresAt: code.expiresAt, + }); + // A persisted code cannot be recovered or replaced by replaying prepare. + if (prepared.codeHash !== code.hash) return recoveryRequired(); + await ownership.checkpoint("arrival-prepared", { + operationId: prepared.operationId, + did: prepared.did, + pdsId: prepared.pdsId, + }); + return prepared; + }); + const reserved = await reservation.reserve(claim, saved.version, saved); + return { + operationId: saved.operationId, + version: reserved.version, + arrivalCode: code.code, + expiresAt: code.expiresAt, + entrywayDid, + sourceEndpoint: observed.source.services.atproto_pds!.endpoint, + destinationEndpoint: saved.endpoint, + expectedPlcHead: saved.sourcePlcHead, + handoff: { + ...observed.source, + rotationKeys: approvedRotationKeys, + prev: saved.sourcePlcHead, + type: "plc_operation", + }, + }; + }, + ); + }; +} + +/** 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..1958e30b --- /dev/null +++ b/src/features/external-migration/provision-arrival.ts @@ -0,0 +1,312 @@ +import { createHash } from "node:crypto"; +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 { incomingCreationMethod } from "./incoming-authorization.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"; +import type { Secp256k1MigrationPlcSigner } from "../../plc/signing.js"; +import * as Plc from "@did-plc/lib"; +import { validateIncomingHandoff } from "../../plc/policy.js"; +import { readIncomingObservation } from "../../plc/incoming-observation.js"; + +/** 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); +}; + +/** For internal composition: saved creation admission is the authority for every + * continuation. Network work never runs inside an arrival transaction. */ +export function createDurableArrivalProvisioning({ + arrivals, + ownership, + receipts, + client, + signer, + backend, + bindPending, +}: { + arrivals: ArrivalTransactor; + ownership: OperationOwnership; + receipts: Pick; + client: Plc.Client; + signer: Secp256k1MigrationPlcSigner; + backend: (saved: ArrivalRecord) => { + inspect(): Promise<{ + did: string; + handle: string; + deactivated: boolean; + } | null>; + create(operation: Record): Promise; + pause(): Promise; + }; + bindPending: ArrivalTransactor["bindProvisionedArrival"]; +}) { + return async (owner: OperationClaim, initial: ArrivalAggregate) => { + const saved = initial.arrival; + const read = async () => { + const value = await arrivals.readArrivalAggregate( + saved.operationId, + saved.userId, + ); + if (!value) + throw new DomainError("AccountNotFound", 404, "Arrival not found"); + return value; + }; + const accepted = initial.admissions.find( + (item) => item.method === incomingCreationMethod, + ); + if ( + !accepted || + accepted.userId !== saved.userId || + accepted.did !== saved.did || + accepted.generation !== saved.generation + ) + throw new DomainError( + "AccountMismatch", + 403, + "An accepted saved creation is required", + ); + if (initial.progress.boundAt !== null) + return { + state: "pending" as const, + operationId: saved.operationId, + version: saved.version, + }; + const handoff = initial.signedOperations.find( + (item) => item.kind === "handoff", + ); + if (!handoff || !saved.signingKey || initial.reservation?.uncertainReason) + return pending("The saved handoff and resolved reservation are required"); + await validateIncomingHandoff({ + operation: handoff.operation, + expectedPredecessor: saved.sourcePredecessor, + approvedRotationKeys: saved.approvedRotationKeys, + source: saved.source, + }); + if (String(await cidForCbor(handoff.operation)) !== handoff.cid) + return conflict("The saved handoff CID differs from its signed bytes"); + let move = initial.signedOperations.find( + (item) => item.kind === "destination-move", + ); + const directory = await readIncomingObservation(client, saved.did); + if ( + directory.sourcePlcHead !== handoff.cid && + directory.sourcePlcHead !== move?.cid + ) + return pending( + "Canonical identity is neither the saved handoff nor the exact saved move", + ); + const target = backend(saved); + const inspect = async () => { + const account = await target.inspect(); + if ( + account && + (account.did !== saved.did || account.handle !== saved.handle) + ) + return pending( + "The destination account identity differs from the saved arrival", + ); + return account; + }; + let account = await inspect(); + if (account && directory.sourcePlcHead !== move?.cid) + return pending( + "Destination presence does not prove publication of the exact saved move", + ); + if (!account && directory.sourcePlcHead === move?.cid) + return pending( + "The exact move is published without a backend; retain the reservation for recovery", + ); + if (!move) { + if (directory.sourcePlcHead !== handoff.cid) + return pending("The canonical handoff is not current"); + await signer.signArrivalMove( + { + handoffOperation: handoff.operation, + repositoryKey: saved.signingKey, + endpoint: saved.endpoint, + handle: saved.handle, + }, + async (operation, _facts, cid) => { + const current = await read(); + await arrivals.recordSignedOperation(owner, current.arrival.version, { + kind: "destination-move", + operationId: saved.operationId, + did: saved.did, + repositoryKey: saved.signingKey!, + operation: operation as unknown as Record, + cid, + }); + }, + ); + move = (await read()).signedOperations.find( + (item) => item.kind === "destination-move", + ); + } + if (!move) return pending("The exact signed move is not durable"); + const parsedMove = Plc.def.operation.parse(move.operation); + if ( + String(await cidForCbor(move.operation)) !== move.cid || + parsedMove.prev !== handoff.cid || + parsedMove.verificationMethods.atproto !== saved.signingKey || + parsedMove.services.atproto_pds?.endpoint !== saved.endpoint || + parsedMove.services.atproto_pds?.type !== "AtprotoPersonalDataServer" || + !parsedMove.alsoKnownAs.includes(`at://${saved.handle}`) || + JSON.stringify(parsedMove.rotationKeys) !== + JSON.stringify(saved.approvedRotationKeys) + ) + return conflict( + "The saved destination move differs from the accepted arrival", + ); + await Plc.assureValidSig([...saved.approvedRotationKeys], parsedMove); + const savedMove = move; + // Both independent public observations are required: actor presence alone + // cannot establish that stock creation published our durable signed move. + const creationApplied = async () => { + const observed = await readIncomingObservation(client, saved.did); + return ( + observed.sourcePlcHead === savedMove.cid && Boolean(await inspect()) + ); + }; + // dispatch owns isolation/drain approval. Association runs before the remote + // send; after observed recovery the same generic acknowledged receipt settles. + const dispatch = async ( + step: "incoming-creation" | "incoming-pause", + method: string, + send: () => Promise, + applied: () => Promise, + ) => { + const intent = { did: saved.did, cid: savedMove.cid, step }; + const descriptor = { + step, + target: saved.endpoint, + method, + intentDigest: createHash("sha256") + .update(JSON.stringify({ cid: savedMove.cid, did: saved.did, step })) + .digest("hex"), + }; + const associate = async () => { + const receipt = await receipts.readExternal(owner, descriptor); + if (!receipt) + return pending("The generic external receipt is unavailable"); + const current = await read(); + await arrivals.associateArrivalAttempt(owner, current.arrival.version, { + operationId: saved.operationId, + did: saved.did, + externalAttemptId: receipt.id, + step, + }); + return receipt; + }; + await ownership.dispatch( + { step, target: saved.endpoint, method, intent }, + { + send: async () => { + await associate(); + await send(); + if (!(await creationApplied()) || !(await applied())) + return pending( + "The destination effect is not canonically observed", + ); + return null; + }, + project: () => null, + resume: (value) => { + if (value !== null) + return conflict("Invalid saved destination receipt"); + return null; + }, + observe: async () => + (await applied()) + ? { state: "applied" as const, result: null } + : { state: "diverged" as const }, + }, + ); + if (!(await creationApplied()) || !(await applied())) + return pending("The destination effect is not canonically observed"); + const receipt = await associate(); + await arrivals.settleArrivalAttempt( + owner, + (await read()).arrival.version, + { + operationId: saved.operationId, + did: saved.did, + externalAttemptId: receipt.id, + step, + }, + ); + }; + // An unresolved generic write must be reconciled even if its remote effect is + // visible. Presence alone cannot bypass the operator isolation/drain gate. + const unresolvedCreation = initial.attempts.some( + (item) => item.reason === "external:incoming-creation", + ); + if ( + !account || + unresolvedCreation || + initial.progress.provisionedAt === null + ) { + await dispatch( + "incoming-creation", + incomingCreationMethod, + async () => { + const before = await inspect(); + if (before) { + if (!(await creationApplied())) + return pending("The exact saved move is not canonical"); + return; + } + const head = await readIncomingObservation(client, saved.did); + if (head.sourcePlcHead !== handoff.cid) + return pending("Creation requires the exact canonical handoff"); + await target.create(savedMove.operation); + }, + creationApplied, + ); + account = await inspect(); + } + if (!account || !(await creationApplied())) + return pending("Destination creation is unobserved"); + // Always visit the generic pause receipt, including a crash between its + // dispatch marker and association. An already-paused backend sends no write. + await dispatch( + "incoming-pause", + "com.atproto.admin.updateSubjectStatus", + async () => { + if (!(await creationApplied())) + return pending("The exact saved move is not canonical"); + if (!(await inspect())?.deactivated) await target.pause(); + }, + async () => (await inspect())?.deactivated === true, + ); + if (!(await creationApplied()) || !(await inspect())?.deactivated) + return pending("Destination deactivation is unobserved"); + const result = await bindPending({ + owner, + expectedVersion: (await read()).arrival.version, + operationId: saved.operationId, + did: saved.did, + userId: saved.userId, + email: saved.email, + handle: saved.handle, + pdsId: saved.pdsId, + placement: { provisioned: true, deactivationObserved: true }, + }); + if (result.kind === "reconciliation-required") + return pending("Pending binding requires recovery"); + return { + state: "pending" as const, + operationId: saved.operationId, + version: result.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..dd547639 --- /dev/null +++ b/src/features/external-migration/submit-handoff.ts @@ -0,0 +1,290 @@ +import type { ArrivalTransactor } from "../../database/migration-journal.port.js"; +import type { OperationClaim } from "../../database/operation-ownership.port.js"; +import { cidForCbor } from "@atproto/common"; +import type * as plc from "@did-plc/lib"; +import { DomainError } from "../../accounts/errors.js"; +import type { OperationOwnership } from "../../accounts/operation-ownership.js"; +import type { ArrivalAggregate } from "./arrival-types.js"; +import { + incomingHandoffMethod, + incomingCreationMethod, + type IncomingMethod, + type VerifyIncomingAuthorization, +} from "./incoming-authorization.js"; +import { parseArrivalRequest } from "./arrival-request.js"; +import { arrivalCodeHash } from "./prepare-arrival.js"; +import { validateIncomingHandoff } from "../../plc/policy.js"; +import { observeIncomingHandoff } from "../../plc/incoming-observation.js"; + +/** Internal composition consumes a trusted browser user separately from the + * operation resource. No caller observation or digest can authorize publication. */ +export function createAuthenticatedArrival({ + arrivals, + ownership, + transact, + verify, + client, + admitCreation, + provision, +}: { + arrivals: ArrivalTransactor; + ownership: OperationOwnership; + transact: (work: () => Promise) => Promise; + verify: VerifyIncomingAuthorization; + client: plc.Client; + provision?: ( + owner: OperationClaim, + aggregate: ArrivalAggregate, + ) => Promise; + admitCreation: ( + owner: OperationClaim, + version: number, + input: { + ownerUserId: string; + facts: import("./arrival-types.js").ArrivalReplayFacts; + proof: import("./arrival-types.js").ArrivalAdmissionProof; + inviteCode: unknown; + }, + ) => Promise; +}) { + const read = async ( + operationId: string, + userId: string, + ): Promise => { + const aggregate = await arrivals.readArrivalAggregate(operationId, userId); + if (!aggregate || aggregate.arrival.cancelledAt !== null) + throw new DomainError("AccountNotFound", 404, "Arrival not found"); + return aggregate; + }; + const underOwner = async ( + operationId: string, + userId: string, + work: (owner: OperationClaim, aggregate: ArrivalAggregate) => Promise, + ) => { + const initial = await read(operationId, userId); + const saved = initial.arrival; + return ownership.resumePending( + `arrival:${saved.did}`, + saved.operationId, + { + kind: "public-arrival", + request: { did: saved.did, handle: saved.handle, userId }, + }, + async () => { + const owner = ownership.currentClaim; + if (!owner) + throw new DomainError( + "OperationLeaseLost", + 409, + "Arrival owner unavailable", + ); + await ownership.assertActive(); + return work(owner, await read(operationId, userId)); + }, + ); + }; + const dispatchSaved = async ( + owner: OperationClaim, + aggregate: ArrivalAggregate, + ) => { + const saved = aggregate.arrival; + const admission = aggregate.admissions.find( + (item) => item.method === incomingHandoffMethod, + ); + const handoff = aggregate.signedOperations.find( + (item) => item.kind === "handoff", + ); + if ( + !admission || + !handoff || + admission.userId !== saved.userId || + admission.did !== saved.did || + admission.generation !== saved.generation + ) + throw new DomainError( + "AccountMismatch", + 403, + "An accepted saved handoff is required", + ); + const observe = () => + observeIncomingHandoff( + client, + saved.did, + handoff.cid, + saved.sourcePlcHead, + ); + await ownership.dispatch( + { + step: "incoming-handoff", + target: client.url, + method: incomingHandoffMethod, + intent: { did: saved.did, cid: handoff.cid }, + }, + { + send: async () => { + const before = await observe(); + if (before.canonical) return null; + if (before.diverged) + throw new DomainError( + "OperationRecoveryRequired", + 409, + "Canonical identity changed before handoff dispatch", + ); + await client.sendOperation( + saved.did, + handoff.operation as unknown as plc.Operation, + ); + return null; + }, + project: () => null, + resume: (value) => { + if (value !== null) + throw new DomainError( + "OperationConflict", + 409, + "Invalid handoff receipt", + ); + return null; + }, + observe: async () => { + const observed = await observe(); + return observed.canonical + ? { state: "applied" as const, result: null } + : { + state: observed.diverged + ? ("diverged" as const) + : ("replay-safe" as const), + }; + }, + }, + ); + const observed = await observe(); + if (!observed.canonical) + return { + state: observed.diverged + ? ("diverged" as const) + : ("uncertain" as const), + cid: handoff.cid, + }; + const current = await read(saved.operationId, saved.userId); + await arrivals.recordCanonicalHandoff(owner, current.arrival.version, { + operationId: saved.operationId, + did: saved.did, + cid: handoff.cid, + }); + return { state: "published" as const, cid: handoff.cid }; + }; + return { + async admit(input: { + operationId: string; + userId: string; + method: IncomingMethod; + body: unknown; + presentation: unknown; + arrivalCode: string; + }) { + return underOwner( + input.operationId, + input.userId, + async (owner, aggregate) => { + const saved = aggregate.arrival; + const parsed = parseArrivalRequest(saved, input.method, input.body); + const authorization = await verify({ + presentation: input.presentation, + method: input.method, + operationId: saved.operationId, + requestDigest: parsed.requestDigest, + expectedDid: saved.did, + }); + const proof = { + codeHash: arrivalCodeHash(input.arrivalCode), + codeGeneration: saved.codeGeneration, + }; + // Crypto and directory work finish before the physical admission transaction. + const signed = + input.method === incomingHandoffMethod + ? await validateIncomingHandoff({ + operation: parsed.operation, + expectedPredecessor: saved.sourcePredecessor, + approvedRotationKeys: saved.approvedRotationKeys, + source: saved.source, + }) + : null; + await transact(async () => { + if (input.method === incomingCreationMethod) { + await admitCreation(owner, saved.version, { + ownerUserId: input.userId, + facts: authorization.replayFacts, + proof, + inviteCode: parsed.inviteCode, + }); + } else { + await arrivals.recordArrivalReplay( + owner, + saved.version, + authorization.replayFacts, + proof, + ); + const current = await read(saved.operationId, input.userId); + await arrivals.recordSignedOperation( + owner, + current.arrival.version, + { + kind: "handoff", + operationId: saved.operationId, + did: saved.did, + operation: signed! as unknown as Record, + cid: String(await cidForCbor(signed)), + }, + ); + } + }); + if (input.method === incomingCreationMethod) + return { + state: "admitted" as const, + operationId: saved.operationId, + }; + return dispatchSaved( + owner, + await read(saved.operationId, input.userId), + ); + }, + ); + }, + /** Composition continues provisioning from accepted identity without source + * credentials; admission-only consumers retain the saved facts. */ + continueCreation(input: { operationId: string; userId: string }) { + return underOwner( + input.operationId, + input.userId, + async (owner, aggregate) => { + const accepted = aggregate.admissions.find( + (item) => item.method === incomingCreationMethod, + ); + if ( + !accepted || + accepted.userId !== aggregate.arrival.userId || + accepted.did !== aggregate.arrival.did || + accepted.generation !== aggregate.arrival.generation + ) + throw new DomainError( + "AccountMismatch", + 403, + "An accepted saved creation is required", + ); + if (provision) return provision(owner, aggregate); + return { + operationId: aggregate.arrival.operationId, + did: accepted.did, + requestDigest: accepted.requestDigest, + generation: accepted.generation, + }; + }, + ); + }, + /** Trusted saved-user recovery only; deliberately no public route or new JWT. */ + continueHandoff(input: { operationId: string; userId: string }) { + return underOwner(input.operationId, input.userId, dispatchSaved); + }, + }; +} diff --git a/src/pds/arrival-client.ts b/src/pds/arrival-client.ts new file mode 100644 index 00000000..1f634bf4 --- /dev/null +++ b/src/pds/arrival-client.ts @@ -0,0 +1,268 @@ +import { parseDidKey } from "@atproto/crypto"; +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. */ +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); + +/** Admin observations must not carry credentials, including in relatedRecords. + * Stock public additive fields remain allowed; this is not a content scanner. */ +function rejectAdminCredentials(value: unknown, method: string): void { + const remaining: unknown[] = [value]; + const credentialFields = new Set([ + "privatekey", + "privatekeys", + "accessjwt", + "refreshjwt", + "signingsecret", + ]); + while (remaining.length > 0) { + const current = remaining.pop(); + if (Array.isArray(current)) remaining.push(...current); + else if (isRecord(current)) + for (const [field, child] of Object.entries(current)) { + if (credentialFields.has(field.toLowerCase())) + throw invalidResponse(method); + remaining.push(child); + } + } +} + +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); + } +} + +/** 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<{ + sign: (did: string) => Promise; + }> + | undefined; + public constructor( + private readonly options: { + readonly endpoint: string; + readonly did: string; + readonly pdsDid: string; + readonly issuer: string; + readonly jwtJwk: JWK; + }, + ) { + for (const did of [options.pdsDid, options.issuer]) + if (!did.startsWith("did:")) + throw new TypeError( + "A destination service DID and issuer are required", + ); + } + /** Configured administrator credentials stay in composition's signing closure. */ + public async getAccountInfo( + authorization: () => string, + ): Promise<{ did: string; handle: string; deactivated: boolean } | null> { + const method = "com.atproto.admin.getAccountInfo"; + const url = this.#url(method); + url.searchParams.set("did", this.options.did); + const response = await fetch(url, { + headers: { authorization: authorization() }, + redirect: "error", + signal: AbortSignal.timeout(15_000), + }); + // Stock NotFound is an authenticated XRPC InvalidRequest (400), not + // necessarily HTTP 404. Neither transport errors nor other errors mean absent. + if (response.status === 400 || response.status === 404) { + const value: unknown = await response.json().catch(() => null); + if (isRecord(value) && value.error === "NotFound") return null; + throw upstreamFailure(method, response.status); + } + const value = await readPublicJson(response, method); + rejectAdminCredentials(value, method); + if ( + !isRecord(value) || + value.did !== this.options.did || + typeof value.handle !== "string" || + typeof value.indexedAt !== "string" || + !Number.isFinite(Date.parse(value.indexedAt)) || + (value.deactivatedAt !== undefined && + (typeof value.deactivatedAt !== "string" || + !Number.isFinite(Date.parse(value.deactivatedAt)))) + ) + throw invalidResponse(method); + return { + did: value.did, + handle: value.handle, + deactivated: value.deactivatedAt !== undefined, + }; + } + public async pauseAccount(authorization: () => string): Promise { + const method = "com.atproto.admin.updateSubjectStatus"; + const response = await fetch(this.#url(method), { + method: "POST", + headers: { + authorization: authorization(), + "content-type": "application/json", + }, + body: JSON.stringify({ + subject: { + $type: "com.atproto.admin.defs#repoRef", + did: this.options.did, + }, + deactivated: { applied: true }, + }), + redirect: "error", + signal: AbortSignal.timeout(30_000), + }); + rejectAdminCredentials(await readPublicJson(response, method), method); + } + #url(method: string): URL { + return new URL(`/xrpc/${method}`, this.options.endpoint); + } + /** 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 { + 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 + * 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.#accessToken(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.#accessToken(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/incoming-observation.ts b/src/plc/incoming-observation.ts new file mode 100644 index 00000000..1c0bdf80 --- /dev/null +++ b/src/plc/incoming-observation.ts @@ -0,0 +1,75 @@ +import { cidForCbor } from "@atproto/common"; +import * as plc from "@did-plc/lib"; +import { + validateAuditObservation, + readCustodyObservation, +} from "./observations.js"; + +/** Publication evidence is derived exclusively from validated configured history. */ +export async function observeIncomingHandoff( + client: plc.Client, + did: string, + cid: string, + predecessor: string, +) { + const observation = await readCustodyObservation(client, did); + const current = await client.getLastOp(did); + if (String(await cidForCbor(current)) !== observation.snapshot.headCid) + throw new PlcError( + "InvalidCustodyObservation", + "Directory head changed during observation", + ); + return { + canonical: + !observation.snapshot.tombstone && observation.snapshot.headCid === cid, + diverged: + observation.snapshot.tombstone || + ![cid, predecessor].includes(observation.snapshot.headCid), + tombstone: observation.snapshot.tombstone, + }; +} +import { PlcError } from "./errors.js"; +import { sameSignedOperation, validateUnsignedOperation } from "./policy.js"; + +/** For incoming-migration orchestration: retain the signed predecessor, not the + * unsigned custody projection. History establishes identity state, not ownership. */ +export async function readIncomingObservation(client: plc.Client, did: string) { + const audit = await client.getAuditableLog(did); + const observation = await validateAuditObservation( + did, + audit, + null, + client.url, + ); + const head = audit.filter((entry) => !entry.nullified).at(-1); + const current = await client.getLastOp(did); + if ( + !head || + observation.snapshot.tombstone || + head.operation.type === "plc_tombstone" || + String(await cidForCbor(current)) !== observation.snapshot.headCid + ) + throw new PlcError( + "InvalidCustodyObservation", + "The incoming identity head changed or is unavailable", + ); + const parsed = plc.def.compatibleOp.parse(head.operation); + if (!sameSignedOperation(parsed, head.operation)) + throw new PlcError( + "InvalidCustodyObservation", + "Unexpected signed operation fields", + ); + const predecessor = structuredClone(head.operation); + const { sig: _signature, ...unsigned } = plc.normalizeOp(predecessor); + const facts = validateUnsignedOperation(unsigned); + return { + sourcePredecessor: predecessor, + sourcePlcHead: head.cid, + rotationKeys: facts.rotationKeys, + source: { + services: facts.services, + verificationMethods: facts.verificationMethods, + alsoKnownAs: facts.alsoKnownAs, + }, + }; +} diff --git a/src/plc/signing.ts b/src/plc/signing.ts index c97e7aea..56ada7de 100644 --- a/src/plc/signing.ts +++ b/src/plc/signing.ts @@ -179,6 +179,64 @@ 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 signed operation and its CID before any dispatch. */ + public async signArrivalMove( + input: { + handoffOperation: unknown; + repositoryKey: string; + endpoint: string; + handle?: string; + }, + persist: ( + operation: Readonly, + facts: Readonly, + cid: string, + ) => Promise, + ): Promise<{ + operation: plc.Operation; + cid: string; + }> { + const previous = this.#previous(input.handoffOperation); + const facts = plc.normalizeOp(previous); + let saved: { operation: plc.Operation; cid: string } | undefined; + await this.#signAuthorizedUpdate( + previous, + { + verificationMethods: { + ...facts.verificationMethods, + atproto: input.repositoryKey, + }, + ...(input.handle + ? { + alsoKnownAs: [ + `at://${input.handle}`, + ...facts.alsoKnownAs.filter( + (alias) => !alias.startsWith("at://"), + ), + ], + } + : {}), + services: { + ...facts.services, + atproto_pds: { + type: "AtprotoPersonalDataServer", + endpoint: input.endpoint, + }, + }, + }, + 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); + }, + ); + if (!saved) throw new PlcError("InvalidPlcOperation", "Move not signed"); + return saved; + } public async signMigrationMove( input: { workflowId: string; diff --git a/tests/contracts/incoming-arrival-admission.test.mjs b/tests/contracts/incoming-arrival-admission.test.mjs new file mode 100644 index 00000000..e06e201e --- /dev/null +++ b/tests/contracts/incoming-arrival-admission.test.mjs @@ -0,0 +1,358 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { generateKeyPairSync } from "node:crypto"; +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 { Secp256k1Keypair } from "@atproto/crypto"; +import * as plc from "@did-plc/lib"; +import { cidForCbor } from "@atproto/common"; + +import { createArrivalAdmission } from "../../dist/src/database/arrival-admission.js"; +import { composeIncomingArrival } from "../../dist/src/compose-incoming-arrival.mjs"; +import { createInvites } from "../../dist/src/features/account-registration/invites.mjs"; +const hosts = [ + { id: "pds1", url: "https://pds1.example.test" }, + { id: "pds2", url: "https://pds2.example.test" }, +]; +const endpoint = hosts[0].url; +const did = "did:plc:arrivalstorage00000000000"; +const otherDid = "did:plc:arrivalother000000000000"; +const day = 86_400_000; + +const hash = (char) => char.repeat(64); +const persistedVersion = async (db, operationId) => + ( + await query(db, "SELECT version FROM arrivals WHERE operation_id = ?", [ + operationId, + ]) + )[0].version; +const sourceKey = await Secp256k1Keypair.create(); +const hotKey = await Secp256k1Keypair.create(); +const reservedKey = await Secp256k1Keypair.create(); +const rotationKeys = [sourceKey.did(), hotKey.did()]; +const sourcePredecessor = await plc.signOperation( + plc.formatAtprotoOp({ + signingKey: sourceKey.did(), + handle: "dest.entryway.test", + pds: endpoint, + rotationKeys: [sourceKey.did()], + prev: null, + }), + sourceKey, +); +const source = { + verificationMethods: sourcePredecessor.verificationMethods, + services: sourcePredecessor.services, + alsoKnownAs: sourcePredecessor.alsoKnownAs, +}; +const sourcePlcHead = String(await cidForCbor(sourcePredecessor)); +const preparationAuthority = { + sourcePredecessor, + source, + sourcePlcHead, + approvedRotationKeys: rotationKeys, +}; + +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: (email, value, purpose, userId) => + accounts.reserveEmail(email, value, purpose, userId), + reserveHandleClaim: (handle, value) => + accounts.reserveHandle(handle, value), + recordSavedUserBinding: (value, userId) => + db.insert( + "account_bindings", + { did: value, user_id: userId }, + { 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); + const claim = await ownership.acquire({ + resource: `arrival:${did}`, + kind: "public-arrival", + requestDigest: hash("c"), + workerId: "worker-1", + leaseMs: 120_000, + }); + const prepare = (overrides = {}) => + arrivals.createArrival({ + operationId: "op-1", + did, + userId: "user-a", + email: "dest@example.test", + handle: "dest.entryway.test", + pdsId: "pds1", + endpoint, + ...preparationAuthority, + codeHash: hash("a"), + codeExpiresAt: Date.now() + day, + ...overrides, + }); + const allocate = async ( + version, + operationId = "op-1", + operationDid = did, + key = reservedKey.did(), + ) => { + const intent = await arrivals.recordAllocationIntent(claim, version, { + operationId, + did: operationDid, + pdsId: "pds1", + endpoint, + }); + assert.deepEqual(intent, { kind: "applied", version: version + 1 }); + const result = await arrivals.recordReservationResult( + claim, + intent.version, + { + operationId, + did: operationDid, + pdsId: "pds1", + endpoint, + signingKey: key, + }, + ); + assert.deepEqual(result, { kind: "applied", version: version + 2 }); + return result.version; + }; + await verifiedUser(db, "user-a", "dest@example.test"); + return { db, accounts, arrivals, claim, prepare, allocate }; +} + +async function admissionFixture(required = true) { + const f = await fixture(); + const config = { + inviteCodeRequired: required, + pds: hosts, + jwtJwk: { + ...generateKeyPairSync("ec", { + namedCurve: "secp256k1", + }).privateKey.export({ format: "jwk" }), + alg: "ES256K", + }, + }; + const accounts = { + get: (value) => f.accounts.get(value), + plcSigner: { publicKey: () => hotKey.did() }, + }; + const invites = await createInvites({ db: f.db, config, accounts }); + const admission = await composeIncomingArrival({ + db: f.db, + arrivals: f.arrivals, + config, + accounts, + browserFlow: { checkCsrf() {}, loadBrowser() {} }, + }); + const arrival = await f.prepare(); + const facts = { + operationId: arrival.operationId, + did, + method: "com.atproto.server.createAccount", + requestDigest: hash("d"), + credentialIssuer: did, + credentialJti: "creation-jti", + }; + const proof = { codeHash: hash("a"), codeGeneration: 1 }; + const admit = (inviteCode, overrides = {}) => + admission.admitCreation(f.claim, 1, { + ownerUserId: "user-a", + facts, + proof, + inviteCode, + ...overrides, + }); + return { ...f, invites, admission, facts, proof, admit }; +} + +for (const required of [true, false]) { + test(`creation invitation policy (required: ${required}) and accepted retry`, async () => { + const f = await admissionFixture(required); + try { + await assert.rejects(f.admit("invalid"), { error: "InvalidInviteCode" }); + assert.equal((await f.db.read("arrival_replay")).length, 0); + if (required) + await assert.rejects(f.admit(undefined), { + error: "InvalidInviteCode", + }); + else { + await f.admit(undefined); + assert.equal((await f.db.read("arrival_replay")).length, 1); + return; + } + const { code } = await f.invites.createInviteCode({ useCount: 1 }); + await f.admit(code); + await f.admit(undefined, { + proof: { codeHash: "expired", codeGeneration: 0 }, + }); + assert.equal((await f.db.get("entryway:invites", code)).remaining, 0); + assert.equal((await f.db.read("arrival_replay")).length, 1); + assert.equal(await persistedVersion(f.db, "op-1"), 2); + await assert.rejects( + f.admit(code, { facts: { ...f.facts, requestDigest: hash("e") } }), + { code: "OperationConflict" }, + ); + } finally { + await f.db.close(); + } + }); +} + +for (const write of ["arrival_replay", "capacity", "reservation"]) { + test(`creation rolls back admission and invite after ${write} failure`, async () => { + const f = await admissionFixture(); + try { + const { code } = await f.invites.createInviteCode({ useCount: 1 }); + const originalInsert = f.db.insert; + const originalSet = f.db.set; + f.db.insert = async (...args) => { + await originalInsert(...args); + if (write === "arrival_replay" && args[0] === "arrival_replay") + throw Error("InjectedAdmissionFailure"); + }; + f.db.set = async (...args) => { + await originalSet(...args); + if ( + (write === "capacity" && args[0] === "entryway:invites") || + (write === "reservation" && + args[0] === "entryway:invite-reservations") + ) + throw Error("InjectedInviteFailure"); + }; + await assert.rejects(f.admit(code), /Injected/); + assert.equal((await f.db.read("arrival_replay")).length, 0); + assert.equal((await f.db.get("entryway:invites", code)).remaining, 1); + assert.equal( + await f.db.get("entryway:invite-reservations", "dest@example.test"), + null, + ); + assert.equal(await persistedVersion(f.db, "op-1"), 1); + } finally { + await f.db.close(); + } + }); +} + +test("pending binding and real invite completion roll back together, then complete once", async () => { + const f = await admissionFixture(); + try { + const { code } = await f.invites.createInviteCode({ useCount: 1 }); + await f.admit(code); + const version = await f.allocate(2); + const input = { + owner: f.claim, + expectedVersion: version, + operationId: "op-1", + did, + userId: "user-a", + email: "dest@example.test", + handle: "dest.entryway.test", + pdsId: "pds1", + placement: { provisioned: true, deactivationObserved: true }, + }; + const originalSet = f.db.set; + f.db.set = async (...args) => { + await originalSet(...args); + if (args[0] === "entryway:invite-reservations") + throw Error("InjectedCompletionFailure"); + }; + await assert.rejects( + f.admission.bindPending(input), + /InjectedCompletionFailure/, + ); + assert.equal(await f.accounts.getByDid(did), null); + assert.equal((await f.arrivals.readArrivalAccess(did)).bound, false); + assert.equal((await f.db.get("entryway:invites", code)).uses.length, 0); + f.db.set = originalSet; + let completionCalls = 0; + const bindingAdmission = createArrivalAdmission({ + db: f.db, + arrivals: f.arrivals, + invitation: { + reserveInvite: (...args) => f.invites.reserveInvite(...args), + completeInvite: async (...args) => { + completionCalls += 1; + return f.invites.completeInvite(...args); + }, + }, + }); + const bound = await bindingAdmission.bindPending(input); + assert.deepEqual(bound, { kind: "applied", version: version + 1 }); + const beforeRetry = await f.db.read("arrivals"); + let retryWrites = 0; + const originalUpdate = f.db.update; + f.db.update = async (...args) => { + retryWrites += 1; + return originalUpdate(...args); + }; + f.db.set = async (...args) => { + retryWrites += 1; + return originalSet(...args); + }; + for (const expectedVersion of [version, bound.version]) + assert.deepEqual( + await bindingAdmission.bindPending({ ...input, expectedVersion }), + { kind: "already-settled", version: bound.version }, + ); + assert.equal(completionCalls, 1); + assert.equal(retryWrites, 0); + assert.deepEqual(await f.db.read("arrivals"), beforeRetry); + assert.equal((await f.arrivals.readArrivalAccess(did)).complete, false); + f.db.update = originalUpdate; + f.db.set = originalSet; + await f.invites.completeInvite({ email: input.email, did }); + assert.equal((await f.db.get("entryway:invites", code)).uses.length, 1); + await assert.rejects( + f.invites.completeInvite({ email: input.email, did: otherDid }), + { error: "InvalidInviteCode" }, + ); + assert.equal( + (await f.db.get("entryway:invite-reservations", input.email)).did, + did, + ); + } finally { + await f.db.close(); + } +}); + +test("real invite capacity contention reserves only one email", async () => { + const f = await admissionFixture(); + try { + const { code } = await f.invites.createInviteCode({ useCount: 1 }); + const results = await Promise.allSettled([ + f.invites.reserveInvite(code, "one@example.test"), + f.invites.reserveInvite(code, "two@example.test"), + ]); + assert.equal( + results.filter((item) => item.status === "fulfilled").length, + 1, + ); + assert.equal((await f.db.list("entryway:invite-reservations")).length, 1); + assert.equal((await f.db.get("entryway:invites", code)).remaining, 0); + } finally { + await f.db.close(); + } +}); diff --git a/tests/contracts/incoming-arrival-composition.test.mjs b/tests/contracts/incoming-arrival-composition.test.mjs new file mode 100644 index 00000000..eb66e42a --- /dev/null +++ b/tests/contracts/incoming-arrival-composition.test.mjs @@ -0,0 +1,1549 @@ +import { Secp256k1MigrationPlcSigner } from "../../dist/src/plc/signing.js"; +import assert from "node:assert/strict"; +import test from "node:test"; +import { generateKeyPairSync } from "node:crypto"; +import { createServiceJwt } from "@atproto/xrpc-server"; +import { + incomingHandoffMethod, + incomingCreationMethod, +} from "../../dist/src/features/external-migration/incoming-authorization.js"; +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"; +import * as plc from "@did-plc/lib"; +import { ArrivalPdsClient } from "../../dist/src/pds/arrival-client.js"; +import { composeIncomingArrival } from "../../dist/src/compose-incoming-arrival.mjs"; +import { createBrowserFlow } from "../../dist/src/http/browser-flow.mjs"; +import { createOperationOwnership } from "../../dist/src/accounts/operation-ownership.js"; +import { createOperationOwnershipStore } from "../../dist/src/database/drizzle/operation-ownership.js"; +import { createAccountStorage } from "../../dist/src/database/drizzle/account-storage.js"; +import { createArrivalStorage } from "../../dist/src/database/drizzle/migration-arrival.js"; +import { validateIncomingHandoff } from "../../dist/src/plc/policy.js"; +import { + failureTrigger, + removeFailureTrigger, + hasFailure, + openTestDatabase, + verifiedUser, + query, +} from "../support/database-fixture.mjs"; + +const endpoint = "https://destination.example.test"; +const sourceEndpoint = "https://source.example.test"; +const email = "destination@example.test"; +const handle = "destination.example.test"; + +async function fixture(t, mode = "modern", mutation = "", fault = "") { + const directory = mkdtempSync(join(tmpdir(), "arrival-preparation-")); + const path = join(directory, "authority.sqlite"); + let db = await openTestDatabase(path); + t.after(async () => { + await db.close(); + rmSync(directory, { recursive: true, force: true }); + }); + const source = await Secp256k1Keypair.create(); + const recovery = await Secp256k1Keypair.create(); + const hot = await Secp256k1Keypair.create({ exportable: true }); + const repository = await Secp256k1Keypair.create(); + let predecessor; + if (mode === "legacy") { + predecessor = await plc.deprecatedSignCreate( + { + type: "create", + signingKey: source.did(), + recoveryKey: recovery.did(), + handle, + service: sourceEndpoint, + prev: null, + }, + recovery, + ); + } else { + const keys = [recovery.did(), source.did()]; + if (mutation === "full") + for (let index = 0; index < 3; index++) + keys.push((await Secp256k1Keypair.create()).did()); + predecessor = await plc.signOperation( + plc.formatAtprotoOp({ + signingKey: source.did(), + handle: mutation === "distinct-handle" ? "source.example.test" : handle, + pds: sourceEndpoint, + rotationKeys: keys, + prev: null, + }), + recovery, + ); + } + const did = await plc.didForCreateOp(predecessor); + const head = String(await cidForCbor(predecessor)); + const audit = [ + { + did, + cid: head, + operation: predecessor, + nullified: false, + createdAt: new Date().toISOString(), + }, + ]; + if (mutation === "wrong-did") audit[0].did = `did:plc:${"a".repeat(24)}`; + if (mutation === "signature") { + audit[0].operation = { ...predecessor, sig: "invalid" }; + audit[0].cid = String(await cidForCbor(audit[0].operation)); + } + if (mutation === "cid") audit[0].cid = "wrong"; + if (mutation === "nullified") audit[0].nullified = true; + if (mutation === "tombstone") { + const operation = await plc.signOperation( + { type: "plc_tombstone", prev: head }, + source, + ); + audit.push({ + did, + operation, + cid: String(await cidForCbor(operation)), + nullified: false, + createdAt: new Date().toISOString(), + }); + } + const hosts = [ + { id: "pds1", url: endpoint, did: "did:web:destination.example.test" }, + ]; + const storage = createAccountStorage(db, hosts); + const arrivalStorage = () => + createArrivalStorage(db, hosts, { + readAccount: (value) => storage.getByDid(value), + readBinding: (value) => storage.getVerifiedBinding(value), + reserveEmailClaim: (...args) => storage.reserveEmail(...args), + reserveHandleClaim: (...args) => storage.reserveHandle(...args), + recordSavedUserBinding: (subject, userId) => + db.insert( + "account_bindings", + { did: subject, user_id: userId }, + { ignoreConflict: true }, + ), + insertPlacedAccount: (input) => + storage.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 arrivals = arrivalStorage(); + if (fault.startsWith("after-commit")) + arrivals.recordAllocationIntent = async () => { + throw new Error("interrupted before allocation intent"); + }; + await verifiedUser(db, "destination-user", email); + const principal = { + userId: "destination-user", + email, + emailVerified: true, + sessionId: "session", + kind: "better-auth", + authenticatedAt: new Date(), + }; + const authentication = { + requireSession: async () => principal, + verifySignInCode: async ({ email: destinationEmail, otp }) => { + assert.equal(destinationEmail, email); + return { + ok: otp === "fresh-otp", + principal: { + ...principal, + ...(mutation === "wrong-user" ? { userId: "other-user" } : {}), + }, + }; + }, + }; + const config = { + inviteCodeRequired: true, + pds: hosts, + issuer: "https://entryway.example.test", + clientUrl: "https://client.example.test", + serviceDid: "did:web:entryway.example.test", + betterAuthSecret: "unit-test-secret", + jwtJwk: generateKeyPairSync("ec", { + namedCurve: "secp256k1", + }).privateKey.export({ format: "jwk" }), + }; + const store = createOperationOwnershipStore(db); + const ownership = createOperationOwnership({ + store: { + ...store, + async checkpoint(...args) { + if (fault === "before-checkpoint") throw new Error("checkpoint fault"); + await store.checkpoint(...args); + if (fault === "after-checkpoint") throw new Error("checkpoint fault"); + }, + release: fault === "after-commit-crash" ? async () => {} : store.release, + }, + heartbeatMs: 0, + }); + let publicationMode = "normal"; + let directoryReads = 0; + let credentialsIssued = 0; + const publicationAttempts = []; + const accounts = { + ownership, + storage, + get: (value) => storage.get(value), + plcSigner: await Secp256k1MigrationPlcSigner.fromHex( + Buffer.from(await hot.export()).toString("hex"), + ), + plcClient: { + url: "https://plc.example.test", + getAuditableLog: async () => { + if ( + backendState.mode === "directory-outage" && + backendState.creates > 0 + ) + throw new Error("directory unavailable"); + return structuredClone(audit); + }, + getDocument: async () => { + directoryReads++; + return plc.formatDidDoc({ + did, + ...plc.normalizeOp(audit.at(-1).operation), + }); + }, + sendOperation: async (subject, operation) => { + assert.equal(subject, did); + const admissions = await query(db, "SELECT * FROM arrival_replay"); + const signed = await query( + db, + "SELECT * FROM arrival_signed_operations", + ); + 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)); + if (publicationMode === "lost-unapplied") + throw new Error("response lost"); + audit.push({ + did, + cid: String(await cidForCbor(operation)), + operation: structuredClone(operation), + nullified: false, + createdAt: new Date().toISOString(), + }); + if (publicationMode === "lost-applied") + throw new Error("response lost"); + }, + getLastOp: async () => + mutation === "race" + ? { ...predecessor, sig: "changed" } + : audit.at(-1).operation, + }, + }; + const browserFlow = createBrowserFlow({ + db, + config, + provider: { + deviceManager: { load: async () => ({ deviceId: "browser" }) }, + }, + }); + const request = { headers: { origin: config.issuer }, body: {} }; + request.body.csrf = (await browserFlow.loadBrowser(request)).csrf; + let reservations = 0; + const backendState = { + exists: false, + deactivated: false, + creates: 0, + pauses: 0, + mode: "normal", + exactMove: null, + adminExtras: {}, + }; + + const originalFetch = globalThis.fetch; + t.after(() => { + globalThis.fetch = originalFetch; + }); + globalThis.fetch = async (url, options) => { + const parsedUrl = new URL(url); + if (parsedUrl.pathname.endsWith("getAccountInfo")) { + assert.match(options.headers.authorization, /^Basic /); + if (backendState.mode === "network") + throw new Error("network unavailable"); + if (backendState.mode === "malformed") return Response.json({ did }); + if (!backendState.exists) + return Response.json({ error: "NotFound" }, { status: 404 }); + return Response.json({ + did: backendState.mode === "wrong-did" ? "did:plc:wrong" : did, + handle, + indexedAt: new Date().toISOString(), + ...backendState.adminExtras, + ...(backendState.deactivated + ? { deactivatedAt: new Date().toISOString() } + : {}), + }); + } + if (parsedUrl.pathname.endsWith("createAccount")) { + backendState.creates++; + const body = JSON.parse(options.body); + const recorded = ( + await query( + db, + "SELECT operation FROM arrival_signed_operations WHERE kind = 'destination-move'", + ) + )[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, + operation: body.plcOp, + cid: String(await cidForCbor(body.plcOp)), + nullified: false, + createdAt: new Date().toISOString(), + }); + if (backendState.mode === "malformed-head") audit.at(-1).cid = "invalid"; + if (backendState.mode !== "published-absent") backendState.exists = true; + if (["creation-lost", "published-absent"].includes(backendState.mode)) + throw new Error("creation response lost"); + return Response.json({ + did, + handle, + accessJwt: "discarded-access", + refreshJwt: "discarded-refresh", + }); + } + if (parsedUrl.pathname.endsWith("updateSubjectStatus")) { + backendState.pauses++; + assert.deepEqual(JSON.parse(options.body), { + 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"); + return Response.json({}); + } + reservations++; + assert.equal( + String(url), + `${endpoint}/xrpc/com.atproto.server.reserveSigningKey`, + ); + assert.deepEqual(JSON.parse(options.body), { did }); + assert.equal(options.headers.authorization, undefined); + const rows = await query(db, "SELECT * FROM arrival_reservations"); + assert.equal(rows.length, 1); + assert.equal(rows[0].signing_key, null); + if (mutation === "lost") throw new Error("reservation response lost"); + if (mutation === "http") return new Response("{}", { status: 503 }); + return Response.json({ signingKey: repository.did() }); + }; + const composed = await composeIncomingArrival({ + db, + arrivals, + config, + accounts, + authentication, + browserFlow, + }); + return { + get db() { + return db; + }, + arrivals, + backendState, + async reopen() { + await db.close(); + db = await openTestDatabase(path); + return arrivalStorage(); + }, + request, + config, + principal, + ownership, + store, + audit, + publicationAttempts, + setPublicationMode: (value) => { + publicationMode = value; + }, + directoryReads: () => directoryReads, + credentialsIssued: () => credentialsIssued, + async credential(method = incomingHandoffMethod, overrides = {}) { + credentialsIssued++; + if (overrides.jti !== undefined) { + const now = Math.floor(Date.now() / 1000); + const header = Buffer.from( + JSON.stringify({ typ: "JWT", alg: "ES256K" }), + ).toString("base64url"); + const payload = Buffer.from( + JSON.stringify({ + iss: did, + aud: config.serviceDid, + lxm: method, + iat: now, + exp: now + 120, + ...overrides, + }), + ).toString("base64url"); + const bytes = `${header}.${payload}`; + return `Bearer ${bytes}.${Buffer.from(await source.sign(Buffer.from(bytes))).toString("base64url")}`; + } + return `Bearer ${await createServiceJwt({ iss: did, aud: config.serviceDid, lxm: method, keypair: source, ...overrides })}`; + }, + did, + predecessor, + head, + source, + hot, + repository, + composed, + reservations: () => reservations, + prepare: (otp = "fresh-otp") => + composed.prepareArrival(request, otp, { did, handle }), + }; +} + +for (const mode of ["modern", "legacy"]) { + test(`composed ${mode} preparation retains signed predecessor and reserves only after durable intent`, async (t) => { + const f = await fixture(t, mode); + const result = await f.prepare(); + const saved = await f.arrivals.readArrival( + result.operationId, + "destination-user", + ); + assert.deepEqual(saved.sourcePredecessor, f.predecessor); + assert.equal(saved.sourcePlcHead, f.head); + assert.equal(String(await cidForCbor(saved.sourcePredecessor)), f.head); + assert.equal(result.expectedPlcHead, f.head); + assert.equal(result.sourceEndpoint, sourceEndpoint); + assert.equal(result.destinationEndpoint, endpoint); + assert.deepEqual(saved.approvedRotationKeys, [ + ...plc.normalizeOp(f.predecessor).rotationKeys, + f.hot.did(), + ]); + assert.equal(saved.codeHash.includes(result.arrivalCode), false); + assert.deepEqual( + Object.keys(result).sort(), + [ + "operationId", + "version", + "arrivalCode", + "expiresAt", + "entrywayDid", + "sourceEndpoint", + "destinationEndpoint", + "expectedPlcHead", + "handoff", + ].sort(), + ); + assert.deepEqual( + Object.keys(f.composed).sort(), + [ + "admitCreation", + "bindPending", + "prepareArrival", + "admitIncoming", + "continueHandoff", + "continueCreation", + "reconcileArrival", + ].sort(), + ); + assert.equal( + (await query(f.db, "SELECT * FROM account_bindings")).length, + 0, + ); + const signed = await plc.signOperation(result.handoff, f.source); + await validateIncomingHandoff({ + operation: signed, + expectedPredecessor: saved.sourcePredecessor, + approvedRotationKeys: saved.approvedRotationKeys, + source: saved.source, + }); + const claim = await query(f.db, "SELECT * FROM operation_admissions"); + assert.ok( + claim.some((row) => Object.values(row).includes(`arrival:${f.did}`)), + ); + assert.equal(f.reservations(), 1); + }); +} + +for (const mutation of [ + "wrong-did", + "signature", + "cid", + "nullified", + "tombstone", + "race", + "full", + "wrong-user", +]) { + test(`composed preparation rejects ${mutation} before persistence and allocation`, async (t) => { + const f = await fixture(t, "modern", mutation); + await assert.rejects(f.prepare()); + assert.equal(f.reservations(), 0); + assert.equal((await query(f.db, "SELECT * FROM arrivals")).length, 0); + }); +} + +for (const mutation of ["lost", "http"]) { + test(`composed preparation retains placement and obligation after ${mutation} reservation response`, async (t) => { + const f = await fixture(t, "modern", mutation); + await assert.rejects(f.prepare()); + const rows = await query(f.db, "SELECT * FROM arrivals"); + assert.equal(rows.length, 1); + assert.equal(rows[0].endpoint, endpoint); + assert.equal( + (await query(f.db, "SELECT * FROM arrival_reservations")).length, + 1, + ); + assert.equal(f.reservations(), 1); + }); +} + +test("preparation rejects missing/stale OTP and existing origin/CSRF violations", async (t) => { + const f = await fixture(t); + await assert.rejects(f.prepare("")); + await assert.rejects(f.prepare("stale-otp")); + f.request.headers.origin = "https://wrong.example.test"; + await assert.rejects(f.prepare()); + f.request.headers.origin = "https://entryway.example.test"; + f.request.body.csrf = "wrong"; + await assert.rejects(f.prepare()); + assert.equal(f.reservations(), 0); + assert.equal((await query(f.db, "SELECT * FROM arrivals")).length, 0); +}); + +for (const fault of ["before-checkpoint", "after-checkpoint"]) { + test(`preparation rolls back arrival and code on ${fault} failure`, async (t) => { + const f = await fixture(t, "modern", "", fault); + await assert.rejects(f.prepare(), /checkpoint fault/); + assert.equal(f.reservations(), 0); + await f.reopen(); + for (const table of [ + "arrivals", + "arrival_code", + "arrival_reservations", + "operation_admissions", + ]) + assert.equal((await query(f.db, `SELECT * FROM ${table}`)).length, 0); + const operations = await query(f.db, "SELECT * FROM authority_operations"); + assert.equal(operations.length, 1); + assert.equal(Boolean(operations[0].pending), false); + assert.equal(operations[0].state, "complete"); + }); +} + +for (const fault of ["after-commit-release", "after-commit-crash"]) { + test(`committed preparation remains recoverable after ${fault} and database reopen`, async (t) => { + const f = await fixture(t, "modern", "", fault); + await assert.rejects(f.prepare(), /interrupted before allocation intent/); + assert.equal(f.reservations(), 0); + const arrivals = await f.reopen(); + const saved = (await query(f.db, "SELECT * FROM arrivals"))[0]; + const operation = ( + await query(f.db, "SELECT * FROM authority_operations") + )[0]; + assert.equal(saved.operation_id, operation.id); + assert.equal(Boolean(operation.pending), true); + assert.equal(operation.phase, "arrival-prepared"); + const admissions = await query(f.db, "SELECT * FROM operation_admissions"); + assert.equal(admissions.length, 1); + assert.equal(admissions[0].operation_id, saved.operation_id); + if (fault === "after-commit-crash") { + assert.ok(operation.worker_id); + await f.db.update( + "authority_operations", + { + lease_expires_at: (await f.db.databaseTime()) - 1, + }, + eq(f.db.tables.authority_operations.id, operation.id), + ); + } else assert.equal(operation.worker_id, null); + const owner = createOperationOwnership({ + store: createOperationOwnershipStore(f.db), + heartbeatMs: 0, + }); + await owner.run( + `arrival:${f.did}`, + { + kind: "public-arrival", + request: { did: f.did, handle, userId: "destination-user" }, + }, + async () => { + const claim = owner.currentClaim; + assert.equal(claim.resumed, true); + assert.equal(claim.operationId, saved.operation_id); + assert.equal(claim.attempt, 2); + const result = await arrivals.cancelArrival({ + owner: claim, + operationId: saved.operation_id, + expectedVersion: saved.version, + ownerUserId: "destination-user", + noRemoteObligation: true, + plcStateUnchanged: true, + }); + assert.equal(result.kind, "applied"); + await owner.checkpoint("complete", null); + }, + ); + assert.equal( + (await query(f.db, "SELECT * FROM operation_admissions")).length, + 0, + ); + assert.equal( + (await query(f.db, "SELECT * FROM arrivals WHERE active = 1")).length, + 0, + ); + }); +} + +for (const mode of ["normal", "lost-applied", "lost-unapplied"]) { + test(`authenticated handoff ${mode} retains exact journal and uses fenced recovery`, async (t) => { + const f = await fixture(t); + const prepared = await f.prepare(); + const operation = await plc.signOperation(prepared.handoff, f.source); + f.setPublicationMode(mode); + const input = { + operationId: prepared.operationId, + method: incomingHandoffMethod, + body: { operation }, + presentation: await f.credential(), + arrivalCode: prepared.arrivalCode, + }; + if (mode === "normal") { + assert.equal( + (await f.composed.admitIncoming(f.request, input)).state, + "published", + ); + } else { + await assert.rejects(f.composed.admitIncoming(f.request, input)); + await assert.rejects( + f.composed.continueHandoff(f.request, prepared.operationId), + { code: "OperationRecoveryRequired" }, + ); + const attempt = await f.ownership.pendingExternal(`arrival:${f.did}`); + await f.store.approveRecovery({ + operationId: attempt.operationId, + externalAttemptId: attempt.id, + executionAttemptId: attempt.executionAttemptId, + target: attempt.target, + dispatcherIsolationReference: "test-dispatcher-stopped", + upstreamDrainReference: "test-directory-drained", + action: "retry-if-safe", + }); + f.setPublicationMode("normal"); + assert.equal( + (await f.composed.continueHandoff(f.request, prepared.operationId)) + .state, + "published", + ); + } + assert.equal( + f.publicationAttempts.length, + mode === "lost-unapplied" ? 2 : 1, + ); + for (const sent of f.publicationAttempts) assert.deepEqual(sent, operation); + // Valid source key cutover does not require a new source credential on trusted continuation. + const cutover = await plc.signOperation( + { + ...prepared.handoff, + verificationMethods: { atproto: f.hot.did() }, + prev: String(await cidForCbor(operation)), + }, + f.hot, + ); + f.audit.push({ + did: f.did, + cid: String(await cidForCbor(cutover)), + operation: cutover, + nullified: false, + createdAt: new Date().toISOString(), + }); + assert.equal( + (await f.composed.continueHandoff(f.request, prepared.operationId)).state, + "diverged", + ); + assert.equal( + f.publicationAttempts.length, + mode === "lost-unapplied" ? 2 : 1, + ); + f.principal.userId = "other-user"; + await assert.rejects( + f.composed.continueHandoff(f.request, prepared.operationId), + { code: "AccountNotFound" }, + ); + }); +} + +test("unresolved accepted handoff stays pending after a signed destination key cutover before canonical settlement", async (t) => { + const f = await fixture(t); + const prepared = await f.prepare(); + // The handoff adds rotation authority, but must preserve the source repository key. + assert.equal(prepared.handoff.verificationMethods.atproto, f.source.did()); + const operation = await plc.signOperation(prepared.handoff, f.source); + const cid = String(await cidForCbor(operation)); + f.setPublicationMode("lost-applied"); + await assert.rejects( + f.composed.admitIncoming(f.request, { + operationId: prepared.operationId, + method: incomingHandoffMethod, + body: { operation }, + presentation: await f.credential(), + arrivalCode: prepared.arrivalCode, + }), + /response lost/, + ); + const accepted = await f.arrivals.readArrivalAggregate( + prepared.operationId, + "destination-user", + ); + assert.equal(accepted.admissions.length, 1); + assert.equal(accepted.signedOperations.length, 1); + assert.deepEqual(accepted.signedOperations[0].operation, operation); + assert.equal(accepted.signedOperations[0].cid, cid); + assert.equal(accepted.progress.canonicalHandoffCid, null); + assert.equal(f.audit.at(-1).cid, cid); + const attempt = await f.ownership.pendingExternal(`arrival:${f.did}`); + assert.ok(attempt); + + // Model a real signed descendant, not an auth resolver disconnected from PLC + // history. This supplies directory state only; it does not implement B3. + const cutover = await plc.signOperation( + { + ...prepared.handoff, + verificationMethods: { atproto: f.repository.did() }, + services: { + ...prepared.handoff.services, + atproto_pds: { type: "AtprotoPersonalDataServer", endpoint }, + }, + prev: cid, + }, + f.hot, + ); + const cutoverCid = String(await cidForCbor(cutover)); + f.audit.push({ + did: f.did, + cid: cutoverCid, + operation: cutover, + nullified: false, + createdAt: new Date().toISOString(), + }); + assert.notEqual(cutoverCid, cid); + assert.notEqual(cutover.verificationMethods.atproto, f.source.did()); + const readsBeforeRecovery = f.directoryReads(); + assert.equal(f.credentialsIssued(), 1); + assert.equal(readsBeforeRecovery, 1); + + // A changed directory key cannot bypass generic isolation/drain approval. + await assert.rejects( + f.composed.continueHandoff(f.request, prepared.operationId), + { code: "OperationRecoveryRequired" }, + ); + assert.deepEqual(f.publicationAttempts, [operation]); + await f.store.approveRecovery({ + operationId: attempt.operationId, + externalAttemptId: attempt.id, + executionAttemptId: attempt.executionAttemptId, + target: attempt.target, + dispatcherIsolationReference: "test-dispatcher-stopped", + upstreamDrainReference: "test-directory-drained", + action: "retry-if-safe", + }); + f.setPublicationMode("normal"); + for (let retry = 0; retry < 2; retry++) { + await assert.rejects( + f.composed.continueHandoff(f.request, prepared.operationId), + { + code: "OperationRecoveryRequired", + message: + "The observed account state does not permit this recovery. Keep the account pending for operator investigation.", + }, + ); + } + const pending = await f.arrivals.readArrivalAggregate( + prepared.operationId, + "destination-user", + ); + assert.equal(pending.progress.canonicalHandoffCid, null); + assert.deepEqual(pending.admissions, accepted.admissions); + assert.deepEqual(pending.signedOperations, accepted.signedOperations); + const unresolved = await f.ownership.pendingExternal(`arrival:${f.did}`); + assert.equal(unresolved.id, attempt.id); + assert.equal(unresolved.state, "recovery-approved"); + assert.equal(unresolved.intentDigest, attempt.intentDigest); + assert.equal(f.credentialsIssued(), 1); + assert.equal(f.directoryReads(), readsBeforeRecovery); + assert.deepEqual(f.publicationAttempts, [operation]); + assert.equal(f.audit.length, 3); + assert.equal(f.audit.at(-1).cid, cutoverCid); + assert.equal(f.reservations(), 1); + assert.equal((await query(f.db, "SELECT * FROM account_bindings")).length, 0); +}); + +test("fresh bodies have semantic server digests and reject unsupported fields", async (t) => { + const f = await fixture(t); + const prepared = await f.prepare(); + const saved = await f.arrivals.readArrival( + prepared.operationId, + "destination-user", + ); + const operation = await plc.signOperation(prepared.handoff, f.source); + const reversed = Object.fromEntries(Object.entries(operation).reverse()); + const digest = (candidate) => + 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({ + ...operation, + rotationKeys: [...operation.rotationKeys].reverse(), + }), + ); + assert.throws(() => + parseArrivalRequest(saved, incomingHandoffMethod, { + operation, + requestDigest: "a".repeat(64), + }), + ); + for (const field of [ + "password", + "verificationCode", + "verificationPhone", + "recoveryKey", + "plcOp", + "unexpected", + ]) + assert.throws(() => + parseArrivalRequest(saved, incomingCreationMethod, { + handle, + [field]: "unsupported", + }), + ); + assert.equal( + parseArrivalRequest(saved, incomingCreationMethod, { handle }) + .requestDigest, + parseArrivalRequest(saved, incomingCreationMethod, { + handle: handle.toUpperCase(), + did: f.did, + email, + }).requestDigest, + ); + const wrong = await plc.signOperation( + { + ...prepared.handoff, + prev: "bafyreiaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + }, + f.source, + ); + await assert.rejects( + f.composed.admitIncoming(f.request, { + operationId: prepared.operationId, + method: incomingHandoffMethod, + body: { operation: wrong }, + presentation: await f.credential(), + arrivalCode: prepared.arrivalCode, + }), + ); + assert.equal((await query(f.db, "SELECT * FROM arrival_replay")).length, 0); + assert.equal(f.publicationAttempts.length, 0); +}); + +test("authenticated creation uses real invitation producer atomically without storing request secrets", async (t) => { + const f = await fixture(t); + const prepared = await f.prepare(); + const input = { + operationId: prepared.operationId, + method: incomingCreationMethod, + body: { handle }, + presentation: await f.credential(incomingCreationMethod), + arrivalCode: prepared.arrivalCode, + }; + await assert.rejects( + f.composed.admitIncoming(f.request, input), + /An invite code is required/, + ); + assert.equal((await query(f.db, "SELECT * FROM arrival_replay")).length, 0); + const { createInvites } = + await import("../../dist/src/features/account-registration/invites.mjs"); + const invites = await createInvites({ + db: f.db, + config: f.config, + accounts: { get: async () => null }, + }); + const { code } = await invites.createInviteCode({ useCount: 1 }); + input.body.inviteCode = code; + assert.equal( + (await f.composed.admitIncoming(f.request, input)).state, + "admitted", + ); + const admissions = await query(f.db, "SELECT * FROM arrival_replay"); + assert.equal(admissions.length, 1); + for (const secret of [code, prepared.arrivalCode, input.presentation]) + assert.equal(JSON.stringify(admissions).includes(secret), false); + assert.equal(f.publicationAttempts.length, 0); + // Admission is durable, but creation cannot proceed without the separately + // accepted signed handoff. B3 no longer returns a metadata-only continuation. + await assert.rejects( + f.composed.continueCreation(f.request, prepared.operationId), + { code: "OperationRecoveryRequired" }, + ); + assert.equal( + (await query(f.db, "SELECT * FROM arrival_replay"))[0].request_digest, + admissions[0].request_digest, + ); +}); + +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(); + const operation = await plc.signOperation(prepared.handoff, f.source); + const record = f.arrivals.recordSignedOperation; + f.arrivals.recordSignedOperation = async (...args) => { + await record(...args); + throw new Error("journal commit fault"); + }; + await assert.rejects( + f.composed.admitIncoming(f.request, { + operationId: prepared.operationId, + method: incomingHandoffMethod, + body: { operation }, + presentation: await f.credential(), + arrivalCode: prepared.arrivalCode, + }), + /journal commit fault/, + ); + assert.equal((await query(f.db, "SELECT * FROM arrival_replay")).length, 0); + assert.equal( + (await query(f.db, "SELECT * FROM arrival_signed_operations")).length, + 0, + ); + assert.equal(f.publicationAttempts.length, 0); +}); + +test("verified credential jti cannot admit another incoming method", async (t) => { + const f = await fixture(t); + const prepared = await f.prepare(); + const operation = await plc.signOperation(prepared.handoff, f.source); + const jti = "same-verified-jti"; + await f.composed.admitIncoming(f.request, { + operationId: prepared.operationId, + method: incomingHandoffMethod, + body: { operation }, + presentation: await f.credential(incomingHandoffMethod, { jti }), + arrivalCode: prepared.arrivalCode, + }); + await assert.rejects( + f.composed.admitIncoming(f.request, { + operationId: prepared.operationId, + method: incomingCreationMethod, + body: { handle }, + presentation: await f.credential(incomingCreationMethod, { jti }), + arrivalCode: prepared.arrivalCode, + }), + { code: "OperationConflict" }, + ); + assert.equal((await query(f.db, "SELECT * FROM arrival_replay")).length, 1); +}); + +async function admitProvisioning(f, interruptHandoff = false) { + const prepared = await f.prepare(); + const operation = await plc.signOperation(prepared.handoff, f.source); + 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({ + db: f.db, + config: f.config, + accounts: { get: async () => null }, + }); + const { code } = await invites.createInviteCode({ useCount: 1 }); + await f.composed.admitIncoming(f.request, { + operationId: prepared.operationId, + method: incomingCreationMethod, + body: { handle, inviteCode: code }, + presentation: await f.credential(incomingCreationMethod), + arrivalCode: prepared.arrivalCode, + }); + 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", + "pause-lost", + "creation-rejected", + "pause-rejected", + "published-absent", + "network", + "malformed", + "wrong-did", +]) { + test(`durable creation ${mode} uses saved move, administrator observation and fenced recovery`, async (t) => { + const f = await fixture(t, "modern", "distinct-handle"); + const prepared = await admitProvisioning(f); + f.backendState.mode = mode; + if (mode === "wrong-did") f.backendState.exists = true; + const continuation = () => + 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}`); + assert.notEqual( + f.backendState.exactMove.alsoKnownAs[0], + f.predecessor.alsoKnownAs[0], + ); + assert.equal((await f.arrivals.readArrivalAccess(f.did)).bound, true); + } else { + await assert.rejects(continuation()); + assert.equal((await f.arrivals.readArrivalAccess(f.did)).bound, false); + assert.equal( + ( + await f.arrivals.readArrivalAggregate( + prepared.operationId, + f.principal.userId, + ) + ).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", + }); + 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"; + assert.equal((await continuation()).state, "pending"); + assert.equal(f.backendState.creates, 1); + assert.equal(f.backendState.pauses, 1); + } + if (mode === "published-absent") { + await assert.rejects(continuation(), { + code: "OperationRecoveryRequired", + }); + assert.equal(f.backendState.creates, 1); + assert.equal(f.reservations(), 1); + } + } + }); +} + +test("durable bind rollback retries exact saved move without another remote effect", async (t) => { + const f = await fixture(t); + const prepared = await admitProvisioning(f); + await failureTrigger( + f.db, + "reject_arrival_binding", + "account_bindings", + "bind rollback", + ); + await assert.rejects( + f.composed.continueCreation(f.request, prepared.operationId), + hasFailure("bind rollback"), + ); + assert.equal((await f.arrivals.readArrivalAccess(f.did)).bound, false); + assert.equal((await query(f.db, "SELECT * FROM accounts")).length, 0); + const exact = structuredClone(f.backendState.exactMove); + await removeFailureTrigger( + f.db, + "reject_arrival_binding", + "account_bindings", + ); + assert.equal( + (await f.composed.continueCreation(f.request, prepared.operationId)).state, + "pending", + ); + assert.deepEqual(f.backendState.exactMove, exact); + assert.equal(f.backendState.creates, 1); + assert.equal(f.backendState.pauses, 1); +}); + +test("saved move tampering and unrelated canonical descendants never dispatch creation", async (t) => { + const f = await fixture(t); + const prepared = await admitProvisioning(f); + f.backendState.mode = "network"; + await assert.rejects( + f.composed.continueCreation(f.request, prepared.operationId), + ); + const handoff = f.audit.at(-1).operation; + const { sig: _signature, ...unsigned } = handoff; + const unrelated = await plc.signOperation( + { + ...unsigned, + prev: String(await cidForCbor(handoff)), + alsoKnownAs: ["at://unrelated.example.test"], + }, + f.hot, + ); + f.audit.push({ + did: f.did, + operation: unrelated, + cid: String(await cidForCbor(unrelated)), + nullified: false, + createdAt: new Date().toISOString(), + }); + f.backendState.mode = "normal"; + await assert.rejects( + f.composed.continueCreation(f.request, prepared.operationId), + { code: "OperationRecoveryRequired" }, + ); + assert.equal(f.backendState.creates, 0); + f.audit.pop(); + // Force a saved move then fail before remote creation; retry must not re-sign. + f.backendState.mode = "malformed"; + const read = f.arrivals.readArrivalAggregate; + f.arrivals.readArrivalAggregate = async (...args) => { + const aggregate = await read(...args); + if ( + aggregate?.signedOperations.some( + (item) => item.kind === "destination-move", + ) + ) { + const item = aggregate.signedOperations.find( + (record) => record.kind === "destination-move", + ); + item.operation.services.atproto_pds.endpoint = + "https://wrong.example.test"; + } + return aggregate; + }; + f.backendState.mode = "normal"; + await assert.rejects( + f.composed.continueCreation(f.request, prepared.operationId), + { code: "OperationConflict" }, + ); + assert.equal(f.backendState.creates, 0); +}); + +for (const mode of [ + "existing-actor", + "unchanged-head", + "malformed-head", + "directory-outage", +]) { + test(`creation cannot settle from actor presence with ${mode}`, async (t) => { + const f = await fixture(t); + const prepared = await admitProvisioning(f); + const acceptedInvites = await f.db.list("entryway:invites"); + const before = await f.arrivals.readArrivalAggregate( + prepared.operationId, + f.principal.userId, + ); + f.backendState.mode = mode; + if (mode === "existing-actor") f.backendState.exists = true; + await assert.rejects( + f.composed.continueCreation(f.request, prepared.operationId), + ); + const after = await f.arrivals.readArrivalAggregate( + prepared.operationId, + f.principal.userId, + ); + assert.equal(after.progress.provisionedAt, null); + assert.equal(after.progress.boundAt, null); + assert.equal(f.backendState.pauses, 0); + assert.equal((await f.arrivals.readArrivalAccess(f.did)).bound, false); + assert.deepEqual(await f.db.list("entryway:invites"), acceptedInvites); + if (mode === "existing-actor") { + assert.deepEqual(after.signedOperations, before.signedOperations); + assert.equal(f.backendState.creates, 0); + } + }); +} + +for (const field of [ + "privateKey", + "accessJwt", + "refreshJwt", + "signingSecret", +]) { + for (const nested of [false, true]) { + test(`administrator observation rejects ${nested ? "nested" : "top-level"} ${field} without retaining material`, async (t) => { + const f = await fixture(t); + const prepared = await admitProvisioning(f); + const marker = Buffer.from(await f.hot.export()).toString("hex"); + f.backendState.adminExtras = nested + ? { relatedRecords: [{ credentials: { [field]: marker } }] } + : { [field]: marker }; + const logged = []; + for (const method of ["log", "warn", "error", "info", "debug"]) + t.mock.method(console, method, (...args) => logged.push(args)); + await assert.rejects( + f.composed.continueCreation(f.request, prepared.operationId), + (error) => { + assert.equal(error.code, "AccountUnavailable"); + assert.equal(String(error).includes(marker), false); + return true; + }, + ); + assert.equal(f.backendState.creates, 1); + assert.equal(f.backendState.pauses, 0); + assert.equal((await f.arrivals.readArrivalAccess(f.did)).bound, false); + const persisted = await query(f.db, "SELECT * FROM key_value_state"); + const aggregate = await f.arrivals.readArrivalAggregate( + prepared.operationId, + f.principal.userId, + ); + assert.equal(aggregate.progress.provisionedAt, null); + assert.equal( + JSON.stringify({ logged, persisted, aggregate }).includes(marker), + false, + ); + }); + } +} + +test("administrator observation permits stock nonsecret additive account fields", async (t) => { + const f = await fixture(t); + f.backendState.exists = true; + f.backendState.adminExtras = { + email, + relatedRecords: [ + { $type: "app.bsky.actor.profile", displayName: "Public profile" }, + ], + invites: [], + invitesDisabled: false, + emailConfirmedAt: new Date().toISOString(), + inviteNote: "Operator note", + threatSignatures: [{ property: "public-test", value: "public-value" }], + }; + const transport = new ArrivalPdsClient({ + endpoint, + did: f.did, + pdsDid: f.config.pds[0].did, + issuer: f.config.serviceDid, + jwtJwk: f.config.jwtJwk, + }); + assert.deepEqual(await transport.getAccountInfo(() => "Basic test"), { + did: f.did, + handle, + deactivated: false, + }); +}); + +test("existing actor under handoff cannot reconcile a previously saved move", async (t) => { + const f = await fixture(t); + const prepared = await admitProvisioning(f); + f.backendState.mode = "unchanged-head"; + await assert.rejects( + f.composed.continueCreation(f.request, prepared.operationId), + ); + const before = await f.arrivals.readArrivalAggregate( + prepared.operationId, + f.principal.userId, + ); + assert.equal( + before.signedOperations.filter((item) => item.kind === "destination-move") + .length, + 1, + ); + const receipt = await f.store.pendingExternal(`arrival:${f.did}`); + assert.ok(receipt); + await f.store.approveRecovery({ + operationId: receipt.operationId, + externalAttemptId: receipt.id, + executionAttemptId: receipt.executionAttemptId, + target: receipt.target, + dispatcherIsolationReference: "test-dispatcher-isolated", + upstreamDrainReference: "test-upstream-drained", + action: "observe", + }); + f.backendState.mode = "normal"; + await assert.rejects( + f.composed.continueCreation(f.request, prepared.operationId), + { code: "OperationRecoveryRequired" }, + ); + const after = await f.arrivals.readArrivalAggregate( + prepared.operationId, + f.principal.userId, + ); + assert.deepEqual(after.signedOperations, before.signedOperations); + assert.equal(after.progress.provisionedAt, null); + assert.equal(after.progress.boundAt, null); + assert.equal(f.backendState.creates, 1); + assert.equal(f.backendState.pauses, 0); + assert.equal( + (await f.store.pendingExternal(`arrival:${f.did}`)).id, + receipt.id, + ); +}); diff --git a/tests/contracts/incoming-arrival-live.test.mjs b/tests/contracts/incoming-arrival-live.test.mjs new file mode 100644 index 00000000..2da6d4f2 --- /dev/null +++ b/tests/contracts/incoming-arrival-live.test.mjs @@ -0,0 +1,72 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +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", + { + skip: !process.env.INCOMING_PUBLIC_MECHANISMS, + timeout: 120_000, + }, + (t) => qualifyIncomingArrival(t), +); + +for (const fault of ["creation-lost", "pause-lost"]) { + test( + `stock applied ${fault} remains unbound and rejects unsafe retry`, + { + skip: !process.env.INCOMING_PUBLIC_MECHANISMS, + timeout: 120_000, + }, + (t) => qualifyIncomingArrival(t, fault), + ); +} diff --git a/tests/contracts/incoming-arrival-reconciliation.test.mjs b/tests/contracts/incoming-arrival-reconciliation.test.mjs new file mode 100644 index 00000000..89fc1e8f --- /dev/null +++ b/tests/contracts/incoming-arrival-reconciliation.test.mjs @@ -0,0 +1,428 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +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", + import.meta.url, +); +const cases = [ + "intent-response-missing", + "key-response-lost", + "signed-handoff", + "handoff-observed", + "creation-admitted", + "saved-move", + "creation-response-lost", + "move-without-backend", + "deactivation-lost", + "deactivated-before-bind", + "binding-response-lost", + "lease-takeover", +]; +const pendingCuts = new Set([ + "intent-response-missing", + "key-response-lost", + "signed-handoff", + "handoff-observed", + "move-without-backend", + "divergent", + "tombstone", + "uncertain", +]); +function worker( + directory, + phase, + cut, + kill = false, + observationDelay = 0, + killDelay = 0, +) { + return new Promise((resolve, reject) => { + const child = fork( + helper, + [directory, phase, cut, String(observationDelay)], + { + stdio: ["ignore", "pipe", "pipe", "ipc"], + }, + ); + let message; + let stderr = ""; + let killTimer; + const timer = setTimeout(() => { + child.kill("SIGKILL"); + reject(new Error(`WorkerTimeout:${phase}:${cut}`)); + }, 20000); + const onStderr = (chunk) => { + stderr += chunk; + }; + 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); + 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("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( + `WorkerFailure:${phase}:${cut}:${code}:${signal}\n${stderr}`, + ), + ); + if (!message) + return reject(new Error(`MissingWorkerEvidence:${phase}:${cut}`)); + resolve({ ...message, exit: code, signal }); + }); + }); +} +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}`, + { timeout: 30000 }, + 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, 0, 250); + writeFileSync( + join(directory, "stopped.json"), + JSON.stringify({ + pid: stopped.pid, + stopped: true, + signal: stopped.signal, + boundary: stopped.boundary, + }), + { mode: 0o600 }, + ); + const inspected = await worker(directory, "inspect", cut); + const checkpoint = inspected.snapshot; + assert.ok(checkpoint.aggregate); + const aggregate = checkpoint.aggregate; + if (cut === "intent-response-missing") { + assert.ok(aggregate.reservation); + assert.equal(aggregate.arrival.signingKey, null); + } else + assert.equal( + aggregate.arrival.signingKey, + JSON.parse(readFileSync(join(directory, "remote.json"))).repository, + ); + if (["signed-handoff", "handoff-observed"].includes(cut)) { + assert.equal(aggregate.signedOperations.length, 1); + assert.equal(aggregate.admissions.length, 1); + assert.equal(aggregate.progress.canonicalHandoffCid, null); + } + if (cut === "creation-admitted" || cut === "lease-takeover") { + assert.equal(aggregate.admissions.length, 2); + assert.equal(aggregate.signedOperations.length, 1); + } + if ( + [ + "saved-move", + "creation-response-lost", + "move-without-backend", + "deactivation-lost", + "deactivated-before-bind", + "binding-response-lost", + ].includes(cut) + ) + assert.equal(aggregate.signedOperations.length, 2); + if (cut === "saved-move") { + assert.equal(checkpoint.counts.create, 0); + assert.equal(checkpoint.external, null); + } + if (cut === "creation-response-lost") { + assert.equal(aggregate.progress.provisionedAt, null); + assert.equal(checkpoint.counts.create, 1); + assert.ok(checkpoint.external); + } + if (cut === "deactivation-lost") { + assert.ok( + aggregate.attempts.some( + (item) => item.reason === "settled:incoming-creation", + ), + ); + assert.ok( + aggregate.attempts.some( + (item) => item.reason === "external:incoming-pause", + ), + ); + assert.equal(aggregate.progress.provisionedAt, null); + assert.equal(aggregate.progress.deactivatedAt, null); + } + if (cut === "deactivated-before-bind") { + assert.ok( + aggregate.attempts.some( + (item) => item.reason === "settled:incoming-pause", + ), + ); + assert.equal(aggregate.progress.deactivatedAt, null); + assert.equal(aggregate.progress.boundAt, null); + } + if (cut === "binding-response-lost") { + assert.ok(aggregate.progress.boundAt); + assert.equal(checkpoint.bindings.length, 1); + } + 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; + const expectedErrors = { + divergent: "OperationRecoveryRequired", + "move-without-backend": "OperationRecoveryRequired", + tombstone: "InvalidCustodyObservation", + uncertain: "FixtureObservationUnavailable", + }; + if (expectedErrors[cut]) + assert.equal(recovered.outcome.code, expectedErrors[cut]); + else { + assert.equal(recovered.outcome.state, "pending"); + assert.equal(recovered.outcome.code, undefined); + } + assert.equal( + recovered.gated, + Boolean(checkpoint.external) && cut !== "move-without-backend", + ); + if (cut === "move-without-backend") { + assert.deepEqual(after.external, checkpoint.external); + assert.equal(after.external.state, "dispatched"); + assert.equal(after.external.recovery, null); + } + if (recovered.gated) { + assert.equal(recovered.gateEvidence.code, "OperationRecoveryRequired"); + assert.equal(recovered.gateEvidence.unresolvedState, "dispatched"); + assert.equal(recovered.gateEvidence.unchangedBeforeApproval, true); + assert.equal(recovered.gateEvidence.killedPid, stopped.pid); + assert.equal(recovered.gateEvidence.signal, "SIGKILL"); + assert.equal(recovered.gateEvidence.approvedState, "recovery-approved"); + if (cut !== "move-without-backend") assert.equal(after.external, null); + } + const inviteCounts = { + reserved: after.invites.length, + completed: after.invites.reduce( + (total, entry) => total + entry.value.uses.length, + 0, + ), + remaining: after.invites.reduce( + (total, entry) => total + entry.value.remaining, + 0, + ), + }; + assert.equal( + inviteCounts.reserved, + aggregate.admissions.length === 2 ? 1 : 0, + ); + assert.equal(inviteCounts.completed, pendingCuts.has(cut) ? 0 : 1); + assert.equal(inviteCounts.remaining, 0); + assert.equal(after.counts.reserve, 1); + assert.equal(after.counts.credentials, checkpoint.counts.credentials); + for (const signed of aggregate.signedOperations) + assert.deepEqual( + after.aggregate.signedOperations.find( + (item) => item.kind === signed.kind, + ), + signed, + ); + assert.deepEqual(after.aggregate.admissions, aggregate.admissions); + if (pendingCuts.has(cut)) { + assert.equal(after.aggregate.progress.boundAt, null); + assert.equal(after.bindings.length, 0); + assert.equal(after.counts.create, checkpoint.counts.create); + assert.equal(after.counts.pause, checkpoint.counts.pause); + assert.equal(after.counts.sign, checkpoint.counts.sign); + if (cut !== "signed-handoff") + assert.equal(after.counts.handoff, checkpoint.counts.handoff); + if (cut === "signed-handoff") { + assert.equal(after.head, aggregate.signedOperations[0].cid); + assert.equal(after.counts.handoff, 1); + } else assert.equal(after.head, checkpoint.head); + assert.equal(after.currentKey, checkpoint.currentKey); + assert.deepEqual(after.invites, checkpoint.invites); + } else { + assert.equal(recovered.outcome.state, "pending"); + assert.ok(after.aggregate.progress.provisionedAt); + assert.ok(after.aggregate.progress.deactivatedAt); + assert.ok(after.aggregate.progress.boundAt); + assert.equal(after.bindings.length, 1); + assert.equal(after.counts.create, 1); + assert.equal(after.counts.pause, 1); + assert.equal(after.counts.sign, 1); + assert.equal(after.counts.handoff, 1); + const remote = JSON.parse(readFileSync(join(directory, "remote.json"))); + assert.equal(remote.moves.length, 1); + const move = after.aggregate.signedOperations.find( + (item) => item.kind === "destination-move", + ); + assert.equal(remote.moves[0], JSON.stringify(move.operation)); + assert.equal(after.currentKey, remote.repository); + // A further new process consumes the committed binding without effects. + const repeat = await worker(directory, "resume", cut); + assert.deepEqual(repeat.snapshot.counts, after.counts); + assert.deepEqual(repeat.snapshot.invites, after.invites); + assert.equal( + repeat.snapshot.aggregate.progress.boundAt, + after.aggregate.progress.boundAt, + ); + } + t.diagnostic( + JSON.stringify({ + cut, + initialPid: stopped.pid, + inspectPid: inspected.pid, + recoveryPid: recovered.pid, + signal: stopped.signal, + outcome: recovered.outcome, + counts: after.counts, + inviteCounts, + gated: recovered.gated, + gateEvidence: recovered.gateEvidence, + bound: after.bindings.length, + }), + ); + }, + ); +} +for (const [phase, cut, marker] of [ + ["resume-unexpected", "uncertain", "UnexpectedObservationFailure"], + ["resume-unexpected-coded", "uncertain", "UnexpectedCodedObservationFailure"], + [ + "resume-unexpected-gate", + "handoff-observed", + "UnexpectedPreapprovalFailure", + ], + ["resume-spoofed-gate", "handoff-observed", "error instanceof DomainError"], +]) { + test(`unexpected exception fails the recovery worker: ${phase}`, 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); + writeFileSync( + join(directory, "stopped.json"), + JSON.stringify({ + pid: stopped.pid, + stopped: true, + signal: stopped.signal, + boundary: stopped.boundary, + }), + { mode: 0o600 }, + ); + await assert.rejects(worker(directory, phase, cut), (error) => { + assert.match( + error.message, + new RegExp(`WorkerFailure:${phase}:${cut}:1:null`), + ); + assert.ok(error.message.includes(marker), error.message); + return true; + }); + t.diagnostic( + JSON.stringify({ + phase, + cut, + signal: stopped.signal, + rejectedWorkerExit: 1, + marker, + }), + ); + }); +} +test("actor appearing during move signing stays pending before create, pause or bind", async (t) => { + const directory = mkdtempSync(join(tmpdir(), "incoming-restart-")); + t.after(() => rmSync(directory, { recursive: true, force: true })); + const result = await worker(directory, "initial", "actor-during-sign"); + assert.equal(result.outcome.code, "OperationRecoveryRequired"); + assert.equal(result.snapshot.counts.sign, 1); + assert.equal(result.snapshot.counts.create, 0); + assert.equal(result.snapshot.counts.pause, 0); + assert.equal(result.snapshot.bindings.length, 0); + assert.equal(result.snapshot.aggregate.progress.provisionedAt, null); + assert.equal(result.snapshot.aggregate.signedOperations.length, 2); +}); diff --git a/tests/contracts/incoming-handoff.test.mjs b/tests/contracts/incoming-handoff.test.mjs new file mode 100644 index 00000000..6952f099 --- /dev/null +++ b/tests/contracts/incoming-handoff.test.mjs @@ -0,0 +1,308 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { generateKeyPairSync } from "node:crypto"; +import { Secp256k1Keypair } from "@atproto/crypto"; +import { decodeJwt, decodeProtectedHeader } from "jose"; +import { + ArrivalPdsClient, + reservationSigningKey, +} from "../../dist/src/pds/arrival-client.js"; +const hosts = [ + { id: "pds1", url: "https://pds1.example.test" }, + { id: "pds2", url: "https://pds2.example.test" }, +]; +const endpoint = hosts[0].url; +const did = `did:plc:${"a".repeat(24)}`; +const handle = "dest.entryway.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")}`; + +/** 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, + pdsDid: destinationDid(endpoint), + issuer: serviceDid, + 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("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("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, + did, + pdsDid: destinationDid(endpoint), + issuer: serviceDid, + 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, + pdsDid: destinationDid(endpoint), + issuer: serviceDid, + 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, + pdsDid: destinationDid(endpoint), + issuer: serviceDid, + 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", + }), + ); +}); diff --git a/tests/contracts/incoming-public-mechanisms.test.mjs b/tests/contracts/incoming-public-mechanisms.test.mjs index 87ebedb2..dcb2678c 100644 --- a/tests/contracts/incoming-public-mechanisms.test.mjs +++ b/tests/contracts/incoming-public-mechanisms.test.mjs @@ -1198,3 +1198,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); + }, +); diff --git a/tests/flows/external-migration.md b/tests/flows/external-migration.md index 884b6d21..c424acee 100644 --- a/tests/flows/external-migration.md +++ b/tests/flows/external-migration.md @@ -1,4 +1,4 @@ -# Synthetic external migration +# External migration testing for contributors ## Public incoming migration: shared-email test on hold @@ -10,10 +10,27 @@ does not prove this behavior. Blocked by [TECH-681 — Implement the public incoming-migration API](https://linear.app/hypercerts/issue/TECH-681/implement-the-public-incoming-migration-api). Once that support is available, add the scenario under [TECH-682 — Prove independent incoming migration and post-move OAuth](https://linear.app/hypercerts/issue/TECH-682/prove-independent-incoming-migration-and-post-move-oauth), -following the existing AiaB test conventions. Use two distinct DIDs with the same -email, migrate through public endpoints with normal ownership proofs, and verify -that the incoming DID, records and blobs survive while the existing account -remains unchanged. Do not substitute private fixture calls for public migration. +following the existing AiaB test conventions. The original shared-email positive +scenario is not the accepted individual-arrival policy: that path now requires a +unique destination email. Cover rejection of an already-claimed destination email +without changing the existing account, then use a distinct verified destination +email for the eventual public journey. Established whole-server shared-primary-email +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 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 diff --git a/tests/local.sh b/tests/local.sh index c9c6c984..ce93e4e8 100755 --- a/tests/local.sh +++ b/tests/local.sh @@ -15,7 +15,7 @@ command=${1:-help} mkdir -p "$artifacts" # Phase identity comes from the controller, never from a command or request body. case "$command" in - fresh|fresh-group|prepare|up|contracts|database-contracts|database-dialects|resilience-profiles|database-profile|browser|incoming-public-mechanisms|migration|migration-resume|resilience|reverify|interop-profile|interop-acceptance|plc-recovery|process-crash|managed-recovery|authority-drills|all|down|status|help) ;; + fresh|fresh-group|prepare|up|contracts|database-contracts|database-dialects|resilience-profiles|database-profile|browser|incoming-public-mechanisms|incoming-arrival-live|migration|migration-resume|resilience|reverify|interop-profile|interop-acceptance|plc-recovery|process-crash|managed-recovery|authority-drills|all|down|status|help) ;; *) echo 'code=UNKNOWN_PHASE'; exit 2 ;; esac printf 'phase=%s status=started\n' "$command" @@ -201,10 +201,19 @@ case "$command" in prepare_incoming_access browser 2>&1 | tee "$artifacts/browser.log" | python3 "$root/scripts/ci-summary.py" ;; - incoming-public-mechanisms) + incoming-public-mechanisms|incoming-arrival-live) require_state prepare_incoming_access - compose run --rm --no-deps --volume "$sandbox/incoming-access.json:/run/incoming-access.json:ro" -e INCOMING_ACCESS_PATH=/run/incoming-access.json -e "INCOMING_PROJECT=$project" -e INCOMING_PUBLIC_MECHANISMS=1 browser node --test tests/contracts/incoming-public-mechanisms.test.mjs + suite=incoming-public-mechanisms + if [[ "$command" == incoming-arrival-live ]]; then suite=incoming-arrival-live; fi + compose run --rm --no-deps --volume "$sandbox/incoming-access.json:/run/incoming-access.json:ro" -e INCOMING_ACCESS_PATH=/run/incoming-access.json -e "INCOMING_PROJECT=$project" -e INCOMING_PUBLIC_MECHANISMS=1 browser node --test "tests/contracts/$suite.test.mjs" + if [[ "$command" == incoming-arrival-live ]]; then + # The disposable dispatcher exited above; stop both owned target workers + # before permitting observation of either uncertain applied effect. + compose stop pds1 pds2 + compose up -d --wait pds1 pds2 + compose run --rm --no-deps --volume "$sandbox/incoming-access.json:/run/incoming-access.json:ro" -e INCOMING_ACCESS_PATH=/run/incoming-access.json -e "INCOMING_PROJECT=$project" -e INCOMING_PUBLIC_MECHANISMS=1 -e INCOMING_RECOVERY=1 -e INCOMING_DISPATCHER_EXIT_REFERENCE=owned-dispatcher-container-exited-0-and-removed -e INCOMING_UPSTREAM_DRAIN_REFERENCE=owned-pds1-pds2-stopped-then-healthy browser node --test --test-name-pattern='stock applied' tests/contracts/incoming-arrival-live.test.mjs + fi ;; migration) require_state diff --git a/tests/support/ci-lifecycle.test.py b/tests/support/ci-lifecycle.test.py index f09e8182..a6c13419 100644 --- a/tests/support/ci-lifecycle.test.py +++ b/tests/support/ci-lifecycle.test.py @@ -48,6 +48,55 @@ 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] + 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 = [] + + 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(compiled, {}) + 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) @@ -128,7 +177,7 @@ def test_explicit_default_guard(self): self.assertNotEqual(self.guard(ENTRYWAY_DOCKER_CONTEXT="default").returncode, 0) self.assertNotEqual(self.guard(ENTRYWAY_DOCKER_CONTEXT="foreign").returncode, 0) - def test_incoming_helpers_have_explicit_native_coverage(self): + def test_incoming_native_coverage_is_explicit_and_unique(self): source = Path(__file__).resolve().parents[2] package = json.loads((source / "package.json").read_text()) helpers = ["tests/support/helpers/stock-plc-mailpit.test.mjs", @@ -136,17 +185,96 @@ def test_incoming_helpers_have_explicit_native_coverage(self): "tests/atmosphere/project-incoming-access.test.mjs"] self.assertEqual(package["scripts"]["test:incoming-helpers"].split(), ["node", "--test", *helpers]) - checks = (source / ".github/workflows/ci.yml").read_text().split(" integration:", 1)[0] - self.assertEqual(checks.count("run: npm run test:incoming-helpers\n"), 1) + workflow = (source / ".github/workflows/ci.yml").read_text() + checks = workflow.split(" integration:", 1)[0] + for script in ["test:unit", "test:incoming-helpers", "test:incoming-reconciliation"]: + self.assertEqual(checks.count(f"run: npm run {script}\n"), 1) discovery = subprocess.run(["node", "--input-type=module", "-e", "import {discoverContracts} from './tests/support/discover-contracts.mjs';" "console.log(JSON.stringify(discoverContracts(undefined,{unit:true})))"], cwd=source, capture_output=True, text=True, check=True) files = json.loads(discovery.stdout) self.assertEqual(len(files), len(set(files))) + for name in ["storage", "admission", "handoff", "composition"]: + filename = f"incoming-{name}.test.mjs" if name == "handoff" else f"incoming-arrival-{name}.test.mjs" + self.assertEqual(files.count(f"tests/contracts/{filename}"), 1) + replay = "tests/contracts/incoming-arrival-reconciliation.test.mjs" + self.assertNotIn(replay, files) + self.assertEqual(package["scripts"]["test:incoming-reconciliation"].split(), + ["node", "--test", replay]) + self.assertNotIn("tests/contracts/incoming-public-mechanisms.test.mjs", files) for helper in helpers: self.assertNotIn(helper, files) - self.assertNotIn("tests/contracts/incoming-public-mechanisms.test.mjs", 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() + phase = controller.split(" incoming-public-mechanisms|incoming-arrival-live)", 1)[1].split(" ;;", 1)[0] + self.assertIn("require_state", phase) + self.assertIn("prepare_incoming_access", phase) + self.assertIn('suite=incoming-arrival-live', phase) + self.assertIn('INCOMING_PROJECT=$project', phase) + self.assertIn('INCOMING_ACCESS_PATH=/run/incoming-access.json', phase) + self.assertIn('tests/contracts/$suite.test.mjs', phase) + suite = (source / "tests/contracts/incoming-arrival-live.test.mjs").read_text() + self.assertIn('creation-lost', suite) + self.assertIn('pause-lost', suite) def test_live_controller_shell_syntax(self): source = Path(__file__).resolve().parents[2] diff --git a/tests/support/discover-contracts.mjs b/tests/support/discover-contracts.mjs index 151c469d..4b781b87 100644 --- a/tests/support/discover-contracts.mjs +++ b/tests/support/discover-contracts.mjs @@ -3,6 +3,10 @@ import { join, relative, resolve } from "node:path"; const unitContracts = new Set([ "external-workflow.test.mjs", + "incoming-arrival-storage.test.mjs", + "incoming-arrival-admission.test.mjs", + "incoming-arrival-composition.test.mjs", + "incoming-handoff.test.mjs", "custody-history.test.mjs", "plc-policy.test.mjs", "plc-signing.test.mjs", diff --git a/tests/support/helpers/incoming-arrival-live.mjs b/tests/support/helpers/incoming-arrival-live.mjs new file mode 100644 index 00000000..dc38525d --- /dev/null +++ b/tests/support/helpers/incoming-arrival-live.mjs @@ -0,0 +1,430 @@ +import assert from "node:assert/strict"; +import { readFile, writeFile, mkdir } from "node:fs/promises"; +import { createOperationOwnershipStore } from "../../../dist/src/database/drizzle/operation-ownership.js"; +import { randomUUID } from "node:crypto"; +import { cidForCbor } from "@atproto/common"; +import { openDatabase } from "../../../dist/src/database/connection.js"; +import { createAccounts } from "../../../dist/src/compose-accounts.mjs"; +import { createArrivalStorage } from "../../../dist/src/database/drizzle/migration-arrival.js"; +import { composeIncomingArrival } from "../../../dist/src/compose-incoming-arrival.mjs"; +import { createBetterAuthAuthentication } from "../../../dist/src/authentication/better-auth.mjs"; +import { createBrowserFlow } from "../../../dist/src/http/browser-flow.mjs"; +import { createMailFeature } from "../../../dist/src/mail/create-mail.js"; +import { createMailOutbox } from "../../../dist/src/database/drizzle/mail-outbox.js"; +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") { + const access = JSON.parse( + await readFile(process.env.INCOMING_ACCESS_PATH, "utf8"), + ); + assert.equal(access.project, process.env.INCOMING_PROJECT); + const config = JSON.parse( + await readFile(process.env.SERVICE_CONFIG_PATH, "utf8"), + ); + const resume = process.env.INCOMING_RECOVERY === "1"; + const receiptPath = `/app/artifacts/incoming-live-recovery-${fault}.json`; + const receipt = resume + ? JSON.parse(await readFile(receiptPath, "utf8")) + : null; + const unique = receipt?.unique ?? randomUUID().replaceAll("-", ""); + const state = `/app/artifacts/incoming-live-${unique}`; + if (!resume) await mkdir(state, { mode: 0o700 }); + const db = await openDatabase({ + backend: "sqlite", + path: `${state}/authority.sqlite`, + }); + t.after(() => db.close()); + const mail = createMailFeature({ + outbox: createMailOutbox(db), + transport: createSmtpMailTransport({ host: "mail-capture", port: 2525 }), + }); + const authentication = await createBetterAuthAuthentication({ + db, + config, + mail, + }); + const email = `arrival-${unique}@example.com`; + const request = receipt?.request ?? { + headers: { origin: config.issuer }, + body: {}, + }; + async function freshCode() { + const since = Date.now(); + await authentication.sendSignInCode(email); + return ( + await waitForMailpitCode({ + recipient: email, + since, + baseUrl: access.mailpitUrl, + }) + ).code; + } + if (!resume) { + const login = await authentication.verifySignInCode({ + email, + otp: await freshCode(), + }); + assert.equal(login.ok, true); + const cookies = []; + login.commitCookies({ + append: (_name, value) => cookies.push(value.split(";")[0]), + }); + request.headers.cookie = cookies.join("; "); + } + const principal = await authentication.requireSession(request); + assert.equal(principal.emailVerified, true); + const browserFlow = createBrowserFlow({ + db, + config, + provider: { deviceManager: { load: async () => ({ deviceId: unique }) } }, + }); + request.body.csrf = (await browserFlow.loadBrowser(request)).csrf; + const accounts = await createAccounts({ db, config }); + const storage = accounts.storage; + const arrivals = createArrivalStorage(db, config.pds, { + readAccount: (did) => storage.getByDid(did), + readBinding: (did) => storage.getVerifiedBinding(did), + reserveEmailClaim: (...args) => storage.reserveEmail(...args), + reserveHandleClaim: (...args) => storage.reserveHandle(...args), + recordSavedUserBinding: (did, userId) => + db.insert( + "account_bindings", + { did, user_id: userId }, + { ignoreConflict: true }, + ), + insertPlacedAccount: (input) => + storage.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 composed = await composeIncomingArrival({ + db, + arrivals, + config, + accounts, + authentication, + browserFlow, + }); + if (resume) { + assert.equal(receipt.project, access.project); + assert.ok(process.env.INCOMING_DISPATCHER_EXIT_REFERENCE); + assert.ok(process.env.INCOMING_UPSTREAM_DRAIN_REFERENCE); + const store = createOperationOwnershipStore(db); + const attempt = await store.pendingExternal(`arrival:${receipt.did}`); + assert.ok(attempt); + await store.approveRecovery({ + operationId: attempt.operationId, + externalAttemptId: attempt.id, + executionAttemptId: attempt.executionAttemptId, + target: attempt.target, + dispatcherIsolationReference: + process.env.INCOMING_DISPATCHER_EXIT_REFERENCE, + upstreamDrainReference: process.env.INCOMING_UPSTREAM_DRAIN_REFERENCE, + action: "observe", + }); + let writes = 0; + const originalFetch = globalThis.fetch; + globalThis.fetch = async (url, options) => { + if (/createAccount|reserveSigningKey/.test(new URL(url).pathname)) + writes++; + return originalFetch(url, options); + }; + t.after(() => { + globalThis.fetch = originalFetch; + }); + assert.equal( + (await composed.reconcileArrival(request, receipt.operationId)).state, + "pending", + ); + assert.ok(await storage.getVerifiedBinding(receipt.did)); + assert.equal(writes, 0); + const aggregate = await arrivals.readArrivalAggregate( + receipt.operationId, + principal.userId, + ); + assert.equal( + String(await cidForCbor(await accounts.plcClient.getLastOp(receipt.did))), + aggregate.signedOperations.find( + (item) => item.kind === "destination-move", + ).cid, + ); + assert.equal((await arrivals.readArrivalAccess(receipt.did)).bound, true); + t.diagnostic( + JSON.stringify({ + fault, + approvedObserveRecovery: true, + boundPending: true, + duplicateCreation: false, + newReservation: false, + }), + ); + return; + } + async function rpc(origin, method, { token, body, params } = {}) { + const url = new URL(`/xrpc/${method}`, origin); + for (const [key, value] of Object.entries(params ?? {})) + url.searchParams.set(key, value); + const emptyProcedure = + method === "com.atproto.identity.requestPlcOperationSignature"; + const response = await fetch(url, { + method: emptyProcedure || body !== undefined ? "POST" : "GET", + headers: { + ...(token ? { authorization: `Bearer ${token}` } : {}), + ...(body === undefined ? {} : { "content-type": "application/json" }), + }, + ...(body === undefined ? {} : { body: JSON.stringify(body) }), + redirect: "error", + signal: AbortSignal.timeout(15_000), + }); + if (!response.ok) + throw new Error(`Live ${method} failed status ${response.status}`); + const text = await response.text(); + return text.trim() ? JSON.parse(text) : {}; + } + const description = await rpc( + access.sourceUrl, + "com.atproto.server.describeServer", + ); + const sourceHandle = `s${unique.slice(0, 16)}${description.availableUserDomains[0]}`; + const destinationHandle = `d${unique.slice(0, 16)}${config.handleDomains[0]}`; + assert.notEqual(sourceHandle, destinationHandle); + const sourceEmail = `source-${unique}@example.com`; + const source = await rpc( + access.sourceUrl, + "com.atproto.server.createAccount", + { + body: { + email: sourceEmail, + password: `Live-${randomUUID()}!`, + handle: sourceHandle, + }, + }, + ); + const prepared = await composed.prepareArrival(request, await freshCode(), { + did: source.did, + handle: destinationHandle, + }); + assert.equal(prepared.sourceEndpoint, access.sourceUrl); + const saved = await arrivals.readArrival( + prepared.operationId, + principal.userId, + ); + assert.equal(saved.source.alsoKnownAs[0], `at://${sourceHandle}`); + const credential = async (method) => + `Bearer ${(await rpc(access.sourceUrl, "com.atproto.server.getServiceAuth", { token: source.accessJwt, params: { aud: config.serviceDid, lxm: method } })).token}`; + // Obtain both source-signed credentials before destination key cutover. + const handoffMethod = "com.atproto.identity.submitPlcOperation"; + const creationMethod = "com.atproto.server.createAccount"; + const handoffCredential = await credential(handoffMethod); + const creationCredential = await credential(creationMethod); + const since = Date.now(); + await rpc( + access.sourceUrl, + "com.atproto.identity.requestPlcOperationSignature", + { token: source.accessJwt }, + ); + const confirmation = await waitForStockPlcMessage({ + recipient: sourceEmail, + since, + excludeIds: [], + baseUrl: access.mailpitUrl, + signal: t.signal, + }); + const signed = await rpc( + access.sourceUrl, + "com.atproto.identity.signPlcOperation", + { + token: source.accessJwt, + body: { + token: confirmation.token, + rotationKeys: prepared.handoff.rotationKeys, + alsoKnownAs: prepared.handoff.alsoKnownAs, + verificationMethods: prepared.handoff.verificationMethods, + services: prepared.handoff.services, + }, + }, + ); + const admit = (method, body, presentation) => + composed.admitIncoming(request, { + operationId: prepared.operationId, + method, + body, + presentation, + arrivalCode: prepared.arrivalCode, + }); + await admit( + handoffMethod, + { operation: signed.operation }, + handoffCredential, + ); + await composed.continueHandoff(request, prepared.operationId); + await admit( + creationMethod, + { handle: destinationHandle }, + creationCredential, + ); + const calls = []; + const originalFetch = globalThis.fetch; + let discarded = false; + globalThis.fetch = async (url, options) => { + const response = await originalFetch(url, options); + const method = new URL(url).pathname.split("/").at(-1); + if (String(url).startsWith(prepared.destinationEndpoint)) { + const binding = await storage.getVerifiedBinding(source.did); + calls.push({ method, status: response.status, bound: Boolean(binding) }); + if ( + await discardAppliedArrivalResponse({ + fault, + method, + response, + discarded, + }) + ) { + discarded = true; + throw new Error("Controlled applied response discard"); + } + } + return response; + }; + t.after(() => { + globalThis.fetch = originalFetch; + }); + if (fault !== "normal") { + await assert.rejects( + composed.continueCreation(request, prepared.operationId), + ); + assert.equal(discarded, true); + assert.equal(await storage.getVerifiedBinding(source.did), null); + const effectCount = calls.filter((item) => + /createAccount|updateSubjectStatus/.test(item.method), + ).length; + await assert.rejects( + composed.reconcileArrival(request, prepared.operationId), + { code: "OperationRecoveryRequired" }, + ); + assert.equal( + calls.filter((item) => + /createAccount|updateSubjectStatus/.test(item.method), + ).length, + effectCount, + ); + await writeFile( + receiptPath, + JSON.stringify({ + project: access.project, + unique, + request, + did: source.did, + operationId: prepared.operationId, + }), + { mode: 0o600 }, + ); + t.diagnostic( + JSON.stringify({ + fault, + appliedResponseDiscarded: true, + unbound: true, + automaticRetryBlocked: true, + operatorRecovery: "pending-owned-worker-stop-and-upstream-drain", + }), + ); + return; + } + const result = await composed.continueCreation(request, prepared.operationId); + assert.equal(result.state, "pending"); + const aggregate = await arrivals.readArrivalAggregate( + prepared.operationId, + principal.userId, + ); + const head = await accounts.plcClient.getLastOp(source.did); + assert.equal( + String(await cidForCbor(head)), + aggregate.signedOperations.find((item) => item.kind === "destination-move") + .cid, + ); + assert.ok(await storage.getVerifiedBinding(source.did)); + assert.ok( + calls.some( + (item) => + item.method === "com.atproto.admin.getAccountInfo" && + item.status === 200 && + !item.bound, + ), + ); + assert.ok( + calls.some( + (item) => + item.method === "com.atproto.admin.updateSubjectStatus" && + item.status === 200 && + !item.bound, + ), + ); + const before = calls.filter((item) => + /createAccount|reserveSigningKey/.test(item.method), + ).length; + await composed.continueCreation(request, prepared.operationId); + assert.equal( + calls.filter((item) => /createAccount|reserveSigningKey/.test(item.method)) + .length, + before, + ); + const target = config.pds.find( + (item) => item.url === prepared.destinationEndpoint, + ); + const status = await originalFetch( + new URL( + `/xrpc/com.atproto.admin.getAccountInfo?did=${encodeURIComponent(source.did)}`, + target.url, + ), + { + headers: { + authorization: `Basic ${Buffer.from(`admin:${target.adminPassword}`).toString("base64")}`, + }, + signal: AbortSignal.timeout(15_000), + }, + ); + assert.equal(status.status, 200); + assert.ok((await status.json()).deactivatedAt); + t.diagnostic( + JSON.stringify({ + source: access.sourceUrl, + target: target.url, + sourceExportOrigin: prepared.sourceEndpoint, + adminBeforeBind: calls.filter((item) => + item.method.startsWith("com.atproto.admin."), + ), + inactive: true, + boundPending: true, + }), + ); +} diff --git a/tests/support/helpers/incoming-arrival-restart.mjs b/tests/support/helpers/incoming-arrival-restart.mjs new file mode 100644 index 00000000..f604b3b2 --- /dev/null +++ b/tests/support/helpers/incoming-arrival-restart.mjs @@ -0,0 +1,610 @@ +import assert from "node:assert/strict"; +import { readFileSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { generateKeyPairSync } from "node:crypto"; +import { Secp256k1Keypair } from "@atproto/crypto"; +import { cidForCbor } from "@atproto/common"; +import { createServiceJwt } from "@atproto/xrpc-server"; +import * as plc from "@did-plc/lib"; +import { DomainError } from "../../../dist/src/accounts/errors.js"; +import { PlcError } from "../../../dist/src/plc/errors.js"; +import { openDatabase } from "../../../dist/src/database/connection.js"; +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 { createOperationOwnership } from "../../../dist/src/accounts/operation-ownership.js"; +import { Secp256k1MigrationPlcSigner } from "../../../dist/src/plc/signing.js"; +import { composeIncomingArrival } from "../../../dist/src/compose-incoming-arrival.mjs"; +import { createInvites } from "../../../dist/src/features/account-registration/invites.mjs"; +import { + incomingCreationMethod, + incomingHandoffMethod, +} from "../../../dist/src/features/external-migration/incoming-authorization.js"; +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, observationDelay = "0"] = process.argv.slice(2); +const journalPath = join(directory, "remote.json"); +const save = (value) => + writeFileSync(journalPath, JSON.stringify(value), { mode: 0o600 }); +const load = () => JSON.parse(readFileSync(journalPath, "utf8")); +const change = (work) => { + const value = load(); + work(value); + save(value); + return value; +}; +let stopping = false; +let takeoverReady = false; +const stop = async (boundary) => { + 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; + }); + } + assert.ok(process.channel); + process.channel.ref(); + process.send({ boundary, pid: process.pid }); + await new Promise(() => {}); +}; +const endpoint = "https://destination.example.test"; +const email = "destination@example.test"; +const handle = "destination.example.test"; +const userId = "destination-user"; +const hosts = [ + { id: "pds1", url: endpoint, did: "did:web:destination.example.test" }, +]; +const db = await openDatabase({ + backend: "sqlite", + path: join(directory, "authority.sqlite"), +}); +let source; +if (phase === "initial") { + source = await Secp256k1Keypair.create(); + const recovery = await Secp256k1Keypair.create(); + const hot = await Secp256k1Keypair.create({ exportable: true }); + const repository = await Secp256k1Keypair.create(); + const predecessor = await plc.signOperation( + plc.formatAtprotoOp({ + signingKey: source.did(), + handle, + pds: "https://source.example.test", + rotationKeys: [recovery.did(), source.did()], + prev: null, + }), + recovery, + ); + const did = await plc.didForCreateOp(predecessor); + save({ + did, + repository: repository.did(), + hot: Buffer.from(await hot.export()).toString("hex"), + audit: [ + { + did, + operation: predecessor, + cid: String(await cidForCbor(predecessor)), + nullified: false, + createdAt: new Date().toISOString(), + }, + ], + counts: { + reserve: 0, + create: 0, + pause: 0, + sign: 0, + handoff: 0, + credentials: 0, + }, + moves: [], + actor: null, + }); + await verifiedUser(db, userId, email); +} +const initialRemote = load(); +const storage = createAccountStorage(db, hosts); +const arrivals = createArrivalStorage(db, hosts, { + readAccount: (did) => storage.getByDid(did), + readBinding: (did) => storage.getVerifiedBinding(did), + reserveEmailClaim: (...args) => storage.reserveEmail(...args), + reserveHandleClaim: (...args) => storage.reserveHandle(...args), + recordSavedUserBinding: (did, owner) => + db.insert( + "account_bindings", + { did, user_id: owner }, + { ignoreConflict: true }, + ), + insertPlacedAccount: (input) => + storage.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 store = createOperationOwnershipStore(db); +const acquire = store.acquire; +store.acquire = async (...args) => { + const claim = await acquire(...args); + change((remote) => { + remote.lastClaim = claim; + }); + if (takeoverReady) await stop("lease-takeover"); + return claim; +}; +const ownership = createOperationOwnership({ + store, + heartbeatMs: 0, +}); +const signer = await Secp256k1MigrationPlcSigner.fromHex(initialRemote.hot); +const originalSign = signer.signArrivalMove.bind(signer); +signer.signArrivalMove = async (...args) => { + change((remote) => { + remote.counts.sign++; + if (cut === "actor-during-sign") + remote.actor = { + did: remote.did, + handle, + indexedAt: new Date().toISOString(), + }; + }); + return originalSign(...args); +}; +for (const [method, boundary] of [ + ["recordReservationResult", "key-response-lost"], + ["recordSignedOperation", "saved-move"], + ["settleArrivalAttempt", "deactivated-before-bind"], +]) { + const original = arrivals[method]; + arrivals[method] = async (...args) => { + const result = await original(...args); + if ( + method === "recordReservationResult" || + (method === "recordSignedOperation" && + args[2].kind === "destination-move") || + (method === "settleArrivalAttempt" && args[2].step === "incoming-pause") + ) + await stop(boundary); + return result; + }; +} +// Transaction wrappers stop only after the physical authority commit, not inside it. +const transact = db.transact.bind(db); +let depth = 0; +db.transact = async (work) => { + depth++; + let result; + try { + result = await transact(work); + } finally { + depth--; + } + if (depth === 0 && phase === "initial") { + const rows = await query(db, "SELECT * FROM arrival_signed_operations"); + if (rows.some((row) => row.kind === "handoff")) + await stop("signed-handoff"); + if ((await query(db, "SELECT * FROM account_bindings")).length) + await stop("binding-response-lost"); + } + return result; +}; +class ControlledObservationOutage extends Error { + code = "FixtureObservationUnavailable"; +} +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") + throw Object.assign(new Error("UnexpectedCodedObservationFailure"), { + code: "UnexpectedFixtureFailure", + }); + if (phase === "resume" && cut === "uncertain") + throw new ControlledObservationOutage("ControlledObservationUnavailable"); + return load().audit; + }, + getLastOp: async () => load().audit.at(-1).operation, + getDocument: async () => + plc.formatDidDoc({ + did: initialRemote.did, + ...plc.normalizeOp(load().audit.at(-1).operation), + }), + sendOperation: async (did, operation) => { + change((remote) => { + remote.counts.handoff++; + remote.audit.push({ + did, + operation, + cid: null, + nullified: false, + createdAt: new Date().toISOString(), + }); + }); + const cid = String(await cidForCbor(operation)); + change((remote) => { + remote.audit.at(-1).cid = cid; + }); + await stop("handoff-observed"); + }, +}; +globalThis.fetch = async (url, options) => { + const method = new URL(url).pathname.split("/").at(-1); + if (method.endsWith("reserveSigningKey")) { + change((remote) => { + remote.counts.reserve++; + }); + await stop("intent-response-missing"); + return Response.json({ signingKey: load().repository }); + } + if (method.endsWith("getAccountInfo")) + return load().actor + ? Response.json(load().actor) + : Response.json({ error: "NotFound" }, { status: 404 }); + if (method.endsWith("createAccount")) { + const operation = JSON.parse(options.body).plcOp; + const saved = ( + await query( + db, + "SELECT * FROM arrival_signed_operations WHERE kind = 'destination-move'", + ) + )[0]; + assert.deepEqual(operation, JSON.parse(saved.operation)); + const cid = String(await cidForCbor(operation)); + change((remote) => { + remote.counts.create++; + remote.moves.push(JSON.stringify(operation)); + remote.audit.push({ + did: remote.did, + operation, + cid, + nullified: false, + createdAt: new Date().toISOString(), + }); + if (cut !== "move-without-backend") + remote.actor = { + did: remote.did, + handle, + indexedAt: new Date().toISOString(), + }; + }); + await stop( + cut === "move-without-backend" + ? "move-without-backend" + : "creation-response-lost", + ); + return Response.json({ + did: initialRemote.did, + handle, + accessJwt: "discarded", + refreshJwt: "discarded", + }); + } + assert.ok(method.endsWith("updateSubjectStatus")); + change((remote) => { + remote.counts.pause++; + remote.actor.deactivatedAt = new Date().toISOString(); + }); + await stop("deactivation-lost"); + return Response.json({}); +}; +const principal = { + userId, + email, + emailVerified: true, + sessionId: "fixture", + kind: "better-auth", + authenticatedAt: new Date(), +}; +const config = { + inviteCodeRequired: true, + pds: hosts, + issuer: "https://entryway.example.test", + clientUrl: "https://client.example.test", + serviceDid: "did:web:entryway.example.test", + betterAuthSecret: "generated-fixture-only", + jwtJwk: generateKeyPairSync("ec", { + namedCurve: "secp256k1", + }).privateKey.export({ format: "jwk" }), +}; +const composed = await composeIncomingArrival({ + db, + arrivals, + config, + accounts: { + ownership, + storage, + get: (did) => storage.get(did), + plcClient: client, + plcSigner: signer, + }, + authentication: { + requireSession: async () => { + if (phase === "resume-unexpected-gate") + throw new TypeError("UnexpectedPreapprovalFailure"); + if (phase === "resume-spoofed-gate") + throw Object.assign( + new Error( + "An external account change is pending. Retry after the operator verifies recovery.", + ), + { code: "OperationRecoveryRequired" }, + ); + return principal; + }, + verifySignInCode: async () => ({ ok: true, principal }), + }, + browserFlow: { loadBrowser: async () => ({}), checkCsrf: () => {} }, +}); +const snapshot = async () => { + const saved = (await query(db, "SELECT * FROM arrivals"))[0]; + return { + aggregate: saved + ? await arrivals.readArrivalAggregate(saved.operation_id, userId) + : null, + invites: await db.list("entryway:invites"), + operations: await query(db, "SELECT * FROM authority_operations"), + claim: load().lastClaim, + bindings: await query(db, "SELECT * FROM account_bindings"), + external: await store.pendingExternal(`arrival:${initialRemote.did}`), + counts: load().counts, + head: load().audit.at(-1).cid, + currentKey: + load().audit.at(-1).operation.type === "plc_tombstone" + ? null + : plc.normalizeOp(load().audit.at(-1).operation).verificationMethods + ?.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; + 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") { + const prepared = await composed.prepareArrival({}, "fixture-proof", { + did: initialRemote.did, + handle, + }); + const token = async (method) => { + change((remote) => { + remote.counts.credentials++; + }); + return `Bearer ${await createServiceJwt({ iss: initialRemote.did, aud: config.serviceDid, lxm: method, keypair: source })}`; + }; + const operation = await plc.signOperation(prepared.handoff, source); + await composed.admitIncoming( + {}, + { + operationId: prepared.operationId, + method: incomingHandoffMethod, + body: { operation }, + presentation: await token(incomingHandoffMethod), + arrivalCode: prepared.arrivalCode, + }, + ); + const invites = await createInvites({ + db, + config, + accounts: { get: async () => null }, + }); + const { code } = await invites.createInviteCode({ useCount: 1 }); + await composed.admitIncoming( + {}, + { + operationId: prepared.operationId, + method: incomingCreationMethod, + body: { handle, inviteCode: code }, + presentation: await token(incomingCreationMethod), + arrivalCode: prepared.arrivalCode, + }, + ); + if (["divergent", "tombstone"].includes(cut)) { + const hot = await Secp256k1Keypair.import(initialRemote.hot); + const previous = load().audit.at(-1); + const descendant = await plc.signOperation( + cut === "tombstone" + ? { type: "plc_tombstone", prev: previous.cid } + : { + ...prepared.handoff, + prev: previous.cid, + alsoKnownAs: ["at://other.example.test"], + }, + hot, + ); + const cid = String(await cidForCbor(descendant)); + change((remote) => { + remote.audit.push({ + did: remote.did, + operation: descendant, + cid, + nullified: false, + createdAt: new Date().toISOString(), + }); + }); + } + await stop( + ["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"); + } else if (phase === "inspect") { + process.send({ pid: process.pid, snapshot: await snapshot() }); + } else { + const before = await snapshot(); + let gated = false; + let gateEvidence = null; + if (before.external && cut !== "move-without-backend") { + assert.equal(before.external.state, "dispatched"); + assert.equal(before.external.result, null); + assert.equal(before.external.recovery, null); + await assert.rejects( + composed.reconcileArrival({}, before.aggregate.arrival.operationId), + (error) => { + assert.ok( + error instanceof DomainError, + `Expected error instanceof DomainError: ${error.message}`, + ); + assert.equal(error.code, "OperationRecoveryRequired"); + assert.equal( + error.message, + "An external account change is pending. Retry after the operator verifies recovery.", + ); + return true; + }, + ); + const blocked = await snapshot(); + assert.deepEqual(blocked.external, before.external); + for (const field of [ + "counts", + "aggregate", + "invites", + "bindings", + "head", + "currentKey", + ]) + assert.deepEqual(blocked[field], before[field]); + gated = true; + const proof = JSON.parse( + readFileSync(join(directory, "stopped.json"), "utf8"), + ); + assert.equal(proof.stopped, true); + assert.equal(proof.signal, "SIGKILL"); + assert.equal(proof.boundary, cut); + assert.throws(() => process.kill(proof.pid, 0), { code: "ESRCH" }); + await store.approveRecovery({ + operationId: before.external.operationId, + externalAttemptId: before.external.id, + executionAttemptId: before.external.executionAttemptId, + target: before.external.target, + dispatcherIsolationReference: `exited-child:${proof.pid}`, + upstreamDrainReference: `synchronous-durable-mock-drained-at:${proof.boundary}:pid:${proof.pid}`, + action: "observe", + }); + const approved = await snapshot(); + assert.equal(approved.external.id, before.external.id); + assert.equal(approved.external.state, "recovery-approved"); + assert.equal(approved.external.recovery.action, "observe"); + assert.deepEqual(approved.counts, before.counts); + gateEvidence = { + code: "OperationRecoveryRequired", + unresolvedState: blocked.external.state, + unchangedBeforeApproval: true, + killedPid: proof.pid, + signal: proof.signal, + boundary: proof.boundary, + dispatcherIsolationReference: + approved.external.recovery.dispatcherIsolationReference, + upstreamDrainReference: + approved.external.recovery.upstreamDrainReference, + approvedState: approved.external.state, + }; + } + let outcome; + try { + outcome = await composed.reconcileArrival( + {}, + before.aggregate.arrival.operationId, + ); + } catch (error) { + if (cut === "uncertain" && error instanceof ControlledObservationOutage) { + assert.equal(error.code, "FixtureObservationUnavailable"); + assert.equal(error.message, "ControlledObservationUnavailable"); + } else if ( + !( + (cut === "divergent" || cut === "move-without-backend") && + error instanceof DomainError && + error.code === "OperationRecoveryRequired" + ) && + !( + cut === "tombstone" && + error instanceof PlcError && + error.code === "InvalidCustodyObservation" + ) + ) + throw error; + outcome = { code: error.code, message: error.message }; + if (cut === "move-without-backend") { + assert.equal( + error.message, + "The exact move is published without a backend; retain the reservation for recovery", + ); + const blocked = await snapshot(); + assert.deepEqual(blocked.external, before.external); + assert.equal(blocked.external.state, "dispatched"); + for (const field of [ + "counts", + "aggregate", + "invites", + "bindings", + "head", + "currentKey", + ]) + assert.deepEqual(blocked[field], before[field]); + } + } + 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", + }); + } + process.send({ + pid: process.pid, + gated, + gateEvidence, + outcome, + before, + snapshot: await snapshot(), + }); + } +} catch (error) { + if (cut === "actor-during-sign" && phase === "initial") + process.send({ + pid: process.pid, + outcome: { code: error.code }, + snapshot: await snapshot(), + }); + else throw error; +} finally { + await db.close(); +} 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);