Skip to content

feat: add shared homeserver management - #357

Merged
pwltr merged 1 commit into
mainfrom
feat/homeserver-mgmt
Nov 9, 2026
Merged

pwltr merged 1 commit into
mainfrom
feat/homeserver-mgmt

Conversation

@pwltr

@pwltr pwltr commented Aug 3, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Closes #85

Add a shared homeserver catalog under Settings → Homeservers, with custom server names, a default for future setups, and removal of unused servers. Public keys stay read-only after saving, the built-in Synonym server remains available, and in-use servers cannot be removed.

Setup/edit discovers an existing public homeserver mapping before choosing a default and distinguishes Sign in from new signup. Freshly generated keys skip discovery and immediately select the preferred server; imported keys and later reopenings still discover unknown accounts. The bottom action is Save for label-only edits, Sign up for signup, or Sign in for reconnection. Labels can be saved independently of a valid homeserver configuration. Done on the label field dismisses the keyboard during unfinished setup rather than closing it.

Scan QR and Paste link appear below the homeserver list. Direct-signup links select the server and fill the invite, including servers absent from Settings, then return to setup for review before submission. Name drafts are preserved, unknown servers display their shortened public key, and invite codes remain transient. Synonym signups require an invite; custom servers can be tried without one and reveal invite entry when required. Accepted scan/paste input clears previous validation errors. Pasted custom invite tokens lose surrounding whitespace while retaining their exact contents. The server-selection migration warning also covers signed-out and imported accounts with a known server.

The × action confirms and signs this pubky out of this Ring installation. It revokes Ring's recorded grants while preserving server data, the public mapping, and other apps’ grants. Sign-out pauses automatic grant refreshes for this pubky, drains running work, and commits signed-out state before refreshes resume. Other pubkys remain independent. Session records include their homeserver, so previous-server grants are revoked through their own tokens; legacy sessions are matched to the current grant list or cleaned up individually. Failures on an older or unknown server do not prevent current-server sign-out: uncertain grants and Keychain secrets remain as cleanup-only records, and a toast reports incomplete cleanup. Only confirmed revocations or explicit grant-expiry errors remove those records. Current-server revocation failures still report an error and preserve credentials for retry.

The last verified server is remembered across restarts so reconnection offers Sign in without another invite. Grant refresh now saves the server returned by native sign-in before listing grants, so a changed public mapping reuses the saved session on later refreshes, including after an initial grant-list failure. If sign-in identifies a changed public mapping, Ring cleans up the temporary grant, updates the selection, and asks the user to sign in again. Sign-out also follows a changed public mapping without forced republishing. Network failures retain the remembered server; sign-in never falls back to signup. Unexpected-server grants that cannot be revoked retain their secrets and server/grant metadata for later cleanup. Cleanup-only records survive persistence and are excluded from active sessions and signed-in UI state.

Includes catalog/default persistence migrations, Settings navigation fixes, native tap-outside keyboard dismissal, and English/Spanish copy. A Podfile hook raises older resource-bundle deployment targets to React Native’s existing iOS 15.1 minimum for Xcode 27 while preserving higher targets; pod versions are unchanged.

Screen.Recording.iPhone.18.Pro.06.11.2026.at.13.16.24.mp4

