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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 82 additions & 0 deletions .changeset/incoming-migration-public-api.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
---
"hypercerts-entryway": minor
---

Entryway now accepts an existing account from an external PDS. Earlier incoming
changes shipped dormant; this release mounts the whole flow, so the lifecycle,
tracked-credential and activation behavior they describe is now reachable.
It does not certify that an account's data transferred completely, and it adds
no schema change or configuration key. The routes are mounted on every
deployment (single-node SQLite, multi-node, and deployments with no migration
intent) with no configuration key or opt-out. No live public
journey, contracts group or stock-PDS callback proof has been run for this
change; it is covered by unit and in-process application tests only.

What operators and users now see:

- **Browser surfaces.** `GET /incoming` and `POST /incoming/prepare`, `/renew`,
`/cancel`, `/recover`, `/activate`, `/resume` and `/code`. Each needs the
verified browser session, the same-origin CSRF token and, except `/resume`,
`/code` and the read-only page, a fresh destination email code. The body is
strict JSON (or a form), the same-origin check runs before any budget is spent, and an unknown field is `InvalidRequest`. Another user's
operation and an unknown one are the same `AccountNotFound` 404. Responses are
`Cache-Control: no-store`. The arrival code is shown once and only its hash is
stored.
- **Tool surfaces (standard XRPC).** `com.atproto.identity.submitPlcOperation`
and `com.atproto.server.createAccount` are incoming only when the
`Entryway-Arrival-Code` header is present, and then are never handled as
hosted-account or managed movement. They also need a source service JWT bound
to that method, to Entryway's DID and to the arrival's DID. Without the header
those routes behave as before. `createAccount` returns the standard tracked
access and refresh credentials only after the account is bound; its supported
body is `handle` plus optional `did`, `email` and `inviteCode`. Other stock
fields, including `password`, are rejected with `InvalidRequest`, so an
unmodified stock tool that sends `password` does not work (pending owner
decision). `refreshSession` and `activateAccount` serve a tracked
arrival credential and otherwise fall through unchanged, after one arrival
lookup on every such request (pending owner decision). Once a migration is
finished, a later ordinary deactivation and reactivation use the ordinary route.
- **Proposed, awaiting owner decision:** the tool surfaces carry no cookie, so
the presented current arrival code selects the arrival and the user saved on
it. This is one bounded resolution that may change.
- **Lost operation ID.** A repeat `/incoming/prepare` by the same saved user for
the same DID, after a valid fresh email code, keeps its existing refusal and
adds that user's own `operationId` and `version`. Never an arrival code, and
never for another user's arrival.
- **Extra surfaces.** `/incoming/resume`, `/incoming/activate`, `/incoming/code`
and the `GET /incoming` status page are not in the accepted contract (pending
owner decision).
- **Lifecycle.** An arrival code lasts 24 hours and is renewable with a fresh
email code. A prepared arrival cannot be cancelled to release its
reservations: cancel returns `OperationRecoveryRequired`. Retrying a tool
request is the same body with the same credential until it expires or the
identity moves to the destination (after that, a `createAccount` retry gets 403
`AccountMismatch` because the source key no longer verifies); later, the saved user recovers with
`/incoming/recover` (new credentials, fresh email code) or continues with
`/incoming/resume`.
- **Pending accounts.** Until activation a migrated account is paused. OAuth
authorization, account settings, signup, status, handle,
deletion and PLC operations refuse it (`MigrationPending` or an honest
page), and ordinary status changes cannot activate it. Browser email sign-in still
succeeds by design and then shows the pending page. By consumer class,
`assertPermitted` protects registration, `assertNoMigration` protects status,
handle, deletion and PLC changes, the `provisioning` status protects login,
security changes, admin and OAuth paths, and `isPending` protects the console,
consent and signup pages. A single enforced guard is follow-up work. Activation is one
operation for the saved user (fresh email code, `/incoming/activate`) and for
an authorized client (its tracked access credential on
`activateAccount`, including the stock PDS callback). The client decides when
to activate; Entryway checks identity, binding and backend state, not
repository or blob completeness, and does not stop later source writes.
- **Limits you should know.** Rotating or replacing credentials does not revoke
an access token already issued: the stock PDS accepts it until it expires
(five minutes). Request budgets reuse existing producers: 30 requests per IP
per ten minutes for each of the browser and tool groups (submit and create
share one tool bucket, so retries after `OperationRecoveryRequired` spend it), and five fresh-code
requests per ten minutes per purpose and user. New stable error codes in
failure logs: `ArrivalExpired`, `ArrivalProofRequired`, `OperationConflict`,
`OperationRecoveryRequired`.

See the [incoming migration guide](https://github.com/hypercerts-org/hypercerts-entryway/blob/main/docs/incoming-migration.md)
for the accepted contract and the open decisions. Independent public
qualification of the whole journey has not been completed.
16 changes: 14 additions & 2 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -185,8 +185,20 @@ backend state and durable operation ownership. It does not certify a final sourc
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.
required. The external-migration feature now owns the mounted incoming routes
(browser pages and strict JSON, and the tool-facing XRPC surfaces selected by the
`Entryway-Arrival-Code` header), registered explicitly through
`compose-incoming-arrival.mjs` and `app.mjs`. A pending arrival is refused by a mix of
existing checks (`assertNoMigration`, the `provisioning` status) and the explicit
predicate and action names in `accounts/pending-arrival.ts` (one enforcing caller;
a single enforced guard is follow-up work); one activation operation
serves the saved user, an authorized client and the stock PDS's forwarded
`activateAccount`. Tracked credentials are the existing legacy families, so a stock
PDS keeps accepting an already-issued access token until it expires (five minutes)
after recovery. Ordinary refresh and activate now do one arrival lookup first. The cookie-less tool resolution (arrival code selects the arrival
and its saved user) is proposed and awaits owner decision. This is not stock-PDS
public journey or recovery qualification, which has not been run; see
[incoming migration](incoming-migration.md#development-mounted-surfaces-and-pending-guard).

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
Expand Down
8 changes: 7 additions & 1 deletion docs/data-custody.md
Original file line number Diff line number Diff line change
Expand Up @@ -408,7 +408,13 @@ backend provisioning and deactivation, before transfer, so the tool can receive
destination credentials. A bound migration-pending account is not active and
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.
signup activation semantics. The routes are mounted (see
[mounted surfaces](incoming-migration.md#development-mounted-surfaces-and-pending-guard));
public qualification remains open. Custody facts that hold in the mounted code: a
source service JWT proves control of the source key for one method and is never
hosted authority, a pending DID has no hosted account for it to act on, the saved
user comes from the arrival and its browser proof and never from email alone, and
the arrival code is shown once and stored only as a hash.

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
Expand Down
Loading