Skip to content
Open
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
60 changes: 50 additions & 10 deletions docs/incoming-migration.md
Original file line number Diff line number Diff line change
Expand Up @@ -604,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 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 |
| 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 |
| Arrival is no longer actionable, or the presented arrival code is superseded, unknown or expired | `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, or renewal finds an uncertain allocation | `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
Expand Down Expand Up @@ -642,6 +642,46 @@ recoverArrival(principal, proof, {operationId, expectedVersion})
-> standard tracked credential fields
```

Implemented behavior of the first two lifecycle callables, both taking
`(request, otp, {operationId, expectedVersion})` and adapted to HTTP by plan 012.
Each validates the body after origin/CSRF and session checks but before the OTP is
verified, so a malformed body spends neither code nor budget. It then re-verifies a
fresh destination OTP and spends the existing challenge budget under `incoming-renew`
or `incoming-cancel`. A request that loses a race with a finished claim maps to its
stable outcome (an idempotent cancelled result, or `ArrivalExpired` for renewal)
rather than a lost-claim error.

Cancellation first refuses any persisted allocation, signed operation, admission,
attempt, progress or unacknowledged external attempt, then requires the canonical
PLC head to equal the saved head. That directory observation happens outside the
storage transaction. The residual risk is bounded because a pre-intent arrival has
no signed handoff or destination move, so no Entryway-signed operation can exist for
it, so a concurrent head change is necessarily client-made. A cancelled arrival is not
reconciled afterwards (`reconcileArrival` returns not found for it), so such a change
is not observed by Entryway after cancel. A retry for an already cancelled arrival returns
the saved cancelled state without a version check and completes any claim left
pending by a crash after the local cancel commit.

Renewal matches C1: it is refused with `ArrivalExpired` once the arrival is cancelled
or provisioned, and with `OperationRecoveryRequired` while the saved allocation is
uncertain. Admissions already recorded survive renewal. Continuations do not
re-verify the request digest or any credential. They check the owner, DID, method and
that the recorded code generation is at least 1 and no greater than the current one,
then dispatch only saved or freshly journaled signed facts. At admission, before any request
comparison, the presented code must be the current, unexpired code for the arrival;
a superseded, unknown or expired code fails with `ArrivalExpired` whether or not an
admission exists for that body, and neither consumes the code nor advances the
arrival version. A new
admission, such as creation after a handoff admission, therefore needs the current
code. Renewal never reserves, signs, dispatches or releases anything. Request digests
include the code generation, so an already admitted body re-submitted with the new
code can never match; C1 is silent on this case, so it stays `OperationConflict`
with a message directing the client to resume the saved arrival.

Accepted decision (proof and budget): renewal and cancellation each require a fresh
destination OTP and spend their own existing-limit buckets, `incoming-renew` and
`incoming-cancel`.

Accepted decision M1 (budgets). Arrival wiring reuses the existing limits in
[existing policy](#existing-policy-these-contracts-reuse) and adds no new numeric
budget. Reservation requests keep the existing 30-per-IP limit in
Expand Down
12 changes: 12 additions & 0 deletions src/compose-incoming-arrival.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ 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 { createArrivalLifecycle } from "./features/external-migration/manage-arrival.js";
import { createAuthenticatedArrival } from "./features/external-migration/submit-handoff.js";
import { readIncomingObservation } from "./plc/incoming-observation.js";

Expand Down Expand Up @@ -50,6 +51,15 @@ export async function composeIncomingArrival({
}).reserveSigningKey(did);
},
});
const lifecycle = createArrivalLifecycle({
arrivals,
ownership: accounts.ownership,
authentication,
checkCsrf: browserFlow.checkCsrf,
loadBrowser: browserFlow.loadBrowser,
rateLimit,
plcClient: accounts.plcClient,
});
const admission = createArrivalAdmission({ db, arrivals, invitation });
const authenticated = createAuthenticatedArrival({
arrivals,
Expand Down Expand Up @@ -111,6 +121,8 @@ export async function composeIncomingArrival({
return {
...admission,
prepareArrival,
renewArrival: lifecycle.renew,
cancelArrival: lifecycle.cancel,
admitIncoming: async (request, input) =>
authenticated.admit({
...input,
Expand Down
16 changes: 16 additions & 0 deletions src/features/external-migration/arrival-types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -174,3 +174,19 @@ export interface ArrivalAggregate {
readonly reason: string;
}[];
}

/** An admission is valid for continuation if it was recorded under a code
* generation that has existed: renewal supersedes the code for new admissions but
* never strands one already recorded. Storage records the generation only inside
* the transaction that verified the then-current code, and generations only
* increase, so a recorded value above the current one is inconsistent. */
export function isRecordedAdmissionGeneration(
admissionGeneration: number,
arrivalGeneration: number,
): boolean {
return (
Number.isSafeInteger(admissionGeneration) &&
admissionGeneration >= 1 &&
admissionGeneration <= arrivalGeneration
);
}
55 changes: 55 additions & 0 deletions src/features/external-migration/fresh-proof.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
import type {
BrowserAuthentication,
BrowserRequest,
} from "../../authentication/port.js";
import { HttpError } from "../../http/http-error.mjs";

/** One fresh destination proof for every saved-user arrival operation. The
* browser origin/CSRF check precedes any session or code work, the existing
* challenge budget is spent before the code is verified, and the verified
* identity must be exactly the saved browser principal. */
export function createFreshArrivalProof({
authentication,
checkCsrf,
loadBrowser,
rateLimit,
}: {
authentication: BrowserAuthentication;
checkCsrf: (request: BrowserRequest, browser: unknown) => void;
loadBrowser: (request: BrowserRequest) => Promise<unknown>;
rateLimit: (subject: string) => Promise<void>;
}) {
return async function requireFreshProof(
request: BrowserRequest,
otp: string,
purpose: string,
/** Input-only validation. It runs before the OTP budget or code is spent and
* reveals nothing about any saved operation. */
beforeProof?: () => void,
) {
const browser = await loadBrowser(request);
checkCsrf(request, browser);
const principal = await authentication.requireSession(request);
const proofRequired = () =>
new HttpError(
403,
"ArrivalProofRequired",
"Verify the destination email again",
);
if (!principal?.emailVerified || !otp) throw proofRequired();
beforeProof?.();
await rateLimit(`${purpose}:${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();
return identity;
};
}
Loading