@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.11

package/dist/infra/throttler/redis-throttler-storage.js

@@ -0,0 +1,130 @@
+/**
+ * One atomic EVAL: when the counter already reached the limit the attempt is rejected and
+ * NOT counted (a rejected attempt must not push the count further, so the window ends on
+ * schedule); otherwise the counter is incremented and always carries a TTL. Returns
+ * `{hits, pttl, blocked}`. `now` is not needed: no TIME command, no clock in the script.
+ */
+const INCREMENT_LUA = `
+local key = KEYS[1]
+local ttlMs = tonumber(ARGV[1])
+local limit = tonumber(ARGV[2])
+local hits = tonumber(redis.call('GET', key) or '0')
+local blocked = 0
+if hits >= limit then
+  blocked = 1
+else
+  hits = redis.call('INCR', key)
+end
+local pttl = redis.call('PTTL', key)
+if pttl < 0 then
+  redis.call('PEXPIRE', key, ttlMs)
+  pttl = ttlMs
+end
+return {hits, pttl, blocked}
+`;
+/**
+ * All-or-nothing reservation across KEYS (one hash tag): ARGV[1] is the window in ms, ARGV[i + 1]
+ * the limit of KEYS[i]. Any key at its limit rejects the attempt and NOTHING is incremented;
+ * otherwise every key is incremented and carries a TTL. Returns `{1}` or `{0, retryPttl}` (the
+ * largest remaining TTL among the keys at their limit).
+ */
+const RESERVE_LUA = `
+local retry = -1
+for i, key in ipairs(KEYS) do
+  local n = tonumber(redis.call('GET', key) or '0')
+  if n >= tonumber(ARGV[i + 1]) then
+    local pttl = redis.call('PTTL', key)
+    if pttl > retry then retry = pttl end
+    if retry < 1 then retry = 1 end
+  end
+end
+if retry > 0 then
+  return {0, retry}
+end
+for i, key in ipairs(KEYS) do
+  local n = redis.call('INCR', key)
+  if n == 1 or redis.call('PTTL', key) < 0 then
+    redis.call('PEXPIRE', key, ARGV[1])
+  end
+end
+return {1}
+`;
+/**
+ * Success: the first ARGV[1] keys are deleted, the rest lose one count (deleted at zero, never
+ * created).
+ */
+const SUCCEEDED_LUA = `
+local nClear = tonumber(ARGV[1])
+for i = 1, nClear do
+  redis.call('DEL', KEYS[i])
+end
+for i = nClear + 1, #KEYS do
+  if redis.call('EXISTS', KEYS[i]) == 1 then
+    if redis.call('DECR', KEYS[i]) <= 0 then
+      redis.call('DEL', KEYS[i])
+    end
+  end
+end
+return 0
+`;
+const NOT_BLOCKED = {
+    totalHits: 0,
+    timeToExpire: 0,
+    isBlocked: false,
+    timeToBlockExpire: 0,
+};
+/** The Redis key of a counter. The `{key}` hash tag keeps it in one Redis Cluster slot. */
+export const throttlerRedisKey = (key, throttlerName) => `throttler:{${key}}:${throttlerName}`;
+/**
+ * The `@nestjs/throttler` storage on the shared Redis connection: every replica counts into the
+ * same keys (the default in-memory storage would give each replica its own quota). Fail-open: a
+ * Redis error lets the request through and logs a warning, so a Redis blip never turns every
+ * throttled route into a 5xx (availability over limit precision).
+ */
+export class RedisThrottlerStorage {
+    redis;
+    log;
+    constructor(redis, log) {
+        this.redis = redis;
+        this.log = log;
+    }
+    /** `ttl` is in milliseconds (the throttler convention); `blockDuration` is unused. */
+    async increment(key, ttl, limit, _blockDuration, throttlerName) {
+        try {
+            const [hits, pttl, blocked] = (await this.redis.eval(INCREMENT_LUA, 1, throttlerRedisKey(key, throttlerName), ttl, limit));
+            // seconds, at least 1 and at most the window: the Retry-After value
+            const timeToExpire = Math.min(Math.max(Math.ceil(pttl / 1000), 1), Math.ceil(ttl / 1000));
+            return {
+                totalHits: hits,
+                timeToExpire,
+                isBlocked: blocked === 1,
+                timeToBlockExpire: blocked === 1 ? timeToExpire : 0,
+            };
+        }
+        catch (err) {
+            this.log.warn("throttler storage unavailable, request allowed (fail-open)", {
+                throttler: throttlerName,
+                err,
+            });
+            return NOT_BLOCKED;
+        }
+    }
+    /**
+     * Reserves one attempt on every key (which must share one hash tag), all or nothing. Unlike
+     * `increment` it does NOT swallow Redis errors: the caller fails closed.
+     */
+    async reserve(keys, limits, ttlMs) {
+        const out = (await this.redis.eval(RESERVE_LUA, keys.length, ...keys, ttlMs, ...limits));
+        if (out[0] === 1)
+            return { allowed: true };
+        const window = Math.ceil(ttlMs / 1000);
+        return {
+            allowed: false,
+            retryAfterSeconds: Math.min(Math.max(Math.ceil((out[1] ?? ttlMs) / 1000), 1), window),
+        };
+    }
+    /** A successful attempt: deletes the `clear` counters and refunds one on the `refund` ones. Fails closed. */
+    async succeeded(clear, refund) {
+        await this.redis.eval(SUCCEEDED_LUA, clear.length + refund.length, ...clear, ...refund, clear.length);
+    }
+}

