npm - @emdash-cms/auth - Versions diffs - 0.0.1 - Mend

@emdash-cms/auth 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (48) hide show

package/dist/adapters/kysely.d.mts +62 -0
package/dist/adapters/kysely.d.mts.map +1 -0
package/dist/adapters/kysely.mjs +379 -0
package/dist/adapters/kysely.mjs.map +1 -0
package/dist/authenticate-D5UgaoTH.d.mts +124 -0
package/dist/authenticate-D5UgaoTH.d.mts.map +1 -0
package/dist/authenticate-j5GayLXB.mjs +373 -0
package/dist/authenticate-j5GayLXB.mjs.map +1 -0
package/dist/index.d.mts +444 -0
package/dist/index.d.mts.map +1 -0
package/dist/index.mjs +728 -0
package/dist/index.mjs.map +1 -0
package/dist/oauth/providers/github.d.mts +12 -0
package/dist/oauth/providers/github.d.mts.map +1 -0
package/dist/oauth/providers/github.mjs +55 -0
package/dist/oauth/providers/github.mjs.map +1 -0
package/dist/oauth/providers/google.d.mts +7 -0
package/dist/oauth/providers/google.d.mts.map +1 -0
package/dist/oauth/providers/google.mjs +38 -0
package/dist/oauth/providers/google.mjs.map +1 -0
package/dist/passkey/index.d.mts +2 -0
package/dist/passkey/index.mjs +3 -0
package/dist/types-Bu4irX9A.d.mts +35 -0
package/dist/types-Bu4irX9A.d.mts.map +1 -0
package/dist/types-CiSNpRI9.mjs +60 -0
package/dist/types-CiSNpRI9.mjs.map +1 -0
package/dist/types-HtRc90Wi.d.mts +208 -0
package/dist/types-HtRc90Wi.d.mts.map +1 -0
package/package.json +72 -0
package/src/adapters/kysely.ts +715 -0
package/src/config.ts +214 -0
package/src/index.ts +135 -0
package/src/invite.ts +205 -0
package/src/magic-link/index.ts +150 -0
package/src/oauth/consumer.ts +324 -0
package/src/oauth/providers/github.ts +68 -0
package/src/oauth/providers/google.ts +34 -0
package/src/oauth/types.ts +36 -0
package/src/passkey/authenticate.ts +183 -0
package/src/passkey/index.ts +27 -0
package/src/passkey/register.ts +232 -0
package/src/passkey/types.ts +120 -0
package/src/rbac.test.ts +141 -0
package/src/rbac.ts +205 -0
package/src/signup.ts +210 -0
package/src/tokens.test.ts +141 -0
package/src/tokens.ts +238 -0
package/src/types.ts +352 -0

package/src/signup.ts ADDED Viewed

