@helyx/bot 1.4.0 → 1.5.1

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 1.5.1
+
+### Patch Changes
+
+- Add the server-scoped `/diag` command with administrator access, one active
+  run per server, guarded repair passes and fresh checks before reporting fixes.
+  Preserve records and configuration outside the explicitly supported repairs.
+- Require PostgreSQL adapter 2.4.1 or MySQL adapter 0.2.1 for the active,
+  non-blacklisted server lookup used by diagnostic admission checks.
+
+## 1.5.0
+
+### Minor Changes
+
+- 7034a9c: Add bounded read-only Channel audit contracts and Discord inspection for Access
+  Control and hosted Verification. The dashboard can explicitly load a narrow
+  channel/role configuration projection and inspect combined role assumptions
+  without enabling the module, changing Discord or saving audit results.
+
+  Cloud Connect uses two explicit negotiated read capabilities for Access Control.
+  Update the hosted API/gateway and self-hosted bot as a coordinated compatible
+  release; older connectors give an explicit unsupported response. No database
+  migration is required. This changeset records future package impact only;
+  versions and publication remain separately controlled.
+
+### Patch Changes
+
+- Updated dependencies [7034a9c]
+  - @helyx/sdk@0.16.0
+  - @helyx/control-protocol@0.8.0
+  - @helyx/module-automod@1.1.1
+  - @helyx/module-moderation@1.1.1
+
 ## 1.4.0
 
 ### Minor Changes

package/dist/channel-audit-configuration.d.ts

@@ -0,0 +1,7 @@
+import type { ChannelAuditConfiguration, ChannelAuditModuleId } from "@helyx/sdk";
+/** Deliberate allowlist: never return provider state, answers or the saved settings object. */
+export declare function channelAuditConfiguration(moduleId: ChannelAuditModuleId, configuration: {
+    version: number;
+    value: Record<string, unknown>;
+} | null): ChannelAuditConfiguration;
+//# sourceMappingURL=channel-audit-configuration.d.ts.map

package/dist/channel-audit-configuration.js

@@ -0,0 +1,40 @@
+import { CHANNEL_AUDIT_LIMITS, channelAuditConfigurationSchema, } from "@helyx/control-protocol/channel-audit";
+/** Deliberate allowlist: never return provider state, answers or the saved settings object. */
+export function channelAuditConfiguration(moduleId, configuration) {
+    const value = configuration?.value ?? {};
+    const mappedFields = [];
+    const id = (field) => {
+        const candidate = value[field];
+        if (typeof candidate !== "string" || !/^\d{17,20}$/u.test(candidate))
+            return null;
+        mappedFields.push(field);
+        return candidate;
+    };
+    const entryChannelId = id(moduleId === "helyx.account-gate"
+        ? "gateChannelId"
+        : "verificationChannelId");
+    const afterRoleId = id("verifiedRoleId");
+    const reviewChannelId = moduleId === "helyx.account-gate" ? id("reviewChannelId") : null;
+    const configuredRoles = moduleId === "helyx.account-gate" && Array.isArray(value.temporaryRoleIds)
+        ? [
+            ...new Set(value.temporaryRoleIds.filter((role) => typeof role === "string" && /^\d{17,20}$/u.test(role))),
+        ]
+        : [];
+    if (configuredRoles.length)
+        mappedFields.push("temporaryRoleIds");
+    const suggested = moduleId === "helyx.verification" ? id("roleToRemoveId") : null;
+    const beforeRoleIds = suggested
+        ? [suggested]
+        : configuredRoles.slice(0, CHANNEL_AUDIT_LIMITS.beforeRoles);
+    return channelAuditConfigurationSchema.parse({
+        moduleId,
+        version: configuration?.version ?? null,
+        entryChannelId,
+        beforeRoleIds,
+        afterRoleId,
+        reviewChannelId,
+        mappedFields,
+        truncated: configuredRoles.length > CHANNEL_AUDIT_LIMITS.beforeRoles,
+    });
+}
+//# sourceMappingURL=channel-audit-configuration.js.map

package/dist/channel-audit-control.d.ts

