@emdash-cms/auth 0.0.1

package/src/passkey/register.ts

@@ -0,0 +1,232 @@
+/**
+ * Passkey registration (credential creation)
+ *
+ * Based on oslo webauthn documentation:
+ * https://webauthn.oslojs.dev/examples/registration
+ */
+
+import { ECDSAPublicKey, p256 } from "@oslojs/crypto/ecdsa";
+import { encodeBase64urlNoPadding, decodeBase64urlIgnorePadding } from "@oslojs/encoding";
+import {
+	parseAttestationObject,
+	parseClientDataJSON,
+	coseAlgorithmES256,
+	coseAlgorithmRS256,
+	coseEllipticCurveP256,
+	ClientDataType,
+	AttestationStatementFormat,
+	COSEKeyType,
+} from "@oslojs/webauthn";
+
+import { generateToken } from "../tokens.js";
+import type { Credential, NewCredential, AuthAdapter, User, DeviceType } from "../types.js";
+import type {
+	RegistrationOptions,
+	RegistrationResponse,
+	VerifiedRegistration,
+	ChallengeStore,
+	PasskeyConfig,
+} from "./types.js";
+
+const CHALLENGE_TTL = 5 * 60 * 1000; // 5 minutes
+
+export type { PasskeyConfig };
+
+/**
+ * Generate registration options for creating a new passkey
+ */
+export async function generateRegistrationOptions(
+	config: PasskeyConfig,
+	user: Pick<User, "id" | "email" | "name">,
+	existingCredentials: Credential[],
+	challengeStore: ChallengeStore,
+): Promise<RegistrationOptions> {
+	const challenge = generateToken();
+
+	// Store challenge for verification
+	await challengeStore.set(challenge, {
+		type: "registration",
+		userId: user.id,
+		expiresAt: Date.now() + CHALLENGE_TTL,
+	});
+
+	// Encode user ID as base64url
+	const userIdBytes = new TextEncoder().encode(user.id);
+	const userIdEncoded = encodeBase64urlNoPadding(userIdBytes);
+
+	return {
+		challenge,
+		rp: {
+			name: config.rpName,
+			id: config.rpId,
+		},
+		user: {
+			id: userIdEncoded,
+			name: user.email,
+			displayName: user.name || user.email,
+		},
+		pubKeyCredParams: [
+			{ type: "public-key", alg: coseAlgorithmES256 }, // ES256 (-7)
+			{ type: "public-key", alg: coseAlgorithmRS256 }, // RS256 (-257)
+		],
+		timeout: 60000,
+		attestation: "none", // We don't need attestation for our use case
+		authenticatorSelection: {
+			residentKey: "preferred", // Allow discoverable credentials
+			userVerification: "preferred",
+		},
+		excludeCredentials: existingCredentials.map((cred) => ({
+			type: "public-key" as const,
+			id: cred.id,
+			transports: cred.transports,
+		})),
+	};
+}
+
+/**
+ * Verify a registration response and extract credential data
+ */
+export async function verifyRegistrationResponse(
+	config: PasskeyConfig,
+	response: RegistrationResponse,
+	challengeStore: ChallengeStore,
+): Promise<VerifiedRegistration> {
+	// Decode the response
+	const clientDataJSON = decodeBase64urlIgnorePadding(response.response.clientDataJSON);
+	const attestationObject = decodeBase64urlIgnorePadding(response.response.attestationObject);
+
+	// Parse client data
+	const clientData = parseClientDataJSON(clientDataJSON);
+
+	// Verify client data
+	if (clientData.type !== ClientDataType.Create) {
+		throw new Error("Invalid client data type");
+	}
+
+	// Verify challenge - convert Uint8Array back to base64url string (no padding, matching stored format)
+	const challengeString = encodeBase64urlNoPadding(clientData.challenge);
+	const challengeData = await challengeStore.get(challengeString);
+	if (!challengeData) {
+		throw new Error("Challenge not found or expired");
+	}
+	if (challengeData.type !== "registration") {
+		throw new Error("Invalid challenge type");
+	}
+	if (challengeData.expiresAt < Date.now()) {
+		await challengeStore.delete(challengeString);
+		throw new Error("Challenge expired");
+	}
+
+	// Delete challenge (single-use)
+	await challengeStore.delete(challengeString);
+
+	// Verify origin
+	if (clientData.origin !== config.origin) {
+		throw new Error(`Invalid origin: expected ${config.origin}, got ${clientData.origin}`);
+	}
+
+	// Parse attestation object
+	const attestation = parseAttestationObject(attestationObject);
+
+	// We only support 'none' attestation for simplicity
+	if (attestation.attestationStatement.format !== AttestationStatementFormat.None) {
+		// For other formats, we'd need to verify the attestation statement
+		// For now, we just ignore it and trust the credential
+	}
+
+	const { authenticatorData } = attestation;
+
+	// Verify RP ID hash
+	if (!authenticatorData.verifyRelyingPartyIdHash(config.rpId)) {
+		throw new Error("Invalid RP ID hash");
+	}
+
+	// Verify flags
+	if (!authenticatorData.userPresent) {
+		throw new Error("User presence not verified");
+	}
+
+	// Extract credential data
+	if (!authenticatorData.credential) {
+		throw new Error("No credential data in attestation");
+	}
+
+	const { credential } = authenticatorData;
+
+	// Verify algorithm is supported and encode public key
+	// Currently only supporting ES256 (ECDSA with P-256)
+	const algorithm = credential.publicKey.algorithm();
+	let encodedPublicKey: Uint8Array;
+
+	if (algorithm === coseAlgorithmES256) {
+		// Verify it's EC2 key type
+		if (credential.publicKey.type() !== COSEKeyType.EC2) {
+			throw new Error("Expected EC2 key type for ES256");
+		}
+		const cosePublicKey = credential.publicKey.ec2();
+		if (cosePublicKey.curve !== coseEllipticCurveP256) {
+			throw new Error("Expected P-256 curve for ES256");
+		}
+		// Encode as SEC1 uncompressed format for storage
+		encodedPublicKey = new ECDSAPublicKey(
+			p256,
+			cosePublicKey.x,
+			cosePublicKey.y,
+		).encodeSEC1Uncompressed();
+	} else if (algorithm === coseAlgorithmRS256) {
+		// RSA is less common for passkeys, skip for now
+		throw new Error("RS256 not yet supported - please use ES256");
+	} else {
+		throw new Error(`Unsupported algorithm: ${algorithm}`);
+	}
+
+	// Determine device type and backup status
+	// Note: oslo webauthn doesn't expose backup flags, so we default to singleDevice
+	// In practice, most modern passkeys are multi-device (e.g., iCloud Keychain, Google Password Manager)
+	const deviceType: DeviceType = "singleDevice";
+	const backedUp = false;
+
+	return {
+		credentialId: response.id,
+		publicKey: encodedPublicKey,
+		counter: authenticatorData.signatureCounter,
+		deviceType,
+		backedUp,
+		transports: response.response.transports ?? [],
+	};
+}
+
+/**
+ * Register a new passkey for a user
+ */
+export async function registerPasskey(
+	adapter: AuthAdapter,
+	userId: string,
+	verified: VerifiedRegistration,
+	name?: string,
+): Promise<Credential> {
+	// Check credential limit
+	const count = await adapter.countCredentialsByUserId(userId);
+	if (count >= 10) {
+		throw new Error("Maximum number of passkeys reached (10)");
+	}
+
+	// Check if credential already exists
+	const existing = await adapter.getCredentialById(verified.credentialId);
+	if (existing) {
+		throw new Error("Credential already registered");
+	}
+
+	const newCredential: NewCredential = {
+		id: verified.credentialId,
+		userId,
+		publicKey: verified.publicKey,
+		counter: verified.counter,
+		deviceType: verified.deviceType,
+		backedUp: verified.backedUp,
+		transports: verified.transports,
+		name,
+	};
+
+	return adapter.createCredential(newCredential);
+}

