@frontmcp/skills 1.3.0 → 1.4.0

package/catalog/frontmcp-auth-ui/references/custom-auth-ui.md

@@ -0,0 +1,162 @@
+---
+name: custom-auth-ui
+description: Replace FrontMCP's built-in OAuth pages with custom React components using the auth.ui slot→file map and auth.extras name→handler map (no decorator, no class) plus the @frontmcp/ui/auth hooks.
+---
+
+# Custom Authorization UI (`auth.ui` / `auth.extras`)
+
+FrontMCP's `local` and `remote` OAuth modes serve built-in HTML for the login, consent, incremental, federated, and error steps. The `auth.ui` **slot→file map** replaces any of those slots with **your own React component** while the framework keeps owning everything security-sensitive — CSRF, the Content-Security-Policy, anti-clickjacking headers, the pending-authorization state, the submit target, and the OAuth redirect. **You write only the UI.**
+
+There is **no decorator and no class** — a slot is just a `.tsx` path, and an extra is just a handler function. If no `auth.ui` slot is configured, the built-in pages are served unchanged — the feature is purely additive and opt-in per slot.
+
+## Two halves
+
+| Half       | Package                                     | Responsibility                                                                                                                                                                                                                                                                   |
+| ---------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Server** | `@frontmcp/sdk` (`auth.ui` / `auth.extras`) | Transpiles your component's `.tsx` once (server-side, single-file transform — deps stay external), inlines it as an ES module + an import-map, injects the flow state, mints/verifies CSRF, sets CSP. It never bundles or renders your component server-side.                    |
+| **Client** | `@frontmcp/ui/auth`                         | The framework-free contract (`AuthFlowState`, wire constants) **plus** hooks (`useAuthFlow`, …), `<AuthPageWrapper>`, and `mountAuthPage` that read the state, render the component in the browser, and drive submits. Loaded in the browser **from esm.sh** via the import-map. |
+
+At request time the server serializes an `AuthFlowState` into `window.__FRONTMCP_AUTH__`, serves a page with an **empty** `#frontmcp-auth-root` mount node, an **`<script type="importmap">`** mapping `react` / `react-dom` / `@frontmcp/ui/auth` to **esm.sh** (the `@frontmcp/ui/auth` entry gets `?external=react,react-dom` for a single React), and an inline **`<script type="module">`** with your transpiled component + a `mountAuthPage(<YourComponent>)` tail. The browser loads the deps from esm.sh, runs the module, and `mountAuthPage` renders your component **client-side** into the empty node — there is **no bundling and no server-side React**, exactly how a `@Tool({ ui: { file } })` widget loads. `@frontmcp/ui` is browser-only — the SDK passes `@frontmcp/ui/auth` to the renderer only as an import-map specifier string and never imports it. Your component reads the state via the hooks and submits back to the OAuth callback.
+
+## Server: `auth.ui` — a slot→file map
+
+Map each slot to a sibling `.tsx`/`.jsx` source (default export); the SDK transpiles it once with esbuild and inlines it as an ES module (deps loaded from esm.sh via an import-map; `mountAuthPage` appended for you), exactly like a `@Tool({ ui: { file } })` widget. The path is **relative and auto-anchored to the config file's directory** — no `fileURLToPath`:
+
+```ts
+import { App } from '@frontmcp/sdk'; // or @FrontMcp
+
+@App({
+  auth: {
+    mode: 'local',
+    // slot → RELATIVE .tsx, auto-anchored to THIS config file's directory.
+    ui: { login: './auth/login.tsx' },
+  },
+})
+export default class Server {}
+```
+
+Absolute paths pass through unchanged. If the declaring file's directory can't be captured (exotic loader), the framework falls back to `process.cwd()` with a warning — use an absolute path if that's wrong.
+
+### Slots
+
+| Slot          | Replaces the built-in…                      | Key fields the component receives         |
+| ------------- | ------------------------------------------- | ----------------------------------------- |
+| `login`       | Local sign-in page                          | `clientName`, `scopes`, `redirectUri`     |
+| `consent`     | Tool-consent screen                         | `tools[]` (selectable tool cards)         |
+| `incremental` | Single-app incremental authorization screen | `extras.appId` / `extras.appName`         |
+| `federated`   | Multi-provider selection                    | `providers[]` (selectable provider cards) |
+| `error`       | OAuth error page                            | `error` text                              |
+
+Map only the slots you want to customize — the rest keep their built-in pages.
+
+### Per-app scoping (`splitByApp`)
+
+`auth.ui` / `auth.extras` are **scoped to the auth config they live on** (like `consent`). Under `splitByApp`, each `@App({ auth: { mode, ui, extras } })` gets its OWN custom auth UI (paths anchored to that `@App` file); the parent multi-app scope uses the top-level `@FrontMcp({ auth })` (paths anchored to the server file).
+
+## Server: `auth.extras` — validated extra fields
+
+An `auth.extras[name]` entry is a **server handler function** that adds a server-validated side endpoint your page can POST to **mid-flow**, without finishing the authorization. Each accepted submission is appended to a per-`(pending-auth, extra)` accumulator the framework keeps; the response carries the full accumulator map back so the page refreshes without a reload.
+
+```ts
+import { type AuthExtraContext } from '@frontmcp/sdk';
+
+export async function addEnv(input: Record<string, unknown>, ctx: AuthExtraContext) {
+  const key = typeof input['key'] === 'string' ? input['key'].trim() : '';
+  if (!key) return { ok: false as const, error: 'key is required' };
+  if (ctx.current.some((it) => (it as { key?: string }).key === key)) {
+    return { ok: false as const, error: `"${key}" was already added` };
+  }
+  const value = typeof input['value'] === 'string' ? input['value'] : '';
+  // `addedItems` here is the list of NEW items to APPEND on success.
+  return { ok: true as const, addedItems: [{ key, value }] };
+}
+```
+
+The handler returns `{ ok, error?, addedItems?, sideEffects? }` (sync or async). The `ctx` is minimal and PII-free: `{ name, pendingAuthId?, current }` (`current` is what's already accepted for this extra). Declare it under `auth`: `@FrontMcp({ auth: { mode: 'local', extras: { 'envs:add': addEnv } } })`.
+
+## The `AuthFlowState` a component receives
+
+| Field           | Type                      | Notes                                                                    |
+| --------------- | ------------------------- | ------------------------------------------------------------------------ |
+| `slot`          | `AuthSlot`                | Which page slot is rendering.                                            |
+| `pendingAuthId` | `string?`                 | Correlation id; round-tripped on every submit. Absent only for `error`.  |
+| `clientName`    | `string?`                 | OAuth client display name (**not** an end user).                         |
+| `clientId`      | `string?`                 | OAuth `client_id`.                                                       |
+| `scopes`        | `string[]`                | Requested OAuth scopes.                                                  |
+| `redirectUri`   | `string?`                 | Validated `redirect_uri` the code is sent to.                            |
+| `resource`      | `string?`                 | RFC 8707 resource indicator, when supplied.                              |
+| `error`         | `string?`                 | Error text (error slot, or a re-rendered failed submit).                 |
+| `csrfToken`     | `string?`                 | Server-minted anti-CSRF token. The hooks echo it for you.                |
+| `providers`     | `AuthProvider[]`          | Selectable providers on the `federated` slot.                            |
+| `tools`         | `AuthTool[]`              | Selectable tools on the `consent` slot.                                  |
+| `extras`        | `Record<string, unknown>` | Free-form, slot-specific extras (e.g. logo URI, incremental target app). |
+
+**No PII is in the contract.** Anything the user types (email, name, …) travels in your own form fields, never in `AuthFlowState`.
+
+## Client: `@frontmcp/ui/auth`
+
+```bash
+npm install @frontmcp/ui react react-dom
+```
+
+`react` / `react-dom` are peer dependencies of `@frontmcp/ui`.
+
+| Import                      | Use                                                                                                                                                                                                                                 |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@frontmcp/ui/auth`         | The framework-free contract types + wire constants (no React) **and** React hooks (`useAuthFlow`, …) + `<AuthPageWrapper>` + `mountAuthPage`. Single source of truth for the client API; imports only `react`/`react-dom` — no MUI. |
+| `@frontmcp/ui/auth/vanilla` | Framework-free (browser) helpers: `getAuthFlow`, `submitFinish`, `submitExtra`, `getAddedItems` (plus the contract types).                                                                                                          |
+
+### React hooks + wrapper + client mount
+
+- **`useAuthFlow()`** — the flow-state fields above plus a `submitFinish` handler. `<form onSubmit={submitFinish}>` `preventDefault`s, serializes the form, attaches `pending_auth_id` + `csrf` + the slot marker, posts to the callback, and follows the OAuth redirect.
+- **`useExtraField(name)`** — `{ onSubmit, result, pending }` for an `auth.extras` form. On success it merges the returned `addedItems` back into context.
+- **`useAddedItems(name)`** — the server-side accumulator for a named extra, reactively.
+- **`<AuthPageWrapper>`** — outer chrome that reads the injected state once, provides it via context, and (by default) renders the enclosing `<form>` with the `pending_auth_id` + `csrf` hidden fields so a no-JS submit still works. Pass `renderForm={false}` to supply your own forms.
+- **`mountAuthPage(Component, options?)`** — the client entrypoint; wraps `Component` in `<AuthPageWrapper>` and renders it (`createRoot(...).render(...)`) into the empty `#frontmcp-auth-root` node in the browser. Pure client render — no server markup to hydrate. **The SDK appends `mountAuthPage(<your default export>)` to the inlined module for you**, so a `file`-based component just needs a default export (loaded in the browser from esm.sh via the import-map).
+
+### Vanilla (no framework)
+
+`@frontmcp/ui/auth/vanilla` exposes the same flow without React: `getAuthFlow()` (read `window.__FRONTMCP_AUTH__`; `tryGetAuthFlow()` is tolerant), `getAddedItems(name)`, `submitFinish(formOrData?)`, and `submitExtra(name, formOrData?)`.
+
+## Routes the server adds
+
+When at least one `auth.extras` handler is configured (otherwise it 404s / falls through, so defaults are untouched):
+
+| Route             | Method | Purpose                                                                                                                                                                             |
+| ----------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/oauth/ui/extra` | `POST` | Routes an `auth.extras[name]` submission (the `action` field names the extra) to its handler; returns `{ ok, error?, addedItems?, sideEffects? }`. CSRF-verified (400 on mismatch). |
+
+There is **no `/oauth/ui/:slot.js` route** — the component is transpiled server-side and **inlined** into the authorize/callback page as a `<script type="module">` (deps from esm.sh via the import-map), so there is no separately-served bundle. The pages themselves are served by the existing `/oauth/authorize` + `/oauth/callback` flows; an `auth.ui` slot swaps the served page body (import-map + injected state + the inline transpiled module + empty mount) — the component renders client-side. The finish submit still posts to `/oauth/callback`.
+
+## Security — the framework owns it
+
+- **CSRF**: the server mints a per-pending-authorization token, stores it (echoed into `csrfToken`), and verifies it on the finish submit and every `auth.extras` POST with a constant-time compare. Your component never generates or checks it.
+- **CSP + anti-clickjacking**: the auth-UI HTML ships with a strict CSP — `default-src 'self'; script-src 'self' 'unsafe-inline' https://esm.sh; connect-src 'self' https://esm.sh; style-src 'self' 'unsafe-inline' https://esm.sh; img-src 'self' data: https:; frame-ancestors 'none'; base-uri 'self'; form-action 'self'` — plus `X-Frame-Options: DENY`, `X-Content-Type-Options: nosniff`, `Referrer-Policy: no-referrer`. It allows `https://esm.sh` (deps) + `'unsafe-inline'` (the JSON-escaped state script) but **NOT `'unsafe-eval'`** — the transform is server-side, never in the browser.
+- **No PII**: the injected state carries OAuth client identifiers + control fields only.
+- **Fail-safe**: a component that can't be transpiled (missing / invalid `.tsx`) is logged (error cached so a broken file isn't retried each request) and **falls back to the built-in page** — a broken custom page can't take the server down.
+
+## Local dev / offline (esm.sh caveat)
+
+The browser loads `react`, `react-dom`, and `@frontmcp/ui/auth` from **esm.sh**. `react`/`react-dom` are always there, but `@frontmcp/ui/auth` resolves only once **published to npm**. In an unpublished monorepo, an in-browser render can't fetch it — though the SERVER still emits the full page (import-map + injected state + inline transpiled module), so HTTP-level checks pass; only the browser DOM render is affected. To render before publishing, map the specifier to a locally-served ESM URL via `@FrontMcp({ ui: { cdnOverrides } })`:
+
+```ts
+@FrontMcp({
+  ui: { cdnOverrides: { '@frontmcp/ui/auth': 'http://localhost:5173/ui-auth.mjs' } },
+  auth: { mode: 'local', ui: { login: './auth/login.tsx' } },
+})
+```
+
+A non-esm.sh override URL is left as-is (no `?external=react`). Once published, no overrides are needed.
+
+## Examples
+
+| Example                                                                        | Level        | Description                                                                                                                                                                                                     |
+| ------------------------------------------------------------------------------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`login-slot`](../examples/custom-auth-ui/login-slot.md)                       | Intermediate | Replace the built-in login page with a custom React component via auth.ui: { login: './login.tsx' } and useAuthFlow, while the framework keeps owning CSRF and CSP.                                             |
+| [`multi-step-auth-extra`](../examples/custom-auth-ui/multi-step-auth-extra.md) | Advanced     | Add a server-validated multi-step field to a custom login page with auth.extras: { 'envs:add': fn }, useExtraField, and useAddedItems — accepted rows accumulate server-side and reflect back without a reload. |
+
+## See also
+
+- Docs: [Custom Authorization UI (`auth.ui`)](https://docs.agentfront.dev/frontmcp/authentication/custom-ui)
+- `frontmcp-config` → `configure-auth` — the declarative `login` / `authenticate` config (tweak the built-in page's fields without React)
+- `create-tool` → `ui-widgets` — the `@Tool({ ui: { file } })` widget pipeline this mirrors

package/catalog/frontmcp-authorities/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontmcp-authorities
-description: 'Use when implementing authorization, access control, RBAC, ABAC, or ReBAC for tools, resources, or prompts. Covers JWT claims mapping, authority profiles, and policy enforcement.'
+description: 'Use when implementing authorization and access control for FrontMCP tools, resources, prompts, or skills, deciding who may invoke what. Covers the RBAC, ABAC, and ReBAC models and when to choose each; JWT claims mapping per identity provider (Auth0, Keycloak, Okta, Cognito, Frontegg); reusable named authority profiles; and custom authority evaluators for domain-specific policy. This is about who-can-do-what (permissions, roles, scopes), distinct from configuring auth modes and login (see frontmcp-config) and custom login UI (see frontmcp-auth-ui). Triggers: authorization, access control, RBAC, ABAC, ReBAC, permissions, roles, scopes, policy enforcement, JWT claims, restrict who can call a tool.'
 tags: [authorization, rbac, abac, rebac, security, permissions, roles, access-control, authorities, jwt]
 category: development
 targets: [all]
@@ -20,9 +20,10 @@ Built-in RBAC/ABAC/ReBAC authorization system for FrontMCP entry types. Each flo
 
 ### Must Use
 
-- Adding role-based or permission-based access control to tools, resources, or prompts
+- Adding role-based or permission-based access control to tools, resources, prompts, or skills
 - Restricting MCP entry visibility based on the caller's JWT claims
 - Enforcing tenant isolation (ABAC) or relationship checks (ReBAC) on entries
+- Gating which skills a caller can discover and load (`@Skill({ authorities })`)
 
 ### Recommended
 
@@ -73,7 +74,7 @@ Add the `authorities` field to your `@FrontMcp` decorator. No plugin import need
 import { FrontMcp } from '@frontmcp/sdk';
 
 @FrontMcp({
-  name: 'my-server',
+  info: { name: 'my-server', version: '1.0.0' },
   authorities: {
     // configured in next steps
   },
@@ -284,23 +285,59 @@ authorities: {
 }
 ```
 
+### Skill Authorities (`@Skill({ authorities })`)
+
+`authorities` on `@Skill` is enforced exactly like the other entry types, across
+**every** surface a skill is served from:
+
+- **Deny on load/read** — loading a gated skill the caller can't access throws
+  `AuthorityDeniedError` (MCP code `-32003`), the same as a denied `tools/call`.
+  Covers `skills/load` (MCP), `skill://<path>/SKILL.md` and `skill://<path>/<file>`
+  reads (SEP-2640), and `GET /skills/{id}` (HTTP).
+- **Filter on discovery** — gated skills the caller can't access are removed from
+  `skills/search` / `skills/list` (MCP), the `skill://index.json` discovery index and
+  skill-path autocomplete (SEP-2640), and `GET /skills` (HTTP).
+
+```typescript
+@Skill({ name: 'review-pr', description: '…', instructions: '…' })            // open to all
+@Skill({ name: 'internal-runbook', description: '…', instructions: '…',
+         authorities: 'admin' })                                              // admins only
+```
+
+Two limitations to design around:
+
+- **List-time filtering is role/permission/claims-only.** Discovery runs without
+  request input, so `{ fromInput: '…' }` ABAC/ReBAC policies can't be evaluated when
+  filtering and will hide the skill from discovery. Use role/permission/claims
+  authorities for discoverable skills; input-dependent policies still enforce at
+  load time. (Same limitation applies to tools/resources/prompts.)
+- **HTTP skills discovery is fail-closed.** The Skills HTTP API uses a binary
+  api-key/bearer gate with no claims, so gated skills are hidden from `GET /skills`
+  and denied on `GET /skills/{id}` regardless of the bearer. Serve gated skills over
+  an MCP transport for claims-based access. Ungated skills are unaffected.
+
+Boot-time fail-fast covers skills too: a `@Skill` with `authorities` but no configured
+authorities engine fails server startup with `AuthConfigurationError`, exactly like a
+tool/resource/prompt/agent.
+
 ## Scenario Routing Table
 
-| Scenario                              | Approach                                                         | Reference                          |
-| ------------------------------------- | ---------------------------------------------------------------- | ---------------------------------- |
-| Simple role gate (admin-only tool)    | `authorities: 'admin'` profile                                   | `references/authority-profiles.md` |
-| Permission-based access               | `authorities: { permissions: { all: ['x'] } }`                   | `references/rbac-abac-rebac.md`    |
-| Tenant isolation                      | ABAC with `{ fromInput: 'tenantId' }`                            | `references/rbac-abac-rebac.md`    |
-| Resource ownership check              | ReBAC with relationship resolver                                 | `references/rbac-abac-rebac.md`    |
-| IP allowlist or custom logic          | Custom evaluator via `custom.*`                                  | `references/custom-evaluators.md`  |
-| Different IdP (Auth0/Keycloak/Okta)   | Configure `claimsMapping`                                        | `references/claims-mapping.md`     |
-| Admin OR (editor AND same-tenant)     | `anyOf` / `allOf` combinators                                    | `references/authority-profiles.md` |
-| Custom pre/post authority logic       | Hook with `Will`/`Did`/`Around` on `checkEntryAuthorities` stage | `references/custom-evaluators.md`  |
-| Replace built-in check with OPA/Cedar | `Around('checkEntryAuthorities')` hook                           | `references/custom-evaluators.md`  |
-| Audit authority decisions             | `Did('checkEntryAuthorities')` hook for logging/metrics          | `references/custom-evaluators.md`  |
-| Tenant allowlist in Redis/DB          | Async custom evaluator with `custom.*` field                     | `references/custom-evaluators.md`  |
-| Subscription check before tool runs   | Async custom evaluator or `Will('checkEntryAuthorities')` hook   | `references/custom-evaluators.md`  |
-| Feature flag gate on a tool           | Async custom evaluator checking flag service                     | `references/custom-evaluators.md`  |
+| Scenario                              | Approach                                                          | Reference                          |
+| ------------------------------------- | ----------------------------------------------------------------- | ---------------------------------- |
+| Simple role gate (admin-only tool)    | `authorities: 'admin'` profile                                    | `references/authority-profiles.md` |
+| Gate skill discovery + load           | `@Skill({ authorities: 'admin' })` (role/permission/claims-based) | `references/authority-profiles.md` |
+| Permission-based access               | `authorities: { permissions: { all: ['x'] } }`                    | `references/rbac-abac-rebac.md`    |
+| Tenant isolation                      | ABAC with `{ fromInput: 'tenantId' }`                             | `references/rbac-abac-rebac.md`    |
+| Resource ownership check              | ReBAC with relationship resolver                                  | `references/rbac-abac-rebac.md`    |
+| IP allowlist or custom logic          | Custom evaluator via `custom.*`                                   | `references/custom-evaluators.md`  |
+| Different IdP (Auth0/Keycloak/Okta)   | Configure `claimsMapping`                                         | `references/claims-mapping.md`     |
+| Admin OR (editor AND same-tenant)     | `anyOf` / `allOf` combinators                                     | `references/authority-profiles.md` |
+| Custom pre/post authority logic       | Hook with `Will`/`Did`/`Around` on `checkEntryAuthorities` stage  | `references/custom-evaluators.md`  |
+| Replace built-in check with OPA/Cedar | `Around('checkEntryAuthorities')` hook                            | `references/custom-evaluators.md`  |
+| Audit authority decisions             | `Did('checkEntryAuthorities')` hook for logging/metrics           | `references/custom-evaluators.md`  |
+| Tenant allowlist in Redis/DB          | Async custom evaluator with `custom.*` field                      | `references/custom-evaluators.md`  |
+| Subscription check before tool runs   | Async custom evaluator or `Will('checkEntryAuthorities')` hook    | `references/custom-evaluators.md`  |
+| Feature flag gate on a tool           | Async custom evaluator checking flag service                      | `references/custom-evaluators.md`  |
 
 ## Common Patterns
 

package/catalog/frontmcp-authorities/references/authority-profiles.md

@@ -15,7 +15,7 @@ Profiles are registered in the `profiles` field of the `authorities` config. Eac
 import { FrontMcp } from '@frontmcp/sdk';
 
 @FrontMcp({
-  name: 'my-server',
+  info: { name: 'my-server', version: '1.0.0' },
   authorities: {
     claimsMapping: {
       roles: 'realm_access.roles',
@@ -95,6 +95,15 @@ export default class AdminReportPrompt extends PromptContext {
     // only admin can use this prompt
   }
 }
+
+// Skills are gated the same way. Non-admins can neither discover nor load this:
+@Skill({
+  name: 'internal-runbook',
+  description: 'Restricted operational runbook',
+  instructions: { file: './internal-runbook.md' },
+  authorities: 'admin',
+})
+export class InternalRunbookSkill {}
 ```
 
 ### Multiple Profiles (String Array)
@@ -244,9 +253,24 @@ The authorities system does not only enforce on execution. The built-in `filterB
 - `tools/list` only returns tools the current user is authorized to call
 - `resources/list` only returns resources the current user can read
 - `prompts/list` only returns prompts the current user can get
+- Skills are filtered on every discovery surface: `skills/search` / `skills/list`, the SEP-2640 `skill://index.json` index + skill-path autocomplete, and `GET /skills`. Loading a gated skill the caller can't access (via `skills/load`, a `skill://…` read, or `GET /skills/{id}`) is denied with `AuthorityDeniedError` (`-32003`).
 
 This filtering happens automatically. No additional configuration is needed. Entries without an `authorities` field are always visible.
 
+**List-time evaluation has no request input.** Because discovery runs before any
+arguments exist, input-dependent policies — ABAC conditions using `{ fromInput: '…' }`
+or ReBAC `resourceId: { fromInput: '…' }` — cannot be evaluated when filtering and
+will exclude the entry from the list (it is still enforced correctly at execution/load
+time, where input is available). For entries (especially **skills**) that must remain
+discoverable, gate them with role/permission/claims-based authorities such as
+`authorities: 'admin'` or `{ roles: { any: ['admin'] } }`.
+
+**HTTP skills discovery is fail-closed.** The Skills HTTP API authenticates with a
+binary api-key/bearer gate that surfaces no JWT claims, so authority-gated skills are
+hidden from `GET /skills` and denied on `GET /skills/{id}` regardless of the bearer.
+Serve gated skills over an MCP transport (full claims context) for claims-based access;
+skills without `authorities` are served over HTTP unchanged.
+
 ## Profile Design Guidelines
 
 | Guideline                                                       | Example                                                                               |

package/catalog/frontmcp-authorities/references/custom-evaluators.md

@@ -66,7 +66,7 @@ import { ipAllowListEvaluator } from './evaluators/ip-allow-list';
 import { timeWindowEvaluator } from './evaluators/time-window';
 
 @FrontMcp({
-  name: 'my-server',
+  info: { name: 'my-server', version: '1.0.0' },
   authorities: {
     claimsMapping: { roles: 'roles', permissions: 'permissions' },
     profiles: { admin: { roles: { any: ['admin'] } } },

package/catalog/frontmcp-authorities/references/rbac-abac-rebac.md

@@ -173,6 +173,15 @@ Instead of hardcoding values, reference runtime data from tool input or JWT clai
 { path: 'claims.department', op: 'eq', value: { fromClaims: 'manager.department' } }
 ```
 
+> **`fromInput` is for tools and agents only.** Only **tools** and **agents**
+> pass request input into the authorities evaluation. `@Resource` and `@Prompt`
+> do not receive tool-style input, so a `fromInput` reference (in an ABAC
+> condition or a ReBAC `resourceId`) has nothing to resolve against on those
+> entries — gate resources and prompts with role / permission / `fromClaims`
+> policies instead. (Separately, list-time discovery filtering runs without any
+> input at all, so `fromInput` policies are also excluded from list results for
+> everyone — reserve them for call-time enforcement.)
+
 ### ABAC Examples
 
 **Tenant isolation:**

package/catalog/frontmcp-channels/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: frontmcp-channels
-description: 'Use when you want to push real-time notifications into Claude Code sessions. Build webhook channels, chat bridges (WhatsApp, Telegram, Slack), agent completion alerts, job status notifications, or error forwarding. The skill for CHANNELS and NOTIFICATIONS.'
+description: 'Use when pushing real-time notifications or events into Claude Code (or another MCP client) sessions, or building two-way chat bridges. Covers channel source types: incoming webhooks (such as GitHub), app error events, agent-completion and job-completion alerts, service connectors, file watchers, and replay buffers; plus two-way conversational bridges connecting WhatsApp, Telegram, Slack, and Discord to a Claude Code session. Triggers: push notifications, real-time alerts, webhook channel, chat bridge, WhatsApp / Telegram / Slack / Discord, agent completion alert, job status notification, error forwarding, server-to-client messaging. The skill for CHANNELS and NOTIFICATIONS.'
+when_to_use: |
+  Trigger when creating or editing a *.channel.ts file, or building a channel
+  that pushes real-time notifications into a Claude Code session: webhook
+  sources, app / agent / job event alerts, service connectors, file watchers,
+  or a two-way chat bridge (WhatsApp, Telegram, Slack, Discord).
+paths: '**/*.channel.ts'
 tags: [channels, notifications, claude-code, webhooks, messaging, real-time, two-way]
 category: development
 targets: [all]

package/catalog/frontmcp-config/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: frontmcp-config
-description: 'Use when you want to configure auth, set up CORS, add rate limiting, throttle requests, manage sessions, choose transport, set HTTP options, add authentication, configure JWT, or set up OAuth. The skill for server CONFIGURATION.'
+description: 'Use when configuring a FrontMCP server through frontmcp.config or the @FrontMcp options. Covers auth modes (public, transparent, local, remote), OAuth plus credential vault and secureStore, CORS, HTTP port / entry-path prefix / unix socket, security headers (CSP, HSTS, X-Frame-Options, X-Content-Type-Options), rate limiting / throttling / concurrency / timeout / IP filtering (GuardConfig), session storage (Redis, Vercel KV), client transport protocols (SSE, Streamable HTTP, stateless, protocol presets), elicitation, multi-target build config, and skillsConfig (HTTP catalog, caching, audit log, instruction injection). Triggers: configure auth, set up CORS, add rate limiting, throttle requests, manage sessions, choose transport, set HTTP options, configure JWT or OAuth. The skill for server CONFIGURATION.'
+when_to_use: |
+  Trigger when creating or editing frontmcp.config.ts/js or the @FrontMcp({...})
+  options: configuring auth modes, OAuth + credential vault, CORS, HTTP port /
+  entry path / unix socket, security headers, rate limiting / throttling /
+  GuardConfig, session storage (Redis, Vercel KV), client transport / protocol
+  presets, elicitation, multi-target builds, or skillsConfig.
+paths: '**/frontmcp.config.*'
 tags: [router, config, transport, http, auth, session, redis, sqlite, throttle, guide]
 category: config
 targets: [all]
@@ -162,7 +169,7 @@ Each reference has matching examples under [`examples/<reference>/`](./examples/
 | Example                                                                                       | Level        | Description                                                                                 |
 | --------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------- |
 | [`local-self-signed-tokens`](./examples/configure-auth-modes/local-self-signed-tokens.md)     | Intermediate | Configure a server that signs its own JWT tokens with consent and incremental auth enabled. |
-| [`remote-enterprise-oauth`](./examples/configure-auth-modes/remote-enterprise-oauth.md)       | Advanced     | Delegate authentication to an external OAuth orchestrator with Redis-backed token storage.  |
+| [`remote-enterprise-oauth`](./examples/configure-auth-modes/remote-enterprise-oauth.md)       | Advanced     | Proxy auth to one mandatory upstream IdP, mint a FrontMCP session, read the upstream token. |
 | [`transparent-jwt-validation`](./examples/configure-auth-modes/transparent-jwt-validation.md) | Basic        | Validate externally-issued JWTs without managing token lifecycle on the server.             |
 
 ### `configure-auth`

package/catalog/frontmcp-config/examples/configure-auth/local-credential-vault.md

@@ -0,0 +1,94 @@
+---
+name: local-credential-vault
+reference: configure-auth
+level: intermediate
+description: 'Persist a per-session credential from a local authenticate() verifier into the built-in encrypted vault and read it from a tool via this.credentials.'
+tags: [config, auth, local, vault, credentials, this-credentials]
+features:
+  - 'Returning `credentials: [{ key, secret, metadata? }]` from `authenticate()` so FrontMCP persists them encrypted, keyed by the minted `sub`'
+  - 'Reading a per-session credential from a tool via `this.credentials.get(key)` (no `this.authProviders` wiring needed)'
+  - 'Prompting the agent to connect a missing credential mid-session with `this.credentials.requireConnect({ key })` (framework-signed `/oauth/connect` URL)'
+  - 'Understanding per-session rotation: a reconnect yields an empty vault and old ciphertext is undecryptable'
+---
+
+# Local Mode with the Per-Session Credential Vault (`this.credentials`)
+
+Persist a per-session credential from a local authenticate() verifier into the built-in encrypted vault and read it from a tool via this.credentials.
+
+The vault is AES-256-GCM-encrypted, keyed by the authenticated `sub`, and enabled
+automatically in `local` (and `remote`) modes — there is nothing to register.
+
+## Code
+
+```typescript
+// src/server.ts
+import { App, FrontMcp, Tool, ToolContext, z } from '@frontmcp/sdk';
+
+@Tool({
+  name: 'call_acme',
+  description: 'Call the Acme API using the session credential',
+  inputSchema: {},
+  outputSchema: { connected: z.boolean(), connectUrl: z.string().optional() },
+})
+class CallAcmeTool extends ToolContext {
+  async execute() {
+    // Read the credential the verifier persisted at login.
+    const cred = await this.credentials.get('acme'); // { secret, metadata } | undefined
+    if (!cred) {
+      // Not connected — hand the agent a framework-signed resume URL so the
+      // user can connect it mid-session (verified server-side, short-lived).
+      const res = await this.credentials.requireConnect({ key: 'acme' });
+      if (!res.connected) return { connected: false, connectUrl: res.resumeUrl };
+    }
+    // const headers = { Authorization: `Bearer ${cred!.secret}` };
+    // … call Acme with cred.secret / cred.metadata …
+    return { connected: true };
+  }
+}
+
+@App({ name: 'acme-tools', tools: [CallAcmeTool] })
+class AcmeApp {}
+
+@FrontMcp({
+  info: { name: 'acme-server', version: '1.0.0' },
+  apps: [AcmeApp],
+  auth: {
+    mode: 'local',
+    login: {
+      title: 'Connect Acme',
+      fields: { apiKey: { type: 'password', label: 'Acme API Key', required: true } },
+      subject: { fromField: 'apiKey', strategy: 'per-account' },
+    },
+    authenticate: async (input) => {
+      // Mid-session connect re-invokes authenticate() with a `resume` context.
+      if (input.resume) {
+        const value = input.fields['apiKey'];
+        if (!value) return { ok: false, message: 'A value is required', retryField: 'apiKey' };
+        return { ok: true, credentials: [{ key: input.resume.key, secret: value }] };
+      }
+      // Initial login: validate and persist the credential into the vault.
+      const apiKey = input.fields['apiKey'];
+      if (!apiKey?.startsWith('sk-')) return { ok: false, message: 'Invalid API key', retryField: 'apiKey' };
+      return {
+        ok: true,
+        credentials: [{ key: 'acme', secret: apiKey, metadata: { baseUrl: 'https://acme.example' } }],
+      };
+    },
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Returning `credentials: [{ key, secret, metadata? }]` from `authenticate()` so FrontMCP persists them encrypted, keyed by the minted `sub`
+- Reading a per-session credential from a tool via `this.credentials.get(key)` (no `this.authProviders` wiring needed)
+- Prompting the agent to connect a missing credential mid-session with `this.credentials.requireConnect({ key })` (framework-signed `/oauth/connect` URL)
+- Understanding per-session rotation: a reconnect yields an empty vault and old ciphertext is undecryptable
+
+## Related
+
+- See `configure-auth` for the full `this.credentials` API and the
+  `authenticate()` verifier contract.
+- See `remote-oauth-with-vault` for the separate `this.authProviders` downstream
+  OAuth-provider vault.

package/catalog/frontmcp-config/examples/configure-auth/local-secure-store.md

@@ -0,0 +1,138 @@
+---
+name: local-secure-store
+reference: configure-auth
+level: intermediate
+description: 'Configure the general session secure-secret store (this.secureStore) with a pluggable backing (memory / sqlite / redis / custom OS-keychain) and read/write user-typed secrets from a tool.'
+tags: [config, auth, local, secure-store, secrets, this-secure-store, keychain]
+features:
+  - 'Selecting the secure-store backing via `auth.secureStore` (memory / sqlite / redis / custom backend) plus a namespace `scope`'
+  - 'Reading/writing arbitrary user-typed secrets from a tool via `this.secureStore.set/get/list/delete` (JSON-serialized, scoped to the session/subject)'
+  - 'Backing the store with an OS keychain by supplying a `SecureStoreBackend` — no native dependency is bundled by the framework'
+  - 'Understanding scope: `user` (keyed by sub, default), `session` (keyed by sessionId), `global` (server-wide)'
+---
+
+# Local Mode with the Session Secure-Secret Store (`this.secureStore`)
+
+Configure the general session secure-secret store (this.secureStore) with a pluggable backing (memory / sqlite / redis / custom OS-keychain) and read/write user-typed secrets from a tool.
+
+The store is distinct from `this.credentials` (which is OAuth-credential-centric):
+use `this.secureStore` for arbitrary secrets like an API key a tool prompts for.
+The built-in backings encrypt at rest with AES-256-GCM, and an OS keychain can be
+plugged in without the framework bundling any native dependency.
+
+## Code
+
+```typescript
+// src/server.ts
+import { App, FrontMcp, Tool, ToolContext, z, type SecureStoreConfig } from '@frontmcp/sdk';
+
+@Tool({
+  name: 'set_api_key',
+  description: 'Store a user-typed API key in the session secure store',
+  inputSchema: { apiKey: z.string() },
+  outputSchema: { saved: z.boolean(), keys: z.array(z.string()) },
+})
+class SetApiKeyTool extends ToolContext {
+  async execute(input: { apiKey: string }) {
+    // Values are JSON-serialized and encrypted at rest (built-in backings),
+    // scoped to the current `sub` (user scope, the default).
+    await this.secureStore.set('stg.api-key', input.apiKey);
+    const keys = await this.secureStore.list();
+    return { saved: true, keys };
+  }
+}
+
+@Tool({
+  name: 'read_api_key',
+  description: 'Read the stored API key (presence only — never returns the raw secret)',
+  inputSchema: {},
+  outputSchema: { present: z.boolean() },
+})
+class ReadApiKeyTool extends ToolContext {
+  async execute() {
+    const apiKey = await this.secureStore.get<string>('stg.api-key');
+    // Never return the raw secret to the model — only presence.
+    return { present: apiKey !== undefined };
+  }
+}
+
+@App({ name: 'Secrets', tools: [SetApiKeyTool, ReadApiKeyTool] })
+class SecretsApp {}
+
+// Pick the backing per deployment. Default ('memory') is encrypted in-process.
+const secureStore: SecureStoreConfig = {
+  sqlite: { path: './.frontmcp/secrets.sqlite' }, // survives restart
+  scope: 'user', // 'user' (default) | 'session' | 'global'
+};
+
+@FrontMcp({
+  info: { name: 'secure-store-demo', version: '0.1.0' },
+  apps: [SecretsApp],
+  auth: {
+    mode: 'local',
+    secureStore,
+    login: {
+      title: 'Sign in',
+      fields: { apiKey: { type: 'password', label: 'API Key', required: true } },
+      subject: { fromField: 'apiKey', strategy: 'per-account' },
+    },
+    authenticate: async (input) => {
+      if (!input.fields['apiKey']) return { ok: false, message: 'API key required', retryField: 'apiKey' };
+      return { ok: true };
+    },
+  },
+})
+export default class Server {}
+```
+
+## What This Demonstrates
+
+- Selecting the secure-store backing via `auth.secureStore` (memory / sqlite / redis / custom backend) plus a namespace `scope`
+- Reading/writing arbitrary user-typed secrets from a tool via `this.secureStore.set/get/list/delete` (JSON-serialized, scoped to the session/subject)
+- Backing the store with an OS keychain by supplying a `SecureStoreBackend` — no native dependency is bundled by the framework
+- Understanding scope: `user` (keyed by sub, default), `session` (keyed by sessionId), `global` (server-wide)
+
+## Optional: back the store with an OS keychain (pluggable, not bundled)
+
+FrontMCP does **not** ship `keytar`/`wincred`/`libsecret`. Supply an object
+implementing `SecureStoreBackend` and the framework uses it as-is (no framework
+crypto — an OS keychain is encrypted by the OS):
+
+```typescript
+import type { SecureStoreBackend } from '@frontmcp/sdk';
+
+// import keytar from 'keytar'; // YOU add the native peer-dep
+
+const keychainBackend: SecureStoreBackend = {
+  async get(namespace, key) {
+    return (await keytar.getPassword(`frontmcp:${namespace}`, key)) ?? null;
+  },
+  async set(namespace, key, value /*, ttlMs */) {
+    await keytar.setPassword(`frontmcp:${namespace}`, key, value); // ttlMs ignored
+  },
+  async delete(namespace, key) {
+    return keytar.deletePassword(`frontmcp:${namespace}`, key);
+  },
+  async list(/* namespace */) {
+    const creds = await keytar.findCredentials('frontmcp');
+    return creds.map((c) => c.account);
+  },
+};
+
+// auth: { mode: 'local', secureStore: { backend: keychainBackend, scope: 'global' } }
+```
+
+## Notes
+
+- **Backings**: `'memory'` (default, encrypted in-process), `{ sqlite: { path } }`,
+  `{ redis: { ... } }`, or `{ backend }` (custom). The persistent built-ins reuse
+  the same `StorageAdapter`/`VaultEncryption` as `tokenStorage`; when the backing
+  matches `tokenStorage` the same connection is shared.
+- **Scope**: `user` keys by `sub` (anonymous requests read empty / skip writes),
+  `session` keys by `sessionId`, `global` shares one server-wide namespace. The
+  identity is hashed into the namespace — never stored raw.
+- **API**: `get<T>(key)`, `set<T>(key, value, { ttlMs? })`, `delete(key)`,
+  `list()`. Object configs also accept `ttlMs` and `encryption.pepper`
+  (overrides `VAULT_SECRET ?? JWT_SECRET`).
+- **Never return raw secrets to the model** — expose presence/redacted previews
+  only, as `read_api_key` does above.