@@ -0,0 +1,14 @@
+import { type ChannelAuditControl, type GuildAccessPolicy, type ModuleConfigurationService, type ModuleDefinition, type PermissionPolicyService, type ServiceAccess } from "@helyx/sdk";
+import type { BotControlGuildResourceDirectory, BotControlRepositories } from "./control-server.js";
+/** Read-only component: no action, transaction, settings-save or Discord mutation helpers. */
+export declare function createChannelAuditControl(input: {
+    modules: ReadonlyMap<string, ModuleDefinition>;
+    resources: Pick<BotControlGuildResourceDirectory, "resolveActor">;
+    configurations: ModuleConfigurationService;
+    permissions: PermissionPolicyService;
+    services: ServiceAccess;
+    listModules: BotControlRepositories["installations"]["listModules"];
+    readGuildPolicy(guildId: string): Promise<GuildAccessPolicy>;
+    requireAccessible(guildId: string, moduleId: string): Promise<void>;
+}): Required<ChannelAuditControl>;
+//# sourceMappingURL=channel-audit-control.d.ts.map

package/dist/channel-audit-control.js

@@ -0,0 +1,61 @@
+import { canAccessGuildDashboard, canUseCommand } from "@helyx/core";
+import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { channelAuditInputSchema, channelAuditModuleIdSchema, channelAuditReportSchema, } from "@helyx/control-protocol/channel-audit";
+import { BotControlForbiddenError, BotControlNotFoundError, BotControlTransportError, } from "./control-errors.js";
+import { safeVersion } from "./control-permissions.js";
+import { channelAuditConfiguration } from "./channel-audit-configuration.js";
+/** Read-only component: no action, transaction, settings-save or Discord mutation helpers. */
+export function createChannelAuditControl(input) {
+    const authorize = async (context) => {
+        channelAuditModuleIdSchema.parse(context.moduleId);
+        const module = input.modules.get(context.moduleId);
+        if (!module)
+            throw new BotControlNotFoundError("Module is not installed");
+        if (!module.manifest.dashboard)
+            throw new BotControlNotFoundError("Module is not dashboard configurable");
+        const [actor, guildAccess, resolvedPolicy, installed] = await Promise.all([
+            input.resources.resolveActor(context.guildId, context.actorUserId),
+            input.readGuildPolicy(context.guildId),
+            input.permissions.getPolicy(context.guildId, context.moduleId),
+            input.listModules(context.guildId),
+        ]);
+        if (!canAccessGuildDashboard(actor, guildAccess) ||
+            !canUseCommand(actor, resolvedPolicy.policy, guildAccess))
+            throw new BotControlForbiddenError("You no longer have permission to inspect this module's channel setup");
+        if (!installed.some((item) => item.moduleId === context.moduleId))
+            throw new BotControlNotFoundError("This module is not installed for this server");
+        await input.requireAccessible(context.guildId, context.moduleId);
+    };
+    return {
+        readChannelAuditConfiguration: async (context) => {
+            await authorize(context);
+            const configuration = await input.configurations.get(context.guildId, context.moduleId);
+            return channelAuditConfiguration(context.moduleId, configuration
+                ? {
+                    version: safeVersion(configuration.version),
+                    value: configuration.value,
+                }
+                : null);
+        },
+        checkChannelAudit: async (context) => {
+            const assumptions = channelAuditInputSchema.parse(context.assumptions);
+            await authorize(context);
+            if (!input.services.has(HELYX_SERVICE_NAMES.discordResources))
+                throw new BotControlTransportError(503, "Channel audit is not supported by this bot's Discord inspection service");
+            const inspection = input.services.get(HELYX_SERVICE_NAMES.discordResources);
+            if (!inspection.inspectChannelAudit)
+                throw new BotControlTransportError(503, "This bot version does not support Channel audit. Update the bot before trying again.");
+            const report = channelAuditReportSchema.parse(await inspection.inspectChannelAudit({
+                guildId: context.guildId,
+                moduleId: context.moduleId,
+                assumptions,
+            }));
+            if (report.guildId !== context.guildId ||
+                report.moduleId !== context.moduleId ||
+                JSON.stringify(report.assumptions) !== JSON.stringify(assumptions))
+                throw new BotControlTransportError(502, "Channel audit returned a different server or module context");
+            return report;
+        },
+    };
+}
+//# sourceMappingURL=channel-audit-control.js.map

package/dist/channel-audit-permissions.d.ts

