@lumoauth/backend 1.0.0 → 1.1.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 +197 -25
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,52 +1,224 @@
1
1
  # @lumoauth/backend
2
2
 
3
- The LumoAuth server SDK for plain Node services. Credentialed with a tenant
4
- API key (`lmk_…`) or machine token, guarded against browser construction, and
5
- exposing the full namespace blueprint: `auth`, `permissions`, `zanzibar`,
6
- `abac`, `agents`, `approvals`, `delegation`, `jit`, `mcp`, plus the `api`
7
- escape hatch to the generated OpenAPI client.
3
+ [![npm](https://img.shields.io/npm/v/@lumoauth/backend.svg)](https://www.npmjs.com/package/@lumoauth/backend)
4
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
8
5
 
9
- Using Express? Install `@lumoauth/express` instead (it re-exports this
10
- package). Next.js apps want `@lumoauth/nextjs`.
6
+ > The LumoAuth server SDK for Node. It holds a server credential, throws an error
7
+ > in a browser, and gives you every namespace plus an escape hatch to the
8
+ > full generated REST client.
9
+
10
+ This package is part of the [LumoAuth JavaScript SDK](../../README.md). Not
11
+ sure that it is the package that you need? See
12
+ [Which package do I need?](../../README.md#which-package-do-i-need).
13
+
14
+ ## Contents
15
+
16
+ - [Is this the right package?](#is-this-the-right-package)
17
+ - [Install](#install)
18
+ - [Quick start](#quick-start)
19
+ - [Which credential to use](#which-credential-to-use)
20
+ - [Configuration](#configuration)
21
+ - [Namespaces](#namespaces)
22
+ - [The `api` escape hatch](#the-api-escape-hatch)
23
+ - [Security model](#security-model)
24
+ - [Troubleshooting](#troubleshooting)
25
+ - [Related packages](#related-packages)
26
+ - [Learn more](#learn-more)
27
+ - [License](#license)
28
+
29
+ ## Is this the right package?
30
+
31
+ | You are… | Use |
32
+ |---|---|
33
+ | Running **Express** | [`@lumoauth/express`](../express/README.md). It adds the login routes for you and re-exports this package |
34
+ | Running **Next.js** | [`@lumoauth/nextjs`](../nextjs/README.md) |
35
+ | Running any other Node server, worker, cron job or script | **This package** |
36
+ | Writing an **AI agent** that signs in as itself | [`@lumoauth/agent`](../agent/README.md) |
37
+ | Writing browser code | [`@lumoauth/client`](../client/README.md). This package throws an error in a browser |
11
38
 
12
39
  ## Install
13
40
 
14
- ```sh
41
+ ```bash
15
42
  npm install @lumoauth/backend
16
43
  ```
17
44
 
18
- ## Example
45
+ This package needs Node 18 or newer.
46
+
47
+ ## Quick start
48
+
49
+ A permission check answers for the subject of the credential. To check a
50
+ signed-in user, pass that user's access token as `secretKey`. A server that
51
+ holds an organization API key can name the user instead; see
52
+ [Which credential to use](#which-credential-to-use).
19
53
 
20
54
  ```ts
21
55
  import { LumoAuthBackend } from '@lumoauth/backend';
22
56
 
57
+ function lumoFor(accessToken: string) {
58
+ return new LumoAuthBackend({
59
+ baseUrl: process.env.LUMOAUTH_URL!, // https://app.lumoauth.dev
60
+ secretKey: accessToken,
61
+ orgId: 'acme-corp',
62
+ });
63
+ }
64
+
65
+ const lumo = lumoFor(userAccessToken);
66
+
67
+ const canEdit = await lumo.permissions.check('documents.edit'); // RBAC
68
+ const isOwner = await lumo.zanzibar.isOwner('folder:projects', 'user:alice'); // relationships
69
+ const decision = await lumo.abac.check({ resourceType: 'document', resourceId: 'doc-123', action: 'read' }); // ABAC, needs abac:read
70
+ ```
71
+
72
+ The ABAC call needs the `abac:read` scope on the user's token. The
73
+ [workspace README](../../README.md#scopes) lists every scope.
74
+
75
+ ## Which credential to use
76
+
77
+ `secretKey` is the credential for every namespace call. An organization API
78
+ key (`lmk_…`) is sent in `X-API-Key`. Any other value is sent as
79
+ `Authorization: Bearer`.
80
+
81
+ | You pass | Namespace calls answer for | Notes |
82
+ |---|---|---|
83
+ | A user access token | that user | The usual choice. Some calls need a scope, for example `authz:read` for `permissions.list()` |
84
+ | An agent's access token | that agent | Agents usually use [`@lumoauth/agent`](../agent/README.md), which gets and refreshes this token for you |
85
+ | An organization API key (`lmk_…`) | the key's owner, or the user that you name | The key works on the permission and Zanzibar checks and in the [`api` escape hatch](#the-api-escape-hatch). The server rejects it on the ABAC, agent and JIT routes |
86
+
87
+ With an API key, name the user whose permission you want to check. The id is
88
+ the LumoAuth user id, which is the `sub` claim of that user's token. The key
89
+ needs the `authz:check` scope for this.
90
+
91
+ ```ts
23
92
  const lumo = new LumoAuthBackend({
24
93
  baseUrl: process.env.LUMOAUTH_URL!,
25
- secretKey: process.env.LUMOAUTH_SECRET_KEY!, // never ship this to a browser
26
- orgId: 'acme-corp',
94
+ secretKey: process.env.LUMOAUTH_API_KEY!, // lmk_…, with the authz:check scope
27
95
  });
28
96
 
29
- // RBAC / ReBAC / ABAC checks
30
- const allowed = await lumo.permissions.check('documents.edit');
97
+ const allowed = await lumo.permissions.check('documents.edit', undefined, { userId: session.sub });
98
+ ```
99
+
100
+ Approvals, JIT tasks and delegation accept agent credentials only. Call them
101
+ from `@lumoauth/agent`.
102
+
103
+ ## Configuration
104
+
105
+ `new LumoAuthBackend(config)` accepts:
106
+
107
+ | Option | Type | Required | Description |
108
+ |---|---|---|---|
109
+ | `baseUrl` | `string` | yes | The LumoAuth host, for example `https://app.lumoauth.dev` |
110
+ | `secretKey` | `string \| () => string \| Promise<string>` | yes | The credential, as described above. A function is called before each request. Load secrets from the environment. Never put them in code or in `NEXT_PUBLIC_*` or `VITE_*` variables |
111
+ | `orgId` | `string` | for org-scoped calls | The organization slug. `abac`, `agents`, `approvals`, `jit`, `mcp` and `delegation` need it |
112
+ | `clientId` | `string` | for `auth` and `delegation` | The OAuth client ID |
113
+ | `clientSecret` | `string` | for `delegation` | The OAuth client secret for the consent-code exchange and for revocation |
114
+ | `redirectUri` | `string` | for `delegation` | The callback URL of the delegation consent flow |
115
+ | `timeout` | `number` | no | Request timeout in milliseconds. Default 30 000 |
116
+ | `fetch` | `typeof fetch` | no | A custom `fetch` |
117
+ | `headers` | `Record<string, string>` | no | Extra headers on every request |
118
+ | `cache` | `boolean \| { ttl?: number; maxSize?: number }` | no | The cache for permission checks. Default: on, 5 minutes, 1 000 entries. `false` turns it off |
31
119
 
32
- // Push-approval for irreversible agent actions
33
- const approval = await lumo.approvals.require({
34
- taskId: 'wire-001',
35
- reason: 'Wire $4,500 to vendor INV-7741',
36
- impact: 'high',
37
- onBehalfOf: 'ada@acme.com',
120
+ The constructor throws `LumoAuthConfigError` when `baseUrl` or `secretKey` is
121
+ missing. Nothing is read from the environment. By convention the values come
122
+ from `LUMOAUTH_URL` and `LUMOAUTH_SECRET_KEY`.
123
+
124
+ ## Namespaces
125
+
126
+ | Namespace | What it does | Methods |
127
+ |---|---|---|
128
+ | `permissions` | RBAC checks for the credential's subject | `check`, `checkDetailed`, `checkBulk`, `checkAny`, `checkAll`, `checkAnyDetailed`, `checkAllDetailed`, `list`, `listSlugs`, `clearCache` |
129
+ | `zanzibar` | Relationship checks | `check`, `checkDetailed`, `expand`, `isViewer`, `isEditor`, `isOwner`, `isMember`, `isAdmin` |
130
+ | `abac` | Attribute-based decisions and attributes | `check`, `isAllowed`, `checkBulk`, `getMyAttributes`, `setUserAttribute`, `getResourceAttributes`, `setResourceAttribute`, `getAttributeDefinitions` |
131
+ | `auth` | OAuth 2.0 flows on the server | `buildAuthorizationUrl`, `exchangeCodeForTokens`, `refreshToken`, `revokeToken`, `getUserInfo`, `passwordGrant` |
132
+ | `agents` | Agent identity | `ask`, `isAllowed`, `me`, `getCurrentAgent`, `capabilities`, `budget`, `register` |
133
+ | `approvals` | Push approval for agent actions (agent credentials only) | `require`, `create`, `getStatus`, `wait` |
134
+ | `delegation` | Act for a user with RFC 8693 token exchange | `getConsentUrl`, `handleConsentCallback`, `setUserToken`, `exchange`, `request`, `delegateToSubAgent`, `revoke`, `revokeAll` |
135
+ | `jit` | Just-in-time permissions | `createTask`, `requestPermission`, `getRequestStatus`, `getToken`, `evaluateTask`, `completeTask`, `listPendingRequests` |
136
+ | `mcp` | Tokens for secured MCP servers | `getToken`, `getTokenDetailed`. The server ID is the MCP server's https URL, which becomes the token's `aud` |
137
+
138
+ `lumo.clearCache()` clears the permission cache. The parameters, return
139
+ values and required credentials of every method are in the
140
+ [workspace API reference](../../README.md#api-reference), with a guide for
141
+ each namespace. This package re-exports all of
142
+ [`@lumoauth/shared`](../shared/README.md), so one import covers the client and
143
+ the error classes:
144
+
145
+ ```ts
146
+ import { LumoAuthBackend, LumoAuthPermissionDeniedError } from '@lumoauth/backend';
147
+ ```
148
+
149
+ ## The `api` escape hatch
150
+
151
+ The namespaces cover the high-level calls. For the other REST operations
152
+ (admin users and roles, webhooks, SCIM, audit logs, …), `lumo.api` loads the
153
+ generated OpenAPI client `@lumoauth/api-client` when you first use it. The
154
+ client comes configured with this backend's base URL and credential:
155
+
156
+ ```ts
157
+ const lumo = new LumoAuthBackend({
158
+ baseUrl: process.env.LUMOAUTH_URL!,
159
+ secretKey: process.env.LUMOAUTH_SECRET_KEY!, // an lmk_… organization API key
160
+ orgId: 'acme-corp',
38
161
  });
39
162
 
40
- // Full REST surface (admin, SCIM, audit logs) via the generated client
41
- // (requires `npm install @lumoauth/api-client`):
42
- const { AdminUsersApi } = lumo.api.module;
163
+ const { AdminUsersApi, AdminWebhooksApi } = lumo.api.module;
43
164
  const users = lumo.api.create(AdminUsersApi);
165
+ const hooks = lumo.api.create(AdminWebhooksApi);
44
166
  ```
45
167
 
46
- ## Docs
168
+ The escape hatch sends an `lmk_…` key as `X-API-Key` and any other credential
169
+ as `Authorization: Bearer`. The key's scopes (for example `admin:users:read`)
170
+ determine which admin calls succeed.
171
+
172
+ `@lumoauth/api-client` is an **optional peer dependency**, because it is not
173
+ published to npm yet. Until it is, install it from the `typescript/`
174
+ directory of the [`LumoAuth/api-clients`](https://github.com/LumoAuth/api-clients)
175
+ repo. Using `lumo.api` without it throws a `LumoAuthConfigError` that says
176
+ how to install it.
177
+
178
+ ## Security model
179
+
180
+ - **Server only, checked in code.** The constructor calls `assertServerOnly()`
181
+ and throws when it finds a browser. A server credential therefore cannot
182
+ reach a browser bundle by accident. `@lumoauth/client` applies the opposite
183
+ rule and rejects `lmk_…` keys.
184
+ - **The secret can be a function.** `secretKey` may be an async function. Use
185
+ that to read the secret from a secrets manager, or to rotate it without
186
+ creating a new client.
187
+ - **The cache is per process.** Permission results are cached in memory for 5
188
+ minutes by default. Call `lumo.permissions.clearCache()` after you change a
189
+ subject's roles.
190
+
191
+ ## Troubleshooting
192
+
193
+ | Symptom | Cause | Fix |
194
+ |---|---|---|
195
+ | 401 on an ABAC, agent or JIT call with an `lmk_` key | Organization API keys only work on the admin API, client registration and the authorization checks | Use a user access token for ABAC, and `@lumoauth/agent` for agent calls |
196
+ | 403 `INSUFFICIENT_PERMISSIONS` from a check with `userId` | The key lacks the `authz:check` scope | Add the scope to the key |
197
+ | 404 `SUBJECT_NOT_FOUND` from a check with `userId` | The id is not a LumoAuth user id in this organization | Pass the user's `sub` claim, not your app's own id |
198
+ | 403 `agent_token_required` from `approvals` | Approvals accept agent credentials only | Use [`@lumoauth/agent`](../agent/README.md) |
199
+ | 403 with `requiredScopes` on the error | The user token lacks a scope | Request the scope at sign-in |
200
+ | `LumoAuthConfigError` that mentions a browser | The backend was constructed in browser code | Keep it in a route handler, a server component or an API route |
201
+ | `LumoAuthConfigError` that mentions `@lumoauth/api-client` | `lumo.api` was used without the generated client installed | Install it as described above |
202
+
203
+ The [workspace README](../../README.md#troubleshooting) has the full list.
204
+
205
+ ## Related packages
206
+
207
+ | Package | How it relates |
208
+ |---|---|
209
+ | [`@lumoauth/express`](../express/README.md) | Express middleware built on this package. It re-exports `LumoAuthBackend` |
210
+ | [`@lumoauth/nextjs`](../nextjs/README.md) | Server-side auth for Next.js. Use it instead of this package in a Next.js app |
211
+ | [`@lumoauth/agent`](../agent/README.md) | For code that acts **as an agent** |
212
+ | [`@lumoauth/client`](../client/README.md) | The browser counterpart |
213
+ | [`@lumoauth/shared`](../shared/README.md) | The core that this package re-exports |
214
+ | [Workspace README](../../README.md) | How all of the packages fit together |
215
+
216
+ ## Learn more
47
217
 
48
- https://docs.lumoauth.dev
218
+ - The [Node.js and Express quickstart](https://docs.lumoauth.dev/quickstarts/node/)
219
+ - The [SDK overview](https://docs.lumoauth.dev/developer/sdks/)
220
+ - The [generated API clients](https://github.com/LumoAuth/api-clients), with notes on when to use them
49
221
 
50
222
  ## License
51
223
 
52
- MIT
224
+ [MIT](./LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lumoauth/backend",
3
- "version": "1.0.0",
3
+ "version": "1.1.0",
4
4
  "description": "Official LumoAuth server SDK — token verification and server-side auth. Never import this from browser code.",
5
5
  "license": "MIT",
6
6
  "author": "LumoAuth",