@dashai/sdk 0.7.0

package/dist/auth/server.d.cts

@@ -0,0 +1,170 @@
+import { AuthOptions, ExchangeResult, RbacMeResponse, Session } from './types.cjs';
+
+/**
+ * Server-side auth helpers — used from React Server Components, route
+ * handlers, and server actions. Imports `next/headers` lazily so the
+ * subpath remains importable from non-Next environments (tests, unit
+ * fixtures) without crashing on missing peer deps.
+ *
+ * Consumers:
+ *   import { getServerSession, exchangeCode } from '@dashai/sdk/auth/server';
+ *
+ * Public surface:
+ *   - `getServerSession(opts?)` — read the current session, or null
+ *   - `exchangeCode(code, opts?)` — exchange an SSO one-time code for a session
+ *   - `signOut(opts?)` — clear the session cookie + tell the backend
+ *
+ * All three accept an optional `AuthOptions` argument. Defaults come
+ * from `DASHWISE_*` env vars; see `config.ts`.
+ */
+
+/**
+ * Get the current session, or `null` if the user isn't signed in.
+ *
+ * Reads the session cookie from `next/headers` and validates it
+ * against the DashWise backend at `/api/auth/sessions/me`. Returns
+ * the validated `Session` on success.
+ *
+ * Cache: this call is uncached on purpose. The backend's `/me`
+ * endpoint is cheap (single DB row by indexed PK). Consumers that
+ * call `getServerSession()` multiple times per request should
+ * memoize at the React Server Component level.
+ *
+ * @example
+ *   import { getServerSession } from '@dashai/sdk/auth/server';
+ *   import { redirect } from 'next/navigation';
+ *
+ *   export default async function DashboardPage() {
+ *     const session = await getServerSession();
+ *     if (!session) redirect('/api/auth/sign-in');
+ *     return <h1>Hi {session.user.email}</h1>;
+ *   }
+ */
+declare function getServerSession(options?: AuthOptions): Promise<Session | null>;
+/**
+ * Fetch `/api/installations/:id/rbac/me` for the active session.
+ * Returns the resolved roles + permissions, or null on any failure
+ * (network, HTTP error, schema mismatch). Failure is non-fatal —
+ * the caller treats null as "no permissions" (default-deny).
+ *
+ * Exported so `auth/middleware.ts` can reuse the same code path
+ * without re-implementing the request shape.
+ */
+declare function fetchRbacMe(apiBaseUrl: string, cookieHeader: string, installationId: number, fetchImpl: typeof globalThis.fetch): Promise<RbacMeResponse | null>;
+/**
+ * Exchange an SSO one-time `code` (received at the OAuth callback
+ * URL `?code=...`) for a session. On success, sets the session
+ * cookie via `next/headers` AND returns the decoded session so the
+ * caller can chain a `redirect(returnTo)`.
+ *
+ * Call from your `/api/auth/callback/route.ts`:
+ *
+ * @example
+ *   import { exchangeCode } from '@dashai/sdk/auth/server';
+ *   import { NextResponse } from 'next/server';
+ *
+ *   export async function GET(request: Request) {
+ *     const url = new URL(request.url);
+ *     const code = url.searchParams.get('code');
+ *     const returnTo = url.searchParams.get('return_to') ?? '/';
+ *     if (!code) return NextResponse.redirect(new URL('/', request.url));
+ *     await exchangeCode(code);  // sets the cookie
+ *     return NextResponse.redirect(new URL(returnTo, request.url));
+ *   }
+ *
+ * Throws `DashwiseError` with `code === 'INVALID_EXCHANGE_CODE'` if
+ * the backend rejects (expired / replay / forged code).
+ */
+declare function exchangeCode(code: string, options?: AuthOptions): Promise<ExchangeResult>;
+/**
+ * Sign out the current user: clears the session cookie and notifies
+ * the backend so the server-side session record can be revoked
+ * before its natural expiry.
+ *
+ * Safe to call when not signed in (no-op). Returns nothing.
+ *
+ * Backend-side revocation is best-effort: if `/sign-out` fails, the
+ * cookie is still cleared client-side, so the user's local session
+ * is over regardless. The backend will reap the orphaned session
+ * record on its next periodic sweep.
+ */
+declare function signOut(options?: AuthOptions): Promise<void>;
+/**
+ * Sync check: does the given session hold `permissionKey`?
+ *
+ * Accepts either the bare form (`tasks:delete`) or the namespaced
+ * form (`tasks-app:tasks:delete`). Returns false if the session is
+ * null OR has no RBAC data (default-deny floor).
+ *
+ * For consumers using `getServerSession()`, prefer the async variants
+ * below — they handle the case where you forgot to call
+ * `getServerSession()` first.
+ *
+ * @example
+ *   const session = await getServerSession();
+ *   if (!hasPermissionInSession(session, 'tasks:delete')) {
+ *     return new Response('Forbidden', { status: 403 });
+ *   }
+ */
+declare function hasPermissionInSession(session: Session | null | undefined, permissionKey: string): boolean;
+/**
+ * Sync check: does the given session hold `roleKey`?
+ * Same semantics as `hasPermissionInSession`.
+ */
+declare function hasRoleInSession(session: Session | null | undefined, roleKey: string): boolean;
+/**
+ * Async convenience: fetch the session AND check a permission in
+ * one call. Returns true iff a session exists + holds the key.
+ *
+ * Most server-component code paths look like:
+ *
+ * @example
+ *   if (!(await hasPermission('tasks:delete'))) {
+ *     return <Forbidden />;
+ *   }
+ */
+declare function hasPermission(permissionKey: string, options?: AuthOptions): Promise<boolean>;
+/**
+ * Async convenience: as `hasPermission` but for roles.
+ */
+declare function hasRole(roleKey: string, options?: AuthOptions): Promise<boolean>;
+/**
+ * Throw `DashwiseError('PERMISSION_DENIED')` if the session lacks
+ * `permissionKey`. Pattern for guarding server actions + RSC
+ * branches that should redirect-to-403 on failure.
+ *
+ * Throws `RBAC_UNAVAILABLE` if there's no session at all — distinct
+ * from PERMISSION_DENIED so callers can branch on "needs sign-in"
+ * vs "signed in but forbidden".
+ *
+ * Returns the loaded session on success — saves a second
+ * `getServerSession()` call in handlers that need both.
+ *
+ * @example
+ *   import { requirePermission } from '@dashai/sdk/auth/server';
+ *
+ *   export default async function DeletePanel() {
+ *     const session = await requirePermission('tasks:delete');
+ *     return <DeleteForm userEmail={session.user.email} />;
+ *   }
+ */
+declare function requirePermission(permissionKey: string, options?: AuthOptions): Promise<Session>;
+/**
+ * Throw `PERMISSION_DENIED` unless the session holds at least one of
+ * the requested permissions. Useful for endpoints with multiple
+ * acceptable scopes.
+ */
+declare function requireAnyPermission(permissionKeys: readonly string[], options?: AuthOptions): Promise<Session>;
+/**
+ * Throw `PERMISSION_DENIED` unless the session holds all of the
+ * requested permissions. Useful for multi-permission gating where
+ * partial grants aren't acceptable.
+ */
+declare function requireAllPermissions(permissionKeys: readonly string[], options?: AuthOptions): Promise<Session>;
+/**
+ * Throw `PERMISSION_DENIED` unless the session holds `roleKey`.
+ * Sugar over `requirePermission` for role-centric handlers.
+ */
+declare function requireRole(roleKey: string, options?: AuthOptions): Promise<Session>;
+
+export { exchangeCode, fetchRbacMe, getServerSession, hasPermission, hasPermissionInSession, hasRole, hasRoleInSession, requireAllPermissions, requireAnyPermission, requirePermission, requireRole, signOut };

