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 CHANGED
@@ -1,35 +1,158 @@
1
1
  # create-lumo-agent
2
2
 
3
- Scaffold a working LumoAuth-secured AI agent application in **under 60 seconds**.
3
+ [![npm](https://img.shields.io/npm/v/create-lumo-agent.svg)](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
- npm install
53
+ cp .env.example .env.local # then set LUMOAUTH_AGENT_TOKEN
9
54
  npm run dev
10
55
  ```
11
56
 
12
- What you get:
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
- - **Next.js 15 (App Router)** with `<SignIn>` (from `@lumoauth/react`) ready out of the box
15
- - An **agent identity** registered with your LumoAuth tenant
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
- ## Templates
63
+ ## What you get
21
64
 
22
- - `nextjs-agent` (default) — Next.js + React + TypeScript
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
- > `python-agent` (FastAPI) and `langgraph-agent` starters are on the roadmap.
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
- ## Prerequisites
78
+ The project uses plain Next.js. You can read every file and change anything.
27
79
 
28
- - Node 18+
29
- - A LumoAuth tenant — sign up free at [https://lumoauth.dev](https://lumoauth.dev)
80
+ ## Configuration
30
81
 
31
- ## CLI options
82
+ Copy `.env.example` to `.env.local`. It holds these variables:
32
83
 
33
- ```bash
34
- create-lumo-agent <project-name> [--template nextjs-agent] [--no-install]
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,6 +1,6 @@
1
1
  {
2
2
  "name": "create-lumo-agent",
3
- "version": "0.1.0",
3
+ "version": "1.2.0",
4
4
  "description": "Scaffold a working LumoAuth agent app in 60 seconds.",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",
@@ -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
- const approval = await lumo.agent.requireApproval({
21
- taskId: `wire-${action}-${vendor}`,
22
- reason: description,
23
- impact: 'high',
24
- // The user (subject) who must approve. In a real app this is the signed-in
25
- // user the agent is acting for.
26
- onBehalfOf: onBehalfOf ?? 'user@example.com',
27
- meta: { action, amount, vendor },
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(