gmcp 0.5.0

data/config/capabilities.yml

@@ -0,0 +1,148 @@
+# Capability manifest for the GMCP MCP server.
+#
+# SOURCE OF TRUTH for what GMCP can do. GMCP::Capabilities loads from here, and
+# spec/gmcp/capability_manifest_spec.rb asserts that every capability declared
+# here is claimed by exactly the tools listed and vice versa — so the manifest
+# cannot drift from the code without the suite going red. Capabilities should
+# be declared by the connector, never inferred; a declaration that can drift is
+# worse than an inference, because it reads as authoritative while being
+# wrong. The drift spec is what makes this file a fact about the connector
+# rather than a claim by it.
+#
+# A static file (rather than a tool) also lets a registration UI read what a
+# connector COULD do without spawning it first.
+#
+# credential_source says where a connector's credential lives:
+# local_file | keychain | delegated | none. GMCP's OAuth tokens are local_file,
+# at ~/.config/gmcp/<account>/token.yaml. Voice is `delegated`: its session is
+# held by an application GMCP does not run (Chrome), though GMCP picks the
+# Chrome profile signed in as the requested account, so the principal is still
+# constrained.
+#
+# ── account_scoping ────────────────────────────────────────────────────────
+#
+# One GMCP process serves several connectors, and they do not share account
+# semantics. Each declares which it has:
+#
+#   enforced — GMCP_ACCOUNTS constrains which principal this connector reaches.
+#              A grant's connector_account means what it says.
+#
+#   ignored  — GMCP_ACCOUNTS does NOT constrain this connector. The principal is
+#              resolved at call time by something outside GMCP. A grant's
+#              connector_account is DECORATIVE for it: it names an account that
+#              constrains nothing.
+#
+# No connector is `ignored` today; the value stays so that one which cannot be
+# scoped is forced to say so rather than look normal. The safety property of the grant model is that the account column always
+# constrains; a connector that quietly violates that has to say so in a field a
+# UI can read, not in a comment. Render an `ignored` grant as the principal it
+# actually reaches, never as the account named on the row.
+
+provider: gmcp
+
+connectors:
+  # ── the server itself ────────────────────────────────────────────────────
+  - name: gmcp
+    account_scoping: enforced
+    credential_source: local_file
+    description: GMCP's own administrative surface.
+    capabilities:
+      - name: gmcp.authorize
+        description: >-
+          Start the OAuth consent flow for a configured Google account. Opens a
+          browser window on the machine running GMCP.
+        tools: [gmcp_authorize]
+
+  # ── Gmail ────────────────────────────────────────────────────────────────
+  - name: gmail
+    account_scoping: enforced
+    credential_source: local_file
+    description: Google Mail, per authorized account.
+    capabilities:
+      - name: gmail.read
+        description: Search and read mail, and list labels. No mutation of any kind.
+        tools: [gmail_search, gmail_get_message, gmail_list_labels,
+                gmail_list_attachments, gmail_unsubscribe_info]
+
+      - name: gmail.modify_labels
+        description: >-
+          Add and remove labels on a message. Archiving is included because in
+          Gmail archiving IS removing the INBOX label — these tools reach labels
+          and nothing else.
+        tools: [gmail_archive_message, gmail_label_message,
+                gmail_batch_archive, gmail_batch_modify]
+
+      - name: gmail.trash
+        description: Move a message to the trash. Separate from modify_labels because it is destructive.
+        tools: [gmail_trash_message, gmail_batch_trash]
+
+      - name: gmail.send
+        description: >-
+          Send mail out into the world, or stage it as a draft. The highest-risk
+          capability here: the only one whose effects reach third parties.
+        tools: [gmail_send, gmail_create_draft, gmail_reply]
+
+      - name: gmail.download
+        description: >-
+          Write attachment bytes to a local directory. Separate from gmail.read
+          because reading headers into a response is not the same act as
+          creating files on the machine GMCP runs on.
+        tools: [gmail_download_attachment]
+
+      - name: gmail.unsubscribe
+        description: >-
+          Send an RFC 8058 one-click unsubscribe to the URL in a message's own
+          List-Unsubscribe header. Separate because it leaves Google entirely
+          and tells a third party the address is live.
+        tools: [gmail_unsubscribe]
+
+  # ── Calendar ─────────────────────────────────────────────────────────────
+  - name: google_calendar
+    account_scoping: enforced
+    credential_source: local_file
+    description: Google Calendar, per authorized account.
+    capabilities:
+      - name: calendar.read
+        description: List calendars and read events. No mutation.
+        tools: [calendar_list_calendars, calendar_list_events, calendar_get_event]
+
+      - name: calendar.write
+        description: >-
+          Create and update events, and respond to invitations. RSVP is here
+          rather than under read because it is visible to other attendees.
+        tools: [calendar_create_event, calendar_update_event, calendar_rsvp]
+
+      - name: calendar.delete
+        description: Delete an event. Separate from write because it is destructive.
+        tools: [calendar_delete_event]
+
+  # ── Drive ────────────────────────────────────────────────────────────────
+  - name: drive
+    account_scoping: enforced
+    credential_source: local_file
+    description: Google Drive, per authorized account. Read-only; GMCP exposes no Drive writes.
+    capabilities:
+      - name: drive.read
+        description: Search Drive, list folders, and read file contents.
+        tools: [drive_search, drive_list_folder, drive_read_file]
+
+  # ── Voice ────────────────────────────────────────────────────────────────
+  - name: voice
+    account_scoping: enforced
+    credential_source: delegated
+    description: >-
+      Google Voice, per account. There is no usable OAuth path, so the session
+      is read from the Chrome profile signed in as the requested account —
+      found by email in Chrome's profile list, never by guessing — and an
+      account with no such profile has no Voice. GMCP_ACCOUNTS constrains it
+      like any other connector.
+    capabilities:
+      - name: voice.read
+        description: >-
+          List and search Voice messages, calls, and voicemail, and report an
+          account's Voice number.
+        tools: [voice_account, voice_list, voice_search]
+
+      - name: voice.modify
+        description: Mark a Voice thread read. Touches the read flag and nothing else.
+        tools: [voice_mark_read]

