edilkamin 1.3.0 → 1.3.1

package/.github/workflows/cli-tests.yml

@@ -0,0 +1,17 @@
+name: CLI Tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20.x"
+      - run: yarn install --no-ignore-optional
+      - run: yarn cli --help

package/.github/workflows/documentation.yml

@@ -0,0 +1,34 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20.x"
+      - name: git config
+        run: |
+          git config user.name documentation-deploy-action
+          git config user.email documentation-deploy-action@@users.noreply.github.com
+          git remote set-url origin https://${{github.actor}}:${{github.token}}@github.com/${{github.repository}}.git
+      - run: yarn install
+      - run: yarn typedoc src/index.ts --out /tmp/docs
+      - name: deploy documentation
+        run: |
+          git ls-remote --exit-code . origin/gh-pages \
+            && git checkout -b gh-pages \
+            || git checkout --orphan gh-pages
+          git reset --hard
+          git pull --set-upstream origin gh-pages || echo probably first commit
+          cp --recursive /tmp/docs/. .
+          echo /node_modules > .gitignore
+          git add --all
+          git commit --all --message ":memo: docs: Update generated documentation"
+          git push origin gh-pages

package/.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20.x"
+          registry-url: "https://registry.npmjs.org"
+      - run: yarn install
+      - run: yarn build
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}

package/.github/workflows/tests.yml

@@ -0,0 +1,18 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20.x"
+      - run: yarn install
+      - run: yarn lint
+      - run: yarn build
+      - run: npm publish --dry-run

package/docs/Release.md

@@ -0,0 +1,41 @@
+# How to release
+
+This is documenting the release process.
+
+We're also using [semantic versioning](https://semver.org/) where `major.minor.patch` should be set accordingly.
+
+```sh
+VERSION=major.minor.patch
+```
+
+## Update package.json and tag
+
+Update the [package.json](../package.json) `version` to match the new release version.
+
+```sh
+sed --regexp-extended 's/"version": "(.+)"/"version": "'$VERSION'"/' --in-place package.json
+```
+
+Then commit and tag:
+
+```sh
+git commit -a -m ":bookmark: $VERSION"
+git tag -a $VERSION -m ":bookmark: $VERSION"
+```
+
+Push everything including tags:
+
+```sh
+git push
+git push --tags
+```
+
+## Publish to npm
+
+Publication to npm happens automatically from GitHub Actions on tag push.
+Alternatively it can be done manually via:
+
+```sh
+yarn build
+npm publish
+```

package/docs/ReverseEngineering.md

