@portaidentity/server 1.7.0

package/dist/routes/permissions.js

@@ -0,0 +1,166 @@
+/**
+ * Permission management API routes.
+ *
+ * All routes are under `/api/admin/applications/:appId/permissions` and
+ * require admin authorization with granular permissions. Provides CRUD
+ * for permissions and a query for roles that include a given permission.
+ *
+ * Route structure:
+ *   POST   /                — Create a new permission
+ *   GET    /                — List permissions (optional ?moduleId filter)
+ *   GET    /:permId         — Get a permission by ID
+ *   PUT    /:permId         — Update a permission (name/description only)
+ *   DELETE /:permId         — Delete a permission (?force=true)
+ *   GET    /:permId/roles   — List roles that have this permission
+ *
+ * Error mapping:
+ *   PermissionNotFoundError → 404
+ *   RbacValidationError → 400
+ *   ZodError → 400 with validation details
+ */
+import Router from '@koa/router';
+import { z } from 'zod';
+import { requireAdminAuth } from '../middleware/admin-auth.js';
+import { requirePermission } from '../middleware/require-permission.js';
+import { ADMIN_PERMISSIONS } from '../lib/admin-permissions.js';
+import * as permissionService from '../rbac/permission-service.js';
+import { PermissionNotFoundError, RbacValidationError } from '../rbac/errors.js';
+// ---------------------------------------------------------------------------
+// Validation schemas
+// ---------------------------------------------------------------------------
+/** Schema for creating a new permission */
+const createPermissionSchema = z.object({
+    name: z.string().min(1).max(255),
+    slug: z.string().min(1).max(150),
+    moduleId: z.string().uuid().optional(),
+    description: z.string().max(1000).optional(),
+});
+/** Schema for updating a permission (name and description only) */
+const updatePermissionSchema = z.object({
+    name: z.string().min(1).max(255).optional(),
+    description: z.string().max(1000).nullable().optional(),
+});
+/** Schema for filtering permissions by module */
+const listPermissionsSchema = z.object({
+    moduleId: z.string().uuid().optional(),
+});
+// ---------------------------------------------------------------------------
+// Error handler helper
+// ---------------------------------------------------------------------------
+/**
+ * Handle domain errors and map them to HTTP responses.
+ * Unknown errors are re-thrown for the global error handler.
+ */
+function handleError(ctx, err) {
+    if (err instanceof PermissionNotFoundError) {
+        ctx.throw(404, 'Permission not found');
+    }
+    if (err instanceof RbacValidationError) {
+        ctx.throw(400, 'Permission request is invalid');
+    }
+    if (err instanceof z.ZodError) {
+        ctx.status = 400;
+        ctx.body = { error: 'Permission request is invalid' };
+        return undefined;
+    }
+    throw err;
+}
+// ---------------------------------------------------------------------------
+// Router factory
+// ---------------------------------------------------------------------------
+/**
+ * Create the permission management router.
+ *
+ * All routes require admin authorization with granular permissions.
+ * Permissions are scoped to an application via the :appId URL parameter.
+ *
+ * Prefix: /api/admin/applications/:appId/permissions
+ *
+ * @returns Configured Koa Router
+ */
+export function createPermissionRouter() {
+    const router = new Router({ prefix: '/api/admin/applications/:appId/permissions' });
+    // All routes require admin authentication
+    router.use(requireAdminAuth());
+    // -------------------------------------------------------------------------
+    // POST / — Create permission
+    // -------------------------------------------------------------------------
+    router.post('/', requirePermission(ADMIN_PERMISSIONS.PERMISSION_CREATE), async (ctx) => {
+        try {
+            const body = createPermissionSchema.parse(ctx.request.body);
+            const permission = await permissionService.createPermission({
+                applicationId: ctx.params.appId,
+                ...body,
+            });
+            ctx.status = 201;
+            ctx.body = { data: permission };
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // GET / — List permissions for application (optional moduleId filter)
+    // -------------------------------------------------------------------------
+    router.get('/', requirePermission(ADMIN_PERMISSIONS.PERMISSION_READ), async (ctx) => {
+        try {
+            const query = listPermissionsSchema.parse(ctx.query);
+            const permissions = await permissionService.listPermissionsByApplication(ctx.params.appId, query.moduleId);
+            ctx.body = { data: permissions };
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // GET /:permId — Get permission by ID
+    // -------------------------------------------------------------------------
+    router.get('/:permId', requirePermission(ADMIN_PERMISSIONS.PERMISSION_READ), async (ctx) => {
+        const permission = await permissionService.findPermissionById(ctx.params.permId);
+        if (!permission) {
+            ctx.throw(404, 'Permission not found');
+        }
+        ctx.body = { data: permission };
+    });
+    // -------------------------------------------------------------------------
+    // PUT /:permId — Update permission (name and description only)
+    // -------------------------------------------------------------------------
+    router.put('/:permId', requirePermission(ADMIN_PERMISSIONS.PERMISSION_CREATE), async (ctx) => {
+        try {
+            const body = updatePermissionSchema.parse(ctx.request.body);
+            const permission = await permissionService.updatePermission(ctx.params.permId, body);
+            ctx.body = { data: permission };
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // DELETE /:permId — Delete permission
+    // Supports ?force=true to delete even when roles reference it
+    // -------------------------------------------------------------------------
+    router.delete('/:permId', requirePermission(ADMIN_PERMISSIONS.PERMISSION_ARCHIVE), async (ctx) => {
+        try {
+            const force = ctx.query.force === 'true';
+            await permissionService.deletePermission(ctx.params.permId, force);
+            ctx.status = 204;
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // GET /:permId/roles — List roles that include this permission
+    // -------------------------------------------------------------------------
+    router.get('/:permId/roles', requirePermission(ADMIN_PERMISSIONS.PERMISSION_READ), async (ctx) => {
+        try {
+            const roles = await permissionService.getRolesWithPermission(ctx.params.permId);
+            ctx.body = { data: roles };
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    return router;
+}
+//# sourceMappingURL=permissions.js.map

package/dist/routes/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../../src/routes/permissions.ts"],"names":[],"mappings":"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"}

package/dist/routes/roles.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Role management API routes.
+ *
+ * All routes are under `/api/admin/applications/:appId/roles` and
+ * require admin authorization with granular permissions. Provides
+ * CRUD for roles, permission assignment/removal, and user listing
+ * per role.
+ *
+ * Route structure:
+ *   POST   /                       — Create a new role
+ *   GET    /                       — List all roles for an application
+ *   GET    /:roleId                — Get a role by ID
+ *   PUT    /:roleId                — Update a role
+ *   DELETE /:roleId                — Delete a role (?force=true)
+ *   GET    /:roleId/permissions    — List permissions for a role
+ *   PUT    /:roleId/permissions    — Assign permissions to a role
+ *   DELETE /:roleId/permissions    — Remove permissions from a role
+ *
+ * Error mapping:
+ *   RoleNotFoundError → 404
+ *   PermissionNotFoundError → 404
+ *   RbacValidationError → 400
+ *   ZodError → 400 with validation details
+ */
+import Router from '@koa/router';
+/**
+ * Create the role management router.
+ *
+ * All routes require admin authorization with granular permissions.
+ * Roles are scoped to an application via the :appId URL parameter.
+ *
+ * Prefix: /api/admin/applications/:appId/roles
+ *
+ * @returns Configured Koa Router
+ */
+export declare function createRoleRouter(): Router;
+//# sourceMappingURL=roles.d.ts.map

package/dist/routes/roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../../src/routes/roles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,MAAM,MAAM,aAAa,CAAC;AAwEjC;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CA6IzC"}

package/dist/routes/roles.js

@@ -0,0 +1,222 @@
+/**
+ * Role management API routes.
+ *
+ * All routes are under `/api/admin/applications/:appId/roles` and
+ * require admin authorization with granular permissions. Provides
+ * CRUD for roles, permission assignment/removal, and user listing
+ * per role.
+ *
+ * Route structure:
+ *   POST   /                       — Create a new role
+ *   GET    /                       — List all roles for an application
+ *   GET    /:roleId                — Get a role by ID
+ *   PUT    /:roleId                — Update a role
+ *   DELETE /:roleId                — Delete a role (?force=true)
+ *   GET    /:roleId/permissions    — List permissions for a role
+ *   PUT    /:roleId/permissions    — Assign permissions to a role
+ *   DELETE /:roleId/permissions    — Remove permissions from a role
+ *
+ * Error mapping:
+ *   RoleNotFoundError → 404
+ *   PermissionNotFoundError → 404
+ *   RbacValidationError → 400
+ *   ZodError → 400 with validation details
+ */
+import Router from '@koa/router';
+import { z } from 'zod';
+import { requireAdminAuth } from '../middleware/admin-auth.js';
+import { requirePermission } from '../middleware/require-permission.js';
+import { ADMIN_PERMISSIONS } from '../lib/admin-permissions.js';
+import * as roleService from '../rbac/role-service.js';
+import * as userRoleService from '../rbac/user-role-service.js';
+import { RoleNotFoundError, PermissionNotFoundError, RbacValidationError } from '../rbac/errors.js';
+// ---------------------------------------------------------------------------
+// Validation schemas
+// ---------------------------------------------------------------------------
+/** Schema for creating a new role */
+const createRoleSchema = z.object({
+    name: z.string().min(1).max(255),
+    slug: z.string().min(1).max(100).optional(),
+    description: z.string().max(1000).optional(),
+});
+/** Schema for updating a role (all fields optional) */
+const updateRoleSchema = z.object({
+    name: z.string().min(1).max(255).optional(),
+    slug: z.string().min(1).max(100).optional(),
+    description: z.string().max(1000).nullable().optional(),
+});
+/** Schema for assigning/removing permissions (array of UUIDs) */
+const permissionIdsSchema = z.object({
+    permissionIds: z.array(z.string().uuid()).min(1),
+});
+/** Schema for listing users with a role (paginated, org-scoped) */
+const listUsersWithRoleSchema = z.object({
+    orgId: z.string().uuid(),
+    page: z.coerce.number().int().min(1).default(1),
+    pageSize: z.coerce.number().int().min(1).max(100).default(20),
+});
+// ---------------------------------------------------------------------------
+// Error handler helper
+// ---------------------------------------------------------------------------
+/**
+ * Handle domain errors and map them to HTTP responses.
+ * Unknown errors are re-thrown for the global error handler.
+ */
+function handleError(ctx, err) {
+    if (err instanceof RoleNotFoundError) {
+        ctx.throw(404, 'Role not found');
+    }
+    if (err instanceof PermissionNotFoundError) {
+        ctx.throw(404, 'Permission not found');
+    }
+    if (err instanceof RbacValidationError) {
+        ctx.throw(400, 'Role request is invalid');
+    }
+    if (err instanceof z.ZodError) {
+        ctx.status = 400;
+        ctx.body = { error: 'Role request is invalid' };
+        return undefined;
+    }
+    throw err;
+}
+// ---------------------------------------------------------------------------
+// Router factory
+// ---------------------------------------------------------------------------
+/**
+ * Create the role management router.
+ *
+ * All routes require admin authorization with granular permissions.
+ * Roles are scoped to an application via the :appId URL parameter.
+ *
+ * Prefix: /api/admin/applications/:appId/roles
+ *
+ * @returns Configured Koa Router
+ */
+export function createRoleRouter() {
+    const router = new Router({ prefix: '/api/admin/applications/:appId/roles' });
+    // All routes require admin authentication
+    router.use(requireAdminAuth());
+    // -------------------------------------------------------------------------
+    // POST / — Create role
+    // -------------------------------------------------------------------------
+    router.post('/', requirePermission(ADMIN_PERMISSIONS.ROLE_CREATE), async (ctx) => {
+        try {
+            const body = createRoleSchema.parse(ctx.request.body);
+            const role = await roleService.createRole({
+                applicationId: ctx.params.appId,
+                ...body,
+            });
+            ctx.status = 201;
+            ctx.body = { data: role };
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // GET / — List roles for application
+    // -------------------------------------------------------------------------
+    router.get('/', requirePermission(ADMIN_PERMISSIONS.ROLE_READ), async (ctx) => {
+        try {
+            const roles = await roleService.listRolesByApplication(ctx.params.appId);
+            ctx.body = { data: roles };
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // GET /:roleId — Get role by ID
+    // -------------------------------------------------------------------------
+    router.get('/:roleId', requirePermission(ADMIN_PERMISSIONS.ROLE_READ), async (ctx) => {
+        const role = await roleService.findRoleById(ctx.params.roleId);
+        if (!role) {
+            ctx.throw(404, 'Role not found');
+        }
+        ctx.body = { data: role };
+    });
+    // -------------------------------------------------------------------------
+    // PUT /:roleId — Update role
+    // -------------------------------------------------------------------------
+    router.put('/:roleId', requirePermission(ADMIN_PERMISSIONS.ROLE_UPDATE), async (ctx) => {
+        try {
+            const body = updateRoleSchema.parse(ctx.request.body);
+            const role = await roleService.updateRole(ctx.params.roleId, body);
+            ctx.body = { data: role };
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // DELETE /:roleId — Delete role
+    // Supports ?force=true to delete even when users are assigned
+    // -------------------------------------------------------------------------
+    router.delete('/:roleId', requirePermission(ADMIN_PERMISSIONS.ROLE_ARCHIVE), async (ctx) => {
+        try {
+            const force = ctx.query.force === 'true';
+            await roleService.deleteRole(ctx.params.roleId, force);
+            ctx.status = 204;
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // GET /:roleId/permissions — List permissions for a role
+    // -------------------------------------------------------------------------
+    router.get('/:roleId/permissions', requirePermission(ADMIN_PERMISSIONS.ROLE_READ), async (ctx) => {
+        try {
+            const permissions = await roleService.getPermissionsForRole(ctx.params.roleId);
+            ctx.body = { data: permissions };
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // PUT /:roleId/permissions — Assign permissions to a role
+    // -------------------------------------------------------------------------
+    router.put('/:roleId/permissions', requirePermission(ADMIN_PERMISSIONS.ROLE_UPDATE), async (ctx) => {
+        try {
+            const body = permissionIdsSchema.parse(ctx.request.body);
+            await roleService.assignPermissionsToRole(ctx.params.roleId, body.permissionIds);
+            ctx.status = 204;
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // DELETE /:roleId/permissions — Remove permissions from a role
+    // -------------------------------------------------------------------------
+    router.delete('/:roleId/permissions', requirePermission(ADMIN_PERMISSIONS.ROLE_UPDATE), async (ctx) => {
+        try {
+            const body = permissionIdsSchema.parse(ctx.request.body);
+            await roleService.removePermissionsFromRole(ctx.params.roleId, body.permissionIds);
+            ctx.status = 204;
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // GET /:roleId/users — List users with this role (org-scoped, paginated)
+    // Requires ?orgId=... query parameter
+    // -------------------------------------------------------------------------
+    router.get('/:roleId/users', requirePermission(ADMIN_PERMISSIONS.ROLE_READ), async (ctx) => {
+        try {
+            const query = listUsersWithRoleSchema.parse(ctx.query);
+            const result = await userRoleService.getUsersWithRole(ctx.params.roleId, query.orgId, {
+                page: query.page,
+                pageSize: query.pageSize,
+            });
+            ctx.body = { data: result.rows, total: result.total };
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    return router;
+}
+//# sourceMappingURL=roles.js.map

package/dist/routes/roles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.js","sourceRoot":"","sources":["../../src/routes/roles.ts"],"names":[],"mappings":"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"}

package/dist/routes/sessions.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Session management API routes.
+ *
+ * Provides admin endpoints for listing, viewing, and revoking OIDC sessions.
+ * Session data is read from the PostgreSQL tracking table (`admin_sessions`),
+ * which mirrors Redis session state via fire-and-forget hooks.
+ *
+ * Route structure:
+ *   GET    /api/admin/sessions              — List active sessions (paginated)
+ *   GET    /api/admin/sessions/:sessionId   — Get session detail
+ *   DELETE /api/admin/sessions/:sessionId   — Revoke a session
+ *   DELETE /api/admin/users/:userId/sessions — Revoke all user sessions
+ *
+ * @see 05-dashboard-sessions-history.md
+ */
+import Router from '@koa/router';
+/**
+ * Create the session management router.
+ *
+ * All routes require admin authentication (Bearer JWT) and appropriate
+ * session permissions.
+ *
+ * @returns Configured Koa Router with two sub-routers:
+ *   - /api/admin/sessions/* for session CRUD
+ *   - /api/admin/users/:userId/sessions for user session revocation
+ */
+export declare function createSessionRouter(): Router;
+/**
+ * Create the user session revocation router.
+ *
+ * Mounted separately because it lives under /api/admin/users/:userId/sessions
+ * rather than /api/admin/sessions.
+ *
+ * @returns Configured Koa Router
+ */
+export declare function createUserSessionRouter(): Router;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/routes/sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../../src/routes/sessions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,MAAM,MAAM,aAAa,CAAC;AA6BjC;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAuD5C;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAehD"}

package/dist/routes/sessions.js

@@ -0,0 +1,121 @@
+/**
+ * Session management API routes.
+ *
+ * Provides admin endpoints for listing, viewing, and revoking OIDC sessions.
+ * Session data is read from the PostgreSQL tracking table (`admin_sessions`),
+ * which mirrors Redis session state via fire-and-forget hooks.
+ *
+ * Route structure:
+ *   GET    /api/admin/sessions              — List active sessions (paginated)
+ *   GET    /api/admin/sessions/:sessionId   — Get session detail
+ *   DELETE /api/admin/sessions/:sessionId   — Revoke a session
+ *   DELETE /api/admin/users/:userId/sessions — Revoke all user sessions
+ *
+ * @see 05-dashboard-sessions-history.md
+ */
+import Router from '@koa/router';
+import { z } from 'zod';
+import { requireAdminAuth } from '../middleware/admin-auth.js';
+import { requirePermission } from '../middleware/require-permission.js';
+import { ADMIN_PERMISSIONS } from '../lib/admin-permissions.js';
+import * as sessionTracking from '../lib/session-tracking.js';
+import { getRedis } from '../lib/redis.js';
+import { afterDatabaseCommit } from '../lib/database.js';
+// ---------------------------------------------------------------------------
+// Validation schemas
+// ---------------------------------------------------------------------------
+const listSessionsSchema = z.object({
+    userId: z.string().uuid().optional(),
+    organizationId: z.string().uuid().optional(),
+    clientId: z.string().uuid().optional(),
+    activeOnly: z
+        .enum(['true', 'false'])
+        .transform((v) => v === 'true')
+        .optional(),
+    page: z.coerce.number().int().min(1).default(1),
+    pageSize: z.coerce.number().int().min(1).max(100).default(20),
+});
+// ---------------------------------------------------------------------------
+// Router factory
+// ---------------------------------------------------------------------------
+/**
+ * Create the session management router.
+ *
+ * All routes require admin authentication (Bearer JWT) and appropriate
+ * session permissions.
+ *
+ * @returns Configured Koa Router with two sub-routers:
+ *   - /api/admin/sessions/* for session CRUD
+ *   - /api/admin/users/:userId/sessions for user session revocation
+ */
+export function createSessionRouter() {
+    const router = new Router({ prefix: '/api/admin/sessions' });
+    // All routes require admin authentication
+    router.use(requireAdminAuth());
+    // -------------------------------------------------------------------------
+    // GET / — List sessions (paginated)
+    // -------------------------------------------------------------------------
+    router.get('/', requirePermission(ADMIN_PERMISSIONS.SESSION_READ), async (ctx) => {
+        const query = listSessionsSchema.parse(ctx.query);
+        const result = await sessionTracking.listSessions(query);
+        ctx.body = result;
+    });
+    // -------------------------------------------------------------------------
+    // GET /:sessionId — Get session detail
+    // -------------------------------------------------------------------------
+    router.get('/:sessionId', requirePermission(ADMIN_PERMISSIONS.SESSION_READ), async (ctx) => {
+        const session = await sessionTracking.getSession(ctx.params.sessionId);
+        if (!session) {
+            ctx.throw(404, 'Session not found');
+            return;
+        }
+        ctx.body = { data: session };
+    });
+    // -------------------------------------------------------------------------
+    // DELETE /:sessionId — Revoke a session
+    //
+    // Revocation cascade:
+    //   1. Mark session as revoked in PostgreSQL tracking table
+    //   2. Delete session from Redis (kills the live session)
+    //   3. Audit log entry for session revocation
+    // -------------------------------------------------------------------------
+    router.delete('/:sessionId', requirePermission(ADMIN_PERMISSIONS.SESSION_REVOKE), async (ctx) => {
+        const { sessionId } = ctx.params;
+        // 1. Mark revoked in PG tracking table
+        await sessionTracking.revokeSession(sessionId);
+        // 2. Delete from Redis to kill the live session
+        await afterDatabaseCommit(async () => {
+            try {
+                const redis = getRedis();
+                await redis.del(`oidc:Session:${sessionId}`);
+            }
+            catch {
+                // Redis deletion failure is non-fatal — session will expire naturally.
+            }
+        });
+        ctx.status = 204;
+    });
+    return router;
+}
+/**
+ * Create the user session revocation router.
+ *
+ * Mounted separately because it lives under /api/admin/users/:userId/sessions
+ * rather than /api/admin/sessions.
+ *
+ * @returns Configured Koa Router
+ */
+export function createUserSessionRouter() {
+    const router = new Router({ prefix: '/api/admin/users/:userId/sessions' });
+    router.use(requireAdminAuth());
+    // -------------------------------------------------------------------------
+    // DELETE / — Revoke all sessions for a user
+    // -------------------------------------------------------------------------
+    router.delete('/', requirePermission(ADMIN_PERMISSIONS.SESSION_REVOKE), async (ctx) => {
+        const { userId } = ctx.params;
+        const count = await sessionTracking.revokeUserSessions(userId);
+        ctx.body = { revoked: count };
+    });
+    return router;
+}
+//# sourceMappingURL=sessions.js.map

package/dist/routes/sessions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.js","sourceRoot":"","sources":["../../src/routes/sessions.ts"],"names":[],"mappings":"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"}

package/dist/routes/stats.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Dashboard statistics API routes.
+ *
+ * Provides system-wide and per-organization statistics for the admin
+ * dashboard. All responses include Cache-Control headers for client-side
+ * caching (60s).
+ *
+ * Route structure:
+ *   GET /api/admin/stats/overview              — System-wide statistics
+ *   GET /api/admin/stats/organization/:orgId   — Per-organization statistics
+ *
+ * Both endpoints require `stats:read` permission.
+ *
+ * @see 05-dashboard-sessions-history.md
+ */
+import Router from '@koa/router';
+/**
+ * Create the dashboard statistics router.
+ *
+ * All routes require admin authentication (Bearer JWT) and `stats:read`
+ * permission. Responses are cacheable for 60 seconds.
+ *
+ * Prefix: /api/admin/stats
+ *
+ * @returns Configured Koa Router
+ */
+export declare function createStatsRouter(): Router;
+//# sourceMappingURL=stats.d.ts.map

package/dist/routes/stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.d.ts","sourceRoot":"","sources":["../../src/routes/stats.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,MAAM,MAAM,aAAa,CAAC;AAoBjC;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CA0B1C"}