@farm.js/auth0 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 +149 -3
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,11 +1,157 @@
1
1
  # @farm.js/auth0
2
2
 
3
- Auth0 integration for Farm.js
3
+ Auth0 login for Farm.js applications. The integration owns the application-facing OAuth routes:
4
+ it runs the Authorization Code flow with PKCE, validates signed state, reads the user profile, and
5
+ keeps it in a signed HTTP-only session cookie. Auth0 keeps hosting the login screens, connections,
6
+ and user records.
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/auth0
13
+ pnpm add @farm.js/auth0
14
+ ```
15
+
16
+ The integration talks to Auth0 over HTTP, so no Auth0 SDK is required. To scaffold the registry
17
+ entry and a sign-in screen in an existing app, run `farm add integration auth0 --ui`.
18
+
19
+ ## Configure
20
+
21
+ ```ts
22
+ // src/lib/integrations.ts
23
+ import { auth0 } from "@farm.js/auth0";
24
+
25
+ export const appIntegrations = {
26
+ auth: auth0({
27
+ callbackPath: "/auth/callback",
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
+ Credentials come from the environment unless they are passed as options:
46
+
47
+ | Variable | Purpose |
48
+ | --------------------- | --------------------------------------------------------------------------- |
49
+ | `AUTH0_DOMAIN` | Tenant domain, such as `tenant.us.auth0.com`. Required. |
50
+ | `AUTH0_CLIENT_ID` | Application client ID. Required. |
51
+ | `AUTH0_CLIENT_SECRET` | Client secret for confidential applications. |
52
+ | `AUTH0_SECRET` | Signs the state and session cookies. Required outside development and test. |
53
+ | `APP_BASE_URL` | Public origin used for callbacks and redirects. |
54
+
55
+ When `AUTH0_SECRET` is unset in development, a random secret is generated once in
56
+ `.farm/auth0-secret` and reused across restarts. Tests get a random secret for the life of the
57
+ process. Any other `NODE_ENV` fails at startup without one.
58
+
59
+ `callbackPath` is combined with `APP_BASE_URL`, or with the request origin, to build the callback
60
+ URL. Pass an absolute `callbackUrl` instead when the callback is fixed. Register that exact URL in
61
+ Auth0.
62
+
63
+ ## Routes
64
+
65
+ | Method | Default route | Purpose |
66
+ | ------ | ---------------- | ------------------------------------------------------------ |
67
+ | `GET` | `/auth/login` | Starts login. Accepts a root-relative `returnTo`. |
68
+ | `GET` | `/auth/signup` | Starts login on Auth0's sign-up screen. |
69
+ | `GET` | `/auth/callback` | Validates state, exchanges the code, writes the session. |
70
+ | `GET` | `/auth/logout` | Clears the session and redirects through Auth0 logout. |
71
+ | `GET` | `/auth/profile` | Returns `{ authenticated, user }`, or `401` when signed out. |
72
+
73
+ Change them with `loginPath`, `signUpPath`, `callbackPath`, `logoutPath`, and `profilePath`. A
74
+ signed-out request to a `protectedRoutes` match is redirected to the login route with the original
75
+ path in `returnTo`.
76
+
77
+ A plain link such as `<a href="/auth/login?returnTo=/dashboard">` starts login. For typed calls,
78
+ create clients from the registry, `api` for server code and `apiClient` for the browser:
79
+
80
+ ```ts
81
+ // src/lib/api.ts
82
+ import { createIntegrations } from "@farm.js/core/client";
83
+ import type { AppIntegrations } from "./integrations";
84
+
85
+ export const { api, apiClient } = createIntegrations<AppIntegrations>();
86
+ ```
87
+
88
+ ```ts
89
+ const profile = await api.auth.profile.get();
90
+ const user = profile.data?.user;
91
+
92
+ const login = await apiClient.auth.login.get({ query: { returnTo: "/dashboard" } });
93
+ if (login.data) window.location.assign(login.data.redirectTo);
94
+ ```
95
+
96
+ `@farm.js/auth0/client` exports `auth0Client`, the same operations bound to the default paths, and
97
+ their result types (`Auth0ProfileResult`, `Auth0RedirectResult`, `Auth0RedirectQuery`).
98
+
99
+ ## Sessions
100
+
101
+ The session is a signed cookie, not a server record, so sign-out clears it only in that browser. By
102
+ default it lasts as long as the token Auth0 returns, and no refresh token is kept. Narrow that
103
+ window with these options:
104
+
105
+ ```ts
106
+ const revoked = new Set<string>(); // use a shared store such as Redis in production
107
+
108
+ auth0({
109
+ // A sign-in lasts at most an hour, whatever the token lifetime.
110
+ sessionMaxAge: 60 * 60,
111
+ onSignOut(session) {
112
+ if (session.sessionId) revoked.add(session.sessionId);
113
+ },
114
+ isSessionRevoked(session) {
115
+ return session.sessionId !== undefined && revoked.has(session.sessionId);
116
+ },
117
+ });
118
+ ```
119
+
120
+ `isSessionRevoked` runs for the profile route and for protected routes.
121
+
122
+ ## Options
123
+
124
+ `domain`, `clientId`, `clientSecret`, `secret`, and `appBaseUrl` override the variables above.
125
+ `callbackUrl` and `callbackPath` set the callback, and the route path options rename the routes.
126
+
127
+ | Option | Default | Notes |
128
+ | ------------------------- | ---------------------- | --------------------------------------------------------- |
129
+ | `audience` | | Auth0 API audience. |
130
+ | `scopes` | `openid profile email` | |
131
+ | `tokenEndpointAuthMethod` | `auto` | `client_secret_basic`, `client_secret_post`, or `none`. |
132
+ | `protectedRoutes` | | One matcher or a list. |
133
+ | `allowedOrigins` | app origin | Extra origins allowed to drive sign-out. |
134
+ | `cookieName` | `farm_auth0_session` | Use a `__Host-` name in production. |
135
+ | `stateCookieName` | `farm_auth0_state` | Must differ from `cookieName`. |
136
+ | `sessionMaxAge` | token lifetime | Seconds, at least 60. |
137
+ | `isSessionRevoked` | | Return `true` to treat a session as signed out. |
138
+ | `onSignOut` | | Called with the session being ended. |
139
+ | `instance` | | App-owned middleware adapter. Disables the built-in flow. |
140
+ | `log` | | Integration lifecycle logger. |
141
+
142
+ The sign-out route answers a request the browser marks as cross-site with `403`, so another site
143
+ cannot sign a visitor out. A plain link or bookmark still works.
144
+
145
+ ## Bring your own middleware
146
+
147
+ `instance` accepts an object with `middleware(request)` and an optional `matcher` (default
148
+ `/auth(.*)`). It is not an Auth0 SDK client. When it is set, Farm mounts only that middleware and
149
+ creates none of the routes above.
150
+
151
+ ## Documentation
152
+
153
+ - [Auth0 integration](https://farmjs.dev/docs/integrations/auth/auth0)
154
+ - [Auth integrations overview](https://farmjs.dev/docs/integrations/auth)
155
+
156
+ Report issues and find examples in the
157
+ [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/auth0",
3
- "version": "0.1.49",
3
+ "version": "0.1.51-beta.0",
4
4
  "description": "Auth0 integration for Farm.js",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -29,8 +29,8 @@
29
29
  "access": "public"
30
30
  },
31
31
  "dependencies": {
32
- "@farm.js/core": "0.1.49",
33
- "@farm.js/integration-utils": "0.1.49"
32
+ "@farm.js/integration-utils": "0.1.51-beta.0",
33
+ "@farm.js/core": "0.1.51-beta.0"
34
34
  },
35
35
  "scripts": {
36
36
  "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc",