@grest-ts/http 0.0.34 → 0.0.35

package/src/server/GGHttp.ts

@@ -3,6 +3,21 @@ import {GGContractApiDefinition, GGContractImplementation} from "@grest-ts/schem
 import {GGHttpServerMiddleware} from "./GGHttpSchema.startServer";
 import {GGHttpServer} from "./GGHttpServer";
 
+/**
+ * Resolves the caller's permission scopes for the current request. The function
+ * is called once between transport middleware and the handler. Sync or async —
+ * both supported (the gate awaits).
+ *
+ * Return `null` when no caller identity is available (the gate will throw
+ * NOT_AUTHORIZED for non-public methods). Return a (possibly empty) set
+ * otherwise; the gate will call satisfies() against the method's permission.
+ *
+ * The resolver should read whatever app-defined context the upstream auth
+ * middleware populated — it should NOT parse the token itself.
+ */
+export type GGScopeResolver =
+    () => ReadonlySet<string> | null | Promise<ReadonlySet<string> | null>
+
 export class GGHttp<TContext = undefined> {
 
     /**
@@ -12,6 +27,7 @@ export class GGHttp<TContext = undefined> {
      */
     protected readonly httpServer: GGHttpServer
     private readonly middlewares: GGHttpServerMiddleware[] = [];
+    private permissionResolver?: GGScopeResolver;
 
     constructor(httpServer: GGHttpServer) {
         this.httpServer = httpServer;
@@ -22,11 +38,29 @@ export class GGHttp<TContext = undefined> {
         return this as any;
     }
 
+    /**
+     * Register a scope resolver. Subsequent .http(...) calls capture this
+     * resolver and use it to gate every request against the contract's
+     * declared `permission`.
+     *
+     * Calling order matters: .use(auth) → .usePermissions(getScopes) → .http(api).
+     * If .http() runs before .usePermissions(), the call sees no resolver — and
+     * the startup check will hard-fail if its schema has any non-public method.
+     */
+    public usePermissions(resolver: GGScopeResolver): this {
+        this.permissionResolver = resolver;
+        return this;
+    }
+
     public http<TContract extends GGContractApiDefinition, TSchemaContext>(
         schema: GGHttpSchema<TContract, TSchemaContext>,
         implementation: GGContractImplementation<TContract>
     ): this {
-        schema.register(implementation, {http: this.httpServer, middlewares: this.middlewares});
+        schema.register(implementation, {
+            http: this.httpServer,
+            middlewares: this.middlewares,
+            permissionResolver: this.permissionResolver,
+        });
         return this as any;
     }
 }

package/src/server/GGHttpSchema.startServer.ts

@@ -6,7 +6,7 @@
 import http from "http";
 import {GGLocator} from "@grest-ts/locator";
 import {ClientHttpRouteToRpcTransformServerCodec, GGHttpCodec, GGHttpSchema} from "../schema/GGHttpSchema";
-import {ERROR, GGContractApiDefinition, GGContractImplementation, GGContractMethod, OK, SERVER_ERROR} from "@grest-ts/schema";
+import {describePermission, ERROR, FORBIDDEN, GG_NO_PERMISSIONS, GGContractApiDefinition, GGContractImplementation, GGContractMethod, GGPermissionChecker, NOT_AUTHORIZED, OK, satisfies, 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";
@@ -17,6 +17,8 @@ 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";
 
 export interface GGHttpSchemaConfig {
     /**
@@ -27,6 +29,12 @@ 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 {
@@ -98,6 +106,8 @@ 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]
@@ -127,6 +137,19 @@ function setupRoutes<TContract extends GGContractApiDefinition>(
                 try {
                     const rpcInput = await requestParser.parseRequest(req)
                     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)}
                         // GGLog.debug(httpSchema, "Response", rpcResult) // This is very slow to log this (like 3x performance loss)
                     } catch (error: unknown) {

package/src/server/GGHttpServer.ts

@@ -6,9 +6,16 @@ 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";
 // 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: unknown; middlewares: readonly unknown[]};
+type AnyWebSocketSchema = {
+    name: string;
+    path: string;
+    contract: {clientToServer: {methods: Record<string, GGContractMethod>}};
+    middlewares: readonly unknown[];
+    connectPermission?: GGPermission;
+};
 
 export interface GGHttpServerAdapterConfig {
     key?: GGLocatorKey<GGHttpServer>;
@@ -183,12 +190,88 @@ 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);
+    }
+
+    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");
+            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.`
+            );
+        }
+        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.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();
         this._port = await new Promise((resolve) => {
             this.httpServer.listen(this.configuredPort, '0.0.0.0', () => {
                 const port = (this.httpServer.address() as any).port;

package/src/server/GG_PERMISSIONS.ts

@@ -0,0 +1,15 @@
+import {GGContextKey} from "@grest-ts/context";
+import {GGPermissionChecker, IsAny} from "@grest-ts/schema";
+
+/**
+ * Per-request permission context populated by the gate when a scope resolver
+ * is wired via GGHttp.usePermissions(...). Handler code can read it to make
+ * sub-decisions inside an authorized method:
+ *
+ *     const perm = GG_PERMISSIONS.get();
+ *     if (perm.has(AppPermission.Admin)) { ... }
+ *
+ * The checker uses the same satisfies() the framework gate uses — no parallel
+ * implementations.
+ */
+export const GG_PERMISSIONS = new GGContextKey<GGPermissionChecker>("permissions", IsAny as any);