@@ -0,0 +1,56 @@
+import type { ChannelAuditInput, ChannelAuditModuleId, ChannelAuditReport } from "@helyx/sdk";
+export declare const AUDIT_PERMISSIONS: {
+    readonly Administrator: bigint;
+    readonly ManageGuild: bigint;
+    readonly ViewChannel: bigint;
+    readonly SendMessages: bigint;
+    readonly ReadMessageHistory: bigint;
+    readonly Connect: bigint;
+    readonly Speak: bigint;
+    readonly ManageRoles: bigint;
+    readonly ManageChannels: bigint;
+    readonly KickMembers: bigint;
+    readonly BanMembers: bigint;
+    readonly RequestToSpeak: bigint;
+    readonly SendMessagesInThreads: bigint;
+};
+export interface AuditRoleSnapshot {
+    id: string;
+    permissions: bigint;
+    managed: boolean;
+    assignable: boolean | null;
+    assignmentReason?: string;
+    assignmentPolicyReason?: string;
+}
+export interface AuditChannelSnapshot {
+    id: string;
+    name: string;
+    type: number;
+    obfuscated: boolean;
+    overwrites: Array<{
+        id: string;
+        type: number;
+        allow: bigint;
+        deny: bigint;
+    }>;
+    botPermissions: bigint | null;
+}
+export interface AuditGuildSnapshot {
+    guildId: string;
+    roles: AuditRoleSnapshot[];
+    rolesComplete: boolean;
+    channels: AuditChannelSnapshot[];
+    fetchedChannels: number;
+    totalChannelsKnown: boolean;
+    fetchLimitations: string[];
+    invalidSelectedChannels?: Array<{
+        id: string;
+        reason: "not_found" | "wrong_guild";
+    }>;
+}
+/** Discord's role union, everyone overwrite, then aggregate role deny/allow. */
+export declare function effectiveAuditPermissions(guildId: string, roles: readonly AuditRoleSnapshot[], selectedRoleIds: readonly string[], channel: AuditChannelSnapshot): bigint | null;
+/** Raw bit presence is insufficient: view/connect prerequisites gate actions. */
+export declare function auditActions(permissions: bigint | null, type: number): string[];
+export declare function buildChannelAuditReport(snapshot: AuditGuildSnapshot, moduleId: ChannelAuditModuleId, assumptions: ChannelAuditInput, observedAt: string): ChannelAuditReport;
+//# sourceMappingURL=channel-audit-permissions.d.ts.map

package/dist/channel-audit-permissions.js

