ism-wifi 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 1.0.0 (2026-07-26)
+
+- Initial release
+- Interactive setup wizard
+- Connectivity monitoring with configurable interval
+- Automatic login to IIT ISM Dhanbad captive portal
+- Exponential backoff retry logic
+- CLI commands: setup, config, login, reset, version, help
+- Cross-platform support (Windows, Linux, macOS)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ism-wifi contributors
+
+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,66 @@
+# ism-wifi
+
+Auto-login to the IIT ISM Dhanbad captive Wi-Fi portal.
+
+## Installation
+
+```bash
+npm install -g ism-wifi
+```
+
+## Usage
+
+```bash
+ism-wifi
+```
+
+On first run you will be prompted for your credentials. The configuration is saved automatically. The tool monitors your internet connectivity and re-authenticates when the connection drops.
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `ism-wifi` | Start monitoring |
+| `ism-wifi setup` | Re-run configuration setup |
+| `ism-wifi config` | Display current configuration |
+| `ism-wifi login` | Single login attempt |
+| `ism-wifi reset` | Delete saved configuration |
+| `ism-wifi change-interval` | Change the connectivity check interval |
+| `ism-wifi version` | Print version |
+| `ism-wifi help` | Display usage |
+
+## Configuration
+
+Stored automatically at:
+
+- **Windows:** `C:\Users\<username>\.ism-wifi\config.json`
+- **Linux/macOS:** `~/.ism-wifi/config.json`
+
+## How It Works
+
+1. Every N seconds (default 30), the tool checks internet connectivity via `clients3.google.com/generate_204`
+2. If connectivity is lost, it posts your credentials to the ISM captive portal
+3. After a 3-second pause, it verifies the connection was restored
+4. If login fails, it retries with exponential backoff (1s, 2s, 4s, 8s, 16s, 30s)
+
+## Troubleshooting
+
+**Login keeps failing:** Run `ism-wifi setup` to re-enter your credentials.
+
+**SSL errors:** The tool disables SSL verification by default for the captive portal endpoint.
+
+## FAQ
+
+**Q: Does this run in the background?**  
+A: No, it runs in the terminal until you press Ctrl+C.
+
+**Q: Is my password stored securely?**  
+A: It is stored in plain text in your home directory. Use OS-level disk encryption for security.
+
+## Contributing
+
+Contributions welcome. Please open an issue or PR.
+
+## License
+
+MIT

package/bin/ism-wifi.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { run } from '../src/index.js'
+
+run()

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "ism-wifi",
+  "version": "1.0.0",
+  "description": "Auto-login to IIT ISM Dhanbad captive Wi-Fi portal",
+  "type": "module",
+  "bin": {
+    "ism-wifi": "./bin/ism-wifi.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "package.json",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "start": "node bin/ism-wifi.js"
+  },
+  "keywords": ["iit-ism", "wifi", "captive-portal", "cli"],
+  "license": "MIT",
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "chalk": "^5.4.0",
+    "commander": "^12.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,156 @@
+/** @module cli */
+
+import { Command } from 'commander'
+import { readFileSync } from 'fs'
+import { dirname, join } from 'path'
+import { fileURLToPath } from 'url'
+import { loadConfig, runSetup, showConfig, deleteConfig, updateInterval } from './config.js'
+import { startMonitor } from './monitor.js'
+import { login } from './login.js'
+import { sleep } from './utils.js'
+import { ok, fail } from './logger.js'
+import { BANNER, NO_CONFIG_MSG, SETUP_HEADER, CONFIG_SAVED_MSG, MONITORING_MSG } from './constants.js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const pkgPath = join(__dirname, '..', 'package.json')
+const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+
+/**
+ * Ensure config exists. If not, run setup.
+ * @returns {Promise<import('./config.js').Config>}
+ */
+async function ensureConfig() {
+  const existing = await loadConfig()
+  if (existing) return existing
+  return runSetup()
+}
+
+/**
+ * Default action — start monitoring.
+ */
+async function defaultAction() {
+  const config = await ensureConfig()
+  await startMonitor(config)
+}
+
+/**
+ * Setup command — re-run configuration.
+ */
+async function setupAction() {
+  await runSetup()
+}
+
+/**
+ * Config command — display current config.
+ */
+async function configAction() {
+  const config = await loadConfig()
+  if (!config) {
+    console.log('\nNo configuration found. Run: ism-wifi setup\n')
+    return
+  }
+  showConfig(config)
+}
+
+/**
+ * Login command — single login attempt.
+ */
+async function loginAction() {
+  const config = await loadConfig()
+  if (!config) {
+    console.log('\nNo configuration found. Run: ism-wifi setup\n')
+    return
+  }
+  console.log('')
+  const online = await login(config.username, config.password, config.verifySSL)
+  if (online) {
+    ok('Access Granted — Internet OK')
+  } else {
+    fail('Login failed')
+  }
+}
+
+/**
+ * Reset command — delete configuration.
+ */
+async function resetAction() {
+  const { confirm } = await import('@inquirer/prompts')
+  const answer = await confirm({
+    message: 'Are you sure you want to delete the saved configuration?',
+    default: false,
+  })
+  if (!answer) {
+    console.log('Aborted.')
+    return
+  }
+  const deleted = await deleteConfig()
+  if (deleted) {
+    console.log('Configuration deleted.')
+  } else {
+    console.log('No configuration found.')
+  }
+}
+
+/**
+ * Build and return the CLI program.
+ * @returns {Command}
+ */
+export function createProgram() {
+  const program = new Command()
+
+  program
+    .name('ism-wifi')
+    .description('Auto-login to IIT ISM Dhanbad captive Wi-Fi')
+    .version(pkg.version)
+    .helpOption('-h, --help', 'Display help')
+
+  program
+    .command('setup')
+    .description('Run interactive configuration setup')
+    .action(setupAction)
+
+  program
+    .command('config')
+    .description('Display current configuration')
+    .action(configAction)
+
+  program
+    .command('login')
+    .description('Perform a single login attempt and exit')
+    .action(loginAction)
+
+  program
+    .command('reset')
+    .description('Delete saved configuration')
+    .action(resetAction)
+
+  program
+    .command('change-interval')
+    .description('Change the connectivity check interval')
+    .action(() => updateInterval())
+
+  program
+    .command('version')
+    .description('Print package version')
+    .action(() => console.log(pkg.version))
+
+  program
+    .command('help')
+    .description('Display usage information')
+    .action(() => program.help())
+
+  return program
+}
+
+/**
+ * Main entry point.
+ */
+export async function run() {
+  const program = createProgram()
+
+  if (process.argv.length <= 2) {
+    await defaultAction()
+  } else {
+    program.parse(process.argv)
+  }
+}

