@grest-ts/http 0.0.47 → 0.0.49

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grest-ts/http",
-  "version": "0.0.47",
+  "version": "0.0.49",
   "type": "module",
   "license": "MIT",
   "description": "HTTP server and client library for Node.js and browser",
@@ -25,7 +25,10 @@
     "src"
   ],
   "scripts": {
-    "typecheck": "tsc --noEmit -p src"
+    "typecheck": "tsc --noEmit -p src",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:coverage:html": "vitest run --coverage --reporter=html"
   },
   "publishConfig": {
     "access": "public"
@@ -58,16 +61,16 @@
     "find-my-way": "^9.4.0"
   },
   "peerDependencies": {
-    "@grest-ts/common": "0.0.47",
-    "@grest-ts/context": "0.0.47",
-    "@grest-ts/discovery": "0.0.47",
-    "@grest-ts/locator": "0.0.47",
-    "@grest-ts/logger": "0.0.47",
-    "@grest-ts/metrics": "0.0.47",
-    "@grest-ts/schema": "0.0.47",
-    "@grest-ts/trace": "0.0.47"
+    "@grest-ts/common": "0.0.49",
+    "@grest-ts/context": "0.0.49",
+    "@grest-ts/discovery": "0.0.49",
+    "@grest-ts/locator": "0.0.49",
+    "@grest-ts/logger": "0.0.49",
+    "@grest-ts/metrics": "0.0.49",
+    "@grest-ts/schema": "0.0.49",
+    "@grest-ts/trace": "0.0.49"
   },
   "devDependencies": {
-    "@grest-ts/testkit": "0.0.47"
+    "@grest-ts/testkit": "0.0.49"
   }
 }

package/src/_dedupCheck.ts

@@ -12,7 +12,7 @@
 const __KEY = Symbol.for("grest-ts:dedup:@grest-ts/http");
 const __slot = globalThis as Record<symbol, unknown>;
 const __existing = __slot[__KEY] as { path: string; version: string } | undefined;
-const __here = { path: import.meta.url, version: "0.0.47" };
+const __here = { path: import.meta.url, version: "0.0.49" };
 // Same path + same version means the same physical package is being
 // re-evaluated by a different ESM runner (e.g. vitest projects share one
 // process but each project has its own module cache). That isn't a true

package/src/client/GGContextKeySynchronizer.test.ts

