@motorical/scope-catalog 0.1.0

package/README.md

@@ -0,0 +1,13 @@
+# @motorical/scope-catalog
+
+Canonical MCP/OAuth scope metadata for Motorical. One source of truth for:
+
+- what each of the seven grantable MCP scopes means, for an agent AND for a customer (`SCOPES`)
+- which Public API scopes each MCP scope unlocks (`SCOPES[id].publicScopes`, `publicScopesFor`)
+- "manage implies read", in both the MCP and Public API vocabularies (`implication.js`)
+- which scopes a tool needs, and which scopes a given MCP resource server allows (`tools.js`)
+- how to group scopes for a consent screen (`groupForConsent`)
+
+Consumed by `motorical-backend` (OAuth server, Public API auth) and `@motorical/mcp`
+(the hosted/local MCP server). See `motorical-docs/specs/2026-09-23-mcp-p7-scope-legibility-founding-doc.md`
+for why this package exists.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@motorical/scope-catalog",
+  "version": "0.1.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": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "license": "UNLICENSED",
+  "dependencies": {},
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "homepage": "https://docs.motorical.com/ai",
+  "bugs": {
+    "url": "https://github.com/motorical-smtp/motorical-backend/issues"
+  },
+  "keywords": [
+    "motorical",
+    "oauth",
+    "scopes",
+    "mcp"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/motorical-smtp/motorical-packages.git",
+    "directory": "packages/motorical-scope-catalog"
+  }
+}

package/src/consent.js

@@ -0,0 +1,40 @@
+const { SCOPES } = require('./scopes');
+
+const LEVEL_RANK = { read: 0, manage: 1 };
+
+/**
+ * "Granular and secure internally; simple for the customer" (P7 design
+ * principle 1). The underlying scopes stay separately grantable and
+ * separately enforced; this only changes what the consent screen SHOWS —
+ * one line per resource area, using whichever granted scope for that
+ * resource has the highest level, while `scopes` on the returned group
+ * still lists every individual scope actually granted for it.
+ */
+function groupForConsent(scopes) {
+  const byResource = new Map();
+  for (const id of scopes) {
+    const meta = SCOPES[id];
+    if (!meta) continue;
+    const existing = byResource.get(meta.resource);
+    if (!existing || LEVEL_RANK[meta.level] > LEVEL_RANK[existing.level]) {
+      byResource.set(meta.resource, { resource: meta.resource, label: meta.customerAction, level: meta.level, scopes: [] });
+    }
+  }
+  for (const id of scopes) {
+    const meta = SCOPES[id];
+    if (!meta) continue;
+    byResource.get(meta.resource).scopes.push(id);
+  }
+  return Array.from(byResource.values()).map(({ resource, label, scopes: s }) => ({ resource, label, scopes: s }));
+}
+
+function publicScopesFor(mcpScopes) {
+  const out = new Set();
+  for (const id of mcpScopes) {
+    for (const p of (SCOPES[id]?.publicScopes || [])) out.add(p);
+  }
+  out.delete('logs.pii');
+  return Array.from(out);
+}
+
+module.exports = { groupForConsent, publicScopesFor };

package/src/implication.js

