@adrata/adrata-mcp 1.0.0

package/access/resource-metadata.js

@@ -0,0 +1,167 @@
+/**
+ * OAuth 2.0 Protected Resource Metadata (RFC 9728) and audience-bound
+ * token validation (RFC 8707 Resource Indicators) for the exposed Adrata
+ * MCP server.
+ *
+ * The MCP HTTP transport is an OAuth *resource server*. Per the 2025-06-18
+ * MCP authorization spec it MUST:
+ *   - publish `/.well-known/oauth-protected-resource` describing itself and
+ *     the authorization server(s) that mint tokens for it (RFC 9728), and
+ *   - validate that every presented access token was issued *for this
+ *     resource* (RFC 8707 audience binding) and REJECT tokens minted for a
+ *     different audience — i.e. never blindly pass a bearer token through.
+ *
+ * This module is pure/stateless so it can be unit-tested without a running
+ * transport. The transport wires it into request handling.
+ */
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+/**
+ * The authorization server that issues tokens for this MCP resource.
+ * Adrata's Rust API serves RFC 8414 metadata at
+ * `${AS}/.well-known/oauth-authorization-server`.
+ */
+export function authorizationServers() {
+  const raw = process.env.ADRATA_MCP_AUTHORIZATION_SERVER
+    || process.env.ADRATA_API_URL
+    || 'https://api.adrata.com';
+  return raw.split(',').map(s => s.trim()).filter(Boolean);
+}
+
+/**
+ * The canonical resource identifier for this MCP server. RFC 8707 clients
+ * send this as the `resource` parameter so the AS can bind the token's
+ * audience to it. Defaults to the REST MCP resource the Rust AS advertises.
+ */
+export function canonicalResource() {
+  if (process.env.ADRATA_MCP_RESOURCE) return process.env.ADRATA_MCP_RESOURCE.trim();
+  const as = authorizationServers()[0] || 'https://api.adrata.com';
+  return `${as.replace(/\/$/, '')}/api/v1/mcp`;
+}
+
+/**
+ * The set of audience values this resource server will accept on a token.
+ * Always includes:
+ *   - the Adrata AS default audience ("adrata"), which every OAuth access
+ *     token minted by the Rust API currently carries, and
+ *   - this server's canonical RFC 8707 resource URI.
+ * Extra values can be added via ADRATA_MCP_ACCEPTED_AUDIENCES (comma list).
+ */
+export function acceptedAudiences() {
+  const base = new Set(['adrata', canonicalResource()]);
+  const extra = process.env.ADRATA_MCP_ACCEPTED_AUDIENCES;
+  if (extra) for (const a of extra.split(',').map(s => s.trim()).filter(Boolean)) base.add(a);
+  return [...base];
+}
+
+/**
+ * Whether a token that carries NO audience claim at all is rejected.
+ * Strict mode (default off) rejects aud-less JWTs; the always-on rule is
+ * that a token whose aud is present but does NOT match is rejected.
+ */
+function strictAudienceEnforcement() {
+  return process.env.ADRATA_MCP_AUDIENCE_ENFORCEMENT === 'strict';
+}
+
+// ---------------------------------------------------------------------------
+// RFC 9728 metadata document
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the RFC 9728 protected-resource-metadata document for this server.
+ * @param {string} [selfUrl] - The metadata document's own URL, echoed back so
+ *   a discovering client can confirm it fetched the right resource metadata.
+ */
+export function protectedResourceMetadata(selfUrl) {
+  return {
+    resource: canonicalResource(),
+    authorization_servers: authorizationServers(),
+    // Must advertise every scope OAUTH_SCOPE requests. Discovery-driven clients
+    // build their authorize request from this list, so anything missing here is
+    // a scope they never ask for. `ai:base` is required by the AI tool
+    // dispatcher (POST /api/v1/ai-crm-tools/execute) — without it every
+    // dispatcher-backed tool (rank_people_by_icp, path-to-power, break-in
+    // targeting, ...) fails with HTTP 403 insufficient_scope.
+    scopes_supported: [
+      'read:companies', 'read:people', 'read:opportunities', 'read:actions',
+      'ai:base',
+      'write:crm', 'read:email', 'write:email', 'mcp:tools',
+    ],
+    bearer_methods_supported: ['header'],
+    resource_name: 'Adrata MCP Server',
+    resource_documentation: 'https://adrata.com/developers',
+    // MCP-specific hints for discovery clients.
+    mcp_protocol_versions: ['2025-06-18', '2025-03-26', '2024-11-05'],
+    ...(selfUrl ? { resource_metadata: selfUrl } : {}),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// JWT decoding (no signature verification — the AS/API verifies signatures)
+// ---------------------------------------------------------------------------
+
+/**
+ * Decode a JWT payload without verifying its signature. Returns null when the
+ * token is not a well-formed three-segment JWT (e.g. an opaque API key).
+ */
+export function decodeJwtPayload(token) {
+  if (typeof token !== 'string') return null;
+  const parts = token.split('.');
+  if (parts.length !== 3) return null;
+  try {
+    const b64 = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+    const pad = b64.length % 4 === 0 ? '' : '='.repeat(4 - (b64.length % 4));
+    const json = Buffer.from(b64 + pad, 'base64').toString('utf8');
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// RFC 8707 audience validation (no token passthrough)
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate that an access token is bound to this resource server's audience.
+ *
+ * Security property (confused-deputy / token-passthrough defense): a JWT whose
+ * `aud` claim is present but does NOT intersect this server's accepted
+ * audiences is REJECTED. A token minted for another resource/client therefore
+ * cannot be replayed against the Adrata MCP server.
+ *
+ * Opaque (non-JWT) tokens cannot be introspected locally and are deferred to
+ * the API, which verifies signature + audience server-side on every call.
+ *
+ * @param {string} token - The bearer token.
+ * @param {{ accepted?: string[] }} [opts]
+ * @returns {{ valid: boolean, reason?: string, audience?: string[]|string }}
+ */
+export function validateTokenAudience(token, opts = {}) {
+  if (!token) return { valid: false, reason: 'missing_token' };
+
+  const accepted = opts.accepted || acceptedAudiences();
+  const payload = decodeJwtPayload(token);
+
+  // Opaque token — defer to the authorization server / API for verification.
+  if (!payload) return { valid: true, reason: 'opaque_token_deferred' };
+
+  const aud = payload.aud;
+  const audList = aud == null ? [] : Array.isArray(aud) ? aud : [aud];
+
+  if (audList.length === 0) {
+    // Token has no audience binding at all.
+    return strictAudienceEnforcement()
+      ? { valid: false, reason: 'missing_audience' }
+      : { valid: true, reason: 'no_audience_claim', audience: [] };
+  }
+
+  const match = audList.some(a => accepted.includes(a));
+  if (!match) {
+    return { valid: false, reason: 'audience_mismatch', audience: audList };
+  }
+  return { valid: true, audience: audList };
+}

package/access/tiers.js

@@ -0,0 +1,422 @@
+/**
+ * Tool tier definitions for Adrata MCP Server.
+ *
+ * Each tool is tagged as 'free', 'pro', or 'enterprise'.
+ *   - free: available without any API key
+ *   - pro: requires ADRATA_API_KEY
+ *   - enterprise: requires OAuth bearer token (workspace connection)
+ */
+
+export const TIERS = {
+  FREE: 'free',
+  PRO: 'pro',
+  ENTERPRISE: 'enterprise',
+};
+
+/**
+ * Map of tool name -> required tier.
+ * Tools not listed here fail closed to 'enterprise' (see getToolTier).
+ */
+export const TOOL_TIERS = {
+  // --- FREE tier: workspace connection (available to all tiers) ---
+  connect_workspace: TIERS.FREE,
+  disconnect_workspace: TIERS.FREE,
+  workspace_status: TIERS.FREE,
+  // Multi-workspace navigation. A user who administers more than one workspace
+  // (e.g. an agency or a founder across two tenants) could not previously see
+  // or reach a second workspace from the CLI at all.
+  list_workspaces: TIERS.ENTERPRISE,
+  switch_workspace: TIERS.ENTERPRISE,
+  adrata_api_catalog: TIERS.FREE,
+  paper_app_audit: TIERS.FREE,
+  adrata_desktop_app_audit: TIERS.FREE,
+
+  // --- FREE tier: tools that genuinely work with NO API key ---
+  // find_company/find_person are Claude-training-data prompts (no API call),
+  // get_demo_availability/schedule_demo use Cal.com (no Adrata auth), and
+  // describe_fields returns a local schema.
+  find_company: TIERS.FREE,
+  find_person: TIERS.FREE,
+  get_demo_availability: TIERS.FREE,
+  schedule_demo: TIERS.FREE,
+  describe_fields: TIERS.FREE,
+
+  // --- PRO tier: authenticated API reads. These were mislabeled FREE, which
+  // advertised tools that always 401'd for unauthenticated users. ---
+  search_companies: TIERS.PRO,
+  search_people: TIERS.PRO,
+  search_emails: TIERS.PRO,
+  get_email: TIERS.PRO,
+  count_emails: TIERS.PRO,
+  check_inbox: TIERS.PRO,
+  find_or_create_person: TIERS.PRO,
+  find_or_create_company: TIERS.PRO,
+  list_custom_fields: TIERS.PRO,
+  search_leads: TIERS.PRO,
+
+  // --- FREE tier: morning brief (free=teaser, pro+=full brief) ---
+  morning_brief: TIERS.FREE,
+
+  // --- FREE tier: billing tools (available at all tiers) ---
+  upgrade_account: TIERS.FREE,
+  check_subscription: TIERS.FREE,
+
+  // --- FREE tier: memory tools (free=local, pro+=server-side) ---
+  save_memory: TIERS.FREE,
+  recall: TIERS.FREE,
+  who_am_i: TIERS.FREE,
+  forget: TIERS.FREE,
+
+  // --- PRO tier: intelligence, analytics, enrichment, coaching ---
+  get_company: TIERS.PRO,
+  get_person: TIERS.PRO,
+  get_opportunity: TIERS.PRO,
+  get_action: TIERS.PRO,
+  enrich_company: TIERS.PRO,
+  enrich_person: TIERS.PRO,
+  get_intent_signals: TIERS.PRO,
+  list_customer_signals: TIERS.PRO,
+  get_deal_authority: TIERS.PRO,
+  get_competitor_intel: TIERS.PRO,
+  get_pipeline_metrics: TIERS.PRO,
+  get_forecast_data: TIERS.PRO,
+  get_activity_summary: TIERS.PRO,
+  // Finance installed base + Adrata Cloud reads. Authenticated workspace data,
+  // so PRO at minimum — never FREE, which would advertise a tool that always 401s.
+  get_installed_base: TIERS.PRO,
+  get_company_invoices: TIERS.PRO,
+  get_cloud_records: TIERS.PRO,
+  get_speedrun_list: TIERS.PRO,
+  get_priority_pursuits: TIERS.PRO,
+  score_company_icp: TIERS.PRO,
+  list_icp_profiles: TIERS.PRO,
+  get_icp_distribution: TIERS.PRO,
+  count_records: TIERS.PRO,
+  list_meetings: TIERS.PRO,
+  get_meeting: TIERS.PRO,
+  get_meeting_summary: TIERS.PRO,
+  get_meeting_action_items: TIERS.PRO,
+  list_actions: TIERS.PRO,
+  list_overdue_actions: TIERS.PRO,
+  list_today_actions: TIERS.PRO,
+  list_notes: TIERS.PRO,
+  log_interaction: TIERS.PRO,
+
+  // --- ENTERPRISE tier: CRM CRUD, sequences, campaigns, admin, bulk ---
+  create_company: TIERS.ENTERPRISE,
+  update_company: TIERS.ENTERPRISE,
+  delete_company: TIERS.ENTERPRISE,
+  create_person: TIERS.ENTERPRISE,
+  update_person: TIERS.ENTERPRISE,
+  delete_person: TIERS.ENTERPRISE,
+  create_opportunity: TIERS.ENTERPRISE,
+  update_opportunity: TIERS.ENTERPRISE,
+  delete_opportunity: TIERS.ENTERPRISE,
+  create_action: TIERS.ENTERPRISE,
+  update_action: TIERS.ENTERPRISE,
+  complete_action: TIERS.ENTERPRISE,
+  delete_action: TIERS.ENTERPRISE,
+  create_note: TIERS.ENTERPRISE,
+  update_note: TIERS.ENTERPRISE,
+  delete_note: TIERS.ENTERPRISE,
+  get_company_people: TIERS.ENTERPRISE,
+  get_company_opportunities: TIERS.ENTERPRISE,
+  get_company_actions: TIERS.ENTERPRISE,
+  search_opportunities: TIERS.ENTERPRISE,
+  list_buyer_groups: TIERS.ENTERPRISE,
+  get_buyer_group: TIERS.ENTERPRISE,
+  create_buyer_group: TIERS.ENTERPRISE,
+  add_buyer_group_member: TIERS.ENTERPRISE,
+  get_buyer_group_members: TIERS.ENTERPRISE,
+  update_buyer_group: TIERS.ENTERPRISE,
+  update_buyer_group_member: TIERS.ENTERPRISE,
+  remove_buyer_group_member: TIERS.ENTERPRISE,
+  delete_buyer_group: TIERS.ENTERPRISE,
+  bulk_delete_buyer_groups: TIERS.ENTERPRISE,
+  list_company_lists: TIERS.ENTERPRISE,
+  create_company_list: TIERS.ENTERPRISE,
+  get_company_list: TIERS.ENTERPRISE,
+  add_to_company_list: TIERS.ENTERPRISE,
+  list_intro_requests: TIERS.ENTERPRISE,
+  get_intro_pipeline: TIERS.ENTERPRISE,
+  create_intro_request: TIERS.ENTERPRISE,
+  update_intro_request: TIERS.ENTERPRISE,
+  find_intro_path: TIERS.PRO,
+  get_network_stats: TIERS.PRO,
+  list_agent_tasks: TIERS.ENTERPRISE,
+  create_agent_task: TIERS.ENTERPRISE,
+  get_agent_task: TIERS.ENTERPRISE,
+  cancel_agent_task: TIERS.ENTERPRISE,
+  list_webhook_events: TIERS.PRO,
+  list_webhooks: TIERS.ENTERPRISE,
+  create_webhook: TIERS.ENTERPRISE,
+  update_webhook: TIERS.ENTERPRISE,
+  delete_webhook: TIERS.ENTERPRISE,
+  test_webhook: TIERS.ENTERPRISE,
+  list_webhook_deliveries: TIERS.ENTERPRISE,
+  get_webhook_delivery: TIERS.ENTERPRISE,
+  replay_webhook_delivery: TIERS.ENTERPRISE,
+  list_campaigns: TIERS.ENTERPRISE,
+  get_campaign: TIERS.ENTERPRISE,
+  list_sequences: TIERS.ENTERPRISE,
+  get_sequence: TIERS.ENTERPRISE,
+  list_users: TIERS.ENTERPRISE,
+  get_user: TIERS.ENTERPRISE,
+  get_current_user: TIERS.ENTERPRISE,
+  adrata_api_request: TIERS.ENTERPRISE,
+  adrata_ai_tool_catalog: TIERS.ENTERPRISE,
+  adrata_ai_tool_execute: TIERS.ENTERPRISE,
+  // Sloan (AI executive assistant) — same governed dispatcher path as
+  // adrata_ai_tool_execute, so same tier.
+  sloan_status: TIERS.ENTERPRISE,
+  sloan_handoff: TIERS.ENTERPRISE,
+  configure_sloan: TIERS.ENTERPRISE,
+  get_account_read: TIERS.ENTERPRISE,
+  build_pursuit_command_center: TIERS.ENTERPRISE,
+  rank_paths_to_power: TIERS.ENTERPRISE,
+  recommend_deal_move: TIERS.ENTERPRISE,
+  list_external_pipelines: TIERS.ENTERPRISE,
+  list_external_pipeline_members: TIERS.ENTERPRISE,
+  import_external_pipeline_members: TIERS.ENTERPRISE,
+  list_external_companies: TIERS.ENTERPRISE,
+  import_external_companies: TIERS.ENTERPRISE,
+  rank_companies_by_icp: TIERS.ENTERPRISE,
+  rank_people_by_icp: TIERS.ENTERPRISE,
+  check_batch_import_status: TIERS.ENTERPRISE,
+  move_pipeline_card: TIERS.ENTERPRISE,
+
+  // --- ENTERPRISE tier: Starfield work boards ---
+  // Every one of these reads or mutates real workspace records through the
+  // governed API, so none can work without a workspace connection. Listing a
+  // read as FREE here would advertise a tool that always 401s — the exact
+  // mislabelling the PRO block above was written to correct.
+  // "What is assigned to me" needs a real workspace connection twice over: the
+  // cards are workspace records, and the caller's identity — the whole point of
+  // the tool — only exists on an OAuth token.
+  list_my_work_items: TIERS.ENTERPRISE,
+  list_work_boards: TIERS.ENTERPRISE,
+  get_work_board: TIERS.ENTERPRISE,
+  get_work_item: TIERS.ENTERPRISE,
+  get_work_item_history: TIERS.ENTERPRISE,
+  get_work_item_comments: TIERS.ENTERPRISE,
+  get_work_board_rollup: TIERS.ENTERPRISE,
+  list_work_board_rollups: TIERS.ENTERPRISE,
+  move_work_item: TIERS.ENTERPRISE,
+  set_work_item_tag: TIERS.ENTERPRISE,
+  set_work_item_kind: TIERS.ENTERPRISE,
+  create_work_item: TIERS.ENTERPRISE,
+  comment_on_work_item: TIERS.ENTERPRISE,
+  flag_work_item: TIERS.ENTERPRISE,
+
+  // --- ENTERPRISE tier: Paper desktop app surfaces ---
+  paper_list_documents: TIERS.ENTERPRISE,
+  paper_get_document: TIERS.ENTERPRISE,
+  paper_create_document: TIERS.ENTERPRISE,
+  paper_update_document: TIERS.ENTERPRISE,
+  paper_archive_document: TIERS.ENTERPRISE,
+  paper_delete_document: TIERS.ENTERPRISE,
+  paper_list_shares: TIERS.ENTERPRISE,
+  paper_create_share: TIERS.ENTERPRISE,
+  paper_revoke_share: TIERS.ENTERPRISE,
+  paper_resolve_share: TIERS.ENTERPRISE,
+  paper_list_tasks: TIERS.ENTERPRISE,
+  paper_create_task: TIERS.ENTERPRISE,
+  paper_update_task: TIERS.ENTERPRISE,
+  paper_list_calendar_events: TIERS.ENTERPRISE,
+  paper_create_calendar_event: TIERS.ENTERPRISE,
+  paper_list_email_threads: TIERS.ENTERPRISE,
+  paper_get_email_thread: TIERS.ENTERPRISE,
+  paper_send_email: TIERS.ENTERPRISE,
+  paper_get_company: TIERS.ENTERPRISE,
+
+  // --- ENTERPRISE tier: enterprise-only tools (bulk, export, admin) ---
+  bulk_import: TIERS.ENTERPRISE,
+  export_data: TIERS.ENTERPRISE,
+  manage_custom_fields: TIERS.ENTERPRISE,
+  get_workspace_settings: TIERS.ENTERPRISE,
+
+  // --- ENTERPRISE tier: email infrastructure (domains, mailboxes, sequences) ---
+  search_domains: TIERS.ENTERPRISE,
+  purchase_domain: TIERS.ENTERPRISE,
+  setup_domain: TIERS.ENTERPRISE,
+  verify_domain: TIERS.ENTERPRISE,
+  list_domains: TIERS.ENTERPRISE,
+  create_email_account: TIERS.ENTERPRISE,
+  list_email_accounts: TIERS.ENTERPRISE,
+  warmup_email: TIERS.ENTERPRISE,
+  get_email_health: TIERS.ENTERPRISE,
+  create_sequence: TIERS.ENTERPRISE,
+  list_sequences_full: TIERS.ENTERPRISE,
+  add_sequence_step: TIERS.ENTERPRISE,
+  activate_sequence: TIERS.ENTERPRISE,
+  pause_sequence: TIERS.ENTERPRISE,
+  get_sequence_analytics: TIERS.ENTERPRISE,
+  enroll_contacts: TIERS.ENTERPRISE,
+
+  // --- PARTNER ECOSYSTEM: reads are pro, every write is enterprise ---
+  // These previously had no entries at all and silently fell back to 'pro',
+  // which left partner WRITES (attribution, consumption, approval) one tier
+  // below every other CRM write. Reads stay pro to match the other
+  // workspace-read surfaces (get_company, get_pipeline_metrics, ...).
+  list_partners: TIERS.PRO,
+  get_partner: TIERS.PRO,
+  rank_partners_for_account: TIERS.PRO,
+  get_partner_revenue: TIERS.PRO,
+  list_partner_attributions: TIERS.PRO,
+  list_strategic_work_streams: TIERS.PRO,
+  list_executive_partner_meetings: TIERS.PRO,
+  list_partner_consumption: TIERS.PRO,
+  get_partner_consumption_rollup: TIERS.PRO,
+  create_partner: TIERS.ENTERPRISE,
+  update_partner: TIERS.ENTERPRISE,
+  delete_partner: TIERS.ENTERPRISE,
+  attribute_partner_to_deal: TIERS.ENTERPRISE,
+  approve_partner_attribution: TIERS.ENTERPRISE,
+  create_strategic_work_stream: TIERS.ENTERPRISE,
+  create_executive_partner_meeting: TIERS.ENTERPRISE,
+  record_partner_consumption: TIERS.ENTERPRISE,
+
+  // --- PRO tier: access graph / path-to-power intelligence reads ---
+  get_access_graph_projection: TIERS.PRO,
+  get_access_score: TIERS.PRO,
+  get_path_to_power: TIERS.PRO,
+
+  // --- PRO tier: enrichment read (same tier as enrich_company) ---
+  get_company_firmographics: TIERS.PRO,
+
+  // --- PRO tier: Matrix analytics (read-only; module documents "Pro tier").
+  // registerGetTool registers each surface under BOTH a dotted and an
+  // underscore alias, and both names hit the same tier gate. ---
+  ask_matrix: TIERS.PRO,
+  get_matrix_anomalies: TIERS.PRO,
+  get_matrix_deal_probability: TIERS.PRO,
+  get_matrix_digest_preview: TIERS.PRO,
+  get_matrix_recommended_actions: TIERS.PRO,
+  'analytics.matrix.nl_ask': TIERS.PRO,
+  matrix_nl_ask: TIERS.PRO,
+  'analytics.matrix.anomalies_feed': TIERS.PRO,
+  matrix_anomalies_feed: TIERS.PRO,
+  'analytics.matrix.forecast_commit_best_worst': TIERS.PRO,
+  matrix_forecast_commit_best_worst: TIERS.PRO,
+  'analytics.matrix.forecast_multi_model_consensus': TIERS.PRO,
+  matrix_forecast_multi_model_consensus: TIERS.PRO,
+  'analytics.matrix.market_competitor_deal_coaching': TIERS.PRO,
+  matrix_market_competitor_deal_coaching: TIERS.PRO,
+  'analytics.matrix.market_competitor_pulse': TIERS.PRO,
+  matrix_market_competitor_pulse: TIERS.PRO,
+  'analytics.matrix.people_causal_lift': TIERS.PRO,
+  matrix_people_causal_lift: TIERS.PRO,
+  'analytics.matrix.people_single_thread_risk': TIERS.PRO,
+  matrix_people_single_thread_risk: TIERS.PRO,
+  'analytics.matrix.pipeline_deal_health_queue': TIERS.PRO,
+  matrix_pipeline_deal_health_queue: TIERS.PRO,
+  'analytics.matrix.pipeline_snapshot_diff': TIERS.PRO,
+  matrix_pipeline_snapshot_diff: TIERS.PRO,
+
+  // --- PRO tier: knowledge hub (module documents "Pro tier") ---
+  search_knowledge: TIERS.PRO,
+  get_account_wiki: TIERS.PRO,
+  create_knowledge_file: TIERS.PRO,
+  link_file_to_entity: TIERS.PRO,
+
+  // --- PRO tier: extensibility / workflow authoring. These were on the 'pro'
+  // fallback; the tier is now explicit. Writes stay governed by the headless
+  // operation policy (dry-run default + control-plane review), not by tier. ---
+  inspect_provider_catalog: TIERS.PRO,
+  get_provider_connect_plan: TIERS.PRO,
+  list_provider_catalog: TIERS.PRO,
+  list_provider_endpoints: TIERS.PRO,
+  add_provider_action_column: TIERS.PRO,
+  test_provider_credential: TIERS.PRO,
+  request_provider_action_execution: TIERS.PRO,
+  request_deployment: TIERS.PRO,
+  submit_adrata_command: TIERS.PRO,
+  draft_workflow: TIERS.PRO,
+  validate_workflow_draft: TIERS.PRO,
+  dry_run_workflow: TIERS.PRO,
+  request_workflow_deployment: TIERS.PRO,
+  replay_workflow_run: TIERS.PRO,
+  validate_extension_manifest: TIERS.PRO,
+  validate_integration_manifest: TIERS.PRO,
+
+  // --- ANALYTICS: local dashboard (free), server-side (pro+) ---
+  get_mcp_analytics: TIERS.FREE,
+  track_conversion: TIERS.PRO,
+
+  // --- COMPOSITE TOOLSETS: always-loaded (free tier) ---
+  list_toolsets: TIERS.FREE,
+  enable_toolset: TIERS.FREE,
+  get_demo_availability: TIERS.FREE,
+  // find_company, find_person already mapped above
+
+  // --- COMPOSITE TOOLSETS: prospecting (pro tier) ---
+  qualify_company: TIERS.PRO,
+  research_company: TIERS.PRO,
+  research_person: TIERS.PRO,
+  // get_speedrun_list already mapped above
+  discover_prospects: TIERS.PRO,
+  get_next_contacts: TIERS.PRO,
+
+  // --- COMPOSITE TOOLSETS: intelligence (pro tier) ---
+  get_competitive_intel: TIERS.PRO,
+  get_meeting_brief: TIERS.PRO,
+  get_deal_coaching: TIERS.PRO,
+  get_signals_dashboard: TIERS.PRO,
+  get_forecast: TIERS.PRO,
+
+  // --- COMPOSITE TOOLSETS: outreach (pro/enterprise tier) ---
+  draft_email: TIERS.PRO,
+  send_email: TIERS.ENTERPRISE,
+  reply_to_email: TIERS.ENTERPRISE,
+  manage_sequences: TIERS.ENTERPRISE,
+  get_outreach_analytics: TIERS.PRO,
+  get_network_paths: TIERS.PRO,
+  search_emails_composite: TIERS.PRO,
+  get_email_thread: TIERS.PRO,
+
+  // --- COMPOSITE TOOLSETS: crm (enterprise tier) ---
+  manage_company: TIERS.ENTERPRISE,
+  manage_person: TIERS.ENTERPRISE,
+  manage_opportunity: TIERS.ENTERPRISE,
+  manage_activity: TIERS.ENTERPRISE,
+  manage_buyer_group: TIERS.ENTERPRISE,
+  get_action_history: TIERS.ENTERPRISE,
+
+  // --- COMPOSITE TOOLSETS: communications (enterprise tier) ---
+  make_call: TIERS.ENTERPRISE,
+  send_sms: TIERS.ENTERPRISE,
+  get_call_transcript: TIERS.ENTERPRISE,
+  check_calendar: TIERS.ENTERPRISE,
+  schedule_meeting: TIERS.ENTERPRISE,
+
+  // --- COMPOSITE TOOLSETS: infrastructure (enterprise tier) ---
+  manage_domains: TIERS.ENTERPRISE,
+  manage_mailboxes: TIERS.ENTERPRISE,
+  get_deliverability: TIERS.ENTERPRISE,
+  connect_provider: TIERS.ENTERPRISE,
+  manage_workspace: TIERS.ENTERPRISE,
+  manage_data: TIERS.ENTERPRISE,
+};
+
+/**
+ * Get the required tier for a tool.
+ *
+ * Unregistered tools default to the MOST restrictive tier (enterprise), never
+ * 'pro': a permissive fallback is how ~20 partner tools — including writes —
+ * silently shipped one tier below every other CRM write. A registry test
+ * asserts every registered tool has an explicit entry, so this fallback only
+ * exists as a fail-closed guard for future omissions.
+ */
+export function getToolTier(toolName) {
+  return TOOL_TIERS[toolName] || TIERS.ENTERPRISE;
+}
+
+/**
+ * Tier hierarchy: enterprise > pro > free.
+ * Returns true if userTier >= requiredTier.
+ */
+const TIER_RANK = { [TIERS.FREE]: 0, [TIERS.PRO]: 1, [TIERS.ENTERPRISE]: 2 };
+
+export function tierSatisfies(userTier, requiredTier) {
+  return (TIER_RANK[userTier] ?? 0) >= (TIER_RANK[requiredTier] ?? 0);
+}