@beignet/core 0.0.2 → 0.0.4

package/dist/server/hooks/idempotency.js

@@ -0,0 +1,154 @@
+/**
+ * Idempotency hooks for @beignet/core/server
+ */
+import { AppError, httpErrors } from "../../errors/index.js";
+import { createIdempotencyFingerprint, IdempotencyConflictError, IdempotencyInProgressError, } from "../../idempotency/index.js";
+/**
+ * Header set on replayed responses.
+ */
+const IDEMPOTENCY_REPLAYED_HEADER = "idempotency-replayed";
+function defaultIdempotencyScope(ctx, meta) {
+    const mode = meta.scope ?? "global";
+    switch (mode) {
+        case "global":
+            return "global";
+        case "actor":
+            return { actorId: ctx.actor?.id };
+        case "tenant":
+            return { tenantId: ctx.tenant?.id };
+        case "actor-tenant":
+            return { actorId: ctx.actor?.id, tenantId: ctx.tenant?.id };
+    }
+}
+function isReplayableHttpResponse(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    if (typeof candidate.status !== "number")
+        return false;
+    if (candidate.headers !== undefined &&
+        (typeof candidate.headers !== "object" ||
+            candidate.headers === null ||
+            Array.isArray(candidate.headers))) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Create metadata-driven idempotency hooks.
+ *
+ * The hook reads `contract.metadata.idempotency` and enforces it with
+ * `ctx.ports.idempotency`. In `beforeHandle` it reserves the client key after
+ * request parsing, replays completed matching responses with an
+ * `idempotency-replayed: true` header, and rejects in-progress or conflicting
+ * keys with the framework `IdempotencyInProgress`/`IdempotencyConflict` catalog
+ * errors. In `beforeSend` it stores 2xx framework-neutral responses for replay
+ * and releases the reservation for errors, non-2xx responses, and native
+ * `Response` results, which are not replayable.
+ *
+ * Use `runIdempotently(...)` from `@beignet/core/idempotency` for non-HTTP
+ * workflows such as jobs, listeners, webhooks, and schedules.
+ *
+ * @param options - Optional namespace, scope, and fingerprint-input builders.
+ * @returns A server hook backed by `ctx.ports.idempotency`.
+ */
+export function createIdempotencyHooks(options = {}) {
+    const pending = new WeakMap();
+    return {
+        name: "idempotency",
+        beforeHandle: async ({ ctx, contract, req, path, query, body }) => {
+            const meta = contract.metadata?.idempotency;
+            if (!meta) {
+                return undefined;
+            }
+            const header = (meta.header ?? "idempotency-key").toLowerCase();
+            const key = req.headers.get(header);
+            if (!key) {
+                if (meta.required) {
+                    throw new AppError(httpErrors.BadRequest, {
+                        contract: contract.name,
+                        header,
+                    }, `Missing required idempotency key header "${header}"`);
+                }
+                return undefined;
+            }
+            const namespace = options.namespace?.({ contract: { name: contract.name } }) ??
+                `http.${contract.name}`;
+            const scope = options.scope?.({ ctx, req, meta }) ??
+                defaultIdempotencyScope(ctx, meta);
+            const fingerprint = await createIdempotencyFingerprint(options.fingerprintInput?.({ path, query, body }) ?? {
+                path,
+                query,
+                body,
+            });
+            const reservation = await ctx.ports.idempotency.reserve({
+                namespace,
+                key,
+                scope,
+                fingerprint,
+                ttlSec: meta.ttlSec,
+            });
+            switch (reservation.status) {
+                case "replay": {
+                    if (!isReplayableHttpResponse(reservation.result)) {
+                        throw new AppError(httpErrors.InternalServerError, { namespace, key }, `Stored idempotency result for "${namespace}" key "${key}" is not a replayable HTTP response`);
+                    }
+                    return {
+                        status: reservation.result.status,
+                        headers: {
+                            ...(reservation.result.headers ?? {}),
+                            [IDEMPOTENCY_REPLAYED_HEADER]: "true",
+                        },
+                        body: reservation.result.body,
+                    };
+                }
+                case "inProgress": {
+                    throw new IdempotencyInProgressError(reservation);
+                }
+                case "conflict": {
+                    throw new IdempotencyConflictError(reservation);
+                }
+                case "reserved": {
+                    pending.set(req, {
+                        port: ctx.ports.idempotency,
+                        namespace,
+                        key,
+                        scope,
+                        fingerprint,
+                    });
+                    return undefined;
+                }
+            }
+        },
+        beforeSend: async ({ req, response, error, native }) => {
+            const reservation = pending.get(req);
+            if (!reservation) {
+                return undefined;
+            }
+            pending.delete(req);
+            const { port, namespace, key, scope, fingerprint } = reservation;
+            if (!native &&
+                !error &&
+                response.status >= 200 &&
+                response.status < 300) {
+                await port.complete({
+                    namespace,
+                    key,
+                    scope,
+                    fingerprint,
+                    result: {
+                        status: response.status,
+                        headers: response.headers,
+                        body: response.body,
+                    },
+                });
+                return undefined;
+            }
+            // Errors, non-2xx responses, and native `Response` results release the
+            // reservation. Streams are not replayable.
+            await port.fail({ namespace, key, scope, fingerprint, error });
+            return undefined;
+        },
+    };
+}
+//# sourceMappingURL=idempotency.js.map

package/dist/server/hooks/idempotency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.js","sourceRoot":"","sources":["../../../src/server/hooks/idempotency.ts"],"names":[],"mappings":"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"}

package/dist/server/hooks/index.d.ts

@@ -1,13 +1,14 @@
 /**
  * Hook utilities for @beignet/core/server
  */
-import type { AnyPorts } from "../../ports";
-import type { ServerHook } from "../http";
-export { type AuthHookArgs, type AuthHookAssignArgs, type AuthHookMode, type AuthHookModeInput, type AuthHooksOptions, type AuthHookUnauthorizedArgs, type CtxWithAuthPort, createAuthHooks, } from "./auth";
-export { applyCorsHeaders, type CorsConfig, createCorsHooks, } from "./cors";
-export { defaultMapErrorToResponse, type ErrorMappingConfig, type ErrorMappingResult, } from "./errors";
-export { createLoggingHooks, type Logger, type LoggingConfig, } from "./logging";
-export { type CtxWithRateLimit, createRateLimitHooks, type RateLimitOptions, } from "./rate-limit";
+import type { AnyPorts } from "../../ports/index.js";
+import type { ServerHook } from "../http.js";
+export { type AuthHookArgs, type AuthHooksOptions, type AuthRouteHooks, createAuthHooks, } from "./auth.js";
+export { applyCorsHeaders, type CorsConfig, createCorsHooks, } from "./cors.js";
+export { defaultMapErrorToResponse, type ErrorMappingConfig, type ErrorMappingResult, } from "./errors.js";
+export { type CtxWithIdempotency, createIdempotencyHooks, type IdempotencyHooksOptions, type IdempotencyPorts, } from "./idempotency.js";
+export { createLoggingHooks, type Logger, type LoggingConfig, } from "./logging.js";
+export { type CtxWithRateLimit, createRateLimitHooks, type RateLimitIpSource, type RateLimitOptions, } from "./rate-limit.js";
 /**
  * Flatten hook arrays into a single hook list.
  */

package/dist/server/hooks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/hooks/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,wBAAwB,EAC7B,KAAK,eAAe,EACpB,eAAe,GAChB,MAAM,QAAQ,CAAC;AAChB,OAAO,EACL,gBAAgB,EAChB,KAAK,UAAU,EACf,eAAe,GAChB,MAAM,QAAQ,CAAC;AAChB,OAAO,EACL,yBAAyB,EACzB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,GACxB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,kBAAkB,EAClB,KAAK,MAAM,EACX,KAAK,aAAa,GACnB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,KAAK,gBAAgB,EACrB,oBAAoB,EACpB,KAAK,gBAAgB,GACtB,MAAM,cAAc,CAAC;AAEtB;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,KAAK,SAAS,QAAQ,GAAG,QAAQ,EACjE,GAAG,KAAK,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,SAAS,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,CAAC,EAAE,GACvE,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,CAE1B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/hooks/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,eAAe,GAChB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,gBAAgB,EAChB,KAAK,UAAU,EACf,eAAe,GAChB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,yBAAyB,EACzB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,kBAAkB,EACvB,sBAAsB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,kBAAkB,EAClB,KAAK,MAAM,EACX,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,gBAAgB,EACrB,oBAAoB,EACpB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AAEzB;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,KAAK,SAAS,QAAQ,GAAG,QAAQ,EACjE,GAAG,KAAK,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,SAAS,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,CAAC,EAAE,GACvE,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,CAE1B"}

package/dist/server/hooks/index.js

@@ -1,11 +1,12 @@
 /**
  * Hook utilities for @beignet/core/server
  */
-export { createAuthHooks, } from "./auth";
-export { applyCorsHeaders, createCorsHooks, } from "./cors";
-export { defaultMapErrorToResponse, } from "./errors";
-export { createLoggingHooks, } from "./logging";
-export { createRateLimitHooks, } from "./rate-limit";
+export { createAuthHooks, } from "./auth.js";
+export { applyCorsHeaders, createCorsHooks, } from "./cors.js";
+export { defaultMapErrorToResponse, } from "./errors.js";
+export { createIdempotencyHooks, } from "./idempotency.js";
+export { createLoggingHooks, } from "./logging.js";
+export { createRateLimitHooks, } from "./rate-limit.js";
 /**
  * Flatten hook arrays into a single hook list.
  */

package/dist/server/hooks/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/server/hooks/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,EAQL,eAAe,GAChB,MAAM,QAAQ,CAAC;AAChB,OAAO,EACL,gBAAgB,EAEhB,eAAe,GAChB,MAAM,QAAQ,CAAC;AAChB,OAAO,EACL,yBAAyB,GAG1B,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,kBAAkB,GAGnB,MAAM,WAAW,CAAC;AACnB,OAAO,EAEL,oBAAoB,GAErB,MAAM,cAAc,CAAC;AAEtB;;GAEG;AACH,MAAM,UAAU,YAAY,CAC1B,GAAG,KAAqE;IAExE,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACxE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/server/hooks/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,EAIL,eAAe,GAChB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,gBAAgB,EAEhB,eAAe,GAChB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,yBAAyB,GAG1B,MAAM,aAAa,CAAC;AACrB,OAAO,EAEL,sBAAsB,GAGvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,kBAAkB,GAGnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAEL,oBAAoB,GAGrB,MAAM,iBAAiB,CAAC;AAEzB;;GAEG;AACH,MAAM,UAAU,YAAY,CAC1B,GAAG,KAAqE;IAExE,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACxE,CAAC"}

package/dist/server/hooks/logging.d.ts

@@ -1,8 +1,8 @@
 /**
  * Logging hook utilities for @beignet/core/server
  */
-import type { HttpContractConfig } from "../../contracts";
-import type { HttpRequestLike, ServerHook } from "../types";
+import type { HttpContractConfig } from "../../contracts/index.js";
+import type { HttpRequestLike, ServerHook } from "../types.js";
 /**
  * Minimal logger shape accepted by `createLoggingHooks(...)`.
  */

package/dist/server/hooks/logging.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logging.d.ts","sourceRoot":"","sources":["../../../src/server/hooks/logging.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAG5D;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB;;OAEG;IACH,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACnC;;OAEG;IACH,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACpC;;OAEG;IACH,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACpC;;OAEG;IACH,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,GAAG;IAChC;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;OAEG;IACH,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE;QACtB,GAAG,CAAC,EAAE,GAAG,CAAC;QACV,GAAG,EAAE,eAAe,CAAC;QACrB,QAAQ,CAAC,EAAE,kBAAkB,CAAC;KAC/B,KAAK,IAAI,CAAC;IACX;;OAEG;IACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE;QACpB,GAAG,CAAC,EAAE,GAAG,CAAC;QACV,GAAG,EAAE,eAAe,CAAC;QACrB,GAAG,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;SAAE,CAAC;QACzD,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,kBAAkB,CAAC;QAC9B,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,KAAK,IAAI,CAAC;CACZ;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EACpC,MAAM,EAAE,aAAa,CAAC,GAAG,CAAC,GACzB,UAAU,CAAC,GAAG,CAAC,CAqFjB"}
+{"version":3,"file":"logging.d.ts","sourceRoot":"","sources":["../../../src/server/hooks/logging.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG/D;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB;;OAEG;IACH,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACnC;;OAEG;IACH,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACpC;;OAEG;IACH,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACpC;;OAEG;IACH,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,GAAG;IAChC;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;OAEG;IACH,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE;QACtB,GAAG,CAAC,EAAE,GAAG,CAAC;QACV,GAAG,EAAE,eAAe,CAAC;QACrB,QAAQ,CAAC,EAAE,kBAAkB,CAAC;KAC/B,KAAK,IAAI,CAAC;IACX;;OAEG;IACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE;QACpB,GAAG,CAAC,EAAE,GAAG,CAAC;QACV,GAAG,EAAE,eAAe,CAAC;QACrB,GAAG,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;SAAE,CAAC;QACzD,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,kBAAkB,CAAC;QAC9B,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,KAAK,IAAI,CAAC;CACZ;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EACpC,MAAM,EAAE,aAAa,CAAC,GAAG,CAAC,GACzB,UAAU,CAAC,GAAG,CAAC,CAqFjB"}

package/dist/server/hooks/logging.js

@@ -1,7 +1,7 @@
 /**
  * Logging hook utilities for @beignet/core/server
  */
-import { getRequestIdFromContext } from "./utils";
+import { getRequestIdFromContext } from "./utils.js";
 /**
  * Create request logging hooks.
  *

package/dist/server/hooks/logging.js.map

@@ -1 +1 @@
-{"version":3,"file":"logging.js","sourceRoot":"","sources":["../../../src/server/hooks/logging.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"logging.js","sourceRoot":"","sources":["../../../src/server/hooks/logging.ts"],"names":[],"mappings":"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"}

package/dist/server/hooks/rate-limit.d.ts

@@ -1,9 +1,9 @@
 /**
  * Rate limit hooks for @beignet/core/server
  */
-import type { RateLimitScope } from "../../contracts";
-import type { ActivityActor, RateLimitPort } from "../../ports";
-import type { HttpRequestLike, ServerHook } from "../types";
+import type { RateLimitScope } from "../../contracts/index.js";
+import type { ActivityActor, RateLimitPort } from "../../ports/index.js";
+import type { HttpRequestLike, ServerHook } from "../types.js";
 /**
  * Ports required by rate-limit hooks.
  */
@@ -18,6 +18,19 @@ export type CtxWithRateLimit = {
     actor?: ActivityActor;
 };
 type EarlyRateLimitScope = Exclude<RateLimitScope, "user">;
+/**
+ * Strategy for resolving the client IP used by `ip`-scoped limits.
+ *
+ * - `"x-forwarded-for-last"` (default): the last `x-forwarded-for` entry.
+ *   This is the address appended by the platform's trusted reverse proxy and
+ *   cannot be chosen by the client.
+ * - `"x-forwarded-for-first"`: the first `x-forwarded-for` entry. This value
+ *   is client-controlled, so only use it when a trusted edge normalizes the
+ *   header before it reaches the app.
+ * - A function receives the raw request and returns the client IP, for
+ *   platform-specific headers such as `cf-connecting-ip`.
+ */
+export type RateLimitIpSource = "x-forwarded-for-last" | "x-forwarded-for-first" | ((req: HttpRequestLike) => string | undefined);
 /**
  * Options for `createRateLimitHooks(...)`.
  */
@@ -42,9 +55,12 @@ export interface RateLimitOptions<Ctx> {
         scope: EarlyRateLimitScope;
     }) => string;
     /**
-     * Resolve a client IP from the raw request.
+     * Resolve the client IP for `ip`-scoped limits.
+     *
+     * Defaults to `"x-forwarded-for-last"`, the entry appended by the
+     * platform's trusted proxy. Pass a function for platform-specific headers.
      */
-    getClientIp?: (req: HttpRequestLike) => string | undefined;
+    ipSource?: RateLimitIpSource;
 }
 /**
  * Create metadata-driven rate-limit hooks.
@@ -52,9 +68,11 @@ export interface RateLimitOptions<Ctx> {
  * The hook reads `contract.metadata.rateLimit`. Global and IP-scoped limits run
  * in `onRequest` before context creation; user-scoped limits run in
  * `beforeHandle` after `ctx.actor` is available. Exceeded limits throw the
- * framework `TooManyRequests` app error.
+ * framework `TooManyRequests` app error with `scope`, `retryAfterSeconds`, and
+ * `resetAt` details. The bucket key is never sent to clients; denials emit a
+ * `rateLimit.denied` instrumentation event that carries the key for operators.
  *
- * @param options - Optional key builders and client-IP resolver.
+ * @param options - Optional key builders and client-IP source.
  * @returns A server hook backed by `ctx.ports.rateLimit`.
  */
 export declare function createRateLimitHooks<Ctx extends CtxWithRateLimit>(options?: RateLimitOptions<Ctx>): ServerHook<Ctx, RateLimitPorts>;

