9alma-app

v3.3.3

Published

3 days ago

9alma — Activation & License Management Assistant. A web dashboard for M******ft product activation: convert Installation IDs (IID) into Confirmation IDs (CID) with multi-account support, automatic OCR, a REST API, and self-update.

Downloads

1,040

0High
0Medium
0Low

oliverawi

9alma activation license cid confirmation-id installation-id ocr dashboard oauth2 dpop

9alma

Activation & License Management Assistant

A web dashboard for M******ft product activation. Convert Installation IDs (IID) into Confirmation IDs (CID) with multi-account support, automatic OCR, a REST API, and self-update.

Quick Start (for Users)

1. Install

npm install -g 9alma-app

2. Run

9alma

The browser will open automatically at http://localhost:8556.

3. First Login

Username: superadmin
Password: superadmin

You will be asked to change your password after the first login.

4. Set Up an M******ft Account

Log in to the dashboard
Go to Token Manager → Setup New Token
Follow the device code flow (sign in with your M******ft account)

5. Configure OCR (optional)

Settings → OCR.space API Key
Sign up for a free key at https://ocr.space/ocrapi/freekey
Paste the key → Save

6. Generate a CID

Go to Generate CID
Paste a 54 or 63 digit IID, or drag and drop a screenshot
Click Generate CID

Updating

Automatic (via Dashboard)

When a new version is available, the sidebar will display:

↑ New version: v3.2.2
[Update Now]
npm i -g 9alma-app@latest --prefer-online

Click Update Now, or copy the command to install manually.

Manual

npm install -g 9alma-app@latest --prefer-online

Data Location

The database and configuration are stored in:

Windows: C:\Users\<username>\.9alma\accounts.db
macOS / Linux: ~/.9alma/accounts.db

This data is not removed during updates.

Features

✅ OAuth2 Device Code Flow for M******ft sign-in
✅ Auto-refreshing tokens (in the background)
✅ Multi-account support with round-robin mode
✅ DPoP-signed JWT requests
✅ Automatic OCR (paste / drop a screenshot to extract the IID)
✅ Realtime token countdown on the accounts page
✅ REST API with token authentication
✅ Role-based access control (superadmin / admin / user)
✅ Endpoint management (enable / disable per endpoint)
✅ Self-update via the npm registry

REST API Usage

After generating an API token from the API Keys page:

Generate a CID

curl -X POST http://localhost:8556/validate \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"iid": "YOUR_63_OR_54_DIGIT_IID"}'

OCR + Generate CID (one-shot)

curl -X POST http://localhost:8556/api/ocr-validate \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"image": "data:image/jpeg;base64,..."}'

Health Check

curl http://localhost:8556/health

For Developers

Requirements

Node.js >= 18
npm 8+

Local Development

git clone https://github.com/oliverawi/9alma.git
cd 9alma
npm install
npm start            # production-like
npm run dev          # nodemon hot-reload

Project Structure

9alma/
├── bin/9alma.js          # CLI entry point
├── src/                  # Source code
│   ├── app.js            # Express app and routes
│   ├── config.js         # Default values and config metadata
│   ├── db.js             # SQLite schema and helpers
│   ├── auth.js           # Session and role middleware
│   ├── oauth.js          # OAuth, DPoP and OCR
│   ├── crypto-utils.js   # DPoP JWT, IID parser
│   ├── seed-endpoints.js # Default API endpoints
│   ├── updater.js        # npm-based self-updater
│   └── banner.js         # Terminal banner with IP info
├── views/                # EJS templates
├── public/               # Static CSS / JS
├── VERSION.txt
├── package.json
├── .gitignore
└── .npmignore

Publishing a New Version

# 1. Bump the version
npm version patch                                  # 3.2.1 → 3.2.2
node -e "require('fs').writeFileSync('VERSION.txt', require('./package.json').version + '\n')"

# 2. Push to GitHub
git add .
git commit -m "Release v3.2.2"
git push origin main --tags

# 3. Publish to npm
npm publish

Existing users will be notified about the new version on the dashboard sidebar within 30 minutes (polling interval).

Security

Session security: The secret key is regenerated on every startup, so old sessions are invalidated after a restart.
API token auth: Each user has an independent API token that inherits their role.
DPoP signing: Every request to the upstream API is signed with a per-account EC private key.
Database isolation: Data is stored in ~/.9alma/, untouched by updates.

Configuration

All configuration can be changed from the Settings page (superadmin only):

| Category | Key | Description | |----------|-----|-------------| | OAuth | ms_client_id | Application client ID | | OAuth | ms_token_url | OAuth2 token endpoint | | OAuth | ms_device_code_url | Device code endpoint | | OAuth | ms_scope | OAuth2 scopes | | Visual Support API | visual_api_url | Validation endpoint URL | | Visual Support API | visual_api_path | Path used for the DPoP signature | | OCR | ocr_api_key | OCR.space API key (free tier is fine) | | OCR | ocr_api_url | OCR.space endpoint | | OCR | ocr_language | Language code (default: eng) | | OCR | ocr_engines | Engines to try (default: 2,3,1) | | Session | session_lifetime_minutes | Session timeout in minutes | | Server | server_port | HTTP port (default: 8556) | | Server | server_host | Bind address (default: 0.0.0.0) |

License

UNLICENSED (private use)