package/src/passkey/types.ts

@@ -0,0 +1,120 @@
+/**
+ * WebAuthn types for passkey authentication
+ */
+
+import type { AuthenticatorTransport, DeviceType } from "../types.js";
+
+// ============================================================================
+// Registration (Creating a new passkey)
+// ============================================================================
+
+export interface RegistrationOptions {
+	challenge: string; // Base64url encoded
+	rp: {
+		name: string;
+		id: string;
+	};
+	user: {
+		id: string; // Base64url encoded user ID
+		name: string;
+		displayName: string;
+	};
+	pubKeyCredParams: Array<{
+		type: "public-key";
+		alg: number; // COSE algorithm identifier
+	}>;
+	timeout?: number;
+	attestation?: "none" | "indirect" | "direct";
+	authenticatorSelection?: {
+		authenticatorAttachment?: "platform" | "cross-platform";
+		residentKey?: "discouraged" | "preferred" | "required";
+		requireResidentKey?: boolean;
+		userVerification?: "discouraged" | "preferred" | "required";
+	};
+	excludeCredentials?: Array<{
+		type: "public-key";
+		id: string; // Base64url encoded credential ID
+		transports?: AuthenticatorTransport[];
+	}>;
+}
+
+export interface RegistrationResponse {
+	id: string; // Base64url credential ID
+	rawId: string; // Base64url
+	type: "public-key";
+	response: {
+		clientDataJSON: string; // Base64url
+		attestationObject: string; // Base64url
+		transports?: AuthenticatorTransport[];
+	};
+	authenticatorAttachment?: "platform" | "cross-platform";
+}
+
+export interface VerifiedRegistration {
+	credentialId: string;
+	publicKey: Uint8Array;
+	counter: number;
+	deviceType: DeviceType;
+	backedUp: boolean;
+	transports: AuthenticatorTransport[];
+}
+
+// ============================================================================
+// Authentication (Using an existing passkey)
+// ============================================================================
+
+export interface AuthenticationOptions {
+	challenge: string; // Base64url encoded
+	rpId: string;
+	timeout?: number;
+	userVerification?: "discouraged" | "preferred" | "required";
+	allowCredentials?: Array<{
+		type: "public-key";
+		id: string; // Base64url encoded credential ID
+		transports?: AuthenticatorTransport[];
+	}>;
+}
+
+export interface AuthenticationResponse {
+	id: string; // Base64url credential ID
+	rawId: string; // Base64url
+	type: "public-key";
+	response: {
+		clientDataJSON: string; // Base64url
+		authenticatorData: string; // Base64url
+		signature: string; // Base64url
+		userHandle?: string; // Base64url (user ID)
+	};
+	authenticatorAttachment?: "platform" | "cross-platform";
+}
+
+export interface VerifiedAuthentication {
+	credentialId: string;
+	newCounter: number;
+}
+
+// ============================================================================
+// Challenge storage
+// ============================================================================
+
+export interface ChallengeStore {
+	set(challenge: string, data: ChallengeData): Promise<void>;
+	get(challenge: string): Promise<ChallengeData | null>;
+	delete(challenge: string): Promise<void>;
+}
+
+export interface ChallengeData {
+	type: "registration" | "authentication";
+	userId?: string; // For registration, the user being registered
+	expiresAt: number;
+}
+
+// ============================================================================
+// Passkey Configuration
+// ============================================================================
+
+export interface PasskeyConfig {
+	rpName: string;
+	rpId: string;
+	origin: string;
+}