@@ -0,0 +1,210 @@
+/**
+ * Self-signup for allowed email domains
+ */
+import { escapeHtml } from "./invite.js";
+import { generateTokenWithHash, hashToken } from "./tokens.js";
+import type { AuthAdapter, RoleLevel, EmailMessage, User } from "./types.js";
+const TOKEN_EXPIRY_MS = 15 * 60 * 1000; // 15 minutes
+/** Function that sends an email (matches the EmailPipeline.send signature) */
+export type EmailSendFn = (message: EmailMessage) => Promise<void>;
+/**
+ * Add artificial delay with jitter to prevent timing attacks.
+ * Range approximates the time for token creation + email send.
+ */
+async function timingDelay(): Promise<void> {
+	const delay = 100 + Math.random() * 150; // 100-250ms
+	await new Promise((resolve) => setTimeout(resolve, delay));
+}
+export interface SignupConfig {
+	baseUrl: string;
+	siteName: string;
+	/** Optional email sender. When omitted, signup verification cannot be sent. */
+	email?: EmailSendFn;
+}
+/**
+ * Check if an email domain is allowed for self-signup
+ */
+export async function canSignup(
+	adapter: AuthAdapter,
+	email: string,
+): Promise<{ allowed: boolean; role: RoleLevel } | null> {
+	const domain = email.split("@")[1]?.toLowerCase();
+	if (!domain) return null;
+	const allowedDomain = await adapter.getAllowedDomain(domain);
+	if (!allowedDomain || !allowedDomain.enabled) {
+		return null;
+	}
+	return {
+		allowed: true,
+		role: allowedDomain.defaultRole,
+	};
+}
+/**
+ * Request self-signup (sends verification email).
+ *
+ * Requires `config.email` to be set. Throws if no email sender is configured.
+ */
+export async function requestSignup(
+	config: SignupConfig,
+	adapter: AuthAdapter,
+	email: string,
+): Promise<void> {
+	if (!config.email) {
+		throw new SignupError("email_not_configured", "Email is not configured");
+	}
+	// Check if user already exists
+	const existing = await adapter.getUserByEmail(email);
+	if (existing) {
+		// Don't reveal that user exists - add delay to match successful path timing
+		await timingDelay();
+		return;
+	}
+	// Check if domain is allowed
+	const signup = await canSignup(adapter, email);
+	if (!signup) {
+		// Don't reveal that domain is not allowed - add delay to match successful path timing
+		await timingDelay();
+		return;
+	}
+	// Generate token
+	const { token, hash } = generateTokenWithHash();
+	// Store token with role info
+	await adapter.createToken({
+		hash,
+		email,
+		type: "email_verify",
+		role: signup.role,
+		expiresAt: new Date(Date.now() + TOKEN_EXPIRY_MS),
+	});
+	// Build verification URL
+	const url = new URL("/api/auth/signup/verify", config.baseUrl);
+	url.searchParams.set("token", token);
+	// Send email
+	const safeName = escapeHtml(config.siteName);
+	await config.email({
+		to: email,
+		subject: `Verify your email for ${config.siteName}`,
+		text: `Click this link to verify your email and create your account:\n\n${url.toString()}\n\nThis link expires in 15 minutes.\n\nIf you didn't request this, you can safely ignore this email.`,
+		html: `
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+</head>
+<body style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; line-height: 1.5; color: #333; max-width: 600px; margin: 0 auto; padding: 20px;">
+  <h1 style="font-size: 24px; margin-bottom: 20px;">Verify your email</h1>
+  <p>Click the button below to verify your email and create your ${safeName} account:</p>
+  <p style="margin: 30px 0;">
+    <a href="${url.toString()}" style="background-color: #0066cc; color: white; padding: 12px 24px; text-decoration: none; border-radius: 6px; display: inline-block;">Verify Email</a>
+  </p>
+  <p style="color: #666; font-size: 14px;">This link expires in 15 minutes.</p>
+  <p style="color: #666; font-size: 14px;">If you didn't request this, you can safely ignore this email.</p>
+</body>
+</html>`,
+	});
+}
+/**
+ * Validate a signup verification token
+ */
+export async function validateSignupToken(
+	adapter: AuthAdapter,
+	token: string,
+): Promise<{ email: string; role: RoleLevel }> {
+	const hash = hashToken(token);
+	const authToken = await adapter.getToken(hash, "email_verify");
+	if (!authToken) {
+		throw new SignupError("invalid_token", "Invalid or expired verification link");
+	}
+	if (authToken.expiresAt < new Date()) {
+		await adapter.deleteToken(hash);
+		throw new SignupError("token_expired", "This link has expired");
+	}
+	if (!authToken.email || authToken.role === null) {
+		throw new SignupError("invalid_token", "Invalid token data");
+	}
+	return {
+		email: authToken.email,
+		role: authToken.role,
+	};
+}
+/**
+ * Complete signup process (after passkey registration)
+ */
+export async function completeSignup(
+	adapter: AuthAdapter,
+	token: string,
+	userData: {
+		name?: string;
+		avatarUrl?: string;
+	},
+): Promise<User> {
+	const hash = hashToken(token);
+	// Validate token one more time
+	const authToken = await adapter.getToken(hash, "email_verify");
+	if (!authToken || authToken.expiresAt < new Date()) {
+		throw new SignupError("invalid_token", "Invalid or expired verification");
+	}
+	if (!authToken.email || authToken.role === null) {
+		throw new SignupError("invalid_token", "Invalid token data");
+	}
+	// Check user doesn't already exist
+	const existing = await adapter.getUserByEmail(authToken.email);
+	if (existing) {
+		await adapter.deleteToken(hash);
+		throw new SignupError("user_exists", "An account with this email already exists");
+	}
+	// Delete token (single-use)
+	await adapter.deleteToken(hash);
+	// Create user
+	const user = await adapter.createUser({
+		email: authToken.email,
+		name: userData.name,
+		avatarUrl: userData.avatarUrl,
+		role: authToken.role,
+		emailVerified: true,
+	});
+	return user;
+}
+export class SignupError extends Error {
+	constructor(
+		public code:
+			| "invalid_token"
+			| "token_expired"
+			| "user_exists"
+			| "domain_not_allowed"
+			| "email_not_configured",
+		message: string,
+	) {
+		super(message);
+		this.name = "SignupError";
+	}
+}