@@ -0,0 +1,44 @@
+/**
+ * "Manage implies read" at the MCP layer. Was resourceAuth.js's
+ * IMPLIED_READ_MCP_SCOPES (packages/motorical-mcp/src/resourceAuth.js).
+ * Kept separate from PUBLIC_IMPLIED_READ below because the two vocabularies
+ * are genuinely different namespaces — see that map's own comment.
+ */
+const MCP_IMPLIED_READ = {
+  'manage:webhooks': 'read:webhooks',
+  'manage:domains': 'read:domains',
+};
+
+function expandMcpImplied(grantedScopes) {
+  const expanded = new Set(grantedScopes);
+  for (const manageScope of Object.keys(MCP_IMPLIED_READ)) {
+    if (expanded.has(manageScope)) expanded.add(MCP_IMPLIED_READ[manageScope]);
+  }
+  return Array.from(expanded);
+}
+
+/**
+ * "Manage implies read" at the Public API layer. Was authenticatePublic.js's
+ * IMPLIED_READ_SCOPES (backend/src/middleware/authenticatePublic.js).
+ *
+ * This is NOT derivable from MCP_IMPLIED_READ above: this map also has to
+ * cover callers that never touch an MCP scope at all (a legacy dashboard-JWT
+ * Public API token, "authenticatePublicMcpAudience.test.js"'s "legacy HS256
+ * tokens keep working unchanged" case) — so it has to exist as its own
+ * independent fact about the Public API's own scope vocabulary, not as a
+ * side effect of the MCP-scope map.
+ */
+const PUBLIC_IMPLIED_READ = {
+  'webhooks.manage': 'webhooks.read',
+  'config.manage': 'config.read',
+};
+
+function expandPublicImplied(grantedScopes) {
+  const expanded = new Set(grantedScopes);
+  for (const manageScope of Object.keys(PUBLIC_IMPLIED_READ)) {
+    if (expanded.has(manageScope)) expanded.add(PUBLIC_IMPLIED_READ[manageScope]);
+  }
+  return Array.from(expanded);
+}
+
+module.exports = { MCP_IMPLIED_READ, expandMcpImplied, PUBLIC_IMPLIED_READ, expandPublicImplied };

package/src/index.js

@@ -0,0 +1,6 @@
+module.exports = {
+  ...require('./scopes'),
+  ...require('./implication'),
+  ...require('./tools'),
+  ...require('./consent'),
+};

package/src/scopes.js

@@ -0,0 +1,76 @@
+// packages/motorical-scope-catalog/src/scopes.js
+
+/**
+ * The one source of truth for what an MCP scope IS: which resource area it
+ * belongs to, whether it's read or manage, which Public API scopes it
+ * unlocks (backend/src/services/oauth/mcpTokens.js used to hand-declare
+ * this as MCP_TO_PUBLIC_SCOPES), and the two audiences that need to
+ * understand it in different words — an agent deciding what to request,
+ * and a customer deciding what to approve.
+ *
+ * publicScopes values below are copied verbatim from the MCP_TO_PUBLIC_SCOPES
+ * this package replaces. logs.pii is deliberately absent everywhere here —
+ * it is never reachable from any MCP scope, by design (P6).
+ */
+// Insertion order matters: Object.keys(SCOPES) drives listGrantableScopes(),
+// which backend/src/routes/oauth.js's MCP_SCOPES_SUPPORTED derives from
+// (Task 9). oauthDiscoveryMetadata.test.js asserts scopes_supported as an
+// EXACT ordered array — this order matches that existing test byte-for-byte
+// so that test needs no change. Do not reorder without checking it first.
+const SCOPES = {
+  'send:transactional': {
+    resource: 'transactional',
+    level: 'manage',
+    publicScopes: [],
+    agentDescription: 'Send transactional email through the caller\'s Motor Block(s).',
+    customerAction: 'Send transactional email through your Motor Blocks',
+  },
+  'read:analytics': {
+    resource: 'analytics',
+    level: 'read',
+    publicScopes: ['logs.read', 'analytics.read', 'usage.read'],
+    agentDescription: 'Read delivery logs, analytics, and usage for the caller\'s Motor Block(s). Never includes unmasked recipient PII (logs.pii) regardless of what is requested.',
+    customerAction: 'Read delivery logs, analytics and usage',
+  },
+  'manage:domains': {
+    resource: 'domains',
+    level: 'manage',
+    publicScopes: ['config.read', 'config.manage'],
+    agentDescription: 'Add, verify, and read sending domains and their DNS health. Includes everything read:domains grants.',
+    customerAction: 'Add and verify sending domains',
+  },
+  'manage:sandbox': {
+    resource: 'sandbox',
+    level: 'manage',
+    publicScopes: ['sandbox.manage'],
+    agentDescription: 'Check, provision, and convert the developer sandbox. Sandbox allowlist requests/confirmations additionally require a dashboard session — this scope alone does not make them callable over OAuth.',
+    customerAction: 'Manage your developer sandbox',
+  },
+  'manage:webhooks': {
+    resource: 'webhooks',
+    level: 'manage',
+    publicScopes: ['webhooks.manage'],
+    agentDescription: 'Create, update, delete, and test webhook endpoints on the caller\'s Motor Block(s). Includes everything read:webhooks grants.',
+    customerAction: 'Manage your webhook endpoints',
+  },
+  'read:webhooks': {
+    resource: 'webhooks',
+    level: 'read',
+    publicScopes: ['webhooks.read'],
+    agentDescription: 'List webhook endpoints and read their delivery history and stats, without creating, updating, deleting, or testing any.',
+    customerAction: 'View your webhook endpoints and delivery history',
+  },
+  'read:domains': {
+    resource: 'domains',
+    level: 'read',
+    publicScopes: ['config.read'],
+    agentDescription: 'List and read sending domains, without adding or verifying any.',
+    customerAction: 'View your sending domains',
+  },
+};
+
+function listGrantableScopes() {
+  return Object.keys(SCOPES);
+}
+
+module.exports = { SCOPES, listGrantableScopes };

