@open-neko/plugin-magic-link 0.3.0

package/LICENSE

@@ -0,0 +1,202 @@
+                                 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 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 Support. 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 support.
+
+   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 the work is included on the
+      same line as the file name.
+
+   Copyright 2026 Amit Deshmukh
+
+   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, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. See the License for the specific language governing
+   permissions and limitations under the License.

package/README.md

@@ -0,0 +1,65 @@
+# @open-neko/plugin-magic-link
+
+Passwordless email sign-in for [OpenNeko](https://github.com/open-neko/neko). Implements the generic `auth` contract with **manual provisioning**: an admin creates each user (email + role) in OpenNeko first, and only those users can request a sign-in link. Possession of a mailbox never mints an account — the whole world can know your sign-in URL and still get nowhere.
+
+## Setup — one command, then the browser
+
+```sh
+openneko install @open-neko/plugin-magic-link
+```
+
+That's the only terminal step. The signing secret is generated and stored by the host automatically (`autogenerate` in the manifest) — you are never prompted for it and never see it.
+
+Everything else happens at **Admin → Settings → Email-link sign-in**, a single page with live status:
+
+1. **Email delivery** — pick a provider (Resend, Postmark, or SendGrid), paste its API key once, and set the From address (must be a sender verified with that provider).
+2. **Who can sign in** — add your own email **as admin**, then the rest of your users. There is no invite email; tell people however you like.
+3. **Delivery test** — send yourself a real email through the configured provider to confirm delivery. The test email's link is deliberately unusable; real sign-in happens at `/signin`.
+
+The page's status banner lists exactly what is still missing. **The sign-in gate cannot flip on until every required value is set *and* at least one active admin user exists** — a half-finished setup can never lock you out; the deployment simply stays in single-operator mode.
+
+## How sign-in works
+
+1. A user enters their email at `/signin` and clicks **Email me a sign-in link**.
+2. OpenNeko's core checks the email against provisioned, non-disabled users **before this plugin is ever called**. Unknown emails get the same "check your email" notice and nothing is sent — no account enumeration, no mailbox spam. Delivery failures are masked identically (diagnose via worker logs, or the delivery test).
+3. For known users, the plugin HMAC-signs `{email, state, expiry}` into a token and emails the link. Clicking it lands on OpenNeko's standard auth callback.
+4. `complete_auth` verifies the signature, expiry, and state binding, and returns the identity. The core signs the user in with the role the admin assigned.
+
+## Security properties
+
+| Property | Mechanism |
+|---|---|
+| Only authorized users sign in | Core gate on pre-provisioned users at begin **and** complete (defense in depth) |
+| No lockout window | Gate requires ≥1 active provisioned admin before it can flip on |
+| Single-use links | Core's state cookie is read-and-cleared on first callback; the token is bound to that state |
+| Same-browser only | Same state binding — the emailed link only completes where it was requested |
+| 10-minute expiry | Token `exp` claim (configurable 60–600 s via `MAGIC_LINK_TTL_SECONDS`) + the core's state-cookie TTL |
+| No self-asserted authorization | Identity always carries `groups: []`; roles come from the admin, never the plugin |
+| Instant revocation | Delete the stored `MAGIC_LINK_SIGNING_SECRET` and restart → every outstanding link dies |
+
+## Environment reference
+
+| Key | Required | Set by | Purpose |
+|---|---|---|---|
+| `MAGIC_LINK_SIGNING_SECRET` | yes | **host (auto-generated)** | HMAC key for sign-in tokens |
+| `MAGIC_LINK_FROM` | yes | settings page (or CLI) | From address, e.g. `OpenNeko <signin@company.com>` |
+| `RESEND_API_KEY` | one of three | settings page (or CLI) | selects Resend delivery |
+| `POSTMARK_SERVER_TOKEN` | one of three | settings page (or CLI) | selects Postmark delivery |
+| `SENDGRID_API_KEY` | one of three | settings page (or CLI) | selects SendGrid delivery |
+| `MAGIC_LINK_TTL_SECONDS` | no | CLI | link lifetime, 60–600 (default 600) |
+
+Exactly one provider key may be set — the settings page enforces this by clearing the other two when you save. CLI-inclined operators can use `openneko secrets set @open-neko/plugin-magic-link <KEY>` for any of these instead.
+
+Network egress from the plugin VM is locked to `api.resend.com`, `api.postmarkapp.com`, and `api.sendgrid.com`.
+
+## Switching from an SSO plugin
+
+`app_user.sub` is bound to the previous provider's subject. A magic-link sign-in for the same email will refuse to take over a row with a foreign `sub` — clear the `sub` column for affected users and it attaches fresh on their next sign-in.
+
+## Development
+
+```sh
+pnpm install
+pnpm build       # tsc + esbuild → dist/run.js
+pnpm test        # vitest
+```

package/dist/email.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Sign-in email delivery. Three interchangeable HTTPS providers —
+ * Resend, Postmark, SendGrid — selected by which API-key env var is
+ * set. The VM's egress allowlist covers exactly their API hosts.
+ */
+export interface EmailMessage {
+    from: string;
+    to: string;
+    subject: string;
+    text: string;
+    html: string;
+}
+export type EmailSender = (message: EmailMessage) => Promise<void>;
+export interface ProviderEnv {
+    resendApiKey?: string;
+    postmarkServerToken?: string;
+    sendgridApiKey?: string;
+}
+export declare function resolveProvider(env: ProviderEnv): {
+    name: "resend" | "postmark" | "sendgrid";
+    send: EmailSender;
+};
+/** "Name <addr@x>" → { name, email }; bare address → { email }. */
+export declare function parseFrom(from: string): {
+    email: string;
+    name?: string;
+};
+export declare function buildSignInEmail(input: {
+    from: string;
+    to: string;
+    link: string;
+    ttlMinutes: number;
+}): EmailMessage;
+//# sourceMappingURL=email.d.ts.map

package/dist/email.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.d.ts","sourceRoot":"","sources":["../src/email.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnE,MAAM,WAAW,WAAW;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,WAAW,GAAG;IACjD,IAAI,EAAE,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;IACzC,IAAI,EAAE,WAAW,CAAC;CACnB,CAyBA;AA6ED,mEAAmE;AACnE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAQxE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,YAAY,CAuBf"}

package/dist/email.js

@@ -0,0 +1,190 @@
+/**
+ * Sign-in email delivery. Three interchangeable HTTPS providers —
+ * Resend, Postmark, SendGrid — selected by which API-key env var is
+ * set. The VM's egress allowlist covers exactly their API hosts.
+ */
+export function resolveProvider(env) {
+    const configured = [
+        env.resendApiKey && "resend",
+        env.postmarkServerToken && "postmark",
+        env.sendgridApiKey && "sendgrid",
+    ].filter((value) => Boolean(value));
+    if (configured.length === 0) {
+        throw new Error("no email provider configured — set one of RESEND_API_KEY, POSTMARK_SERVER_TOKEN, or SENDGRID_API_KEY");
+    }
+    if (configured.length > 1) {
+        throw new Error(`multiple email providers configured (${configured.join(", ")}) — set exactly one API key`);
+    }
+    if (env.resendApiKey) {
+        return { name: "resend", send: resendSender(env.resendApiKey) };
+    }
+    if (env.postmarkServerToken) {
+        return { name: "postmark", send: postmarkSender(env.postmarkServerToken) };
+    }
+    return { name: "sendgrid", send: sendgridSender(env.sendgridApiKey) };
+}
+async function expectOk(res, provider) {
+    if (res.ok)
+        return;
+    const body = await res.text().catch(() => "");
+    // Provider errors can echo the recipient address; truncate and pass
+    // through — this surfaces in worker logs only, never to the visitor
+    // (the core masks manual-provisioning begin failures).
+    throw new Error(`${provider} rejected the sign-in email (${res.status}): ${body.slice(0, 300)}`);
+}
+function resendSender(apiKey) {
+    return async (message) => {
+        const res = await fetch("https://api.resend.com/emails", {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                from: message.from,
+                to: [message.to],
+                subject: message.subject,
+                text: message.text,
+                html: message.html,
+            }),
+        });
+        await expectOk(res, "Resend");
+    };
+}
+function postmarkSender(serverToken) {
+    return async (message) => {
+        const res = await fetch("https://api.postmarkapp.com/email", {
+            method: "POST",
+            headers: {
+                "X-Postmark-Server-Token": serverToken,
+                "Content-Type": "application/json",
+                Accept: "application/json",
+            },
+            body: JSON.stringify({
+                From: message.from,
+                To: message.to,
+                Subject: message.subject,
+                TextBody: message.text,
+                HtmlBody: message.html,
+                MessageStream: "outbound",
+            }),
+        });
+        await expectOk(res, "Postmark");
+    };
+}
+function sendgridSender(apiKey) {
+    return async (message) => {
+        const res = await fetch("https://api.sendgrid.com/v3/mail/send", {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                personalizations: [{ to: [{ email: message.to }] }],
+                from: parseFrom(message.from),
+                subject: message.subject,
+                content: [
+                    { type: "text/plain", value: message.text },
+                    { type: "text/html", value: message.html },
+                ],
+            }),
+        });
+        await expectOk(res, "SendGrid");
+    };
+}
+/** "Name <addr@x>" → { name, email }; bare address → { email }. */
+export function parseFrom(from) {
+    const match = /^\s*(.*?)\s*<([^<>\s]+@[^<>\s]+)>\s*$/.exec(from);
+    const email = match?.[2];
+    if (match && email) {
+        const name = (match[1] ?? "").replace(/^"|"$/g, "").trim();
+        return name ? { email, name } : { email };
+    }
+    return { email: from.trim() };
+}
+export function buildSignInEmail(input) {
+    const { to, link, ttlMinutes } = input;
+    return {
+        from: input.from,
+        to,
+        subject: "Your OpenNeko sign-in link",
+        text: [
+            `Sign in to OpenNeko`,
+            ``,
+            `Open this link to sign in as ${to}:`,
+            ``,
+            link,
+            ``,
+            `The link works once and expires in ${ttlMinutes} minutes. Open it in`,
+            `the same browser you requested it from.`,
+            ``,
+            `Someone asked for a sign-in link for this address. If that was not`,
+            `you, ignore this email. Nobody can sign in without the link.`,
+            ``,
+            `OpenNeko · AI that helps run your business.`,
+        ].join("\n"),
+        html: signInHtml({ to, link, ttlMinutes }),
+    };
+}
+/**
+ * Table layout with inline styles, because Gmail and Outlook drop
+ * stylesheets, and system fonts, because they drop web fonts too.
+ */
+function signInHtml(input) {
+    const href = escapeHtml(input.link);
+    const address = escapeHtml(input.to);
+    const minutes = String(input.ttlMinutes);
+    const sans = "-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif";
+    const mono = "ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace";
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<meta name="color-scheme" content="light">
+<meta name="supported-color-schemes" content="light">
+<title>Your OpenNeko sign-in link</title>
+</head>
+<body style="margin:0;padding:0;background:#FAFAF7;">
+<div style="display:none;max-height:0;overflow:hidden;opacity:0;">The link works once and expires in ${minutes} minutes.</div>
+<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="background:#FAFAF7;">
+<tr><td align="center" style="padding:32px 16px;">
+<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="max-width:480px;background:#FFFFFF;border:1px solid #EEEBE4;border-radius:14px;">
+<tr><td style="padding:32px 32px 8px 32px;font-family:${sans};">
+<div style="font-size:15px;font-weight:700;letter-spacing:-0.01em;color:#2D2A24;">OpenNeko</div>
+</td></tr>
+<tr><td style="padding:16px 32px 0 32px;font-family:${sans};">
+<h1 style="margin:0;font-size:22px;line-height:1.3;font-weight:700;letter-spacing:-0.02em;color:#2D2A24;">Sign in to OpenNeko</h1>
+<p style="margin:12px 0 0 0;font-size:15px;line-height:1.55;color:#6F6A60;">Select the button to sign in as <span style="color:#2D2A24;font-weight:600;">${address}</span>.</p>
+</td></tr>
+<tr><td style="padding:24px 32px 0 32px;">
+<table role="presentation" cellpadding="0" cellspacing="0" border="0"><tr>
+<td align="center" bgcolor="#6B5CE7" style="border-radius:10px;">
+<a href="${href}" style="display:inline-block;padding:14px 28px;font-family:${sans};font-size:15px;font-weight:600;color:#FFFFFF;text-decoration:none;border-radius:10px;">Sign in</a>
+</td></tr></table>
+<p style="margin:16px 0 0 0;font-family:${sans};font-size:13px;line-height:1.55;color:#6F6A60;">The link works once and expires in ${minutes} minutes. Open it in the same browser you requested it from.</p>
+</td></tr>
+<tr><td style="padding:24px 32px 0 32px;font-family:${sans};">
+<p style="margin:0 0 8px 0;font-size:13px;color:#6F6A60;">Or paste this link into your browser:</p>
+<div style="padding:12px 14px;background:#F7F4ED;border:1px solid #EEEBE4;border-radius:10px;font-family:${mono};font-size:12px;line-height:1.6;color:#2D2A24;word-break:break-all;">${href}</div>
+</td></tr>
+<tr><td style="padding:24px 32px 32px 32px;font-family:${sans};">
+<div style="height:1px;background:#EEEBE4;font-size:0;line-height:0;">&nbsp;</div>
+<p style="margin:20px 0 0 0;font-size:12px;line-height:1.6;color:#756F65;">Someone asked for a sign-in link for this address. If that was not you, ignore this email. Nobody can sign in without the link.</p>
+<p style="margin:12px 0 0 0;font-size:12px;line-height:1.6;color:#756F65;">OpenNeko · AI that helps run your business.</p>
+</td></tr>
+</table>
+</td></tr>
+</table>
+</body>
+</html>`;
+}
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;");
+}
+//# sourceMappingURL=email.js.map

package/dist/email.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.js","sourceRoot":"","sources":["../src/email.ts"],"names":[],"mappings":"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"}

package/dist/plugin.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @open-neko/plugin-magic-link — passwordless email sign-in.
+ *
+ * Implements OpenNeko's auth contract with `provisioning: "manual"`:
+ * the core only starts this flow for emails an admin pre-provisioned,
+ * and never creates users from it. This plugin's job is narrow —
+ * mint a signed token, email the link, verify the token on callback:
+ *
+ *   begin_auth    → HMAC-sign {email, state, expiry}, email the link
+ *                   `${redirectUri}?code=<token>&state=<state>`, and
+ *                   point the browser at the "check your email" notice.
+ *   complete_auth → verify signature + expiry + state binding, return
+ *                   the identity (groups always empty — role and
+ *                   access assignment is the core's job, and nothing
+ *                   self-asserted should influence it).
+ *
+ * Single-use and same-browser properties come from the core's
+ * read-and-clear state cookie; see token.ts for the exact argument.
+ */
+import { type BeginAuthParams, type BeginAuthResult, type CompleteAuthParams, type CompleteAuthResult } from "@open-neko/plugin-types";
+import { type EmailSender } from "./email.js";
+export declare class MagicLinkPluginError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/** Test seam: inject a fake sender / clock instead of the real ones. */
+export interface InvokeOptions {
+    send?: EmailSender;
+    nowMs?: number;
+}
+export declare function runBeginAuth(params: BeginAuthParams, options?: InvokeOptions): Promise<BeginAuthResult>;
+export declare function runCompleteAuth(params: CompleteAuthParams, options?: InvokeOptions): Promise<CompleteAuthResult>;
+declare const _default: import("@open-neko/plugin-types").PluginDefinition;
+export default _default;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACxB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAqC,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAQjF,qBAAa,oBAAqB,SAAQ,KAAK;aACS,KAAK,CAAC,EAAE,OAAO;gBAAzD,OAAO,EAAE,MAAM,EAA2B,KAAK,CAAC,EAAE,OAAO,YAAA;CAItE;AAED,wEAAwE;AACxE,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA0BD,wBAAsB,YAAY,CAChC,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,eAAe,CAAC,CAwD1B;AAED,wBAAsB,eAAe,CACnC,MAAM,EAAE,kBAAkB,EAC1B,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,kBAAkB,CAAC,CAyB7B;;AAED,wBAUG"}