data/config/scopes.yml

@@ -0,0 +1,14 @@
+# OAuth scope definitions per service.
+# Used by GMCP::Auth when requesting consent.
+
+gmail:
+  - https://www.googleapis.com/auth/gmail.modify
+
+calendar:
+  - https://www.googleapis.com/auth/calendar.events
+
+drive:
+  - https://www.googleapis.com/auth/drive.readonly
+
+voice:
+  - https://www.googleapis.com/auth/userinfo.email

data/lib/gmcp/account_registry.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module GMCP
+  class AccountRegistry
+    attr_reader :accounts
+
+    def initialize(accounts:)
+      @accounts = accounts
+      @apis = {}
+      ApiBinding.install!
+    end
+
+    def load_authorized_accounts!
+      accounts.each { |account| load_account(account) }
+    end
+
+    def reinitialize!(account:)
+      @apis[account] = Apis.build_for_account(account:)
+    end
+
+    def default_account
+      accounts.first
+    end
+
+    def account_description
+      accounts.length == 1 ? default_account : accounts.join(', ')
+    end
+
+    # The API set for an account, or nil if it is unknown or unauthorized.
+    def apis_for(account = nil)
+      account ||= default_account
+      account && @apis[account]
+    end
+
+    # Runs the block with this account bound, restoring whatever was bound
+    # before. Returns [error_message, nil] or [nil, block_result] so the caller
+    # can tell an auth failure from a legitimately nil result.
+    def scoped(account = nil)
+      apis = apis_for(account)
+      return [authorization_message(account || default_account), nil] unless apis
+
+      [nil, ApiBinding.with(apis) { yield }]
+    end
+
+    def authorization_message(account)
+      if account && accounts.include?(account)
+        "Not authorized for #{account}. Call gmcp_authorize(account: \"#{account}\")."
+      elsif account
+        "Unknown account #{account.inspect}. Configured: #{accounts.join(', ')}."
+      else
+        'Not authorized. Call gmcp_authorize.'
+      end
+    end
+
+    private
+
+    def load_account(account)
+      @apis[account] = Apis.build_for_account(account:)
+    rescue Auth::AuthRequired, Errno::ENOENT
+      nil # not authorized yet, or no credentials.json; gmcp_authorize reports which
+    rescue Signet::AuthorizationError, Google::Auth::AuthorizationError => e
+      # Refresh token revoked or expired. Don't crash the whole server —
+      # leave this account unbound and let the user re-authorize via gmcp_authorize.
+      warn "GMCP: stored token for #{account} is no longer valid (#{e.message[0, 120]}); call gmcp_authorize to reconnect"
+      nil
+    end
+  end
+end

