@fuzdev/fuz_app 0.1.0

package/dist/auth/request_context.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Request context middleware and permit checking helpers.
+ *
+ * Builds `{ account, actor, permits }` from a session cookie
+ * for every authenticated request. Downstream handlers check
+ * permits, never flags.
+ *
+ * `build_request_context` is the shared helper used by session,
+ * bearer, and daemon token middleware to resolve account → actor → permits.
+ * `refresh_permits` reloads permits on an existing context.
+ *
+ * @module
+ */
+import type { Context, MiddlewareHandler } from 'hono';
+import type { Logger } from '@fuzdev/fuz_util/log.js';
+import { type Account, type Actor, type Permit } from './account_schema.js';
+import type { QueryDeps } from '../db/query_deps.js';
+/** The resolved identity context for an authenticated request. */
+export interface RequestContext {
+    account: Account;
+    actor: Actor;
+    permits: Array<Permit>;
+}
+/** Hono context variable name for the request context. */
+export declare const REQUEST_CONTEXT_KEY = "request_context";
+/**
+ * Get the request context from a Hono context, or `null` if unauthenticated.
+ *
+ * @param c - the Hono context
+ * @returns the request context, or `null`
+ */
+export declare const get_request_context: (c: Context) => RequestContext | null;
+/**
+ * Get the request context, throwing if unauthenticated.
+ *
+ * Use in route handlers where auth middleware guarantees a context exists
+ * (i.e., routes with `auth: {type: 'authenticated'}` or stricter).
+ * Prefer this over `get_request_context(c)!` for explicit error handling.
+ *
+ * @param c - the Hono context
+ * @returns the request context (never null)
+ * @throws Error if no request context is set (middleware misconfiguration)
+ */
+export declare const require_request_context: (c: Context) => RequestContext;
+/**
+ * Check if a request context has an active permit for a given role.
+ *
+ * Checks the permits already loaded in the context (no DB query).
+ *
+ * @param ctx - the request context
+ * @param role - the role to check
+ * @param now - current time (defaults to `new Date()`, pass for testability and hot-path efficiency)
+ * @returns `true` if the actor has an active permit for the role
+ */
+export declare const has_role: (ctx: RequestContext, role: string, now?: Date) => boolean;
+/**
+ * Create middleware that builds the request context from a session cookie.
+ *
+ * Reads the session identity (set by session middleware), looks up
+ * the `auth_session`, loads account + actor + active permits, and
+ * sets the `RequestContext` on the Hono context.
+ *
+ * If the session is invalid or the account is not found, the context
+ * is set to `null` (unauthenticated). No 401 is returned — use
+ * `require_role` or `require_auth` for enforcement.
+ *
+ * @param deps - query dependencies (pool-level db for middleware)
+ * @param log - the logger instance
+ * @param session_context_key - the Hono context key where session middleware stored the session token
+ */
+export declare const create_request_context_middleware: (deps: QueryDeps, log: Logger, session_context_key?: string) => MiddlewareHandler;
+/**
+ * Middleware that requires authentication.
+ *
+ * Returns 401 if no request context is set.
+ */
+export declare const require_auth: MiddlewareHandler;
+/**
+ * Create middleware that requires a specific role.
+ *
+ * Returns 401 if unauthenticated, 403 if the role is missing.
+ *
+ * @param role - the required role
+ */
+export declare const require_role: (role: string) => MiddlewareHandler;
+/**
+ * Reload active permits from the database, returning a new request context.
+ *
+ * Useful for long-lived WebSocket connections where permits may change
+ * (grant or revoke) during the connection lifetime. Call periodically
+ * or after receiving a revocation signal.
+ *
+ * Returns a new `RequestContext` with updated permits — the original
+ * context is not mutated, making concurrent calls safe.
+ *
+ * @param ctx - the request context to refresh
+ * @param deps - query dependencies
+ * @returns a new `RequestContext` with fresh permits
+ */
+export declare const refresh_permits: (ctx: RequestContext, deps: QueryDeps) => Promise<RequestContext>;
+/**
+ * Build a full `RequestContext` from an account id.
+ *
+ * Shared helper used by session, bearer, and daemon token middleware,
+ * as well as WebSocket upgrade handlers. Does the account → actor → permits
+ * lookup pipeline and returns the composed context, or `null` if
+ * the account or actor is not found.
+ *
+ * @param deps - query dependencies
+ * @param account_id - the account to build context for
+ * @returns a request context, or `null` if account/actor not found
+ */
+export declare const build_request_context: (deps: QueryDeps, account_id: string) => Promise<RequestContext | null>;
+//# sourceMappingURL=request_context.d.ts.map

