LCOV - code coverage report
Current view: top level - packages/account-core/src - workspaceLink.ts Coverage Total Hit
Test: ComfyUI E2E Coverage Lines: 38.5 % 26 10
Test Date: 2026-11-17 04:17:53

            Line data    Source code
       1              : /**
       2              :  * The workspace deep-link contract: the one query parameter, `workspace`,
       3              :  * that every surface — the cloud app, comfy.org, and the billing SDK's entry
       4              :  * URL — reads and writes to say which workspace a link is for.
       5              :  *
       6              :  * It is the URL parameter only, never the token API field. `POST
       7              :  * /api/auth/token` still takes `{ workspace_id }` in its request body; that
       8              :  * name does not change here and this module does not touch it.
       9              :  *
      10              :  * A destination applies the link before it loads workspace-scoped content:
      11              :  * it mints a token for the named id and lets the server decide membership,
      12              :  * the same way any other mint does. A payment or billing destination fails
      13              :  * closed on a link it cannot honor and never acts on a workspace other than
      14              :  * the one named — silently falling back to the caller's own active workspace
      15              :  * would bill or expose the wrong one. A navigation destination may fall back
      16              :  * to its own active workspace when the link is absent or invalid, but must
      17              :  * show which workspace it landed on rather than switch silently. The
      18              :  * parameter is carried through the sign-in redirect like any other query
      19              :  * parameter on the path being returned to.
      20              :  */
      21              : 
      22         2356 : export const WORKSPACE_LINK_PARAM = 'workspace'
      23              : 
      24              : export type WorkspaceLinkRead =
      25              :   | { readonly status: 'absent' }
      26              :   | { readonly status: 'ok'; readonly workspaceId: string }
      27              :   | { readonly status: 'invalid' }
      28              : 
      29              : /** Same charset as `@comfyorg/billing-contract`'s identifiers: no path separator, query delimiter, or percent escape survives it. */
      30         2356 : const WORKSPACE_ID = /^[A-Za-z0-9_-]{1,128}$/
      31              : 
      32            8 : export function isWorkspaceId(value: string): boolean {
      33            8 :   return WORKSPACE_ID.test(value)
      34              : }
      35              : 
      36              : /** Reserved by RFC 2606; only used to parse a path+query string that carries no origin of its own. */
      37         2356 : const PARSE_BASE = 'https://workspace-link.invalid/'
      38              : 
      39            0 : function searchParamsOf(
      40              :   source: URL | URLSearchParams | string
      41              : ): URLSearchParams | undefined {
      42            0 :   if (source instanceof URLSearchParams) return source
      43            0 :   if (source instanceof URL) return source.searchParams
      44            0 :   try {
      45            0 :     return new URL(source, PARSE_BASE).searchParams
      46              :   } catch {
      47            0 :     return undefined
      48              :   }
      49              : }
      50              : 
      51              : /**
      52              :  * Reads the link out of a URL, a `URLSearchParams`, or a string (a full URL
      53              :  * or the path-and-query form a router hands over). A missing parameter is
      54              :  * `absent`; a present-but-empty value is `invalid`, the same as any other
      55              :  * value outside the shared charset — an empty `workspace=` is a producer
      56              :  * bug, not "no link," and a payment destination has to fail closed on it
      57              :  * rather than treat it as though the link were never there. A repeated
      58              :  * parameter is also `invalid` rather than picking one, so a caller cannot be
      59              :  * pointed at two different workspaces by ambiguity.
      60              :  */
      61            0 : export function readWorkspaceLink(
      62              :   source: URL | URLSearchParams | string
      63              : ): WorkspaceLinkRead {
      64            0 :   const params = searchParamsOf(source)
      65            0 :   if (!params) return { status: 'absent' }
      66              : 
      67            0 :   const values = params.getAll(WORKSPACE_LINK_PARAM)
      68            0 :   if (values.length === 0) return { status: 'absent' }
      69            0 :   if (values.length > 1) return { status: 'invalid' }
      70              : 
      71            0 :   const [value] = values
      72            0 :   if (!isWorkspaceId(value)) return { status: 'invalid' }
      73              : 
      74            0 :   return { status: 'ok', workspaceId: value }
      75              : }
      76              : 
      77              : /** Returns a new `URL` carrying the link; never mutates `url`. Throws `RangeError` on an id outside the shared charset. */
      78            4 : export function withWorkspaceLink(url: URL, workspaceId: string): URL {
      79            4 :   if (!isWorkspaceId(workspaceId))
      80            0 :     throw new RangeError(`not a workspace id: ${workspaceId}`)
      81            4 :   const next = new URL(url.href)
      82            4 :   next.searchParams.set(WORKSPACE_LINK_PARAM, workspaceId)
      83            4 :   return next
      84              : }
      85              : 
      86              : /** Returns a new `URL` with the link removed; never mutates `url`. */
      87              : export function withoutWorkspaceLink(url: URL): URL {
      88              :   const next = new URL(url.href)
      89              :   next.searchParams.delete(WORKSPACE_LINK_PARAM)
      90              :   return next
      91              : }
        

Generated by: LCOV version 2.0-1