@azlib/identity 0.2.0

package/dist/identity-Bz9RDOvT.mjs

@@ -0,0 +1,410 @@
+import { i as IdentityConfigError } from "./errors-CEmnZxIn.mjs";
+import { r as resolveLogger } from "./logger-CcCHJVVe.mjs";
+//#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 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 IdentityConfigError("accessTokenTtlSeconds must be positive.");
+	if (refreshTokenTtlSeconds <= accessTokenTtlSeconds) throw new IdentityConfigError("refreshTokenTtlSeconds must be greater than accessTokenTtlSeconds.");
+	if ((passwordScryptCost & passwordScryptCost - 1) !== 0) throw new 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: 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
+export { hydratePrincipal as a, isAuthorized as c, createOAuthService as i, resolveIdentityConfig as l, OAuthProviderNotFoundError as n, issueSession as o, OAuthStateMismatchError as r, evaluateAuthorization as s, identitySchemaModel as t };
+
+//# sourceMappingURL=identity-Bz9RDOvT.mjs.map

package/dist/identity-Bz9RDOvT.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-Bz9RDOvT.mjs","names":[],"sources":["../core/config.ts","../core/authorization.ts","../core/session-state.ts","../core/oauth/oauth-service.ts","../schema/model.ts"],"sourcesContent":["import { IdentityConfigError } from \"./errors\";\nimport type { IdentityLogger } from \"./logger\";\nimport { resolveLogger } from \"./logger\";\nimport type { NotificationService } from \"./notification\";\nimport type { IdentityEvent } from \"./types\";\n\n/**\n * Pluggable override points for advanced consumers. All are optional; sensible Node\n * defaults are supplied by the runtime entry (`@azlib/identity/node`).\n */\nexport interface IdentityOverrides {\n  /** Returns the current time. Override in tests for deterministic clocks. */\n  now?: () => Date;\n  /** Generates a unique id (user ids, session ids). Defaults to `crypto.randomUUID`. */\n  generateId?: () => string;\n  /**\n   * Lifecycle hook invoked for every audit event (registration, login, refresh, etc.).\n   * Use it to forward events to your own logging/analytics pipeline. It must never throw\n   * for normal operation; failures are swallowed so auditing cannot break auth flows.\n   */\n  onEvent?: (event: IdentityEvent) => void | Promise<void>;\n}\n\n/** Account lockout policy applied after repeated failed logins. */\nexport interface LockoutConfig {\n  /**\n   * How many consecutive failed login attempts are allowed before the account is\n   * temporarily locked. Set to 0 to disable lockout. Default 10.\n   */\n  maxFailedAttempts: number;\n  /**\n   * How long (in seconds) a locked account is blocked before automatic unlock.\n   * Default 900 (15 minutes). Set to 0 for permanent lock (manual unlock required).\n   */\n  durationSeconds: number;\n}\n\n/** Raw configuration accepted from consumers. */\nexport interface IdentityConfigInput {\n  /**\n   * Secret used to sign and verify access tokens (HMAC). Must be at least 32 characters.\n   * Provide via environment, never hardcode.\n   */\n  accessTokenSecret: string;\n  /** Access-token lifetime in seconds. Default 900 (15 minutes). */\n  accessTokenTtlSeconds?: number;\n  /** Refresh-token lifetime in seconds. Default 1209600 (14 days). */\n  refreshTokenTtlSeconds?: number;\n  /** Token issuer (`iss`). Default `azlib-identity`. */\n  issuer?: string;\n  /** Token audience (`aud`). Optional. */\n  audience?: string;\n  /** scrypt cost parameter `N`. Default 16384. */\n  passwordScryptCost?: number;\n  /**\n   * Account lockout policy. Omit or set `maxFailedAttempts: 0` to disable. Default: 10\n   * attempts, 15-minute lockout.\n   */\n  lockout?: Partial<LockoutConfig>;\n  /**\n   * Pluggable notification service for email verification, password reset, and SMS 2FA.\n   * Omit if you do not need these features.\n   */\n  notifications?: NotificationService;\n  /**\n   * Logger used throughout the package. Pass your own `IdentityLogger` to route\n   * diagnostic output to Winston, Pino, or any other provider. Pass `false` to silence\n   * all logging. Defaults to a console-based logger when omitted.\n   */\n  logger?: IdentityLogger | false;\n  /** Override points for clock and id generation. */\n  overrides?: IdentityOverrides;\n}\n\n/** Fully resolved, validated configuration used internally. */\nexport interface IdentityConfig {\n  accessTokenSecret: string;\n  accessTokenTtlSeconds: number;\n  refreshTokenTtlSeconds: number;\n  issuer: string;\n  audience: string | undefined;\n  passwordScryptCost: number;\n  lockout: LockoutConfig;\n  notifications: NotificationService | undefined;\n  /** Resolved logger; never `false` — `false` becomes {@link noopLogger}. */\n  logger: IdentityLogger;\n  now: () => Date;\n  generateId: () => string;\n  onEvent: ((event: IdentityEvent) => void | Promise<void>) | undefined;\n}\n\nconst MIN_SECRET_LENGTH = 32;\n\nconst defaultGenerateId = (): string => globalThis.crypto.randomUUID();\nconst defaultNow = (): Date => new Date();\n\n/**\n * Validates and applies defaults to consumer-provided configuration.\n * Throws {@link IdentityConfigError} when required values are missing or invalid.\n */\nexport function resolveIdentityConfig(input: IdentityConfigInput): IdentityConfig {\n  if (!input.accessTokenSecret || input.accessTokenSecret.length < MIN_SECRET_LENGTH) {\n    throw new IdentityConfigError(\n      `accessTokenSecret must be at least ${MIN_SECRET_LENGTH} characters.`,\n    );\n  }\n\n  const accessTokenTtlSeconds = input.accessTokenTtlSeconds ?? 900;\n  const refreshTokenTtlSeconds = input.refreshTokenTtlSeconds ?? 60 * 60 * 24 * 14;\n  const passwordScryptCost = input.passwordScryptCost ?? 16384;\n\n  if (accessTokenTtlSeconds <= 0) {\n    throw new IdentityConfigError(\"accessTokenTtlSeconds must be positive.\");\n  }\n  if (refreshTokenTtlSeconds <= accessTokenTtlSeconds) {\n    throw new IdentityConfigError(\n      \"refreshTokenTtlSeconds must be greater than accessTokenTtlSeconds.\",\n    );\n  }\n  if ((passwordScryptCost & (passwordScryptCost - 1)) !== 0) {\n    throw new IdentityConfigError(\"passwordScryptCost must be a power of two.\");\n  }\n\n  return {\n    accessTokenSecret: input.accessTokenSecret,\n    accessTokenTtlSeconds,\n    refreshTokenTtlSeconds,\n    issuer: input.issuer ?? \"azlib-identity\",\n    audience: input.audience,\n    passwordScryptCost,\n    lockout: {\n      maxFailedAttempts: input.lockout?.maxFailedAttempts ?? 10,\n      durationSeconds: input.lockout?.durationSeconds ?? 900,\n    },\n    now: input.overrides?.now ?? defaultNow,\n    generateId: input.overrides?.generateId ?? defaultGenerateId,\n    onEvent: input.overrides?.onEvent,\n    notifications: input.notifications,\n    logger: resolveLogger(input.logger),\n  };\n}\n","import type { AuthenticatedIdentity, Permission } from \"./types\";\n\n/**\n * Context passed to authorization checks. `resource` is an opaque consumer-supplied\n * object (e.g. a loaded document) used by ownership/relationship policies.\n */\nexport interface AuthorizationContext<TResource = unknown> {\n  principal: AuthenticatedIdentity;\n  /** The action being attempted, typically a permission string. */\n  action: string;\n  /** The target resource, if any. */\n  resource?: TResource;\n}\n\n/**\n * A policy rule returns:\n * - `true` to allow,\n * - `false`/`undefined` to abstain (deny-by-default unless another rule allows),\n * It must never throw for normal \"denied\" outcomes.\n */\nexport type PolicyRule<TResource = unknown> = (\n  context: AuthorizationContext<TResource>,\n) => boolean | undefined | Promise<boolean | undefined>;\n\n/** A named requirement combining a required permission and optional ownership policy. */\nexport interface AuthorizationRequirement<TResource = unknown> {\n  /** Permission the principal must hold. Omit to rely solely on policies. */\n  permission?: Permission;\n  /** Optional ownership/relationship rule evaluated against the resource. */\n  policy?: PolicyRule<TResource>;\n}\n\n/** Result of an authorization decision. */\nexport interface AuthorizationDecision {\n  allowed: boolean;\n  /** Non-sensitive reason for diagnostics/audit. */\n  reason: string;\n}\n\nconst hasPermission = (\n  principal: AuthenticatedIdentity,\n  permission: Permission,\n): boolean => principal.permissions.includes(permission);\n\n/**\n * Evaluates a requirement using deny-by-default semantics:\n * 1. If a `permission` is required and the principal lacks it, deny.\n * 2. If a `policy` is provided, it must return `true` to allow.\n * 3. If neither is provided, deny (nothing explicitly granted access).\n */\nexport async function evaluateAuthorization<TResource = unknown>(\n  requirement: AuthorizationRequirement<TResource>,\n  context: AuthorizationContext<TResource>,\n): Promise<AuthorizationDecision> {\n  const { permission, policy } = requirement;\n\n  if (permission !== undefined && !hasPermission(context.principal, permission)) {\n    return { allowed: false, reason: \"missing-permission\" };\n  }\n\n  if (policy) {\n    const result = await policy(context);\n    if (result !== true) {\n      return { allowed: false, reason: \"policy-denied\" };\n    }\n    return { allowed: true, reason: \"policy-allowed\" };\n  }\n\n  if (permission !== undefined) {\n    return { allowed: true, reason: \"permission-granted\" };\n  }\n\n  return { allowed: false, reason: \"no-grant\" };\n}\n\n/** Convenience boolean form of {@link evaluateAuthorization}. */\nexport async function isAuthorized<TResource = unknown>(\n  requirement: AuthorizationRequirement<TResource>,\n  context: AuthorizationContext<TResource>,\n): Promise<boolean> {\n  return (await evaluateAuthorization(requirement, context)).allowed;\n}\n","import type { IdentityConfig } from \"./config\";\nimport type { IdentityStore } from \"./identity-store\";\nimport type { TokenService } from \"./token-service\";\nimport type { AuthResult, AuthenticatedIdentity, IdentityUser } from \"./types\";\n\n/** Dependencies shared by the register/login/refresh flows. */\nexport interface SessionDeps {\n  config: IdentityConfig;\n  store: IdentityStore;\n  tokenService: TokenService;\n}\n\n/**\n * Builds the runtime principal for a user by reading their roles and permissions from\n * the store. Returns the shape attached to authenticated requests.\n */\nexport async function hydratePrincipal(\n  store: IdentityStore,\n  user: IdentityUser,\n): Promise<AuthenticatedIdentity> {\n  const [roles, permissions] = await Promise.all([\n    store.listRolesForUser(user.userId),\n    store.listPermissionsForUser(user.userId),\n  ]);\n\n  return {\n    userId: user.userId,\n    email: user.email,\n    displayName: user.displayName,\n    status: user.status,\n    emailVerified: user.emailVerifiedAt !== null,\n    roles: roles.map((role) => role.name),\n    permissions: [...permissions],\n  };\n}\n\n/**\n * Issues a fresh token pair for a user and persists a new refresh session\n * (storing only the hash of the refresh token).\n */\nexport async function issueSession(\n  deps: SessionDeps,\n  user: IdentityUser,\n): Promise<AuthResult> {\n  const { config, store, tokenService } = deps;\n  const now = config.now();\n\n  const principal = await hydratePrincipal(store, user);\n  const access = await tokenService.issueAccessToken(user.userId, user.authVersion);\n  const sessionId = config.generateId();\n  const refresh = tokenService.createRefreshToken(sessionId);\n\n  const refreshExpiresAt = new Date(now.getTime() + config.refreshTokenTtlSeconds * 1000);\n  await store.createSession({\n    sessionId,\n    userId: user.userId,\n    refreshTokenHash: refresh.hash,\n    createdAt: now,\n    expiresAt: refreshExpiresAt,\n  });\n\n  return {\n    user: principal,\n    tokens: {\n      accessToken: access.token,\n      refreshToken: refresh.token,\n      accessTokenExpiresAt: access.expiresAt,\n      refreshTokenExpiresAt: refreshExpiresAt,\n    },\n  };\n}\n","import type { AuditLogger } from \"../audit\";\nimport type { IdentityConfig } from \"../config\";\nimport type { IdentityStore } from \"../identity-store\";\nimport { issueSession, type SessionDeps } from \"../session-state\";\nimport type { AuthResult, OAuthLinkedAccount } from \"../types\";\nimport type { OAuthProvider } from \"./oauth-provider\";\n\n/** Result of {@link OAuthService.buildAuthorizationUrl}. */\nexport interface OAuthAuthorizationUrl {\n  /** The full provider authorization URL to redirect the user to. */\n  url: string;\n  /**\n   * An opaque CSRF-prevention state value. Store this in a signed cookie or server\n   * session and pass it as `expectedState` when calling {@link OAuthService.handleCallback}.\n   */\n  state: string;\n}\n\n/** Parameters for {@link OAuthService.handleCallback}. */\nexport interface OAuthCallbackParams {\n  /** The authorization code received from the provider callback query string. */\n  code: string;\n  /** The `state` value received from the provider callback query string. */\n  state: string;\n  /**\n   * The expected state value previously returned by {@link OAuthService.buildAuthorizationUrl}.\n   * The callback will be rejected when they do not match (CSRF protection).\n   */\n  expectedState: string;\n  /** The same redirect URI that was used in the authorization request. */\n  redirectUri: string;\n  /** Optional scopes to override for this callback's code exchange. */\n  scopes?: string[];\n}\n\n/** The OAuth2 / OIDC surface of the identity service. */\nexport interface OAuthService {\n  /** Returns the registered provider names, e.g. `[\"google\", \"microsoft\"]`. */\n  readonly providers: readonly string[];\n\n  /**\n   * Builds the authorization URL for the given provider. Redirect the user's browser to\n   * the returned `url`, then store `state` for later verification.\n   */\n  buildAuthorizationUrl(providerName: string, redirectUri: string, scopes?: string[]): OAuthAuthorizationUrl;\n\n  /**\n   * Handles the provider callback after user consent. Verifies state, exchanges the code\n   * for tokens, resolves or provisions a local user, and returns a full auth result.\n   *\n   * Throws {@link OAuthProviderNotFoundError} for unknown providers.\n   * Throws a generic {@link IdentityError} when state mismatches (CSRF guard).\n   */\n  handleCallback(providerName: string, params: OAuthCallbackParams): Promise<AuthResult>;\n}\n\n/** Thrown when an OAuth operation targets an unregistered provider name. */\nexport class OAuthProviderNotFoundError extends Error {\n  constructor(providerName: string) {\n    super(`No OAuth provider registered with name \"${providerName}\".`);\n    this.name = \"OAuthProviderNotFoundError\";\n  }\n}\n\n/** Thrown when the callback state does not match the expected state (CSRF guard). */\nexport class OAuthStateMismatchError extends Error {\n  constructor() {\n    super(\"OAuth state mismatch. The callback may have been replayed or tampered with.\");\n    this.name = \"OAuthStateMismatchError\";\n  }\n}\n\n/** Dependencies for {@link createOAuthService}. */\nexport interface OAuthServiceDeps {\n  providers: readonly OAuthProvider[];\n  config: IdentityConfig;\n  store: IdentityStore;\n  sessionDeps: SessionDeps;\n  audit: AuditLogger;\n}\n\n/**\n * Creates the OAuth2 / OIDC service. Wire into the identity service by passing configured\n * provider instances (e.g. `createGoogleOAuthProvider(...)`) to the `oauth.providers` list\n * in {@link IdentityConfigInput}.\n */\nexport function createOAuthService(deps: OAuthServiceDeps): OAuthService {\n  const { providers, config, store, sessionDeps, audit } = deps;\n\n  const providerMap = new Map<string, OAuthProvider>();\n  for (const p of providers) {\n    providerMap.set(p.name, p);\n  }\n\n  function getProvider(name: string): OAuthProvider {\n    const p = providerMap.get(name);\n    if (!p) throw new OAuthProviderNotFoundError(name);\n    return p;\n  }\n\n  return {\n    get providers() {\n      return [...providerMap.keys()];\n    },\n\n    buildAuthorizationUrl(providerName, redirectUri, scopes) {\n      const provider = getProvider(providerName);\n      const state = config.generateId();\n      const url = provider.buildAuthorizationUrl({ redirectUri, state, scopes });\n      return { url, state };\n    },\n\n    async handleCallback(providerName, params) {\n      // CSRF guard — must be the first check.\n      if (params.state !== params.expectedState) {\n        throw new OAuthStateMismatchError();\n      }\n\n      const provider = getProvider(providerName);\n\n      // Exchange the authorization code for provider tokens.\n      const tokens = await provider.exchangeCode({\n        code: params.code,\n        redirectUri: params.redirectUri,\n      });\n\n      // Fetch normalized user info from the provider.\n      const userInfo = await provider.fetchUserInfo(tokens);\n\n      const now = config.now();\n\n      // 1. Look up by OAuth link (returning user).\n      if (store.findUserByOAuthId) {\n        const linkedUser = await store.findUserByOAuthId(providerName, userInfo.providerUserId);\n        if (linkedUser) {\n          await audit.record(\"user.login.succeeded\", linkedUser.userId, {\n            email: linkedUser.email,\n            provider: providerName,\n          });\n          return issueSession(sessionDeps, linkedUser);\n        }\n      }\n\n      // 2. Look up by email (existing local account — link the provider).\n      if (userInfo.email) {\n        const existingUser = await store.findUserByEmail(userInfo.email);\n        if (existingUser) {\n          await linkOAuthAccount(store, existingUser.userId, providerName, userInfo, now);\n          await audit.record(\"user.oauth.linked\", existingUser.userId, {\n            provider: providerName,\n            providerUserId: userInfo.providerUserId,\n          });\n          await audit.record(\"user.login.succeeded\", existingUser.userId, {\n            email: existingUser.email,\n            provider: providerName,\n          });\n          return issueSession(sessionDeps, existingUser);\n        }\n      }\n\n      // 3. Provision a new local user and link the provider.\n      const newUser = await store.createUser({\n        userId: config.generateId(),\n        email: userInfo.email ?? `oauth:${providerName}:${userInfo.providerUserId}`,\n        displayName: userInfo.displayName,\n        status: \"active\",\n        authVersion: 0,\n        createdAt: now,\n        updatedAt: now,\n      });\n      await linkOAuthAccount(store, newUser.userId, providerName, userInfo, now);\n      await audit.record(\"user.registered\", newUser.userId, {\n        provider: providerName,\n        providerUserId: userInfo.providerUserId,\n      });\n      await audit.record(\"user.oauth.linked\", newUser.userId, {\n        provider: providerName,\n        providerUserId: userInfo.providerUserId,\n      });\n      await audit.record(\"user.login.succeeded\", newUser.userId, {\n        email: newUser.email,\n        provider: providerName,\n      });\n      return issueSession(sessionDeps, newUser);\n    },\n  };\n}\n\nasync function linkOAuthAccount(\n  store: IdentityStore,\n  userId: string,\n  provider: string,\n  userInfo: { providerUserId: string; email: string | null; displayName: string | null },\n  now: Date,\n): Promise<void> {\n  if (!store.createOAuthLink) return; // Store does not support OAuth links — skip silently.\n\n  const link: OAuthLinkedAccount = {\n    userId,\n    provider,\n    providerUserId: userInfo.providerUserId,\n    email: userInfo.email,\n    displayName: userInfo.displayName,\n    linkedAt: now,\n  };\n  await store.createOAuthLink(link);\n}\n","/**\n * Logical description of the relational schema `@azlib/identity` expects.\n *\n * Concrete DDL is shipped alongside this module:\n * - `@azlib/identity/schema/postgres.sql`\n * - `@azlib/identity/schema/mysql.sql`\n * - `@azlib/identity/schema/sqlite.sql`\n * - `@azlib/identity/schema/prisma.schema`\n *\n * This object is documentation-as-data so consumers and tooling can introspect the\n * expected tables without parsing SQL.\n */\nexport interface SchemaColumn {\n  name: string;\n  description: string;\n  nullable: boolean;\n}\n\nexport interface SchemaTable {\n  name: string;\n  description: string;\n  columns: readonly SchemaColumn[];\n}\n\nexport interface SchemaModel {\n  tables: readonly SchemaTable[];\n}\n\nexport const identitySchemaModel: SchemaModel = {\n  tables: [\n    {\n      name: \"identity_users\",\n      description: \"Core user accounts.\",\n      columns: [\n        { name: \"user_id\", description: \"Primary key.\", nullable: false },\n        { name: \"email\", description: \"Unique, case-insensitive login email.\", nullable: false },\n        { name: \"display_name\", description: \"Optional display name.\", nullable: true },\n        { name: \"status\", description: \"active | disabled | locked.\", nullable: false },\n        { name: \"email_verified_at\", description: \"When email was verified.\", nullable: true },\n        { name: \"auth_version\", description: \"Token invalidation counter.\", nullable: false },\n        { name: \"created_at\", description: \"Creation timestamp.\", nullable: false },\n        { name: \"updated_at\", description: \"Last update timestamp.\", nullable: false },\n      ],\n    },\n    {\n      name: \"identity_credentials\",\n      description: \"Password hashes, one per user.\",\n      columns: [\n        { name: \"user_id\", description: \"FK to identity_users.\", nullable: false },\n        { name: \"password_hash\", description: \"Algorithm-tagged hash.\", nullable: false },\n        { name: \"updated_at\", description: \"Last update timestamp.\", nullable: false },\n      ],\n    },\n    {\n      name: \"identity_sessions\",\n      description: \"Server-side refresh sessions with hashed tokens.\",\n      columns: [\n        { name: \"session_id\", description: \"Primary key.\", nullable: false },\n        { name: \"user_id\", description: \"FK to identity_users.\", nullable: false },\n        { name: \"refresh_token_hash\", description: \"Hash of the active refresh token.\", nullable: false },\n        { name: \"created_at\", description: \"Creation timestamp.\", nullable: false },\n        { name: \"expires_at\", description: \"Expiry timestamp.\", nullable: false },\n        { name: \"revoked_at\", description: \"Set when rotated or revoked.\", nullable: true },\n      ],\n    },\n    {\n      name: \"identity_roles\",\n      description: \"Named roles.\",\n      columns: [\n        { name: \"role_id\", description: \"Primary key.\", nullable: false },\n        { name: \"name\", description: \"Unique role name.\", nullable: false },\n        { name: \"description\", description: \"Optional description.\", nullable: true },\n      ],\n    },\n    {\n      name: \"identity_user_roles\",\n      description: \"User-to-role assignments.\",\n      columns: [\n        { name: \"user_id\", description: \"FK to identity_users.\", nullable: false },\n        { name: \"role_id\", description: \"FK to identity_roles.\", nullable: false },\n      ],\n    },\n    {\n      name: \"identity_role_permissions\",\n      description: \"Permissions granted to roles.\",\n      columns: [\n        { name: \"role_id\", description: \"FK to identity_roles.\", nullable: false },\n        { name: \"permission\", description: \"Permission string.\", nullable: false },\n      ],\n    },\n    {\n      name: \"identity_user_permissions\",\n      description: \"Permissions granted directly to users.\",\n      columns: [\n        { name: \"user_id\", description: \"FK to identity_users.\", nullable: false },\n        { name: \"permission\", description: \"Permission string.\", nullable: false },\n      ],\n    },\n  ],\n};\n"],"mappings":"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"}

