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 : }
|