@brass-build/client 0.1.0 → 0.3.0

package/dist/client.js

@@ -1,7 +1,7 @@
-import { buildSignInUrl, buildSignedOutOfAppUrl, refreshTokens, } from './auth-flow.js';
+import { buildSignInUrl, buildSignedOutOfAppUrl, refreshTokens, revokeAppApproval, } from './auth-flow.js';
 import { decodeIdToken } from './jwt.js';
 import { createEmitter } from './emitter.js';
-import { createOpenDocument, } from './open-document.js';
+import { clearParkedDocuments, createOpenDocument, } from './open-document.js';
 import { askSchemaConflict } from './schema-conflict-dialog.js';
 import { BrassError } from './errors.js';
 import { createHostedUiLauncher, trackHostedUiActivations, } from './hosted-ui.js';
@@ -20,6 +20,10 @@ import { createSessionToolbar, createSessionHeader, createFileMenu, createDocume
 import { BrassWsClient } from './ws-client.js';
 import { fetchHostedRuntime, readInjectedRuntime, isBrassHostedHost, HOSTED_RUNTIME_PATH, } from './hosted-runtime.js';
 const DEFAULT_AUTH_BASE_URL = 'https://auth.brass.build';
+// How long `signOut` waits for the revocation before it navigates. The page
+// it lands on finishes an unrevoked sign-out itself, so waiting longer than
+// this only delays the sign-out.
+const SIGN_OUT_REVOKE_DEADLINE_MS = 4000;
 // The data API has its own host, NOT the dashboard origin: the
 // dashboard (app.brass.build) is a static SPA, the data API is a
 // separate gateway behind api.brass.build.
@@ -41,11 +45,22 @@ const PROD_ORIGINS = {
 };
 // Resolve the four base URLs from init options. Zero config applies all
 // four production origins (including `wsBaseUrl`, so documents and
-// presence work with nothing passed). Naming ANY `*BaseUrl` fills
-// nothing from production: an app that overrides `apiBaseUrl` and
-// inherits a production `wsBaseUrl` would connect the WS to the wrong
-// stack and silently drop events, whereas an unfilled `wsBaseUrl` fails
-// loudly on subscribe. Pure so the precedence is unit-testable.
+// presence work with nothing passed).
+//
+// Naming ANY `*BaseUrl` withholds the production `wsBaseUrl`: an app that
+// overrides `apiBaseUrl` and inherited a production socket would connect to
+// the wrong stack and silently drop events, where an unfilled `wsBaseUrl`
+// fails loudly on subscribe.
+//
+// `authBaseUrl`, `apiBaseUrl` and `dashboardBaseUrl` still fall back to their
+// production defaults, so a caller who names some but not all of them reaches
+// production for the rest. `dashboardBaseUrl` is the one that goes wrong
+// quietly: every hosted surface (the picker, share, the version bar) is framed
+// from it, so an app on another stack frames production's, which either
+// refuses to render or hands back ids the configured API cannot open. Name it
+// alongside the others.
+//
+// Pure so the precedence is unit-testable.
 export function resolveBaseUrls(options) {
     const anyUrlOverride = Boolean(options.authBaseUrl || options.apiBaseUrl || options.wsBaseUrl || options.dashboardBaseUrl);
     const base = anyUrlOverride ? null : PROD_ORIGINS;
@@ -71,6 +86,13 @@ const REFRESH_LEEWAY_MS = 60_000;
 // group accepts both shapes, and the permissive tail keeps minor
 // server-side format bumps from stranding SDK consumers.
 const APP_ID_PATTERN = /^brass_app_(?:(?:test|live|internal)_)?[A-Za-z0-9_-]+$/;
+// The rejection for `unavailable`. A 503 status is what makes the outcome
+// legible to the layers that branch on one: an app's own retry, and the
+// selection self-heal that clears a persisted doc id on a definitive 403 /
+// 404 and leaves a transient alone.
+function refreshUnavailableError() {
+    return new BrassError('The sign-in service is unavailable', { status: 503 });
+}
 export class BrassClient {
     appId = null;
     authBaseUrl = DEFAULT_AUTH_BASE_URL;
@@ -123,6 +145,11 @@ export class BrassClient {
     // cannot block the others or mask the original error (already logged).
     errorListeners = createEmitter({ onError: () => { } });
     inflightRefresh = null;
+    // Bumped by every `signOut`, and captured by a `/refresh` when it starts.
+    // A refresh that settles against a moved epoch drops its answer: the
+    // credentials it would write were cleared by a sign-out while it was in
+    // flight, and re-writing them signs the person back in.
+    authEpoch = 0;
     initialized = false;
     // Incognito / third-party-cookie fallback state. Both null in a normal
     // browser, where the cross-site `brass_auth` cookie carries the session
@@ -130,7 +157,7 @@ export class BrassClient {
     //   - `pendingAuthCode`: the one-time `brass_code` pulled off the
     //     landing URL by bootstrap(), consumed at most once by refresh() if
     //     the cookie channel is unavailable.
-    //   - `sessionToken`: the platform-session pointer from a code
+    //   - `sessionToken`: the app-bound session pointer from a code
     //     exchange. Once set, every refresh() uses it instead of the
     //     cookie. Mirrored into sessionStorage so a reload in a
     //     cookie-blocked browser hydrates it; see session-persistence.ts.
@@ -170,8 +197,9 @@ export class BrassClient {
         completeImport: (docId) => this.docsInternal().completeImport(docId),
         reportError: (error) => this.fireError(error),
     });
-    // Separate from the projects namespace's WS client: one connection
-    // per surface.
+    // One socket carrying every document topic this client subscribes,
+    // built on first open so an app that never opens a document never
+    // connects.
     docWsClient = null;
     // init ALWAYS resolves: failures (bad/missing app_id) fire onError +
     // console.error rather than rejecting. Otherwise
@@ -320,7 +348,7 @@ export class BrassClient {
             // renders a signed-out UI or calls `signIn()`, which navigates the
             // frame away from the export it was loaded to run.
             if (this.exportGuest === null) {
-                for (const listener of this.listeners) {
+                for (const listener of Array.from(this.listeners)) {
                     listener(this.user);
                 }
             }
@@ -338,23 +366,34 @@ export class BrassClient {
             return;
         window.location.assign(buildSignInUrl(this.authBaseUrl, appId, window.location.href));
     }
-    // Per-app sign-out. Top-level navigation to a Brass-hosted confirmation
-    // page that:
-    //   1. Revokes this app's server-side approval (subsequent /refresh
-    //      calls for this app return 401 even on cookie reuse).
-    //   2. Surfaces the email the user is still signed in to Brass as,
-    //      and offers a one-click "Sign out of Brass too" link.
+    // Per-app sign-out. Revokes this app's server-side approval (subsequent
+    // /refresh calls for this app return 401 even on cookie reuse), then makes
+    // a top-level navigation to a Brass-hosted page that surfaces the email
+    // the user is still signed in to Brass as, and offers a one-click "Sign
+    // out of Brass too" link.
     //
-    // Navigation (not a background fetch) so the user gets a visible
-    // confirmation, closing the trust gap of "did sign-out actually
-    // happen?" The decision to ALSO sign out of the platform belongs to
-    // the user, made on the Brass-hosted page; the calling app cannot
-    // trigger platform-level sign-out from its own UI.
+    // The navigation is what closes the trust gap of "did sign-out actually
+    // happen?"; the revocation rides the credentialed route because the page
+    // answers whoever arrives at it and so writes nothing on arrival. The
+    // decision to ALSO sign out of the platform belongs to the user, made on
+    // the Brass-hosted page; the calling app cannot trigger platform-level
+    // sign-out from its own UI.
     signOut() {
         const appId = this.requireAppId();
         if (typeof window === 'undefined') {
             throw new Error('Brass.signOut must be called in a browser');
         }
+        // Read before the clears below drop it: where the cross-site cookie is
+        // blocked, this pointer is the revocation's only credential.
+        const credential = this.sessionToken
+            ? { kind: 'sessionToken', sessionToken: this.sessionToken }
+            : { kind: 'cookie' };
+        // Fence any `/refresh` already on the wire: landing after the clears
+        // below, it writes back the token set, the login hint and the session
+        // pointer, and re-emits the signed-in user. The hint and the pointer
+        // outlive the page, so that resurrects the session on the next load
+        // too, and the navigation below can be delayed or cancelled.
+        this.authEpoch += 1;
         this.setTokens(null);
         // Drop any fallback-mode credential too, so a stale session token
         // can't resurrect the session on the next getAccessToken(). Clear
@@ -376,13 +415,23 @@ export class BrassClient {
         // on the way to the confirmation page. Harmless when the app is not
         // gated (the cookie simply isn't there). Off a hosted origin there is
         // no such cookie, so go straight to the confirmation page.
-        if (isBrassHostedHost(window.location.hostname)) {
-            const leave = `${window.location.origin}/__brass/leave?return_to=${encodeURIComponent(signedOutUrl)}`;
-            window.location.assign(leave);
-        }
-        else {
-            window.location.assign(signedOutUrl);
-        }
+        const target = isBrassHostedHost(window.location.hostname)
+            ? `${window.location.origin}/__brass/leave?return_to=${encodeURIComponent(signedOutUrl)}`
+            : signedOutUrl;
+        // Leave once the revocation settles, so the page reports a sign-out that
+        // already happened rather than offering the button that finishes it.
+        let left = false;
+        const leave = () => {
+            if (left)
+                return;
+            left = true;
+            window.location.assign(target);
+        };
+        const deadline = setTimeout(leave, SIGN_OUT_REVOKE_DEADLINE_MS);
+        void revokeAppApproval(this.authBaseUrl, appId, credential).then(() => {
+            clearTimeout(deadline);
+            leave();
+        });
     }
     get currentUser() {
         return this.user;
@@ -438,10 +487,11 @@ export class BrassClient {
     fireError(error) {
         this.errorListeners.emit(error);
     }
-    // The raw HTTP metadata + grant namespace (create / get / move /
-    // grantAccess); the editable surface stays on
-    // `Brass.openDocumentById` / `Brass.createDocument`. Throws "Call
-    // Brass.init(appId) first" before init.
+    // The metadata + thumbnail namespace for a document the app already
+    // holds an id for (`get` / `setThumbnail` / `getThumbnail`); the
+    // editable surface stays on `Brass.openDocumentById` /
+    // `Brass.createDocument`. Throws "Call Brass.init(appId) first" before
+    // init.
     get documents() {
         return this.docsInternal();
     }
@@ -564,9 +614,8 @@ export class BrassClient {
             dashboardBaseUrl: this._dashboardBaseUrl,
             getDocument: (docId) => this.documents.get(docId),
             // The version-preview bar is a hosted embed; it takes the same theme
-            // and fallback session pointer as the other hosted surfaces.
+            // as the other hosted surfaces.
             hostedUiTheme: this.hostedUiTheme,
-            getSessionToken: () => this.sessionToken,
         };
     }
     // Opens the hosted document picker in a modal iframe and resolves with
@@ -634,11 +683,6 @@ export class BrassClient {
                     else
                         this.session._clearLocalDelete(docId);
                 },
-                // Hand our fallback platform-session pointer to the embed so it can
-                // authenticate the dashboard when its own framed cookie is blocked
-                // (incognito / Safari ITP). Null in a normal browser, where the
-                // embed's cross-site cookie carries the session on its own.
-                getSessionToken: () => this.sessionToken,
                 // Name the user this app is acting as, so the embed can refuse to
                 // act as anyone else. The embed authenticates from the dashboard
                 // origin's platform-session cookie, which moves when a second
@@ -679,14 +723,21 @@ export class BrassClient {
     // "live editing unavailable" in the UI.
     async openDocumentById(docId, options) {
         const opened = await this.openDocumentInternal(docId, options);
-        this.maybeWriteDocIdToUrl(opened.id);
+        // The URL names the document the reader is looking at, and the session
+        // owns that whenever it holds one: this open is detached, so claiming the
+        // URL would leave the address bar naming a document the session is not
+        // showing, and a reload would swap the reader onto it. An app with no
+        // session document still gets the sync, which is the read-mostly caller
+        // this method exists for.
+        if (this.session.document === null)
+            this.maybeWriteDocIdToUrl(opened.id);
         return opened;
     }
     // Open a document READ-ONLY from a public-link token (the "anyone with
     // the link" anonymous path). No sign-in: the token is the credential and
     // the server serves a read-only, member-stripped snapshot with no live
     // subscription. `Brass.session` drives this from the URL on boot when the
-    // page carries `?brass_link=`; there is no app-facing entry point.
+    // page carries `?brass_link=`.
     async openByLinkInternal(token, options) {
         const factory = this.getDocumentFactory();
         const opened = await factory.openByLink(token, options);
@@ -850,12 +901,12 @@ export class BrassClient {
         this.importRunner.setImporter(importer);
         if (this.guestLinkTokenValue !== null)
             return;
-        for (const doc of this.openDocuments.values()) {
+        for (const doc of this.liveOpenDocuments()) {
             void this.importRunner.attempt(doc);
         }
     }
     // Track an opened document so an export request can resolve its id to
-    // the live Document. Drop it when the doc goes; a re-open overwrites.
+    // the live Document. A re-open overwrites.
     trackOpenDocument(doc) {
         this.openDocuments.set(doc.id, doc);
         doc.onGone(() => {
@@ -870,22 +921,82 @@ export class BrassClient {
             void this.importRunner.attempt(doc);
         }
     }
+    // The tracked documents still open, dropping the rest as it goes.
+    // `onGone` covers only a server-side eviction, and two ordinary paths
+    // retire a Document without one: an app's `close()` (which parks it, so
+    // the public surface throws while the instance lives on in the park
+    // cache) and that cache's LRU eviction (a full teardown, no listener
+    // left to fire). Reading through this is what keeps a retired wrapper
+    // out of an answer, and what keeps the set from growing for the life of
+    // the page.
+    liveOpenDocuments() {
+        const live = [];
+        for (const [docId, doc] of this.openDocuments) {
+            if (doc._isLive)
+                live.push(doc);
+            else
+                this.openDocuments.delete(docId);
+        }
+        return live;
+    }
+    liveOpenDocument(docId) {
+        const doc = this.openDocuments.get(docId);
+        if (!doc)
+            return null;
+        if (doc._isLive)
+            return doc;
+        this.openDocuments.delete(docId);
+        return null;
+    }
+    // Publish a document to a drive, supplying the bytes when the platform has
+    // no writer for it.
+    //
+    // Where the export of this document runs in THIS app, the SDK runs the
+    // registered serializer in process and the push carries its bytes, rather
+    // than sending the reader through the hosted export frame. That is what
+    // makes a publish from inside an app one click, and it is the same on the
+    // publish that creates the drive file and on every push after it: the
+    // caller's own app either writes this document or it does not.
+    //
+    // Everything else is the route's, including refusing bytes from an app the
+    // exporter setting does not name, which it does by name rather than the
+    // client predicting it.
+    async pushDocumentToDrive(doc, input) {
+        const docId = doc.id;
+        if (docId === null || !doc._exportRunsHere) {
+            return await this.docsInternal().pushToDrive(doc, input);
+        }
+        const serialized = await this.serializeForExport(docId);
+        if (!serialized.ok) {
+            throw new BrassError(`This app could not write the document out to publish it: ${serialized.message}`, { status: 400 });
+        }
+        return await this.docsInternal().pushToDrive(doc, {
+            ...input,
+            bytes: serialized.bytes,
+        });
+    }
     // Run the registered serializer for an export request from a hosted
     // surface. Resolves the doc from the open set (the active session doc is
     // the fallback for an app that drives it through the session), then hands
     // it to the serializer. A missing serializer is the ordinary "this app
-    // does not export" outcome, not an error.
+    // does not export" outcome, not an error. A document the app has closed
+    // reports `no_document`: running the serializer against it would throw
+    // out of the app's own record reads and report `serializer_failed`, which
+    // names the app's code for a state the platform is holding.
     async serializeForExport(docId) {
         if (!this.serializer) {
             return { ok: false, code: 'no_serializer', message: 'No serializer registered.' };
         }
         const sessionDoc = this.documentSession?.document ?? null;
-        const doc = this.openDocuments.get(docId) ??
-            (sessionDoc && sessionDoc.id === docId ? sessionDoc : null);
+        const doc = this.liveOpenDocument(docId) ??
+            (sessionDoc && sessionDoc.id === docId && sessionDoc._isLive ? sessionDoc : null);
         if (!doc) {
             return { ok: false, code: 'no_document', message: 'Document is not open.' };
         }
         try {
+            // A serializer runs detached, with no subscription to have been fed by,
+            // and it needs the document once, so it is handed the containers whole
+            // (`StoredDocument`) rather than the fed surface an app holds.
             const bytes = await this.serializer(doc);
             return { ok: true, bytes };
         }
@@ -932,6 +1043,7 @@ export class BrassClient {
                 apiBaseUrl: this.apiBaseUrl,
                 getAccessToken: () => this.getAccessToken(),
                 getAppAssertion: () => this.getAppAssertion(),
+                identity: () => this.user?.sub ?? null,
                 ...(wsClient ? { wsClient } : {}),
                 branchProvider: {
                     list: (docId) => docsInternal.listBranches(docId),
@@ -946,7 +1058,7 @@ export class BrassClient {
                 },
                 thumbnailUploader: (doc, image, width, height) => docsNs.setThumbnail(doc, { image, width, height }),
                 checkpointCreator: (doc) => docsInternal.createCheckpoint(doc),
-                drivePusher: (doc, input) => docsInternal.pushToDrive(doc, input),
+                drivePusher: (doc, input) => this.pushDocumentToDrive(doc, input),
                 sourceBlobFetcher: (doc) => docsInternal.sourceBlob(doc),
                 hostedUiProvider: {
                     documentHistory: (docId, options) => this.documentHistory(docId, options),
@@ -1019,28 +1131,53 @@ export class BrassClient {
         });
         return this.docWsClient;
     }
+    // Resolves null only when the server answered that this app has no live
+    // session, and rejects with a 503 `BrassError` when a `/refresh` found no
+    // answer at all. The two outcomes drive opposite handling: null is the
+    // signed-out state a caller renders a sign-in CTA for, where a rejection
+    // is a momentary outage the caller retries. Collapsing them into null
+    // reports a 401-shaped "Not signed in" to a signed-in user whose network
+    // blipped, and hides the transient from every layer that self-heals on it.
     async getAccessToken() {
         this.requireInit();
+        // On a `?brass_link=` page the link token is the credential and `init`
+        // runs no auth bootstrap, so answer null rather than probing /refresh.
+        // A visitor with no session would draw a 401 the browser logs; one who
+        // holds a session for this app would get a real token, and a caller
+        // that prefers a token over the link token (the socket does) would then
+        // present membership where the page's whole authority is the link.
+        if (this.guestLinkTokenValue !== null)
+            return null;
         const current = this.tokens;
         if (current && current.expiresAt - REFRESH_LEEWAY_MS > Date.now()) {
             return current.accessToken;
         }
-        const refreshed = await this.refresh();
-        return refreshed?.accessToken ?? null;
+        const settled = await this.refresh();
+        if (settled.status === 'unavailable')
+            throw refreshUnavailableError();
+        return settled.status === 'ok' ? settled.tokens.accessToken : null;
     }
     // The acting-app assertion paired with the current access token, or
     // null when the proxy issued none. Mirrors `getAccessToken`'s
     // freshness check so the two stay in lockstep: a request builder that
     // calls `getAccessToken()` then this reads the same (possibly just
-    // refreshed) token set without forcing a second refresh.
+    // refreshed) token set without forcing a second refresh. Rejects on a
+    // transient outage for the same reason `getAccessToken` does.
     async getAppAssertion() {
         this.requireInit();
+        // Paired with `getAccessToken`: a link guest holds no token to assert
+        // an acting app against, and reaching /refresh here would authenticate
+        // the page the same way.
+        if (this.guestLinkTokenValue !== null)
+            return null;
         const current = this.tokens;
         if (current && current.expiresAt - REFRESH_LEEWAY_MS > Date.now()) {
             return current.appAssertion ?? null;
         }
-        const refreshed = await this.refresh();
-        return refreshed?.appAssertion ?? null;
+        const settled = await this.refresh();
+        if (settled.status === 'unavailable')
+            throw refreshUnavailableError();
+        return settled.status === 'ok' ? (settled.tokens.appAssertion ?? null) : null;
     }
     async bootstrap() {
         if (typeof window === 'undefined')
@@ -1048,7 +1185,7 @@ export class BrassClient {
         const appId = this.requireAppId();
         // Every successful sign-in 302s back to return_to with the
         // platform-session cookie set AND a one-time `brass_code` query
-        // parameter (see infra/lambda/auth/token-redirect.ts). The cookie
+        // parameter. The cookie
         // is the primary channel; the code is the incognito / Safari ITP /
         // post-third-party-cookie fallback for when the browser drops the
         // cross-site cookie on our /refresh XHR.
@@ -1061,8 +1198,7 @@ export class BrassClient {
         //
         // No app-controlled silent-mint path: the SDK never auto-fires
         // Brass.signIn() based on a URL hint. New app approvals always
-        // require an explicit click on the auth-hosted picker (see the
-        // adaptive /sign-in branch in infra/lambda/auth/sign-in.ts).
+        // require an explicit click on the auth-hosted picker.
         // Same treatment for the launching organization: read it off the URL
         // and strip it here, so a client-side navigation later in the session
         // cannot lose it and the address bar stays the app's own.
@@ -1120,16 +1256,26 @@ export class BrassClient {
         if (this.inflightRefresh)
             return this.inflightRefresh;
         const appId = this.requireAppId();
+        const epoch = this.authEpoch;
         this.inflightRefresh = (async () => {
-            const result = await this.runRefresh(appId);
+            const outcome = await this.runRefresh(appId);
+            // No answer means no change: the token set, the login hint, and any
+            // fallback session token stay as they are, and a later attempt settles
+            // the session.
+            if (outcome.status === 'unavailable')
+                return { status: 'unavailable' };
+            // A sign-out landed while this round-trip was in flight, so whatever
+            // it resolved belongs to a session the person has left. Report it as
+            // no session and write nothing: the caller waiting on this token gets
+            // the signed-out answer the sign-out established.
+            if (this.authEpoch !== epoch)
+                return { status: 'no_session' };
+            const result = outcome.status === 'ok' ? outcome.result : null;
             this.setTokens(result?.tokens ?? null);
             // Remember whether a live session exists for this app so the next
             // cold load knows whether to probe /refresh (see bootstrap). A
-            // success proves a session; an empty result means none (or it's
-            // gone), so drop the hint and the next signed-out load stays
-            // silent. A transient network failure also clears it; the cost is
-            // one extra sign-in click on the next load, self-healing on the
-            // next success.
+            // success proves a session; `no_session` is the server saying there
+            // is none, so drop the hint and the next signed-out load stays silent.
             if (result) {
                 storeLoginHint(appId);
             }
@@ -1141,12 +1287,11 @@ export class BrassClient {
                 // Mirror into sessionStorage so a reload on this tab can
                 // hydrate it (the cookie channel is unavailable in this
                 // browser by construction; we only get here via the code or
-                // sid channels). The server-side `approved_apps` gate stays
-                // the security boundary; the stored sid is no more sensitive
-                // than the cookie it mirrors.
+                // sid channels). The pointer is bound to this app id, so what
+                // is stored authenticates this app and nothing else.
                 storeSessionToken(appId, result.sessionToken);
             }
-            return result?.tokens ?? null;
+            return result ? { status: 'ok', tokens: result.tokens } : { status: 'no_session' };
         })().finally(() => {
             this.inflightRefresh = null;
         });
@@ -1155,16 +1300,20 @@ export class BrassClient {
     // Picks the credential channel for a single /refresh round-trip. The
     // cookie path is primary and untouched for browsers that send the
     // third-party cookie; the one-time code is consumed only when that
-    // cookie path genuinely came back empty. Once a fallback session
+    // cookie path resolved no session. Once a fallback session
     // token is in hand (the cross-site cookie is proven unavailable for
     // this page's life), every later refresh uses it directly.
+    //
+    // A rung falls through to the next only on `no_session`. Each one discards
+    // a credential as it passes (the stale sid, the one-time code), and an
+    // `unavailable` says nothing about the credential it just tried.
     async runRefresh(appId) {
         if (this.sessionToken) {
             const viaSession = await refreshTokens(this.authBaseUrl, appId, {
                 kind: 'sessionToken',
                 sessionToken: this.sessionToken,
             });
-            if (viaSession)
+            if (viaSession.status !== 'no_session')
                 return viaSession;
             // Stored sid is stale (server-side revoke, row expiry). Drop both
             // the in-memory copy and the sessionStorage mirror, then fall
@@ -1176,20 +1325,31 @@ export class BrassClient {
             clearSessionToken(appId);
         }
         const viaCookie = await refreshTokens(this.authBaseUrl, appId);
-        if (viaCookie)
+        if (viaCookie.status !== 'no_session')
             return viaCookie;
-        // Cookie channel produced nothing. Fall back to the one-time code if
-        // we landed with one. Clear it first: it is single-use server-side,
-        // so a failed exchange must not be retried.
+        // Cookie channel resolved no session. Fall back to the one-time code if
+        // we landed with one. Clear it first: it is single-use server-side, so a
+        // failed exchange must not be retried.
         const code = this.pendingAuthCode;
-        this.pendingAuthCode = null;
         if (!code)
-            return null;
+            return viaCookie;
+        this.pendingAuthCode = null;
         return refreshTokens(this.authBaseUrl, appId, { kind: 'code', code });
     }
     setTokens(next) {
-        this.tokens = next;
         const nextUser = next ? decodeIdToken(next.idToken) : null;
+        // A different person on this page. `/refresh` resolves whichever platform
+        // session the browser holds, so the identity behind a page that never
+        // navigated can become someone else's (another tab signs out and a second
+        // person signs in). Run the retirement first, as its own transition, so
+        // what the previous identity left open is retired before the new one is
+        // announced rather than inherited by it.
+        if (this.user !== null &&
+            nextUser !== null &&
+            this.user.sub !== nextUser.sub) {
+            this.setTokens(null);
+        }
+        this.tokens = next;
         if (sameUser(this.user, nextUser))
             return;
         this.user = nextUser;
@@ -1200,9 +1360,18 @@ export class BrassClient {
         // (the same user), double-emitting on every signed-in app load.
         if (!this.bootstrapped)
             return;
-        for (const listener of this.listeners) {
+        // Copied before the walk: a listener that detaches another would otherwise
+        // remove it before its turn, and a `Set` never visits such an entry.
+        for (const listener of Array.from(this.listeners)) {
             listener(nextUser);
         }
+        // After the listeners, because the session closes the active document as
+        // it hears the sign-out and a close PARKS the Document. A parked Document
+        // answers the next open of its key out of memory, with no token and no
+        // request, so one left behind here is the previous person's document
+        // handed to whoever signs in next.
+        if (nextUser === null)
+            clearParkedDocuments();
     }
     async hydrateProfile() {
         if (!this.user)