Validation

  • yarn test --runInBand --silent — 469 tests passed across 47 suites, including fresh-key setup, discovery/reconnection, remembered-server mismatch recovery, sign-out/persistence, label-only edits, optional/required invites, signup-link review, and catalog migrations.
  • yarn typecheck — passed.
  • yarn lint — no errors; two existing warnings in App.tsx and MigrationProgressOverlay.tsx.
  • Formatting and git diff --check — passed.
  • Xcode 27.2 Debug simulator build and pod minimum deployment targets were previously verified with the Podfile hook.
  • Maestro coverage includes catalog add/rename/default/cancel/delete, restart persistence, signup/auth, and sign-out cancellation/reconnection. All four CI checks passed on bc61154: lint, checks, iOS E2E, and Android E2E.
  • Regression tests reproduce the review findings with mocked native responses: held sign-in and Keychain writes during sign-out, queued refreshes, independent pubkys, failed sign-out recovery, and failed grant cleanup/persistence/retry. Additional coverage models signup on A, switching to B, and sign-out against independent server grant lists, including persistence, legacy records, failed cleanup, and partial revocation retries. Additional tests cover changed-mapping sign-out, multiple failed older-server cleanups, selective Keychain retention, grant expiry versus ambiguous token errors, and Done keeping unfinished setup open. Native device timing and live multi-server cleanup have not been reproduced.
  • Squashed into one commit; verified the resulting source tree matches the tested tree.

Preservation of another app’s live session and a native upgrade from an older installed version remain manual verification gaps; mocked grant/migration tests cover their intended behavior.

Known limitations

Returning to a previously registered server that is no longer publicly mapped can still attempt signup and fail. This pre-existing limitation remains tracked in #135 and upstream pubky/pubky-homeserver#670; explicit-server sign-in/grant exchange still needs SDK/FFI/React Native support. Data does not migrate automatically between homeservers.

Import no longer automatically republishes a default mapping when discovery fails. An imported account with a missing public mapping remains unconfigured; unlike #135, this is a behavior change introduced by this PR. An explicit, user-confirmed recovery flow is deferred follow-up work; restoring unconditional publication could overwrite account state.

@pwltr
pwltr force-pushed the feat/homeserver-mgmt branch from 4f137c0 to dfb4e81 Compare November 5, 2026 12:16
@pwltr pwltr changed the title feat: homeserver mgmt feat: add shared homeserver management Nov 5, 2026
@pwltr
pwltr marked this pull request as ready for review November 5, 2026 13:57
@pwltr
pwltr force-pushed the feat/homeserver-mgmt branch 3 times, most recently from 96da58f to 4bd1748 Compare November 6, 2026 11:49

@pwltr pwltr left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed 4bd1748. One Medium candidate from static source tracing.

Medium candidate — Retain previous-server sessions until their grants are revoked. After signing up on server A and switching to B, ordinary sessions from A remain recorded without their homeserver. Sign-out on B cleans up cross-server cleanupOnly sessions and revokes grants listed by B, but then deletes all local session secrets and records, including ordinary A sessions that were not revoked. Sign-out can therefore report success while an old A token remains active and its local cleanup credentials are lost. Preserve per-server cleanup information or retain sessions until their grants are revoked. See src/utils/pubky.ts:1008–1014 and 1046–1059.

This is an unconfirmed candidate. Native server-scoped grant behavior was not independently executed; no tests or builds ran. Broader security and validation remain uncompleted while the finding is assessed or fixed. Optional verification can challenge both Quick and Deep evidence.

Review details

General review: GPT-6.1 Sol / High, independent static source review.

@coreyphillips coreyphillips left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two independent reviews.

needs changing before merge

  • Signing out after switching servers leaves earlier grants active (src/utils/pubky.ts:1056-1059)

worth doing, does not block

  • Import no longer recovers an account with no public mapping (src/utils/pubky.ts:474-476)
  • Typing a label during setup replaces Sign up or Sign in with Save (src/components/EditPubky/useEditPubkyForm.ts:123)
  • An unrevocable cleanup record blocks sign-out permanently (src/utils/pubky.ts:1008-1015)
  • Sign-out forgets the previous server's Ring grant without revoking it (src/utils/pubky.ts:1038-1056)
  • Sign-out on a changed mapping is a dead end with misleading advice (src/utils/pubky.ts:1022-1033)
  • Migration notice is hidden for keys with existing data elsewhere (src/screens/EditPubkySelectServer.tsx:29)
  • Custom invite tokens keep clipboard whitespace (src/utils/homeserverSignupInput.ts:441). parseHomeserverSignupInput tests input.trim() but returns the raw input as the invite code, and custom servers skip formatSignupToken. Pasting tok123\n into a custom server's invite flow sent "tok123\n" to signUpToHomeserver, which would surface as a rejected invite. Trim the outer whitespace and keep the rest of the token exact, which still satisfies the existing test that preserves case and punctuation.
  • Changed public mappings leave sign-out without a recovery path (src/components/EditPubky/useEditPubkyForm.ts:73-74)

