@polaris-auth/client 0.0.0-stage → 0.7.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 2am.tech
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,115 @@
1
- # Temporary Holding Version
1
+ # @polaris-auth/client
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The TypeScript client for [Polaris for PHP](https://github.com/univeros/polaris-core), generated from
4
+ the route manifest: `openapi-fetch` typed by the 52 core endpoints and the routes of the `polaris/audit`,
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
7
+ `data` and its `error` are checked at compile time against the same contract the PHP hosts serve.
8
+
9
+ ```sh
10
+ npm install @polaris-auth/client
11
+ ```
12
+
13
+ ```ts
14
+ import { createClient } from "@polaris-auth/client";
15
+
16
+ const polaris = createClient({ baseUrl: "https://app.example.com" }); // or .../api/auth behind a prefix
17
+
18
+ const login = await polaris.POST("/auth/login", { body: { email, password } });
19
+ if (login.data && "access_token" in login.data.data) { // a session, or an MFA ticket
20
+ const me = await polaris.withToken(login.data.data.access_token).GET("/auth/me");
21
+ me.data?.data.email; // typed
22
+ } else if (login.error) {
23
+ login.error.error; // "invalid_credentials", ...
24
+ }
25
+ ```
26
+
27
+ `createClient({ baseUrl, token, challenge, fetch, headers })` takes `openapi-fetch`'s options plus `token`,
28
+ sent as `Authorization: Bearer` on every request (an access token, or the `mfa_token` for the MFA gate), and
29
+ `challenge` (below); `withToken(token)` returns a new client bound to another token, `token: null` an
30
+ anonymous one. Nothing else: when to refresh and where to keep tokens is your application's policy. Every method of
31
+ `openapi-fetch` is there (`GET`, `POST`, `PATCH`, `DELETE`, `use` for middleware).
32
+
33
+ ## The plugins
34
+
35
+ The routes a plugin adds are methods of a namespace named after the plugin, one method per endpoint
36
+ class (`ListUsersEndpoint` → `listUsers`), taking the same `openapi-fetch` init as `client.GET(path, init)`:
37
+
38
+ ```ts
39
+ const operator = createClient({ baseUrl, token: "pak_..." }); // an admin API key, or an admin user's access token
40
+ const users = await operator.admin.listUsers({ params: { query: { status: "active" } } });
41
+ await operator.admin.banUser({ params: { path: { id: users.data!.data[0]!.id } } });
42
+ const trail = await polaris.withToken(accessToken).audit.me();
43
+ ```
44
+
45
+ `client.audit` (`me`, `organization`, `types`), `client.admin` (users, sessions, MFA, organizations,
46
+ audit, drains, stats, keys, grants; see the package README), `client.sentinel` (`listDecisions`,
47
+ `listIpRules`, `createIpRule`, `deleteIpRule`, `unblock`), `client.sso` (`signIn`, `exchange`, `logout`,
48
+ the organization's providers and domains, the operators' list), `client.scim` (the organization's
49
+ connections, the operators' list, and the SCIM server's own routes for a directory client),
50
+ `client.passwordless` (`magicLinkSend`, `magicLinkVerify`, `magicLinkExchange`, `emailOtpSend`,
51
+ `emailOtpVerify`, `emailOtpVerifyEmail`, `emailOtpResetPassword`, `phoneSend`, `phoneVerify`, `phoneAdd`,
52
+ `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
55
+ `x-polaris-plugin` marker of the OpenAPI document; a later plugin gets its namespace the same way, its id
56
+ camel-cased (`multi-session` is `client.multiSession`). Their errors are RFC 9457 problem documents,
57
+ `ProblemBody` (`{ type, title, status, detail, error, message, errors? }`), served as
58
+ `application/problem+json`.
59
+
60
+ Response types come from each endpoint's `output.example` in the manifest (JSON Schema by example,
61
+ `docs/adapters/spec.md` §7): a documented approximation, exact for the shapes the specs show. Error
62
+ bodies are `ErrorBody` (`{ error, message }`) and `ValidationErrorBody` (`{ errors }`).
63
+
64
+ ## Several accounts on one device
65
+
66
+ With `polaris/multi-session`, every response that carries a token pair also carries the device id in
67
+ `X-Polaris-Device` (and, for a browser, the HttpOnly cookie `polaris_ms_device`). A client that is not a
68
+ browser sends it back on the multi-session routes:
69
+
70
+ ```ts
71
+ const device = signIn.response.headers.get("X-Polaris-Device")!;
72
+ const accounts = await polaris.withToken(access).multiSession.list({ headers: { "X-Polaris-Device": device } });
73
+ const other = await polaris.withToken(access).multiSession.switch({ body: { session_id: accounts.data!.data[1]!.session_id }, headers: { "X-Polaris-Device": device } });
74
+ const button = (await polaris.multiSession.lastMethod({ headers: { "X-Polaris-Device": device } })).data?.data.last_method;
75
+ ```
76
+
77
+ ## The sentinel challenge
78
+
79
+ With `polaris/sentinel` enforcing, a sign-up, sign-in, password reset or code send may answer `403` with
80
+ the `sentinel/challenge_required` problem and `challenge: captcha`. Give the client a way to get a captcha
81
+ token and it answers the challenge itself: the callback is asked once, and the same request is sent
82
+ again with `captcha_token` added to its body.
83
+
84
+ ```ts
85
+ const polaris = createClient({
86
+ baseUrl,
87
+ challenge: { captcha: () => turnstile.execute() }, // the host's widget (Turnstile, hCaptcha, ...) yields the token
88
+ });
89
+ const login = await polaris.POST("/auth/login", { body: { email, password } }); // challenged, solved, answered
90
+ ```
91
+
92
+ One retry only: the retried response is returned as it is, so a wrong token is one problem document
93
+ and never a loop; every other error, and the challenge when no `captcha` callback is given, is returned
94
+ as today. `withToken` keeps the callback. `challengeRetry(options)` is exported for a plain `openapi-fetch`
95
+ client (`client.use(challengeRetry({ captcha }))`).
96
+
97
+ ## Development
98
+
99
+ ```sh
100
+ npm ci
101
+ npm run generate # bin/polaris manifest --format=openapi --bootstrap=polaris.php > openapi.json; openapi-typescript → src/schema.d.ts; the namespaces
102
+ npm run typecheck
103
+ npm test # starts examples/slim (installed and set up) and runs register → verify → login → me, then the admin and audit namespaces
104
+ ```
105
+
106
+ `openapi.json`, `src/schema.d.ts` and the namespaces (`src/audit.ts`, `src/admin.ts`, `src/sentinel.ts`,
107
+ `src/sso.ts`, `src/scim.ts`) are checked in; CI regenerates them and fails on a difference, so a manifest
108
+ change ships with its types. `polaris.php` is the application the client is generated for (core with the
109
+ five plugins that have routes). `POLARIS_URL=http://host:port npm test` runs the test against a server
110
+ you started. Node 20 or later. Every `v*` tag of the monorepo publishes the package to npm through
111
+ trusted publishing (`.github/workflows/npm-publish.yml`, OIDC, provenance attached, no token).
112
+
113
+ ## License
114
+
115
+ MIT. Polaris for PHP is created and maintained by [2am.tech](https://2am.tech).