@storyshelf/auth-password 0.1.0

package/README.md

@@ -0,0 +1,59 @@
+# @storyshelf/auth-password
+
+A shared-password auth adapter for StoryShelf: a single server-wide password gates access, and sessions are HMAC-signed cookies with a 7-day TTL.
+
+## Install
+
+```sh
+nub add @storyshelf/auth-password
+```
+
+or
+
+```sh
+npm install @storyshelf/auth-password
+```
+
+## Quick start
+
+```ts
+import { createPasswordAuth } from "@storyshelf/auth-password";
+import { createShelfRouter } from "@storyshelf/core";
+
+const auth = createPasswordAuth({
+  password: process.env.SHELF_PASSWORD!,
+  secret: process.env.SHELF_SECRET!,
+});
+
+const app = createShelfRouter({ database, storage, auth });
+```
+
+## API
+
+### `PasswordAuthOptions`
+
+```ts
+interface PasswordAuthOptions {
+  password: string; // the shared password users must enter to log in
+  secret: string;   // secret used to HMAC-sign session cookies
+}
+```
+
+### `createPasswordAuth(options: PasswordAuthOptions): PasswordAuth`
+
+Returns a `PasswordAuth`, which extends `AuthAdapter` with an extra method:
+
+```ts
+interface PasswordAuth extends AuthAdapter {
+  login(password: string, user: AuthUser): Promise<string>;
+}
+```
+
+- `login(password, user)` — throws if `password` does not match; otherwise creates an HMAC-signed session cookie string for the given `AuthUser`.
+- `check(request)`, `createSession(user)`, `destroySession(sessionId)` — the standard `AuthAdapter` interface. Sessions last 7 days and are verified with timing-safe comparison.
+
+## How it fits in
+
+`auth-password` is the `auth` option for `createShelfRouter` when you want simple single-password protection for a self-hosted instance. When supplied, the router gates the server-rendered UI behind a login page and signs sessions with the shared secret.
+
+See `docs/architecture.md` and ADR 0008.

package/dist/index.d.mts

