@portaidentity/server 1.7.0

package/dist/routes/magic-link.js

@@ -0,0 +1,264 @@
+/**
+ * Magic link verification route handler.
+ *
+ * Handles the callback when a user clicks the magic link in their email.
+ * Verifies the token, marks the user's email as verified, records the login,
+ * and creates a short-lived `_ml_session` in Redis. Then redirects to the
+ * interaction login page where the session cookie is detected and either:
+ *   - **Same browser**: OIDC flow completes seamlessly via interactionFinished()
+ *   - **Different browser**: success page shown ("return to original browser")
+ *
+ * Route structure:
+ *   GET /:orgSlug/auth/magic-link/:token → verifyMagicLink
+ *
+ * The tenant resolver middleware runs before this route, ensuring
+ * ctx.state.organization is populated with the resolved organization.
+ *
+ * Security features:
+ *   - Token is hashed (SHA-256) before DB lookup — plaintext never stored
+ *   - Token is single-use (marked as used after verification)
+ *   - Expired/used tokens show a generic error page
+ *   - `_ml_session` is HttpOnly, 5-min TTL, single-use (Redis-backed)
+ *   - Audit logging for all magic link events
+ */
+import Router from '@koa/router';
+import { tenantResolver } from '../middleware/tenant-resolver.js';
+import { hashToken } from '../auth/tokens.js';
+import { consumeAuthorizedMagicLink } from '../auth/token-repository.js';
+import { resolveLocale, getTranslationFunction } from '../auth/i18n.js';
+import { renderPage } from '../auth/template-engine.js';
+import { generateCsrfToken } from '../auth/csrf.js';
+import { invalidateUserCache } from '../users/cache.js';
+import { createMagicLinkSession } from '../auth/magic-link-session.js';
+import { writeAuditLog } from '../lib/audit-log.js';
+import { logger } from '../lib/logger.js';
+import { createInteractionAuthorityResolver, } from '../auth/interaction-authority.js';
+import { buildMagicLinkCallbackRateLimitKey, checkRateLimitStrict, loadMagicLinkRateLimitConfig, } from '../auth/rate-limiter.js';
+import { magicLinkCallbackArtifactDigest } from '../auth/recovery-crypto.js';
+/** Production dependencies used unless a test owns an explicit failure boundary. */
+const DEFAULT_MAGIC_LINK_ROUTE_DEPENDENCIES = {
+    checkCallbackRateLimit: checkRateLimitStrict,
+};
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Build branding context from organization data.
+ *
+ * @param org - Organization with branding fields
+ * @returns Branding context for templates
+ */
+function buildBrandingFromOrg(org) {
+    return {
+        logoUrl: org.brandingLogoUrl,
+        faviconUrl: org.brandingFaviconUrl,
+        primaryColor: org.brandingPrimaryColor ?? '#3B82F6',
+        companyName: org.brandingCompanyName ?? org.name,
+        customCss: org.brandingCustomCss,
+    };
+}
+/**
+ * Parse the optional interaction query without normalizing malformed input into standalone use.
+ *
+ * @param value - Raw Koa query value.
+ * @returns Exact bounded interaction authority and a fail-closed validity discriminator.
+ */
+function parsePresentedInteraction(value) {
+    if (value === undefined)
+        return { valid: true, value: null };
+    if (typeof value !== 'string' || value.length < 1 || value.length > 128) {
+        return { valid: false, value: null };
+    }
+    return { valid: true, value };
+}
+// ---------------------------------------------------------------------------
+// Router factory
+// ---------------------------------------------------------------------------
+/**
+ * Create the magic link auth router.
+ *
+ * Handles magic link token verification at /:orgSlug/auth/magic-link/:token. Interaction-bound
+ * callbacks resolve their current client through the provider before durable authority is used.
+ *
+ * @param provider - Provider-owned live interaction model. Omit only for standalone callbacks.
+ * @param dependencies - Fail-closed callback-limiter boundary.
+ * @returns Koa router with magic link routes
+ */
+export function createMagicLinkRouter(provider, dependencies = DEFAULT_MAGIC_LINK_ROUTE_DEPENDENCIES) {
+    const router = new Router();
+    const interactionAuthority = provider ? createInteractionAuthorityResolver(provider) : null;
+    // Tenant resolver — resolves orgSlug to organization and sets ctx.state.organization.
+    // Applied at route level because this router is mounted directly on the Koa app
+    // (not under the OIDC catch-all router which has its own tenant resolver).
+    const resolve = tenantResolver();
+    // GET /:orgSlug/auth/magic-link/:token — Verify magic link
+    router.get('/:orgSlug/auth/magic-link/:token', resolve, async (ctx) => {
+        await verifyMagicLink(ctx, interactionAuthority, dependencies);
+    });
+    return router;
+}
+// ---------------------------------------------------------------------------
+// Route handler
+// ---------------------------------------------------------------------------
+/**
+ * Verify a magic link token and set up the `_ml_session` for flow completion.
+ *
+ * 1. Hashes the token from URL params for DB lookup
+ * 2. Locks and validates the token, route tenant, account, and persisted interaction authority
+ * 3. If invalid/expired: renders error page with "link expired" message
+ * 4. If valid:
+ *    a. Atomically consumes the token, updates the user, and writes the successful audit row
+ *    e. Creates `_ml_session` in Redis (5-min TTL, single-use)
+ *    f. Redirects to `/interaction/{uid}` where the interaction handler
+ *       detects the session cookie and completes the OIDC flow (same
+ *       browser) or shows a "return to original browser" page (different
+ *       browser)
+ *
+ * @param ctx - Koa context with organization state
+ */
+async function verifyMagicLink(ctx, interactionAuthority, dependencies) {
+    const org = ctx.state.organization;
+    const tokenPlaintext = ctx.params.token;
+    const presentedInteraction = parsePresentedInteraction(ctx.query.interaction);
+    // Resolve locale for error pages
+    const locale = await resolveLocale(undefined, ctx.get('Accept-Language') || undefined, org.defaultLocale);
+    const t = getTranslationFunction(locale, org.slug);
+    try {
+        // Step 1: Hash the token for DB lookup
+        const tokenHash = hashToken(tokenPlaintext);
+        const socketPeer = ctx.req.socket.remoteAddress ?? 'unavailable';
+        const rateLimitKey = buildMagicLinkCallbackRateLimitKey(org.id, socketPeer, magicLinkCallbackArtifactDigest(tokenPlaintext));
+        const rateLimit = await dependencies.checkCallbackRateLimit(rateLimitKey, await loadMagicLinkRateLimitConfig());
+        if (!rateLimit.allowed) {
+            await rejectMagicLink(ctx, org, locale, t);
+            return;
+        }
+        const liveAuthority = presentedInteraction.valid && presentedInteraction.value !== null && interactionAuthority
+            ? await interactionAuthority.resolve(presentedInteraction.value)
+            : null;
+        const interactionAccepted = presentedInteraction.valid &&
+            (presentedInteraction.value === null ||
+                (liveAuthority !== null && liveAuthority.interactionUid === presentedInteraction.value));
+        // Step 2: Lock and validate all durable authority before any successful mutation.
+        const authority = interactionAccepted
+            ? await consumeAuthorizedMagicLink({
+                tokenHash,
+                organizationId: org.id,
+                interactionUid: presentedInteraction.value,
+                clientId: liveAuthority?.clientId ?? null,
+                ipAddress: ctx.ip,
+            })
+            : null;
+        if (!authority) {
+            await rejectMagicLink(ctx, org, locale, t);
+            return;
+        }
+        // The durable transaction has committed. Remove any stale cached account representation.
+        await invalidateUserCache(authority.userId);
+        // Step 8: Complete the OIDC flow via _ml_session cookie.
+        //
+        // Create a magic link session and redirect to the interaction handler.
+        // The interaction handler will detect the session cookie and complete
+        // the OIDC flow (same browser) or show a success page (different browser).
+        if (authority.interactionUid) {
+            await createMagicLinkSession(ctx, {
+                userId: authority.userId,
+                interactionUid: authority.interactionUid,
+                organizationId: org.id,
+            });
+            ctx.redirect(`/interaction/${authority.interactionUid}`);
+            return;
+        }
+        // No interaction UID — magic link opened outside an OIDC flow.
+        // Show the magic link success page (standalone authentication confirmation).
+        logger.info({ event: 'magic-link-standalone-completed' }, 'Magic link verification completed');
+        await renderSuccessPageForAuth(ctx, org, locale, t);
+    }
+    catch {
+        logger.error({ event: 'magic-link-verification-failed' }, 'Magic link verification failed');
+        await renderErrorPageForAuth(ctx, org, locale, t, t('errors.generic'));
+    }
+}
+/** Render and audit the one generic callback rejection without retaining bearer authority. */
+async function rejectMagicLink(ctx, org, locale, t) {
+    writeAuditLog({
+        organizationId: org.id,
+        eventType: 'user.magic_link.failed',
+        eventCategory: 'security',
+        description: 'Magic link verification failed: invalid or expired token',
+        ipAddress: ctx.ip,
+    });
+    await renderErrorPageForAuth(ctx, org, locale, t, t('errors.magic_link_expired'));
+}
+// ---------------------------------------------------------------------------
+// Helper: render success page for auth routes
+// ---------------------------------------------------------------------------
+/**
+ * Render a success page when a magic link is verified outside an OIDC flow.
+ *
+ * This handles the edge case where a magic link URL doesn't have an
+ * interaction UID (e.g., link was malformed or interaction expired).
+ * Shows a generic "email verified" confirmation instead of redirecting
+ * to the forgot-password page.
+ *
+ * @param ctx - Koa context
+ * @param org - Organization for branding
+ * @param locale - Resolved locale
+ * @param t - Translation function
+ */
+async function renderSuccessPageForAuth(ctx, org, locale, t) {
+    try {
+        const csrfToken = generateCsrfToken();
+        const context = {
+            branding: buildBrandingFromOrg(org),
+            locale,
+            t,
+            csrfToken,
+            orgSlug: org.slug,
+        };
+        const html = await renderPage('magic-link-success', context);
+        ctx.status = 200;
+        ctx.type = 'text/html';
+        ctx.body = html;
+    }
+    catch {
+        logger.error({ event: 'magic-link-success-render-failed' }, 'Magic link success page failed');
+        ctx.status = 200;
+        ctx.body = 'Your email has been verified. You may close this tab.';
+    }
+}
+// ---------------------------------------------------------------------------
+// Helper: render error page for auth routes
+// ---------------------------------------------------------------------------
+/**
+ * Render an error page for auth routes (outside OIDC interaction flow).
+ *
+ * @param ctx - Koa context
+ * @param org - Organization for branding
+ * @param locale - Resolved locale
+ * @param t - Translation function
+ * @param errorMessage - Error message to display
+ */
+async function renderErrorPageForAuth(ctx, org, locale, t, errorMessage) {
+    try {
+        const csrfToken = generateCsrfToken();
+        const context = {
+            branding: buildBrandingFromOrg(org),
+            locale,
+            t,
+            csrfToken,
+            orgSlug: org.slug,
+            errorMessage,
+        };
+        const html = await renderPage('error', context);
+        ctx.status = 400;
+        ctx.type = 'text/html';
+        ctx.body = html;
+    }
+    catch {
+        logger.error({ event: 'auth-error-render-failed' }, 'Authentication error page failed');
+        ctx.status = 500;
+        ctx.body = 'An error occurred';
+    }
+}
+//# sourceMappingURL=magic-link.js.map

