@open-neko/plugin-magic-link 0.3.0

package/dist/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,MAAM,MAAM,aAAa,CAAC;AAEjC,MAAM,mBAAmB,CAAC,MAAM,CAAC,CAAC"}

package/dist/token.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Stateless single-use sign-in tokens.
+ *
+ * The plugin VM keeps no storage between calls, so the token itself
+ * carries everything verification needs: the email it was issued for,
+ * the CSRF state of the browser that requested it, and an expiry —
+ * HMAC-SHA256-signed so none of it can be altered.
+ *
+ * Single-use is enforced by the core, not here: the state cookie is
+ * read-and-cleared on the first callback, and a token only verifies
+ * against the state it was minted for, so a replayed link finds no
+ * matching cookie and dies at the core's login-CSRF check. The same
+ * binding means a link only works in the browser that requested it.
+ */
+export declare const MIN_SECRET_LENGTH = 32;
+export declare const DEFAULT_TTL_SECONDS = 600;
+export declare const MIN_TTL_SECONDS = 60;
+/** The core's state cookie dies at 10 minutes; longer tokens buy nothing. */
+export declare const MAX_TTL_SECONDS = 600;
+export interface TokenClaims {
+    email: string;
+    state: string;
+    expiresAt: number;
+}
+export declare function mintToken(input: {
+    email: string;
+    state: string;
+    secret: string;
+    ttlSeconds?: number;
+    nowMs?: number;
+}): string;
+export declare function clampTtl(ttlSeconds: number | undefined): number;
+/**
+ * Verify signature, expiry, and state binding. Returns the claims or
+ * throws — callers surface the message on the sign-in page, so keep
+ * reasons generic (no oracle for which part failed beyond expiry,
+ * which the user genuinely needs to know to re-request a link).
+ */
+export declare function verifyToken(input: {
+    token: string;
+    state: string;
+    secret: string;
+    nowMs?: number;
+}): TokenClaims;
+//# sourceMappingURL=token.d.ts.map

package/dist/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,eAAO,MAAM,mBAAmB,MAAM,CAAC;AACvC,eAAO,MAAM,eAAe,KAAK,CAAC;AAClC,6EAA6E;AAC7E,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAUD,wBAAgB,SAAS,CAAC,KAAK,EAAE;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,MAAM,CAcT;AAED,wBAAgB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAK/D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,WAAW,CAyCd"}

package/dist/token.js

@@ -0,0 +1,89 @@
+/**
+ * Stateless single-use sign-in tokens.
+ *
+ * The plugin VM keeps no storage between calls, so the token itself
+ * carries everything verification needs: the email it was issued for,
+ * the CSRF state of the browser that requested it, and an expiry —
+ * HMAC-SHA256-signed so none of it can be altered.
+ *
+ * Single-use is enforced by the core, not here: the state cookie is
+ * read-and-cleared on the first callback, and a token only verifies
+ * against the state it was minted for, so a replayed link finds no
+ * matching cookie and dies at the core's login-CSRF check. The same
+ * binding means a link only works in the browser that requested it.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+export const MIN_SECRET_LENGTH = 32;
+export const DEFAULT_TTL_SECONDS = 600;
+export const MIN_TTL_SECONDS = 60;
+/** The core's state cookie dies at 10 minutes; longer tokens buy nothing. */
+export const MAX_TTL_SECONDS = 600;
+function b64url(data) {
+    return Buffer.from(data).toString("base64url");
+}
+function sign(payload, secret) {
+    return createHmac("sha256", secret).update(payload).digest("base64url");
+}
+export function mintToken(input) {
+    if (input.secret.length < MIN_SECRET_LENGTH) {
+        throw new Error(`MAGIC_LINK_SIGNING_SECRET must be at least ${MIN_SECRET_LENGTH} characters`);
+    }
+    const ttl = clampTtl(input.ttlSeconds);
+    const claims = {
+        email: input.email,
+        state: input.state,
+        expiresAt: Math.floor((input.nowMs ?? Date.now()) / 1000) + ttl,
+    };
+    const payload = b64url(JSON.stringify(claims));
+    return `${payload}.${sign(payload, input.secret)}`;
+}
+export function clampTtl(ttlSeconds) {
+    if (ttlSeconds === undefined || Number.isNaN(ttlSeconds)) {
+        return DEFAULT_TTL_SECONDS;
+    }
+    return Math.min(MAX_TTL_SECONDS, Math.max(MIN_TTL_SECONDS, Math.floor(ttlSeconds)));
+}
+/**
+ * Verify signature, expiry, and state binding. Returns the claims or
+ * throws — callers surface the message on the sign-in page, so keep
+ * reasons generic (no oracle for which part failed beyond expiry,
+ * which the user genuinely needs to know to re-request a link).
+ */
+export function verifyToken(input) {
+    const parts = input.token.split(".");
+    if (parts.length !== 2 || !parts[0] || !parts[1]) {
+        throw new Error("this sign-in link is not valid");
+    }
+    const [payload, signature] = parts;
+    const expected = sign(payload, input.secret);
+    const provided = Buffer.from(signature, "base64url");
+    const wanted = Buffer.from(expected, "base64url");
+    if (provided.length !== wanted.length || !timingSafeEqual(provided, wanted)) {
+        throw new Error("this sign-in link is not valid");
+    }
+    let claims;
+    try {
+        const parsed = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+        if (typeof parsed.email !== "string" ||
+            parsed.email.length === 0 ||
+            typeof parsed.state !== "string" ||
+            parsed.state.length === 0 ||
+            typeof parsed.expiresAt !== "number") {
+            throw new Error("malformed claims");
+        }
+        claims = parsed;
+    }
+    catch {
+        throw new Error("this sign-in link is not valid");
+    }
+    if (claims.state !== input.state) {
+        // Wrong browser or a replayed link — the state cookie can't match.
+        throw new Error("this sign-in link must be opened in the browser that requested it");
+    }
+    const now = Math.floor((input.nowMs ?? Date.now()) / 1000);
+    if (claims.expiresAt <= now) {
+        throw new Error("this sign-in link has expired — request a new one");
+    }
+    return claims;
+}
+//# sourceMappingURL=token.js.map