package/dist/auth/request_context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request_context.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/request_context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAE,iBAAiB,EAAC,MAAM,MAAM,CAAC;AACrD,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,EAAC,KAAK,OAAO,EAAE,KAAK,KAAK,EAAoB,KAAK,MAAM,EAAC,MAAM,qBAAqB,CAAC;AAQ5F,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAOnD,kEAAkE;AAClE,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACvB;AAED,0DAA0D;AAC1D,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,GAAG,OAAO,KAAG,cAAc,GAAG,IAEjE,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,GAAI,GAAG,OAAO,KAAG,cAMpD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,cAAc,EAAE,MAAM,MAAM,EAAE,MAAK,IAAiB,KAAG,OAChB,CAAC;AAEtE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iCAAiC,GAC7C,MAAM,SAAS,EACf,KAAK,MAAM,EACX,4BAAuC,KACrC,iBAqCF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,iBAM1B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,iBAW3C,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,eAAe,GAC3B,KAAK,cAAc,EACnB,MAAM,SAAS,KACb,OAAO,CAAC,cAAc,CAGxB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,GACjC,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,cAAc,GAAG,IAAI,CAS/B,CAAC"}

package/dist/auth/request_context.js

@@ -0,0 +1,176 @@
+/**
+ * Request context middleware and permit checking helpers.
+ *
+ * Builds `{ account, actor, permits }` from a session cookie
+ * for every authenticated request. Downstream handlers check
+ * permits, never flags.
+ *
+ * `build_request_context` is the shared helper used by session,
+ * bearer, and daemon token middleware to resolve account → actor → permits.
+ * `refresh_permits` reloads permits on an existing context.
+ *
+ * @module
+ */
+import { is_permit_active } from './account_schema.js';
+import { hash_session_token, session_touch_fire_and_forget, query_session_get_valid, } from './session_queries.js';
+import { query_actor_by_account, query_account_by_id } from './account_queries.js';
+import { query_permit_find_active_for_actor } from './permit_queries.js';
+import { CREDENTIAL_TYPE_KEY } from '../hono_context.js';
+import { ERROR_AUTHENTICATION_REQUIRED, ERROR_INSUFFICIENT_PERMISSIONS, } from '../http/error_schemas.js';
+/** Hono context variable name for the request context. */
+export const REQUEST_CONTEXT_KEY = 'request_context';
+/**
+ * Get the request context from a Hono context, or `null` if unauthenticated.
+ *
+ * @param c - the Hono context
+ * @returns the request context, or `null`
+ */
+export const get_request_context = (c) => {
+    return c.get(REQUEST_CONTEXT_KEY) ?? null;
+};
+/**
+ * Get the request context, throwing if unauthenticated.
+ *
+ * Use in route handlers where auth middleware guarantees a context exists
+ * (i.e., routes with `auth: {type: 'authenticated'}` or stricter).
+ * Prefer this over `get_request_context(c)!` for explicit error handling.
+ *
+ * @param c - the Hono context
+ * @returns the request context (never null)
+ * @throws Error if no request context is set (middleware misconfiguration)
+ */
+export const require_request_context = (c) => {
+    const ctx = get_request_context(c);
+    if (!ctx) {
+        throw new Error('require_request_context: no request context — is auth middleware applied?');
+    }
+    return ctx;
+};
+/**
+ * Check if a request context has an active permit for a given role.
+ *
+ * Checks the permits already loaded in the context (no DB query).
+ *
+ * @param ctx - the request context
+ * @param role - the role to check
+ * @param now - current time (defaults to `new Date()`, pass for testability and hot-path efficiency)
+ * @returns `true` if the actor has an active permit for the role
+ */
+export const has_role = (ctx, role, now = new Date()) => ctx.permits.some((p) => p.role === role && is_permit_active(p, now));
+/**
+ * Create middleware that builds the request context from a session cookie.
+ *
+ * Reads the session identity (set by session middleware), looks up
+ * the `auth_session`, loads account + actor + active permits, and
+ * sets the `RequestContext` on the Hono context.
+ *
+ * If the session is invalid or the account is not found, the context
+ * is set to `null` (unauthenticated). No 401 is returned — use
+ * `require_role` or `require_auth` for enforcement.
+ *
+ * @param deps - query dependencies (pool-level db for middleware)
+ * @param log - the logger instance
+ * @param session_context_key - the Hono context key where session middleware stored the session token
+ */
+export const create_request_context_middleware = (deps, log, session_context_key = 'auth_session_id') => {
+    return async (c, next) => {
+        const session_token = c.get(session_context_key) ?? null;
+        if (!session_token) {
+            c.set(REQUEST_CONTEXT_KEY, null);
+            c.set(CREDENTIAL_TYPE_KEY, null);
+            await next();
+            return;
+        }
+        const token_hash = hash_session_token(session_token);
+        const session = await query_session_get_valid(deps, token_hash);
+        if (!session) {
+            c.set(REQUEST_CONTEXT_KEY, null);
+            c.set(CREDENTIAL_TYPE_KEY, null);
+            await next();
+            return;
+        }
+        const ctx = await build_request_context(deps, session.account_id);
+        if (!ctx) {
+            c.set(REQUEST_CONTEXT_KEY, null);
+            c.set(CREDENTIAL_TYPE_KEY, null);
+            await next();
+            return;
+        }
+        c.set(REQUEST_CONTEXT_KEY, ctx);
+        c.set(CREDENTIAL_TYPE_KEY, 'session');
+        // Touch session (fire-and-forget, don't block the request)
+        void session_touch_fire_and_forget(deps, token_hash, c.var.pending_effects, log);
+        await next();
+    };
+};
+/**
+ * Middleware that requires authentication.
+ *
+ * Returns 401 if no request context is set.
+ */
+export const require_auth = async (c, next) => {
+    const ctx = get_request_context(c);
+    if (!ctx) {
+        return c.json({ error: ERROR_AUTHENTICATION_REQUIRED }, 401);
+    }
+    await next();
+};
+/**
+ * Create middleware that requires a specific role.
+ *
+ * Returns 401 if unauthenticated, 403 if the role is missing.
+ *
+ * @param role - the required role
+ */
+export const require_role = (role) => {
+    return async (c, next) => {
+        const ctx = get_request_context(c);
+        if (!ctx) {
+            return c.json({ error: ERROR_AUTHENTICATION_REQUIRED }, 401);
+        }
+        if (!has_role(ctx, role)) {
+            return c.json({ error: ERROR_INSUFFICIENT_PERMISSIONS, required_role: role }, 403);
+        }
+        await next();
+    };
+};
+/**
+ * Reload active permits from the database, returning a new request context.
+ *
+ * Useful for long-lived WebSocket connections where permits may change
+ * (grant or revoke) during the connection lifetime. Call periodically
+ * or after receiving a revocation signal.
+ *
+ * Returns a new `RequestContext` with updated permits — the original
+ * context is not mutated, making concurrent calls safe.
+ *
+ * @param ctx - the request context to refresh
+ * @param deps - query dependencies
+ * @returns a new `RequestContext` with fresh permits
+ */
+export const refresh_permits = async (ctx, deps) => {
+    const permits = await query_permit_find_active_for_actor(deps, ctx.actor.id);
+    return { ...ctx, permits };
+};
+/**
+ * Build a full `RequestContext` from an account id.
+ *
+ * Shared helper used by session, bearer, and daemon token middleware,
+ * as well as WebSocket upgrade handlers. Does the account → actor → permits
+ * lookup pipeline and returns the composed context, or `null` if
+ * the account or actor is not found.
+ *
+ * @param deps - query dependencies
+ * @param account_id - the account to build context for
+ * @returns a request context, or `null` if account/actor not found
+ */
+export const build_request_context = async (deps, account_id) => {
+    const account = await query_account_by_id(deps, account_id);
+    if (!account)
+        return null;
+    const actor = await query_actor_by_account(deps, account.id);
+    if (!actor)
+        return null;
+    const permits = await query_permit_find_active_for_actor(deps, actor.id);
+    return { account, actor, permits };
+};