@@ -0,0 +1,106 @@
+import {describe, it, expect, vi} from 'vitest'
+import {GGContext} from '@grest-ts/context'
+import {GGContextKey} from '@grest-ts/context'
+import {GGContextKeySynchronizer} from './GGContextKeySynchronizer'
+import {IsString} from '@grest-ts/schema'
+
+const KEY_A = new GGContextKey<string | undefined>('sync-test:a', IsString.orUndefined)
+const KEY_B = new GGContextKey<string | undefined>('sync-test:b', IsString.orUndefined)
+
+function inContext<T>(fn: () => Promise<T>): Promise<T> {
+    return new GGContext('test').run(fn)
+}
+
+describe('GGContextKeySynchronizer', () => {
+
+    describe('waitFor — no controller', () => {
+        it('resolves immediately when no controller is registered', async () => {
+            await inContext(async () => {
+                await expect(GGContextKeySynchronizer.waitFor(KEY_A)).resolves.toBeUndefined()
+            })
+        })
+    })
+
+    describe('waitFor — not stale', () => {
+        it('does not call recover when isStale returns false', async () => {
+            await inContext(async () => {
+                const recover = vi.fn().mockResolvedValue(undefined)
+                GGContextKeySynchronizer.provide(KEY_A, {isStale: () => false, recover})
+                await GGContextKeySynchronizer.waitFor(KEY_A)
+                expect(recover).not.toHaveBeenCalled()
+            })
+        })
+    })
+
+    describe('waitFor — stale once', () => {
+        it('calls recover once and after it resolves a second waitFor does not call recover again', async () => {
+            await inContext(async () => {
+                let stale = true
+                const recover = vi.fn(async () => { stale = false })
+                GGContextKeySynchronizer.provide(KEY_A, {isStale: () => stale, recover})
+
+                await GGContextKeySynchronizer.waitFor(KEY_A)
+                expect(recover).toHaveBeenCalledTimes(1)
+
+                await GGContextKeySynchronizer.waitFor(KEY_A)
+                expect(recover).toHaveBeenCalledTimes(1)
+            })
+        })
+    })
+
+    describe('waitFor — coalescing', () => {
+        it('fires recover exactly once for 5 concurrent waitFor calls', async () => {
+            await inContext(async () => {
+                let resolveRecover!: () => void
+                const recoverDone = new Promise<void>(res => { resolveRecover = res })
+                const recover = vi.fn(() => recoverDone)
+
+                GGContextKeySynchronizer.provide(KEY_B, {isStale: () => true, recover})
+
+                const waits = Promise.all([
+                    GGContextKeySynchronizer.waitFor(KEY_B),
+                    GGContextKeySynchronizer.waitFor(KEY_B),
+                    GGContextKeySynchronizer.waitFor(KEY_B),
+                    GGContextKeySynchronizer.waitFor(KEY_B),
+                    GGContextKeySynchronizer.waitFor(KEY_B),
+                ])
+
+                resolveRecover()
+                await waits
+                expect(recover).toHaveBeenCalledTimes(1)
+            })
+        })
+    })
+
+    describe('waitFor — recover rejects', () => {
+        it('rejects waitFor when recover rejects, then clears inflight so next call can retry', async () => {
+            await inContext(async () => {
+                let callCount = 0
+                const recover = vi.fn(async () => {
+                    callCount++
+                    if (callCount === 1) throw new Error('refresh failed')
+                })
+
+                GGContextKeySynchronizer.provide(KEY_A, {isStale: () => true, recover})
+
+                await expect(GGContextKeySynchronizer.waitFor(KEY_A)).rejects.toThrow('refresh failed')
+                expect(recover).toHaveBeenCalledTimes(1)
+
+                await expect(GGContextKeySynchronizer.waitFor(KEY_A)).resolves.toBeUndefined()
+                expect(recover).toHaveBeenCalledTimes(2)
+            })
+        })
+    })
+
+    describe('clear', () => {
+        it('removes the controller so subsequent waitFor is a no-op', async () => {
+            await inContext(async () => {
+                const recover = vi.fn().mockResolvedValue(undefined)
+                GGContextKeySynchronizer.provide(KEY_A, {isStale: () => true, recover})
+                GGContextKeySynchronizer.clear(KEY_A)
+                await GGContextKeySynchronizer.waitFor(KEY_A)
+                expect(recover).not.toHaveBeenCalled()
+            })
+        })
+    })
+})

package/src/client/GGContextKeySynchronizer.ts

@@ -0,0 +1,42 @@
+import {GGContextKey} from "@grest-ts/context"
+import {IsAny, type GGSchema} from "@grest-ts/schema"
+
+export interface GGKeyController {
+    isStale: () => boolean
+    recover: () => Promise<void>
+}
+
+interface ControllerEntry {
+    controller: GGKeyController
+    inflight: Promise<void> | undefined
+}
+
+const GG_SYNC_CONTROLLERS = new GGContextKey<Map<string, ControllerEntry>>(
+    "sync:controllers",
+    IsAny as unknown as GGSchema<Map<string, ControllerEntry>>
+)
+
+export class GGContextKeySynchronizer {
+
+    static provide(key: GGContextKey<any>, controller: GGKeyController): void {
+        let registry = GG_SYNC_CONTROLLERS.get()
+        if (registry === undefined) {
+            registry = new Map()
+            GG_SYNC_CONTROLLERS.set(registry)
+        }
+        registry.set(key.name, {controller, inflight: undefined})
+    }
+
+    static async waitFor(key: GGContextKey<any>): Promise<void> {
+        const entry = GG_SYNC_CONTROLLERS.get()?.get(key.name)
+        if (entry === undefined || !entry.controller.isStale()) return
+        entry.inflight ??= entry.controller.recover().finally(() => {
+            entry.inflight = undefined
+        })
+        await entry.inflight
+    }
+
+    static clear(key: GGContextKey<any>): void {
+        GG_SYNC_CONTROLLERS.get()?.delete(key.name)
+    }
+}

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,11 +2,15 @@ import "./_dedupCheck";
 // API Schema
 export * from "./schema/GGHttpSchema";
 export * from "./schema/httpSchema";