package/dist/infra/throttler/throttler.guard.d.ts

@@ -0,0 +1,23 @@
+import { type ExecutionContext } from "@nestjs/common";
+import { Reflector } from "@nestjs/core";
+import { ThrottlerGuard, type ThrottlerModuleOptions, type ThrottlerRequest, type ThrottlerStorage } from "@nestjs/throttler";
+/** The throttler names selected for the route `context` runs (empty: none, the guard passes). */
+export declare function selectedThrottlers(context: ExecutionContext): readonly string[];
+/**
+ * Opts a route (or controller) in to the named throttlers `names` (see `NAMED_THROTTLERS`).
+ * Throttling is per-route opt-in because the kernel limits only credential-checking routes today;
+ * health, SSE and extension routes stay unlimited.
+ */
+export declare const Throttled: (...names: string[]) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;
+/**
+ * `@nestjs/throttler`'s guard with the kernel's error contract: the first named throttler of the
+ * route at its limit answers 429 `auth.rate_limited` with its own message and `retry-after`
+ * (seconds, 1..window), as the credential routes answer; no `x-ratelimit-*` headers (the
+ * kernel sends none today). Which throttlers apply to a route is chosen by `@Throttled`; they are
+ * counted one after another in `NAMED_THROTTLERS` order (table order is check order). Fail-open on
+ * Redis errors (see `RedisThrottlerStorage`). For credential checks use `CredentialThrottler`.
+ */
+export declare class KernelThrottlerGuard extends ThrottlerGuard {
+    constructor(options: ThrottlerModuleOptions, storage: ThrottlerStorage, reflector: Reflector);
+    protected handleRequest(props: ThrottlerRequest): Promise<boolean>;
+}

package/dist/infra/throttler/throttler.guard.js

