ruze 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c05176b082da3e8a263b95baf98b6982b0bf1563686fd9c357b575d33c860e2e
-  data.tar.gz: a95ddfa50c47176f21bf7b36d5a6be61ec84f5ba8994abd99739f58fac2e292e
+  metadata.gz: 1fa802b8dceb6e72c4e9c04b3a0ee3fd0a1c70d2063b0ffae6d46398057b317d
+  data.tar.gz: 9976f664f420a5b351023f3d4bb8ef44947849c752aebbc0c0d8de402dd0a507
 SHA512:
-  metadata.gz: c48c8ac959d98088fca9d2028e281264a37be188a2a94e5bc5233751bf3d9e4463da88b2a4e7eaf7381a16f15448b55e4e0ccfbbce23ebb94bbc6b068e655e2e
-  data.tar.gz: 133d2f1b88778b4b01e56f03a1ba6dd629d7968a8030917ba39b14e71487ccb8e2bed733aaa60b7e402912457d75a9f24852f528e44127d93a838b455ec4e9c5
+  metadata.gz: 5b5e04039d1562360d0f237179555b5660e8f0d5369269723f343d689dd9f747c2ff184a6bd68331fa493bb9ae5f75e7801fdf55b8924928efe7fea1525f5691
+  data.tar.gz: 708613986c1f2f35bd215cc2a4099bc2487d7f456200643c8fba86ffef83b132e30a2cf2878337a15d0eb3236d8172a03bb97489f34abb152d2bbb55c7ecf08d

data/.env.test

@@ -7,3 +7,6 @@ KAMEREON_API_KEY=bar
 RENAULT_PERSON_ID=1234567890
 RENAULT_VIN=VF1AG000X12345678
 RENAULT_ACCOUNT_ID=0987654321
+
+RUZE_GMID=gmid.test
+RUZE_UCID=ucid.test

data/.github/workflows/main.yml

@@ -9,7 +9,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby: ['3.0', '3.1', '3.2', '3.3']
+        ruby: ['4.0']
 
     steps:
     - uses: actions/checkout@v3

data/.rubocop.yml

@@ -1,8 +1,11 @@
 AllCops:
-  TargetRubyVersion: 2.7
+  TargetRubyVersion: 4.0
   NewCops: enable
   SuggestExtensions: false
 
+Metrics/ClassLength:
+  Max: 170
+
 Metrics/MethodLength:
   Max: 20
 

data/Gemfile

@@ -20,3 +20,6 @@ gem 'dotenv'
 
 # Automatic Ruby code style checking tool. (https://github.com/rubocop/rubocop)
 gem 'rubocop'
+
+# Interactive Ruby console for bin/console (no longer a default gem since Ruby 4.0)
+gem 'irb'

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2021-2024 Georg Ledermann
+Copyright (c) 2021-2026 Georg Ledermann
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -38,27 +38,25 @@ export KAMEREON_API_KEY=...
 ## Usage
 
 ```ruby
-car = Ruze::Car.new('me@example.com', 'my-password')
+car = Ruze::Car.new('john@example.com', 'my-password')
 
 car.battery
 # {
-#                      "timestamp" => "2021-03-13T09:59:12Z",
-#                   "batteryLevel" => 66,
-#             "batteryTemperature" => 20,
-#                "batteryAutonomy" => 194,
-#                "batteryCapacity" => 0,
-#         "batteryAvailableEnergy" => 33,
-#                     "plugStatus" => 0,
-#                 "chargingStatus" => 0.0,
-#          "chargingRemainingTime" => 55,
-#     "chargingInstantaneousPower" => 0.0
+#                                   "timestamp" => "2026-03-13T09:59:12Z",
+#                                "batteryLevel" => 66,
+#                             "batteryAutonomy" => 194,
+#                                  "plugStatus" => 0,
+#                              "chargingStatus" => 0.0,
+#                       "chargingRemainingTime" => 55,
+#     "chargingRemainingTimeLastUpdateDateTime" => "2026-03-13T09:30:00Z"
 # }
 
 car.cockpit
 # {
 #     "fuelAutonomy" => 0.0,
 #     "fuelQuantity" => 0.0,
-#     "totalMileage" => 12345.67
+#     "totalMileage" => 12345.67,
+#        "timestamp" => "2026-03-13T09:59:12Z"
 # }
 
 car.location
@@ -66,11 +64,51 @@ car.location
 #       "gpsDirection" => nil,
 #        "gpsLatitude" => 50.12345678,
 #       "gpsLongitude" => 6.12345678,
-#     "lastUpdateTime" => "2021-03-12T11:43:18Z"
+#     "lastUpdateTime" => "2026-03-12T11:43:18Z"
 # }
 ```
 
 
