@nemorize/korean-banking-email-parser 0.0.1

package/.github/workflows/release.yml

@@ -0,0 +1,46 @@
+on:
+    workflow_dispatch:
+        inputs:
+            tags:
+                description: 'Semantic version tag (v.x.y.z)'
+                required: true
+                type: string
+            release_body:
+                description: 'Description of the release'
+                type: string
+jobs:
+    release:
+        name: Release and publish to NPM registry
+        runs-on: ubuntu-latest
+        permissions:
+            actions: write
+            contents: write
+            id-token: write
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@v6
+
+            - name: Set up Node.js
+              uses: actions/setup-node@v6
+              with:
+                node-version: latest
+            
+            - name: Bump version
+              uses: ramonpaolo/bump-version@v2.3.1
+              with:
+                tag: ${{ inputs.tags }}
+                commit: true
+                branch_to_push: main
+
+            - name: Publish to NPM
+              run: npm ci
+                   npm publish
+              env:
+                NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+            - name: Create GitHub Release
+              uses: ncipollo/release-action@v1
+              with:
+                tag: ${{ inputs.tags }}
+                release_name: ${{ inputs.tags }}
+                body: ${{ inputs.release_body }}

package/LICENSE

@@ -0,0 +1,8 @@
+Copyright 2026 Ji Yong, Kim.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

package/README.md

