crewhaus 0.1.7 → 0.2.0

package/dist/channel-provision.d.ts

@@ -0,0 +1,360 @@
+import type { IrChannels, IrDiscordConfig, IrSecretRef, IrSlackConfig, IrTelegramConfig } from "@crewhaus/ir";
+/**
+ * Item 61 — `crewhaus channel provision|verify`: one-command channel app
+ * setup + scope doctor, factored out of the entry file `index.ts` (which
+ * runs a top-level argv switch and so cannot be imported by a test without
+ * executing the CLI). Side-effect-free on import and directly unit-testable,
+ * mirroring `audit-verify.ts` / `security-digest.ts` / `scope-audit-drift.ts`.
+ *
+ * The problem this closes: channel-bot harnesses assume platform-side
+ * configuration the user had to hand-build — a Slack app with the right
+ * scopes/event subscriptions, a Telegram webhook registered with the secret
+ * the adapter verifies (`channel-adapter-telegram` documents the
+ * `setWebhook(secret_token=...)` expectation but nothing performed it), a
+ * Discord application pointed at the daemon's interactions endpoint.
+ *
+ * Everything here is DERIVED from the adapters + the compiled daemon, not
+ * guessed (per-platform derivations are documented on the builders below).
+ * The one shared fact: the generated gateway routes webhooks by path —
+ * `/^\/([^/]+)\/events$/` in target-channel-bot's `renderGateway` — so the
+ * platform-side URL is always `<base-url>/<adapterId>/events`.
+ *
+ * Design decisions:
+ *   - Slack is EMIT-AND-INSTRUCT only (no `--apply`). Slack's manifest API
+ *     (`apps.manifest.create`) authenticates with an app *configuration*
+ *     token; the adapter/spec carry only the bot token (`xoxb`, Bearer for
+ *     chat.postMessage/reactions.add), the signing secret (HMAC verify), and
+ *     the reserved Socket-Mode `appToken` (`xapp`) — none of which can call
+ *     the manifest API, and inventing a new env var for a token family the
+ *     runtime never uses was ruled out.
+ *   - Discord's adapter is interactions-endpoint-based (Ed25519-verified
+ *     webhooks; types 1/2/3/5), NOT gateway-websocket-based — so provision
+ *     PATCHes `applications/@me` `interactions_endpoint_url` and prints the
+ *     invite URL with permission bits derived from the adapter's REST usage.
+ *     Application *commands* are not registered: the spec declares no
+ *     command list and the adapter accepts ANY command name (it renders
+ *     `/<name> <options>` into the agent turn), so command names cannot be
+ *     derived without guesswork — provision prints the registration
+ *     instruction instead.
+ *   - All network calls go through an injectable `fetchImpl` so tests are
+ *     credential-free, and every network-performing path has a dry-run
+ *     counterpart (`display` plans / `describeVerifyProbes`) that renders
+ *     env refs as `$NAME` and literals as `[redacted]` — never the value.
+ */
+/** Platforms `channel provision|verify` supports. whatsapp (Meta app config
+ *  lives in the Meta developer console) and imessage (host-local chat.db —
+ *  there is no platform side to provision) are out of item-61 scope; when a
+ *  spec configures them the CLI prints a note instead of failing. */
+export declare const CHANNEL_PLATFORMS: readonly ["slack", "telegram", "discord"];
+export type ChannelPlatform = (typeof CHANNEL_PLATFORMS)[number];
+export type FetchLike = typeof fetch;
+/** Placeholder for an inline-literal secret in printable output — mirrors
+ *  `packages/ir/src/redact.ts`'s `REDACTED_VALUE` convention. */
+export declare const REDACTED_LITERAL = "[redacted]";
+/** Thrown on a malformed/unconfigured `--platform` value. The CLI entry file
+ *  catches it and routes the message through `die()`. */
+export declare class InvalidPlatformFlagError extends Error {
+    readonly name = "InvalidPlatformFlagError";
+}
+/** Thrown when a secret env-ref (`$VAR_NAME` in the spec) is unset at the
+ *  moment a REAL platform call needs its value. Dry-run paths never throw
+ *  this — they print the `$VAR_NAME` placeholder instead. */
+export declare class ChannelEnvRefError extends Error {
+    readonly label: string;
+    readonly envName: string;
+    readonly name = "ChannelEnvRefError";
+    constructor(label: string, envName: string);
+}
+/** Thrown on a failed platform API call (non-2xx or a logical `ok: false`).
+ *  Messages are built from REDACTED endpoints — never the token-bearing URL. */
+export declare class ChannelApiError extends Error {
+    readonly name = "ChannelApiError";
+}
+/** Thrown on a malformed `--base-url`. */
+export declare class InvalidBaseUrlError extends Error {
+    readonly name = "InvalidBaseUrlError";
+    constructor(value: string, detail: string);
+}
+/**
+ * Resolve the `--platform` flag against the spec's configured channels.
+ * `all` (or an absent flag) selects every configured platform this command
+ * supports; an explicit platform must actually be configured in the spec —
+ * provisioning a channel the daemon will never serve is a footgun, not a
+ * convenience. `unsupported` lists configured channels outside item-61
+ * scope (whatsapp/imessage) so the CLI can print a note.
+ */
+export declare function resolvePlatformsFlag(flagValue: string | undefined, channels: IrChannels): {
+    readonly platforms: ReadonlyArray<ChannelPlatform>;
+    readonly unsupported: ReadonlyArray<string>;
+};
+/** Resolve a lowered secret ref to its value. Env-refs read `env`; an unset
+ *  (or empty) env var throws {@link ChannelEnvRefError} — matching the
+ *  compiled daemon's own startup check, which exits non-zero on the same
+ *  condition rather than serving webhooks with an empty secret. */
+export declare function resolveSecretRef(label: string, ref: IrSecretRef, env: NodeJS.ProcessEnv): string;
+/** Printable form of a secret ref: `$NAME` for env-refs (the indirection is
+ *  not a secret), {@link REDACTED_LITERAL} for inline literals. */
+export declare function describeSecretRef(ref: IrSecretRef): string;
+/** The daemon route the platform must deliver webhooks to. Single source:
+ *  target-channel-bot's gateway matches `/^\/([^/]+)\/events$/` and looks the
+ *  captured segment up in its adapter map keyed by adapter id. */
+export declare function channelEventsPath(platform: ChannelPlatform): string;
+/**
+ * Join `--base-url` with a daemon route. Validates the base URL parses and
+ * is http(s); trailing slashes are normalized so `https://x/` and `https://x`
+ * produce the same webhook URL. (Slack, Telegram, and Discord all require a
+ * publicly reachable https URL in production — http is tolerated here for
+ * local tunnels/tests; the platform rejects it server-side if unsupported.)
+ */
+export declare function joinBaseUrl(baseUrl: string, path: string): string;
+/** A missing env-ref surfaced by a provision plan builder: which spec field,
+ *  which env var. The CLI dies listing these before a live (non-dry-run) call. */
+export type MissingEnvRef = {
+    readonly label: string;
+    readonly envName: string;
+};
+/**
+ * The secret fields a platform's daemon REQUIRES at boot, per
+ * target-channel-bot's `requiredEnvNames`: slack botToken + signingSecret
+ * (appToken is reserved for a future Socket-Mode path — parsed but unused,
+ * so not required), telegram botToken + secretToken, discord applicationId +
+ * botToken + publicKeyHex. Shared by the doctor channel check and `verify`.
+ */
+export declare function platformSecretRefs(platform: ChannelPlatform, channels: IrChannels): ReadonlyArray<{
+    readonly label: string;
+    readonly ref: IrSecretRef;
+}>;
+export declare const SLACK_MANIFEST_FILENAME = "slack-app-manifest.yaml";
+export type SlackScope = {
+    readonly scope: string;
+    readonly reason: string;
+};
+/**
+ * Bot scopes derived from `@crewhaus/channel-adapter-slack`'s ACTUAL API
+ * usage and parsed event types — not from a generic bot template:
+ *   - `sendReply` POSTs `chat.postMessage`            → chat:write
+ *   - `react` POSTs `reactions.add` (the generated session-router always
+ *     attempts 👀/✅/⚠️ status acks)                    → reactions:write
+ *   - `parseInbound` handles `app_mention`            → app_mentions:read
+ *   - `parseInbound` handles `message` in any
+ *     conversation type, so each `message.*` event
+ *     subscription needs its history scope            → channels/groups/im/mpim:history
+ *   - `parseInbound` normalises `reaction_added` into 👍/👎 `user_feedback`
+ *     (the v0.1.8 ratings feature), but the generated gateway only
+ *     dispatches it when the spec sets `feedback.channelReactions` — so
+ *     reactions:read is requested exactly then         → reactions:read
+ */
+export declare function deriveSlackScopes(opts: {
+    readonly channelReactions: boolean;
+}): ReadonlyArray<SlackScope>;
+/** Event subscriptions matching {@link deriveSlackScopes} — the event types
+ *  the adapter's `parseInbound` consumes (everything else parses to skip). */
+export declare function deriveSlackBotEvents(opts: {
+    readonly channelReactions: boolean;
+}): ReadonlyArray<string>;
+/** A Slack app manifest (api.slack.com/reference/manifests), restricted to
+ *  the sections the channel daemon needs. */
+export type SlackAppManifest = {
+    readonly display_information: {
+        readonly name: string;
+        readonly description: string;
+    };
+    readonly features: {
+        readonly bot_user: {
+            readonly display_name: string;
+            readonly always_online: boolean;
+        };
+    };
+    readonly oauth_config: {
+        readonly scopes: {
+            readonly bot: ReadonlyArray<string>;
+        };
+    };
+    readonly settings: {
+        readonly event_subscriptions: {
+            readonly request_url: string;
+            readonly bot_events: ReadonlyArray<string>;
+        };
+        readonly org_deploy_enabled: boolean;
+        readonly socket_mode_enabled: boolean;
+        readonly token_rotation_enabled: boolean;
+    };
+};
+/**
+ * Build the complete Slack app manifest for a channel spec. The request URL
+ * is the compiled daemon's slack route under `--base-url`; `socket_mode` is
+ * off because the daemon is a webhook server (the spec's `appToken` is
+ * documented as reserved for a future Socket-Mode path).
+ */
+export declare function buildSlackManifest(spec: {
+    readonly name: string;
+    readonly channelReactions: boolean;
+}, baseUrl: string): SlackAppManifest;
+export declare function renderSlackManifestYaml(manifest: SlackAppManifest): string;
+/** Post-manifest instructions. Slack app creation from a manifest is a
+ *  console flow (no `--apply` — see the module header for why), so the CLI
+ *  prints exactly what to do with the file it just wrote. */
+export declare function slackNextSteps(cfg: IrSlackConfig, manifestRef: string): ReadonlyArray<string>;
+/** Update kinds the adapter's `parseInbound` actually consumes — its three
+ *  populated slots are `message`, `edited_message`, and `callback_query`;
+ *  everything else returns skip, so the webhook shouldn't receive it. */
+export declare const TELEGRAM_ALLOWED_UPDATES: readonly ["message", "edited_message", "callback_query"];
+export type TelegramSetWebhookPayload = {
+    readonly url: string;
+    readonly secret_token: string;
+    readonly allowed_updates: ReadonlyArray<string>;
+};
+export type TelegramProvision = {
+    /** Printable call — token/secret rendered as `$NAME` / `[redacted]`. */
+    readonly display: {
+        readonly endpoint: string;
+        readonly payload: TelegramSetWebhookPayload;
+    };
+    /** The real call. Absent when an env-ref is unset (see `missingEnv`). */
+    readonly request?: {
+        readonly endpoint: string;
+        readonly payload: TelegramSetWebhookPayload;
+    };
+    readonly missingEnv: ReadonlyArray<MissingEnvRef>;
+};
+/**
+ * Build the `setWebhook` call: url = the daemon's `/telegram/events` route
+ * under `--base-url`, secret_token = the spec's `secretToken` — the SAME
+ * value the adapter compares (timing-safely) against the
+ * `X-Telegram-Bot-Api-Secret-Token` header on every inbound POST —
+ * allowed_updates = the adapter's three consumed update kinds. The api base
+ * honours `TELEGRAM_API_BASE_URL` exactly like the adapter does.
+ */
+export declare function buildTelegramProvision(cfg: IrTelegramConfig, baseUrl: string, env: NodeJS.ProcessEnv): TelegramProvision;
+/** Perform the setWebhook POST. Errors carry the REDACTED endpoint (the real
+ *  one embeds the bot token in its path). Returns Telegram's description. */
+export declare function performTelegramSetWebhook(provision: TelegramProvision, fetchImpl?: FetchLike): Promise<string>;
+/**
+ * Invite-URL permission bits derived from the adapter's REST usage — the
+ * adapter never opens a gateway websocket, so no presence/guild intents:
+ *   - `sendReply` POSTs `channels/<id>/messages`  → View Channel + Send Messages
+ *   - threads are first-class (`threadTs` from `channel.parent_id`), and the
+ *     same POST into a thread channel                → Send Messages in Threads
+ *   - `setTyping` POSTs `channels/<id>/typing`      → covered by Send Messages
+ */
+export declare const DISCORD_PERMISSIONS: readonly [{
+    readonly name: "View Channel";
+    readonly bit: 1024;
+}, {
+    readonly name: "Send Messages";
+    readonly bit: 2048;
+}, {
+    readonly name: "Send Messages in Threads";
+    readonly bit: 274877906944;
+}];
+export declare const DISCORD_PERMISSION_BITS: number;
+export type DiscordProvision = {
+    /** Printable call — token rendered as `Bot $NAME` / `Bot [redacted]`. */
+    readonly display: {
+        readonly method: "PATCH";
+        readonly endpoint: string;
+        readonly payload: {
+            readonly interactions_endpoint_url: string;
+        };
+        readonly authorization: string;
+        readonly inviteUrl: string;
+    };
+    /** The real call. Absent when an env-ref is unset (see `missingEnv`). */
+    readonly request?: {
+        readonly endpoint: string;
+        readonly payload: {
+            readonly interactions_endpoint_url: string;
+        };
+        readonly authorization: string;
+    };
+    /** Invite URL with the RESOLVED application id (needs no secret — the id
+     *  is public); absent when the id's env-ref is unset. */
+    readonly inviteUrl?: string;
+    readonly missingEnv: ReadonlyArray<MissingEnvRef>;
+};
+/**
+ * Build the interactions-endpoint registration: PATCH `applications/@me`
+ * (Bot-token auth — the same token the adapter uses for its REST sends)
+ * setting `interactions_endpoint_url` to the daemon's `/discord/events`
+ * route. Discord VALIDATES the URL during the PATCH (it sends a PING plus a
+ * bad-signature probe), so the daemon must be live at `--base-url` first.
+ */
+export declare function buildDiscordProvision(cfg: IrDiscordConfig, baseUrl: string, env: NodeJS.ProcessEnv): DiscordProvision;
+export type DiscordProvisionResult = {
+    /** `interactions_endpoint_url` found on the application BEFORE the PATCH
+     *  (undefined when none was set). */
+    readonly previousEndpoint?: string;
+    /** True when a different pre-existing endpoint was overwritten (--force). */
+    readonly replacedPrevious: boolean;
+};
+/**
+ * Perform the registration, read-before-write (adversarial-review F5): GET
+ * `applications/@me` first, and if an `interactions_endpoint_url` is already
+ * set to something OTHER than the daemon route, refuse to overwrite it
+ * unless `force` is set — silently clobbering it would detach whatever
+ * service the application currently points at (the same stance as `state
+ * restore`, which refuses to overwrite without --force). A 4xx on the PATCH
+ * usually means Discord's live endpoint validation failed — surfaced with
+ * that hint.
+ */
+export declare function performDiscordProvision(provision: DiscordProvision, fetchImpl?: FetchLike, opts?: {
+    readonly force?: boolean;
+}): Promise<DiscordProvisionResult>;
+/** Post-registration instructions: the invite URL plus the command-
+ *  registration note (see the module header for why commands aren't
+ *  auto-registered: the spec declares none and the adapter accepts any). */
+export declare function discordNextSteps(inviteUrl: string): ReadonlyArray<string>;
+/** Shape shared with `index.ts`'s DoctorCheck and audit-verify's
+ *  AuditIntegrityCheck (label/pass/warn/reason). */
+export type ChannelCheck = {
+    readonly label: string;
+    readonly pass: boolean;
+    /** warn+pass renders as "~" — informational, never fails verify. */
+    readonly warn?: boolean;
+    readonly reason?: string;
+};
+export type ChannelVerifyOptions = {
+    readonly env: NodeJS.ProcessEnv;
+    readonly fetchImpl?: FetchLike;
+    /** When set, webhook/endpoint URLs are asserted against the daemon route
+     *  under this origin; when absent those checks degrade to informational. */
+    readonly baseUrl?: string;
+};
+/**
+ * Slack probes: `auth.test` with the bot token (identity + reachability),
+ * then the token's GRANTED scopes — Slack returns them on every Web API
+ * response in the `x-oauth-scopes` header — diffed against the needed set
+ * from {@link deriveSlackScopes}. The signing secret is only checked for
+ * presence: Slack never exposes it back over the API.
+ */
+export declare function verifySlackChannel(cfg: IrSlackConfig, spec: {
+    readonly channelReactions: boolean;
+}, opts: ChannelVerifyOptions): Promise<ChannelCheck[]>;
+/**
+ * Telegram probes: `getWebhookInfo`, compared against the daemon route.
+ * Telegram never returns the configured secret_token (write-only by design),
+ * so the secret is checked for presence on the daemon side — the adapter
+ * rejects every inbound POST if the two ever diverge, which surfaces as
+ * pending updates + a 401 last_error here.
+ */
+export declare function verifyTelegramChannel(cfg: IrTelegramConfig, opts: ChannelVerifyOptions): Promise<ChannelCheck[]>;
+/**
+ * Discord probes: `GET applications/@me` with the bot token, asserting the
+ * three facts the adapter depends on — the token belongs to the declared
+ * `applicationId`, the application's `verify_key` equals the spec's
+ * `publicKeyHex` (a mismatch means every inbound webhook fails Ed25519
+ * verification with a 401), and `interactions_endpoint_url` points at the
+ * daemon's `/discord/events` route.
+ */
+export declare function verifyDiscordChannel(cfg: IrDiscordConfig, opts: ChannelVerifyOptions): Promise<ChannelCheck[]>;
+/** Redacted one-liners describing what `verify` would call — the dry-run
+ *  counterpart for the probes (network never happens under --dry-run). */
+export declare function describeVerifyProbes(platform: ChannelPlatform, channels: IrChannels, env: NodeJS.ProcessEnv): ReadonlyArray<string>;
+export type ChannelVerifySummary = {
+    readonly lines: ReadonlyArray<string>;
+    readonly exitCode: 0 | 1;
+};
+/** Render checks as the doctor's ✓/~/✗ lines + the exit code — non-zero on
+ *  any hard failure (missing scopes, mismatched webhook, bad credentials);
+ *  warns are informational. Mirrors audit-verify's `summarizeVerifyResult`. */
+export declare function summarizeChannelChecks(checks: ReadonlyArray<ChannelCheck>): ChannelVerifySummary;