@@ -0,0 +1,143 @@
+# Edilkamin Stove Reverse Engineering
+
+Edilkamin pellet stoves remote control reverse engineering.
+This is documenting my journey to reverse engineering [The Mind Edilkamin app](https://play.google.com/store/apps/details?id=com.edilkamin.stufe).
+The goal was to be able to control the stove wirelessly without having to use the proprietary app.
+
+## APK download & decompiling
+
+The steps to decompile an APK are mainly described in this article:
+[Reverse Engineering Sodexo's API](https://medium.com/@andre.miras/reverse-engineering-sodexos-api-d13710b7bf0d)
+
+Here we summarize some of them.
+
+- APK used: https://play.google.com/store/apps/details?id=com.edilkamin.stufe
+- version: 1.2.3 (19 November 2021)
+
+Assuming the APK is already loaded on the Android device, proceed as below to download on the computer.
+Get the APK on device path:
+
+```sh
+adb shell pm list packages -f | grep edilkamin
+```
+
+Output:
+
+```
+package:/data/app/com.edilkamin.stufe-Di57pxUTs3wzjQF0dIxeEQ==/base.apk=com.edilkamin.stufe
+```
+
+Copy to the computer:
+
+```sh
+adb shell cp /data/app/com.edilkamin.stufe-Di57pxUTs3wzjQF0dIxeEQ==/base.apk /sdcard/
+adb pull /sdcard/base.apk .
+```
+
+Decompile (jadx v1.3.3):
+
+```sh
+jadx --output-dir base base.apk
+```
+
+## Looking into `strings.xml`
+
+Often an interesting starting point is the `base/resources/res/values/strings.xml` file.
+We find the usual `google_api_key` and `google_app_id`, but no endpoint prefix or anything that
+will be used in the short terms.
+
+## Let's `grep` through the source
+
+The APK source contains a lot of thirdparty code, but the actual application code is located in:
+`base/sources/com/edilkamin/stufe/`
+
+Let's `grep` into it looking for some endpoints:
+
+```sh
+cd base/sources/com/edilkamin/stufe/ && grep -irE 'http(s)://' .
+```
+
+Output extract:
+
+```
+./network/EdilkaminApiServiceKt.java:    public static final String BASE_URL = "https://s5zsjtooy4.execute-api.eu-central-1.amazonaws.com/test/";
+./network/EdilkaminApiServiceKt.java:    public static final String PROD_URL = "https://fxtj7xkgc6.execute-api.eu-central-1.amazonaws.com/prod/";
+```
+
+Other interesting files found and their extract:
+
+- `base/sources/com/edilkamin/stufe/network/ApiService.java`:
+
+```java
+@PUT("device/{mac_address}")
+Object editAssociation(@Header("Authorization") String str, @Path("mac_address") String str2, @Body EditDeviceAssociationBody editDeviceAssociationBody, Continuation<Object> continuation);
+
+@GET("device/{macAddress}/info")
+Object getFireplaceInfo(@Path("macAddress") String str, Continuation<? super GeneralResponse> continuation);
+```
+
+- `base/resources/res/raw/amplifyconfiguration.json`:
+
+```json
+"Default": {
+  "PoolId": "eu-central-1_BYmQ2VBlo",
+  "AppClientId": "7sc1qltkqobo3ddqsk4542dg2h",
+  "Region": "eu-central-1"
+}
+```
+
+## Poking the /prod/ endpoint around
+
+```sh
+curl https://fxtj7xkgc6.execute-api.eu-central-1.amazonaws.com/prod/
+```
+
+Output (status code 403):
+
+```json
+{ "message": "Missing Authentication Token" }
+```
+
+Let's try an unauthenticated endpoint then, remember that file `network/ApiService.java`.
+
+```sh
+curl --verbose https://fxtj7xkgc6.execute-api.eu-central-1.amazonaws.com/prod/device/AA:BB:CC:DD:EE:FF/info
+```
+
+Output (status code 404):
+
+```json
+{}
+```
+
+That looks already promising.
+After poking that endpoint around and using the real device MAC address we get a valid response.
+Note how the MAC address is all lower case and no column:
+
+```sh
+curl --verbose https://fxtj7xkgc6.execute-api.eu-central-1.amazonaws.com/prod/device/aabbccddeeff/info
+```
+
+Output (status code 200):
+
+```json
+{"mac_address":"aabbccddeeff","pk":1,"component_info":{"temp_umidity_voc_probe_3":...}}
+```
+
+Bingo!
+
+## Turn the stove on
+
+```sh
+curl --verbose --request PUT --header "Content-Type: application/json" \
+--data '{"mac_address":"aabbccddeeff", "name": "power", "value": 1}' \
+https://fxtj7xkgc6.execute-api.eu-central-1.amazonaws.com/prod/mqtt/command
+```
+
+## Note on Security
+
+It seems like most endpoints let you read info or control the stove without any authentication.
+All we need is a valid device MAC address.
+Don't leak your MAC address or people can potentially control your stove.
+
+October 2022 update: the endpoints got updated to require a JWT token and the stoves are linked to the account.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edilkamin",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,9 +13,6 @@
     "format": "prettier --write src docs .github *.md",
     "build": "tsc"
   },
-  "files": [
-    "/dist"
-  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AndreMiras/edilkamin.js.git"

package/src/cli.ts

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import { signIn, configure } from "./library";
+import { Command } from "commander";
+import readline from "readline";
+import { version } from "../package.json";
+
+const promptPassword = (): Promise<string> => {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: true,
+  });
+  return new Promise((resolve) => {
+    rl.question("Enter password: ", (password) => {
+      // Hide the password input
+      readline.moveCursor(process.stdout, 0, -1);
+      readline.clearLine(process.stdout, 0);
+      rl.close();
+      resolve(password);
+    });
+    // Disable input echoing for password
+    process.stdin.on("data", (char) => {
+      if (char.toString("hex") === "0d0a") return; // Enter key
+      process.stdout.write("*");
+    });
+  });
+};
+
+/**
+ * Adds common options (username and password) to a command.
+ * @param command The command to which options should be added.
+ * @returns The command with options added.
+ */
+const addCommonOptions = (command: Command): Command =>
+  command
+    .requiredOption("-u, --username <username>", "Username")
+    .option("-p, --password <password>", "Password");
+
+const createProgram = (): Command => {
+  const program = new Command();
+  program
+    .name("edilkamin-cli")
+    .description("CLI tool for interacting with the Edilkamin API")
+    .version(version);
+  // Command: signIn
+  addCommonOptions(
+    program.command("signIn").description("Sign in and retrieve a JWT token")
+  ).action(async (options) => {
+    const { username, password } = options;
+    const pwd = password || (await promptPassword());
+    const jwtToken = await signIn(username, pwd);
+    console.log("JWT Token:", jwtToken);
+  });
+  // Command: deviceInfo
+  addCommonOptions(
+    program
+      .command("deviceInfo")
+      .description("Retrieve device info for a specific MAC address")
+      .requiredOption("-m, --mac <macAddress>", "MAC address of the device")
+  ).action(async (options) => {
+    const { username, password, mac } = options;
+    const pwd = password || (await promptPassword());
+    const jwtToken = await signIn(username, pwd);
+    const api = configure(); // Use the default API configuration
+    const deviceInfo = await api.deviceInfo(jwtToken, mac);
+    console.log("Device Info:", deviceInfo.data);
+  });
+  return program;
+};
+
+const main = (): void => {
+  const program = createProgram();
+  program.parse(process.argv);
+};
+
+if (require.main === module) {
+  main();
+}
+
+export { main };

