@polaris-auth/client 0.11.0 → 0.12.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -129,6 +129,30 @@ and never a loop; every other error, and the challenge when no `captcha` callbac
129
129
  as today. `withToken` keeps the callback. `challengeRetry(options)` is exported for a plain `openapi-fetch`
130
130
  client (`client.use(challengeRetry({ captcha }))`).
131
131
 
132
+ ## Cookie token delivery
133
+
134
+ For a server with `auth.flows.token_delivery: cookie`, the refresh token never reaches JavaScript: it lives
135
+ in an `HttpOnly` cookie scoped to the refresh route.
136
+
137
+ ```ts
138
+ import { createClient, refreshSession } from "@polaris-auth/client";
139
+
140
+ const polaris = createClient({ baseUrl: location.origin, tokenDelivery: "cookie" }); // sends X-Polaris-CSRF: 1
141
+ const login = await polaris.POST("/auth/login", { body: { email, password } }); // data has no refresh_token
142
+ let access = login.data?.data.access_token; // keep it in memory
143
+
144
+ const refreshed = await refreshSession(polaris); // POST /auth/token/refresh with {}, the browser sends the cookie
145
+ access = refreshed.data?.data.access_token;
146
+ await polaris.withToken(access ?? null).POST("/auth/logout"); // clears the cookie
147
+ ```
148
+
149
+ `refreshSession()` serialises refreshes across tabs with the Web Locks API (`polaris:refresh`), so two tabs
150
+ never present the same rotated cookie; it does not schedule refreshes, that stays the application's
151
+ policy. `credentials` stays at the fetch default (`same-origin`); an application on another origin of the
152
+ same site passes `credentials: "include"` and must be in `flows.cookie.trusted_origins`, behind a CORS layer
153
+ the host provides. `data.refresh_token` is optional in the types of the routes that open or rotate a
154
+ session, since cookie mode omits it.
155
+
132
156
  ## Development
133
157
 
