@carlonicora/nextjs-jsonapi 1.24.3 → 1.25.1

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