@carlonicora/nextjs-jsonapi 1.24.2 → 1.25.0

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,
+  };
+}

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

@@ -0,0 +1,125 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import { OAuthConsentInfo, OAuthConsentRequest } from "../interfaces/oauth.interface";
+import { OAuthService } from "../data/oauth.service";
+
+export interface UseOAuthConsentReturn {
+  /** Client and scope info for consent display */
+  clientInfo: OAuthConsentInfo | null;
+  /** Whether consent info is being loaded */
+  isLoading: boolean;
+  /** Error from consent flow */
+  error: Error | null;
+  /** Approve the authorization request */
+  approve: () => Promise<void>;
+  /** Deny the authorization request */
+  deny: () => Promise<void>;
+  /** Whether approve/deny is in progress */
+  isSubmitting: boolean;
+}
+
+/**
+ * Hook for managing the OAuth consent flow
+ *
+ * @param params - OAuth authorization parameters from URL
+ *
+ * @example
+ * ```tsx
+ * const { clientInfo, isLoading, approve, deny } = useOAuthConsent({
+ *   clientId: searchParams.client_id,
+ *   redirectUri: searchParams.redirect_uri,
+ *   scope: searchParams.scope,
+ *   state: searchParams.state,
+ * });
+ *
+ * // Render consent screen with clientInfo
+ * // On button click: approve() or deny()
+ * ```
+ */
+export function useOAuthConsent(params: OAuthConsentRequest): UseOAuthConsentReturn {
+  const [clientInfo, setClientInfo] = useState<OAuthConsentInfo | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  // Fetch client info on mount
+  useEffect(() => {
+    const fetchInfo = async () => {
+      if (!params.clientId || !params.redirectUri || !params.scope) {
+        setError(new Error("Missing required authorization parameters"));
+        setIsLoading(false);
+        return;
+      }
+
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        const info = await OAuthService.getAuthorizationInfo(params);
+        setClientInfo(info);
+      } catch (err) {
+        console.error("[useOAuthConsent] Failed to fetch authorization info:", err);
+        setError(err instanceof Error ? err : new Error("Failed to load authorization info"));
+      } finally {
+        setIsLoading(false);
+      }
+    };
+
+    fetchInfo();
+  }, [
+    params.clientId,
+    params.redirectUri,
+    params.scope,
+    params.state,
+    params.codeChallenge,
+    params.codeChallengeMethod,
+  ]);
+
+  const approve = useCallback(async (): Promise<void> => {
+    setIsSubmitting(true);
+    setError(null);
+
+    try {
+      const result = await OAuthService.approveAuthorization(params);
+
+      // Redirect to client with authorization code
+      if (result.redirectUrl) {
+        window.location.href = result.redirectUrl;
+      }
+    } catch (err) {
+      console.error("[useOAuthConsent] Failed to approve authorization:", err);
+      setError(err instanceof Error ? err : new Error("Failed to approve authorization"));
+      setIsSubmitting(false);
+    }
+    // Note: Don't set isSubmitting to false on success - we're redirecting
+  }, [params]);
+
+  const deny = useCallback(async (): Promise<void> => {
+    setIsSubmitting(true);
+    setError(null);
+
+    try {
+      const result = await OAuthService.denyAuthorization(params);
+
+      // Redirect to client with error
+      if (result.redirectUrl) {
+        window.location.href = result.redirectUrl;
+      }
+    } catch (err) {
+      console.error("[useOAuthConsent] Failed to deny authorization:", err);
+      setError(err instanceof Error ? err : new Error("Failed to deny authorization"));
+      setIsSubmitting(false);
+    }
+    // Note: Don't set isSubmitting to false on success - we're redirecting
+  }, [params]);
+
+  return {
+    clientInfo,
+    isLoading,
+    error,
+    approve,
+    deny,
+    isSubmitting,
+  };
+}

package/src/features/oauth/index.ts

@@ -0,0 +1,6 @@
+export * from "./oauth.module";
+export * from "./interfaces";
+export * from "./data";
+export * from "./atoms";
+export * from "./hooks";
+export * from "./components";

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

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

package/src/features/oauth/interfaces/oauth.interface.ts