@@ -0,0 +1,68 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { applyDecorators, Inject, Injectable, SetMetadata, UseGuards, } from "@nestjs/common";
+import { Reflector } from "@nestjs/core";
+import { getOptionsToken, getStorageToken, ThrottlerGuard, } from "@nestjs/throttler";
+import { ApiError } from "../../errors.js";
+import { NAMED_THROTTLERS } from "./named-throttlers.js";
+const THROTTLED = "kernel:throttled";
+/** The throttler names selected for the route `context` runs (empty: none, the guard passes). */
+export function selectedThrottlers(context) {
+    return (Reflect.getMetadata(THROTTLED, context.getHandler()) ??
+        Reflect.getMetadata(THROTTLED, context.getClass()) ??
+        []);
+}
+/**
+ * Opts a route (or controller) in to the named throttlers `names` (see `NAMED_THROTTLERS`).
+ * Throttling is per-route opt-in because the kernel limits only credential-checking routes today;
+ * health, SSE and extension routes stay unlimited.
+ */
+export const Throttled = (...names) => {
+    for (const n of names) {
+        if (!NAMED_THROTTLERS.some((t) => t.name === n))
+            throw new Error(`unknown throttler "${n}"`);
+    }
+    return applyDecorators(SetMetadata(THROTTLED, names), UseGuards(KernelThrottlerGuard));
+};
+/**
+ * `@nestjs/throttler`'s guard with the kernel's error contract: the first named throttler of the
+ * route at its limit answers 429 `auth.rate_limited` with its own message and `retry-after`
+ * (seconds, 1..window), as the credential routes answer; no `x-ratelimit-*` headers (the
+ * kernel sends none today). Which throttlers apply to a route is chosen by `@Throttled`; they are
+ * counted one after another in `NAMED_THROTTLERS` order (table order is check order). Fail-open on
+ * Redis errors (see `RedisThrottlerStorage`). For credential checks use `CredentialThrottler`.
+ */
+let KernelThrottlerGuard = class KernelThrottlerGuard extends ThrottlerGuard {
+    constructor(options, storage, reflector) {
+        super(options, storage, reflector);
+    }
+    async handleRequest(props) {
+        const { context, limit, ttl, throttler, blockDuration, getTracker, generateKey } = props;
+        const http = context.switchToHttp();
+        const name = throttler.name ?? "default";
+        const tracker = await getTracker(http.getRequest(), context);
+        const key = generateKey(context, tracker, name);
+        const r = await this.storageService.increment(key, ttl, limit, blockDuration, name);
+        if (!r.isBlocked)
+            return true;
+        http.getResponse().header("retry-after", String(r.timeToBlockExpire));
+        const known = NAMED_THROTTLERS.find((t) => t.name === name);
+        if (!known)
+            throw new Error(`unknown throttler "${name}"`);
+        throw new ApiError("auth.rate_limited", known.message);
+    }
+};
+KernelThrottlerGuard = __decorate([
+    Injectable(),
+    __param(0, Inject(getOptionsToken())),
+    __param(1, Inject(getStorageToken())),
+    __param(2, Inject(Reflector))
+], KernelThrottlerGuard);
+export { KernelThrottlerGuard };

