@frontmcp/auth 1.9.6 → 1.9.7

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/README.md +101 -56
  2. package/esm/package.json +16 -11
  3. package/package.json +16 -11
package/README.md CHANGED
@@ -1,85 +1,130 @@
1
1
  # @frontmcp/auth
2
2
 
3
- Authentication, session management, and credential vault for FrontMCP servers.
3
+ Authentication and authorization for FrontMCP servers: the five `auth` modes, OAuth 2.1 sign-in with FrontMCP as its own authorization server or in front of your identity provider, JSON Web Token (JWT) and session checks, access rules on tools, and the built-in sign-in pages. `@frontmcp/sdk` depends on this package, so a FrontMCP server already has it, and you configure it through `@FrontMcp({ auth })`. Install it yourself only to import something the SDK doesn't re-export, like `escapeHtml` for a custom sign-in page or `AuthorityDeniedError`.
4
4
 
5
- [![NPM](https://img.shields.io/npm/v/@frontmcp/auth.svg)](https://www.npmjs.com/package/@frontmcp/auth)
5
+ [![npm](https://img.shields.io/npm/v/@frontmcp/auth.svg)](https://www.npmjs.com/package/@frontmcp/auth) [![License](https://img.shields.io/npm/l/@frontmcp/auth.svg)](https://github.com/agentfront/frontmcp/blob/main/LICENSE)
6
6
 
7
7
  ## Install
8
8
 
9
+ A FrontMCP server doesn't need this step: `@frontmcp/sdk` installs `@frontmcp/auth`. To import from it directly:
10
+
9
11
  ```bash
10
12
  npm install @frontmcp/auth
11
13
  ```
12
14
 
13
- > Typically consumed via `@frontmcp/sdk` — direct installation is only needed for advanced use cases.
15
+ Use the same version as `@frontmcp/sdk`. It needs Node.js 24 or later.
14
16
 
15
- ## Features
17
+ | Peer dependency | Required | What it's for |
18
+ | -------------------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
19
+ | `@frontmcp/lazy-zod` | Yes | The option schemas. `@frontmcp/sdk` already brings it; it needs `zod` 4. |
20
+ | `ioredis` | No | Redis-backed stores: `tokenStorage: { redis }` in `local` and `remote` modes, `RedisSessionStore`, and others. |
21
+ | `@vercel/kv` | No | `VercelKvSessionStore`. |
22
+ | `@frontmcp/storage-sqlite` | No | `tokenStorage: { sqlite }`. |
16
23
 
17
- - **Remote OAuth** — delegate authentication to an external IdP with optional DCR ([docs][docs-remote])
18
- - **Local OAuth** — built-in token issuance with configurable sign keys ([docs][docs-local])
19
- - **JWKS validation** — JSON Web Key Set discovery and token verification ([docs][docs-jwks])
20
- - **OAuth stores** — session, token, and authorization code persistence (memory, Redis, Vercel KV) ([docs][docs-stores])
21
- - **Credential vault** — encrypted storage for secrets and API keys ([docs][docs-vault])
22
- - **PKCE** — Proof Key for Code Exchange (RFC 7636) built on `@frontmcp/utils` crypto ([docs][docs-pkce])
23
- - **CIMD** — Client Instance Machine Detection for session continuity ([docs][docs-cimd])
24
- - **Auth UI templates** — consent, login, and error pages ([docs][docs-ui])
25
- - **Audience validation** — per-app audience and scope enforcement ([docs][docs-audience])
26
- - **Token vault** — secure token exchange and refresh management ([docs][docs-token-vault])
24
+ ## Usage
27
25
 
28
- ## Quick Example
26
+ Set `auth` on `@FrontMcp`; its schema comes from this package. Here users sign in at your identity provider, and FrontMCP issues the tokens MCP clients send:
29
27
 
30
28
  ```ts
31
- import { App, FrontMcp } from '@frontmcp/sdk';
29
+ import { FrontMcp } from '@frontmcp/sdk';
30
+
31
+ import { DeskApp } from './desk.app';
32
32
 
33
33
  @FrontMcp({
34
- info: { name: 'Secure Server', version: '1.0.0' },
35
- apps: [MyApp],
34
+ info: { name: 'desk', version: '1.0.0' },
35
+ apps: [DeskApp],
36
36
  auth: {
37
- type: 'remote',
38
- name: 'my-idp',
39
- baseUrl: 'https://idp.example.com',
37
+ mode: 'remote',
38
+ provider: 'https://idp.example.com',
39
+ clientId: 'desk-mcp',
40
+ clientSecret: process.env.IDP_CLIENT_SECRET,
41
+ scopes: ['openid', 'profile', 'email'],
40
42
  },
41
43
  })
42
44
  export default class Server {}
43
45
  ```
44
46
 
45
- > Full guide: [Authentication Overview][docs-overview]
47
+ In production, set `JWT_SECRET`: FrontMCP signs its tokens with it. [Remote and proxied auth](https://frontmcp.dev/reference/auth/remote) lists every option, and the callback URL to register at your provider. `mode` is one of:
48
+
49
+ | `mode` | Who gets in |
50
+ | --------------- | -------------------------------------------------------------- |
51
+ | `'public'` | Everyone. The default. |
52
+ | `'static'` | Requests that send one of your keys. |
53
+ | `'transparent'` | Requests with a valid JWT signed by your identity provider. |
54
+ | `'local'` | Users who sign in on FrontMCP's own page. |
55
+ | `'remote'` | Users who sign in at your identity provider, through FrontMCP. |
56
+
57
+ ### Importing from the package directly
58
+
59
+ In `local` mode, `login.render` replaces the sign-in page. FrontMCP doesn't escape what you print, so pass every value through `escapeHtml`:
60
+
61
+ ```ts
62
+ import { escapeHtml } from '@frontmcp/auth';
63
+ import { FrontMcp } from '@frontmcp/sdk';
64
+
65
+ import { DeskApp } from './desk.app';
66
+
67
+ @FrontMcp({
68
+ info: { name: 'desk', version: '1.0.0' },
69
+ apps: [DeskApp],
70
+ auth: {
71
+ mode: 'local',
72
+ login: {
73
+ fields: { deskKey: { type: 'password', label: 'Desk key', required: true } },
74
+ render: (ctx) => `<!doctype html>
75
+ <html lang="en">
76
+ <body>
77
+ <p>${escapeHtml(ctx.clientName)} wants to connect to your desk.</p>
78
+ ${ctx.error ? `<p role="alert">${escapeHtml(ctx.error)}</p>` : ''}
79
+ <form method="POST" action="${escapeHtml(ctx.callbackPath)}">
80
+ <input type="hidden" name="pending_auth_id" value="${escapeHtml(ctx.pendingAuthId)}">
81
+ <label>Desk key <input type="password" name="deskKey" required></label>
82
+ <button>Sign in</button>
83
+ </form>
84
+ </body>
85
+ </html>`,
86
+ },
87
+ authenticate: async ({ fields }) =>
88
+ fields.deskKey === process.env.DESK_KEY
89
+ ? { ok: true, sub: 'operator' }
90
+ : { ok: false, message: 'Unknown desk key' },
91
+ },
92
+ })
93
+ export default class Server {}
94
+ ```
95
+
96
+ ## What's in it
97
+
98
+ - **Auth modes**: `authOptionsSchema` and the option types of each mode. See [Auth modes](https://frontmcp.dev/reference/auth/modes).
99
+ - **Local mode**: FrontMCP as an OAuth 2.1 authorization server, with PKCE (Proof Key for Code Exchange), dynamic client registration and refresh tokens. See [Local auth](https://frontmcp.dev/reference/auth/local).
100
+ - **Remote mode**: users sign in at your identity provider, and FrontMCP issues the tokens. See [Remote and proxied auth](https://frontmcp.dev/reference/auth/remote).
101
+ - **Upstream providers**: several OAuth providers linked in one sign-in. See [Upstream providers](https://frontmcp.dev/reference/auth/upstream-providers).
102
+ - **Token checks**: JWT verification against a JSON Web Key Set (JWKS), and audience and scope checks (`JwksService`, `validateAudience`). See [Tokens and sessions](https://frontmcp.dev/reference/auth/tokens).
103
+ - **CIMD (Client ID Metadata Documents)**: clients whose `client_id` is the URL of a metadata document (`CimdService`). See [Client ID metadata](https://frontmcp.dev/reference/auth/cimd).
104
+ - **Authorities**: rules on tools, resources, prompts, skills and agents, from roles, permissions, token claims, the call's arguments or your own code (`AuthorityDeniedError`). See [Authorities](https://frontmcp.dev/reference/auth/authorities).
105
+ - **Credential vault**: per-user credentials that tools read with `this.credentials`, and that users can add to mid-session. See [Progressive auth](https://frontmcp.dev/reference/auth/progressive).
106
+ - **Sign-in pages**: the built-in sign-in, consent and error pages, and `escapeHtml`, `buildLoginPage` and `baseLayout` for your own. See [Custom login UI](https://frontmcp.dev/reference/auth/login-ui).
107
+ - **Storage**: memory, Redis, Vercel KV and SQLite stores for sessions, authorization codes and tokens, and encrypted storage for secrets (`EncryptedTypedStorage`, `TokenVault`). See [Local auth storage](https://frontmcp.dev/reference/auth/local#storage).
46
108
 
47
109
  ## Docs
48
110
 
49
- | Topic | Link |
50
- | ----------------- | ---------------------------------------------- |
51
- | Overview | [Authentication Overview][docs-overview] |
52
- | Remote OAuth | [Remote OAuth][docs-remote] |
53
- | Local OAuth | [Local OAuth][docs-local] |
54
- | JWKS | [JWKS Validation][docs-jwks] |
55
- | Session stores | [Session Stores][docs-stores] |
56
- | Credential vault | [Credential Vault][docs-vault] |
57
- | PKCE | [PKCE][docs-pkce] |
58
- | CIMD | [Client Instance Machine Detection][docs-cimd] |
59
- | Auth UI | [Auth UI Templates][docs-ui] |
60
- | Audience & scopes | [Audience Validation][docs-audience] |
61
- | Token vault | [Token Vault][docs-token-vault] |
62
-
63
- ## Related Packages
64
-
65
- - [`@frontmcp/sdk`](../sdk) — core framework (imports auth internally)
66
- - [`@frontmcp/utils`](../utils) — crypto primitives used by PKCE and vault
67
- - [`@frontmcp/ui`](../ui) — consent and login page components
111
+ - [Authentication and authorization](https://frontmcp.dev/reference/auth): an overview, and which page covers which task
112
+ - [Auth in production](https://frontmcp.dev/reference/auth/production): secrets, HTTPS, token checks and several instances
113
+ - [`this.auth`](https://frontmcp.dev/reference/sdk/auth): who is calling, from inside a tool
114
+ - [Authenticating clients](https://frontmcp.dev/learn/authenticating-clients) and [Authorizing calls](https://frontmcp.dev/learn/authorizing-calls): step-by-step guides
115
+ - [Testing authentication](https://frontmcp.dev/reference/testing/auth)
116
+
117
+ ## Related packages
118
+
119
+ - [`@frontmcp/sdk`](https://www.npmjs.com/package/@frontmcp/sdk): the framework. It runs this package and re-exports its option types.
120
+ - [`@frontmcp/utils`](https://www.npmjs.com/package/@frontmcp/utils): the crypto (PKCE, encryption, key derivation) and storage adapters this package builds on.
121
+ - [`@frontmcp/ui`](https://www.npmjs.com/package/@frontmcp/ui): `@frontmcp/ui/auth`, for React sign-in pages set with `auth.ui`.
122
+ - [`@frontmcp/testing`](https://www.npmjs.com/package/@frontmcp/testing): token factories and mock OAuth servers for tests.
123
+
124
+ ## Contributing
125
+
126
+ Source: [`libs/auth`](https://github.com/agentfront/frontmcp/tree/main/libs/auth). Issues and pull requests are welcome; see [CONTRIBUTING.md](https://github.com/agentfront/frontmcp/blob/main/CONTRIBUTING.md).
68
127
 
69
128
  ## License
70
129
 
71
- Apache-2.0 — see [LICENSE](../../LICENSE).
72
-
73
- <!-- links -->
74
-
75
- [docs-overview]: https://frontmcp.dev/reference/auth
76
- [docs-remote]: https://frontmcp.dev/reference/auth/remote
77
- [docs-local]: https://frontmcp.dev/reference/auth/local
78
- [docs-jwks]: https://frontmcp.dev/reference/auth/local
79
- [docs-stores]: https://frontmcp.dev/reference/auth/production
80
- [docs-vault]: https://frontmcp.dev/reference/auth/authorities
81
- [docs-pkce]: https://frontmcp.dev/reference/auth/local
82
- [docs-cimd]: https://frontmcp.dev/reference/auth/cimd
83
- [docs-ui]: https://frontmcp.dev/reference/auth/login-ui
84
- [docs-audience]: https://frontmcp.dev/reference/auth/tokens
85
- [docs-token-vault]: https://frontmcp.dev/reference/auth/authorities
130
+ Apache-2.0. See [LICENSE](https://github.com/agentfront/frontmcp/blob/main/LICENSE).
package/esm/package.json CHANGED
@@ -1,26 +1,31 @@
1
1
  {
2
2
  "name": "@frontmcp/auth",
3
- "version": "1.9.6",
4
- "description": "FrontMCP Auth - Authentication, session management, and credential vault",
3
+ "version": "1.9.7",
4
+ "description": "Authentication and authorization for FrontMCP servers: auth modes, OAuth 2.1 (local and remote), JWT and session checks, authorities and the credential vault",
5
5
  "author": "AgentFront <info@agentfront.dev>",
6
6
  "homepage": "https://frontmcp.dev/reference/auth",
7
7
  "license": "Apache-2.0",
8
8
  "keywords": [
9
+ "frontmcp",
9
10
  "mcp",
11
+ "model-context-protocol",
10
12
  "auth",
11
13
  "authentication",
12
- "session",
14
+ "authorization",
13
15
  "oauth",
16
+ "oauth2",
14
17
  "jwt",
15
18
  "jwks",
19
+ "pkce",
20
+ "cimd",
21
+ "session",
16
22
  "vault",
17
- "credentials",
18
- "agentfront",
19
- "frontmcp"
23
+ "agentfront"
20
24
  ],
21
25
  "repository": {
22
26
  "type": "git",
23
- "url": "git+https://github.com/agentfront/frontmcp.git"
27
+ "url": "git+https://github.com/agentfront/frontmcp.git",
28
+ "directory": "libs/auth"
24
29
  },
25
30
  "bugs": {
26
31
  "url": "https://github.com/agentfront/frontmcp/issues"
@@ -47,8 +52,8 @@
47
52
  "node": ">=24.0.0"
48
53
  },
49
54
  "peerDependencies": {
50
- "@frontmcp/lazy-zod": "1.9.6",
51
- "@frontmcp/storage-sqlite": "1.9.6",
55
+ "@frontmcp/lazy-zod": "1.9.7",
56
+ "@frontmcp/storage-sqlite": "1.9.7",
52
57
  "@vercel/kv": "^3.0.0",
53
58
  "ioredis": "^5.0.0"
54
59
  },
@@ -64,8 +69,8 @@
64
69
  }
65
70
  },
66
71
  "dependencies": {
67
- "@frontmcp/di": "1.9.6",
68
- "@frontmcp/utils": "1.9.6",
72
+ "@frontmcp/di": "1.9.7",
73
+ "@frontmcp/utils": "1.9.7",
69
74
  "jose": "^6.0.0"
70
75
  },
71
76
  "devDependencies": {
package/package.json CHANGED
@@ -1,26 +1,31 @@
1
1
  {
2
2
  "name": "@frontmcp/auth",
3
- "version": "1.9.6",
4
- "description": "FrontMCP Auth - Authentication, session management, and credential vault",
3
+ "version": "1.9.7",
4
+ "description": "Authentication and authorization for FrontMCP servers: auth modes, OAuth 2.1 (local and remote), JWT and session checks, authorities and the credential vault",
5
5
  "author": "AgentFront <info@agentfront.dev>",
6
6
  "homepage": "https://frontmcp.dev/reference/auth",
7
7
  "license": "Apache-2.0",
8
8
  "keywords": [
9
+ "frontmcp",
9
10
  "mcp",
11
+ "model-context-protocol",
10
12
  "auth",
11
13
  "authentication",
12
- "session",
14
+ "authorization",
13
15
  "oauth",
16
+ "oauth2",
14
17
  "jwt",
15
18
  "jwks",
19
+ "pkce",
20
+ "cimd",
21
+ "session",
16
22
  "vault",
17
- "credentials",
18
- "agentfront",
19
- "frontmcp"
23
+ "agentfront"
20
24
  ],
21
25
  "repository": {
22
26
  "type": "git",
23
- "url": "git+https://github.com/agentfront/frontmcp.git"
27
+ "url": "git+https://github.com/agentfront/frontmcp.git",
28
+ "directory": "libs/auth"
24
29
  },
25
30
  "bugs": {
26
31
  "url": "https://github.com/agentfront/frontmcp/issues"
@@ -47,8 +52,8 @@
47
52
  "node": ">=24.0.0"
48
53
  },
49
54
  "peerDependencies": {
50
- "@frontmcp/lazy-zod": "1.9.6",
51
- "@frontmcp/storage-sqlite": "1.9.6",
55
+ "@frontmcp/lazy-zod": "1.9.7",
56
+ "@frontmcp/storage-sqlite": "1.9.7",
52
57
  "@vercel/kv": "^3.0.0",
53
58
  "ioredis": "^5.0.0"
54
59
  },
@@ -64,8 +69,8 @@
64
69
  }
65
70
  },
66
71
  "dependencies": {
67
- "@frontmcp/di": "1.9.6",
68
- "@frontmcp/utils": "1.9.6",
72
+ "@frontmcp/di": "1.9.7",
73
+ "@frontmcp/utils": "1.9.7",
69
74
  "jose": "^6.0.0"
70
75
  },
71
76
  "devDependencies": {