@logickernel/bridge 0.5.0

package/dist/next/index.d.cts

@@ -0,0 +1,345 @@
+import { b as Session, S as SessionCookie, M as MicroFrontendConfig } from '../types-YvOY9KNP.cjs';
+export { d as SessionUser } from '../types-YvOY9KNP.cjs';
+import { NextRequest } from 'next/server';
+
+/**
+ * Kernel Bridge Next.js Session
+ * Server-side session utilities for Next.js
+ */
+
+/**
+ * Get the session cookie from Next.js cookies
+ */
+declare function getSessionCookie(): Promise<SessionCookie | undefined>;
+/**
+ * Get the session token value from cookies
+ */
+declare function getSessionToken(): Promise<string | undefined>;
+/**
+ * Check if secure cookie is being used
+ */
+declare function isSecureCookie(): Promise<boolean>;
+/**
+ * Get the current session from cookies
+ *
+ * This reads the NextAuth session cookie and decodes the JWT.
+ * Use this in Server Components, Server Actions, or API routes.
+ *
+ * @returns Session object or null if not authenticated
+ *
+ * @example
+ * ```typescript
+ * import { getSession } from "@logickernel/bridge/next"
+ *
+ * export default async function Page() {
+ *   const session = await getSession()
+ *   if (!session) {
+ *     redirect("/auth/signin")
+ *   }
+ *   return <div>Hello {session.user.email}</div>
+ * }
+ * ```
+ */
+declare function getSession(): Promise<Session | null>;
+/**
+ * Get the base URL (facade/load balancer) for user-facing links and redirects
+ *
+ * This is the URL that users access through the facade/load balancer.
+ * Use this for:
+ * - Sign-in redirect URLs
+ * - User-facing links to the kernel
+ * - Any URLs that users will see or click
+ */
+declare function getBaseUrl(): string;
+/**
+ * Get user roles in an organization
+ *
+ * Fetches roles from the kernel API using the current session.
+ * The user ID is determined from the session token.
+ *
+ * @param organizationId - Organization ID to fetch roles in
+ * @returns Array of role names (empty if error or no roles)
+ *
+ * @example
+ * ```typescript
+ * import { getUserRoles } from "@logickernel/bridge/next"
+ *
+ * const roles = await getUserRoles("org-123")
+ * const isOwner = roles.includes("organization.owner")
+ * ```
+ */
+declare function getUserRoles(organizationId: string): Promise<string[]>;
+
+/**
+ * Kernel Bridge Next.js Types
+ * Next.js-specific type definitions
+ */
+
+/**
+ * Options for the proxy factory
+ */
+interface ProxyOptions extends MicroFrontendConfig {
+    /**
+     * Dynamic route patterns that contain organization IDs
+     * e.g., "/[organization_id]/admin" matches "/abc123/admin"
+     */
+    dynamicRoutes?: DynamicRoutePattern[];
+    /**
+     * Custom error page path (defaults to showing error in redirect)
+     */
+    errorPath?: string;
+}
+/**
+ * Dynamic route pattern configuration
+ */
+interface DynamicRoutePattern {
+    /**
+     * Pattern to match (e.g., "/[organization_id]/admin")
+     * Use [param] syntax for dynamic segments
+     */
+    pattern: string;
+    /**
+     * Required roles for this route (empty = any authenticated user)
+     */
+    requiredRoles: string[];
+}
+/**
+ * Result from parsing a dynamic route
+ */
+interface DynamicRouteMatch {
+    matched: boolean;
+    params: Record<string, string>;
+    requiredRoles: string[];
+}
+/**
+ * API route handler with auth context
+ */
+type AuthenticatedHandler = (request: NextRequest, context: AuthContext) => Promise<Response> | Response;
+/**
+ * Context provided to authenticated handlers
+ */
+interface AuthContext {
+    session: Session;
+    params?: Record<string, string>;
+}
+/**
+ * Options for withAuth wrapper
+ */
+interface WithAuthOptions {
+    /**
+     * Required roles (empty = any authenticated user)
+     */
+    requiredRoles?: string[];
+    /**
+     * Organization ID parameter name in dynamic routes
+     */
+    organizationId?: string;
+}
+/**
+ * Page auth result
+ */
+type PageAuthResult = {
+    authenticated: true;
+    session: Session;
+    roles: string[];
+} | {
+    authenticated: false;
+    redirectUrl: string;
+};
+/**
+ * Options for page auth check
+ */
+interface PageAuthOptions {
+    /**
+     * Required roles (empty = any authenticated user)
+     */
+    requiredRoles?: string[];
+    /**
+     * Organization ID for role checking
+     */
+    organizationId?: string;
+}
+
+/**
+ * Kernel Bridge Next.js Page
+ * Authentication utilities for pages/server components
+ */
+
+/**
+ * Check authentication and optionally roles for a page
+ *
+ * This is a helper for pages that need both auth and role checking.
+ * For simple auth-only checks, use getSession() directly.
+ *
+ * @param options - Authentication options
+ * @returns Auth result with session/roles or redirect URL
+ *
+ * @example
+ * ```typescript
+ * import { checkPageAuth } from "@logickernel/bridge/next"
+ * import { redirect } from "next/navigation"
+ *
+ * export default async function AdminPage({ params }) {
+ *   const { organization_id } = await params
+ *
+ *   const auth = await checkPageAuth({
+ *     requiredRoles: ["organization.owner"],
+ *     organizationId: organization_id,
+ *   })
+ *
+ *   if (!auth.authenticated) {
+ *     redirect(auth.redirectUrl)
+ *   }
+ *
+ *   return <div>Welcome {auth.session.user.email}</div>
+ * }
+ * ```
+ */
+declare function checkPageAuth(options?: PageAuthOptions): Promise<PageAuthResult>;
+/**
+ * Require authentication for a page
+ *
+ * This is a simpler helper that throws if not authenticated.
+ * Use with redirect() in the catch block.
+ *
+ * @returns Session if authenticated
+ * @throws RedirectInfo if not authenticated
+ *
+ * @example
+ * ```typescript
+ * import { requireAuth } from "@logickernel/bridge/next"
+ * import { redirect } from "next/navigation"
+ *
+ * export default async function DashboardPage() {
+ *   const session = await requireAuth()
+ *   // If we get here, user is authenticated
+ *   return <div>Hello {session.user.email}</div>
+ * }
+ * ```
+ */
+declare function requireAuth(): Promise<Session>;
+/**
+ * Check if user has any of the required roles
+ *
+ * The user ID is determined from the session token in cookies.
+ *
+ * @param organizationId - Organization to check roles in
+ * @param requiredRoles - Roles to check for
+ * @returns True if user has at least one required role
+ *
+ * @example
+ * ```typescript
+ * const hasAccess = await hasRequiredRole(
+ *   "org-123",
+ *   ["organization.owner", "organization.editor"]
+ * )
+ * ```
+ */
+declare function hasRequiredRole(organizationId: string, requiredRoles: string[]): Promise<boolean>;
+
+/**
+ * Kernel Bridge Next.js API
+ * Authentication utilities for API routes
+ */
+
+/**
+ * Wrap an API route handler with authentication
+ *
+ * This handles JWT validation and optionally role checking.
+ * The handler receives the session and can focus on business logic.
+ *
+ * @param handler - The authenticated handler function
+ * @param options - Authentication options
+ * @returns A Next.js route handler
+ *
+ * @example
+ * ```typescript
+ * // Any authenticated user
+ * export const GET = withAuth(async (request, { session }) => {
+ *   return NextResponse.json({ user: session.user })
+ * })
+ *
+ * // With role requirement
+ * export const DELETE = withAuth(
+ *   async (request, { session }) => {
+ *     return NextResponse.json({ deleted: true })
+ *   },
+ *   { requiredRoles: ["organization.owner"] }
+ * )
+ * ```
+ */
+declare function withAuth(handler: AuthenticatedHandler, options?: WithAuthOptions): (request: NextRequest, context?: {
+    params?: Promise<Record<string, string>>;
+}) => Promise<Response>;
+/**
+ * Get session from a request (for manual handling)
+ *
+ * Use this when you need more control than withAuth provides.
+ *
+ * @param request - The Next.js request
+ * @returns Session or null
+ *
+ * @example
+ * ```typescript
+ * export async function GET(request: NextRequest) {
+ *   const session = await getSessionFromRequest(request)
+ *   if (!session) {
+ *     return NextResponse.json({ error: "Unauthorized" }, { status: 401 })
+ *   }
+ *   // Custom logic...
+ * }
+ * ```
+ */
+declare function getSessionFromRequest(request: NextRequest): Promise<Session | null>;
+
+/**
+ * Kernel Bridge Next.js Proxy
+ * Middleware/proxy utilities for Next.js
+ */
+
+/**
+ * Create a proxy/middleware handler function for Next.js
+ *
+ * This creates a fully configured middleware handler that:
+ * - Validates authentication for protected routes
+ * - Handles dynamic routes with organization IDs
+ * - Redirects unauthenticated users to sign in
+ * - Adds user info to request headers for downstream use
+ *
+ * Note: The `config` export must be defined statically in your proxy.ts file
+ * for Next.js to analyze it at compile time.
+ *
+ * @param options - Proxy configuration
+ * @returns A Next.js proxy handler function
+ *
+ * @example
+ * ```typescript
+ * // src/proxy.ts
+ * import { createProxyHandler, type ProxyOptions } from "@logickernel/bridge/next"
+ *
+ * const proxyConfig: ProxyOptions = {
+ *   basePath: "/aura",
+ *   protectedRoutes: { "/dashboard": [] },
+ *   dynamicRoutes: [
+ *     { pattern: "/[organization_id]/admin", requiredRoles: ["organization.owner"] },
+ *   ],
+ * }
+ *
+ * export const proxy = createProxyHandler(proxyConfig)
+ *
+ * // Config must be static for Next.js
+ * export const config = {
+ *   matcher: ["/((?!_next/static|_next/image|favicon.ico|public).*)"],
+ * }
+ * ```
+ */
+declare function createProxyHandler(options: ProxyOptions): (request: NextRequest) => Promise<Response>;
+/**
+ * Default matcher config for proxy
+ * Can be used if you don't want to define your own config
+ */
+declare const defaultProxyConfig: {
+    matcher: string[];
+};
+
+export { type AuthContext, type AuthenticatedHandler, type DynamicRouteMatch, type DynamicRoutePattern, type PageAuthOptions, type PageAuthResult, type ProxyOptions, Session, SessionCookie, type WithAuthOptions, checkPageAuth, createProxyHandler, defaultProxyConfig, getBaseUrl, getSession, getSessionCookie, getSessionFromRequest, getSessionToken, getUserRoles, hasRequiredRole, isSecureCookie, requireAuth, withAuth };