package/dist/infra/throttler/throttler.module.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Two limiters share the named-throttler table and the Redis storage, with opposite failure modes:
+ * - `@Throttled` (`KernelThrottlerGuard`): plain per-route limits, counted before the handler,
+ *   FAIL-OPEN on Redis errors (octok's rule: a Redis blip must not 5xx every limited route).
+ * - `CredentialThrottler`: called inside a handler for credential checks, all-or-nothing across
+ *   keys, FAIL-CLOSED on Redis errors (an attacker must not get unlimited guesses by making Redis
+ *   fail).
+ *
+ * Global: `@nestjs/throttler` over the Redis storage with the kernel's named throttlers, and the
+ * guard behind `@Throttled(...)`. The storage is injectable as `ThrottlerStorage`;
+ * `CredentialThrottler` casts it to `RedisThrottlerStorage` for its multi-key `reserve` /
+ * `succeeded`.
+ */
+export declare class KernelThrottlerModule {
+}

package/dist/infra/throttler/throttler.module.js

@@ -0,0 +1,53 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Global, Module } from "@nestjs/common";
+import { ThrottlerModule } from "@nestjs/throttler";
+import { KERNEL_LOGGER, REDIS } from "../tokens.js";
+import { CredentialThrottler } from "./credential-throttler.js";
+import { NAMED_THROTTLERS, throttlerKey } from "./named-throttlers.js";
+import { RedisThrottlerStorage } from "./redis-throttler-storage.js";
+import { KernelThrottlerGuard, selectedThrottlers } from "./throttler.guard.js";
+/**
+ * Two limiters share the named-throttler table and the Redis storage, with opposite failure modes:
+ * - `@Throttled` (`KernelThrottlerGuard`): plain per-route limits, counted before the handler,
+ *   FAIL-OPEN on Redis errors (octok's rule: a Redis blip must not 5xx every limited route).
+ * - `CredentialThrottler`: called inside a handler for credential checks, all-or-nothing across
+ *   keys, FAIL-CLOSED on Redis errors (an attacker must not get unlimited guesses by making Redis
+ *   fail).
+ *
+ * Global: `@nestjs/throttler` over the Redis storage with the kernel's named throttlers, and the
+ * guard behind `@Throttled(...)`. The storage is injectable as `ThrottlerStorage`;
+ * `CredentialThrottler` casts it to `RedisThrottlerStorage` for its multi-key `reserve` /
+ * `succeeded`.
+ */
+let KernelThrottlerModule = class KernelThrottlerModule {
+};
+KernelThrottlerModule = __decorate([
+    Global(),
+    Module({
+        imports: [
+            ThrottlerModule.forRootAsync({
+                inject: [REDIS, KERNEL_LOGGER],
+                useFactory: (redis, log) => ({
+                    storage: new RedisThrottlerStorage(redis, log),
+                    setHeaders: false,
+                    throttlers: NAMED_THROTTLERS.map((t) => ({
+                        name: t.name,
+                        limit: t.limit,
+                        ttl: t.ttl,
+                        getTracker: (req) => t.getTracker(req),
+                        generateKey: (_ctx, tracker, name) => throttlerKey(name, tracker),
+                        skipIf: (ctx) => !selectedThrottlers(ctx).includes(t.name),
+                    })),
+                }),
+            }),
+        ],
+        providers: [KernelThrottlerGuard, CredentialThrottler],
+        exports: [KernelThrottlerGuard, CredentialThrottler],
+    })
+], KernelThrottlerModule);
+export { KernelThrottlerModule };

package/dist/infra/tokens.d.ts

@@ -0,0 +1,20 @@
+/** Injection tokens of the global infra modules. */
+/**
+ * A class's logger (`KernelLogger`): the process logger with `context` set to the injecting class's
+ * name. Transient, so `app.get` cannot resolve it; use `KERNEL_ROOT_LOGGER` outside an injection.
+ */
+export declare const KERNEL_LOGGER: unique symbol;
+/** The process logger itself (`KernelLogger`), without a context. */
+export declare const KERNEL_ROOT_LOGGER: unique symbol;
+/** The startup input of `KernelConfigService`: `{ config, env }`. */
+export declare const KERNEL_CONFIG_INPUT: unique symbol;
+/** The Kysely pool, untyped (`Kysely<any>`); infra only, services inject `KernelDb`. */
+export declare const KERNEL_POOL: unique symbol;
+/** The main ioredis connection (lazy: connects on first command or an explicit `connect()`). */
+export declare const REDIS: unique symbol;
+/** The shared bus subscriber connection (`BusSubscriber` with `close()`). */
+export declare const REDIS_SUBSCRIBER: unique symbol;
+/** The kernel bus (`createBus(..., "kernel")`, `ExtensionContext["bus"]`). */
+export declare const KERNEL_BUS: unique symbol;
+/** The master keyring (`createKeyring` over `masterKey` / `masterKeyPrevious`). */
+export declare const KEYRING: unique symbol;

package/dist/infra/tokens.js

