@majikah/majik-slink 0.0.2 → 0.2.0

package/LICENSE

@@ -1,67 +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.
-
+Copyright (c) 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.
+
+---
+
+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

@@ -1,74 +1,153 @@
 # Majik SLink
 
-[![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)
+[![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)
+![npm](https://img.shields.io/npm/v/@majikah/majik-slink) ![npm downloads](https://img.shields.io/npm/dm/@majikah/majik-slink) [![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)
 
-**MajikSLink** is a specialized TypeScript library designed for URL ownership verification and cryptographic identity linking. It provides a robust mechanism to prove that a specific digital identity (a MajikKey) controls a publicly accessible web resource (such as a YouTube channel, social media profile, or personal blog).
+**MajikSLink** is a specialized TypeScript library designed for URL binding, ownership, and cryptographic attribution. It provides a robust, zero-trust mechanism to prove that a specific digital identity (via a **MajikKey** and **MUID**) controls or is attested to a publicly accessible web resource (such as a YouTube channel, social media profile, DNS record, or personal blog).
 
-By combining traditional **Ed25519** signatures with post-quantum **ML-DSA-87** (Dilithium) hybrid cryptography, MajikSLink ensures that your identity-to-URL associations are tamper-proof and future-proof.
+By combining traditional **Ed25519** signatures with post-quantum **ML-DSA-87 (Dilithium)** hybrid cryptography via `@majikah/majik-signature`, MajikSLink ensures that your identity-to-URL associations are tamper-proof, resilient against future quantum threats, and structurally decoupled for decentralized verification.
 
+Identities can be created and managed via the web application at **[https://id.majikah.solutions](https://id.majikah.solutions)**.
 
+---
 
-Identities can be created and managed via the web application at **[https://id.majikah.solutions](https://id.majikah.solutions)** using your own Majik Keys.
+## Key Features
 
-![npm](https://img.shields.io/npm/v/@majikah/majik-slink) ![npm downloads](https://img.shields.io/npm/dm/@majikah/majik-slink) [![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)
+1. **Deterministic URL Normalization:** Automatically converts URLs into a canonical format (`majik-slink-v1:<subdomain>::<sld>::<tld>::<path>`). It strips tracking queries, fragments, and trailing slashes so the exact same core resource always generates a consistent hash and verification code.
+2. **Flexible Claim Types:**
+   * **`ownership`**: The strongest claim, indicating domain control. Verified via DNS TXT records.
+   * **`attribution`**: Indicates content control (e.g., a channel bio or GitHub README) but not DNS control. Verified via page content scraping.
+   * **`reference`**: A pure cryptographic attestation ("this URL is relevant to me") with no independent third-party verification possible.
+3. **Compact Post-Quantum Signatures:** Signatures are stored in a compact envelope. Public keys are *never* embedded directly, requiring verifiers to externally resolve them via the signer's `muid`, ensuring up-to-date registry checks.
+4. **Challenge-Response Verification:** Derives a short OTP-style code (`vCode`) from the SHA-256 hash of the canonical URL to be placed in DNS TXT records or page bios. 
+5. **Serialization Ready:** Built-in support for flawless JSON rehydration (`toJSON` / `fromJSON`) and Base64 serialization (`serialize` / `deserialize`).
 
+---
 
+## Installation
+
+```bash
+npm install @majikah/majik-slink @majikah/majik-key @majikah/majik-signature
+```
+
+---
 
+## Quick Start & Usage
 
-## Key Features:
-1. **Deterministic URL Normalization:** Automatically converts URLs into a canonical format (stripping query params and fragments) so that the same resource always generates the same verification code.
+### 1. Generating a UI Challenge (Without Signing)
+If you are building a UI and want to show the user their verification code *before* they confirm and sign, you can generate a challenge using just the URL.
 
-2. **Challenge-Response Verification:** Generates short, embeddable verification codes (v_code) that users can place in their bios or page metadata for automated scrapers to detect.
+```typescript
+import { MajikSLink } from "@majikah/majik-slink";
 
-3. **Hybrid Signing:** Leverages [@majikah/majik-signature](https://www.npmjs.com/package/@majikah/majik-signature) to sign canonical URL data with both classical and post-quantum algorithms.
+const preview = await MajikSLink.generateChallenge("https://github.com/majikah/repo?utm_source=test#readme");
 
-4. **Proof of Ownership:** Enables a trustless workflow where a crawler can verify the presence of a code, and the library verifies the cryptographic signature against the owner's public keys.
+if (preview) {
+  console.log("Canonical URL:", preview.cleanUrl); // https://github.com/majikah/repo
+  console.log("Ask user to add this to their bio:", preview.v_code); // majik-slink:xxxx...
+}
+```
 
-5. **Seamless Serialization:** Includes built-in support for JSON rehydration and Base64 serialization for easy storage in databases or transmission via QR codes.
+### 2. Creating and Signing a New SLink
+To permanently link an identity to a URL, create a `MajikSLink` instance using an unlocked `MajikKey`.
 
+```typescript
+import { MajikKey } from "@majikah/majik-key";
 
-## Related Projects
+// 1. Initialize and unlock your identity
+const mnemonic = MajikKey.generateMnemonic();
+const key = await MajikKey.create(mnemonic, 'my-passphrase', 'My Signing Key');
+const userId = "user_abc123";
+const muid = "muid_xyz987";
 
+// 2. Create the SLink payload
+const targetUrl = "https://www.youtube.com/watch?v=dQw4w9WgXcQ";
 
-### [Majik Signature](https://www.npmjs.com/package/@majikah/majik-signature)
-Hybrid post-quantum content signing — the signing engine used by `signContent()` and `signFile()`.
+const slink = await MajikSLink.create(targetUrl, key, userId, muid, {
+  claimType: "attribution" // Automatically defaults verificationMethod to "page_content"
+});
 
-[Read Docs](https://majikah.solutions/products/majik-signature/docs) · [Microsoft Store](https://apps.microsoft.com/detail/9pl9g3xzvd1x)
+console.log("Status:", slink.status); // "unverified"
+console.log("Source Platform:", slink.source); // "youtube"
+```
 
-[![Majik Signature Microsoft App Store](https://get.microsoft.com/images/en-us%20light.svg)](https://apps.microsoft.com/detail/9pl9g3xzvd1x)
+### 3. Displaying Verification Requirements
+Depending on the `claimType`, you can guide users on how to prove their link:
 
+```typescript
+if (slink.verificationMethod === "dns_txt") {
+  console.log("Add a TXT Record:");
+  console.log("Name:", slink.dnsRecordName);   // _majik-challenge.youtube.com
+  console.log("Value:", slink.dnsRecordValue); // majik-slink-verify=majik-slink:a1b2...
+} else if (slink.verificationMethod === "page_content") {
+  console.log("Add this code anywhere in your bio or README:");
+  console.log(slink.vCode); // majik-slink:a1b2...
+  
+  // You can also display it in nice OTP chunks:
+  console.log("Display Code:", slink.codeChunks.join("-"));
+}
+```
 
+### 4. Verifying Cryptographic Signatures
+Because MajikSLink uses **compact signatures**, public keys are not stored in the SLink payload. You must fetch the public keys (via `muid`) from your trusted identity registry to verify the claim.
 
-### [Majik Message](https://message.majikah.solutions)
-Secure messaging platform using Majik Keys and Majik Signatures for identity-bound communication.
+```typescript
+import { MajikSignature } from "@majikah/majik-signature";
 
-[Read Docs](https://majikah.solutions/products/majik-message/docs) · [Microsoft Store](https://apps.microsoft.com/detail/9pmjgvzzjspn)
+// 1. Fetch public keys from your trusted registry using the SLink's MUID
+const publicKeys = await fetchPublicKeysForMuid(slink.muid); 
 
-[![Majik Message Microsoft App Store](https://get.microsoft.com/images/en-us%20light.svg)](https://apps.microsoft.com/detail/9pmjgvzzjspn)
+// 2. Verify the cryptographic signature against the canonical URL
+const verificationResult = slink.verify(publicKeys);
 
+if (verificationResult.valid) {
+    console.log("Valid signature from:", verificationResult.signerId);
+    
+    // 3. (Optional) If you also successfully scraped the vCode from the web:
+    slink.markVerified(); 
+} else {
+    slink.markSignatureInvalid();
+}
+```
 
-### [Majik Key](https://www.npmjs.com/package/@majikah/majik-key)
-Seed phrase account library — required peer dependency for signing and encryption.
+*Note: You can also verify statically without hydrating via `MajikSLink.verifySignature(slinkJSON, publicKeys)`.*
 
-[Read More Information](https://majikah.solutions/sdk/majik-key)
+### 5. Utilities & Comparisons
+Easily compare URLs to see if they resolve to the exact same signed resource:
 
-### [Majik Envelope](https://www.npmjs.com/package/@majikah/majik-envelope)
-Post-quantum group encryption — used to encrypt and share private personal info.
+```typescript
+// Ignores query params and fragments automatically
+const isMatch = slink.isSameResource("https://www.youtube.com/watch?v=dQw4w9WgXcQ&t=42s");
+console.log(isMatch); // true
 
-[Read More Information](https://majikah.solutions/sdk/majik-envelope)
+// View a human-readable debug summary
+console.log(slink.toSummary());
+```
 
+### 6. Serialization and Database Storage
+Store and retrieve `MajikSLink` objects seamlessly.
 
-### [Majik Universal ID](https://id.majikah.solutions)
-A cryptographically anchored identity layer for the Majikah ecosystem.
+```typescript
+// Export to JSON for Database storage
+const jsonPayload = slink.toJSON();
 
-[Read More Information](https://majikah.solutions/sdk/majik-universal-id)
+// Hydrate from DB (Note: signatures must still be verified with external keys)
+const hydratedSLink = MajikSLink.fromJSON(jsonPayload);
 
+// Export to Base64 (Useful for QR codes or URL parameters)
+const base64String = slink.serialize();
+const fromBase64 = MajikSLink.deserialize(base64String);
+```
 
 ---
 
-## Contributing
+## Related Ecosystem Projects
 
-If you want to contribute or help extend support, reach out via email. All contributions are welcome!
+*   **[Majik Signature](https://www.npmjs.com/package/@majikah/majik-signature)**: Hybrid post-quantum content signing engine. ([Microsoft Store](https://apps.microsoft.com/detail/9pl9g3xzvd1x))
+*   **[Majik Message](https://message.majikah.solutions)**: Secure messaging platform utilizing Majik Keys and hybrid ML-KEM-768/X25519 protocols for identity-bound communication. ([Microsoft Store](https://apps.microsoft.com/detail/9pmjgvzzjspn))
+*   **[Majik Key](https://www.npmjs.com/package/@majikah/majik-key)**: Foundational seed phrase account library.
+*   **[Majik Universal ID](https://id.majikah.solutions)**: A cryptographically anchored identity layer for the Majikah ecosystem.
+*   **[Majik Envelope](https://www.npmjs.com/package/@majikah/majik-envelope)**: Post-quantum group encryption.
 
 ---
 
@@ -80,16 +159,16 @@ If you want to contribute or help extend support, reach out via email. All contr
 
 ## Author
 
-Made with 💙 by [@thezelijah](https://github.com/jedlsf)
+Developed by **Josef Elijah Fabian (Zelijah)** | [Majikah Solutions OPC](https://majikah.solutions/about)
 
-**Developer**: Josef Elijah Fabian  
-**GitHub**: [https://github.com/jedlsf](https://github.com/jedlsf)  
-**Project Repository**: [https://github.com/Majikah/majik-slink](https://github.com/Majikah/majik-slink)
+**Developer**: [Josef Elijah Fabian](https://github.com/jedlsf)  
+**GitHub**: [https://github.com/Majikah](https://github.com/Majikah)  
+**Project Repository**: [https://github.com/Majikah/majik-slink](https://github.com/Majikah/majik-slink)  
 
 ---
 
 ## Contact
 
-- **Business Email**: [business@thezelijah.world](mailto:business@thezelijah.world)
+- **Business Email**: [business@majikah.solutions](mailto:business@majikah.solutions)
 - **Official Website**: [https://www.thezelijah.world](https://www.thezelijah.world)
-- **ID Web App**: [https://id.majikah.solutions](https://id.majikah.solutions)
+- **Majikah Ecosystem**: [https://majikah.solutions](https://majikah.solutions)

package/dist/core/types.d.ts

@@ -1,26 +1,23 @@
-import { MajikSignatureJSON } from "@majikah/majik-signature";
-/** Source platform of the signed URL */
-export type SLinkSource = "youtube" | "x" | "instagram" | "tiktok" | "github" | "website" | "other";
-/** Structured URL parts extracted during normalisation */
-export interface UrlInfo {
-    /** Full registered domain e.g. "youtube.com" */
-    domain: string;
-    /** Second-level domain only e.g. "youtube" */
-    sld: string;
-    /** Top-level domain e.g. "com" */
-    tld: string;
-    /** Subdomain or null e.g. "www" | null */
-    subdomain: string | null;
-    /** Normalised pathname e.g. "/watch/dQw4w9WgXcQ" */
-    path: string;
-    /** Reconstructed clean URL (no params, no fragment) */
-    cleanUrl: string;
-    /** The string that is actually hashed + signed */
-    canonical: string;
-}
+import { ISODateString } from "@majikah/majik-key";
+import { MajikSignatureCompactJSON } from "@majikah/majik-signature";
+/**
+ * What kind of relationship the user claims to have with this URL.
+ *   - "ownership":    user controls the domain (can add a DNS TXT record).
+ *                      Strongest proof; independent of any single page's content.
+ *   - "attribution":  user controls the *content* at this URL (a profile bio,
+ *                      video description, repo README) but not the domain/DNS
+ *                      itself — e.g. a YouTube channel, a GitHub profile.
+ *                      Provable only via page-embed code, never DNS.
+ *   - "reference":     user controls neither the domain nor the content.
+ *                      A pure attestation ("this URL is about me / relevant to
+ *                      me") with no independent proof possible. Should never
+ *                      be presented to end users as "verified" — surface it
+ *                      as "attested by <signer>" instead.
+ */
+export type SLinkClaimType = "ownership" | "attribution" | "reference";
+export type SLinkVerificationMethod = "dns_txt" | "page_content" | null;
 /** Verification status of a MajikSLink */
 export type SLinkVerificationStatus = "pending" | "unverified" | "verified" | "failed" | "sig_invalid";
-/** Shape persisted to / rehydrated from a database */
 export interface MajikSLinkJSON {
     version: 1;
     id: string;
@@ -40,14 +37,35 @@ export interface MajikSLinkJSON {
     v_code: string;
     /** Detected source platform */
     source: SLinkSource;
+    claim_type: SLinkClaimType;
+    verification_method: SLinkVerificationMethod;
     /** Verification status */
     status: SLinkVerificationStatus;
     /** ISO timestamp of when this SLink was created */
-    timestamp: string;
+    timestamp: ISODateString;
     /** ISO timestamp of the last verification attempt, or null */
-    verified_at: string | null;
-    /** The MajikSignature envelope covering the canonical URL */
-    signature: MajikSignatureJSON;
+    verified_at: ISODateString | null;
+    /** Compact envelope — no embedded public keys. Resolve via muid/signerId at verify time. */
+    signature: MajikSignatureCompactJSON;
+}
+/** Source platform of the signed URL */
+export type SLinkSource = "youtube" | "x" | "instagram" | "tiktok" | "github" | "website" | "other";
+/** Structured URL parts extracted during normalisation */
+export interface UrlInfo {
+    /** Full registered domain e.g. "youtube.com" */
+    domain: string;
+    /** Second-level domain only e.g. "youtube" */
+    sld: string;
+    /** Top-level domain e.g. "com" */
+    tld: string;
+    /** Subdomain or null e.g. "www" | null */
+    subdomain: string | null;
+    /** Normalised pathname e.g. "/watch/dQw4w9WgXcQ" */
+    path: string;
+    /** Reconstructed clean URL (no params, no fragment) */
+    cleanUrl: string;
+    /** The string that is actually hashed + signed */
+    canonical: string;
 }
 /** Lightweight code-only payload — useful for the UI before full create() */
 export interface SLinkCodePreview {
@@ -60,3 +78,25 @@ export interface SLinkCodePreview {
     /** Parsed URL parts */
     urlInfo: UrlInfo;
 }
+export interface MajikSLinkConstructorOptions {
+    version: 1;
+    id: string;
+    user_id: string;
+    muid: string;
+    domain: string;
+    sld: string;
+    tld: string;
+    subdomain: string | null;
+    path: string;
+    url: string;
+    clean_url: string;
+    hash: string;
+    v_code: string;
+    source: SLinkSource;
+    claim_type?: SLinkClaimType;
+    verification_method?: SLinkVerificationMethod;
+    status: SLinkVerificationStatus;
+    verified_at: Date | null;
+    signature: MajikSignatureCompactJSON;
+    timestamp: Date;
+}

package/dist/core/utils.d.ts

@@ -1,5 +1,5 @@
 import { MajikKey } from "@majikah/majik-key";
-import { SLinkSource, UrlInfo } from "./types";
+import { SLinkClaimType, SLinkSource, SLinkVerificationMethod, UrlInfo } from "./types";
 export declare function sha256Hex(input: string): Promise<string>;
 export declare function generateId(): string;
 /**
@@ -22,3 +22,11 @@ export declare function parseUrlInfo(rawUrl: string): UrlInfo | null;
  * Used during fromJSON rehydration to avoid re-running PSL.
  */
 export declare function buildCanonical(subdomain: string | null, sld: string, tld: string, path: string): string;
+/**
+ * Derive the natural default verification method for a claim type when the
+ * caller doesn't specify one explicitly.
+ *   - "ownership"   → "dns_txt" (strongest available proof for a domain the signer controls)
+ *   - "attribution" → "page_content" (only proof possible without domain control)
+ *   - "reference"   → null (no independent proof is possible at all)
+ */
+export declare function defaultVerificationMethod(claimType: SLinkClaimType): SLinkVerificationMethod;

package/dist/core/utils.js

@@ -118,3 +118,20 @@ export function parseUrlInfo(rawUrl) {
 export function buildCanonical(subdomain, sld, tld, path) {
     return `${CANONICAL_PREFIX}${subdomain ?? "root"}::${sld}::${tld}::${path}`;
 }
+/**
+ * Derive the natural default verification method for a claim type when the
+ * caller doesn't specify one explicitly.
+ *   - "ownership"   → "dns_txt" (strongest available proof for a domain the signer controls)
+ *   - "attribution" → "page_content" (only proof possible without domain control)
+ *   - "reference"   → null (no independent proof is possible at all)
+ */
+export function defaultVerificationMethod(claimType) {
+    switch (claimType) {
+        case "ownership":
+            return "dns_txt";
+        case "attribution":
+            return "page_content";
+        case "reference":
+            return null;
+    }
+}

package/dist/index.d.ts

@@ -6,4 +6,4 @@ export { MajikSLink } from "./majik-slink";
 export type * from "./core/types";
 export * from "./core/errors";
 export * from "./core/constants";
-export { parseUrlInfo, buildCanonical, detectSource } from "./core/utils";
+export { parseUrlInfo, buildCanonical, detectSource, defaultVerificationMethod, } from "./core/utils";

package/dist/index.js

@@ -9,4 +9,4 @@ export * from "./core/errors";
 // ── Constants ─────────────────────────────────────────────────────────────────
 export * from "./core/constants";
 // ── Low-level utilities (opt-in) ──────────────────────────────────────────────
-export { parseUrlInfo, buildCanonical, detectSource } from "./core/utils";
+export { parseUrlInfo, buildCanonical, detectSource, defaultVerificationMethod, } from "./core/utils";

package/dist/majik-slink.d.ts

@@ -2,13 +2,13 @@
  * majik-slink.ts
  */
 import type { MajikKey } from "@majikah/majik-key";
-import { MajikSignature, type MajikSignatureJSON } from "@majikah/majik-signature";
-import { MajikSLinkJSON, SLinkCodePreview, SLinkSource, SLinkVerificationStatus, UrlInfo } from "./core/types";
+import { MajikSignature, MajikSignatureCompactJSON, MajikSignerPublicKeys, VerificationResult } from "@majikah/majik-signature";
+import { MajikSLinkJSON, SLinkClaimType, SLinkCodePreview, SLinkSource, SLinkVerificationMethod, SLinkVerificationStatus, UrlInfo } from "./core/types";
 /**
  * MajikSLink
  * ---------------------
- * MajikSLink — URL ownership signing and verification.
- * A MajikSLink proves that the holder of a MajikKey owns (or controls) a
+ * MajikSLink — URL binding, ownership, and attribution signing/verification.
+ * A MajikSLink cryptographically associates a MUID/MajikKey with a
  * publicly-accessible URL by:
  *
  *   1. Normalising the URL to a canonical form (scheme + subdomain + domain +
@@ -16,13 +16,28 @@ import { MajikSLinkJSON, SLinkCodePreview, SLinkSource, SLinkVerificationStatus,
  *   2. Deriving a short, deterministic verification code from a SHA-256 digest
  *      of the canonical URL parts — so the same resource always produces the
  *      same code regardless of query params or tracking tokens.
- *   3. Signing the canonical URL string with the owner's MajikKey via
- *      MajikSignature (Ed25519 + ML-DSA-87 hybrid).
+ *   3. Signing the canonical URL string with the signer's MajikKey via
+ *      MajikSignature (Ed25519 + ML-DSA-87 hybrid), stored in compact form
+ *      (no embedded public keys — resolved externally at verify time via
+ *      muid / signerId).
  *
- * The owner embeds the verification code (`v_code`) anywhere in the public
- * page (description, bio, comment, HTML body) and a scraper verifies its
- * presence. Once found, the MajikSignature certifies the association between
- * the signer's identity and the URL.
+ * The *strength* of the claim is described by `claimType`:
+ *   - "ownership":   the signer controls the domain. Verifiable via DNS TXT
+ *                     (strongest — survives page changes) or page content.
+ *   - "attribution": the signer controls the content at this URL (a channel
+ *                     bio, repo README) but not the domain/DNS. Verifiable
+ *                     only via page content.
+ *   - "reference":   the signer controls neither. A signed attestation with
+ *                     no independent proof possible — never present this to
+ *                     end users as "verified"; surface it as "attested by
+ *                     <signer>" instead.
+ * See `SLinkClaimType` / `SLinkVerificationMethod` for the full contract.
+ *
+ * For "dns_txt" verification, the owner publishes `dnsRecordValue` at
+ * `dnsRecordName`. For "page_content", the owner embeds `vCode` anywhere in
+ * the public page (description, bio, comment, HTML body) and a scraper
+ * verifies its presence. Once found, the MajikSignature certifies the
+ * association between the signer's identity and the URL.
  *
  * Canonical URL format (what is signed):
  *   "majik-slink-v1:<subdomain>::<sld>::<tld>::<path>"
@@ -49,8 +64,10 @@ export declare class MajikSLink {
     private readonly _source;
     private _status;
     private _verified_at;
+    private readonly _claim_type;
+    private readonly _verification_method;
     private readonly _signature;
-    private _signatureInstance;
+    private _resolvedSignature;
     private readonly _timestamp;
     private constructor();
     get version(): 1;
@@ -79,20 +96,59 @@ export declare class MajikSLink {
     get status(): SLinkVerificationStatus;
     get verifiedAt(): Date | null;
     /**
-     * Get the signature as a MajikSignature instance.
-     * The instance is cached to avoid re-parsing on every access.
+     * The resolved MajikSignature instance, if `resolveSignature()` has been
+     * called. Null until then — MajikSLink stores only the compact envelope
+     * (no embedded public keys), so there is nothing to eagerly resolve.
+     */
+    get signature(): MajikSignature | null;
+    /**
+     * Get the raw compact signature JSON as stored/persisted.
+     * No public keys are embedded — resolve them externally (e.g. by
+     * `signerId` / `muid` from your key registry) before verifying.
      */
-    get signature(): MajikSignature;
+    get signatureJSON(): MajikSignatureCompactJSON;
     /**
-     * Get the raw signature JSON.
-     * Useful when you need the serializable form without parsing.
+     * Resolve the compact signature into a full MajikSignature instance, using
+     * externally-supplied public keys (looked up by `this.muid` or
+     * `this.signatureJSON.signerId` from your key registry).
+     *
+     * There is nothing to fall back to by design — MajikSLink never stores
+     * public keys inline, so `publicKeys` is mandatory. The result is cached;
+     * subsequent calls with the same (correct) keys are free.
+     *
+     * @throws {MajikSLinkValidationError} if `publicKeys.signerId` does not
+     *         match the signerId recorded on this SLink's signature.
+     *
+     * @example
+     *   const keys = await resolvePublicKeysForMuid(slink.muid);
+     *   const sig = slink.resolveSignature(keys);
+     *   console.log(sig.hasTSA);
      */
-    get signatureJSON(): MajikSignatureJSON;
+    resolveSignature(publicKeys: MajikSignerPublicKeys): MajikSignature;
+    get claimType(): SLinkClaimType;
+    get verificationMethod(): SLinkVerificationMethod;
     get timestamp(): Date;
     /** True when a successful scrape + signature verification has been recorded */
     get isVerified(): boolean;
     /** The OTP-display chunks (groups of 4 hex chars from the hash) */
     get codeChunks(): string[];
+    /**
+     * The DNS TXT record name to publish for `"dns_txt"` verification.
+     * Only meaningful when `verificationMethod === "dns_txt"` — for
+     * `"page_content"` or `"reference"` SLinks this value is simply
+     * irrelevant (not an error), so check `verificationMethod` before using it.
+     *
+     * @example "_majik-challenge.example.com"
+     */
+    get dnsRecordName(): string;
+    /**
+     * The DNS TXT record value to publish for `"dns_txt"` verification.
+     * See `dnsRecordName` — only meaningful when
+     * `verificationMethod === "dns_txt"`.
+     *
+     * @example "majik-slink-verify=majik-slink:a1b2c3d4..."
+     */
+    get dnsRecordValue(): string;
     /**
      * Create and sign a new MajikSLink.
      *
@@ -119,6 +175,8 @@ export declare class MajikSLink {
         id?: string;
         timestamp?: Date;
         status?: SLinkVerificationStatus;
+        claimType?: SLinkClaimType;
+        verificationMethod?: SLinkVerificationMethod;
     }): Promise<MajikSLink>;
     /**
      * Derive the verification code and URL info for a raw URL *without* signing.
@@ -135,43 +193,53 @@ export declare class MajikSLink {
      */
     static generateChallenge(rawUrl: string): Promise<SLinkCodePreview | null>;
     /**
-     * Verify the embedded MajikSignature of a persisted MajikSLink.
+     * Verify the stored MajikSignature of a persisted MajikSLink against
+     * externally-supplied public keys.
      *
-     * This does NOT scrape the target page — it only cryptographically checks
-     * that the signature covers the canonical URL and was issued by the stated
-     * signer.
+     * This does NOT scrape the target page or check DNS — it only
+     * cryptographically checks that the signature covers the canonical URL
+     * and was issued by the holder of `publicKeys`. No public keys are
+     * embedded in the stored SLink; you must resolve them yourself (e.g. by
+     * `signerId` / `muid` from your key registry) before calling this.
      *
-     * Use in conjunction with your scraper to fully verify ownership:
-     *   1. Scrape the page and confirm `v_code` is present.
+     * Use in conjunction with your DNS/scrape check to fully verify a claim:
+     *   1. Look up (dns_txt) or scrape (page_content) per `verificationMethod`
+     *      and confirm `v_code` is present.
      *   2. Call `verifySignature()` to confirm the cryptographic provenance.
      *
      * @example
-     *   const result = MajikSLink.verifySignature(slink, signerPublicKeys);
-     *   if (!result.valid) console.warn("Signature tampered:", result.reason);
+     *   const keys = await resolvePublicKeysForMuid(slink.muid);
+     *   const result = MajikSLink.verifySignature(slink, keys);
+     *   if (!result.valid) console.warn("Signature invalid:", result.reason);
      */
-    static verifySignature(slink: MajikSLink | MajikSLinkJSON, publicKeys: Parameters<typeof MajikSignature.verify>[2]): ReturnType<typeof MajikSignature.verify>;
+    static verifySignature(slink: MajikSLink | MajikSLinkJSON, publicKeys: MajikSignerPublicKeys): VerificationResult;
     /**
-     * Verify this SLink's embedded signature against the provided public keys.
+     * Verify this SLink's stored signature against externally-supplied
+     * public keys.
      *
      * This validates that:
      *   1. The signature cryptographically matches the canonical URL
      *   2. The signature was created by the holder of the private key
+     *      corresponding to `publicKeys`
      *
-     * Note: This does NOT scrape the page. Use with `markVerified()` after
-     * a successful scrape to complete the verification flow.
+     * Note: This does NOT scrape the page or check DNS. Use with
+     * `markVerified()` after a successful DNS lookup / scrape (per
+     * `verificationMethod`) to complete the verification flow.
      *
-     * @param publicKeys The signer's public keys (classic Ed25519 + ML-DSA-87)
+     * @param publicKeys The signer's public keys (classic Ed25519 + ML-DSA-87),
+     *                    resolved externally — e.g. by `this.muid`.
      * @returns Verification result with valid/invalid status and optional reason
      *
      * @example
-     *   // After scraping and finding v_code on the page:
-     *   const result = slink.verify(user.publicKeys);
+     *   // After confirming v_code via DNS or page scrape:
+     *   const keys = await resolvePublicKeysForMuid(slink.muid);
+     *   const result = slink.verify(keys);
      *   if (result.valid) {
      *     slink.markVerified();
      *     await db.save(slink);
      *   }
      */
-    verify(publicKeys?: Parameters<typeof MajikSignature.verify>[2]): ReturnType<typeof MajikSignature.verify>;
+    verify(publicKeys: MajikSignerPublicKeys): VerificationResult;
     /**
      * Record a successful scrape verification.
      * Should be called by your server route after a positive scrape result.
@@ -208,7 +276,8 @@ export declare class MajikSLink {
     toJSON(): MajikSLinkJSON;
     /**
      * Rehydrate a MajikSLink from a plain JSON object (e.g. from a database row).
-     * Does NOT re-verify the signature — call `verify()` explicitly.
+     * Does NOT re-verify the signature — call `verify()` explicitly with
+     * externally-resolved public keys.
      *
      * @throws {MajikSLinkSerializationError} if any required field is missing or malformed.
      */

package/dist/majik-slink.js

@@ -1,16 +1,16 @@
 /**
  * majik-slink.ts
  */
-import { base64ToBytes, MajikSignature, } from "@majikah/majik-signature";
+import { MajikSignature, } from "@majikah/majik-signature";
 import { MajikSLinkError, MajikSLinkSerializationError, MajikSLinkSigningError, MajikSLinkValidationError, } from "./core/errors";
 import { CODE_HEX_LENGTH, CODE_PREFIX, SLINK_VERSION } from "./core/constants";
-import { assertMajikKey, assertNonEmptyString, assertUnlockedKey, assertValidHttpUrl, buildCanonical, detectSource, generateId, parseUrlInfo, sha256Hex, } from "./core/utils";
+import { assertMajikKey, assertNonEmptyString, assertUnlockedKey, assertValidHttpUrl, buildCanonical, defaultVerificationMethod, detectSource, generateId, parseUrlInfo, sha256Hex, } from "./core/utils";
 // ─── MajikSLink ───────────────────────────────────────────────────────────────
 /**
  * MajikSLink
  * ---------------------
- * MajikSLink — URL ownership signing and verification.
- * A MajikSLink proves that the holder of a MajikKey owns (or controls) a
+ * MajikSLink — URL binding, ownership, and attribution signing/verification.
+ * A MajikSLink cryptographically associates a MUID/MajikKey with a
  * publicly-accessible URL by:
  *
  *   1. Normalising the URL to a canonical form (scheme + subdomain + domain +
@@ -18,13 +18,28 @@ import { assertMajikKey, assertNonEmptyString, assertUnlockedKey, assertValidHtt
  *   2. Deriving a short, deterministic verification code from a SHA-256 digest
  *      of the canonical URL parts — so the same resource always produces the
  *      same code regardless of query params or tracking tokens.
- *   3. Signing the canonical URL string with the owner's MajikKey via
- *      MajikSignature (Ed25519 + ML-DSA-87 hybrid).
+ *   3. Signing the canonical URL string with the signer's MajikKey via
+ *      MajikSignature (Ed25519 + ML-DSA-87 hybrid), stored in compact form
+ *      (no embedded public keys — resolved externally at verify time via
+ *      muid / signerId).
  *
- * The owner embeds the verification code (`v_code`) anywhere in the public
- * page (description, bio, comment, HTML body) and a scraper verifies its
- * presence. Once found, the MajikSignature certifies the association between
- * the signer's identity and the URL.
+ * The *strength* of the claim is described by `claimType`:
+ *   - "ownership":   the signer controls the domain. Verifiable via DNS TXT
+ *                     (strongest — survives page changes) or page content.
+ *   - "attribution": the signer controls the content at this URL (a channel
+ *                     bio, repo README) but not the domain/DNS. Verifiable
+ *                     only via page content.
+ *   - "reference":   the signer controls neither. A signed attestation with
+ *                     no independent proof possible — never present this to
+ *                     end users as "verified"; surface it as "attested by
+ *                     <signer>" instead.
+ * See `SLinkClaimType` / `SLinkVerificationMethod` for the full contract.
+ *
+ * For "dns_txt" verification, the owner publishes `dnsRecordValue` at
+ * `dnsRecordName`. For "page_content", the owner embeds `vCode` anywhere in
+ * the public page (description, bio, comment, HTML body) and a scraper
+ * verifies its presence. Once found, the MajikSignature certifies the
+ * association between the signer's identity and the URL.
  *
  * Canonical URL format (what is signed):
  *   "majik-slink-v1:<subdomain>::<sld>::<tld>::<path>"
@@ -52,8 +67,10 @@ export class MajikSLink {
     _source;
     _status;
     _verified_at;
+    _claim_type;
+    _verification_method;
     _signature;
-    _signatureInstance = null; // Cached instance
+    _resolvedSignature = null;
     _timestamp;
     // ── Private constructor — use MajikSLink.create() ────────────────────────
     constructor(data) {
@@ -71,6 +88,12 @@ export class MajikSLink {
         this._hash = data.hash;
         this._v_code = data.v_code;
         this._source = data.source;
+        // `??` — not `||` — so an explicit `null` (a deliberate "no verification
+        // possible" for claim_type "reference") is preserved rather than being
+        // silently overwritten by the default.
+        this._claim_type = data.claim_type ?? "ownership";
+        this._verification_method =
+            data.verification_method ?? defaultVerificationMethod(this._claim_type);
         this._status = data.status;
         this._verified_at = data.verified_at;
         this._signature = data.signature;
@@ -135,22 +158,53 @@ export class MajikSLink {
         return this._verified_at;
     }
     /**
-     * Get the signature as a MajikSignature instance.
-     * The instance is cached to avoid re-parsing on every access.
+     * The resolved MajikSignature instance, if `resolveSignature()` has been
+     * called. Null until then — MajikSLink stores only the compact envelope
+     * (no embedded public keys), so there is nothing to eagerly resolve.
      */
     get signature() {
-        if (!this._signatureInstance) {
-            this._signatureInstance = MajikSignature.fromJSON(this._signature);
-        }
-        return this._signatureInstance;
+        return this._resolvedSignature;
     }
     /**
-     * Get the raw signature JSON.
-     * Useful when you need the serializable form without parsing.
+     * Get the raw compact signature JSON as stored/persisted.
+     * No public keys are embedded — resolve them externally (e.g. by
+     * `signerId` / `muid` from your key registry) before verifying.
      */
     get signatureJSON() {
         return this._signature;
     }
+    /**
+     * Resolve the compact signature into a full MajikSignature instance, using
+     * externally-supplied public keys (looked up by `this.muid` or
+     * `this.signatureJSON.signerId` from your key registry).
+     *
+     * There is nothing to fall back to by design — MajikSLink never stores
+     * public keys inline, so `publicKeys` is mandatory. The result is cached;
+     * subsequent calls with the same (correct) keys are free.
+     *
+     * @throws {MajikSLinkValidationError} if `publicKeys.signerId` does not
+     *         match the signerId recorded on this SLink's signature.
+     *
+     * @example
+     *   const keys = await resolvePublicKeysForMuid(slink.muid);
+     *   const sig = slink.resolveSignature(keys);
+     *   console.log(sig.hasTSA);
+     */
+    resolveSignature(publicKeys) {
+        if (!this._resolvedSignature) {
+            if (publicKeys.signerId !== this._signature.signerId) {
+                throw new MajikSLinkValidationError(`publicKeys are for signer "${publicKeys.signerId}" but this SLink was signed by "${this._signature.signerId}".`);
+            }
+            this._resolvedSignature = MajikSignature.fromCompact(this._signature, publicKeys);
+        }
+        return this._resolvedSignature;
+    }
+    get claimType() {
+        return this._claim_type;
+    }
+    get verificationMethod() {
+        return this._verification_method;
+    }
     get timestamp() {
         return this._timestamp;
     }
@@ -167,6 +221,27 @@ export class MajikSLink {
         }
         return chunks;
     }
+    /**
+     * The DNS TXT record name to publish for `"dns_txt"` verification.
+     * Only meaningful when `verificationMethod === "dns_txt"` — for
+     * `"page_content"` or `"reference"` SLinks this value is simply
+     * irrelevant (not an error), so check `verificationMethod` before using it.
+     *
+     * @example "_majik-challenge.example.com"
+     */
+    get dnsRecordName() {
+        return `_majik-challenge.${this._domain}`;
+    }
+    /**
+     * The DNS TXT record value to publish for `"dns_txt"` verification.
+     * See `dnsRecordName` — only meaningful when
+     * `verificationMethod === "dns_txt"`.
+     *
+     * @example "majik-slink-verify=majik-slink:a1b2c3d4..."
+     */
+    get dnsRecordValue() {
+        return `majik-slink-verify=${this._v_code}`;
+    }
     // ── Static: create ────────────────────────────────────────────────────────
     /**
      * Create and sign a new MajikSLink.
@@ -202,16 +277,14 @@ export class MajikSLink {
         if (!urlInfo) {
             throw new MajikSLinkValidationError(`Could not parse URL into a valid domain: "${rawUrl}". Ensure it is a public https:// URL.`);
         }
-        // ── Hash the canonical string ────────────────────────────────────────
+        const ts = options?.timestamp ?? new Date();
         const hash = await sha256Hex(urlInfo.canonical);
         const v_code = `${CODE_PREFIX}${hash.slice(0, CODE_HEX_LENGTH)}`;
-        // ── Sign with MajikSignature ─────────────────────────────────────────
         let signature;
         try {
-            signature = await MajikSignature.sign(urlInfo.canonical, // what we're signing
-            key, {
+            signature = await MajikSignature.sign(urlInfo.canonical, key, {
                 contentType: "majik-slink/url",
-                timestamp: (options?.timestamp ?? new Date()).toISOString(),
+                timestamp: ts.toISOString(),
             });
         }
         catch (err) {
@@ -221,7 +294,7 @@ export class MajikSLink {
             version: SLINK_VERSION,
             id: options?.id ?? generateId(),
             user_id: userId,
-            muid: muid,
+            muid,
             domain: urlInfo.domain,
             sld: urlInfo.sld,
             tld: urlInfo.tld,
@@ -232,10 +305,12 @@ export class MajikSLink {
             hash,
             v_code,
             source: detectSource(urlInfo.sld),
+            claim_type: options?.claimType ?? "ownership",
+            verification_method: options?.verificationMethod ?? null,
             status: options?.status ?? "unverified",
             verified_at: null,
-            signature: signature.toJSON(),
-            timestamp: options?.timestamp ?? new Date(),
+            signature: signature.toCompact(),
+            timestamp: ts,
         });
     }
     // ── Static: generateChallenge ─────────────────────────────────────────────
@@ -268,65 +343,63 @@ export class MajikSLink {
     }
     // ── Static: verifySignature ───────────────────────────────────────────────
     /**
-     * Verify the embedded MajikSignature of a persisted MajikSLink.
+     * Verify the stored MajikSignature of a persisted MajikSLink against
+     * externally-supplied public keys.
      *
-     * This does NOT scrape the target page — it only cryptographically checks
-     * that the signature covers the canonical URL and was issued by the stated
-     * signer.
+     * This does NOT scrape the target page or check DNS — it only
+     * cryptographically checks that the signature covers the canonical URL
+     * and was issued by the holder of `publicKeys`. No public keys are
+     * embedded in the stored SLink; you must resolve them yourself (e.g. by
+     * `signerId` / `muid` from your key registry) before calling this.
      *
-     * Use in conjunction with your scraper to fully verify ownership:
-     *   1. Scrape the page and confirm `v_code` is present.
+     * Use in conjunction with your DNS/scrape check to fully verify a claim:
+     *   1. Look up (dns_txt) or scrape (page_content) per `verificationMethod`
+     *      and confirm `v_code` is present.
      *   2. Call `verifySignature()` to confirm the cryptographic provenance.
      *
      * @example
-     *   const result = MajikSLink.verifySignature(slink, signerPublicKeys);
-     *   if (!result.valid) console.warn("Signature tampered:", result.reason);
+     *   const keys = await resolvePublicKeysForMuid(slink.muid);
+     *   const result = MajikSLink.verifySignature(slink, keys);
+     *   if (!result.valid) console.warn("Signature invalid:", result.reason);
      */
     static verifySignature(slink, publicKeys) {
         const json = slink instanceof MajikSLink ? slink.toJSON() : slink;
-        // Reconstruct the canonical string from stored parts
-        // We need to extract sld and tld from the domain field
         const parts = json.domain.split(".");
         const tld = parts[parts.length - 1] ?? "";
         const sld = parts.slice(0, -1).join(".") || json.domain;
         const canonical = buildCanonical(json.subdomain, sld, tld, json.path);
-        return MajikSignature.verify(canonical, json.signature, publicKeys);
+        return MajikSignature.verifyCompact(canonical, json.signature, publicKeys);
     }
     // ── Instance: verify ──────────────────────────────────────────────────────
     /**
-     * Verify this SLink's embedded signature against the provided public keys.
+     * Verify this SLink's stored signature against externally-supplied
+     * public keys.
      *
      * This validates that:
      *   1. The signature cryptographically matches the canonical URL
      *   2. The signature was created by the holder of the private key
+     *      corresponding to `publicKeys`
      *
-     * Note: This does NOT scrape the page. Use with `markVerified()` after
-     * a successful scrape to complete the verification flow.
+     * Note: This does NOT scrape the page or check DNS. Use with
+     * `markVerified()` after a successful DNS lookup / scrape (per
+     * `verificationMethod`) to complete the verification flow.
      *
-     * @param publicKeys The signer's public keys (classic Ed25519 + ML-DSA-87)
+     * @param publicKeys The signer's public keys (classic Ed25519 + ML-DSA-87),
+     *                    resolved externally — e.g. by `this.muid`.
      * @returns Verification result with valid/invalid status and optional reason
      *
      * @example
-     *   // After scraping and finding v_code on the page:
-     *   const result = slink.verify(user.publicKeys);
+     *   // After confirming v_code via DNS or page scrape:
+     *   const keys = await resolvePublicKeysForMuid(slink.muid);
+     *   const result = slink.verify(keys);
      *   if (result.valid) {
      *     slink.markVerified();
      *     await db.save(slink);
      *   }
      */
     verify(publicKeys) {
-        const signerKeys = {
-            edPublicKey: publicKeys?.edPublicKey ||
-                base64ToBytes(this.signature.signerEdPublicKey),
-            mlDsaPublicKey: publicKeys?.mlDsaPublicKey ||
-                base64ToBytes(this.signature.signerMlDsaPublicKey),
-            signerId: publicKeys?.signerId || this.signature.signerId,
-        };
-        // Rebuild canonical string from stored parts
         const canonical = buildCanonical(this._subdomain, this._sld, this._tld, this._path);
-        this.signature.validate();
-        // Verify the signature against the canonical URL
-        return MajikSignature.verify(canonical, this._signature, signerKeys);
+        return MajikSignature.verifyCompact(canonical, this._signature, publicKeys);
     }
     // ── Status mutation ───────────────────────────────────────────────────────
     /**
@@ -403,6 +476,8 @@ export class MajikSLink {
             hash: this._hash,
             v_code: this._v_code,
             source: this._source,
+            claim_type: this._claim_type,
+            verification_method: this._verification_method,
             status: this._status,
             timestamp: this._timestamp.toISOString(),
             verified_at: this._verified_at?.toISOString() ?? null,
@@ -411,7 +486,8 @@ export class MajikSLink {
     }
     /**
      * Rehydrate a MajikSLink from a plain JSON object (e.g. from a database row).
-     * Does NOT re-verify the signature — call `verify()` explicitly.
+     * Does NOT re-verify the signature — call `verify()` explicitly with
+     * externally-resolved public keys.
      *
      * @throws {MajikSLinkSerializationError} if any required field is missing or malformed.
      */
@@ -427,10 +503,23 @@ export class MajikSLink {
             assertNonEmptyString(json?.hash, "hash");
             assertNonEmptyString(json?.v_code, "v_code");
             assertNonEmptyString(json?.source, "source");
+            assertNonEmptyString(json?.claim_type, "claim_type");
             assertNonEmptyString(json?.status, "status");
             assertNonEmptyString(json?.timestamp, "timestamp");
+            if (json?.claim_type !== "ownership" &&
+                json?.claim_type !== "attribution" &&
+                json?.claim_type !== "reference") {
+                throw new MajikSLinkSerializationError(`"claim_type" must be "ownership", "attribution", or "reference". Got: ${String(json?.claim_type)}`);
+            }
+            // verification_method is nullable by design — check it's a valid
+            // value rather than asserting non-empty.
+            if (json?.verification_method !== null &&
+                json?.verification_method !== "dns_txt" &&
+                json?.verification_method !== "page_content") {
+                throw new MajikSLinkSerializationError(`"verification_method" must be "dns_txt", "page_content", or null. Got: ${String(json?.verification_method)}`);
+            }
             if (!json?.signature || typeof json.signature !== "object") {
-                throw new MajikSLinkSerializationError('"signature" must be a MajikSignatureJSON object.');
+                throw new MajikSLinkSerializationError('"signature" must be a MajikSignatureCompactJSON object.');
             }
             // Derive sld / tld from stored domain ("youtube.com" → "youtube", "com")
             // Note: This is a simplified approach. For production use with multi-part
@@ -459,6 +548,8 @@ export class MajikSLink {
                 hash: json.hash,
                 v_code: json.v_code,
                 source: json.source,
+                claim_type: json.claim_type,
+                verification_method: json.verification_method,
                 status: json.status,
                 verified_at: json.verified_at ? new Date(json.verified_at) : null,
                 signature: json.signature,
@@ -519,6 +610,7 @@ export class MajikSLink {
             `  user:     ${this._user_id}`,
             `  url:      ${this._clean_url}`,
             `  v_code:   ${this._v_code}`,
+            `  claim:    ${this._claim_type} (${this._verification_method ?? "no verification possible"})`,
             `  status:   ${this._status}`,
             `  source:   ${this._source}`,
             `  signed:   ${this._timestamp.toISOString()}`,
@@ -526,3 +618,7 @@ export class MajikSLink {
         ].join("\n");
     }
 }
+// Freeze static methods
+Object.freeze(MajikSLink);
+// Freeze instance methods
+Object.freeze(MajikSLink.prototype);

package/package.json

@@ -2,7 +2,7 @@
   "name": "@majikah/majik-slink",
   "type": "module",
   "description": "Majik SLink is a specialized TypeScript library designed for URL ownership verification and cryptographic identity linking. It provides a robust mechanism to prove that a specific digital identity (a MajikKey) controls a publicly accessible web resource (such as a YouTube channel, social media profile, or personal blog).",
-  "version": "0.0.2",
+  "version": "0.2.0",
   "license": "Apache-2.0",
   "author": "Zelijah",
   "main": "./dist/index.js",
@@ -41,17 +41,22 @@
     "url": "https://github.com/Majikah/majik-slink/issues"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
     "build": "tsc",
-    "prepublishOnly": "npm run build"
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "package": "npm run build && npm version patch && git push && git push --tags",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "update": "npm i @majikah/majik-key@latest @majikah/majik-signature@latest"
   },
   "dependencies": {
-    "@majikah/majik-key": "^0.2.3",
-    "@majikah/majik-signature": "^0.0.15",
+    "@majikah/majik-key": "^0.4.0",
+    "@majikah/majik-signature": "^0.3.0",
     "@types/psl": "^1.1.3",
     "psl": "^1.15.0"
   },
   "devDependencies": {
-    "@types/node": "^25.5.0"
+    "@types/node": "^26.2.0",
+    "vitest": "^4.1.10"
   }
 }