package/dist/auth/require_keeper.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Keeper credential type guard.
+ *
+ * Two-part check:
+ * 1. Credential type must be `daemon_token` (not session cookie, not API token).
+ * 2. Account must hold active keeper permit.
+ *
+ * Both must pass. A session cookie from the bootstrap account still fails check #1.
+ *
+ * @module
+ */
+import type { MiddlewareHandler } from 'hono';
+/**
+ * Middleware that requires keeper credentials.
+ *
+ * Returns 401 if unauthenticated, 403 if credential type is not
+ * `daemon_token` or if the keeper role is missing.
+ */
+export declare const require_keeper: MiddlewareHandler;
+//# sourceMappingURL=require_keeper.d.ts.map

package/dist/auth/require_keeper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"require_keeper.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/require_keeper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,MAAM,CAAC;AAW5C;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,iBAmB5B,CAAC"}

package/dist/auth/require_keeper.js

@@ -0,0 +1,35 @@
+/**
+ * Keeper credential type guard.
+ *
+ * Two-part check:
+ * 1. Credential type must be `daemon_token` (not session cookie, not API token).
+ * 2. Account must hold active keeper permit.
+ *
+ * Both must pass. A session cookie from the bootstrap account still fails check #1.
+ *
+ * @module
+ */
+import { get_request_context, has_role } from './request_context.js';
+import { CREDENTIAL_TYPE_KEY } from '../hono_context.js';
+import { ROLE_KEEPER } from './role_schema.js';
+import { ERROR_AUTHENTICATION_REQUIRED, ERROR_INSUFFICIENT_PERMISSIONS, ERROR_KEEPER_REQUIRES_DAEMON_TOKEN, } from '../http/error_schemas.js';
+/**
+ * Middleware that requires keeper credentials.
+ *
+ * Returns 401 if unauthenticated, 403 if credential type is not
+ * `daemon_token` or if the keeper role is missing.
+ */
+export const require_keeper = async (c, next) => {
+    const ctx = get_request_context(c);
+    if (!ctx) {
+        return c.json({ error: ERROR_AUTHENTICATION_REQUIRED }, 401);
+    }
+    const credential_type = c.get(CREDENTIAL_TYPE_KEY);
+    if (credential_type !== 'daemon_token') {
+        return c.json({ error: ERROR_KEEPER_REQUIRES_DAEMON_TOKEN, credential_type: credential_type ?? 'none' }, 403);
+    }
+    if (!has_role(ctx, ROLE_KEEPER)) {
+        return c.json({ error: ERROR_INSUFFICIENT_PERMISSIONS, required_role: ROLE_KEEPER }, 403);
+    }
+    await next();
+};

