lambder 1.0.128 → 1.0.129

package/examples/output-type-enforcement-example.ts

@@ -0,0 +1,218 @@
+/**
+ * Output Type Enforcement Example
+ * 
+ * This example demonstrates how Lambder now enforces output types
+ * in addition to input types for type-safe APIs.
+ */
+
+import Lambder from '../src/Lambder.js';
+import type { ApiContract } from '../src/index.js';
+
+// ============================================================================
+// Define Types
+// ============================================================================
+
+type User = {
+    id: string;
+    name: string;
+    email: string;
+    age: number;
+};
+
+type Product = {
+    id: string;
+    name: string;
+    price: number;
+    inStock: boolean;
+};
+
+type Stats = {
+    totalUsers: number;
+    totalProducts: number;
+    revenue: number;
+};
+
+// ============================================================================
+// Define API Contract
+// ============================================================================
+
+type MyApiContract = ApiContract<{
+    // Simple primitive outputs
+    getCount: { input: void, output: number },
+    getMessage: { input: { id: string }, output: string },
+    isActive: { input: void, output: boolean },
+    
+    // Complex object outputs
+    getUser: { input: { userId: string }, output: User },
+    getProduct: { input: { productId: string }, output: Product },
+    
+    // Array outputs
+    listUsers: { input: void, output: User[] },
+    listProducts: { input: { category: string }, output: Product[] },
+    
+    // Complex nested outputs
+    getStats: { input: void, output: Stats },
+    
+    // Nullable outputs
+    findUser: { input: { email: string }, output: User | null },
+}>;
+
+// ============================================================================
+// Setup Backend with Type Enforcement
+// ============================================================================
+
+const lambder = new Lambder<MyApiContract>({
+    publicPath: './public',
+    apiPath: '/api',
+});
+
+// ✅ EXAMPLE 1: Simple primitive outputs are enforced
+lambder.addApi('getCount', async (ctx, resolver) => {
+    const count = 42;
+    return resolver.api(count); // ✅ TypeScript validates this is a number
+});
+
+lambder.addApi('getMessage', async (ctx, resolver) => {
+    const message = `Message for ${ctx.apiPayload.id}`;
+    return resolver.api(message); // ✅ TypeScript validates this is a string
+});
+
+lambder.addApi('isActive', async (ctx, resolver) => {
+    const active = true;
+    return resolver.api(active); // ✅ TypeScript validates this is a boolean
+});
+
+// ✅ EXAMPLE 2: Complex objects must match the shape
+lambder.addApi('getUser', async (ctx, resolver) => {
+    const user: User = {
+        id: ctx.apiPayload.userId,
+        name: "John Doe",
+        email: "john@example.com",
+        age: 30,
+    };
+    return resolver.api(user); // ✅ All required fields are present
+});
+
+lambder.addApi('getProduct', async (ctx, resolver) => {
+    const product: Product = {
+        id: ctx.apiPayload.productId,
+        name: "Widget",
+        price: 99.99,
+        inStock: true,
+    };
+    return resolver.api(product); // ✅ Correct shape
+});
+
+// ✅ EXAMPLE 3: Arrays are type-checked
+lambder.addApi('listUsers', async (ctx, resolver) => {
+    const users: User[] = [
+        { id: "1", name: "Alice", email: "alice@example.com", age: 25 },
+        { id: "2", name: "Bob", email: "bob@example.com", age: 30 },
+    ];
+    return resolver.api(users); // ✅ Array of User objects
+});
+
+lambder.addApi('listProducts', async (ctx, resolver) => {
+    const category = ctx.apiPayload.category;
+    const products: Product[] = [
+        { id: "1", name: "Item 1", price: 10, inStock: true },
+        { id: "2", name: "Item 2", price: 20, inStock: false },
+    ];
+    return resolver.api(products); // ✅ Array of Product objects
+});
+
+// ✅ EXAMPLE 4: Nested objects are validated
+lambder.addApi('getStats', async (ctx, resolver) => {
+    const stats: Stats = {
+        totalUsers: 100,
+        totalProducts: 50,
+        revenue: 10000,
+    };
+    return resolver.api(stats); // ✅ Matches Stats shape
+});
+
+// ✅ EXAMPLE 5: Nullable types work correctly
+lambder.addApi('findUser', async (ctx, resolver) => {
+    const email = ctx.apiPayload.email;
+    
+    if (email === "john@example.com") {
+        // Found user
+        const user: User = {
+            id: "123",
+            name: "John",
+            email: email,
+            age: 30,
+        };
+        return resolver.api(user); // ✅ Can return User
+    } else {
+        // Not found
+        return resolver.api(null); // ✅ Can return null
+    }
+});
+
+// ✅ EXAMPLE 6: Using die.api() also enforces types
+lambder.addApi('getCount', async (ctx, resolver) => {
+    return resolver.die.api(42); // ✅ die.api() also type-checks
+});
+
+// ✅ EXAMPLE 7: Session APIs also enforce output types
+lambder.addSessionApi('getUser', async (ctx, resolver) => {
+    const user: User = {
+        id: ctx.apiPayload.userId,
+        name: "Jane Doe",
+        email: "jane@example.com",
+        age: 28,
+    };
+    return resolver.api(user); // ✅ Type-safe for session APIs too
+});
+
+// ============================================================================
+// What TypeScript Prevents (these would cause compile errors)
+// ============================================================================
+
+/*
+// ❌ ERROR: Wrong primitive type
+lambder.addApi('getCount', async (ctx, resolver) => {
+    return resolver.api("not a number"); // Error: string not assignable to number
+});
+
+// ❌ ERROR: Missing required field
+lambder.addApi('getUser', async (ctx, resolver) => {
+    return resolver.api({
+        id: "123",
+        name: "John",
+        email: "john@example.com",
+        // age is missing! - TypeScript error
+    });
+});
+
+// ❌ ERROR: Wrong field type
+lambder.addApi('getUser', async (ctx, resolver) => {
+    return resolver.api({
+        id: "123",
+        name: "John",
+        email: "john@example.com",
+        age: "30", // Error: string not assignable to number
+    });
+});
+
+// ❌ ERROR: Wrong array element type
+lambder.addApi('listUsers', async (ctx, resolver) => {
+    return resolver.api([
+        { id: "1", name: "Alice", email: "alice@example.com", age: 25 },
+        "not a user object", // Error: string not assignable to User
+    ]);
+});
+
+// ❌ ERROR: Returning wrong type when null is not allowed
+lambder.addApi('getUser', async (ctx, resolver) => {
+    return resolver.api(null); // Error: null not assignable to User (findUser allows null, but getUser doesn't)
+});
+*/
+
+console.log("✅ All examples demonstrate proper output type enforcement!");
+console.log("✅ TypeScript will catch type mismatches at compile time!");
+console.log("✅ This works with both resolver.api() and resolver.die.api()!");
+console.log("✅ Both addApi() and addSessionApi() enforce output types!");
+
+export default lambder;

