feat(discord): hosted OAuth relay for secure credential management (#76)

* chore: update workflow and Discord RPC migration integration

* fix(ci): stop pushing version bumps from protected branch workflows

* feat(discord): add hosted OAuth relay for secure credential management

- Add Cloudflare Worker relay scaffold (discord-relay/) with endpoints:
  POST /oauth/discord/exchange, /access, /revoke; GET /health
- Add relay-aware token exchange/refresh in discord-rpc.cjs with
  backward-compatible direct Discord fallback when no relay URL set
- Add relayUrl, relayApiKey, relaySessionId to plugin settings/auth flow;
  client secret and refresh token cleared from local settings in hosted mode
- Add Relay URL and Relay API Key fields to inspector UI; client secret
  relabeled as legacy fallback
- Document hosted relay quickstart in README and installation guide
- 115/115 unit tests pass; test:local crash is pre-existing (hardware absent)

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Author: tech-stack-studios

README.md

@@ -225,9 +225,26 @@ The Scene, Scene Collection, Source, Input, and Transition pickers in the Proper
 
 1. Install the plugin (see [Installing a plugin](#installing-a-plugin) above)
 2. Open Discord desktop app
-3. In the button's Property Inspector, enter Discord application `client_id` and `client_secret`
-4. Click **Authorize** and approve the Discord prompt
-5. For voice/text channel actions, pick a guild and channel from the inspector dropdowns
+3. In the button's Property Inspector, enter Discord application `client_id`
+4. Configure `relay_url` (recommended) so your `client_secret` and refresh token stay server-side
+5. Click **Authorize** and approve the Discord prompt
+6. For voice/text channel actions, pick a guild and channel from the inspector dropdowns
+
+Hosted relay quick start (free, Cloudflare Workers):
+
+```bash
+# from repo root
+cd discord-relay
+wrangler login
+wrangler kv namespace create DISCORD_SESSIONS
+wrangler kv namespace create DISCORD_SESSIONS --preview
+# paste generated KV IDs into discord-relay/wrangler.toml
+wrangler secret put DISCORD_CLIENT_SECRET
+wrangler secret put RELAY_API_KEY
+wrangler deploy
+```
+
+Then paste the deployed Worker URL into the `Relay URL` field in the Discord inspector. If you set `RELAY_API_KEY`, also paste it into `Relay API Key`.
 
 ---
 

discord-plugin/com.discord.streamdeck.sdPlugin/bin/discord-rpc.cjs

@@ -13,6 +13,45 @@ const OPCODE_PING = 3
 const OPCODE_PONG = 4
 
 const REQUEST_TIMEOUT_MS = 12_000
+const RELAY_TIMEOUT_MS = 12_000
+
+async function postJson(url, payload, headers = {}) {
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), RELAY_TIMEOUT_MS)
+
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...headers },
+      body: JSON.stringify(payload || {}),
+      signal: controller.signal,
+    })
+
+    let data = null
+    try { data = await res.json() } catch {}
+
+    if (!res.ok) {
+      const reason = data?.error || data?.message || `HTTP ${res.status}`
+      throw new Error(reason)
+    }
+
+    return data || {}
+  } catch (err) {
+    if (err?.name === 'AbortError') throw new Error('Relay request timed out')
+    throw err
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+function normalizeRelayUrl(relayUrl) {
+  const base = String(relayUrl || '').trim().replace(/\/+$/, '')
+  if (!base) return ''
+  if (!/^https?:\/\//i.test(base)) {
+    throw new Error('Relay URL must start with http:// or https://')
+  }
+  return base
+}
 
 function makeNonce() {
   return crypto.randomBytes(8).toString('hex')
@@ -314,7 +353,31 @@ class DiscordRpcClient {
   }
 }
 
-async function exchangeAuthCode({ clientId, clientSecret, code }) {
+async function exchangeAuthCode({ clientId, clientSecret, code, relayUrl, relayApiKey, relaySessionId }) {
+  const relayBaseUrl = normalizeRelayUrl(relayUrl)
+  const relayKey = String(relayApiKey || '').trim()
+  const relaySession = String(relaySessionId || '').trim()
+
+  if (relayBaseUrl) {
+    if (!clientId) throw new Error('Missing client ID for relay exchange')
+    if (!code) throw new Error('Missing authorization code from Discord')
+
+    const relayPayload = await postJson(
+      `${relayBaseUrl}/oauth/discord/exchange`,
+      { clientId, code, sessionId: relaySession || null },
+      relayKey ? { 'x-relay-key': relayKey } : {}
+    )
+
+    return {
+      accessToken: relayPayload.accessToken || '',
+      refreshToken: relayPayload.refreshToken || null,
+      sessionId: relayPayload.sessionId || relaySession || null,
+      expiresAt: Number(relayPayload.expiresAt || 0),
+      scope: relayPayload.scope || null,
+      tokenType: relayPayload.tokenType || null,
+    }
+  }
+
   if (!clientId) throw new Error('Missing client ID for token exchange')
   if (!clientSecret) throw new Error('Missing client secret for token exchange')
   if (!code) throw new Error('Missing authorization code from Discord')
@@ -349,7 +412,31 @@ async function exchangeAuthCode({ clientId, clientSecret, code }) {
   }
 }
 
-async function refreshAccessToken({ clientId, clientSecret, refreshToken }) {
+async function refreshAccessToken({ clientId, clientSecret, refreshToken, relayUrl, relayApiKey, relaySessionId }) {
+  const relayBaseUrl = normalizeRelayUrl(relayUrl)
+  const relayKey = String(relayApiKey || '').trim()
+  const relaySession = String(relaySessionId || '').trim()
+
+  if (relayBaseUrl) {
+    if (!clientId) throw new Error('Missing client ID for relay refresh')
+    if (!relaySession && !refreshToken) throw new Error('Missing relay session or refresh token')
+
+    const relayPayload = await postJson(
+      `${relayBaseUrl}/oauth/discord/access`,
+      { clientId, sessionId: relaySession || null, refreshToken: refreshToken || null },
+      relayKey ? { 'x-relay-key': relayKey } : {}
+    )
+
+    return {
+      accessToken: relayPayload.accessToken || '',
+      refreshToken: relayPayload.refreshToken || refreshToken || null,
+      sessionId: relayPayload.sessionId || relaySession || null,
+      expiresAt: Number(relayPayload.expiresAt || 0),
+      scope: relayPayload.scope || null,
+      tokenType: relayPayload.tokenType || null,
+    }
+  }
+
   if (!clientId) throw new Error('Missing client ID for refresh')
   if (!clientSecret) throw new Error('Missing client secret for refresh')
   if (!refreshToken) throw new Error('Missing refresh token')

discord-plugin/com.discord.streamdeck.sdPlugin/bin/plugin.cjs

@@ -31,6 +31,9 @@ function sanitizeSettings(settings = {}) {
   return {
     clientId: String(settings.clientId || '').trim(),
     clientSecret: String(settings.clientSecret || '').trim(),
+    relayUrl: String(settings.relayUrl || '').trim(),
+    relayApiKey: String(settings.relayApiKey || '').trim(),
+    relaySessionId: String(settings.relaySessionId || '').trim(),
     accessToken: String(settings.accessToken || '').trim(),
     refreshToken: String(settings.refreshToken || '').trim(),
     expiresAt: Number(settings.expiresAt || 0),
@@ -60,6 +63,33 @@ async function ensureAuthenticated(actionUUID, settings) {
       clientId: s.clientId,
       clientSecret: s.clientSecret,
       refreshToken: s.refreshToken,
+      relayUrl: s.relayUrl,
+      relayApiKey: s.relayApiKey,
+      relaySessionId: s.relaySessionId,
+    })
+
+    await rpc.authenticate(refreshed.accessToken)
+
+    const patch = {
+      accessToken: refreshed.accessToken,
+      expiresAt: refreshed.expiresAt,
+      scope: refreshed.scope,
+      tokenType: refreshed.tokenType,
+    }
+    if (refreshed.refreshToken) patch.refreshToken = refreshed.refreshToken
+    if (refreshed.sessionId) patch.relaySessionId = refreshed.sessionId
+    if (s.relayUrl) { patch.clientSecret = ''; patch.refreshToken = '' }
+
+    sendToInspector(actionUUID, { type: 'patchSettings', patch })
+    return { ...s, ...refreshed }
+  }
+
+  if (s.relayUrl && s.relaySessionId) {
+    const refreshed = await refreshAccessToken({
+      clientId: s.clientId,
+      relayUrl: s.relayUrl,
+      relayApiKey: s.relayApiKey,
+      relaySessionId: s.relaySessionId,
     })
 
     await rpc.authenticate(refreshed.accessToken)
@@ -68,10 +98,12 @@ async function ensureAuthenticated(actionUUID, settings) {
       type: 'patchSettings',
       patch: {
         accessToken: refreshed.accessToken,
-        refreshToken: refreshed.refreshToken,
         expiresAt: refreshed.expiresAt,
         scope: refreshed.scope,
         tokenType: refreshed.tokenType,
+        relaySessionId: refreshed.sessionId || s.relaySessionId,
+        clientSecret: '',
+        refreshToken: '',
       },
     })
 
@@ -222,19 +254,23 @@ async function handleInspectorMessage(actionUUID, payload) {
         clientId: s.clientId,
         clientSecret: s.clientSecret,
         code: auth.code,
+        relayUrl: s.relayUrl,
+        relayApiKey: s.relayApiKey,
+        relaySessionId: s.relaySessionId,
       })
       await rpc.authenticate(token.accessToken)
 
-      sendToInspector(actionUUID, {
-        type: 'patchSettings',
-        patch: {
-          accessToken: token.accessToken,
-          refreshToken: token.refreshToken,
-          expiresAt: token.expiresAt,
-          scope: token.scope,
-          tokenType: token.tokenType,
-        },
-      })
+      const patch = {
+        accessToken: token.accessToken,
+        expiresAt: token.expiresAt,
+        scope: token.scope,
+        tokenType: token.tokenType,
+      }
+      if (token.refreshToken) patch.refreshToken = token.refreshToken
+      if (token.sessionId) patch.relaySessionId = token.sessionId
+      if (s.relayUrl) { patch.clientSecret = ''; patch.refreshToken = '' }
+
+      sendToInspector(actionUUID, { type: 'patchSettings', patch })
 
       sendToInspector(actionUUID, {
         type: 'status',

discord-plugin/com.discord.streamdeck.sdPlugin/ui/inspector.html

@@ -140,8 +140,14 @@ <h3>Discord RPC Auth</h3>
     <label for="clientId">Client ID</label>
     <input type="text" id="clientId" placeholder="Discord application client ID" autocomplete="off" />
 
-    <label for="clientSecret">Client Secret</label>
-    <input type="password" id="clientSecret" placeholder="Discord application client secret" autocomplete="off" />
+    <label for="relayUrl">Relay URL (recommended)</label>
+    <input type="text" id="relayUrl" placeholder="https://your-relay.workers.dev" autocomplete="off" />
+
+    <label for="relayApiKey">Relay API Key (optional)</label>
+    <input type="password" id="relayApiKey" placeholder="x-relay-key if enabled on your relay" autocomplete="off" />
+
+    <label for="clientSecret">Client Secret (legacy fallback)</label>
+    <input type="password" id="clientSecret" placeholder="Only needed when no relay URL is configured" autocomplete="off" />
 
     <label for="scopes">Scopes</label>
     <input type="text" id="scopes" value="rpc identify" autocomplete="off" />
@@ -153,7 +159,7 @@ <h3>Discord RPC Auth</h3>
     </div>
 
     <div class="hint">
-      Authorize opens Discord's permission prompt. This action stores tokens in your local profile so the plugin can call RPC commands.
+      Authorize opens Discord's permission prompt. With a relay URL configured, your Discord client secret and refresh token stay on the relay and are not persisted locally.
     </div>
 
     <div class="status" id="status"></div>
@@ -219,6 +225,8 @@ <h3>Channel Selection</h3>
       instruction: document.getElementById('instruction'),
       status: document.getElementById('status'),
       clientId: document.getElementById('clientId'),
+      relayUrl: document.getElementById('relayUrl'),
+      relayApiKey: document.getElementById('relayApiKey'),
       clientSecret: document.getElementById('clientSecret'),
       scopes: document.getElementById('scopes'),
       saveBtn: document.getElementById('saveBtn'),
@@ -261,6 +269,8 @@ <h3>Channel Selection</h3>
 
     function syncFormFromSettings() {
       el.clientId.value = settings.clientId || ''
+      el.relayUrl.value = settings.relayUrl || ''
+      el.relayApiKey.value = settings.relayApiKey || ''
       el.clientSecret.value = settings.clientSecret || ''
       el.scopes.value = settings.scopes || 'rpc identify'
     }
@@ -332,28 +342,37 @@ <h3>Channel Selection</h3>
     }
 
     el.saveBtn.addEventListener('click', () => {
+      const relayUrl = el.relayUrl.value.trim()
       persist({
         clientId: el.clientId.value.trim(),
-        clientSecret: el.clientSecret.value.trim(),
+        relayUrl,
+        relayApiKey: el.relayApiKey.value.trim(),
+        clientSecret: relayUrl ? '' : el.clientSecret.value.trim(),
         scopes: el.scopes.value.trim() || 'rpc identify',
       })
       setStatus('Saved settings', 'success')
     })
 
     el.authorizeBtn.addEventListener('click', () => {
+      const relayUrl = el.relayUrl.value.trim()
       persist({
         clientId: el.clientId.value.trim(),
-        clientSecret: el.clientSecret.value.trim(),
+        relayUrl,
+        relayApiKey: el.relayApiKey.value.trim(),
+        clientSecret: relayUrl ? '' : el.clientSecret.value.trim(),
         scopes: el.scopes.value.trim() || 'rpc identify',
       })
       setStatus('Authorizing via Discord...', null)
       sendPlugin('rpc-authorize')
     })
 
     el.refreshBtn.addEventListener('click', () => {
+      const relayUrl = el.relayUrl.value.trim()
       persist({
         clientId: el.clientId.value.trim(),
-        clientSecret: el.clientSecret.value.trim(),
+        relayUrl,
+        relayApiKey: el.relayApiKey.value.trim(),
+        clientSecret: relayUrl ? '' : el.clientSecret.value.trim(),
         scopes: el.scopes.value.trim() || 'rpc identify',
       })
       setStatus('Refreshing Discord data...', null)

discord-relay/README.md

@@ -0,0 +1,46 @@
+# Discord OAuth Relay (Cloudflare Worker)
+
+This worker keeps the Discord client secret and refresh tokens on the server side.
+The Stream Deck Discord plugin calls this relay for OAuth token exchange and refresh.
+
+## Endpoints
+
+- `GET /health`
+- `POST /oauth/discord/exchange`
+- `POST /oauth/discord/access`
+- `POST /oauth/discord/revoke`
+
+## Required bindings and secrets
+
+1. Cloudflare KV namespace bound as `DISCORD_SESSIONS`
+1. Secret: `DISCORD_CLIENT_SECRET`
+1. Optional secret: `RELAY_API_KEY`
+
+## Local dev
+
+1. Install Wrangler
+   - `npm i -g wrangler`
+1. Authenticate
+   - `wrangler login`
+1. Create KV
+   - `wrangler kv namespace create DISCORD_SESSIONS`
+   - `wrangler kv namespace create DISCORD_SESSIONS --preview`
+1. Put generated IDs into `wrangler.toml`
+1. Set secrets
+   - `wrangler secret put DISCORD_CLIENT_SECRET`
+   - `wrangler secret put RELAY_API_KEY`
+1. Start worker
+   - `wrangler dev`
+
+## Deploy
+
+1. `wrangler deploy`
+1. Copy deployed worker URL
+1. Put relay URL into the Discord action inspector
+1. Put `RELAY_API_KEY` into the plugin setting if you enabled it
+
+## Security notes
+
+- In hosted mode, the plugin should not store `clientSecret` or `refreshToken`.
+- The relay stores refresh tokens in KV with TTL (`SESSION_TTL_SECONDS`).
+- Rotate `RELAY_API_KEY` and `DISCORD_CLIENT_SECRET` regularly.