package/dist/auth/role_schema.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Role system — builtin roles, role options, and extensible role schema factory.
+ *
+ * Defines the authorization policy vocabulary: which roles exist, what
+ * capabilities they require (daemon token, web grantability), and a factory
+ * for extending with app-defined roles.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/** Valid role name: lowercase letters and underscores, no leading/trailing underscore. */
+export declare const RoleName: z.ZodString;
+export type RoleName = z.infer<typeof RoleName>;
+/** System-level role. Requires daemon token (filesystem proof). Controls the keep. */
+export declare const ROLE_KEEPER = "keeper";
+/** App-level administrative role. Web-grantable, manages users and content. */
+export declare const ROLE_ADMIN = "admin";
+/** The builtin role names as a const tuple. */
+export declare const BUILTIN_ROLES: readonly ["keeper", "admin"];
+/** Zod schema for builtin roles only. */
+export declare const BuiltinRole: z.ZodEnum<{
+    keeper: "keeper";
+    admin: "admin";
+}>;
+export type BuiltinRole = z.infer<typeof BuiltinRole>;
+/**
+ * Configuration for a role.
+ *
+ * Builtin roles have fixed configs. App-defined roles get sensible defaults
+ * (`requires_daemon_token: false`, `web_grantable: true`).
+ */
+export interface RoleOptions {
+    /** If true, exercising this role requires daemon token authentication. Only `keeper` for now. */
+    requires_daemon_token?: boolean;
+    /** If true, admins can grant this role via the web UI. Default `true`. */
+    web_grantable?: boolean;
+}
+/** Builtin role configs. Not overridable by consumers. */
+export declare const BUILTIN_ROLE_OPTIONS: ReadonlyMap<string, Required<RoleOptions>>;
+/** The result of `create_role_schema` — a Zod schema and config map for all roles. */
+export interface RoleSchemaResult {
+    /** Zod schema that validates role strings. Use at I/O boundaries (grant endpoint, permit queries). */
+    Role: z.ZodType<string>;
+    /** Options for every role (builtins + app-defined). Keyed by role name. */
+    role_options: ReadonlyMap<string, Required<RoleOptions>>;
+}
+/**
+ * Create a role schema and config map that extends the builtins with app-defined roles.
+ *
+ * Call once at server init. The returned `Role` schema validates role strings
+ * at I/O boundaries (grant endpoint, permit queries). The `role_options` map
+ * is used by middleware to check `requires_daemon_token` and by admin UI to
+ * filter `web_grantable` roles.
+ *
+ * @param app_roles - app-defined roles with optional config overrides
+ * @returns `{Role, role_options}` — Zod schema and full config map
+ *
+ * @example
+ * ```ts
+ * // visiones
+ * const {Role, role_options} = create_role_schema({
+ *   teacher: {},
+ * });
+ * // Role validates 'keeper' | 'admin' | 'teacher'
+ * // role_options has all 3 entries with defaults applied
+ * ```
+ */
+export declare const create_role_schema: <T extends string>(app_roles: Record<T, RoleOptions>) => RoleSchemaResult;
+//# sourceMappingURL=role_schema.d.ts.map