package/src/config.js

@@ -0,0 +1,115 @@
+/** @module config */
+
+import { readFile, writeFile, unlink, mkdir } from 'fs/promises'
+import { existsSync } from 'fs'
+import { input, password, confirm, number } from '@inquirer/prompts'
+import { getConfigDir, getConfigPath, clampDelay, maskPassword } from './utils.js'
+import { BANNER, NO_CONFIG_MSG, SETUP_HEADER, CONFIG_SAVED_MSG, DEFAULT_CHECK_INTERVAL_S, MAX_RETRY_DELAY_S } from './constants.js'
+import { plain, info, ok } from './logger.js'
+
+/**
+ * @typedef {Object} Config
+ * @property {string} username
+ * @property {string} password
+ * @property {number} checkInterval
+ * @property {boolean} verifySSL
+ */
+
+/**
+ * Load configuration from disk.
+ * @returns {Promise<Config|null>}
+ */
+export async function loadConfig() {
+  const configPath = getConfigPath()
+  try {
+    const data = await readFile(configPath, 'utf-8')
+    return JSON.parse(data)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Save configuration to disk.
+ * @param {Config} config
+ * @returns {Promise<void>}
+ */
+export async function saveConfig(config) {
+  const dir = getConfigDir()
+  await mkdir(dir, { recursive: true })
+  await writeFile(getConfigPath(), JSON.stringify(config, null, 4), 'utf-8')
+}
+
+/**
+ * Delete the configuration file.
+ * @returns {Promise<boolean>}
+ */
+export async function deleteConfig() {
+  const configPath = getConfigPath()
+  if (!existsSync(configPath)) return false
+  await unlink(configPath)
+  return true
+}
+
+/**
+ * Update the check interval interactively.
+ * @returns {Promise<void>}
+ */
+export async function updateInterval() {
+  const config = await loadConfig()
+  if (!config) {
+    console.log('\nNo configuration found. Run: ism-wifi setup first.\n')
+    return
+  }
+
+  const oldInterval = config.checkInterval
+  const intervalStr = await input({
+    message: `New check interval in seconds (current: ${oldInterval}):`,
+    default: String(oldInterval),
+    validate: (val) => {
+      const num = Number(val)
+      if (Number.isNaN(num) || num < 1) return 'Must be a positive number'
+      if (num > MAX_RETRY_DELAY_S) return `Maximum is ${MAX_RETRY_DELAY_S} seconds`
+      return true
+    },
+  })
+
+  config.checkInterval = clampDelay(Number(intervalStr) || oldInterval)
+  await saveConfig(config)
+  console.log(`\nInterval updated: ${oldInterval} → ${config.checkInterval} seconds\n`)
+}
+
+/**
+ * Run interactive first-time (or re-) configuration.
+ * @returns {Promise<Config>}
+ */
+export async function runSetup() {
+  plain(BANNER)
+  plain(NO_CONFIG_MSG)
+  info(SETUP_HEADER)
+
+  const username = await input({ message: 'Username:', required: true })
+  const pwd = await password({ message: 'Password:', mask: true, required: true })
+  const intervalStr = await input({
+    message: 'Connectivity check interval [30]:',
+    default: String(DEFAULT_CHECK_INTERVAL_S),
+  })
+  const checkInterval = clampDelay(Number(intervalStr) || DEFAULT_CHECK_INTERVAL_S)
+
+  const config = { username, password: pwd, checkInterval, verifySSL: false }
+  await saveConfig(config)
+  plain(CONFIG_SAVED_MSG)
+  return config
+}
+
+/**
+ * Display current configuration (password masked).
+ * @param {Config} config
+ */
+export function showConfig(config) {
+  const { username, password, checkInterval, verifySSL } = config
+  console.log(`\nUsername : ${username}`)
+  console.log(`\nInterval : ${checkInterval} seconds`)
+  console.log(`\nSSL Verify : ${verifySSL}`)
+  console.log(`\nPassword : ${maskPassword(password)}\n`)
+}

package/src/connectivity.js

@@ -0,0 +1,22 @@
+/** @module connectivity */
+
+import { CONNECTIVITY_URL, CONNECTIVITY_TIMEOUT_MS } from './constants.js'
+
+/**
+ * Check whether the internet is reachable.
+ * Sends a GET to clients3.google.com/generate_204.
+ * Returns true only on HTTP 204.
+ * @returns {Promise<boolean>}
+ */
+export async function checkConnectivity() {
+  try {
+    const response = await fetch(CONNECTIVITY_URL, {
+      method: 'GET',
+      redirect: 'manual',
+      signal: AbortSignal.timeout(CONNECTIVITY_TIMEOUT_MS),
+    })
+    return response.status === 204
+  } catch {
+    return false
+  }
+}

package/src/constants.js

@@ -0,0 +1,24 @@
+/** @module constants */
+
+export const PORTAL_URL = 'https://netaccess.iitism.ac.in:6082/?url='
+export const CONNECTIVITY_URL = 'https://clients3.google.com/generate_204'
+export const CONFIG_DIR_NAME = '.ism-wifi'
+export const CONFIG_FILE_NAME = 'config.json'
+export const CONNECTIVITY_TIMEOUT_MS = 10_000
+export const VERIFY_WAIT_MS = 3_000
+export const DEFAULT_CHECK_INTERVAL_S = 30
+export const RETRY_DELAYS_S = [1, 2, 4, 8, 16, 30]
+export const MAX_RETRY_DELAY_S = 30
+
+export const BANNER = `
+======================================
+       ISM WiFi Auto Login
+======================================
+`
+
+export const NO_CONFIG_MSG = '\nNo configuration found.\n'
+export const SETUP_HEADER = "Let's configure ISM WiFi."
+export const CONFIG_SAVED_MSG = '\nConfiguration saved.\n'
+export const MONITORING_MSG = '\nStarting monitoring...\n'
+export const STOPPING_MSG = '\nStopping ISM WiFi...\n'
+export const GOODBYE_MSG = 'Goodbye!'

package/src/index.js

@@ -0,0 +1 @@
+export { run } from './cli.js'

package/src/logger.js

@@ -0,0 +1,46 @@
+/** @module logger */
+
+import chalk from 'chalk'
+import { formatTime } from './utils.js'
+
+/**
+ * Core log function.
+ * @param {string} message
+ * @param {'ok'|'fail'|'info'|'warn'|'granted'} type
+ */
+function log(message, type) {
+  const timestamp = chalk.gray(`[${formatTime()}]`)
+  let symbol
+  switch (type) {
+    case 'ok':
+      symbol = chalk.green('✓')
+      break
+    case 'fail':
+      symbol = chalk.red('✗')
+      break
+    case 'granted':
+      symbol = chalk.green('✓')
+      break
+    default:
+      symbol = ''
+  }
+  console.log(`\n${timestamp} ${symbol} ${message}`)
+}
+
+/** @param {string} msg */
+export function ok(msg) { log(msg, 'ok') }
+
+/** @param {string} msg */
+export function fail(msg) { log(msg, 'fail') }
+
+/** @param {string} msg */
+export function info(msg) { log(msg, 'info') }
+
+/** @param {string} msg */
+export function warn(msg) { log(msg, 'warn') }
+
+/** @param {string} msg */
+export function granted(msg) { log(msg, 'granted') }
+
+/** @param {string} msg */
+export function plain(msg) { console.log(msg) }

package/src/login.js

@@ -0,0 +1,38 @@
+/** @module login */
+
+import { Agent } from 'https'
+import { PORTAL_URL, VERIFY_WAIT_MS } from './constants.js'
+import { sleep } from './utils.js'
+import { checkConnectivity } from './connectivity.js'
+
+/**
+ * Attempt to log in to the ISM Wi-Fi portal.
+ * Posts credentials, waits, then verifies connectivity.
+ * @param {string} username
+ * @param {string} password
+ * @param {boolean} verifySSL
+ * @returns {Promise<boolean>}
+ */
+export async function login(username, password, verifySSL) {
+  const body = new URLSearchParams({ username, password })
+
+  const agent = verifySSL ? undefined : new Agent({ rejectUnauthorized: false })
+
+  try {
+    const response = await fetch(PORTAL_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: body.toString(),
+      signal: AbortSignal.timeout(15_000),
+      ...(agent ? { agent } : {}),
+    })
+
+    if (!response.ok) return false
+
+    await sleep(VERIFY_WAIT_MS)
+    return checkConnectivity()
+  } catch {
+    await sleep(VERIFY_WAIT_MS)
+    return checkConnectivity()
+  }
+}

package/src/monitor.js

@@ -0,0 +1,68 @@
+/** @module monitor */
+
+import { checkConnectivity } from './connectivity.js'
+import { login } from './login.js'
+import { sleep } from './utils.js'
+import { RETRY_DELAYS_S, MONITORING_MSG, STOPPING_MSG, GOODBYE_MSG } from './constants.js'
+import { ok, fail, info, granted, plain } from './logger.js'
+
+let running = false
+
+/**
+ * Start the monitoring loop.
+ * @param {import('./config.js').Config} config
+ */
+export async function startMonitor(config) {
+  running = true
+
+  process.on('SIGINT', handleSigint)
+
+  plain(MONITORING_MSG)
+
+  while (running) {
+    const online = await checkConnectivity()
+
+    if (online) {
+      ok('Internet OK')
+    } else {
+      fail('Internet unavailable')
+      await attemptLoginWithBackoff(config)
+    }
+
+    if (!running) break
+    await sleep(config.checkInterval * 1000)
+  }
+}
+
+/**
+ * Attempt login with exponential backoff.
+ * @param {import('./config.js').Config} config
+ */
+async function attemptLoginWithBackoff(config) {
+  for (const delay of RETRY_DELAYS_S) {
+    if (!running) return
+
+    info('Logging in...')
+
+    const success = await login(config.username, config.password, config.verifySSL)
+
+    if (success) {
+      granted('Access Granted')
+      ok('Internet restored')
+      return
+    }
+
+    fail('Login failed, retrying...')
+    await sleep(delay * 1000)
+  }
+}
+
+/**
+ * Handle Ctrl+C gracefully.
+ */
+function handleSigint() {
+  running = false
+  plain(STOPPING_MSG)
+  plain(GOODBYE_MSG)
+  process.exit(0)
+}

package/src/utils.js

@@ -0,0 +1,61 @@
+/** @module utils */
+
+import { homedir } from 'os'
+import { join } from 'path'
+import { CONFIG_DIR_NAME, CONFIG_FILE_NAME, MAX_RETRY_DELAY_S } from './constants.js'
+
+/**
+ * Sleep for a given number of milliseconds.
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+export function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+/**
+ * Format a Date as HH:MM:SS.
+ * @param {Date} [date]
+ * @returns {string}
+ */
+export function formatTime(date = new Date()) {
+  const h = String(date.getHours()).padStart(2, '0')
+  const m = String(date.getMinutes()).padStart(2, '0')
+  const s = String(date.getSeconds()).padStart(2, '0')
+  return `${h}:${m}:${s}`
+}
+
+/**
+ * Mask a string, showing only the first character.
+ * @param {string} str
+ * @returns {string}
+ */
+export function maskPassword(str) {
+  if (!str || str.length === 0) return ''
+  return str[0] + '*'.repeat(str.length - 1)
+}
+
+/**
+ * Get the config directory path.
+ * @returns {string}
+ */
+export function getConfigDir() {
+  return join(homedir(), CONFIG_DIR_NAME)
+}
+
+/**
+ * Get the full config file path.
+ * @returns {string}
+ */
+export function getConfigPath() {
+  return join(getConfigDir(), CONFIG_FILE_NAME)
+}
+
+/**
+ * Clamp a value to max 30 seconds.
+ * @param {number} seconds
+ * @returns {number}
+ */
+export function clampDelay(seconds) {
+  return Math.min(seconds, MAX_RETRY_DELAY_S)
+}