package/examples/secure-session-example.ts

@@ -0,0 +1,191 @@
+import Lambder from "../src/Lambder.js";
+
+// Example: Secure session handling with all security fixes applied
+
+const lambder = new Lambder({
+    publicPath: "/public",
+    apiPath: "/api",
+    ejsPath: "/views",
+});
+
+// Enable session management with sliding expiration
+lambder.enableDdbSession(
+    {
+        tableName: process.env.SESSION_TABLE || "sessions",
+        tableRegion: process.env.AWS_REGION || "us-east-1",
+        sessionSalt: process.env.SESSION_SALT || "change-this-to-a-secure-random-string",
+        enableSlidingExpiration: true, // Sessions extend on each access
+    },
+    { partitionKey: "pk", sortKey: "sk" }
+);
+
+// Example: Login API with session regeneration
+lambder.addApi("user.login", async (ctx, resolver) => {
+    const { username, password } = ctx.apiPayload;
+
+    // Validate credentials (implement your own logic)
+    const user = await authenticateUser(username, password);
+    if (!user) {
+        return resolver.api({ success: false, error: "Invalid credentials" });
+    }
+
+    // Create new session
+    const sessionController = lambder.getSessionController(ctx);
+    await sessionController.createSession(user.id, {
+        userId: user.id,
+        username: user.username,
+        role: user.role,
+    });
+
+    return resolver.api({
+        success: true,
+        csrfToken: ctx.session?.csrfToken,
+    });
+});
+
+// Example: Protected API that requires session
+lambder.addSessionApi("user.profile", async (ctx, resolver) => {
+    // Session is automatically fetched and validated
+    const sessionData = ctx.session?.data;
+
+    return resolver.api({
+        userId: sessionData.userId,
+        username: sessionData.username,
+        role: sessionData.role,
+    });
+});
+
+// Example: Sensitive operation that regenerates session
+lambder.addSessionApi("user.changePassword", async (ctx, resolver) => {
+    const { oldPassword, newPassword } = ctx.apiPayload;
+    const sessionController = lambder.getSessionController(ctx);
+
+    // Validate old password
+    const isValid = await validatePassword(
+        ctx.session?.data.userId,
+        oldPassword
+    );
+    if (!isValid) {
+        return resolver.api({ success: false, error: "Invalid password" });
+    }
+
+    // Update password
+    await updatePassword(ctx.session?.data.userId, newPassword);
+
+    // IMPORTANT: Regenerate session after password change to prevent session fixation
+    await sessionController.regenerateSession();
+
+    // OPTIONAL: End all other sessions for this user
+    await sessionController.endSessionAll();
+
+    return resolver.api({
+        success: true,
+        message: "Password changed successfully",
+        csrfToken: ctx.session?.csrfToken, // Send new CSRF token
+    });
+});
+
+// Example: Update session data
+lambder.addSessionApi("user.updatePreferences", async (ctx, resolver) => {
+    const { theme, language } = ctx.apiPayload;
+    const sessionController = lambder.getSessionController(ctx);
+
+    // Update session data (also extends expiration if sliding is enabled)
+    await sessionController.updateSessionData({
+        ...ctx.session?.data,
+        preferences: { theme, language },
+    });
+
+    return resolver.api({
+        success: true,
+        message: "Preferences updated",
+    });
+});
+
+// Example: Logout
+lambder.addSessionApi("user.logout", async (ctx, resolver) => {
+    const sessionController = lambder.getSessionController(ctx);
+
+    // End current session
+    await sessionController.endSession();
+
+    return resolver.api({
+        success: true,
+        message: "Logged out successfully",
+    });
+});
+
+// Example: Logout from all devices
+lambder.addSessionApi("user.logoutAll", async (ctx, resolver) => {
+    const sessionController = lambder.getSessionController(ctx);
+
+    // End all sessions for this user (same sessionKey)
+    await sessionController.endSessionAll();
+
+    return resolver.api({
+        success: true,
+        message: "Logged out from all devices",
+    });
+});
+
+// Example: Optional session (check if logged in)
+lambder.addApi("user.checkAuth", async (ctx, resolver) => {
+    const sessionController = lambder.getSessionController(ctx);
+
+    // Try to fetch session without throwing error
+    const session = await sessionController.fetchSessionIfExists();
+
+    if (session) {
+        return resolver.api({
+            authenticated: true,
+            userId: session.data.userId,
+            username: session.data.username,
+        });
+    }
+
+    return resolver.api({
+        authenticated: false,
+    });
+});
+
+// Example: Route with session
+lambder.addSessionRoute("/dashboard", async (ctx, resolver) => {
+    // Session is automatically fetched and validated
+    const userData = ctx.session?.data;
+
+    return resolver.ejsFile("dashboard.ejs", {
+        user: userData,
+        csrfToken: ctx.session?.csrfToken,
+    });
+});
+
+// Example: Route with optional session
+lambder.addRoute("/", async (ctx, resolver) => {
+    const sessionController = lambder.getSessionController(ctx);
+    const session = await sessionController.fetchSessionIfExists();
+
+    return resolver.ejsFile("home.ejs", {
+        isLoggedIn: !!session,
+        user: session?.data,
+        csrfToken: session?.csrfToken,
+    });
+});
+
+// Dummy functions (implement these)
+async function authenticateUser(username: string, password: string) {
+    // Implement your authentication logic
+    return { id: "user123", username, role: "user" };
+}
+
+async function validatePassword(userId: string, password: string) {
+    // Implement password validation
+    return true;
+}
+
+async function updatePassword(userId: string, newPassword: string) {
+    // Implement password update
+}
+
+export const handler = async (event: any, context: any) => {
+    return await lambder.render(event, context);
+};

