@yackey-labs/yauth-shared 0.1.0

package/dist/index.js

@@ -0,0 +1,39 @@
+// @bun
+// src/aaguid.ts
+var AAGUID_MAP = {
+  "fbfc3007-154e-4ecc-8c0b-6e020557d7bd": "iCloud Keychain",
+  "dd4ec289-e01d-41c9-bb89-70fa845d4bf2": "iCloud Keychain (Managed)",
+  "adce0002-35bc-c60a-648b-0b25f1f05503": "Chrome on Mac",
+  "ea9b8d66-4d01-1d21-3ce4-b6b48cb575d4": "Google Password Manager",
+  "b5397571-f314-4571-9173-2155a0baf341": "Google Password Manager",
+  "6028b017-b1d4-4c02-b4b3-afcdafc96bb2": "Windows Hello",
+  "9ddd1817-af5a-4672-a2b9-3e3dd95000a9": "Windows Hello",
+  "08987058-cadc-4b81-b6e1-30de50dcbe96": "Windows Hello",
+  "2fc0579f-8113-47ea-b116-bb5a8db9202a": "YubiKey 5 Series (USB-A, NFC)",
+  "73bb0cd4-e502-49b8-9c6f-b59445bf720b": "YubiKey 5 FIPS Series",
+  "c5ef55ff-ad9a-4b9f-b580-adebafe026d0": "YubiKey 5Ci FIPS",
+  "85203421-48f9-4355-9bc8-8a53846e5083": "YubiKey 5Ci",
+  "d8522d9f-575b-4866-88a9-ba99fa02f35b": "YubiKey Bio Series (USB-A)",
+  "ee882879-721c-4913-9775-3dfcee97617a": "YubiKey Bio Series (USB-C)",
+  "fa2b99dc-9e39-4257-8f92-4a30d23c4118": "YubiKey 5 Series (USB-C, NFC)",
+  "cb69481e-8ff7-4039-93ec-0a2729a154a8": "YubiKey 5 Series (USB-C)",
+  "c1f9a0bc-1dd2-404a-b27f-8e29047a43fd": "YubiKey 5 Series (USB-A, NFC, FIDO2)",
+  "f8a011f3-8c0a-4d15-8006-17111f9edc7d": "Security Key by Yubico (USB-A, NFC)",
+  "b92c3f9a-c014-4056-887f-140a2501163b": "Security Key by Yubico (USB-C, NFC)",
+  "6d44ba9b-f6ec-2e49-b930-0c8fe920cb73": "Security Key by Yubico (USB-C)",
+  "149a2021-8ef6-4133-96b8-81f8d5b7f1f5": "Security Key by Yubico (USB-A, FIDO2)",
+  "bada5566-a7aa-401f-bd96-45619a55120d": "1Password",
+  "b84e4048-15dc-4dd0-8640-f4f60813c8af": "1Password",
+  "d548826e-79b4-db40-a3d8-11116f7e8349": "Bitwarden",
+  "531126d6-e717-415c-9320-3d9aa6981239": "Dashlane",
+  "53414d53-554e-4700-0000-000000000000": "Samsung Pass",
+  "b267239b-954f-4041-a01b-ee4f33c145b7": "Thales IDPrime FIDO Bio",
+  "fdb141b2-5d84-443e-8a35-4698c205a502": "KeePassXC"
+};
+function resolveAAGUID(aaguid) {
+  return AAGUID_MAP[aaguid.toLowerCase()] ?? null;
+}
+export {
+  resolveAAGUID,
+  AAGUID_MAP
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+	"name": "@yackey-labs/yauth-shared",
+	"version": "0.1.0",
+	"type": "module",
+	"main": "dist/index.js",
+	"module": "dist/index.js",
+	"types": "src/index.ts",
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./src/index.ts",
+			"default": "./src/index.ts"
+		},
+		"./types": {
+			"import": "./src/types.ts",
+			"types": "./src/types.ts"
+		},
+		"./aaguid": {
+			"import": "./src/aaguid.ts",
+			"types": "./src/aaguid.ts"
+		}
+	},
+	"files": [
+		"dist",
+		"src"
+	],
+	"scripts": {
+		"build": "bun build src/index.ts --outdir dist --target bun",
+		"typecheck": "tsc --noEmit",
+		"test": "bun test"
+	},
+	"devDependencies": {
+		"typescript": "^5.7.2"
+	}
+}