+## Two-factor authentication
+
+Renault enforces two-factor authentication (2FA) on Gigya accounts, so a
+password alone is no longer enough to log in. RuZE handles this by establishing
+a *trusted device* once: after a single email verification, Renault remembers
+the device for about 30 days, during which logins succeed without a prompt.
+
+### One-time setup
+
+Trigger a verification code, confirm it with the 6-digit code Renault emails to
+your account, then read the resulting trusted-device pair:
+
+```ruby
+gigya = Ruze::Gigya.new('john@example.com', 'my-password')
+
+gigya.request_verification_code # emails a 6-digit code (returns nil if none is needed)
+
+gigya.verify_code('123456')
+
+gmid = gigya.device.gmid
+ucid = gigya.device.ucid
+# Store this gmid/ucid pair somewhere durable (env vars, a file, a database).
+```
+
+`Ruze::Device` keeps the pair in memory only, so persisting it is up to you. The
+pair stays valid across renewals, so you store it once.
+
+### Normal usage
+
+Seed a device with your stored pair and `Ruze::Car` logs in without prompting:
+
+```ruby
+device = Ruze::Device.new(gmid: gmid, ucid: ucid)
+car = Ruze::Car.new('john@example.com', 'my-password', device: device)
+```
+
+When the device is missing or has expired, login raises
+`Ruze::TwoFactorRequired` — repeat the one-time setup to renew it.
+
+
 ## Background
 
 Thanks to James Muscat (@jamesremuscat) for making PyZE, the Python client for Renault ZE API:
@@ -106,7 +144,7 @@ This project is not affiliated with, endorsed by, or connected to Renault. I acc
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 
-Copyright (c) 2021-2024 Georg Ledermann, released under the AGPL-3.0 License
+Copyright (c) 2021-2026 Georg Ledermann, released under the AGPL-3.0 License
 
 ## Code of Conduct
 

data/bin/console

@@ -1,14 +1,24 @@
 #!/usr/bin/env ruby
 
 require 'bundler/setup'
+require 'dotenv/load'
 require 'ruze'
 
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
+# Convenience for experimenting against the real API, using the credentials and
+# trusted device from your .env (RENAULT_EMAIL, RENAULT_PASSWORD, GIGYA_API_KEY,
+# KAMEREON_API_KEY, RUZE_GMID, RUZE_UCID):
+#
+#   car.battery
+#   car.cockpit
+#   car.location
+#
+def car
+  Ruze::Car.new(
+    ENV.fetch('RENAULT_EMAIL'),
+    ENV.fetch('RENAULT_PASSWORD'),
+    device: Ruze::Device.new(gmid: ENV.fetch('RUZE_GMID', nil), ucid: ENV.fetch('RUZE_UCID', nil))
+  )
+end
 
 require 'irb'
 IRB.start(__FILE__)

data/lib/ruze/car.rb

@@ -3,8 +3,8 @@ require_relative 'kamereon'
 
 module Ruze
   class Car
-    def initialize(email, password, vin = nil)
-      gigya = Ruze::Gigya.new(email, password)
+    def initialize(email, password, vin = nil, device: Ruze::Device.new)
+      gigya = Ruze::Gigya.new(email, password, device: device)
       @kamereon = Ruze::Kamereon.new(gigya.person_id, gigya.jwt, vin)
     end
 

data/lib/ruze/device.rb

@@ -0,0 +1,30 @@
+module Ruze
+  # Holds the Gigya trusted-device identity (gmid/ucid) that lets us skip the
+  # two-factor prompt on subsequent logins.
+  #
+  # This default implementation keeps the pair in memory only. For headless
+  # operation across process restarts, seed it from durable storage and persist
+  # the pair (see #gmid/#ucid) after a successful bootstrap:
+  #
+  #   device = Ruze::Device.new(gmid: stored_gmid, ucid: stored_ucid)
+  #   Ruze::Car.new(email, password, device: device)
+  class Device
+    def initialize(gmid: nil, ucid: nil)
+      @gmid = gmid
+      @ucid = ucid
+    end
+    attr_reader :gmid, :ucid
+
+    # Returns { gmid:, ucid: } or nil when no (complete) device is available.
+    def load
+      return nil if gmid.to_s.empty? || ucid.to_s.empty?
+
+      { gmid: gmid, ucid: ucid }
+    end
+
+    def save(gmid:, ucid:)
+      @gmid = gmid
+      @ucid = ucid
+    end
+  end
+end