+export * from "./schema/GGCookie";
+export * from "./schema/GGWireContextKey";
+export * from "./schema/GGHeader";
 export * from "./rpc/GGHttpRouteRPC";
 export * from "./rpc/RpcRequest/GGRpcRequestBuilder";
 export * from "./rpc/RpcResponse/GGRpcResponseParser";
 
 // Client
+export * from "./client/GGContextKeySynchronizer";
 export * from "./client/GGHttpSchema.createClient";
 
 // Extensions

package/src/index-node.ts

@@ -3,21 +3,29 @@ import "./_dedupCheck";
 import {_registerRpcServerCodecFactory} from "./rpc/GGHttpRouteRPC";
 import {GGRpcResponseBuilder} from "./rpc/RpcResponse/GGRpcResponseBuilder";
 import {GGRpcRequestParser} from "./rpc/RpcRequest/GGRpcRequestParser";
-_registerRpcServerCodecFactory((method, path, config) => ({
-    parseRequest: new GGRpcRequestParser(method, path, config).parseRequest,
-    sendResponse: new GGRpcResponseBuilder(config).sendResponse
-}));
+
+_registerRpcServerCodecFactory((method, path, config) => {
+    const parser = new GGRpcRequestParser(method, path, config);
+    return {
+        readRequest: parser.readRequest,
+        validateInput: parser.validateInput,
+        sendResponse: new GGRpcResponseBuilder(config).sendResponse
+    };
+});
 
 // Metrics
 export * from "./server/GGHttpMetrics";
 
 // Context
 export * from "./server/GG_HTTP_REQUEST";
-export * from "./server/GG_PERMISSIONS";
 
 // API Schema
 export * from "./schema/GGHttpSchema";
 export * from "./schema/httpSchema";
+export * from "./schema/GGCookie";
+export * from "./schema/GGWireContextKey";
+export * from "./schema/GGWireContextKey.node";
+export * from "./schema/GGHeader";
 export * from "./rpc/GGHttpRouteRPC";
 export * from "./rpc/openApiSuccessResponse";
 export * from "./rpc/openApiHelpers";
@@ -31,8 +39,12 @@ export * from "./server/GGHttp";
 export * from "./server/GGHttp";
 export * from "./server/GGHttpServer";
 export * from "./server/GG_HTTP_SERVER";
+export * from "./server/applyResponseMiddleware";
+export * from "./server/applyRequestMiddleware";
+export * from "./schema/GGHttpPermissionsChecker";
 
 // Client
+export * from "./client/GGContextKeySynchronizer";
 export * from "./client/GGHttpSchema.createClient";
 export * from "./server/GGHttpSchema.startServer";
 
@@ -40,3 +52,4 @@ export * from "./server/GGHttpSchema.startServer";
 // Extensions
 import "./client/GGHttpSchema.createClient";
 import "./server/GGHttpSchema.startServer";
+import "./schema/GGWireContextKey.node";

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/RpcRequest/GGRpcRequestBuilder.ts

@@ -1,11 +1,13 @@
 import type {HttpMethod} from "@grest-ts/common";
 import {GGContractMethod} from "@grest-ts/schema";