package/dist/server/hooks/rate-limit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../../src/server/hooks/rate-limit.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE5D;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,SAAS,EAAE,aAAa,CAAC;CAC1B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,cAAc,CAAC;IACtB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB,CAAC;AAEF,KAAK,mBAAmB,GAAG,OAAO,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,GAAG;IACnC;;;;OAIG;IACH,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE;QACX,GAAG,EAAE,GAAG,CAAC;QACT,GAAG,EAAE,eAAe,CAAC;QACrB,KAAK,EAAE,cAAc,CAAC;KACvB,KAAK,MAAM,CAAC;IACb;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE;QAChB,GAAG,EAAE,eAAe,CAAC;QACrB,KAAK,EAAE,mBAAmB,CAAC;KAC5B,KAAK,MAAM,CAAC;IACb;;OAEG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,MAAM,GAAG,SAAS,CAAC;CAC5D;AAmFD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,SAAS,gBAAgB,EAC/D,OAAO,GAAE,gBAAgB,CAAC,GAAG,CAAM,GAClC,UAAU,CAAC,GAAG,EAAE,cAAc,CAAC,CAsDjC"}
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../../src/server/hooks/rate-limit.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAKzE,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE/D;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,SAAS,EAAE,aAAa,CAAC;CAC1B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,cAAc,CAAC;IACtB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB,CAAC;AAEF,KAAK,mBAAmB,GAAG,OAAO,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;AAE3D;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,iBAAiB,GACzB,sBAAsB,GACtB,uBAAuB,GACvB,CAAC,CAAC,GAAG,EAAE,eAAe,KAAK,MAAM,GAAG,SAAS,CAAC,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,GAAG;IACnC;;;;OAIG;IACH,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE;QACX,GAAG,EAAE,GAAG,CAAC;QACT,GAAG,EAAE,eAAe,CAAC;QACrB,KAAK,EAAE,cAAc,CAAC;KACvB,KAAK,MAAM,CAAC;IACb;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE;QAChB,GAAG,EAAE,eAAe,CAAC;QACrB,KAAK,EAAE,mBAAmB,CAAC;KAC5B,KAAK,MAAM,CAAC;IACb;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CAC9B;AA4HD;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,SAAS,gBAAgB,EAC/D,OAAO,GAAE,gBAAgB,CAAC,GAAG,CAAM,GAClC,UAAU,CAAC,GAAG,EAAE,cAAc,CAAC,CAuDjC"}