package/dist/auth/role_schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/role_schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,0FAA0F;AAC1F,eAAO,MAAM,QAAQ,aAKnB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAIhD,sFAAsF;AACtF,eAAO,MAAM,WAAW,WAAW,CAAC;AAEpC,+EAA+E;AAC/E,eAAO,MAAM,UAAU,UAAU,CAAC;AAElC,+CAA+C;AAC/C,eAAO,MAAM,aAAa,8BAAqC,CAAC;AAEhE,yCAAyC;AACzC,eAAO,MAAM,WAAW;;;EAAwB,CAAC;AACjD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAItD;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B,iGAAiG;IACjG,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,0EAA0E;IAC1E,aAAa,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,0DAA0D;AAC1D,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,CAG1E,CAAC;AAEH,sFAAsF;AACtF,MAAM,WAAW,gBAAgB;IAChC,sGAAsG;IACtG,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACxB,2EAA2E;IAC3E,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC;CACzD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,SAAS,MAAM,EAClD,WAAW,MAAM,CAAC,CAAC,EAAE,WAAW,CAAC,KAC/B,gBAwBF,CAAC"}

package/dist/auth/role_schema.js

@@ -0,0 +1,70 @@
+/**
+ * Role system — builtin roles, role options, and extensible role schema factory.
+ *
+ * Defines the authorization policy vocabulary: which roles exist, what
+ * capabilities they require (daemon token, web grantability), and a factory
+ * for extending with app-defined roles.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/** Valid role name: lowercase letters and underscores, no leading/trailing underscore. */
+export const RoleName = z
+    .string()
+    .regex(/^[a-z][a-z_]*[a-z]$|^[a-z]$/, 'Role names must be lowercase letters and underscores (a-z_), no leading/trailing underscore');
+// Builtin roles — provided by fuz_app, always available.
+/** System-level role. Requires daemon token (filesystem proof). Controls the keep. */
+export const ROLE_KEEPER = 'keeper';
+/** App-level administrative role. Web-grantable, manages users and content. */
+export const ROLE_ADMIN = 'admin';
+/** The builtin role names as a const tuple. */
+export const BUILTIN_ROLES = [ROLE_KEEPER, ROLE_ADMIN];
+/** Zod schema for builtin roles only. */
+export const BuiltinRole = z.enum(BUILTIN_ROLES);
+/** Builtin role configs. Not overridable by consumers. */
+export const BUILTIN_ROLE_OPTIONS = new Map([
+    [ROLE_KEEPER, { requires_daemon_token: true, web_grantable: false }],
+    [ROLE_ADMIN, { requires_daemon_token: false, web_grantable: true }],
+]);
+/**
+ * Create a role schema and config map that extends the builtins with app-defined roles.
+ *
+ * Call once at server init. The returned `Role` schema validates role strings
+ * at I/O boundaries (grant endpoint, permit queries). The `role_options` map
+ * is used by middleware to check `requires_daemon_token` and by admin UI to
+ * filter `web_grantable` roles.
+ *
+ * @param app_roles - app-defined roles with optional config overrides
+ * @returns `{Role, role_options}` — Zod schema and full config map
+ *
+ * @example
+ * ```ts
+ * // visiones
+ * const {Role, role_options} = create_role_schema({
+ *   teacher: {},
+ * });
+ * // Role validates 'keeper' | 'admin' | 'teacher'
+ * // role_options has all 3 entries with defaults applied
+ * ```
+ */
+export const create_role_schema = (app_roles) => {
+    const app_role_names = Object.keys(app_roles);
+    // Validate role names and no collisions with builtins
+    for (const name of app_role_names) {
+        RoleName.parse(name);
+        if (BUILTIN_ROLE_OPTIONS.has(name)) {
+            throw new Error(`App role "${name}" collides with builtin role`);
+        }
+    }
+    const all_names = [...BUILTIN_ROLES, ...app_role_names];
+    const Role = z.enum(all_names);
+    const role_options = new Map(BUILTIN_ROLE_OPTIONS);
+    for (const name of app_role_names) {
+        const config = app_roles[name];
+        role_options.set(name, {
+            requires_daemon_token: config.requires_daemon_token ?? false,
+            web_grantable: config.web_grantable ?? true,
+        });
+    }
+    return { Role, role_options };
+};