-import {ClientHttpRouteToRpcTransformClientConfig, GGHttpFetchRequest, GGHttpTransportMiddleware} from "../../schema/GGHttpSchema";
+import {ClientHttpRouteToRpcTransformClientConfig, GGHttpFetchRequest} from "../../schema/GGHttpSchema";
+import {GGContextKey, type GGTransportMiddleware} from "@grest-ts/context";
+import {GGContextKeySynchronizer} from "../../client/GGContextKeySynchronizer";
 
 export class GGRpcRequestBuilder {
 
     public readonly contract: GGContractMethod
-    public readonly middlewares: readonly GGHttpTransportMiddleware[]
+    public readonly middlewares: readonly GGTransportMiddleware[]
     public readonly method: HttpMethod;
     public readonly pathTemplate: string;
     public readonly pathParams: string[];
@@ -26,7 +28,7 @@ export class GGRpcRequestBuilder {
         this.hasBody = method === "POST" || method === "PUT" || method === "PATCH"
     }
 
-    public createRequest = (data: unknown): GGHttpFetchRequest => {
+    public createRequest = async (data: unknown): Promise<GGHttpFetchRequest> => {
         let result: GGHttpFetchRequest;
         if (this.hasBody) {
             result = {
@@ -43,7 +45,12 @@ export class GGRpcRequestBuilder {
                 body: undefined
             }
         }
-        this.middlewares?.forEach(mw => mw.updateRequest?.(result))
+        for (const mw of this.middlewares ?? []) {
+            if (mw instanceof GGContextKey) {
+                await GGContextKeySynchronizer.waitFor(mw)
+            }
+        }
+        this.middlewares?.forEach(mw => mw.update?.(result))
         return result
     }
 

package/src/rpc/RpcRequest/GGRpcRequestParser.ts

@@ -1,8 +1,9 @@
 import type http from "http";
 import type {HttpMethod} from "@grest-ts/common";
 import {GGContractExecutor, GGContractMethod, PAYLOAD_TOO_LARGE} from "@grest-ts/schema";
-import {ClientHttpRouteToRpcTransformServerConfig, GGHttpRequest, GGHttpTransportMiddleware} from "../../schema/GGHttpSchema";
-import type {GGHttpServerMiddleware} from "../../server/GGHttpSchema.startServer";
+import type {GGTransportMiddleware} from "@grest-ts/context";
+import {ClientHttpRouteToRpcTransformServerConfig} from "../../schema/GGHttpSchema";
+import {applyRequestMiddleware} from "../../server/applyRequestMiddleware";
 
 export const DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
 
@@ -12,8 +13,7 @@ export class GGRpcRequestParser {
     private readonly pathParams: string[];
     private readonly hasBody: boolean;
     protected readonly contract: GGContractMethod
-    private readonly apiMiddlewares: readonly GGHttpTransportMiddleware[]
-    private readonly serverMiddlewares: readonly GGHttpServerMiddleware[]
+    private readonly middlewares: readonly GGTransportMiddleware[]
 
     constructor(
         method: HttpMethod,
@@ -24,32 +24,31 @@ export class GGRpcRequestParser {
         this.pathParams = (pathTemplate.match(/:(\w+)/g) || []).map(m => m.slice(1))
         this.hasBody = method === "POST" || method === "PUT" || method === "PATCH"
         this.contract = config.contract
-        this.apiMiddlewares = config.apiMiddlewares
-        this.serverMiddlewares = config.serverMiddlewares
+        this.middlewares = config.middlewares
     }
 
-    public parseRequest = async (req: http.IncomingMessage): Promise<unknown> => {
+    // Resolve identity (run the wire pipeline) and extract the raw, unvalidated input.
+    // Validation is deferred to validateInput so the permission gate can run in between.
+    public readRequest = async (req: http.IncomingMessage): Promise<unknown> => {
         const url = req.url || '/'
         const qIndex = url.indexOf('?')
         const queryArgs = this.parseQueryString(qIndex === -1 ? '' : url.substring(qIndex + 1))
-        if (this.apiMiddlewares?.length > 0) {
-            const mwQuery: GGHttpRequest = {headers: req.headers, queryArgs: queryArgs}
-            this.apiMiddlewares?.forEach(mw => mw.parseRequest?.(mwQuery))
-        }
-        for (const mw of this.serverMiddlewares ?? []) await mw.process?.();
+        await applyRequestMiddleware(req, queryArgs, this.middlewares)
 
-        let input: unknown;
         if (this.hasBody) {
-            input = await this.parseBody(req);
+            return await this.parseBody(req);
         } else if (this.pathParams.length > 0) {
-            input = {
+            return {
                 ...this.extractPathParams(qIndex === -1 ? url : url.substring(0, qIndex)),
                 ...queryArgs
             };
         } else {
-            input = queryArgs;
+            return queryArgs;
         }
-        return GGContractExecutor.parseInput(this.contract.input, input);
+    }
+
+    public validateInput = (rawInput: unknown): unknown => {
+        return GGContractExecutor.parseInput(this.contract.input, rawInput);
     }
 
     private parseQueryString(rawQuery: string): Record<string, string | string[]> {

package/src/rpc/RpcResponse/GGRpcResponseBuilder.ts

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

package/src/schema/GGCookie.ts

@@ -0,0 +1,151 @@
+import {GGContextKey, type GGInbound, type GGResponse} from "@grest-ts/context"
+import {type GGSchema, IsAny, IsString, SERVER_ERROR} from "@grest-ts/schema"
+import {GGWireContextKey} from "./GGWireContextKey"
+
+/**
+ * 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>>)
+
+/**
+ * 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>>)
+
+export interface CookieOptions {
+    httpOnly?: boolean
+    secure?: boolean
+    sameSite?: "lax" | "strict" | "none"
+    path?: string
+    domain?: string
+    maxAgeSec?: number
+}
+
+const SAFE_DEFAULTS: CookieOptions = {
+    httpOnly: true,
+    secure: true,
+    sameSite: "lax",
+    path: "/"
+} as const
+
+interface PendingCookie {
+    value: string | undefined
+    options?: CookieOptions
+}
+
+/**
+ * A cookie that IS its own context key.
+ *
+ *   // ambient — the named cookie's value lands in the wire and persists, no implementation needed.
+ *   const SESSION_WIRE = new GGCookie("session_id")
+ *
+ * Reads ONLY the named cookie — never a header — from the inbound Cookie header into the wire.
+ * For HTTP that is the request Cookie; for WebSocket the real upgrade Cookie (the runtime fills
+ * inbound.cookie from there, never from the spoofable in-band message). The cookie name is the
+ * first constructor argument (case-sensitive — unlike a header it is not lowercased). To write
+ * the cookie, call GGCookie.setCookie(key, …) from a route that declared .updatesCookie(key);
+ * this wire flushes it as Set-Cookie (HTTP only — a WebSocket has no response to set a cookie on).
+ */
+export class GGCookie extends GGWireContextKey {
+
+    public readonly cookieParams: Record<string, GGSchema<string | undefined>>
+
+    constructor(name: string) {
+        const WIRE_SCHEMA = IsString.orUndefined
+        super(name, WIRE_SCHEMA)
+        _assertCookieSafe("name", this.name)
+        this.cookieParams = {[this.name]: WIRE_SCHEMA}
+    }
+
+    public parse(inbound: GGInbound): void {
+        const value = _readCookie(inbound.cookie, this.name)
+        if (value !== undefined) this.set(value)
+    }
+
+    public respond(res: GGResponse): void {
+        const pending = GG_COOKIE_PENDING.get()?.get(this.name)
+        if (pending === undefined) return
+        const line = _serializeSetCookie(this.name, 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
+    }
+
+    /**
+     * 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).
+     */
+    public static 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.
+     */
+    public static clearCookie(key: GGContextKey<string | undefined>, options?: CookieOptions): void {
+        this.setCookie(key, undefined, options)
+    }
+
+}
+
+
+// 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. A malformed
+ * percent-encoding (e.g. "sid=%") must not crash — fall back to the raw value.
+ */
+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}`
+}

package/src/schema/GGHeader.ts

@@ -0,0 +1,48 @@
+import {type GGInbound, type GGOutbound} from "@grest-ts/context"
+import {type GGSchema, IsString} from "@grest-ts/schema"
+import {GGWireContextKey} from "./GGWireContextKey"
+
+const BEARER = "Bearer "
+
+
+/**
+ * A request header that IS its own context key.
+ *
+ *   // verified: requires .define() server-side; raw credential is ephemeral.
+ *   const USER_TOKEN_WIRE = new GGHeader("authorization", {scheme: "bearer"})
+ *
+ *   // ambient: parsed value lands in the wire and persists, no implementation needed.
+ *   const CLIENT_VERSION_WIRE = new GGHeader("x-client-version")
+ */
+export class GGHeader extends GGWireContextKey {
+
+    public readonly headers: Record<string, GGSchema<string | undefined>>
+    private readonly scheme?: "bearer"
+    private readonly wireName: string
+
+    constructor(name: string, options?: { scheme?: "bearer" }) {
+        const WIRE_SCHEMA = IsString.orUndefined
+        super(name, WIRE_SCHEMA)
+        this.scheme = options?.scheme
+        this.wireName = name.toLowerCase()
+        this.headers = {[this.wireName]: WIRE_SCHEMA}
+    }
+
+    public parse(inbound: GGInbound): void {
+        const raw = inbound.headers[this.wireName];
+        if (raw === undefined) {
+            return undefined
+        }
+        const value = this.scheme === "bearer" && raw.startsWith(BEARER) ? raw.slice(BEARER.length) : raw
+        if (value !== undefined) {
+            this.set(value)
+        }
+    }
+
+    public update(outbound: GGOutbound): void {
+        const value = this.get()
+        if (value !== undefined) {
+            outbound.headers[this.wireName] = (this.scheme === "bearer" ? `${BEARER}${value}` : value)
+        }
+    }
+}