data/lib/ruze/errors.rb

@@ -0,0 +1,8 @@
+module Ruze
+  class Error < StandardError; end
+
+  # Raised when Renault/Gigya requires two-factor authentication and no trusted
+  # device is available. Run the bootstrap flow (request_verification_code +
+  # verify_code) to establish a trusted device.
+  class TwoFactorRequired < Error; end
+end

data/lib/ruze/gigya.rb

@@ -1,68 +1,227 @@
 require 'net/http'
 require 'json'
+require_relative 'errors'
+require_relative 'device'
 
 module Ruze
   class Gigya
-    BASE_URL = 'https://accounts.eu1.gigya.com'.freeze
+    BASE_URL      = 'https://accounts.eu1.gigya.com'.freeze
+    SOCIALIZE_URL = 'https://socialize.eu1.gigya.com'.freeze
 
-    def initialize(email, password)
+    def initialize(email, password, device: Device.new)
       raise ArgumentError unless email.is_a?(String) && password.is_a?(String)
 
       @email = email
       @password = password
+      @device = device
     end
-    attr_reader :email, :password
+    attr_reader :email, :password, :device
 
     def person_id
-      @person_id ||= return_from Net::HTTP.post_form(
-        uri('/accounts.getAccountInfo'),
-        'ApiKey'      => api_key,
-        'login_token' => session_cookie_value
-      ), keys: %w[data personId]
+      @person_id ||= dig_from post(
+        "#{BASE_URL}/accounts.getAccountInfo",
+        { 'apiKey' => api_key, 'login_token' => session_cookie_value }
+      ), label: 'person_id', keys: %w[data personId]
     end
 
     def jwt
-      @jwt ||= return_from Net::HTTP.post_form(
-        uri('/accounts.getJWT'),
-        'ApiKey'      => api_key,
-        'login_token' => session_cookie_value,
-        'fields'      => 'data.personId,data.gigyaDataCenter',
-        'expiration'  => 900
-      ), keys: %w[id_token]
+      @jwt ||= dig_from post(
+        "#{BASE_URL}/accounts.getJWT",
+        { 'apiKey'      => api_key,
+          'login_token' => session_cookie_value,
+          'fields'      => 'data.personId,data.gigyaDataCenter',
+          'expiration'  => 900 }
+      ), label: 'jwt', keys: %w[id_token]
     end
 
+    # Logs in using the trusted device and returns the session cookie value.
+    # Raises TwoFactorRequired when Renault demands a fresh 2FA verification.
     def session_cookie_value
-      @session_cookie_value ||= return_from Net::HTTP.post_form(
-        uri('/accounts.login'),
-        'ApiKey'   => api_key,
-        'loginID'  => email,
-        'password' => password
-      ), keys: %w[sessionInfo cookieValue]
+      @session_cookie_value ||= login
+    end
+
+    # --- Two-factor bootstrap ------------------------------------------------
+    #
+    # The Gigya 2FA trusted-device flow below (initTFA -> getEmails ->
+    # sendVerificationCode -> completeVerification -> finalizeTFA -> re-login)
+    # was reverse-engineered by the renault-api community:
+    # https://github.com/hacf-fr/renault-api/issues/2132
+    #
+    # Run once interactively to establish a trusted device:
+    #
+    #   gigya = Ruze::Gigya.new(email, password)
+    #   puts "Code sent to #{gigya.request_verification_code}"
+    #   gigya.verify_code(gets.strip)
+    #
+    # After that, session_cookie_value works headlessly for ~30 days.
+
+    # Triggers the email verification code and returns the obfuscated address it
+    # was sent to. Returns nil when no verification is needed -- either the
+    # account has no 2FA or this device is already trusted.
+    def request_verification_code
+      ids = device_ids
+      reg_token = login_reg_token(ids)
+      return nil unless reg_token
+
+      assertion = init_tfa(reg_token, ids)
+      mail = first_email(assertion, ids)
+      phv_token = send_verification_code(mail['id'], assertion, ids)
+
+      @bootstrap = { ids: ids, reg_token: reg_token, assertion: assertion, phv_token: phv_token }
+      mail['obfuscated']
+    end
+
+    # Completes the 2FA flow with the emailed code, finalizes the device as
+    # trusted (remembered for ~30 days) and persists it.
+    def verify_code(code)
+      raise Error, 'Call request_verification_code before verify_code' unless @bootstrap
+
+      ids = @bootstrap[:ids]
+      provider_assertion = complete_verification(code, ids)
+      finalize_tfa(provider_assertion, ids)
+
+      @session_cookie_value = login(ids)
+      device.save(gmid: ids[:gmid], ucid: ids[:ucid])
+      @session_cookie_value
     end
 
     private
 