package/dist/next/index.d.ts

@@ -0,0 +1,345 @@
+import { b as Session, S as SessionCookie, M as MicroFrontendConfig } from '../types-YvOY9KNP.js';
+export { d as SessionUser } from '../types-YvOY9KNP.js';
+import { NextRequest } from 'next/server';
+
+/**
+ * Kernel Bridge Next.js Session
+ * Server-side session utilities for Next.js
+ */
+
+/**
+ * Get the session cookie from Next.js cookies
+ */
+declare function getSessionCookie(): Promise<SessionCookie | undefined>;
+/**
+ * Get the session token value from cookies
+ */
+declare function getSessionToken(): Promise<string | undefined>;
+/**
+ * Check if secure cookie is being used
+ */
+declare function isSecureCookie(): Promise<boolean>;
+/**
+ * Get the current session from cookies
+ *
+ * This reads the NextAuth session cookie and decodes the JWT.
+ * Use this in Server Components, Server Actions, or API routes.
+ *
+ * @returns Session object or null if not authenticated
+ *
+ * @example
+ * ```typescript
+ * import { getSession } from "@logickernel/bridge/next"
+ *
+ * export default async function Page() {
+ *   const session = await getSession()
+ *   if (!session) {
+ *     redirect("/auth/signin")
+ *   }
+ *   return <div>Hello {session.user.email}</div>
+ * }
+ * ```
+ */
+declare function getSession(): Promise<Session | null>;
+/**
+ * Get the base URL (facade/load balancer) for user-facing links and redirects
+ *
+ * This is the URL that users access through the facade/load balancer.
+ * Use this for:
+ * - Sign-in redirect URLs
+ * - User-facing links to the kernel
+ * - Any URLs that users will see or click
+ */
+declare function getBaseUrl(): string;
+/**
+ * Get user roles in an organization
+ *
+ * Fetches roles from the kernel API using the current session.
+ * The user ID is determined from the session token.
+ *
+ * @param organizationId - Organization ID to fetch roles in
+ * @returns Array of role names (empty if error or no roles)
+ *
+ * @example
+ * ```typescript
+ * import { getUserRoles } from "@logickernel/bridge/next"
+ *
+ * const roles = await getUserRoles("org-123")
+ * const isOwner = roles.includes("organization.owner")
+ * ```
+ */
+declare function getUserRoles(organizationId: string): Promise<string[]>;
+
+/**
+ * Kernel Bridge Next.js Types
+ * Next.js-specific type definitions
+ */
+
+/**
+ * Options for the proxy factory
+ */
+interface ProxyOptions extends MicroFrontendConfig {
+    /**
+     * Dynamic route patterns that contain organization IDs
+     * e.g., "/[organization_id]/admin" matches "/abc123/admin"
+     */
+    dynamicRoutes?: DynamicRoutePattern[];
+    /**
+     * Custom error page path (defaults to showing error in redirect)
+     */
+    errorPath?: string;
+}
+/**
+ * Dynamic route pattern configuration
+ */
+interface DynamicRoutePattern {
+    /**
+     * Pattern to match (e.g., "/[organization_id]/admin")
+     * Use [param] syntax for dynamic segments
+     */
+    pattern: string;
+    /**
+     * Required roles for this route (empty = any authenticated user)
+     */
+    requiredRoles: string[];
+}
+/**
+ * Result from parsing a dynamic route
+ */
+interface DynamicRouteMatch {
+    matched: boolean;
+    params: Record<string, string>;
+    requiredRoles: string[];
+}
+/**
+ * API route handler with auth context
+ */
+type AuthenticatedHandler = (request: NextRequest, context: AuthContext) => Promise<Response> | Response;
+/**
+ * Context provided to authenticated handlers
+ */
+interface AuthContext {
+    session: Session;
+    params?: Record<string, string>;
+}
+/**
+ * Options for withAuth wrapper
+ */
+interface WithAuthOptions {
+    /**
+     * Required roles (empty = any authenticated user)
+     */
+    requiredRoles?: string[];
+    /**
+     * Organization ID parameter name in dynamic routes
+     */
+    organizationId?: string;
+}
+/**
+ * Page auth result
+ */
+type PageAuthResult = {
+    authenticated: true;
+    session: Session;
+    roles: string[];
+} | {
+    authenticated: false;
+    redirectUrl: string;
+};
+/**
+ * Options for page auth check
+ */
+interface PageAuthOptions {
+    /**
+     * Required roles (empty = any authenticated user)
+     */
+    requiredRoles?: string[];
+    /**
+     * Organization ID for role checking
+     */
+    organizationId?: string;
+}
+
+/**
+ * Kernel Bridge Next.js Page
+ * Authentication utilities for pages/server components
+ */
+
+/**
+ * Check authentication and optionally roles for a page
+ *
+ * This is a helper for pages that need both auth and role checking.
+ * For simple auth-only checks, use getSession() directly.
+ *
+ * @param options - Authentication options
+ * @returns Auth result with session/roles or redirect URL
+ *
+ * @example
+ * ```typescript
+ * import { checkPageAuth } from "@logickernel/bridge/next"
+ * import { redirect } from "next/navigation"
+ *
+ * export default async function AdminPage({ params }) {
+ *   const { organization_id } = await params
+ *
+ *   const auth = await checkPageAuth({
+ *     requiredRoles: ["organization.owner"],
+ *     organizationId: organization_id,
+ *   })
+ *
+ *   if (!auth.authenticated) {
+ *     redirect(auth.redirectUrl)
+ *   }
+ *
+ *   return <div>Welcome {auth.session.user.email}</div>
+ * }
+ * ```
+ */
+declare function checkPageAuth(options?: PageAuthOptions): Promise<PageAuthResult>;
+/**
+ * Require authentication for a page
+ *
+ * This is a simpler helper that throws if not authenticated.
+ * Use with redirect() in the catch block.
+ *
+ * @returns Session if authenticated
+ * @throws RedirectInfo if not authenticated
+ *
+ * @example
+ * ```typescript
+ * import { requireAuth } from "@logickernel/bridge/next"
+ * import { redirect } from "next/navigation"
+ *
+ * export default async function DashboardPage() {
+ *   const session = await requireAuth()
+ *   // If we get here, user is authenticated
+ *   return <div>Hello {session.user.email}</div>
+ * }
+ * ```
+ */
+declare function requireAuth(): Promise<Session>;
+/**
+ * Check if user has any of the required roles
+ *
+ * The user ID is determined from the session token in cookies.
+ *
+ * @param organizationId - Organization to check roles in
+ * @param requiredRoles - Roles to check for
+ * @returns True if user has at least one required role
+ *
+ * @example
+ * ```typescript
+ * const hasAccess = await hasRequiredRole(
+ *   "org-123",
+ *   ["organization.owner", "organization.editor"]
+ * )
+ * ```
+ */
+declare function hasRequiredRole(organizationId: string, requiredRoles: string[]): Promise<boolean>;
+
+/**
+ * Kernel Bridge Next.js API
+ * Authentication utilities for API routes
+ */
+
+/**
+ * Wrap an API route handler with authentication
+ *
+ * This handles JWT validation and optionally role checking.
+ * The handler receives the session and can focus on business logic.
+ *
+ * @param handler - The authenticated handler function
+ * @param options - Authentication options
+ * @returns A Next.js route handler
+ *
+ * @example
+ * ```typescript
+ * // Any authenticated user
+ * export const GET = withAuth(async (request, { session }) => {
+ *   return NextResponse.json({ user: session.user })
+ * })
+ *
+ * // With role requirement
+ * export const DELETE = withAuth(
+ *   async (request, { session }) => {
+ *     return NextResponse.json({ deleted: true })
+ *   },
+ *   { requiredRoles: ["organization.owner"] }
+ * )
+ * ```
+ */
+declare function withAuth(handler: AuthenticatedHandler, options?: WithAuthOptions): (request: NextRequest, context?: {
+    params?: Promise<Record<string, string>>;
+}) => Promise<Response>;
+/**
+ * Get session from a request (for manual handling)
+ *
+ * Use this when you need more control than withAuth provides.
+ *
+ * @param request - The Next.js request
+ * @returns Session or null
+ *
+ * @example
+ * ```typescript
+ * export async function GET(request: NextRequest) {
+ *   const session = await getSessionFromRequest(request)
+ *   if (!session) {
+ *     return NextResponse.json({ error: "Unauthorized" }, { status: 401 })
+ *   }
+ *   // Custom logic...
+ * }
+ * ```
+ */
+declare function getSessionFromRequest(request: NextRequest): Promise<Session | null>;
+
+/**
+ * Kernel Bridge Next.js Proxy
+ * Middleware/proxy utilities for Next.js
+ */
+
+/**
+ * Create a proxy/middleware handler function for Next.js
+ *
+ * This creates a fully configured middleware handler that:
+ * - Validates authentication for protected routes
+ * - Handles dynamic routes with organization IDs
+ * - Redirects unauthenticated users to sign in
+ * - Adds user info to request headers for downstream use
+ *
+ * Note: The `config` export must be defined statically in your proxy.ts file
+ * for Next.js to analyze it at compile time.
+ *
+ * @param options - Proxy configuration
+ * @returns A Next.js proxy handler function
+ *
+ * @example
+ * ```typescript
+ * // src/proxy.ts
+ * import { createProxyHandler, type ProxyOptions } from "@logickernel/bridge/next"
+ *
+ * const proxyConfig: ProxyOptions = {
+ *   basePath: "/aura",
+ *   protectedRoutes: { "/dashboard": [] },
+ *   dynamicRoutes: [
+ *     { pattern: "/[organization_id]/admin", requiredRoles: ["organization.owner"] },
+ *   ],
+ * }
+ *
+ * export const proxy = createProxyHandler(proxyConfig)
+ *
+ * // Config must be static for Next.js
+ * export const config = {
+ *   matcher: ["/((?!_next/static|_next/image|favicon.ico|public).*)"],
+ * }
+ * ```
+ */
+declare function createProxyHandler(options: ProxyOptions): (request: NextRequest) => Promise<Response>;
+/**
+ * Default matcher config for proxy
+ * Can be used if you don't want to define your own config
+ */
+declare const defaultProxyConfig: {
+    matcher: string[];
+};
+
+export { type AuthContext, type AuthenticatedHandler, type DynamicRouteMatch, type DynamicRoutePattern, type PageAuthOptions, type PageAuthResult, type ProxyOptions, Session, SessionCookie, type WithAuthOptions, checkPageAuth, createProxyHandler, defaultProxyConfig, getBaseUrl, getSession, getSessionCookie, getSessionFromRequest, getSessionToken, getUserRoles, hasRequiredRole, isSecureCookie, requireAuth, withAuth };