package/dist/token.js.map

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

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@open-neko/plugin-magic-link",
+  "version": "0.3.0",
+  "description": "Passwordless email sign-in for OpenNeko. Implements the auth contract with manual provisioning: an admin creates each user (email + role) in OpenNeko first, and only those users can request a single-use, HMAC-signed sign-in link — possession of a mailbox never mints an account. Delivery via Resend, Postmark, or SendGrid.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/open-neko/plugins.git",
+    "directory": "packages/magic-link"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "openneko": {
+    "runner": "./dist/run.js",
+    "permissions": {
+      "network": [
+        "api.resend.com",
+        "api.postmarkapp.com",
+        "api.sendgrid.com"
+      ],
+      "env": [
+        {
+          "key": "MAGIC_LINK_SIGNING_SECRET",
+          "required": true,
+          "secret": true,
+          "autogenerate": true,
+          "description": "HMAC key that signs each sign-in token. Generated and stored by the host automatically — never prompted, never seen. Deleting the stored value and restarting rotates it, which invalidates every outstanding link."
+        },
+        {
+          "key": "MAGIC_LINK_FROM",
+          "required": true,
+          "secret": false,
+          "description": "From address for the sign-in email, e.g. \"OpenNeko <signin@company.com>\". Must be a sender verified with your email provider."
+        },
+        {
+          "key": "RESEND_API_KEY",
+          "required": false,
+          "secret": true,
+          "description": "Resend API key. Set exactly one of RESEND_API_KEY, POSTMARK_SERVER_TOKEN, or SENDGRID_API_KEY — it selects the delivery provider."
+        },
+        {
+          "key": "POSTMARK_SERVER_TOKEN",
+          "required": false,
+          "secret": true,
+          "description": "Postmark server token. Set exactly one of RESEND_API_KEY, POSTMARK_SERVER_TOKEN, or SENDGRID_API_KEY."
+        },
+        {
+          "key": "SENDGRID_API_KEY",
+          "required": false,
+          "secret": true,
+          "description": "SendGrid API key. Set exactly one of RESEND_API_KEY, POSTMARK_SERVER_TOKEN, or SENDGRID_API_KEY."
+        },
+        {
+          "key": "MAGIC_LINK_TTL_SECONDS",
+          "required": false,
+          "secret": false,
+          "description": "Sign-in link lifetime in seconds, 60–600. Defaults to 600 (10 minutes) — the core's state cookie expires then anyway, so longer values buy nothing."
+        }
+      ]
+    },
+    "capabilities": {
+      "auth": {
+        "providerLabel": "Email link",
+        "provisioning": "manual",
+        "loginHintRequired": true
+      }
+    }
+  },
+  "dependencies": {
+    "@open-neko/plugin-types": "0.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.0",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/bundle.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}