data/lib/gmcp/api_binding.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module GMCP
+  # Per-fiber binding of models to a set of account APIs.
+  #
+  # him resolves `use_api` at request time and calls it if it responds to
+  # :call (him/lib/him/model/http.rb). Binding a *resolver* once therefore lets
+  # the API in effect change per fiber without ever mutating class state again.
+  #
+  # This is what makes it safe for one process to serve more than one account:
+  # writing the API onto the model class instead would let two concurrent
+  # requests for different accounts race on process-global state.
+  #
+  # Binding is fiber-local (Thread.current[]) rather than thread-local, so it
+  # holds under fiber schedulers as well as threads.
+  module ApiBinding
+    KEY = :gmcp_current_apis
+
+    # Deferred so autoload is not forced at require time.
+    MODELS = {
+      gmail:    -> { [Gmail::Message, Gmail::Label, Gmail::Draft] },
+      calendar: -> { [Calendar::Event, Calendar::Calendar] },
+      drive:    -> { [Drive::File] }
+    }.freeze
+
+    # Raised when a model issues a request with no account bound. Better than
+    # him's NoMethodError on nil, and better than silently reusing whatever the
+    # previous caller left behind.
+    class NotBound < StandardError; end
+
+    class << self
+      # Idempotent — the resolvers only need installing once per process.
+      def install!
+        return if @installed
+
+        MODELS.each do |service, models|
+          resolver = -> { fetch(service) }
+          models.call.each { |model| model.use_api(resolver) }
+        end
+        @installed = true
+      end
+
+      def current
+        Thread.current[KEY]
+      end
+
+      def current=(apis)
+        Thread.current[KEY] = apis
+      end
+
+      # Scopes a binding to a block and restores whatever was in effect before,
+      # so a nested call cannot leak its account to its caller.
+      def with(apis)
+        previous = current
+        self.current = apis
+        yield
+      ensure
+        self.current = previous
+      end
+
+      def fetch(service)
+        apis = current
+        raise NotBound, "no account is bound on this fiber (wanted #{service})" if apis.nil?
+
+        apis[service] || raise(NotBound, "bound account has no #{service} API")
+      end
+
+      # Test seam.
+      def reset!
+        @installed = false
+        self.current = nil
+      end
+    end
+  end
+end

data/lib/gmcp/api_error.rb

@@ -0,0 +1,33 @@
+require 'json'
+
+module GMCP
+  # A Google API request that came back 4xx/5xx. Without this, him hands an
+  # error body back as if it were the resource, so a failed trash or send
+  # reported success and a missing message surfaced as NoMethodError on nil.
+  class ApiError < StandardError
+    attr_reader :status
+
+    def initialize(status, message)
+      @status = status
+      super("Google API error #{status}: #{message}")
+    end
+
+    # Sits next to the adapter so it sees the raw body before any JSON parsing.
+    class Middleware < Faraday::Middleware
+      def on_complete(env)
+        return if env[:status] < 400
+
+        raise ApiError.new(env[:status], message_from(env[:body]) || env[:reason_phrase] || 'request failed')
+      end
+
+      private
+
+      def message_from(body)
+        error = JSON.parse(body.to_s)['error']
+        error.is_a?(Hash) ? error['message'] : error
+      rescue JSON::ParserError
+        body.to_s[0, 200] unless body.to_s.empty?
+      end
+    end
+  end
+end

data/lib/gmcp/apis.rb

@@ -0,0 +1,46 @@
+require 'erb'
+
+module GMCP
+  module Apis
+    GMAIL_BASE    = 'https://gmail.googleapis.com/gmail/v1/users/me/'
+    CALENDAR_BASE = 'https://www.googleapis.com/calendar/v3/'
+    DRIVE_BASE    = 'https://www.googleapis.com/drive/v3/'
+
+    # Fails fast (AuthRequired, or a refresh error) when the account has no
+    # usable token, then resolves the access token per request so it is
+    # refreshed as it nears expiry.
+    # Joins path segments, escaping each. Calendar ids are email-like and
+    # holiday and contact calendars contain '#', which would otherwise end the
+    # path and send the request to the wrong resource.
+    def self.path(*segments)
+      segments.map { |s| ERB::Util.url_encode(s.to_s) }.join('/')
+    end
+
+    def self.build_for_account(account:)
+      Auth.credentials(account:)
+      build(token: -> { Auth.access_token(account:) })
+    end
+
+    # The adapter is a seam for specs, which run the real middleware stack
+    # against Faraday's :test adapter.
+    def self.build(token:, adapter: [Faraday.default_adapter])
+      {
+        gmail:    build_api(GMAIL_BASE,    token, adapter),
+        calendar: build_api(CALENDAR_BASE, token, adapter),
+        drive:    build_api(DRIVE_BASE,    token, adapter)
+      }
+    end
+
+    def self.build_api(base_url, token, adapter)
+      Him::API.new(url: base_url) do |conn|
+        conn.options.params_encoder = Faraday::FlatParamsEncoder # labelIds=a&labelIds=b, as Google expects
+        conn.request :json
+        conn.use BearerMiddleware, token: token
+        conn.use Him::Middleware::DefaultParseJSON
+        conn.use ApiError::Middleware
+        conn.adapter(*adapter)
+      end
+    end
+    private_class_method :build_api
+  end
+end

