@frontmcp/skills 1.0.4 → 1.1.0

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

@@ -0,0 +1,391 @@
+---
+name: rbac-abac-rebac
+description: Comparison of RBAC, ABAC, and ReBAC authorization models with when to use each, policy syntax, and examples
+---
+
+# RBAC, ABAC, and ReBAC Models
+
+The FrontMCP authorities system supports three authorization models that can be used independently or combined. This reference explains each model, its policy syntax, and when to choose it.
+
+## Model Comparison
+
+| Model     | Based On                                  | Strength                                   | Weakness                                      | Use When                                                |
+| --------- | ----------------------------------------- | ------------------------------------------ | --------------------------------------------- | ------------------------------------------------------- |
+| **RBAC**  | User roles and permissions                | Simple, well-understood, fast              | No context awareness, role explosion at scale | Fixed role hierarchies (admin, editor, viewer)          |
+| **ABAC**  | Attributes of user, resource, environment | Flexible, context-aware, fine-grained      | More complex to configure and debug           | Tenant isolation, environment gates, dynamic conditions |
+| **ReBAC** | Relationships between users and resources | Models ownership and hierarchies naturally | Requires external relationship store          | Document ownership, team membership, org hierarchies    |
+
+## RBAC -- Role-Based Access Control
+
+RBAC checks whether the user has specific roles or permissions. Roles and permissions are extracted from JWT claims via `claimsMapping`.
+
+### Roles Policy
+
+```typescript
+interface RbacRolesPolicy {
+  /** User must have ALL of these roles (AND) */
+  all?: string[];
+  /** User must have at least ONE of these roles (OR) */
+  any?: string[];
+}
+```
+
+When both `all` and `any` are set, both conditions must be satisfied.
+
+**Examples:**
+
+```typescript
+// User must be an admin
+authorities: {
+  roles: { any: ['admin', 'superadmin'] },
+}
+
+// User must have BOTH 'reviewer' AND 'approver' roles
+authorities: {
+  roles: { all: ['reviewer', 'approver'] },
+}
+
+// User must have 'editor' AND at least one of 'us-team' or 'eu-team'
+authorities: {
+  roles: {
+    all: ['editor'],
+    any: ['us-team', 'eu-team'],
+  },
+}
+```
+
+### Permissions Policy
+
+Same structure as roles, but checked against the user's permissions array.
+
+```typescript
+interface RbacPermissionsPolicy {
+  all?: string[];
+  any?: string[];
+}
+```
+
+**Examples:**
+
+```typescript
+// User must have the 'users:delete' permission
+authorities: {
+  permissions: { all: ['users:delete'] },
+}
+
+// User must have 'content:read' AND ('content:write' OR 'content:publish')
+authorities: {
+  permissions: {
+    all: ['content:read'],
+    any: ['content:write', 'content:publish'],
+  },
+}
+```
+
+### Combining Roles and Permissions
+
+Within a single policy object, roles and permissions are combined using the `operator` field (default `'AND'`).
+
+```typescript
+// User must be an admin AND have 'users:delete' permission
+authorities: {
+  roles: { any: ['admin'] },
+  permissions: { all: ['users:delete'] },
+}
+
+// User must be an admin OR have 'users:delete' permission
+authorities: {
+  roles: { any: ['admin'] },
+  permissions: { all: ['users:delete'] },
+  operator: 'OR',
+}
+```
+
+## ABAC -- Attribute-Based Access Control
+
+ABAC evaluates conditions against a context envelope containing `user`, `claims`, `input`, and `env`. This enables tenant isolation, environment-specific gates, and dynamic value matching.
+
+### Context Envelope
+
+The evaluation context has four top-level namespaces:
+
+| Prefix     | Content                                                      | Example Path                        |
+| ---------- | ------------------------------------------------------------ | ----------------------------------- |
+| `user.*`   | Resolved user info (`sub`, `roles`, `permissions`, `claims`) | `user.sub`, `user.roles`            |
+| `claims.*` | Raw JWT claims                                               | `claims.org_id`, `claims.email`     |
+| `input.*`  | Tool/prompt input arguments                                  | `input.tenantId`, `input.projectId` |
+| `env.*`    | Runtime environment variables                                | `env.NODE_ENV`, `env.REGION`        |
+
+### Simple Match
+
+The `match` field provides simple equality checks. All pairs must match (AND semantics).
+
+```typescript
+authorities: {
+  attributes: {
+    match: {
+      'claims.org_id': 'tenant-abc',
+      'env.NODE_ENV': 'production',
+    },
+  },
+}
+```
+
+### Advanced Conditions
+
+The `conditions` array supports operators. All conditions must pass (AND semantics).
+
+```typescript
+interface AbacCondition {
+  path: string; // Dot-path into context envelope
+  op: AbacOperator; // Comparison operator
+  value: unknown; // Literal or DynamicValueRef
+}
+```
+
+**Available operators:**
+
+| Operator     | Description                       | Example                                                                     |
+| ------------ | --------------------------------- | --------------------------------------------------------------------------- |
+| `eq`         | Strict equality                   | `{ path: 'claims.tier', op: 'eq', value: 'enterprise' }`                    |
+| `neq`        | Not equal                         | `{ path: 'claims.status', op: 'neq', value: 'suspended' }`                  |
+| `in`         | Value is in array                 | `{ path: 'env.REGION', op: 'in', value: ['us-east', 'eu-west'] }`           |
+| `notIn`      | Value is not in array             | `{ path: 'claims.role', op: 'notIn', value: ['blocked'] }`                  |
+| `gt`         | Greater than (number)             | `{ path: 'claims.tokenVersion', op: 'gt', value: 2 }`                       |
+| `gte`        | Greater than or equal             | `{ path: 'claims.apiQuota', op: 'gte', value: 100 }`                        |
+| `lt`         | Less than (number)                | `{ path: 'claims.failCount', op: 'lt', value: 5 }`                          |
+| `lte`        | Less than or equal                | `{ path: 'claims.riskScore', op: 'lte', value: 50 }`                        |
+| `contains`   | String contains or array includes | `{ path: 'claims.email', op: 'contains', value: '@corp.com' }`              |
+| `startsWith` | String starts with                | `{ path: 'user.sub', op: 'startsWith', value: 'service-' }`                 |
+| `endsWith`   | String ends with                  | `{ path: 'claims.email', op: 'endsWith', value: '@acme.com' }`              |
+| `exists`     | Value exists (not null/undefined) | `{ path: 'user.sub', op: 'exists', value: true }`                           |
+| `matches`    | Regex match                       | `{ path: 'claims.email', op: 'matches', value: '^.*@(acme\|corp)\\.com$' }` |
+
+### Dynamic Value References
+
+Instead of hardcoding values, reference runtime data from tool input or JWT claims.
+
+```typescript
+// Match tenant from tool input
+{ path: 'claims.org_id', op: 'eq', value: { fromInput: 'tenantId' } }
+
+// Match a value from another claim
+{ path: 'claims.department', op: 'eq', value: { fromClaims: 'manager.department' } }
+```
+
+### ABAC Examples
+
+**Tenant isolation:**
+
+```typescript
+@Tool({
+  name: 'get_tenant_data',
+  inputSchema: { tenantId: z.string() },
+  authorities: {
+    attributes: {
+      conditions: [
+        { path: 'claims.org_id', op: 'eq', value: { fromInput: 'tenantId' } },
+      ],
+    },
+  },
+})
+export default class GetTenantDataTool extends ToolContext { ... }
+```
+
+**Environment gate:**
+
+```typescript
+@Tool({
+  name: 'run_migration',
+  authorities: {
+    attributes: {
+      conditions: [
+        { path: 'env.NODE_ENV', op: 'in', value: ['staging', 'production'] },
+        { path: 'claims.role', op: 'eq', value: 'dba' },
+      ],
+    },
+  },
+})
+export default class RunMigrationTool extends ToolContext { ... }
+```
+
+**Authenticated user check:**
+
+```typescript
+authorities: {
+  attributes: {
+    conditions: [{ path: 'user.sub', op: 'exists', value: true }],
+  },
+}
+```
+
+## ReBAC -- Relationship-Based Access Control
+
+ReBAC checks whether the authenticated user has a specific relationship to a named resource. This requires a `RelationshipResolver` that queries your authorization backend (SpiceDB, OpenFGA, custom database).
+
+### Policy Syntax
+
+```typescript
+interface RebacPolicy {
+  /** Relationship type (e.g., 'owner', 'member', 'viewer') */
+  type: string;
+  /** Resource type (e.g., 'document', 'site', 'org') */
+  resource: string;
+  /** Resource identifier -- literal, from input, or from claims */
+  resourceId: ResourceIdRef;
+}
+
+type ResourceIdRef = string | { fromInput: string } | { fromClaims: string };
+```
+
+### Implementing a Relationship Resolver
+
+The resolver is passed via the `authorities.relationshipResolver` config in `@FrontMcp()`. It must implement the `RelationshipResolver` interface.
+
+```typescript
+import type { RelationshipResolver, AuthoritiesEvaluationContext } from '@frontmcp/auth';
+
+const myRelationshipResolver: RelationshipResolver = {
+  async check(
+    type: string,
+    resource: string,
+    resourceId: string,
+    userSub: string,
+    ctx: AuthoritiesEvaluationContext,
+  ): Promise<boolean> {
+    // Example: query SpiceDB / OpenFGA / your database
+    const result = await spiceDb.checkPermission({
+      subject: { object: { objectType: 'user', objectId: userSub } },
+      permission: type,
+      resource: { objectType: resource, objectId: resourceId },
+    });
+    return result.permissionship === 'HAS_PERMISSION';
+  },
+};
+
+// In @FrontMcp({ authorities: { ... } })
+authorities: {
+  claimsMapping: { roles: 'roles' },
+  relationshipResolver: myRelationshipResolver,
+  profiles: { ... },
+}
+```
+
+### ReBAC Examples
+
+**Document ownership:**
+
+```typescript
+@Tool({
+  name: 'edit_document',
+  inputSchema: { documentId: z.string() },
+  authorities: {
+    relationships: {
+      type: 'owner',
+      resource: 'document',
+      resourceId: { fromInput: 'documentId' },
+    },
+  },
+})
+export default class EditDocumentTool extends ToolContext { ... }
+```
+
+**Team membership:**
+
+```typescript
+@Tool({
+  name: 'view_team_dashboard',
+  inputSchema: { teamId: z.string() },
+  authorities: {
+    relationships: {
+      type: 'member',
+      resource: 'team',
+      resourceId: { fromInput: 'teamId' },
+    },
+  },
+})
+export default class ViewTeamDashboardTool extends ToolContext { ... }
+```
+
+**Multiple relationships (AND):**
+
+```typescript
+@Tool({
+  name: 'approve_expense',
+  inputSchema: { expenseId: z.string(), departmentId: z.string() },
+  authorities: {
+    relationships: [
+      { type: 'manager', resource: 'department', resourceId: { fromInput: 'departmentId' } },
+      { type: 'reviewer', resource: 'expense', resourceId: { fromInput: 'expenseId' } },
+    ],
+  },
+})
+export default class ApproveExpenseTool extends ToolContext { ... }
+```
+
+## Combining Models
+
+The real power of the authorities system is combining models in a single policy. All fields within a policy are combined using `operator` (default `'AND'`).
+
+**RBAC + ABAC (role AND tenant match):**
+
+```typescript
+authorities: {
+  roles: { any: ['admin'] },
+  attributes: {
+    conditions: [
+      { path: 'claims.org_id', op: 'eq', value: { fromInput: 'tenantId' } },
+    ],
+  },
+}
+```
+
+**RBAC + ReBAC (role AND document ownership):**
+
+```typescript
+authorities: {
+  roles: { any: ['editor'] },
+  relationships: {
+    type: 'owner',
+    resource: 'document',
+    resourceId: { fromInput: 'documentId' },
+  },
+}
+```
+
+**Complex: admin bypasses ownership, others need ownership:**
+
+```typescript
+authorities: {
+  anyOf: [
+    { roles: { any: ['admin'] } },
+    {
+      roles: { any: ['editor'] },
+      relationships: {
+        type: 'owner',
+        resource: 'document',
+        resourceId: { fromInput: 'documentId' },
+      },
+    },
+  ],
+}
+```
+
+## Decision Guide
+
+Use this guide to pick the right model for your use case:
+
+| Question                                  | If Yes                                 | If No                  |
+| ----------------------------------------- | -------------------------------------- | ---------------------- |
+| Are roles/permissions defined in the IdP? | Start with RBAC                        | Consider ABAC or ReBAC |
+| Do you need tenant isolation?             | Use ABAC with `{ fromInput: ... }`     | RBAC may suffice       |
+| Do you need per-resource ownership?       | Use ReBAC with a relationship resolver | RBAC or ABAC           |
+| Do you need environment-specific gates?   | Use ABAC with `env.*` paths            | Not needed             |
+| Is the logic too complex for one model?   | Combine with `allOf`/`anyOf`           | Keep it simple         |
+
+## Reference
+
+- Types: `libs/auth/src/authorities/authorities.types.ts`
+- Evaluators: `libs/auth/src/authorities/authorities.evaluator.ts`
+- Context: `libs/auth/src/authorities/authorities.context.ts`
+- Related: `references/claims-mapping.md`, `references/authority-profiles.md`, `references/custom-evaluators.md`

