@carlonicora/nextjs-jsonapi 1.24.3 → 1.25.1

package/src/features/oauth/components/consent/OAuthScopeList.tsx

@@ -0,0 +1,72 @@
+"use client";
+
+import {
+  Eye,
+  Pencil,
+  Image,
+  Upload,
+  Film,
+  FolderPlus,
+  User,
+  Shield,
+  LucideIcon,
+} from "lucide-react";
+import { OAuthScopeInfo } from "../../interfaces/oauth.interface";
+
+export interface OAuthScopeListProps {
+  /** List of requested scopes */
+  scopes: OAuthScopeInfo[];
+}
+
+/** Map scope icons to Lucide components */
+const SCOPE_ICONS: Record<string, LucideIcon> = {
+  eye: Eye,
+  pencil: Pencil,
+  image: Image,
+  upload: Upload,
+  film: Film,
+  "folder-plus": FolderPlus,
+  user: User,
+  shield: Shield,
+};
+
+/**
+ * List of requested OAuth scopes for consent display
+ */
+export function OAuthScopeList({ scopes }: OAuthScopeListProps) {
+  if (scopes.length === 0) {
+    return null;
+  }
+
+  return (
+    <div className="space-y-3">
+      <h2 className="text-sm font-medium text-muted-foreground uppercase tracking-wide">
+        This will allow the application to:
+      </h2>
+      <ul className="space-y-3">
+        {scopes.map((scope) => {
+          const IconComponent = scope.icon ? SCOPE_ICONS[scope.icon] : Eye;
+
+          return (
+            <li
+              key={scope.scope}
+              className="flex items-start gap-3 p-3 rounded-lg bg-muted/50"
+            >
+              <div className="flex-shrink-0 mt-0.5">
+                <div className="h-8 w-8 rounded-full bg-primary/10 flex items-center justify-center">
+                  {IconComponent && (
+                    <IconComponent className="h-4 w-4 text-primary" />
+                  )}
+                </div>
+              </div>
+              <div className="flex-1">
+                <p className="font-medium">{scope.name}</p>
+                <p className="text-sm text-muted-foreground">{scope.description}</p>
+              </div>
+            </li>
+          );
+        })}
+      </ul>
+    </div>
+  );
+}

package/src/features/oauth/components/consent/index.ts

@@ -0,0 +1,4 @@
+export * from "./OAuthConsentHeader";
+export * from "./OAuthScopeList";
+export * from "./OAuthConsentActions";
+export * from "./OAuthConsentScreen";

package/src/features/oauth/components/index.ts

@@ -0,0 +1,8 @@
+export * from "./OAuthRedirectUriInput";
+export * from "./OAuthScopeSelector";
+export * from "./OAuthClientSecretDisplay";
+export * from "./OAuthClientCard";
+export * from "./OAuthClientList";
+export * from "./OAuthClientForm";
+export * from "./OAuthClientDetail";
+export * from "./consent";

package/src/features/oauth/data/index.ts

@@ -0,0 +1,2 @@
+export * from "./oauth";
+export * from "./oauth.service";

package/src/features/oauth/data/oauth.service.ts

