Adds a token-authed API for the companion browser extension

- Versioned /api/v1 endpoints (Sanctum bearer) to list a user's tags and read/sync a repo's tags
- Extracts the star/tag sync into a shared SyncStarTags action so the web and API paths can't diverge
- Adds a single regenerable browser-extension access token, managed from the settings dialog

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: syropian

app/Data/UserData.php

@@ -26,15 +26,15 @@ public function __construct(
         public readonly ?string $scope,
         public readonly ?string $avatar,
         public readonly ?bool $is_sponsor,
+        public readonly bool $has_browser_extension_token,
         public readonly UserSettingsData $settings,
         /** @var Collection<int, UserFlagData> */
         public readonly Collection $flags,
         #[RecordTypeScriptType(Limit::class, 'int')]
         public readonly array $limits,
         #[RecordTypeScriptType(Ability::class, 'bool')]
         public readonly array $abilities,
-    ) {
-    }
+    ) {}
 
     public static function fromModel(User $user): self
     {
@@ -48,6 +48,7 @@ public static function fromModel(User $user): self
             $user->scope,
             $user->avatar,
             $user->is_sponsor,
+            $user->tokens()->where('name', User::BROWSER_EXTENSION_TOKEN)->exists(),
             UserSettingsData::from($user->settings),
             UserFlagData::collect($user->flags),
             $user->limits(),

app/Exceptions/TagLimitExceededException.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Exceptions;
+
+use App\Data\Enums\Ability;
+use Exception;
+
+class TagLimitExceededException extends Exception
+{
+    public function __construct(public readonly Ability $ability)
+    {
+        parent::__construct('Tag limit exceeded.');
+    }
+}

app/Http/Controllers/Api/V1/ExtensionController.php

@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Data\TagData;
+use App\Exceptions\TagLimitExceededException;
+use App\Http\Controllers\Controller;
+use App\Lib\SyncStarTags;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+class ExtensionController extends Controller
+{
+    /**
+     * The authenticated user's full tag list, used for the extension's autocomplete.
+     */
+    public function tags(Request $request): JsonResponse
+    {
+        return response()->json([
+            'tags' => TagData::collect($request->user()->tags()->withStarCount()->get()),
+        ]);
+    }
+
+    /**
+     * The Astral tags currently applied to a repo, keyed by its GitHub database id.
+     * Returns an empty set (not 404) when the repo has never been tagged.
+     */
+    public function repoTags(Request $request, int $databaseId): JsonResponse
+    {
+        $star = $request->user()->stars()->with('tags')->where('repo_id', $databaseId)->first();
+
+        return response()->json([
+            'databaseId' => $databaseId,
+            'starExists' => (bool) $star,
+            'tags' => $star ? TagData::collect($star->tags) : [],
+        ]);
+    }
+
+    /**
+     * Replace the full set of tags on a repo, creating the star and any missing
+     * tags. Mirrors the dashboard sync via the shared SyncStarTags action.
+     */
+    public function syncTags(Request $request, SyncStarTags $syncStarTags): JsonResponse
+    {
+        $request->validate([
+            'databaseId' => ['required', 'integer'],
+            'nameWithOwner' => ['required', 'string'],
+            'url' => ['required', 'string', 'url'],
+            'description' => ['nullable', 'string'],
+            'tags' => 'array',
+            'tags.*.name' => ['required_with:tags', 'string'],
+        ]);
+
+        try {
+            $star = $syncStarTags->handle(
+                $request->user(),
+                (int) $request->input('databaseId'),
+                $request->only(['nameWithOwner', 'url', 'description']),
+                $request->input('tags', []),
+            );
+        } catch (TagLimitExceededException $e) {
+            return response()->json([
+                'message' => 'Tag limit reached. An active sponsorship is required to add more tags.',
+                'sponsorshipRequired' => $e->ability->value,
+            ], 403);
+        }
+
+        return response()->json([
+            'databaseId' => $star->repo_id,
+            'tags' => TagData::collect($star->load('tags')->tags),
+        ]);
+    }
+}

app/Http/Controllers/BrowserExtensionTokenController.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers;
+
+use App\Models\User;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Response;
+
+class BrowserExtensionTokenController extends Controller
+{
+    /**
+     * Generate (or regenerate) the user's single browser-extension token and
+     * return the plaintext value once. Returns JSON so the secret never rides
+     * through Hybridly's persisted shared props.
+     */
+    public function store(): JsonResponse
+    {
+        /** @var User $user */
+        $user = auth()->user();
+
+        $user->tokens()->where('name', User::BROWSER_EXTENSION_TOKEN)->delete();
+
+        return response()->json([
+            'token' => $user->createToken(User::BROWSER_EXTENSION_TOKEN)->plainTextToken,
+        ]);
+    }
+
+    public function destroy(): Response
+    {
+        auth()->user()->tokens()->where('name', User::BROWSER_EXTENSION_TOKEN)->delete();
+
+        return response()->noContent();
+    }
+}

app/Http/Controllers/StarTagsController.php

@@ -4,10 +4,9 @@
 
 namespace App\Http\Controllers;
 
-use App\Data\Enums\Ability;
-use App\Models\Tag;
+use App\Exceptions\TagLimitExceededException;
+use App\Lib\SyncStarTags;
 use Illuminate\Http\Request;
-use Illuminate\Support\Facades\DB;
 use Illuminate\Validation\Rule;
 
 class StarTagsController extends Controller
@@ -55,7 +54,7 @@ public function store(Request $request)
      *
      * @return \Illuminate\Http\Response
      */
-    public function update(Request $request)
+    public function update(Request $request, SyncStarTags $syncStarTags)
     {
         $request->validate([
             'databaseId' => ['required', 'integer'],
@@ -66,45 +65,17 @@ public function update(Request $request)
             'tags.*.name' => ['required_with:tags', 'string'],
         ]);
 
-        DB::beginTransaction();
-
-        $repoId = $request->input('databaseId');
-        $tags = $request->input('tags');
-        $meta = $request->only(['nameWithOwner', 'url', 'description']);
-
-        $star = auth()
-            ->user()
-            ->stars()
-            ->firstOrCreate(
-                ['repo_id' => $repoId],
-                ['meta' => $meta]
+        try {
+            $syncStarTags->handle(
+                auth()->user(),
+                (int) $request->input('databaseId'),
+                $request->only(['nameWithOwner', 'url', 'description']),
+                $request->input('tags', []),
             );
-
-        $star->meta = $meta;
-        $star->save();
-
-        $ids = [];
-
-        if (empty($tags)) {
-            $star->removeAllTags();
-        } else {
-            foreach ($tags as $tag) {
-                $tag = auth()->user()->tags()->firstOrCreate(['name' => $tag['name']]);
-                $ids[] = $tag->id;
-            }
-            $star->tags()->sync($ids);
+        } catch (TagLimitExceededException $e) {
+            return $this->sponsorshipRequired($e->ability);
         }
 
-        // Authorized after the writes: syncing can firstOrCreate new tags, so the
-        // sponsorship cap is only knowable against the resulting tag count.
-        if (auth()->user()->cannot('sync', Tag::class)) {
-            DB::rollBack();
-
-            return $this->sponsorshipRequired(Ability::CREATE_TAG);
-        }
-
-        DB::commit();
-
         return redirect()->route('dashboard.show');
     }
 }

app/Lib/SyncStarTags.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Lib;
+
+use App\Data\Enums\Ability;
+use App\Exceptions\TagLimitExceededException;
+use App\Models\Star;
+use App\Models\Tag;
+use App\Models\User;
+use Illuminate\Support\Facades\DB;
+
+class SyncStarTags
+{
+    /**
+     * Sync the full set of tags on a user's star for the given repo, creating the
+     * star and any missing tags as needed. Shared by the web dashboard and the
+     * extension API so both stay identical.
+     *
+     * @param  array<string, mixed>  $meta  nameWithOwner, url, description
+     * @param  array<int, array{name: string}>  $tags
+     *
+     * @throws TagLimitExceededException when a non-sponsor exceeds the tag cap
+     */
+    public function handle(User $user, int $repoId, array $meta, array $tags): Star
+    {
+        DB::beginTransaction();
+
+        $star = $user->stars()->firstOrCreate(
+            ['repo_id' => $repoId],
+            ['meta' => $meta]
+        );
+
+        $star->meta = $meta;
+        $star->save();
+
+        if (empty($tags)) {
+            $star->removeAllTags();
+        } else {
+            $ids = [];
+            foreach ($tags as $tag) {
+                $ids[] = $user->tags()->firstOrCreate(['name' => $tag['name']])->id;
+            }
+            $star->tags()->sync($ids);
+        }
+
+        // Authorized after the writes: syncing can firstOrCreate new tags, so the
+        // sponsorship cap is only knowable against the resulting tag count.
+        if ($user->cannot('sync', Tag::class)) {
+            DB::rollBack();
+
+            throw new TagLimitExceededException(Ability::CREATE_TAG);
+        }
+
+        DB::commit();
+
+        return $star;
+    }
+}

app/Models/User.php

@@ -9,13 +9,16 @@
 use Illuminate\Foundation\Auth\User as Authenticatable;
 use Illuminate\Notifications\Notifiable;
 use Illuminate\Support\Facades\Http;
+use Laravel\Sanctum\HasApiTokens;
 
 /**
  * @mixin IdeHelperUser
  */
 class User extends Authenticatable
 {
-    use HasFactory, Notifiable;
+    use HasApiTokens, HasFactory, Notifiable;
+
+    public const BROWSER_EXTENSION_TOKEN = 'browser-extension';
 
     protected $hidden = [
         'remember_token',
@@ -43,6 +46,7 @@ protected static function booted()
             $user->tags()->delete();
             $user->stars()->delete();
             $user->flags()->delete();
+            $user->tokens()->delete();
         });
     }
 

database/migrations/2019_12_14_000001_create_personal_access_tokens_table.php

@@ -0,0 +1,33 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('personal_access_tokens', function (Blueprint $table) {
+            $table->id();
+            $table->morphs('tokenable');
+            $table->text('name');
+            $table->string('token', 64)->unique();
+            $table->text('abilities')->nullable();
+            $table->timestamp('last_used_at')->nullable();
+            $table->timestamp('expires_at')->nullable()->index();
+            $table->timestamps();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('personal_access_tokens');
+    }
+};