package/dist/auth/server.d.ts

@@ -0,0 +1,170 @@
+import { AuthOptions, ExchangeResult, RbacMeResponse, Session } from './types.js';
+
+/**
+ * Server-side auth helpers — used from React Server Components, route
+ * handlers, and server actions. Imports `next/headers` lazily so the
+ * subpath remains importable from non-Next environments (tests, unit
+ * fixtures) without crashing on missing peer deps.
+ *
+ * Consumers:
+ *   import { getServerSession, exchangeCode } from '@dashai/sdk/auth/server';
+ *
+ * Public surface:
+ *   - `getServerSession(opts?)` — read the current session, or null
+ *   - `exchangeCode(code, opts?)` — exchange an SSO one-time code for a session
+ *   - `signOut(opts?)` — clear the session cookie + tell the backend
+ *
+ * All three accept an optional `AuthOptions` argument. Defaults come
+ * from `DASHWISE_*` env vars; see `config.ts`.
+ */
+
+/**
+ * Get the current session, or `null` if the user isn't signed in.
+ *
+ * Reads the session cookie from `next/headers` and validates it
+ * against the DashWise backend at `/api/auth/sessions/me`. Returns
+ * the validated `Session` on success.
+ *
+ * Cache: this call is uncached on purpose. The backend's `/me`
+ * endpoint is cheap (single DB row by indexed PK). Consumers that
+ * call `getServerSession()` multiple times per request should
+ * memoize at the React Server Component level.
+ *
+ * @example
+ *   import { getServerSession } from '@dashai/sdk/auth/server';
+ *   import { redirect } from 'next/navigation';
+ *
+ *   export default async function DashboardPage() {
+ *     const session = await getServerSession();
+ *     if (!session) redirect('/api/auth/sign-in');
+ *     return <h1>Hi {session.user.email}</h1>;
+ *   }
+ */
+declare function getServerSession(options?: AuthOptions): Promise<Session | null>;
+/**
+ * Fetch `/api/installations/:id/rbac/me` for the active session.
+ * Returns the resolved roles + permissions, or null on any failure
+ * (network, HTTP error, schema mismatch). Failure is non-fatal —
+ * the caller treats null as "no permissions" (default-deny).
+ *
+ * Exported so `auth/middleware.ts` can reuse the same code path
+ * without re-implementing the request shape.
+ */
+declare function fetchRbacMe(apiBaseUrl: string, cookieHeader: string, installationId: number, fetchImpl: typeof globalThis.fetch): Promise<RbacMeResponse | null>;
+/**
+ * Exchange an SSO one-time `code` (received at the OAuth callback
+ * URL `?code=...`) for a session. On success, sets the session
+ * cookie via `next/headers` AND returns the decoded session so the
+ * caller can chain a `redirect(returnTo)`.
+ *
+ * Call from your `/api/auth/callback/route.ts`:
+ *
+ * @example
+ *   import { exchangeCode } from '@dashai/sdk/auth/server';
+ *   import { NextResponse } from 'next/server';
+ *
+ *   export async function GET(request: Request) {
+ *     const url = new URL(request.url);
+ *     const code = url.searchParams.get('code');
+ *     const returnTo = url.searchParams.get('return_to') ?? '/';
+ *     if (!code) return NextResponse.redirect(new URL('/', request.url));
+ *     await exchangeCode(code);  // sets the cookie
+ *     return NextResponse.redirect(new URL(returnTo, request.url));
+ *   }
+ *
+ * Throws `DashwiseError` with `code === 'INVALID_EXCHANGE_CODE'` if
+ * the backend rejects (expired / replay / forged code).
+ */
+declare function exchangeCode(code: string, options?: AuthOptions): Promise<ExchangeResult>;
+/**
+ * Sign out the current user: clears the session cookie and notifies
+ * the backend so the server-side session record can be revoked
+ * before its natural expiry.
+ *
+ * Safe to call when not signed in (no-op). Returns nothing.
+ *
+ * Backend-side revocation is best-effort: if `/sign-out` fails, the
+ * cookie is still cleared client-side, so the user's local session
+ * is over regardless. The backend will reap the orphaned session
+ * record on its next periodic sweep.
+ */
+declare function signOut(options?: AuthOptions): Promise<void>;
+/**
+ * Sync check: does the given session hold `permissionKey`?
+ *
+ * Accepts either the bare form (`tasks:delete`) or the namespaced
+ * form (`tasks-app:tasks:delete`). Returns false if the session is
+ * null OR has no RBAC data (default-deny floor).
+ *
+ * For consumers using `getServerSession()`, prefer the async variants
+ * below — they handle the case where you forgot to call
+ * `getServerSession()` first.
+ *
+ * @example
+ *   const session = await getServerSession();
+ *   if (!hasPermissionInSession(session, 'tasks:delete')) {
+ *     return new Response('Forbidden', { status: 403 });
+ *   }
+ */
+declare function hasPermissionInSession(session: Session | null | undefined, permissionKey: string): boolean;
+/**
+ * Sync check: does the given session hold `roleKey`?
+ * Same semantics as `hasPermissionInSession`.
+ */
+declare function hasRoleInSession(session: Session | null | undefined, roleKey: string): boolean;
+/**
+ * Async convenience: fetch the session AND check a permission in
+ * one call. Returns true iff a session exists + holds the key.
+ *
+ * Most server-component code paths look like:
+ *
+ * @example
+ *   if (!(await hasPermission('tasks:delete'))) {
+ *     return <Forbidden />;
+ *   }
+ */
+declare function hasPermission(permissionKey: string, options?: AuthOptions): Promise<boolean>;
+/**
+ * Async convenience: as `hasPermission` but for roles.
+ */
+declare function hasRole(roleKey: string, options?: AuthOptions): Promise<boolean>;
+/**
+ * Throw `DashwiseError('PERMISSION_DENIED')` if the session lacks
+ * `permissionKey`. Pattern for guarding server actions + RSC
+ * branches that should redirect-to-403 on failure.
+ *
+ * Throws `RBAC_UNAVAILABLE` if there's no session at all — distinct
+ * from PERMISSION_DENIED so callers can branch on "needs sign-in"
+ * vs "signed in but forbidden".
+ *
+ * Returns the loaded session on success — saves a second
+ * `getServerSession()` call in handlers that need both.
+ *
+ * @example
+ *   import { requirePermission } from '@dashai/sdk/auth/server';
+ *
+ *   export default async function DeletePanel() {
+ *     const session = await requirePermission('tasks:delete');
+ *     return <DeleteForm userEmail={session.user.email} />;
+ *   }
+ */
+declare function requirePermission(permissionKey: string, options?: AuthOptions): Promise<Session>;
+/**
+ * Throw `PERMISSION_DENIED` unless the session holds at least one of
+ * the requested permissions. Useful for endpoints with multiple
+ * acceptable scopes.
+ */
+declare function requireAnyPermission(permissionKeys: readonly string[], options?: AuthOptions): Promise<Session>;
+/**
+ * Throw `PERMISSION_DENIED` unless the session holds all of the
+ * requested permissions. Useful for multi-permission gating where
+ * partial grants aren't acceptable.
+ */
+declare function requireAllPermissions(permissionKeys: readonly string[], options?: AuthOptions): Promise<Session>;
+/**
+ * Throw `PERMISSION_DENIED` unless the session holds `roleKey`.
+ * Sugar over `requirePermission` for role-centric handlers.
+ */
+declare function requireRole(roleKey: string, options?: AuthOptions): Promise<Session>;
+
+export { exchangeCode, fetchRbacMe, getServerSession, hasPermission, hasPermissionInSession, hasRole, hasRoleInSession, requireAllPermissions, requireAnyPermission, requirePermission, requireRole, signOut };