package/src/rbac.test.ts

@@ -0,0 +1,141 @@
+import { describe, it, expect } from "vitest";
+
+import {
+	hasPermission,
+	requirePermission,
+	canActOnOwn,
+	requirePermissionOnResource,
+	PermissionError,
+} from "./rbac.js";
+import { Role } from "./types.js";
+
+describe("rbac", () => {
+	describe("hasPermission", () => {
+		it("returns false for null user", () => {
+			expect(hasPermission(null, "content:read")).toBe(false);
+		});
+
+		it("returns false for undefined user", () => {
+			expect(hasPermission(undefined, "content:read")).toBe(false);
+		});
+
+		it("allows subscriber to read content", () => {
+			expect(hasPermission({ role: Role.SUBSCRIBER }, "content:read")).toBe(true);
+		});
+
+		it("denies subscriber from creating content", () => {
+			expect(hasPermission({ role: Role.SUBSCRIBER }, "content:create")).toBe(false);
+		});
+
+		it("allows contributor to create content", () => {
+			expect(hasPermission({ role: Role.CONTRIBUTOR }, "content:create")).toBe(true);
+		});
+
+		it("allows admin to do anything", () => {
+			const admin = { role: Role.ADMIN };
+			expect(hasPermission(admin, "content:read")).toBe(true);
+			expect(hasPermission(admin, "content:create")).toBe(true);
+			expect(hasPermission(admin, "users:manage")).toBe(true);
+			expect(hasPermission(admin, "schema:manage")).toBe(true);
+		});
+
+		it("denies editor from managing users", () => {
+			expect(hasPermission({ role: Role.EDITOR }, "users:manage")).toBe(false);
+		});
+
+		it("allows author to edit own media", () => {
+			expect(hasPermission({ role: Role.AUTHOR }, "media:edit_own")).toBe(true);
+		});
+
+		it("denies contributor from editing media", () => {
+			expect(hasPermission({ role: Role.CONTRIBUTOR }, "media:edit_own")).toBe(false);
+		});
+
+		it("allows editor to edit any media", () => {
+			expect(hasPermission({ role: Role.EDITOR }, "media:edit_any")).toBe(true);
+		});
+
+		it("denies author from editing any media", () => {
+			expect(hasPermission({ role: Role.AUTHOR }, "media:edit_any")).toBe(false);
+		});
+	});
+
+	describe("requirePermission", () => {
+		it("throws for null user", () => {
+			expect(() => requirePermission(null, "content:read")).toThrow(PermissionError);
+		});
+
+		it("throws unauthorized for missing user", () => {
+			try {
+				requirePermission(null, "content:read");
+			} catch (e) {
+				expect(e).toBeInstanceOf(PermissionError);
+				expect((e as PermissionError).code).toBe("unauthorized");
+			}
+		});
+
+		it("throws forbidden for insufficient permissions", () => {
+			try {
+				requirePermission({ role: Role.SUBSCRIBER }, "content:create");
+			} catch (e) {
+				expect(e).toBeInstanceOf(PermissionError);
+				expect((e as PermissionError).code).toBe("forbidden");
+			}
+		});
+
+		it("does not throw for sufficient permissions", () => {
+			expect(() => requirePermission({ role: Role.ADMIN }, "content:create")).not.toThrow();
+		});
+	});
+
+	describe("canActOnOwn", () => {
+		const user = { role: Role.AUTHOR, id: "user-1" };
+
+		it("allows action on own resource with own permission", () => {
+			expect(canActOnOwn(user, "user-1", "content:edit_own", "content:edit_any")).toBe(true);
+		});
+
+		it("denies action on others resource without any permission", () => {
+			expect(canActOnOwn(user, "user-2", "content:edit_own", "content:edit_any")).toBe(false);
+		});
+
+		it("allows editor to edit any resource", () => {
+			const editor = { role: Role.EDITOR, id: "editor-1" };
+			expect(canActOnOwn(editor, "user-2", "content:edit_own", "content:edit_any")).toBe(true);
+		});
+
+		it("allows author to edit own media", () => {
+			expect(canActOnOwn(user, "user-1", "media:edit_own", "media:edit_any")).toBe(true);
+		});
+
+		it("denies author from editing others media", () => {
+			expect(canActOnOwn(user, "user-2", "media:edit_own", "media:edit_any")).toBe(false);
+		});
+
+		it("denies contributor from editing any media (including own)", () => {
+			const contributor = { role: Role.CONTRIBUTOR, id: "contrib-1" };
+			expect(canActOnOwn(contributor, "contrib-1", "media:edit_own", "media:edit_any")).toBe(false);
+		});
+
+		it("allows editor to edit any media", () => {
+			const editor = { role: Role.EDITOR, id: "editor-1" };
+			expect(canActOnOwn(editor, "user-2", "media:edit_own", "media:edit_any")).toBe(true);
+		});
+	});
+
+	describe("requirePermissionOnResource", () => {
+		it("allows author to edit own content", () => {
+			const user = { role: Role.AUTHOR, id: "user-1" };
+			expect(() =>
+				requirePermissionOnResource(user, "user-1", "content:edit_own", "content:edit_any"),
+			).not.toThrow();
+		});
+
+		it("throws for author editing others content", () => {
+			const user = { role: Role.AUTHOR, id: "user-1" };
+			expect(() =>
+				requirePermissionOnResource(user, "user-2", "content:edit_own", "content:edit_any"),
+			).toThrow(PermissionError);
+		});
+	});
+});