nits

  • New English copy includes unused keys (src/i18n/locales/en.json). editPubkySheet.inviteCodeLabel, editPubkySheet.pkdnsLabel, editPubkySheet.pkdnsButton and homeservers.rename have no references in src. The two pkdns keys are also missing from es.json, so they look like leftovers.

the reviewers disagree, your call

  • Closes #85 leaves its health check and #135 outstanding (general). Objection: I could not verify the issue discussion or PR closing text. The code confirms no reachability check, but does not establish that this optional feature or #135 is required to close #85.

Comment thread src/utils/pubky.ts
Comment on lines +474 to +476
const lookup = await resolveHomeserver(pubky);
// A failed lookup leaves the key imported. Setup can retry discovery.
if (lookup.isErr() || !lookup.value) return savePubkyRes;

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

worth doing, does not block: Import no longer recovers an account with no public mapping

Importing a key whose _pubky record cannot be resolved now leaves it unconfigured, where main recovered it. The PR calls this a pre-existing limitation, which it is not. At importPubky the code returns as soon as the lookup is empty, so no sign-in is attempted. Setup then offers only Sign up, and submitEditPubky never falls back to sign-in. On Synonym that also means an invite for an account that already exists. I ran the same mocked scenario on both trees (lookup returns No homeserver found for this public key, first signIn fails, republish succeeds): origin/main: signIn 2, republish 1, signedUp true, homeserver set, 1 session HEAD: signIn 0, republish 0, signedUp false, homeserver '' Main's sheet had a second recovery path too: after a failed signup it called signInToHomeserver with republish when the stored server was empty or unchanged. #135 describes changing a working key's server, not this case. Non-blocking because the homeserver's user key republisher should normally keep the record resolvable. Please correct the PR text, and consider an explicit user-confirmed recovery action, since the unconditional republish was presumably removed to avoid overwriting a mapping.

needsSignup && (inviteRequired || expandedHomeserver === homeServer || Boolean(signupToken));
const nameChanged = newPubkyName.trim() !== storedName;
const connectionFieldsChanged = homeServer !== baselineHomeserver || Boolean(signupToken);
const saveNameOnly = nameChanged && (!connectionFieldsChanged || (!needsSignup && !needsSignin));

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

worth doing, does not block: Typing a label during setup replaces Sign up or Sign in with Save

On an unconfigured key, any label edit with no server or invite change makes saveNameOnly true, so submit saves the label and closes the sheet without connecting. I rendered the sheet and confirmed three cases: - Fresh Synonym key: type a label, press keyboard Done. hideSheet is called once and signup is not called. This is the natural order, because the label is the first field. On main, handleNameSubmit moved focus to the invite field. - Fresh key with a custom default server that needs no invite: Sign up becomes Save, and pressing it closes with signedUp: false. - Signed-out key with a remembered server: Sign in becomes Save, and pressing it closes without signing in. The button swap has tests, so it looks deliberate, but they do not cover the Done path or the tokenless custom default. Nothing is lost and reopening recovers, so this is non-blocking. When needsSignup or needsSignin is true and the connection is otherwise ready, Done and the primary button should connect and carry the label with them. Done on the label field during setup should not close the sheet.

Comment thread src/utils/pubky.ts Resolved
Comment thread src/utils/pubky.ts Resolved
Comment thread src/utils/pubky.ts Resolved
Comment thread src/screens/EditPubkySelectServer.tsx Resolved
Comment thread src/utils/pubky.ts Resolved
@pwltr
pwltr force-pushed the feat/homeserver-mgmt branch 2 times, most recently from 5058662 to bc83bfe Compare November 6, 2026 14:36
@pwltr

