fix: Add API key scoped permissions (#319)

* fix: Add API key scoped permissions

* fix: Add API key scoped permissions

---------

Co-authored-by: Emmanuel Chukwunyere <emmanuelanalaba@gmail.com>

Author: Bamzy123

.env.example

@@ -1,3 +1,4 @@
 NEXT_PUBLIC_STELLAR_NETWORK=testnet
 NEXT_PUBLIC_CONTRACT_ID=YOUR_CONTRACT_ID_HERE
 NEXT_PUBLIC_RPC_URL=https://soroban-testnet.stellar.org
+API_KEY_SIGNING_SECRET=replace-with-a-long-random-server-secret

AUDIT-219.md

@@ -0,0 +1,39 @@
+# Audit: Issue #219 API Key Scoped Permissions
+
+## Result
+
+Issue #219 is implemented, including the security gap found during the first audit.
+
+## What Is Fixed
+
+- API key creation now includes a permission scope selector defaulting to `read` in `src/app/settings/api-keys/page.tsx`.
+- Generated keys store a `scope: "read" | "write"` field and the key list displays the scope with a badge.
+- Existing keys without a `scope` field migrate to `write` for backward-compatible display behavior, and the settings page shows a one-time review banner.
+- Mutating API routes under `src/app/api` require write scope through `requireWriteScope`.
+- New API keys are minted by `POST /api/api-keys` and signed server-side.
+- Write-route authorization now verifies the API key signature instead of trusting the `sk_write_` prefix, so forged keys like `sk_write_anything` are rejected.
+- Unit tests cover migration behavior, read-only rejection, write-key allowance, and forged write-key rejection.
+
+## Files Reviewed / Updated
+
+- `src/app/settings/api-keys/page.tsx`
+- `src/app/api/api-keys/route.ts`
+- `src/app/api/test-webhook/route.ts`
+- `src/app/api/send-confirmation/route.ts`
+- `src/lib/apiKeys.ts`
+- `src/lib/apiKeyAuth.ts`
+- `src/lib/signedApiKeys.ts`
+- `src/__tests__/apiKeys.test.ts`
+- `.env.example`
+
+## Remaining Notes
+
+- Deployments should set a stable `API_KEY_SIGNING_SECRET`. If this secret changes, previously generated signed keys will stop verifying.
+- Legacy pre-signed keys are still migrated to `write` in the local settings UI, but unsigned legacy tokens are no longer accepted by protected server routes because the server cannot authenticate browser-local historical keys safely.
+
+## Verification
+
+- `npm install` completed and restored the local Jest package.
+- `npm test -- --runTestsByPath src/__tests__/apiKeys.test.ts --runInBand` could not complete because Next's native SWC package fails to load locally: `next-swc.win32-x64-msvc.node is not a valid Win32 application`.
+- `npm rebuild @next/swc-win32-x64-msvc` completed, but the SWC loader error persisted.
+- `npx tsc --noEmit` could not complete because of an existing unrelated type declaration issue for `html2canvas` in `src/components/AchievementCard.tsx`.

src/__tests__/apiKeys.test.ts

@@ -0,0 +1,168 @@
+/**
+ * Unit tests for API key scoped permissions (#219):
+ * - Legacy key migration defaults to write scope
+ * - Read-only key rejected on write endpoints
+ * - Write key allowed on write endpoints
+ */
+
+import {
+  STORAGE_KEY,
+  checkWriteScope,
+  generateKeyValue,
+  loadKeys,
+  parseScopeFromKey,
+} from "@/lib/apiKeys";
+import { generateSignedApiKey, verifySignedApiKey } from "@/lib/signedApiKeys";
+import { POST as testWebhookPost } from "@/app/api/test-webhook/route";
+
+const store: Record<string, string> = {};
+const localStorageMock = {
+  getItem: (k: string) => store[k] ?? null,
+  setItem: (k: string, v: string) => {
+    store[k] = v;
+  },
+  removeItem: (k: string) => {
+    delete store[k];
+  },
+  clear: () => {
+    Object.keys(store).forEach((k) => delete store[k]);
+  },
+};
+Object.defineProperty(global, "localStorage", { value: localStorageMock });
+
+let fetchMock: jest.Mock;
+
+beforeEach(() => {
+  localStorageMock.clear();
+  fetchMock = jest.fn().mockResolvedValue({
+    ok: true,
+    status: 200,
+    text: async () => "ok",
+    headers: { forEach: () => {} },
+  });
+  global.fetch = fetchMock;
+});
+
+describe("parseScopeFromKey", () => {
+  it("returns read for sk_read_ keys", () => {
+    expect(parseScopeFromKey("sk_read_abc-123")).toBe("read");
+  });
+
+  it("returns write for sk_write_ keys", () => {
+    expect(parseScopeFromKey("sk_write_abc-123")).toBe("write");
+  });
+
+  it("returns write for legacy sk_<uuid> keys", () => {
+    expect(parseScopeFromKey("sk_550e8400-e29b-41d4-a716-446655440000")).toBe("write");
+  });
+
+  it("returns null for invalid keys", () => {
+    expect(parseScopeFromKey("invalid")).toBeNull();
+  });
+});
+
+describe("checkWriteScope", () => {
+  it("rejects read-only keys with 403", () => {
+    const result = checkWriteScope(generateSignedApiKey("read").key, verifySignedApiKey);
+    expect(result).toEqual({
+      ok: false,
+      status: 403,
+      error: "This endpoint requires write scope. Your API key is read-only.",
+    });
+  });
+
+  it("allows write-scoped keys", () => {
+    const result = checkWriteScope(generateSignedApiKey("write").key, verifySignedApiKey);
+    expect(result).toEqual({ ok: true, scope: "write" });
+  });
+
+  it("rejects forged write-prefixed keys", () => {
+    const result = checkWriteScope("sk_write_anything", verifySignedApiKey);
+    expect(result).toEqual({ ok: false, status: 401, error: "Invalid API key." });
+  });
+
+  it("returns 401 when token is missing", () => {
+    const result = checkWriteScope(null);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.status).toBe(401);
+  });
+});
+
+describe("loadKeys migration", () => {
+  it("defaults legacy keys without scope to write", () => {
+    localStorageMock.setItem(
+      STORAGE_KEY,
+      JSON.stringify([
+        {
+          id: "legacy-1",
+          name: "old-service",
+          key: "sk_550e8400-e29b-41d4-a716-446655440000",
+          createdAt: 1_700_000_000_000,
+        },
+      ])
+    );
+
+    const { keys, migratedLegacy } = loadKeys();
+    expect(migratedLegacy).toBe(true);
+    expect(keys).toHaveLength(1);
+    expect(keys[0]?.scope).toBe("write");
+  });
+
+  it("does not flag keys that already have scope", () => {
+    localStorageMock.setItem(
+      STORAGE_KEY,
+      JSON.stringify([
+        {
+          id: "new-1",
+          name: "readonly",
+          key: generateKeyValue("read"),
+          scope: "read",
+          createdAt: Date.now(),
+        },
+      ])
+    );
+
+    const { keys, migratedLegacy } = loadKeys();
+    expect(migratedLegacy).toBe(false);
+    expect(keys[0]?.scope).toBe("read");
+  });
+});
+
+describe("POST /api/test-webhook scope enforcement", () => {
+  const url = "https://example.com/hook";
+
+  async function callWebhook(token: string | null) {
+    const headers: Record<string, string> = { "Content-Type": "application/json" };
+    if (token) headers.Authorization = `Bearer ${token}`;
+
+    const req = new Request("http://localhost/api/test-webhook", {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ url }),
+    });
+
+    return testWebhookPost(req as unknown as import("next/server").NextRequest);
+  }
+
+  it("rejects read-only keys with 403", async () => {
+    const res = await callWebhook(generateSignedApiKey("read").key);
+    expect(res.status).toBe(403);
+    const body = await res.json();
+    expect(body.error).toContain("write scope");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("allows write-scoped keys", async () => {
+    const res = await callWebhook(generateSignedApiKey("write").key);
+    expect(res.status).toBe(200);
+    expect(fetchMock).toHaveBeenCalled();
+  });
+
+  it("rejects forged write keys", async () => {
+    const res = await callWebhook("sk_write_anything");
+    expect(res.status).toBe(401);
+    const body = await res.json();
+    expect(body.error).toBe("Invalid API key.");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});

src/app/api/api-keys/route.ts

@@ -0,0 +1,18 @@
+import { NextRequest, NextResponse } from "next/server";
+import { type ApiKeyScope } from "@/lib/apiKeys";
+import { generateSignedApiKey } from "@/lib/signedApiKeys";
+
+function isScope(value: unknown): value is ApiKeyScope {
+  return value === "read" || value === "write";
+}
+
+export async function POST(request: NextRequest) {
+  const body = await request.json().catch(() => null);
+  const scope = body?.scope;
+
+  if (!isScope(scope)) {
+    return NextResponse.json({ error: "scope must be read or write" }, { status: 400 });
+  }
+
+  return NextResponse.json(generateSignedApiKey(scope));
+}

src/app/api/send-confirmation/route.ts

@@ -1,4 +1,5 @@
 import { NextRequest, NextResponse } from "next/server";
+import { requireWriteScope } from "@/lib/apiKeyAuth";
 
 interface ConfirmationRequest {
   email: string;
@@ -8,6 +9,9 @@ interface ConfirmationRequest {
 }
 
 export async function POST(request: NextRequest) {
+  const authError = requireWriteScope(request);
+  if (authError) return authError;
+
   try {
     const body: ConfirmationRequest = await request.json();
     const { email, invoiceId, txHash, amount } = body;

src/app/api/test-webhook/route.ts

@@ -1,4 +1,5 @@
 import { NextRequest, NextResponse } from "next/server";
+import { requireWriteScope } from "@/lib/apiKeyAuth";
 
 const SAMPLE_PAYLOADS: Record<string, object> = {
   "invoice.created": {
@@ -37,6 +38,9 @@ const SAMPLE_PAYLOADS: Record<string, object> = {
 };
 
 export async function POST(req: NextRequest) {
+  const authError = requireWriteScope(req);
+  if (authError) return authError;
+
   const body = await req.json().catch(() => null);
   if (!body || typeof body.url !== "string" || !body.url) {
     return NextResponse.json({ error: "url is required" }, { status: 400 });