@grest-ts/http 0.0.47 → 0.0.49

package/src/server/GGHttpSchema.startServer.ts

@@ -6,19 +6,19 @@
 import http from "http";
 import {GGLocator} from "@grest-ts/locator";
 import {ClientHttpRouteToRpcTransformServerCodec, GGHttpCodec, GGHttpSchema} from "../schema/GGHttpSchema";
-import {describePermission, ERROR, FORBIDDEN, GG_NO_PERMISSIONS, GGContractApiDefinition, GGContractImplementation, GGContractMethod, GGPermissionChecker, NOT_AUTHORIZED, OK, satisfies, SERVER_ERROR} from "@grest-ts/schema";
+import {ERROR, GGContractApiDefinition, GGContractImplementation, GGContractMethod, OK, SERVER_ERROR} from "@grest-ts/schema";
 import {HttpMethod} from "@grest-ts/common";
 import {GG_DISCOVERY} from "@grest-ts/discovery";
-import {GGContext, GGContextStore} from "@grest-ts/context";
+import {GGContext, GGContextStore, type GGTransportMiddleware} 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/GGCookie";
 import {GG_METRICS} from "@grest-ts/metrics";
 import {GGHttpMetrics} from "./GGHttpMetrics";
 import {GG_HTTP_SERVER} from "./GG_HTTP_SERVER";
 import {GGHttpServer} from "./GGHttpServer";
 import {GGLog} from "@grest-ts/logger";
