Majik API

Majik API is an API key management library designed for the Majikah ecosystem. It provides a robust, developer-friendly interface for creating, hashing, and managing API keys with built-in support for rate limiting, IP/Domain whitelisting, and secure rotation.

---

• Majik API
  • Technical Architecture
    • 1. Security via SHA-256 Hashing
    • 2. Identity Persistence (UUID)
    • 3. Rate Limit Enforcement
  • Features
  • Installation
  • Quick Start
  • API Reference
    • Instance Getters
    • Static Methods
    • Instance Methods: Key Management
    • Instance Methods: Constraints & Whitelisting
  • Contributing
  • License
  • Author
  • About the Developer
  • Contact

---

Technical Architecture

1. Security via SHA-256 Hashing

The library ensures that the raw plaintext API key is never stored within the permanent state of the object. Upon creation or rotation, the key is immediately hashed using SHA-256. The rawApiKey property is a temporary field provided only during the initial generation/rotation event to allow for one-time display to the user.

2. Identity Persistence (UUID)

Each key instance maintains a stable id (UUIDv4). This ID remains constant even if the API key text is rotated, allowing for consistent Foreign Key relationships in databases (like Supabase) or audit logs.

3. Rate Limit Enforcement

The class includes built-in logic to normalize and validate rate limits. It enforces a "Safe Limit" ceiling of 500 requests per minute by default. Any attempt to set a limit higher than this requires an explicit bypassSafeLimit flag.

---

Features

• Automated Lifecycle: Manage active, restricted, and expired statuses automatically based on timestamps and boolean flags.

• IP Whitelisting: Supports individual IP addresses and CIDR notation validation.

• Domain Whitelisting: Validates domains with support for wildcard (*) subdomains.

• Status Calculation: Dynamic status getter that evaluates if a key is revoked, expired, or active.

• JSON Serialization: Methods to export/import the class state for database storage (storing only hashes, never raw keys).

---

Installation

# Using npm
npm install @majikah/majik-api

---

Quick Start

import { MajikAPI } from '@majikah/majik-api';

// Create a new key for a specific owner
const key = MajikAPI.create('owner_user_id', undefined, {
  name: 'Production Environment Key'
});

// Capture the raw key once (it won't be in the object after serialization)
console.log('Provide this to user:', key.rawApiKey);

// Save to DB (this only saves the SHA-256 hash)
const data = key.toJSON();
// ... save data to your database ...

// Verifying a request later
const isValid = key.verify('key_provided_by_client'); // returns boolean

---

API Reference

Instance Getters

Property	Type	Description
id	string	The stable UUIDv4 identifier for the record.
ownerId	string	The identifier of the key owner (e.g., a user ID).
name	string	Human-readable label for the API key.
apiKey	string	The SHA-256 hash of the API key.
rawApiKey	string | undefined	The plaintext key. Only populated immediately after create() or rotate().
timestamp	string	ISO 8601 string of the last rotation or creation time.
restricted	boolean	Manual toggle indicating if the key is administratively disabled.
validUntil	string | null	ISO 8601 expiration date, or null if the key never expires.
settings	MajikAPISettings	A structured clone of the key's rate limits and whitelist configurations.
status	'revoked' | 'expired' | 'active'	Returns the current operational state based on internal flags and time.
msUntilExpiry	number	Milliseconds remaining until validUntil. Returns -1 if no expiry is set.

---

Static Methods

Method	Parameters	Return Type	Description
create	ownerID: string, text?: string, options?: MajikAPICreateOptions	MajikAPI	Instantiates a new key. Generates a random UUID as the key if text is omitted.
fromJSON	json: MajikAPIJSON	MajikAPI	Reconstructs an instance from a serialized data object.

---

Instance Methods: Key Management

Method	Parameters	Return Type	Description
verify	text: string	boolean	Hashes the input string and performs a constant-time comparison against the stored hash.
rotate	text?: string	void	Generates a new hash and updates the timestamp. Populates rawApiKey with the new plaintext.
revoke	None	void	Permanently disables the key by setting restricted to true and the expiry to 1970-01-01.
isActive	None	boolean	Returns true if the key is not restricted and not expired.
setName	name: string	void	Updates the human-readable label.
setRestricted	restricted: boolean	void	Manually enables or disables the key.
toJSON	None	MajikAPIJSON	Serializes the instance into a plain object for database storage.

---

Instance Methods: Constraints & Whitelisting

Method	Parameters	Return Type	Description
setExpiry	date: Date | string | null	void	Updates the valid_until property. Accepts Date objects or ISO strings.
setRateLimit	amount: number, freq: RateLimitFrequency, bypass?: boolean	void	Sets requests per window. Caps at 500 req/min unless bypassSafeLimit is true.
enableIPWhitelist	None	void	Enables the IP restriction check.
disableIPWhitelist	None	void	Disables the IP restriction check.
addIP	ip: string	void	Adds an IPv4, IPv6, or CIDR range to the whitelist.
removeIP	ip: string	void	Removes a specific IP/range from the whitelist.
enableDomainWhitelist	None	void	Enables the Domain restriction check.
disableDomainWhitelist	None	void	Disables the Domain restriction check.
addDomain	domain: string	void	Adds a domain (supports *.example.com wildcards) to the whitelist.
removeDomain	domain: string	void	Removes a specific domain from the whitelist.

---

Contributing

If you want to contribute or help extend support to more platforms, reach out via email. All contributions are welcome!

---

License

Apache-2.0 — free for personal and commercial use.

---

Author

Made with 💙 by @thezelijah

About the Developer

• Developer: Josef Elijah Fabian
• GitHub: https://github.com/jedlsf
• Project Repository: https://github.com/Majikah/majik-api

---

Contact

• Business Email: business@thezelijah.world
• Official Website: https://www.thezelijah.world