@htlkg/core 0.0.2 → 0.0.3

package/src/amplify-astro-adapter/errors.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect } from "vitest";
+import {
+	AmplifyAstroAdapterError,
+	ErrorCodes,
+	createConfigMissingError,
+	createAuthFailedError,
+	createCookieError,
+	createGraphQLError,
+	createContextCreationError,
+	createTokenRefreshError,
+} from "./errors";
+
+describe("AmplifyAstroAdapterError", () => {
+	it("should create error with message and code", () => {
+		const error = new AmplifyAstroAdapterError(
+			"Test error",
+			"TEST_CODE"
+		);
+
+		expect(error.message).toBe("Test error");
+		expect(error.code).toBe("TEST_CODE");
+		expect(error.name).toBe("AmplifyAstroAdapterError");
+		expect(error.recoverySuggestion).toBeUndefined();
+	});
+
+	it("should create error with recovery suggestion", () => {
+		const error = new AmplifyAstroAdapterError(
+			"Test error",
+			"TEST_CODE",
+			"Try this fix"
+		);
+
+		expect(error.recoverySuggestion).toBe("Try this fix");
+	});
+
+	it("should be instanceof Error", () => {
+		const error = new AmplifyAstroAdapterError("Test", "CODE");
+		expect(error).toBeInstanceOf(Error);
+	});
+});
+
+describe("Error factory functions", () => {
+	describe("createConfigMissingError", () => {
+		it("should create config missing error", () => {
+			const error = createConfigMissingError("userPoolId");
+
+			expect(error.message).toContain("userPoolId");
+			expect(error.code).toBe(ErrorCodes.CONFIG_MISSING);
+			expect(error.recoverySuggestion).toContain("amplify_outputs.json");
+		});
+	});
+
+	describe("createAuthFailedError", () => {
+		it("should create auth failed error", () => {
+			const error = createAuthFailedError("Invalid token");
+
+			expect(error.message).toContain("Invalid token");
+			expect(error.code).toBe(ErrorCodes.AUTH_FAILED);
+			expect(error.recoverySuggestion).toContain("tokens are valid");
+		});
+	});
+
+	describe("createCookieError", () => {
+		it("should create cookie error", () => {
+			const error = createCookieError("set", "Invalid format");
+
+			expect(error.message).toContain("set");
+			expect(error.message).toContain("Invalid format");
+			expect(error.code).toBe(ErrorCodes.COOKIE_ERROR);
+			expect(error.recoverySuggestion).toContain("cookie");
+		});
+	});
+
+	describe("createGraphQLError", () => {
+		it("should create GraphQL error", () => {
+			const error = createGraphQLError("query", "Network error");
+
+			expect(error.message).toContain("query");
+			expect(error.message).toContain("Network error");
+			expect(error.code).toBe(ErrorCodes.GRAPHQL_ERROR);
+			expect(error.recoverySuggestion).toContain("network");
+		});
+	});
+
+	describe("createContextCreationError", () => {
+		it("should create context creation error", () => {
+			const error = createContextCreationError("Missing config");
+
+			expect(error.message).toContain("Missing config");
+			expect(error.code).toBe(ErrorCodes.CONTEXT_CREATION_FAILED);
+			expect(error.recoverySuggestion).toContain("Amplify configuration");
+		});
+	});
+
+	describe("createTokenRefreshError", () => {
+		it("should create token refresh error", () => {
+			const error = createTokenRefreshError("Expired refresh token");
+
+			expect(error.message).toContain("Expired refresh token");
+			expect(error.code).toBe(ErrorCodes.TOKEN_REFRESH_FAILED);
+			expect(error.recoverySuggestion).toContain("re-authenticate");
+		});
+	});
+});
+
+describe("ErrorCodes", () => {
+	it("should have all expected error codes", () => {
+		expect(ErrorCodes.CONFIG_MISSING).toBe("CONFIG_MISSING");
+		expect(ErrorCodes.AUTH_FAILED).toBe("AUTH_FAILED");
+		expect(ErrorCodes.COOKIE_ERROR).toBe("COOKIE_ERROR");
+		expect(ErrorCodes.GRAPHQL_ERROR).toBe("GRAPHQL_ERROR");
+		expect(ErrorCodes.CONTEXT_CREATION_FAILED).toBe("CONTEXT_CREATION_FAILED");
+		expect(ErrorCodes.TOKEN_REFRESH_FAILED).toBe("TOKEN_REFRESH_FAILED");
+	});
+});

package/src/amplify-astro-adapter/errors.ts

