@htlkg/core 0.0.2 → 0.0.3

package/package.json

@@ -1,17 +1,39 @@
 {
   "name": "@htlkg/core",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "type": "module",
   "exports": {
-    ".": "./dist/index.js",
-    "./auth": "./dist/auth/index.js",
-    "./types": "./dist/types/index.js",
-    "./utils": "./dist/utils/index.js",
-    "./constants": "./dist/constants/index.js",
-    "./errors": "./dist/errors/index.js",
-    "./amplify-astro-adapter": "./dist/amplify-astro-adapter/index.js"
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./auth": {
+      "import": "./dist/auth/index.js",
+      "types": "./dist/auth/index.d.ts"
+    },
+    "./types": {
+      "import": "./dist/types/index.js",
+      "types": "./dist/types/index.d.ts"
+    },
+    "./utils": {
+      "import": "./dist/utils/index.js",
+      "types": "./dist/utils/index.d.ts"
+    },
+    "./constants": {
+      "import": "./dist/constants/index.js",
+      "types": "./dist/constants/index.d.ts"
+    },
+    "./errors": {
+      "import": "./dist/errors/index.js",
+      "types": "./dist/errors/index.d.ts"
+    },
+    "./amplify-astro-adapter": {
+      "import": "./dist/amplify-astro-adapter/index.js",
+      "types": "./dist/amplify-astro-adapter/index.d.ts"
+    }
   },
   "files": [
+    "src",
     "dist"
   ],
   "dependencies": {

package/src/amplify-astro-adapter/amplify-astro-adapter.md

@@ -0,0 +1,167 @@
+# Amplify Astro Adapter
+
+Server-side authentication support for Astro applications using AWS Amplify. Handles cookie-based authentication context for SSR.
+
+## Installation
+
+```typescript
+import { 
+  createRunWithAmplifyServerContext,
+  createCookieStorageAdapterFromAstroContext,
+  globalSettings 
+} from '@htlkg/core/amplify-astro-adapter';
+```
+
+## Core Functions
+
+### createRunWithAmplifyServerContext
+
+Creates a function that runs operations within an authenticated Amplify server context.
+
+```typescript
+import { Amplify } from 'aws-amplify';
+import { createRunWithAmplifyServerContext, globalSettings } from '@htlkg/core/amplify-astro-adapter';
+
+const amplifyConfig = Amplify.getConfig();
+
+const runWithAmplifyServerContext = createRunWithAmplifyServerContext({
+  config: amplifyConfig,
+  globalSettings, // Pass explicitly to avoid module singleton issues
+});
+
+// Use in Astro page or API route
+const result = await runWithAmplifyServerContext({
+  astroServerContext: {
+    cookies: Astro.cookies,
+    request: Astro.request,
+  },
+  operation: async (contextSpec) => {
+    // Perform authenticated operations
+    const user = await getCurrentUser(contextSpec);
+    return user;
+  },
+});
+```
+
+### createCookieStorageAdapterFromAstroContext
+
+Creates a cookie storage adapter compatible with Amplify's auth system.
+
+```typescript
+import { createCookieStorageAdapterFromAstroContext } from '@htlkg/core/amplify-astro-adapter';
+
+const cookieAdapter = await createCookieStorageAdapterFromAstroContext({
+  cookies: Astro.cookies,
+  request: Astro.request,
+});
+
+// Adapter methods
+cookieAdapter.get('cookie-name');
+cookieAdapter.getAll();
+cookieAdapter.set('name', 'value', options);
+cookieAdapter.delete('name');
+```
+
+### globalSettings
+
+Runtime configuration for the adapter.
+
+```typescript
+import { globalSettings } from '@htlkg/core/amplify-astro-adapter';
+
+// Enable server-side auth (enabled by default)
+globalSettings.enableServerSideAuth();
+
+// Check if SSL origin (affects secure cookie flag)
+globalSettings.setIsSSLOrigin(true);
+
+// Set custom cookie options
+globalSettings.setRuntimeOptions({
+  cookies: {
+    domain: '.example.com',
+    sameSite: 'lax',
+  },
+});
+```
+
+## Error Handling
+
+The adapter provides specific error classes for different failure scenarios:
+
+```typescript
+import { 
+  AmplifyAstroAdapterError,
+  ErrorCodes,
+  createAuthFailedError,
+  createCookieError,
+  createConfigMissingError,
+} from '@htlkg/core/amplify-astro-adapter';
+
+try {
+  // ... adapter operations
+} catch (error) {
+  if (error instanceof AmplifyAstroAdapterError) {
+    console.error(`[${error.code}] ${error.message}`);
+    if (error.recoverySuggestion) {
+      console.log('Suggestion:', error.recoverySuggestion);
+    }
+  }
+}
+```
+
+### Error Codes
+
+| Code | Description |
+|------|-------------|
+| `CONFIG_MISSING` | Amplify configuration not found |
+| `AUTH_FAILED` | Authentication failed |
+| `COOKIE_ERROR` | Cookie read/write error |
+| `GRAPHQL_ERROR` | GraphQL operation failed |
+| `CONTEXT_CREATION_FAILED` | Server context creation failed |
+| `TOKEN_REFRESH_FAILED` | Token refresh failed |
+
+## Types
+
+```typescript
+import type { AstroServer, AstroAmplifyConfig } from '@htlkg/core/amplify-astro-adapter';
+
+// Server context types
+type ServerContext = AstroServer.AstroComponentContext | AstroServer.APIEndpointContext | null;
+
+// Runtime options
+interface RuntimeOptions {
+  cookies?: RuntimeCookieOptions;
+}
+
+// Run operation signature
+type RunOperationWithContext = <T>(input: {
+  astroServerContext: ServerContext;
+  operation: (contextSpec: unknown) => Promise<T>;
+}) => Promise<T>;
+```
+
+## Cookie Handling
+
+The adapter handles Cognito authentication cookies with:
+
+- Automatic encoding compatible with js-cookie
+- Secure defaults (`httpOnly`, `sameSite: 'lax'`, `secure` based on SSL)
+- Support for both Astro component and API endpoint contexts
+
+## Debug Logging
+
+Enable debug logs by setting environment variables:
+
+```bash
+DEBUG=true
+# or
+HTLKG_DEBUG=true
+```
+
+```typescript
+import { createLogger } from '@htlkg/core/amplify-astro-adapter';
+
+const log = createLogger('my-module');
+log.debug('Debug message'); // Only shown when DEBUG=true
+log.info('Info message');   // Always shown
+```

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

@@ -0,0 +1,296 @@
+import { describe, it, expect, vi } from "vitest";
+import { createCookieStorageAdapterFromAstroContext } from "./createCookieStorageAdapterFromAstroContext";
+import type { AstroServer } from "./types";
+
+describe("createCookieStorageAdapterFromAstroContext", () => {
+	describe("with null context", () => {
+		it("should return a no-op adapter", async () => {
+			const adapter = await createCookieStorageAdapterFromAstroContext(null as any);
+
+			expect(adapter.get("test")).toBeUndefined();
+			expect(adapter.getAll()).toEqual([]);
+			
+			// These should not throw
+			adapter.set("test", "value");
+			adapter.delete("test");
+		});
+	});
+
+	describe("with valid context", () => {
+		it("should get cookie from Astro cookies", async () => {
+			const mockCookies = {
+				get: vi.fn((name: string) => ({ name, value: "cookie-value" })),
+				set: vi.fn(),
+				delete: vi.fn(),
+			};
+
+			const mockRequest = new Request("https://example.com", {
+				headers: { cookie: "" },
+			});
+
+			const context: AstroServer.ServerContext = {
+				cookies: mockCookies as any,
+				request: mockRequest,
+			};
+
+			const adapter = await createCookieStorageAdapterFromAstroContext(context);
+			const result = adapter.get("test");
+
+			expect(result).toEqual({ name: "test", value: "cookie-value" });
+			expect(mockCookies.get).toHaveBeenCalledWith("test");
+		});
+
+		it("should get cookie from request headers if not in Astro cookies", async () => {
+			// When cookies.get returns an object without value property, it falls back to headers
+			const mockCookies = {
+				get: vi.fn(() => ({ value: undefined })),
+				set: vi.fn(),
+				delete: vi.fn(),
+			};
+
+			const mockRequest = new Request("https://example.com", {
+				headers: { cookie: "test=header-value; other=value2" },
+			});
+
+			const context: AstroServer.ServerContext = {
+				cookies: mockCookies as any,
+				request: mockRequest,
+			};
+
+			const adapter = await createCookieStorageAdapterFromAstroContext(context);
+			const result = adapter.get("test");
+
+			expect(result).toEqual({ name: "test", value: "header-value" });
+		});
+
+		it("should handle URL-encoded cookie values", async () => {
+			const mockCookies = {
+				get: vi.fn(() => ({ value: undefined })),
+				set: vi.fn(),
+				delete: vi.fn(),
+			};
+
+			const mockRequest = new Request("https://example.com", {
+				headers: { cookie: "test=hello%20world" },
+			});
+
+			const context: AstroServer.ServerContext = {
+				cookies: mockCookies as any,
+				request: mockRequest,
+			};
+
+			const adapter = await createCookieStorageAdapterFromAstroContext(context);
+			const result = adapter.get("test");
+
+			expect(result).toEqual({ name: "test", value: "hello world" });
+		});
+
+		it("should get all cookies from getAll method", async () => {
+			const mockCookies = {
+				get: vi.fn(),
+				getAll: vi.fn(() => [
+					{ name: "cookie1", value: "value1" },
+					{ name: "cookie2", value: "value2" },
+				]),
+				set: vi.fn(),
+				delete: vi.fn(),
+			};
+
+			const mockRequest = new Request("https://example.com", {
+				headers: { cookie: "" },
+			});
+
+			const context: AstroServer.ServerContext = {
+				cookies: mockCookies as any,
+				request: mockRequest,
+			};
+
+			const adapter = await createCookieStorageAdapterFromAstroContext(context);
+			const result = adapter.getAll();
+
+			expect(result).toEqual([
+				{ name: "cookie1", value: "value1" },
+				{ name: "cookie2", value: "value2" },
+			]);
+		});
+
+		it("should get all cookies from headers when getAll is not available", async () => {
+			const mockCookies = {
+				get: vi.fn(),
+				set: vi.fn(),
+				delete: vi.fn(),
+				// No getAll method
+			};
+
+			const mockRequest = new Request("https://example.com", {
+				headers: { cookie: "cookie1=value1; cookie2=value2" },
+			});
+
+			const context: AstroServer.ServerContext = {
+				cookies: mockCookies as any,
+				request: mockRequest,
+			};
+
+			const adapter = await createCookieStorageAdapterFromAstroContext(context);
+			const result = adapter.getAll();
+
+			expect(result).toEqual([
+				{ name: "cookie1", value: "value1" },
+				{ name: "cookie2", value: "value2" },
+			]);
+		});
+
+		it("should set cookie with options", async () => {
+			const mockCookies = {
+				get: vi.fn(),
+				set: vi.fn(),
+				delete: vi.fn(),
+			};
+
+			const mockRequest = new Request("https://example.com", {
+				headers: { cookie: "" },
+			});
+
+			const context: AstroServer.ServerContext = {
+				cookies: mockCookies as any,
+				request: mockRequest,
+			};
+
+			const adapter = await createCookieStorageAdapterFromAstroContext(context);
+			adapter.set("test", "value", {
+				httpOnly: true,
+				secure: true,
+				sameSite: "lax",
+			});
+
+			expect(mockCookies.set).toHaveBeenCalledWith("test", "value", {
+				httpOnly: true,
+				secure: true,
+				sameSite: "lax",
+			});
+		});
+
+		it("should map sameSite boolean values", async () => {
+			const mockCookies = {
+				get: vi.fn(),
+				set: vi.fn(),
+				delete: vi.fn(),
+			};
+
+			const mockRequest = new Request("https://example.com", {
+				headers: { cookie: "" },
+			});
+
+			const context: AstroServer.ServerContext = {
+				cookies: mockCookies as any,
+				request: mockRequest,
+			};
+
+			const adapter = await createCookieStorageAdapterFromAstroContext(context);
+			
+			// sameSite: true -> 'strict'
+			adapter.set("test1", "value1", { sameSite: true as any });
+			expect(mockCookies.set).toHaveBeenCalledWith("test1", "value1", {
+				sameSite: "strict",
+			});
+
+			// sameSite: false -> 'lax'
+			adapter.set("test2", "value2", { sameSite: false as any });
+			expect(mockCookies.set).toHaveBeenCalledWith("test2", "value2", {
+				sameSite: "lax",
+			});
+		});
+
+		it("should delete cookie", async () => {
+			const mockCookies = {
+				get: vi.fn(),
+				set: vi.fn(),
+				delete: vi.fn(),
+			};
+
+			const mockRequest = new Request("https://example.com", {
+				headers: { cookie: "" },
+			});
+
+			const context: AstroServer.ServerContext = {
+				cookies: mockCookies as any,
+				request: mockRequest,
+			};
+
+			const adapter = await createCookieStorageAdapterFromAstroContext(context);
+			adapter.delete("test");
+
+			expect(mockCookies.delete).toHaveBeenCalledWith("test");
+		});
+
+		it("should handle errors gracefully when setting cookies", async () => {
+			const mockCookies = {
+				get: vi.fn(),
+				set: vi.fn(() => {
+					throw new Error("Cookie error");
+				}),
+				delete: vi.fn(),
+			};
+
+			const mockRequest = new Request("https://example.com", {
+				headers: { cookie: "" },
+			});
+
+			const context: AstroServer.ServerContext = {
+				cookies: mockCookies as any,
+				request: mockRequest,
+			};
+
+			const adapter = await createCookieStorageAdapterFromAstroContext(context);
+			
+			// Should not throw
+			expect(() => adapter.set("test", "value")).not.toThrow();
+		});
+
+		it("should handle errors gracefully when deleting cookies", async () => {
+			const mockCookies = {
+				get: vi.fn(),
+				set: vi.fn(),
+				delete: vi.fn(() => {
+					throw new Error("Delete error");
+				}),
+			};
+
+			const mockRequest = new Request("https://example.com", {
+				headers: { cookie: "" },
+			});
+
+			const context: AstroServer.ServerContext = {
+				cookies: mockCookies as any,
+				request: mockRequest,
+			};
+
+			const adapter = await createCookieStorageAdapterFromAstroContext(context);
+			
+			// Should not throw
+			expect(() => adapter.delete("test")).not.toThrow();
+		});
+
+		it("should return undefined when cookie not found anywhere", async () => {
+			const mockCookies = {
+				get: vi.fn(() => ({ value: undefined })),
+				set: vi.fn(),
+				delete: vi.fn(),
+			};
+
+			const mockRequest = new Request("https://example.com", {
+				headers: { cookie: "" },
+			});
+
+			const context: AstroServer.ServerContext = {
+				cookies: mockCookies as any,
+				request: mockRequest,
+			};
+
+			const adapter = await createCookieStorageAdapterFromAstroContext(context);
+			const result = adapter.get("nonexistent");
+
+			expect(result).toBeUndefined();
+		});
+	});
+});

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

@@ -0,0 +1,97 @@
+import type { CookieStorage } from 'aws-amplify/adapter-core';
+import type { AstroServer } from './types';
+import { createLogger } from '../utils/logger';
+
+const log = createLogger('cookie-storage-adapter');
+
+// Ensures the cookie names are encoded in order to look up the cookie store
+// that is manipulated by js-cookie on the client side.
+// Details of the js-cookie encoding behavior see:
+// https://github.com/js-cookie/js-cookie#encoding
+// The implementation is borrowed from js-cookie without escaping `[()]` as
+// we are not using those chars in the auth keys.
+function ensureEncodedForJSCookie(name: string): string {
+  return encodeURIComponent(name).replace(/%(2[346B]|5E|60|7C)/g, decodeURIComponent);
+}
+
+function parseCookieHeader(cookieHeader: string | null) {
+  const out: Record<string, string> = {};
+  if (!cookieHeader) return out;
+  for (const part of cookieHeader.split(';')) {
+    const [rawName, ...rest] = part.trim().split('=');
+    const name = decodeURIComponent(rawName || '');
+    const value = decodeURIComponent(rest.join('=') || '');
+    if (name) out[name] = value;
+  }
+  return out;
+}
+
+function mapSameSite(
+  s: CookieStorage.SetCookieOptions['sameSite']
+): 'lax' | 'strict' | 'none' | undefined {
+  if (s === true) return 'strict';
+  if (s === false) return 'lax';
+  if (s === 'lax' || s === 'strict' || s === 'none') return s;
+  return undefined;
+}
+
+export async function createCookieStorageAdapterFromAstroContext(
+  astroServerContext: AstroServer.ServerContext
+): Promise<CookieStorage.Adapter> {
+  if (astroServerContext === null) {
+    log.debug('Context is null, returning no-op adapter');
+    return {
+      get: () => undefined,
+      getAll: () => [],
+      set: () => {},
+      delete: () => {},
+    };
+  }
+
+  const { cookies, request } = astroServerContext;
+  const cookieHeader = request?.headers?.get('cookie');
+  const headerCookies = parseCookieHeader(cookieHeader ?? null);
+
+  // Debug: Log available cookies (names only for security)
+  const cookieNames = Object.keys(headerCookies);
+  const cognitoCookies = cookieNames.filter(name => name.includes('CognitoIdentityServiceProvider'));
+  log.debug('Available cookies:', cookieNames.length);
+  log.debug('Cognito cookies found:', cognitoCookies.length);
+  if (cognitoCookies.length > 0) {
+    log.debug('Cognito cookie names:', cognitoCookies);
+  }
+
+  const adapter: CookieStorage.Adapter = {
+    get(name) {
+      const encodedName = ensureEncodedForJSCookie(name);
+      const v = cookies?.get(encodedName)?.value ?? headerCookies[encodedName] ?? headerCookies[name];
+      // Debug: Log token lookups (only for auth-related cookies)
+      if (name.includes('accessToken') || name.includes('idToken') || name.includes('refreshToken') || name.includes('LastAuthUser')) {
+        log.debug(`get('${name}'): ${v ? 'FOUND' : 'NOT FOUND'}`);
+      }
+      return v ? { name, value: v } : undefined;
+    },
+    getAll() {
+      const fromAPI =
+        (typeof (cookies as any)?.getAll === 'function'
+          ? (cookies as any).getAll().map((c: any) => ({ name: c.name, value: c.value }))
+          : Object.entries(headerCookies).map(([name, value]) => ({ name, value })));
+      return fromAPI;
+    },
+    set(name, value, options) {
+      try {
+        (cookies as any).set(name, value, {
+          ...(options ?? {}),
+          sameSite: mapSameSite(options?.sameSite),
+        });
+      } catch {}
+    },
+    delete(name: string) {
+      try {
+        (cookies as any).delete(name);
+      } catch {}
+    },
+  };
+
+  return adapter;
+}

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

@@ -0,0 +1,84 @@
+import type { ResourcesConfig } from 'aws-amplify';
+import { sharedInMemoryStorage } from 'aws-amplify/utils';
+import {
+  createAWSCredentialsAndIdentityIdProvider,
+  createKeyValueStorageFromCookieStorageAdapter,
+  createUserPoolsTokenProvider,
+  runWithAmplifyServerContext as coreRunWithContext,
+} from 'aws-amplify/adapter-core';
+
+import type { AstroServer } from './types';
+import { globalSettings as defaultGlobalSettings } from './globalSettings';
+import { createCookieStorageAdapterFromAstroContext } from './createCookieStorageAdapterFromAstroContext';
+import { createLogger } from '../utils/logger';
+
+const log = createLogger('amplify-server-context');
+
+/**
+ * Creates a function that runs operations within the Amplify server context.
+ *
+ * IMPORTANT: Pass globalSettings explicitly to avoid module singleton issues
+ * when using linked packages or different bundling contexts.
+ */
+export const createRunWithAmplifyServerContext = ({
+  config: resourcesConfig,
+  globalSettings = defaultGlobalSettings,
+}: {
+  config: ResourcesConfig;
+  globalSettings?: AstroServer.GlobalSettings;
+}): AstroServer.RunOperationWithContext => {
+  const isServerSideAuthEnabled = globalSettings.isServerSideAuthEnabled();
+  const isSSLOrigin = globalSettings.isSSLOrigin();
+  const setCookieOptions = globalSettings.getRuntimeOptions().cookies ?? {};
+
+  log.debug('Settings:', {
+    isServerSideAuthEnabled,
+    isSSLOrigin,
+    hasCookieOptions: Object.keys(setCookieOptions).length > 0,
+  });
+  
+  const mergedSetCookieOptions = {
+    ...(isServerSideAuthEnabled && { httpOnly: true, sameSite: 'lax' as const }),
+    ...setCookieOptions,
+    ...(isServerSideAuthEnabled && { secure: isSSLOrigin }),
+    path: '/',
+  };
+
+  const runWithContext: AstroServer.RunOperationWithContext = async ({
+    astroServerContext,
+    operation,
+  }) => {
+    if (resourcesConfig.Auth) {
+      const cookieAdapter = await createCookieStorageAdapterFromAstroContext(astroServerContext);
+      
+      const keyValueStorage =
+        astroServerContext === null
+          ? sharedInMemoryStorage
+          : createKeyValueStorageFromCookieStorageAdapter(
+              cookieAdapter,
+              undefined,
+              mergedSetCookieOptions
+            );
+
+      const credentialsProvider = createAWSCredentialsAndIdentityIdProvider(
+        resourcesConfig.Auth,
+        keyValueStorage
+      );
+      
+      const tokenProvider = createUserPoolsTokenProvider(
+        resourcesConfig.Auth,
+        keyValueStorage
+      );
+
+      return coreRunWithContext(
+        resourcesConfig,
+        { Auth: { credentialsProvider, tokenProvider } },
+        operation
+      );
+    }
+
+    return coreRunWithContext(resourcesConfig, {}, operation);
+  };
+
+  return runWithContext;
+};