feat: 2fa support

#26
#39

Author: dgreif

api/api.ts

@@ -12,18 +12,18 @@ import { RingCamera } from './ring-camera'
 import { EMPTY, merge, Subject } from 'rxjs'
 import { debounceTime, switchMap, throttleTime } from 'rxjs/operators'
 
-export type RingAlarmOptions = {
+export interface RingAlarmOptions {
   locationIds?: string[]
   cameraStatusPollingSeconds?: number
   cameraDingsPollingSeconds?: number
-} & RingAuth
+}
 
 export class RingApi {
   public readonly restClient = new RingRestClient(this.options)
 
   private locations = this.fetchAndBuildLocations()
 
-  constructor(public readonly options: RingAlarmOptions) {}
+  constructor(public readonly options: RingAlarmOptions & RingAuth) {}
 
   async fetchRingDevices() {
     const {
@@ -40,6 +40,16 @@ export class RingApi {
       beams_bridges: BeamBridge[]
     }>({ url: clientApi('ring_devices') })
 
+    if (this.restClient.using2fa && this.restClient.refreshToken) {
+      console.error(
+        'Your Ring account is configured to use 2-factor authentication (2fa).'
+      )
+      console.error(
+        `Please change your Ring configuration to include "refreshToken": "${this.restClient.refreshToken}"`
+      )
+      process.exit(1)
+    }
+
     return {
       doorbots,
       authorizedDoorbots,

api/rest-client.ts

@@ -1,5 +1,11 @@
 import axios, { AxiosRequestConfig, ResponseType } from 'axios'
-import { delay, generateRandomId, logError, logInfo } from './util'
+import {
+  delay,
+  generateRandomId,
+  logError,
+  logInfo,
+  requestInput
+} from './util'
 import * as querystring from 'querystring'
 import { AuthTokenResponse, SessionResponse } from './ring-types'
 
@@ -63,14 +69,15 @@ export type RingAuth = EmailAuth | RefreshTokenAuth
 
 export class RingRestClient {
   // prettier-ignore
-  private refreshToken = ('refreshToken' in this.authOptions ? this.authOptions.refreshToken : undefined)
+  public refreshToken = ('refreshToken' in this.authOptions ? this.authOptions.refreshToken : undefined)
   private authPromise = this.getAuthToken()
   private sessionPromise = this.getSession()
+  public using2fa = false
 
   constructor(private authOptions: RingAuth) {}
 
-  private getGrantData() {
-    if (this.refreshToken) {
+  private getGrantData(twoFactorAuthCode?: string) {
+    if (this.refreshToken && !twoFactorAuthCode) {
       return {
         grant_type: 'refresh_token',
         refresh_token: this.refreshToken
@@ -91,8 +98,16 @@ export class RingRestClient {
     )
   }
 
-  private async getAuthToken(): Promise<AuthTokenResponse> {
-    const grantData = this.getGrantData()
+  private async getAuthToken(
+    twoFactorAuthCode?: string
+  ): Promise<AuthTokenResponse> {
+    const grantData = this.getGrantData(twoFactorAuthCode),
+      twoFactorAuthHeaders = twoFactorAuthCode
+        ? {
+            '2fa-code': twoFactorAuthCode,
+            '2fa-Support': 'true'
+          }
+        : {}
 
     try {
       const response = await requestWithRetry<AuthTokenResponse>({
@@ -104,7 +119,8 @@ export class RingRestClient {
         },
         method: 'POST',
         headers: {
-          'content-type': 'application/json'
+          'content-type': 'application/json',
+          ...twoFactorAuthHeaders
         }
       })
 
@@ -118,8 +134,30 @@ export class RingRestClient {
         return this.getAuthToken()
       }
 
-      const errorMessage =
-        'Failed to fetch oauth token from Ring.  Verify that your email and password are correct.'
+      const response = requestError.response || {},
+        responseData = response.data || {},
+        responseError =
+          typeof responseData.error === 'string' ? responseData.error : ''
+
+      if (
+        response.status === 412 || // need 2fa code
+        (response.status === 400 &&
+          responseError.startsWith('Verification Code')) // invalid 2fa code entered
+      ) {
+        const code = await requestInput(
+          'Ring 2fa enabled.  Please enter code from text message: '
+        )
+        this.using2fa = true
+        return this.getAuthToken(code)
+      }
+
+      const authTypeMessage =
+          'refreshToken' in this.authOptions
+            ? 'refresh token is'
+            : 'email and password are',
+        errorMessage =
+          `Failed to fetch oauth token from Ring. Verify that your ${authTypeMessage} correct. ` +
+          responseError
       logError(requestError.response)
       logError(errorMessage)
       throw new Error(errorMessage)

api/util.ts

@@ -1,6 +1,7 @@
 import debug = require('debug')
 import { red } from 'colors'
 import { randomBytes } from 'crypto'
+import { createInterface } from 'readline'
 
 const logger = debug('ring-alarm')
 
@@ -32,3 +33,17 @@ export function generateRandomId() {
     id.substr(20, 12)
   )
 }
+
+export async function requestInput(question: string) {
+  const lineReader = createInterface({
+      input: process.stdin,
+      output: process.stdout
+    }),
+    answer = await new Promise<string>(resolve => {
+      lineReader.question(question, resolve)
+    })
+
+  lineReader.close()
+
+  return answer.trim()
+}

examples/example.ts

@@ -8,8 +8,10 @@ async function example() {
       // Replace with your ring email/password
       email: env.RING_EMAIL!,
       password: env.RING_PASS!,
-      cameraDingsPollingSeconds: 1,
-      locationIds: [env.RING_LOCATION_ID!] // Remove if you want all locations
+      // Refresh token is used when 2fa is on
+      refreshToken: env.RING_REFRESH_TOKEN!,
+      // Listen for dings and motion events
+      cameraDingsPollingSeconds: 1
     }),
     locations = await ringApi.getLocations(),
     cameras = await ringApi.getCameras()

homebridge/README.md

@@ -27,6 +27,9 @@ and third party devices that connect to the Ring Alarm System.
       "platform": "RingAlarm",
       "email": "some.one@website.com",
       "password": "abc123!#",
+      
+      // For 2fa accounts only.  See below for details
+      "refreshToken": "TOKEN GENERATED FOR 2fa ACCOUNTS",
 
       // Optional. DO NOT INCLUDE UNLESS NEEDED.  See below for details
       "locationIds": ["488e4800-fcde-4493-969b-d1a06f683102", "4bbed7a7-06df-4f18-b3af-291c89854d60"],
@@ -86,6 +89,14 @@ light/siren status do not update in real time and need to be requested periodica
 `cameraDingsPollingSeconds`: How frequently to poll for new events from your cameras.  These include motion and
 doorbell presses.  Defaults to every `1` second. 
 
+### 2-Factor Authentication (2fa)
+
+If you have 2fa turned on for your Ring account, start by running the homebridge plugin with your email and password in `config.json`.
+You will be prompted to enter the 2fa code that you received via text message.  Type the code into your terminal, and then
+press enter.  Homebridge will exit with an error, but a message will log out your `refreshToken`.  Copy this refresh token
+and in your homebridge `config.json` add `"refreshToken": "REFERSH TOKEN LOGGED AFTER ENTERING YOUR 2fa CODE"` to the RingPlatform
+config section.  You can delete `email` and `password` as these will no longer be used.
+
 ### Camera Setup
 
 This plugin will connect all of your Ring cameras to homebridge, but they require a little extra work to get set up.

homebridge/ring-alarm-platform.ts

@@ -13,6 +13,7 @@ import { RingAlarmPlatformConfig } from './config'
 import { Beam } from './beam'
 import { MultiLevelSwitch } from './multi-level-switch'
 import { Camera } from './camera'
+import { RingAuth } from '../api/rest-client'
 
 const pluginName = 'homebridge-ring-alarm',
   platformName = 'RingAlarm',
@@ -61,7 +62,7 @@ export class RingAlarmPlatform {
 
   constructor(
     public log: HAP.Log,
-    public config: RingAlarmPlatformConfig,
+    public config: RingAlarmPlatformConfig & RingAuth,
     public api: HAP.Platform
   ) {
     if (!config) {