@@ -0,0 +1,191 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules, NextRef } from "../../../core";
+import {
+  OAuthClientCreateRequest,
+  OAuthClientCreateResponse,
+  OAuthClientInput,
+  OAuthClientInterface,
+  OAuthConsentInfo,
+  OAuthConsentRequest,
+} from "../interfaces/oauth.interface";
+
+/**
+ * Service for OAuth client management and authorization consent flow.
+ *
+ * Client Management endpoints:
+ * - GET /oauth/clients - List all clients for current user
+ * - GET /oauth/clients/:clientId - Get single client
+ * - POST /oauth/clients - Create new client (returns secret once)
+ * - PATCH /oauth/clients/:clientId - Update client
+ * - DELETE /oauth/clients/:clientId - Delete client
+ * - POST /oauth/clients/:clientId/regenerate-secret - Regenerate client secret
+ *
+ * Consent Flow endpoints:
+ * - GET /oauth/authorize/info - Get client info for consent screen
+ * - POST /oauth/authorize/approve - Approve authorization
+ * - POST /oauth/authorize/deny - Deny authorization
+ */
+export class OAuthService extends AbstractService {
+  // ==========================================
+  // CLIENT MANAGEMENT
+  // ==========================================
+
+  /**
+   * List all OAuth clients for the current user
+   */
+  static async listClients(params?: { next?: NextRef }): Promise<OAuthClientInterface[]> {
+    return this.callApi<OAuthClientInterface[]>({
+      type: Modules.OAuth,
+      method: HttpMethod.GET,
+      endpoint: new EndpointCreator({ endpoint: "oauth/clients" }).generate(),
+      next: params?.next,
+    });
+  }
+
+  /**
+   * Get a single OAuth client by ID
+   */
+  static async getClient(params: { clientId: string }): Promise<OAuthClientInterface> {
+    return this.callApi<OAuthClientInterface>({
+      type: Modules.OAuth,
+      method: HttpMethod.GET,
+      endpoint: new EndpointCreator({ endpoint: "oauth/clients", id: params.clientId }).generate(),
+    });
+  }
+
+  /**
+   * Create a new OAuth client
+   * @returns The created client AND the client secret (shown only once!)
+   */
+  static async createClient(data: OAuthClientCreateRequest): Promise<OAuthClientCreateResponse> {
+    const result = await this.callApiWithMeta<OAuthClientInterface>({
+      type: Modules.OAuth,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({ endpoint: "oauth/clients" }).generate(),
+      input: data,
+    });
+
+    return {
+      client: result.data,
+      clientSecret: result.meta?.clientSecret as string | undefined,
+    };
+  }
+
+  /**
+   * Update an existing OAuth client
+   */
+  static async updateClient(params: {
+    clientId: string;
+    data: Partial<OAuthClientInput>;
+  }): Promise<OAuthClientInterface> {
+    return this.callApi<OAuthClientInterface>({
+      type: Modules.OAuth,
+      method: HttpMethod.PATCH,
+      endpoint: new EndpointCreator({ endpoint: "oauth/clients", id: params.clientId }).generate(),
+      input: { id: params.clientId, ...params.data },
+    });
+  }
+
+  /**
+   * Delete an OAuth client
+   */
+  static async deleteClient(params: { clientId: string }): Promise<void> {
+    await this.callApi({
+      type: Modules.OAuth,
+      method: HttpMethod.DELETE,
+      endpoint: new EndpointCreator({ endpoint: "oauth/clients", id: params.clientId }).generate(),
+    });
+  }
+
+  /**
+   * Regenerate the client secret
+   * @returns The new client secret (shown only once!)
+   */
+  static async regenerateSecret(params: { clientId: string }): Promise<{ clientSecret: string }> {
+    const result = await this.callApiWithMeta<OAuthClientInterface>({
+      type: Modules.OAuth,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({
+        endpoint: "oauth/clients",
+        id: params.clientId,
+        childEndpoint: "regenerate-secret",
+      }).generate(),
+    });
+
+    return {
+      clientSecret: result.meta?.clientSecret as string,
+    };
+  }
+
+  // ==========================================
+  // CONSENT FLOW
+  // ==========================================
+
+  /**
+   * Get client information for the consent screen
+   * Called when user is redirected to /oauth/authorize
+   */
+  static async getAuthorizationInfo(params: OAuthConsentRequest): Promise<OAuthConsentInfo> {
+    const endpoint = new EndpointCreator({ endpoint: "oauth/authorize/info" });
+
+    // Add query parameters
+    endpoint.addAdditionalParam("client_id", params.clientId);
+    endpoint.addAdditionalParam("redirect_uri", params.redirectUri);
+    endpoint.addAdditionalParam("scope", params.scope);
+    if (params.state) endpoint.addAdditionalParam("state", params.state);
+    if (params.codeChallenge) endpoint.addAdditionalParam("code_challenge", params.codeChallenge);
+    if (params.codeChallengeMethod) endpoint.addAdditionalParam("code_challenge_method", params.codeChallengeMethod);
+
+    return this.callApi<OAuthConsentInfo>({
+      type: Modules.OAuth,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+    });
+  }
+
+  /**
+   * Approve the authorization request
+   * @returns Redirect URL with authorization code
+   */
+  static async approveAuthorization(params: OAuthConsentRequest): Promise<{ redirectUrl: string }> {
+    const result = await this.callApiWithMeta<unknown>({
+      type: Modules.OAuth,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({ endpoint: "oauth/authorize/approve" }).generate(),
+      input: {
+        client_id: params.clientId,
+        redirect_uri: params.redirectUri,
+        scope: params.scope,
+        state: params.state,
+        code_challenge: params.codeChallenge,
+        code_challenge_method: params.codeChallengeMethod,
+      },
+      overridesJsonApiCreation: true,
+    });
+
+    return {
+      redirectUrl: result.meta?.redirectUrl as string,
+    };
+  }
+
+  /**
+   * Deny the authorization request
+   * @returns Redirect URL with error=access_denied
+   */
+  static async denyAuthorization(params: OAuthConsentRequest): Promise<{ redirectUrl: string }> {
+    const result = await this.callApiWithMeta<unknown>({
+      type: Modules.OAuth,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({ endpoint: "oauth/authorize/deny" }).generate(),
+      input: {
+        client_id: params.clientId,
+        redirect_uri: params.redirectUri,
+        state: params.state,
+      },
+      overridesJsonApiCreation: true,
+    });
+
+    return {
+      redirectUrl: result.meta?.redirectUrl as string,
+    };
+  }
+}

