@polaris-auth/client 0.7.0 → 0.8.0

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
@@ -3,7 +3,8 @@
3
3
  The TypeScript client for [Polaris for PHP](https://github.com/univeros/polaris-core), generated from
4
4
  the route manifest: `openapi-fetch` typed by the 52 core endpoints and the routes of the `polaris/audit`,
5
5
  `polaris/admin`, `polaris/sentinel`, `polaris/sso`, `polaris/scim`, `polaris/passwordless`,
6
- `polaris/username`, `polaris/anonymous` and `polaris/multi-session` plugins, so a request body, its
6
+ `polaris/username`, `polaris/anonymous`, `polaris/multi-session`, `polaris/social` and `polaris/passkey`
7
+ plugins, so a request body, its
7
8
  `data` and its `error` are checked at compile time against the same contract the PHP hosts serve.
8
9
 
9
10
  ```sh
@@ -50,8 +51,10 @@ connections, the operators' list, and the SCIM server's own routes for a directo
50
51
  `client.passwordless` (`magicLinkSend`, `magicLinkVerify`, `magicLinkExchange`, `emailOtpSend`,
51
52
  `emailOtpVerify`, `emailOtpVerifyEmail`, `emailOtpResetPassword`, `phoneSend`, `phoneVerify`, `phoneAdd`,
52
53
  `phoneConfirm`, `oneTimeTokenGenerate`, `oneTimeTokenVerify`), `client.username` (`signIn`, `update`),
53
- `client.anonymous` (`signIn`, `convert`) and `client.multiSession` (`list`, `switch`, `revoke`,
54
- `lastMethod`) are generated into `src/<plugin id>.ts` by `scripts/generate-namespaces.mjs` from the
54
+ `client.anonymous` (`signIn`, `convert`), `client.multiSession` (`list`, `switch`, `revoke`,
55
+ `lastMethod`), `client.social` (`start`, `exchange`, `oneTap`, `accounts`, `link`, `unlink`, `token`) and
56
+ `client.passkey` (`registerOptions`, `registerVerify`, `authenticateOptions`, `authenticateVerify`, `list`,
57
+ `rename`, `delete`) are generated into `src/<plugin id>.ts` by `scripts/generate-namespaces.mjs` from the
55
58
  `x-polaris-plugin` marker of the OpenAPI document; a later plugin gets its namespace the same way, its id
56
59
  camel-cased (`multi-session` is `client.multiSession`). Their errors are RFC 9457 problem documents,
57
60
  `ProblemBody` (`{ type, title, status, detail, error, message, errors? }`), served as
@@ -61,6 +64,38 @@ Response types come from each endpoint's `output.example` in the manifest (JSON
61
64
  `docs/adapters/spec.md` §7): a documented approximation, exact for the shapes the specs show. Error
62
65
  bodies are `ErrorBody` (`{ error, message }`) and `ValidationErrorBody` (`{ errors }`).
63
66
 
67
+ ## Social sign-in
68
+
69
+ `client.social.start()` answers the provider's URL and a `state`; keep the state (`sessionStorage`), send
70
+ the browser to the URL, and on the page the sign-in ends on compare the `state` in the query with it
71
+ before exchanging the `code`:
72
+
73
+ ```ts
74
+ const { data } = await polaris.social.start({ params: { path: { provider: "google" } }, body: {} });
75
+ sessionStorage.setItem("polaris.social.state", data!.data.state);
76
+ location.assign(data!.data.url);
77
+ // ...on /signed-in:
78
+ const query = new URLSearchParams(location.search);
79
+ if (query.get("state") !== sessionStorage.getItem("polaris.social.state")) throw new Error("not the flow this browser started");
80
+ const session = await polaris.social.exchange({ body: { code: query.get("code")! } });
81
+ ```
82
+
83
+ ## Passkeys
84
+
85
+ `registerPasskey()`, `signInWithPasskey()` and `passkeyAssertion()` run the WebAuthn ceremonies of
86
+ `polaris/passkey` in the browser (`navigator.credentials`, a secure context) over the client's routes;
87
+ they are the only hand-written code besides the sentinel retry.
88
+
89
+ ```ts
90
+ import { createClient, registerPasskey, signInWithPasskey, passkeyAssertion } from "@polaris-auth/client";
91
+
92
+ const { passkey, recovery_codes } = await registerPasskey(polaris.withToken(accessToken), "MacBook");
93
+ const session = await signInWithPasskey(polaris); // a prompt
94
+ const autofilled = await signInWithPasskey(polaris, { conditional: true }); // the form's autofill (autocomplete="username webauthn")
95
+ // The passkey as the second factor of a password login that answered mfa_required:
96
+ await polaris.withToken(mfaToken).POST("/auth/mfa/verify", { body: { factor_id, code: await passkeyAssertion(polaris) } });
97
+ ```
98
+
64
99
  ## Several accounts on one device
65
100
 
66
101
  With `polaris/multi-session`, every response that carries a token pair also carries the device id in
package/dist/index.d.ts CHANGED
@@ -4,9 +4,11 @@ import { type AnonymousApi } from "./anonymous.js";
4
4
  import { type AuditApi } from "./audit.js";
5
5
  import { type ChallengeOptions } from "./challenge.js";
6
6
  import { type MultiSessionApi } from "./multi-session.js";
7
+ import { type PasskeyApi } from "./passkey.js";
7
8
  import { type PasswordlessApi } from "./passwordless.js";
8
9
  import { type SentinelApi } from "./sentinel.js";
9
10
  import { type ScimApi } from "./scim.js";
11
+ import { type SocialApi } from "./social.js";
10
12
  import { type SsoApi } from "./sso.js";
11
13
  import { type UsernameApi } from "./username.js";
12
14
  import type { components, paths } from "./schema.js";
@@ -16,16 +18,19 @@ export { anonymous, type AnonymousApi } from "./anonymous.js";
16
18
  export { audit, type AuditApi } from "./audit.js";
17
19
  export { challengeRetry, type ChallengeOptions } from "./challenge.js";
18
20
  export { multiSession, type MultiSessionApi } from "./multi-session.js";
21
+ export { passkey, type PasskeyApi } from "./passkey.js";
19
22
  export { passwordless, type PasswordlessApi } from "./passwordless.js";
20
23
  export { sentinel, type SentinelApi } from "./sentinel.js";
21
24
  export { scim, type ScimApi } from "./scim.js";
25
+ export { social, type SocialApi } from "./social.js";
22
26
  export { sso, type SsoApi } from "./sso.js";
23
27
  export { username, type UsernameApi } from "./username.js";
28
+ export { registerPasskey, signInWithPasskey, passkeyAssertion, passkeyAutofillAvailable, type SignInWithPasskeyOptions } from "./webauthn.js";
24
29
  /** The `{ error, message }` envelope every non-2xx response of a core route carries. */
25
30
  export type ErrorBody = components["schemas"]["Error"];
26
31
  /** The `{ errors: [...] }` envelope of a core route's 422. */
27
32
  export type ValidationErrorBody = components["schemas"]["ValidationError"];
28
- /** The RFC 9457 problem document every non-2xx response of a plugin route (`audit`, `admin`, `sentinel`, `sso`, `scim`, `passwordless`, `username`, `anonymous`, `multi-session`) carries. */
33
+ /** The RFC 9457 problem document every non-2xx response of a plugin route (`audit`, `admin`, `sentinel`, `sso`, `scim`, `passwordless`, `username`, `anonymous`, `multi-session`, `social`, `passkey`) carries. */
29
34
  export type ProblemBody = components["schemas"]["Problem"];
30
35
  export interface PolarisClientOptions extends ClientOptions {
31
36
  /** Where Polaris is mounted: `https://app.example.com`, or `https://app.example.com/api/auth` behind a prefix. */
@@ -63,6 +68,10 @@ export interface PolarisClient extends Client<paths> {
63
68
  * The device travels as the `X-Polaris-Device` header a sign-in answers (or the HttpOnly cookie in a browser).
64
69
  */
65
70
  readonly multiSession: MultiSessionApi;
71
+ /** The `polaris/social` routes: `client.social.start()`, `exchange()`, `oneTap()`, `accounts()`, `link()`, `unlink()`, `token()`. */
72
+ readonly social: SocialApi;
73
+ /** The `polaris/passkey` routes (`registerOptions()`, `registerVerify()`, `authenticateOptions()`, `authenticateVerify()`, `list()`, `rename()`, `delete()`); `registerPasskey()` and `signInWithPasskey()` run the browser ceremonies. */
74
+ readonly passkey: PasskeyApi;
66
75
  /** A new client on the same options bound to another token (null for anonymous); this one is unchanged. */
67
76
  withToken(token: string | null): PolarisClient;
68
77
  }
@@ -70,7 +79,7 @@ export interface PolarisClient extends Client<paths> {
70
79
  * An `openapi-fetch` client typed by `paths` (generated from `polaris manifest --format=openapi`), so
71
80
  * `client.POST("/auth/login", { body })` checks the body and types `data` and `error`; the plugins' routes
72
81
  * are also methods of `client.audit`, `client.admin`, `client.sentinel`, `client.sso`, `client.scim`, `client.passwordless`,
73
- * `client.username`, `client.anonymous` and `client.multiSession`; `challenge.captcha`
82
+ * `client.username`, `client.anonymous`, `client.multiSession`, `client.social` and `client.passkey`; `challenge.captcha`
74
83
  * answers a sentinel captcha challenge with one retry. No refresh loop and no storage: when to refresh
75
84
  * and where to keep tokens is the application's policy.
76
85
  */
package/dist/index.js CHANGED
@@ -4,9 +4,11 @@ import { anonymous } from "./anonymous.js";
4
4
  import { audit } from "./audit.js";
5
5
  import { challengeRetry } from "./challenge.js";
6
6
  import { multiSession } from "./multi-session.js";
7
+ import { passkey } from "./passkey.js";
7
8
  import { passwordless } from "./passwordless.js";
8
9
  import { sentinel } from "./sentinel.js";
9
10
  import { scim } from "./scim.js";
11
+ import { social } from "./social.js";
10
12
  import { sso } from "./sso.js";
11
13
  import { username } from "./username.js";
12
14
  export { admin } from "./admin.js";
@@ -14,16 +16,19 @@ export { anonymous } from "./anonymous.js";
14
16
  export { audit } from "./audit.js";
15
17
  export { challengeRetry } from "./challenge.js";
16
18
  export { multiSession } from "./multi-session.js";
19
+ export { passkey } from "./passkey.js";
17
20
  export { passwordless } from "./passwordless.js";
18
21
  export { sentinel } from "./sentinel.js";
19
22
  export { scim } from "./scim.js";
23
+ export { social } from "./social.js";
20
24
  export { sso } from "./sso.js";
21
25
  export { username } from "./username.js";
26
+ export { registerPasskey, signInWithPasskey, passkeyAssertion, passkeyAutofillAvailable } from "./webauthn.js";
22
27
  /**
23
28
  * An `openapi-fetch` client typed by `paths` (generated from `polaris manifest --format=openapi`), so
24
29
  * `client.POST("/auth/login", { body })` checks the body and types `data` and `error`; the plugins' routes
25
30
  * are also methods of `client.audit`, `client.admin`, `client.sentinel`, `client.sso`, `client.scim`, `client.passwordless`,
26
- * `client.username`, `client.anonymous` and `client.multiSession`; `challenge.captcha`
31
+ * `client.username`, `client.anonymous`, `client.multiSession`, `client.social` and `client.passkey`; `challenge.captcha`
27
32
  * answers a sentinel captcha challenge with one retry. No refresh loop and no storage: when to refresh
28
33
  * and where to keep tokens is the application's policy.
29
34
  */
@@ -53,6 +58,8 @@ export function createClient(options) {
53
58
  username: username(client),
54
59
  anonymous: anonymous(client),
55
60
  multiSession: multiSession(client),
61
+ social: social(client),
62
+ passkey: passkey(client),
56
63
  withToken: (next) => createClient({ ...options, token: next }),
57
64
  };
58
65
  }