@azlib/identity 0.2.0

package/dist/identity-4eP45YIP.cjs

@@ -0,0 +1,461 @@
+const require_errors = require("./errors-Bcjx9o6g.cjs");
+const require_logger = require("./logger-Be1wDzBC.cjs");
+//#region core/config.ts
+const MIN_SECRET_LENGTH = 32;
+const defaultGenerateId = () => globalThis.crypto.randomUUID();
+const defaultNow = () => /* @__PURE__ */ new Date();
+/**
+* Validates and applies defaults to consumer-provided configuration.
+* Throws {@link IdentityConfigError} when required values are missing or invalid.
+*/
+function resolveIdentityConfig(input) {
+	if (!input.accessTokenSecret || input.accessTokenSecret.length < MIN_SECRET_LENGTH) throw new require_errors.IdentityConfigError(`accessTokenSecret must be at least ${MIN_SECRET_LENGTH} characters.`);
+	const accessTokenTtlSeconds = input.accessTokenTtlSeconds ?? 900;
+	const refreshTokenTtlSeconds = input.refreshTokenTtlSeconds ?? 3600 * 24 * 14;
+	const passwordScryptCost = input.passwordScryptCost ?? 16384;
+	if (accessTokenTtlSeconds <= 0) throw new require_errors.IdentityConfigError("accessTokenTtlSeconds must be positive.");
+	if (refreshTokenTtlSeconds <= accessTokenTtlSeconds) throw new require_errors.IdentityConfigError("refreshTokenTtlSeconds must be greater than accessTokenTtlSeconds.");
+	if ((passwordScryptCost & passwordScryptCost - 1) !== 0) throw new require_errors.IdentityConfigError("passwordScryptCost must be a power of two.");
+	return {
+		accessTokenSecret: input.accessTokenSecret,
+		accessTokenTtlSeconds,
+		refreshTokenTtlSeconds,
+		issuer: input.issuer ?? "azlib-identity",
+		audience: input.audience,
+		passwordScryptCost,
+		lockout: {
+			maxFailedAttempts: input.lockout?.maxFailedAttempts ?? 10,
+			durationSeconds: input.lockout?.durationSeconds ?? 900
+		},
+		now: input.overrides?.now ?? defaultNow,
+		generateId: input.overrides?.generateId ?? defaultGenerateId,
+		onEvent: input.overrides?.onEvent,
+		notifications: input.notifications,
+		logger: require_logger.resolveLogger(input.logger)
+	};
+}
+//#endregion
+//#region core/authorization.ts
+const hasPermission = (principal, permission) => principal.permissions.includes(permission);
+/**
+* Evaluates a requirement using deny-by-default semantics:
+* 1. If a `permission` is required and the principal lacks it, deny.
+* 2. If a `policy` is provided, it must return `true` to allow.
+* 3. If neither is provided, deny (nothing explicitly granted access).
+*/
+async function evaluateAuthorization(requirement, context) {
+	const { permission, policy } = requirement;
+	if (permission !== void 0 && !hasPermission(context.principal, permission)) return {
+		allowed: false,
+		reason: "missing-permission"
+	};
+	if (policy) {
+		if (await policy(context) !== true) return {
+			allowed: false,
+			reason: "policy-denied"
+		};
+		return {
+			allowed: true,
+			reason: "policy-allowed"
+		};
+	}
+	if (permission !== void 0) return {
+		allowed: true,
+		reason: "permission-granted"
+	};
+	return {
+		allowed: false,
+		reason: "no-grant"
+	};
+}
+/** Convenience boolean form of {@link evaluateAuthorization}. */
+async function isAuthorized(requirement, context) {
+	return (await evaluateAuthorization(requirement, context)).allowed;
+}
+//#endregion
+//#region core/session-state.ts
+/**
+* Builds the runtime principal for a user by reading their roles and permissions from
+* the store. Returns the shape attached to authenticated requests.
+*/
+async function hydratePrincipal(store, user) {
+	const [roles, permissions] = await Promise.all([store.listRolesForUser(user.userId), store.listPermissionsForUser(user.userId)]);
+	return {
+		userId: user.userId,
+		email: user.email,
+		displayName: user.displayName,
+		status: user.status,
+		emailVerified: user.emailVerifiedAt !== null,
+		roles: roles.map((role) => role.name),
+		permissions: [...permissions]
+	};
+}
+/**
+* Issues a fresh token pair for a user and persists a new refresh session
+* (storing only the hash of the refresh token).
+*/
+async function issueSession(deps, user) {
+	const { config, store, tokenService } = deps;
+	const now = config.now();
+	const principal = await hydratePrincipal(store, user);
+	const access = await tokenService.issueAccessToken(user.userId, user.authVersion);
+	const sessionId = config.generateId();
+	const refresh = tokenService.createRefreshToken(sessionId);
+	const refreshExpiresAt = new Date(now.getTime() + config.refreshTokenTtlSeconds * 1e3);
+	await store.createSession({
+		sessionId,
+		userId: user.userId,
+		refreshTokenHash: refresh.hash,
+		createdAt: now,
+		expiresAt: refreshExpiresAt
+	});
+	return {
+		user: principal,
+		tokens: {
+			accessToken: access.token,
+			refreshToken: refresh.token,
+			accessTokenExpiresAt: access.expiresAt,
+			refreshTokenExpiresAt: refreshExpiresAt
+		}
+	};
+}
+//#endregion
+//#region core/oauth/oauth-service.ts
+/** Thrown when an OAuth operation targets an unregistered provider name. */
+var OAuthProviderNotFoundError = class extends Error {
+	constructor(providerName) {
+		super(`No OAuth provider registered with name "${providerName}".`);
+		this.name = "OAuthProviderNotFoundError";
+	}
+};
+/** Thrown when the callback state does not match the expected state (CSRF guard). */
+var OAuthStateMismatchError = class extends Error {
+	constructor() {
+		super("OAuth state mismatch. The callback may have been replayed or tampered with.");
+		this.name = "OAuthStateMismatchError";
+	}
+};
+/**
+* Creates the OAuth2 / OIDC service. Wire into the identity service by passing configured
+* provider instances (e.g. `createGoogleOAuthProvider(...)`) to the `oauth.providers` list
+* in {@link IdentityConfigInput}.
+*/
+function createOAuthService(deps) {
+	const { providers, config, store, sessionDeps, audit } = deps;
+	const providerMap = /* @__PURE__ */ new Map();
+	for (const p of providers) providerMap.set(p.name, p);
+	function getProvider(name) {
+		const p = providerMap.get(name);
+		if (!p) throw new OAuthProviderNotFoundError(name);
+		return p;
+	}
+	return {
+		get providers() {
+			return [...providerMap.keys()];
+		},
+		buildAuthorizationUrl(providerName, redirectUri, scopes) {
+			const provider = getProvider(providerName);
+			const state = config.generateId();
+			return {
+				url: provider.buildAuthorizationUrl({
+					redirectUri,
+					state,
+					scopes
+				}),
+				state
+			};
+		},
+		async handleCallback(providerName, params) {
+			if (params.state !== params.expectedState) throw new OAuthStateMismatchError();
+			const provider = getProvider(providerName);
+			const tokens = await provider.exchangeCode({
+				code: params.code,
+				redirectUri: params.redirectUri
+			});
+			const userInfo = await provider.fetchUserInfo(tokens);
+			const now = config.now();
+			if (store.findUserByOAuthId) {
+				const linkedUser = await store.findUserByOAuthId(providerName, userInfo.providerUserId);
+				if (linkedUser) {
+					await audit.record("user.login.succeeded", linkedUser.userId, {
+						email: linkedUser.email,
+						provider: providerName
+					});
+					return issueSession(sessionDeps, linkedUser);
+				}
+			}
+			if (userInfo.email) {
+				const existingUser = await store.findUserByEmail(userInfo.email);
+				if (existingUser) {
+					await linkOAuthAccount(store, existingUser.userId, providerName, userInfo, now);
+					await audit.record("user.oauth.linked", existingUser.userId, {
+						provider: providerName,
+						providerUserId: userInfo.providerUserId
+					});
+					await audit.record("user.login.succeeded", existingUser.userId, {
+						email: existingUser.email,
+						provider: providerName
+					});
+					return issueSession(sessionDeps, existingUser);
+				}
+			}
+			const newUser = await store.createUser({
+				userId: config.generateId(),
+				email: userInfo.email ?? `oauth:${providerName}:${userInfo.providerUserId}`,
+				displayName: userInfo.displayName,
+				status: "active",
+				authVersion: 0,
+				createdAt: now,
+				updatedAt: now
+			});
+			await linkOAuthAccount(store, newUser.userId, providerName, userInfo, now);
+			await audit.record("user.registered", newUser.userId, {
+				provider: providerName,
+				providerUserId: userInfo.providerUserId
+			});
+			await audit.record("user.oauth.linked", newUser.userId, {
+				provider: providerName,
+				providerUserId: userInfo.providerUserId
+			});
+			await audit.record("user.login.succeeded", newUser.userId, {
+				email: newUser.email,
+				provider: providerName
+			});
+			return issueSession(sessionDeps, newUser);
+		}
+	};
+}
+async function linkOAuthAccount(store, userId, provider, userInfo, now) {
+	if (!store.createOAuthLink) return;
+	const link = {
+		userId,
+		provider,
+		providerUserId: userInfo.providerUserId,
+		email: userInfo.email,
+		displayName: userInfo.displayName,
+		linkedAt: now
+	};
+	await store.createOAuthLink(link);
+}
+//#endregion
+//#region schema/model.ts
+const identitySchemaModel = { tables: [
+	{
+		name: "identity_users",
+		description: "Core user accounts.",
+		columns: [
+			{
+				name: "user_id",
+				description: "Primary key.",
+				nullable: false
+			},
+			{
+				name: "email",
+				description: "Unique, case-insensitive login email.",
+				nullable: false
+			},
+			{
+				name: "display_name",
+				description: "Optional display name.",
+				nullable: true
+			},
+			{
+				name: "status",
+				description: "active | disabled | locked.",
+				nullable: false
+			},
+			{
+				name: "email_verified_at",
+				description: "When email was verified.",
+				nullable: true
+			},
+			{
+				name: "auth_version",
+				description: "Token invalidation counter.",
+				nullable: false
+			},
+			{
+				name: "created_at",
+				description: "Creation timestamp.",
+				nullable: false
+			},
+			{
+				name: "updated_at",
+				description: "Last update timestamp.",
+				nullable: false
+			}
+		]
+	},
+	{
+		name: "identity_credentials",
+		description: "Password hashes, one per user.",
+		columns: [
+			{
+				name: "user_id",
+				description: "FK to identity_users.",
+				nullable: false
+			},
+			{
+				name: "password_hash",
+				description: "Algorithm-tagged hash.",
+				nullable: false
+			},
+			{
+				name: "updated_at",
+				description: "Last update timestamp.",
+				nullable: false
+			}
+		]
+	},
+	{
+		name: "identity_sessions",
+		description: "Server-side refresh sessions with hashed tokens.",
+		columns: [
+			{
+				name: "session_id",
+				description: "Primary key.",
+				nullable: false
+			},
+			{
+				name: "user_id",
+				description: "FK to identity_users.",
+				nullable: false
+			},
+			{
+				name: "refresh_token_hash",
+				description: "Hash of the active refresh token.",
+				nullable: false
+			},
+			{
+				name: "created_at",
+				description: "Creation timestamp.",
+				nullable: false
+			},
+			{
+				name: "expires_at",
+				description: "Expiry timestamp.",
+				nullable: false
+			},
+			{
+				name: "revoked_at",
+				description: "Set when rotated or revoked.",
+				nullable: true
+			}
+		]
+	},
+	{
+		name: "identity_roles",
+		description: "Named roles.",
+		columns: [
+			{
+				name: "role_id",
+				description: "Primary key.",
+				nullable: false
+			},
+			{
+				name: "name",
+				description: "Unique role name.",
+				nullable: false
+			},
+			{
+				name: "description",
+				description: "Optional description.",
+				nullable: true
+			}
+		]
+	},
+	{
+		name: "identity_user_roles",
+		description: "User-to-role assignments.",
+		columns: [{
+			name: "user_id",
+			description: "FK to identity_users.",
+			nullable: false
+		}, {
+			name: "role_id",
+			description: "FK to identity_roles.",
+			nullable: false
+		}]
+	},
+	{
+		name: "identity_role_permissions",
+		description: "Permissions granted to roles.",
+		columns: [{
+			name: "role_id",
+			description: "FK to identity_roles.",
+			nullable: false
+		}, {
+			name: "permission",
+			description: "Permission string.",
+			nullable: false
+		}]
+	},
+	{
+		name: "identity_user_permissions",
+		description: "Permissions granted directly to users.",
+		columns: [{
+			name: "user_id",
+			description: "FK to identity_users.",
+			nullable: false
+		}, {
+			name: "permission",
+			description: "Permission string.",
+			nullable: false
+		}]
+	}
+] };
+//#endregion
+Object.defineProperty(exports, "OAuthProviderNotFoundError", {
+	enumerable: true,
+	get: function() {
+		return OAuthProviderNotFoundError;
+	}
+});
+Object.defineProperty(exports, "OAuthStateMismatchError", {
+	enumerable: true,
+	get: function() {
+		return OAuthStateMismatchError;
+	}
+});
+Object.defineProperty(exports, "createOAuthService", {
+	enumerable: true,
+	get: function() {
+		return createOAuthService;
+	}
+});
+Object.defineProperty(exports, "evaluateAuthorization", {
+	enumerable: true,
+	get: function() {
+		return evaluateAuthorization;
+	}
+});
+Object.defineProperty(exports, "hydratePrincipal", {
+	enumerable: true,
+	get: function() {
+		return hydratePrincipal;
+	}
+});
+Object.defineProperty(exports, "identitySchemaModel", {
+	enumerable: true,
+	get: function() {
+		return identitySchemaModel;
+	}
+});
+Object.defineProperty(exports, "isAuthorized", {
+	enumerable: true,
+	get: function() {
+		return isAuthorized;
+	}
+});
+Object.defineProperty(exports, "issueSession", {
+	enumerable: true,
+	get: function() {
+		return issueSession;
+	}
+});
+Object.defineProperty(exports, "resolveIdentityConfig", {
+	enumerable: true,
+	get: function() {
+		return resolveIdentityConfig;
+	}
+});