package/src/features/oauth/data/oauth.ts

@@ -0,0 +1,87 @@
+import { AbstractApiData, JsonApiHydratedDataInterface } from "../../../core";
+import { OAuthClientInput, OAuthClientInterface } from "../interfaces/oauth.interface";
+
+/**
+ * OAuth client data model
+ * Represents a registered OAuth application that can request access tokens
+ */
+export class OAuthClient extends AbstractApiData implements OAuthClientInterface {
+  private _clientId?: string;
+  private _name?: string;
+  private _description?: string;
+  private _redirectUris: string[] = [];
+  private _allowedScopes: string[] = [];
+  private _allowedGrantTypes: string[] = [];
+  private _isConfidential: boolean = true;
+  private _isActive: boolean = true;
+
+  get clientId(): string {
+    return this._clientId ?? this.id;
+  }
+
+  get name(): string {
+    if (!this._name) throw new Error("Name is not defined");
+    return this._name;
+  }
+
+  get description(): string | undefined {
+    return this._description;
+  }
+
+  get redirectUris(): string[] {
+    return this._redirectUris;
+  }
+
+  get allowedScopes(): string[] {
+    return this._allowedScopes;
+  }
+
+  get allowedGrantTypes(): string[] {
+    return this._allowedGrantTypes;
+  }
+
+  get isConfidential(): boolean {
+    return this._isConfidential;
+  }
+
+  get isActive(): boolean {
+    return this._isActive;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attrs = data.jsonApi.attributes || {};
+
+    this._clientId = attrs.clientId ?? this._id;
+    this._name = attrs.name;
+    this._description = attrs.description;
+    this._redirectUris = attrs.redirectUris ?? [];
+    this._allowedScopes = attrs.allowedScopes ?? [];
+    this._allowedGrantTypes = attrs.allowedGrantTypes ?? [];
+    this._isConfidential = attrs.isConfidential ?? true;
+    this._isActive = attrs.isActive ?? true;
+
+    return this;
+  }
+
+  createJsonApi(data: OAuthClientInput) {
+    const response: any = {
+      data: {
+        type: "oauth-clients",
+        attributes: {},
+      },
+    };
+
+    if (data.id) response.data.id = data.id;
+    if (data.name !== undefined) response.data.attributes.name = data.name;
+    if (data.description !== undefined) response.data.attributes.description = data.description;
+    if (data.redirectUris !== undefined) response.data.attributes.redirectUris = data.redirectUris;
+    if (data.allowedScopes !== undefined) response.data.attributes.allowedScopes = data.allowedScopes;
+    if (data.allowedGrantTypes !== undefined) response.data.attributes.allowedGrantTypes = data.allowedGrantTypes;
+    if (data.isConfidential !== undefined) response.data.attributes.isConfidential = data.isConfidential;
+    if (data.isActive !== undefined) response.data.attributes.isActive = data.isActive;
+
+    return response;
+  }
+}