pwltr commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

Addressed the sign-out findings and smaller fixes in bc83bfe. Two review suggestions remain deliberately unchanged/deferred, detailed below.

  • Previous-server grants: fixed. New sessions record their homeserver. Sign-out revokes ordinary previous-server sessions using their own tokens; legacy records are matched to the current server's grant list or cleaned up individually. Confirmed revocations are removed individually. Uncertain records and their Keychain secrets are retained as cleanup-only rather than silently discarded. Covers the blocking finding, its duplicate, and the earlier retention review.
  • Unrevocable old sessions blocking sign-out: fixed. Cleanup failures on older/unknown servers no longer prevent current-server revocation and signed-out state. Ring retains uncertain cleanup credentials and shows an incomplete-cleanup toast. Explicit SDK errors identifying an expired grant credential allow removal; generic invalid/expired/revoked-token errors, missing Keychain secrets, and unreachable servers remain uncertain. Current-server revocation failures still report an error and preserve credentials for retry. This also addresses the latest recheck of 5058662. Thread.
  • Changed public mapping during sign-out: fixed. Sign-out follows the actual server returned by native sign-in without forced publication, cleans up prior-server grants separately, and commits the actual mapping with signed-out state. The form updates its selection, shows the changed-server toast, and offers Sign in without an invite. The misleading refresh advice is removed. Utility finding, form finding.
  • Migration warning: fixed. The selection screen checks for a configured account, stored server, or remembered server, covering signed-out/imported accounts with a known mapping and excluding fresh keys. Thread.
  • Custom invite whitespace and unused copy: fixed. Pasted/scanned opaque custom tokens lose only surrounding whitespace, preserving internal contents. Removed the unused translation keys identified in the review.
  • Label submission: Done now dismisses the keyboard during unfinished setup/reconnection rather than saving and closing the sheet. The bottom button's label-only Save remains intentional: saving a name independently of homeserver validity is an explicit product requirement. It has not been changed to always connect after a label edit. Tests cover fresh Synonym, tokenless custom-default, and remembered signed-out accounts. Thread.
  • Import recovery with no public mapping: deferred, not fixed. The PR now explicitly documents this as a regression introduced here, distinct from Error Unable to authorise after changing key's homeserver #135. Restoring unconditional default-server publication could overwrite account mappings; a separate user-confirmed recovery action remains follow-up work. Thread.
  • Closing Feature: Homeserver management #85: retained. Reachability checking is listed there as an additional consideration, and Error Unable to authorise after changing key's homeserver #135 was explicitly agreed not to block this work. Both remain outside this PR's scope.

Validation: all 465 tests across 47 suites pass, typecheck passes, formatting/diff checks pass, and lint has only the two existing warnings. Regression tests cover separate server grant lists, partial cleanup/retry, missing Keychain secrets, grant expiry versus ambiguous token errors, changed-mapping recovery, and unfinished-setup Done behavior. These use mocked native responses; live multi-server cleanup and device timing have not been independently reproduced. CI lint/checks have passed; iOS and Android E2E are still running at the time of this reply.

Posting one linked response because GitHub rejected inline replies while this account has an existing pending review; that draft review has been left untouched. Threads remain open for reviewer verification.

@pwltr
pwltr requested a review from coreyphillips November 6, 2026 15:21

@coreyphillips coreyphillips left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rechecked after the branch was rewritten, so every earlier point was verified again from scratch. Nothing blocking remains.