package/dist/routes/magic-link.js.map

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

package/dist/routes/organizations.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Organization management API routes.
+ *
+ * All routes are under `/api/admin/organizations` and require
+ * admin authentication (Bearer JWT). Provides CRUD, status lifecycle,
+ * branding management, and slug validation endpoints.
+ *
+ * Route structure:
+ *   POST   /                  — Create a new organization
+ *   GET    /                  — List organizations (paginated)
+ *   GET    /validate-slug     — Validate slug availability
+ *   GET    /:id               — Get organization by ID
+ *   PUT    /:id               — Update organization
+ *   PUT    /:id/branding      — Update branding
+ *   POST   /:id/suspend       — Suspend organization
+ *   POST   /:id/activate      — Activate organization
+ *   POST   /:id/archive       — Archive organization
+ *   POST   /:id/restore       — Restore organization
+ *
+ * Error mapping:
+ *   OrganizationNotFoundError → 404
+ *   OrganizationValidationError → 400
+ *   ZodError → 400 with validation details
+ */
+import Router from '@koa/router';
+/**
+ * Create the organization management router.
+ *
+ * All routes require admin authentication (Bearer JWT via requireAdminAuth).
+ * The middleware validates the token, checks the user belongs to the
+ * super-admin org, and verifies the porta-admin role.
+ *
+ * Prefix: /api/admin/organizations
+ *
+ * @returns Configured Koa Router
+ */
+export declare function createOrganizationRouter(): Router;
+//# sourceMappingURL=organizations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"organizations.d.ts","sourceRoot":"","sources":["../../src/routes/organizations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,MAAM,MAAM,aAAa,CAAC;AAqIjC;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,CA2MjD"}