package/src/tokens.test.ts ADDED Viewed

@@ -0,0 +1,141 @@
+import { describe, it, expect } from "vitest";
+import {
+	generateToken,
+	hashToken,
+	generateTokenWithHash,
+	generateSessionId,
+	generateAuthSecret,
+	secureCompare,
+	computeS256Challenge,
+	encrypt,
+	decrypt,
+} from "./tokens.js";
+const BASE64URL_REGEX = /^[A-Za-z0-9_-]+$/;
+const NO_PADDING_REGEX = /^[A-Za-z0-9_-]+$/;
+describe("tokens", () => {
+	describe("generateToken", () => {
+		it("generates a base64url-encoded token", () => {
+			const token = generateToken();
+			expect(token).toMatch(BASE64URL_REGEX);
+			// 32 bytes = 43 base64url characters (without padding)
+			expect(token.length).toBe(43);
+		});
+		it("generates unique tokens", () => {
+			// eslint-disable-next-line e18e/prefer-array-fill -- We need unique tokens, not the same token repeated
+			const tokens = new Set(Array.from({ length: 100 }, () => generateToken()));
+			expect(tokens.size).toBe(100);
+		});
+	});
+	describe("hashToken", () => {
+		it("produces consistent hashes", () => {
+			const token = generateToken();
+			const hash1 = hashToken(token);
+			const hash2 = hashToken(token);
+			expect(hash1).toBe(hash2);
+		});
+		it("produces different hashes for different tokens", () => {
+			const token1 = generateToken();
+			const token2 = generateToken();
+			expect(hashToken(token1)).not.toBe(hashToken(token2));
+		});
+	});
+	describe("generateTokenWithHash", () => {
+		it("returns both token and hash", () => {
+			const { token, hash } = generateTokenWithHash();
+			expect(token).toBeDefined();
+			expect(hash).toBeDefined();
+			expect(hashToken(token)).toBe(hash);
+		});
+	});
+	describe("generateSessionId", () => {
+		it("generates a shorter session ID", () => {
+			const sessionId = generateSessionId();
+			expect(sessionId).toMatch(BASE64URL_REGEX);
+			// 20 bytes = 27 base64url characters
+			expect(sessionId.length).toBe(27);
+		});
+	});
+	describe("generateAuthSecret", () => {
+		it("generates a 32-byte secret", () => {
+			const secret = generateAuthSecret();
+			expect(secret).toMatch(BASE64URL_REGEX);
+			expect(secret.length).toBe(43);
+		});
+	});
+	describe("secureCompare", () => {
+		it("returns true for equal strings", () => {
+			expect(secureCompare("hello", "hello")).toBe(true);
+		});
+		it("returns false for different strings", () => {
+			expect(secureCompare("hello", "world")).toBe(false);
+		});
+		it("returns false for different length strings", () => {
+			expect(secureCompare("hello", "hello!")).toBe(false);
+		});
+	});
+	describe("computeS256Challenge", () => {
+		it("produces correct S256 challenge for a known verifier", () => {
+			// RFC 7636 Appendix B test vector:
+			// verifier = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
+			// expected challenge = "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
+			const challenge = computeS256Challenge("dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk");
+			expect(challenge).toBe("E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM");
+		});
+		it("produces base64url output without padding", () => {
+			const challenge = computeS256Challenge("test-verifier-string");
+			expect(challenge).toMatch(NO_PADDING_REGEX);
+			expect(challenge).not.toContain("=");
+		});
+		it("is deterministic", () => {
+			const a = computeS256Challenge("same-input");
+			const b = computeS256Challenge("same-input");
+			expect(a).toBe(b);
+		});
+		it("produces different output for different input", () => {
+			const a = computeS256Challenge("verifier-one");
+			const b = computeS256Challenge("verifier-two");
+			expect(a).not.toBe(b);
+		});
+	});
+	describe("encrypt/decrypt", () => {
+		const secret = generateAuthSecret();
+		it("encrypts and decrypts a string", async () => {
+			const plaintext = "my-secret-value";
+			const encrypted = await encrypt(plaintext, secret);
+			const decrypted = await decrypt(encrypted, secret);
+			expect(decrypted).toBe(plaintext);
+		});
+		it("produces different ciphertext each time (due to random IV)", async () => {
+			const plaintext = "my-secret-value";
+			const encrypted1 = await encrypt(plaintext, secret);
+			const encrypted2 = await encrypt(plaintext, secret);
+			expect(encrypted1).not.toBe(encrypted2);
+		});
+		it("fails to decrypt with wrong secret", async () => {
+			const plaintext = "my-secret-value";
+			const encrypted = await encrypt(plaintext, secret);
+			const wrongSecret = generateAuthSecret();
+			await expect(decrypt(encrypted, wrongSecret)).rejects.toThrow();
+		});
+	});
+});