addressed

  • An unrevocable cleanup record blocks sign-out permanently (src/utils/pubky.ts:1008-1015). Fixed: src/utils/pubky.ts:1058-1079 no longer returns on a cleanup failure. In a scratch test with one record failing Failed to import session: expired and one missing its secret, two sign-outs both reached the current server, set signedUp false and kept both records with cleanupPending true.
  • Sign-out forgets the previous server's Ring grant without revoking it (src/utils/pubky.ts:1038-1056). Fixed: Sessions now record their server (src/utils/pubky.ts:171), and src/utils/pubky.ts:1058-1079 ends other-server sessions with their own token. A scratch test with separate grant sets for A and B left both empty after sign-out, and the SDK and homeserver sources confirm the token targets its own server and DELETE /auth/grant/session revokes the grant.
  • Sign-out on a changed mapping is a dead end with misleading advice (src/utils/pubky.ts:1022-1033). Fixed: The serverChanged advice is gone and sign-out follows the server returned by native sign-in (src/utils/pubky.ts:1023 and 1100-1112). A scratch test with stored A and signIn returning B revoked A's token through signOut, committed B as homeserver and lastKnownHomeserver, and made no republish call.
  • Migration notice is hidden for keys with existing data elsewhere (src/screens/EditPubkySelectServer.tsx:29). Fixed: src/screens/EditPubkySelectServer.tsx:29-36 now also checks the stored and remembered server. The test at tests/EditPubkyHomeservers.test.tsx:304 passes in my run for signed-out, discovered and fresh keys, and fresh keys stay excluded because their default homeserver is empty.
  • Custom invite tokens keep clipboard whitespace (src/utils/homeserverSignupInput.ts:441). Fixed: src/utils/homeserverSignupInput.ts:38 now returns input.trim(), and all scan and paste paths go through this function. The test at tests/homeserverSignupInput.test.ts:22 passes in my run with outer whitespace around a token that keeps its inner spaces.
  • New English copy includes unused keys (src/i18n/locales/en.json). Fixed: A script over both locale files found all four keys gone from src/i18n/locales/en.json and es.json. The only other new keys it could not match in src are the usedBy plurals, which i18next resolves from homeservers.usedBy.
  • Signing out after switching servers leaves earlier grants active (src/utils/pubky.ts:1056-1059). Fixed: Same change as point 4, at src/utils/pubky.ts:1050-1079. My scratch test signed up on A, then B, and sign-out left no live grants on either; with A unreachable, its record and secret stayed as cleanup-only with cleanupPending true. This used mocked native calls, not a live multi-server run.
  • Changed public mappings leave sign-out without a recovery path (src/components/EditPubky/useEditPubkyForm.ts:73-74). Fixed: The guard at src/components/EditPubky/useEditPubkyForm.ts:73-74 remains, but sign-out now learns the real server itself, and lines 227-231 move the link, selection and baseline to it so needsSignin offers Sign in without an invite. Confirmed by my store-level test and by the form test 'reports partial cleanup after sign-out and follows the public server', which passes in my run.