package/examples/test-output-type-enforcement.ts

@@ -0,0 +1,101 @@
+/**
+ * Test file to verify output type enforcement
+ * This file should have TypeScript errors if output types are not correct
+ */
+
+import Lambder from '../src/Lambder.js';
+import type { ApiContract } from '../src/index.js';
+
+// Define a simple API contract
+type TestContract = ApiContract<{
+    getNumber: { input: void, output: number },
+    getString: { input: { id: string }, output: string },
+    getUser: { input: { userId: string }, output: { id: string; name: string; age: number } },
+}>;
+
+const lambder = new Lambder<TestContract>({
+    publicPath: './public',
+    apiPath: '/api',
+});
+
+// ✅ CORRECT: Returns the right type
+lambder.addApi('getNumber', async (ctx, resolver) => {
+    // This should work - returning number
+    return resolver.api(42);
+});
+
+// ❌ INCORRECT: Should cause TypeScript error - returning wrong type
+lambder.addApi('getNumber', async (ctx, resolver) => {
+    // @ts-expect-error - Testing type enforcement: should not accept string when output is number
+    return resolver.api("wrong type");
+});
+
+// ✅ CORRECT: Returns string
+lambder.addApi('getString', async (ctx, resolver) => {
+    const id = ctx.apiPayload.id;
+    return resolver.api(`String for ${id}`);
+});
+
+// ❌ INCORRECT: Should cause TypeScript error - returning wrong type
+lambder.addApi('getString', async (ctx, resolver) => {
+    // @ts-expect-error - Testing type enforcement: should not accept number when output is string
+    return resolver.api(123);
+});
+
+// ✅ CORRECT: Returns correct object shape
+lambder.addApi('getUser', async (ctx, resolver) => {
+    return resolver.api({
+        id: ctx.apiPayload.userId,
+        name: "John Doe",
+        age: 30,
+    });
+});
+
+// ❌ INCORRECT: Should cause TypeScript error - missing required field
+lambder.addApi('getUser', async (ctx, resolver) => {
+    // @ts-expect-error - Testing type enforcement: missing 'age' field
+    return resolver.api({
+        id: ctx.apiPayload.userId,
+        name: "John Doe",
+        // age is missing
+    });
+});
+
+// ❌ INCORRECT: Should cause TypeScript error - wrong field type
+lambder.addApi('getUser', async (ctx, resolver) => {
+    return resolver.api({
+        id: ctx.apiPayload.userId,
+        name: "John Doe",
+        // @ts-expect-error - Testing type enforcement: age should be number, not string
+        age: "30", // wrong type
+    });
+});
+
+// ✅ CORRECT: Using null is allowed
+lambder.addApi('getNumber', async (ctx, resolver) => {
+    return resolver.api(null);
+});
+
+// ✅ CORRECT: Using resolver.die.api also enforces types
+lambder.addApi('getNumber', async (ctx, resolver) => {
+    return resolver.die.api(42);
+});
+
+// ❌ INCORRECT: resolver.die.api should also enforce types
+lambder.addApi('getNumber', async (ctx, resolver) => {
+    // @ts-expect-error - Testing type enforcement: die.api should also check types
+    return resolver.die.api("wrong type");
+});
+
+// Test with addSessionApi
+lambder.addSessionApi('getString', async (ctx, resolver) => {
+    // Should also enforce output type for session APIs
+    return resolver.api("correct string");
+});
+
+lambder.addSessionApi('getString', async (ctx, resolver) => {
+    // @ts-expect-error - Testing type enforcement: session API should also enforce types
+    return resolver.api(123);
+});
+
+console.log("If this file compiles with @ts-expect-error comments, output type enforcement is working!");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "1.0.128",
+  "version": "1.0.129",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/Lambder.ts