package/src/aaguid.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "bun:test";
+import { AAGUID_MAP, resolveAAGUID } from "./aaguid";
+
+describe("AAGUID_MAP", () => {
+	test("contains known Apple entry", () => {
+		expect(AAGUID_MAP["fbfc3007-154e-4ecc-8c0b-6e020557d7bd"]).toBe(
+			"iCloud Keychain",
+		);
+	});
+
+	test("contains known YubiKey entry", () => {
+		expect(AAGUID_MAP["2fc0579f-8113-47ea-b116-bb5a8db9202a"]).toBe(
+			"YubiKey 5 Series (USB-A, NFC)",
+		);
+	});
+
+	test("returns undefined for unknown AAGUID", () => {
+		expect(AAGUID_MAP["00000000-0000-0000-0000-000000000000"]).toBeUndefined();
+	});
+});
+
+describe("resolveAAGUID", () => {
+	test("resolves known AAGUID", () => {
+		expect(resolveAAGUID("fbfc3007-154e-4ecc-8c0b-6e020557d7bd")).toBe(
+			"iCloud Keychain",
+		);
+	});
+
+	test("resolves case-insensitively", () => {
+		expect(resolveAAGUID("FBFC3007-154E-4ECC-8C0B-6E020557D7BD")).toBe(
+			"iCloud Keychain",
+		);
+	});
+
+	test("returns null for unknown AAGUID", () => {
+		expect(resolveAAGUID("00000000-0000-0000-0000-000000000000")).toBeNull();
+	});
+
+	test("resolves 1Password entry", () => {
+		expect(resolveAAGUID("bada5566-a7aa-401f-bd96-45619a55120d")).toBe(
+			"1Password",
+		);
+	});
+
+	test("resolves Windows Hello entry", () => {
+		expect(resolveAAGUID("6028b017-b1d4-4c02-b4b3-afcdafc96bb2")).toBe(
+			"Windows Hello",
+		);
+	});
+});

package/src/aaguid.ts