package/src/constants.ts

@@ -0,0 +1,4 @@
+const API_URL =
+  "https://fxtj7xkgc6.execute-api.eu-central-1.amazonaws.com/prod/";
+
+export { API_URL };

package/src/index.ts

@@ -0,0 +1,15 @@
+import { configure } from "./library";
+
+export { API_URL } from "./constants";
+
+export {
+  CommandsType,
+  DeviceInfoType,
+  StatusType,
+  TemperaturesType,
+  UserParametersType,
+} from "./types";
+
+export { signIn, configure } from "./library";
+
+export const { deviceInfo, setPower, setPowerOff, setPowerOn } = configure();

package/src/library.test.ts

@@ -0,0 +1,77 @@
+import { strict as assert } from "assert";
+import sinon from "sinon";
+import { Amplify } from "aws-amplify";
+import axios from "axios";
+import { signIn, configure } from "../src/library";
+
+describe("library", () => {
+  let axiosStub: sinon.SinonStub;
+
+  beforeEach(() => {
+    axiosStub = sinon.stub(axios, "create").returns({
+      get: sinon.stub(),
+      put: sinon.stub(),
+    } as any);
+  });
+
+  afterEach(() => {
+    sinon.restore();
+  });
+
+  describe("configure", () => {
+    it("should create API methods with the correct baseURL", () => {
+      const baseURL = "https://example.com/api";
+      const api = configure(baseURL);
+      assert.ok(axiosStub.calledOnce);
+      assert.deepEqual(axiosStub.firstCall.args[0], { baseURL });
+      assert.deepEqual(Object.keys(api), [
+        "deviceInfo",
+        "setPower",
+        "setPowerOff",
+        "setPowerOn",
+      ]);
+    });
+  });
+
+  describe("API Methods", () => {
+    it("should call axios for deviceInfo", async () => {
+      const mockAxios = {
+        get: sinon
+          .stub()
+          .resolves({ data: { id: "123", name: "Mock Device" } }),
+      };
+      axiosStub.returns(mockAxios as any);
+      const api = configure("https://example.com/api");
+      const result = await api.deviceInfo("mockToken", "mockMacAddress");
+      assert.ok(mockAxios.get.calledOnce);
+      assert.equal(
+        mockAxios.get.firstCall.args[0],
+        "device/mockMacAddress/info"
+      );
+      assert.deepEqual(mockAxios.get.firstCall.args[1], {
+        headers: { Authorization: "Bearer mockToken" },
+      });
+      assert.deepEqual(result.data, { id: "123", name: "Mock Device" });
+    });
+
+    it("should call axios for setPowerOn", async () => {
+      const mockAxios = {
+        put: sinon.stub().resolves({ status: 200 }),
+      };
+      axiosStub.returns(mockAxios as any);
+      const api = configure("https://example.com/api");
+      const result = await api.setPowerOn("mockToken", "mockMacAddress");
+      assert.ok(mockAxios.put.calledOnce);
+      assert.equal(mockAxios.put.firstCall.args[0], "mqtt/command");
+      assert.deepEqual(mockAxios.put.firstCall.args[1], {
+        mac_address: "mockMacAddress",
+        name: "power",
+        value: 1,
+      });
+      assert.deepEqual(mockAxios.put.firstCall.args[2], {
+        headers: { Authorization: "Bearer mockToken" },
+      });
+      assert.equal(result.status, 200);
+    });
+  });
+});

