@mastra/auth-neon 0.0.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 (3) hide show
  1. package/CHANGELOG.md +29 -0
  2. package/README.md +101 -0
  3. package/package.json +62 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,29 @@
1
+ # @mastra/auth-neon
2
+
3
+ ## 0.2.0
4
+
5
+ ### Minor Changes
6
+
7
+ - Added Neon Auth adapter for managed authentication with Neon's Better Auth service. ([#17864](https://github.com/mastra-ai/mastra/pull/17864))
8
+ - `MastraAuthNeon` — JWT verification via JWKS, session cookie verification, email/password sign-in/sign-up for Studio, full `ISessionProvider` implementation
9
+ - `MastraRBACNeon` — Role-based access control mapping Neon Auth organization roles (`owner`/`admin`/`member`) to Mastra permissions, with LRU caching
10
+
11
+ **Usage:**
12
+
13
+ ```typescript
14
+ import { MastraAuthNeon, MastraRBACNeon } from '@mastra/auth-neon';
15
+
16
+ const mastra = new Mastra({
17
+ server: {
18
+ auth: new MastraAuthNeon({ baseUrl: process.env.NEON_AUTH_BASE_URL }),
19
+ rbac: new MastraRBACNeon({
20
+ roleMapping: { owner: ['*'], admin: ['*'], member: ['agents:read', 'workflows:*'], _default: [] },
21
+ }),
22
+ },
23
+ });
24
+ ```
25
+
26
+ ### Patch Changes
27
+
28
+ - Updated dependencies [[`de66bb0`](https://github.com/mastra-ai/mastra/commit/de66bb040570444c702ce4d8e1e228a5de2949cb), [`67bf8e2`](https://github.com/mastra-ai/mastra/commit/67bf8e206dfe583954d96015cf0d09f7ac50e45f), [`8216d05`](https://github.com/mastra-ai/mastra/commit/8216d0528d866eb9a07f5d4c87ea3bb1e1139b45), [`d18b23c`](https://github.com/mastra-ai/mastra/commit/d18b23c5e29dfc381e73e3c51fcf6c779afd1823), [`5eb94eb`](https://github.com/mastra-ai/mastra/commit/5eb94ebcf66d4e28c9e26d5821ac93379bab20a0), [`1fa3e12`](https://github.com/mastra-ai/mastra/commit/1fa3e123582b63cfe49de4ee52dc6a065e8d956a), [`f9ee2ac`](https://github.com/mastra-ai/mastra/commit/f9ee2ac661af584e61bc063ac208c9035cd752ef), [`c853d53`](https://github.com/mastra-ai/mastra/commit/c853d535d2df84ab89db1adb4c28900c54c9a2d2), [`d8df1f8`](https://github.com/mastra-ai/mastra/commit/d8df1f8e947e1966c9d4e54713df56d0d0d65226), [`9192ddb`](https://github.com/mastra-ai/mastra/commit/9192ddbced8949113b30de444cbe763f075b59f5), [`ae96523`](https://github.com/mastra-ai/mastra/commit/ae965231f562d9766b0c90c49a69fc68acaa031c), [`17d5a92`](https://github.com/mastra-ai/mastra/commit/17d5a9211aa293b4d4418de3de70dc0394d58101), [`5573693`](https://github.com/mastra-ai/mastra/commit/5573693b589822250e20dfe6cf66e9ff3bc96da8), [`ec4da8a`](https://github.com/mastra-ai/mastra/commit/ec4da8a09e0d2ab452c6ee2c786042ea826b77e5), [`adc44e1`](https://github.com/mastra-ai/mastra/commit/adc44e13c7e570b91e86b20ea7556e61d819db31), [`ed346c0`](https://github.com/mastra-ai/mastra/commit/ed346c0bee2d8496690a4e538bfba1e46894660f), [`c9ce1b2`](https://github.com/mastra-ai/mastra/commit/c9ce1b28d10871110648f9d7b6d76e880b9fa999), [`3ef01fd`](https://github.com/mastra-ai/mastra/commit/3ef01fd130b53d5bd4f828beb174e516a2eb1158), [`245a9a3`](https://github.com/mastra-ai/mastra/commit/245a9a315705fce17ddd980f78a92504b6615c4a), [`dc0b611`](https://github.com/mastra-ai/mastra/commit/dc0b6119b769bd00ee2c5df9259fb376fe63077a), [`38b5de8`](https://github.com/mastra-ai/mastra/commit/38b5de8e5d1d41a69522addf53d96f4b3a1d5bf0), [`dc0b611`](https://github.com/mastra-ai/mastra/commit/dc0b6119b769bd00ee2c5df9259fb376fe63077a), [`dd6a66e`](https://github.com/mastra-ai/mastra/commit/dd6a66ea0b32e0dea8059aec6b35d151e2c87dc4), [`d785c59`](https://github.com/mastra-ai/mastra/commit/d785c593b67fcb4cdc4fab9fdbde5f3b7665efc0), [`1fa3e12`](https://github.com/mastra-ai/mastra/commit/1fa3e123582b63cfe49de4ee52dc6a065e8d956a), [`8b984f4`](https://github.com/mastra-ai/mastra/commit/8b984f4361c202270ceb69257185c4756c9a7c56), [`bf08402`](https://github.com/mastra-ai/mastra/commit/bf084022374fa5d06ca70ed67a86dd64e379071b), [`81fe587`](https://github.com/mastra-ai/mastra/commit/81fe587275035715c1720ddf3fee0505cf053036), [`1fa3e12`](https://github.com/mastra-ai/mastra/commit/1fa3e123582b63cfe49de4ee52dc6a065e8d956a), [`403c438`](https://github.com/mastra-ai/mastra/commit/403c438e417278989ce247233d2c465b8d902cdd), [`f8ba195`](https://github.com/mastra-ai/mastra/commit/f8ba1954e27ee2b20586cc6cd9cf13c002c232f2)]:
29
+ - @mastra/core@1.43.0
package/README.md ADDED
@@ -0,0 +1,101 @@
1
+ # @mastra/auth-neon
2
+
3
+ Mastra authentication provider for [Neon Auth](https://neon.com/docs/auth/overview), the managed authentication service built on Better Auth.
4
+
5
+ Supports JWT bearer token verification via JWKS, session cookie verification, email/password sign-in/sign-up for Studio, full session management, and optional RBAC via Neon Auth's Organization plugin.
6
+
7
+ ## Installation
8
+
9
+ ```bash
10
+ npm install @mastra/auth-neon
11
+ ```
12
+
13
+ ## Usage
14
+
15
+ ```typescript
16
+ import { MastraAuthNeon } from '@mastra/auth-neon';
17
+ import { Mastra } from '@mastra/core';
18
+
19
+ const auth = new MastraAuthNeon({
20
+ baseUrl: process.env.NEON_AUTH_BASE_URL,
21
+ });
22
+
23
+ const mastra = new Mastra({
24
+ server: {
25
+ auth,
26
+ },
27
+ });
28
+ ```
29
+
30
+ ### With RBAC
31
+
32
+ Neon Auth uses Better Auth's Organization plugin which provides `owner`, `admin`, and `member` roles. `MastraRBACNeon` maps these to Mastra permissions:
33
+
34
+ ```typescript
35
+ import { MastraAuthNeon, MastraRBACNeon } from '@mastra/auth-neon';
36
+ import { Mastra } from '@mastra/core';
37
+
38
+ const mastra = new Mastra({
39
+ server: {
40
+ auth: new MastraAuthNeon({
41
+ baseUrl: process.env.NEON_AUTH_BASE_URL,
42
+ }),
43
+ rbac: new MastraRBACNeon({
44
+ roleMapping: {
45
+ owner: ['*'],
46
+ admin: ['*'],
47
+ member: ['agents:read', 'workflows:*'],
48
+ _default: [],
49
+ },
50
+ }),
51
+ },
52
+ });
53
+ ```
54
+
55
+ ## Configuration
56
+
57
+ ### Auth Provider
58
+
59
+ | Option | Environment Variable | Description |
60
+ | ------------------- | -------------------- | ----------------------------------------------------------- |
61
+ | `baseUrl` | `NEON_AUTH_BASE_URL` | Neon Auth base URL (e.g., `https://your-project.neon.tech`) |
62
+ | `jwksUrl` | `NEON_AUTH_JWKS_URL` | Explicit JWKS URL (overrides `baseUrl`-derived URL) |
63
+ | `sessionCookieName` | — | Session cookie name (default: `neonauth.session_token`) |
64
+ | `signUpEnabled` | — | Whether sign-up is allowed (default: `true`) |
65
+
66
+ ### RBAC Provider
67
+
68
+ | Option | Description |
69
+ | ---------------- | ----------------------------------------------------------------------------------- |
70
+ | `baseUrl` | Neon Auth base URL (falls back to `NEON_AUTH_BASE_URL` env var) |
71
+ | `roleMapping` | Map of role slugs to Mastra permission patterns (use `_default` for unmapped roles) |
72
+ | `organizationId` | Scope role lookups to a specific organization |
73
+ | `cache.ttlMs` | Role cache TTL in ms (default: 60000) |
74
+ | `cache.maxSize` | Max cached entries (default: 1000) |
75
+ | `getUserRoles` | Custom function to extract roles from user (bypasses API calls) |
76
+
77
+ ## Authentication flow
78
+
79
+ The adapter verifies tokens in two stages:
80
+
81
+ 1. **JWT verification** — Bearer JWT tokens (e.g., Neon Auth `access_token`) are verified against the JWKS endpoint at `{baseUrl}/auth/jwks`.
82
+ 2. **Session verification** — If JWT verification fails, the token is treated as a session cookie and verified via the Neon Auth REST API (`GET {baseUrl}/auth/get-session`).
83
+
84
+ ## Implemented Interfaces
85
+
86
+ - `MastraAuthProvider` — Token authentication and authorization
87
+ - `IUserProvider` — User awareness for Studio (getCurrentUser, getUser)
88
+ - `ICredentialsProvider` — Email/password sign-in and sign-up for Studio
89
+ - `ISessionProvider` — Session management (validate, refresh, destroy, cookie handling)
90
+ - `IRBACProvider` (via `MastraRBACNeon`) — Role-based access control with permission mapping
91
+
92
+ ## Custom Authorization
93
+
94
+ ```typescript
95
+ const auth = new MastraAuthNeon({
96
+ baseUrl: process.env.NEON_AUTH_BASE_URL,
97
+ authorizeUser: async user => {
98
+ return user.jwt?.role === 'authenticated';
99
+ },
100
+ });
101
+ ```
package/package.json ADDED
@@ -0,0 +1,62 @@
1
+ {
2
+ "name": "@mastra/auth-neon",
3
+ "version": "0.0.0",
4
+ "description": "Mastra Neon Auth integration",
5
+ "type": "module",
6
+ "main": "dist/index.js",
7
+ "types": "dist/index.d.ts",
8
+ "exports": {
9
+ ".": {
10
+ "import": {
11
+ "types": "./dist/index.d.ts",
12
+ "default": "./dist/index.js"
13
+ },
14
+ "require": {
15
+ "types": "./dist/index.d.ts",
16
+ "default": "./dist/index.cjs"
17
+ }
18
+ },
19
+ "./package.json": "./package.json"
20
+ },
21
+ "scripts": {
22
+ "build": "tsup --silent --config tsup.config.ts",
23
+ "build:watch": "tsup --watch --silent --config tsup.config.ts",
24
+ "test": "vitest run",
25
+ "lint": "eslint ."
26
+ },
27
+ "license": "Apache-2.0",
28
+ "dependencies": {
29
+ "jose": "^6.2.1"
30
+ },
31
+ "peerDependencies": {
32
+ "@mastra/core": ">=1.0.0-0 <2.0.0-0"
33
+ },
34
+ "devDependencies": {
35
+ "@internal/lint": "workspace:*",
36
+ "@internal/types-builder": "workspace:*",
37
+ "@mastra/core": "workspace:*",
38
+ "@types/node": "22.19.21",
39
+ "@vitest/coverage-v8": "catalog:",
40
+ "@vitest/ui": "catalog:",
41
+ "eslint": "^10.4.1",
42
+ "tsup": "^8.5.1",
43
+ "typescript": "catalog:",
44
+ "vitest": "catalog:"
45
+ },
46
+ "files": [
47
+ "dist",
48
+ "CHANGELOG.md"
49
+ ],
50
+ "homepage": "https://mastra.ai",
51
+ "repository": {
52
+ "type": "git",
53
+ "url": "git+https://github.com/mastra-ai/mastra.git",
54
+ "directory": "auth/neon"
55
+ },
56
+ "bugs": {
57
+ "url": "https://github.com/mastra-ai/mastra/issues"
58
+ },
59
+ "engines": {
60
+ "node": ">=22.13.0"
61
+ }
62
+ }