@@ -0,0 +1,114 @@
+# korean-banking-email-parser
+
+대한민국 은행 입출금 이메일 알림을 복호화하고 파싱합니다.
+
+현재 아래의 은행을 지원합니다.
+
+* NH농협
+
+## 설치하기
+
+```shell
+yarn add @nemorize/korean-banking-email-parser
+```
+
+## 예시
+
+```js
+import { parse } from '@nemorize/korean-banking-email-parser'
+import { readFile } from 'fs/promises';
+
+const encryptedHtml = await readFile('./Message.html', 'utf-8');
+console.log(
+    await parse(encryptedHtml, '000-00-00000')
+);
+
+// Output: {
+//   account: {
+//     accountNumber: '301-****-1234-56',
+//     accountHolder: '네모컴퍼니',
+//     accountStatus: '정상',
+//     balance: 100000,
+//     availableBalance: 100000,
+//   },
+//   transactions: [
+//     {
+//       transactionDate: '2026/01/01',
+//       type: 'deposit',
+//       amount: 30000,
+//       balanceAfter: 100000,
+//       branch: '자금과',
+//       bank: 'SC제일',
+//       description: '홍길동'
+//     }
+//   ]
+// }
+```
+
+# 보안 주의사항
+
+이 라이브러리는 메일을 복호화하기 위해 `new JSDOM(_, { runScripts: 'dangerously' })` 옵션을 사용합니다. 신뢰할 수 없는 HTML 컨텐츠를 전달할 경우 심각한 보안 문제가 발생할 수 있습니다. 입출금 알림을 발송한 이메일 주소가 각 은행의 공식 이메일 주소가 맞는지, 위변조된 이메일이 아닌지 다시 한번 확인해야 합니다.
+
+~~쓸데없이 html 파일을 보내며 고객을 위협하는 K-금융에게서 나 자신을 지키기 위해 충분한 노력을 다해야 합니다.~~
+
+# API
+
+### `parse`
+
+```ts
+parse(html: string, password: string, timeout: number) => Promise<{
+    account: {
+        accountNumber: string,
+        accountHolder: string,
+        accountStatus: string,
+        balance: number,
+        availableBalance: number,
+    },
+    transactions: {
+        transactionDate: string,
+        type: 'deposit'|'withdrawal'|'unknown',
+        amount: number,
+        balanceAfter: number,
+        branch: string,
+        bank: string,
+        description: string,
+    }[],
+}>
+```
+
+암호화된 HTML 컨텐츠를 복호화한 뒤, 복호화된 컨텐츠에서 필요한 데이터만 추출해 반환합니다.
+
+* `html`: 암호화된 HTML 컨텐츠.
+* `password`: 복호화를 위한 비밀번호. 일반적으로 생년월일 6자리 또는 사업자번호 10자리.
+* `timeout`: 복호화 작업의 타임아웃. ms 단위.
+* `account`: 계좌 정보.
+  * `accountNumber`: 계좌번호. 은행에 따라 일부 번호가 마스킹 되어 있을 수 있음.
+  * `accountHolder`: 예금주명.
+  * `accountStatus`: 계좌의 상태. 지급정지, 압류 등의 정보를 표기하기 위한 용도로 추측됨.
+  * `balance`: 계좌의 잔액. 아래의 트랜잭션이 모두 완료된 이후의 최종 잔액.
+  * `availableBalance`: 계좌의 출금 가능 잔액. 잔액에서 압류된 금액을 제외한 금액으로 추측됨.
+* `transactions`: 입출금 트랜잭션. 1개의 항목만 포함될 것으로 추측됨.
+  * `transactionDate`: `YYYY/mm/dd` 포맷의 입출금 날짜.
+  * `type`: 입금 또는 출금.
+    * `'deposit'`: 입금.
+    * `'withdrawal'`: 출금.
+    * `'unknown'`: 알 수 없음.
+  * `amount`: 입출금 액수.
+  * `balanceAfter`: 입출금 후 계좌의 잔액.
+  * `branch`: 해당 트랜잭션이 이루어진 거래점.
+  * `bank`: 해당 트랜잭션이 이루어진 은행명.
+  * `description`: 입금자명 또는 출금통장기록.
+
+# 기여
+
+현재 극소수의 은행만을 지원하고 있습니다. 다른 은행들도 지원할 수 있도록 많은 기여 부탁드립니다.
+
+새로운 은행의 파서를 기여하고자 할 경우, 해당 은행에서 수신한 이메일 첨부파일 및 비밀번호를 PR에 함께 동봉하여 정상 작동 여부를 테스트 할 수 있도록 해 주세요.
+
+코드 없이 이메일 첨부파일만 기여하시는 것도 환영합니다. 이슈를 통해 이메일 첨부파일과 비밀번호를 동봉해 주시면 검토하여 반영토록 하겠습니다.
+
+혹 계좌 정보가 공개적으로 업로드되지 않기를 원하신다면, `jiyong.kim@headercat.com`으로 메일을 발송해 주셔도 좋습니다.
+
+# 라이선스
+
+MIT 라이선스를 따릅니다.

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@nemorize/korean-banking-email-parser",
+  "version": "0.0.1",
+  "description": "Decrypt and parse email notification regarding deposits and withdrawals from South Korea banks.",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "type": "module",
+  "repository": "https://github.com/nemorize/korean-banking-email-parser",
+  "author": "Ji Yong, Kim <jiyong.kim@headercat.com>",
+  "license": "MIT",
+  "dependencies": {
+    "jsdom": "^29.1.1"
+  }
+}

package/src/dom.js

@@ -0,0 +1,22 @@
+import { JSDOM, VirtualConsole } from 'jsdom';
+
+/**
+ * Create a JSDOM instance from the given HTML and options.
+ * 
+ * @param {string} html 
+ * @param {import('jsdom').ConstructorOptions} options 
+ * @returns {JSDOM}
+ */
+export function createDom(html, options) {
+    const virtualConsole = new VirtualConsole();
+    virtualConsole.on('error', () => { });
+
+    const dom = new JSDOM(html, {
+        ...options,
+        virtualConsole,
+        beforeParse(window) {
+            window.alert = function () { };
+        },
+    });
+    return dom;
+}

package/src/index.js