package/src/rbac.ts

@@ -0,0 +1,205 @@
+/**
+ * Role-Based Access Control
+ */
+
+import type { ApiTokenScope } from "./tokens.js";
+import { Role, type RoleLevel } from "./types.js";
+
+/**
+ * Permission definitions with minimum role required
+ */
+export const Permissions = {
+	// Content
+	"content:read": Role.SUBSCRIBER,
+	"content:create": Role.CONTRIBUTOR,
+	"content:edit_own": Role.AUTHOR,
+	"content:edit_any": Role.EDITOR,
+	"content:delete_own": Role.AUTHOR,
+	"content:delete_any": Role.EDITOR,
+	"content:publish_own": Role.AUTHOR,
+	"content:publish_any": Role.EDITOR,
+
+	// Media
+	"media:read": Role.SUBSCRIBER,
+	"media:upload": Role.CONTRIBUTOR,
+	"media:edit_own": Role.AUTHOR,
+	"media:edit_any": Role.EDITOR,
+	"media:delete_own": Role.AUTHOR,
+	"media:delete_any": Role.EDITOR,
+
+	// Taxonomies
+	"taxonomies:read": Role.SUBSCRIBER,
+	"taxonomies:manage": Role.EDITOR,
+
+	// Comments
+	"comments:read": Role.SUBSCRIBER,
+	"comments:moderate": Role.EDITOR,
+	"comments:delete": Role.ADMIN,
+	"comments:settings": Role.ADMIN,
+
+	// Menus
+	"menus:read": Role.SUBSCRIBER,
+	"menus:manage": Role.EDITOR,
+
+	// Widgets
+	"widgets:read": Role.SUBSCRIBER,
+	"widgets:manage": Role.EDITOR,
+
+	// Sections
+	"sections:read": Role.SUBSCRIBER,
+	"sections:manage": Role.EDITOR,
+
+	// Redirects
+	"redirects:read": Role.EDITOR,
+	"redirects:manage": Role.ADMIN,
+
+	// Users
+	"users:read": Role.ADMIN,
+	"users:invite": Role.ADMIN,
+	"users:manage": Role.ADMIN,
+
+	// Settings
+	"settings:read": Role.EDITOR,
+	"settings:manage": Role.ADMIN,
+
+	// Schema (content types)
+	"schema:read": Role.EDITOR,
+	"schema:manage": Role.ADMIN,
+
+	// Plugins
+	"plugins:read": Role.EDITOR,
+	"plugins:manage": Role.ADMIN,
+
+	// Import
+	"import:execute": Role.ADMIN,
+
+	// Search
+	"search:read": Role.SUBSCRIBER,
+	"search:manage": Role.ADMIN,
+
+	// Auth
+	"auth:manage_own_credentials": Role.SUBSCRIBER,
+	"auth:manage_connections": Role.ADMIN,
+} as const;
+
+export type Permission = keyof typeof Permissions;
+
+/**
+ * Check if a user has a specific permission
+ */
+export function hasPermission(
+	user: { role: RoleLevel } | null | undefined,
+	permission: Permission,
+): boolean {
+	if (!user) return false;
+	return user.role >= Permissions[permission];
+}
+
+/**
+ * Require a permission, throwing if not met
+ */
+export function requirePermission(
+	user: { role: RoleLevel } | null | undefined,
+	permission: Permission,
+): asserts user is { role: RoleLevel } {
+	if (!user) {
+		throw new PermissionError("unauthorized", "Authentication required");
+	}
+	if (!hasPermission(user, permission)) {
+		throw new PermissionError("forbidden", `Missing permission: ${permission}`);
+	}
+}
+
+/**
+ * Check if user can perform action on a resource they own
+ */
+export function canActOnOwn(
+	user: { role: RoleLevel; id: string } | null | undefined,
+	ownerId: string,
+	ownPermission: Permission,
+	anyPermission: Permission,
+): boolean {
+	if (!user) return false;
+	if (user.id === ownerId) {
+		return hasPermission(user, ownPermission);
+	}
+	return hasPermission(user, anyPermission);
+}
+
+/**
+ * Require permission on a resource, checking ownership
+ */
+export function requirePermissionOnResource(
+	user: { role: RoleLevel; id: string } | null | undefined,
+	ownerId: string,
+	ownPermission: Permission,
+	anyPermission: Permission,
+): asserts user is { role: RoleLevel; id: string } {
+	if (!user) {
+		throw new PermissionError("unauthorized", "Authentication required");
+	}
+	if (!canActOnOwn(user, ownerId, ownPermission, anyPermission)) {
+		throw new PermissionError("forbidden", `Missing permission: ${anyPermission}`);
+	}
+}
+
+export class PermissionError extends Error {
+	constructor(
+		public code: "unauthorized" | "forbidden",
+		message: string,
+	) {
+		super(message);
+		this.name = "PermissionError";
+	}
+}
+
+// ---------------------------------------------------------------------------
+// API Token Scope ↔ Role mapping
+//
+// Maps each API token scope to the minimum RBAC role required to hold it.
+// Used at token issuance time to clamp granted scopes to the user's role.
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimum role required for each API token scope.
+ *
+ * This is the authoritative mapping between the two authorization systems
+ * (RBAC roles and API token scopes). When issuing a token, the granted
+ * scopes must be intersected with the scopes allowed by the user's role.
+ */
+const SCOPE_MIN_ROLE: Record<ApiTokenScope, RoleLevel> = {
+	"content:read": Role.SUBSCRIBER,
+	"content:write": Role.CONTRIBUTOR,
+	"media:read": Role.SUBSCRIBER,
+	"media:write": Role.CONTRIBUTOR,
+	"schema:read": Role.EDITOR,
+	"schema:write": Role.ADMIN,
+	admin: Role.ADMIN,
+};
+
+/**
+ * Return the maximum set of API token scopes a given role level may hold.
+ *
+ * Used at token issuance time (device flow, authorization code exchange)
+ * to enforce: effective_scopes = requested_scopes ∩ scopesForRole(role).
+ */
+export function scopesForRole(role: RoleLevel): ApiTokenScope[] {
+	// eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- Object.entries loses tuple types; SCOPE_MIN_ROLE keys are ApiTokenScope by construction
+	const entries = Object.entries(SCOPE_MIN_ROLE) as [ApiTokenScope, RoleLevel][];
+	return entries.reduce<ApiTokenScope[]>((acc, [scope, minRole]) => {
+		if (role >= minRole) acc.push(scope);
+		return acc;
+	}, []);
+}
+
+/**
+ * Clamp a set of requested scopes to those permitted by a user's role.
+ *
+ * Returns the intersection of `requested` and the scopes the role allows.
+ * This is the central policy enforcement point: effective permissions =
+ * role permissions ∩ token scopes.
+ */
+export function clampScopes(requested: string[], role: RoleLevel): string[] {
+	const allowed = new Set<string>(scopesForRole(role));
+	return requested.filter((s) => allowed.has(s));
+}