134
158
  ```sh
@@ -348,7 +348,7 @@ export declare function anonymous(client: Client<paths>): {
348
348
  access_token: string;
349
349
  token_type: string;
350
350
  expires_in: number;
351
- refresh_token: string;
351
+ refresh_token?: string;
352
352
  user: {
353
353
  id: string;
354
354
  email: string;
@@ -379,7 +379,7 @@ export declare function anonymous(client: Client<paths>): {
379
379
  access_token: string;
380
380
  token_type: string;
381
381
  expires_in: number;
382
- refresh_token: string;
382
+ refresh_token?: string;
383
383
  user: {
384
384
  id: string;
385
385
  email: string;
@@ -417,7 +417,7 @@ export declare function anonymous(client: Client<paths>): {
417
417
  access_token: string;
418
418
  token_type: string;
419
419
  expires_in: number;
420
- refresh_token: string;
420
+ refresh_token?: string;
421
421
  user: {
422
422
  id: string;
423
423
  email: string;
@@ -458,7 +458,7 @@ export declare function anonymous(client: Client<paths>): {
458
458
  access_token: string;
459
459
  token_type: string;
460
460
  expires_in: number;
461
- refresh_token: string;
461
+ refresh_token?: string;
462
462
  user: {
463
463
  id: string;
464
464
  email: string;
@@ -489,7 +489,7 @@ export declare function anonymous(client: Client<paths>): {
489
489
  access_token: string;
490
490
  token_type: string;
491
491
  expires_in: number;
492
- refresh_token: string;
492
+ refresh_token?: string;
493
493
  user: {
494
494
  id: string;
495
495
  email: string;
@@ -0,0 +1,69 @@
1
+ import type { Client, Middleware } from "openapi-fetch";
2
+ import type { paths } from "./schema.js";
3
+ /** The header a cookie-mode client sends on every request; the server's CSRF guard requires it on every route that sets or uses the refresh cookie. */
4
+ export declare const CSRF_HEADER = "X-Polaris-CSRF";
5
+ /** How the server delivers the refresh token: in the JSON body (the default) or in an `HttpOnly` cookie the client never sees. */
6
+ export type TokenDelivery = "body" | "cookie";
7
+ /** Adds `X-Polaris-CSRF: 1` to every request, for a server with `auth.flows.token_delivery: cookie`. */
8
+ export declare function cookieDelivery(): Middleware;
9
+ declare function refresh(client: Client<paths>): Promise<import("openapi-fetch").FetchResponse<{
10
+ parameters: {
11
+ query?: never;
12
+ header?: never;
13
+ path?: never;
14
+ cookie?: never;
15
+ };
16
+ requestBody: {
17
+ content: {
18
+ "application/json": {
19
+ refresh_token?: string;
20
+ };
21
+ };
22
+ };
23
+ responses: {
24
+ 200: {
25
+ headers: {
26
+ [name: string]: unknown;
27
+ };
28
+ content: {
29
+ "application/json": {
30
+ data: {
31
+ access_token: string;
32
+ token_type: string;
33
+ expires_in: number;
34
+ refresh_token?: string;
35
+ };
36
+ };
37
+ };
38
+ };
39
+ 401: {
40
+ headers: {
41
+ [name: string]: unknown;
42
+ };
43
+ content: {
44
+ "application/json": import("./schema.js").components["schemas"]["Error"];
45
+ };
46
+ };
47
+ 422: {
48
+ headers: {
49
+ [name: string]: unknown;
50
+ };
51
+ content: {
52
+ "application/json": import("./schema.js").components["schemas"]["ValidationError"];
53
+ };
54
+ };
55
+ };
56
+ }, {
57
+ body: {};
58
+ }, `${string}/${string}`>>;
59
+ /** What `refreshSession()` answers: the refresh route's response, as `client.POST` answers it. */
60
+ export type RefreshSessionResult = Awaited<ReturnType<typeof refresh>>;
61
+ /**
62
+ * Rotates the session in cookie mode: posts an empty body to `/auth/token/refresh`, whose cookie the
63
+ * browser sends, and answers the new access token in `data`. Refreshes are serialised across the tabs of
64
+ * a browser profile through the Web Locks API, so two tabs never present the same rotated cookie (the
65
+ * server would take the second as a replay and end the session); a tab waiting for the lock refreshes
66
+ * with the cookie the first one received. Without Web Locks, concurrent calls in one tab share one request.
67
+ */
68
+ export declare function refreshSession(client: Client<paths>): Promise<RefreshSessionResult>;
69
+ export {};
package/dist/cookie.js ADDED
@@ -0,0 +1,34 @@
1
+ /** The header a cookie-mode client sends on every request; the server's CSRF guard requires it on every route that sets or uses the refresh cookie. */
2
+ export const CSRF_HEADER = "X-Polaris-CSRF";
3
+ /** Adds `X-Polaris-CSRF: 1` to every request, for a server with `auth.flows.token_delivery: cookie`. */
4
+ export function cookieDelivery() {
5
+ return {
6
+ onRequest({ request }) {
7
+ request.headers.set(CSRF_HEADER, "1");
8
+ return request;
9
+ },
10
+ };
11
+ }
12
+ function refresh(client) {
13
+ // The refresh cookie is the credential; the body is empty.
14
+ return client.POST("/auth/token/refresh", { body: {} });
15
+ }
16
+ let inFlight = null;
17
+ /**
18
+ * Rotates the session in cookie mode: posts an empty body to `/auth/token/refresh`, whose cookie the
19
+ * browser sends, and answers the new access token in `data`. Refreshes are serialised across the tabs of
20
+ * a browser profile through the Web Locks API, so two tabs never present the same rotated cookie (the
21
+ * server would take the second as a replay and end the session); a tab waiting for the lock refreshes
22
+ * with the cookie the first one received. Without Web Locks, concurrent calls in one tab share one request.
23
+ */
24
+ export function refreshSession(client) {
25
+ const locks = globalThis.navigator?.locks;
26
+ if (locks !== undefined) {
27
+ // The DOM typing wraps the callback's promise once more; the runtime resolves it.
28
+ return locks.request("polaris:refresh", () => refresh(client)).then((result) => result);
29
+ }
30
+ inFlight ??= refresh(client).finally(() => {
31
+ inFlight = null;
32
+ });
33
+ return inFlight;
34
+ }
package/dist/index.d.ts CHANGED
@@ -3,6 +3,7 @@ import { type AdminApi } from "./admin.js";
3
3
  import { type AnonymousApi } from "./anonymous.js";
4
4
  import { type AuditApi } from "./audit.js";
5
5
  import { type ChallengeOptions } from "./challenge.js";
6
+ import { type TokenDelivery } from "./cookie.js";
6
7
  import { type MultiSessionApi } from "./multi-session.js";
7
8
  import { type PasskeyApi } from "./passkey.js";
8
9
  import { type PasswordlessApi } from "./passwordless.js";
@@ -21,6 +22,7 @@ export { admin, type AdminApi } from "./admin.js";
21
22
  export { anonymous, type AnonymousApi } from "./anonymous.js";
22
23
  export { audit, type AuditApi } from "./audit.js";
23
24
  export { challengeRetry, type ChallengeOptions } from "./challenge.js";
25
+ export { CSRF_HEADER, cookieDelivery, refreshSession, type RefreshSessionResult, type TokenDelivery } from "./cookie.js";
24
26
  export { multiSession, type MultiSessionApi } from "./multi-session.js";
25
27
  export { passkey, type PasskeyApi } from "./passkey.js";
26
28
  export { passwordless, type PasswordlessApi } from "./passwordless.js";
@@ -51,6 +53,14 @@ export interface PolarisClientOptions extends ClientOptions {
51
53
  * in the body. Without it the problem document is returned as any other error.
52
54
  */
53
55
  challenge?: ChallengeOptions;
56
+ /**
57
+ * `"cookie"` for a server with `auth.flows.token_delivery: cookie`: the refresh token never reaches
58
+ * the client (an `HttpOnly` cookie scoped to the refresh route), every request carries the
59
+ * `X-Polaris-CSRF: 1` header the server's guard requires, and `refreshSession(client)` rotates the
60
+ * session. `credentials` stays at the fetch default (`same-origin`); an application on a trusted
61
+ * origin passes `credentials: "include"` itself. Default `"body"`.
62
+ */
63
+ tokenDelivery?: TokenDelivery;
54
64
  }
55
65
  export interface PolarisClient extends Client<paths> {
56
66
  /** The token this client sends; null when anonymous. */
@@ -96,7 +106,8 @@ export interface PolarisClient extends Client<paths> {
96
106
  * `client.POST("/auth/login", { body })` checks the body and types `data` and `error`; the plugins' routes
97
107
  * are also methods of `client.audit`, `client.admin`, `client.sentinel`, `client.sso`, `client.scim`, `client.passwordless`,
98
108
  * `client.username`, `client.anonymous`, `client.multiSession`, `client.social`, `client.passkey`, `client.apiKeys`, `client.oauth`, `client.mcp` and `client.agents`; `challenge.captcha`
99
- * answers a sentinel captcha challenge with one retry. No refresh loop and no storage: when to refresh
100
- * and where to keep tokens is the application's policy.
109
+ * answers a sentinel captcha challenge with one retry; `tokenDelivery: "cookie"` sends the CSRF header cookie
110
+ * mode requires. No refresh loop and no storage: when to refresh and where to keep tokens is the
111
+ * application's policy (`refreshSession()` serialises a cookie-mode refresh, it does not schedule one).
101
112
  */
102
113
  export declare function createClient(options: PolarisClientOptions): PolarisClient;
package/dist/index.js CHANGED
@@ -3,6 +3,7 @@ import { admin } from "./admin.js";
3
3
  import { anonymous } from "./anonymous.js";
4
4
  import { audit } from "./audit.js";
5
5
  import { challengeRetry } from "./challenge.js";
6
+ import { cookieDelivery } from "./cookie.js";
6
7
  import { multiSession } from "./multi-session.js";
7
8
  import { passkey } from "./passkey.js";
8
9
  import { passwordless } from "./passwordless.js";
@@ -19,6 +20,7 @@ export { admin } from "./admin.js";
19
20
  export { anonymous } from "./anonymous.js";
20
21
  export { audit } from "./audit.js";
21
22
  export { challengeRetry } from "./challenge.js";
23
+ export { CSRF_HEADER, cookieDelivery, refreshSession } from "./cookie.js";
22
24
  export { multiSession } from "./multi-session.js";
23
25
  export { passkey } from "./passkey.js";
24
26
  export { passwordless } from "./passwordless.js";
@@ -37,12 +39,16 @@ export { registerPasskey, signInWithPasskey, passkeyAssertion, passkeyAutofillAv
37
39
  * `client.POST("/auth/login", { body })` checks the body and types `data` and `error`; the plugins' routes
38
40
  * are also methods of `client.audit`, `client.admin`, `client.sentinel`, `client.sso`, `client.scim`, `client.passwordless`,
39
41
  * `client.username`, `client.anonymous`, `client.multiSession`, `client.social`, `client.passkey`, `client.apiKeys`, `client.oauth`, `client.mcp` and `client.agents`; `challenge.captcha`
40
- * answers a sentinel captcha challenge with one retry. No refresh loop and no storage: when to refresh
41
- * and where to keep tokens is the application's policy.
42
+ * answers a sentinel captcha challenge with one retry; `tokenDelivery: "cookie"` sends the CSRF header cookie
43
+ * mode requires. No refresh loop and no storage: when to refresh and where to keep tokens is the
44
+ * application's policy (`refreshSession()` serialises a cookie-mode refresh, it does not schedule one).
42
45
  */
43
46
  export function createClient(options) {
44
- const { token = null, challenge, ...clientOptions } = options;
47
+ const { token = null, challenge, tokenDelivery = "body", ...clientOptions } = options;
45
48
  const client = createOpenApiClient(clientOptions);
49
+ if (tokenDelivery === "cookie") {
50
+ client.use(cookieDelivery());
51
+ }
46
52
  if (challenge !== undefined) {
47
53
  client.use(challengeRetry(challenge));
48
54
  }
@@ -755,7 +755,7 @@ export declare function multiSession(client: Client<paths>): {
755
755
  access_token: string;
756
756
  token_type: string;
757
757
  expires_in: number;
758
- refresh_token: string;
758
+ refresh_token?: string;
759
759
  user: {
760
760
  id: string;
761
761
  email: string;
@@ -824,7 +824,7 @@ export declare function multiSession(client: Client<paths>): {
824
824
  access_token: string;
825
825
  token_type: string;
826
826
  expires_in: number;
827
- refresh_token: string;
827
+ refresh_token?: string;
828
828
  user: {
829
829
  id: string;
830
830
  email: string;
@@ -900,7 +900,7 @@ export declare function multiSession(client: Client<paths>): {
900
900
  access_token: string;
901
901
  token_type: string;
902
902
  expires_in: number;
903
- refresh_token: string;
903
+ refresh_token?: string;
904
904
  user: {
905
905
  id: string;
906
906
  email: string;
@@ -981,7 +981,7 @@ export declare function multiSession(client: Client<paths>): {
981
981
  access_token: string;
982
982
  token_type: string;
983
983
  expires_in: number;
984
- refresh_token: string;
984
+ refresh_token?: string;
985
985
  user: {
986
986
  id: string;
987
987
  email: string;
@@ -1050,7 +1050,7 @@ export declare function multiSession(client: Client<paths>): {
1050
1050
  access_token: string;
1051
1051
  token_type: string;
1052
1052
  expires_in: number;
1053
- refresh_token: string;
1053
+ refresh_token?: string;
1054
1054
  user: {
1055
1055
  id: string;
1056
1056
  email: string;
package/dist/passkey.d.ts CHANGED
@@ -218,7 +218,7 @@ export declare function passkey(client: Client<paths>): {
218
218
  access_token: string;
219
219
  token_type: string;
220
220
  expires_in: number;
221
- refresh_token: string;
221
+ refresh_token?: string;
222
222
  user: {
223
223
  id: string;
224
224
  email: string;
@@ -273,7 +273,7 @@ export declare function passkey(client: Client<paths>): {
273
273
  access_token: string;
274
274
  token_type: string;
275
275
  expires_in: number;
276
- refresh_token: string;
276
+ refresh_token?: string;
277
277
  user: {
278
278
  id: string;
279
279
  email: string;
@@ -335,7 +335,7 @@ export declare function passkey(client: Client<paths>): {
335
335
  access_token: string;
336
336
  token_type: string;
337
337
  expires_in: number;
338
- refresh_token: string;
338
+ refresh_token?: string;
339
339
  user: {
340
340
  id: string;
341
341
  email: string;
@@ -404,7 +404,7 @@ export declare function passkey(client: Client<paths>): {
404
404
  access_token: string;
405
405
  token_type: string;
406
406
  expires_in: number;
407
- refresh_token: string;
407
+ refresh_token?: string;
408
408
  user: {
409
409
  id: string;
410
410
  email: string;
@@ -459,7 +459,7 @@ export declare function passkey(client: Client<paths>): {
459
459
  access_token: string;
460
460
  token_type: string;
461
461
  expires_in: number;
462
- refresh_token: string;
462
+ refresh_token?: string;
463
463
  user: {
464
464
  id: string;
465
465
  email: string;
@@ -513,7 +513,7 @@ export declare function passwordless(client: Client<paths>): {
513
513
  access_token: string;
514
514
  token_type: string;
515
515
  expires_in: number;
516
- refresh_token: string;
516
+ refresh_token?: string;
517
517
  user: {
518
518
  id: string;
519
519
  email: string;
@@ -567,7 +567,7 @@ export declare function passwordless(client: Client<paths>): {
567
567
  access_token: string;
568
568
  token_type: string;
569
569
  expires_in: number;
570
- refresh_token: string;
570
+ refresh_token?: string;
571
571
  user: {
572
572
  id: string;
573
573
  email: string;
@@ -628,7 +628,7 @@ export declare function passwordless(client: Client<paths>): {
628
628
  access_token: string;
629
629
  token_type: string;
630
630
  expires_in: number;
631
- refresh_token: string;
631
+ refresh_token?: string;
632
632
  user: {
633
633
  id: string;
634
634
  email: string;
@@ -695,7 +695,7 @@ export declare function passwordless(client: Client<paths>): {
695
695
  access_token: string;
696
696
  token_type: string;
697
697
  expires_in: number;
698
- refresh_token: string;
698
+ refresh_token?: string;
699
699
  user: {
700
700
  id: string;
701
701
  email: string;
@@ -749,7 +749,7 @@ export declare function passwordless(client: Client<paths>): {
749
749
  access_token: string;
750
750
  token_type: string;
751
751
  expires_in: number;
752
- refresh_token: string;
752
+ refresh_token?: string;
753
753
  user: {
754
754
  id: string;
755
755
  email: string;
@@ -1053,7 +1053,7 @@ export declare function passwordless(client: Client<paths>): {
1053
1053
  access_token: string;
1054
1054
  token_type: string;
1055
1055
  expires_in: number;
1056
- refresh_token: string;
1056
+ refresh_token?: string;
1057
1057
  user: {
1058
1058
  id: string;
1059
1059
  email: string;
@@ -1098,7 +1098,7 @@ export declare function passwordless(client: Client<paths>): {
1098
1098
  access_token: string;
1099
1099
  token_type: string;
1100
1100
  expires_in: number;
1101
- refresh_token: string;
1101
+ refresh_token?: string;
1102
1102
  user: {
1103
1103
  id: string;
1104
1104
  email: string;
@@ -1150,7 +1150,7 @@ export declare function passwordless(client: Client<paths>): {
1150
1150
  access_token: string;
1151
1151
  token_type: string;
1152
1152
  expires_in: number;
1153
- refresh_token: string;
1153
+ refresh_token?: string;
1154
1154
  user: {
1155
1155
  id: string;
1156
1156
  email: string;
@@ -1207,7 +1207,7 @@ export declare function passwordless(client: Client<paths>): {
1207
1207
  access_token: string;
1208
1208
  token_type: string;
1209
1209
  expires_in: number;
1210
- refresh_token: string;
1210
+ refresh_token?: string;
1211
1211
  user: {
1212
1212
  id: string;
1213
1213
  email: string;
@@ -1252,7 +1252,7 @@ export declare function passwordless(client: Client<paths>): {
1252
1252
  access_token: string;
1253
1253
  token_type: string;
1254
1254
  expires_in: number;
1255
- refresh_token: string;
1255
+ refresh_token?: string;
1256
1256
  user: {
1257
1257
  id: string;
1258
1258
  email: string;
@@ -2009,7 +2009,7 @@ export declare function passwordless(client: Client<paths>): {
2009
2009
  access_token: string;
2010
2010
  token_type: string;
2011
2011
  expires_in: number;
2012
- refresh_token: string;
2012
+ refresh_token?: string;
2013
2013
  user: {
2014
2014
  id: string;
2015
2015
  email: string;
@@ -2054,7 +2054,7 @@ export declare function passwordless(client: Client<paths>): {
2054
2054
  access_token: string;
2055
2055
  token_type: string;
2056
2056
  expires_in: number;
2057
- refresh_token: string;
2057
+ refresh_token?: string;
2058
2058
  user: {
2059
2059
  id: string;
2060
2060
  email: string;
@@ -2106,7 +2106,7 @@ export declare function passwordless(client: Client<paths>): {
2106
2106
  access_token: string;
2107
2107
  token_type: string;
2108
2108
  expires_in: number;
2109
- refresh_token: string;
2109
+ refresh_token?: string;
2110
2110
  user: {
2111
2111
  id: string;
2112
2112
  email: string;
@@ -2163,7 +2163,7 @@ export declare function passwordless(client: Client<paths>): {
2163
2163
  access_token: string;
2164
2164
  token_type: string;
2165
2165
  expires_in: number;
2166
- refresh_token: string;
2166
+ refresh_token?: string;
2167
2167
  user: {
2168
2168
  id: string;
2169
2169
  email: string;
@@ -2208,7 +2208,7 @@ export declare function passwordless(client: Client<paths>): {
2208
2208
  access_token: string;
2209
2209
  token_type: string;
2210
2210
  expires_in: number;
2211
- refresh_token: string;
2211
+ refresh_token?: string;
2212
2212
  user: {
2213
2213
  id: string;
2214
2214
  email: string;
@@ -3079,7 +3079,7 @@ export declare function passwordless(client: Client<paths>): {
3079
3079
  access_token: string;
3080
3080
  token_type: string;
3081
3081
  expires_in: number;
3082
- refresh_token: string;
3082
+ refresh_token?: string;
3083
3083
  user: {
3084
3084
  id: string;
3085
3085
  email: string;
@@ -3133,7 +3133,7 @@ export declare function passwordless(client: Client<paths>): {
3133
3133
  access_token: string;
3134
3134
  token_type: string;
3135
3135
  expires_in: number;
3136
- refresh_token: string;
3136
+ refresh_token?: string;
3137
3137
  user: {
3138
3138
  id: string;
3139
3139
  email: string;
@@ -3194,7 +3194,7 @@ export declare function passwordless(client: Client<paths>): {
3194
3194
  access_token: string;
3195
3195
  token_type: string;
3196
3196
  expires_in: number;
3197
- refresh_token: string;
3197
+ refresh_token?: string;
3198
3198
  user: {
3199
3199
  id: string;
3200
3200
  email: string;
@@ -3261,7 +3261,7 @@ export declare function passwordless(client: Client<paths>): {
3261
3261
  access_token: string;
3262
3262
  token_type: string;
3263
3263
  expires_in: number;
3264
- refresh_token: string;
3264
+ refresh_token?: string;
3265
3265
  user: {
3266
3266
  id: string;
3267
3267
  email: string;
@@ -3315,7 +3315,7 @@ export declare function passwordless(client: Client<paths>): {
3315
3315
  access_token: string;
3316
3316
  token_type: string;
3317
3317
  expires_in: number;
3318
- refresh_token: string;
3318
+ refresh_token?: string;
3319
3319
  user: {
3320
3320
  id: string;
3321
3321
  email: string;
package/dist/social.d.ts CHANGED
@@ -980,7 +980,7 @@ export declare function social(client: Client<paths>): {
980
980
  access_token: string;
981
981
  token_type: string;
982
982
  expires_in: number;
983
- refresh_token: string;
983
+ refresh_token?: string;
984
984
  user: {
985
985
  id: string;
986
986
  email: string;
@@ -1025,7 +1025,7 @@ export declare function social(client: Client<paths>): {
1025
1025
  access_token: string;
1026
1026
  token_type: string;
1027
1027
  expires_in: number;
1028
- refresh_token: string;
1028
+ refresh_token?: string;
1029
1029
  user: {
1030
1030
  id: string;
1031
1031
  email: string;
@@ -1077,7 +1077,7 @@ export declare function social(client: Client<paths>): {
1077
1077
  access_token: string;
1078
1078
  token_type: string;
1079
1079
  expires_in: number;
1080
- refresh_token: string;
1080
+ refresh_token?: string;
1081
1081
  user: {
1082
1082
  id: string;
1083
1083
  email: string;
@@ -1134,7 +1134,7 @@ export declare function social(client: Client<paths>): {
1134
1134
  access_token: string;
1135
1135
  token_type: string;
1136
1136
  expires_in: number;
1137
- refresh_token: string;
1137
+ refresh_token?: string;
1138
1138
  user: {
1139
1139
  id: string;
1140
1140
  email: string;
@@ -1179,7 +1179,7 @@ export declare function social(client: Client<paths>): {
1179
1179
  access_token: string;
1180
1180
  token_type: string;
1181
1181
  expires_in: number;
1182
- refresh_token: string;
1182
+ refresh_token?: string;
1183
1183
  user: {
1184
1184
  id: string;
1185
1185
  email: string;
@@ -1574,7 +1574,7 @@ export declare function social(client: Client<paths>): {
1574
1574
  access_token: string;
1575
1575
  token_type: string;
1576
1576
  expires_in: number;
1577
- refresh_token: string;
1577
+ refresh_token?: string;
1578
1578
  user: {
1579
1579
  id: string;
1580
1580
  email: string;
@@ -1643,7 +1643,7 @@ export declare function social(client: Client<paths>): {
1643
1643
  access_token: string;
1644
1644
  token_type: string;
1645
1645
  expires_in: number;
1646
- refresh_token: string;
1646
+ refresh_token?: string;
1647
1647
  user: {
1648
1648
  id: string;
1649
1649
  email: string;
@@ -1719,7 +1719,7 @@ export declare function social(client: Client<paths>): {
1719
1719
  access_token: string;
1720
1720
  token_type: string;
1721
1721
  expires_in: number;
1722
- refresh_token: string;
1722
+ refresh_token?: string;
1723
1723
  user: {
1724
1724
  id: string;
1725
1725
  email: string;
@@ -1800,7 +1800,7 @@ export declare function social(client: Client<paths>): {
1800
1800
  access_token: string;
1801
1801
  token_type: string;
1802
1802
  expires_in: number;
1803
- refresh_token: string;
1803
+ refresh_token?: string;
1804
1804
  user: {
1805
1805
  id: string;
1806
1806
  email: string;
@@ -1869,7 +1869,7 @@ export declare function social(client: Client<paths>): {
1869
1869
  access_token: string;
1870
1870
  token_type: string;
1871
1871
  expires_in: number;
1872
- refresh_token: string;
1872
+ refresh_token?: string;
1873
1873
  user: {
1874
1874
  id: string;
1875
1875
  email: string;
package/dist/sso.d.ts CHANGED
@@ -2127,7 +2127,7 @@ export declare function sso(client: Client<paths>): {
2127
2127
  access_token: string;
2128
2128
  token_type: string;
2129
2129
  expires_in: number;
2130
- refresh_token: string;
2130
+ refresh_token?: string;
2131
2131
  user: {
2132
2132
  id: string;
2133
2133
  email: string;
@@ -2172,7 +2172,7 @@ export declare function sso(client: Client<paths>): {
2172
2172
  access_token: string;
2173
2173
  token_type: string;
2174
2174
  expires_in: number;
2175
- refresh_token: string;
2175
+ refresh_token?: string;
2176
2176
  user: {
2177
2177
  id: string;
2178
2178
  email: string;
@@ -2224,7 +2224,7 @@ export declare function sso(client: Client<paths>): {
2224
2224
  access_token: string;
2225
2225
  token_type: string;
2226
2226
  expires_in: number;
2227
- refresh_token: string;
2227
+ refresh_token?: string;
2228
2228
  user: {
2229
2229
  id: string;
2230
2230
  email: string;
@@ -2281,7 +2281,7 @@ export declare function sso(client: Client<paths>): {
2281
2281
  access_token: string;
2282
2282
  token_type: string;
2283
2283
  expires_in: number;
2284
- refresh_token: string;
2284
+ refresh_token?: string;
2285
2285
  user: {
2286
2286
  id: string;
2287
2287
  email: string;
@@ -2326,7 +2326,7 @@ export declare function sso(client: Client<paths>): {
2326
2326
  access_token: string;
2327
2327
  token_type: string;
2328
2328
  expires_in: number;
2329
- refresh_token: string;
2329
+ refresh_token?: string;
2330
2330
  user: {
2331
2331
  id: string;
2332
2332
  email: string;
@@ -44,7 +44,7 @@ export declare function username(client: Client<paths>): {
44
44
  access_token: string;
45
45
  token_type: string;
46
46
  expires_in: number;
47
- refresh_token: string;
47
+ refresh_token?: string;
48
48
  user: {
49
49
  id: string;
50
50
  email: string;
@@ -106,7 +106,7 @@ export declare function username(client: Client<paths>): {
106
106
  access_token: string;
107
107
  token_type: string;
108
108
  expires_in: number;
109
- refresh_token: string;
109
+ refresh_token?: string;
110
110
  user: {
111
111
  id: string;
112
112
  email: string;
@@ -175,7 +175,7 @@ export declare function username(client: Client<paths>): {
175
175
  access_token: string;
176
176
  token_type: string;
177
177
  expires_in: number;
178
- refresh_token: string;
178
+ refresh_token?: string;
179
179
  user: {
180
180
  id: string;
181
181
  email: string;
@@ -250,7 +250,7 @@ export declare function username(client: Client<paths>): {
250
250
  access_token: string;
251
251
  token_type: string;
252
252
  expires_in: number;
253
- refresh_token: string;
253
+ refresh_token?: string;
254
254
  user: {
255
255
  id: string;
256
256
  email: string;
@@ -312,7 +312,7 @@ export declare function username(client: Client<paths>): {
312
312
  access_token: string;
313
313
  token_type: string;
314
314
  expires_in: number;
315
- refresh_token: string;
315
+ refresh_token?: string;
316
316
  user: {
317
317
  id: string;
318
318
  email: string;
package/openapi.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "openapi": "3.1.0",
3
3
  "info": {
4
4
  "title": "Polaris for PHP",
5
- "version": "0.11.0",
5
+ "version": "0.12.1",
6
6
  "description": "Self-hosted authentication, MFA, organizations and RBAC."
7
7
  },
8
8
  "paths": {
@@ -339,6 +339,7 @@
339
339
  "x-polaris-effect": "write",
340
340
  "x-polaris-receipt": true,
341
341
  "x-polaris-rate-limit": "login",
342
+ "x-polaris-session": "issue",
342
343
  "requestBody": {
343
344
  "required": true,
344
345
  "content": {
@@ -561,6 +562,7 @@
561
562
  ],
562
563
  "x-polaris-effect": "destructive",
563
564
  "x-polaris-receipt": true,
565
+ "x-polaris-session": "end",
564
566
  "security": [
565
567
  {
566
568
  "bearerAuth": []
@@ -620,6 +622,7 @@
620
622
  ],
621
623
  "x-polaris-effect": "write",
622
624
  "x-polaris-receipt": true,
625
+ "x-polaris-session": "end",
623
626
  "security": [
624
627
  {
625
628
  "bearerAuth": []
@@ -2144,6 +2147,7 @@
2144
2147
  "x-polaris-effect": "write",
2145
2148
  "x-polaris-receipt": true,
2146
2149
  "x-polaris-rate-limit": "mfa_confirm",
2150
+ "x-polaris-session": "issue",
2147
2151
  "security": [
2148
2152
  {
2149
2153
  "mfaToken": []
@@ -2916,6 +2920,7 @@
2916
2920
  "x-polaris-effect": "write",
2917
2921
  "x-polaris-receipt": true,
2918
2922
  "x-polaris-rate-limit": "token_refresh",
2923
+ "x-polaris-session": "refresh",
2919
2924
  "requestBody": {
2920
2925
  "required": true,
2921
2926
  "content": {
@@ -11258,6 +11263,7 @@
11258
11263
  "x-polaris-effect": "write",
11259
11264
  "x-polaris-receipt": false,
11260
11265
  "x-polaris-plugin": "sso",
11266
+ "x-polaris-session": "issue",
11261
11267
  "requestBody": {
11262
11268
  "required": true,
11263
11269
  "content": {
@@ -11371,6 +11377,7 @@
11371
11377
  "x-polaris-effect": "write",
11372
11378
  "x-polaris-receipt": true,
11373
11379
  "x-polaris-plugin": "sso",
11380
+ "x-polaris-session": "end",
11374
11381
  "security": [
11375
11382
  {
11376
11383
  "bearerAuth": []
@@ -15188,6 +15195,7 @@
15188
15195
  "x-polaris-receipt": true,
15189
15196
  "x-polaris-plugin": "passwordless",
15190
15197
  "x-polaris-rate-limit": "token_consume",
15198
+ "x-polaris-session": "issue",
15191
15199
  "requestBody": {
15192
15200
  "required": true,
15193
15201
  "content": {
@@ -15320,6 +15328,7 @@
15320
15328
  "x-polaris-receipt": false,
15321
15329
  "x-polaris-plugin": "passwordless",
15322
15330
  "x-polaris-rate-limit": "token_consume",
15331
+ "x-polaris-session": "issue",
15323
15332
  "requestBody": {
15324
15333
  "required": true,
15325
15334
  "content": {
@@ -15649,6 +15658,7 @@
15649
15658
  "x-polaris-receipt": true,
15650
15659
  "x-polaris-plugin": "passwordless",
15651
15660
  "x-polaris-rate-limit": "token_consume",
15661
+ "x-polaris-session": "issue",
15652
15662
  "requestBody": {
15653
15663
  "required": true,
15654
15664
  "content": {
@@ -16043,6 +16053,7 @@
16043
16053
  "x-polaris-receipt": true,
16044
16054
  "x-polaris-plugin": "passwordless",
16045
16055
  "x-polaris-rate-limit": "token_consume",
16056
+ "x-polaris-session": "issue",
16046
16057
  "requestBody": {
16047
16058
  "required": true,
16048
16059
  "content": {
@@ -16174,6 +16185,7 @@
16174
16185
  "x-polaris-receipt": true,
16175
16186
  "x-polaris-plugin": "username",
16176
16187
  "x-polaris-rate-limit": "login",
16188
+ "x-polaris-session": "issue",
16177
16189
  "requestBody": {
16178
16190
  "required": true,
16179
16191
  "content": {
@@ -16533,6 +16545,7 @@
16533
16545
  "x-polaris-receipt": true,
16534
16546
  "x-polaris-plugin": "anonymous",
16535
16547
  "x-polaris-rate-limit": "register",
16548
+ "x-polaris-session": "issue",
16536
16549
  "responses": {
16537
16550
  "201": {
16538
16551
  "description": "Success",
@@ -16873,6 +16886,7 @@
16873
16886
  "x-polaris-effect": "write",
16874
16887
  "x-polaris-receipt": true,
16875
16888
  "x-polaris-plugin": "multi-session",
16889
+ "x-polaris-session": "issue",
16876
16890
  "security": [
16877
16891
  {
16878
16892
  "bearerAuth": []
@@ -17356,6 +17370,7 @@
17356
17370
  "x-polaris-receipt": false,
17357
17371
  "x-polaris-plugin": "social",
17358
17372
  "x-polaris-rate-limit": "token_consume",
17373
+ "x-polaris-session": "issue",
17359
17374
  "requestBody": {
17360
17375
  "required": true,
17361
17376
  "content": {
@@ -17587,6 +17602,7 @@
17587
17602
  "x-polaris-receipt": true,
17588
17603
  "x-polaris-plugin": "social",
17589
17604
  "x-polaris-rate-limit": "login",
17605
+ "x-polaris-session": "issue",
17590
17606
  "requestBody": {
17591
17607
  "required": true,
17592
17608
  "content": {
@@ -18096,6 +18112,7 @@
18096
18112
  "x-polaris-receipt": true,
18097
18113
  "x-polaris-plugin": "passkey",
18098
18114
  "x-polaris-rate-limit": "login",
18115
+ "x-polaris-session": "issue",
18099
18116
  "requestBody": {
18100
18117
  "required": true,
18101
18118
  "content": {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@polaris-auth/client",
3
- "version": "0.11.0",
3
+ "version": "0.12.1",
4
4
  "description": "Typed TypeScript client for Polaris for PHP, generated from the route manifest",
5
5
  "keywords": [
6
6
  "polaris",
@@ -71,7 +71,7 @@
71
71
  "node": ">=20"
72
72
  },
73
73
  "scripts": {
74
- "generate": "php ../../bin/polaris manifest --format=openapi --bootstrap=polaris.php > openapi.json && openapi-typescript openapi.json -o src/schema.d.ts && node scripts/generate-namespaces.mjs",
74
+ "generate": "php ../../bin/polaris manifest --format=openapi --bootstrap=polaris.php > openapi.json && node scripts/session-types.mjs openapi.json .openapi.types.json && openapi-typescript .openapi.types.json -o src/schema.d.ts && rm .openapi.types.json && node scripts/generate-namespaces.mjs",
75
75
  "typecheck": "tsc --noEmit",
76
76
  "build": "tsc -p tsconfig.build.json",
77
77
  "test": "vitest run",
package/src/cookie.ts ADDED
@@ -0,0 +1,48 @@
1
+ import type { Client, Middleware } from "openapi-fetch";
2
+ import type { paths } from "./schema.js";
3
+
4
+ /** The header a cookie-mode client sends on every request; the server's CSRF guard requires it on every route that sets or uses the refresh cookie. */
5
+ export const CSRF_HEADER = "X-Polaris-CSRF";
6
+
7
+ /** How the server delivers the refresh token: in the JSON body (the default) or in an `HttpOnly` cookie the client never sees. */
8
+ export type TokenDelivery = "body" | "cookie";
9
+
10
+ /** Adds `X-Polaris-CSRF: 1` to every request, for a server with `auth.flows.token_delivery: cookie`. */
11
+ export function cookieDelivery(): Middleware {
12
+ return {
13
+ onRequest({ request }) {
14
+ request.headers.set(CSRF_HEADER, "1");
15
+ return request;
16
+ },
17
+ };
18
+ }
19
+
20
+ function refresh(client: Client<paths>) {
21
+ // The refresh cookie is the credential; the body is empty.
22
+ return client.POST("/auth/token/refresh", { body: {} });
23
+ }
24
+
25
+ /** What `refreshSession()` answers: the refresh route's response, as `client.POST` answers it. */
26
+ export type RefreshSessionResult = Awaited<ReturnType<typeof refresh>>;
27
+
28
+ let inFlight: Promise<RefreshSessionResult> | null = null;
29
+
30
+ /**
31
+ * Rotates the session in cookie mode: posts an empty body to `/auth/token/refresh`, whose cookie the
32
+ * browser sends, and answers the new access token in `data`. Refreshes are serialised across the tabs of
33
+ * a browser profile through the Web Locks API, so two tabs never present the same rotated cookie (the
34
+ * server would take the second as a replay and end the session); a tab waiting for the lock refreshes
35
+ * with the cookie the first one received. Without Web Locks, concurrent calls in one tab share one request.
36
+ */
37
+ export function refreshSession(client: Client<paths>): Promise<RefreshSessionResult> {
38
+ const locks = (globalThis as { navigator?: { locks?: LockManager } }).navigator?.locks;
39
+ if (locks !== undefined) {
40
+ // The DOM typing wraps the callback's promise once more; the runtime resolves it.
41
+ return locks.request("polaris:refresh", () => refresh(client)).then((result) => result);
42
+ }
43
+ inFlight ??= refresh(client).finally(() => {
44
+ inFlight = null;
45
+ });
46
+
47
+ return inFlight;
48
+ }
package/src/index.ts CHANGED
@@ -3,6 +3,7 @@ import { admin, type AdminApi } from "./admin.js";
3
3
  import { anonymous, type AnonymousApi } from "./anonymous.js";
4
4
  import { audit, type AuditApi } from "./audit.js";
5
5
  import { challengeRetry, type ChallengeOptions } from "./challenge.js";
6
+ import { cookieDelivery, type TokenDelivery } from "./cookie.js";
6
7
  import { multiSession, type MultiSessionApi } from "./multi-session.js";
7
8
  import { passkey, type PasskeyApi } from "./passkey.js";
8
9
  import { passwordless, type PasswordlessApi } from "./passwordless.js";
@@ -22,6 +23,7 @@ export { admin, type AdminApi } from "./admin.js";
22
23
  export { anonymous, type AnonymousApi } from "./anonymous.js";
23
24
  export { audit, type AuditApi } from "./audit.js";
24
25
  export { challengeRetry, type ChallengeOptions } from "./challenge.js";
26
+ export { CSRF_HEADER, cookieDelivery, refreshSession, type RefreshSessionResult, type TokenDelivery } from "./cookie.js";
25
27
  export { multiSession, type MultiSessionApi } from "./multi-session.js";
26
28
  export { passkey, type PasskeyApi } from "./passkey.js";
27
29
  export { passwordless, type PasswordlessApi } from "./passwordless.js";
@@ -54,6 +56,14 @@ export interface PolarisClientOptions extends ClientOptions {
54
56
  * in the body. Without it the problem document is returned as any other error.
55
57
  */
56
58
  challenge?: ChallengeOptions;
59
+ /**
60
+ * `"cookie"` for a server with `auth.flows.token_delivery: cookie`: the refresh token never reaches
61
+ * the client (an `HttpOnly` cookie scoped to the refresh route), every request carries the
62
+ * `X-Polaris-CSRF: 1` header the server's guard requires, and `refreshSession(client)` rotates the
63
+ * session. `credentials` stays at the fetch default (`same-origin`); an application on a trusted
64
+ * origin passes `credentials: "include"` itself. Default `"body"`.
65
+ */
66
+ tokenDelivery?: TokenDelivery;
57
67
  }
58
68
 
59
69
  export interface PolarisClient extends Client<paths> {
@@ -101,12 +111,16 @@ export interface PolarisClient extends Client<paths> {
101
111
  * `client.POST("/auth/login", { body })` checks the body and types `data` and `error`; the plugins' routes
102
112
  * are also methods of `client.audit`, `client.admin`, `client.sentinel`, `client.sso`, `client.scim`, `client.passwordless`,
103
113
  * `client.username`, `client.anonymous`, `client.multiSession`, `client.social`, `client.passkey`, `client.apiKeys`, `client.oauth`, `client.mcp` and `client.agents`; `challenge.captcha`
104
- * answers a sentinel captcha challenge with one retry. No refresh loop and no storage: when to refresh
105
- * and where to keep tokens is the application's policy.
114
+ * answers a sentinel captcha challenge with one retry; `tokenDelivery: "cookie"` sends the CSRF header cookie
115
+ * mode requires. No refresh loop and no storage: when to refresh and where to keep tokens is the
116
+ * application's policy (`refreshSession()` serialises a cookie-mode refresh, it does not schedule one).
106
117
  */
107
118
  export function createClient(options: PolarisClientOptions): PolarisClient {
108
- const { token = null, challenge, ...clientOptions } = options;
119
+ const { token = null, challenge, tokenDelivery = "body", ...clientOptions } = options;
109
120
  const client = createOpenApiClient<paths>(clientOptions);
121
+ if (tokenDelivery === "cookie") {
122
+ client.use(cookieDelivery());
123
+ }
110
124
  if (challenge !== undefined) {
111
125
  client.use(challengeRetry(challenge));
112
126
  }
package/src/schema.d.ts CHANGED
@@ -3397,7 +3397,7 @@ export interface operations {
3397
3397
  access_token: string;
3398
3398
  token_type: string;
3399
3399
  expires_in: number;
3400
- refresh_token: string;
3400
+ refresh_token?: string;
3401
3401
  user: {
3402
3402
  id: string;
3403
3403
  email: string;
@@ -4477,7 +4477,7 @@ export interface operations {
4477
4477
  access_token: string;
4478
4478
  token_type: string;
4479
4479
  expires_in: number;
4480
- refresh_token: string;
4480
+ refresh_token?: string;
4481
4481
  };
4482
4482
  };
4483
4483
  };
@@ -4940,7 +4940,7 @@ export interface operations {
4940
4940
  content: {
4941
4941
  "application/json": {
4942
4942
  /** Format: password */
4943
- refresh_token: string;
4943
+ refresh_token?: string;
4944
4944
  };
4945
4945
  };
4946
4946
  };
@@ -4966,7 +4966,7 @@ export interface operations {
4966
4966
  access_token: string;
4967
4967
  token_type: string;
4968
4968
  expires_in: number;
4969
- refresh_token: string;
4969
+ refresh_token?: string;
4970
4970
  };
4971
4971
  };
4972
4972
  };
@@ -9913,7 +9913,7 @@ export interface operations {
9913
9913
  access_token: string;
9914
9914
  token_type: string;
9915
9915
  expires_in: number;
9916
- refresh_token: string;
9916
+ refresh_token?: string;
9917
9917
  user: {
9918
9918
  id: string;
9919
9919
  email: string;
@@ -12274,7 +12274,7 @@ export interface operations {
12274
12274
  access_token: string;
12275
12275
  token_type: string;
12276
12276
  expires_in: number;
12277
- refresh_token: string;
12277
+ refresh_token?: string;
12278
12278
  user: {
12279
12279
  id: string;
12280
12280
  email: string;
@@ -12346,7 +12346,7 @@ export interface operations {
12346
12346
  access_token: string;
12347
12347
  token_type: string;
12348
12348
  expires_in: number;
12349
- refresh_token: string;
12349
+ refresh_token?: string;
12350
12350
  user: {
12351
12351
  id: string;
12352
12352
  email: string;
@@ -12550,7 +12550,7 @@ export interface operations {
12550
12550
  access_token: string;
12551
12551
  token_type: string;
12552
12552
  expires_in: number;
12553
- refresh_token: string;
12553
+ refresh_token?: string;
12554
12554
  user: {
12555
12555
  id: string;
12556
12556
  email: string;
@@ -12783,7 +12783,7 @@ export interface operations {
12783
12783
  access_token: string;
12784
12784
  token_type: string;
12785
12785
  expires_in: number;
12786
- refresh_token: string;
12786
+ refresh_token?: string;
12787
12787
  user: {
12788
12788
  id: string;
12789
12789
  email: string;
@@ -12856,7 +12856,7 @@ export interface operations {
12856
12856
  access_token: string;
12857
12857
  token_type: string;
12858
12858
  expires_in: number;
12859
- refresh_token: string;
12859
+ refresh_token?: string;
12860
12860
  user: {
12861
12861
  id: string;
12862
12862
  email: string;
@@ -13066,7 +13066,7 @@ export interface operations {
13066
13066
  access_token: string;
13067
13067
  token_type: string;
13068
13068
  expires_in: number;
13069
- refresh_token: string;
13069
+ refresh_token?: string;
13070
13070
  user: {
13071
13071
  id: string;
13072
13072
  email: string;
@@ -13279,7 +13279,7 @@ export interface operations {
13279
13279
  access_token: string;
13280
13280
  token_type: string;
13281
13281
  expires_in: number;
13282
- refresh_token: string;
13282
+ refresh_token?: string;
13283
13283
  user: {
13284
13284
  id: string;
13285
13285
  email: string;
@@ -13571,7 +13571,7 @@ export interface operations {
13571
13571
  access_token: string;
13572
13572
  token_type: string;
13573
13573
  expires_in: number;
13574
- refresh_token: string;
13574
+ refresh_token?: string;
13575
13575
  user: {
13576
13576
  id: string;
13577
13577
  email: string;
@@ -13703,7 +13703,7 @@ export interface operations {
13703
13703
  access_token: string;
13704
13704
  token_type: string;
13705
13705
  expires_in: number;
13706
- refresh_token: string;
13706
+ refresh_token?: string;
13707
13707
  user: {
13708
13708
  id: string;
13709
13709
  email: string;
@@ -14020,7 +14020,7 @@ export interface operations {
14020
14020
  access_token: string;
14021
14021
  token_type: string;
14022
14022
  expires_in: number;
14023
- refresh_token: string;
14023
+ refresh_token?: string;
14024
14024
  user: {
14025
14025
  id: string;
14026
14026
  email: string;