package/src/tools.js

@@ -0,0 +1,149 @@
+/**
+ * Declarative tool/resource membership — moved out of
+ * packages/motorical-mcp/src/servers.js (P7 second review round: that
+ * file's own comment already said "a server's advertised scopes are the
+ * union of its tools' required scopes," so a second hand-maintained
+ * resource->scopes map would have duplicated exactly that logic).
+ *
+ * TOOL_ROUTES, LOCAL_ONLY_TOOLS, HOSTED_ONLY_TOOLS, PROMPT_TOOLS,
+ * LOCAL_SERVER_TOOL_COUNT, ACCOUNT_SCOPED_TOOLS, byPath, and
+ * canonicalUriFor all stay in servers.js — those are @motorical/mcp's own
+ * implementation wiring, not shared policy. Only the tool-name lists, the
+ * scope map, and their derivation move here.
+ */
+const MCP_HOST = 'https://mcp.motorical.com';
+
+const TRANSACTIONAL_TOOLS = [
+  'motorical_send_email',
+  'motorical_get_message',
+  'motorical_get_message_events',
+  'motorical_wait_for_outcome',
+  'motorical_get_send_status',
+  'motorical_integrate_send',
+];
+
+const ANALYTICS_TOOLS = [
+  'motorical_list_motor_blocks',
+  'motorical_get_overview',
+  'motorical_get_daily_summary',
+  'motorical_get_metrics',
+  'motorical_get_deliverability',
+  'motorical_get_reputation',
+  'motorical_get_anomalies',
+  'motorical_get_providers',
+  'motorical_get_error_codes',
+  'motorical_get_rate_limits',
+  'motorical_get_account_rate_limits',
+  'motorical_get_onboarding_state',
+  'motorical_get_logs',
+  'motorical_get_message_by_smtp_id',
+];
+
+const DOMAIN_TOOLS = [
+  'motorical_domain_list',
+  'motorical_domain_add',
+  'motorical_domain_verify',
+  'motorical_domain_check_dns',
+  'motorical_get_config',
+  'motorical_get_domain_health',
+];
+
+const SANDBOX_TOOLS = [
+  'motorical_sandbox_status',
+  'motorical_sandbox_provision',
+  'motorical_sandbox_convert',
+  'motorical_sandbox_allowlist_request',
+  'motorical_sandbox_allowlist_confirm',
+];
+
+const WEBHOOK_TOOLS = [
+  'motorical_webhook_list',
+  'motorical_webhook_create',
+  'motorical_webhook_update',
+  'motorical_webhook_delete',
+  'motorical_webhook_test',
+  'motorical_webhook_get_deliveries',
+  'motorical_webhook_get_stats',
+];
+
+const ALL_TOOLS = [
+  ...new Set([...TRANSACTIONAL_TOOLS, ...ANALYTICS_TOOLS, ...DOMAIN_TOOLS, ...SANDBOX_TOOLS, ...WEBHOOK_TOOLS]),
+];
+
+const SERVER_TOOLS = {
+  main: ALL_TOOLS,
+  transactional: TRANSACTIONAL_TOOLS,
+  analytics: ANALYTICS_TOOLS,
+  domains: DOMAIN_TOOLS,
+  sandbox: SANDBOX_TOOLS,
+  webhooks: WEBHOOK_TOOLS,
+  signup: ['motorical_signup_handoff'],
+};
+
+/** The one source of truth for "what scope does this tool need". */
+const TOOL_SCOPES = {
+  motorical_send_email: ['send:transactional'],
+  motorical_integrate_send: ['send:transactional'],
+  motorical_get_message: ['read:analytics'],
+  motorical_get_message_events: ['read:analytics'],
+  motorical_wait_for_outcome: ['read:analytics'],
+  motorical_get_send_status: ['read:analytics'],
+  motorical_list_motor_blocks: ['read:analytics'],
+  motorical_get_overview: ['read:analytics'],
+  motorical_get_daily_summary: ['read:analytics'],
+  motorical_get_metrics: ['read:analytics'],
+  motorical_get_deliverability: ['read:analytics'],
+  motorical_get_reputation: ['read:analytics'],
+  motorical_get_anomalies: ['read:analytics'],
+  motorical_get_providers: ['read:analytics'],
+  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_logs: ['read:analytics'],
+  motorical_get_message_by_smtp_id: ['read:analytics'],
+  motorical_get_config: ['manage:domains'],
+  motorical_get_domain_health: ['manage:domains'],
+  motorical_domain_list: ['read:domains'],
+  motorical_domain_add: ['manage:domains'],
+  motorical_domain_verify: ['manage:domains'],
+  motorical_domain_check_dns: ['manage:domains'],
+  motorical_sandbox_status: ['manage:sandbox'],
+  motorical_sandbox_provision: ['manage:sandbox'],
+  motorical_sandbox_convert: ['manage:sandbox'],
+  motorical_sandbox_allowlist_request: ['manage:sandbox'],
+  motorical_sandbox_allowlist_confirm: ['manage:sandbox'],
+  motorical_webhook_list: ['read:webhooks'],
+  motorical_webhook_create: ['manage:webhooks'],
+  motorical_webhook_update: ['manage:webhooks'],
+  motorical_webhook_delete: ['manage:webhooks'],
+  motorical_webhook_test: ['manage:webhooks'],
+  motorical_webhook_get_deliveries: ['read:webhooks'],
+  motorical_webhook_get_stats: ['read:webhooks'],
+};
+
+/** `|| []`: a tool with no entry (signup's own tool) contributes no scopes rather than throwing. */
+function scopesForTools(tools) {
+  return [...new Set(tools.flatMap((t) => TOOL_SCOPES[t] || []))];
+}
+
+const SERVER_SLUGS = {
+  main: 'motorical',
+  transactional: 'motorical_transactional',
+  analytics: 'motorical_analytics',
+  domains: 'motorical_domains',
+  sandbox: 'motorical_sandbox',
+  webhooks: 'motorical_webhooks',
+  signup: 'signup',
+};
+
+/** Every authenticated server, keyed by its canonical URI. signup is excluded — public, no token, never grantable. */
+const RESOURCE_SCOPES = Object.fromEntries(
+  Object.keys(SERVER_TOOLS)
+    .filter((key) => key !== 'signup')
+    .map((key) => [`${MCP_HOST}/v1/${SERVER_SLUGS[key]}/mcp`, scopesForTools(SERVER_TOOLS[key])])
+);
+
+module.exports = {
+  MCP_HOST, SERVER_TOOLS, TOOL_SCOPES, scopesForTools, RESOURCE_SCOPES,
+};