@@ -140,11 +140,11 @@ export default class Lambder<TContract extends ApiContractShape = any> {
     }
 
     enableDdbSession(
-        { tableName, tableRegion, sessionSalt }: { tableName: string; tableRegion: string; sessionSalt: string; }, 
+        { tableName, tableRegion, sessionSalt, enableSlidingExpiration }: { tableName: string; tableRegion: string; sessionSalt: string; enableSlidingExpiration?: boolean; }, 
         { partitionKey, sortKey }: { partitionKey: string, sortKey: string } = { partitionKey: "pk", sortKey: "sk" }
     ){
         this.lambderSessionManager = new LambderSessionManager({
-            tableName, tableRegion, partitionKey, sortKey, sessionSalt
+            tableName, tableRegion, partitionKey, sortKey, sessionSalt, enableSlidingExpiration
         });
     }
 
@@ -249,7 +249,7 @@ export default class Lambder<TContract extends ApiContractShape = any> {
         apiName: TApiName,
         actionFn: (
             ctx: LambderRenderContext<TContract[TApiName]['input']>,
-            resolver: LambderResolver
+            resolver: LambderResolver<TContract, TApiName>
         ) => LambderResolverResponse|Promise<LambderResolverResponse>
     ):void;
     // Overload for untyped API with string (backward compatibility, must be last)