package/src/library.ts

@@ -0,0 +1,74 @@
+import { strict as assert } from "assert";
+import { Amplify } from "aws-amplify";
+import * as amplifyAuth from "aws-amplify/auth";
+import axios, { AxiosInstance } from "axios";
+import { DeviceInfoType } from "./types";
+import { API_URL } from "./constants";
+
+const amplifyconfiguration = {
+  aws_project_region: "eu-central-1",
+  aws_user_pools_id: "eu-central-1_BYmQ2VBlo",
+  aws_user_pools_web_client_id: "7sc1qltkqobo3ddqsk4542dg2h",
+};
+Amplify.configure(amplifyconfiguration);
+
+const headers = (jwtToken: string) => ({ Authorization: `Bearer ${jwtToken}` });
+
+/**
+ * Sign in to return the JWT token.
+ */
+const signIn = async (username: string, password: string): Promise<string> => {
+  const { isSignedIn, nextStep } = await amplifyAuth.signIn({
+    username,
+    password,
+  });
+  assert.ok(isSignedIn);
+  const { tokens } = await amplifyAuth.fetchAuthSession();
+  assert.ok(tokens);
+  return tokens.accessToken.toString();
+};
+
+const deviceInfo =
+  (axiosInstance: AxiosInstance) => (jwtToken: string, macAddress: string) =>
+    axiosInstance.get<DeviceInfoType>(`device/${macAddress}/info`, {
+      headers: headers(jwtToken),
+    });
+
+const mqttCommand =
+  (axiosInstance: AxiosInstance) =>
+  (jwtToken: string, macAddress: string, payload: any) =>
+    axiosInstance.put(
+      "mqtt/command",
+      { mac_address: macAddress, ...payload },
+      { headers: headers(jwtToken) }
+    );
+
+const setPower =
+  (axiosInstance: AxiosInstance) =>
+  (jwtToken: string, macAddress: string, value: number) =>
+    mqttCommand(axiosInstance)(jwtToken, macAddress, { name: "power", value });
+
+const setPowerOn =
+  (axiosInstance: AxiosInstance) => (jwtToken: string, macAddress: string) =>
+    setPower(axiosInstance)(jwtToken, macAddress, 1);
+const setPowerOff =
+  (axiosInstance: AxiosInstance) => (jwtToken: string, macAddress: string) =>
+    setPower(axiosInstance)(jwtToken, macAddress, 0);
+
+const configure = (baseURL: string = API_URL) => {
+  const axiosInstance = axios.create({ baseURL });
+  const deviceInfoInstance = deviceInfo(axiosInstance);
+  const setPowerInstance = setPower(axiosInstance);
+  const setPowerOffInstance = setPowerOff(axiosInstance);
+  const setPowerOnInstance = setPowerOn(axiosInstance);
+  return {
+    deviceInfo: deviceInfoInstance,
+    setPower: setPowerInstance,
+    setPowerOff: setPowerOffInstance,
+    setPowerOn: setPowerOnInstance,
+  };
+};
+
+const defaultApi = configure();
+
+export { signIn, configure };