package/dist/routes/organizations.js

@@ -0,0 +1,347 @@
+/**
+ * Organization management API routes.
+ *
+ * All routes are under `/api/admin/organizations` and require
+ * admin authentication (Bearer JWT). Provides CRUD, status lifecycle,
+ * branding management, and slug validation endpoints.
+ *
+ * Route structure:
+ *   POST   /                  — Create a new organization
+ *   GET    /                  — List organizations (paginated)
+ *   GET    /validate-slug     — Validate slug availability
+ *   GET    /:id               — Get organization by ID
+ *   PUT    /:id               — Update organization
+ *   PUT    /:id/branding      — Update branding
+ *   POST   /:id/suspend       — Suspend organization
+ *   POST   /:id/activate      — Activate organization
+ *   POST   /:id/archive       — Archive organization
+ *   POST   /:id/restore       — Restore organization
+ *
+ * Error mapping:
+ *   OrganizationNotFoundError → 404
+ *   OrganizationValidationError → 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 organizationService from '../organizations/service.js';
+import { setETagHeader, checkIfMatch } from '../lib/etag.js';
+import { getEntityHistory } from '../lib/entity-history.js';
+import { OrganizationNotFoundError, OrganizationValidationError } from '../organizations/errors.js';
+import { LOGIN_METHODS } from '../clients/types.js';
+// ---------------------------------------------------------------------------
+// Validation schemas
+// ---------------------------------------------------------------------------
+/**
+ * Login method Zod schema — single source of truth for HTTP payload validation.
+ * Uses the runtime `LOGIN_METHODS` const so adding a new method only requires
+ * updating the union in `src/clients/types.ts`.
+ */
+const loginMethodSchema = z.enum(LOGIN_METHODS);
+/**
+ * Organization-level default login methods — a non-empty array (empty arrays
+ * are rejected by the service layer and must be rejected at the HTTP boundary
+ * too so the 400 carries a useful validation message).
+ */
+const defaultLoginMethodsSchema = z.array(loginMethodSchema).min(1);
+const createOrganizationSchema = z.object({
+    name: z.string().min(1).max(255),
+    slug: z.string().min(3).max(100).optional(),
+    defaultLocale: z.string().min(2).max(10).optional(),
+    defaultLoginMethods: defaultLoginMethodsSchema.optional(),
+    branding: z
+        .object({
+        logoUrl: z.string().url().nullable().optional(),
+        faviconUrl: z.string().url().nullable().optional(),
+        primaryColor: z
+            .string()
+            .regex(/^#[0-9A-Fa-f]{6}$/)
+            .nullable()
+            .optional(),
+        companyName: z.string().max(255).nullable().optional(),
+        customCss: z.string().max(10000).nullable().optional(),
+    })
+        .optional(),
+});
+const updateOrganizationSchema = z.object({
+    name: z.string().min(1).max(255).optional(),
+    defaultLocale: z.string().min(2).max(10).optional(),
+    defaultLoginMethods: defaultLoginMethodsSchema.optional(),
+    branding: z
+        .object({
+        logoUrl: z.string().url().nullable().optional(),
+        faviconUrl: z.string().url().nullable().optional(),
+        primaryColor: z
+            .string()
+            .regex(/^#[0-9A-Fa-f]{6}$/)
+            .nullable()
+            .optional(),
+        companyName: z.string().max(255).nullable().optional(),
+        customCss: z.string().max(10000).nullable().optional(),
+    })
+        .optional(),
+});
+const updateBrandingSchema = z.object({
+    logoUrl: z.string().url().nullable().optional(),
+    faviconUrl: z.string().url().nullable().optional(),
+    primaryColor: z
+        .string()
+        .regex(/^#[0-9A-Fa-f]{6}$/)
+        .nullable()
+        .optional(),
+    companyName: z.string().max(255).nullable().optional(),
+    customCss: z.string().max(10000).nullable().optional(),
+});
+const listOrganizationsSchema = z.object({
+    page: z.coerce.number().int().min(1).default(1),
+    pageSize: z.coerce.number().int().min(1).max(100).default(20),
+    status: z.enum(['active', 'suspended', 'archived']).optional(),
+    search: z.string().max(255).optional(),
+    sortBy: z.enum(['name', 'created_at']).default('created_at'),
+    sortOrder: z.enum(['asc', 'desc']).default('desc'),
+});
+/** Schema for cursor-based listing (keyset pagination) */
+const listOrganizationsCursorSchema = z.object({
+    cursor: z.string().optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(25),
+    status: z.enum(['active', 'suspended', 'archived']).optional(),
+    search: z.string().max(255).optional(),
+    sortBy: z.enum(['name', 'created_at']).default('created_at'),
+    sortOrder: z.enum(['asc', 'desc']).default('desc'),
+});
+const validateSlugSchema = z.object({
+    slug: z.string().min(1),
+});
+// ---------------------------------------------------------------------------
+// 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 OrganizationNotFoundError) {
+        ctx.throw(404, 'Organization not found');
+    }
+    if (err instanceof OrganizationValidationError) {
+        ctx.throw(400, 'Organization request is invalid');
+    }
+    if (err instanceof z.ZodError) {
+        ctx.status = 400;
+        ctx.body = { error: 'Organization request is invalid' };
+        return undefined;
+    }
+    throw err;
+}
+// ---------------------------------------------------------------------------
+// Router factory
+// ---------------------------------------------------------------------------
+/**
+ * Create the organization management router.
+ *
+ * All routes require admin authentication (Bearer JWT via requireAdminAuth).
+ * The middleware validates the token, checks the user belongs to the
+ * super-admin org, and verifies the porta-admin role.
+ *
+ * Prefix: /api/admin/organizations
+ *
+ * @returns Configured Koa Router
+ */
+export function createOrganizationRouter() {
+    const router = new Router({ prefix: '/api/admin/organizations' });
+    // All routes require admin authentication
+    router.use(requireAdminAuth());
+    // -------------------------------------------------------------------------
+    // POST / — Create organization
+    // -------------------------------------------------------------------------
+    router.post('/', requirePermission(ADMIN_PERMISSIONS.ORG_CREATE), async (ctx) => {
+        try {
+            const body = createOrganizationSchema.parse(ctx.request.body);
+            const org = await organizationService.createOrganization(body);
+            ctx.status = 201;
+            ctx.body = { data: org };
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // GET / — List organizations (paginated)
+    // -------------------------------------------------------------------------
+    router.get('/', requirePermission(ADMIN_PERMISSIONS.ORG_READ), async (ctx) => {
+        try {
+            // Cursor-based pagination when `cursor` or `limit` param is present
+            if (ctx.query.cursor !== undefined || ctx.query.limit !== undefined) {
+                const query = listOrganizationsCursorSchema.parse(ctx.query);
+                const result = await organizationService.listOrganizationsCursor(query);
+                ctx.body = result;
+                return;
+            }
+            // Default: offset-based pagination (backward compatible)
+            const query = listOrganizationsSchema.parse(ctx.query);
+            const result = await organizationService.listOrganizations(query);
+            ctx.body = result;
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // GET /validate-slug — Validate slug availability
+    // Must be BEFORE /:id to avoid matching "validate-slug" as an :id param
+    // -------------------------------------------------------------------------
+    router.get('/validate-slug', requirePermission(ADMIN_PERMISSIONS.ORG_READ), async (ctx) => {
+        try {
+            const { slug } = validateSlugSchema.parse(ctx.query);
+            const result = await organizationService.validateSlugAvailability(slug);
+            ctx.body = result;
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // GET /:id — Get organization by ID
+    // -------------------------------------------------------------------------
+    router.get('/:id', requirePermission(ADMIN_PERMISSIONS.ORG_READ), async (ctx) => {
+        const param = ctx.params.id;
+        // Support both UUID and slug lookups — CLI and API consumers may use either
+        const isUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(param);
+        const org = isUuid
+            ? await organizationService.getOrganizationById(param)
+            : await organizationService.getOrganizationBySlug(param);
+        if (!org) {
+            ctx.throw(404, 'Organization not found');
+            return; // unreachable — keeps TS narrowing happy
+        }
+        setETagHeader(ctx, 'organization', org.id, org.updatedAt);
+        ctx.body = { data: org };
+    });
+    // -------------------------------------------------------------------------
+    // PUT /:id — Update organization
+    // -------------------------------------------------------------------------
+    router.put('/:id', requirePermission(ADMIN_PERMISSIONS.ORG_UPDATE), async (ctx) => {
+        try {
+            const body = updateOrganizationSchema.parse(ctx.request.body);
+            // Check If-Match for optimistic concurrency (optional — backward compatible)
+            const current = await organizationService.getOrganizationById(ctx.params.id);
+            if (current && !checkIfMatch(ctx, 'organization', current.id, current.updatedAt, current))
+                return;
+            const org = await organizationService.updateOrganization(ctx.params.id, body);
+            setETagHeader(ctx, 'organization', org.id, org.updatedAt);
+            ctx.body = { data: org };
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // PUT /:id/branding — Update branding
+    // -------------------------------------------------------------------------
+    router.put('/:id/branding', requirePermission(ADMIN_PERMISSIONS.ORG_UPDATE), async (ctx) => {
+        try {
+            const body = updateBrandingSchema.parse(ctx.request.body);
+            const org = await organizationService.updateOrganizationBranding(ctx.params.id, body);
+            ctx.body = { data: org };
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // POST /:id/suspend — Suspend organization
+    // -------------------------------------------------------------------------
+    router.post('/:id/suspend', requirePermission(ADMIN_PERMISSIONS.ORG_SUSPEND), async (ctx) => {
+        try {
+            const body = ctx.request.body;
+            await organizationService.suspendOrganization(ctx.params.id, body?.reason);
+            ctx.status = 204;
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // POST /:id/activate — Activate organization
+    // -------------------------------------------------------------------------
+    router.post('/:id/activate', requirePermission(ADMIN_PERMISSIONS.ORG_SUSPEND), async (ctx) => {
+        try {
+            await organizationService.activateOrganization(ctx.params.id);
+            ctx.status = 204;
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // POST /:id/archive — Archive organization
+    // -------------------------------------------------------------------------
+    router.post('/:id/archive', requirePermission(ADMIN_PERMISSIONS.ORG_ARCHIVE), async (ctx) => {
+        try {
+            await organizationService.archiveOrganization(ctx.params.id);
+            ctx.status = 204;
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // GET /:id/history — Organization change history
+    // -------------------------------------------------------------------------
+    router.get('/:id/history', requirePermission(ADMIN_PERMISSIONS.ORG_READ), async (ctx) => {
+        const { limit, after, event_type } = ctx.query;
+        const result = await getEntityHistory('organization', ctx.params.id, {
+            limit: limit ? parseInt(limit, 10) : undefined,
+            after: after || undefined,
+            eventTypePrefix: event_type || undefined,
+        });
+        ctx.body = result;
+    });
+    // -------------------------------------------------------------------------
+    // POST /:id/restore — Restore organization
+    // -------------------------------------------------------------------------
+    router.post('/:id/restore', requirePermission(ADMIN_PERMISSIONS.ORG_ARCHIVE), async (ctx) => {
+        try {
+            await organizationService.restoreOrganization(ctx.params.id);
+            ctx.status = 204;
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // DELETE /:idOrSlug — Permanently destroy organization (cascade)
+    // -------------------------------------------------------------------------
+    router.delete('/:idOrSlug', requirePermission(ADMIN_PERMISSIONS.ORG_ARCHIVE), async (ctx) => {
+        try {
+            const { idOrSlug } = ctx.params;
+            const dryRun = ctx.query['dry-run'] === 'true';
+            if (dryRun) {
+                // Resolve org and return cascade counts without deleting
+                const org = (await organizationService.getOrganizationById(idOrSlug)) ??
+                    (await organizationService.getOrganizationBySlug(idOrSlug));
+                if (!org) {
+                    ctx.throw(404, `Organization not found: ${idOrSlug}`);
+                    return;
+                }
+                if (org.isSuperAdmin) {
+                    ctx.throw(400, 'Cannot destroy the super-admin organization');
+                    return;
+                }
+                const cascadeCounts = await organizationService.getCascadeCounts(org.id);
+                ctx.body = { dryRun: true, organization: org, cascadeCounts };
+                return;
+            }
+            const result = await organizationService.destroyOrganization(idOrSlug, ctx.state.adminUser?.id);
+            ctx.body = result;
+        }
+        catch (err) {
+            handleError(ctx, err);
+        }
+    });
+    return router;
+}
+//# sourceMappingURL=organizations.js.map