package/src/tokens.ts ADDED Viewed

@@ -0,0 +1,238 @@
+/**
+ * Secure token utilities
+ *
+ * Crypto via Oslo.js (@oslojs/crypto). Base64url via @oslojs/encoding.
+ *
+ * Tokens are opaque random values. We store only the SHA-256 hash in the database.
+ */
+import { sha256 } from "@oslojs/crypto/sha2";
+import { encodeBase64urlNoPadding, decodeBase64urlIgnorePadding } from "@oslojs/encoding";
+const TOKEN_BYTES = 32; // 256 bits of entropy
+// ---------------------------------------------------------------------------
+// API Token Prefixes
+// ---------------------------------------------------------------------------
+/** Valid API token prefixes */
+export const TOKEN_PREFIXES = {
+	PAT: "ec_pat_",
+	OAUTH_ACCESS: "ec_oat_",
+	OAUTH_REFRESH: "ec_ort_",
+} as const;
+// ---------------------------------------------------------------------------
+// Scopes
+// ---------------------------------------------------------------------------
+/** All valid API token scopes */
+export const VALID_SCOPES = [
+	"content:read",
+	"content:write",
+	"media:read",
+	"media:write",
+	"schema:read",
+	"schema:write",
+	"admin",
+] as const;
+export type ApiTokenScope = (typeof VALID_SCOPES)[number];
+/**
+ * Validate that scopes are all valid.
+ * Returns the invalid scopes, or empty array if all valid.
+ */
+export function validateScopes(scopes: string[]): string[] {
+	const validSet = new Set<string>(VALID_SCOPES);
+	return scopes.filter((s) => !validSet.has(s));
+}
+/**
+ * Check if a set of scopes includes a required scope.
+ * The `admin` scope grants access to everything.
+ */
+export function hasScope(scopes: string[], required: string): boolean {
+	if (scopes.includes("admin")) return true;
+	return scopes.includes(required);
+}
+/**
+ * Generate a cryptographically secure random token
+ * Returns base64url-encoded string (URL-safe)
+ */
+export function generateToken(): string {
+	const bytes = new Uint8Array(TOKEN_BYTES);
+	crypto.getRandomValues(bytes);
+	return encodeBase64urlNoPadding(bytes);
+}
+/**
+ * Hash a token for storage
+ * We never store raw tokens - only their SHA-256 hash
+ */
+export function hashToken(token: string): string {
+	const bytes = decodeBase64urlIgnorePadding(token);
+	const hash = sha256(bytes);
+	return encodeBase64urlNoPadding(hash);
+}
+/**
+ * Generate a token and its hash together
+ */
+export function generateTokenWithHash(): { token: string; hash: string } {
+	const token = generateToken();
+	const hash = hashToken(token);
+	return { token, hash };
+}
+/**
+ * Generate a session ID (shorter, for cookie storage)
+ */
+export function generateSessionId(): string {
+	const bytes = new Uint8Array(20); // 160 bits
+	crypto.getRandomValues(bytes);
+	return encodeBase64urlNoPadding(bytes);
+}
+/**
+ * Generate an auth secret for configuration
+ */
+export function generateAuthSecret(): string {
+	const bytes = new Uint8Array(32);
+	crypto.getRandomValues(bytes);
+	return encodeBase64urlNoPadding(bytes);
+}
+// ---------------------------------------------------------------------------
+// Prefixed API tokens (ec_pat_, ec_oat_, ec_ort_)
+// ---------------------------------------------------------------------------
+/**
+ * Generate a prefixed API token and its hash.
+ * Returns the raw token (shown once to the user), the hash (stored server-side),
+ * and a display prefix (for identification in UIs/logs).
+ *
+ * Uses oslo/crypto for SHA-256 hashing.
+ */
+export function generatePrefixedToken(prefix: string): {
+	raw: string;
+	hash: string;
+	prefix: string;
+} {
+	const bytes = new Uint8Array(TOKEN_BYTES);
+	crypto.getRandomValues(bytes);
+	const encoded = encodeBase64urlNoPadding(bytes);
+	const raw = `${prefix}${encoded}`;
+	const hash = hashPrefixedToken(raw);
+	// First few chars for identification in UIs
+	const displayPrefix = raw.slice(0, prefix.length + 4);
+	return { raw, hash, prefix: displayPrefix };
+}
+/**
+ * Hash a prefixed API token for storage/lookup.
+ * Hashes the full prefixed token string via SHA-256, returns base64url (no padding).
+ */
+export function hashPrefixedToken(token: string): string {
+	const bytes = new TextEncoder().encode(token);
+	const hash = sha256(bytes);
+	return encodeBase64urlNoPadding(hash);
+}
+// ---------------------------------------------------------------------------
+// PKCE (RFC 7636) — server-side verification
+// ---------------------------------------------------------------------------
+/**
+ * Compute an S256 PKCE code challenge from a code verifier.
+ * Used server-side to verify that code_verifier matches the stored code_challenge.
+ *
+ * Equivalent to: BASE64URL(SHA256(ASCII(code_verifier)))
+ */
+export function computeS256Challenge(codeVerifier: string): string {
+	const hash = sha256(new TextEncoder().encode(codeVerifier));
+	return encodeBase64urlNoPadding(hash);
+}
+/**
+ * Constant-time comparison to prevent timing attacks
+ */
+export function secureCompare(a: string, b: string): boolean {
+	if (a.length !== b.length) return false;
+	const aBytes = new TextEncoder().encode(a);
+	const bBytes = new TextEncoder().encode(b);
+	let result = 0;
+	for (let i = 0; i < aBytes.length; i++) {
+		result |= aBytes[i]! ^ bBytes[i]!;
+	}
+	return result === 0;
+}
+// ============================================================================
+// Encryption utilities (for storing OAuth secrets)
+// ============================================================================
+const ALGORITHM = "AES-GCM";
+const IV_BYTES = 12;
+/**
+ * Derive an encryption key from the auth secret
+ */
+async function deriveKey(secret: string): Promise<CryptoKey> {
+	const decoded = decodeBase64urlIgnorePadding(secret);
+	// Create a new ArrayBuffer to ensure compatibility with crypto.subtle
+	const buffer = new Uint8Array(decoded).buffer;
+	const keyMaterial = await crypto.subtle.importKey("raw", buffer, "PBKDF2", false, ["deriveKey"]);
+	return crypto.subtle.deriveKey(
+		{
+			name: "PBKDF2",
+			salt: new TextEncoder().encode("emdash-auth-v1"),
+			iterations: 100000,
+			hash: "SHA-256",
+		},
+		keyMaterial,
+		{ name: ALGORITHM, length: 256 },
+		false,
+		["encrypt", "decrypt"],
+	);
+}
+/**
+ * Encrypt a value using AES-GCM
+ */
+export async function encrypt(plaintext: string, secret: string): Promise<string> {
+	const key = await deriveKey(secret);
+	const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES));
+	const encoded = new TextEncoder().encode(plaintext);
+	const ciphertext = await crypto.subtle.encrypt({ name: ALGORITHM, iv }, key, encoded);
+	// Prepend IV to ciphertext
+	const combined = new Uint8Array(iv.length + ciphertext.byteLength);
+	combined.set(iv);
+	combined.set(new Uint8Array(ciphertext), iv.length);
+	return encodeBase64urlNoPadding(combined);
+}
+/**
+ * Decrypt a value encrypted with encrypt()
+ */
+export async function decrypt(encrypted: string, secret: string): Promise<string> {
+	const key = await deriveKey(secret);
+	const combined = decodeBase64urlIgnorePadding(encrypted);
+	const iv = combined.slice(0, IV_BYTES);
+	const ciphertext = combined.slice(IV_BYTES);
+	const decrypted = await crypto.subtle.decrypt({ name: ALGORITHM, iv }, key, ciphertext);
+	return new TextDecoder().decode(decrypted);
+}