diff --git a/src/pages/sdk/auth-core/README.mdx b/src/pages/sdk/auth-core/README.mdx index a1dce81..2c8384b 100644 --- a/src/pages/sdk/auth-core/README.mdx +++ b/src/pages/sdk/auth-core/README.mdx @@ -23,6 +23,8 @@ export const metadata = { - [AuthKey](type-aliases/AuthKey.mdx) - [DisplayIdentityKind](type-aliases/DisplayIdentityKind.mdx) +- [IncomingRequestHeaders](type-aliases/IncomingRequestHeaders.mdx) +- [ResolveSessionResult](type-aliases/ResolveSessionResult.mdx) ## Variables @@ -30,6 +32,7 @@ export const metadata = { - [DISPLAY\_IDENTITY\_KINDS](variables/DISPLAY_IDENTITY_KINDS.mdx) - [JWT\_ALG](variables/JWT_ALG.mdx) - [SESSION\_COOKIE](variables/SESSION_COOKIE.mdx) +- [TAB\_SESSION\_HEADER](variables/TAB_SESSION_HEADER.mdx) ## Functions @@ -38,8 +41,10 @@ export const metadata = { - [loadPrivateKey](functions/loadPrivateKey.mdx) - [loadPublicKey](functions/loadPublicKey.mdx) - [parsePublicJwk](functions/parsePublicJwk.mdx) +- [readAllSessionCookies](functions/readAllSessionCookies.mdx) - [readSessionCookie](functions/readSessionCookie.mdx) - [resolveDisplayIdentity](functions/resolveDisplayIdentity.mdx) +- [resolveSessionFromRequest](functions/resolveSessionFromRequest.mdx) - [serializeSessionCookie](functions/serializeSessionCookie.mdx) - [signSession](functions/signSession.mdx) - [verifyOcToken](functions/verifyOcToken.mdx) diff --git a/src/pages/sdk/auth-core/functions/getOcSession.mdx b/src/pages/sdk/auth-core/functions/getOcSession.mdx index 0507bdb..40e25a1 100644 --- a/src/pages/sdk/auth-core/functions/getOcSession.mdx +++ b/src/pages/sdk/auth-core/functions/getOcSession.mdx @@ -13,11 +13,11 @@ export const metadata = { ```ts function getOcSession(headers: - | SessionRequestHeaders -| Headers, options?: VerifyOcOptions): Promise; + | Headers +| SessionRequestHeaders, options?: VerifyOcOptions): Promise; ``` -Defined in: [index.ts:603](https://github.com/orangecheck/oc-packages/blob/main/auth-core/src/index.ts#L603) +Defined in: [index.ts:688](https://github.com/orangecheck/oc-packages/blob/main/auth-core/src/index.ts#L688) Verify the OC session for a request. Accepts either a plain object with `cookie` / `authorization` properties (Express / Next.js / etc.) @@ -33,7 +33,7 @@ Never throws. | Parameter | Type | | ------ | ------ | -| `headers` | \| [`SessionRequestHeaders`](../interfaces/SessionRequestHeaders.mdx) \| `Headers` | +| `headers` | \| `Headers` \| [`SessionRequestHeaders`](../interfaces/SessionRequestHeaders.mdx) | | `options` | [`VerifyOcOptions`](../interfaces/VerifyOcOptions.mdx) | ## Returns diff --git a/src/pages/sdk/auth-core/functions/readAllSessionCookies.mdx b/src/pages/sdk/auth-core/functions/readAllSessionCookies.mdx new file mode 100644 index 0000000..3ede992 --- /dev/null +++ b/src/pages/sdk/auth-core/functions/readAllSessionCookies.mdx @@ -0,0 +1,33 @@ +export const metadata = { + title: "Function: readAllSessionCookies()", + description: "Auto-generated API reference for Function: readAllSessionCookies(). Source: TypeScript types in oc-packages.", +}; + +[**@orangecheck/auth-core**](../README.mdx) + +*** + +[@orangecheck/auth-core](../README.mdx) / readAllSessionCookies + +# Function: readAllSessionCookies() + +```ts +function readAllSessionCookies(cookieHeader: string | null | undefined): string[]; +``` + +Defined in: [index.ts:440](https://github.com/orangecheck/oc-packages/blob/main/auth-core/src/index.ts#L440) + +Read EVERY oc_session value out of a raw `Cookie:` header string. +Multiple same-name cookies are legitimate (e.g. a stale host-scoped +cookie shadowing the `Domain=.ochk.io` one) — verification should +try each rather than trust ordering. + +## Parameters + +| Parameter | Type | +| ------ | ------ | +| `cookieHeader` | `string` \| `null` \| `undefined` | + +## Returns + +`string`[] diff --git a/src/pages/sdk/auth-core/functions/resolveSessionFromRequest.mdx b/src/pages/sdk/auth-core/functions/resolveSessionFromRequest.mdx new file mode 100644 index 0000000..f265a0f --- /dev/null +++ b/src/pages/sdk/auth-core/functions/resolveSessionFromRequest.mdx @@ -0,0 +1,45 @@ +export const metadata = { + title: "Function: resolveSessionFromRequest()", + description: "Auto-generated API reference for Function: resolveSessionFromRequest(). Source: TypeScript types in oc-packages.", +}; + +[**@orangecheck/auth-core**](../README.mdx) + +*** + +[@orangecheck/auth-core](../README.mdx) / resolveSessionFromRequest + +# Function: resolveSessionFromRequest() + +```ts +function resolveSessionFromRequest(headers: IncomingRequestHeaders, cfg: VerifyConfig): Promise; +``` + +Defined in: [index.ts:501](https://github.com/orangecheck/oc-packages/blob/main/auth-core/src/index.ts#L501) + +Resolve the EFFECTIVE session for a request — the per-tab choke +point every consumer's `readJwtSession` should delegate to. + +Precedence: + 1. `x-oc-tab-session` header, when present. **Fail-closed**: a + present-but-invalid tab token resolves to + `{ ok: false, reason: 'tab_invalid' }` rather than silently + falling back to the cookie — falling back would execute the + request as a DIFFERENT account than the tab is displaying, + which is precisely the bug per-tab pinning exists to prevent. + Clients clear their pin on 401 and re-resolve. + 2. Every `oc_session` cookie in the jar, first one that verifies. + +Crypto-only (signature + exp + iss via [verifySessionToken](verifySessionToken.mdx)); +revocation-aware checks remain the auth host's job. Never throws. + +## Parameters + +| Parameter | Type | +| ------ | ------ | +| `headers` | [`IncomingRequestHeaders`](../type-aliases/IncomingRequestHeaders.mdx) | +| `cfg` | [`VerifyConfig`](../interfaces/VerifyConfig.mdx) | + +## Returns + +`Promise`\<[`ResolveSessionResult`](../type-aliases/ResolveSessionResult.mdx)\> diff --git a/src/pages/sdk/auth-core/functions/verifyOcToken.mdx b/src/pages/sdk/auth-core/functions/verifyOcToken.mdx index aca4e5e..99d4085 100644 --- a/src/pages/sdk/auth-core/functions/verifyOcToken.mdx +++ b/src/pages/sdk/auth-core/functions/verifyOcToken.mdx @@ -15,7 +15,7 @@ export const metadata = { function verifyOcToken(token: string, options?: VerifyOcOptions): Promise; ``` -Defined in: [index.ts:547](https://github.com/orangecheck/oc-packages/blob/main/auth-core/src/index.ts#L547) +Defined in: [index.ts:632](https://github.com/orangecheck/oc-packages/blob/main/auth-core/src/index.ts#L632) Verify a JWT issued by an OC auth host. Lazy-fetches the JWKS from `/.well-known/jwks.json`, picks the key whose `kid` matches diff --git a/src/pages/sdk/auth-core/interfaces/SessionRequestHeaders.mdx b/src/pages/sdk/auth-core/interfaces/SessionRequestHeaders.mdx index 7daf0cb..c878fbb 100644 --- a/src/pages/sdk/auth-core/interfaces/SessionRequestHeaders.mdx +++ b/src/pages/sdk/auth-core/interfaces/SessionRequestHeaders.mdx @@ -11,11 +11,11 @@ export const metadata = { # Interface: SessionRequestHeaders -Defined in: [index.ts:587](https://github.com/orangecheck/oc-packages/blob/main/auth-core/src/index.ts#L587) +Defined in: [index.ts:672](https://github.com/orangecheck/oc-packages/blob/main/auth-core/src/index.ts#L672) ## Properties | Property | Type | Defined in | | ------ | ------ | ------ | -| <a id="property-authorization"></a> `authorization?` | `string` \| `null` | [index.ts:589](https://github.com/orangecheck/oc-packages/blob/main/auth-core/src/index.ts#L589) | -| <a id="property-cookie"></a> `cookie?` | `string` \| `null` | [index.ts:588](https://github.com/orangecheck/oc-packages/blob/main/auth-core/src/index.ts#L588) | +| <a id="property-authorization"></a> `authorization?` | `string` \| `null` | [index.ts:674](https://github.com/orangecheck/oc-packages/blob/main/auth-core/src/index.ts#L674) | +| <a id="property-cookie"></a> `cookie?` | `string` \| `null` | [index.ts:673](https://github.com/orangecheck/oc-packages/blob/main/auth-core/src/index.ts#L673) | diff --git a/src/pages/sdk/auth-core/interfaces/VerifyOcOptions.mdx b/src/pages/sdk/auth-core/interfaces/VerifyOcOptions.mdx index f7e3d3f..ad379a5 100644 --- a/src/pages/sdk/auth-core/interfaces/VerifyOcOptions.mdx +++ b/src/pages/sdk/auth-core/interfaces/VerifyOcOptions.mdx @@ -11,11 +11,11 @@ export const metadata = { # Interface: VerifyOcOptions -Defined in: [index.ts:525](https://github.com/orangecheck/oc-packages/blob/main/auth-core/src/index.ts#L525) +Defined in: [index.ts:610](https://github.com/orangecheck/oc-packages/blob/main/auth-core/src/index.ts#L610) ## Properties | Property | Type | Description | Defined in | | ------ | ------ | ------ | ------ | -| <a id="property-issuer"></a> `issuer?` | `string` | Auth host issuer. Defaults to https://ochk.io. | [index.ts:527](https://github.com/orangecheck/oc-packages/blob/main/auth-core/src/index.ts#L527) | -| <a id="property-jwkscachettlms"></a> `jwksCacheTtlMs?` | `number` | JWKS cache TTL in ms. Defaults to 1 hour. Stale-on-error: if the cache exists, verification still works during a transient outage. | [index.ts:530](https://github.com/orangecheck/oc-packages/blob/main/auth-core/src/index.ts#L530) | +| <a id="property-issuer"></a> `issuer?` | `string` | Auth host issuer. Defaults to https://ochk.io. | [index.ts:612](https://github.com/orangecheck/oc-packages/blob/main/auth-core/src/index.ts#L612) | +| <a id="property-jwkscachettlms"></a> `jwksCacheTtlMs?` | `number` | JWKS cache TTL in ms. Defaults to 1 hour. Stale-on-error: if the cache exists, verification still works during a transient outage. | [index.ts:615](https://github.com/orangecheck/oc-packages/blob/main/auth-core/src/index.ts#L615) | diff --git a/src/pages/sdk/auth-core/type-aliases/IncomingRequestHeaders.mdx b/src/pages/sdk/auth-core/type-aliases/IncomingRequestHeaders.mdx new file mode 100644 index 0000000..8629dbd --- /dev/null +++ b/src/pages/sdk/auth-core/type-aliases/IncomingRequestHeaders.mdx @@ -0,0 +1,20 @@ +export const metadata = { + title: "Type Alias: IncomingRequestHeaders", + description: "Auto-generated API reference for Type Alias: IncomingRequestHeaders. Source: TypeScript types in oc-packages.", +}; + +[**@orangecheck/auth-core**](../README.mdx) + +*** + +[@orangecheck/auth-core](../README.mdx) / IncomingRequestHeaders + +# Type Alias: IncomingRequestHeaders + +```ts +type IncomingRequestHeaders = Headers | Record; +``` + +Defined in: [index.ts:473](https://github.com/orangecheck/oc-packages/blob/main/auth-core/src/index.ts#L473) + +Header bag shapes accepted by [resolveSessionFromRequest](../functions/resolveSessionFromRequest.mdx). diff --git a/src/pages/sdk/auth-core/type-aliases/ResolveSessionResult.mdx b/src/pages/sdk/auth-core/type-aliases/ResolveSessionResult.mdx new file mode 100644 index 0000000..fa307bb --- /dev/null +++ b/src/pages/sdk/auth-core/type-aliases/ResolveSessionResult.mdx @@ -0,0 +1,27 @@ +export const metadata = { + title: "Type Alias: ResolveSessionResult", + description: "Auto-generated API reference for Type Alias: ResolveSessionResult. Source: TypeScript types in oc-packages.", +}; + +[**@orangecheck/auth-core**](../README.mdx) + +*** + +[@orangecheck/auth-core](../README.mdx) / ResolveSessionResult + +# Type Alias: ResolveSessionResult + +```ts +type ResolveSessionResult = + | { + ok: true; + payload: SessionPayload; + via: "tab" | "cookie"; +} + | { + ok: false; + reason: "tab_invalid" | "no_session"; +}; +``` + +Defined in: [index.ts:468](https://github.com/orangecheck/oc-packages/blob/main/auth-core/src/index.ts#L468) diff --git a/src/pages/sdk/auth-core/variables/TAB_SESSION_HEADER.mdx b/src/pages/sdk/auth-core/variables/TAB_SESSION_HEADER.mdx new file mode 100644 index 0000000..400f5da --- /dev/null +++ b/src/pages/sdk/auth-core/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-core**](../README.mdx) + +*** + +[@orangecheck/auth-core](../README.mdx) / TAB\_SESSION\_HEADER + +# Variable: TAB\_SESSION\_HEADER + +```ts +const TAB_SESSION_HEADER: "x-oc-tab-session"; +``` + +Defined in: [index.ts:466](https://github.com/orangecheck/oc-packages/blob/main/auth-core/src/index.ts#L466) + +Header carrying a tab-pinned session JWT. Lowercase (Node folds headers).