@majikah/majik-bip-39 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 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:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) 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
+
+      (d) 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
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Majikah Solutions OPC
+
+   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.

package/README.md

@@ -1,4 +1,1016 @@
-# Temporary Holding Version
+# Majik BIP-39
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
-If no other versions are published within 30 days, this package and version will be deleted.
+[![Developed by Zelijah](https://img.shields.io/badge/Developed%20by-Zelijah-red?logo=github&logoColor=white)](https://www.thezelijah.world) ![GitHub Sponsors](https://img.shields.io/github/sponsors/jedlsf?style=plastic&label=Sponsors&link=https%3A%2F%2Fgithub.com%2Fsponsors%2Fjedlsf)
+
+Deterministically derive a **standard BIP-39 mnemonic** from supported binary inputs such as images.
+
+`@majikah/majik-bip-39` converts an input into a **versioned canonical representation**, derives exactly **256 bits of entropy**, and encodes that entropy using the standard BIP-39 wordlists.
+
+The library does **not redefine BIP-39**. It only provides a deterministic way to produce BIP-39-compatible entropy from structured input.
+
+> **Current support:** PNG images
+> **Planned:** additional media handlers such as WAV/audio and video
+>
+
+![npm](https://img.shields.io/npm/v/@majikah/majik-bip-39) ![npm downloads](https://img.shields.io/npm/dm/@majikah/majik-bip-39) ![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+---
+
+## Table of Contents
+
+- [Majik BIP-39](#majik-bip-39)
+  - [Table of Contents](#table-of-contents)
+  - [Features](#features)
+  - [Installation](#installation)
+  - [Quick Start](#quick-start)
+    - [Derive from bytes](#derive-from-bytes)
+    - [Derive from a browser `File`](#derive-from-a-browser-file)
+  - [How It Works](#how-it-works)
+    - [Passphrase mode](#passphrase-mode)
+  - [Determinism](#determinism)
+    - [Language does not change the entropy](#language-does-not-change-the-entropy)
+- [Image Derivation](#image-derivation)
+  - [PNG Canonicalization](#png-canonicalization)
+    - [Supported image data](#supported-image-data)
+    - [Currently rejected](#currently-rejected)
+- [Resource Limits](#resource-limits)
+- [Passphrase Mode](#passphrase-mode-1)
+    - [Important](#important)
+- [BIP-39 Helpers](#bip-39-helpers)
+  - [Entropy → mnemonic](#entropy--mnemonic)
+  - [Mnemonic → entropy](#mnemonic--entropy)
+  - [Validate a mnemonic](#validate-a-mnemonic)
+- [Supported BIP-39 Languages](#supported-bip-39-languages)
+- [API](#api)
+  - [`MajikBip39.fromBytes()`](#majikbip39frombytes)
+  - [`MajikBip39.fromFile()`](#majikbip39fromfile)
+  - [`MajikBip39.derive()`](#majikbip39derive)
+  - [`MajikBip39.deriveMnemonic()`](#majikbip39derivemnemonic)
+  - [`MajikBip39.deriveEntropy()`](#majikbip39deriveentropy)
+  - [`MajikBip39.toMnemonic()`](#majikbip39tomnemonic)
+  - [`MajikBip39.toEntropy()`](#majikbip39toentropy)
+  - [`MajikBip39.validateMnemonic()`](#majikbip39validatemnemonic)
+  - [`MajikBip39.listHandlers()`](#majikbip39listhandlers)
+  - [`MajikBip39.listSchemes()`](#majikbip39listschemes)
+- [Scheme Resolution](#scheme-resolution)
+- [Errors](#errors)
+- [Versioned Derivation](#versioned-derivation)
+- [Reproducibility](#reproducibility)
+- [Security Considerations](#security-considerations)
+  - [This is deterministic derivation, not random generation](#this-is-deterministic-derivation-not-random-generation)
+  - [Do not expose the mnemonic](#do-not-expose-the-mnemonic)
+  - [Passphrase security](#passphrase-security)
+  - [Input entropy is not automatically wallet entropy](#input-entropy-is-not-automatically-wallet-entropy)
+- [Privacy](#privacy)
+- [Design Philosophy](#design-philosophy)
+- [Current Status](#current-status)
+    - [Implemented](#implemented)
+    - [Planned](#planned)
+- [Example: Complete Deterministic Flow](#example-complete-deterministic-flow)
+- [Compatibility with BIP-39](#compatibility-with-bip-39)
+- [Important Limitations](#important-limitations)
+  - [License](#license)
+  - [Author](#author)
+  - [Contact](#contact)
+
+
+---
+
+## Features
+
+* Deterministic input → BIP-39 derivation
+* Versioned, handler-specific canonicalization
+* Metadata-independent PNG canonicalization
+* Standard BIP-39 entropy and mnemonic encoding
+* Optional Argon2id passphrase derivation
+* Multiple BIP-39 languages
+* Browser `Blob` / `File` support
+* Node.js `Uint8Array` support
+* Explicit resource limits for untrusted input
+* Extensible handler architecture for future media types
+* Strict scheme resolution; no silent format guessing when ambiguous
+* Standard BIP-39 import/export helpers
+
+---
+
+## Installation
+
+```sh
+npm install @majikah/majik-bip-39
+```
+
+---
+
+## Quick Start
+
+### Derive from bytes
+
+```js
+import { readFile } from "node:fs/promises";
+import { MajikBip39 } from "@majikah/majik-bip-39";
+
+const image = new Uint8Array(
+  await readFile("./image.png")
+);
+
+const mnemonic = await MajikBip39.fromBytes(image, {
+  mediaType: "image/png",
+});
+
+console.log(mnemonic);
+```
+
+The resulting mnemonic is a normal **24-word BIP-39 mnemonic**.
+
+---
+
+### Derive from a browser `File`
+
+`fromFile()` accepts any `Blob` or `File` that provides `arrayBuffer()`.
+
+```js
+const mnemonic = await MajikBip39.fromFile(file);
+
+console.log(mnemonic);
+```
+
+You may also provide derivation options:
+
+```js
+const mnemonic = await MajikBip39.fromFile(file, {
+  mediaType: "image/png",
+  mnemonicLanguage: "en",
+});
+```
+
+---
+
+## How It Works
+
+Majik BIP-39 uses a two-stage model:
+
+```mermaid
+flowchart TD
+    A[Input] --> B[Handler]
+
+    B --> C[Detect / validate input]
+    B --> D[Canonicalize content]
+    B --> E[Produce canonical chunks]
+
+    C --> F[Versioned domain]
+    D --> F
+    E --> F
+
+    F --> G[SHA-256]
+    G --> H[256-bit entropy]
+    H --> I[BIP-39]
+    I --> J[24-word mnemonic]
+```
+
+For an input without a passphrase, the core derivation is conceptually:
+
+```text
+digest =
+  SHA-256(
+    UTF-8(canonical-domain) ||
+    canonical-chunk-1 ||
+    canonical-chunk-2 ||
+    ...
+  )
+```
+
+The resulting 32-byte digest is used directly as BIP-39 entropy.
+
+### Passphrase mode
+
+When a passphrase is supplied, Majik BIP-39 derives the final entropy using Argon2id.
+
+Conceptually:
+
+```text
+digest =
+  SHA-256(
+    UTF-8(canonical-domain) ||
+    canonical-content
+  )
+
+salt =
+  SHA-256(
+    UTF-8(canonical-domain + "/salt") ||
+    digest
+  )
+
+entropy =
+  Argon2id(
+    passphrase,
+    salt,
+    versioned parameters
+  )
+```
+
+The final result is still ordinary **32-byte BIP-39 entropy**.
+
+This means the output remains compatible with software that understands standard BIP-39.
+
+---
+
+## Determinism
+
+For a fixed scheme, canonical representation, passphrase, and BIP-39 wordlist, the same input produces the same mnemonic.
+
+For example:
+
+```text
+same image
+    +
+same scheme
+    +
+same passphrase
+    +
+same canonicalization version
+    =
+same entropy
+    =
+same mnemonic
+```
+
+Without a passphrase, the result depends only on the canonicalized content.
+
+With a passphrase, the passphrase becomes part of the derivation.
+
+### Language does not change the entropy
+
+Changing the BIP-39 language changes the **words used to represent the entropy**, not the underlying entropy itself.
+
+For example, these are different textual representations of the same 256-bit value:
+
+```js
+const entropy = await MajikBip39.deriveEntropy(image, {
+  mediaType: "image/png",
+});
+
+const english = await MajikBip39.toMnemonic(entropy, "en");
+const japanese = await MajikBip39.toMnemonic(entropy, "ja");
+```
+
+The entropy is identical; only the BIP-39 wordlist changes.
+
+---
+
+# Image Derivation
+
+The currently implemented handler is the PNG image handler.
+
+The default scheme is:
+
+```text
+image-v1
+```
+
+You can explicitly request it:
+
+```js
+const mnemonic = await MajikBip39.fromBytes(image, {
+  mediaType: "image/png",
+  scheme: "image-v1",
+});
+```
+
+Or inspect the complete derivation result:
+
+```js
+const result = await MajikBip39.derive(image, {
+  mediaType: "image/png",
+  scheme: "image-v1",
+});
+
+console.log(result.mnemonic);
+console.log(result.entropy);
+console.log(result.scheme);
+console.log(result.handler);
+console.log(result.passphraseUsed);
+console.log(result.canonicalization);
+```
+
+A result has the following shape:
+
+```ts
+interface Bip39DerivationResult {
+  mnemonic: string;
+  entropy: Uint8Array;
+  scheme: Scheme;
+  handler: HandlerId;
+  passphraseUsed: boolean;
+  canonicalization: unknown;
+}
+```
+
+The exact `canonicalization` metadata is handler-specific.
+
+---
+
+## PNG Canonicalization
+
+`image-v1` does not hash the raw PNG file bytes directly.
+
+Instead, the image handler decodes the PNG and constructs a canonical representation of its pixel data.
+
+This is important because a PNG file can contain metadata or encoding differences while representing the same underlying image.
+
+Consequently, image metadata and other non-canonical PNG information do not affect the derived mnemonic.
+
+Conceptually:
+
+```text
+PNG file
+   │
+   ├─ metadata
+   ├─ ancillary chunks
+   ├─ encoding details
+   └─ pixel data
+          │
+          ▼
+   canonical pixels
+          │
+          ▼
+      image-v1
+          │
+          ▼
+       SHA-256
+```
+
+Two PNG files that canonicalize to the same representation produce the same result.
+
+### Supported image data
+
+`image-v1` currently supports static, non-indexed PNG images using:
+
+* 8-bit grayscale
+* 16-bit grayscale
+* 8-bit grayscale + alpha
+* 16-bit grayscale + alpha
+* 8-bit RGB
+* 16-bit RGB
+* 8-bit RGBA
+* 16-bit RGBA
+
+### Currently rejected
+
+The current handler rejects:
+
+* animated PNGs
+* indexed / palette-based PNGs
+* `tRNS` transparency
+* bit depths below 8 bits
+
+Other image formats may be recognized at the input-detection layer, but their decoders are not yet implemented.
+
+In particular, JPEG, BMP, WebP, and TIFF decoding are currently unavailable.
+
+---
+
+# Resource Limits
+
+Image processing operates on untrusted binary input, so the library applies explicit resource limits.
+
+The default limits are:
+
+| Limit                |    Default |
+| -------------------- | ---------: |
+| Maximum file size    |     64 MiB |
+| Maximum width        |  16,384 px |
+| Maximum height       |  16,384 px |
+| Maximum total pixels | 64,000,000 |
+
+These limits can be overridden:
+
+```js
+const mnemonic = await MajikBip39.fromBytes(image, {
+  mediaType: "image/png",
+  limits: {
+    maxFileBytes: 32 * 1024 * 1024,
+    maxWidth: 8192,
+    maxHeight: 8192,
+    maxPixels: 32_000_000,
+  },
+});
+```
+
+Use lower limits when processing untrusted files in memory-constrained environments.
+
+Limits must be positive integers.
+
+---
+
+# Passphrase Mode
+
+An optional passphrase adds a password-based derivation step using **Argon2id**.
+
+```js
+const mnemonic = await MajikBip39.fromBytes(image, {
+  mediaType: "image/png",
+  passphrase: "your private passphrase",
+});
+```
+
+A different passphrase produces a different entropy value and therefore a different mnemonic.
+
+The passphrase is normalized before derivation.
+
+```text
+same image + different passphrase
+        │
+        ▼
+    different entropy
+        │
+        ▼
+    different mnemonic
+```
+
+### Important
+
+A passphrase is not automatically a secure password.
+
+A weak, predictable, reused, or exposed passphrase remains weak.
+
+Do not treat passphrase mode as protection against a low-entropy or publicly known input.
+
+---
+
+# BIP-39 Helpers
+
+Majik BIP-39 also exposes standard BIP-39 conversion and validation helpers.
+
+These functions are independent of image derivation.
+
+## Entropy → mnemonic
+
+```js
+const mnemonic = await MajikBip39.toMnemonic(
+  entropy,
+  "en",
+);
+```
+
+The standard BIP-39 entropy sizes are supported:
+
+```text
+16 bytes  → 12 words
+20 bytes  → 15 words
+24 bytes  → 18 words
+28 bytes  → 21 words
+32 bytes  → 24 words
+```
+
+Invalid entropy lengths are rejected.
+
+---
+
+## Mnemonic → entropy
+
+```js
+const entropy = await MajikBip39.toEntropy(
+  mnemonic,
+  "en",
+);
+```
+
+The mnemonic is validated against the selected BIP-39 wordlist before entropy is returned.
+
+---
+
+## Validate a mnemonic
+
+```js
+const result = await MajikBip39.validateMnemonic(
+  mnemonic,
+  "en",
+);
+
+console.log(result.valid);
+console.log(result.wordCount);
+```
+
+Example result:
+
+```js
+{
+  valid: true,
+  wordCount: 24
+}
+```
+
+An invalid mnemonic returns `valid: false`.
+
+An unsupported language is rejected.
+
+---
+
+# Supported BIP-39 Languages
+
+The following standard wordlists are currently supported:
+
+| Language            | Code    |
+| ------------------- | ------- |
+| English             | `en`    |
+| French              | `fr`    |
+| Spanish             | `es`    |
+| Italian             | `it`    |
+| Japanese            | `ja`    |
+| Korean              | `ko`    |
+| Czech               | `czech` |
+| Portuguese          | `pt`    |
+| Simplified Chinese  | `zh-cn` |
+| Traditional Chinese | `zh-tw` |
+
+Example:
+
+```js
+const mnemonic = await MajikBip39.fromBytes(image, {
+  mediaType: "image/png",
+  mnemonicLanguage: "ja",
+});
+```
+
+---
+
+# API
+
+## `MajikBip39.fromBytes()`
+
+Derive a mnemonic from raw bytes.
+
+```ts
+static async fromBytes(
+  bytes: Uint8Array,
+  options?: DeriveOptions,
+): Promise<string>
+```
+
+This is the simplest entry point for Node.js and other byte-oriented environments.
+
+---
+
+## `MajikBip39.fromFile()`
+
+Derive a mnemonic from a browser `File` or `Blob`.
+
+```ts
+static async fromFile(
+  file: Blob,
+  options?: DeriveOptions,
+): Promise<string>
+```
+
+The file contents are read into a `Uint8Array` before processing.
+
+The file's MIME type is used as `mediaType` when available.
+
+An explicitly supplied `mediaType` in `options` takes precedence over the automatic file MIME type.
+
+---
+
+## `MajikBip39.derive()`
+
+Return the complete derivation result.
+
+```ts
+static async derive(
+  bytes: Uint8Array,
+  options?: DeriveOptions,
+): Promise<Bip39DerivationResult>
+```
+
+Use this when an application needs the entropy, scheme, handler, or canonicalization information in addition to the mnemonic.
+
+---
+
+## `MajikBip39.deriveMnemonic()`
+
+Alias for mnemonic derivation:
+
+```ts
+static async deriveMnemonic(
+  bytes: Uint8Array,
+  options?: DeriveOptions,
+): Promise<string>
+```
+
+---
+
+## `MajikBip39.deriveEntropy()`
+
+Derive only the final BIP-39 entropy.
+
+```ts
+static async deriveEntropy(
+  bytes: Uint8Array,
+  options?: DeriveOptions,
+): Promise<Uint8Array>
+```
+
+The current image derivation produces 32 bytes / 256 bits of entropy.
+
+---
+
+## `MajikBip39.toMnemonic()`
+
+Convert valid BIP-39 entropy to a mnemonic.
+
+```ts
+static async toMnemonic(
+  entropy: Uint8Array,
+  language?: MnemonicLanguage,
+): Promise<string>
+```
+
+---
+
+## `MajikBip39.toEntropy()`
+
+Convert and validate a BIP-39 mnemonic.
+
+```ts
+static async toEntropy(
+  mnemonic: string,
+  language?: MnemonicLanguage,
+): Promise<Uint8Array>
+```
+
+---
+
+## `MajikBip39.validateMnemonic()`
+
+Validate a mnemonic against the selected wordlist.
+
+```ts
+static async validateMnemonic(
+  mnemonic: string,
+  language?: MnemonicLanguage,
+): Promise<MnemonicValidation>
+```
+
+---
+
+## `MajikBip39.listHandlers()`
+
+List registered input handlers.
+
+```js
+const handlers = MajikBip39.listHandlers();
+
+console.log(handlers);
+```
+
+This is useful for feature discovery in applications.
+
+---
+
+## `MajikBip39.listSchemes()`
+
+List schemes currently exposed by the registered handlers.
+
+```js
+const schemes = MajikBip39.listSchemes();
+
+console.log(schemes);
+```
+
+As additional handlers are added, this registry becomes the discovery mechanism for supported derivation schemes.
+
+---
+
+# Scheme Resolution
+
+Majik BIP-39 intentionally does not silently guess between multiple possible derivation schemes.
+
+Resolution follows this order:
+
+```text
+1. Explicit scheme
+      ↓
+2. Declared media type
+      ↓
+3. Content detection
+```
+
+For example:
+
+```js
+const result = await MajikBip39.derive(image, {
+  mediaType: "image/png",
+  scheme: "image-v1",
+});
+```
+
+When no scheme is explicitly specified, the library attempts to determine the appropriate handler.
+
+If no handler recognizes the input, derivation fails.
+
+If multiple handlers recognize the input and no scheme was specified, derivation fails with an ambiguity error rather than selecting one arbitrarily.
+
+This makes derivation behavior explicit and reproducible.
+
+---
+
+# Errors
+
+The library exposes specific error types for common failure conditions, including:
+
+* `HandlerNotFoundError`
+* `InvalidEntropyLengthError`
+* `InvalidInputError`
+* `InvalidMnemonicError`
+* `InvalidOptionError`
+* `UnsupportedSchemeError`
+
+Example:
+
+```js
+import {
+  HandlerNotFoundError,
+  UnsupportedSchemeError,
+} from "@majikah/majik-bip-39";
+
+try {
+  const mnemonic = await MajikBip39.fromBytes(input);
+} catch (error) {
+  if (error instanceof HandlerNotFoundError) {
+    console.error("Unsupported input");
+  } else if (error instanceof UnsupportedSchemeError) {
+    console.error("Unsupported derivation scheme");
+  } else {
+    throw error;
+  }
+}
+```
+
+---
+
+# Versioned Derivation
+
+Derivation schemes are explicitly versioned.
+
+For example:
+
+```text
+image-v1
+```
+
+should be treated as a stable algorithm identifier rather than merely an implementation label.
+
+Applications that need long-term reproducibility should persist the scheme alongside any other recovery information.
+
+A future `image-v2` may use different canonicalization or derivation rules without changing the meaning of `image-v1`.
+
+This separation allows the library to evolve without silently changing existing derivation results.
+
+---
+
+# Reproducibility
+
+For deterministic recovery, preserve enough information to reproduce the original derivation:
+
+```text
+Input
+Scheme
+Passphrase
+Canonicalization version
+```
+
+The mnemonic language only affects the textual BIP-39 representation; the underlying entropy remains the same.
+
+For long-term interoperability, storing the explicit scheme is recommended instead of relying on the current default.
+
+---
+
+# Security Considerations
+
+## This is deterministic derivation, not random generation
+
+A mnemonic derived from an image inherits its unpredictability from the image and any passphrase used.
+
+A predictable or publicly available image can produce a predictable mnemonic.
+
+For example, using a famous photograph, stock image, logo, or otherwise publicly known file should not be assumed to provide secret entropy.
+
+```text
+public / guessable input
+        +
+predictable derivation
+        =
+guessable secret
+```
+
+This is fundamentally different from generating a wallet mnemonic from a cryptographically secure random number generator.
+
+---
+
+## Do not expose the mnemonic
+
+The resulting mnemonic and entropy are sensitive secrets.
+
+Avoid:
+
+* logging them
+* sending them to analytics systems
+* storing them in URLs
+* embedding them in source code
+* putting them in telemetry
+* displaying them unnecessarily
+* publishing the source image when the image itself is intended to be secret
+
+Applications should handle derived entropy and mnemonics with the same care as other wallet secrets.
+
+---
+
+## Passphrase security
+
+Argon2id increases the cost of passphrase guessing, but it cannot compensate for a weak or exposed passphrase.
+
+Use a strong, unique passphrase when passphrase mode is part of the security model.
+
+---
+
+## Input entropy is not automatically wallet entropy
+
+A deterministic image-to-mnemonic system can be useful for reproducibility, portability, experimentation, or specialized recovery workflows.
+
+It should **not automatically be considered a replacement for cryptographically secure random wallet generation**.
+
+Before using image-derived mnemonics for high-value assets, independently evaluate:
+
+* input entropy
+* attacker knowledge of the input
+* passphrase strength
+* recovery procedures
+* canonicalization stability
+* scheme/version persistence
+* operational security
+
+---
+
+# Privacy
+
+Majik BIP-39 performs derivation locally from the supplied bytes.
+
+The library itself does not require a remote service, account, or network-based derivation step.
+
+Applications are still responsible for avoiding accidental disclosure through their own logging, storage, telemetry, synchronization, or UI layers.
+
+---
+
+# Design Philosophy
+
+Majik BIP-39 is intentionally split into two concerns:
+
+```text
+Input-specific processing
+        │
+        ▼
+Canonical representation
+        │
+        ▼
+Deterministic entropy
+        │
+        ▼
+Standard BIP-39
+```
+
+The media handler is responsible for understanding a specific input type.
+
+BIP-39 remains responsible for mnemonic encoding.
+
+This separation makes it possible to add new handlers without creating a new mnemonic standard for every media type.
+
+Future handlers may support inputs such as:
+
+```text
+PNG
+WAV
+MP3
+FLAC
+MP4
+...
+```
+
+while still producing ordinary BIP-39 entropy and mnemonics.
+
+---
+
+# Current Status
+
+### Implemented
+
+* PNG image handler
+* `image-v1`
+* deterministic canonicalization
+* SHA-256 derivation
+* optional Argon2id passphrase mode
+* 256-bit entropy output
+* BIP-39 mnemonic encoding
+* BIP-39 mnemonic validation
+* BIP-39 entropy ↔ mnemonic conversion
+* 10 BIP-39 wordlists
+* browser `Blob` / `File` input
+* byte-oriented input
+* image resource limits
+* handler and scheme registry
+
+### Planned
+
+Additional input handlers are intended to be added without changing the BIP-39 layer.
+
+Examples include:
+
+* WAV / PCM audio
+* other audio formats
+* video
+* additional deterministic media representations
+
+Each handler should define its own canonicalization and versioned scheme while preserving standard BIP-39 compatibility.
+
+---
+
+# Example: Complete Deterministic Flow
+
+```js
+import { readFile } from "node:fs/promises";
+import { MajikBip39 } from "@majikah/majik-bip-39";
+
+const image = new Uint8Array(
+  await readFile("./secret.png")
+);
+
+const result = await MajikBip39.derive(image, {
+  mediaType: "image/png",
+  scheme: "image-v1",
+  passphrase: "correct horse battery staple",
+  mnemonicLanguage: "en",
+});
+
+console.log("Mnemonic:", result.mnemonic);
+console.log("Entropy:", result.entropy);
+console.log("Scheme:", result.scheme);
+console.log("Handler:", result.handler);
+console.log("Passphrase used:", result.passphraseUsed);
+console.log("Canonicalization:", result.canonicalization);
+```
+
+The same canonical input, scheme, passphrase, and derivation parameters will reproduce the same underlying entropy.
+
+---
+
+# Compatibility with BIP-39
+
+The final output is a standard BIP-39 mnemonic.
+
+That means applications can use the resulting mnemonic with existing BIP-39-compatible tooling, subject to the normal requirements of that application.
+
+Majik BIP-39 does **not** introduce a custom mnemonic format.
+
+Its purpose is to answer a different question:
+
+> **How can deterministic input be converted into valid BIP-39 entropy?**
+
+---
+
+# Important Limitations
+
+This library currently should not be interpreted as:
+
+* a general-purpose image hash
+* a cryptographically random number generator
+* a replacement for secure wallet generation
+* a custom BIP-39 implementation
+* a universal media decoder
+
+Only supported handlers and explicitly supported schemes should be relied upon.
+
+The current implementation supports PNG images through `image-v1`; additional image formats and media types are not yet fully implemented.
+
+---
+
+
+## License
+
+**License:** [Apache-2.0](LICENSE) — free for personal and commercial use.
+
+## Author
+
+Developed by **Josef Elijah Fabian (Zelijah)** | [Majikah Solutions OPC](https://majikah.solutions/about)
+
+**Developer**: [Josef Elijah Fabian](https://github.com/jedlsf)
+
+**GitHub**: [https://github.com/Majikah](https://github.com/Majikah)
+
+**Project Repository**: [https://github.com/Majikah/majik-bip-39](https://github.com/Majikah/majik-bip-39)
+
+
+---
+
+## Contact
+
+- **Business Email**: [business@majikah.solutions](mailto:business@majikah.solutions)
+- **Official Website**: [https://www.thezelijah.world](https://www.thezelijah.world)
+- **Majikah Ecosystem**: [https://majikah.solutions](https://majikah.solutions)

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@majikah/majik-bip-39",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "type": "module",
+  "version": "0.1.0",
+  "description": "Derive deterministic BIP-39 mnemonics from PNG images, with optional Argon2id passphrase mode.",
+  "license": "Apache-2.0",
+  "author": "Zelijah",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Majikah/majik-bip-39.git"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/jedlsf"
+  },
+  "keywords": [
+    "bip39",
+    "bip-39",
+    "mnemonic",
+    "seed-phrase",
+    "recovery-phrase",
+    "image-to-mnemonic",
+    "png",
+    "image",
+    "deterministic",
+    "entropy",
+    "argon2id",
+    "cryptography",
+    "wallet"
+  ],
+  "homepage": "https://github.com/Majikah/majik-bip-39#readme",
+  "bugs": {
+    "url": "https://github.com/Majikah/majik-bip-39/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@noble/hashes": "2.4.0",
+    "@scure/bip39": "2.4.0",
+    "fast-png": "8.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "26.6.4",
+    "typescript": "7.0.2",
+    "vitest": "5.0.3"
+  },
+  "files": [
+    "dist",
+    "docs"
+  ]
+}