package/dist/auth/route_guards.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Auth guard resolver for the route spec system.
+ *
+ * Maps `RouteAuth` discriminants to auth middleware handlers.
+ * Injected into `apply_route_specs` to decouple the generic HTTP
+ * framework (`route_spec.ts`) from auth-specific middleware.
+ *
+ * @module
+ */
+import type { AuthGuardResolver } from '../http/route_spec.js';
+/**
+ * Standard auth guard resolver for fuz_app.
+ *
+ * Maps `RouteAuth` to middleware:
+ * - `none` → no guards
+ * - `authenticated` → `require_auth`
+ * - `role` → `require_role(role)`
+ * - `keeper` → `require_keeper`
+ */
+export declare const fuz_auth_guard_resolver: AuthGuardResolver;
+//# sourceMappingURL=route_guards.d.ts.map

package/dist/auth/route_guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route_guards.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/route_guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,uBAAuB,CAAC;AAE7D;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAWrC,CAAC"}

package/dist/auth/route_guards.js

@@ -0,0 +1,32 @@
+/**
+ * Auth guard resolver for the route spec system.
+ *
+ * Maps `RouteAuth` discriminants to auth middleware handlers.
+ * Injected into `apply_route_specs` to decouple the generic HTTP
+ * framework (`route_spec.ts`) from auth-specific middleware.
+ *
+ * @module
+ */
+import { require_auth, require_role } from './request_context.js';
+import { require_keeper } from './require_keeper.js';
+/**
+ * Standard auth guard resolver for fuz_app.
+ *
+ * Maps `RouteAuth` to middleware:
+ * - `none` → no guards
+ * - `authenticated` → `require_auth`
+ * - `role` → `require_role(role)`
+ * - `keeper` → `require_keeper`
+ */
+export const fuz_auth_guard_resolver = (auth) => {
+    switch (auth.type) {
+        case 'none':
+            return [];
+        case 'authenticated':
+            return [require_auth];
+        case 'role':
+            return [require_role(auth.role)];
+        case 'keeper':
+            return [require_keeper];
+    }
+};