@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 +21 -0
- package/README.md +114 -2
- package/dist/admin.d.ts +9532 -0
- package/dist/admin.js +63 -0
- package/dist/anonymous.d.ts +513 -0
- package/dist/anonymous.js +9 -0
- package/dist/audit.d.ts +944 -0
- package/dist/audit.js +11 -0
- package/dist/challenge.d.ts +17 -0
- package/dist/challenge.js +59 -0
- package/dist/index.d.ts +77 -0
- package/dist/index.js +58 -0
- package/dist/multi-session.d.ts +1104 -0
- package/dist/multi-session.js +13 -0
- package/dist/namespace.d.ts +15 -0
- package/dist/namespace.js +1 -0
- package/dist/passwordless.d.ts +3353 -0
- package/dist/passwordless.js +31 -0
- package/dist/scim.d.ts +6656 -0
- package/dist/scim.js +49 -0
- package/dist/sentinel.d.ts +1564 -0
- package/dist/sentinel.js +15 -0
- package/dist/sso.d.ts +6455 -0
- package/dist/sso.js +45 -0
- package/dist/username.d.ts +674 -0
- package/dist/username.js +9 -0
- package/openapi.json +17093 -0
- package/package.json +70 -5
- package/src/admin.ts +70 -0
- package/src/anonymous.ts +16 -0
- package/src/audit.ts +18 -0
- package/src/challenge.ts +80 -0
- package/src/index.ts +111 -0
- package/src/multi-session.ts +20 -0
- package/src/namespace.ts +13 -0
- package/src/passwordless.ts +38 -0
- package/src/schema.d.ts +12248 -0
- package/src/scim.ts +56 -0
- package/src/sentinel.ts +22 -0
- package/src/sso.ts +52 -0
- package/src/username.ts +16 -0
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
|
-
#
|
|
1
|
+
# @polaris-auth/client
|
|
2
2
|
|
|
3
|
-
|
|
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).
|