[FEAT] API Key Plugin

[m-t-a97]

User Story

As a developer using GoBetterAuth,
I want to issue API keys that are linked to user accounts and restricted by both "Scopes" and "RBAC Roles,"
So that I can provide secure programmatic access that automatically respects the owner's current permission levels.

Context & Rationale

An API key should never be a "blank check." By linking a key to an OwnerID and implementing Permission Intersection, we ensure a multi-layered security model.

If a user is demoted in the RBAC system, their API keys should immediately lose those corresponding powers, even if the key's "scopes" claim otherwise. This makes the system "secure by default" and prevents stale permissions from lingering on long-lived keys.

---

Technical Implementation Details

1. Data Model Extension

The API Key storage must include:

• OwnerID: A reference to the User/Account that owns the key.
• Scopes: A list of specific capabilities assigned to this key (e.g., reports:read).
• Metadata: Information for the developer's use (e.g., "CI/CD Bot").

2. Validation & Intersection Logic

When a request arrives with an API key, the validation logic must perform three steps:

1. Authentication: Does this key exist and match the stored hash?
2. Identity Retrieval: Who is the OwnerID associated with this key?
3. Permission Intersection: * Fetch the RBAC Roles/Permissions for the OwnerID.

• Compare them against the Scopes explicitly granted to the API key.
• The Result: The request is only authorized for actions that exist in both sets.

3. Management & Lifecycle

• CRUD for Keys: Endpoints to generate, rotate, and revoke keys for a specific OwnerID.
• Usage Tracking: Atomic updates for last_used_at and request_count to allow for usage monitoring.
• Revocation Ripple: If an account is deleted or suspended, all associated API keys must immediately fail validation.

---

Acceptance Criteria (AC)

• Owner Linking: API keys successfully link to an existing UserID.
• Scope Enforcement: A key with only read scopes cannot perform write actions, even if the owner is an Admin.
• RBAC Enforcement: A key with admin scopes cannot perform admin actions if the owner's RBAC role has been changed to viewer.
• Secure Key Display: The raw API key is displayed exactly once upon creation and never stored.
• Usage Transparency: Key usage is tracked (count and timestamp) and exposed via the plugin's management API.
• Request Context Injection: The validated identity and the "Intersected" permission set are injected into the request context.

Implementation Hints

• The "Intersection" Rule: Logic-wise, this looks like: EffectivePermissions = UserPermissions ∩ KeyScopes.
• Caching: Since fetching RBAC roles on every API call can be expensive, the hook should support an optional short-lived cache (using the SecondaryStorage plugin indirectly) for the "Intersected" permission set.
• Naming Convention: Consider a recognizable prefix for keys (e.g., gba_sk_...) to help users identify the source of the key in their own logs.

---

Subject to change.