Skip to content

FE-2893 docs: describe the shared web session in the billing-web README and account-core - #19449

Merged
dante01yoon merged 1 commit into
mainfrom
dante01yoon/fe-2893-web-session-docs
Sep 29, 2026
Merged

dante01yoon merged 1 commit into
mainfrom
dante01yoon/fe-2893-web-session-docs

Conversation

@dante01yoon

Copy link
Copy Markdown
Collaborator

Why

FE-2893 says the READMEs follow the app slices. The billing-web README still describes only its own Firebase sign-in, and even lists a cookie-backed session as out of scope. The shared web session has no doc beside the package that implements it.

How

  • apps/billing-web/README.md: the Authentication section now has a flag-off paragraph (unchanged text) and a unified_web_session paragraph. The new one covers how the mode is decided once per page load with an 800 ms cap, where identity and workspace come from, the cookie transport, and when Firebase loads. The scope list no longer denies a cookie session, and the section links the ADR.
  • packages/account-core/docs/web-session.md (new): an entry-point table with when to use each, the request-authorization matrix, the token mint rules, a WebSessionErrorCode table with the source of each code, and per-app usage for cloud, website and billing-web.

Every export, path and behaviour was checked against the code on main.

AS IS / TO BE

There is no UI change.

Doc AS IS TO BE
apps/billing-web/README.md, Current scope Lists "a cookie-backed session transport" as not contained Names the shared web session behind the flag and says it is read through @comfyorg/account-core
apps/billing-web/README.md, Authentication Firebase identity exchanged at /api/auth/token only Same text for flag off, plus the flag-on path and the ADR link
packages/account-core/docs/web-session.md Does not exist Entry points, authorization matrix, mint rules, error codes, per-app usage

Where this sits

PR Ticket Change
#19390 FE-3079 part 1 Web session follow-up
#19414 FE-3079 part 2 Web session follow-up
F2a FE-2900 Mint failure copy
F3a FE-2899 Website balance
F4 FE-2901 API-key rows
F5 FE-2891 Flag-off pins
F6 (this PR) FE-2893 Docs
F8 FE-2904 E2E Run, depends on #19414
graph LR
  A["#19390 FE-3079 part 1"] --> R
  B["#19414 FE-3079 part 2"] --> R
  B --> F8
  C["F2a FE-2900 mint failure copy"] --> R
  D["F3a FE-2899 website balance"] --> R
  E["F4 FE-2901 API-key rows"] --> R
  F["F5 FE-2891 flag-off pins"] --> R
  G["F6 FE-2893 docs"] --> R
  F8["F8 FE-2904 E2E Run"] --> R
  R["FE-2907 ramp"]
  style G fill:#f9c74f,stroke:#000,stroke-width:3px,color:#000
Loading
  • Part of FE-2893

@coderabbitai

coderabbitai Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository: Comfy-Org/ComfyUI_frontend/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: ba3492ed-17d0-42d4-9df2-71c02115a870

📥 Commits

Reviewing files that changed from the base of the PR and between 7b7dfb3 and 194bf8c.

📒 Files selected for processing (2)
  • apps/billing-web/README.md
  • packages/account-core/docs/web-session.md

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 3 remain after this review.


📝 Walkthrough

Walkthrough

The changes document the shared web-session package and its use in Billing Web. They describe feature-flag selection, identity and workspace behavior, request authorization, token minting, and error handling.

Changes

Shared web session

Layer / File(s) Summary
Session activation, identity, and app usage
packages/account-core/docs/web-session.md, apps/billing-web/README.md
Documents feature-flag checks and identity lifecycle. Describes Billing Web’s Firebase and shared-session modes, workspace selection, and cookie-based Billing calls.
Request authorization, tokens, and errors
packages/account-core/docs/web-session.md
Documents authorization by request target, workspace token caching and rate limits, and shared session error codes and retryability.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 194bf

No actionable documentation mismatch or runtime change is established; the PR is mergeable after normal checks.

Architecture Summary

Architecture risk: 🔵 Low · up to 194bf

The change affects 2 systems.

Changed systems: apps/billing-web, packages/account-core

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

  • observed — apps/billing-web (service) was modified; 1 changed file maps to changed impact.
  • observed — packages/account-core (library) was modified; 1 changed file maps to changed impact.

