@rayselfs/cf-rule-engine 1.5.0

package/README.md

@@ -0,0 +1,276 @@
+# @rayselfs/cf-rule-engine
+
+A composable, tree-shakeable rule engine for **AWS CloudFront Functions and Lambda@Edge**.
+
+Define edge rules — redirects, CORS headers, IP allowlists, token auth, image optimization — as plain TypeScript using an Akamai-inspired criteria + behaviors API. Rules are fully tree-shakeable and compile down to CloudFront-compatible JS.
+
+## Installation
+
+```bash
+npm install @rayselfs/cf-rule-engine
+```
+
+## Quick Start
+
+**viewer-request** — IP blocking and method handling:
+
+```typescript
+import { rule, not } from '@rayselfs/cf-rule-engine'
+import { ipCidr, methodIs } from '@rayselfs/cf-rule-engine/criteria/index'
+import { redirect, constructResponse } from '@rayselfs/cf-rule-engine/behaviors/index'
+import { defineViewerRequest } from '@rayselfs/cf-rule-engine/adapters/cf-function'
+
+export default defineViewerRequest([
+  rule(not(ipCidr(['10.0.0.0/8', '172.16.0.0/12'])), redirect(302, '/blocked')),
+  rule(methodIs(['OPTIONS']), constructResponse({ statusCode: 200, body: 'ok' })),
+])
+```
+
+**viewer-response** — security and CORS headers:
+
+```typescript
+import { setSecurityHeaders, setCorsHeaders } from '@rayselfs/cf-rule-engine/behaviors/index'
+import { defineViewerResponse } from '@rayselfs/cf-rule-engine/adapters/cf-function'
+
+export default defineViewerResponse([
+  setSecurityHeaders(),
+  setCorsHeaders({ allowedOrigins: ['https://www.viverse.com'] }),
+])
+```
+
+Build and deploy:
+
+```bash
+esbuild viewer-request.ts \
+  --bundle --minify --target=es2017 \
+  --supported:for-of=false --supported:template-literal=false --supported:arrow=false \
+  --format=iife --global-name=handler \
+  --outfile=dist/viewer-request.js
+# Append handler unwrap for IIFE compatibility:
+echo 'handler=handler.default||handler;' >> dist/viewer-request.js
+```
+
+## Concepts
+
+Rules are composed of an optional **criteria** guard and a **behavior**. If criteria is omitted, the behavior always runs.
+
+```typescript
+rule(criteria?, behavior)   // with or without criteria guard
+
+all([criteriaA, criteriaB])   // AND
+any([criteriaA, criteriaB])   // OR
+not(criteria)                 // NOT
+
+chain([behaviorA, behaviorB]) // sequential: B sees mutations made by A
+```
+
+Use `chain()` when one behavior must see the request mutations (URI rewrite, header change) made by a previous behavior. Without `chain()`, each separate `rule()` re-evaluates criteria against the **original** unmodified request.
+
+**Adapters** normalize CloudFront's event format so the same rule definitions work across both runtimes:
+
+| Adapter | Import | Use for |
+|---|---|---|
+| CF Function | `@rayselfs/cf-rule-engine/adapters/cf-function` | `viewer-request`, `viewer-response` |
+| Lambda@Edge | `@rayselfs/cf-rule-engine/adapters/lambda-edge` | `viewer-request`, `viewer-response` |
+
+## Akamai → CloudFront Mapping
+
+### Criteria
+
+| Function | Description |
+|---|---|
+| `pathPrefix(prefixes)` | URI starts with any prefix in the array |
+| `pathEquals(paths)` | URI exactly matches any path in the array |
+| `pathMatches(patterns)` | URI matches any wildcard pattern (`*`, `?`) in the array |
+| `hostnameIs(hosts)` | Host header matches any host in the array |
+| `methodIs(methods)` | HTTP method matches any method in the array |
+| `fileExtension(exts)` | URI file extension matches any extension in the array |
+| `headerEquals(name, values)` | Request header equals any value in the array |
+| `headerContains(name, substrings)` | Request header contains any of the substrings (`string[]`) |
+| `ipCidr(cidrs)` | Client IP is within any CIDR range in the array |
+| `countryIs(codes)` | `CloudFront-Viewer-Country` matches any ISO code in the array |
+| `userAgentMatches(patterns)` | User-Agent matches any wildcard pattern in the array |
+
+### Behaviors (`@rayselfs/cf-rule-engine/behaviors/index`)
+
+| Function | CF Function | Lambda@Edge |
+|---|---|---|
+| `redirect(status, url)` | ✅ | ✅ |
+| `rewriteUri(mode, value)` | ✅ | ✅ |
+| `constructResponse(options)` | ✅ | ✅ |
+| `setRequestHeader(name, value)` | ✅ | ✅ |
+| `copyHeader(from, to)` | ✅ | ✅ |
+| `setResponseHeader(name, value)` | ✅ | ✅ |
+| `removeResponseHeaders(names)` | ✅ | ✅ |
+| `setCorsHeaders(options)` | ✅ | ✅ |
+| `stripQueryParams(params)` | ✅ | ✅ |
+| `setSecurityHeaders(options)` | ✅ | ✅ |
+| `setCacheControl(options)` | ✅ | ✅ |
+| `setCsp(options)` | ✅ | ✅ |
+| `directoryIndex(file)` | ✅ | ✅ |
+| `imageOptimize(options)` | ✅ | ✅ |
+| `verifyToken(options)` | ❌ | ✅ |
+
+## Helpers (`@rayselfs/cf-rule-engine/helpers/index`)
+
+Helpers are pre-configured rule factories that combine multiple criteria and behaviors for common use cases.
+
+### sendCountryCode
+
+Copies the `CloudFront-Viewer-Country` header to a custom request header (default: `x-viewer-country`), making the viewer's country code available to the origin server.
+
+```typescript
+import { sendCountryCode } from '@rayselfs/cf-rule-engine/helpers/index'
+
+rule(sendCountryCode())                        // copies to x-viewer-country
+rule(sendCountryCode('x-custom-country'))      // copies to a custom header
+```
+
+### stagingIndicator
+
+Adds `x-cf-distribution: staging` to the response when the request carries `aws-cf-cd-staging: true`. Use in `viewer-response` configs shared between the primary and staging distributions so clients can confirm via DevTools or curl which distribution served the request.
+
+```typescript
+import { stagingIndicator } from '@rayselfs/cf-rule-engine/helpers/index'
+
+defineViewerResponse([
+  setCorsHeaders({ allowedOrigins: ['https://www.viverse.com'] }),
+  stagingIndicator(),
+])
+```
+
+Primary distribution requests do not carry `aws-cf-cd-staging`, so the rule is a no-op there.
+
+### stagingWhitelist
+
+Restricts access to a staging environment by IP CIDR range and/or User-Agent pattern. Requests that don't match any allowed CIDR or User-Agent (and aren't on a bypassed path) are redirected with HTTP 302.
+
+No default allowlists are included — callers must supply all CIDRs and User-Agent patterns explicitly.
+
+```typescript
+import { stagingWhitelist } from '@rayselfs/cf-rule-engine/helpers/index'
+
+stagingWhitelist({
+  cidrs: ['203.0.113.0/24', '10.0.0.0/8'],
+  userAgents: ['*InternalBot*', '*Prerender*'],
+  redirectUrl: 'https://www.example.com',
+})
+
+// With bypass paths:
+stagingWhitelist({
+  cidrs: ['203.0.113.0/24'],
+  redirectUrl: 'https://www.example.com',
+  bypassPaths: ['/api/health', '/robots.txt'],
+})
+```
+
+**Parameters:**
+- `cidrs` (required): CIDR ranges to allow (e.g. office IPs, VPN, stage VPCs)
+- `userAgents`: User-Agent wildcard patterns to allow (supports `*` and `?`)
+- `redirectUrl` (required): Where to redirect blocked requests
+- `bypassPaths`: Paths exempt from whitelist checks (supports wildcards)
+
+## CF Function vs Lambda@Edge
+
+| | CF Function | Lambda@Edge |
+|---|---|---|
+| Bundle size limit | **10 KB** | 1 MB (viewer), 50 MB (origin) |
+| Runtime | ES 5.1 + select ES6–12 (see AWS docs) | Node.js 20.x |
+| Cold start | ~1 ms | ~100 ms |
+| Max execution time | 1 ms | 5 s (viewer) |
+| Environment variables | ❌ | ✅ (origin events only) |
+| Node.js `crypto` | ❌ | ✅ |
+
+**Use CF Function** for: redirects, header manipulation, CORS, rewrites, IP allowlists.
+
+**Use Lambda@Edge** for: HMAC token validation (`verifyToken`), any behavior requiring Node.js APIs.
+
+## Bundle Size
+
+CF Functions have a **10 KB post-minification limit**. cf-engine is fully tree-shakeable — only imported behaviors and criteria enter the bundle.
+
+Rough estimates per rule type:
+- Base overhead ≈ 2 KB
+- Redirect rule ≈ 150–200 bytes
+- CIDR check ≈ 50 bytes
+
+If a bundle exceeds ~8 KB, split heavy rule groups into a Lambda@Edge and route via CloudFront path-pattern behaviors.
+
+## Build
+
+**CF Function:**
+
+```bash
+esbuild viewer-request.ts \
+  --bundle --minify --target=es2017 \
+  --supported:for-of=false --supported:template-literal=false --supported:arrow=false \
+  --format=iife --global-name=handler \
+  --outfile=dist/viewer-request.js
+# Append handler unwrap for IIFE compatibility:
+echo 'handler=handler.default||handler;' >> dist/viewer-request.js
+```
+
+**Lambda@Edge:**
+
+```bash
+esbuild lambda-viewer-request.ts \
+  --bundle --minify --platform=node --target=node20 \
+  --format=cjs \
+  --outfile=dist/lambda-viewer-request.js
+```
+
+> `dist/` must be committed in consumer repos — Terraform reads built files at `plan` time and cannot invoke a build step.
+
+## CF JS 2.0 Compatibility
+
+> **v1.1.0 Breaking Change**: All criteria and combinator functions now accept arrays instead of variadic arguments.
+> `ipCidr('a', 'b')` → `ipCidr(['a', 'b'])`, `all(fn1, fn2)` → `all([fn1, fn2])`.
+
+cf-engine source code is written to be directly compatible with the CloudFront JS 2.0 runtime. The runtime is documented as ES 5.1 compliant with select ES6–12 features, but in practice the parser rejects several ES6+ syntax patterns inside esbuild-minified IIFE bundles — even some that the official docs claim are supported.
+
+### Build flags (required for CF Function targets)
+
+```bash
+esbuild --target=es2017 \
+  --supported:for-of=false \
+  --supported:template-literal=false \
+  --supported:arrow=false \
+  --format=iife --global-name=handler
+# Then append: echo 'handler=handler.default||handler;' >> output.js
+```
+
+The handler unwrap is needed because esbuild IIFE wraps the export as `{default: fn}`, but CF expects a bare `handler` function.
+
+### Syntax avoided in cf-engine source
+
+These patterns are NOT used anywhere in cf-engine, so esbuild cannot emit them regardless of flags:
+
+| Pattern | Why avoided |
+|---------|------------|
+| `for...of` | Not in CF JS 2.0 statement list |
+| Object/array spread `{...x}` `[...x]` | Not documented as supported |
+| Rest parameters `...args` | Fails in minified IIFE bundles |
+| Destructuring `[a, b] = arr` | Fails in minified IIFE bundles |
+| Default parameters `f(x = 1)` | Not documented as supported |
+| `new Map` / `new Set` | Not documented as supported |
+
+### Syntax handled by esbuild flags
+
+| Pattern | esbuild flag | What esbuild does |
+|---------|-------------|-------------------|
+| Arrow functions `=>` | `--supported:arrow=false` | Converts to `function` |
+| Template literals `` ` `` | `--supported:template-literal=false` | Converts to string concat |
+| `for...of` | `--supported:for-of=false` | Converts to index loop |
+| Optional chaining `?.` | `--target=es2017` | Auto-downleveled |
+| Nullish coalescing `??` | `--target=es2017` | Auto-downleveled |
+
+## Development
+
+```bash
+npm run build      # tsup
+npm run typecheck  # tsc --noEmit
+npm test           # vitest
+```
+
+See `samples/` for complete working examples.
+

package/dist/adapters/cf-function.cjs

@@ -0,0 +1,10 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+var _chunkSAXDN5NScjs = require('../chunk-SAXDN5NS.cjs');
+require('../chunk-WKYMSRCD.cjs');
+require('../chunk-75ZPJI57.cjs');
+
+
+
+exports.defineViewerRequest = _chunkSAXDN5NScjs.defineViewerRequest; exports.defineViewerResponse = _chunkSAXDN5NScjs.defineViewerResponse;

package/dist/adapters/cf-function.d.cts

@@ -0,0 +1,2 @@
+import '../core/types.cjs';
+export { d as defineViewerRequest, a as defineViewerResponse } from '../cf-function-D27hUVtN.cjs';

package/dist/adapters/cf-function.d.ts

@@ -0,0 +1,2 @@
+import '../core/types.js';
+export { d as defineViewerRequest, a as defineViewerResponse } from '../cf-function-u0PvbW_s.js';

package/dist/adapters/cf-function.js

@@ -0,0 +1,10 @@
+import {
+  defineViewerRequest,
+  defineViewerResponse
+} from "../chunk-NPMGSPNL.js";
+import "../chunk-Q4NP4C3B.js";
+import "../chunk-MLKGABMK.js";
+export {
+  defineViewerRequest,
+  defineViewerResponse
+};

package/dist/adapters/lambda-edge.cjs

@@ -0,0 +1,10 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+var _chunk3BBLG4IXcjs = require('../chunk-3BBLG4IX.cjs');
+require('../chunk-WKYMSRCD.cjs');
+require('../chunk-75ZPJI57.cjs');
+
+
+
+exports.defineViewerRequest = _chunk3BBLG4IXcjs.defineViewerRequest; exports.defineViewerResponse = _chunk3BBLG4IXcjs.defineViewerResponse;

package/dist/adapters/lambda-edge.d.cts

@@ -0,0 +1,2 @@
+import '../core/types.cjs';
+export { d as defineViewerRequest, a as defineViewerResponse } from '../lambda-edge-DxTOa2cg.cjs';

package/dist/adapters/lambda-edge.d.ts

@@ -0,0 +1,2 @@
+import '../core/types.js';
+export { d as defineViewerRequest, a as defineViewerResponse } from '../lambda-edge-D15Nf__n.js';

package/dist/adapters/lambda-edge.js

@@ -0,0 +1,10 @@
+import {
+  defineViewerRequest,
+  defineViewerResponse
+} from "../chunk-WEBU4R5C.js";
+import "../chunk-Q4NP4C3B.js";
+import "../chunk-MLKGABMK.js";
+export {
+  defineViewerRequest,
+  defineViewerResponse
+};

package/dist/behaviors/construct-response.cjs

@@ -0,0 +1,7 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+var _chunkOSGZTNTScjs = require('../chunk-OSGZTNTS.cjs');
+require('../chunk-75ZPJI57.cjs');
+
+
+exports.constructResponse = _chunkOSGZTNTScjs.constructResponse;

package/dist/behaviors/construct-response.d.cts

@@ -0,0 +1,62 @@
+import { BehaviorFn } from '../core/types.cjs';
+
+/**
+ * Options for constructing a synthetic HTTP response at the edge.
+ */
+interface ConstructResponseOptions {
+    /**
+     * The HTTP status code for the response (e.g. `200`, `403`, `404`).
+     */
+    statusCode: number;
+    /**
+     * Optional response body string. If omitted, an empty body is returned.
+     */
+    body?: string;
+    /**
+     * Optional `Content-Type` header value (e.g. `'application/json'`, `'text/plain'`).
+     * Omit to exclude the `Content-Type` header from the response.
+     */
+    contentType?: string;
+    /**
+     * Additional response headers to include, as a plain key-value map.
+     * Header names are automatically lowercased.
+     *
+     * @example `{ 'x-request-id': '123', 'retry-after': '60' }`
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Constructs and returns a synthetic HTTP response directly from the edge,
+ * without forwarding the request to the origin.
+ *
+ * The response always includes `Cache-Control: no-store`.
+ *
+ * Akamai equivalent: `constructResponse` behavior.
+ *
+ * @param options - The response configuration: status code, optional body, content type,
+ *   and any additional headers.
+ * @returns A `BehaviorFn` to use as the second argument to `rule()`.
+ *
+ * @example
+ * ```ts
+ * import { constructResponse } from '@viverse/cf-engine/behaviors'
+ * import { methodIs, pathPrefix } from '@viverse/cf-engine/criteria'
+ * import { rule } from '@viverse/cf-engine'
+ *
+ * // Respond to OPTIONS preflight requests
+ * rule(methodIs(['OPTIONS']), constructResponse({ statusCode: 200, body: '' }))
+ *
+ * // Block with 403 and JSON error body
+ * rule(
+ *   pathPrefix(['/admin/']),
+ *   constructResponse({
+ *     statusCode: 403,
+ *     contentType: 'application/json',
+ *     body: JSON.stringify({ error: 'Forbidden' }),
+ *   }),
+ * )
+ * ```
+ */
+declare function constructResponse(options: ConstructResponseOptions): BehaviorFn;
+
+export { type ConstructResponseOptions, constructResponse };

package/dist/behaviors/construct-response.d.ts

@@ -0,0 +1,62 @@
+import { BehaviorFn } from '../core/types.js';
+
+/**
+ * Options for constructing a synthetic HTTP response at the edge.
+ */
+interface ConstructResponseOptions {
+    /**
+     * The HTTP status code for the response (e.g. `200`, `403`, `404`).
+     */
+    statusCode: number;
+    /**
+     * Optional response body string. If omitted, an empty body is returned.
+     */
+    body?: string;
+    /**
+     * Optional `Content-Type` header value (e.g. `'application/json'`, `'text/plain'`).
+     * Omit to exclude the `Content-Type` header from the response.
+     */
+    contentType?: string;
+    /**
+     * Additional response headers to include, as a plain key-value map.
+     * Header names are automatically lowercased.
+     *
+     * @example `{ 'x-request-id': '123', 'retry-after': '60' }`
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Constructs and returns a synthetic HTTP response directly from the edge,
+ * without forwarding the request to the origin.
+ *
+ * The response always includes `Cache-Control: no-store`.
+ *
+ * Akamai equivalent: `constructResponse` behavior.
+ *
+ * @param options - The response configuration: status code, optional body, content type,
+ *   and any additional headers.
+ * @returns A `BehaviorFn` to use as the second argument to `rule()`.
+ *
+ * @example
+ * ```ts
+ * import { constructResponse } from '@viverse/cf-engine/behaviors'
+ * import { methodIs, pathPrefix } from '@viverse/cf-engine/criteria'
+ * import { rule } from '@viverse/cf-engine'
+ *
+ * // Respond to OPTIONS preflight requests
+ * rule(methodIs(['OPTIONS']), constructResponse({ statusCode: 200, body: '' }))
+ *
+ * // Block with 403 and JSON error body
+ * rule(
+ *   pathPrefix(['/admin/']),
+ *   constructResponse({
+ *     statusCode: 403,
+ *     contentType: 'application/json',
+ *     body: JSON.stringify({ error: 'Forbidden' }),
+ *   }),
+ * )
+ * ```
+ */
+declare function constructResponse(options: ConstructResponseOptions): BehaviorFn;
+
+export { type ConstructResponseOptions, constructResponse };

package/dist/behaviors/construct-response.js

@@ -0,0 +1,7 @@
+import {
+  constructResponse
+} from "../chunk-6DBZBV2M.js";
+import "../chunk-MLKGABMK.js";
+export {
+  constructResponse
+};

package/dist/behaviors/copy-header.cjs

@@ -0,0 +1,7 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+var _chunkJU5WX5RUcjs = require('../chunk-JU5WX5RU.cjs');
+require('../chunk-75ZPJI57.cjs');
+
+
+exports.copyHeader = _chunkJU5WX5RUcjs.copyHeader;

package/dist/behaviors/copy-header.d.cts

@@ -0,0 +1,27 @@
+import { BehaviorFn } from '../core/types.cjs';
+
+/**
+ * Copies the value of one request header into another request header.
+ *
+ * If the source header does not exist in the request, the behavior is a no-op —
+ * the request is passed through unchanged. Header names are matched and written
+ * in lowercase.
+ *
+ * Commonly used to forward CloudFront-injected headers (e.g. `CloudFront-Viewer-Country`)
+ * under a custom name that the origin server expects.
+ *
+ * @param sourceHeader - The request header to read from. Case-insensitive.
+ * @param targetHeader - The request header to write to. Case-insensitive.
+ * @returns A `BehaviorFn` to use as the second argument to `rule()`.
+ *
+ * @example
+ * ```ts
+ * import { copyHeader } from '@viverse/cf-engine/behaviors'
+ * import { rule } from '@viverse/cf-engine'
+ *
+ * rule(copyHeader('cloudfront-viewer-country', 'x-htc-request-country-code'))
+ * ```
+ */
+declare function copyHeader(sourceHeader: string, targetHeader: string): BehaviorFn;
+
+export { copyHeader };

package/dist/behaviors/copy-header.d.ts

@@ -0,0 +1,27 @@
+import { BehaviorFn } from '../core/types.js';
+
+/**
+ * Copies the value of one request header into another request header.
+ *
+ * If the source header does not exist in the request, the behavior is a no-op —
+ * the request is passed through unchanged. Header names are matched and written
+ * in lowercase.
+ *
+ * Commonly used to forward CloudFront-injected headers (e.g. `CloudFront-Viewer-Country`)
+ * under a custom name that the origin server expects.
+ *
+ * @param sourceHeader - The request header to read from. Case-insensitive.
+ * @param targetHeader - The request header to write to. Case-insensitive.
+ * @returns A `BehaviorFn` to use as the second argument to `rule()`.
+ *
+ * @example
+ * ```ts
+ * import { copyHeader } from '@viverse/cf-engine/behaviors'
+ * import { rule } from '@viverse/cf-engine'
+ *
+ * rule(copyHeader('cloudfront-viewer-country', 'x-htc-request-country-code'))
+ * ```
+ */
+declare function copyHeader(sourceHeader: string, targetHeader: string): BehaviorFn;
+
+export { copyHeader };

package/dist/behaviors/copy-header.js

@@ -0,0 +1,7 @@
+import {
+  copyHeader
+} from "../chunk-BDNPQ7AU.js";
+import "../chunk-MLKGABMK.js";
+export {
+  copyHeader
+};

package/dist/behaviors/directory-index.cjs

@@ -0,0 +1,7 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+var _chunkLTLBEBKLcjs = require('../chunk-LTLBEBKL.cjs');
+require('../chunk-75ZPJI57.cjs');
+
+
+exports.directoryIndex = _chunkLTLBEBKLcjs.directoryIndex;

package/dist/behaviors/directory-index.d.cts

@@ -0,0 +1,33 @@
+import { BehaviorFn } from '../core/types.cjs';
+
+/**
+ * Handles directory index routing for static site hosting, applying three transformations:
+ *
+ * 1. **Directory request** (`/path/`) → rewrites URI to `/path/index.html` (or custom file).
+ * 2. **Index file request** (`/path/index.html`) → 301 redirects to `/path/`.
+ * 3. **Extensionless path** (`/path/about`) → 301 redirects to `/path/about/`.
+ *
+ * This mirrors the behavior of S3 static website hosting when accessed via CloudFront
+ * without using an S3 website endpoint.
+ *
+ * @param indexFile - The index file name to append to directory URIs.
+ *   Default: `'index.html'`.
+ * @returns A `BehaviorFn` to use as the second argument to `rule()`.
+ *
+ * @example
+ * ```ts
+ * import { directoryIndex } from '@viverse/cf-engine/behaviors'
+ * import { rule } from '@viverse/cf-engine'
+ * import { defineViewerRequest } from '@viverse/cf-engine/adapters/cf-function'
+ *
+ * export default defineViewerRequest([
+ *   rule(directoryIndex()),
+ * ])
+ *
+ * // With a custom index file
+ * rule(directoryIndex('default.html'))
+ * ```
+ */
+declare function directoryIndex(indexFile?: string): BehaviorFn;
+
+export { directoryIndex };

package/dist/behaviors/directory-index.d.ts

@@ -0,0 +1,33 @@
+import { BehaviorFn } from '../core/types.js';
+
+/**
+ * Handles directory index routing for static site hosting, applying three transformations:
+ *
+ * 1. **Directory request** (`/path/`) → rewrites URI to `/path/index.html` (or custom file).
+ * 2. **Index file request** (`/path/index.html`) → 301 redirects to `/path/`.
+ * 3. **Extensionless path** (`/path/about`) → 301 redirects to `/path/about/`.
+ *
+ * This mirrors the behavior of S3 static website hosting when accessed via CloudFront
+ * without using an S3 website endpoint.
+ *
+ * @param indexFile - The index file name to append to directory URIs.
+ *   Default: `'index.html'`.
+ * @returns A `BehaviorFn` to use as the second argument to `rule()`.
+ *
+ * @example
+ * ```ts
+ * import { directoryIndex } from '@viverse/cf-engine/behaviors'
+ * import { rule } from '@viverse/cf-engine'
+ * import { defineViewerRequest } from '@viverse/cf-engine/adapters/cf-function'
+ *
+ * export default defineViewerRequest([
+ *   rule(directoryIndex()),
+ * ])
+ *
+ * // With a custom index file
+ * rule(directoryIndex('default.html'))
+ * ```
+ */
+declare function directoryIndex(indexFile?: string): BehaviorFn;
+
+export { directoryIndex };

package/dist/behaviors/directory-index.js

@@ -0,0 +1,7 @@
+import {
+  directoryIndex
+} from "../chunk-R7WXS7BI.js";
+import "../chunk-MLKGABMK.js";
+export {
+  directoryIndex
+};

package/dist/behaviors/image-optimize.cjs

@@ -0,0 +1,9 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+var _chunkTQLJIT4Hcjs = require('../chunk-TQLJIT4H.cjs');
+require('../chunk-75ZPJI57.cjs');
+
+
+
+exports.imageOptimize = _chunkTQLJIT4Hcjs.imageOptimize; exports.resolveImageParams = _chunkTQLJIT4Hcjs.resolveImageParams;