@motorical/scope-catalog 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motorical/scope-catalog",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Canonical MCP/OAuth scope metadata for Motorical — descriptions, Public API scope mapping, implied-read rules, and declarative tool/resource membership. One source of truth consumed by motorical-backend and @motorical/mcp.",
   "main": "./src/index.js",
   "engines": {

package/src/comms.js

@@ -0,0 +1,37 @@
+/**
+ * Communications (marketing) MCP constants. Spec: motorical-docs specs/2026-10-27-comms-mcp-m2-auth-delegation-scopes-design.md.
+ *
+ * Shared by the backend (grant resolver, OAuth consent), the Communications Block (delegation verification, route to scope table)
+ * and @motorical/mcp (the `communications` server), so the audience and the scope names cannot drift between them.
+ */
+const { MCP_HOST } = require('./tools');
+
+/** Fixed order; also the order the scopes appear in SCOPES (after the nine core scopes, so existing order is untouched). */
+const COMMS_SCOPES = [
+  'read:comms',
+  'write:comms.audience',
+  'write:comms.content',
+  'send:comms.campaign',
+  'manage:comms.workspace',
+  'manage:comms.webhooks',
+];
+
+/** What the FIRST consent asks for. Sending and managing are a step-up, so sending always has its own consent moment. */
+const COMMS_INITIAL_SCOPES = ['read:comms', 'write:comms.audience', 'write:comms.content'];
+
+/** The hosted server's canonical URI = its RFC 8707 audience = the `resource` stored on its grants. */
+const COMMS_CANONICAL_URI = `${MCP_HOST}/v1/motorical_communications/mcp`;
+
+/** Audience of the delegation assertion minted for this server. Distinct from the backend's `.../internal/mcp`, so neither can be replayed at the other. */
+const COMMS_DELEGATION_AUDIENCE = 'https://api.motorical.com/internal/mcp/comms';
+
+/**
+ * How a NEW oauth_resource_servers row is created for a resource that needs more than the transactional defaults. The sync inserts
+ * these and never changes `enabled` or `block_types` of an existing row. The communications server is marketing-only and starts
+ * DISABLED: nobody can consent to it until it is switched on deliberately (Comms MCP M2d).
+ */
+const RESOURCE_SERVER_DEFAULTS = {
+  [COMMS_CANONICAL_URI]: { blockTypes: ['marketing'], enabled: false },
+};
+
+module.exports = { COMMS_SCOPES, COMMS_INITIAL_SCOPES, COMMS_CANONICAL_URI, COMMS_DELEGATION_AUDIENCE, RESOURCE_SERVER_DEFAULTS };

package/src/implication.js

@@ -7,6 +7,13 @@
 const MCP_IMPLIED_READ = {
   'manage:webhooks': 'read:webhooks',
   'manage:domains': 'read:domains',
+  // Every Communications write, send and manage scope can read what it works on. Never the other way, and never sideways:
+  // writing content does not imply sending.
+  'write:comms.audience': 'read:comms',
+  'write:comms.content': 'read:comms',
+  'send:comms.campaign': 'read:comms',
+  'manage:comms.workspace': 'read:comms',
+  'manage:comms.webhooks': 'read:comms',
 };
 
 function expandMcpImplied(grantedScopes) {

package/src/index.js

@@ -3,4 +3,5 @@ module.exports = {
   ...require('./implication'),
   ...require('./tools'),
   ...require('./consent'),
+  ...require('./comms'),
 };

package/src/scopes.js

@@ -81,6 +81,51 @@ const SCOPES = {
     agentDescription: 'List and read sending domains, their DNS records and email-authentication health, and read a Motor Block\'s configuration, without adding or verifying any domain.',
     customerAction: 'View your sending domains and Motor Block configuration',
   },
+  // Communications (marketing). One area per scope so the consent screen shows sending on its own line. No Public API scopes:
+  // the Comms API is not a Public API route, the Communications Block checks these itself. There is deliberately no scope for
+  // permanent delete, recycle-bin cleanup or GDPR export/erase: those stay human-only.
+  'read:comms': {
+    resource: 'comms',
+    level: 'read',
+    publicScopes: [],
+    agentDescription: 'Read Communications data for the workspaces the person chose: lists and contacts, templates, campaigns, reports and events, the workspace map and readiness, and run read-only checks (template preview, lint, link check, starter render). Never changes anything.',
+    customerAction: 'View your lists, templates, campaigns and results',
+  },
+  'write:comms.audience': {
+    resource: 'comms-audience',
+    level: 'manage',
+    publicScopes: [],
+    agentDescription: 'Create and change lists and contacts, add contacts (with a dry run), derive lists from lists, import, and add or remove suppressions. Includes everything read:comms grants. Cannot delete anything permanently.',
+    customerAction: 'Add and change your lists and contacts',
+  },
+  'write:comms.content': {
+    resource: 'comms-content',
+    level: 'manage',
+    publicScopes: [],
+    agentDescription: 'Create and change templates, the brand kit and campaign drafts, duplicate and compile campaigns, and send a test email to the account owner only. Includes everything read:comms grants. Does not send to your contacts.',
+    customerAction: 'Create and edit email templates and campaign drafts, and send test emails to you',
+  },
+  'send:comms.campaign': {
+    resource: 'comms-sending',
+    level: 'manage',
+    publicScopes: [],
+    agentDescription: 'Schedule a campaign (which sends it to the audience) and cancel a scheduled or sending one. Cancelling is final. Includes everything read:comms grants.',
+    customerAction: 'Send campaigns to your contacts (this is what actually emails people)',
+  },
+  'manage:comms.workspace': {
+    resource: 'comms-workspace',
+    level: 'manage',
+    publicScopes: [],
+    agentDescription: 'Change workspace settings (consent, open tracking, unsubscribe page) and which marketing Motor Blocks a workspace uses. Includes everything read:comms grants.',
+    customerAction: 'Change workspace settings and which sending addresses a workspace uses',
+  },
+  'manage:comms.webhooks': {
+    resource: 'comms-webhooks',
+    level: 'manage',
+    publicScopes: [],
+    agentDescription: 'Create, update, delete and test campaign event webhooks of the workspaces the person chose. Includes everything read:comms grants.',
+    customerAction: 'Manage your campaign event webhooks',
+  },
 };
 
 function listGrantableScopes() {

package/src/tools.js

@@ -34,13 +34,14 @@ const ANALYTICS_TOOLS = [
   'motorical_get_error_codes',
   'motorical_get_rate_limits',
   'motorical_get_account_rate_limits',
-  'motorical_get_onboarding_state',
   'motorical_whoami',
   'motorical_get_logs',
   'motorical_get_message_by_smtp_id',
 ];
 
 const DOMAIN_TOOLS = [
+  // Domain verification, DNS readiness and Motor Block state: a domains read (GET /account/state needs config.read, which read:domains carries).
+  'motorical_get_onboarding_state',
   'motorical_domain_list',
   'motorical_domain_get',
   'motorical_domain_dns_records',
@@ -85,6 +86,13 @@ const MOTOR_BLOCK_TOOLS = [
   'motorical_motor_block_delete_status',
 ];
 
+/**
+ * The hosted `communications` server (Comms MCP M2c). Two read-only proof tools that exercise the whole path (consent, delegation with
+ * the comms audience, grant resolution, scope table, workspace binding). Not in ALL_TOOLS and not on the main server: marketing has its
+ * own server and its own consent. More tools arrive in M3, each adding the scope it needs to this server's offer.
+ */
+const COMMS_TOOLS = ['comms_get_readiness', 'comms_get_map'];
+
 const ALL_TOOLS = [
   ...new Set([
     ...TRANSACTIONAL_TOOLS,
@@ -112,6 +120,7 @@ const SERVER_TOOLS = {
   sandbox: [...SANDBOX_TOOLS, ...ANY_GRANT_TOOLS],
   webhooks: [...WEBHOOK_TOOLS, ...ANY_GRANT_TOOLS],
   motorBlocks: [...MOTOR_BLOCK_TOOLS, ...ANY_GRANT_TOOLS],
+  communications: [...COMMS_TOOLS, ...ANY_GRANT_TOOLS],
   signup: ['motorical_signup_handoff'],
 };
 
@@ -134,7 +143,7 @@ const TOOL_SCOPES = {
   motorical_get_error_codes: ['read:analytics'],
   motorical_get_rate_limits: ['read:analytics'],
   motorical_get_account_rate_limits: ['read:analytics'],
-  motorical_get_onboarding_state: ['read:analytics'],
+  motorical_get_onboarding_state: ['read:domains'],
   motorical_whoami: [], // any OAuth grant; see ANY_GRANT_TOOLS
   motorical_get_logs: ['read:analytics'],
   motorical_get_message_by_smtp_id: ['read:analytics'],
@@ -171,6 +180,8 @@ const TOOL_SCOPES = {
   motorical_motor_block_reactivate: ['manage:motor-blocks'],
   motorical_motor_block_delete: ['manage:motor-blocks'],
   motorical_motor_block_delete_status: ['manage:motor-blocks'],
+  comms_get_readiness: ['read:comms'],
+  comms_get_map: ['read:comms'],
 };
 
 /** `|| []`: a tool with no entry (signup's own tool) contributes no scopes rather than throwing. */
@@ -186,6 +197,7 @@ const SERVER_SLUGS = {
   sandbox: 'motorical_sandbox',
   webhooks: 'motorical_webhooks',
   motorBlocks: 'motorical_motor_blocks',
+  communications: 'motorical_communications',
   signup: 'signup',
 };