effortless-aws 0.33.0 → 0.33.1

package/dist/{chunk-HGSMOO4A.js → chunk-6HFS224S.js}

@@ -233,9 +233,6 @@ var createTableClient = (tableName, options) => {
   };
 };
 
-// src/handlers/auth.ts
-import * as crypto from "crypto";
-
 // src/handlers/handler-options.ts
 var toSeconds = (d) => {
   if (typeof d === "number") return d;
@@ -250,10 +247,35 @@ var toSeconds = (d) => {
 };
 
 // src/handlers/auth.ts
+import * as crypto from "crypto";
+var cfBase64Encode = (buffer) => buffer.toString("base64").replace(/\+/g, "-").replace(/=/g, "_").replace(/\//g, "~");
+var signCfCookies = (policy, config) => {
+  const ttlSeconds = toSeconds(policy.ttl);
+  const expireTime = Math.floor(Date.now() / 1e3) + ttlSeconds;
+  const resource = config.domain === "*" ? `https://*${policy.path}` : `https://${config.domain}${policy.path}`;
+  const policyJson = JSON.stringify({
+    Statement: [{
+      Resource: resource,
+      Condition: {
+        DateLessThan: { "AWS:EpochTime": expireTime }
+      }
+    }]
+  });
+  const policyBase64 = cfBase64Encode(Buffer.from(policyJson, "utf-8"));
+  const signature = cfBase64Encode(
+    crypto.sign("sha1", Buffer.from(policyJson, "utf-8"), config.privateKey)
+  );
+  const cookieAttrs = `; Secure; SameSite=Lax; Path=/; Max-Age=${ttlSeconds}`;
+  return [
+    `CloudFront-Policy=${policyBase64}${cookieAttrs}`,
+    `CloudFront-Signature=${signature}${cookieAttrs}`,
+    `CloudFront-Key-Pair-Id=${config.keyPairId}${cookieAttrs}`
+  ];
+};
 var AUTH_COOKIE_NAME = "__eff_session";
-var createAuthRuntime = (secret, defaultExpiresIn, apiTokenVerify, apiTokenHeader, apiTokenCacheTtlSeconds) => {
+var createAuthRuntime = (secret, defaultExpiresIn, apiTokenVerify, apiTokenHeader, apiTokenCacheTtlSeconds, cfSigningConfig) => {
   const tokenCache = apiTokenCacheTtlSeconds ? /* @__PURE__ */ new Map() : void 0;
-  const sign = (payload) => crypto.createHmac("sha256", secret).update(payload).digest("base64url");
+  const sign2 = (payload) => crypto.createHmac("sha256", secret).update(payload).digest("base64url");
   const cookieBase = `${AUTH_COOKIE_NAME}=`;
   const cookieAttrs = "; HttpOnly; Secure; SameSite=Lax; Path=/";
   const decodeSession = (cookieValue) => {
@@ -262,7 +284,7 @@ var createAuthRuntime = (secret, defaultExpiresIn, apiTokenVerify, apiTokenHeade
     if (dot === -1) return void 0;
     const payload = cookieValue.slice(0, dot);
     const sig = cookieValue.slice(dot + 1);
-    if (sign(payload) !== sig) return void 0;
+    if (sign2(payload) !== sig) return void 0;
     try {
       const parsed = JSON.parse(Buffer.from(payload, "base64url").toString("utf-8"));
       if (parsed.exp <= Math.floor(Date.now() / 1e3)) return void 0;
@@ -284,13 +306,16 @@ var createAuthRuntime = (secret, defaultExpiresIn, apiTokenVerify, apiTokenHeade
       const seconds = options?.expiresIn ? toSeconds(options.expiresIn) : defaultExpiresIn;
       const exp = Math.floor(Date.now() / 1e3) + seconds;
       const payload = Buffer.from(JSON.stringify({ exp, ...data }), "utf-8").toString("base64url");
-      const sig = sign(payload);
+      const sig = sign2(payload);
+      const sessionCookie = `${cookieBase}${payload}.${sig}${cookieAttrs}; Max-Age=${seconds}`;
+      const cfCookies = options?.cdnPolicy && cfSigningConfig ? signCfCookies(options.cdnPolicy, cfSigningConfig) : void 0;
       return {
         status: 200,
         body: { ok: true },
         headers: {
-          "set-cookie": `${cookieBase}${payload}.${sig}${cookieAttrs}; Max-Age=${seconds}`
-        }
+          "set-cookie": sessionCookie
+        },
+        ...cfCookies ? { cookies: [sessionCookie, ...cfCookies] } : {}
       };
     },
     clearSession() {
@@ -327,34 +352,91 @@ var createAuthRuntime = (secret, defaultExpiresIn, apiTokenVerify, apiTokenHeade
 
 // src/runtime/bucket-client.ts
 import { S3 } from "@aws-sdk/client-s3";
-var createBucketClient = (bucketName) => {
-  let client2 = null;
-  const getClient2 = () => client2 ??= new S3({});
+var createBucketMethods = (getClient2, bucketName) => ({
+  bucketName,
+  async put(key, body, options) {
+    await getClient2().putObject({
+      Bucket: bucketName,
+      Key: key,
+      Body: typeof body === "string" ? Buffer.from(body) : body,
+      ...options?.contentType ? { ContentType: options.contentType } : {}
+    });
+  },
+  async get(key) {
+    try {
+      const result = await getClient2().getObject({
+        Bucket: bucketName,
+        Key: key
+      });
+      const chunks = [];
+      const stream = result.Body;
+      for await (const chunk of stream) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      }
+      return {
+        body: Buffer.concat(chunks),
+        contentType: result.ContentType
+      };
+    } catch (error) {
+      if (error instanceof Error && (error.name === "NoSuchKey" || error.$metadata?.httpStatusCode === 404)) {
+        return void 0;
+      }
+      throw error;
+    }
+  },
+  async delete(key) {
+    await getClient2().deleteObject({
+      Bucket: bucketName,
+      Key: key
+    });
+  },
+  async list(prefix) {
+    const items = [];
+    let continuationToken;
+    do {
+      const result = await getClient2().listObjectsV2({
+        Bucket: bucketName,
+        ...prefix ? { Prefix: prefix } : {},
+        ...continuationToken ? { ContinuationToken: continuationToken } : {}
+      });
+      for (const obj of result.Contents ?? []) {
+        if (obj.Key) {
+          items.push({
+            key: obj.Key,
+            size: obj.Size ?? 0,
+            lastModified: obj.LastModified
+          });
+        }
+      }
+      continuationToken = result.IsTruncated ? result.NextContinuationToken : void 0;
+    } while (continuationToken);
+    return items;
+  }
+});
+var createEntityClient = (getClient2, bucketName, entityName, cacheSeconds) => {
+  const entityKey = (id) => `${entityName}/${id}.json`;
   return {
-    bucketName,
-    async put(key, body, options) {
+    async put(id, data) {
       await getClient2().putObject({
         Bucket: bucketName,
-        Key: key,
-        Body: typeof body === "string" ? Buffer.from(body) : body,
-        ...options?.contentType ? { ContentType: options.contentType } : {}
+        Key: entityKey(id),
+        Body: JSON.stringify(data),
+        ContentType: "application/json",
+        ...cacheSeconds != null ? { CacheControl: `public, max-age=${cacheSeconds}` } : {}
       });
     },
-    async get(key) {
+    async get(id) {
       try {
         const result = await getClient2().getObject({
           Bucket: bucketName,
-          Key: key
+          Key: entityKey(id)
         });
         const chunks = [];
         const stream = result.Body;
         for await (const chunk of stream) {
           chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
         }
-        return {
-          body: Buffer.concat(chunks),
-          contentType: result.ContentType
-        };
+        return JSON.parse(Buffer.concat(chunks).toString("utf-8"));
       } catch (error) {
         if (error instanceof Error && (error.name === "NoSuchKey" || error.$metadata?.httpStatusCode === 404)) {
           return void 0;
@@ -362,28 +444,37 @@ var createBucketClient = (bucketName) => {
         throw error;
       }
     },
-    async delete(key) {
+    async delete(id) {
       await getClient2().deleteObject({
         Bucket: bucketName,
-        Key: key
+        Key: entityKey(id)
       });
     },
-    async list(prefix) {
+    async list() {
       const items = [];
       let continuationToken;
+      const prefix = `${entityName}/`;
       do {
         const result = await getClient2().listObjectsV2({
           Bucket: bucketName,
-          ...prefix ? { Prefix: prefix } : {},
+          Prefix: prefix,
           ...continuationToken ? { ContinuationToken: continuationToken } : {}
         });
         for (const obj of result.Contents ?? []) {
-          if (obj.Key) {
-            items.push({
-              key: obj.Key,
-              size: obj.Size ?? 0,
-              lastModified: obj.LastModified
+          if (!obj.Key || !obj.Key.endsWith(".json")) continue;
+          const id = obj.Key.slice(prefix.length, -".json".length);
+          try {
+            const getResult = await getClient2().getObject({
+              Bucket: bucketName,
+              Key: obj.Key
             });
+            const chunks = [];
+            const stream = getResult.Body;
+            for await (const chunk of stream) {
+              chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+            }
+            items.push({ id, data: JSON.parse(Buffer.concat(chunks).toString("utf-8")) });
+          } catch {
           }
         }
         continuationToken = result.IsTruncated ? result.NextContinuationToken : void 0;
@@ -392,6 +483,21 @@ var createBucketClient = (bucketName) => {
     }
   };
 };
+var createBucketClient = (bucketName) => {
+  let client2 = null;
+  const getClient2 = () => client2 ??= new S3({});
+  return createBucketMethods(getClient2, bucketName);
+};
+var createBucketClientWithEntities = (bucketName, entitiesConfig) => {
+  let client2 = null;
+  const getClient2 = () => client2 ??= new S3({});
+  const base = createBucketMethods(getClient2, bucketName);
+  const result = { ...base };
+  for (const [entityName, config] of Object.entries(entitiesConfig)) {
+    result[entityName] = createEntityClient(getClient2, bucketName, entityName, config.cacheSeconds);
+  }
+  return result;
+};
 
 // src/runtime/handler-utils.ts
 import { readFileSync } from "fs";
@@ -566,7 +672,17 @@ var DEP_FACTORIES = {
     const tagField = depHandler?.__spec?.tagField;
     return createTableClient(name, tagField ? { tagField } : void 0);
   },
-  bucket: (name) => createBucketClient(name),
+  bucket: (name, depHandler) => {
+    const entities = depHandler?.__spec?.entities;
+    if (entities && Object.keys(entities).length > 0) {
+      const config = {};
+      for (const [entityName, entityOpts] of Object.entries(entities)) {
+        config[entityName] = entityOpts.cache ? { cacheSeconds: toSeconds(entityOpts.cache) } : {};
+      }
+      return createBucketClientWithEntities(name, config);
+    }
+    return createBucketClient(name);
+  },
   mailer: () => createEmailClient(),
   queue: (name) => createQueueClient(name),
   worker: (name) => createWorkerClient(name)
@@ -630,6 +746,25 @@ var createHandlerRuntime = (handler, handlerType, logLevel = "info", extraSetupA
     resolvedParams = await buildParams(handler.config);
     return resolvedParams;
   };
+  let resolvedCfSigningConfig = null;
+  const getCfSigningConfig = async () => {
+    if (resolvedCfSigningConfig !== null) return resolvedCfSigningConfig;
+    const cfSigningKeySsmPath = process.env.EFF_CF_SIGNING_KEY;
+    const cfKeyPairId = process.env.EFF_CF_KEY_PAIR_ID;
+    const cfDomain = process.env.EFF_CF_DOMAIN;
+    if (!cfSigningKeySsmPath || !cfKeyPairId || !cfDomain) {
+      resolvedCfSigningConfig = void 0;
+      return void 0;
+    }
+    const values = await getParameters([cfSigningKeySsmPath]);
+    const privateKey = values.get(cfSigningKeySsmPath);
+    if (!privateKey) {
+      resolvedCfSigningConfig = void 0;
+      return void 0;
+    }
+    resolvedCfSigningConfig = { privateKey, keyPairId: cfKeyPairId, domain: cfDomain };
+    return resolvedCfSigningConfig;
+  };
   const getAuthRuntime = async (setupCtx) => {
     if (resolvedAuthRuntime !== null) return resolvedAuthRuntime;
     const authOpts = setupCtx && typeof setupCtx === "object" && "auth" in setupCtx ? setupCtx.auth : void 0;
@@ -644,12 +779,14 @@ var createHandlerRuntime = (handler, handlerType, logLevel = "info", extraSetupA
     const cacheTtlSeconds = apiToken?.cacheTtl ? toSeconds(apiToken.cacheTtl) : void 0;
     const rawVerify = apiToken?.verify;
     const wrappedVerify = rawVerify ? (args) => rawVerify(args.value) : void 0;
+    const cfSigningConfig = await getCfSigningConfig();
     resolvedAuthRuntime = createAuthRuntime(
       secret,
       defaultExpires,
       wrappedVerify,
       apiToken?.header,
-      cacheTtlSeconds
+      cacheTtlSeconds,
+      cfSigningConfig
     );
     return resolvedAuthRuntime;
   };
@@ -733,8 +870,10 @@ var createHandlerRuntime = (handler, handlerType, logLevel = "info", extraSetupA
 
 export {
   createTableClient,
+  toSeconds,
   AUTH_COOKIE_NAME,
   createBucketClient,
+  createBucketClientWithEntities,
   buildDeps,
   buildParams,
   createHandlerRuntime

package/dist/index.d.ts

@@ -263,6 +263,12 @@ type HttpResponse = {
     contentType?: ContentType;
     /** Response headers (use for custom content-types not covered by contentType) */
     headers?: Record<string, string>;
+    /**
+     * Multiple Set-Cookie values. Used by Lambda Function URLs to set multiple cookies
+     * in a single response (e.g., session cookie + CloudFront signed cookies).
+     * When present, takes precedence over `set-cookie` in `headers`.
+     */
+    cookies?: string[];
     /**
      * Set to `true` to return binary data.
      * When enabled, `body` must be a base64-encoded string and the response
@@ -317,7 +323,37 @@ type BucketClient = {
     /** The underlying S3 bucket name */
     bucketName: string;
 };
+/**
+ * Typed client for a single entity stored as JSON in a bucket.
+ * Objects are stored at `{entityName}/{id}.json`.
+ */
+type StoreEntityClient<T> = {
+    /** Store a JSON document by id */
+    put(id: string, data: T): Promise<void>;
+    /** Retrieve a JSON document by id. Returns undefined if not found. */
+    get(id: string): Promise<T | undefined>;
+    /** Delete a document by id */
+    delete(id: string): Promise<void>;
+    /** List all documents for this entity */
+    list(): Promise<{
+        id: string;
+        data: T;
+    }[]>;
+};
+/**
+ * BucketClient extended with typed entity clients.
+ */
+type BucketClientWithEntities<Entities extends Record<string, any>> = BucketClient & {
+    [K in keyof Entities]: StoreEntityClient<Entities[K]>;
+};
 
+/**
+ * Per-entity configuration for typed JSON key-value storage within a bucket.
+ */
+type BucketEntityConfig = {
+    /** Cache duration for CloudFront/browser caching (e.g., "10s", "5m", "1h"). No caching if omitted. */
+    cache?: Duration;
+};
 /**
  * Configuration options for defineBucket.
  */
@@ -333,6 +369,8 @@ type BucketConfig = {
     prefix?: string;
     /** S3 key suffix filter for event notifications (e.g., ".jpg") */
     suffix?: string;
+    /** Typed JSON entity definitions for key-value storage */
+    entities?: Record<string, BucketEntityConfig>;
 };
 /**
  * S3 event record passed to onObjectCreated/onObjectRemoved callbacks.
@@ -354,8 +392,8 @@ type BucketEvent = {
 /** Spread ctx into callback args (empty when no setup) */
 type SpreadCtx$6<C> = [C] extends [undefined] ? {} : C & {};
 /** Setup factory — receives bucket/deps/config/files based on what was declared */
-type SetupArgs$6<D, P, HasFiles extends boolean> = {
-    bucket: BucketClient;
+type SetupArgs$6<D, P, HasFiles extends boolean, Entities extends Record<string, any> = {}> = {
+    bucket: {} extends Entities ? BucketClient : BucketClientWithEntities<Entities>;
 } & ([D] extends [undefined] ? {} : {
     deps: ResolveDeps<D>;
 }) & ([P] extends [undefined] ? {} : {
@@ -379,7 +417,7 @@ type BucketObjectRemovedFn<C = undefined> = (args: {
  * Internal handler object created by defineBucket
  * @internal
  */
-type BucketHandler$1<C = any> = {
+type BucketHandler$1<C = any, Entities extends Record<string, any> = {}> = {
     readonly __brand: "effortless-bucket";
     readonly __spec: BucketConfig;
     readonly onError?: (...args: any[]) => any;
@@ -398,31 +436,35 @@ type BucketOptions = {
     /** S3 key suffix filter for event notifications (e.g., ".jpg") */
     suffix?: string;
 };
-interface BucketBuilder<D = undefined, P = undefined, C = undefined, HasFiles extends boolean = false> {
+interface BucketBuilder<D = undefined, P = undefined, C = undefined, HasFiles extends boolean = false, Entities extends Record<string, any> = {}> {
     /** Declare handler dependencies */
-    deps<D2 extends Record<string, AnyDepHandler>>(fn: () => D2): BucketBuilder<D2, P, C, HasFiles>;
+    deps<D2 extends Record<string, AnyDepHandler>>(fn: () => D2): BucketBuilder<D2, P, C, HasFiles, Entities>;
     /** Declare SSM secrets */
-    config<P2 extends Record<string, AnySecretRef>>(fn: ConfigFactory<P2>): BucketBuilder<D, P2, C, HasFiles>;
+    config<P2 extends Record<string, AnySecretRef>>(fn: ConfigFactory<P2>): BucketBuilder<D, P2, C, HasFiles, Entities>;
     /** Include static files in the Lambda ZIP */
-    include(glob: string): BucketBuilder<D, P, C, true>;
+    include(glob: string): BucketBuilder<D, P, C, true, Entities>;
+    /** Register a typed JSON entity stored as `{name}/{id}.json` in the bucket */
+    entity<N extends string, T>(name: N, options?: BucketEntityConfig): BucketBuilder<D, P, C, HasFiles, Entities & {
+        [K in N]: T;
+    }>;
     /** Initialize shared state on cold start with lambda options */
-    setup(lambda: LambdaOptions): BucketBuilder<D, P, C, HasFiles>;
+    setup(lambda: LambdaOptions): BucketBuilder<D, P, C, HasFiles, Entities>;
     /** Initialize shared state on cold start. Receives bucket (self-client), deps, config, files. */
-    setup<C2>(fn: (args: SetupArgs$6<D, P, HasFiles>) => C2 | Promise<C2>): BucketBuilder<D, P, C2, HasFiles>;
+    setup<C2>(fn: (args: SetupArgs$6<D, P, HasFiles, Entities>) => C2 | Promise<C2>): BucketBuilder<D, P, C2, HasFiles, Entities>;
     /** Initialize shared state on cold start with lambda options. Receives bucket (self-client), deps, config, files. */
-    setup<C2>(fn: (args: SetupArgs$6<D, P, HasFiles>) => C2 | Promise<C2>, lambda: LambdaOptions): BucketBuilder<D, P, C2, HasFiles>;
+    setup<C2>(fn: (args: SetupArgs$6<D, P, HasFiles, Entities>) => C2 | Promise<C2>, lambda: LambdaOptions): BucketBuilder<D, P, C2, HasFiles, Entities>;
     /** Handle errors thrown by callbacks */
     onError(fn: (args: {
         error: unknown;
-    } & SpreadCtx$6<C>) => void | Promise<void>): BucketBuilder<D, P, C, HasFiles>;
+    } & SpreadCtx$6<C>) => void | Promise<void>): BucketBuilder<D, P, C, HasFiles, Entities>;
     /** Cleanup callback — runs after each invocation, before Lambda freezes */
-    onCleanup(fn: (args: SpreadCtx$6<C>) => void | Promise<void>): BucketBuilder<D, P, C, HasFiles>;
+    onCleanup(fn: (args: SpreadCtx$6<C>) => void | Promise<void>): BucketBuilder<D, P, C, HasFiles, Entities>;
     /** Handle S3 ObjectCreated events (terminal — returns finalized handler) */
-    onObjectCreated(fn: BucketObjectCreatedFn<C>): BucketHandler$1<C>;
+    onObjectCreated(fn: BucketObjectCreatedFn<C>): BucketHandler$1<C, Entities>;
     /** Handle S3 ObjectRemoved events (terminal — returns finalized handler) */
-    onObjectRemoved(fn: BucketObjectRemovedFn<C>): BucketHandler$1<C>;
+    onObjectRemoved(fn: BucketObjectRemovedFn<C>): BucketHandler$1<C, Entities>;
     /** Finalize as resource-only bucket (no Lambda) */
-    build(): BucketHandler$1<C>;
+    build(): BucketHandler$1<C, Entities>;
 }
 /**
  * Define an S3 bucket with optional event handlers.
@@ -926,10 +968,10 @@ type WorkerClient<T = unknown> = {
 };
 
 /** Dep value types supported by the deps declaration */
-type AnyDepHandler = TableHandler$1<any, any> | BucketHandler$1<any> | MailerHandler | FifoQueueHandler$1<any, any> | WorkerHandler$1<any, any>;
+type AnyDepHandler = TableHandler$1<any, any> | BucketHandler$1<any, any> | MailerHandler | FifoQueueHandler$1<any, any> | WorkerHandler$1<any, any>;
 /** Maps a deps declaration to resolved runtime client types */
 type ResolveDeps<D> = {
-    [K in keyof D]: D[K] extends TableHandler$1<infer T> ? TableClient<T> : D[K] extends BucketHandler$1 ? BucketClient : D[K] extends MailerHandler ? EmailClient : D[K] extends FifoQueueHandler$1<infer T> ? QueueClient<T> : D[K] extends WorkerHandler$1<infer T> ? WorkerClient<T> : never;
+    [K in keyof D]: D[K] extends TableHandler$1<infer T> ? TableClient<T> : D[K] extends BucketHandler$1<any, infer E> ? ({} extends E ? BucketClient : BucketClientWithEntities<E>) : D[K] extends MailerHandler ? EmailClient : D[K] extends FifoQueueHandler$1<infer T> ? QueueClient<T> : D[K] extends WorkerHandler$1<infer T> ? WorkerClient<T> : never;
 };
 
 /** DynamoDB Streams view type - determines what data is captured in stream records */
@@ -1160,6 +1202,18 @@ declare const defineApp: () => (options: AppConfig) => AppHandler;
 type AnyRoutableHandler = {
     readonly __brand: string;
 };
+/** Route configuration for serving bucket content through CloudFront */
+type BucketRouteConfig = {
+    bucket: {
+        readonly __brand: "effortless-bucket";
+    };
+    /** Access control: "private" requires CloudFront signed cookies, "public" serves openly. Default: "public" */
+    access?: "private" | "public";
+};
+/** A route value: either an API handler or a bucket route config */
+type RouteValue = AnyRoutableHandler | BucketRouteConfig;
+/** Type guard for bucket route entries */
+declare const isBucketRoute: (v: unknown) => v is BucketRouteConfig;
 /** Simplified request object passed to middleware */
 type MiddlewareRequest = {
     uri: string;
@@ -1206,10 +1260,10 @@ type StaticSiteConfig = {
     build?: string;
     /** Custom domain name. Accepts a string (same domain for all stages) or a Record mapping stage names to domains (e.g., `{ prod: "example.com", dev: "dev.example.com" }`). Requires an ACM certificate in us-east-1. If the cert also covers www, a 301 redirect from www to non-www is set up automatically. */
     domain?: string | Record<string, string>;
-    /** CloudFront route overrides: path patterns forwarded to API Gateway instead of S3.
-     * Keys are CloudFront path patterns (e.g., "/api/*"), values are HTTP handlers.
-     * Example: `routes: { "/api/*": api }` */
-    routes?: Record<string, AnyRoutableHandler>;
+    /** CloudFront route overrides: path patterns forwarded to API Gateway or S3 bucket origins.
+     * Keys are CloudFront path patterns (e.g., "/api/*"), values are HTTP handlers or bucket route configs.
+     * Example: `routes: { "/api/*": api, "/files/*": { bucket: storage, access: "private" } }` */
+    routes?: Record<string, RouteValue>;
     /** Custom 404 error page path relative to `dir` (e.g. "404.html").
      * For non-SPA sites only. If not set, a default page is generated automatically. */
     errorPage?: string;
@@ -1236,17 +1290,27 @@ type StaticSiteHandler = {
  */
 declare const defineStaticSite: () => (options: StaticSiteConfig) => StaticSiteHandler;
 
+/** Options for CloudFront signed cookie policy */
+type CdnPolicyOptions = {
+    /** Path pattern to grant access to (e.g., "/files/users/123/*"). Supports `*` and `?` wildcards. */
+    path: string;
+    /** How long the CDN access is valid (e.g., "1h", "30m") */
+    ttl: Duration;
+};
 /** Options for creating a session */
 type SessionOptions = {
     expiresIn?: Duration;
+    /** CloudFront signed cookie policy for CDN-level access control */
+    cdnPolicy?: CdnPolicyOptions;
 };
-/** Session response with Set-Cookie header */
+/** Session response with Set-Cookie headers */
 type SessionResponse = {
     status: 200;
     body: {
         ok: true;
     };
     headers: Record<string, string>;
+    cookies?: string[];
 };
 /**
  * Auth helpers injected into API handler callback args when `auth` is configured.
@@ -1300,12 +1364,28 @@ type OkHelper = (body?: unknown, status?: number) => HttpResponse;
 /** Error response helper: `fail("message")` → `{ status: 400, body: { error: "message" } }` */
 type FailHelper = (message: string, status?: number) => HttpResponse;
 type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/** Cache options for a GET route. Duration shorthand (e.g. "30s", "5m") or object for fine-grained control. */
+type CacheOptions = Duration | {
+    ttl: Duration;
+    swr?: Duration;
+    scope?: "public" | "private";
+};
+/** Resolved cache config with numeric seconds */
+type ResolvedCache = {
+    private?: false;
+    ttl: number;
+    swr: number;
+} | {
+    private: true;
+    ttl: number;
+};
 /** Parsed route definition stored at runtime */
 type RouteEntry = {
     method: HttpMethod;
     path: string;
     onRequest: (...args: any[]) => any;
     public?: boolean;
+    cache?: ResolvedCache;
 };
 /** Spread ctx into route args: Omit auth config, add AuthHelpers if present */
 type SpreadCtx$2<C> = ([C] extends [undefined] ? {} : Omit<C & {}, 'auth'>) & ([ExtractAuth<C>] extends [undefined] ? {} : {
@@ -1322,10 +1402,14 @@ type RouteArgs<C, ST> = SpreadCtx$2<C> & {
 } : {});
 /** Route handler function */
 type RouteHandler<C, ST> = (args: RouteArgs<C, ST>) => Promise<HttpResponse | void> | HttpResponse | void;
-/** Route options (e.g. public) */
+/** Route options for all methods */
 type RouteOptions = {
     public?: boolean;
 };
+/** Route options for GET — supports caching */
+type GetRouteOptions = RouteOptions & {
+    cache?: CacheOptions;
+};
 /** Setup factory — receives deps/config/files/enableAuth based on what was declared */
 type SetupArgs$2<D, P, HasFiles extends boolean> = {
     enableAuth: EnableAuth;
@@ -1375,7 +1459,7 @@ type ApiOptions = {
  * Has `__brand` so CLI discovers it. Each `.get()/.post()` adds a route and returns self.
  */
 interface ApiRoutes<C = undefined, ST extends boolean = false> extends ApiHandler<C> {
-    get(path: `/${string}`, handler: RouteHandler<C, ST>, options?: RouteOptions): ApiRoutes<C, ST>;
+    get(path: `/${string}`, handler: RouteHandler<C, ST>, options?: GetRouteOptions): ApiRoutes<C, ST>;
     post(path: `/${string}`, handler: RouteHandler<C, ST>, options?: RouteOptions): ApiRoutes<C, ST>;
     put(path: `/${string}`, handler: RouteHandler<C, ST>, options?: RouteOptions): ApiRoutes<C, ST>;
     patch(path: `/${string}`, handler: RouteHandler<C, ST>, options?: RouteOptions): ApiRoutes<C, ST>;
@@ -1410,7 +1494,7 @@ interface ApiBuilder<D = undefined, P = undefined, C = undefined, ST extends boo
     /** Cleanup callback — runs after each invocation, before Lambda freezes */
     onCleanup(fn: (args: SpreadCtx$2<C>) => void | Promise<void>): ApiBuilder<D, P, C, ST, HasFiles>;
     /** Add a GET route (terminal — returns finalized handler with route methods) */
-    get(path: `/${string}`, handler: RouteHandler<C, ST>, options?: RouteOptions): ApiRoutes<C, ST>;
+    get(path: `/${string}`, handler: RouteHandler<C, ST>, options?: GetRouteOptions): ApiRoutes<C, ST>;
     /** Add a POST route (terminal) */
     post(path: `/${string}`, handler: RouteHandler<C, ST>, options?: RouteOptions): ApiRoutes<C, ST>;
     /** Add a PUT route (terminal) */
@@ -1685,9 +1769,9 @@ declare function defineMcp(options: McpOptions): McpBuilder;
 
 type TableHandler<T = Record<string, unknown>> = TableHandler$1<T, any>;
 type FifoQueueHandler<T = unknown> = FifoQueueHandler$1<T, any>;
-type BucketHandler = BucketHandler$1<any>;
+type BucketHandler<Entities extends Record<string, any> = {}> = BucketHandler$1<any, Entities>;
 type CronHandler = CronHandler$1<any>;
 type WorkerHandler<T = any> = WorkerHandler$1<T, any>;
 type McpHandler = McpHandler$1<any>;
 
-export { type ApiAuthConfig, type ApiConfig, type ApiHandler, type ApiRoutes, type AppConfig, type AppHandler, type AuthHelpers, type BucketClient, type BucketConfig, type BucketEvent, type BucketHandler, type ConfigHelpers, type ContentType, type CronConfig, type CronHandler, type DefineSecretFn, type Duration, type EffortlessConfig, type EmailClient, type FifoQueueConfig, type FifoQueueHandler, type FifoQueueMessage, type HttpMethod$1 as HttpMethod, type HttpRequest, type HttpResponse, type LogLevel, type MailerConfig, type MailerHandler, type McpConfig, type McpHandler, type McpInputSchema, type McpToolContent, type McpToolDef, type McpToolResult, type MiddlewareDeny, type MiddlewareHandler, type MiddlewareRedirect, type MiddlewareRequest, type MiddlewareResult, type ParamRef, type Permission, type PutInput, type PutOptions, type QueryByTagParams, type QueryParams, type QueueClient, type ResponseStream, type SecretRef, type SendEmailOptions, type SendMessageInput, type SkCondition, type StaticFiles, type StaticSiteConfig, type StaticSiteHandler, type StaticSiteSeo, type StreamView, type TableClient, type TableConfig, type TableHandler, type TableItem, type TableKey, type TableRecord, type Timezone, type UpdateActions, type WorkerClient, type WorkerConfig, type WorkerHandler, type WorkerSendOptions, defineApi, defineApp, defineBucket, defineConfig, defineCron, defineFifoQueue, defineMailer, defineMcp, defineSecret, defineStaticSite, defineTable, defineWorker, generateBase64, generateHex, generateUuid, param, secret, toSeconds };
+export { type ApiAuthConfig, type ApiConfig, type ApiHandler, type ApiRoutes, type AppConfig, type AppHandler, type AuthHelpers, type BucketClient, type BucketClientWithEntities, type BucketConfig, type BucketEntityConfig, type BucketEvent, type BucketHandler, type BucketRouteConfig, type CacheOptions, type CdnPolicyOptions, type ConfigHelpers, type ContentType, type CronConfig, type CronHandler, type DefineSecretFn, type Duration, type EffortlessConfig, type EmailClient, type FifoQueueConfig, type FifoQueueHandler, type FifoQueueMessage, type HttpMethod$1 as HttpMethod, type HttpRequest, type HttpResponse, type LogLevel, type MailerConfig, type MailerHandler, type McpConfig, type McpHandler, type McpInputSchema, type McpToolContent, type McpToolDef, type McpToolResult, type MiddlewareDeny, type MiddlewareHandler, type MiddlewareRedirect, type MiddlewareRequest, type MiddlewareResult, type ParamRef, type Permission, type PutInput, type PutOptions, type QueryByTagParams, type QueryParams, type QueueClient, type ResponseStream, type SecretRef, type SendEmailOptions, type SendMessageInput, type SkCondition, type StaticFiles, type StaticSiteConfig, type StaticSiteHandler, type StaticSiteSeo, type StoreEntityClient, type StreamView, type TableClient, type TableConfig, type TableHandler, type TableItem, type TableKey, type TableRecord, type Timezone, type UpdateActions, type WorkerClient, type WorkerConfig, type WorkerHandler, type WorkerSendOptions, defineApi, defineApp, defineBucket, defineConfig, defineCron, defineFifoQueue, defineMailer, defineMcp, defineSecret, defineStaticSite, defineTable, defineWorker, generateBase64, generateHex, generateUuid, isBucketRoute, param, secret, toSeconds };

package/dist/index.js

@@ -116,6 +116,7 @@ var defineApp = () => (options) => ({
 });
 
 // src/handlers/define-static-site.ts
+var isBucketRoute = (v) => v != null && typeof v === "object" && "bucket" in v && v.bucket != null && typeof v.bucket === "object" && v.bucket.__brand === "effortless-bucket";
 var defineStaticSite = () => (options) => ({
   __brand: "effortless-static-site",
   __spec: options
@@ -231,6 +232,13 @@ function defineBucket(options) {
       state.static = [...state.static ?? [], glob];
       return builder;
     },
+    entity(name, options2) {
+      state.spec = {
+        ...state.spec,
+        entities: { ...state.spec.entities, [name]: options2 ?? {} }
+      };
+      return builder;
+    },
     setup(fnOrLambda, maybeLambda) {
       if (typeof fnOrLambda === "function") {
         state.setup = fnOrLambda;
@@ -270,6 +278,20 @@ var defineMailer = () => (options) => ({
 });
 
 // src/handlers/define-api.ts
+var resolveCache = (cache) => {
+  if (typeof cache === "number" || typeof cache === "string") {
+    const ttl2 = toSeconds(cache);
+    return { ttl: ttl2, swr: ttl2 * 2 };
+  }
+  const ttl = toSeconds(cache.ttl);
+  if (cache.scope === "private") {
+    return { private: true, ttl };
+  }
+  return {
+    ttl,
+    swr: cache.swr != null ? toSeconds(cache.swr) : ttl * 2
+  };
+};
 function defineApi(options) {
   const { basePath, stream } = options;
   const state = {
@@ -280,11 +302,13 @@ function defineApi(options) {
     routes: []
   };
   const addRoute = (method, path, handler, opts) => {
+    const routeCache = opts?.cache != null ? resolveCache(opts.cache) : void 0;
     state.routes.push({
       method,
       path,
       onRequest: handler,
-      ...opts?.public ? { public: true } : {}
+      ...opts?.public ? { public: true } : {},
+      ...routeCache ? { cache: routeCache } : {}
     });
   };
   const applyLambdaOptions = (lambda) => {
@@ -567,6 +591,7 @@ export {
   generateBase64,
   generateHex,
   generateUuid,
+  isBucketRoute,
   param,
   secret,
   toSeconds