@@ -0,0 +1,105 @@
+/**
+ * Error classes for adapter-specific errors
+ */
+
+/**
+ * Base error class for Amplify Astro Adapter errors
+ */
+export class AmplifyAstroAdapterError extends Error {
+  public readonly code: string;
+  public readonly recoverySuggestion?: string;
+
+  constructor(
+    message: string,
+    code: string,
+    recoverySuggestion?: string
+  ) {
+    super(message);
+    this.name = 'AmplifyAstroAdapterError';
+    this.code = code;
+    this.recoverySuggestion = recoverySuggestion;
+
+    // Maintains proper stack trace for where our error was thrown (only available on V8)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, AmplifyAstroAdapterError);
+    }
+  }
+}
+
+/**
+ * Error codes for different types of adapter errors
+ */
+export const ErrorCodes = {
+  CONFIG_MISSING: 'CONFIG_MISSING',
+  AUTH_FAILED: 'AUTH_FAILED',
+  COOKIE_ERROR: 'COOKIE_ERROR',
+  GRAPHQL_ERROR: 'GRAPHQL_ERROR',
+  CONTEXT_CREATION_FAILED: 'CONTEXT_CREATION_FAILED',
+  TOKEN_REFRESH_FAILED: 'TOKEN_REFRESH_FAILED',
+} as const;
+
+/**
+ * Creates a configuration missing error
+ */
+export function createConfigMissingError(missingConfig: string): AmplifyAstroAdapterError {
+  return new AmplifyAstroAdapterError(
+    `Amplify configuration is missing: ${missingConfig}`,
+    ErrorCodes.CONFIG_MISSING,
+    'Ensure amplify_outputs.json is properly configured and accessible to the adapter'
+  );
+}
+
+/**
+ * Creates an authentication failed error
+ */
+export function createAuthFailedError(reason: string): AmplifyAstroAdapterError {
+  return new AmplifyAstroAdapterError(
+    `Authentication failed: ${reason}`,
+    ErrorCodes.AUTH_FAILED,
+    'Check that authentication tokens are valid and not expired'
+  );
+}
+
+/**
+ * Creates a cookie error
+ */
+export function createCookieError(operation: string, reason: string): AmplifyAstroAdapterError {
+  return new AmplifyAstroAdapterError(
+    `Cookie ${operation} failed: ${reason}`,
+    ErrorCodes.COOKIE_ERROR,
+    'Verify cookie data format and ensure cookies are properly set in the response'
+  );
+}
+
+/**
+ * Creates a GraphQL error
+ */
+export function createGraphQLError(operation: string, reason: string): AmplifyAstroAdapterError {
+  return new AmplifyAstroAdapterError(
+    `GraphQL ${operation} failed: ${reason}`,
+    ErrorCodes.GRAPHQL_ERROR,
+    'Check network connectivity and GraphQL schema configuration'
+  );
+}
+
+/**
+ * Creates a context creation failed error
+ */
+export function createContextCreationError(reason: string): AmplifyAstroAdapterError {
+  return new AmplifyAstroAdapterError(
+    `Server context creation failed: ${reason}`,
+    ErrorCodes.CONTEXT_CREATION_FAILED,
+    'Verify Amplify configuration and authentication setup'
+  );
+}
+
+/**
+ * Creates a token refresh failed error
+ */
+export function createTokenRefreshError(reason: string): AmplifyAstroAdapterError {
+  return new AmplifyAstroAdapterError(
+    `Token refresh failed: ${reason}`,
+    ErrorCodes.TOKEN_REFRESH_FAILED,
+    'User may need to re-authenticate or check refresh token validity'
+  );
+}