@@ -0,0 +1,175 @@
+import { ApiDataInterface } from "../../../core";
+
+/**
+ * OAuth client application interface
+ * Represents a registered OAuth application that can request access tokens
+ */
+export interface OAuthClientInterface extends ApiDataInterface {
+  /** The public client identifier (UUID format) */
+  get clientId(): string;
+  /** Human-readable application name */
+  get name(): string;
+  /** Optional description of the application */
+  get description(): string | undefined;
+  /** Array of allowed redirect URIs (exact match validation) */
+  get redirectUris(): string[];
+  /** Array of scopes this client can request */
+  get allowedScopes(): string[];
+  /** Supported grant types (authorization_code, client_credentials, refresh_token) */
+  get allowedGrantTypes(): string[];
+  /** True for server-side apps (can keep secret secure), false for mobile/desktop apps */
+  get isConfidential(): boolean;
+  /** Whether the client is currently active */
+  get isActive(): boolean;
+  /** When the client was created */
+  get createdAt(): Date;
+  /** When the client was last updated */
+  get updatedAt(): Date;
+}
+
+/**
+ * Input type for OAuth client CRUD operations
+ */
+export type OAuthClientInput = {
+  id?: string;
+  name?: string;
+  description?: string;
+  redirectUris?: string[];
+  allowedScopes?: string[];
+  allowedGrantTypes?: string[];
+  isConfidential?: boolean;
+  isActive?: boolean;
+};
+
+/**
+ * Request body for creating a new OAuth client
+ */
+export interface OAuthClientCreateRequest {
+  /** Required: Human-readable application name */
+  name: string;
+  /** Optional: Description of the application */
+  description?: string;
+  /** Required: At least one redirect URI */
+  redirectUris: string[];
+  /** Required: Array of scopes the client needs */
+  allowedScopes: string[];
+  /** Optional: Grant types (defaults to authorization_code + refresh_token) */
+  allowedGrantTypes?: string[];
+  /** Required: Whether this is a confidential client */
+  isConfidential: boolean;
+}
+
+/**
+ * Response when creating a client (includes one-time secret)
+ */
+export interface OAuthClientCreateResponse {
+  client: OAuthClientInterface;
+  /** Only returned on creation - must be saved immediately */
+  clientSecret?: string;
+}
+
+/**
+ * Parameters for the OAuth authorization consent flow
+ * Passed via URL query parameters to the consent page
+ */
+export interface OAuthConsentRequest {
+  /** The client_id requesting authorization */
+  clientId: string;
+  /** Where to redirect after authorization */
+  redirectUri: string;
+  /** Space-separated list of requested scopes */
+  scope: string;
+  /** CSRF protection token (passed back on redirect) */
+  state?: string;
+  /** PKCE code challenge (required for public clients) */
+  codeChallenge?: string;
+  /** PKCE method: 'S256' (recommended) or 'plain' */
+  codeChallengeMethod?: string;
+}
+
+/**
+ * Scope information for display in consent screen
+ */
+export interface OAuthScopeInfo {
+  /** The scope identifier (e.g., 'photographs:read') */
+  scope: string;
+  /** Human-readable scope name */
+  name: string;
+  /** Description of what this scope allows */
+  description: string;
+  /** Optional icon identifier */
+  icon?: string;
+}
+
+/**
+ * Client info returned for consent screen display
+ */
+export interface OAuthConsentInfo {
+  client: OAuthClientInterface;
+  scopes: OAuthScopeInfo[];
+}
+
+/**
+ * Default scope display configuration
+ * Maps scope identifiers to human-readable info
+ */
+export const OAUTH_SCOPE_DISPLAY: Record<string, OAuthScopeInfo> = {
+  read: {
+    scope: "read",
+    name: "Read Access",
+    description: "Read access to your data",
+    icon: "eye",
+  },
+  write: {
+    scope: "write",
+    name: "Write Access",
+    description: "Write access to your data",
+    icon: "pencil",
+  },
+  "photographs:read": {
+    scope: "photographs:read",
+    name: "View Photographs",
+    description: "Access and download your photo library",
+    icon: "image",
+  },
+  "photographs:write": {
+    scope: "photographs:write",
+    name: "Upload Photographs",
+    description: "Add new photos to your rolls",
+    icon: "upload",
+  },
+  "rolls:read": {
+    scope: "rolls:read",
+    name: "View Rolls",
+    description: "See your film rolls and collections",
+    icon: "film",
+  },
+  "rolls:write": {
+    scope: "rolls:write",
+    name: "Manage Rolls",
+    description: "Create and modify film rolls",
+    icon: "folder-plus",
+  },
+  profile: {
+    scope: "profile",
+    name: "View Profile",
+    description: "Access your name and email",
+    icon: "user",
+  },
+  admin: {
+    scope: "admin",
+    name: "Administrative Access",
+    description: "Full administrative access to your account",
+    icon: "shield",
+  },
+};
+
+/**
+ * Available scopes list for the scope selector
+ */
+export const AVAILABLE_OAUTH_SCOPES: OAuthScopeInfo[] = Object.values(OAUTH_SCOPE_DISPLAY);
+
+/**
+ * Default grant types for new clients
+ */
+export const DEFAULT_GRANT_TYPES = ["authorization_code", "refresh_token"];

package/src/features/oauth/oauth.module.ts

@@ -0,0 +1,9 @@
+import { ModuleFactory } from "../../permissions";
+import { OAuthClient } from "./data/oauth";
+
+export const OAuthModule = (factory: ModuleFactory) =>
+  factory({
+    pageUrl: "/oauth",
+    name: "oauth-clients",
+    model: OAuthClient,
+  });