@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.
- package/README.md +197 -25
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,52 +1,224 @@
|
|
|
1
1
|
# @lumoauth/backend
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
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
|
+
[](https://www.npmjs.com/package/@lumoauth/backend)
|
|
4
|
+
[](./LICENSE)
|
|
8
5
|
|
|
9
|
-
|
|
10
|
-
|
|
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
|
-
```
|
|
41
|
+
```bash
|
|
15
42
|
npm install @lumoauth/backend
|
|
16
43
|
```
|
|
17
44
|
|
|
18
|
-
|
|
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.
|
|
26
|
-
orgId: 'acme-corp',
|
|
94
|
+
secretKey: process.env.LUMOAUTH_API_KEY!, // lmk_…, with the authz:check scope
|
|
27
95
|
});
|
|
28
96
|
|
|
29
|
-
|
|
30
|
-
|
|
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
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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