@@ -0,0 +1,63 @@
+/**
+ * FIDO Alliance MDS AAGUID -> device name mapping.
+ * Used to resolve human-friendly names for passkey authenticators.
+ *
+ * Source: https://github.com/nickspatties/passkeys-aaguid
+ * Updated periodically. Falls back to "Unknown" for unrecognized AAGUIDs.
+ */
+export const AAGUID_MAP: Record<string, string> = {
+	// Apple
+	"fbfc3007-154e-4ecc-8c0b-6e020557d7bd": "iCloud Keychain",
+	"dd4ec289-e01d-41c9-bb89-70fa845d4bf2": "iCloud Keychain (Managed)",
+
+	// Google
+	"adce0002-35bc-c60a-648b-0b25f1f05503": "Chrome on Mac",
+	"ea9b8d66-4d01-1d21-3ce4-b6b48cb575d4": "Google Password Manager",
+	"b5397571-f314-4571-9173-2155a0baf341": "Google Password Manager",
+
+	// Microsoft
+	"6028b017-b1d4-4c02-b4b3-afcdafc96bb2": "Windows Hello",
+	"9ddd1817-af5a-4672-a2b9-3e3dd95000a9": "Windows Hello",
+	"08987058-cadc-4b81-b6e1-30de50dcbe96": "Windows Hello",
+
+	// YubiKey
+	"2fc0579f-8113-47ea-b116-bb5a8db9202a": "YubiKey 5 Series (USB-A, NFC)",
+	"73bb0cd4-e502-49b8-9c6f-b59445bf720b": "YubiKey 5 FIPS Series",
+	"c5ef55ff-ad9a-4b9f-b580-adebafe026d0": "YubiKey 5Ci FIPS",
+	"85203421-48f9-4355-9bc8-8a53846e5083": "YubiKey 5Ci",
+	"d8522d9f-575b-4866-88a9-ba99fa02f35b": "YubiKey Bio Series (USB-A)",
+	"ee882879-721c-4913-9775-3dfcee97617a": "YubiKey Bio Series (USB-C)",
+	"fa2b99dc-9e39-4257-8f92-4a30d23c4118": "YubiKey 5 Series (USB-C, NFC)",
+	"cb69481e-8ff7-4039-93ec-0a2729a154a8": "YubiKey 5 Series (USB-C)",
+	"c1f9a0bc-1dd2-404a-b27f-8e29047a43fd":
+		"YubiKey 5 Series (USB-A, NFC, FIDO2)",
+	"f8a011f3-8c0a-4d15-8006-17111f9edc7d": "Security Key by Yubico (USB-A, NFC)",
+	"b92c3f9a-c014-4056-887f-140a2501163b": "Security Key by Yubico (USB-C, NFC)",
+	"6d44ba9b-f6ec-2e49-b930-0c8fe920cb73": "Security Key by Yubico (USB-C)",
+	"149a2021-8ef6-4133-96b8-81f8d5b7f1f5":
+		"Security Key by Yubico (USB-A, FIDO2)",
+
+	// 1Password
+	"bada5566-a7aa-401f-bd96-45619a55120d": "1Password",
+	"b84e4048-15dc-4dd0-8640-f4f60813c8af": "1Password",
+
+	// Bitwarden
+	"d548826e-79b4-db40-a3d8-11116f7e8349": "Bitwarden",
+
+	// Dashlane
+	"531126d6-e717-415c-9320-3d9aa6981239": "Dashlane",
+
+	// Samsung
+	"53414d53-554e-4700-0000-000000000000": "Samsung Pass",
+
+	// Thales
+	"b267239b-954f-4041-a01b-ee4f33c145b7": "Thales IDPrime FIDO Bio",
+
+	// KeePass
+	"fdb141b2-5d84-443e-8a35-4698c205a502": "KeePassXC",
+};
+
+/** Resolve an AAGUID to a human-friendly device name */
+export function resolveAAGUID(aaguid: string): string | null {
+	return AAGUID_MAP[aaguid.toLowerCase()] ?? null;
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export { AAGUID_MAP, resolveAAGUID } from "./aaguid";
+export type {
+	AuthEvent,
+	AuthSession,
+	AuthUser,
+	EventResponse,
+} from "./types";

package/src/types.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, test } from "bun:test";
+import type { AuthEvent, AuthSession, AuthUser, EventResponse } from "./types";
+
+describe("AuthUser type", () => {
+	test("accepts valid user object", () => {
+		const user: AuthUser = {
+			id: "550e8400-e29b-41d4-a716-446655440000",
+			email: "test@example.com",
+			display_name: "Test User",
+			email_verified: true,
+			role: "user",
+			banned: false,
+			auth_method: "session",
+		};
+		expect(user.id).toBe("550e8400-e29b-41d4-a716-446655440000");
+		expect(user.role).toBe("user");
+		expect(user.auth_method).toBe("session");
+	});
+
+	test("accepts null display_name", () => {
+		const user: AuthUser = {
+			id: "1",
+			email: "a@b.com",
+			display_name: null,
+			email_verified: false,
+			role: "admin",
+			banned: false,
+			auth_method: "bearer",
+		};
+		expect(user.display_name).toBeNull();
+	});
+
+	test("accepts apikey auth_method", () => {
+		const user: AuthUser = {
+			id: "1",
+			email: "a@b.com",
+			display_name: null,
+			email_verified: false,
+			role: "user",
+			banned: false,
+			auth_method: "apikey",
+		};
+		expect(user.auth_method).toBe("apikey");
+	});
+});
+
+describe("AuthSession type", () => {
+	test("accepts valid session object", () => {
+		const session: AuthSession = {
+			id: "session-1",
+			user_id: "user-1",
+			expires_at: "2025-12-31T23:59:59Z",
+			ip_address: "192.168.1.1",
+			user_agent: "Mozilla/5.0",
+		};
+		expect(session.id).toBe("session-1");
+		expect(session.ip_address).toBe("192.168.1.1");
+	});
+
+	test("accepts null ip_address and user_agent", () => {
+		const session: AuthSession = {
+			id: "s",
+			user_id: "u",
+			expires_at: "2025-01-01T00:00:00Z",
+			ip_address: null,
+			user_agent: null,
+		};
+		expect(session.ip_address).toBeNull();
+		expect(session.user_agent).toBeNull();
+	});
+});
+
+describe("AuthEvent type", () => {
+	test("userRegistered event has correct shape", () => {
+		const event: AuthEvent = {
+			type: "userRegistered",
+			userId: "user-1",
+			email: "test@example.com",
+		};
+		expect(event.type).toBe("userRegistered");
+	});
+
+	test("loginFailed event includes reason", () => {
+		const event: AuthEvent = {
+			type: "loginFailed",
+			email: "test@example.com",
+			method: "email",
+			reason: "invalid password",
+		};
+		expect(event.reason).toBe("invalid password");
+	});
+
+	test("magicLinkVerified event includes isNewUser", () => {
+		const event: AuthEvent = {
+			type: "magicLinkVerified",
+			userId: "user-1",
+			isNewUser: true,
+		};
+		expect(event.isNewUser).toBe(true);
+	});
+});
+
+describe("EventResponse type", () => {
+	test("continue response", () => {
+		const resp: EventResponse = { action: "continue" };
+		expect(resp.action).toBe("continue");
+	});
+
+	test("requireMfa response", () => {
+		const resp: EventResponse = {
+			action: "requireMfa",
+			userId: "user-1",
+			pendingSessionId: "session-1",
+		};
+		expect(resp.action).toBe("requireMfa");
+	});
+
+	test("block response", () => {
+		const resp: EventResponse = {
+			action: "block",
+			status: 403,
+			message: "Account banned",
+		};
+		expect(resp.status).toBe(403);
+	});
+});