@@ -0,0 +1,20 @@
+/** Injection tokens of the global infra modules. */
+/**
+ * A class's logger (`KernelLogger`): the process logger with `context` set to the injecting class's
+ * name. Transient, so `app.get` cannot resolve it; use `KERNEL_ROOT_LOGGER` outside an injection.
+ */
+export const KERNEL_LOGGER = Symbol("KERNEL_LOGGER");
+/** The process logger itself (`KernelLogger`), without a context. */
+export const KERNEL_ROOT_LOGGER = Symbol("KERNEL_ROOT_LOGGER");
+/** The startup input of `KernelConfigService`: `{ config, env }`. */
+export const KERNEL_CONFIG_INPUT = Symbol("KERNEL_CONFIG_INPUT");
+/** The Kysely pool, untyped (`Kysely<any>`); infra only, services inject `KernelDb`. */
+export const KERNEL_POOL = Symbol("KERNEL_POOL");
+/** The main ioredis connection (lazy: connects on first command or an explicit `connect()`). */
+export const REDIS = Symbol("REDIS");
+/** The shared bus subscriber connection (`BusSubscriber` with `close()`). */
+export const REDIS_SUBSCRIBER = Symbol("REDIS_SUBSCRIBER");
+/** The kernel bus (`createBus(..., "kernel")`, `ExtensionContext["bus"]`). */
+export const KERNEL_BUS = Symbol("KERNEL_BUS");
+/** The master keyring (`createKeyring` over `masterKey` / `masterKeyPrevious`). */
+export const KEYRING = Symbol("KEYRING");

package/dist/infra/validation/create-zod-dto.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+/** A class carrying a zod schema; the global validation pipe validates parameters typed with one. */
+export interface ZodDtoClass<S extends z.ZodType = z.ZodType> {
+    new (): z.infer<S>;
+    readonly schema: S;
+    /** The name the swagger document lists the schema under. */
+    readonly dtoName: string | undefined;
+    /** The schema as JSON Schema (input side: what a client sends). */
+    jsonSchema(): Record<string, unknown>;
+}
+/** Every DTO created so far (the swagger document lists the named ones). */
+export declare function registeredZodDtos(): readonly ZodDtoClass[];
+/**
+ * Creates a DTO class from a zod schema (nestjs-zod does not support Nest 12, so the kernel has its
+ * own, same shape as octok's `createI18nZodDto`). Use it as the metatype of `@Body()`, `@Query()`
+ * or `@Param()`: `class CreateX extends createZodDto(schema, "CreateX") {}`. The instance type is
+ * the schema's output type.
+ */
+export declare function createZodDto<S extends z.ZodType>(schema: S, name?: string): ZodDtoClass<S>;
+/** The DTO's schema when `metatype` is one, else undefined. */
+export declare function zodSchemaOf(metatype: unknown): z.ZodType | undefined;
+/** What `@ZBody` / `@ZQuery` / `@ZParam` hand to the global pipe as the argument's `data`. */
+export declare function isZodDto(value: unknown): value is ZodDtoClass;

package/dist/infra/validation/create-zod-dto.js

@@ -0,0 +1,35 @@
+// Ported from octok-platform libs/common/src/validation/create-i18n-zod-dto.ts (owner-approved, 2026-10-28).
+import { z } from "zod";
+const registry = new Set();
+/** Every DTO created so far (the swagger document lists the named ones). */
+export function registeredZodDtos() {
+    return [...registry];
+}
+/**
+ * Creates a DTO class from a zod schema (nestjs-zod does not support Nest 12, so the kernel has its
+ * own, same shape as octok's `createI18nZodDto`). Use it as the metatype of `@Body()`, `@Query()`
+ * or `@Param()`: `class CreateX extends createZodDto(schema, "CreateX") {}`. The instance type is
+ * the schema's output type.
+ */
+export function createZodDto(schema, name) {
+    class ZodDto {
+        static schema = schema;
+        static dtoName = name;
+        static jsonSchema() {
+            return z.toJSONSchema(schema, { io: "input", unrepresentable: "any" });
+        }
+    }
+    registry.add(ZodDto);
+    return ZodDto;
+}
+/** The DTO's schema when `metatype` is one, else undefined. */
+export function zodSchemaOf(metatype) {
+    if (typeof metatype !== "function")
+        return undefined;
+    const s = metatype.schema;
+    return s instanceof z.ZodType ? s : undefined;
+}
+/** What `@ZBody` / `@ZQuery` / `@ZParam` hand to the global pipe as the argument's `data`. */
+export function isZodDto(value) {
+    return zodSchemaOf(value) !== undefined;
+}

package/dist/infra/validation/parse-with-zod.d.ts

@@ -0,0 +1,7 @@
+import type { z } from "zod";
+/**
+ * Parses `value` with a zod schema and returns the output (transforms and defaults applied); a
+ * failure throws `validation_failed` whose details list each issue's path and message. The
+ * implementation behind the global `ZodValidationPipe`.
+ */
+export declare function parseWithZod<S extends z.ZodType>(schema: S, value: unknown): z.infer<S>;

package/dist/infra/validation/parse-with-zod.js

@@ -0,0 +1,12 @@
+import { ApiError } from "../../errors.js";
+/**
+ * Parses `value` with a zod schema and returns the output (transforms and defaults applied); a
+ * failure throws `validation_failed` whose details list each issue's path and message. The
+ * implementation behind the global `ZodValidationPipe`.
+ */
+export function parseWithZod(schema, value) {
+    const r = schema.safeParse(value);
+    if (r.success)
+        return r.data;
+    throw new ApiError("validation_failed", "Request validation failed", r.error.issues.map((i) => ({ path: i.path.map(String).join("."), message: i.message })));
+}

package/dist/infra/validation/validation.module.d.ts

@@ -0,0 +1,3 @@
+/** Registers the global zod validation pipe. */
+export declare class ValidationModule {
+}

package/dist/infra/validation/validation.module.js

@@ -0,0 +1,16 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Module } from "@nestjs/common";
+import { APP_PIPE } from "@nestjs/core";
+import { ZodValidationPipe } from "./zod-validation.pipe.js";
+/** Registers the global zod validation pipe. */
+let ValidationModule = class ValidationModule {
+};
+ValidationModule = __decorate([
+    Module({ providers: [{ provide: APP_PIPE, useClass: ZodValidationPipe }] })
+], ValidationModule);
+export { ValidationModule };

package/dist/infra/validation/zod-params.d.ts

@@ -0,0 +1,7 @@
+import type { ZodDtoClass } from "./create-zod-dto.js";
+/** The request body, validated against the DTO's schema; the parameter is the schema's output. */
+export declare const ZBody: (dto: ZodDtoClass) => ParameterDecorator;
+/** The query string, validated against the DTO's schema; each property is a swagger query parameter. */
+export declare const ZQuery: (dto: ZodDtoClass) => ParameterDecorator;
+/** The path parameters, validated against the DTO's schema; each property is a swagger path parameter. */
+export declare const ZParam: (dto: ZodDtoClass) => ParameterDecorator;

package/dist/infra/validation/zod-params.js

@@ -0,0 +1,42 @@
+import { createParamDecorator } from "@nestjs/common";
+import { ApiBody, ApiParam, ApiQuery } from "@nestjs/swagger";
+// esbuild, tsx and the kernel's own tsc build emit no decorator metadata, so a parameter's type is
+// never visible to a pipe or to @nestjs/swagger. These decorators name the DTO explicitly: they
+// pass the raw request part through, hand the DTO to the global ZodValidationPipe as the argument's
+// `data`, and describe the parameter to swagger on the method.
+const part = (key) => createParamDecorator((_dto, ctx) => ctx.switchToHttp().getRequest()[key]);
+const body = part("body");
+const query = part("query");
+const params = part("params");
+function onMethod(decorators, target, key) {
+    if (key === undefined)
+        return;
+    const desc = Object.getOwnPropertyDescriptor(target, key);
+    if (desc === undefined)
+        return;
+    for (const d of decorators)
+        d(target, key, desc);
+}
+function perProperty(dto, make) {
+    const js = dto.jsonSchema();
+    const required = new Set(js.required ?? []);
+    return Object.entries(js.properties ?? {}).map(([name, schema]) => make({ name, required: required.has(name), schema }));
+}
+/** The request body, validated against the DTO's schema; the parameter is the schema's output. */
+export const ZBody = (dto) => (target, key, index) => {
+    body(dto)(target, key, index);
+    const schema = dto.dtoName === undefined
+        ? dto.jsonSchema()
+        : { $ref: `#/components/schemas/${dto.dtoName}` };
+    onMethod([ApiBody({ schema: schema })], target, key);
+};
+/** The query string, validated against the DTO's schema; each property is a swagger query parameter. */
+export const ZQuery = (dto) => (target, key, index) => {
+    query(dto)(target, key, index);
+    onMethod(perProperty(dto, ApiQuery), target, key);
+};
+/** The path parameters, validated against the DTO's schema; each property is a swagger path parameter. */
+export const ZParam = (dto) => (target, key, index) => {
+    params(dto)(target, key, index);
+    onMethod(perProperty(dto, ApiParam), target, key);
+};

package/dist/infra/validation/zod-validation.pipe.d.ts

@@ -0,0 +1,11 @@
+import { type ArgumentMetadata, type PipeTransform } from "@nestjs/common";
+/**
+ * Global pipe (`APP_PIPE`): validates the arguments declared with `@ZBody(Dto)` / `@ZQuery(Dto)` /
+ * `@ZParam(Dto)` (the DTO arrives as `metadata.data`; a parameter whose metatype is a DTO, where
+ * the build emits decorator metadata, is validated too) and returns the parse output (transforms
+ * and defaults applied). Failures are `validation_failed` ({@link parseWithZod}). Any
+ * other argument (primitives, the raw request, other custom decorators) passes untouched.
+ */
+export declare class ZodValidationPipe implements PipeTransform {
+    transform(value: unknown, metadata: ArgumentMetadata): unknown;
+}

package/dist/infra/validation/zod-validation.pipe.js

@@ -0,0 +1,31 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+// Ported from octok-platform libs/common/src/validation (owner-approved, 2026-10-28).
+import { Injectable } from "@nestjs/common";
+import { zodSchemaOf } from "./create-zod-dto.js";
+import { parseWithZod } from "./parse-with-zod.js";
+/**
+ * Global pipe (`APP_PIPE`): validates the arguments declared with `@ZBody(Dto)` / `@ZQuery(Dto)` /
+ * `@ZParam(Dto)` (the DTO arrives as `metadata.data`; a parameter whose metatype is a DTO, where
+ * the build emits decorator metadata, is validated too) and returns the parse output (transforms
+ * and defaults applied). Failures are `validation_failed` ({@link parseWithZod}). Any
+ * other argument (primitives, the raw request, other custom decorators) passes untouched.
+ */
+let ZodValidationPipe = class ZodValidationPipe {
+    transform(value, metadata) {
+        const schema = metadata.type === "custom"
+            ? zodSchemaOf(metadata.data)
+            : metadata.type === "body" || metadata.type === "query" || metadata.type === "param"
+                ? zodSchemaOf(metadata.metatype)
+                : undefined;
+        return schema === undefined ? value : parseWithZod(schema, value);
+    }
+};
+ZodValidationPipe = __decorate([
+    Injectable()
+], ZodValidationPipe);
+export { ZodValidationPipe };