package/src/types.ts

@@ -0,0 +1,36 @@
+interface CommandsType {
+  power: boolean;
+}
+
+interface TemperaturesType {
+  board: number;
+  enviroment: number;
+}
+
+interface StatusType {
+  commands: CommandsType;
+  temperatures: TemperaturesType;
+}
+
+interface UserParametersType {
+  enviroment_1_temperature: number;
+  enviroment_2_temperature: number;
+  enviroment_3_temperature: number;
+  is_auto: boolean;
+  is_sound_active: boolean;
+}
+
+interface DeviceInfoType {
+  status: StatusType;
+  nvm: {
+    user_parameters: UserParametersType;
+  };
+}
+
+export type {
+  CommandsType,
+  DeviceInfoType,
+  StatusType,
+  TemperaturesType,
+  UserParametersType,
+};

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "target": "es2015",
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "preserveConstEnums": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ]
+}

package/dist/package.json

@@ -1,50 +0,0 @@
-{
-    "name": "edilkamin",
-    "version": "1.3.0",
-    "description": "",
-    "main": "dist/index.js",
-    "types": "dist/index.d.ts",
-    "scripts": {
-        "cli": "ts-node src/cli.ts",
-        "cli:debug": "node --inspect --require ts-node/register/transpile-only src/cli.ts",
-        "test": "mocha --require ts-node/register src/*.test.ts",
-        "test:debug": "mocha --require ts-node/register/transpile-only --inspect src/*.test.ts",
-        "lint": "prettier --check src docs .github *.md",
-        "format": "prettier --write src docs .github *.md",
-        "build": "tsc"
-    },
-    "files": [
-        "/dist"
-    ],
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/AndreMiras/edilkamin.js.git"
-    },
-    "author": "Andre Miras",
-    "license": "MIT",
-    "bugs": {
-        "url": "https://github.com/AndreMiras/edilkamin.js/issues"
-    },
-    "homepage": "https://github.com/AndreMiras/edilkamin.js#readme",
-    "bin": {
-        "edilkamin": "dist/cli.js"
-    },
-    "dependencies": {
-        "aws-amplify": "^6.10.0",
-        "axios": "^0.26.0"
-    },
-    "devDependencies": {
-        "@aws-amplify/cli": "^7.6.21",
-        "@types/mocha": "^10.0.10",
-        "@types/sinon": "^17.0.3",
-        "mocha": "^10.8.2",
-        "prettier": "^2.5.1",
-        "sinon": "^19.0.2",
-        "ts-node": "^10.9.1",
-        "typedoc": "^0.27.2",
-        "typescript": "^5.7.2"
-    },
-    "optionalDependencies": {
-        "commander": "^12.1.0"
-    }
-}