create-lumo-agent 0.1.0 → 1.2.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 +140 -17
- package/package.json +1 -1
- package/templates/nextjs-agent/app/api/approval/route.ts +26 -9
package/README.md
CHANGED
|
@@ -1,35 +1,158 @@
|
|
|
1
1
|
# create-lumo-agent
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/create-lumo-agent)
|
|
4
|
+
|
|
5
|
+
`create-lumo-agent` creates a small Next.js app that shows LumoAuth securing an AI agent. The app
|
|
6
|
+
has three parts:
|
|
7
|
+
|
|
8
|
+
- sign-in for people, with `@lumoauth/react`;
|
|
9
|
+
- an API route that acts as the agent and checks a permission before it works;
|
|
10
|
+
- a demo of human approval, in which a person approves on their phone before the agent does
|
|
11
|
+
something that cannot be undone.
|
|
12
|
+
|
|
13
|
+
It is part of the [LumoAuth JavaScript SDK](../../README.md).
|
|
14
|
+
|
|
15
|
+
## Contents
|
|
16
|
+
|
|
17
|
+
- [Is this the right package?](#is-this-the-right-package)
|
|
18
|
+
- [Requirements](#requirements)
|
|
19
|
+
- [Quick start](#quick-start)
|
|
20
|
+
- [What you get](#what-you-get)
|
|
21
|
+
- [Configuration](#configuration)
|
|
22
|
+
- [CLI reference](#cli-reference)
|
|
23
|
+
- [Templates](#templates)
|
|
24
|
+
- [Troubleshooting](#troubleshooting)
|
|
25
|
+
- [Versioning](#versioning)
|
|
26
|
+
- [Related packages](#related-packages)
|
|
27
|
+
- [Licence](#licence)
|
|
28
|
+
|
|
29
|
+
## Is this the right package?
|
|
30
|
+
|
|
31
|
+
| You want to… | Use |
|
|
32
|
+
|---|---|
|
|
33
|
+
| Start a new agent project from a working example | **This package** |
|
|
34
|
+
| Add agent identity, approvals or JIT permissions to existing Node code | [`@lumoauth/agent`](../agent/README.md) |
|
|
35
|
+
| Add sign-in to an existing React or Next.js app | [`@lumoauth/react`](../react/README.md) or [`@lumoauth/nextjs`](../nextjs/README.md) |
|
|
36
|
+
|
|
37
|
+
## Requirements
|
|
38
|
+
|
|
39
|
+
- Node 18 or newer, with `npm`
|
|
40
|
+
- A LumoAuth organization. Sign up at [lumoauth.dev](https://lumoauth.dev).
|
|
41
|
+
- From the LumoAuth dashboard:
|
|
42
|
+
- your organization slug, such as `acme-corp`;
|
|
43
|
+
- a **public** OAuth client with PKCE. Register `http://localhost:3000/callback` as a redirect
|
|
44
|
+
URI, and add `http://localhost:3000` to its allowed origins;
|
|
45
|
+
- an AI agent, and an access token for it;
|
|
46
|
+
- for the approval demo, a user with the LumoAuth mobile app enrolled.
|
|
47
|
+
|
|
48
|
+
## Quick start
|
|
4
49
|
|
|
5
50
|
```bash
|
|
6
51
|
npx create-lumo-agent my-agent
|
|
7
52
|
cd my-agent
|
|
8
|
-
|
|
53
|
+
cp .env.example .env.local # then set LUMOAUTH_AGENT_TOKEN
|
|
9
54
|
npm run dev
|
|
10
55
|
```
|
|
11
56
|
|
|
12
|
-
|
|
57
|
+
The CLI asks for your LumoAuth domain, organization slug and OAuth client ID. It writes them into
|
|
58
|
+
the project and runs `npm install`.
|
|
13
59
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
- **JIT permission requests** wired to a sample tool the agent calls on the user's behalf
|
|
17
|
-
- **Push approval** so a human approves on their phone before the agent does anything irreversible
|
|
18
|
-
- A working `npm run dev` demo: visit `/`, sign in, ask the agent to do something — watch the request hit your phone for approval, see it complete
|
|
60
|
+
Open <http://localhost:3000> and sign in. Then ask the agent to do something, and approve the
|
|
61
|
+
request on your phone.
|
|
19
62
|
|
|
20
|
-
##
|
|
63
|
+
## What you get
|
|
21
64
|
|
|
22
|
-
|
|
65
|
+
A Next.js 15 App Router project in TypeScript. It depends on the published `@lumoauth/react` and
|
|
66
|
+
`@lumoauth/client` packages.
|
|
23
67
|
|
|
24
|
-
|
|
68
|
+
| File | What it does |
|
|
69
|
+
|---|---|
|
|
70
|
+
| `app/providers.tsx` | Sets up `<LumoAuthProvider>` with your domain, organization and client ID. The redirect URI is `<current origin>/callback`. |
|
|
71
|
+
| `app/page.tsx` | The sign-in card (`<SignIn>`) and the agent demo |
|
|
72
|
+
| `app/callback/page.tsx` | Finishes sign-in with `<AuthCallback>` |
|
|
73
|
+
| `lib/lumo.ts` | A server-side `LumoAuth` client that authenticates **as the agent** with `LUMOAUTH_AGENT_TOKEN` |
|
|
74
|
+
| `app/api/agent/route.ts` | An agent endpoint. It checks `permissions.check('reports.send')` as the agent before it works, and answers `403` when the agent lacks the permission. |
|
|
75
|
+
| `app/api/approval/route.ts` | The approval demo. It sends an approval request to the user's phone, waits for the answer, and only then reports a "wire transfer" as done. |
|
|
76
|
+
| `.env.example` | The four variables below, filled in from your answers |
|
|
25
77
|
|
|
26
|
-
|
|
78
|
+
The project uses plain Next.js. You can read every file and change anything.
|
|
27
79
|
|
|
28
|
-
|
|
29
|
-
- A LumoAuth tenant — sign up free at [https://lumoauth.dev](https://lumoauth.dev)
|
|
80
|
+
## Configuration
|
|
30
81
|
|
|
31
|
-
|
|
82
|
+
Copy `.env.example` to `.env.local`. It holds these variables:
|
|
32
83
|
|
|
33
|
-
|
|
34
|
-
|
|
84
|
+
| Variable | Public? | Description |
|
|
85
|
+
|---|---|---|
|
|
86
|
+
| `NEXT_PUBLIC_LUMOAUTH_DOMAIN` | yes | Root URL of LumoAuth, not an `/orgs/…` path. For example `https://app.lumoauth.dev`, or `https://eu.app.lumoauth.dev` for the EU region. |
|
|
87
|
+
| `NEXT_PUBLIC_LUMOAUTH_ORG_ID` | yes | Organization slug, such as `acme-corp` |
|
|
88
|
+
| `NEXT_PUBLIC_LUMOAUTH_CLIENT_ID` | yes | OAuth client ID that the browser uses for sign-in |
|
|
89
|
+
| `LUMOAUTH_AGENT_TOKEN` | **no**, server only | An access token for your agent. The server uses it for permission checks and approvals. |
|
|
90
|
+
|
|
91
|
+
Never give the agent token a `NEXT_PUBLIC_` prefix. Next.js puts every `NEXT_PUBLIC_` value into
|
|
92
|
+
the browser bundle.
|
|
93
|
+
|
|
94
|
+
## CLI reference
|
|
95
|
+
|
|
96
|
+
```
|
|
97
|
+
npx create-lumo-agent [project-name] [options]
|
|
98
|
+
|
|
99
|
+
Options
|
|
100
|
+
-t, --template <name> Template to use (default: nextjs-agent)
|
|
101
|
+
--no-install Do not run npm install after creating the project
|
|
35
102
|
```
|
|
103
|
+
|
|
104
|
+
The CLI asks for anything that you did not pass on the command line:
|
|
105
|
+
|
|
106
|
+
| Question | Default | Rule |
|
|
107
|
+
|---|---|---|
|
|
108
|
+
| Project name | `my-agent` | Lowercase letters, digits and dashes. The folder must be empty or must not exist. |
|
|
109
|
+
| Template | the only template | Asked only when there is more than one |
|
|
110
|
+
| LumoAuth domain | `https://app.lumoauth.dev` | Must be a URL |
|
|
111
|
+
| Organization ID | `your-org` | |
|
|
112
|
+
| OAuth client ID | empty | You can fill it in later in `.env.local`. |
|
|
113
|
+
|
|
114
|
+
Press Ctrl+C at any question to stop without creating files.
|
|
115
|
+
|
|
116
|
+
## Templates
|
|
117
|
+
|
|
118
|
+
| Template | Stack | Status |
|
|
119
|
+
|---|---|---|
|
|
120
|
+
| `nextjs-agent` (default) | Next.js 15, React 18, TypeScript | Available |
|
|
121
|
+
|
|
122
|
+
Templates are in this package's `templates/` folder. The CLI replaces `{{projectName}}`,
|
|
123
|
+
`{{domain}}`, `{{orgId}}` and `{{clientId}}` in every file. A file named `gitignore` becomes
|
|
124
|
+
`.gitignore`.
|
|
125
|
+
|
|
126
|
+
## Troubleshooting
|
|
127
|
+
|
|
128
|
+
| Symptom | Cause | Fix |
|
|
129
|
+
|---|---|---|
|
|
130
|
+
| `error: my-agent/ already exists and is not empty` | The target folder has files in it. | Choose another name, or empty the folder. |
|
|
131
|
+
| The app throws `NEXT_PUBLIC_LUMOAUTH_DOMAIN must be set` | `.env.local` is missing. | Copy `.env.example` to `.env.local`. |
|
|
132
|
+
| Sign-in fails with a redirect URI or CORS error | The OAuth client does not list `http://localhost:3000/callback` or `http://localhost:3000`. | Add them to the client in the dashboard. |
|
|
133
|
+
| `/api/agent` answers `403` | The agent does not hold `reports.send`. | Grant the permission to the agent, or change the permission in the route. |
|
|
134
|
+
| `/api/approval` fails with `403 test_token_not_accepted` | The agent token is a test token from the portal. Approvals do not accept test tokens. | Use a client-credentials access token for the agent. |
|
|
135
|
+
| `/api/approval` fails with an error while the user gets an email | The user in `onBehalfOf` has not enrolled the mobile app. LumoAuth emails that user a notification and returns no approval to wait on. | Enroll the LumoAuth mobile app for that user. |
|
|
136
|
+
| `npm install failed; you can run it manually` | The install step failed. | Run `npm install` in the project folder. |
|
|
137
|
+
|
|
138
|
+
## Versioning
|
|
139
|
+
|
|
140
|
+
This package is version 0.1.0. The generated project depends on `@lumoauth/client` and
|
|
141
|
+
`@lumoauth/react` `^1.0.0`.
|
|
142
|
+
|
|
143
|
+
## Related packages
|
|
144
|
+
|
|
145
|
+
| Package | Relationship |
|
|
146
|
+
|---|---|
|
|
147
|
+
| [`@lumoauth/react`](../react/README.md) | Provides sign-in in the generated app |
|
|
148
|
+
| [`@lumoauth/client`](../client/README.md) | Provides the agent's server-side client in the generated app |
|
|
149
|
+
| [`@lumoauth/agent`](../agent/README.md) | The full agent SDK: client-credentials sign-in, JIT, delegation and AAuth |
|
|
150
|
+
| [Workspace README](../../README.md) | How the packages fit together |
|
|
151
|
+
|
|
152
|
+
More: [Secure AI agents](https://docs.lumoauth.dev/quickstarts/ai-agent-security/),
|
|
153
|
+
[AAuth quickstart](https://docs.lumoauth.dev/agents/aauth-quickstart/) and the
|
|
154
|
+
[SDK overview](https://docs.lumoauth.dev/developer/sdks/).
|
|
155
|
+
|
|
156
|
+
## Licence
|
|
157
|
+
|
|
158
|
+
See [LICENSE](./LICENSE).
|
package/package.json
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { NextResponse } from 'next/server';
|
|
2
|
+
import { LumoAuthApprovalNotDeliveredError } from '@lumoauth/client';
|
|
2
3
|
import { lumo } from '@/lib/lumo';
|
|
3
4
|
|
|
4
5
|
/**
|
|
@@ -10,6 +11,9 @@ import { lumo } from '@/lib/lumo';
|
|
|
10
11
|
* 2. polls until the user taps approve/deny (or the request times out)
|
|
11
12
|
* 3. resolves with the approval status + a short-lived approval token
|
|
12
13
|
*
|
|
14
|
+
* When the user has no enrolled push device, no prompt is sent and it
|
|
15
|
+
* throws LumoAuthApprovalNotDeliveredError instead (never "approved").
|
|
16
|
+
*
|
|
13
17
|
* This is the demo nobody else has.
|
|
14
18
|
*/
|
|
15
19
|
export async function POST(req: Request) {
|
|
@@ -17,15 +21,28 @@ export async function POST(req: Request) {
|
|
|
17
21
|
|
|
18
22
|
const description = `Wire $${Number(amount).toLocaleString()} to vendor ${vendor}`;
|
|
19
23
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
24
|
+
let approval;
|
|
25
|
+
try {
|
|
26
|
+
approval = await lumo.agent.requireApproval({
|
|
27
|
+
taskId: `wire-${action}-${vendor}`,
|
|
28
|
+
reason: description,
|
|
29
|
+
impact: 'high',
|
|
30
|
+
// The user (subject) who must approve. In a real app this is the signed-in
|
|
31
|
+
// user the agent is acting for.
|
|
32
|
+
onBehalfOf: onBehalfOf ?? 'user@example.com',
|
|
33
|
+
meta: { action, amount, vendor },
|
|
34
|
+
});
|
|
35
|
+
} catch (err) {
|
|
36
|
+
if (err instanceof LumoAuthApprovalNotDeliveredError) {
|
|
37
|
+
// email_fallback_sent: the user was emailed and should enrol a device.
|
|
38
|
+
// no_enrolled_device: no device, and the email could not be sent.
|
|
39
|
+
return NextResponse.json(
|
|
40
|
+
{ error: 'approval_not_delivered', reason: err.reason },
|
|
41
|
+
{ status: 409 },
|
|
42
|
+
);
|
|
43
|
+
}
|
|
44
|
+
throw err;
|
|
45
|
+
}
|
|
29
46
|
|
|
30
47
|
if (approval.status !== 'approved') {
|
|
31
48
|
return NextResponse.json(
|