package/dist/server/hooks/rate-limit.js

@@ -1,10 +1,26 @@
 /**
  * Rate limit hooks for @beignet/core/server
  */
-import { AppError, httpErrors } from "../../errors";
-function defaultGetClientIp(req) {
-    const xfwd = req.headers.get("x-forwarded-for") ?? "";
-    return xfwd.split(",")[0].trim() || undefined;
+import { AppError, httpErrors } from "../../errors/index.js";
+import { createProviderInstrumentation, } from "../../providers/index.js";
+function parseForwardedFor(req) {
+    const header = req.headers.get("x-forwarded-for") ?? "";
+    return header
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+}
+function resolveClientIp(req, ipSource) {
+    if (typeof ipSource === "function") {
+        return ipSource(req) || undefined;
+    }
+    const entries = parseForwardedFor(req);
+    if (entries.length === 0) {
+        return undefined;
+    }
+    return ipSource === "x-forwarded-for-first"
+        ? entries[0]
+        : entries[entries.length - 1];
 }
 function emitUserKey(userId) {
     return `user:${userId}`;
@@ -30,8 +46,8 @@ function defaultEarlyRateLimitKey(args, getClientIp) {
     }
     return "global";
 }
-async function enforceRateLimit(rateLimit, args) {
-    const result = await rateLimit.hit({
+async function enforceRateLimit(ports, args) {
+    const result = await ports.rateLimit.hit({
         key: args.key,
         limit: args.limit,
         windowSec: args.windowSec,
@@ -39,8 +55,24 @@ async function enforceRateLimit(rateLimit, args) {
     if (result.allowed) {
         return;
     }
+    // App ports may carry an `instrumentation` or `devtools` sink alongside the
+    // typed rate-limit port; the helper resolves them at runtime.
+    const instrumentation = createProviderInstrumentation(ports, {
+        providerName: "rate-limit",
+        watcher: "rateLimit",
+    });
+    instrumentation.custom({
+        name: "rateLimit.denied",
+        label: "Rate limit denied",
+        summary: `Rate limit denied for ${args.key}`,
+        details: {
+            key: args.key,
+            scope: args.scope,
+            limit: args.limit,
+            windowSec: args.windowSec,
+        },
+    });
     throw new AppError(httpErrors.TooManyRequests, {
-        key: args.key,
         scope: args.scope,
         retryAfterSeconds: result.retryAfterSeconds,
         resetAt: result.resetAt?.toISOString() ?? null,
@@ -52,13 +84,16 @@ async function enforceRateLimit(rateLimit, args) {
  * The hook reads `contract.metadata.rateLimit`. Global and IP-scoped limits run
  * in `onRequest` before context creation; user-scoped limits run in
  * `beforeHandle` after `ctx.actor` is available. Exceeded limits throw the
- * framework `TooManyRequests` app error.
+ * framework `TooManyRequests` app error with `scope`, `retryAfterSeconds`, and
+ * `resetAt` details. The bucket key is never sent to clients; denials emit a
+ * `rateLimit.denied` instrumentation event that carries the key for operators.
  *
- * @param options - Optional key builders and client-IP resolver.
+ * @param options - Optional key builders and client-IP source.
  * @returns A server hook backed by `ctx.ports.rateLimit`.
  */
 export function createRateLimitHooks(options = {}) {
-    const getClientIp = options.getClientIp ?? defaultGetClientIp;
+    const ipSource = options.ipSource ?? "x-forwarded-for-last";
+    const getClientIp = (req) => resolveClientIp(req, ipSource);
     return {
         name: "rate-limit",
         onRequest: async ({ contract, ports, req }) => {
@@ -72,7 +107,7 @@ export function createRateLimitHooks(options = {}) {
             }
             const key = options.earlyKey?.({ req, scope }) ??
                 defaultEarlyRateLimitKey({ req, scope }, getClientIp);
-            await enforceRateLimit(ports.rateLimit, {
+            await enforceRateLimit(ports, {
                 key,
                 limit: rlMeta.max,
                 windowSec: rlMeta.windowSec,
@@ -91,7 +126,7 @@ export function createRateLimitHooks(options = {}) {
             }
             const key = options.key?.({ ctx, req, scope }) ??
                 defaultRateLimitKey({ ctx, req, scope }, getClientIp);
-            await enforceRateLimit(ctx.ports.rateLimit, {
+            await enforceRateLimit(ctx.ports, {
                 key,
                 limit: rlMeta.max,
                 windowSec: rlMeta.windowSec,

package/dist/server/hooks/rate-limit.js.map

@@ -1 +1 @@
-{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../../../src/server/hooks/rate-limit.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../../../src/server/hooks/rate-limit.ts"],"names":[],"mappings":"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"}

package/dist/server/hooks.d.ts

@@ -1,2 +1,2 @@
-export * from "./hooks/index";
+export * from "./hooks/index.js";
 //# sourceMappingURL=hooks.d.ts.map

package/dist/server/hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/server/hooks.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC"}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/server/hooks.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}

package/dist/server/hooks.js

@@ -1,2 +1,2 @@
-export * from "./hooks/index";
+export * from "./hooks/index.js";
 //# sourceMappingURL=hooks.js.map

package/dist/server/hooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/server/hooks.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC"}
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/server/hooks.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}

package/dist/server/http.d.ts

@@ -1,5 +1,5 @@
-import type { HttpContractConfig, InferHeaderSchemaOutput, InferOutput, StandardSchema } from "../contracts";
-import type { AnyPorts } from "../ports";
+import type { HttpContractConfig, InferHeaderSchemaOutput, InferOutput, StandardSchema } from "../contracts/index.js";
+import type { AnyPorts } from "../ports/index.js";
 /**
  * Framework-neutral request shape consumed by Beignet server adapters.
  *
@@ -75,6 +75,41 @@ export interface HttpResponseLike {
  * `Response` only when the current adapter can pass it through unchanged.
  */
 export type HttpResponse = HttpResponseLike | Response;
+/**
+ * Framework-neutral Beignet API handler consumed by HTTP adapters.
+ */
+export type HttpAdapterApiHandler = (req: HttpRequestLike) => Promise<HttpResponse>;
+/**
+ * Native handler shape produced by an HTTP adapter.
+ */
+export type HttpAdapterHandler<NativeRequest, NativeResponse> = (req: NativeRequest) => Promise<NativeResponse>;
+/**
+ * Contract implemented by packages that adapt Beignet's framework-neutral
+ * server runtime to a platform HTTP API.
+ *
+ * Core owns request parsing, hooks, route matching, validation, error mapping,
+ * response ownership, and provider lifecycle. Adapters own only the conversion
+ * between the platform request/response types and Beignet's `HttpRequestLike`
+ * / `HttpResponse` boundary.
+ */
+export interface HttpAdapter<NativeRequest, NativeResponse> {
+    /**
+     * Human-readable adapter name for diagnostics and documentation.
+     */
+    name: string;
+    /**
+     * Convert a platform request into Beignet's framework-neutral request shape.
+     */
+    toRequestLike(req: NativeRequest): HttpRequestLike;
+    /**
+     * Convert a Beignet response into the platform response type.
+     */
+    toNativeResponse(res: HttpResponse): NativeResponse | Promise<NativeResponse>;
+    /**
+     * Wrap a Beignet API handler in the platform's native handler shape.
+     */
+    createHandler(handler: HttpAdapterApiHandler): HttpAdapterHandler<NativeRequest, NativeResponse>;
+}
 type InferSchemaOrFallback<T extends StandardSchema | null, Fallback> = T extends StandardSchema ? InferOutput<T> : Fallback;
 /**
  * Infer the handler path parameter type for a contract.
@@ -101,7 +136,7 @@ export interface HandlerArgs<Ctx, C extends HttpContractConfig> {
      */
     req: HttpRequestLike;
     /**
-     * Application context returned by `createContext`.
+     * Application context assembled by the server context blueprint.
      */
     ctx: Ctx;
     /**
@@ -133,6 +168,40 @@ export type Handler<Ctx, C extends HttpContractConfig> = (args: HandlerArgs<Ctx,
  * Value or promise of that value.
  */
 export type MaybePromise<T> = T | Promise<T>;
+/**
+ * Arguments passed to a route-scoped hook after request parsing and context
+ * creation.
+ */
+export type RouteHookArgs<Ctx, C extends HttpContractConfig = HttpContractConfig> = HandlerArgs<Ctx, C>;
+/**
+ * Hook that runs only for the route or route group where it is attached.
+ *
+ * Route hooks are for scoped policy and context enrichment such as
+ * authentication, tenant resolution, feature gates, and idempotency. They add
+ * fields to the handler context instead of replacing the app context.
+ *
+ * Hook additions must not include `gate`: the server re-attaches the gate
+ * declared by the context blueprint after every hook, so identity changes are
+ * picked up automatically.
+ */
+export interface RouteHook<Ctx, AddedCtx extends object & {
+    gate?: never;
+} = Record<string, never>> {
+    /**
+     * Optional name used in diagnostics and devtools.
+     */
+    name?: string;
+    /**
+     * Resolve additional context for this route or throw to stop handling.
+     */
+    resolve: (args: RouteHookArgs<Ctx>) => MaybePromise<AddedCtx | undefined>;
+}
+type AddedCtxFromHook<Hook> = Hook extends RouteHook<infer _Ctx, infer AddedCtx> ? AddedCtx : unknown;
+type UnionToIntersection<Union> = (Union extends unknown ? (value: Union) => void : never) extends (value: infer Intersection) => void ? Intersection : never;
+/**
+ * Intersection of the context fields added by a route hook list.
+ */
+export type AddedCtxFromHooks<Hooks extends readonly unknown[]> = Hooks extends readonly [] ? unknown : UnionToIntersection<AddedCtxFromHook<Hooks[number]>>;
 /**
  * Hook that runs after a route is matched but before request parsing and
  * context creation.
@@ -168,10 +237,11 @@ export type BeforeHandleHook<Ctx, C extends HttpContractConfig = HttpContractCon
     body: InferBody<C>;
 }) => MaybePromise<BeforeHandleResult<Ctx>>;
 /**
- * Hook that runs before a framework-neutral response is returned.
+ * Hook that runs before the response is returned.
  *
  * Return a response to replace or decorate the outgoing response. Hooks run in
- * declaration order.
+ * declaration order. For native web `Response` results the hook receives a
+ * headers-only view and only header changes are applied.
  */
 export type BeforeSendHook<Ctx, C extends HttpContractConfig = HttpContractConfig> = (args: {
     req: HttpRequestLike;
@@ -183,6 +253,13 @@ export type BeforeSendHook<Ctx, C extends HttpContractConfig = HttpContractConfi
     body?: InferBody<C>;
     response: HttpResponseLike;
     error?: unknown;
+    /**
+     * True when the route returned a native web Response. The response argument
+     * is a headers-only view ({ status, headers }); the body is not readable and
+     * returned body/status changes are ignored. Header changes are merged onto
+     * the native Response.
+     */
+    native?: boolean;
 }) => MaybePromise<HttpResponseLike | undefined>;
 /**
  * Hook that runs after the response has been prepared.
@@ -253,7 +330,8 @@ export interface ServerHook<Ctx, Ports extends AnyPorts = AnyPorts> {
      */
     beforeHandle?: BeforeHandleHook<Ctx>;
     /**
-     * Runs before a framework-neutral response is returned.
+     * Runs before the response is returned. Native web `Response` results get a
+     * headers-only view with `native: true`.
      */
     beforeSend?: BeforeSendHook<Ctx>;
     /**