+    def login(ids = device_ids)
+      json = parse post(
+        "#{BASE_URL}/accounts.login",
+        login_params(ids), cookie: cookie(ids)
+      )
+
+      case json['errorCode']
+      when 0
+        json.dig('sessionInfo', 'cookieValue')
+      when 403_101
+        raise TwoFactorRequired,
+              'Two-factor authentication required. Run the bootstrap flow to trust this device.'
+      else
+        raise Error, "Error in session_cookie_value: #{error_detail(json)}"
+      end
+    end
+
+    # Like #login but returns the regToken from a pending-2FA response instead of
+    # raising. Returns nil when the account is already logged in without 2FA.
+    def login_reg_token(ids)
+      json = parse post(
+        "#{BASE_URL}/accounts.login",
+        login_params(ids), cookie: cookie(ids)
+      )
+      return json['regToken'] if json['errorCode'] == 403_101
+      return nil if json['errorCode']&.zero?
+
+      raise Error, "Error in session_cookie_value: #{error_detail(json)}"
+    end
+
+    def login_params(ids)
+      {
+        'apiKey'   => api_key,
+        'loginID'  => email,
+        'password' => password,
+        'gmid'     => ids[:gmid],
+        'ucid'     => ids[:ucid]
+      }
+    end
+
+    def init_tfa(reg_token, ids)
+      dig_from post(
+        "#{BASE_URL}/accounts.tfa.initTFA",
+        { 'apiKey' => api_key, 'regToken' => reg_token, 'provider' => 'gigyaEmail',
+          'mode' => 'verify', 'gmid' => ids[:gmid], 'ucid' => ids[:ucid] },
+        cookie: cookie(ids)
+      ), label: 'init_tfa', keys: %w[gigyaAssertion]
+    end
+
+    def first_email(assertion, ids)
+      emails = dig_from post(
+        "#{BASE_URL}/accounts.tfa.email.getEmails",
+        { 'apiKey' => api_key, 'gigyaAssertion' => assertion, 'gmid' => ids[:gmid], 'ucid' => ids[:ucid] },
+        cookie: cookie(ids)
+      ), label: 'get_emails', keys: %w[emails]
+      raise Error, 'No verified email address available for 2FA' if emails.nil? || emails.empty?
+
+      emails.first
+    end
+
+    def send_verification_code(email_id, assertion, ids)
+      dig_from post(
+        "#{BASE_URL}/accounts.tfa.email.sendVerificationCode",
+        { 'apiKey' => api_key, 'emailID' => email_id, 'gigyaAssertion' => assertion,
+          'lang' => 'en', 'gmid' => ids[:gmid], 'ucid' => ids[:ucid] },
+        cookie: cookie(ids)
+      ), label: 'send_verification_code', keys: %w[phvToken]
+    end
+
+    def complete_verification(code, ids)
+      dig_from post(
+        "#{BASE_URL}/accounts.tfa.email.completeVerification",
+        { 'apiKey' => api_key, 'gigyaAssertion' => @bootstrap[:assertion],
+          'phvToken' => @bootstrap[:phv_token], 'code' => code,
+          'gmid' => ids[:gmid], 'ucid' => ids[:ucid] },
+        cookie: cookie(ids)
+      ), label: 'complete_verification', keys: %w[providerAssertion]
+    end
+
+    # tempDevice=false marks the device as remembered (no 2FA for ~30 days).
+    def finalize_tfa(provider_assertion, ids)
+      json = parse post(
+        "#{BASE_URL}/accounts.tfa.finalizeTFA",
+        { 'apiKey' => api_key, 'gigyaAssertion' => @bootstrap[:assertion],
+          'providerAssertion' => provider_assertion, 'tempDevice' => 'false',
+          'regToken' => @bootstrap[:reg_token], 'gmid' => ids[:gmid], 'ucid' => ids[:ucid] },
+        cookie: cookie(ids)
+      )
+      raise Error, "Error in finalize_tfa: #{error_detail(json)}" unless json['errorCode']&.zero?
+
+      json
+    end
+
+    def device_ids
+      @device_ids ||= device.load || fetch_ids
+    end
+
+    def fetch_ids
+      json = parse post("#{SOCIALIZE_URL}/socialize.getIDs", { 'apiKey' => api_key })
+      raise Error, "Error in fetch_ids: #{error_detail(json)}" unless json['errorCode']&.zero?
+
+      { gmid: json['gmid'], ucid: json['ucid'] }
+    end
+
+    def cookie(ids)
+      "gmid=#{ids[:gmid]}; ucid=#{ids[:ucid]}"
+    end
+
     def api_key
       ENV.fetch('GIGYA_API_KEY')
     end
 