still open

  • Import no longer recovers an account with no public mapping (src/utils/pubky.ts:474-476). Importing a key whose _pubky record cannot be resolved now leaves it unconfigured, where main recovered it. The PR calls this a pre-existing limitation, which it is not. At importPubky the code returns as soon as the lookup is empty, so no sign-in is attempted. Setup then offers only Sign up, and submitEditPubky never falls back to sign-in. On Synonym that also means an invite for an account that already exists. I ran the same mocked scenario on both trees (lookup returns No homeserver found for this public key, first signIn fails, republish succeeds): origin/main: signIn 2, republish 1, signedUp true, homeserver set, 1 session HEAD: signIn 0, republish 0, signedUp false, homeserver '' Main's sheet had a second recovery path too: after a failed signup it called signInToHomeserver with republish when the stored server was empty or unchanged. #135 describes changing a working key's server, not this case. Non-blocking because the homeserver's user key republisher should normally keep the record resolvable. Please correct the PR text, and consider an explicit user-confirmed recovery action, since the unconditional republish was presumably removed to avoid overwriting a mapping. importPubky still returns at src/utils/pubky.ts:479 when the lookup is empty, so a key with no public mapping stays unconfigured, and your reply says this is deferred rather than fixed. The PR text is now accurate, but the recovery action is still missing.
  • Typing a label during setup replaces Sign up or Sign in with Save (src/components/EditPubky/useEditPubkyForm.ts:123). On an unconfigured key, any label edit with no server or invite change makes saveNameOnly true, so submit saves the label and closes the sheet without connecting. I rendered the sheet and confirmed three cases: - Fresh Synonym key: type a label, press keyboard Done. hideSheet is called once and signup is not called. This is the natural order, because the label is the first field. On main, handleNameSubmit moved focus to the invite field. - Fresh key with a custom default server that needs no invite: Sign up becomes Save, and pressing it closes with signedUp: false. - Signed-out key with a remembered server: Sign in becomes Save, and pressing it closes without signing in. The button swap has tests, so it looks deliberate, but they do not cover the Done path or the tokenless custom default. Nothing is lost and reopening recovers, so this is non-blocking. When needsSignup or needsSignin is true and the connection is otherwise ready, Done and the primary button should connect and carry the label with them. Done on the label field during setup should not close the sheet. Done is fixed at src/screens/EditPubkyMain.tsx:38, but src/components/EditPubky/useEditPubkyForm.ts:123 still turns a ready Sign in or tokenless Sign up into a Save that closes without connecting. The product requirement appears only in your own text and covers saving a label, not withholding the connect action once it is ready, so this needs that change or a maintainer's confirmation.
  • Closes #85 leaves its health check and #135 outstanding. Closes #85 will close the issue even though the reachability health check it listed for consideration is not implemented, and the PR does not mention dropping it. The issue's last comment also deferred this work until #135 was addressed. #135 remains open, and returning to a previous server still fails after the picker makes switching easy. Neither has to hold the merge, but the maintainer should decide on them explicitly. A follow-up issue for the health check would preserve it. Codex still sees it: The reply says '#135 was explicitly agreed not to block this work', but the supplied discussion contains no superseding agreement to verify against the issue's explicit deferral. Reachability is optional; the remaining question is whether that deferral has been lifted before retaining Closes #85.

new since the last review

worth doing, does not block

  • Refresh mints a new grant every time when stored and mapped servers differ (src/utils/pubky.ts:909)

Comment thread src/utils/pubky.ts Resolved
Add a shared homeserver catalog with default selection, setup discovery, signup-link review, and confirmed Ring sign-out. Preserve transient invites and label-only edits, recover from remembered-server mismatches, and skip discovery for newly generated keys. Serialize automatic grant refresh with sign-out, persist each session’s homeserver, and retain cleanup credentials until grant revocation is confirmed, including after server switches.

Include homeserver flow regression coverage and align iOS pod resource bundles with the existing deployment minimum.
@pwltr
pwltr force-pushed the feat/homeserver-mgmt branch from bc83bfe to bc61154 Compare November 6, 2026 15:44
@pwltr

pwltr commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

Fixed the new refresh finding in bc61154. After fallback sign-in succeeds, grant refresh now saves the actual returned homeserver and remembered server before listing grants. Later refreshes reuse that server's saved session, even if the first grant-list request failed. Existing cleanup-only records remain retained; this does not publish or republish a mapping.

Four regression cases fail against the previous code and pass with the fix: invalid, cleanup-only, or absent old-server sessions, plus a failed initial grant-list request. Five refreshes now cause one sign-in/secret write rather than five. All 469 tests pass across 47 suites; typecheck, formatting and diff checks pass. Lint reports only the two existing warnings. Fresh native CI is pending on the rewritten single commit.

The two earlier scope decisions remain as documented: missing-public-mapping import recovery is deferred; label-only Save is intentional, while Done no longer closes unfinished setup. The maintainer explicitly directed in the working session that #135 does not block this PR. No automatic mapping-recovery publication or health check was added.

@pwltr
pwltr merged commit 97bd2dd into main Nov 9, 2026
4 checks passed
@pwltr
pwltr deleted the feat/homeserver-mgmt branch November 9, 2026 14:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

2 participants