@@ -281,7 +281,7 @@ export default class Lambder<TContract extends ApiContractShape = any> {
         apiName: TApiName,
         actionFn: (
             ctx: LambderRenderContext<TContract[TApiName]['input']>,
-            resolver: LambderResolver
+            resolver: LambderResolver<TContract, TApiName>
         ) => LambderResolverResponse|Promise<LambderResolverResponse>
     ):void;
     // Overload for untyped session API with string (backward compatibility, must be last)

package/src/LambderResolver.ts

@@ -1,28 +1,36 @@
 import type { LambderRenderContext } from "./Lambder.js";
 import LambderResponseBuilder, { LambderResolverResponse } from "./LambderResponseBuilder.js";
 import LambderUtils from "./LambderUtils.js";
+import type { ApiContractShape, ApiOutput } from "./LambderApiContract.js";
 
 type MethodType<T, M extends keyof T> = T[M] extends (...args: any[]) => any ? T[M] : never;
 
-interface DieResolverMethods {
-    raw: MethodType<LambderResponseBuilder, 'raw'>;
-    json: MethodType<LambderResponseBuilder, 'json'>;
-    xml: MethodType<LambderResponseBuilder, 'xml'>;
-    html: MethodType<LambderResponseBuilder, 'html'>;
-    status301: MethodType<LambderResponseBuilder, 'status301'>;
-    status404: MethodType<LambderResponseBuilder, 'status404'>;
-    cors: MethodType<LambderResponseBuilder, 'cors'>;
-    fileBase64: MethodType<LambderResponseBuilder, 'fileBase64'>;
-    file: MethodType<LambderResponseBuilder, 'file'>;
-    ejsFile: MethodType<LambderResponseBuilder, 'ejsFile'>;
-    ejsTemplate: MethodType<LambderResponseBuilder, 'ejsTemplate'>;
-    api: MethodType<LambderResponseBuilder, 'api'>;
+interface DieResolverMethods<TContract extends ApiContractShape, TApiName extends keyof TContract & string> {
+    raw: MethodType<LambderResponseBuilder<TContract>, 'raw'>;
+    json: MethodType<LambderResponseBuilder<TContract>, 'json'>;
+    xml: MethodType<LambderResponseBuilder<TContract>, 'xml'>;
+    html: MethodType<LambderResponseBuilder<TContract>, 'html'>;
+    status301: MethodType<LambderResponseBuilder<TContract>, 'status301'>;
+    status404: MethodType<LambderResponseBuilder<TContract>, 'status404'>;
+    cors: MethodType<LambderResponseBuilder<TContract>, 'cors'>;
+    fileBase64: MethodType<LambderResponseBuilder<TContract>, 'fileBase64'>;
+    file: MethodType<LambderResponseBuilder<TContract>, 'file'>;
+    ejsFile: MethodType<LambderResponseBuilder<TContract>, 'ejsFile'>;
+    ejsTemplate: MethodType<LambderResponseBuilder<TContract>, 'ejsTemplate'>;
+    api: (
+        payload: ApiOutput<TContract, TApiName> | null,
+        config?: Parameters<LambderResponseBuilder<TContract>['api']>[1],
+        headers?: Parameters<LambderResponseBuilder<TContract>['api']>[2]
+    ) => LambderResolverResponse;
 }
 
-export default class LambderResolver extends LambderResponseBuilder {
+export default class LambderResolver<
+    TContract extends ApiContractShape = any,
+    TApiName extends keyof TContract & string = any
+> extends LambderResponseBuilder<TContract> {
     public resolve: (response: LambderResolverResponse) => void;
     public reject: (err: Error) => void;
-    public die: DieResolverMethods;
+    public die: DieResolverMethods<TContract, TApiName>;
 
     constructor(
         { isCorsEnabled, publicPath, apiVersion, lambderUtils, ctx, resolve, reject }: 
@@ -56,6 +64,15 @@ export default class LambderResolver extends LambderResponseBuilder {
         };
     }
 
+    // Override api method with proper typing
+    api(
+        payload: ApiOutput<TContract, TApiName> | null,
+        config?: Parameters<LambderResponseBuilder<TContract>['api']>[1],
+        headers?: Parameters<LambderResponseBuilder<TContract>['api']>[2]
+    ): LambderResolverResponse {
+        return super.api(payload, config, headers);
+    }
+
     private autoResolve<
         T extends (...args: any[]) => LambderResolverResponse
     >(method: T): (...funcArgs: Parameters<T>) => LambderResolverResponse {

package/src/LambderResponseBuilder.ts

@@ -4,6 +4,7 @@ import ejs from "ejs";
 import mimeTypeResolver from "mime-types";
 import LambderUtils from "./LambderUtils.js";
 import { LambderRenderContext } from "./Lambder.js";
+import type { ApiContractShape } from "./LambderApiContract.js";
 
 const convertToMultiHeader = (
     headers: Record<string, string|string[]> | undefined
@@ -38,7 +39,7 @@ export type LambderApiResponse<T> = LambderApiResponseConfig & {
     payload?: T | null; 
 }
 
-export default class LambderResponseBuilder {
+export default class LambderResponseBuilder<TContract extends ApiContractShape = any> {
     private isCorsEnabled: boolean;
     private publicPath: string;
     private apiVersion: string|null;

package/src/LambderSessionController.ts

@@ -48,6 +48,15 @@ export default class LambderSessionController {
         return this.ctx.session;
     };
 
+    async regenerateSession (): Promise<LambderSessionContext> {
+        if(!this.ctx.session) throw new Error("Session not found.");
+        const newSession = await this.lambderSessionManager.regenerateSession(this.ctx.session);
+        this.ctx._otherInternal.addHeaderFnAccumulator.push({ key: "Set-Cookie", value: `${this.sessionTokenCookieKey}=${newSession.sessionToken}; Expires=${new Date(newSession.expiresAt * 1000).toUTCString()}; Path=/; HttpOnly; SameSite=Lax; Secure` });
+        this.ctx._otherInternal.addHeaderFnAccumulator.push({ key: "Set-Cookie", value: `${this.sessionCsrfCookieKey}=${newSession.csrfToken}; Expires=${new Date(newSession.expiresAt * 1000).toUTCString()}; Path=/; SameSite=Lax; Secure` });
+        this.ctx.session = newSession;
+        return this.ctx.session;
+    };
+
     async fetchSession (): Promise<LambderSessionContext>{
         if(!this.areRequestSessionTokensValid()){ throw new Error("Session tokens are invalid"); }