@farm.js/workos 0.1.50 → 0.1.51-beta.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 +137 -3
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,11 +1,145 @@
|
|
|
1
1
|
# @farm.js/workos
|
|
2
2
|
|
|
3
|
-
WorkOS
|
|
3
|
+
WorkOS AuthKit sign-in for Farm.js applications. The integration mounts the login, sign-up,
|
|
4
|
+
callback, logout, and session routes, stores the AuthKit session in a sealed cookie, and can
|
|
5
|
+
redirect signed-out visitors away from protected pages. WorkOS keeps owning organizations, SSO
|
|
6
|
+
connections, and user management.
|
|
4
7
|
|
|
5
8
|
See [Stability and Support](https://farmjs.dev/docs/stability) for what this package guarantees.
|
|
6
9
|
|
|
10
|
+
## Install
|
|
11
|
+
|
|
7
12
|
```bash
|
|
8
|
-
|
|
13
|
+
pnpm add @farm.js/workos
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
The WorkOS Node SDK, `@workos-inc/node`, is a dependency and installs with the package. Add it to
|
|
17
|
+
the app directly only when the app constructs its own client (see below). To scaffold the registry
|
|
18
|
+
entry and a sign-in screen in an existing app, run `farm add integration workos --ui`.
|
|
19
|
+
|
|
20
|
+
## Configure
|
|
21
|
+
|
|
22
|
+
```ts
|
|
23
|
+
// src/lib/integrations.ts
|
|
24
|
+
import { workos } from "@farm.js/workos";
|
|
25
|
+
|
|
26
|
+
export const appIntegrations = {
|
|
27
|
+
auth: workos({
|
|
28
|
+
protectedRoutes: ["/dashboard(.*)"],
|
|
29
|
+
}),
|
|
30
|
+
} as const;
|
|
31
|
+
|
|
32
|
+
export type AppIntegrations = typeof appIntegrations;
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
```ts
|
|
36
|
+
// farm.config.ts
|
|
37
|
+
import { defineConfig } from "@farm.js/core";
|
|
38
|
+
import { appIntegrations } from "./src/lib/integrations";
|
|
39
|
+
|
|
40
|
+
export default defineConfig({
|
|
41
|
+
integrations: appIntegrations,
|
|
42
|
+
});
|
|
9
43
|
```
|
|
10
44
|
|
|
11
|
-
|
|
45
|
+
Values come from the environment unless they are passed as `clientId`, `apiKey`, and
|
|
46
|
+
`cookiePassword`:
|
|
47
|
+
|
|
48
|
+
| Variable | Purpose |
|
|
49
|
+
| ----------------------------- | ---------------------------------------------------------------- |
|
|
50
|
+
| `WORKOS_CLIENT_ID` | AuthKit client ID. Required unless the `instance` carries one. |
|
|
51
|
+
| `WORKOS_API_KEY` | Server API key. Required unless an `instance` is passed. |
|
|
52
|
+
| `WORKOS_COOKIE_PASSWORD` | Seals the session cookie. Required outside development and test. |
|
|
53
|
+
| `FARM_WORKOS_COOKIE_PASSWORD` | Alternative name for the cookie password. |
|
|
54
|
+
|
|
55
|
+
When no cookie password is set in development, a random one is generated once in
|
|
56
|
+
`.farm/workos-secret` and reused across restarts. Tests get a random one for the life of the
|
|
57
|
+
process. Any other `NODE_ENV` fails at startup without one.
|
|
58
|
+
|
|
59
|
+
## Routes
|
|
60
|
+
|
|
61
|
+
| Method | Default route | Purpose |
|
|
62
|
+
| ------ | --------------- | ------------------------------------------------------------ |
|
|
63
|
+
| `GET` | `/login` | Starts AuthKit sign-in. Accepts a root-relative `returnTo`. |
|
|
64
|
+
| `GET` | `/signup` | Starts AuthKit sign-up. |
|
|
65
|
+
| `GET` | `/callback` | Verifies state, exchanges the code, stores the session. |
|
|
66
|
+
| `POST` | `/logout` | Clears the cookie and redirects through WorkOS logout. |
|
|
67
|
+
| `GET` | `/auth/session` | Returns the user, session ID, and organization ID, or `401`. |
|
|
68
|
+
|
|
69
|
+
Change them with `loginPath`, `signUpPath`, `callbackPath`, `logoutPath`, and `sessionPath`. The
|
|
70
|
+
redirect URI sent to WorkOS is `callbackPath` on the request origin, for example
|
|
71
|
+
`https://app.example.com/callback`; register that exact URL in WorkOS.
|
|
72
|
+
|
|
73
|
+
A signed-out request to a `protectedRoutes` match is redirected to the login route with the original
|
|
74
|
+
path in `returnTo`.
|
|
75
|
+
|
|
76
|
+
## Typed calls
|
|
77
|
+
|
|
78
|
+
```ts
|
|
79
|
+
// src/lib/api.ts
|
|
80
|
+
import { createIntegrations } from "@farm.js/core/client";
|
|
81
|
+
import type { AppIntegrations } from "./integrations";
|
|
82
|
+
|
|
83
|
+
export const { api, apiClient } = createIntegrations<AppIntegrations>();
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
```ts
|
|
87
|
+
const session = await api.auth.session.get();
|
|
88
|
+
const organizationId = session.data?.organizationId;
|
|
89
|
+
|
|
90
|
+
const logout = await apiClient.auth.logout.post();
|
|
91
|
+
if (logout.data) window.location.assign(logout.data.redirectTo);
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Document navigation works too, for example `<a href="/login?returnTo=/dashboard">Sign in</a>`.
|
|
95
|
+
`@farm.js/workos/client` exports `workosClient`, the same operations bound to the default paths,
|
|
96
|
+
and their result types (`WorkOSSessionResult`, `WorkOSRedirectResult`, `WorkOSRedirectQuery`).
|
|
97
|
+
|
|
98
|
+
The organization ID identifies the WorkOS organization. Map it to your own tenant record and
|
|
99
|
+
resolve roles and permissions in the application.
|
|
100
|
+
|
|
101
|
+
## Bring your own client
|
|
102
|
+
|
|
103
|
+
Pass a configured SDK through `instance` when the app needs constructor options Farm does not own.
|
|
104
|
+
`apiKey` is then not required, and the client ID can come from the instance. The cookie password is
|
|
105
|
+
still required, because Farm owns the sealed session cookie.
|
|
106
|
+
|
|
107
|
+
```ts
|
|
108
|
+
import { WorkOS } from "@workos-inc/node";
|
|
109
|
+
import { workos } from "@farm.js/workos";
|
|
110
|
+
|
|
111
|
+
const client = new WorkOS({
|
|
112
|
+
apiKey: process.env.WORKOS_API_KEY,
|
|
113
|
+
clientId: process.env.WORKOS_CLIENT_ID,
|
|
114
|
+
});
|
|
115
|
+
|
|
116
|
+
export const auth = workos({
|
|
117
|
+
instance: client,
|
|
118
|
+
protectedRoutes: ["/dashboard(.*)"],
|
|
119
|
+
});
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
## Options
|
|
123
|
+
|
|
124
|
+
| Option | Default | Notes |
|
|
125
|
+
| ----------------- | ------------------- | -------------------------------------------------------- |
|
|
126
|
+
| `instance` | | Existing `WorkOS` client. Wins over `clientId`/`apiKey`. |
|
|
127
|
+
| `clientId` | `WORKOS_CLIENT_ID` | |
|
|
128
|
+
| `apiKey` | `WORKOS_API_KEY` | |
|
|
129
|
+
| `cookiePassword` | cookie password env | |
|
|
130
|
+
| `cookieName` | `wos-session` | Use a `__Host-` name in production. |
|
|
131
|
+
| `stateCookieName` | `farm_workos_state` | Must differ from `cookieName`. |
|
|
132
|
+
| `protectedRoutes` | | One matcher or a list. |
|
|
133
|
+
| `allowedOrigins` | app origin | Extra origins allowed to post sign-out. |
|
|
134
|
+
| `log` | | Integration lifecycle logger. |
|
|
135
|
+
|
|
136
|
+
The sign-out route only accepts posts from the app's own origin, plus any `allowedOrigins`. A
|
|
137
|
+
cross-site request gets `403` before the session is cleared.
|
|
138
|
+
|
|
139
|
+
## Documentation
|
|
140
|
+
|
|
141
|
+
- [WorkOS integration](https://farmjs.dev/docs/integrations/auth/workos)
|
|
142
|
+
- [Auth integrations overview](https://farmjs.dev/docs/integrations/auth)
|
|
143
|
+
|
|
144
|
+
Report issues and find examples in the
|
|
145
|
+
[Farm.js repository](https://github.com/farming-labs/farm.js).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@farm.js/workos",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.51-beta.1",
|
|
4
4
|
"description": "WorkOS integration for Farm.js",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -30,8 +30,8 @@
|
|
|
30
30
|
},
|
|
31
31
|
"dependencies": {
|
|
32
32
|
"@workos-inc/node": "^8.9.0",
|
|
33
|
-
"@farm.js/core": "0.1.
|
|
34
|
-
"@farm.js/integration-utils": "0.1.
|
|
33
|
+
"@farm.js/core": "0.1.51-beta.1",
|
|
34
|
+
"@farm.js/integration-utils": "0.1.51-beta.1"
|
|
35
35
|
},
|
|
36
36
|
"scripts": {
|
|
37
37
|
"build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc",
|