Repository navigation
feat: persist incoming arrival authority (TECH-681 plan 009) #22
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
c0c0cf9
8fce736
99776cd
ce37a9e
fef8cd7
7bd9e1c
f02dc21
3afa48d
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,66 @@ | ||
| --- | ||
| "hypercerts-entryway": minor | ||
| --- | ||
|
|
||
| For operators initializing fresh state, the database schema now includes durable | ||
| storage for dormant incoming arrivals: an immutable | ||
| `{operation, incoming DID, selected PDS and endpoint}` tuple with the saved | ||
| verified user and email, a hashed 24-hour arrival authorization, conditional | ||
| persistence of the reserved public repository key, and one live arrival per DID | ||
| with completed history retained. | ||
|
|
||
| Storage and shared-claim behavior: | ||
|
|
||
| - A destination email used by an individual arrival must be unique. It is no | ||
| longer shared with another identity's claim, reservation or live arrival. | ||
| Whole-server association imports keep their existing shared-claim behaviour, | ||
| so the two paths stay explicitly distinct. | ||
| - An arrival authorization is stored only as a hash and must expire no later than | ||
| 24 hours after issue. The ceiling is enforced when the code is written and again | ||
| by a database constraint, so a reissued or shortened lifetime cannot exceed a | ||
| day and code expiry does not release destination reservations or erase progress. | ||
| - A saved public key is immutable for its arrival and is included when a valid | ||
| arrival code resolves the saved arrival. Reservation-result validation checks | ||
| the expected version and owner first: stale versions return `OperationConflict` | ||
| and lost ownership returns `OperationLeaseLost`. With current ownership and | ||
| version, saved allocation uncertainty returns `OperationRecoveryRequired` before | ||
| tuple comparison; otherwise a changed DID, host or endpoint is | ||
| `OperationConflict`. A different key for the unchanged tuple returns | ||
| `reconciliation-required` with reason `saved-key-differs`. Nothing silently | ||
| reallocates or switches placement. | ||
| - Cancellation releases local reservations only when the arrival recorded no | ||
| allocation at all. The allocation intent is saved before the destination host is | ||
| asked for a signing key, so a recorded intent whose key is not yet known already | ||
| means dispatch began or is still in flight; cancelling then requires | ||
| `OperationRecoveryRequired` and the arrival stays pending for verified recovery. | ||
| Cancellation also needs the owning operation's claim and the caller's own | ||
| no-remote-obligation and unchanged-PLC evidence; an expired lease authorizes | ||
| nothing. Local cancellation never claims remote private material was removed. | ||
| - A signed public PLC operation is journaled before it is dispatched. The | ||
| source-authorized handoff and the Entryway-signed destination move are stored | ||
| with their exact bytes, CID and kind, in the same fenced transaction that | ||
| advances the arrival, so an accepted operation is durable before directory | ||
| submission and a destination move cannot be recorded ahead of its handoff. | ||
| Recorded bytes are immutable: repeating the same operation and CID is | ||
| idempotent and changes nothing, while a different operation or CID for the same | ||
| kind is a conflict rather than an overwrite. A stale worker records nothing. | ||
| Private key material never enters this table, and no new status value is added. | ||
| - Preparation requires the actual signed source predecessor, its CID, source | ||
| public facts and approved ordered custody. The original source endpoint is | ||
| saved from those facts. Signed handoffs and moves must match that authority, | ||
| their signed CIDs and the saved destination reservation. | ||
| - Accepted admissions are immutable per method and bind the saved principal, | ||
| DID, request digest, code generation and verified credential issuer and ID. | ||
| Exact retries under current ownership do not advance the version. Creation | ||
| admission and invitation reservation can commit together; pending account | ||
| binding and invitation completion can also commit together. Bearer credentials, | ||
| arrival codes and invitation codes are not stored in arrival admissions. | ||
|
|
||
| Operators must initialize fresh state for the changed database schema. This is | ||
| not a database-upgrade procedure or a qualification of public account migration. | ||
| - Migration-pending access is derived from the current operation, not a new | ||
| account status. An arrival does not gain ordinary access or activation from | ||
| storage alone, and no readiness or completeness claim is made here. | ||
|
|
||
| No public route, remote write, credential signing or activation is added by this | ||
| change. Readiness and public exposure remain separately gated. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| --- | ||
| "hypercerts-entryway": patch | ||
| --- | ||
|
|
||
| For operators managing incoming migrations, active arrivals now reserve their destination email, handle and DID against competing account and migration writes. Existing claims also prevent a conflicting arrival from starting. Expired arrival codes do not release pending reservations; the arrival's own validated binding remains atomic, and established shared-primary-email associations remain supported. | ||
|
|
||
| Cancellation now refuses persisted remote obligations, including a signed source handoff even when no repository-key allocation exists. Keep these arrivals pending for verified recovery rather than releasing their claims. No configuration change is required. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| sonar.cpd.exclusions=src/database/schema/postgresql.ts,src/database/schema/sqlite.ts |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,5 @@ | ||
| import { randomUUID } from "node:crypto"; | ||
| import { and, asc, desc, eq, ne, sql } from "drizzle-orm"; | ||
| import { and, asc, desc, eq, ne, or, sql } from "drizzle-orm"; | ||
| import { | ||
| assertAccountShape, | ||
| assertBindingMatchesAccount, | ||
|
|
@@ -187,6 +187,38 @@ export function createAccountStorage( | |
| return null; | ||
| return { userId: user.id, email: user.email, authenticatedAt }; | ||
| }; | ||
| const assertNoActiveArrival = async ( | ||
| email: string, | ||
| did?: string, | ||
| handle?: string, | ||
| ) => { | ||
| const arrivals = await db.read("arrivals", { | ||
| where: and( | ||
| eq(t.arrivals.active, 1), | ||
| or( | ||
| eq(sql`lower(${t.arrivals.email})`, normalizeEmail(email)), | ||
| did ? eq(t.arrivals.did, did) : undefined, | ||
| handle | ||
| ? eq(sql`lower(${t.arrivals.handle})`, handle.trim().toLowerCase()) | ||
| : undefined, | ||
| ), | ||
| ), | ||
| }); | ||
| if (arrivals.some((arrival) => arrival.did === did)) | ||
| throw new DomainError( | ||
| "IdentityConflict", | ||
| 409, | ||
| "Identity has a pending arrival", | ||
| ); | ||
| if (arrivals.some((arrival) => arrival.email === normalizeEmail(email))) | ||
| throw new DomainError( | ||
| "EmailNotAvailable", | ||
| 409, | ||
| "Email address is reserved", | ||
| ); | ||
| if (arrivals.length > 0) | ||
| throw new DomainError("HandleNotAvailable", 409, "Handle is reserved"); | ||
| }; | ||
| const reserveEmail = async ( | ||
| email: string, | ||
| did: string, | ||
|
|
@@ -195,6 +227,7 @@ export function createAccountStorage( | |
| ) => | ||
| db.transact(async () => { | ||
| email = normalizeEmail(email); | ||
| await assertNoActiveArrival(email, did); | ||
| const [claims, reservations] = await Promise.all([ | ||
| db.read("email_claims", { | ||
| where: eq(sql`lower(${t.email_claims.email})`, email), | ||
|
|
@@ -242,6 +275,18 @@ export function createAccountStorage( | |
| const reserveHandle = async (handle: string, did: string) => | ||
| db.transact(async () => { | ||
| handle = handle.trim().toLowerCase(); | ||
| const arrival = await one( | ||
| "arrivals", | ||
| and( | ||
| eq(t.arrivals.active, 1), | ||
| or( | ||
| eq(sql`lower(${t.arrivals.handle})`, handle), | ||
| eq(t.arrivals.did, did), | ||
| ), | ||
| )!, | ||
| ); | ||
| if (arrival) | ||
| throw new DomainError("HandleNotAvailable", 409, "Handle is reserved"); | ||
| const external = await one( | ||
| "migration_reservations", | ||
| eq(t.migration_reservations.handle, handle), | ||
|
|
@@ -281,6 +326,7 @@ export function createAccountStorage( | |
| assertPds(row); | ||
| try { | ||
| await db.transact(async () => { | ||
| await assertNoActiveArrival(row.email, row.did, row.handle); | ||
| const previous = ( | ||
| await db.read("accounts", { | ||
| orderBy: [desc(t.accounts.sequence)], | ||
|
|
@@ -309,6 +355,7 @@ export function createAccountStorage( | |
| assertPds(row); | ||
| try { | ||
| await db.transact(async () => { | ||
| await assertNoActiveArrival(row.email, row.did, row.handle); | ||
| const previous = await getByDid(row.did); | ||
| if (!previous) | ||
| throw new DomainError("AccountNotFound", 404, "Account not found"); | ||
|
|
@@ -499,6 +546,7 @@ export function createAccountStorage( | |
| "Recent verified owner session required", | ||
| ); | ||
| const email = normalizeEmail(owner.email); | ||
| await assertNoActiveArrival(email, input.did, input.handle); | ||
| const [emailClaims, emailReservations] = await Promise.all([ | ||
| db.read("email_claims", { | ||
| where: eq(sql`lower(${t.email_claims.email})`, email), | ||
|
|
@@ -618,14 +666,24 @@ export function createAccountStorage( | |
| ); | ||
| }, | ||
| async hasPendingExternalMigration(did) { | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Still open at
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Updated in |
||
| return Boolean( | ||
| await one( | ||
| const [adopting, arrival] = await Promise.all([ | ||
| one( | ||
| "migration_reservations", | ||
| and( | ||
| eq(t.migration_reservations.did, did), | ||
| ne(t.migration_reservations.state, "complete"), | ||
| )!, | ||
| ), | ||
| one( | ||
| "arrivals", | ||
| and(eq(t.arrivals.did, did), eq(t.arrivals.active, 1))!, | ||
| ), | ||
| ]); | ||
| return Boolean(adopting || arrival); | ||
| }, | ||
| async hadPublishedPlcOperation(did) { | ||
| return Boolean( | ||
| await one("custody_operations", eq(t.custody_operations.did, did)), | ||
| ); | ||
| }, | ||
| async listAccounts() { | ||
|
|
@@ -659,7 +717,7 @@ export function createAccountStorage( | |
| and(eq(t.handle_claims.handle, handle), eq(t.handle_claims.did, did))!, | ||
| ); | ||
| }, | ||
| async finalizeImportedAccount(input) { | ||
| async bindProvisionedArrival(input) { | ||
| return db.transact(async () => { | ||
| const reservation = await one( | ||
| "migration_reservations", | ||
|
|
@@ -735,7 +793,7 @@ export function createAccountStorage( | |
| return row; | ||
| }); | ||
| }, | ||
| async activateImportedAccount(input) { | ||
| async activateBoundArrival(input) { | ||
| return db.transact(async () => { | ||
| const reservation = await one( | ||
| "migration_reservations", | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Renaming the whole-server
finalizeImportedAccount/activateImportedAccounttobindProvisionedArrival/activateBoundArrivalmakes them collide with the newArrivalTransactor.bindProvisionedArrival, which does something different (binds anarrivalsrow, not amigration_reservationsworkflow). Nothing in this PR needs the rename, and it touchesimport-account.tsand two test files. Please revert it, or give the arrival-side methods distinct names.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Deferred: the similarly named whole-server and arrival binding operations remain at
ce37a9e. This is a naming/maintainability concern, not a claim that the two operations are equivalent.