diff --git a/src/pages/sdk/auth-client/README.mdx b/src/pages/sdk/auth-client/README.mdx index 0d9bbd9..bcf1396 100644 --- a/src/pages/sdk/auth-client/README.mdx +++ b/src/pages/sdk/auth-client/README.mdx @@ -23,6 +23,7 @@ export const metadata = { - [OcSessionState](interfaces/OcSessionState.mdx) - [OcSignInButtonProps](interfaces/OcSignInButtonProps.mdx) - [OcSignInProps](interfaces/OcSignInProps.mdx) +- [OcTabSession](interfaces/OcTabSession.mdx) - [RedirectToSudoArgs](interfaces/RedirectToSudoArgs.mdx) - [UseOcAddressSuggestionOptions](interfaces/UseOcAddressSuggestionOptions.mdx) - [UseOcAddressSuggestionReturn](interfaces/UseOcAddressSuggestionReturn.mdx) @@ -49,23 +50,32 @@ export const metadata = { - [DEFAULT\_CONFIG](variables/DEFAULT_CONFIG.mdx) - [DISPLAY\_IDENTITY\_KINDS](variables/DISPLAY_IDENTITY_KINDS.mdx) - [OcAddressInput](variables/OcAddressInput.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) ## Functions - [buildAddAccountUrl](functions/buildAddAccountUrl.mdx) - [buildSignInUrl](functions/buildSignInUrl.mdx) +- [clearTabSession](functions/clearTabSession.mdx) +- [consumeTabAdoptMarker](functions/consumeTabAdoptMarker.mdx) - [fetchOcLinkedIdentities](functions/fetchOcLinkedIdentities.mdx) - [handleSudoRequired](functions/handleSudoRequired.mdx) +- [installTabFetchInterceptor](functions/installTabFetchInterceptor.mdx) - [OcAccountChip](functions/OcAccountChip.mdx) - [OcAccountPill](functions/OcAccountPill.mdx) - [OcLinkedIdentities](functions/OcLinkedIdentities.mdx) - [OcSessionProvider](functions/OcSessionProvider.mdx) - [OcSignIn](functions/OcSignIn.mdx) - [OcSignInButton](functions/OcSignInButton.mdx) +- [readTabSession](functions/readTabSession.mdx) - [redirectToSudo](functions/redirectToSudo.mdx) +- [tabSessionHeader](functions/tabSessionHeader.mdx) - [useOcAddressSuggestion](functions/useOcAddressSuggestion.mdx) - [useOcSession](functions/useOcSession.mdx) - [useOptionalOcSession](functions/useOptionalOcSession.mdx) - [useStepUpAuth](functions/useStepUpAuth.mdx) - [useWebAuthnList](functions/useWebAuthnList.mdx) - [useWebAuthnRegister](functions/useWebAuthnRegister.mdx) +- [writeTabSession](functions/writeTabSession.mdx) diff --git a/src/pages/sdk/auth-client/functions/OcSessionProvider.mdx b/src/pages/sdk/auth-client/functions/OcSessionProvider.mdx index 7ab75f1..3b5688a 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:180](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/provider.tsx#L180) +Defined in: [provider.tsx:190](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/provider.tsx#L190) 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/OcSignIn.mdx b/src/pages/sdk/auth-client/functions/OcSignIn.mdx index 8c4fa48..9c7df56 100644 --- a/src/pages/sdk/auth-client/functions/OcSignIn.mdx +++ b/src/pages/sdk/auth-client/functions/OcSignIn.mdx @@ -15,7 +15,7 @@ export const metadata = { function OcSignIn(__namedParameters: OcSignInProps): ReactElement; ``` -Defined in: [signin.tsx:163](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L163) +Defined in: [signin.tsx:191](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L191) ## Parameters diff --git a/src/pages/sdk/auth-client/functions/buildAddAccountUrl.mdx b/src/pages/sdk/auth-client/functions/buildAddAccountUrl.mdx index 7d855c5..d8ff37a 100644 --- a/src/pages/sdk/auth-client/functions/buildAddAccountUrl.mdx +++ b/src/pages/sdk/auth-client/functions/buildAddAccountUrl.mdx @@ -15,7 +15,7 @@ export const metadata = { function buildAddAccountUrl(cfg: Required, returnTo?: string): string; ``` -Defined in: [types.ts:246](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L246) +Defined in: [types.ts:255](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L255) Multi-account · build the URL for the "add another account" entry point. Same as [buildSignInUrl](buildSignInUrl.mdx) but appends `?add=1` so the diff --git a/src/pages/sdk/auth-client/functions/buildSignInUrl.mdx b/src/pages/sdk/auth-client/functions/buildSignInUrl.mdx index 599cba0..10b1c57 100644 --- a/src/pages/sdk/auth-client/functions/buildSignInUrl.mdx +++ b/src/pages/sdk/auth-client/functions/buildSignInUrl.mdx @@ -15,7 +15,7 @@ export const metadata = { function buildSignInUrl(cfg: Required, returnTo?: string): string; ``` -Defined in: [types.ts:231](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L231) +Defined in: [types.ts:240](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L240) ## Parameters diff --git a/src/pages/sdk/auth-client/functions/clearTabSession.mdx b/src/pages/sdk/auth-client/functions/clearTabSession.mdx new file mode 100644 index 0000000..01dc092 --- /dev/null +++ b/src/pages/sdk/auth-client/functions/clearTabSession.mdx @@ -0,0 +1,22 @@ +export const metadata = { + title: "Function: clearTabSession()", + description: "Auto-generated API reference for Function: clearTabSession(). Source: TypeScript types in oc-packages.", +}; + +[**@orangecheck/auth-client**](../README.mdx) + +*** + +[@orangecheck/auth-client](../README.mdx) / clearTabSession + +# Function: clearTabSession() + +```ts +function clearTabSession(): void; +``` + +Defined in: [tab-session.ts:64](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L64) + +## Returns + +`void` diff --git a/src/pages/sdk/auth-client/functions/consumeTabAdoptMarker.mdx b/src/pages/sdk/auth-client/functions/consumeTabAdoptMarker.mdx new file mode 100644 index 0000000..3ad60f2 --- /dev/null +++ b/src/pages/sdk/auth-client/functions/consumeTabAdoptMarker.mdx @@ -0,0 +1,26 @@ +export const metadata = { + title: "Function: consumeTabAdoptMarker()", + description: "Auto-generated API reference for Function: consumeTabAdoptMarker(). Source: TypeScript types in oc-packages.", +}; + +[**@orangecheck/auth-client**](../README.mdx) + +*** + +[@orangecheck/auth-client](../README.mdx) / consumeTabAdoptMarker + +# Function: consumeTabAdoptMarker() + +```ts +function consumeTabAdoptMarker(): boolean; +``` + +Defined in: [tab-session.ts:148](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L148) + +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 +address bar. Returns `true` when adoption happened. + +## Returns + +`boolean` diff --git a/src/pages/sdk/auth-client/functions/installTabFetchInterceptor.mdx b/src/pages/sdk/auth-client/functions/installTabFetchInterceptor.mdx new file mode 100644 index 0000000..959903c --- /dev/null +++ b/src/pages/sdk/auth-client/functions/installTabFetchInterceptor.mdx @@ -0,0 +1,41 @@ +export const metadata = { + title: "Function: installTabFetchInterceptor()", + description: "Auto-generated API reference for Function: installTabFetchInterceptor(). Source: TypeScript types in oc-packages.", +}; + +[**@orangecheck/auth-client**](../README.mdx) + +*** + +[@orangecheck/auth-client](../README.mdx) / installTabFetchInterceptor + +# Function: installTabFetchInterceptor() + +```ts +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) + +Install a scoped `window.fetch` wrapper that attaches the tab pin to +every same-site request, so app-level data fetches (vault shares, me +wallet, fleet projects, …) execute as the account this tab displays — +without touching any call site. Returns an uninstaller. + +Conservative by design: + - no pin → pass-through (zero behavior change) + - only same-origin + auth-host URLs (see isPinnableUrl) + - never overrides an existing `Authorization` or `x-oc-tab-session` + header (programmatic Bearer / integrator-token paths keep their + own credential semantics) + - any internal error → original fetch, untouched + +## 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 new file mode 100644 index 0000000..b30bb38 --- /dev/null +++ b/src/pages/sdk/auth-client/functions/readTabSession.mdx @@ -0,0 +1,22 @@ +export const metadata = { + title: "Function: readTabSession()", + description: "Auto-generated API reference for Function: readTabSession(). Source: TypeScript types in oc-packages.", +}; + +[**@orangecheck/auth-client**](../README.mdx) + +*** + +[@orangecheck/auth-client](../README.mdx) / readTabSession + +# Function: readTabSession() + +```ts +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) + +## Returns + +[`OcTabSession`](../interfaces/OcTabSession.mdx) \| `null` diff --git a/src/pages/sdk/auth-client/functions/tabSessionHeader.mdx b/src/pages/sdk/auth-client/functions/tabSessionHeader.mdx new file mode 100644 index 0000000..772119c --- /dev/null +++ b/src/pages/sdk/auth-client/functions/tabSessionHeader.mdx @@ -0,0 +1,24 @@ +export const metadata = { + title: "Function: tabSessionHeader()", + description: "Auto-generated API reference for Function: tabSessionHeader(). Source: TypeScript types in oc-packages.", +}; + +[**@orangecheck/auth-client**](../README.mdx) + +*** + +[@orangecheck/auth-client](../README.mdx) / tabSessionHeader + +# Function: tabSessionHeader() + +```ts +function tabSessionHeader(): Record; +``` + +Defined in: [tab-session.ts:74](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L74) + +`{ 'x-oc-tab-session': }` when this tab is pinned, else `{}`. + +## Returns + +`Record`\<`string`, `string`\> diff --git a/src/pages/sdk/auth-client/functions/useOcSession.mdx b/src/pages/sdk/auth-client/functions/useOcSession.mdx index 8b71b67..f03dda6 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:388](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/provider.tsx#L388) +Defined in: [provider.tsx:529](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/provider.tsx#L529) 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 847cf1d..01447ed 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:403](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/provider.tsx#L403) +Defined in: [provider.tsx:544](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/provider.tsx#L544) 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 new file mode 100644 index 0000000..5e49216 --- /dev/null +++ b/src/pages/sdk/auth-client/functions/writeTabSession.mdx @@ -0,0 +1,28 @@ +export const metadata = { + title: "Function: writeTabSession()", + description: "Auto-generated API reference for Function: writeTabSession(). Source: TypeScript types in oc-packages.", +}; + +[**@orangecheck/auth-client**](../README.mdx) + +*** + +[@orangecheck/auth-client](../README.mdx) / writeTabSession + +# Function: writeTabSession() + +```ts +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) + +## Parameters + +| Parameter | Type | +| ------ | ------ | +| `session` | [`OcTabSession`](../interfaces/OcTabSession.mdx) | + +## Returns + +`void` diff --git a/src/pages/sdk/auth-client/interfaces/OcAuthConfig.mdx b/src/pages/sdk/auth-client/interfaces/OcAuthConfig.mdx index 9bc8d95..0dfe2a5 100644 --- a/src/pages/sdk/auth-client/interfaces/OcAuthConfig.mdx +++ b/src/pages/sdk/auth-client/interfaces/OcAuthConfig.mdx @@ -11,13 +11,13 @@ export const metadata = { # Interface: OcAuthConfig -Defined in: [types.ts:186](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L186) +Defined in: [types.ts:195](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L195) ## Properties | Property | Type | Description | Defined in | | ------ | ------ | ------ | ------ | -| <a id="property-authorigin"></a> `authOrigin?` | `string` | Origin of the auth host — the subdomain that runs the sign-in UI, issues session cookies, and exposes `/api/auth/me` + `/api/auth/logout`. Defaults to `https://ochk.io`. Override in preview/dev. | [types.ts:193](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L193) | -| <a id="property-logoutpath"></a> `logoutPath?` | `string` | Path on the auth host to hit to clear the session cookie. Defaults to `/api/auth/logout`. Called with `credentials: 'include'` so the `.ochk.io` cookie is sent along. | [types.ts:217](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L217) | -| <a id="property-mepath"></a> `mePath?` | `string` | Local path (same origin as the current app) that exposes the crypto-verified session. If your app ships one at `/api/auth/me`, leave as default. Returns 200 `{ account }` or 401. | [types.ts:211](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L211) | -| <a id="property-signinpath"></a> `signInPath?` | `string` | Path on the auth host that accepts `?return_to=` and drives the sign-in flow. The page offers two paths in-place: - email + OTP (default — federation-custodied wallet provisioned for the user; identity is `did:email:`) - BIP-322 wallet sign (paste address → in-page wallet sign; identity is the Bitcoin address itself) Defaults to `/signin`. | [types.ts:205](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L205) | +| <a id="property-authorigin"></a> `authOrigin?` | `string` | Origin of the auth host — the subdomain that runs the sign-in UI, issues session cookies, and exposes `/api/auth/me` + `/api/auth/logout`. Defaults to `https://ochk.io`. Override in preview/dev. | [types.ts:202](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L202) | +| <a id="property-logoutpath"></a> `logoutPath?` | `string` | Path on the auth host to hit to clear the session cookie. Defaults to `/api/auth/logout`. Called with `credentials: 'include'` so the `.ochk.io` cookie is sent along. | [types.ts:226](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L226) | +| <a id="property-mepath"></a> `mePath?` | `string` | Local path (same origin as the current app) that exposes the crypto-verified session. If your app ships one at `/api/auth/me`, leave as default. Returns 200 `{ account }` or 401. | [types.ts:220](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L220) | +| <a id="property-signinpath"></a> `signInPath?` | `string` | Path on the auth host that accepts `?return_to=` and drives the sign-in flow. The page offers two paths in-place: - email + OTP (default — federation-custodied wallet provisioned for the user; identity is `did:email:`) - BIP-322 wallet sign (paste address → in-page wallet sign; identity is the Bitcoin address itself) Defaults to `/signin`. | [types.ts:214](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L214) | diff --git a/src/pages/sdk/auth-client/interfaces/OcSessionState.mdx b/src/pages/sdk/auth-client/interfaces/OcSessionState.mdx index 21a9d93..fad67c5 100644 --- a/src/pages/sdk/auth-client/interfaces/OcSessionState.mdx +++ b/src/pages/sdk/auth-client/interfaces/OcSessionState.mdx @@ -18,12 +18,13 @@ Defined in: [types.ts:137](https://github.com/orangecheck/oc-packages/blob/main/ | Property | Type | Description | Defined in | | ------ | ------ | ------ | ------ | | <a id="property-account"></a> `account` | [`OcAccount`](OcAccount.mdx) \| `null` | - | [types.ts:139](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L139) | -| <a id="property-addaccounturl"></a> `addAccountUrl` | (`returnTo?`: `string`) => `string` | Multi-account · open the sign-in flow in "add" mode — the new account joins the current browser's roster instead of replacing it. Returns the URL to navigate to (so callers can mount it in a popup or hard-navigate as they prefer); pass `returnTo` to route back to a specific page after the add completes. | [types.ts:172](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L172) | -| <a id="property-error"></a> `error` | `Error` \| `null` | `null` while loading; an `Error` instance when `status === 'error'`. | [types.ts:148](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L148) | -| <a id="property-refresh"></a> `refresh` | () => `Promise`\<`void`\> | Re-fetch the session. Useful after sign-in/sign-out happens elsewhere. | [types.ts:150](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L150) | +| <a id="property-addaccounturl"></a> `addAccountUrl` | (`returnTo?`: `string`) => `string` | Multi-account · open the sign-in flow in "add" mode — the new account joins the current browser's roster instead of replacing it. Returns the URL to navigate to (so callers can mount it in a popup or hard-navigate as they prefer); pass `returnTo` to route back to a specific page after the add completes. | [types.ts:181](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L181) | +| <a id="property-error"></a> `error` | `Error` \| `null` | `null` while loading; an `Error` instance when `status === 'error'`. | [types.ts:157](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L157) | +| <a id="property-refresh"></a> `refresh` | () => `Promise`\<`void`\> | Re-fetch the session. Useful after sign-in/sign-out happens elsewhere. | [types.ts:159](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L159) | | <a id="property-roster"></a> `roster` | [`OcAccountSummary`](OcAccountSummary.mdx)[] | Multi-account · other accounts the user has signed into in this browser. `[]` for single-account sessions and for tokens minted before multi-account shipped. The active account (`account` above) is NOT included — these are the *switch targets*. | [types.ts:146](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L146) | -| <a id="property-setdisplayidentity"></a> `setDisplayIdentity` | (`kind`: `"email"` \| `"btc"` \| `"did"` \| `"nostr"`) => `Promise`\<`void`\> | Promote a linked identity to be the account-badge label across every `.ochk.io` site. PATCHes the auth host, which re-mints the session cookie with the new `display_identity` claim, then `refresh()`es this session. Rejects if the chosen kind is not a verified identity on the account (`btc` / `email` / `nostr` must actually be linked; `did` is always valid). | [types.ts:181](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L181) | -| <a id="property-signinurl"></a> `signInUrl` | `string` | URL to navigate to for sign-in on the auth host. | [types.ts:183](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L183) | -| <a id="property-signout"></a> `signOut` | (`opts?`: \{ `scope?`: [`OcSignOutScope`](../type-aliases/OcSignOutScope.mdx); \}) => `Promise`\<`void`\> | Trigger a sign-out. By default signs out of EVERY account in the roster (back-compat); pass `{ scope: 'current' }` to sign out of just the active account and stay logged into the next peer. | [types.ts:156](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L156) | +| <a id="property-setdisplayidentity"></a> `setDisplayIdentity` | (`kind`: `"email"` \| `"btc"` \| `"did"` \| `"nostr"`) => `Promise`\<`void`\> | Promote a linked identity to be the account-badge label across every `.ochk.io` site. PATCHes the auth host, which re-mints the session cookie with the new `display_identity` claim, then `refresh()`es this session. Rejects if the chosen kind is not a verified identity on the account (`btc` / `email` / `nostr` must actually be linked; `did` is always valid). | [types.ts:190](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L190) | +| <a id="property-signinurl"></a> `signInUrl` | `string` | URL to navigate to for sign-in on the auth host. | [types.ts:192](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L192) | +| <a id="property-signout"></a> `signOut` | (`opts?`: \{ `scope?`: [`OcSignOutScope`](../type-aliases/OcSignOutScope.mdx); \}) => `Promise`\<`void`\> | Trigger a sign-out. By default signs out of EVERY account in the roster (back-compat); pass `{ scope: 'current' }` to sign out of just the active account and stay logged into the next peer. | [types.ts:165](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L165) | | <a id="property-status"></a> `status` | [`OcSessionStatus`](../type-aliases/OcSessionStatus.mdx) | - | [types.ts:138](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L138) | -| <a id="property-switchaccount"></a> `switchAccount` | (`didOc`: `string`) => `Promise`\<`void`\> | Multi-account · flip the active session to a different account in the roster. Resolves once the new cookie has been set and the session has been re-fetched. Throws if the target `did_oc` isn't in the current roster (the user must add it via addAccount first) or if the auth host is unreachable. | [types.ts:164](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L164) | +| <a id="property-switchaccount"></a> `switchAccount` | (`didOc`: `string`) => `Promise`\<`void`\> | Multi-account · flip the active session to a different account in the roster. Resolves once the new cookie has been set and the session has been re-fetched. Throws if the target `did_oc` isn't in the current roster (the user must add it via addAccount first) or if the auth host is unreachable. | [types.ts:173](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L173) | +| <a id="property-tabpinned"></a> `tabPinned` | `boolean` | Per-tab pinning · `true` when this tab holds its own session token (sessionStorage) and operates as `account` independently of the shared `.ochk.io` cookie — i.e. switching accounts in another tab will NOT change this tab's identity. `false` on hosts that predate `/api/auth/tab`, in privacy modes without sessionStorage, and while anonymous. | [types.ts:155](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L155) | diff --git a/src/pages/sdk/auth-client/interfaces/OcSignInProps.mdx b/src/pages/sdk/auth-client/interfaces/OcSignInProps.mdx index d9f3d99..0502b6f 100644 --- a/src/pages/sdk/auth-client/interfaces/OcSignInProps.mdx +++ b/src/pages/sdk/auth-client/interfaces/OcSignInProps.mdx @@ -11,21 +11,21 @@ export const metadata = { # Interface: OcSignInProps -Defined in: [signin.tsx:42](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L42) +Defined in: [signin.tsx:43](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L43) ## Properties | Property | Type | Description | Defined in | | ------ | ------ | ------ | ------ | -| <a id="property-add"></a> `add?` | `boolean` | Multi-account · when `true`, the sign-in is performed in "add" mode: the resulting session is appended to the browser's existing roster instead of replacing it. The previously-active account stays signed in and remains a switch target on the auth host. Off by default (back-compat). The component also reads `?add=1` from the URL search params and treats it the same — so the auth host's `/signin?add=1` entry point Just Works without any extra prop. The `add` flag is forwarded as a body field to the host's `/api/auth/signin` and `/api/auth/email-otp/verify`; if the host hasn't deployed the multi-account migration yet it silently ignores the field and the call falls back to ordinary signin. | [signin.tsx:119](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L119) | -| <a id="property-audience"></a> `audience` | `string` | Consumer-site audience URL passed as `expectedAudience` on the BIP-322 challenge. e.g. `'https://vault.ochk.io'`. Required — the challenge nonce is bound to this audience. | [signin.tsx:48](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L48) | -| <a id="property-authorigin"></a> `authOrigin?` | `string` | Override the auth host. Defaults to `'https://ochk.io'`. For preview / dev / staging only. | [signin.tsx:82](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L82) | -| <a id="property-classname"></a> `className?` | `string` | className for the outer container. | [signin.tsx:121](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L121) | -| <a id="property-initialpath"></a> `initialPath?` | `"wallet"` \| `"email"` | Initial visible tab on mobile. Defaults to `'wallet'`. On desktop both paths render side-by-side and this is ignored. | [signin.tsx:87](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L87) | -| <a id="property-linkprompt"></a> `linkPrompt?` | `boolean` | Whether to show the "also link my other identity" checkbox on the sign-in form. **On by default.** The checkbox is optional and unchecked by default; it is shown on both the wallet and email paths. If the user ticks it, the complementary identity's link ceremony (BIP-322 for a wallet, OTP for an email) runs inline immediately after a successful sign-in — before `onSuccess` / `returnTo`, so it composes with custom routing — because the sign-in just proved one credential and the link ceremony proves the second. Pass `linkPrompt={false}` to omit the checkbox. | [signin.tsx:104](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L104) | -| <a id="property-onsuccess"></a> `onSuccess?` | (`account`: [`OcAccount`](OcAccount.mdx), `token?`: `string`) => `void` | Override the default hard-navigation behavior. When provided, called with the account and the session JWT. The component will NOT navigate — the caller is responsible. Use for custom post-signin routing — e.g. /popup/signin postMessages `{ account, token }` to its opener so a cross-domain integrator (different eTLD+1 from .ochk.io, which the HttpOnly cookie can't reach) can verify the session via JWKS. | [signin.tsx:64](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L64) | -| <a id="property-paths"></a> `paths?` | \{ `email?`: `boolean`; `wallet?`: `boolean`; \} | Disable one of the two paths. Default is both enabled. Useful for B2B-only sites that don't want to expose email-OTP. | [signin.tsx:92](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L92) | -| `paths.email?` | `boolean` | - | [signin.tsx:92](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L92) | -| `paths.wallet?` | `boolean` | - | [signin.tsx:92](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L92) | -| <a id="property-resolvereturnto"></a> `resolveReturnTo?` | (`account`: [`OcAccount`](OcAccount.mdx)) => `string` \| `Promise`\<`string`\> | Async post-success routing. When provided (and `onSuccess` is not), the component awaits `resolveReturnTo(account)` and hard-navigates to the result instead of the static `returnTo`. This is the seam that lets a site keep persona-aware routing without forking the ceremony — e.g. me.ochk.io resolves `/api/me/intent` and routes to `/me/developer` | `/me/operator` | `/me`. The returned value is open-redirect-checked exactly like `returnTo` (same-origin paths only); on a resolver throw the component falls back to the static `returnTo`. | [signin.tsx:77](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L77) | -| <a id="property-returnto"></a> `returnTo?` | `string` | Where to navigate after success. Defaults to `'/'`. Open-redirect-safe: same-origin paths only (must start with `/`, NOT `//`). Absolute URLs are ignored. | [signin.tsx:54](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L54) | +| <a id="property-add"></a> `add?` | `boolean` | Multi-account · when `true`, the sign-in is performed in "add" mode: the resulting session is appended to the browser's existing roster instead of replacing it. The previously-active account stays signed in and remains a switch target on the auth host. Off by default (back-compat). The component also reads `?add=1` from the URL search params and treats it the same — so the auth host's `/signin?add=1` entry point Just Works without any extra prop. The `add` flag is forwarded as a body field to the host's `/api/auth/signin` and `/api/auth/email-otp/verify`; if the host hasn't deployed the multi-account migration yet it silently ignores the field and the call falls back to ordinary signin. | [signin.tsx:126](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L126) | +| <a id="property-audience"></a> `audience` | `string` | Consumer-site audience URL passed as `expectedAudience` on the BIP-322 challenge. e.g. `'https://vault.ochk.io'`. Required — the challenge nonce is bound to this audience. | [signin.tsx:49](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L49) | +| <a id="property-authorigin"></a> `authOrigin?` | `string` | Override the auth host. Defaults to `'https://ochk.io'`. For preview / dev / staging only. | [signin.tsx:89](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L89) | +| <a id="property-classname"></a> `className?` | `string` | className for the outer container. | [signin.tsx:128](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L128) | +| <a id="property-initialpath"></a> `initialPath?` | `"wallet"` \| `"email"` | Initial visible tab on mobile. Defaults to `'wallet'`. On desktop both paths render side-by-side and this is ignored. | [signin.tsx:94](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L94) | +| <a id="property-linkprompt"></a> `linkPrompt?` | `boolean` | Whether to show the "also link my other identity" checkbox on the sign-in form. **On by default.** The checkbox is optional and unchecked by default; it is shown on both the wallet and email paths. If the user ticks it, the complementary identity's link ceremony (BIP-322 for a wallet, OTP for an email) runs inline immediately after a successful sign-in — before `onSuccess` / `returnTo`, so it composes with custom routing — because the sign-in just proved one credential and the link ceremony proves the second. Pass `linkPrompt={false}` to omit the checkbox. | [signin.tsx:111](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L111) | +| <a id="property-onsuccess"></a> `onSuccess?` | (`account`: [`OcAccount`](OcAccount.mdx), `token?`: `string`) => `void` | Override the default hard-navigation behavior. When provided, called with the account and the session JWT. The component will NOT navigate — the caller is responsible. Use for custom post-signin routing — e.g. /popup/signin postMessages `{ account, token }` to its opener so a cross-domain integrator (different eTLD+1 from .ochk.io, which the HttpOnly cookie can't reach) can verify the session via JWKS. | [signin.tsx:71](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L71) | +| <a id="property-paths"></a> `paths?` | \{ `email?`: `boolean`; `wallet?`: `boolean`; \} | Disable one of the two paths. Default is both enabled. Useful for B2B-only sites that don't want to expose email-OTP. | [signin.tsx:99](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L99) | +| `paths.email?` | `boolean` | - | [signin.tsx:99](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L99) | +| `paths.wallet?` | `boolean` | - | [signin.tsx:99](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L99) | +| <a id="property-resolvereturnto"></a> `resolveReturnTo?` | (`account`: [`OcAccount`](OcAccount.mdx)) => `string` \| `Promise`\<`string`\> | Async post-success routing. When provided (and `onSuccess` is not), the component awaits `resolveReturnTo(account)` and hard-navigates to the result instead of the static `returnTo`. This is the seam that lets a site keep persona-aware routing without forking the ceremony — e.g. me.ochk.io resolves `/api/me/intent` and routes to `/me/developer` | `/me/operator` | `/me`. The returned value is open-redirect-checked exactly like `returnTo` (same-origin paths only); on a resolver throw the component falls back to the static `returnTo`. | [signin.tsx:84](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L84) | +| <a id="property-returnto"></a> `returnTo?` | `string` | Where to navigate after success. Defaults to `'/'`. Open-redirect-safe: a same-origin path (must start with `/`, NOT `//`) or an absolute `https://` URL on `ochk.io` / `*.ochk.io` — the add-another-account flow starts on a consumer subdomain and must round-trip back to it, including through the OAuth provider hop. Anything else is ignored. When omitted, the component reads `?return_to=` (or `?next=`) from the page URL — so the auth host's `/signin?add=1&return_to=…` entry point Just Works, the same way the `add` prop auto-detects `?add=1`. | [signin.tsx:61](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L61) | diff --git a/src/pages/sdk/auth-client/interfaces/OcTabSession.mdx b/src/pages/sdk/auth-client/interfaces/OcTabSession.mdx new file mode 100644 index 0000000..3de0633 --- /dev/null +++ b/src/pages/sdk/auth-client/interfaces/OcTabSession.mdx @@ -0,0 +1,21 @@ +export const metadata = { + title: "Interface: OcTabSession", + description: "Auto-generated API reference for Interface: OcTabSession. Source: TypeScript types in oc-packages.", +}; + +[**@orangecheck/auth-client**](../README.mdx) + +*** + +[@orangecheck/auth-client](../README.mdx) / OcTabSession + +# Interface: OcTabSession + +Defined in: [tab-session.ts:35](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L35) + +## 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) | diff --git a/src/pages/sdk/auth-client/variables/DEFAULT_CONFIG.mdx b/src/pages/sdk/auth-client/variables/DEFAULT_CONFIG.mdx index f6b32d7..b245767 100644 --- a/src/pages/sdk/auth-client/variables/DEFAULT_CONFIG.mdx +++ b/src/pages/sdk/auth-client/variables/DEFAULT_CONFIG.mdx @@ -15,7 +15,7 @@ export const metadata = { const DEFAULT_CONFIG: Required; ``` -Defined in: [types.ts:220](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L220) +Defined in: [types.ts:229](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L229) @orangecheck/auth-client diff --git a/src/pages/sdk/auth-client/variables/TAB_ADOPT_HASH.mdx b/src/pages/sdk/auth-client/variables/TAB_ADOPT_HASH.mdx new file mode 100644 index 0000000..4a0a229 --- /dev/null +++ b/src/pages/sdk/auth-client/variables/TAB_ADOPT_HASH.mdx @@ -0,0 +1,23 @@ +export const metadata = { + title: "Variable: TABADOPTHASH", + description: "Auto-generated API reference for Variable: TABADOPTHASH. Source: TypeScript types in oc-packages.", +}; + +[**@orangecheck/auth-client**](../README.mdx) + +*** + +[@orangecheck/auth-client](../README.mdx) / TAB\_ADOPT\_HASH + +# Variable: TAB\_ADOPT\_HASH + +```ts +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) + +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 +(the user just completed a sign-in/add ceremony and expects to BE the +new account in that tab). Never sent to any server (it's a fragment). diff --git a/src/pages/sdk/auth-client/variables/TAB_SESSION_HEADER.mdx b/src/pages/sdk/auth-client/variables/TAB_SESSION_HEADER.mdx new file mode 100644 index 0000000..b644ff9 --- /dev/null +++ b/src/pages/sdk/auth-client/variables/TAB_SESSION_HEADER.mdx @@ -0,0 +1,20 @@ +export const metadata = { + title: "Variable: TABSESSIONHEADER", + description: "Auto-generated API reference for Variable: TABSESSIONHEADER. Source: TypeScript types in oc-packages.", +}; + +[**@orangecheck/auth-client**](../README.mdx) + +*** + +[@orangecheck/auth-client](../README.mdx) / TAB\_SESSION\_HEADER + +# Variable: TAB\_SESSION\_HEADER + +```ts +const TAB_SESSION_HEADER: "x-oc-tab-session" = 'x-oc-tab-session'; +``` + +Defined in: [tab-session.ts:23](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L23) + +Header carrying the tab-pinned session JWT. Mirrors `@orangecheck/auth-core`'s `TAB_SESSION_HEADER`. diff --git a/src/pages/sdk/auth-client/variables/TAB_SESSION_STORAGE_KEY.mdx b/src/pages/sdk/auth-client/variables/TAB_SESSION_STORAGE_KEY.mdx new file mode 100644 index 0000000..e171592 --- /dev/null +++ b/src/pages/sdk/auth-client/variables/TAB_SESSION_STORAGE_KEY.mdx @@ -0,0 +1,18 @@ +export const metadata = { + title: "Variable: TABSESSIONSTORAGEKEY", + description: "Auto-generated API reference for Variable: TABSESSIONSTORAGEKEY. Source: TypeScript types in oc-packages.", +}; + +[**@orangecheck/auth-client**](../README.mdx) + +*** + +[@orangecheck/auth-client](../README.mdx) / TAB\_SESSION\_STORAGE\_KEY + +# Variable: TAB\_SESSION\_STORAGE\_KEY + +```ts +const TAB_SESSION_STORAGE_KEY: "oc_tab_session" = 'oc_tab_session'; +``` + +Defined in: [tab-session.ts:25](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/tab-session.ts#L25)