@majikah/majik-api 0.1.0

package/LICENSE

@@ -0,0 +1,67 @@
+Copyright (c) 2025 Josef Elijah Delos Santos Fabian
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+---
+
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of this License; and
+You must cause any modified files to carry prominent notices stating that You changed the files; and
+You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,185 @@
+# Majik API
+
+[![Developed by Zelijah](https://img.shields.io/badge/Developed%20by-Zelijah-red?logo=github&logoColor=white)](https://thezelijah.world) ![GitHub Sponsors](https://img.shields.io/github/sponsors/jedlsf?style=plastic&label=Sponsors&link=https%3A%2F%2Fgithub.com%2Fsponsors%2Fjedlsf)
+
+**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.
+
+![npm](https://img.shields.io/npm/v/@majikah/majik-api) ![npm downloads](https://img.shields.io/npm/dm/@majikah/majik-api) ![npm bundle size](https://img.shields.io/bundlephobia/min/%40majikah%2Fmajik-api) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) ![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)
+
+
+
+---
+- [Majik API](#majik-api)
+  - [Technical Architecture](#technical-architecture)
+    - [1. Security via SHA-256 Hashing](#1-security-via-sha-256-hashing)
+    - [2. Identity Persistence (UUID)](#2-identity-persistence-uuid)
+    - [3. Rate Limit Enforcement](#3-rate-limit-enforcement)
+  - [Features](#features)
+  - [Installation](#installation)
+  - [Quick Start](#quick-start)
+  - [API Reference](#api-reference)
+    - [Instance Getters](#instance-getters)
+    - [Static Methods](#static-methods)
+    - [Instance Methods: Key Management](#instance-methods-key-management)
+    - [Instance Methods: Constraints \& Whitelisting](#instance-methods-constraints--whitelisting)
+  - [Contributing](#contributing)
+  - [License](#license)
+  - [Author](#author)
+  - [About the Developer](#about-the-developer)
+  - [Contact](#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
+
+```bash
+# Using npm
+npm install @majikah/majik-api
+
+```
+
+---
+
+## Quick Start
+
+```ts
+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](LICENSE) — free for personal and commercial use.
+
+---
+## Author
+
+Made with 💙 by [@thezelijah](https://github.com/jedlsf)
+
+## About the Developer
+
+- **Developer**: Josef Elijah Fabian
+- **GitHub**: [https://github.com/jedlsf](https://github.com/jedlsf)
+- **Project Repository**: [https://github.com/Majikah/majik-api](https://github.com/Majikah/majik-api)
+
+---
+
+## Contact
+
+- **Business Email**: [business@thezelijah.world](mailto:business@thezelijah.world)
+- **Official Website**: [https://www.thezelijah.world](https://www.thezelijah.world)

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./majik-api";
+export type * from "./types";

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./majik-api";

package/dist/majik-api.d.ts

@@ -0,0 +1,173 @@
+import type { DomainWhitelist, IPWhitelist, MajikAPICreateOptions, MajikAPIJSON, MajikAPISettings, RateLimit, RateLimitFrequency } from "./types";
+export declare const DEFAULT_RATE_LIMIT: RateLimit;
+/**
+ * Hard ceiling for any rate limit set on a MajikAPI key.
+ * No key — regardless of trust level — may exceed this without bypassSafeLimit.
+ * Expressed in req/min for normalisation purposes; stored as a RateLimit for
+ * consistency with the rest of the API.
+ */
+export declare const MAX_RATE_LIMIT: RateLimit;
+export declare class MajikAPI {
+    private readonly _id;
+    private readonly _owner_id;
+    private _name;
+    private _api_key;
+    private _raw_api_key;
+    private readonly _timestamp;
+    private _restricted;
+    private _valid_until;
+    private _settings;
+    private constructor();
+    /**
+     * Create a brand-new MajikAPI key instance.
+     *
+     * @param ownerID - UUID of the user who owns this key. Required.
+     * @param text    - Optional raw key text. If omitted, a UUIDv4 is generated.
+     * @param options - Optional name, expiry, restrictions, and settings.
+     *
+     * After creation, `instance.rawApiKey` holds the plaintext key. This is the
+     * only moment it is accessible. Store it safely — it cannot be recovered.
+     */
+    static create(ownerID: string, text?: string, options?: MajikAPICreateOptions): MajikAPI;
+    /**
+     * Reconstruct a MajikAPI instance from a serialised MajikAPIJSON object.
+     * Accepts the raw output of `toJSON()`, a Supabase row, or a Redis cache hit.
+     *
+     * `raw_api_key` is intentionally NOT restored — it is never in the JSON.
+     */
+    static fromJSON(data: MajikAPIJSON): MajikAPI;
+    /**
+     * Serialise to a plain JSON-safe object matching MajikAPIJSON.
+     * Safe to store in Supabase or cache in Redis.
+     * raw_api_key is NEVER included.
+     */
+    toJSON(): MajikAPIJSON;
+    /**
+     * Assert the integrity of all fields on this instance.
+     * Throws a descriptive error for the first field that fails.
+     */
+    validate(): void;
+    /**
+     * Hash `text` and compare against the stored api_key hash.
+     * This is the correct way to verify an incoming key at your API gateway.
+     * Returns true if the key matches.
+     */
+    verify(text: string): boolean;
+    /** Alias for verify(). */
+    matches(text: string): boolean;
+    /** Returns true if valid_until is set and has passed. Always false if null. */
+    isExpired(): boolean;
+    /** Returns true only if the key is not expired and not restricted. */
+    isActive(): boolean;
+    /**
+     * Set the rate limit for this key.
+     *
+     * The effective rate (normalised to req/min) cannot exceed MAX_RATE_LIMIT
+     * (500 req/min). Attempting to set a higher rate will throw unless
+     * bypassSafeLimit is explicitly passed as true.
+     *
+     * @param amount        - Number of allowed requests per frequency window.
+     * @param frequency     - The time window unit.
+     * @param bypassSafeLimit - When true, skips the MAX_RATE_LIMIT ceiling check.
+     *                        Defaults to false. Use with caution.
+     */
+    setRateLimit(amount: number, frequency: RateLimitFrequency, bypassSafeLimit?: boolean): void;
+    /** Reset the rate limit back to DEFAULT_RATE_LIMIT. */
+    resetRateLimit(): void;
+    /**
+     * Rotate the API key. Generates a new raw key (or accepts a provided one),
+     * hashes it, and replaces _api_key. The stable _id and _owner_id are
+     * untouched, so all FK references in audit/event tables remain valid.
+     *
+     * After rotation, `rawApiKey` holds the new plaintext key. This is the only
+     * moment it is accessible. The old key is immediately invalidated in-memory.
+     *
+     * IMPORTANT: After calling rotate(), you must:
+     *   1. Save the new toJSON() to Supabase (updates the api_key column).
+     *   2. Delete the old Redis cache entry (old hash key is now stale).
+     *   3. Show the caller rawApiKey before discarding this instance.
+     *
+     * @param text - Optional new raw key. If omitted, a UUIDv4 is generated.
+     */
+    rotate(text?: string): void;
+    /** Rename this key. */
+    rename(name: string): void;
+    /**
+     * Set or clear the expiry date.
+     * Pass null to make the key never expire.
+     */
+    setExpiry(date: Date | string | null): void;
+    /** Disable this key without deleting it. */
+    restrict(): void;
+    /** Re-enable a previously restricted key. */
+    unrestrict(): void;
+    /**
+     * Permanently revoke this key. Sets valid_until to epoch (always expired)
+     * and marks it restricted. Both flags must be cleared to undo this — prefer
+     * deleting the Supabase row and creating a new key instead.
+     */
+    revoke(): void;
+    enableIPWhitelist(): void;
+    disableIPWhitelist(): void;
+    addIP(ip: string): void;
+    removeIP(ip: string): void;
+    setIPWhitelist(addresses: string[]): void;
+    clearIPWhitelist(): void;
+    enableDomainWhitelist(): void;
+    disableDomainWhitelist(): void;
+    addDomain(domain: string): void;
+    removeDomain(domain: string): void;
+    setDomainWhitelist(domains: string[]): void;
+    clearDomainWhitelist(): void;
+    setAllowedMethods(methods: string[]): void;
+    clearAllowedMethods(): void;
+    setMetadata(key: string, value: unknown): void;
+    getMetadata(key: string): unknown;
+    deleteMetadata(key: string): void;
+    clearMetadata(): void;
+    /** The key's own stable UUID. Primary key in Supabase. */
+    get id(): string;
+    /** UUID of the user who owns this key. FK to auth.users. */
+    get ownerId(): string;
+    get name(): string;
+    /**
+     * The SHA-256 hash of the raw key. This is what is stored in Supabase and
+     * used as the Redis cache key prefix. Never the plaintext.
+     */
+    get apiKey(): string;
+    /**
+     * The raw plaintext key. Only defined immediately after create() or rotate().
+     * Undefined after fromJSON() or any serialise/deserialise round-trip.
+     * Treat this like a password — show it once and discard.
+     */
+    get rawApiKey(): string | undefined;
+    get createdAt(): Date;
+    get timestamp(): string;
+    get restricted(): boolean;
+    get validUntil(): Date | null;
+    /** Returns a deep clone — mutations to the returned object have no effect. */
+    get settings(): Readonly<MajikAPISettings>;
+    get rateLimit(): Readonly<RateLimit>;
+    get ipWhitelist(): Readonly<IPWhitelist>;
+    get domainWhitelist(): Readonly<DomainWhitelist>;
+    get allowedMethods(): string[];
+    /**
+     * Milliseconds until this key expires.
+     * Returns -1 if the key never expires (valid_until is null).
+     * Returns 0 if the key has already expired.
+     */
+    get msUntilExpiry(): number;
+    /**
+     * Human-readable lifecycle status.
+     *
+     * "active"     — valid, not restricted, not expired.
+     * "restricted" — manually disabled, not expired.
+     * "expired"    — past valid_until date.
+     * "revoked"    — permanently invalidated via revoke().
+     */
+    get status(): "active" | "restricted" | "expired" | "revoked";
+    private static parseDate;
+    private static validateSettings;
+    toString(): string;
+}
+export default MajikAPI;

package/dist/majik-api.js

@@ -0,0 +1,642 @@
+import { generateID, sha256 } from "./utils";
+// ─────────────────────────────────────────────
+//  Constants
+// ─────────────────────────────────────────────
+export const DEFAULT_RATE_LIMIT = {
+    amount: 100,
+    frequency: "minutes",
+};
+/**
+ * Hard ceiling for any rate limit set on a MajikAPI key.
+ * No key — regardless of trust level — may exceed this without bypassSafeLimit.
+ * Expressed in req/min for normalisation purposes; stored as a RateLimit for
+ * consistency with the rest of the API.
+ */
+export const MAX_RATE_LIMIT = {
+    amount: 500,
+    frequency: "minutes",
+};
+/** Multipliers to convert each frequency unit into requests-per-minute. */
+const TO_MINUTES = {
+    seconds: 1 / 60,
+    minutes: 1,
+    hours: 60,
+};
+// ─────────────────────────────────────────────
+//  Validation Helpers
+// ─────────────────────────────────────────────
+function assertString(value, label) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new TypeError(`[MajikAPI] "${label}" must be a non-empty string. Received: ${JSON.stringify(value)}`);
+    }
+}
+function assertPositiveInteger(value, label) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+        throw new RangeError(`[MajikAPI] "${label}" must be a positive integer. Received: ${JSON.stringify(value)}`);
+    }
+}
+function assertRateLimitFrequency(value, label) {
+    const valid = ["seconds", "minutes", "hours"];
+    if (!valid.includes(value)) {
+        throw new TypeError(`[MajikAPI] "${label}" must be one of: ${valid.join(", ")}. Received: ${JSON.stringify(value)}`);
+    }
+}
+function assertBoolean(value, label) {
+    if (typeof value !== "boolean") {
+        throw new TypeError(`[MajikAPI] "${label}" must be a boolean. Received: ${JSON.stringify(value)}`);
+    }
+}
+function assertStringArray(value, label) {
+    if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
+        throw new TypeError(`[MajikAPI] "${label}" must be an array of strings. Received: ${JSON.stringify(value)}`);
+    }
+}
+function isValidIPv4(ip) {
+    return (/^(\d{1,3}\.){3}\d{1,3}$/.test(ip) &&
+        ip.split(".").every((o) => parseInt(o) <= 255));
+}
+function isValidIPv6(ip) {
+    return /^[0-9a-fA-F:]+$/.test(ip) && ip.includes(":");
+}
+function isValidCIDR(cidr) {
+    const [ip, prefix] = cidr.split("/");
+    if (!prefix)
+        return false;
+    const p = parseInt(prefix);
+    return ((isValidIPv4(ip) && p >= 0 && p <= 32) ||
+        (isValidIPv6(ip) && p >= 0 && p <= 128));
+}
+function validateIP(ip) {
+    if (!isValidIPv4(ip) && !isValidIPv6(ip) && !isValidCIDR(ip)) {
+        throw new Error(`[MajikAPI] Invalid IP address or CIDR: "${ip}"`);
+    }
+}
+function isValidDomain(domain) {
+    return (/^(\*\.)?[a-zA-Z0-9]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z]{2,})+$/.test(domain) || /^\*$/.test(domain));
+}
+function validateDomain(domain) {
+    if (!isValidDomain(domain)) {
+        throw new Error(`[MajikAPI] Invalid domain: "${domain}"`);
+    }
+}
+function isValidISODate(value) {
+    const d = new Date(value);
+    return !isNaN(d.getTime());
+}
+// ─────────────────────────────────────────────
+//  Default Settings Factory
+// ─────────────────────────────────────────────
+function buildDefaultSettings(overrides) {
+    return {
+        rateLimit: { ...DEFAULT_RATE_LIMIT, ...(overrides?.rateLimit ?? {}) },
+        ipWhitelist: {
+            enabled: false,
+            addresses: [],
+            ...(overrides?.ipWhitelist ?? {}),
+        },
+        domainWhitelist: {
+            enabled: false,
+            domains: [],
+            ...(overrides?.domainWhitelist ?? {}),
+        },
+        allowedMethods: overrides?.allowedMethods ?? [],
+        metadata: overrides?.metadata ?? {},
+    };
+}
+// ─────────────────────────────────────────────
+//  MajikAPI Class
+// ─────────────────────────────────────────────
+export class MajikAPI {
+    // ── Private fields ───────────────────────────────────────────────────────
+    //
+    //  _id        — stable UUID. Primary key in Supabase. Never changes even
+    //               when the key is rotated. Safe to FK against in audit tables.
+    //
+    //  _owner_id  — UUID of the user who owns this key. FK to auth.users.
+    //
+    //  _api_key   — SHA-256 hash of the raw plaintext key. Has a UNIQUE INDEX
+    //               in Postgres (not the PK). Used as the Redis cache key.
+    //               The raw key is never stored or logged anywhere.
+    //
+    //  _raw_api_key — Only populated immediately after create(). Cleared
+    //                 (undefined) when reconstructed via fromJSON(). This is
+    //                 the one and only moment the caller can read the plaintext.
+    // ─────────────────────────────────────────────────────────────────────────
+    _id;
+    _owner_id;
+    _name;
+    _api_key;
+    _raw_api_key;
+    _timestamp;
+    _restricted;
+    _valid_until;
+    _settings;
+    // ─────────────────────────────────────────────
+    //  Private Constructor
+    // ─────────────────────────────────────────────
+    constructor(id, owner_id, name, api_key, timestamp, restricted, valid_until, settings, raw_api_key) {
+        this._id = id;
+        this._owner_id = owner_id;
+        this._name = name;
+        this._api_key = api_key;
+        this._timestamp = timestamp;
+        this._restricted = restricted;
+        this._valid_until = valid_until;
+        this._settings = settings;
+        this._raw_api_key = raw_api_key;
+    }
+    // ─────────────────────────────────────────────
+    //  Static Factory: create()
+    // ─────────────────────────────────────────────
+    /**
+     * Create a brand-new MajikAPI key instance.
+     *
+     * @param ownerID - UUID of the user who owns this key. Required.
+     * @param text    - Optional raw key text. If omitted, a UUIDv4 is generated.
+     * @param options - Optional name, expiry, restrictions, and settings.
+     *
+     * After creation, `instance.rawApiKey` holds the plaintext key. This is the
+     * only moment it is accessible. Store it safely — it cannot be recovered.
+     */
+    static create(ownerID, text, options = {}) {
+        assertString(ownerID, "ownerID");
+        // Resolve raw key
+        let rawKey;
+        if (text !== undefined) {
+            if (typeof text !== "string" || text.trim() === "") {
+                throw new TypeError("[MajikAPI] create(): 'text' must be a non-empty string if provided.");
+            }
+            rawKey = text.trim();
+        }
+        else {
+            rawKey = generateID();
+        }
+        const name = options.name ?? "Unnamed Key";
+        if (typeof name !== "string" || name.trim() === "") {
+            throw new TypeError("[MajikAPI] create(): 'options.name' must be a non-empty string.");
+        }
+        const restricted = options.restricted ?? false;
+        assertBoolean(restricted, "options.restricted");
+        let valid_until = null;
+        if (options.valid_until !== undefined && options.valid_until !== null) {
+            valid_until = MajikAPI.parseDate(options.valid_until, "options.valid_until");
+            if (valid_until <= new Date()) {
+                throw new RangeError("[MajikAPI] create(): 'valid_until' must be a future date.");
+            }
+        }
+        const settings = buildDefaultSettings(options.settings);
+        MajikAPI.validateSettings(settings);
+        return new MajikAPI(generateID(), // _id        — stable primary key, separate from the key hash
+        ownerID.trim(), // _owner_id
+        name.trim(), // _name
+        sha256(rawKey), // _api_key   — hash only, never store raw
+        new Date(), // _timestamp
+        restricted, valid_until, settings, rawKey);
+    }
+    // ─────────────────────────────────────────────
+    //  Static Factory: fromJSON()
+    // ─────────────────────────────────────────────
+    /**
+     * Reconstruct a MajikAPI instance from a serialised MajikAPIJSON object.
+     * Accepts the raw output of `toJSON()`, a Supabase row, or a Redis cache hit.
+     *
+     * `raw_api_key` is intentionally NOT restored — it is never in the JSON.
+     */
+    static fromJSON(data) {
+        if (typeof data !== "object" || data === null || Array.isArray(data)) {
+            throw new TypeError("[MajikAPI] fromJSON(): Expected a plain object.");
+        }
+        assertString(data.id, "id");
+        assertString(data.owner_id, "owner_id");
+        assertString(data.name, "name");
+        assertString(data.api_key, "api_key");
+        assertString(data.timestamp, "timestamp");
+        if (!isValidISODate(data.timestamp)) {
+            throw new TypeError(`[MajikAPI] fromJSON(): 'timestamp' is not a valid ISO date: "${data.timestamp}"`);
+        }
+        if (typeof data.restricted !== "boolean") {
+            throw new TypeError("[MajikAPI] fromJSON(): 'restricted' must be a boolean.");
+        }
+        if (data.valid_until !== null && data.valid_until !== undefined) {
+            assertString(data.valid_until, "valid_until");
+            if (!isValidISODate(data.valid_until)) {
+                throw new TypeError("[MajikAPI] fromJSON(): 'valid_until' is not a valid ISO date.");
+            }
+        }
+        if (typeof data.settings !== "object" || data.settings === null) {
+            throw new TypeError("[MajikAPI] fromJSON(): 'settings' must be an object.");
+        }
+        const settings = buildDefaultSettings(data.settings);
+        MajikAPI.validateSettings(settings);
+        return new MajikAPI(data.id, data.owner_id, data.name, data.api_key, new Date(data.timestamp), data.restricted, data.valid_until ? new Date(data.valid_until) : null, settings, undefined);
+    }
+    // ─────────────────────────────────────────────
+    //  Serialisation
+    // ─────────────────────────────────────────────
+    /**
+     * Serialise to a plain JSON-safe object matching MajikAPIJSON.
+     * Safe to store in Supabase or cache in Redis.
+     * raw_api_key is NEVER included.
+     */
+    toJSON() {
+        return {
+            id: this._id,
+            owner_id: this._owner_id,
+            name: this._name,
+            api_key: this._api_key,
+            timestamp: this._timestamp.toISOString(),
+            restricted: this._restricted,
+            valid_until: this._valid_until ? this._valid_until.toISOString() : null,
+            settings: structuredClone(this._settings),
+        };
+    }
+    // ─────────────────────────────────────────────
+    //  Validation
+    // ─────────────────────────────────────────────
+    /**
+     * Assert the integrity of all fields on this instance.
+     * Throws a descriptive error for the first field that fails.
+     */
+    validate() {
+        assertString(this._id, "id");
+        assertString(this._owner_id, "owner_id");
+        assertString(this._name, "name");
+        assertString(this._api_key, "api_key");
+        if (!/^[a-f0-9]{64}$/.test(this._api_key)) {
+            throw new Error("[MajikAPI] validate(): 'api_key' does not appear to be a valid SHA-256 hash.");
+        }
+        if (!(this._timestamp instanceof Date) ||
+            isNaN(this._timestamp.getTime())) {
+            throw new TypeError("[MajikAPI] validate(): 'timestamp' is not a valid Date.");
+        }
+        assertBoolean(this._restricted, "restricted");
+        if (this._valid_until !== null) {
+            if (!(this._valid_until instanceof Date) ||
+                isNaN(this._valid_until.getTime())) {
+                throw new TypeError("[MajikAPI] validate(): 'valid_until' is not a valid Date.");
+            }
+        }
+        MajikAPI.validateSettings(this._settings);
+    }
+    // ─────────────────────────────────────────────
+    //  Key Verification
+    // ─────────────────────────────────────────────
+    /**
+     * Hash `text` and compare against the stored api_key hash.
+     * This is the correct way to verify an incoming key at your API gateway.
+     * Returns true if the key matches.
+     */
+    verify(text) {
+        if (typeof text !== "string" || text.trim() === "") {
+            throw new TypeError("[MajikAPI] verify(): Input must be a non-empty string.");
+        }
+        return sha256(text.trim()) === this._api_key;
+    }
+    /** Alias for verify(). */
+    matches(text) {
+        return this.verify(text);
+    }
+    // ─────────────────────────────────────────────
+    //  Status Checks
+    // ─────────────────────────────────────────────
+    /** Returns true if valid_until is set and has passed. Always false if null. */
+    isExpired() {
+        if (this._valid_until === null)
+            return false;
+        return new Date() > this._valid_until;
+    }
+    /** Returns true only if the key is not expired and not restricted. */
+    isActive() {
+        return !this.isExpired() && !this._restricted;
+    }
+    // ─────────────────────────────────────────────
+    //  Rate Limit
+    // ─────────────────────────────────────────────
+    /**
+     * Set the rate limit for this key.
+     *
+     * The effective rate (normalised to req/min) cannot exceed MAX_RATE_LIMIT
+     * (500 req/min). Attempting to set a higher rate will throw unless
+     * bypassSafeLimit is explicitly passed as true.
+     *
+     * @param amount        - Number of allowed requests per frequency window.
+     * @param frequency     - The time window unit.
+     * @param bypassSafeLimit - When true, skips the MAX_RATE_LIMIT ceiling check.
+     *                        Defaults to false. Use with caution.
+     */
+    setRateLimit(amount, frequency, bypassSafeLimit = false) {
+        assertPositiveInteger(amount, "amount");
+        assertRateLimitFrequency(frequency, "frequency");
+        assertBoolean(bypassSafeLimit, "bypassSafeLimit");
+        if (!bypassSafeLimit) {
+            const incomingRpm = amount * TO_MINUTES[frequency];
+            const ceilingRpm = MAX_RATE_LIMIT.amount * TO_MINUTES[MAX_RATE_LIMIT.frequency];
+            if (incomingRpm > ceilingRpm) {
+                throw new RangeError(`[MajikAPI] setRateLimit(): The requested rate (${amount} per ${frequency} ` +
+                    `\u2248 ${incomingRpm.toFixed(4)} req/min) exceeds the system ceiling of ` +
+                    `${ceilingRpm.toFixed(4)} req/min (${MAX_RATE_LIMIT.amount} per ` +
+                    `${MAX_RATE_LIMIT.frequency}). ` +
+                    `Pass bypassSafeLimit = true to override this guard.`);
+            }
+        }
+        this._settings.rateLimit = { amount, frequency };
+    }
+    /** Reset the rate limit back to DEFAULT_RATE_LIMIT. */
+    resetRateLimit() {
+        this._settings.rateLimit = { ...DEFAULT_RATE_LIMIT };
+    }
+    // ─────────────────────────────────────────────
+    //  Key Rotation
+    // ─────────────────────────────────────────────
+    /**
+     * Rotate the API key. Generates a new raw key (or accepts a provided one),
+     * hashes it, and replaces _api_key. The stable _id and _owner_id are
+     * untouched, so all FK references in audit/event tables remain valid.
+     *
+     * After rotation, `rawApiKey` holds the new plaintext key. This is the only
+     * moment it is accessible. The old key is immediately invalidated in-memory.
+     *
+     * IMPORTANT: After calling rotate(), you must:
+     *   1. Save the new toJSON() to Supabase (updates the api_key column).
+     *   2. Delete the old Redis cache entry (old hash key is now stale).
+     *   3. Show the caller rawApiKey before discarding this instance.
+     *
+     * @param text - Optional new raw key. If omitted, a UUIDv4 is generated.
+     */
+    rotate(text) {
+        let rawKey;
+        if (text !== undefined) {
+            if (typeof text !== "string" || text.trim() === "") {
+                throw new TypeError("[MajikAPI] rotate(): 'text' must be a non-empty string if provided.");
+            }
+            rawKey = text.trim();
+        }
+        else {
+            rawKey = generateID();
+        }
+        this._api_key = sha256(rawKey);
+        this._raw_api_key = rawKey;
+    }
+    // ─────────────────────────────────────────────
+    //  Mutation Methods
+    // ─────────────────────────────────────────────
+    /** Rename this key. */
+    rename(name) {
+        assertString(name, "name");
+        this._name = name.trim();
+    }
+    /**
+     * Set or clear the expiry date.
+     * Pass null to make the key never expire.
+     */
+    setExpiry(date) {
+        if (date === null) {
+            this._valid_until = null;
+            return;
+        }
+        const parsed = MajikAPI.parseDate(date, "date");
+        if (parsed <= new Date()) {
+            throw new RangeError("[MajikAPI] setExpiry(): Expiry date must be in the future.");
+        }
+        this._valid_until = parsed;
+    }
+    /** Disable this key without deleting it. */
+    restrict() {
+        this._restricted = true;
+    }
+    /** Re-enable a previously restricted key. */
+    unrestrict() {
+        this._restricted = false;
+    }
+    /**
+     * Permanently revoke this key. Sets valid_until to epoch (always expired)
+     * and marks it restricted. Both flags must be cleared to undo this — prefer
+     * deleting the Supabase row and creating a new key instead.
+     */
+    revoke() {
+        this._valid_until = new Date(0);
+        this._restricted = true;
+    }
+    // ─────────────────────────────────────────────
+    //  IP Whitelist
+    // ─────────────────────────────────────────────
+    enableIPWhitelist() {
+        this._settings.ipWhitelist.enabled = true;
+    }
+    disableIPWhitelist() {
+        this._settings.ipWhitelist.enabled = false;
+    }
+    addIP(ip) {
+        assertString(ip, "ip");
+        validateIP(ip.trim());
+        const trimmed = ip.trim();
+        if (!this._settings.ipWhitelist.addresses.includes(trimmed)) {
+            this._settings.ipWhitelist.addresses.push(trimmed);
+        }
+    }
+    removeIP(ip) {
+        assertString(ip, "ip");
+        this._settings.ipWhitelist.addresses =
+            this._settings.ipWhitelist.addresses.filter((a) => a !== ip.trim());
+    }
+    setIPWhitelist(addresses) {
+        assertStringArray(addresses, "addresses");
+        addresses.forEach((ip) => validateIP(ip.trim()));
+        this._settings.ipWhitelist.addresses = addresses.map((ip) => ip.trim());
+    }
+    clearIPWhitelist() {
+        this._settings.ipWhitelist.addresses = [];
+    }
+    // ─────────────────────────────────────────────
+    //  Domain Whitelist
+    // ─────────────────────────────────────────────
+    enableDomainWhitelist() {
+        this._settings.domainWhitelist.enabled = true;
+    }
+    disableDomainWhitelist() {
+        this._settings.domainWhitelist.enabled = false;
+    }
+    addDomain(domain) {
+        assertString(domain, "domain");
+        validateDomain(domain.trim());
+        const trimmed = domain.trim();
+        if (!this._settings.domainWhitelist.domains.includes(trimmed)) {
+            this._settings.domainWhitelist.domains.push(trimmed);
+        }
+    }
+    removeDomain(domain) {
+        assertString(domain, "domain");
+        this._settings.domainWhitelist.domains =
+            this._settings.domainWhitelist.domains.filter((d) => d !== domain.trim());
+    }
+    setDomainWhitelist(domains) {
+        assertStringArray(domains, "domains");
+        domains.forEach((d) => validateDomain(d.trim()));
+        this._settings.domainWhitelist.domains = domains.map((d) => d.trim());
+    }
+    clearDomainWhitelist() {
+        this._settings.domainWhitelist.domains = [];
+    }
+    // ─────────────────────────────────────────────
+    //  Allowed Methods
+    // ─────────────────────────────────────────────
+    setAllowedMethods(methods) {
+        assertStringArray(methods, "methods");
+        const valid = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+        for (const m of methods) {
+            if (!valid.includes(m.toUpperCase())) {
+                throw new Error(`[MajikAPI] setAllowedMethods(): Unknown HTTP method "${m}". Valid: ${valid.join(", ")}`);
+            }
+        }
+        this._settings.allowedMethods = methods.map((m) => m.toUpperCase());
+    }
+    clearAllowedMethods() {
+        this._settings.allowedMethods = [];
+    }
+    // ─────────────────────────────────────────────
+    //  Metadata
+    // ─────────────────────────────────────────────
+    setMetadata(key, value) {
+        assertString(key, "metadata key");
+        this._settings.metadata = this._settings.metadata ?? {};
+        this._settings.metadata[key] = value;
+    }
+    getMetadata(key) {
+        assertString(key, "metadata key");
+        return this._settings.metadata?.[key];
+    }
+    deleteMetadata(key) {
+        assertString(key, "metadata key");
+        if (this._settings.metadata) {
+            delete this._settings.metadata[key];
+        }
+    }
+    clearMetadata() {
+        this._settings.metadata = {};
+    }
+    // ─────────────────────────────────────────────
+    //  Getters
+    // ─────────────────────────────────────────────
+    /** The key's own stable UUID. Primary key in Supabase. */
+    get id() {
+        return this._id;
+    }
+    /** UUID of the user who owns this key. FK to auth.users. */
+    get ownerId() {
+        return this._owner_id;
+    }
+    get name() {
+        return this._name;
+    }
+    /**
+     * The SHA-256 hash of the raw key. This is what is stored in Supabase and
+     * used as the Redis cache key prefix. Never the plaintext.
+     */
+    get apiKey() {
+        return this._api_key;
+    }
+    /**
+     * The raw plaintext key. Only defined immediately after create() or rotate().
+     * Undefined after fromJSON() or any serialise/deserialise round-trip.
+     * Treat this like a password — show it once and discard.
+     */
+    get rawApiKey() {
+        return this._raw_api_key;
+    }
+    get createdAt() {
+        return new Date(this._timestamp);
+    }
+    get timestamp() {
+        return this._timestamp.toISOString();
+    }
+    get restricted() {
+        return this._restricted;
+    }
+    get validUntil() {
+        return this._valid_until ? new Date(this._valid_until) : null;
+    }
+    /** Returns a deep clone — mutations to the returned object have no effect. */
+    get settings() {
+        return structuredClone(this._settings);
+    }
+    get rateLimit() {
+        return { ...this._settings.rateLimit };
+    }
+    get ipWhitelist() {
+        return structuredClone(this._settings.ipWhitelist);
+    }
+    get domainWhitelist() {
+        return structuredClone(this._settings.domainWhitelist);
+    }
+    get allowedMethods() {
+        return [...(this._settings.allowedMethods ?? [])];
+    }
+    /**
+     * Milliseconds until this key expires.
+     * Returns -1 if the key never expires (valid_until is null).
+     * Returns 0 if the key has already expired.
+     */
+    get msUntilExpiry() {
+        if (this._valid_until === null)
+            return -1;
+        return Math.max(0, this._valid_until.getTime() - Date.now());
+    }
+    /**
+     * Human-readable lifecycle status.
+     *
+     * "active"     — valid, not restricted, not expired.
+     * "restricted" — manually disabled, not expired.
+     * "expired"    — past valid_until date.
+     * "revoked"    — permanently invalidated via revoke().
+     */
+    get status() {
+        if (this._valid_until?.getTime() === new Date(0).getTime())
+            return "revoked";
+        if (this.isExpired())
+            return "expired";
+        if (this._restricted)
+            return "restricted";
+        return "active";
+    }
+    // ─────────────────────────────────────────────
+    //  Private Static Utilities
+    // ─────────────────────────────────────────────
+    static parseDate(value, label) {
+        if (value instanceof Date) {
+            if (isNaN(value.getTime())) {
+                throw new TypeError(`[MajikAPI] "${label}" is an invalid Date object.`);
+            }
+            return value;
+        }
+        if (typeof value === "string") {
+            if (!isValidISODate(value)) {
+                throw new TypeError(`[MajikAPI] "${label}" is not a valid ISO date string: "${value}"`);
+            }
+            return new Date(value);
+        }
+        throw new TypeError(`[MajikAPI] "${label}" must be a Date instance or an ISO date string.`);
+    }
+    static validateSettings(settings) {
+        if (typeof settings !== "object" || settings === null) {
+            throw new TypeError("[MajikAPI] 'settings' must be an object.");
+        }
+        assertPositiveInteger(settings.rateLimit?.amount, "settings.rateLimit.amount");
+        assertRateLimitFrequency(settings.rateLimit?.frequency, "settings.rateLimit.frequency");
+        assertBoolean(settings.ipWhitelist?.enabled, "settings.ipWhitelist.enabled");
+        assertStringArray(settings.ipWhitelist?.addresses, "settings.ipWhitelist.addresses");
+        settings.ipWhitelist.addresses.forEach((ip) => validateIP(ip));
+        assertBoolean(settings.domainWhitelist?.enabled, "settings.domainWhitelist.enabled");
+        assertStringArray(settings.domainWhitelist?.domains, "settings.domainWhitelist.domains");
+        settings.domainWhitelist.domains.forEach((d) => validateDomain(d));
+    }
+    // ─────────────────────────────────────────────
+    //  Debug
+    // ─────────────────────────────────────────────
+    toString() {
+        return `[MajikAPI id="${this._id}" owner="${this._owner_id}" name="${this._name}" status="${this.status}"]`;
+    }
+    [Symbol.for("nodejs.util.inspect.custom")]() {
+        return this.toString();
+    }
+}
+export default MajikAPI;

package/dist/types.d.ts

@@ -0,0 +1,46 @@
+export type RateLimitFrequency = "seconds" | "minutes" | "hours";
+export interface RateLimit {
+    amount: number;
+    frequency: RateLimitFrequency;
+}
+export interface IPWhitelist {
+    enabled: boolean;
+    addresses: string[];
+}
+export interface DomainWhitelist {
+    enabled: boolean;
+    domains: string[];
+}
+export interface MajikAPISettings {
+    rateLimit: RateLimit;
+    ipWhitelist: IPWhitelist;
+    domainWhitelist: DomainWhitelist;
+    allowedMethods?: string[];
+    metadata?: Record<string, unknown>;
+}
+/**
+ * The serialised shape stored in Supabase and cached in Redis.
+ *
+ * id       — stable UUID primary key in Supabase. Never changes, even on
+ *            key rotation. Safe to use as a FK in audit/event tables.
+ * owner_id — FK to auth.users. Identifies who owns this key.
+ * api_key  — SHA-256 hash of the raw plaintext key. Has a UNIQUE INDEX in
+ *            Postgres (not the PK). Used as the Redis cache key prefix.
+ *            The raw key is never stored anywhere.
+ */
+export interface MajikAPIJSON {
+    id: string;
+    owner_id: string;
+    name: string;
+    api_key: string;
+    timestamp: string;
+    restricted: boolean;
+    valid_until: string | null;
+    settings: MajikAPISettings;
+}
+export interface MajikAPICreateOptions {
+    name?: string;
+    restricted?: boolean;
+    valid_until?: Date | string | null;
+    settings?: Partial<MajikAPISettings>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,6 @@
+export declare function sha256(input: string): string;
+export declare function arrayToBase64(data: Uint8Array): string;
+/**
+ * Generate a Random v4 UUID
+ */
+export declare function generateID(): string;

package/dist/utils.js

@@ -0,0 +1,27 @@
+import { hash } from "@stablelib/sha256";
+import { v4 as uuidv4 } from "uuid";
+export function sha256(input) {
+    const hashed = hash(new TextEncoder().encode(input));
+    return arrayToBase64(hashed);
+}
+export function arrayToBase64(data) {
+    let binary = "";
+    const bytes = data;
+    const len = bytes.byteLength;
+    for (let i = 0; i < len; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+/**
+ * Generate a Random v4 UUID
+ */
+export function generateID() {
+    try {
+        const genID = uuidv4();
+        return genID;
+    }
+    catch (error) {
+        throw new Error(`Failed to generate ID: ${error}`);
+    }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@majikah/majik-api",
+  "type": "module",
+  "description": "A high-security API key management library for TypeScript. Handles generation, SHA-256 hashing, and lifecycle management including rate limiting, IP/domain whitelisting, and secure key rotation.",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "author": "Zelijah",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Majikah/majik-api.git"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/jedlsf"
+  },
+  "keywords": [
+    "api-key",
+    "api-management",
+    "security",
+    "sha256",
+    "rate-limiting",
+    "whitelisting",
+    "key-rotation",
+    "ip-filtering",
+    "domain-validation",
+    "typescript",
+    "supabase",
+    "redis",
+    "majikah"
+  ],
+  "homepage": "https://github.com/Majikah/majik-api#readme",
+  "bugs": {
+    "url": "https://github.com/Majikah/majik-api/issues"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@stablelib/sha256": "^2.0.1",
+    "uuid": "^13.0.0"
+  }
+}