Before / after behavior

  • observed — Modified behavior in apps/billing-web/README.md: The scope description now includes the app’s own Firebase identity and workspace session, the flag-controlled shared web session, and the shared session’s Cloud source. It also clarifies that the app has no cookie-backed session of its own.
  • observed — Modified behavior in apps/billing-web/README.md: The authentication section now states that only same-origin absolute return paths are honored and labels the existing Firebase identity and token-exchange session as the default, flag-off mode.
  • observed — Modified behavior in apps/billing-web/README.md: Documents the unified_web_session mode: the app reads the feature probe and then the flag, defaults to Firebase if neither responds within 800 ms, and does not change modes during the page load. In shared-session mode, identity comes from the Cloud session endpoint; workspace selection uses the entry link’s workspace ID or the personal workspace; Billing calls use cookie transport and CSRF tokens on unsafe methods. Firebase loads only when no session is reported or for sign-in. Adds links to the ADR and shared building-block documentation.
  • observed — Modified behavior in packages/account-core/docs/web-session.md: Documents that, when unified_web_session is enabled, Comfy sites share the host-only session cookie; hosts retain their own sign-in while the flag is off. Lists package entry points, exports, and their use cases.
🚥 Pre-merge checks | ✅ 7
✅ Passed checks (7 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly identifies the documentation changes in the billing-web README and account-core package.
Description check ✅ Passed The description provides the purpose, implementation details, affected files, scope, dependencies, and review context. It does not use the repository template headings or explicitly address breaking c…
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
End-To-End Regression Coverage For Fixes ✅ Passed The title and commit subject use documentation language and contain no bug-fix signal such as “fix” or “bugfix.” The PR changes only documentation files: apps/billing-web/README.md and `packages/acc…
Website End-To-End Regression Coverage ✅ Passed No files under apps/website/src/ or apps/website/public/ changed. The PR changes only apps/billing-web/README.md and packages/account-core/docs/web-session.md, so this website-specific check i…
Adr Compliance For Entity/Litegraph Changes ✅ Passed The pull request changes only apps/billing-web/README.md and packages/account-core/docs/web-session.md. No changed file is under src/lib/litegraph/, src/ecs/, or a graph-entity file. The ADR-L…
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR

Comment @coderabbitai help to get the list of available commands.

@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

🌾 Fallow: ✅ Passed

Fallow audits the diff for duplication, complexity and dead code. It gates on new findings only, so when the audit completes, a red is something this PR introduced or moved — never inherited backlog. A red can also mean the audit itself did not finish; the details below say which happened.

No new findings in the changed files.

Reproduce locally
# the base the gate compared against
npx fallow audit --root . --quiet --format json \
  --changed-since 7b7dfb3b39d2dc70107b064d445df3ddde8470b5

Full docs: ADR-DEVEX-LINT-0015

🎨 Storybook: ✅ Built — View Storybook

Details

⏰ Completed at: 09/29/2026, 07:20:28 PM UTC

Links

🧩 Custom Nodes Ecosystem Matrix: 🟡 Withheld — could not measure

Executes the frontend JS of every registry pack that ships any, against this change, in both renderers. The eight ecosystem-matrix shard checks are a harness self-test; the pack verdict is matrix-verdict.

This candidate changes nothing the matrix measures, so every expensive stage was skipped.

Reproduce locally
# build one shard's fixture, then run it
python3 scripts/registry-census/build_matrix.py --shard 1/4
MATRIX_RENDERER=vue MATRIX_VUE=1 \
  npx vitest run --config vitest.matrix.config.mts

Full docs: scripts/registry-census/README.md

🌐 Website E2E

Tip

All tests passed.

Status ✅ Passed
Report View Report

@codecov

codecov Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@            Coverage Diff            @@
##             main   #19449     +/-   ##
=========================================
  Coverage   84.16%   84.16%             
=========================================
  Files        3237     3237             
  Lines      156372   156372             
  Branches    42319    40427   -1892     
=========================================
  Hits       131614   131614             
  Misses      23003    23003             
  Partials     1755     1755             
Flag Coverage Δ
billing-web-unit 87.08% <ø> (ø)
website-unit 78.94% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@github-actions github-actions Bot added the risk:high PR risk grade (advisory shadow check; grader-owned) label Sep 29, 2026

@christian-byrne christian-byrne left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Approved: the docs accurately describe the flag-off and shared-session paths, including cookie ownership, workspace selection, and transport behavior.

Full context for agent readers

The account-core entry-point and error tables are consistent with the shared-session design, and the billing-web guidance preserves entry-link workspace scope instead of introducing global workspace state.

@dante01yoon
dante01yoon added this pull request to the merge queue Sep 29, 2026
Merged via the queue into main with commit ac7bbad Sep 29, 2026
95 checks passed
@dante01yoon
dante01yoon deleted the dante01yoon/fe-2893-web-session-docs branch September 29, 2026 22:37
christian-byrne pushed a commit to christian-byrne/ComfyUI_frontend that referenced this pull request Sep 30, 2026
…credit action (Comfy-Org#19454)

## Why

The other `useWorkshopCredits` callers still mint via Firebase in
session mode. This continues Comfy-Org#19368, which moved the model page onto
`useWorkshopModelBalance`.

## How

Switch three callers from `useWorkshopCredits().balance` to
`useWorkshopModelBalance(session)`:

- `WorkflowPlayground.vue`, which takes `session` from
`useWorkshopSession()`
- `CinematicCreditAction.vue`
- `useCinematicStudioRun.ts`, which already destructures `session`

`useWorkshopModelBalance` binds once per page: the cookie balance for a
personal workspace in session mode, the Firebase balance otherwise. The
Firebase store is only started on the Firebase branch.
`BuyCreditsDialog.vue` is unchanged.

The request recorder from `workshop-model-balance.test.ts` moves to
`config/__fixtures__/workshopCloudRecorder.ts` so both suites share it.

## AS IS / TO BE

Requests from the three callers' balance path, per rollout state:

| State | AS IS | TO BE |
| --- | --- | --- |
| Flag off (probe absent or false) | Firebase balance, no cookie request
| Same: Firebase balance, no `/api/billing/balance` or `/api/auth/token`
from the balance path |
| Session mode, personal workspace | `POST /api/auth/token` with
Firebase ID token, then `GET /api/billing/balance` with Bearer | One
`GET /api/billing/balance` (cookie, `X-Comfy-Client`), no
`/api/auth/token`, Firebase store not started |
| Session mode, team workspace | Firebase balance | Balance unknown; the
server's refusal still gates the run |

Screenshots follow.

## Tests

- New `BalanceCallers.test.ts` renders `WorkflowPlayground`,
`CinematicStudio` and `CinematicCreditAction` against the recorder.
- Session mode: exactly one cookie balance read, no `/api/auth/token`,
`useWorkshopCredits` never called.
  - Flag off: Firebase balance read, no balance or token request.
- Run gates: a funded cookie balance runs where an empty Firebase
balance would not; flag off with an empty Firebase balance cannot run.
- `WorkflowPlayground.test.ts` mocks `useWorkshopModelBalance` as
`ModelDetail.test.ts` does.
- Website unit suite: 512 files, 9779 tests pass. Website typecheck,
oxlint, eslint and oxfmt are clean.
- Mutation check: reverting each caller to `useWorkshopCredits` turns
red.
- `WorkflowPlayground`: the session-mode read test and the funded-gate
test.
  - `CinematicCreditAction`: the session-mode read test.
- `useCinematicStudioRun`: the session-mode read test and the
funded-gate test.
- `models-performance.spec.ts` passes. Total website JS is 8,828,894 B
before and 8,828,836 B after (-58 B).

## Known limits

- The Run gate still starts Firebase: `refreshWorkshopCredits` and the
run path use the Firebase store.
- Needs the backend to confirm that Router accepts session-minted tokens
and that comfy.org is trusted for credentialed POSTs.
- `BuyCreditsDialog` is skipped: it renders nothing in session mode, and
top-up needs the Firebase token.

## Where this sits

| Node | PR / ticket | Scope |
| --- | --- | --- |
| Comfy-Org#19390 | FE-3079 part 1 | Run token on session, part 1 |
| Comfy-Org#19414 | FE-3079 part 2 | Run token on session, part 2 |
| Comfy-Org#19452 | FE-2900 | Mint failure copy |
| **F3a** | **FE-2899** | **Website balance (this PR)** |
| Comfy-Org#19450 | FE-2901 | API-key rows |
| Comfy-Org#19453 | FE-2891 | Flag-off pins |
| Comfy-Org#19449 | FE-2893 | Docs |
| F8 | FE-2904 | E2E Run (depends on Comfy-Org#19414) |
| Ramp | FE-2907 | Fed by all of the above |

```mermaid
graph LR
  A["Comfy-Org#19390 FE-3079 part 1"] --> R
  B["Comfy-Org#19414 FE-3079 part 2"] --> R
  B --> F8["F8 FE-2904 E2E Run"]
  C["Comfy-Org#19452 FE-2900 mint failure copy"] --> R
  D["F3a FE-2899 website balance"]:::this --> R
  E["Comfy-Org#19450 FE-2901 API-key rows"] --> R
  F["Comfy-Org#19453 FE-2891 flag-off pins"] --> R
  G["Comfy-Org#19449 FE-2893 docs"] --> R
  F8 --> R
  R["FE-2907 ramp"]
  classDef this fill:#ffd54f,stroke:#f57f17,stroke-width:3px,color:#000
```

- Part of FE-2899
christian-byrne pushed a commit to christian-byrne/ComfyUI_frontend that referenced this pull request Sep 30, 2026
…ied_web_session is on (Comfy-Org#19450)

## Why

FE-2901: API-key clients keep sending only `X-API-KEY`, whichever flags
are on. `authorize()` must never mint or reach for a session for an
`apiKey` principal, and an API-key login must produce no
`/api/auth/session` traffic when `unified_web_session` is true.

## Root cause

With `unified_web_session` on, an API-key user still resolves through
`useCurrentUser`, so the `Comfy.Cloud.SessionCookie`
`onAuthUserResolved` hook runs `useSessionCookie.createSession` ->
`useCloudWebSessionStore.start()` -> `identity.boot()`, which sends a
credentialed `GET /api/auth/session`. The new `uws:true` rows were red
on main for exactly this.

## How

`createSession` returns early when the flag is on and the login is an
API-key login (`isApiKeyLogin`). It sits before `start()` and behind the
flag check, so flag-off is byte-identical (including the existing
`reportError` path). 8 non-test lines.

## AS IS / TO BE

No UI change.

| Case | AS IS | TO BE |
| --- | --- | --- |
| API-key login, `unified_web_session` true | `GET /api/auth/session`
(credentials: include) after `POST /customers` | no session request;
only `POST /customers` and `X-API-KEY` API calls |
| API-key login, flag absent/false | `X-API-KEY` only | unchanged |
| `authorize({kind:'apiKey'})` | `{headers:{'X-API-KEY'}}` | unchanged,
now pinned |

## Tests

- `requestAuth.test.ts`: `it.for` over {ingest, resource} x {GET, POST,
DELETE} with an `apiKey` principal; result
`toStrictEqual({headers:{'X-API-KEY'}})` (no `credentials`),
`getWorkspaceToken` and `fetch` never called.
- `nonWebClientsStayOnTokens.test.ts`: the authorizer built as
`cloudWebSessionStore` builds it (real `createSessionTokenMint`, spied
`getSession`/`fetchImpl`) returns `useApiKeyAuthStore().getAuthHeader()`
and touches neither spy; `{uca:false,uws:true}` and
`{uca:true,uws:true}` rows added to the API-key case with
`expectNoSessionTraffic`.
- On main the two `uws:true` rows were red (extra credentialed `GET
/api/auth/session`); green with the fix.
- Mutations, each reverted: `apiKey` calls `getWorkspaceToken` -> unit
rows red; `apiKey` returns `credentials:'include'` -> unit and header
rows red; guard removed -> both `uws:true` rows red.
- `pnpm typecheck`, `pnpm lint`, `pnpm fallow:audit` clean.

## Where this sits

| PR | Ticket | Scope |
| --- | --- | --- |
| Comfy-Org#19390 | FE-3079 part 1 | workspace API and agent consent on the
session |
| Comfy-Org#19414 | FE-3079 part 2 | Run token minted from the session |
| F2a | FE-2900 | mint failure copy |
| F3a | FE-2899 | website balance |
| **F4 (this PR)** | FE-2901 | API-key rows |
| F5 | FE-2891 | flag-off pins |
| Comfy-Org#19449 | FE-2893 | docs |
| F8 | FE-2904 | E2E Run (depends on Comfy-Org#19414) |
| FE-2907 | ramp | all of the above feed in |

```mermaid
graph LR
  A["Comfy-Org#19390 FE-3079 part 1"] --> R
  B["Comfy-Org#19414 FE-3079 part 2"] --> R
  C["F2a FE-2900 mint failure copy"] --> R
  D["F3a FE-2899 website balance"] --> R
  E["F4 FE-2901 API-key rows"] --> R
  F["F5 FE-2891 flag-off pins"] --> R
  G["F6 FE-2893 docs (Comfy-Org#19449)"] --> R
  B --> H["F8 FE-2904 E2E Run"]
  H --> R
  R["FE-2907 ramp"]
  style E fill:#f9d71c,stroke:Comfy-Org#333,stroke-width:3px,color:#000
```

- Part of FE-2901
christian-byrne pushed a commit to christian-byrne/ComfyUI_frontend that referenced this pull request Sep 30, 2026
…ession off (Comfy-Org#19453)

## Why

FE-2891's criterion: with `unified_web_session` absent, the three apps
issue the same network calls as main. Only the cloud app was pinned
(`nonWebClientsStayOnTokens.test.ts`). The website had no request-level
pin, and billing-web pinned main only relatively (the flag-off rows were
compared against a run of the same code, so a change that hit both sides
passed).

## How

Tests only, no production change.

- **website**: new `workshop-flag-off.requests.test.ts`. Real
`workshop-account`, `workshop-session-state`, `workshop-credits`,
`workshop-account-source` and `workshop-model-balance` run over a
recording `fetch`. Only `workshop-firebase` (signed-in user,
`getIdToken` -> `id-token`) and `scripts/posthog` (auth flag on) are
mocked. Flow: boot, header balance, model-page balance, a direct session
freshness check (`ensureFresh`), refocus, sign-out. Each request records
`{method, url, credentials, header names, authorization, client, body}`
and is compared to a literal golden. `setTimeout` is faked and never
advanced, so the 800 ms account-source cap cannot fire.
- **billing-web**: `billingWebAuth.flagOff.test.ts` gains a literal
`MAIN_GOLDEN` next to the existing relative check, plus an entry-link
workspace rebind flow and a sign-out flow.

Golden values were captured by running main's code, not written by hand.

## AS IS / TO BE

No UI change.

| | AS IS | TO BE |
|---|---|---|
| website, probe absent / `false` | unpinned | anonymous `GET
/api/features` (`credentials: 'omit'`, no headers), then `POST
/api/auth/token` (Bearer id-token), `GET /api/billing/balance` (Bearer
jwt), a targeted `POST /api/auth/token` for the freshness check, one
more balance read on refocus, nothing on sign-out |
| website, probe `true` + flag `false` / `'true'` (string) | unpinned |
same, plus one credentialed `GET /api/features` (`credentials:
'include'`, `X-Comfy-Client`) |
| website, all rows | no assertion on `/api/auth/session` or
`X-CSRF-Token` | neither ever appears; header names are pinned, so an
extra header fails |
| billing-web sign-in + billing call | compared only to a run of the
same code | literal: features, `POST /api/auth/token` `{}`, `POST
/api/auth/token` `{workspace_id: 'ws-1'}`, `GET /api/billing/status`,
with header names and `Authorization` values |
| billing-web entry link -> `ws-2` | unpinned | exactly one `POST
/api/auth/token` `{workspace_id: 'ws-2'}`, however often the link
repeats |
| billing-web sign-out | unpinned | stored credential dropped, no
request |

## Tests

`pnpm --filter @comfyorg/website test:unit` (512 files, 9773 tests),
`pnpm --filter @comfyorg/billing-web test:unit` (27 files, 312 tests),
`pnpm typecheck:website`, `pnpm typecheck:billing-web`: green.

Mutation checks, each reverted afterwards:

| Mutation | Result |
|---|---|
| `decideAccountSource` returns `'session'` when the probe is false |
website: 4/4 rows red |
| `credentials: 'omit'` dropped from `readWebSessionProbe` | website:
4/4 red |
| flag read as true for the string `'true'` | website: the `'true'` row
red; billing-web: the `'true'` row red |
| `X-Comfy-Client` sent on the probe | website: 4/4 red |
| billing-web default flips to web-session | billing-web: 9/10 red
(timeouts, since the Firebase path never runs) |
| extra header on the token exchange | website: 4/4 red; billing-web:
6/10 red |
| entry-workspace re-mint removed | billing-web: rebind test red |

## Where this sits

| Item | PR | Ticket | Depends on |
|---|---|---|---|
| Web session, part 1 | Comfy-Org#19390 | FE-3079 | |
| Web session, part 2 | Comfy-Org#19414 | FE-3079 | Comfy-Org#19390 |
| Comfy-Org#19452 | | FE-2900 mint failure copy | |
| F3a | | FE-2899 website balance | |
| Comfy-Org#19450 | | FE-2901 API-key rows | |
| **F5 (this PR)** | | FE-2891 flag-off pins | |
| Comfy-Org#19449 | | FE-2893 docs | |
| Comfy-Org#19457 | | FE-2904 E2E Run | Comfy-Org#19414 |
| Ramp | | FE-2907 | all of the above |

```mermaid
graph LR
  P1["Comfy-Org#19390 FE-3079 part 1"] --> P2["Comfy-Org#19414 FE-3079 part 2"]
  P2 --> F8["F8 FE-2904 E2E Run"]
  F2a["Comfy-Org#19452 FE-2900 mint failure copy"] --> R["FE-2907 ramp"]
  F3a["F3a FE-2899 website balance"] --> R
  F4["Comfy-Org#19450 FE-2901 API-key rows"] --> R
  F5["F5 FE-2891 flag-off pins"] --> R
  F6["Comfy-Org#19449 FE-2893 docs"] --> R
  F8 --> R
  P1 --> R
  P2 --> R
  style F5 fill:#f9c74f,stroke:#000,stroke-width:3px,color:#000
```

- Part of FE-2891
christian-byrne pushed a commit to christian-byrne/ComfyUI_frontend that referenced this pull request Sep 30, 2026
…rg#19457)

## Why

Comfy-Org#19382 covered the queue path with `fetchApi('/prompt')` because Run did
not yet take its token from the web session. With Comfy-Org#19390 and Comfy-Org#19414 it
does, so the E2E should click the real Run button and prove the prompt
carries the session-minted workspace token.

## How

- `WEB_SESSION_MINT` in `fixtures/data/webSession.ts`, typed as
`ExchangeTokenResponse` from `@comfyorg/ingest-types`.
- `webSessionFixture` routes `**/api/auth/token` to that fixture and
records each mint as `{ body, authorization, workspace }` instead of a
string.
- The fixture also mocks billing (`mockBilling`, active subscription) so
Run is not replaced by the subscribe dialog.
- Existing prompt tests click Run via `runDefaultWorkflow`; E2E-06 keeps
`fetchApi` because it needs a bare request.
- New test: exactly one mint `{ workspace_id: 'ws-team' }`, no
`Authorization` header, `x-comfy-workspace-id: ws-team`, and
`extra_data.auth_token_comfy_org === 'session-jwt-e2e'` on the prompt.
- E2E-03: no mint after the switch, exactly one `ws-team` mint after
Run.

Needs Comfy-Org#19390 (billing reads on the session; without it Run opens the
subscribe dialog) and Comfy-Org#19414 (the Run token). Both are merged into main.

## AS IS / TO BE

No UI change.

| Step | AS IS | TO BE |
| --- | --- | --- |
| Queue a prompt | `fetchApi('/prompt')` from `page.evaluate` | Load
default workflow, click Run |
| `/api/auth/token` | Not mocked, mints recorded as strings | Typed
`ExchangeTokenResponse`, mints recorded with body, auth and workspace
header |
| Token asserted | None | One `ws-team` mint, prompt carries
`session-jwt-e2e` |
| E2E-03 mints | Empty after the whole flow | Empty after the switch,
one `ws-team` mint after Run |

## Tests

- `pnpm typecheck:browser`, oxlint and eslint on the touched files:
clean.
- `unifiedWebSession.spec.ts` against a production cloud build (`pnpm
build:cloud`) served by a local ComfyUI backend, `--project=cloud`: 5
passed on main with Comfy-Org#19390 and Comfy-Org#19414 merged, no temporary merges.
- Mutation: `webSessionRunToken` ignored (branch skipped) turns 3 tests
red; token altered to `credential.token + 'x'` turns only the new token
test red (`Received: "session-jwt-e2ex"`). Reverted.

## Where this sits

| PR | Ticket | What |
| --- | --- | --- |
| Comfy-Org#19390 (merged) | FE-3079 part 1 | Workspace API and agent consent on
the session |
| Comfy-Org#19414 (merged) | FE-3079 part 2 | Run token from the session |
| Comfy-Org#19452 | FE-2900 | Mint failure copy |
| Comfy-Org#19454 | FE-2899 | Website balance |
| Comfy-Org#19450 | FE-2901 | API-key rows |
| Comfy-Org#19453 | FE-2891 | Flag-off pins |
| Comfy-Org#19449 | FE-2893 | Docs |
| **Comfy-Org#19457 (this PR)** | FE-2904 | E2E clicks Run, depends on Comfy-Org#19414 |
| FE-2907 | ramp | All of the above feed into it |

```mermaid
graph LR
  A["Comfy-Org#19390 FE-3079 part 1"] --> B["Comfy-Org#19414 FE-3079 part 2"]
  B --> F8["F8 FE-2904 E2E Run (this PR)"]
  F2a["Comfy-Org#19452 FE-2900 mint failure copy"] --> R["FE-2907 ramp"]
  F3a["Comfy-Org#19454 FE-2899 website balance"] --> R
  F4["Comfy-Org#19450 FE-2901 API-key rows"] --> R
  F5["Comfy-Org#19453 FE-2891 flag-off pins"] --> R
  F6["Comfy-Org#19449 FE-2893 docs"] --> R
  A --> R
  B --> R
  F8 --> R
  style F8 fill:#f9d648,stroke:Comfy-Org#333,stroke-width:3px
```

- Part of FE-2904
another-chi pushed a commit to another-chi/ComfyUI_frontend that referenced this pull request Oct 1, 2026
…d web session (Comfy-Org#19756)

## Why

FE-2893 asks for an auth section in each README the shared web session
touches. The account-core doc
(`packages/account-core/docs/web-session.md`) and the billing-web README
are already merged (Comfy-Org#19449). The website README is the last one: it
doesn't yet say where the website gets its account, what changes with
`unified_web_session` on, or why Run still uses the comfy.org login.

## How

A new `## Authentication` section in `apps/website/README.md`, after
"Which Cloud the Workshop talks to". It records what a maintainer can't
read off the code quickly:
- **Flag off (default):** the Firebase login exchanged at
`/api/auth/token`, plus the one anonymous `/api/features` probe the flag
costs.
- **Flag on:**
  - the credentialed flag read with `X-Comfy-Client`;
  - the 800 ms cap before falling back to Firebase;
- the `GET /api/auth/session` identity read on the host-only
`__Host-comfy_session` cookie;
  - the balance read on the cookie;
  - the restore through `POST /api/auth/session`;
- the fact that the website never sends `X-CSRF-Token` or calls
`DELETE`.
- **Not wired yet (F3b):** Run still sends the Firebase-exchanged Bearer
token to the Router with `credentials: 'omit'`. It's blocked on the
backend: the Router must accept session tokens, and comfy.org must be
trusted for credentialed POST.
- **Unchanged clients:** CLI, MCP, Desktop, API keys and localhost keep
their tokens.

It links the ADR and the account-core doc instead of restating them.
Every relative link resolves.

The docs.comfy.org suggestion (one sign-in across comfy.org, Cloud and
billing; Desktop, CLI and API keys unchanged) is drafted separately for
the docs team. It holds back "sign out everywhere" until that has a
button: today only the account-core `revokeAllWebSessions` call exists,
with no UI.

## AS IS / TO BE

Docs only, no UI change.

## Plan position

| Item | PR | Status |
|---|---|---|
| ADR: shared web session on a host-only cookie |
Comfy-Org#18707 | merged |
| account-core doc, billing-web README |
Comfy-Org#19449 | merged |
| **website README auth section** | **this PR** | **in review** |
| docs.comfy.org suggestion | handed to docs | drafted |

```mermaid
graph LR
  ADR["ADR Comfy-Org#18707 merged"] --> AC["account-core + billing-web docs Comfy-Org#19449 merged"]
  AC --> WEB["website README (this PR)"]
  WEB --> DOCS["docs.comfy.org suggestion"]
  style WEB fill:#f9d71c,stroke:Comfy-Org#333,stroke-width:2px
```

Fixes FE-2893
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk:high PR risk grade (advisory shadow check; grader-owned)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants