[oauth] add bitbucket connection

.env.example

@@ -258,3 +258,36 @@ WEBHOOKS__BOT_USER_EMAIL=bot@bitissues.local
 # Example: {"implements":{"status":"In Progress"},"closes":{"status":"Closed","verb":"Closed"}}
 # Valid statuses: New, Open, In Progress, Resolved, Closed, Reopened, Invalid, Duplicate, Wontfix, On Hold
 WEBHOOKS__ACTION_KEYWORDS='{"fixes":{"status":"Resolved","verb":"Resolved"},"fixed":{"status":"Resolved","verb":"Resolved"},"resolves":{"status":"Resolved","verb":"Resolved"},"resolved":{"status":"Resolved","verb":"Resolved"},"closes":{"status":"Closed","verb":"Closed"},"closed":{"status":"Closed","verb":"Closed"},"blocks":{"status":"On Hold","verb":"On Hold"},"blocked":{"status":"On Hold","verb":"On Hold"},"on hold":{"status":"On Hold","verb":"On Hold"}}'
+
+# =============================================================================
+# BITBUCKET CONFIGURATION
+# =============================================================================
+
+# Bitbucket OAuth Client ID (optional)
+# Purpose: Consumer key of the Bitbucket OAuth consumer app used by the admin
+#   "Connect with Bitbucket" flow
+# Format: String (Bitbucket OAuth consumer key)
+# Default: (empty - OAuth connection disabled)
+# Setup: Bitbucket workspace settings -> OAuth consumers -> Add consumer.
+#   Required scope: webhook. See docs/oauth-setup.md for the walkthrough.
+OAUTH__CLIENT_ID=
+
+# Bitbucket OAuth Client Secret (optional)
+# Purpose: Consumer secret of the Bitbucket OAuth consumer app; sent only to
+#   the Bitbucket OAuth token endpoint, never logged
+# Format: String (Bitbucket OAuth consumer secret)
+# Default: (empty - OAuth connection disabled)
+OAUTH__CLIENT_SECRET=
+
+# OAuth Token Encryption Key (required only when OAuth connection is enabled)
+# Purpose: AES key used to encrypt the Bitbucket access and refresh tokens at
+#   rest in the oauth_tokens table (AES-GCM, 12-byte random nonce per value).
+# Format: 32 bytes (AES-256) encoded as hex or standard base64. Examples:
+#   base64: OAUTH__TOKEN_ENCRYPTION_KEY=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
+#   hex:    OAUTH__TOKEN_ENCRYPTION_KEY=<64-char hex string>
+# Default: (empty - OAuth disabled)
+# SECURITY: Must be kept secret and unique per environment. Store in a secrets
+#   manager, never commit it. Rotating the key renders all existing stored
+#   tokens unreadable (treat as a disconnect). When empty, the OAuth
+#   connection stays disabled and startup does not fail.
+OAUTH__TOKEN_ENCRYPTION_KEY=

bitbucket.http

@@ -0,0 +1,10 @@
+@client_id={{$dotenv BITBUCKET__CLIENT_ID}}
+@client_secret={{$dotenv BITBUCKET__CLIENT_SECRET}}
+@code={{$dotenv BITBUCKET__CODE}}
+
+###
+POST https://bitbucket.org/site/oauth2/access_token HTTP/1.1
+Authorization: Basic {{client_id}}:{{client_secret}}
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=authorization_code&code={{code}}

frontend/src/lib/api/oauth.ts

@@ -0,0 +1,20 @@
+import { apiRequest } from './client'
+import type {
+  BitbucketOAuthAuthorizeResponse,
+  BitbucketOAuthStatus,
+} from '$lib/types/api'
+
+export function getBitbucketOAuthStatus(): Promise<BitbucketOAuthStatus> {
+  return apiRequest<BitbucketOAuthStatus>('GET', '/oauth/bitbucket/status')
+}
+
+export function getBitbucketOAuthAuthorizeUrl(): Promise<BitbucketOAuthAuthorizeResponse> {
+  return apiRequest<BitbucketOAuthAuthorizeResponse>(
+    'GET',
+    '/oauth/bitbucket/authorize',
+  )
+}
+
+export function disconnectBitbucketOAuth(): Promise<void> {
+  return apiRequest<void>('POST', '/oauth/bitbucket/disconnect')
+}

frontend/src/lib/components/BitbucketOAuthCard.svelte

@@ -0,0 +1,167 @@
+<script lang="ts">
+  import { Button } from "$lib/components/ui/button";
+  import * as Card from "$lib/components/ui/card";
+  import * as Badge from "$lib/components/ui/badge";
+  import * as Dialog from "$lib/components/ui/dialog";
+  import {
+    disconnectBitbucketOAuth,
+    getBitbucketOAuthAuthorizeUrl,
+    getBitbucketOAuthStatus,
+  } from "$lib/api/oauth";
+  import { toast } from "$lib/toast";
+  import type { BitbucketOAuthStatus } from "$lib/types/api";
+
+  let status = $state<BitbucketOAuthStatus | null>(null);
+  let loading = $state(true);
+  let loadError = $state("");
+  let busy = $state(false);
+  let showDisconnectDialog = $state(false);
+
+  let connected = $derived(status?.connected === true);
+
+  let badgeLabel = $derived(connected ? "Connected" : "Disconnected");
+  let badgeColor = $derived(
+    connected
+      ? "border-transparent bg-green-100 text-green-700 dark:bg-green-300/15 dark:text-green-300"
+      : "border-transparent bg-gray-100 text-gray-600 dark:bg-gray-300/15 dark:text-gray-300",
+  );
+
+  function formatDate(iso?: string): string {
+    if (!iso) return "-";
+    const d = new Date(iso);
+    return Number.isNaN(d.getTime()) ? iso : d.toLocaleString();
+  }
+
+  function loadStatus() {
+    loading = true;
+    loadError = "";
+    getBitbucketOAuthStatus()
+      .then((res) => {
+        status = res;
+      })
+      .catch((e: Error) => {
+        status = null;
+        loadError = e?.message || "Failed to load Bitbucket connection status";
+      })
+      .finally(() => {
+        loading = false;
+      });
+  }
+
+  $effect(loadStatus);
+
+  async function handleConnect() {
+    if (busy) return;
+    busy = true;
+    try {
+      const { url } = await getBitbucketOAuthAuthorizeUrl();
+      window.location.assign(url);
+    } catch (e: any) {
+      toast.error(e?.message || "Failed to start Bitbucket connection");
+      busy = false;
+    }
+  }
+
+  async function handleDisconnect() {
+    if (busy) return;
+    busy = true;
+    try {
+      await disconnectBitbucketOAuth();
+      status = { connected: false };
+      showDisconnectDialog = false;
+      toast.success("Disconnected from Bitbucket");
+    } catch (e: any) {
+      toast.error(e?.message || "Failed to disconnect from Bitbucket");
+    } finally {
+      busy = false;
+    }
+  }
+</script>
+
+<Card.Root>
+  <Card.CardHeader>
+    <div class="flex items-center justify-between gap-2">
+      <Card.CardTitle>Bitbucket OAuth</Card.CardTitle>
+      {#if status}
+        <Badge.Root class={badgeColor}>{badgeLabel}</Badge.Root>
+      {/if}
+    </div>
+  </Card.CardHeader>
+  <Card.CardContent>
+    {#if loading}
+      <p class="text-muted-foreground text-sm">Loading...</p>
+    {:else if loadError}
+      <p class="text-destructive text-sm">{loadError}</p>
+    {:else if status}
+      <div class="flex flex-col gap-2">
+        <p class="text-muted-foreground text-sm">
+          {#if connected}
+            Webhook registration uses the connected Bitbucket app.
+          {:else}
+            Connect a Bitbucket app to manage repository webhooks.
+          {/if}
+        </p>
+        {#if connected}
+          <div class="flex flex-col gap-1">
+            <span class="text-muted-foreground text-xs font-medium">
+              Connected At
+            </span>
+            <span class="text-sm">{formatDate(status.connected_at)}</span>
+          </div>
+          <div class="flex flex-col gap-1">
+            <span class="text-muted-foreground text-xs font-medium">
+              Token Expires At
+            </span>
+            <span class="text-sm">{formatDate(status.expires_at)}</span>
+          </div>
+          {#if status.scopes?.length}
+            <div class="flex flex-col gap-1">
+              <span class="text-muted-foreground text-xs font-medium">
+                Scopes
+              </span>
+              <span class="text-sm">{status.scopes.join(", ")}</span>
+            </div>
+          {/if}
+        {/if}
+      </div>
+    {/if}
+  </Card.CardContent>
+  {#if !loading && (status || loadError)}
+    <Card.CardFooter class="justify-end gap-2">
+      {#if loadError && !status}
+        <Button size="sm" variant="outline" onclick={loadStatus}>Retry</Button>
+      {/if}
+      {#if status}
+        {#if connected}
+          <Button
+            size="sm"
+            variant="destructive"
+            disabled={busy}
+            onclick={() => (showDisconnectDialog = true)}
+          >
+            Disconnect
+          </Button>
+        {:else}
+          <Button size="sm" disabled={busy} onclick={handleConnect}>
+            {busy ? "Connecting..." : "Connect with Bitbucket"}
+          </Button>
+        {/if}
+      {/if}
+    </Card.CardFooter>
+  {/if}
+</Card.Root>
+
+<Dialog.Root
+  bind:open={showDisconnectDialog}
+  title="Disconnect from Bitbucket?"
+  description="Remove the stored Bitbucket OAuth connection?"
+>
+  {#snippet footer()}
+    <Button variant="ghost" onclick={() => (showDisconnectDialog = false)}>
+      Cancel
+    </Button>
+    <Button variant="destructive" onclick={handleDisconnect} disabled={busy}>
+      {busy ? "Disconnecting..." : "Disconnect"}
+    </Button>
+  {/snippet}
+</Dialog.Root>

frontend/src/lib/components/Sidebar.svelte

@@ -39,6 +39,7 @@
   const adminNav = [
     { pattern: "/admin/users", label: "Users", icon: UsersIcon },
     { pattern: "/admin/projects", label: "Projects", icon: SettingsIcon },
+    { pattern: "/admin", label: "Settings", icon: SettingsIcon },
   ];
 </script>
 
@@ -97,9 +98,7 @@
       </button>
 
       {#if pattern === "/projects" && recentProjects.length > 0}
-        <div
-          class="mt-2 ml-1 space-y-0.5 border-l border-border pl-2"
-        >
+        <div class="mt-2 ml-1 space-y-0.5 border-l border-border pl-2">
           <p class="px-2 pb-0.5 text-xs font-medium text-muted-foreground">
             Recent
           </p>

frontend/src/lib/pages/admin.svelte

@@ -1,5 +1,63 @@
 <script lang="ts">
   import { onMount } from "svelte";
-  import { navigate } from "$lib/router/routes";
-  onMount(() => navigate("/admin/users"));
+  import BitbucketOAuthCard from "$lib/components/BitbucketOAuthCard.svelte";
+  import { toast } from "$lib/toast";
+
+  const OAUTH_ERROR_MESSAGES: Record<string, string> = {
+    access_denied: "Bitbucket authorization was denied",
+    missing_params: "The Bitbucket callback was missing required parameters",
+    exchange_failed: "Bitbucket rejected the authorization code",
+    invalid_state: "The connection session expired or was already used. Try again.",
+  };
+
+  onMount(() => {
+    // The Bitbucket OAuth callback redirects to /#/admin?oauth=success|error.
+    // With the hash router the result lives in the fragment, so read it from
+    // window.location.hash (falling back to search for robustness).
+    const hashQuery = window.location.hash.split("?")[1] ?? "";
+    const params = new URLSearchParams(hashQuery || window.location.search);
+    const outcome = params.get("oauth");
+    if (outcome === "success") {
+      toast.success("Connected to Bitbucket");
+    } else if (outcome === "error") {
+      const reason = params.get("reason") ?? "";
+      toast.error(
+        OAUTH_ERROR_MESSAGES[reason] ?? "Failed to connect to Bitbucket",
+      );
+    } else {
+      return;
+    }
+
+    // Consume the one-shot oauth/reason params so a page refresh cannot replay
+    // the toast. Strip them from BOTH the hash fragment and window.location.search.
+    const hashParts = window.location.hash.slice(1).split("?");
+    const route = hashParts[0] || "/admin";
+    const hashParams = new URLSearchParams(hashParts[1] ?? "");
+    hashParams.delete("oauth");
+    hashParams.delete("reason");
+
+    const searchParams = new URLSearchParams(window.location.search);
+    searchParams.delete("oauth");
+    searchParams.delete("reason");
+
+    const searchStr = searchParams.toString();
+    const hashQueryStr = hashParams.toString();
+    const newURL =
+      window.location.pathname +
+      (searchStr ? "?" + searchStr : "") +
+      "#" + route +
+      (hashQueryStr ? "?" + hashQueryStr : "");
+
+    window.history.replaceState(null, "", newURL);
+  });
 </script>
+
+<div class="flex flex-col gap-4 p-6">
+  <div>
+    <h1 class="text-2xl font-bold">Settings</h1>
+    <p class="text-muted-foreground text-sm">
+      Manage integrations and workspace settings
+    </p>
+  </div>
+  <BitbucketOAuthCard />
+</div>

frontend/src/lib/types/api.ts

@@ -63,6 +63,17 @@ export interface UserBrief {
   created_at: string
 }
 
+export interface BitbucketOAuthStatus {
+  connected: boolean
+  connected_at?: string
+  expires_at?: string
+  scopes?: string[]
+}
+
+export interface BitbucketOAuthAuthorizeResponse {
+  url: string
+}
+
 export interface Task {
   id: number
   project_slug: string

go.mod

@@ -30,6 +30,7 @@ require (
 	go.uber.org/fx v1.24.0
 	go.uber.org/zap v1.28.0
 	golang.org/x/crypto v0.53.0
+	golang.org/x/sync v0.21.0
 )
 
 require (
@@ -110,7 +111,6 @@ require (
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
 	golang.org/x/mod v0.37.0 // indirect
 	golang.org/x/net v0.56.0 // indirect
-	golang.org/x/sync v0.21.0 // indirect
 	golang.org/x/sys v0.46.0 // indirect
 	golang.org/x/text v0.38.0 // indirect
 	golang.org/x/tools v0.46.0 // indirect

internal/commands/serve/serve.go

@@ -9,6 +9,7 @@ import (
 	"github.com/bit-issues/backend/internal/config"
 	"github.com/bit-issues/backend/internal/db"
 	"github.com/bit-issues/backend/internal/jwt"
+	"github.com/bit-issues/backend/internal/oauth"
 	"github.com/bit-issues/backend/internal/projects"
 	"github.com/bit-issues/backend/internal/server"
 	"github.com/bit-issues/backend/internal/storage"
@@ -75,12 +76,13 @@ func run(ctx context.Context, version healthfx.Version) error {
 		//
 		// BUSINESS MODULES
 		fx.Supply(version),
+		attachments.Module(),
+		comments.Module(),
 		jwt.Module(),
-		users.Module(),
+		oauth.Module(),
 		projects.Module(),
 		tasks.Module(),
-		attachments.Module(),
-		comments.Module(),
+		users.Module(),
 		webauthn.Module(),
 		webhooks.Module(),
 		//