@@ -0,0 +1,417 @@
+import { CHANNEL_AUDIT_LIMITS } from "@helyx/control-protocol/channel-audit";
+export const AUDIT_PERMISSIONS = {
+    Administrator: 1n << 3n,
+    ManageGuild: 1n << 5n,
+    ViewChannel: 1n << 10n,
+    SendMessages: 1n << 11n,
+    ReadMessageHistory: 1n << 16n,
+    Connect: 1n << 20n,
+    Speak: 1n << 21n,
+    ManageRoles: 1n << 28n,
+    ManageChannels: 1n << 4n,
+    KickMembers: 1n << 1n,
+    BanMembers: 1n << 2n,
+    RequestToSpeak: 1n << 32n,
+    SendMessagesInThreads: 1n << 38n,
+};
+/** Discord's role union, everyone overwrite, then aggregate role deny/allow. */
+export function effectiveAuditPermissions(guildId, roles, selectedRoleIds, channel) {
+    if (channel.obfuscated)
+        return null;
+    const selected = new Set([guildId, ...selectedRoleIds]);
+    const roleMap = new Map(roles.map((role) => [role.id, role]));
+    let permissions = 0n;
+    for (const id of selected) {
+        const role = roleMap.get(id);
+        if (!role)
+            return null;
+        permissions |= role.permissions;
+    }
+    if (has(permissions, AUDIT_PERMISSIONS.Administrator))
+        return (1n << 64n) - 1n;
+    const everyone = channel.overwrites.find((overwrite) => overwrite.type === 0 && overwrite.id === guildId);
+    if (everyone)
+        permissions = (permissions & ~everyone.deny) | everyone.allow;
+    let allow = 0n, deny = 0n;
+    for (const overwrite of channel.overwrites) {
+        if (overwrite.type !== 0 ||
+            overwrite.id === guildId ||
+            !selected.has(overwrite.id))
+            continue;
+        allow |= overwrite.allow;
+        deny |= overwrite.deny;
+    }
+    return (permissions & ~deny) | allow;
+}
+function has(permissions, permission) {
+    return permissions !== null && (permissions & permission) === permission;
+}
+const channelTypes = new Map([
+    [0, "Text"],
+    [5, "Announcement"],
+    [15, "Forum"],
+    [16, "Media"],
+    [2, "Voice"],
+    [13, "Stage"],
+    [4, "Category"],
+    [10, "Announcement thread"],
+    [11, "Public thread"],
+    [12, "Private thread"],
+]);
+const activityTypes = new Set([0, 5, 15, 16, 2, 13]);
+/** Raw bit presence is insufficient: view/connect prerequisites gate actions. */
+export function auditActions(permissions, type) {
+    if (!activityTypes.has(type) ||
+        !has(permissions, AUDIT_PERMISSIONS.ViewChannel))
+        return [];
+    const actions = ["View"];
+    if ([0, 5].includes(type)) {
+        if (has(permissions, AUDIT_PERMISSIONS.ReadMessageHistory))
+            actions.push("Read existing panel");
+        if (has(permissions, AUDIT_PERMISSIONS.SendMessages))
+            actions.push("Post messages");
+    }
+    else if ([15, 16].includes(type)) {
+        if (has(permissions, AUDIT_PERMISSIONS.SendMessages))
+            actions.push("Create posts");
+        if (has(permissions, AUDIT_PERMISSIONS.SendMessagesInThreads))
+            actions.push("Reply in accessible threads");
+    }
+    else if (has(permissions, AUDIT_PERMISSIONS.Connect)) {
+        actions.push("Connect");
+        if (type === 2 && has(permissions, AUDIT_PERMISSIONS.Speak))
+            actions.push("Speak");
+        if (type === 13 && has(permissions, AUDIT_PERMISSIONS.RequestToSpeak))
+            actions.push("Request to speak");
+    }
+    return actions;
+}
+const panelUsable = (permissions, type) => [0, 5].includes(type) &&
+    has(permissions, AUDIT_PERMISSIONS.ViewChannel | AUDIT_PERMISSIONS.ReadMessageHistory);
+export function buildChannelAuditReport(snapshot, moduleId, assumptions, observedAt) {
+    const findings = [];
+    const channels = [];
+    const add = (finding) => findings.push(finding);
+    const roles = new Map(snapshot.roles.map((role) => [role.id, role]));
+    const requiredRoles = new Set([
+        ...assumptions.beforeRoleIds,
+        assumptions.afterRoleId,
+    ]);
+    for (const roleId of requiredRoles) {
+        if (!roles.has(roleId))
+            add(snapshot.rolesComplete
+                ? {
+                    code: "role_not_in_guild",
+                    category: "blocked",
+                    title: "Selected role is not in this server",
+                    detail: "The fresh server role list does not contain this role. Select a current role from this server.",
+                    roleId,
+                }
+                : {
+                    code: "role_unknown",
+                    category: "unknown",
+                    title: "Could not inspect a selected role",
+                    detail: "The current server role list could not be fetched. This is not evidence that the role was deleted.",
+                    roleId,
+                });
+    }
+    const afterRole = roles.get(assumptions.afterRoleId);
+    if (afterRole?.assignmentPolicyReason)
+        add({
+            code: "after_role_policy_blocked",
+            category: "blocked",
+            title: "Helyx's safety policy blocks the after-check role",
+            detail: afterRole.assignmentPolicyReason,
+            roleId: afterRole.id,
+        });
+    for (const roleId of assumptions.beforeRoleIds) {
+        const beforeRole = roles.get(roleId);
+        if (beforeRole?.assignmentPolicyReason)
+            add({
+                code: "before_role_removal_policy_risk",
+                category: "review",
+                title: "Safety policy may prevent removing a before-check role",
+                detail: `${beforeRole.assignmentPolicyReason} If the entry workflow removes this role, that removal is also blocked.`,
+                roleId,
+            });
+        if (beforeRole?.assignable === false)
+            add({
+                code: "before_role_removal_risk",
+                category: "review",
+                title: "Review removal of a selected before-check role",
+                detail: `${beforeRole.assignmentReason ?? "Helyx cannot currently manage this role."} If the entry workflow is configured to remove it, that transition may fail.`,
+                roleId,
+            });
+        else if (beforeRole?.assignable === null)
+            add({
+                code: "before_role_removal_unknown",
+                category: "unknown",
+                title: "Before-role removal capability is unknown",
+                detail: "Helyx's current role-management capability could not be established. No removal is attempted by this audit.",
+                roleId,
+            });
+    }
+    if (afterRole &&
+        (afterRole.assignable === false ||
+            afterRole.managed ||
+            afterRole.id === snapshot.guildId))
+        add({
+            code: "after_role_unassignable",
+            category: "blocked",
+            title: "Helyx cannot assign the after-check role",
+            detail: afterRole.assignmentReason ??
+                "The role is managed, everyone, above Helyx, or Helyx lacks Manage Roles. This audit changes none of them.",
+            roleId: afterRole.id,
+        });
+    else if (afterRole?.assignable === null)
+        add({
+            code: "after_role_unknown",
+            category: "unknown",
+            title: "Role assignment capability could not be checked",
+            detail: "Helyx's current member and role-management permissions are unavailable.",
+            roleId: afterRole.id,
+        });
+    const dangerous = Object.entries(AUDIT_PERMISSIONS).filter(([name]) => [
+        "Administrator",
+        "ManageGuild",
+        "ManageRoles",
+        "ManageChannels",
+        "KickMembers",
+        "BanMembers",
+    ].includes(name));
+    for (const roleId of new Set([snapshot.guildId, ...requiredRoles])) {
+        const role = roles.get(roleId);
+        const names = role
+            ? dangerous
+                .filter(([, bit]) => has(role.permissions, bit))
+                .map(([name]) => name)
+            : [];
+        if (names.length)
+            add({
+                code: "high_impact_role",
+                category: "review",
+                title: "Review elevated role permissions",
+                detail: `Role grants ${names.join(", ")}. These permissions can undermine a restricted entrance.`,
+                roleId,
+            });
+    }
+    const selectedIds = new Set([
+        assumptions.entryChannelId,
+        ...assumptions.allowedChannelIds,
+        ...(assumptions.reviewChannelId ? [assumptions.reviewChannelId] : []),
+    ]);
+    const ordered = [...snapshot.channels].sort((left, right) => Number(selectedIds.has(right.id)) - Number(selectedIds.has(left.id)) ||
+        left.id.localeCompare(right.id));
+    const inspected = ordered.slice(0, CHANNEL_AUDIT_LIMITS.channels);
+    let unknownChannels = 0, unsupportedChannels = 0, broadAccess = 0;
+    const rolePaths = assumptions.beforeRoleIds.map((roleId) => ({
+        roleId,
+        entranceUsable: null,
+        visibleChannels: 0,
+    }));
+    for (const channel of inspected) {
+        if (channel.obfuscated) {
+            unknownChannels += 1;
+            continue;
+        }
+        if (!activityTypes.has(channel.type)) {
+            unsupportedChannels += 1;
+            continue;
+        }
+        const before = effectiveAuditPermissions(snapshot.guildId, snapshot.roles, assumptions.beforeRoleIds, channel);
+        const everyone = effectiveAuditPermissions(snapshot.guildId, snapshot.roles, [], channel);
+        const after = effectiveAuditPermissions(snapshot.guildId, snapshot.roles, [assumptions.afterRoleId], channel);
+        const retained = effectiveAuditPermissions(snapshot.guildId, snapshot.roles, [...assumptions.beforeRoleIds, assumptions.afterRoleId], channel);
+        const row = {
+            id: channel.id,
+            name: channel.name.slice(0, 100),
+            type: channelTypes.get(channel.type) ?? "Unsupported",
+            beforeActions: auditActions(before, channel.type),
+            afterActions: auditActions(after, channel.type),
+            retainedActions: auditActions(retained, channel.type),
+            limitations: [],
+        };
+        if (before === null || after === null)
+            row.limitations.push("Selected role assumptions could not all be evaluated.");
+        if (channel.overwrites.some((overwrite) => overwrite.type === 1))
+            row.limitations.push("Member-specific overwrites can change an individual's access.");
+        if ([15, 16].includes(channel.type))
+            row.limitations.push("Thread membership, archive/lock and thread-specific state are not inspected.");
+        if (channels.length < CHANNEL_AUDIT_LIMITS.reportChannels)
+            channels.push(row);
+        for (const path of rolePaths) {
+            const permissions = effectiveAuditPermissions(snapshot.guildId, snapshot.roles, [path.roleId], channel);
+            if (has(permissions, AUDIT_PERMISSIONS.ViewChannel))
+                path.visibleChannels += 1;
+            if (channel.id === assumptions.entryChannelId)
+                path.entranceUsable =
+                    permissions === null ? null : panelUsable(permissions, channel.type);
+        }
+        if (channel.id === assumptions.entryChannelId) {
+            if (before === null || everyone === null)
+                add({
+                    code: "entrance_unknown",
+                    category: "unknown",
+                    title: "Could not evaluate the entrance",
+                    detail: "One or more required role assumptions are unavailable.",
+                    channelId: channel.id,
+                });
+            else if (!panelUsable(before, channel.type))
+                add({
+                    code: "entrance_unusable",
+                    category: "blocked",
+                    title: "Assumed entrants cannot reliably reach the panel",
+                    detail: "A supported text or announcement entrance needs View Channel and Read Message History. Send Messages is not required to press a panel button.",
+                    channelId: channel.id,
+                });
+            else if (assumptions.entrance === "public" &&
+                !panelUsable(everyone, channel.type))
+                add({
+                    code: "public_entrance_unusable",
+                    category: "blocked",
+                    title: "Everyone cannot use the intended public entrance",
+                    detail: "The public path needs View Channel and Read Message History without relying on selected extra roles.",
+                    channelId: channel.id,
+                });
+            else {
+                add({
+                    code: "entrance_working",
+                    category: "working",
+                    title: "Entrance is reachable under the selected assumptions",
+                    detail: "Role-only permissions allow reading the entrance. This does not prove a panel exists, is active or will accept a particular member.",
+                    channelId: channel.id,
+                });
+                if (assumptions.entrance === "restricted" &&
+                    has(everyone, AUDIT_PERMISSIONS.ViewChannel))
+                    add({
+                        code: "entrance_public",
+                        category: "review",
+                        title: "The restricted entrance is visible to everyone",
+                        detail: "Review whether the selected public/restricted intent matches your server design. No lockdown or permission change is applied.",
+                        channelId: channel.id,
+                    });
+            }
+            const publishing = AUDIT_PERMISSIONS.ViewChannel | AUDIT_PERMISSIONS.SendMessages;
+            if (channel.botPermissions === null)
+                add({
+                    code: "bot_publish_unknown",
+                    category: "unknown",
+                    title: "Helyx publishing access could not be checked",
+                    detail: "Current bot-specific permissions are unavailable.",
+                    channelId: channel.id,
+                });
+            else if (!has(channel.botPermissions, publishing))
+                add({
+                    code: "bot_cannot_publish",
+                    category: "blocked",
+                    title: "Helyx cannot publish an entrance panel here",
+                    detail: "Helyx needs View Channel and Send Messages in the selected entrance. Existing publication safeguards still apply.",
+                    channelId: channel.id,
+                });
+        }
+        else if (has(before, AUDIT_PERMISSIONS.ViewChannel) &&
+            !assumptions.allowedChannelIds.includes(channel.id))
+            broadAccess += 1;
+        if (channel.id === assumptions.reviewChannelId &&
+            has(before, AUDIT_PERMISSIONS.ViewChannel))
+            add({
+                code: "review_exposure",
+                category: "review",
+                title: "Assumed entrants can view the selected staff-review channel",
+                detail: "Review this explicitly selected staff-review destination separately from entrance visibility.",
+                channelId: channel.id,
+            });
+    }
+    for (const channelId of selectedIds) {
+        const invalid = snapshot.invalidSelectedChannels?.find((item) => item.id === channelId);
+        if (invalid) {
+            add({
+                code: "selected_channel_invalid",
+                category: "blocked",
+                title: "Selected channel is unavailable in this server",
+                detail: invalid.reason === "wrong_guild"
+                    ? "The fresh channel lookup identified a different server. Choose a channel from this server."
+                    : "Discord returned Unknown Channel for this selected ID. It may be deleted or invalid; this does not establish when or why it became unavailable.",
+                channelId,
+            });
+            continue;
+        }
+        const channel = inspected.find((item) => item.id === channelId);
+        if (!channel || channel.obfuscated)
+            add({
+                code: "selected_channel_unknown",
+                category: "unknown",
+                title: "A selected channel could not be inspected",
+                detail: "Discord may omit or obfuscate channels Helyx cannot view. Absence from this inspection is not proof of deletion or of entrant denial.",
+                channelId,
+            });
+        else if (!activityTypes.has(channel.type))
+            add({
+                code: "selected_channel_unsupported",
+                category: "unknown",
+                title: "Selected channel type is outside this audit",
+                detail: "Categories, individual threads and other unsupported types are not counted as a usable entrance or as a pass.",
+                channelId,
+            });
+    }
+    if (broadAccess)
+        add({
+            code: "wider_access",
+            category: "review",
+            title: "Review wider before-check access",
+            detail: `The combined before-role assumption can view ${broadAccess} inspected channels beyond the entrance and allowed exceptions. Wider access is advisory.`,
+        });
+    if (!assumptions.reviewChannelId)
+        add({
+            code: "review_context_unknown",
+            category: "unknown",
+            title: "Staff-review exposure has no selected context",
+            detail: "Select a staff-review channel or explicitly Load config to assess that destination. Hidden channels are not assumed to be staff-only.",
+        });
+    const limitations = [
+        "Role assumptions exclude member overwrites, screening, timeouts and actual member assignment; no member directory or messages are read.",
+        moduleId === "helyx.account-gate"
+            ? "Access Control grants the access role, then attempts removal of its configured temporary roles. Selected before roles are assumptions, and delivery can be partial."
+            : "Verification grants the verified role and removes its configured removal role when present. It does not assign the before roles, and other member roles can remain.",
+        "After-check view assumes selected before roles were removed; the retained view shows their combination with the after role. Actual transitions can differ or partially complete.",
+        "The retained view includes all selected before roles; it does not enumerate every partially retained role combination.",
+        ...snapshot.fetchLimitations,
+    ];
+    if (!snapshot.totalChannelsKnown)
+        limitations.push("Coverage is limited to Discord's bot-visible channel list and known inventory; other inaccessible channels may be omitted and their total is unknown.");
+    const channelsTruncated = snapshot.channels.length > inspected.length ||
+        inspected.filter((channel) => !channel.obfuscated && activityTypes.has(channel.type)).length > channels.length;
+    if (unknownChannels || unsupportedChannels || channelsTruncated)
+        add({
+            code: "coverage_incomplete",
+            category: "unknown",
+            title: "Some channel coverage is incomplete",
+            detail: `${unknownChannels} observed channels are unknown/obfuscated; ${unsupportedChannels} types are unsupported. ${channelsTruncated ? "Inspection or displayed channel rows were capped." : "Unsupported channels are not passed."}`,
+        });
+    // Keep failures and uncertainty before successful findings if the output cap is reached.
+    const priority = { blocked: 0, unknown: 1, review: 2, working: 3 };
+    findings.sort((left, right) => priority[left.category] - priority[right.category]);
+    return {
+        guildId: snapshot.guildId,
+        moduleId,
+        observedAt,
+        assumptions: structuredClone(assumptions),
+        simulation: false,
+        findings: findings.slice(0, CHANNEL_AUDIT_LIMITS.findings),
+        channels,
+        rolePaths,
+        coverage: {
+            fetchedChannels: snapshot.fetchedChannels,
+            totalChannelsKnown: snapshot.totalChannelsKnown,
+            inspectedChannels: inspected.length,
+            returnedChannels: channels.length,
+            unknownChannels,
+            unsupportedChannels,
+            channelsTruncated,
+            findingsTruncated: findings.length > CHANNEL_AUDIT_LIMITS.findings,
+            roleOnly: true,
+            limitations: limitations.slice(0, 12),
+        },
+    };
+}
+//# sourceMappingURL=channel-audit-permissions.js.map

package/dist/channel-audit-routes.d.ts

@@ -0,0 +1,4 @@
+import type { ChannelAuditControl } from "@helyx/sdk";
+import type { FastifyInstance } from "fastify";
+export declare function registerChannelAuditRoutes(server: FastifyInstance, control: ChannelAuditControl): void;
+//# sourceMappingURL=channel-audit-routes.d.ts.map