@grest-ts/http 0.0.46 → 0.0.48

package/src/client/GGHttpSchema.createClient.ts

@@ -29,6 +29,7 @@ export type GGHttpTransport = (
         headers: Record<string, string>
         body: string | FormData | undefined
         signal: AbortSignal
+        credentials?: "omit" | "same-origin" | "include"
     }
 ) => Promise<Response>
 
@@ -36,6 +37,13 @@ export interface GGHttpClientConfig {
     url?: string;
     timeout?: number;
     noValidation?: boolean
+    /**
+     * Cross-origin credentials mode for the default fetch transport. Default
+     * (unset → fetch's "same-origin") is unchanged; pass "include" so the browser
+     * attaches/stores cross-origin cookies. Ignored by custom transports unless
+     * they read it.
+     */
+    credentials?: "omit" | "same-origin" | "include"
     /**
      * Override the wire-layer call. Defaults to `fetch`. When provided,
      * service discovery is skipped (the transport is presumed to know how
@@ -111,7 +119,8 @@ export function createClient<TContract extends GGContractApiDefinition, TContext
                     method: fetchRequest.method,
                     signal: controller.signal,
                     headers: fetchRequest.headers,
-                    body: fetchRequest.body
+                    body: fetchRequest.body,
+                    credentials: config.credentials
                 }).finally(() => clearTimeout(timeoutId));
                 const resData = await wireFormat.parseResponse(wireResponse);
 

package/src/index-browser.ts

@@ -2,6 +2,8 @@ import "./_dedupCheck";
 // API Schema
 export * from "./schema/GGHttpSchema";
 export * from "./schema/httpSchema";
+export * from "./schema/cookieMiddleware";
+export * from "./schema/headerBinding";
 export * from "./rpc/GGHttpRouteRPC";
 export * from "./rpc/RpcRequest/GGRpcRequestBuilder";
 export * from "./rpc/RpcResponse/GGRpcResponseParser";

package/src/index-node.ts

@@ -18,6 +18,8 @@ export * from "./server/GG_PERMISSIONS";
 // API Schema
 export * from "./schema/GGHttpSchema";
 export * from "./schema/httpSchema";
+export * from "./schema/cookieMiddleware";
+export * from "./schema/headerBinding";
 export * from "./rpc/GGHttpRouteRPC";
 export * from "./rpc/openApiSuccessResponse";
 export * from "./rpc/openApiHelpers";
@@ -31,6 +33,7 @@ export * from "./server/GGHttp";
 export * from "./server/GGHttp";
 export * from "./server/GGHttpServer";
 export * from "./server/GG_HTTP_SERVER";
+export * from "./server/applyResponseMiddleware";
 
 // Client
 export * from "./client/GGHttpSchema.createClient";

package/src/rpc/GGHttpRouteRPC.ts

@@ -2,6 +2,7 @@ import {HttpMethod} from "@grest-ts/common"
 import {ClientHttpRouteToRpcTransformClientCodec, ClientHttpRouteToRpcTransformClientConfig, ClientHttpRouteToRpcTransformServerCodec, ClientHttpRouteToRpcTransformServerConfig, GGHttpCodec, GGHttpCodecOpenApiConfig} from "../schema/GGHttpSchema"
 import {GGRpcRequestBuilder} from "./RpcRequest/GGRpcRequestBuilder";
 import {GGRpcResponseParser} from "./RpcResponse/GGRpcResponseParser";
+import type {GGContextKey} from "@grest-ts/context";
 import type {OpenAPIV3_1} from "openapi-types";
 import {GGSchema} from "@grest-ts/schema";
 import {buildRpcSuccessResponses} from "./openApiSuccessResponse";
@@ -28,6 +29,7 @@ class GGHttpRpcCodec implements GGHttpCodec {
     public readonly path: string
     public readonly deprecated: boolean | undefined
     public readonly responseHeaders: Record<string, GGSchema<string | undefined>> = {}
+    public readonly updatesCookies: GGContextKey<string | undefined>[] = []
 
     constructor(method: HttpMethod, path: string, deprecated?: boolean) {
         this.method = method
@@ -35,6 +37,12 @@ class GGHttpRpcCodec implements GGHttpCodec {
         this.deprecated = deprecated
     }
 
+    /** Permit this route to set/clear the given cookie context key(s). Reading needs no declaration. */
+    public updatesCookie(...keys: GGContextKey<string | undefined>[]): this {
+        this.updatesCookies.push(...keys)
+        return this
+    }
+
     public createForClient(config: ClientHttpRouteToRpcTransformClientConfig): ClientHttpRouteToRpcTransformClientCodec {
         return {
             createRequest: new GGRpcRequestBuilder(this.method, this.path, config).createRequest,

package/src/rpc/RpcResponse/GGRpcResponseBuilder.ts

@@ -1,14 +1,17 @@
 import type http from "http";
 import {ANY_ERROR, ERROR, GGContractExecutor, GGContractMethod, GGDebugData, GGErrorData, GGSchema, OK} from "@grest-ts/schema";
-import {ClientHttpRouteToRpcTransformServerConfig} from "../../schema/GGHttpSchema";
+import {ClientHttpRouteToRpcTransformServerConfig, GGHttpTransportMiddleware} from "../../schema/GGHttpSchema";
+import {applyResponseMiddleware} from "../../server/applyResponseMiddleware";
 
 
 export class GGRpcResponseBuilder {
 
     protected readonly contract: GGContractMethod
+    private readonly apiMiddlewares: readonly GGHttpTransportMiddleware[]
 
     constructor(config: ClientHttpRouteToRpcTransformServerConfig) {
         this.contract = config.contract;
+        this.apiMiddlewares = config.apiMiddlewares;
     }
 
     public sendResponse = async (res: http.ServerResponse, rpcResult: ERROR<string, unknown> | OK<unknown>): Promise<void> => {
@@ -25,6 +28,7 @@ export class GGRpcResponseBuilder {
             json = this.makeError(GGContractExecutor.getResponseSchema(this.contract, rpcResult), rpcResult);
             statusCode = rpcResult.statusCode;
         }
+        applyResponseMiddleware(res, this.apiMiddlewares);
         res.writeHead(statusCode, {
             'Content-Type': 'application/json',
             'Content-Length': Buffer.byteLength(json)

package/src/schema/GGHttpSchema.ts

@@ -2,6 +2,7 @@ import {ERROR, ERROR_JSON, GGContractApiDefinition, GGContractClass, GGContractM
 import type {HttpMethod} from "@grest-ts/common";
 import type http from "http";
 import type {GGHttpServerMiddleware} from "../server/GGHttpSchema.startServer";
+import type {GGContextKey} from "@grest-ts/context";
 import type {OpenAPIV3_1} from "openapi-types";
 
 export class GGHttpSchema<TContract extends GGContractApiDefinition, TContext> {
@@ -114,6 +115,13 @@ export interface GGHttpCodec {
      */
     readonly responseHeaders: Record<string, GGSchema<string | undefined>>;
 
+    /**
+     * Cookie context keys this route is permitted to modify (set/clear), declared via
+     * GGRpc.*(...).updatesCookie(key). A handler that changes a cookie its route did not
+     * declare is a SERVER_ERROR. Reading a cookie needs no declaration.
+     */
+    readonly updatesCookies?: readonly GGContextKey<string | undefined>[];
+
     createForClient(config: ClientHttpRouteToRpcTransformClientConfig): ClientHttpRouteToRpcTransformClientCodec
 
     createForServer(config: ClientHttpRouteToRpcTransformServerConfig): ClientHttpRouteToRpcTransformServerCodec
@@ -156,6 +164,13 @@ export interface GGHttpTransportMiddleware {
      */
     readonly responseHeaders: Record<string, GGSchema<string | undefined>>;
 
+    /**
+     * Cookies this middleware reads, mapped to their value schemas. Emitted as `in: cookie`
+     * parameters in OpenAPI so cookie-bound inputs are documented. Absent for header/plain
+     * middlewares.
+     */
+    readonly cookieParams?: Record<string, GGSchema<string | undefined>>;
+
     /**
      * Client-side: modify outgoing request (add headers, etc.)
      */

package/src/schema/cookieMiddleware.ts

@@ -0,0 +1,164 @@
+import {GGContextKey} from "@grest-ts/context"
+import {IsAny, IsString, SERVER_ERROR, type GGSchema} from "@grest-ts/schema"
+import type {GGHttpRequest, GGHttpResponse, GGHttpTransportMiddleware} from "./GGHttpSchema"
+
+/**
+ * Per-request set of context-key names the current route is permitted to write a cookie
+ * for (declared via GGRpc.*(...).updatesCookie(key)). Populated by the server route
+ * handler; read by setCookie() to reject undeclared cookie writes.
+ */
+export const GG_COOKIE_WRITES = new GGContextKey<Set<string>>("cookie:writes", IsAny as unknown as GGSchema<Set<string>>)
+
+/**
+ * Cookie write rules — passed to setCookie(key, value, options). They live at the write
+ * call site (the handler that mints the cookie), never in the shared API.
+ */
+export interface CookieOptions {
+    httpOnly?: boolean
+    secure?: boolean
+    sameSite?: "lax" | "strict" | "none"
+    path?: string
+    domain?: string
+    maxAgeSec?: number
+}
+
+const SAFE_DEFAULTS = {httpOnly: true, secure: true, sameSite: "lax", path: "/"} as const
+
+interface PendingCookie {
+    value: string | undefined
+    options?: CookieOptions
+}
+
+/**
+ * Per-request Set-Cookie writes scheduled via setCookie()/clearCookie(), keyed by the
+ * context key's name. Flushed onto the response by the matching cookie() binding.
+ */
+const GG_COOKIE_PENDING = new GGContextKey<Map<string, PendingCookie>>("cookie:pending", IsAny as unknown as GGSchema<Map<string, PendingCookie>>)
+
+// Reject anything that could break out of the Set-Cookie line / inject attributes.
+function assertCookieSafe(label: string, value: string): void {
+    if (/[\x00-\x1f;]/.test(value)) {
+        throw new Error(`Cookie ${label} contains illegal characters (control chars or ';'): ${JSON.stringify(value)}`)
+    }
+}
+
+/**
+ * Read a single named cookie out of a raw `Cookie` header value. Shared by the HTTP
+ * binding (parseRequest) and the WebSocket binding (parseHandshake). A malformed
+ * percent-encoding (e.g. "sid=%") must not crash — fall back to the raw value.
+ */
+export function readCookie(rawCookieHeader: string | undefined, name: string): string | undefined {
+    if (typeof rawCookieHeader !== "string") return undefined
+    for (const part of rawCookieHeader.split(";")) {
+        const eq = part.indexOf("=")
+        if (eq === -1) continue
+        if (part.slice(0, eq).trim() === name) {
+            const rawValue = part.slice(eq + 1).trim()
+            try {
+                return decodeURIComponent(rawValue)
+            } catch {
+                return rawValue
+            }
+        }
+    }
+    return undefined
+}
+
+function serializeSetCookie(name: string, value: string | undefined, options?: CookieOptions): string {
+    const o = {...SAFE_DEFAULTS, ...options}
+    const secure = o.sameSite === "none" ? true : o.secure
+    const sameSite = `${o.sameSite.charAt(0).toUpperCase()}${o.sameSite.slice(1)}`
+    const attrs = `; Path=${o.path}${o.domain ? `; Domain=${o.domain}` : ""}; SameSite=${sameSite}${secure ? "; Secure" : ""}${o.httpOnly ? "; HttpOnly" : ""}`
+    return value
+        ? `${name}=${encodeURIComponent(value)}${o.maxAgeSec !== undefined ? `; Max-Age=${Math.trunc(o.maxAgeSec)}` : ""}${attrs}`
+        : `${name}=; Max-Age=0${attrs}`
+}
+
+/**
+ * Local structural copy of GGWebSocketHandshakeContext (defined in @grest-ts/websocket).
+ * http must not import websocket; cookie()'s WS half is typed against this shape and
+ * matches GGWebSocketMiddleware structurally at the webSocketSchema.use() call site.
+ * `upgradeHeaders` is the real browser upgrade request (carries httpOnly cookies); the
+ * in-band `headers` map cannot spoof it.
+ */
+interface WsHandshakeContextLike {
+    headers: Record<string, string>
+    upgradeHeaders?: Record<string, string>
+    queryArgs: Record<string, string>
+}
+
+export interface GGCookieBinding extends GGHttpTransportMiddleware {
+    /** The cookie this binding reads, mapped to its value schema — emitted as an `in: cookie` doc param. */
+    readonly cookieParams: Record<string, GGSchema<string | undefined>>
+    parseHandshake(ctx: WsHandshakeContextLike): void
+}
+
+/**
+ * Bind a context key to a cookie, read-only on the wire. Reads ONLY the named cookie —
+ * never a header — from the incoming HTTP Cookie (parseRequest) or the real WS upgrade
+ * Cookie (parseHandshake), into key.get(). The cookie's wire name defaults to the key's
+ * name. To write the cookie, call setCookie(key, …) from a route that declared
+ * .updatesCookie(key); the matching binding flushes it as Set-Cookie (HTTP only — a
+ * WebSocket has no response to set a cookie on).
+ */
+export function cookie(key: GGContextKey<string | undefined>, opts?: {name?: string; schema?: GGSchema<string | undefined>}): GGCookieBinding {
+    const cookieName = opts?.name ?? key.name
+    assertCookieSafe("name", cookieName)
+    return {
+        headers: {},
+        responseHeaders: {},
+        cookieParams: {[cookieName]: opts?.schema ?? IsString.orUndefined},
+        parseRequest(req: GGHttpRequest): void {
+            const raw = req.headers?.["cookie"]
+            const value = readCookie(typeof raw === "string" ? raw : undefined, cookieName)
+            if (value !== undefined) key.set(value)
+        },
+        updateResponse(res: GGHttpResponse): void {
+            const pending = GG_COOKIE_PENDING.get()?.get(key.name)
+            if (pending === undefined) return
+            const line = serializeSetCookie(cookieName, pending.value, pending.options)
+            const existing = res.headers["set-cookie"]
+            const arr = existing === undefined ? [] : Array.isArray(existing) ? existing : [existing]
+            arr.push(line)
+            res.headers["set-cookie"] = arr
+        },
+        parseHandshake(ctx: WsHandshakeContextLike): void {
+            const value = readCookie(ctx.upgradeHeaders?.["cookie"], cookieName)
+            if (value !== undefined) key.set(value)
+        },
+    }
+}
+
+/**
+ * Schedule a Set-Cookie on the response (HTTP only). The value never touches key.get() —
+ * inbound reads stay set-once. The route must declare .updatesCookie(key); an undeclared
+ * call is invalid usage and throws SERVER_ERROR. The matching cookie() binding serializes
+ * the pending write with these options (HttpOnly/Secure/SameSite/Path/Domain/Max-Age).
+ */
+export function setCookie(key: GGContextKey<string | undefined>, value: string | undefined, options?: CookieOptions): void {
+    if (options) {
+        if (options.maxAgeSec !== undefined && !Number.isFinite(options.maxAgeSec)) {
+            throw new Error(`setCookie("${key.name}"): maxAgeSec must be a finite number, got ${options.maxAgeSec}.`)
+        }
+        if (options.path !== undefined) assertCookieSafe("path", options.path)
+        if (options.domain !== undefined) assertCookieSafe("domain", options.domain)
+    }
+    if (!GG_COOKIE_WRITES.get()?.has(key.name)) {
+        throw new SERVER_ERROR({debugMessage: `setCookie("${key.name}") was called, but this route did not declare .updatesCookie(<key>). Only routes that declare it may set or clear the cookie.`})
+    }
+    let pending = GG_COOKIE_PENDING.get()
+    if (pending === undefined) {
+        pending = new Map()
+        GG_COOKIE_PENDING.set(pending)
+    }
+    pending.set(key.name, {value, options})
+}
+
+/**
+ * Clear the cookie — schedules a Set-Cookie with Max-Age=0. Pass path/domain to match a
+ * scoped cookie (deletion only works when path+domain match what was set). Equivalent to
+ * setCookie(key, undefined, options), but reads clearer at logout-style call sites.
+ */
+export function clearCookie(key: GGContextKey<string | undefined>, options?: CookieOptions): void {
+    setCookie(key, undefined, options)
+}

package/src/schema/headerBinding.ts

@@ -0,0 +1,65 @@
+import {GGContextKey} from "@grest-ts/context"
+import {IsString, type GGSchema} from "@grest-ts/schema"
+import type {GGHttpRequest, GGHttpTransportMiddleware} from "./GGHttpSchema"
+
+/**
+ * Local structural copy of GGWebSocketHandshakeContext (defined in @grest-ts/websocket).
+ * http must not import websocket; header()'s WS half is typed against this shape and
+ * matches GGWebSocketMiddleware structurally at the webSocketSchema.use() call site.
+ * `headers` is the in-band handshake bag (client-set, spoofable — same trust level as an
+ * HTTP request header).
+ */
+interface WsHandshakeContextLike {
+    headers: Record<string, string>
+    upgradeHeaders?: Record<string, string>
+    queryArgs: Record<string, string>
+}
+
+export interface GGHeaderBinding extends GGHttpTransportMiddleware {
+    parseHandshake(ctx: WsHandshakeContextLike): void
+    updateHandshake(ctx: WsHandshakeContextLike): void
+}
+
+const BEARER = "Bearer "
+
+/**
+ * Bind a context key to a single named header, on both transports. Reads ONLY that header
+ * — never a cookie — from the HTTP request (parseRequest) or the in-band WS handshake
+ * (parseHandshake) into key.get(), and writes it from key.get() on the client (HTTP
+ * updateRequest / WS updateHandshake). `scheme: "bearer"` strips/adds the `Bearer ` prefix;
+ * default is verbatim. The wire name defaults to the key's name (lowercased — HTTP headers
+ * are case-insensitive). Client-attachable, so it is the service-to-service variant (a
+ * Node client can carry it; a browser cookie cannot).
+ */
+export function header(key: GGContextKey<string | undefined>, opts?: {name?: string; scheme?: "bearer"; schema?: GGSchema<string | undefined>}): GGHeaderBinding {
+    const name = (opts?.name ?? key.name).toLowerCase()
+    const bearer = opts?.scheme === "bearer"
+    const unwrap = (raw: string | undefined): string | undefined => {
+        if (raw === undefined) return undefined
+        return bearer && raw.startsWith(BEARER) ? raw.slice(BEARER.length) : raw
+    }
+    const wrap = (value: string): string => bearer ? `${BEARER}${value}` : value
+    return {
+        headers: {[name]: opts?.schema ?? IsString.orUndefined},
+        responseHeaders: {},
+        parseRequest(req: GGHttpRequest): void {
+            const raw = req.headers?.[name]
+            const value = unwrap(typeof raw === "string" ? raw : Array.isArray(raw) ? raw[0] : undefined)
+            if (value !== undefined) key.set(value)
+        },
+        updateRequest(req: GGHttpRequest): void {
+            const value = key.get()
+            if (value === undefined) return
+            req.headers = req.headers ?? {}
+            req.headers[name] = wrap(value)
+        },
+        parseHandshake(ctx: WsHandshakeContextLike): void {
+            const value = unwrap(ctx.headers?.[name])
+            if (value !== undefined) key.set(value)
+        },
+        updateHandshake(ctx: WsHandshakeContextLike): void {
+            const value = key.get()
+            if (value !== undefined) ctx.headers[name] = wrap(value)
+        },
+    }
+}

package/src/schema/httpSchema.ts

@@ -1,8 +1,6 @@
-import type http from "http";
 import {GGHttpCodec, GGHttpSchema} from "./GGHttpSchema";
-import {GGHttpRequest, GGHttpTransportMiddleware} from "./GGHttpSchema";
-import {GGContractApiDefinition, GGContractClass, GGSchema} from "@grest-ts/schema";
-import {GGContextKey} from "@grest-ts/context";
+import {GGHttpTransportMiddleware} from "./GGHttpSchema";
+import {GGContractApiDefinition, GGContractClass} from "@grest-ts/schema";
 
 /**
  * Create an HTTP API schema builder from a contract.
@@ -54,57 +52,6 @@ class GGHttpSchemaBuilder<TContract extends GGContractApiDefinition, TContext =
         return this as unknown as GGHttpSchemaBuilder<TContract, TContext | M>
     }
 
-    useHeader<Input>(contextKey: GGContextKey<Input>): GGHttpSchemaBuilder<TContract, TContext | Input> {
-        const codec = contextKey.getCodec("http");
-        if (!codec) {
-            throw new Error(`Context key '${contextKey.name}' does not have an 'http-header' codec registered.`);
-        }
-
-        // Build the typed header map from codec.inputSchema — the IsObject({headerName: schema})
-        // that describes which headers this codec reads and what format each value has.
-        const inputSchema = codec.inputSchema;
-        const headers: Record<string, GGSchema<string | undefined>> = {};
-        if (inputSchema) {
-            const desc = inputSchema.toSchemaDescription();
-            if (desc.node.kind === 'object') {
-                for (const [k, fieldDesc] of Object.entries(desc.node.properties)) {
-                    headers[k] = fieldDesc.schema as GGSchema<string | undefined>;
-                }
-            }
-        }
-
-        const middleware: GGHttpTransportMiddleware = {
-            headers,
-            responseHeaders: {},
-            updateRequest(req: GGHttpRequest) {
-                const contextValue = contextKey.get();
-                if (contextValue !== undefined) {
-                    const result = codec.decode(contextValue);
-                    if (result.success) {
-                        Object.assign(req.headers, result.value);
-                    }
-                } else {
-                    const emptyResult = codec.decode({} as Input);
-                    if (emptyResult.success) {
-                        for (const key of Object.keys(emptyResult.value as object)) {
-                            delete req.headers[key];
-                        }
-                    }
-                }
-            },
-            parseRequest(req: http.IncomingMessage) {
-                const headers = req.headers as Record<string, string>;
-                const result = codec.encode(headers);
-                if (result.success) {
-                    contextKey.set(result.value);
-                }
-            }
-        };
-
-        this._middlewares.push(middleware);
-        return this as unknown as GGHttpSchemaBuilder<TContract, TContext | Input>;
-    }
-
     routes(mapping: { [K in keyof TContract]: GGHttpCodec }): GGHttpSchema<TContract, TContext> {
         return new GGHttpSchema(this._pathPrefix, this._contract, mapping, this._middlewares)
     }

package/src/server/GGHttpSchema.startServer.ts

@@ -12,6 +12,7 @@ import {GG_DISCOVERY} from "@grest-ts/discovery";
 import {GGContext, GGContextStore} from "@grest-ts/context";
 import {GG_TRACE} from "@grest-ts/trace";
 import {GG_HTTP_REQUEST} from "./GG_HTTP_REQUEST";
+import {GG_COOKIE_WRITES} from "../schema/cookieMiddleware";
 import {GG_METRICS} from "@grest-ts/metrics";
 import {GGHttpMetrics} from "./GGHttpMetrics";
 import {GG_HTTP_SERVER} from "./GG_HTTP_SERVER";
@@ -127,11 +128,13 @@ function setupRoutes<TContract extends GGContractApiDefinition>(
             apiMiddlewares: apiMiddlewares,
             serverMiddlewares: config.middlewares
         })
+        const cookieWriteNames = new Set((codec.updatesCookies ?? []).map(k => k.name))
         server.registerRoute(codec.method, pathPrefix + codec.path, async (req: http.IncomingMessage, res: http.ServerResponse): Promise<void> => {
             scope.ensureEntered();
-            return new GGContext("REQ", parentContext).run(async () => {
+            return new GGContext("REQ", parentContext, true).run(async () => {
                 GG_TRACE.init();
                 GG_HTTP_REQUEST.set({port: server.port, method: req.method, path: req.url});
+                GG_COOKIE_WRITES.set(cookieWriteNames);
                 const startTime = performance.now()
                 let rpcResult: ERROR<string, unknown> | OK<unknown>
                 try {

package/src/server/GGHttpServer.ts

@@ -17,9 +17,31 @@ type AnyWebSocketSchema = {
     connectPermission?: GGPermission;
 };
 
+export interface GGCorsConfig {
+    /**
+     * Allowed cross-origin origins. Either an exact-match list or a predicate.
+     * Only a matching Origin is echoed back — an arbitrary origin is never
+     * reflected (that would be a credential-leak / CSRF hole with credentials on).
+     */
+    origins: string[] | ((origin: string) => boolean);
+    /**
+     * When true, adds Access-Control-Allow-Credentials: true so the browser will
+     * send/store cross-origin cookies. Requires an exact-origin echo (never `*`),
+     * which this enforces by construction.
+     */
+    credentials?: boolean;
+}
+
 export interface GGHttpServerAdapterConfig {
     key?: GGLocatorKey<GGHttpServer>;
     port?: number;
+    /**
+     * Cross-origin policy. Omitted (default) keeps the permissive
+     * `Access-Control-Allow-Origin: *` with no credentials — backward compatible.
+     * When set, switches to allowlisted mode: only an Origin in `origins` is echoed
+     * (never `*`), and `credentials: true` enables cross-origin cookies.
+     */
+    cors?: GGCorsConfig;
     /**
      * If provided, the server listens over HTTPS using this cert+key. Both
      * must be PEM-encoded strings or Buffers. Leaving undefined keeps the
@@ -41,6 +63,7 @@ export class GGHttpServer {
     protected readonly scope: GGLocatorScope;
     protected readonly runtimeName: string;
     private readonly configuredPort: number;
+    private readonly cors?: GGCorsConfig;
 
     private readonly _onStart: Array<() => void> = [];
     private readonly _onTeardown: Array<() => void> = [];
@@ -75,6 +98,7 @@ export class GGHttpServer {
         this.runtimeName = GGLocator.getScope().serviceName;
         this.scope = GGLocator.getScope();
         this.configuredPort = config?.port ?? (process.env.PORT ? Number(process.env.PORT) : 0);
+        this.cors = config?.cors;
 
         GGLocator.getScope().setWithLifecycle(config?.key ?? GG_HTTP_SERVER, this, {
             type: GGLocatorServiceType.HTTP,
@@ -90,14 +114,8 @@ export class GGHttpServer {
             }
             this.activeRequests++;
             try {
-                if (req.headers.origin) { // For browsers
-                    res.setHeader('Access-Control-Allow-Origin', '*');
-                    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS');
-                    res.setHeader('Access-Control-Allow-Headers', this._corsHeadersCache);
-                    if (this._corsExposeHeadersCache) {
-                        res.setHeader('Access-Control-Expose-Headers', this._corsExposeHeadersCache);
-                    }
-                }
+                const cors = corsResponseHeaders(req.headers.origin, this.cors, this._corsHeadersCache, this._corsExposeHeadersCache);
+                for (const name in cors) res.setHeader(name, cors[name]);
                 if (req.method === 'OPTIONS') {
                     res.writeHead(204);
                     res.end();
@@ -313,3 +331,34 @@ export class GGHttpServer {
 }
 
 export type GGHttpRequestCallback = (req: http.IncomingMessage, res: http.ServerResponse) => Promise<void>;
+
+/**
+ * Computes CORS response headers for a request Origin. Pure (no req/res) so it is
+ * unit-testable. Default (no config) = permissive `*`, no credentials. With config =
+ * allowlisted: only a matching Origin is echoed (never `*`), `credentials` adds
+ * Allow-Credentials, and Vary: Origin is always set so caches key on the origin.
+ */
+export function corsResponseHeaders(
+    origin: string | undefined,
+    cors: GGCorsConfig | undefined,
+    allowHeaders: string,
+    exposeHeaders: string
+): Record<string, string> {
+    if (!origin) return {};
+    const headers: Record<string, string> = {};
+    if (cors) {
+        // Never reflect the literal "null" origin (sandboxed iframe / file:// / opaque
+        // origins) with credentials — the classic null-origin credential-leak footgun.
+        const allowed = origin !== "null" && (Array.isArray(cors.origins) ? cors.origins.includes(origin) : cors.origins(origin));
+        headers['Vary'] = 'Origin';
+        if (!allowed) return headers;
+        headers['Access-Control-Allow-Origin'] = origin;
+        if (cors.credentials) headers['Access-Control-Allow-Credentials'] = 'true';
+    } else {
+        headers['Access-Control-Allow-Origin'] = '*';
+    }
+    headers['Access-Control-Allow-Methods'] = 'GET, POST, PUT, PATCH, DELETE, OPTIONS';
+    headers['Access-Control-Allow-Headers'] = allowHeaders;
+    if (exposeHeaders) headers['Access-Control-Expose-Headers'] = exposeHeaders;
+    return headers;
+}

package/src/server/applyResponseMiddleware.ts

@@ -0,0 +1,27 @@
+import type http from "http";
+import type {GGHttpResponse, GGHttpTransportMiddleware} from "../schema/GGHttpSchema";
+
+/**
+ * Runs the transport chain's server-side response hook and writes the collected
+ * headers onto the Node response. Applied via setHeader (not writeHead) so a
+ * string[] value emits one header line per element — the only way to send
+ * multiple Set-Cookie headers — and so the codec's later writeHead(Content-*)
+ * merges rather than clobbers. Must run inside the request GGContext so a
+ * middleware can read per-request staged state.
+ */
+export function applyResponseMiddleware(
+    res: http.ServerResponse,
+    middlewares: readonly GGHttpTransportMiddleware[] | undefined
+): void {
+    if (!middlewares?.length || res.headersSent) return;
+    let response: GGHttpResponse | undefined;
+    for (const mw of middlewares) {
+        if (!mw.updateResponse) continue;
+        response ??= {headers: {}};
+        mw.updateResponse(response);
+    }
+    if (!response) return;
+    for (const name in response.headers) {
+        res.setHeader(name, response.headers[name]);
+    }
+}