package/dist/identity-router-DBL20UWT.d.mts

@@ -0,0 +1,115 @@
+import { F as IdentityLogger } from "./errors-BGMwaW5s.mjs";
+import { t as IdentityService } from "./identity-service-B9zrvE9z.mjs";
+import { Request, Response, Router } from "express";
+
+//#region core/express/identity-router.d.ts
+/** Options for controlling the refresh-token cookie. */
+interface CookieRefreshOptions {
+  /** Cookie name. Default: `"azlib_rt"`. */
+  name?: string;
+  /** Mark the cookie as `HttpOnly`. Default: `true`. */
+  httpOnly?: boolean;
+  /**
+   * Mark the cookie as `Secure`. Defaults to `true` when `NODE_ENV` is `"production"`,
+   * `false` otherwise.
+   */
+  secure?: boolean;
+  /** `SameSite` policy. Default: `"lax"`. */
+  sameSite?: "strict" | "lax" | "none";
+  /** Cookie path. Default: `"/"`. */
+  path?: string;
+  /** Cookie domain. Omit to use the current host. */
+  domain?: string;
+}
+/**
+ * Options for {@link createIdentityRouter}.
+ */
+interface IdentityRouterOptions {
+  /**
+   * Controls how the refresh token is transported between server and client.
+   *
+   * - **`"body"`** (default) — the refresh token is included in the `tokens` object of
+   *   every successful `register`/`login`/`refresh` response. The client must store it
+   *   and send it back via the JSON body on `/refresh` and `/logout`.
+   *
+   * - **`{ cookie: CookieRefreshOptions }`** — the refresh token is sent as an
+   *   `HttpOnly` cookie. `/refresh` and `/logout` read it automatically; the response
+   *   body only includes the access token.
+   */
+  refreshToken?: "body" | {
+    cookie: CookieRefreshOptions;
+  };
+  /**
+   * Base URL under which the OAuth callback routes are hosted.
+   *
+   * Example: `"https://api.example.com/auth"`.
+   *
+   * The callback URI for a provider becomes `{oauthBaseUrl}/{providerName}/callback`.
+   * Required when the identity service has OAuth providers configured.
+   */
+  oauthBaseUrl?: string;
+  /**
+   * URL path prefix prepended to all identity routes.
+   *
+   * Default: `"account"`. Routes are served at `/{prefix}/login`, `/{prefix}/register`, etc.
+   *
+   * Mount the returned router at the application root:
+   * ```ts
+   * app.use(createIdentityRouter(service, { prefix: "auth" }));
+   * // → POST /auth/login, POST /auth/register, …
+   * ```
+   *
+   * Set to `""` to omit the prefix and mount routes directly at the router's mount point.
+   */
+  prefix?: string;
+  /**
+   * Logger for request/response and error diagnostics.
+   *
+   * - Omit — defaults to a `console`-based logger with an `[identity]` prefix.
+   * - Supply your own `IdentityLogger` — route output to Winston, Pino, etc.
+   * - Pass `false` — disable all logging from this router.
+   *
+   * @example
+   * ```ts
+   * import pino from "pino";
+   * app.use(createIdentityRouter(service, { logger: pino() }));
+   * ```
+   */
+  logger?: IdentityLogger | false;
+}
+/**
+ * Creates a pre-wired Express `Router` with all standard identity endpoints.
+ *
+ * Mount it once on your application:
+ * ```ts
+ * import express from "express";
+ * import { createIdentityService } from "@azlib/identity/node";
+ * import { createIdentityRouter, identityErrorHandler } from "@azlib/identity/express";
+ *
+ * const service = createIdentityService(config, store);
+ * const app = express();
+ *
+ * app.use(express.json());
+ * // Routes are served at /account/login, /account/register, etc. (default prefix)
+ * app.use(createIdentityRouter(service));
+ * // Or use a custom prefix:
+ * app.use(createIdentityRouter(service, { prefix: "auth" }));
+ * app.use(identityErrorHandler()); // optional convenience error handler
+ * ```
+ *
+ * Pre-wired routes:
+ *
+ * | Method | Path | Description |
+ * |--------|------|-------------|
+ * | POST | `/register` | Create a new account |
+ * | POST | `/login` | Email + password login |
+ * | POST | `/refresh` | Rotate the refresh token |
+ * | POST | `/logout` | Revoke the current session |
+ * | GET  | `/me` | Return the authenticated principal |
+ * | GET  | `/:provider` | Start an OAuth 2.0 authorisation flow *(optional)* |
+ * | GET  | `/:provider/callback` | Handle an OAuth 2.0 callback *(optional)* |
+ */
+declare function createIdentityRouter(service: IdentityService, options?: IdentityRouterOptions): Router;
+//#endregion
+export { IdentityRouterOptions as n, createIdentityRouter as r, CookieRefreshOptions as t };
+//# sourceMappingURL=identity-router-DBL20UWT.d.mts.map

package/dist/identity-router-DBL20UWT.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-router-DBL20UWT.d.mts","names":[],"sources":["../core/express/identity-router.ts"],"mappings":";;;;;;UAeiB,oBAAA;EAAA;EAEf,IAAA;;EAEA,QAAA;EAFA;;;;EAOA,MAAA;EAMA;EAJA,QAAA;EAIM;EAFN,IAAA;EAQoC;EANpC,MAAA;AAAA;;;;UAMe,qBAAA;EAqCf;;;;AAeuB;AAsIzB;;;;;;EA9KE,YAAA;IAA0B,MAAA,EAAQ,oBAAA;EAAA;EA+KlC;;;;;AAEO;;;EAvKP,YAAA;;;;;;;;;;;;;;EAeA,MAAA;;;;;;;;;;;;;;EAeA,MAAA,GAAS,cAAc;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsIT,oBAAA,CACd,OAAA,EAAS,eAAA,EACT,OAAA,GAAS,qBAAA,GACR,MAAA"}