data/lib/gmcp/auth.rb

@@ -0,0 +1,189 @@
+require 'googleauth'
+require 'googleauth/token_store'
+require 'securerandom'
+require 'webrick'
+require 'yaml'
+
+module GMCP
+  module Auth
+    CONFIG_DIR = File.expand_path('~/.config/gmcp').freeze
+    DEFAULT_CREDENTIALS_PATH = File.join(CONFIG_DIR, 'credentials.json').freeze
+    CALLBACK_PATH  = '/oauth2callback'
+    AUTH_TIMEOUT   = 900
+    REFRESH_MARGIN = 60
+    # An email address, and nothing that could climb out of CONFIG_DIR.
+    ACCOUNT_FORMAT = /\A[^\s\/\\@]+@[^\s\/\\@]+\z/
+    AUTH_SUCCESS_HTML = '<html><body><h2>Authorized! You can close this tab.</h2></body></html>'
+    AUTH_FAILURE_HTML = '<html><body><h2>Authorization failed — no code returned.</h2></body></html>'
+
+    class AuthRequired < StandardError; end
+
+    # Refresh tokens are long-lived secrets: written owner-only, atomically, and
+    # never created as a side effect of a read. googleauth's FileTokenStore
+    # wraps YAML::Store, whose read transaction creates an empty file under the
+    # process umask, which left 0644 token.yaml files for accounts that were
+    # never authorized. The on-disk format is the same, so existing tokens load.
+    class TokenStore < Google::Auth::TokenStore
+      def initialize(path)
+        super()
+        @path = path
+      end
+
+      def load(id)
+        read[id]
+      end
+
+      def store(id, token)
+        write(read.merge(id => token))
+      end
+
+      def delete(id)
+        write(read.except(id))
+      end
+
+      private
+
+      def read
+        return {} unless File.size?(@path)
+
+        File.chmod(0o600, @path) unless (File.stat(@path).mode & 0o077).zero? # tighten older files
+        YAML.safe_load_file(@path) || {}
+      end
+
+      def write(data)
+        FileUtils.mkdir_p(File.dirname(@path), mode: 0o700)
+        tmp = "#{@path}.#{Process.pid}.tmp"
+        File.write(tmp, YAML.dump(data), perm: 0o600)
+        File.rename(tmp, @path)
+      end
+    end
+
+    class << self
+      def credentials_path
+        ENV.fetch('GMCP_CREDENTIALS_FILE', DEFAULT_CREDENTIALS_PATH)
+      end
+
+      def token_path(account)
+        raise ArgumentError, "not an email address: #{account.inspect}" unless account.to_s.match?(ACCOUNT_FORMAT)
+
+        File.join(CONFIG_DIR, account, 'token.yaml')
+      end
+
+      def scopes
+        @scopes ||= YAML.load_file(GMCP.root('config', 'scopes.yml')).values.flatten.freeze
+      end
+
+      # Live credentials for an account, refreshed when within REFRESH_MARGIN
+      # of expiry. Held per account so a refresh is shared by every request,
+      # and serialized so concurrent requests do not all refresh at once.
+      def credentials(account:)
+        lock.synchronize do
+          creds = (cache[account] ||= load_credentials(account))
+          creds.refresh! if creds.expires_within?(REFRESH_MARGIN)
+          creds
+        end
+      end
+
+      def access_token(account:)
+        credentials(account:).access_token
+      end
+
+      # Opens Google's consent page in a browser and returns its URL. The code
+      # exchange completes on a background thread when Google redirects to the
+      # loopback callback; exactly one of on_success / on_failure is called,
+      # unless the timeout passes first.
+      def authorize_interactive!(account:, on_success:, on_failure: nil, timeout: AUTH_TIMEOUT)
+        token_path(account) # validates before anything touches disk or network
+        state  = SecureRandom.urlsafe_base64(24)
+        server = WEBrick::HTTPServer.new(
+          BindAddress: '127.0.0.1', Port: 0,
+          Logger: WEBrick::Log.new(File::NULL), AccessLog: []
+        )
+        base_url = "http://127.0.0.1:#{server.config[:Port]}"
+        on_failure ||= ->(_acct, error) { warn "GMCP auth error: #{error.class}: #{error.message}" }
+
+        server.mount_proc(CALLBACK_PATH) do |req, res|
+          handle_callback(req, res, server:, state:, account:, base_url:, on_success:, on_failure:)
+        end
+        serve(server, timeout)
+
+        url = authorizer.get_authorization_url(base_url:, state:, login_hint: account)
+        open_browser(url)
+        url
+      end
+
+      # Test seam.
+      def reset!
+        @cache = @authorizer = @client_id = nil
+      end
+
+      private
+
+      def lock
+        @lock ||= Mutex.new
+      end
+
+      def cache
+        @cache ||= {}
+      end
+
+      def load_credentials(account)
+        raise AuthRequired, "No stored token for #{account.inspect}" unless File.size?(token_path(account))
+
+        authorizer(account).get_credentials(account) ||
+          raise(AuthRequired, "Stored token for #{account.inspect} lacks the required scopes")
+      end
+
+      def client_id
+        @client_id ||= Google::Auth::ClientId.from_file(credentials_path)
+      end
+
+      # One authorizer per token file; with no account, one for building the
+      # consent URL, which never reads or writes a token.
+      def authorizer(account = nil)
+        store = account ? TokenStore.new(token_path(account)) : TokenStore.new(File::NULL)
+        Google::Auth::UserAuthorizer.new(client_id, scopes, store)
+      end
+
+      # Requests that do not carry our state are ignored rather than ending the
+      # flow, so a stray or forged hit cannot cancel or hijack a sign-in.
+      def handle_callback(req, res, server:, state:, account:, base_url:, on_success:, on_failure:)
+        res['Content-Type'] = 'text/html'
+        unless req.query['state'] == state
+          res.status = 400
+          res.body = AUTH_FAILURE_HTML
+          return
+        end
+
+        code = req.query['code']
+        res.body = code ? AUTH_SUCCESS_HTML : AUTH_FAILURE_HTML
+        server.shutdown
+        return on_failure.call(account, AuthRequired.new(req.query['error'] || 'no code returned')) unless code
+
+        Thread.new do
+          authorizer(account).get_and_store_credentials_from_code(user_id: account, code:, base_url:)
+          lock.synchronize { cache.delete(account) }
+          on_success.call(account)
+        rescue StandardError => e
+          on_failure.call(account, e)
+        end
+      end
+
+      def serve(server, timeout)
+        Thread.new { server.start }
+        Thread.new do
+          sleep timeout
+          server.shutdown
+        end
+      end
+
+      def open_browser(url)
+        case RbConfig::CONFIG['host_os']
+        when /darwin/      then system('open', url)
+        when /linux/       then system('xdg-open', url)
+        when /mswin|mingw/ then system('start', url)
+        end
+      end
+    end
+  end
+end

data/lib/gmcp/bearer_middleware.rb

@@ -0,0 +1,17 @@
+module GMCP
+  # Sets the Authorization header from a token provider called per request, so
+  # a long-running server picks up refreshed access tokens instead of sending
+  # the one it started with until Google rejects it an hour later.
+  class BearerMiddleware < Faraday::Middleware
+    def initialize(app, token:)
+      super(app)
+      @token = token
+    end
+
+    def call(env)
+      token = @token.respond_to?(:call) ? @token.call : @token
+      env[:request_headers]['Authorization'] = "Bearer #{token}"
+      @app.call(env)
+    end
+  end
+end

data/lib/gmcp/calendar/calendar.rb

@@ -0,0 +1,16 @@
+module GMCP
+  module Calendar
+    class Calendar
+      include Him::Model
+
+      collection_path 'users/me/calendarList'
+      primary_key :id
+
+      parse_root_in_json true
+      root_element :items
+
+      attributes :id, :summary, :description, :timeZone, :primary, :accessRole,
+                 :backgroundColor, :foregroundColor
+    end
+  end
+end