package/src/features/oauth/hooks/index.ts

@@ -0,0 +1,3 @@
+export * from "./useOAuthClients";
+export * from "./useOAuthClient";
+export * from "./useOAuthConsent";

package/src/features/oauth/hooks/useOAuthClient.ts

@@ -0,0 +1,161 @@
+"use client";
+
+import { useAtomValue, useSetAtom } from "jotai";
+import { useCallback, useEffect, useState } from "react";
+import {
+  oauthClientByIdAtom,
+  removeOAuthClientAtom,
+  setNewClientSecretAtom,
+  updateOAuthClientAtom,
+} from "../atoms/oauth.atoms";
+import { OAuthClientInput, OAuthClientInterface } from "../interfaces/oauth.interface";
+import { OAuthService } from "../data/oauth.service";
+
+export interface UseOAuthClientReturn {
+  /** The OAuth client (from store or fetched) */
+  client: OAuthClientInterface | null;
+  /** Whether the client is being loaded */
+  isLoading: boolean;
+  /** Error from last operation */
+  error: Error | null;
+  /** Update the client */
+  update: (data: Partial<OAuthClientInput>) => Promise<void>;
+  /** Delete the client */
+  deleteClient: () => Promise<void>;
+  /** Regenerate the client secret */
+  regenerateSecret: () => Promise<string>;
+  /** Refetch client from API */
+  refetch: () => Promise<void>;
+}
+
+/**
+ * Hook for managing a single OAuth client
+ *
+ * @param clientId - The client ID to manage
+ *
+ * @example
+ * ```tsx
+ * const { client, update, deleteClient, regenerateSecret } = useOAuthClient(clientId);
+ *
+ * const handleRegenerate = async () => {
+ *   const newSecret = await regenerateSecret();
+ *   // newSecret is shown only once!
+ * };
+ * ```
+ */
+export function useOAuthClient(clientId: string): UseOAuthClientReturn {
+  // Try to get from store first (populated by useOAuthClients)
+  const storedClient = useAtomValue(oauthClientByIdAtom(clientId));
+  const updateClientInStore = useSetAtom(updateOAuthClientAtom);
+  const removeClientFromStore = useSetAtom(removeOAuthClientAtom);
+  const setNewClientSecret = useSetAtom(setNewClientSecretAtom);
+
+  // Local state for fetched client (if not in store)
+  const [fetchedClient, setFetchedClient] = useState<OAuthClientInterface | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const client = storedClient || fetchedClient;
+
+  const fetchClient = useCallback(async () => {
+    if (!clientId) return;
+
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const fetched = await OAuthService.getClient({ clientId });
+      setFetchedClient(fetched);
+    } catch (err) {
+      console.error("[useOAuthClient] Failed to fetch client:", err);
+      setError(err instanceof Error ? err : new Error("Failed to fetch OAuth client"));
+    } finally {
+      setIsLoading(false);
+    }
+  }, [clientId]);
+
+  // Fetch if not in store
+  useEffect(() => {
+    if (!storedClient && clientId) {
+      fetchClient();
+    }
+  }, [storedClient, clientId, fetchClient]);
+
+  const update = useCallback(
+    async (data: Partial<OAuthClientInput>): Promise<void> => {
+      if (!clientId) throw new Error("No client ID");
+
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        const updated = await OAuthService.updateClient({ clientId, data });
+        updateClientInStore(updated);
+        setFetchedClient(updated);
+      } catch (err) {
+        console.error("[useOAuthClient] Failed to update client:", err);
+        const error = err instanceof Error ? err : new Error("Failed to update OAuth client");
+        setError(error);
+        throw error;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [clientId, updateClientInStore],
+  );
+
+  const deleteClient = useCallback(async (): Promise<void> => {
+    if (!clientId) throw new Error("No client ID");
+
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      await OAuthService.deleteClient({ clientId });
+      removeClientFromStore(clientId);
+    } catch (err) {
+      console.error("[useOAuthClient] Failed to delete client:", err);
+      const error = err instanceof Error ? err : new Error("Failed to delete OAuth client");
+      setError(error);
+      throw error;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [clientId, removeClientFromStore]);
+
+  const regenerateSecret = useCallback(async (): Promise<string> => {
+    if (!clientId) throw new Error("No client ID");
+
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const result = await OAuthService.regenerateSecret({ clientId });
+
+      // Store for one-time display
+      setNewClientSecret({
+        clientId,
+        secret: result.clientSecret,
+      });
+
+      return result.clientSecret;
+    } catch (err) {
+      console.error("[useOAuthClient] Failed to regenerate secret:", err);
+      const error = err instanceof Error ? err : new Error("Failed to regenerate client secret");
+      setError(error);
+      throw error;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [clientId, setNewClientSecret]);
+
+  return {
+    client,
+    isLoading,
+    error,
+    update,
+    deleteClient,
+    regenerateSecret,
+    refetch: fetchClient,
+  };
+}

package/src/features/oauth/hooks/useOAuthClients.ts

@@ -0,0 +1,111 @@
+"use client";
+
+import { useAtom, useSetAtom } from "jotai";
+import { useCallback, useEffect } from "react";
+import {
+  addOAuthClientAtom,
+  oauthClientsAtom,
+  oauthClientsErrorAtom,
+  oauthClientsLoadingAtom,
+  setNewClientSecretAtom,
+} from "../atoms/oauth.atoms";
+import {
+  OAuthClientCreateRequest,
+  OAuthClientCreateResponse,
+  OAuthClientInterface,
+} from "../interfaces/oauth.interface";
+import { OAuthService } from "../data/oauth.service";
+
+export interface UseOAuthClientsReturn {
+  /** List of OAuth clients */
+  clients: OAuthClientInterface[];
+  /** Whether clients are being loaded */
+  isLoading: boolean;
+  /** Error from last operation */
+  error: Error | null;
+  /** Refetch clients from API */
+  refetch: () => Promise<void>;
+  /** Create a new OAuth client */
+  createClient: (data: OAuthClientCreateRequest) => Promise<OAuthClientCreateResponse>;
+}
+
+/**
+ * Hook for managing OAuth clients list
+ *
+ * @example
+ * ```tsx
+ * const { clients, isLoading, createClient } = useOAuthClients();
+ *
+ * const handleCreate = async (data) => {
+ *   const { client, clientSecret } = await createClient(data);
+ *   // clientSecret is shown only once!
+ * };
+ * ```
+ */
+export function useOAuthClients(): UseOAuthClientsReturn {
+  const [clients, setClients] = useAtom(oauthClientsAtom);
+  const [isLoading, setIsLoading] = useAtom(oauthClientsLoadingAtom);
+  const [error, setError] = useAtom(oauthClientsErrorAtom);
+  const addClient = useSetAtom(addOAuthClientAtom);
+  const setNewClientSecret = useSetAtom(setNewClientSecretAtom);
+
+  const fetchClients = useCallback(async () => {
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const fetchedClients = await OAuthService.listClients();
+      setClients(fetchedClients);
+    } catch (err) {
+      console.error("[useOAuthClients] Failed to fetch clients:", err);
+      setError(err instanceof Error ? err : new Error("Failed to fetch OAuth clients"));
+    } finally {
+      setIsLoading(false);
+    }
+  }, [setClients, setIsLoading, setError]);
+
+  // Fetch clients on mount
+  useEffect(() => {
+    fetchClients();
+  }, [fetchClients]);
+
+  const createClient = useCallback(
+    async (data: OAuthClientCreateRequest): Promise<OAuthClientCreateResponse> => {
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        const result = await OAuthService.createClient(data);
+
+        // Add to local state
+        addClient(result.client);
+
+        // Store secret for one-time display
+        if (result.clientSecret) {
+          setNewClientSecret({
+            clientId: result.client.clientId,
+            secret: result.clientSecret,
+          });
+        }
+
+        return result;
+      } catch (err) {
+        console.error("[useOAuthClients] Failed to create client:", err);
+        const error = err instanceof Error ? err : new Error("Failed to create OAuth client");
+        setError(error);
+        throw error;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [addClient, setNewClientSecret, setIsLoading, setError],
+  );
+
+  return {
+    clients,
+    isLoading,
+    error,
+    refetch: fetchClients,
+    createClient,
+  };
+}