@@ -0,0 +1,26 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { AuthAdapter, AuthUser } from "@storyshelf/core/adapter/auth";
+//#region src/index.d.ts
+/** Options for configuring a shared-password auth adapter. */
+interface PasswordAuthOptions {
+  /** The shared password users must present to log in. */
+  password: string;
+  /** Secret used to sign and verify session cookies. */
+  secret: string;
+}
+/** Auth adapter that authenticates with a single shared password. */
+interface PasswordAuth extends AuthAdapter {
+  /** Verify `password` and, if correct, create a session for `user`, returning a session token. */
+  login(password: string, user: AuthUser): Promise<string>;
+}
+/**
+ * Create a shared-password auth adapter.
+ *
+ * @param options - Password and session signing configuration.
+ * @returns A PasswordAuth instance.
+ */
+declare function createPasswordAuth(options: PasswordAuthOptions): PasswordAuth;
+//#endregion
+export { PasswordAuth, PasswordAuthOptions, createPasswordAuth };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,104 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { SESSION_COOKIE } from "@storyshelf/core/adapter/auth";
+import { createHmac, timingSafeEqual } from "node:crypto";
+//#region src/index.ts
+const SESSION_TTL_MS = 6048e5;
+function hmacHex(secret, value) {
+	return createHmac("sha256", secret).update(value).digest("hex");
+}
+function equalStrings(left, right) {
+	const leftBuffer = Buffer.from(left);
+	const rightBuffer = Buffer.from(right);
+	return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
+}
+function encodePayload(payload) {
+	return Buffer.from(JSON.stringify(payload)).toString("base64url");
+}
+function decodePayload(body) {
+	try {
+		return JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
+	} catch {
+		return null;
+	}
+}
+function signPayload(secret, payload) {
+	const body = encodePayload(payload);
+	return `${body}.${hmacHex(secret, body)}`;
+}
+function verifyPayload(secret, token) {
+	const dot = token.lastIndexOf(".");
+	if (dot === -1) return null;
+	const body = token.slice(0, dot);
+	const signature = token.slice(dot + 1);
+	if (!equalStrings(hmacHex(secret, body), signature)) return null;
+	return decodePayload(body);
+}
+function readCookie(request, name) {
+	const header = request.headers.get("cookie");
+	if (!header) return;
+	for (const part of header.split(";")) {
+		const eq = part.indexOf("=");
+		if (eq === -1) continue;
+		if (part.slice(0, eq).trim() === name) return part.slice(eq + 1).trim();
+	}
+}
+function toUser(payload) {
+	return {
+		id: payload.userId,
+		email: payload.email,
+		name: payload.name,
+		avatarUrl: payload.avatarUrl,
+		role: payload.role
+	};
+}
+/**
+* Create a shared-password auth adapter.
+*
+* @param options - Password and session signing configuration.
+* @returns A PasswordAuth instance.
+*/
+function createPasswordAuth(options) {
+	const { password, secret } = options;
+	const check = async (request) => {
+		const token = readCookie(request, SESSION_COOKIE);
+		if (!token) return null;
+		const payload = verifyPayload(secret, token);
+		if (!payload || payload.expiresAt <= Date.now()) return null;
+		return toUser(payload);
+	};
+	const createSession = async (user) => {
+		const payload = {
+			userId: user.id,
+			email: user.email,
+			name: user.name,
+			avatarUrl: user.avatarUrl,
+			role: user.role,
+			expiresAt: Date.now() + SESSION_TTL_MS
+		};
+		return signPayload(secret, payload);
+	};
+	const login = async (input, user) => {
+		if (!equalStrings(input, password)) throw new Error("Invalid password");
+		return await createSession(user);
+	};
+	return {
+		metadata: {
+			name: "Password Auth",
+			version: "0.1.0",
+			description: "Shared-password auth adapter",
+			kind: "password"
+		},
+		check,
+		createSession,
+		async destroySession() {
+			await Promise.resolve();
+		},
+		login
+	};
+}
+//#endregion
+export { createPasswordAuth };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import { SESSION_COOKIE, type AuthAdapter, type AuthUser } from \"@storyshelf/core/adapter/auth\";\nimport { createHmac, timingSafeEqual } from \"node:crypto\";\n\ndeclare const __PKG_VERSION__: string;\n\nconst SESSION_TTL_MS = 7 * 24 * 60 * 60 * 1000;\n\ninterface SessionPayload {\n  userId: string;\n  email: string;\n  name: string;\n  avatarUrl?: string;\n  role: AuthUser[\"role\"];\n  expiresAt: number;\n}\n\n/** Options for configuring a shared-password auth adapter. */\nexport interface PasswordAuthOptions {\n  /** The shared password users must present to log in. */\n  password: string;\n  /** Secret used to sign and verify session cookies. */\n  secret: string;\n}\n\n/** Auth adapter that authenticates with a single shared password. */\nexport interface PasswordAuth extends AuthAdapter {\n  /** Verify `password` and, if correct, create a session for `user`, returning a session token. */\n  login(password: string, user: AuthUser): Promise<string>;\n}\n\nfunction hmacHex(secret: string, value: string): string {\n  return createHmac(\"sha256\", secret).update(value).digest(\"hex\");\n}\n\nfunction equalStrings(left: string, right: string): boolean {\n  const leftBuffer = Buffer.from(left);\n  const rightBuffer = Buffer.from(right);\n  return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);\n}\n\nfunction encodePayload(payload: SessionPayload): string {\n  return Buffer.from(JSON.stringify(payload)).toString(\"base64url\");\n}\n\nfunction decodePayload(body: string): SessionPayload | null {\n  try {\n    return JSON.parse(Buffer.from(body, \"base64url\").toString(\"utf8\")) as SessionPayload;\n  } catch {\n    return null;\n  }\n}\n\nfunction signPayload(secret: string, payload: SessionPayload): string {\n  const body = encodePayload(payload);\n  return `${body}.${hmacHex(secret, body)}`;\n}\n\nfunction verifyPayload(secret: string, token: string): SessionPayload | null {\n  const dot = token.lastIndexOf(\".\");\n  if (dot === -1) {\n    return null;\n  }\n  const body = token.slice(0, dot);\n  const signature = token.slice(dot + 1);\n  if (!equalStrings(hmacHex(secret, body), signature)) {\n    return null;\n  }\n  return decodePayload(body);\n}\n\nfunction readCookie(request: Request, name: string): string | undefined {\n  const header = request.headers.get(\"cookie\");\n  if (!header) {\n    return undefined;\n  }\n  for (const part of header.split(\";\")) {\n    const eq = part.indexOf(\"=\");\n    if (eq === -1) {\n      continue;\n    }\n    if (part.slice(0, eq).trim() === name) {\n      return part.slice(eq + 1).trim();\n    }\n  }\n  return undefined;\n}\n\nfunction toUser(payload: SessionPayload): AuthUser {\n  return {\n    id: payload.userId,\n    email: payload.email,\n    name: payload.name,\n    avatarUrl: payload.avatarUrl,\n    role: payload.role,\n  };\n}\n\n/**\n * Create a shared-password auth adapter.\n *\n * @param options - Password and session signing configuration.\n * @returns A PasswordAuth instance.\n */\nexport function createPasswordAuth(options: PasswordAuthOptions): PasswordAuth {\n  const { password, secret } = options;\n\n  // Async is required by the AuthAdapter interface, though the logic is synchronous.\n  // eslint-disable-next-line require-await\n  const check = async (request: Request): Promise<AuthUser | null> => {\n    const token = readCookie(request, SESSION_COOKIE);\n    if (!token) {\n      return null;\n    }\n    const payload = verifyPayload(secret, token);\n    if (!payload || payload.expiresAt <= Date.now()) {\n      return null;\n    }\n    return toUser(payload);\n  };\n\n  // eslint-disable-next-line require-await\n  const createSession = async (user: AuthUser): Promise<string> => {\n    const payload: SessionPayload = {\n      userId: user.id,\n      email: user.email,\n      name: user.name,\n      avatarUrl: user.avatarUrl,\n      role: user.role,\n      expiresAt: Date.now() + SESSION_TTL_MS,\n    };\n    return signPayload(secret, payload);\n  };\n\n  const login = async (input: string, user: AuthUser): Promise<string> => {\n    if (!equalStrings(input, password)) {\n      throw new Error(\"Invalid password\");\n    }\n    return await createSession(user);\n  };\n\n  return {\n    metadata: {\n      name: \"Password Auth\",\n      version: typeof __PKG_VERSION__ === \"undefined\" ? \"0.0.0\" : __PKG_VERSION__, // oxlint-disable-line unicorn/no-typeof-undefined\n      description: \"Shared-password auth adapter\",\n      kind: \"password\",\n    },\n    check,\n    createSession,\n    async destroySession() {\n      await Promise.resolve();\n    },\n    login,\n  };\n}\n"],"mappings":";;;;;;AAKA,MAAM,iBAAiB;AAyBvB,SAAS,QAAQ,QAAgB,OAAuB;CACtD,OAAO,WAAW,UAAU,MAAM,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,KAAK;AAChE;AAEA,SAAS,aAAa,MAAc,OAAwB;CAC1D,MAAM,aAAa,OAAO,KAAK,IAAI;CACnC,MAAM,cAAc,OAAO,KAAK,KAAK;CACrC,OAAO,WAAW,WAAW,YAAY,UAAU,gBAAgB,YAAY,WAAW;AAC5F;AAEA,SAAS,cAAc,SAAiC;CACtD,OAAO,OAAO,KAAK,KAAK,UAAU,OAAO,CAAC,CAAC,CAAC,SAAS,WAAW;AAClE;AAEA,SAAS,cAAc,MAAqC;CAC1D,IAAI;EACF,OAAO,KAAK,MAAM,OAAO,KAAK,MAAM,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC;CACnE,QAAQ;EACN,OAAO;CACT;AACF;AAEA,SAAS,YAAY,QAAgB,SAAiC;CACpE,MAAM,OAAO,cAAc,OAAO;CAClC,OAAO,GAAG,KAAK,GAAG,QAAQ,QAAQ,IAAI;AACxC;AAEA,SAAS,cAAc,QAAgB,OAAsC;CAC3E,MAAM,MAAM,MAAM,YAAY,GAAG;CACjC,IAAI,QAAQ,IACV,OAAO;CAET,MAAM,OAAO,MAAM,MAAM,GAAG,GAAG;CAC/B,MAAM,YAAY,MAAM,MAAM,MAAM,CAAC;CACrC,IAAI,CAAC,aAAa,QAAQ,QAAQ,IAAI,GAAG,SAAS,GAChD,OAAO;CAET,OAAO,cAAc,IAAI;AAC3B;AAEA,SAAS,WAAW,SAAkB,MAAkC;CACtE,MAAM,SAAS,QAAQ,QAAQ,IAAI,QAAQ;CAC3C,IAAI,CAAC,QACH;CAEF,KAAK,MAAM,QAAQ,OAAO,MAAM,GAAG,GAAG;EACpC,MAAM,KAAK,KAAK,QAAQ,GAAG;EAC3B,IAAI,OAAO,IACT;EAEF,IAAI,KAAK,MAAM,GAAG,EAAE,CAAC,CAAC,KAAK,MAAM,MAC/B,OAAO,KAAK,MAAM,KAAK,CAAC,CAAC,CAAC,KAAK;CAEnC;AAEF;AAEA,SAAS,OAAO,SAAmC;CACjD,OAAO;EACL,IAAI,QAAQ;EACZ,OAAO,QAAQ;EACf,MAAM,QAAQ;EACd,WAAW,QAAQ;EACnB,MAAM,QAAQ;CAChB;AACF;;;;;;;AAQA,SAAgB,mBAAmB,SAA4C;CAC7E,MAAM,EAAE,UAAU,WAAW;CAI7B,MAAM,QAAQ,OAAO,YAA+C;EAClE,MAAM,QAAQ,WAAW,SAAS,cAAc;EAChD,IAAI,CAAC,OACH,OAAO;EAET,MAAM,UAAU,cAAc,QAAQ,KAAK;EAC3C,IAAI,CAAC,WAAW,QAAQ,aAAa,KAAK,IAAI,GAC5C,OAAO;EAET,OAAO,OAAO,OAAO;CACvB;CAGA,MAAM,gBAAgB,OAAO,SAAoC;EAC/D,MAAM,UAA0B;GAC9B,QAAQ,KAAK;GACb,OAAO,KAAK;GACZ,MAAM,KAAK;GACX,WAAW,KAAK;GAChB,MAAM,KAAK;GACX,WAAW,KAAK,IAAI,IAAI;EAC1B;EACA,OAAO,YAAY,QAAQ,OAAO;CACpC;CAEA,MAAM,QAAQ,OAAO,OAAe,SAAoC;EACtE,IAAI,CAAC,aAAa,OAAO,QAAQ,GAC/B,MAAM,IAAI,MAAM,kBAAkB;EAEpC,OAAO,MAAM,cAAc,IAAI;CACjC;CAEA,OAAO;EACL,UAAU;GACR,MAAM;GACN,SAAA;GACA,aAAa;GACb,MAAM;EACR;EACA;EACA;EACA,MAAM,iBAAiB;GACrB,MAAM,QAAQ,QAAQ;EACxB;EACA;CACF;AACF"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@storyshelf/auth-password",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Shared-password auth adapter for StoryShelf.",
+  "author": {
+    "name": "Siddhant Gupta",
+    "url": "https://guptasiddhant.com"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GuptaSiddhant/storyshelf.git",
+    "directory": "packages/auth-password"
+  },
+  "homepage": "https://github.com/GuptaSiddhant/storyshelf#readme",
+  "bugs": {
+    "url": "https://github.com/GuptaSiddhant/storyshelf/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.mjs",
+      "./package.json": "./package.json"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown -w",
+    "fmt": "oxfmt -c ../../.oxfmtrc.json ./src",
+    "lint": "oxlint --type-aware --type-check ./src",
+    "test": "vitest run",
+    "prepublishOnly": "nub run build"
+  },
+  "dependencies": {
+    "@storyshelf/core": "workspace:*",
+    "hono": "^4.11.0"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "@vitest/coverage-v8": "catalog:",
+    "oxfmt": "catalog:",
+    "oxlint": "catalog:",
+    "oxlint-tsgolint": "catalog:",
+    "tsdown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  }
+}