@vertz/server 0.2.11 → 0.2.13

package/dist/index.d.ts

@@ -1,167 +1,315 @@
 import { AccumulateProvides, AppBuilder as AppBuilder2, AppConfig as AppConfig2, CorsConfig, Ctx, DeepReadonly, Deps, EnvConfig, HandlerCtx, HttpMethod, HttpStatusCode, Infer, InferSchema, ListenOptions, MiddlewareDef, NamedMiddlewareDef, RawRequest, ServerAdapter, ServerHandle } from "@vertz/core";
 import { BadRequestException, ConflictException, createEnv, createImmutableProxy, createMiddleware, deepFreeze, ForbiddenException, InternalServerErrorException, makeImmutable, NotFoundException, ServiceUnavailableException, UnauthorizedException, ValidationException, VertzException, vertz } from "@vertz/core";
-import { ModelDef as ModelDef2, RelationDef, SchemaLike, TableDef } from "@vertz/db";
-import { ModelDef } from "@vertz/db";
-import { EntityDbAdapter, ListOptions } from "@vertz/db";
-import { EntityError, Result } from "@vertz/errors";
-import { EntityDbAdapter as EntityDbAdapter2, ListOptions as ListOptions2 } from "@vertz/db";
-interface ListResult<T = Record<string, unknown>> {
-	items: T[];
-	total: number;
-	limit: number;
-	nextCursor: string | null;
-	hasNextPage: boolean;
+import { ModelEntry } from "@vertz/db";
+import { AuthError, Result } from "@vertz/errors";
+/**
+* defineAccess() — Phase 6 RBAC & Access Control configuration
+*
+* Replaces createAccess() with hierarchical RBAC: resources form trees,
+* roles inherit down the hierarchy, and entitlements map to roles/plans/flags.
+*/
+/** Denial reasons ordered by actionability (most actionable first) */
+type DenialReason = "plan_required" | "role_required" | "limit_reached" | "flag_disabled" | "hierarchy_denied" | "step_up_required" | "not_authenticated";
+/** Metadata attached to denial reasons */
+interface DenialMeta {
+	requiredPlans?: string[];
+	requiredRoles?: string[];
+	disabledFlags?: string[];
+	limit?: {
+		max: number;
+		consumed: number;
+		remaining: number;
+	};
+	fvaMaxAge?: number;
 }
-interface CrudResult<T = unknown> {
-	status: number;
-	body: T;
+/** Result of a full access check (all layers evaluated) */
+interface AccessCheckResult {
+	allowed: boolean;
+	reasons: DenialReason[];
+	reason?: DenialReason;
+	meta?: DenialMeta;
 }
-interface CrudHandlers {
-	list(ctx: EntityContext, options?: ListOptions): Promise<Result<CrudResult<ListResult>, EntityError>>;
-	get(ctx: EntityContext, id: string): Promise<Result<CrudResult<Record<string, unknown>>, EntityError>>;
-	create(ctx: EntityContext, data: Record<string, unknown>): Promise<Result<CrudResult<Record<string, unknown>>, EntityError>>;
-	update(ctx: EntityContext, id: string, data: Record<string, unknown>): Promise<Result<CrudResult<Record<string, unknown>>, EntityError>>;
-	delete(ctx: EntityContext, id: string): Promise<Result<CrudResult<null>, EntityError>>;
+/** Entitlement definition — maps to roles, optional plans and flags */
+interface EntitlementDef {
+	roles: string[];
+	plans?: string[];
+	flags?: string[];
 }
-declare function createCrudHandlers(def: EntityDefinition, db: EntityDbAdapter): CrudHandlers;
+/** Billing period for plan limits */
+type BillingPeriod = "month" | "day" | "hour";
+/** Limit definition within a plan */
+interface LimitDef {
+	per: BillingPeriod;
+	max: number;
+}
+/** Plan definition — which entitlements are included and their usage limits */
+interface PlanDef {
+	entitlements: readonly string[] | string[];
+	limits?: Record<string, LimitDef>;
+}
+/** The input config for defineAccess() */
+interface DefineAccessInput {
+	hierarchy: string[];
+	roles: Record<string, string[]>;
+	inheritance?: Record<string, Record<string, string>>;
+	entitlements: Record<string, EntitlementDef>;
+	plans?: Record<string, PlanDef>;
+	/** Fallback plan name when an org's plan expires. Defaults to 'free'. */
+	defaultPlan?: string;
+}
+/** The frozen config returned by defineAccess() */
+interface AccessDefinition {
+	readonly hierarchy: readonly string[];
+	readonly roles: Readonly<Record<string, readonly string[]>>;
+	readonly inheritance: Readonly<Record<string, Readonly<Record<string, string>>>>;
+	readonly entitlements: Readonly<Record<string, Readonly<EntitlementDef>>>;
+	readonly plans?: Readonly<Record<string, Readonly<PlanDef>>>;
+	/** Fallback plan name when an org's plan expires. Defaults to 'free'. */
+	readonly defaultPlan?: string;
+}
+declare function defineAccess(input: DefineAccessInput): AccessDefinition;
 /**
-* EntityOperations — typed CRUD facade for a single entity.
+* InMemoryClosureStore — closure table for resource hierarchy.
 *
-* When used as `ctx.entity`, TModel fills in actual column types.
-* When used as `ctx.entities.*`, TModel defaults to `ModelDef` (loose typing).
+* Stores ancestor/descendant relationships with depth tracking.
+* Self-reference rows (depth 0) are created for every resource.
+* Hierarchy depth is capped at 4 levels.
 */
-interface EntityOperations<TModel extends ModelDef = ModelDef> {
-	get(id: string): Promise<TModel["table"]["$response"]>;
-	list(options?: ListOptions2): Promise<ListResult<TModel["table"]["$response"]>>;
-	create(data: TModel["table"]["$create_input"]): Promise<TModel["table"]["$response"]>;
-	update(id: string, data: TModel["table"]["$update_input"]): Promise<TModel["table"]["$response"]>;
-	delete(id: string): Promise<void>;
+interface ClosureRow {
+	ancestorType: string;
+	ancestorId: string;
+	descendantType: string;
+	descendantId: string;
+	depth: number;
+}
+interface ClosureEntry {
+	type: string;
+	id: string;
+	depth: number;
+}
+interface ParentRef {
+	parentType: string;
+	parentId: string;
+}
+interface ClosureStore {
+	addResource(type: string, id: string, parent?: ParentRef): Promise<void>;
+	removeResource(type: string, id: string): Promise<void>;
+	getAncestors(type: string, id: string): Promise<ClosureEntry[]>;
+	getDescendants(type: string, id: string): Promise<ClosureEntry[]>;
+	hasPath(ancestorType: string, ancestorId: string, descendantType: string, descendantId: string): Promise<boolean>;
+	dispose(): void;
+}
+declare class InMemoryClosureStore implements ClosureStore {
+	private rows;
+	addResource(type: string, id: string, parent?: ParentRef): Promise<void>;
+	removeResource(type: string, id: string): Promise<void>;
+	getAncestors(type: string, id: string): Promise<ClosureEntry[]>;
+	getDescendants(type: string, id: string): Promise<ClosureEntry[]>;
+	hasPath(ancestorType: string, ancestorId: string, descendantType: string, descendantId: string): Promise<boolean>;
+	dispose(): void;
+}
+interface RoleAssignment {
+	userId: string;
+	resourceType: string;
+	resourceId: string;
+	role: string;
+}
+interface RoleAssignmentStore {
+	assign(userId: string, resourceType: string, resourceId: string, role: string): Promise<void>;
+	revoke(userId: string, resourceType: string, resourceId: string, role: string): Promise<void>;
+	getRoles(userId: string, resourceType: string, resourceId: string): Promise<string[]>;
+	getRolesForUser(userId: string): Promise<RoleAssignment[]>;
+	getEffectiveRole(userId: string, resourceType: string, resourceId: string, accessDef: AccessDefinition, closureStore: ClosureStore): Promise<string | null>;
+	dispose(): void;
+}
+declare class InMemoryRoleAssignmentStore implements RoleAssignmentStore {
+	private assignments;
+	assign(userId: string, resourceType: string, resourceId: string, role: string): Promise<void>;
+	revoke(userId: string, resourceType: string, resourceId: string, role: string): Promise<void>;
+	getRoles(userId: string, resourceType: string, resourceId: string): Promise<string[]>;
+	getRolesForUser(userId: string): Promise<RoleAssignment[]>;
+	/**
+	* Compute the effective role for a user on a resource.
+	* Considers direct assignments + inherited roles from ancestors.
+	* Most permissive role wins (additive model).
+	*/
+	getEffectiveRole(userId: string, resourceType: string, resourceId: string, accessDef: AccessDefinition, closureStore: ClosureStore): Promise<string | null>;
+	dispose(): void;
 }
-/** Extracts the model type from an EntityDefinition */
-type ExtractModel<T> = T extends EntityDefinition<infer M> ? M : ModelDef2;
 /**
-* Maps an inject config `{ key: EntityDefinition<TModel> }` to
-* `{ key: EntityOperations<TModel> }` for typed ctx.entities access.
+* Feature Flag Store — per-tenant boolean feature flags.
+*
+* Pluggable interface with in-memory default.
+* Used by Layer 1 of access context to gate entitlements on feature flags.
 */
-type InjectToOperations<TInject extends Record<string, EntityDefinition> = {}> = { readonly [K in keyof TInject] : EntityOperations<ExtractModel<TInject[K]>> };
-interface BaseContext {
-	readonly userId: string | null;
-	authenticated(): boolean;
-	tenant(): boolean;
-	role(...roles: string[]): boolean;
+interface FlagStore {
+	setFlag(orgId: string, flag: string, enabled: boolean): void;
+	getFlag(orgId: string, flag: string): boolean;
+	getFlags(orgId: string): Record<string, boolean>;
 }
-interface EntityContext<
-	TModel extends ModelDef2 = ModelDef2,
-	TInject extends Record<string, EntityDefinition> = {}
-> extends BaseContext {
-	/** Typed CRUD on the current entity */
-	readonly entity: EntityOperations<TModel>;
-	/** Typed access to injected entities only */
-	readonly entities: InjectToOperations<TInject>;
-}
-type AccessRule = false | ((ctx: BaseContext, row: Record<string, unknown>) => boolean | Promise<boolean>);
-interface EntityBeforeHooks<
-	TCreateInput = unknown,
-	TUpdateInput = unknown
-> {
-	readonly create?: (data: TCreateInput, ctx: EntityContext) => TCreateInput | Promise<TCreateInput>;
-	readonly update?: (data: TUpdateInput, ctx: EntityContext) => TUpdateInput | Promise<TUpdateInput>;
+declare class InMemoryFlagStore implements FlagStore {
+	private flags;
+	setFlag(orgId: string, flag: string, enabled: boolean): void;
+	getFlag(orgId: string, flag: string): boolean;
+	getFlags(orgId: string): Record<string, boolean>;
 }
-interface EntityAfterHooks<TResponse = unknown> {
-	readonly create?: (result: TResponse, ctx: EntityContext) => void | Promise<void>;
-	readonly update?: (prev: TResponse, next: TResponse, ctx: EntityContext) => void | Promise<void>;
-	readonly delete?: (row: TResponse, ctx: EntityContext) => void | Promise<void>;
+/**
+* PlanStore — org-level plan assignments with overrides.
+*
+* Stores which plan an organization is on, when it started,
+* optional expiration, and per-customer limit overrides.
+*/
+/** Per-customer limit override. Only affects the cap, not the billing period. */
+interface LimitOverride {
+	max: number;
 }
-interface EntityActionDef<
-	TInput = unknown,
-	TOutput = unknown,
-	TResponse = unknown,
-	TCtx extends EntityContext = EntityContext
-> {
-	readonly method?: string;
-	readonly path?: string;
-	readonly body: SchemaLike<TInput>;
-	readonly response: SchemaLike<TOutput>;
-	readonly handler: (input: TInput, ctx: TCtx, row: TResponse | null) => Promise<TOutput>;
+interface OrgPlan {
+	orgId: string;
+	planId: string;
+	startedAt: Date;
+	expiresAt: Date | null;
+	overrides: Record<string, LimitOverride>;
 }
-/** Extract column keys from a RelationDef's target table. */
-type RelationColumnKeys<R> = R extends RelationDef<infer TTarget> ? TTarget extends TableDef<infer TCols> ? Extract<keyof TCols, string> : string : string;
-type EntityRelationsConfig<TRelations extends Record<string, RelationDef> = Record<string, RelationDef>> = { [K in keyof TRelations]? : true | false | { [F in RelationColumnKeys<TRelations[K]>]? : true } };
-interface EntityConfig<
-	TModel extends ModelDef2 = ModelDef2,
-	TActions extends Record<string, EntityActionDef<any, any, any, any>> = {},
-	TInject extends Record<string, EntityDefinition> = {}
-> {
-	readonly model: TModel;
-	readonly inject?: TInject;
-	readonly access?: Partial<Record<"list" | "get" | "create" | "update" | "delete" | Extract<keyof NoInfer<TActions>, string>, AccessRule>>;
-	readonly before?: {
-		readonly create?: (data: TModel["table"]["$create_input"], ctx: EntityContext<TModel, TInject>) => TModel["table"]["$create_input"] | Promise<TModel["table"]["$create_input"]>;
-		readonly update?: (data: TModel["table"]["$update_input"], ctx: EntityContext<TModel, TInject>) => TModel["table"]["$update_input"] | Promise<TModel["table"]["$update_input"]>;
-	};
-	readonly after?: {
-		readonly create?: (result: TModel["table"]["$response"], ctx: EntityContext<TModel, TInject>) => void | Promise<void>;
-		readonly update?: (prev: TModel["table"]["$response"], next: TModel["table"]["$response"], ctx: EntityContext<TModel, TInject>) => void | Promise<void>;
-		readonly delete?: (row: TModel["table"]["$response"], ctx: EntityContext<TModel, TInject>) => void | Promise<void>;
-	};
-	readonly actions?: { readonly [K in keyof TActions] : TActions[K] };
-	readonly relations?: EntityRelationsConfig<TModel["relations"]>;
+interface PlanStore {
+	/**
+	* Assign a plan to an org. Resets per-customer overrides (overrides are plan-specific).
+	* To preserve overrides across plan changes, re-apply them after calling assignPlan().
+	*/
+	assignPlan(orgId: string, planId: string, startedAt?: Date, expiresAt?: Date | null): Promise<void>;
+	getPlan(orgId: string): Promise<OrgPlan | null>;
+	updateOverrides(orgId: string, overrides: Record<string, LimitOverride>): Promise<void>;
+	removePlan(orgId: string): Promise<void>;
+	dispose(): void;
 }
-interface EntityDefinition<TModel extends ModelDef2 = ModelDef2> {
-	readonly kind: "entity";
-	readonly name: string;
-	readonly model: TModel;
-	readonly inject: Record<string, EntityDefinition>;
-	readonly access: Partial<Record<string, AccessRule>>;
-	readonly before: EntityBeforeHooks;
-	readonly after: EntityAfterHooks;
-	readonly actions: Record<string, EntityActionDef>;
-	readonly relations: EntityRelationsConfig<TModel["relations"]>;
+declare class InMemoryPlanStore implements PlanStore {
+	private plans;
+	assignPlan(orgId: string, planId: string, startedAt?: Date, expiresAt?: Date | null): Promise<void>;
+	getPlan(orgId: string): Promise<OrgPlan | null>;
+	updateOverrides(orgId: string, overrides: Record<string, LimitOverride>): Promise<void>;
+	removePlan(orgId: string): Promise<void>;
+	dispose(): void;
 }
-import { SchemaLike as SchemaLike2 } from "@vertz/db";
-/** Extracts the model type from an EntityDefinition */
-type ExtractModel2<T> = T extends EntityDefinition<infer M> ? M : never;
 /**
-* Maps an inject config `{ key: EntityDefinition<TModel> }` to
-* `{ key: EntityOperations<TModel> }` for typed ctx.entities access.
+* WalletStore — consumption tracking for plan-limited entitlements.
+*
+* Tracks per-org usage within billing periods with atomic
+* check-and-increment operations.
 */
-type InjectToOperations2<TInject extends Record<string, EntityDefinition> = {}> = { readonly [K in keyof TInject] : EntityOperations<ExtractModel2<TInject[K]>> };
-interface ActionContext<TInject extends Record<string, EntityDefinition> = {}> extends BaseContext {
-	/** Typed access to injected entities only */
-	readonly entities: InjectToOperations2<TInject>;
+interface WalletEntry {
+	orgId: string;
+	entitlement: string;
+	periodStart: Date;
+	periodEnd: Date;
+	consumed: number;
 }
-interface ActionActionDef<
-	TInput = unknown,
-	TOutput = unknown,
-	TCtx extends ActionContext = ActionContext
-> {
-	readonly method?: string;
-	readonly path?: string;
-	readonly body: SchemaLike2<TInput>;
-	readonly response: SchemaLike2<TOutput>;
-	readonly handler: (input: TInput, ctx: TCtx) => Promise<TOutput>;
+interface ConsumeResult {
+	success: boolean;
+	consumed: number;
+	limit: number;
+	remaining: number;
 }
-interface ActionConfig<
-	TActions extends Record<string, ActionActionDef<any, any, any>> = Record<string, ActionActionDef<any, any, any>>,
-	TInject extends Record<string, EntityDefinition> = {}
-> {
-	readonly inject?: TInject;
-	readonly access?: Partial<Record<Extract<keyof NoInfer<TActions>, string>, AccessRule>>;
-	readonly actions: { readonly [K in keyof TActions] : TActions[K] };
+interface WalletStore {
+	consume(orgId: string, entitlement: string, periodStart: Date, periodEnd: Date, limit: number, amount?: number): Promise<ConsumeResult>;
+	unconsume(orgId: string, entitlement: string, periodStart: Date, periodEnd: Date, amount?: number): Promise<void>;
+	getConsumption(orgId: string, entitlement: string, periodStart: Date, periodEnd: Date): Promise<number>;
+	dispose(): void;
 }
-interface ActionDefinition {
-	readonly kind: "action";
-	readonly name: string;
-	readonly inject: Record<string, EntityDefinition>;
-	readonly access: Partial<Record<string, AccessRule>>;
-	readonly actions: Record<string, ActionActionDef>;
+declare class InMemoryWalletStore implements WalletStore {
+	private entries;
+	private key;
+	consume(orgId: string, entitlement: string, periodStart: Date, periodEnd: Date, limit: number, amount?: number): Promise<ConsumeResult>;
+	unconsume(orgId: string, entitlement: string, periodStart: Date, _periodEnd: Date, amount?: number): Promise<void>;
+	getConsumption(orgId: string, entitlement: string, periodStart: Date, _periodEnd: Date): Promise<number>;
+	dispose(): void;
 }
-declare function action<
-	TInject extends Record<string, EntityDefinition> = {},
-	TActions extends Record<string, ActionActionDef<any, any, any>> = Record<string, ActionActionDef<any, any, any>>
->(name: string, config: ActionConfig<TActions, TInject>): ActionDefinition;
-import { AuthValidationError } from "@vertz/errors";
-import { AuthError, Result as Result2 } from "@vertz/errors";
+interface ResourceRef {
+	type: string;
+	id: string;
+}
+interface AccessContextConfig {
+	userId: string | null;
+	accessDef: AccessDefinition;
+	closureStore: ClosureStore;
+	roleStore: RoleAssignmentStore;
+	/** Factor verification age — seconds since last MFA. undefined if no MFA done. */
+	fva?: number;
+	/** Flag store — required for Layer 1 feature flag checks */
+	flagStore?: FlagStore;
+	/** Plan store — required for Layer 4 plan checks */
+	planStore?: PlanStore;
+	/** Wallet store — required for Layer 5 wallet checks and canAndConsume() */
+	walletStore?: WalletStore;
+	/** Resolves an org ID from a resource. Required for plan/wallet checks. */
+	orgResolver?: (resource?: ResourceRef) => Promise<string | null>;
+}
+interface AccessContext {
+	can(entitlement: string, resource?: ResourceRef): Promise<boolean>;
+	check(entitlement: string, resource?: ResourceRef): Promise<AccessCheckResult>;
+	authorize(entitlement: string, resource?: ResourceRef): Promise<void>;
+	canAll(checks: Array<{
+		entitlement: string;
+		resource?: ResourceRef;
+	}>): Promise<Map<string, boolean>>;
+	/** Atomic check + consume. Runs full can() then increments wallet if all layers pass. */
+	canAndConsume(entitlement: string, resource?: ResourceRef, amount?: number): Promise<boolean>;
+	/** Rollback a previous canAndConsume(). Use when the operation fails after consumption. */
+	unconsume(entitlement: string, resource?: ResourceRef, amount?: number): Promise<void>;
+}
+declare function createAccessContext(config: AccessContextConfig): AccessContext;
+interface AccessCheckData {
+	allowed: boolean;
+	reasons: DenialReason[];
+	reason?: DenialReason;
+	meta?: DenialMeta;
+}
+interface AccessSet {
+	entitlements: Record<string, AccessCheckData>;
+	flags: Record<string, boolean>;
+	plan: string | null;
+	computedAt: string;
+}
+interface ComputeAccessSetConfig {
+	userId: string | null;
+	accessDef: AccessDefinition;
+	roleStore: RoleAssignmentStore;
+	closureStore: ClosureStore;
+	plan?: string | null;
+	/** Flag store — for feature flag state in access set */
+	flagStore?: FlagStore;
+	/** Plan store — for limit info in access set */
+	planStore?: PlanStore;
+	/** Wallet store — for consumption info in access set */
+	walletStore?: WalletStore;
+	/** Org resolver — for plan/wallet lookups */
+	orgResolver?: (resource?: ResourceRef) => Promise<string | null>;
+	/** Org ID — direct org ID for global access set (bypass orgResolver) */
+	orgId?: string | null;
+}
+declare function computeAccessSet(config: ComputeAccessSetConfig): Promise<AccessSet>;
+/** Sparse encoding for JWT. Only includes allowed + denied-with-meta entries. */
+interface EncodedAccessSet {
+	entitlements: Record<string, EncodedAccessCheckData>;
+	flags: Record<string, boolean>;
+	plan: string | null;
+	computedAt: string;
+}
+interface EncodedAccessCheckData {
+	allowed: boolean;
+	reasons?: DenialReason[];
+	reason?: DenialReason;
+	meta?: DenialMeta;
+}
+/**
+* Encode an AccessSet for JWT embedding.
+* Sparse: only includes allowed entitlements and denied entries with meta.
+* Strips requiredRoles and requiredPlans from meta (organizational info).
+*/
+declare function encodeAccessSet(set: AccessSet): EncodedAccessSet;
+/**
+* Decode a sparse encoded AccessSet back to full form.
+* Missing entitlements default to denied with 'role_required'.
+*/
+declare function decodeAccessSet(encoded: EncodedAccessSet, accessDef: AccessDefinition): AccessSet;
 type SessionStrategy = "jwt" | "database" | "hybrid";
 interface CookieConfig {
 	name?: string;
@@ -174,8 +322,10 @@ interface CookieConfig {
 interface SessionConfig {
 	strategy: SessionStrategy;
 	ttl: string | number;
+	refreshTtl?: string | number;
 	refreshable?: boolean;
 	cookie?: CookieConfig;
+	refreshName?: string;
 }
 interface PasswordRequirements {
 	minLength?: number;
@@ -192,11 +342,168 @@ interface RateLimitConfig {
 	window: string;
 	maxAttempts: number;
 }
+interface SessionStore {
+	createSessionWithId(id: string, data: {
+		userId: string;
+		refreshTokenHash: string;
+		ipAddress: string;
+		userAgent: string;
+		expiresAt: Date;
+		currentTokens?: AuthTokens;
+	}): Promise<StoredSession>;
+	findByRefreshHash(hash: string): Promise<StoredSession | null>;
+	findByPreviousRefreshHash(hash: string): Promise<StoredSession | null>;
+	revokeSession(id: string): Promise<void>;
+	listActiveSessions(userId: string): Promise<StoredSession[]>;
+	countActiveSessions(userId: string): Promise<number>;
+	getCurrentTokens(sessionId: string): Promise<AuthTokens | null>;
+	updateSession(id: string, data: {
+		refreshTokenHash: string;
+		previousRefreshHash: string;
+		lastActiveAt: Date;
+		currentTokens?: AuthTokens;
+	}): Promise<void>;
+	dispose(): void;
+}
+interface StoredSession {
+	id: string;
+	userId: string;
+	refreshTokenHash: string;
+	previousRefreshHash: string | null;
+	ipAddress: string;
+	userAgent: string;
+	createdAt: Date;
+	lastActiveAt: Date;
+	expiresAt: Date;
+	revokedAt: Date | null;
+}
+interface RateLimitStore {
+	check(key: string, maxAttempts: number, windowMs: number): Promise<RateLimitResult>;
+	dispose(): void;
+}
+interface UserStore {
+	createUser(user: AuthUser, passwordHash: string | null): Promise<void>;
+	findByEmail(email: string): Promise<{
+		user: AuthUser;
+		passwordHash: string | null;
+	} | null>;
+	findById(id: string): Promise<AuthUser | null>;
+	updatePasswordHash(userId: string, passwordHash: string): Promise<void>;
+	updateEmailVerified(userId: string, verified: boolean): Promise<void>;
+}
+interface MfaConfig {
+	enabled?: boolean;
+	issuer?: string;
+	backupCodeCount?: number;
+}
+interface MFAStore {
+	enableMfa(userId: string, encryptedSecret: string): Promise<void>;
+	disableMfa(userId: string): Promise<void>;
+	getSecret(userId: string): Promise<string | null>;
+	isMfaEnabled(userId: string): Promise<boolean>;
+	setBackupCodes(userId: string, hashedCodes: string[]): Promise<void>;
+	getBackupCodes(userId: string): Promise<string[]>;
+	consumeBackupCode(userId: string, hashedCode: string): Promise<void>;
+	dispose(): void;
+}
+interface MfaSetupData {
+	secret: string;
+	uri: string;
+}
+interface MfaChallengeData {
+	userId: string;
+	sessionId?: string;
+	expiresAt: number;
+}
+interface OAuthProviderConfig {
+	clientId: string;
+	clientSecret: string;
+	redirectUrl?: string;
+	scopes?: string[];
+}
+interface OAuthTokens {
+	accessToken: string;
+	refreshToken?: string;
+	expiresIn?: number;
+	idToken?: string;
+}
+interface OAuthUserInfo {
+	providerId: string;
+	email: string;
+	emailVerified: boolean;
+	name?: string;
+	avatarUrl?: string;
+}
+interface OAuthProvider {
+	id: string;
+	name: string;
+	scopes: string[];
+	trustEmail: boolean;
+	getAuthorizationUrl: (state: string, codeChallenge?: string, nonce?: string) => string;
+	exchangeCode: (code: string, codeVerifier?: string) => Promise<OAuthTokens>;
+	getUserInfo: (accessToken: string, idToken?: string, nonce?: string) => Promise<OAuthUserInfo>;
+}
+interface OAuthAccountStore {
+	linkAccount(userId: string, provider: string, providerId: string, email?: string): Promise<void>;
+	findByProviderAccount(provider: string, providerId: string): Promise<string | null>;
+	findByUserId(userId: string): Promise<{
+		provider: string;
+		providerId: string;
+	}[]>;
+	unlinkAccount(userId: string, provider: string): Promise<void>;
+	dispose(): void;
+}
+interface EmailVerificationConfig {
+	enabled: boolean;
+	tokenTtl?: string | number;
+	onSend: (user: AuthUser, token: string) => Promise<void>;
+}
+interface StoredEmailVerification {
+	id: string;
+	userId: string;
+	tokenHash: string;
+	expiresAt: Date;
+	createdAt: Date;
+}
+interface EmailVerificationStore {
+	createVerification(data: {
+		userId: string;
+		tokenHash: string;
+		expiresAt: Date;
+	}): Promise<StoredEmailVerification>;
+	findByTokenHash(tokenHash: string): Promise<StoredEmailVerification | null>;
+	deleteByUserId(userId: string): Promise<void>;
+	deleteByTokenHash(tokenHash: string): Promise<void>;
+	dispose(): void;
+}
+interface PasswordResetConfig {
+	enabled: boolean;
+	tokenTtl?: string | number;
+	revokeSessionsOnReset?: boolean;
+	onSend: (user: AuthUser, token: string) => Promise<void>;
+}
+interface StoredPasswordReset {
+	id: string;
+	userId: string;
+	tokenHash: string;
+	expiresAt: Date;
+	createdAt: Date;
+}
+interface PasswordResetStore {
+	createReset(data: {
+		userId: string;
+		tokenHash: string;
+		expiresAt: Date;
+	}): Promise<StoredPasswordReset>;
+	findByTokenHash(tokenHash: string): Promise<StoredPasswordReset | null>;
+	deleteByUserId(userId: string): Promise<void>;
+	dispose(): void;
+}
 interface AuthConfig {
 	session: SessionConfig;
 	emailPassword?: EmailPasswordConfig;
 	jwtSecret?: string;
-	jwtAlgorithm?: "HS256" | "HS384" | "HS512" | "RS256";
+	jwtAlgorithm?: "HS256" | "HS384" | "HS512";
 	/** Custom claims function for JWT payload */
 	claims?: (user: AuthUser) => Record<string, unknown>;
 	/**
@@ -211,12 +518,50 @@ interface AuthConfig {
 	* Only used in non-production mode when jwtSecret is not provided.
 	*/
 	devSecretPath?: string;
+	/** Pluggable session store — defaults to InMemorySessionStore */
+	sessionStore?: SessionStore;
+	/** Pluggable rate limit store — defaults to InMemoryRateLimitStore */
+	rateLimitStore?: RateLimitStore;
+	/** Pluggable user store — defaults to InMemoryUserStore */
+	userStore?: UserStore;
+	/** OAuth provider instances */
+	providers?: OAuthProvider[];
+	/** Pluggable OAuth account store — required when providers are configured */
+	oauthAccountStore?: OAuthAccountStore;
+	/** Encryption key for OAuth state cookies — required when providers are configured */
+	oauthEncryptionKey?: string;
+	/** Redirect URL after successful OAuth (default '/') */
+	oauthSuccessRedirect?: string;
+	/** Redirect URL on OAuth error (default '/auth/error') */
+	oauthErrorRedirect?: string;
+	/** MFA configuration */
+	mfa?: MfaConfig;
+	/** Pluggable MFA store — defaults to InMemoryMFAStore */
+	mfaStore?: MFAStore;
+	/** Email verification configuration */
+	emailVerification?: EmailVerificationConfig;
+	/** Pluggable email verification store — defaults to InMemoryEmailVerificationStore */
+	emailVerificationStore?: EmailVerificationStore;
+	/** Password reset configuration */
+	passwordReset?: PasswordResetConfig;
+	/** Pluggable password reset store — defaults to InMemoryPasswordResetStore */
+	passwordResetStore?: PasswordResetStore;
+	/** Access control configuration — enables ACL claim in JWT */
+	access?: AuthAccessConfig;
+}
+/** Access control configuration for JWT acl claim computation. */
+interface AuthAccessConfig {
+	definition: AccessDefinition;
+	roleStore: RoleAssignmentStore;
+	closureStore: ClosureStore;
+	flagStore?: FlagStore;
 }
 interface AuthUser {
 	id: string;
 	email: string;
 	role: string;
 	plan?: string;
+	emailVerified?: boolean;
 	createdAt: Date;
 	updatedAt: Date;
 	[key: string]: unknown;
@@ -227,12 +572,41 @@ interface SessionPayload {
 	role: string;
 	iat: number;
 	exp: number;
+	jti: string;
+	sid: string;
 	claims?: Record<string, unknown>;
+	fva?: number;
+	acl?: AclClaim;
+}
+/** JWT acl claim — embedded access set with overflow strategy. */
+interface AclClaim {
+	/** Full sparse set when fits within 2KB budget */
+	set?: EncodedAccessSet;
+	/** SHA-256 hex of canonical JSON — always present */
+	hash: string;
+	/** True when set omitted due to size */
+	overflow: boolean;
+}
+interface AuthTokens {
+	jwt: string;
+	refreshToken: string;
 }
 interface Session {
 	user: AuthUser;
 	expiresAt: Date;
 	payload: SessionPayload;
+	tokens?: AuthTokens;
+}
+interface SessionInfo {
+	id: string;
+	userId: string;
+	ipAddress: string;
+	userAgent: string;
+	deviceName: string;
+	createdAt: Date;
+	lastActiveAt: Date;
+	expiresAt: Date;
+	isCurrent: boolean;
 }
 interface SignUpInput {
 	email: string;
@@ -245,11 +619,22 @@ interface SignInInput {
 	password: string;
 }
 interface AuthApi {
-	signUp: (data: SignUpInput) => Promise<Result2<Session, AuthError>>;
-	signIn: (data: SignInInput) => Promise<Result2<Session, AuthError>>;
-	signOut: (ctx: AuthContext) => Promise<Result2<void, AuthError>>;
-	getSession: (headers: Headers) => Promise<Result2<Session | null, AuthError>>;
-	refreshSession: (ctx: AuthContext) => Promise<Result2<Session, AuthError>>;
+	signUp: (data: SignUpInput, ctx?: {
+		headers: Headers;
+	}) => Promise<Result<Session, AuthError>>;
+	signIn: (data: SignInInput, ctx?: {
+		headers: Headers;
+	}) => Promise<Result<Session, AuthError>>;
+	signOut: (ctx: {
+		headers: Headers;
+	}) => Promise<Result<void, AuthError>>;
+	getSession: (headers: Headers) => Promise<Result<Session | null, AuthError>>;
+	refreshSession: (ctx: {
+		headers: Headers;
+	}) => Promise<Result<Session, AuthError>>;
+	listSessions: (headers: Headers) => Promise<Result<SessionInfo[], AuthError>>;
+	revokeSession: (sessionId: string, headers: Headers) => Promise<Result<void, AuthError>>;
+	revokeAllSessions: (headers: Headers) => Promise<Result<void, AuthError>>;
 }
 interface AuthInstance {
 	/** HTTP handler for auth routes */
@@ -257,9 +642,11 @@ interface AuthInstance {
 	/** Server-side API */
 	api: AuthApi;
 	/** Session middleware that injects ctx.user */
-	middleware: () => any;
+	middleware: () => (ctx: Record<string, unknown>, next: () => Promise<void>) => Promise<void>;
 	/** Initialize auth (create tables, etc.) */
 	initialize: () => Promise<void>;
+	/** Dispose stores and cleanup intervals */
+	dispose: () => void;
 }
 interface AuthContext {
 	headers: Headers;
@@ -271,6 +658,51 @@ interface RateLimitResult {
 	remaining: number;
 	resetAt: Date;
 }
+interface UserTableEntry extends ModelEntry<any, any> {
+	table: {
+		id: {
+			type: string;
+		};
+		email: {
+			type: string;
+		};
+		passwordHash: {
+			type: string;
+		};
+		role: {
+			type: string;
+		};
+		plan?: {
+			type: string;
+		};
+		createdAt: {
+			type: Date;
+		};
+		updatedAt: {
+			type: Date;
+		};
+	};
+}
+interface RoleAssignmentTableEntry extends ModelEntry<any, any> {
+	table: {
+		id: {
+			type: string;
+		};
+		userId: {
+			type: string;
+		};
+		role: {
+			type: string;
+		};
+		createdAt: {
+			type: Date;
+		};
+	};
+}
+import { AuthValidationError } from "@vertz/errors";
+declare function hashPassword(password: string): Promise<string>;
+declare function verifyPassword(password: string, hash: string): Promise<boolean>;
+declare function validatePassword(password: string, requirements?: PasswordRequirements): AuthValidationError | null;
 type Entitlement = string;
 interface RoleDefinition {
 	entitlements: Entitlement[];
@@ -316,17 +748,426 @@ declare class AuthorizationError extends Error {
 }
 declare function createAccess(config: AccessConfig): AccessInstance;
 declare const defaultAccess: AccessInstance;
-declare function hashPassword(password: string): Promise<string>;
-declare function verifyPassword(password: string, hash: string): Promise<boolean>;
-declare function validatePassword(password: string, requirements?: PasswordRequirements): AuthValidationError | null;
+type AccessEvent = {
+	type: "access:flag_toggled";
+	orgId: string;
+	flag: string;
+	enabled: boolean;
+} | {
+	type: "access:limit_updated";
+	orgId: string;
+	entitlement: string;
+	consumed: number;
+	remaining: number;
+	max: number;
+} | {
+	type: "access:role_changed";
+	userId: string;
+} | {
+	type: "access:plan_changed";
+	orgId: string;
+};
+interface AccessWsData {
+	userId: string;
+	orgId: string;
+}
+interface AccessEventBroadcasterConfig {
+	jwtSecret: string;
+	jwtAlgorithm?: string;
+	/** WebSocket upgrade path. Defaults to '/api/auth/access-events'. */
+	path?: string;
+	/** Cookie name for session JWT. Defaults to 'vertz.sid'. */
+	cookieName?: string;
+}
+interface AccessEventBroadcaster {
+	handleUpgrade(request: Request, server: BunServer): Promise<boolean>;
+	websocket: {
+		open(ws: BunWebSocket<AccessWsData>): void;
+		message(ws: BunWebSocket<AccessWsData>, msg: string | Buffer): void;
+		close(ws: BunWebSocket<AccessWsData>): void;
+	};
+	broadcastFlagToggle(orgId: string, flag: string, enabled: boolean): void;
+	broadcastLimitUpdate(orgId: string, entitlement: string, consumed: number, remaining: number, max: number): void;
+	broadcastRoleChange(userId: string): void;
+	broadcastPlanChange(orgId: string): void;
+	getConnectionCount: number;
+}
+/** Minimal Bun.Server interface for WebSocket upgrade */
+interface BunServer {
+	upgrade(request: Request, options?: {
+		data?: AccessWsData;
+	}): boolean;
+}
+/** Minimal Bun.ServerWebSocket interface */
+interface BunWebSocket<T> {
+	data: T;
+	send(data: string): void;
+	close(): void;
+	ping(): void;
+}
+declare function createAccessEventBroadcaster(config: AccessEventBroadcasterConfig): AccessEventBroadcaster;
+interface Period {
+	periodStart: Date;
+	periodEnd: Date;
+}
+/**
+* Calculate the billing period that contains `now`, anchored to `startedAt`.
+*
+* For 'month': walks from startedAt adding 1 month at a time until we find
+* the period containing now. For 'day'/'hour': uses fixed-duration periods.
+*/
+declare function calculateBillingPeriod(startedAt: Date, per: BillingPeriod, now?: Date): Period;
+declare class InMemoryEmailVerificationStore implements EmailVerificationStore {
+	private byId;
+	private byTokenHash;
+	private byUserId;
+	createVerification(data: {
+		userId: string;
+		tokenHash: string;
+		expiresAt: Date;
+	}): Promise<StoredEmailVerification>;
+	findByTokenHash(tokenHash: string): Promise<StoredEmailVerification | null>;
+	deleteByUserId(userId: string): Promise<void>;
+	deleteByTokenHash(tokenHash: string): Promise<void>;
+	dispose(): void;
+}
+/**
+* Compute access metadata for a specific entity.
+*
+* @param entitlements - Entitlement names to check
+* @param entity - The resource to check against
+* @param accessContext - The server-side access context
+* @returns Record of entitlement name to AccessCheckData (client-compatible shape)
+*/
+declare function computeEntityAccess(entitlements: string[], entity: {
+	type: string;
+	id: string;
+}, accessContext: AccessContext): Promise<Record<string, AccessCheckData>>;
+/**
+* Check if the session's factor verification is still fresh.
+* Returns true if `fva` exists and (now - fva) < maxAgeSeconds.
+*/
+declare function checkFva(payload: SessionPayload, maxAgeSeconds: number): boolean;
+declare class InMemoryMFAStore implements MFAStore {
+	private secrets;
+	private backupCodes;
+	private enabled;
+	enableMfa(userId: string, encryptedSecret: string): Promise<void>;
+	disableMfa(userId: string): Promise<void>;
+	getSecret(userId: string): Promise<string | null>;
+	isMfaEnabled(userId: string): Promise<boolean>;
+	setBackupCodes(userId: string, hashedCodes: string[]): Promise<void>;
+	getBackupCodes(userId: string): Promise<string[]>;
+	consumeBackupCode(userId: string, hashedCode: string): Promise<void>;
+	dispose(): void;
+}
+declare class InMemoryOAuthAccountStore implements OAuthAccountStore {
+	private byProviderAccount;
+	private byUserId;
+	private providerKey;
+	linkAccount(userId: string, provider: string, providerId: string, email?: string): Promise<void>;
+	findByProviderAccount(provider: string, providerId: string): Promise<string | null>;
+	findByUserId(userId: string): Promise<{
+		provider: string;
+		providerId: string;
+	}[]>;
+	unlinkAccount(userId: string, provider: string): Promise<void>;
+	dispose(): void;
+}
+declare class InMemoryPasswordResetStore implements PasswordResetStore {
+	private byId;
+	private byTokenHash;
+	private byUserId;
+	createReset(data: {
+		userId: string;
+		tokenHash: string;
+		expiresAt: Date;
+	}): Promise<StoredPasswordReset>;
+	findByTokenHash(tokenHash: string): Promise<StoredPasswordReset | null>;
+	deleteByUserId(userId: string): Promise<void>;
+	dispose(): void;
+}
+declare function discord(config: OAuthProviderConfig): OAuthProvider;
+declare function github(config: OAuthProviderConfig): OAuthProvider;
+declare function google(config: OAuthProviderConfig): OAuthProvider;
+declare class InMemoryRateLimitStore implements RateLimitStore {
+	private store;
+	private cleanupTimer;
+	constructor();
+	check(key: string, maxAttempts: number, windowMs: number): Promise<RateLimitResult>;
+	dispose(): void;
+	private cleanup;
+}
+/**
+* rules.* builders — declarative access rule data structures.
+*
+* These are pure data structures with no evaluation logic.
+* The access context evaluates them at runtime (sub-phase 4).
+*/
+interface RoleRule {
+	readonly type: "role";
+	readonly roles: readonly string[];
+}
+interface EntitlementRule {
+	readonly type: "entitlement";
+	readonly entitlement: string;
+}
+interface WhereRule {
+	readonly type: "where";
+	readonly conditions: Record<string, unknown>;
+}
+interface AllRule {
+	readonly type: "all";
+	readonly rules: readonly AccessRule[];
+}
+interface AnyRule {
+	readonly type: "any";
+	readonly rules: readonly AccessRule[];
+}
+interface AuthenticatedRule {
+	readonly type: "authenticated";
+}
+interface FvaRule {
+	readonly type: "fva";
+	readonly maxAge: number;
+}
+type AccessRule = RoleRule | EntitlementRule | WhereRule | AllRule | AnyRule | AuthenticatedRule | FvaRule;
+interface UserMarker {
+	readonly __marker: string;
+}
+declare const rules: {
+	/** User has at least one of the specified roles (OR) */
+	role(...roleNames: string[]): RoleRule;
+	/** User has the specified entitlement (resolves role+plan+flag from defineAccess config) */
+	entitlement(name: string): EntitlementRule;
+	/** Row-level condition — DB query syntax. Use rules.user.id for dynamic user markers */
+	where(conditions: Record<string, unknown>): WhereRule;
+	/** All sub-rules must pass (AND) */
+	all(...ruleList: AccessRule[]): AllRule;
+	/** At least one sub-rule must pass (OR) */
+	any(...ruleList: AccessRule[]): AnyRule;
+	/** User must be authenticated (no specific role required) */
+	authenticated(): AuthenticatedRule;
+	/** User must have verified MFA within maxAge seconds */
+	fva(maxAge: number): FvaRule;
+	/** Declarative user markers — resolved at evaluation time */
+	user: {
+		readonly id: UserMarker;
+		readonly tenantId: UserMarker;
+	};
+};
+declare class InMemorySessionStore implements SessionStore {
+	private sessions;
+	private currentTokens;
+	private cleanupTimer;
+	private maxSessionsPerUser;
+	constructor(maxSessionsPerUser?: number);
+	createSession(data: {
+		userId: string;
+		refreshTokenHash: string;
+		ipAddress: string;
+		userAgent: string;
+		expiresAt: Date;
+	}): Promise<StoredSession>;
+	createSessionWithId(id: string, data: {
+		userId: string;
+		refreshTokenHash: string;
+		ipAddress: string;
+		userAgent: string;
+		expiresAt: Date;
+		currentTokens?: AuthTokens;
+	}): Promise<StoredSession>;
+	findByRefreshHash(hash: string): Promise<StoredSession | null>;
+	findByPreviousRefreshHash(hash: string): Promise<StoredSession | null>;
+	revokeSession(id: string): Promise<void>;
+	listActiveSessions(userId: string): Promise<StoredSession[]>;
+	countActiveSessions(userId: string): Promise<number>;
+	getCurrentTokens(sessionId: string): Promise<AuthTokens | null>;
+	updateSession(id: string, data: {
+		refreshTokenHash: string;
+		previousRefreshHash: string;
+		lastActiveAt: Date;
+		currentTokens?: AuthTokens;
+	}): Promise<void>;
+	dispose(): void;
+	private cleanup;
+}
+declare class InMemoryUserStore implements UserStore {
+	private byEmail;
+	private byId;
+	createUser(user: AuthUser, passwordHash: string | null): Promise<void>;
+	findByEmail(email: string): Promise<{
+		user: AuthUser;
+		passwordHash: string | null;
+	} | null>;
+	findById(id: string): Promise<AuthUser | null>;
+	updatePasswordHash(userId: string, passwordHash: string): Promise<void>;
+	updateEmailVerified(userId: string, verified: boolean): Promise<void>;
+}
 declare function createAuth(config: AuthConfig): AuthInstance;
 import { AppBuilder, AppConfig } from "@vertz/core";
 import { DatabaseClient, EntityDbAdapter as EntityDbAdapter3, ModelEntry as ModelEntry2 } from "@vertz/db";
+import { ModelDef as ModelDef2, RelationDef, SchemaLike, TableDef } from "@vertz/db";
+import { ModelDef } from "@vertz/db";
+import { EntityDbAdapter, ListOptions } from "@vertz/db";
+import { EntityError, Result as Result2 } from "@vertz/errors";
+import { EntityDbAdapter as EntityDbAdapter2, ListOptions as ListOptions2 } from "@vertz/db";
+interface ListResult<T = Record<string, unknown>> {
+	items: T[];
+	total: number;
+	limit: number;
+	nextCursor: string | null;
+	hasNextPage: boolean;
+}
+interface CrudResult<T = unknown> {
+	status: number;
+	body: T;
+}
+interface CrudHandlers {
+	list(ctx: EntityContext, options?: ListOptions): Promise<Result2<CrudResult<ListResult>, EntityError>>;
+	get(ctx: EntityContext, id: string): Promise<Result2<CrudResult<Record<string, unknown>>, EntityError>>;
+	create(ctx: EntityContext, data: Record<string, unknown>): Promise<Result2<CrudResult<Record<string, unknown>>, EntityError>>;
+	update(ctx: EntityContext, id: string, data: Record<string, unknown>): Promise<Result2<CrudResult<Record<string, unknown>>, EntityError>>;
+	delete(ctx: EntityContext, id: string): Promise<Result2<CrudResult<null>, EntityError>>;
+}
+declare function createCrudHandlers(def: EntityDefinition, db: EntityDbAdapter): CrudHandlers;
+/**
+* EntityOperations — typed CRUD facade for a single entity.
+*
+* When used as `ctx.entity`, TModel fills in actual column types.
+* When used as `ctx.entities.*`, TModel defaults to `ModelDef` (loose typing).
+*/
+interface EntityOperations<TModel extends ModelDef = ModelDef> {
+	get(id: string): Promise<TModel["table"]["$response"]>;
+	list(options?: ListOptions2): Promise<ListResult<TModel["table"]["$response"]>>;
+	create(data: TModel["table"]["$create_input"]): Promise<TModel["table"]["$response"]>;
+	update(id: string, data: TModel["table"]["$update_input"]): Promise<TModel["table"]["$response"]>;
+	delete(id: string): Promise<void>;
+}
+/** Extracts the model type from an EntityDefinition */
+type ExtractModel<T> = T extends EntityDefinition<infer M> ? M : ModelDef2;
+/**
+* Maps an inject config `{ key: EntityDefinition<TModel> }` to
+* `{ key: EntityOperations<TModel> }` for typed ctx.entities access.
+*/
+type InjectToOperations<TInject extends Record<string, EntityDefinition> = {}> = { readonly [K in keyof TInject] : EntityOperations<ExtractModel<TInject[K]>> };
+interface BaseContext {
+	readonly userId: string | null;
+	authenticated(): boolean;
+	tenant(): boolean;
+	role(...roles: string[]): boolean;
+}
+interface EntityContext<
+	TModel extends ModelDef2 = ModelDef2,
+	TInject extends Record<string, EntityDefinition> = {}
+> extends BaseContext {
+	/** Typed CRUD on the current entity */
+	readonly entity: EntityOperations<TModel>;
+	/** Typed access to injected entities only */
+	readonly entities: InjectToOperations<TInject>;
+}
+type AccessRule2 = false | ((ctx: BaseContext, row: Record<string, unknown>) => boolean | Promise<boolean>);
+interface EntityBeforeHooks<
+	TCreateInput = unknown,
+	TUpdateInput = unknown
+> {
+	readonly create?: (data: TCreateInput, ctx: EntityContext) => TCreateInput | Promise<TCreateInput>;
+	readonly update?: (data: TUpdateInput, ctx: EntityContext) => TUpdateInput | Promise<TUpdateInput>;
+}
+interface EntityAfterHooks<TResponse = unknown> {
+	readonly create?: (result: TResponse, ctx: EntityContext) => void | Promise<void>;
+	readonly update?: (prev: TResponse, next: TResponse, ctx: EntityContext) => void | Promise<void>;
+	readonly delete?: (row: TResponse, ctx: EntityContext) => void | Promise<void>;
+}
+interface EntityActionDef<
+	TInput = unknown,
+	TOutput = unknown,
+	TResponse = unknown,
+	TCtx extends EntityContext = EntityContext
+> {
+	readonly method?: string;
+	readonly path?: string;
+	readonly body: SchemaLike<TInput>;
+	readonly response: SchemaLike<TOutput>;
+	readonly handler: (input: TInput, ctx: TCtx, row: TResponse | null) => Promise<TOutput>;
+}
+/** Extract column keys from a RelationDef's target table. */
+type RelationColumnKeys<R> = R extends RelationDef<infer TTarget> ? TTarget extends TableDef<infer TCols> ? Extract<keyof TCols, string> : string : string;
+type EntityRelationsConfig<TRelations extends Record<string, RelationDef> = Record<string, RelationDef>> = { [K in keyof TRelations]? : true | false | { [F in RelationColumnKeys<TRelations[K]>]? : true } };
+interface EntityConfig<
+	TModel extends ModelDef2 = ModelDef2,
+	TActions extends Record<string, EntityActionDef<any, any, any, any>> = {},
+	TInject extends Record<string, EntityDefinition> = {}
+> {
+	readonly model: TModel;
+	readonly inject?: TInject;
+	readonly access?: Partial<Record<"list" | "get" | "create" | "update" | "delete" | Extract<keyof NoInfer<TActions>, string>, AccessRule2>>;
+	readonly before?: {
+		readonly create?: (data: TModel["table"]["$create_input"], ctx: EntityContext<TModel, TInject>) => TModel["table"]["$create_input"] | Promise<TModel["table"]["$create_input"]>;
+		readonly update?: (data: TModel["table"]["$update_input"], ctx: EntityContext<TModel, TInject>) => TModel["table"]["$update_input"] | Promise<TModel["table"]["$update_input"]>;
+	};
+	readonly after?: {
+		readonly create?: (result: TModel["table"]["$response"], ctx: EntityContext<TModel, TInject>) => void | Promise<void>;
+		readonly update?: (prev: TModel["table"]["$response"], next: TModel["table"]["$response"], ctx: EntityContext<TModel, TInject>) => void | Promise<void>;
+		readonly delete?: (row: TModel["table"]["$response"], ctx: EntityContext<TModel, TInject>) => void | Promise<void>;
+	};
+	readonly actions?: { readonly [K in keyof TActions] : TActions[K] };
+	readonly relations?: EntityRelationsConfig<TModel["relations"]>;
+}
+interface EntityDefinition<TModel extends ModelDef2 = ModelDef2> {
+	readonly kind: "entity";
+	readonly name: string;
+	readonly model: TModel;
+	readonly inject: Record<string, EntityDefinition>;
+	readonly access: Partial<Record<string, AccessRule2>>;
+	readonly before: EntityBeforeHooks;
+	readonly after: EntityAfterHooks;
+	readonly actions: Record<string, EntityActionDef>;
+	readonly relations: EntityRelationsConfig<TModel["relations"]>;
+}
+import { SchemaLike as SchemaLike2 } from "@vertz/db";
+/** Extracts the model type from an EntityDefinition */
+type ExtractModel2<T> = T extends EntityDefinition<infer M> ? M : never;
+/**
+* Maps an inject config `{ key: EntityDefinition<TModel> }` to
+* `{ key: EntityOperations<TModel> }` for typed ctx.entities access.
+*/
+type InjectToOperations2<TInject extends Record<string, EntityDefinition> = {}> = { readonly [K in keyof TInject] : EntityOperations<ExtractModel2<TInject[K]>> };
+interface ServiceContext<TInject extends Record<string, EntityDefinition> = {}> extends BaseContext {
+	/** Typed access to injected entities only */
+	readonly entities: InjectToOperations2<TInject>;
+}
+interface ServiceActionDef<
+	TInput = unknown,
+	TOutput = unknown,
+	TCtx extends ServiceContext = ServiceContext
+> {
+	readonly method?: string;
+	readonly path?: string;
+	readonly body: SchemaLike2<TInput>;
+	readonly response: SchemaLike2<TOutput>;
+	readonly handler: (input: TInput, ctx: TCtx) => Promise<TOutput>;
+}
+interface ServiceConfig<
+	TActions extends Record<string, ServiceActionDef<any, any, any>> = Record<string, ServiceActionDef<any, any, any>>,
+	TInject extends Record<string, EntityDefinition> = {}
+> {
+	readonly inject?: TInject;
+	readonly access?: Partial<Record<Extract<keyof NoInfer<TActions>, string>, AccessRule2>>;
+	readonly actions: { readonly [K in keyof TActions] : TActions[K] };
+}
+interface ServiceDefinition {
+	readonly kind: "service";
+	readonly name: string;
+	readonly inject: Record<string, EntityDefinition>;
+	readonly access: Partial<Record<string, AccessRule2>>;
+	readonly actions: Record<string, ServiceActionDef>;
+}
 interface ServerConfig extends Omit<AppConfig, "_entityDbFactory" | "entities"> {
 	/** Entity definitions created via entity() from @vertz/server */
 	entities?: EntityDefinition[];
-	/** Standalone action definitions created via action() from @vertz/server */
-	actions?: ActionDefinition[];
+	/** Standalone service definitions created via service() from @vertz/server */
+	services?: ServiceDefinition[];
 	/**
 	* Database for entity CRUD operations.
 	* Accepts either:
@@ -347,13 +1188,13 @@ import { EntityForbiddenError, Result as Result3 } from "@vertz/errors";
 * Evaluates an access rule for the given operation.
 * Returns err(EntityForbiddenError) if access is denied.
 *
-* Accepts BaseContext so both EntityContext and ActionContext can use it.
+* Accepts BaseContext so both EntityContext and ServiceContext can use it.
 *
 * - No rule defined → deny (deny by default)
 * - Rule is false → operation is disabled
 * - Rule is a function → evaluate and deny if returns false
 */
-declare function enforceAccess(operation: string, accessRules: Partial<Record<string, AccessRule>>, ctx: BaseContext, row?: Record<string, unknown>): Promise<Result3<void, EntityForbiddenError>>;
+declare function enforceAccess(operation: string, accessRules: Partial<Record<string, AccessRule2>>, ctx: BaseContext, row?: Record<string, unknown>): Promise<Result3<void, EntityForbiddenError>>;
 import { ModelDef as ModelDef3 } from "@vertz/db";
 /**
 * Request info extracted from HTTP context / auth middleware.
@@ -426,4 +1267,8 @@ interface EntityRouteOptions {
 * Operations explicitly disabled (access: false) get a 405 handler.
 */
 declare function generateEntityRoutes(def: EntityDefinition, registry: EntityRegistry, db: EntityDbAdapter2, options?: EntityRouteOptions): EntityRouteEntry[];
-export { vertz, verifyPassword, validatePassword, stripReadOnlyFields, stripHiddenFields, makeImmutable, hashPassword, generateEntityRoutes, entityErrorHandler, entity, enforceAccess, defaultAccess, deepFreeze, createServer, createMiddleware, createImmutableProxy, createEnv, createEntityContext, createCrudHandlers, createAuth, createAccess, action, VertzException, ValidationException, UnauthorizedException, SignUpInput, SignInInput, SessionStrategy, SessionPayload, SessionConfig, Session, ServiceUnavailableException, ServerHandle, ServerConfig, ServerAdapter, Resource, RequestInfo, RawRequest, RateLimitResult, RateLimitConfig, PasswordRequirements, NotFoundException, NamedMiddlewareDef, MiddlewareDef, ListenOptions, ListResult, ListOptions2 as ListOptions, InternalServerErrorException, InferSchema, Infer, HttpStatusCode, HttpMethod, HandlerCtx, ForbiddenException, EnvConfig, EntityRouteOptions, EntityRelationsConfig, EntityRegistry, EntityOperations, EntityErrorResult, EntityDefinition, EntityDbAdapter2 as EntityDbAdapter, EntityContext, EntityConfig, EntityActionDef, EntitlementDefinition, Entitlement, EmailPasswordConfig, Deps, DeepReadonly, Ctx, CrudResult, CrudHandlers, CorsConfig, CookieConfig, ConflictException, BaseContext, BadRequestException, AuthorizationError, AuthUser, AuthInstance, AuthContext, AuthConfig, AuthApi, AppConfig2 as AppConfig, AppBuilder2 as AppBuilder, ActionDefinition, ActionContext, ActionConfig, ActionActionDef, AccumulateProvides, AccessRule, AccessInstance, AccessConfig };
+declare function service<
+	TInject extends Record<string, EntityDefinition> = {},
+	TActions extends Record<string, ServiceActionDef<any, any, any>> = Record<string, ServiceActionDef<any, any, any>>
+>(name: string, config: ServiceConfig<TActions, TInject>): ServiceDefinition;
+export { vertz, verifyPassword, validatePassword, stripReadOnlyFields, stripHiddenFields, service, rules, makeImmutable, hashPassword, google, github, generateEntityRoutes, entityErrorHandler, entity, enforceAccess, encodeAccessSet, discord, defineAccess, defaultAccess, deepFreeze, decodeAccessSet, createServer, createMiddleware, createImmutableProxy, createEnv, createEntityContext, createCrudHandlers, createAuth, createAccessEventBroadcaster, createAccessContext, createAccess, computeEntityAccess, computeAccessSet, checkFva, calculateBillingPeriod, WalletStore, WalletEntry, VertzException, ValidationException, UserTableEntry, UserStore, UnauthorizedException, StoredSession, StoredPasswordReset, StoredEmailVerification, SignUpInput, SignInInput, SessionStrategy, SessionStore, SessionPayload, SessionInfo, SessionConfig, Session, ServiceUnavailableException, ServiceDefinition, ServiceContext, ServiceConfig, ServiceActionDef, ServerHandle, ServerConfig, ServerAdapter, RoleAssignmentTableEntry, RoleAssignmentStore, RoleAssignment, ResourceRef, Resource, RequestInfo, RawRequest, RateLimitStore, RateLimitResult, RateLimitConfig, PlanStore, PlanDef, Period, PasswordResetStore, PasswordResetConfig, PasswordRequirements, ParentRef, OrgPlan, OAuthUserInfo, OAuthTokens, OAuthProviderConfig, OAuthProvider, OAuthAccountStore, NotFoundException, NamedMiddlewareDef, MiddlewareDef, MfaSetupData, MfaConfig, MfaChallengeData, MFAStore, ListenOptions, ListResult, ListOptions2 as ListOptions, LimitOverride, LimitDef, InternalServerErrorException, InferSchema, Infer, InMemoryWalletStore, InMemoryUserStore, InMemorySessionStore, InMemoryRoleAssignmentStore, InMemoryRateLimitStore, InMemoryPlanStore, InMemoryPasswordResetStore, InMemoryOAuthAccountStore, InMemoryMFAStore, InMemoryFlagStore, InMemoryEmailVerificationStore, InMemoryClosureStore, HttpStatusCode, HttpMethod, HandlerCtx, ForbiddenException, FlagStore, EnvConfig, EntityRouteOptions, EntityRelationsConfig, EntityRegistry, EntityOperations, EntityErrorResult, EntityDefinition, EntityDbAdapter2 as EntityDbAdapter, EntityContext, EntityConfig, EntityActionDef, EntitlementDefinition, EntitlementDef, Entitlement, EncodedAccessSet, EmailVerificationStore, EmailVerificationConfig, EmailPasswordConfig, Deps, DenialReason, DenialMeta, DefineAccessInput, DeepReadonly, Ctx, CrudResult, CrudHandlers, CorsConfig, CookieConfig, ConsumeResult, ConflictException, ComputeAccessSetConfig, ClosureStore, ClosureRow, ClosureEntry, BillingPeriod, BaseContext, BadRequestException, AuthorizationError, AuthUser, AuthTokens, AuthInstance, AuthContext, AuthConfig, AuthApi, AppConfig2 as AppConfig, AppBuilder2 as AppBuilder, AclClaim, AccumulateProvides, AccessWsData, AccessSet, AccessRule2 as AccessRule, AccessInstance, AccessEventBroadcasterConfig, AccessEventBroadcaster, AccessEvent, AccessDefinition, AccessContextConfig, AccessContext, AccessConfig, AccessCheckResult, AccessCheckData };