SHARDWIRE
Operations

Secret policy cookbook

Concrete scoped-secret patterns for dashboard, moderation, analytics, and voice workers sharing one bot bridge.

One bot bridge can serve multiple app processes with different secrets. The cookbook pattern is always the same:

  1. Each app gets a manifest (defineShardwireApp).
  2. Each secret entry uses allow derived from (or equal to) generateSecretScope(manifest).
  3. Each app uses strict startup and optionally expectedScope so deploy-time negotiation cannot drift.

Read Capabilities & scoped secrets for the rules: negotiation is the intersection of bot intents and each secret’s allow.

Topology (happy path)

Dashboard secret

  • Typical events: messageCreate, channelUpdate, guildUpdate (tune to your UI).
  • Typical actions: sendMessage, editMessage, fetchChannel, fetchGuild, createChannel, createThread, pinMessage, unpinMessage.
  • Risk: this secret is often the broadest. Prefer a dedicated dashboard app user story and keep expectedScope tight.

Moderation secret

  • Typical events: messageCreate, guildMemberUpdate, messageDelete.
  • Typical actions: deleteMessage, timeoutMember, removeMemberTimeout, banMember, kickMember, interaction replies if you handle reports in-app.
  • Recipe: Moderation worker.

Analytics secret

  • Typical events only: messageCreate, messageDelete, guildMemberAdd, guildMemberRemove, voiceStateUpdate (pick what you ingest).
  • Typical actions: usually none — keep allow.actions empty or omit actions from negotiation for that secret.
  • Recipe: Analytics listener.

Voice automation secret

  • Typical events: voiceStateUpdate.
  • Typical actions: moveMemberVoice, setMemberMute, setMemberDeaf, setMemberSuppressed.
  • Intents: include GuildVoiceStates on the bot bridge.

Rotation playbook

  1. Generate a new secret value and add it as an additional secrets[] entry (or replace the value during a maintenance window).
  2. Deploy app processes with the new value, verify ready and capabilities.
  3. Remove the old secret from the bot config once all clients moved.

Never widen allow “just in case” for a single consumer—add a new secret entry if a new app needs a different shape.

CI contract validation

Fail pull requests when a Shardwire app manifest, intents, subscriptions, or expectedScope drift from what production should negotiate.

Remote bridge (wss)

Run the app process off-host with wss://, TLS, secret rotation, logging boundaries, and realistic health expectations.

On this page

Topology (happy path)Dashboard secretModeration secretAnalytics secretVoice automation secretRotation playbookRelated