package/catalog/frontmcp-channels/SKILL.md

@@ -0,0 +1,122 @@
+---
+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.'
+tags: [channels, notifications, claude-code, webhooks, messaging, real-time, two-way]
+category: development
+targets: [all]
+bundle: [full]
+priority: 8
+visibility: both
+license: Apache-2.0
+metadata:
+  docs: https://code.claude.com/docs/en/channels-reference
+---
+
+# FrontMCP Channels
+
+Build push-based notification channels that stream real-time events into Claude Code. Channels let your MCP server forward webhooks, application errors, agent completions, job results, and chat messages directly into Claude's context, with optional two-way reply support.
+
+## When to Use This Skill
+
+### Must Use
+
+- You need Claude Code to react to external events (CI failures, monitoring alerts, deploy status)
+- You are building a chat bridge (WhatsApp, Telegram, Slack, Discord) for Claude Code
+- You want agents or background jobs to notify Claude Code upon completion
+
+### Recommended
+
+- You want to forward application errors to Claude for debugging assistance
+- You need a messaging interface where remote users can interact with Claude via chat platforms
+
+### Skip When
+
+- You only need standard MCP resource subscriptions (use `@Resource` with `resources/subscribe`)
+- Your client is not Claude Code and does not support `experimental['claude/channel']`
+- You need request-response patterns (use `@Tool` instead)
+
+> **Decision:** Use channels when you need server-initiated push notifications into Claude Code. Use resources when the client pulls data on demand.
+
+## Prerequisites
+
+- `@frontmcp/sdk` >= 1.0.0
+- Basic understanding of `@FrontMcp`, `@App`, and `@Tool` decorators
+- For webhook sources: HTTP transport (not stdio-only)
+- For chat bridges: external API credentials (WhatsApp Business API, Telegram Bot Token, etc.)
+
+## Steps
+
+1. Choose your channel source type from the Scenario Routing Table
+2. Create a channel class or function
+3. Register it in your app
+4. Enable channels in `@FrontMcp` config
+5. Test with Claude Code using `--dangerously-load-development-channels`
+
+## Scenario Routing Table
+
+| Scenario                           | Reference                       | Description                                    |
+| ---------------------------------- | ------------------------------- | ---------------------------------------------- |
+| Webhook alerts (CI, monitoring)    | `references/channel-sources.md` | Forward HTTP webhooks into Claude              |
+| Application error forwarding       | `references/channel-sources.md` | Push app errors via event bus                  |
+| Agent completion notifications     | `references/channel-sources.md` | Notify when agents finish                      |
+| Job/workflow completion            | `references/channel-sources.md` | Notify when jobs complete                      |
+| Service connector (WhatsApp, etc.) | `references/channel-sources.md` | Persistent connection with bidirectional tools |
+| File/log watcher                   | `references/channel-sources.md` | File system change monitoring                  |
+| Event replay for offline sessions  | `references/channel-sources.md` | Buffer events for later delivery               |
+| WhatsApp/Telegram chat bridge      | `references/channel-two-way.md` | Two-way messaging with Claude                  |
+| Slack/Discord integration          | `references/channel-two-way.md` | Chat platform bridges                          |
+| Permission relay                   | `references/channel-two-way.md` | Remote tool approval via chat                  |
+
+## Common Patterns
+
+| Pattern        | Correct                                 | Incorrect                                    | Why                                                                |
+| -------------- | --------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------ |
+| Meta keys      | `meta: { env: 'prod' }`                 | `meta: { 'my-env': 'prod' }`                 | Meta keys must be valid identifiers (letters, digits, underscores) |
+| Source naming  | `name: 'deploy-alerts'`                 | `name: 'Deploy Alerts!'`                     | Channel names should be kebab-case identifiers                     |
+| Two-way gating | Check sender identity before emitting   | Trust room/group membership                  | Prevent prompt injection from untrusted group members              |
+| Error channels | Use `app-event` source with event bus   | Poll for errors in a loop                    | Event bus is push-based and efficient                              |
+| Manual push    | Use `scope.channelNotifications.send()` | Call `pushNotification` on instance directly | Service handles capability filtering                               |
+
+## Verification Checklist
+
+### Server Setup
+
+- [ ] `@FrontMcp({ channels: { enabled: true } })` is set
+- [ ] Channel classes extend `ChannelContext` with `@Channel()` decorator
+- [ ] Channels are listed in `@App({ channels: [...] })`
+- [ ] `onEvent()` returns `{ content: string, meta?: Record<string, string> }`
+
+### Capability
+
+- [ ] Server advertises `experimental: { 'claude/channel': {} }` in capabilities
+- [ ] Only sessions with matching capability receive notifications
+- [ ] `instructions` field mentions `<channel>` tags when channels are active
+
+### Two-Way
+
+- [ ] `twoWay: true` is set on channels that need replies
+- [ ] `channel-reply` tool appears in tool list
+- [ ] `onReply()` is implemented and forwards to external system
+- [ ] Sender authentication is enforced before emitting events
+
+### Sources
+
+- [ ] Webhook endpoints return 200 on success
+- [ ] Event bus subscriptions are cleaned up on scope teardown
+- [ ] Agent/job completion filters match expected IDs
+
+## Troubleshooting
+
+| Problem                      | Cause                           | Solution                                                           |
+| ---------------------------- | ------------------------------- | ------------------------------------------------------------------ |
+| No notifications arrive      | Client doesn't support channels | Check client capabilities include `experimental['claude/channel']` |
+| `channel-reply` tool missing | No two-way channels registered  | Set `twoWay: true` on at least one channel                         |
+| Webhook returns 500          | `onEvent()` throws              | Check channel handler error logs                                   |
+| Duplicate notifications      | Multiple sessions subscribed    | This is correct behavior -- each session gets its own copy         |
+| Events lost on reconnect     | Channels are in-memory          | Channel state resets on server restart; use persistent sources     |
+
+## Reference
+
+- [Claude Code Channels Reference](https://code.claude.com/docs/en/channels-reference)
+- [MCP Specification - Notifications](https://modelcontextprotocol.io/specification/2025-03-26)
+- Related skills: `frontmcp-development`, `frontmcp-testing`, `frontmcp-deployment`

package/catalog/frontmcp-channels/examples/channel-sources/agent-notify.md

@@ -0,0 +1,70 @@
+---
+name: agent-notify
+reference: channel-sources
+level: intermediate
+description: Notify Claude Code when AI agents complete their tasks
+tags: [agents, completion, notifications, automation]
+features:
+  - Agent completion source with ID filtering
+  - Duration and output reporting
+  - Integration with agent registry emitter
+---
+
+# Agent Completion Channel
+
+Notify Claude Code when AI agents complete their tasks
+
+## Code
+
+```typescript
+// src/apps/automation/channels/agent-done.channel.ts
+import { Channel, ChannelContext, ChannelNotification } from '@frontmcp/sdk';
+
+@Channel({
+  name: 'agent-done',
+  description: 'Notifies when code review or test agents complete',
+  source: {
+    type: 'agent-completion',
+    agentIds: ['code-reviewer', 'test-writer', 'security-scanner'],
+  },
+})
+export class AgentDoneChannel extends ChannelContext {
+  async onEvent(payload: unknown): Promise<ChannelNotification> {
+    const event = payload as {
+      agentId: string;
+      agentName: string;
+      status: 'success' | 'error';
+      durationMs?: number;
+      output?: string;
+      error?: string;
+    };
+
+    const duration = event.durationMs ? ` in ${(event.durationMs / 1000).toFixed(1)}s` : '';
+
+    if (event.status === 'error') {
+      return {
+        content: `Agent "${event.agentName}" failed${duration}.\nError: ${event.error ?? 'Unknown error'}`,
+        meta: { agent: event.agentId, status: 'error' },
+      };
+    }
+
+    const output = event.output ? `\nResult: ${event.output.slice(0, 500)}` : '';
+
+    return {
+      content: `Agent "${event.agentName}" completed successfully${duration}.${output}`,
+      meta: { agent: event.agentId, status: 'success' },
+    };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Agent completion source with ID filtering
+- Duration and output reporting
+- Integration with agent registry emitter
+
+## Related
+
+- See `channel-sources` for all source type documentation
+- See `frontmcp-development` for agent creation patterns

package/catalog/frontmcp-channels/examples/channel-sources/app-errors.md

@@ -0,0 +1,71 @@
+---
+name: app-errors
+reference: channel-sources
+level: basic
+description: Forward application errors to Claude Code via the in-process event bus
+tags: [errors, app-event, debugging, monitoring]
+features:
+  - App event source with ChannelEventBus
+  - Error severity classification
+  - Stack trace forwarding
+---
+
+# Application Error Channel
+
+Forward application errors to Claude Code via the in-process event bus
+
+## Code
+
+```typescript
+// src/apps/monitoring/channels/error-alert.channel.ts
+import { Channel, ChannelContext, ChannelNotification } from '@frontmcp/sdk';
+
+@Channel({
+  name: 'app-errors',
+  description: 'Application error notifications for debugging',
+  source: { type: 'app-event', event: 'error' },
+})
+export class ErrorAlertChannel extends ChannelContext {
+  async onEvent(payload: unknown): Promise<ChannelNotification> {
+    const error = payload as {
+      message: string;
+      stack?: string;
+      code?: string;
+      severity: 'warning' | 'error' | 'critical';
+      source?: string;
+    };
+
+    const lines = [`[${error.severity.toUpperCase()}] ${error.message}`];
+    if (error.code) lines.push(`Code: ${error.code}`);
+    if (error.stack) lines.push(`Stack:\n${error.stack}`);
+
+    return {
+      content: lines.join('\n'),
+      meta: {
+        severity: error.severity,
+        ...(error.code ? { code: error.code } : {}),
+        ...(error.source ? { error_source: error.source } : {}),
+      },
+    };
+  }
+}
+
+// Emit from anywhere in your application:
+// scope.channelEventBus.emit('error', {
+//   message: 'Database connection timeout',
+//   severity: 'critical',
+//   code: 'DB_TIMEOUT',
+//   source: 'user-service',
+//   stack: new Error().stack,
+// });
+```
+
+## What This Demonstrates
+
+- App event source with ChannelEventBus
+- Error severity classification
+- Stack trace forwarding
+
+## Related
+
+- See `channel-sources` for all source type documentation