@@ -0,0 +1,47 @@
+import { parseContent } from './parse.js';
+import { nonghyupPreset } from './presets/nonghyup.js';
+import { decryptVestMail } from './vestmail.js';
+
+/**
+ * 
+ * @param {string} html Full encrypted HTML content of the VestMail.
+ * @param {string} password Password to decrypt the VestMail.
+ * @param {number} [timeout=10000] Maximum time to wait for decryption (in milliseconds).
+ * 
+ * @returns {Promise<{
+ *   account: {
+ *     accountNumber: string,
+ *     accountHolder: string,
+ *     accountStatus: string,
+ *     balance: number,
+ *     availableBalance: number,
+ *   },
+ *   transactions: {
+ *     transactionDate: string,
+ *     type: 'deposit'|'withdrawal'|'unknown',
+ *     amount: number,
+ *     balanceAfter: number,
+ *     branch: string,
+ *     bank: string,
+ *     description: string,
+ *   }[]
+ * }>}
+ */
+export async function parse(html, password, timeout) {
+    const preset = detectPreset(html);
+    const decryptedHtml = await decryptVestMail(html, password, preset.verifier, timeout);
+    return parseContent(decryptedHtml, preset);
+}
+
+const presets = {
+    '농협': nonghyupPreset,
+}
+
+function detectPreset(html) {
+    for (const [name, preset] of Object.entries(presets)) {
+        if (html.includes(name)) {
+            return preset;
+        }
+    }
+    throw new Error('Cannot detect bank from the VestMail content');
+}

package/src/parse.js

@@ -0,0 +1,51 @@
+import { JSDOM } from 'jsdom';
+import { createDom } from './dom.js';
+
+/**
+ * Parse the VestMail content and extract account information and transactions using the provided parser functions.
+ * 
+ * @param {string} html 
+ * @param {{
+ *   account: (dom: JSDOM) => {
+ *     accountNumber: string,
+ *     accountHolder: string,
+ *     accountStatus: string,
+ *     balance: number,
+ *     availableBalance: number,
+ *   },
+ *   transactions: (dom: JSDOM) => {
+ *     transactionDate: string,
+ *     type: 'deposit'|'withdrawal'|'unknown',
+ *     amount: number,
+ *     balanceAfter: number,
+ *     branch: string,
+ *     bank: string,
+ *     description: string,
+ *   }[]
+ * }} parser 
+ * @returns {{
+ *   account: {
+ *     accountNumber: string,
+ *     accountHolder: string,
+ *     accountStatus: string,
+ *     balance: number,
+ *     availableBalance: number,
+ *   },
+ *   transactions: {
+ *     transactionDate: string,
+ *     type: 'deposit'|'withdrawal'|'unknown',
+ *     amount: number,
+ *     balanceAfter: number,
+ *     branch: string,
+ *     bank: string,
+ *     description: string,
+ *   }[]
+ * }}
+ */
+export function parseContent(html, parser) {
+    const dom = createDom(html);
+    return {
+        account: parser.account(dom),
+        transactions: parser.transactions(dom),
+    };
+}

package/src/presets/nonghyup.js