-    def uri(path)
-      URI("#{BASE_URL}#{path}")
+    def post(url, params, cookie: nil)
+      uri = URI(url)
+      request = Net::HTTP::Post.new(uri)
+      request.set_form_data(params.merge('format' => 'json'))
+      request['Cookie'] = cookie if cookie
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
+        http.request(request)
+      end
     end
 
-    def return_from(response, keys:)
-      unless response.is_a?(Net::HTTPOK)
-        caller = caller_locations(1, 1)[0].label
-        raise Error, "Error in #{caller}: #{response.message} (#{response.code})"
-      end
+    def parse(response)
+      JSON.parse(response.body)
+    end
 
-      json = JSON.parse(response.body)
-      unless json['errorCode']&.zero?
-        caller = caller_locations(1, 1)[0].label
-        raise Error, "Error in #{caller}: #{json['errorDetails']}"
-      end
+    def dig_from(response, label:, keys:)
+      json = parse(response)
+      raise Error, "Error in #{label}: #{error_detail(json)}" unless json['errorCode']&.zero?
 
       json.dig(*keys)
     end
+
+    def error_detail(json)
+      json['errorDetails'] || json['errorMessage'] || "errorCode #{json['errorCode']}"
+    end
   end
 end

data/lib/ruze/kamereon.rb

@@ -89,7 +89,7 @@ module Ruze
 
     def return_from(response, keys:)
       unless response.is_a?(Net::HTTPOK)
-        caller = caller_locations(1, 1)[0].label
+        caller = caller_locations(1, 1)[0].base_label
         raise Error, "Error in #{caller}: #{response.message} (#{response.code})"
       end
 

data/lib/ruze/version.rb

@@ -1,3 +1,3 @@
 module Ruze
-  VERSION = '0.1.2'.freeze
+  VERSION = '0.2.0'.freeze
 end

data/lib/ruze.rb

@@ -1,6 +1,3 @@
 require_relative 'ruze/version'
+require_relative 'ruze/errors'
 require_relative 'ruze/car'
-
-module Ruze
-  class Error < StandardError; end
-end

data/ruze.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.description   = 'Queries vehicle data like mileage, charging state and GPS location'
   spec.homepage      = 'https://github.com/solectrus/ruze'
   spec.license       = 'MIT'
-  spec.required_ruby_version = Gem::Requirement.new('>= 2.7.0')
+  spec.required_ruby_version = Gem::Requirement.new('>= 4.0.0')
 
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = 'https://github.com/solectrus/ruze'

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ruze
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Georg Ledermann
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-04-16 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: Queries vehicle data like mileage, charging state and GPS location
 email:
@@ -31,6 +30,8 @@ files:
 - bin/setup
 - lib/ruze.rb
 - lib/ruze/car.rb
+- lib/ruze/device.rb
+- lib/ruze/errors.rb
 - lib/ruze/gigya.rb
 - lib/ruze/kamereon.rb
 - lib/ruze/version.rb
@@ -43,7 +44,6 @@ metadata:
   source_code_uri: https://github.com/solectrus/ruze
   changelog_uri: https://github.com/solectrus/ruze/releases
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -51,15 +51,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 4.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
-signing_key:
+rubygems_version: 4.0.12
 specification_version: 4
 summary: Unofficial Ruby client for the Renault ZE API
 test_files: []