@farm.js/workos 0.1.49 → 0.1.51-beta.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.
Files changed (2) hide show
  1. package/README.md +137 -3
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,11 +1,145 @@
1
1
  # @farm.js/workos
2
2
 
3
- WorkOS integration for Farm.js
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
- npm install @farm.js/workos
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
- See the [Farm.js repository](https://github.com/farming-labs/farm.js) for documentation, examples, and support.
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.49",
3
+ "version": "0.1.51-beta.0",
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.49",
34
- "@farm.js/integration-utils": "0.1.49"
33
+ "@farm.js/core": "0.1.51-beta.0",
34
+ "@farm.js/integration-utils": "0.1.51-beta.0"
35
35
  },
36
36
  "scripts": {
37
37
  "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc",