diff --git a/src/pages/sdk/auth-client/README.mdx b/src/pages/sdk/auth-client/README.mdx index bcf1396..312f2ca 100644 --- a/src/pages/sdk/auth-client/README.mdx +++ b/src/pages/sdk/auth-client/README.mdx @@ -50,6 +50,7 @@ export const metadata = { - [DEFAULT\_CONFIG](variables/DEFAULT_CONFIG.mdx) - [DISPLAY\_IDENTITY\_KINDS](variables/DISPLAY_IDENTITY_KINDS.mdx) - [OcAddressInput](variables/OcAddressInput.mdx) +- [TAB\_ACCOUNT\_HINT\_KEY](variables/TAB_ACCOUNT_HINT_KEY.mdx) - [TAB\_ADOPT\_HASH](variables/TAB_ADOPT_HASH.mdx) - [TAB\_SESSION\_HEADER](variables/TAB_SESSION_HEADER.mdx) - [TAB\_SESSION\_STORAGE\_KEY](variables/TAB_SESSION_STORAGE_KEY.mdx) @@ -59,10 +60,12 @@ export const metadata = { - [buildAddAccountUrl](functions/buildAddAccountUrl.mdx) - [buildSignInUrl](functions/buildSignInUrl.mdx) - [clearTabSession](functions/clearTabSession.mdx) +- [consumeTabAccountHint](functions/consumeTabAccountHint.mdx) - [consumeTabAdoptMarker](functions/consumeTabAdoptMarker.mdx) - [fetchOcLinkedIdentities](functions/fetchOcLinkedIdentities.mdx) - [handleSudoRequired](functions/handleSudoRequired.mdx) - [installTabFetchInterceptor](functions/installTabFetchInterceptor.mdx) +- [installTabLinkDecorator](functions/installTabLinkDecorator.mdx) - [OcAccountChip](functions/OcAccountChip.mdx) - [OcAccountPill](functions/OcAccountPill.mdx) - [OcLinkedIdentities](functions/OcLinkedIdentities.mdx) diff --git a/src/pages/sdk/auth-client/functions/OcSessionProvider.mdx b/src/pages/sdk/auth-client/functions/OcSessionProvider.mdx index 3b5688a..81a0ef0 100644 --- a/src/pages/sdk/auth-client/functions/OcSessionProvider.mdx +++ b/src/pages/sdk/auth-client/functions/OcSessionProvider.mdx @@ -15,7 +15,7 @@ export const metadata = { function OcSessionProvider(__namedParameters: OcSessionProviderProps): ReactElement; ``` -Defined in: [provider.tsx:190](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/provider.tsx#L190) +Defined in: [provider.tsx:192](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/provider.tsx#L192) Top-level provider that exposes the cross-subdomain oc_session to every component below it. Mount once, near the root of your tree. diff --git a/src/pages/sdk/auth-client/functions/clearTabSession.mdx b/src/pages/sdk/auth-client/functions/clearTabSession.mdx index 01dc092..1f1b8e3 100644 --- a/src/pages/sdk/auth-client/functions/clearTabSession.mdx +++ b/src/pages/sdk/auth-client/functions/clearTabSession.mdx @@ -15,7 +15,7 @@ export const metadata = { function clearTabSession(): void; ``` -Defined in: [tab-session.ts:64](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L64) +Defined in: [tab-session.ts:78](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L78) ## Returns diff --git a/src/pages/sdk/auth-client/functions/consumeTabAccountHint.mdx b/src/pages/sdk/auth-client/functions/consumeTabAccountHint.mdx new file mode 100644 index 0000000..490c4de --- /dev/null +++ b/src/pages/sdk/auth-client/functions/consumeTabAccountHint.mdx @@ -0,0 +1,41 @@ +export const metadata = { + title: "Function: consumeTabAccountHint()", + description: "Auto-generated API reference for Function: consumeTabAccountHint(). Source: TypeScript types in oc-packages.", +}; + +[**@orangecheck/auth-client**](../README.mdx) + +*** + +[@orangecheck/auth-client](../README.mdx) / consumeTabAccountHint + +# Function: consumeTabAccountHint() + +```ts +function consumeTabAccountHint(authOrigin: string): Promise; +``` + +Defined in: [tab-session.ts:300](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L300) + +On load, if the URL carries `#oc-as=`, adopt that account for +THIS tab: mint a pin for it via the host's `/api/auth/tab` (which +re-validates the did is in this browser's roster) and stash it in +sessionStorage, then strip the fragment from the address bar. Must run +BEFORE the provider's first `/api/auth/me` fetch so that fetch carries +the right pin. + +Returns the adopted `did:oc` on success, else null. Best-effort and +fail-safe: a stale host (no targeted minting), a roster miss (403), or +a network error leaves the tab unpinned — exactly the legacy +cookie-following behavior. The fragment is always stripped so it never +lingers in history/bookmarks or re-fires on reload. + +## Parameters + +| Parameter | Type | +| ------ | ------ | +| `authOrigin` | `string` | + +## Returns + +`Promise`\<`string` \| `null`\> diff --git a/src/pages/sdk/auth-client/functions/consumeTabAdoptMarker.mdx b/src/pages/sdk/auth-client/functions/consumeTabAdoptMarker.mdx index 3ad60f2..822394b 100644 --- a/src/pages/sdk/auth-client/functions/consumeTabAdoptMarker.mdx +++ b/src/pages/sdk/auth-client/functions/consumeTabAdoptMarker.mdx @@ -15,7 +15,7 @@ export const metadata = { function consumeTabAdoptMarker(): boolean; ``` -Defined in: [tab-session.ts:148](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L148) +Defined in: [tab-session.ts:162](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L162) If the URL carries the [TAB\_ADOPT\_HASH](../variables/TAB_ADOPT_HASH.mdx) marker, clear the pin (so the tab adopts the cookie account) and strip the marker from the diff --git a/src/pages/sdk/auth-client/functions/installTabFetchInterceptor.mdx b/src/pages/sdk/auth-client/functions/installTabFetchInterceptor.mdx index 959903c..9a4c37f 100644 --- a/src/pages/sdk/auth-client/functions/installTabFetchInterceptor.mdx +++ b/src/pages/sdk/auth-client/functions/installTabFetchInterceptor.mdx @@ -15,7 +15,7 @@ export const metadata = { function installTabFetchInterceptor(authOrigin: string): () => void; ``` -Defined in: [tab-session.ts:108](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L108) +Defined in: [tab-session.ts:122](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L122) Install a scoped `window.fetch` wrapper that attaches the tab pin to every same-site request, so app-level data fetches (vault shares, me diff --git a/src/pages/sdk/auth-client/functions/installTabLinkDecorator.mdx b/src/pages/sdk/auth-client/functions/installTabLinkDecorator.mdx new file mode 100644 index 0000000..e5cf0d6 --- /dev/null +++ b/src/pages/sdk/auth-client/functions/installTabLinkDecorator.mdx @@ -0,0 +1,47 @@ +export const metadata = { + title: "Function: installTabLinkDecorator()", + description: "Auto-generated API reference for Function: installTabLinkDecorator(). Source: TypeScript types in oc-packages.", +}; + +[**@orangecheck/auth-client**](../README.mdx) + +*** + +[@orangecheck/auth-client](../README.mdx) / installTabLinkDecorator + +# Function: installTabLinkDecorator() + +```ts +function installTabLinkDecorator(authOrigin: string): () => void; +``` + +Defined in: [tab-session.ts:252](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L252) + +Install a capture-phase listener that stamps the tab's effective +`did:oc` onto outgoing family-origin links the instant they're +activated, so a new/cross-subdomain tab adopts THIS tab's account. +Returns an uninstaller. Mirrors [installTabFetchInterceptor](installTabFetchInterceptor.mdx)'s +conservatism: + - no pin → never stamps (zero behavior change) + - family origins only → never leaks the did to third parties + - reads the pin FRESH per event (no install-time capture) + - never clobbers an existing `#fragment`, a download, or a + non-http(s) scheme + - any internal error → leaves the link alone + +It mutates `a.href` in place rather than calling `window.open`, so it +never trips a popup blocker and the browser's own ctrl/⌘/middle-click +handling (and the context menu's "open in new tab") all carry the +stamp. The stamp is idempotent and self-healing — React resets the +href on the next render, and the destination strips the fragment via +[consumeTabAccountHint](consumeTabAccountHint.mdx). + +## Parameters + +| Parameter | Type | +| ------ | ------ | +| `authOrigin` | `string` | + +## Returns + +() => `void` diff --git a/src/pages/sdk/auth-client/functions/readTabSession.mdx b/src/pages/sdk/auth-client/functions/readTabSession.mdx index b30bb38..c1f9524 100644 --- a/src/pages/sdk/auth-client/functions/readTabSession.mdx +++ b/src/pages/sdk/auth-client/functions/readTabSession.mdx @@ -15,7 +15,7 @@ export const metadata = { function readTabSession(): OcTabSession | null; ``` -Defined in: [tab-session.ts:40](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L40) +Defined in: [tab-session.ts:54](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L54) ## Returns diff --git a/src/pages/sdk/auth-client/functions/tabSessionHeader.mdx b/src/pages/sdk/auth-client/functions/tabSessionHeader.mdx index 772119c..f89a298 100644 --- a/src/pages/sdk/auth-client/functions/tabSessionHeader.mdx +++ b/src/pages/sdk/auth-client/functions/tabSessionHeader.mdx @@ -15,7 +15,7 @@ export const metadata = { function tabSessionHeader(): Record; ``` -Defined in: [tab-session.ts:74](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L74) +Defined in: [tab-session.ts:88](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L88) `{ 'x-oc-tab-session': }` when this tab is pinned, else `{}`. diff --git a/src/pages/sdk/auth-client/functions/useOcSession.mdx b/src/pages/sdk/auth-client/functions/useOcSession.mdx index f03dda6..c19362f 100644 --- a/src/pages/sdk/auth-client/functions/useOcSession.mdx +++ b/src/pages/sdk/auth-client/functions/useOcSession.mdx @@ -15,7 +15,7 @@ export const metadata = { function useOcSession(): OcSessionState; ``` -Defined in: [provider.tsx:529](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/provider.tsx#L529) +Defined in: [provider.tsx:546](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/provider.tsx#L546) Access the current cross-subdomain oc_session. Must be called inside an ``. diff --git a/src/pages/sdk/auth-client/functions/useOptionalOcSession.mdx b/src/pages/sdk/auth-client/functions/useOptionalOcSession.mdx index 01447ed..86ac08d 100644 --- a/src/pages/sdk/auth-client/functions/useOptionalOcSession.mdx +++ b/src/pages/sdk/auth-client/functions/useOptionalOcSession.mdx @@ -15,7 +15,7 @@ export const metadata = { function useOptionalOcSession(): OcSessionState | null; ``` -Defined in: [provider.tsx:544](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/provider.tsx#L544) +Defined in: [provider.tsx:561](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/provider.tsx#L561) Non-throwing variant — returns `null` if called outside a provider. Useful for libraries that want to read the session *if it exists* but diff --git a/src/pages/sdk/auth-client/functions/writeTabSession.mdx b/src/pages/sdk/auth-client/functions/writeTabSession.mdx index 5e49216..7f2b9af 100644 --- a/src/pages/sdk/auth-client/functions/writeTabSession.mdx +++ b/src/pages/sdk/auth-client/functions/writeTabSession.mdx @@ -15,7 +15,7 @@ export const metadata = { function writeTabSession(session: OcTabSession): void; ``` -Defined in: [tab-session.ts:55](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L55) +Defined in: [tab-session.ts:69](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L69) ## Parameters diff --git a/src/pages/sdk/auth-client/interfaces/OcTabSession.mdx b/src/pages/sdk/auth-client/interfaces/OcTabSession.mdx index 3de0633..045a1b8 100644 --- a/src/pages/sdk/auth-client/interfaces/OcTabSession.mdx +++ b/src/pages/sdk/auth-client/interfaces/OcTabSession.mdx @@ -11,11 +11,11 @@ export const metadata = { # Interface: OcTabSession -Defined in: [tab-session.ts:35](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L35) +Defined in: [tab-session.ts:49](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L49) ## Properties | Property | Type | Defined in | | ------ | ------ | ------ | -| <a id="property-didoc"></a> `didOc` | `string` | [tab-session.ts:37](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L37) | -| <a id="property-token"></a> `token` | `string` | [tab-session.ts:36](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L36) | +| <a id="property-didoc"></a> `didOc` | `string` | [tab-session.ts:51](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L51) | +| <a id="property-token"></a> `token` | `string` | [tab-session.ts:50](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L50) | diff --git a/src/pages/sdk/auth-client/variables/TAB_ACCOUNT_HINT_KEY.mdx b/src/pages/sdk/auth-client/variables/TAB_ACCOUNT_HINT_KEY.mdx new file mode 100644 index 0000000..71a25cf --- /dev/null +++ b/src/pages/sdk/auth-client/variables/TAB_ACCOUNT_HINT_KEY.mdx @@ -0,0 +1,29 @@ +export const metadata = { + title: "Variable: TABACCOUNTHINTKEY", + description: "Auto-generated API reference for Variable: TABACCOUNTHINTKEY. Source: TypeScript types in oc-packages.", +}; + +[**@orangecheck/auth-client**](../README.mdx) + +*** + +[@orangecheck/auth-client](../README.mdx) / TAB\_ACCOUNT\_HINT\_KEY + +# Variable: TAB\_ACCOUNT\_HINT\_KEY + +```ts +const TAB_ACCOUNT_HINT_KEY: "oc-as" = 'oc-as'; +``` + +Defined in: [tab-session.ts:39](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L39) + +URL-fragment key the link decorator stamps onto family-origin +navigations so a NEW tab (or a cross-subdomain document GET) inherits +the OPENER tab's effective account instead of falling back to the +shared cookie's default account. + +The value is the account's `did:oc` — a PUBLIC identifier, never the +session JWT. It rides a fragment (`#oc-as=`), which is never sent +to any server, and the host re-validates roster membership before +minting a tab token for it, so a hand-crafted link grants nothing the +visitor's own cookie/roster doesn't already authorize. diff --git a/src/pages/sdk/auth-client/variables/TAB_ADOPT_HASH.mdx b/src/pages/sdk/auth-client/variables/TAB_ADOPT_HASH.mdx index 4a0a229..acf770b 100644 --- a/src/pages/sdk/auth-client/variables/TAB_ADOPT_HASH.mdx +++ b/src/pages/sdk/auth-client/variables/TAB_ADOPT_HASH.mdx @@ -15,7 +15,7 @@ export const metadata = { const TAB_ADOPT_HASH: "#oc-adopt" = '#oc-adopt'; ``` -Defined in: [tab-session.ts:33](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L33) +Defined in: [tab-session.ts:47](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L47) Hash marker the auth host appends to a post-ceremony redirect so the landing tab adopts the cookie account instead of keeping a stale pin