@open-neko/plugin-magic-link 0.3.0

package/dist/plugin.js

@@ -0,0 +1,131 @@
+/**
+ * @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 { definePlugin, } from "@open-neko/plugin-types";
+import { buildSignInEmail, resolveProvider } from "./email.js";
+import { clampTtl, mintToken, MIN_SECRET_LENGTH, verifyToken, } from "./token.js";
+export class MagicLinkPluginError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "MagicLinkPluginError";
+    }
+}
+function resolveEnv() {
+    const secret = process.env.MAGIC_LINK_SIGNING_SECRET ?? "";
+    if (secret.length < MIN_SECRET_LENGTH) {
+        throw new MagicLinkPluginError(`MAGIC_LINK_SIGNING_SECRET must be set to at least ${MIN_SECRET_LENGTH} characters`);
+    }
+    const from = process.env.MAGIC_LINK_FROM?.trim() ?? "";
+    if (!from) {
+        throw new MagicLinkPluginError("MAGIC_LINK_FROM must be set");
+    }
+    const rawTtl = process.env.MAGIC_LINK_TTL_SECONDS;
+    const ttlSeconds = clampTtl(rawTtl ? Number(rawTtl) : undefined);
+    return { secret, from, ttlSeconds };
+}
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+export async function runBeginAuth(params, options = {}) {
+    if (!params.redirectUri) {
+        throw new MagicLinkPluginError("params.redirectUri is required");
+    }
+    if (!params.state) {
+        throw new MagicLinkPluginError("params.state is required");
+    }
+    const email = params.loginHint?.trim().toLowerCase() ?? "";
+    if (!EMAIL_RE.test(email)) {
+        // The core's sign-in page requires the email field
+        // (loginHintRequired), so reaching here means a hand-built request.
+        throw new MagicLinkPluginError("magic link sign-in requires the email address as loginHint");
+    }
+    let callback;
+    try {
+        callback = new URL(params.redirectUri);
+    }
+    catch {
+        throw new MagicLinkPluginError("params.redirectUri must be an absolute URL");
+    }
+    const env = resolveEnv();
+    const token = mintToken({
+        email,
+        state: params.state,
+        secret: env.secret,
+        ttlSeconds: env.ttlSeconds,
+        nowMs: options.nowMs,
+    });
+    const link = new URL(callback.toString());
+    link.searchParams.set("code", token);
+    link.searchParams.set("state", params.state);
+    const send = options.send ?? resolveProvider({
+        resendApiKey: process.env.RESEND_API_KEY,
+        postmarkServerToken: process.env.POSTMARK_SERVER_TOKEN,
+        sendgridApiKey: process.env.SENDGRID_API_KEY,
+    }).send;
+    await send(buildSignInEmail({
+        from: env.from,
+        to: email,
+        link: link.toString(),
+        ttlMinutes: Math.max(1, Math.round(env.ttlSeconds / 60)),
+    }));
+    // No IdP to redirect to — bounce the browser to the sign-in page's
+    // "check your email" notice. The core shows the identical notice when
+    // it drops an unprovisioned email before ever calling us.
+    return {
+        authorizationUrl: `${callback.origin}/signin?notice=link-sent`,
+    };
+}
+export async function runCompleteAuth(params, options = {}) {
+    if (!params.code) {
+        throw new MagicLinkPluginError("params.code is required");
+    }
+    if (!params.state) {
+        throw new MagicLinkPluginError("params.state is required");
+    }
+    const env = resolveEnv();
+    const claims = verifyToken({
+        token: params.code,
+        state: params.state,
+        secret: env.secret,
+        nowMs: options.nowMs,
+    });
+    const identity = {
+        // Deterministic per mailbox so repeat sign-ins hit the same
+        // app_user row via the sub lookup.
+        sub: `magic-link:${claims.email}`,
+        email: claims.email,
+        name: null,
+        orgId: null,
+        // Self-asserted flows must never influence role mapping.
+        groups: [],
+    };
+    return { identity };
+}
+export default definePlugin({
+    name: "@open-neko/plugin-magic-link",
+    version: "0.3.0", // x-release-please-version
+    capabilities: {
+        auth: {
+            providerLabel: "Email link",
+            begin: (params) => runBeginAuth(params),
+            complete: (params) => runCompleteAuth(params),
+        },
+    },
+});
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

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

package/dist/run.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=run.d.ts.map

package/dist/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":""}