package/src/types.ts

@@ -0,0 +1,42 @@
+/** Auth event types emitted by plugins for cross-plugin communication */
+export type AuthEvent =
+	| { type: "userRegistered"; userId: string; email: string }
+	| { type: "loginSucceeded"; userId: string; method: string }
+	| { type: "loginFailed"; email: string; method: string; reason: string }
+	| { type: "sessionCreated"; userId: string; sessionId: string }
+	| { type: "logout"; userId: string; sessionId: string }
+	| { type: "passwordChanged"; userId: string }
+	| { type: "emailVerified"; userId: string }
+	| { type: "mfaEnabled"; userId: string; method: string }
+	| { type: "mfaDisabled"; userId: string; method: string }
+	| { type: "userBanned"; userId: string }
+	| { type: "userUnbanned"; userId: string }
+	| { type: "magicLinkSent"; email: string }
+	| { type: "magicLinkVerified"; userId: string; isNewUser: boolean };
+
+/** Response from an event handler — controls auth flow */
+export type EventResponse =
+	| { action: "continue" }
+	| { action: "requireMfa"; userId: string; pendingSessionId: string }
+	| { action: "block"; status: number; message: string };
+
+/** Authenticated user returned from the API (snake_case matches Rust serde) */
+export interface AuthUser {
+	id: string;
+	email: string;
+	display_name: string | null;
+	email_verified: boolean;
+	role: "user" | "admin";
+	banned: boolean;
+	/** Which method was used for this request: 'session' | 'bearer' | 'apikey' */
+	auth_method: "session" | "bearer" | "apikey";
+}
+
+/** Session info for cookie-based auth (snake_case matches Rust serde) */
+export interface AuthSession {
+	id: string;
+	user_id: string;
+	expires_at: string;
+	ip_address: string | null;
+	user_agent: string | null;
+}