9alma

Activation & License Management Assistant

A web dashboard for M****ft product activation. Convert I****n Ds (IID) into C**tion *Ds (CID) with multi-account support, automatic OCR, a REST API, and self-update.

⚠️ Disclaimer

This project is provided strictly for educational, research, testing, and personal development purposes.

• The author is NOT responsible for any misuse of this software.
• The author is NOT affiliated with, sponsored by, endorsed by, or working in cooperation with any company, organization, or third party referenced in this project.
• This software is NOT intended to harm, defraud, or cause loss to any person, company, or entity.
• Any user of this software is fully responsible for ensuring their use complies with all applicable laws, regulations, and the terms of service of any third-party platform.
• Use at your own risk. The software is provided "AS IS" without warranty of any kind.

By installing or using this software you acknowledge and accept the terms above.

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.x.x
[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 (supervisor)
├── 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 / images
├── build/obfuscate.js    # Source obfuscation build script
├── VERSION.txt
├── package.json
├── .gitignore
└── .npmignore

Publishing a New Version

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

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

# 3. Publish to npm (prepublishOnly auto-runs source obfuscation)
npm publish

Existing users will be notified about the new version on the dashboard sidebar within 30 minutes (polling interval). The supervisor in bin/9alma.js will auto-restart the app in place after a successful update.

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 | | VL S*****t API | visual_api_url | Validation endpoint URL | | VL S*****t 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) |

Links

• npm: https://www.npmjs.com/package/9alma-app
• Issues: https://github.com/oliverawi/9alma/issues

License

No Warranty / No Liability — Personal & Educational Use Only

This software is released without any warranty, express or implied. The author provides this project free of charge for educational, research, testing, and personal development purposes only.

• No liability: The author shall not be held liable for any direct, indirect, incidental, special, consequential, or punitive damages arising out of the use, misuse, or inability to use this software.
• No affiliation: This project is an independent work. It is not affiliated with, endorsed by, or sponsored by any company, organization, or third party referenced (directly or indirectly) in the source code, documentation, or runtime output.
• No malicious intent: This project is not designed to defraud, harm, or cause loss to any person or entity.
• User responsibility: Each user is solely responsible for verifying that their use of this software complies with all applicable laws, regulations, and third-party terms of service in their jurisdiction.

By downloading, installing, or running this software, you accept these terms in full.

Credits

Powered by Logic 💪