-import {GG_PERMISSIONS} from "./GG_PERMISSIONS";
-import type {GGScopeResolver} from "./GGHttp";
+import {GGHttpPermissionsChecker} from "../schema/GGHttpPermissionsChecker";
 
 export interface GGHttpSchemaConfig {
     /**
@@ -28,17 +28,7 @@ export interface GGHttpSchemaConfig {
     /**
      * Additional middlewares to apply to all routes.
      */
-    middlewares?: GGHttpServerMiddleware[];
-    /**
-     * Optional scope resolver. When set, the gate calls it once per request,
-     * populates GG_PERMISSIONS, and rejects requests whose contract permission
-     * is not satisfied by the resolved scopes.
-     */
-    permissionResolver?: GGScopeResolver;
-}
-
-export interface GGHttpServerMiddleware {
-    process?(): Promise<void>
+    middlewares?: GGTransportMiddleware[];
 }
 
 declare module "../schema/GGHttpSchema" {
@@ -80,9 +70,10 @@ function setupRoutes<TContract extends GGContractApiDefinition>(
     const scope = GGLocator.getScope();
     const parentContext = GGContextStore.tryGetContext();
 
+    const permissionsChecker = new GGHttpPermissionsChecker(apiMiddlewares);
     for (const mw of apiMiddlewares) {
-        const hKeys = Object.keys(mw.headers);
-        const rhKeys = Object.keys(mw.responseHeaders);
+        const hKeys = Object.keys(mw.headers ?? {});
+        const rhKeys = Object.keys(mw.responseHeaders ?? {});
         if (hKeys.length) server.registerCorsHeaders(hKeys);
         if (rhKeys.length) server.registerCorsExposeHeaders(rhKeys);
     }
@@ -106,8 +97,6 @@ function setupRoutes<TContract extends GGContractApiDefinition>(
     // @TODO This is not really used and only for testkit so it would register implementation of the contract... Not cool
     httpSchema.contract.implement(implementation);
 
-    if (config.permissionResolver) server._markResolverWired(httpSchema);
-
     for (const methodName in httpSchema.codec) {
         // Wire format.
         const codec: GGHttpCodec = httpSchema.codec[methodName]
@@ -124,33 +113,22 @@ function setupRoutes<TContract extends GGContractApiDefinition>(
         // build request mapping
         const requestParser: ClientHttpRouteToRpcTransformServerCodec = codec.createForServer({
             contract: contractFunctionSchema,
-            apiMiddlewares: apiMiddlewares,
-            serverMiddlewares: config.middlewares
+            middlewares: [...apiMiddlewares, ...(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 {
-                    const rpcInput = await requestParser.parseRequest(req)
+                    const rawInput = await requestParser.readRequest(req)
+                    await permissionsChecker.assert(httpSchema.name, methodName, contractFunctionSchema.permission)
                     try {
-                        if (config.permissionResolver) {
-                            const scopes = await config.permissionResolver()
-                            if (scopes != null) GG_PERMISSIONS.set(new GGPermissionChecker(scopes))
-                            const required = contractFunctionSchema.permission
-                            if (required !== undefined && required !== GG_NO_PERMISSIONS) {
-                                if (scopes == null) throw new NOT_AUTHORIZED({
-                                    debugMessage: `${httpSchema.name}.${methodName} requires ${describePermission(required)} but no caller identity was resolved`
-                                })
-                                if (!satisfies(required, scopes)) throw new FORBIDDEN({
-                                    debugMessage: `${httpSchema.name}.${methodName} requires ${describePermission(required)} — caller scopes did not satisfy`
-                                })
-                            }
-                        }
-                        rpcResult = {success: true, type: "OK", data: await implFn(rpcInput)}
+                        rpcResult = {success: true, type: "OK", data: await implFn(requestParser.validateInput(rawInput))}
                         // GGLog.debug(httpSchema, "Response", rpcResult) // This is very slow to log this (like 3x performance loss)
                     } catch (error: unknown) {
                         rpcResult = ERROR.fromUnknown(error);
@@ -167,7 +145,7 @@ function setupRoutes<TContract extends GGContractApiDefinition>(
                     metrics(rpcResult?.type, httpSchema.name, codec.method, pathPrefix, codec.path, startTime)
                 }
             });
-        })
+        }, `${httpSchema.name}.${methodName}`)
     }
 }
 

package/src/server/GGHttpServer.ts

@@ -6,20 +6,50 @@ import {GG_HTTP_SERVER} from "./GG_HTTP_SERVER";
 import {GGLog} from "@grest-ts/logger";
 import findMyWay, {HTTPMethod} from "find-my-way";
 import type {GGHttpSchema} from "../schema/GGHttpSchema";
-import {describePermission, GG_NO_PERMISSIONS, GGContractMethod, GGPermission} from "@grest-ts/schema";
+import {checkWiresImplemented} from "./checkers/checkWiresImplemented";
+import {checkPermissionsAtStart} from "./checkers/checkPermissionsAtStart";
+import {checkWireConflicts} from "./checkers/checkWireConflicts";
+import "../schema/GGWireContextKey.node";
+import {GGContractMethod, GGPermission} from "@grest-ts/schema";
+import type {GGTransportMiddleware} from "@grest-ts/context";
 // Forward declaration — actual type lives in @grest-ts/websocket to avoid circular dep.
 // GGHttpServer only stores the array; callers cast as needed.
 type AnyWebSocketSchema = {
     name: string;
     path: string;
-    contract: {clientToServer: {methods: Record<string, GGContractMethod>}};
-    middlewares: readonly unknown[];
+    contract: {
+        clientToServer: {methods: Record<string, GGContractMethod>};
+        serverToClient: {methods: Record<string, GGContractMethod>};
+    };
+    middlewares: readonly GGTransportMiddleware[];
     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 +71,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> = [];
@@ -50,16 +81,10 @@ export class GGHttpServer {
      * Framework-internal — only setupRoutes() (in GGHttpSchema.startServer.ts) should push here.
      */
     private readonly _registeredSchemas: GGHttpSchema<any, any>[] = [];
-
-    /**
-     * All GGHttpSchema instances registered on this server, in registration order.
-     * Available from the moment compose() begins; frozen (no further push allowed) once start() is called.
-     */
-    get registeredSchemas(): ReadonlyArray<GGHttpSchema<any, any>> {
-        return this._registeredSchemas;
-    }
+    private readonly _registeredWebSocketSchemas: AnyWebSocketSchema[] = [];
 
     public readonly httpServer: http.Server;
+    private readonly _routeOwners = new Map<string, string>();
     private activeRequests = 0;
     private router = findMyWay<findMyWay.HTTPVersion.V1>();
 
@@ -75,6 +100,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 +116,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();
@@ -175,14 +195,12 @@ export class GGHttpServer {
         this._registeredSchemas.push(schema);
     }
 
-    private readonly _registeredWebSocketSchemas: AnyWebSocketSchema[] = [];
-
     /**
-     * All GGWebSocketSchema instances registered on this server, in registration order.
-     * Populated automatically by GGWebSocketSchema.startServer() / .register().
+     * All GGHttpSchema instances registered on this server, in registration order.
+     * Available from the moment compose() begins; frozen (no further push allowed) once start() is called.
      */
-    get registeredWebSocketSchemas(): ReadonlyArray<AnyWebSocketSchema> {
-        return this._registeredWebSocketSchemas;
+    get registeredSchemas(): ReadonlyArray<GGHttpSchema<any, any>> {
+        return this._registeredSchemas;
     }
 
     /** @internal Called by GGWebSocketSchema.startServer(). Do not call directly. */
@@ -190,88 +208,32 @@ export class GGHttpServer {
         this._registeredWebSocketSchemas.push(schema);
     }
 
-    private readonly _schemasWithResolver = new Set<object>();
-
-    /** @internal Called by HTTP / WS register paths when a scope resolver is wired. */
-    public _markResolverWired(schema: object): void {
-        this._schemasWithResolver.add(schema);
+    /**
+     * All GGWebSocketSchema instances registered on this server, in registration order.
+     * Populated automatically by GGWebSocketSchema.startServer() / .register().
+     */
+    get registeredWebSocketSchemas(): ReadonlyArray<AnyWebSocketSchema> {
+        return this._registeredWebSocketSchemas;
     }
 
-    private _checkPermissionsAtStart(): void {
-        type Surface = {label: string; permission: GGPermission | undefined; resolverWired: boolean};
-        const surfaces: Surface[] = [];
-
-        for (const schema of this._registeredSchemas) {
-            const resolverWired = this._schemasWithResolver.has(schema);
-            const methods = schema.contract?.methods ?? {};
-            for (const name of Object.keys(methods)) {
-                surfaces.push({
-                    label: `${schema.name}.${name}`,
-                    permission: (methods[name] as GGContractMethod).permission,
-                    resolverWired,
-                });
-            }
-        }
-        for (const ws of this._registeredWebSocketSchemas) {
-            const resolverWired = this._schemasWithResolver.has(ws);
-            const methods = ws.contract.clientToServer.methods;
-            for (const name of Object.keys(methods)) {
-                surfaces.push({
-                    label: `${ws.name}.${name}`,
-                    permission: methods[name].permission,
-                    resolverWired,
-                });
-            }
-            if (ws.connectPermission !== undefined) {
-                surfaces.push({
-                    label: `${ws.name} (connectPermission)`,
-                    permission: ws.connectPermission,
-                    resolverWired,
-                });
-            }
-        }
-
-        let strict = false;
-        const undeclared: Surface[] = [];
-        const orphaned: Surface[] = [];
-        for (const s of surfaces) {
-            if (s.permission !== undefined || s.resolverWired) strict = true;
-            if (s.permission === undefined) undeclared.push(s);
-            else if (s.permission !== GG_NO_PERMISSIONS && !s.resolverWired) orphaned.push(s);
-        }
-        if (!strict) return;
-
-        if (undeclared.length > 0) {
-            const lines = undeclared.map(s => `  ${s.label}`).join("\n");
+    public registerRoute(method: HttpMethod, path: string, handler: GGHttpRequestCallback, owner?: string): void {
+        const route = `${method} ${path}`;
+        const existing = this._routeOwners.get(route);
+        if (existing !== undefined) {
             throw new Error(
-                `GGHttpServer: permission strict mode is active on this server ` +
-                `(at least one route declares a permission or has .usePermissions(...) wired), ` +
-                `but the following routes have no \`permission\` declared:\n\n` +
-                lines +
-                `\n\nFix: declare \`permission\` on every route — use \`GG_NO_PERMISSIONS\` for intentionally public ones.`
+                `GGHttpServer: route ${route} is declared by both ${existing} and ${owner ?? "another route"}. ` +
+                `Give each route a distinct path (change a pathPrefix or route path).`
             );
         }
-        if (orphaned.length > 0) {
-            const lines = orphaned.map(s =>
-                `  ${s.label}   requires ${describePermission(s.permission)}`
-            ).join("\n");
-            throw new Error(
-                `GGHttpServer: these routes declare non-public permissions but their schema was ` +
-                `registered without a scope resolver:\n\n` +
-                lines +
-                `\n\nFix: call \`.usePermissions(yourResolver)\` on the GGHttp chain (or pass ` +
-                `\`permissionResolver\` to the WS schema config) before registering these routes.`
-            );
-        }
-    }
-
-    public registerRoute(method: HttpMethod, path: string, handler: GGHttpRequestCallback): void {
+        this._routeOwners.set(route, owner ?? path);
         this.router.on(method as HTTPMethod, path, handler as unknown as findMyWay.Handler<findMyWay.HTTPVersion.V1>);
     }
 
     public async start(): Promise<void> {
         Object.freeze(this._registeredSchemas);
-        this._checkPermissionsAtStart();
+        checkWireConflicts(this.registeredSchemas, this.registeredWebSocketSchemas);
+        checkWiresImplemented(this.registeredSchemas, this.registeredWebSocketSchemas);
+        checkPermissionsAtStart(this.registeredSchemas, this.registeredWebSocketSchemas);
         this._port = await new Promise((resolve) => {
             this.httpServer.listen(this.configuredPort, '0.0.0.0', () => {
                 const port = (this.httpServer.address() as any).port;
@@ -313,3 +275,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/applyRequestMiddleware.ts

@@ -0,0 +1,40 @@
+import type http from "http";
+import type {GGInbound, GGTransportMiddleware} from "@grest-ts/context";
+
+/**
+ * Normalizes a Node request + parsed query into a GGInbound and runs the server-side
+ * pipeline: every parse() (populating context keys) before any process() (async
+ * validation), so a middleware can validate against a key an earlier one parsed.
+ * The cookie is taken only from the real request header — never from anywhere a
+ * client could forge — preserving the anti-spoof guarantee on every transport.
+ */
+export async function applyRequestMiddleware(
+    req: http.IncomingMessage,
+    queryArgs: Record<string, string | string[]>,
+    middlewares: readonly GGTransportMiddleware[]
+): Promise<void> {
+    if (middlewares.length === 0) return;
+    const inbound: GGInbound = {
+        headers: flatten(req.headers),
+        cookie: typeof req.headers.cookie === "string" ? req.headers.cookie : undefined,
+        query: flatten(queryArgs)
+    };
+    for (const mw of middlewares) mw.parse?.(inbound);
+    // finally: a rejecting process() (e.g. anonymous → NOT_AUTHORIZED) must still drop every
+    // ephemeral credential — including those an earlier wire already parsed — so no raw token
+    // outlives the failed request in context.
+    try {
+        for (const mw of middlewares) await mw.process?.();
+    } finally {
+        for (const mw of middlewares) mw.clear?.();
+    }
+}
+
+function flatten(src: Record<string, string | string[] | undefined>): Record<string, string | undefined> {
+    const out: Record<string, string | undefined> = {};
+    for (const key in src) {
+        const value = src[key];
+        out[key] = Array.isArray(value) ? value[0] : value;
+    }
+    return out;
+}

package/src/server/applyResponseMiddleware.ts

@@ -0,0 +1,27 @@
+import type http from "http";
+import type {GGResponse, GGTransportMiddleware} from "@grest-ts/context";
+
+/**
+ * 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 GGTransportMiddleware[] | undefined
+): void {
+    if (!middlewares?.length || res.headersSent) return;
+    let response: GGResponse | undefined;
+    for (const mw of middlewares) {
+        if (!mw.respond) continue;
+        response ??= {headers: {}};
+        mw.respond(response);
+    }
+    if (!response) return;
+    for (const name in response.headers) {
+        res.setHeader(name, response.headers[name]);
+    }
+}

package/src/server/checkers/checkPermissionsAtStart.ts

@@ -0,0 +1,112 @@
+/**
+ * Run at GGHttpServer.start() over the frozen schema graph. Three permission-coherence checks:
+ *
+ *  - strict-mode coverage: once any route declares a permission, every route on the server must
+ *    declare one (use GG_NO_PERMISSIONS for intentionally public routes).
+ *  - unsatisfiable route: a route requiring a non-public permission on a schema with no
+ *    permission-resolving wire (a .define()d wire whose handler exposes permissions()) can never
+ *    pass the gate — its pooled grants are always empty, so it is permanently FORBIDDEN.
+ *  - dead serverToClient permission: the gate has no caller identity for server-pushed messages,
+ *    so a non-public permission on a WS serverToClient method is silently ignored.
+ *
+ * Scopes come only from the schema's wires; there is no resolver wiring.
+ */
+import {GG_NO_PERMISSIONS, GGContractMethod, GGPermission} from "@grest-ts/schema"
+import type {GGTransportMiddleware} from "@grest-ts/context"
+import {GGWireContextKey} from "../../schema/GGWireContextKey"
+import "../../schema/GGWireContextKey.node"
+
+interface HttpSchemaLike {
+    name: string
+    apiMiddlewares: readonly GGTransportMiddleware[]
+    contract?: {methods: Record<string, GGContractMethod>}
+}
+
+interface WebSocketSchemaLike {
+    name: string
+    middlewares: readonly GGTransportMiddleware[]
+    contract: {
+        clientToServer: {methods: Record<string, GGContractMethod>}
+        serverToClient: {methods: Record<string, GGContractMethod>}
+    }
+    connectPermission?: GGPermission
+}
+
+function isNonPublic(permission: GGPermission | undefined): boolean {
+    return permission !== undefined && permission !== GG_NO_PERMISSIONS
+}
+
+function hasPermissionWire(wires: readonly GGTransportMiddleware[]): boolean {
+    return wires.some(mw => mw instanceof GGWireContextKey && mw.hasPermissions())
+}
+
+export function checkPermissionsAtStart(
+    httpSchemas: readonly HttpSchemaLike[],
+    webSocketSchemas: readonly WebSocketSchemaLike[],
+): void {
+    type Surface = {label: string; permission: GGPermission | undefined; hasWire: boolean}
+    const surfaces: Surface[] = []
+    const deadServerToClient: string[] = []
+
+    for (const schema of httpSchemas) {
+        const hasWire = hasPermissionWire(schema.apiMiddlewares)
+        const methods = schema.contract?.methods ?? {}
+        for (const name of Object.keys(methods)) {
+            surfaces.push({label: `${schema.name}.${name}`, permission: methods[name].permission, hasWire})
+        }
+    }
+    for (const ws of webSocketSchemas) {
+        const hasWire = hasPermissionWire(ws.middlewares)
+        const methods = ws.contract.clientToServer.methods
+        for (const name of Object.keys(methods)) {
+            surfaces.push({label: `${ws.name}.${name}`, permission: methods[name].permission, hasWire})
+        }
+        if (ws.connectPermission !== undefined) {
+            surfaces.push({label: `${ws.name} (connectPermission)`, permission: ws.connectPermission, hasWire})
+        }
+        const pushed = ws.contract.serverToClient.methods
+        for (const name of Object.keys(pushed)) {
+            if (isNonPublic(pushed[name].permission)) deadServerToClient.push(`  ${ws.name}.${name}`)
+        }
+    }
+
+    if (deadServerToClient.length > 0) {
+        throw new Error(
+            `GGHttpServer: these WebSocket serverToClient methods declare a non-public permission, ` +
+            `but server-pushed messages have no caller to gate — the permission is silently ignored:\n\n` +
+            deadServerToClient.join("\n") +
+            `\n\nFix: set \`permission: GG_NO_PERMISSIONS\` on serverToClient methods.`
+        )
+    }
+
+    const unsatisfiable = surfaces.filter(s => isNonPublic(s.permission) && !s.hasWire)
+    if (unsatisfiable.length > 0) {
+        const lines = unsatisfiable.map(s => `  ${s.label}`).join("\n")
+        throw new Error(
+            `GGHttpServer: these routes require a permission but their schema .use()s no wire that ` +
+            `resolves permissions — they can never pass the gate (permanently FORBIDDEN):\n\n` +
+            lines +
+            `\n\nFix: .use() an auth wire whose handler exposes permissions(), or set the route to ` +
+            `\`GG_NO_PERMISSIONS\` if it is meant to be public.`
+        )
+    }
+
+    let strict = false
+    const undeclared: Surface[] = []
+    for (const s of surfaces) {
+        if (s.permission !== undefined) strict = true
+        if (s.permission === undefined) undeclared.push(s)
+    }
+    if (!strict) return
+
+    if (undeclared.length > 0) {
+        const lines = undeclared.map(s => `  ${s.label}`).join("\n")
+        throw new Error(
+            `GGHttpServer: permission strict mode is active on this server ` +
+            `(at least one route declares a permission), ` +
+            `but the following routes have no \`permission\` declared:\n\n` +
+            lines +
+            `\n\nFix: declare \`permission\` on every route — use \`GG_NO_PERMISSIONS\` for intentionally public ones.`
+        )
+    }
+}

package/src/server/checkers/checkWireConflicts.ts

@@ -0,0 +1,65 @@
+/**
+ * Run at GGHttpServer.start() over the frozen schema graph: the wires a single schema .use()s
+ * must not conflict with each other. Two conflicts are caught:
+ *   - same context-key name → both wires resolve to one storage slot; parse() of one clobbers
+ *     the value the other read.
+ *   - same inbound header / cookie → both wires read (and a client writes) the same transport
+ *     field; one silently overwrites the other in parse()/update().
+ * Both are per-schema: the same wire reused across different schemas is fine.
+ */
+import type {GGTransportMiddleware} from "@grest-ts/context"
+import {GGWireContextKey} from "../../schema/GGWireContextKey"
+
+interface SchemaLike {
+    name: string
+    wires: readonly GGTransportMiddleware[]
+}
+
+function transportKeys(mw: GGTransportMiddleware): string[] {
+    return [
+        ...Object.keys(mw.headers ?? {}).map(h => `header "${h.toLowerCase()}"`),
+        ...Object.keys(mw.cookieParams ?? {}).map(c => `cookie "${c}"`),
+    ]
+}
+
+export function checkWireConflicts(
+    httpSchemas: readonly {name: string; apiMiddlewares: readonly GGTransportMiddleware[]}[],
+    webSocketSchemas: readonly {name: string; middlewares: readonly GGTransportMiddleware[]}[],
+): void {
+    const schemas: SchemaLike[] = [
+        ...httpSchemas.map(s => ({name: s.name, wires: s.apiMiddlewares})),
+        ...webSocketSchemas.map(s => ({name: s.name, wires: s.middlewares})),
+    ]
+
+    const conflicts: string[] = []
+    for (const schema of schemas) {
+        const names = new Map<string, GGWireContextKey>()
+        const fields = new Map<string, GGTransportMiddleware>()
+
+        for (const mw of schema.wires) {
+            if (mw instanceof GGWireContextKey) {
+                if (names.has(mw.name)) {
+                    conflicts.push(`  ${schema.name}: two wires share context-key name "${mw.name}"`)
+                } else {
+                    names.set(mw.name, mw)
+                }
+            }
+            for (const field of transportKeys(mw)) {
+                if (fields.has(field)) {
+                    conflicts.push(`  ${schema.name}: two wires bind the same ${field}`)
+                } else {
+                    fields.set(field, mw)
+                }
+            }
+        }
+    }
+
+    if (conflicts.length > 0) {
+        throw new Error(
+            `GGHttpServer: conflicting wires .use()d on one schema:\n\n` +
+            conflicts.join("\n") +
+            `\n\nFix: a schema must not .use() two wires that share a context-key name or read the ` +
+            `same header/cookie — one silently clobbers the other.`
+        )
+    }
+}

package/src/server/checkers/checkWiresImplemented.ts

@@ -0,0 +1,42 @@
+/**
+ * Run at GGHttpServer.start() over the frozen schema graph: every wire a schema
+ * .use()s and that is .define()d must have a .create()d handler on this runtime.
+ */
+import {GGWireContextKey} from "../../schema/GGWireContextKey"
+import {wireIsDefined} from "../../schema/GGWireContextKey.node"
+
+interface HttpSchemaLike {
+    name: string
+    apiMiddlewares: readonly unknown[]
+}
+
+interface WebSocketSchemaLike {
+    name: string
+    middlewares: readonly unknown[]
+}
+
+export function checkWiresImplemented(
+    httpSchemas: readonly HttpSchemaLike[],
+    webSocketSchemas: readonly WebSocketSchemaLike[],
+): void {
+    const surfaces: {name: string; wires: readonly unknown[]}[] = [
+        ...httpSchemas.map(s => ({name: s.name, wires: s.apiMiddlewares})),
+        ...webSocketSchemas.map(s => ({name: s.name, wires: s.middlewares})),
+    ]
+    const missing: string[] = []
+    for (const surface of surfaces) {
+        for (const mw of surface.wires) {
+            if (mw instanceof GGWireContextKey && wireIsDefined(mw) && !mw.hasHandler()) {
+                missing.push(`  ${surface.name}  uses wire "${mw.name}"`)
+            }
+        }
+    }
+    if (missing.length > 0) {
+        throw new Error(
+            `GGHttpServer: these schemas .use() a smart wire that was never implemented on this ` +
+            `runtime:\n\n` +
+            missing.join("\n") +
+            `\n\nFix: call \`${"<WIRE>"}.define(...).create(deps)\` in compose() before the server starts.`
+        )
+    }
+}