@@ -0,0 +1,89 @@
+
+export const nonghyupPreset = {
+    verifier: (html) => html.includes('입출금 거래 내역 조회'),
+    account: parseNonghyupAccount,
+    transactions: parseNonghyupTransactions,
+};
+
+function parseNonghyupAccount(dom) {
+    const { document } = dom.window;
+    return {
+        accountNumber: findValueByLabel(document, '계좌번호'),
+        accountHolder: findValueByLabel(document, '예금주명'),
+        accountStatus: findValueByLabel(document, '계좌상태'),
+        balance: parseMoney(findValueByLabel(document, '통 장 잔 액')),
+        availableBalance: parseMoney(findValueByLabel(document, '지급가능잔액')),
+    };
+}
+
+function parseNonghyupTransactions(dom) {
+    const { document } = dom.window;
+    const rows = [...document.querySelectorAll('tr')];
+    const transactions = [];
+    for (const row of rows) {
+        const cells = [...row.querySelectorAll('td')].map((v) => normalizeText(v.textContent));
+        if (!isTransactionRow(cells)) {
+            continue;
+        }
+        transactions.push({
+            transactionDate: cells[1],
+            type: cells[2] === '입금' ? 'deposit' : cells[2] === '출금' ? 'withdrawal' : 'unknown',
+            amount: parseMoney(cells[3]),
+            balanceAfter: parseMoney(cells[4]),
+            branch: cells[5],
+            bank: cells[6],
+            description: cells[7],
+        });
+    }
+    return transactions;
+}
+
+function parseMoney(text) {
+    text = normalizeText(text);
+    if (!text) {
+        return 0;
+    }
+    if (!text.endsWith('원')) {
+        return 0;
+    }
+    const number = Number(text.replace(/[^0-9\-]/g, ''));
+    if (!number || isNaN(number)) {
+        return 0;
+    }
+    return number;
+}
+
+function normalizeText(text) {
+    return String(text || '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+
+function findValueByLabel(document, label) {
+    const tds = [...document.querySelectorAll('td')];
+    for (const td of tds) {
+        if (normalizeText(td.textContent) === label) {
+            const next = td.nextElementSibling;
+            if (next) {
+                return normalizeText(next.textContent);
+            }
+        }
+    }
+    return '';
+}
+
+function isTransactionRow(cells) {
+    if (cells.length < 8) {
+        return false;
+    }
+    if (!/^\d+$/.test(cells[0])) {
+        return false;
+    }
+    if (!/\d{4}\/\d{2}\/\d{2}/.test(cells[1])) {
+        return false;
+    }
+    if (!cells[3].includes('원')) {
+        return false;
+    }
+    return true;
+}

package/src/vestmail.js

@@ -0,0 +1,85 @@
+import { createDom } from './dom.js';
+
+/**
+ * Decrypt the VestMail content from the given HTML and password.
+ * 
+ * @param {string} html Full HTML content of the VestMail.
+ * @param {string} password Password to decrypt the VestMail.
+ * @param {(html:string)=>boolean} [verifier=(html)=>html.length>100] Function to verify if the decrypted content is correct. It receives the decrypted HTML and should return true if it's valid.
+ * @param {number} [timeout=10000] Maximum time to wait for decryption (in milliseconds).
+ * 
+ * @returns {Promise<string>} Decrypted HTML content of the VestMail.
+ * 
+ * @warning This executes the JavaScript code embedded in the HTML. Make sure to use it only with trusted content.
+ */
+export async function decryptVestMail(html, password, verifier, timeout) {
+    timeout = timeout || 10000;
+    verifier = verifier || ((html) => html.length > 100);
+
+    const dom = createDom(html, {
+        runScripts: 'dangerously',
+        resources: 'usable',
+        pretendToBeVisual: true,
+        url: 'http://localhost/'
+    });
+
+    const { window } = dom;
+    const { document } = window;
+    const documentWrite = document.write.bind(document);
+
+    let resultHtml = null;
+    document.write = function (content) {
+        if (typeof content === 'string' && verifier(content)) {
+            resultHtml = content;
+        }
+        return documentWrite(content);
+    };
+
+    let finished = false;
+    window.vestmail_onend = function () {
+        finished = true;
+    };
+
+    const startTime = Date.now();
+    await new Promise((resolve) => {
+        window.addEventListener('load', () => resolve(), {
+            once: true,
+        });
+        setTimeout(resolve, Math.min(3000, timeout));
+    });
+    timeout = timeout - (Date.now() - startTime);
+
+    const inputs = [...document.querySelectorAll('input')];
+    const passwordInput = inputs.find((v) => {
+        const s = `${v.id} ${v.name} ${v.type}`.toLowerCase();
+        return s.includes('pass');
+    });
+    if (!passwordInput) {
+        throw new Error('Cannot find password input');
+    }
+    passwordInput.value = password;
+
+    const doAction = window.doAction || window.N;
+    if (typeof doAction !== 'function') {
+        throw new Error('Cannot find doAction function');
+    }
+
+    doAction();
+    await new Promise((resolve) => {
+        const started = Date.now();
+        const t = setInterval(() => {
+            if (finished || resultHtml || Date.now() - started > timeout) {
+                clearInterval(t);
+                resolve();
+            }
+        }, 50);
+    });
+
+    if (!resultHtml) {
+        resultHtml = document.documentElement.outerHTML;
+    }
+    if (!resultHtml || !verifier(resultHtml)) {
+        throw new Error('Failed to decrypt VestMail');
+    }
+    return resultHtml;
+}