package/src/amplify-astro-adapter/globalSettings.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { globalSettings } from "./globalSettings";
+
+describe("globalSettings", () => {
+	beforeEach(() => {
+		// Reset settings before each test
+		globalSettings.setRuntimeOptions({});
+		globalSettings.setIsSSLOrigin(false);
+	});
+
+	describe("runtimeOptions", () => {
+		it("should set and get runtime options", () => {
+			const options = {
+				cookies: {
+					domain: "example.com",
+					httpOnly: true,
+					secure: true,
+				},
+			};
+
+			globalSettings.setRuntimeOptions(options);
+			expect(globalSettings.getRuntimeOptions()).toEqual(options);
+		});
+
+		it("should handle empty options", () => {
+			globalSettings.setRuntimeOptions({});
+			expect(globalSettings.getRuntimeOptions()).toEqual({});
+		});
+
+		it("should handle undefined options", () => {
+			globalSettings.setRuntimeOptions(undefined as any);
+			expect(globalSettings.getRuntimeOptions()).toEqual({});
+		});
+	});
+
+	describe("serverSideAuth", () => {
+		it("should be enabled by default", () => {
+			// The implementation starts with serverSideAuthEnabled = true
+			expect(globalSettings.isServerSideAuthEnabled()).toBe(true);
+		});
+
+		it("should enable server-side auth", () => {
+			globalSettings.enableServerSideAuth();
+			expect(globalSettings.isServerSideAuthEnabled()).toBe(true);
+		});
+
+		it("should remain enabled after multiple calls", () => {
+			globalSettings.enableServerSideAuth();
+			globalSettings.enableServerSideAuth();
+			expect(globalSettings.isServerSideAuthEnabled()).toBe(true);
+		});
+	});
+
+	describe("SSL origin", () => {
+		it("should start as false", () => {
+			expect(globalSettings.isSSLOrigin()).toBe(false);
+		});
+
+		it("should set SSL origin to true", () => {
+			globalSettings.setIsSSLOrigin(true);
+			expect(globalSettings.isSSLOrigin()).toBe(true);
+		});
+
+		it("should set SSL origin to false", () => {
+			globalSettings.setIsSSLOrigin(true);
+			globalSettings.setIsSSLOrigin(false);
+			expect(globalSettings.isSSLOrigin()).toBe(false);
+		});
+
+		it("should toggle SSL origin", () => {
+			expect(globalSettings.isSSLOrigin()).toBe(false);
+			globalSettings.setIsSSLOrigin(true);
+			expect(globalSettings.isSSLOrigin()).toBe(true);
+			globalSettings.setIsSSLOrigin(false);
+			expect(globalSettings.isSSLOrigin()).toBe(false);
+		});
+	});
+});

package/src/amplify-astro-adapter/globalSettings.ts

@@ -0,0 +1,16 @@
+import type { AstroServer } from './types';
+
+export const globalSettings: AstroServer.GlobalSettings = (() => {
+  let runtimeOptions: AstroServer.RuntimeOptions = {};
+  let serverSideAuthEnabled = true;
+  let sslOrigin = false;
+
+  return {
+    setRuntimeOptions(opts) { runtimeOptions = opts ?? {}; },
+    getRuntimeOptions() { return runtimeOptions; },
+    enableServerSideAuth() { serverSideAuthEnabled = true; },
+    isServerSideAuthEnabled() { return serverSideAuthEnabled; },
+    setIsSSLOrigin(v: boolean) { sslOrigin = v; },
+    isSSLOrigin() { return sslOrigin; },
+  };
+})();

package/src/amplify-astro-adapter/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Amplify Astro Adapter
+ * 
+ * Provides server-side authentication support for Astro with AWS Amplify
+ */
+
+export { createRunWithAmplifyServerContext } from './createRunWithAmplifyServerContext';
+export { createCookieStorageAdapterFromAstroContext } from './createCookieStorageAdapterFromAstroContext';
+export { globalSettings } from './globalSettings';
+export * from './types';
+export * from './errors';
+
+// Re-export logger for convenience
+export { logger, createLogger } from '../utils/logger';

package/src/amplify-astro-adapter/types.ts

@@ -0,0 +1,55 @@
+import type { ResourcesConfig } from 'aws-amplify';
+import type { CookieStorage } from 'aws-amplify/adapter-core';
+
+/**
+ * Amplify configuration structure matching amplify_outputs.json format
+ */
+export type AstroAmplifyConfig = ResourcesConfig;
+
+export namespace AstroServer {
+  export type RuntimeCookieOptions = CookieStorage.SetCookieOptions & {
+    domain?: string;
+  };
+
+  export interface RuntimeOptions {
+    cookies?: RuntimeCookieOptions;
+  }
+
+  export interface AstroComponentContext {
+    cookies: import('astro').AstroGlobal['cookies'];
+    request: Request;
+  }
+
+  export interface APIEndpointContext {
+    cookies: import('astro').APIContext['cookies'];
+    request: Request;
+  }
+
+  export type ServerContext =
+    | AstroComponentContext
+    | APIEndpointContext
+    | null;
+
+  export interface GlobalSettings {
+    setRuntimeOptions(opts: RuntimeOptions): void;
+    getRuntimeOptions(): RuntimeOptions;
+    enableServerSideAuth(): void;
+    isServerSideAuthEnabled(): boolean;
+    setIsSSLOrigin(val: boolean): void;
+    isSSLOrigin(): boolean;
+  }
+
+  export type RunOperationWithContext = <T>(input: {
+    astroServerContext: ServerContext;
+    operation: (contextSpec: unknown) => Promise<T>;
+  }) => Promise<T>;
+
+  export interface CreateServerRunnerInput {
+    config: ResourcesConfig;
+    runtimeOptions?: RuntimeOptions;
+  }
+
+  export interface CreateServerRunnerOutput {
+    runWithAmplifyServerContext: RunOperationWithContext;
+  }
+}

package/src/auth/auth.md

@@ -0,0 +1,178 @@
+# Auth Module
+
+Core authentication functions for server-side and client-side user management with AWS Cognito.
+
+## Installation
+
+```typescript
+import { 
+  getUser, 
+  getClientUser,
+  hasAccessToBrand,
+  hasAccessToAccount,
+  isAdminUser,
+  isSuperAdminUser,
+} from '@htlkg/core/auth';
+```
+
+## User Interface
+
+```typescript
+interface User {
+  username: string;
+  email: string;
+  brandIds: number[];
+  accountIds: number[];
+  isAdmin: boolean;
+  isSuperAdmin: boolean;
+  roles: string[];
+}
+```
+
+## Server-Side Authentication
+
+### getUser
+
+Retrieves the authenticated user from Astro's API context using Cognito cookies.
+
+```typescript
+import type { APIContext } from 'astro';
+import { getUser } from '@htlkg/core/auth';
+
+export async function GET(context: APIContext) {
+  const user = await getUser(context);
+  
+  if (!user) {
+    return new Response('Unauthorized', { status: 401 });
+  }
+  
+  return new Response(JSON.stringify(user));
+}
+```
+
+In Astro pages:
+
+```astro
+---
+import { getUser } from '@htlkg/core/auth';
+
+const user = await getUser(Astro);
+
+if (!user) {
+  return Astro.redirect('/login');
+}
+---
+
+<h1>Welcome, {user.username}</h1>
+```
+
+## Client-Side Authentication
+
+### getClientUser
+
+Retrieves the authenticated user on the client side.
+
+```typescript
+import { getClientUser } from '@htlkg/core/auth';
+
+const user = await getClientUser();
+
+if (user) {
+  console.log(`Logged in as ${user.email}`);
+}
+```
+
+## Access Control Helpers
+
+### hasAccessToBrand
+
+Check if user has access to a specific brand.
+
+```typescript
+import { getUser, hasAccessToBrand } from '@htlkg/core/auth';
+
+const user = await getUser(context);
+const brandId = 123;
+
+if (!hasAccessToBrand(user, brandId)) {
+  return new Response('Forbidden', { status: 403 });
+}
+```
+
+### hasAccessToAccount
+
+Check if user has access to a specific account.
+
+```typescript
+import { getUser, hasAccessToAccount } from '@htlkg/core/auth';
+
+const user = await getUser(context);
+
+if (hasAccessToAccount(user, accountId)) {
+  // User can access this account
+}
+```
+
+### isAdminUser / isSuperAdminUser
+
+Check admin status.
+
+```typescript
+import { getUser, isAdminUser, isSuperAdminUser } from '@htlkg/core/auth';
+
+const user = await getUser(context);
+
+if (isAdminUser(user)) {
+  // User is admin or super admin
+}
+
+if (isSuperAdminUser(user)) {
+  // User is super admin only
+}
+```
+
+## Cognito Groups
+
+The module recognizes these Cognito groups:
+
+| Group | Admin | Super Admin |
+|-------|-------|-------------|
+| `admin` | ✓ | ✗ |
+| `ADMINS` | ✓ | ✗ |
+| `SUPER_ADMINS` | ✓ | ✓ |
+
+## Custom Attributes
+
+User attributes are parsed from Cognito tokens:
+
+- `custom:brand_ids` - Comma-separated brand IDs
+- `custom:account_ids` - Comma-separated account IDs
+- `email` - From ID token
+- `cognito:groups` - User roles/groups
+
+## Error Handling
+
+Authentication errors are logged without exposing sensitive data:
+
+```typescript
+const user = await getUser(context);
+// Returns null on any auth error
+// Errors logged with sanitized messages (tokens masked)
+```
+
+## Middleware Placeholders
+
+These functions are placeholders that should be imported from `@htlkg/astro/middleware`:
+
+```typescript
+// These throw errors if called directly from @htlkg/core
+requireAuth(context, loginUrl);
+requireAdminAccess(context, loginUrl);
+requireBrandAccess(context, brandId, loginUrl);
+```
+
+Import from the correct package:
+
+```typescript
+import { requireAuth } from '@htlkg/astro/middleware';
+```