@marinoscar/platform-api 0.1.0-next.21 → 0.1.0-next.22

package/dist/nodes/node-ownership.js

@@ -0,0 +1,92 @@
+"use strict";
+// =============================================================================
+// Node ownership: the one rule, and the narrow provider an app route may use
+// =============================================================================
+//
+// `assertNodeOwnedBy` is the rule `NodesService.assertOwnership` has always
+// applied (404 for a node that does not exist, 403 for one that belongs to
+// somebody else; the argument for 403 over 404 is in `nodes.service.ts`). It is
+// extracted so the packaged control plane and the `@NodeRoute()` guard cannot
+// drift into two opinions about who owns a node.
+//
+// `NodeOwnershipService` exists because `NodesService` is deliberately NOT
+// exported from `NodesModule` (a feature module that could inject it could
+// claim jobs or settle them outside the terminal chokepoint). This is the
+// least-privilege handle: one method, read-only.
+// =============================================================================
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeOwnershipService = void 0;
+exports.assertNodeOwnedBy = assertNodeOwnedBy;
+const common_1 = require("@nestjs/common");
+const index_1 = require("../core/index");
+/**
+ * Loads node `nodeId` and proves `userId` owns it.
+ *
+ * @param prisma - anything with the `workerNode` delegate.
+ * @param userId - the authenticated owner.
+ * @param nodeId - the node's id.
+ * @returns the verified node row.
+ * @throws NotFoundException when the node does not exist; ForbiddenException when another user owns it.
+ *
+ * @stability stable
+ */
+async function assertNodeOwnedBy(prisma, userId, nodeId) {
+    const node = await prisma.workerNode.findUnique({ where: { id: nodeId } });
+    if (!node) {
+        throw new common_1.NotFoundException({
+            message: `Worker node ${nodeId} was not found.`,
+            details: { nodeId },
+        });
+    }
+    if (node.createdById !== userId) {
+        throw new common_1.ForbiddenException({
+            message: `Worker node ${nodeId} belongs to another user. Check that this credential and ` +
+                `this node id came from the same registration.`,
+            details: { nodeId },
+        });
+    }
+    return node;
+}
+/**
+ * The ownership check an app's node-plane code may inject: the same rule as
+ * the packaged control plane, with none of the rest of `NodesService`. Provided
+ * and exported by `NodeRouteModule`.
+ *
+ * @stability stable
+ */
+let NodeOwnershipService = class NodeOwnershipService {
+    prisma;
+    constructor(prisma) {
+        this.prisma = prisma;
+    }
+    /**
+     * Proves `userId` owns node `nodeId`.
+     *
+     * @param userId - the authenticated owner.
+     * @param nodeId - the node's id.
+     * @returns the verified node row.
+     * @throws NotFoundException (missing node) or ForbiddenException (not yours).
+     */
+    assertOwnership(userId, nodeId) {
+        return assertNodeOwnedBy(this.prisma, userId, nodeId);
+    }
+};
+exports.NodeOwnershipService = NodeOwnershipService;
+exports.NodeOwnershipService = NodeOwnershipService = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(index_1.PLATFORM_PRISMA)),
+    __metadata("design:paramtypes", [Object])
+], NodeOwnershipService);
+//# sourceMappingURL=node-ownership.js.map

package/dist/nodes/node-ownership.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-ownership.js","sourceRoot":"","sources":["../../src/nodes/node-ownership.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,6EAA6E;AAC7E,gFAAgF;AAChF,EAAE;AACF,4EAA4E;AAC5E,2EAA2E;AAC3E,gFAAgF;AAChF,8EAA8E;AAC9E,iDAAiD;AACjD,EAAE;AACF,2EAA2E;AAC3E,2EAA2E;AAC3E,0EAA0E;AAC1E,iDAAiD;AACjD,gFAAgF;;;;;;;;;;;;;;;AAkBhF,8CAoBC;AApCD,2CAA2F;AAE3F,yCAAgD;AAGhD;;;;;;;;;;GAUG;AACI,KAAK,UAAU,iBAAiB,CAAC,MAAsC,EAAE,MAAc,EAAE,MAAc;IAC5G,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;IAE3E,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,0BAAiB,CAAC;YAC1B,OAAO,EAAE,eAAe,MAAM,iBAAiB;YAC/C,OAAO,EAAE,EAAE,MAAM,EAAE;SACpB,CAAC,CAAC;IACL,CAAC;IAED,IAAI,IAAI,CAAC,WAAW,KAAK,MAAM,EAAE,CAAC;QAChC,MAAM,IAAI,2BAAkB,CAAC;YAC3B,OAAO,EACL,eAAe,MAAM,2DAA2D;gBAChF,+CAA+C;YACjD,OAAO,EAAE,EAAE,MAAM,EAAE;SACpB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AAEI,IAAM,oBAAoB,GAA1B,MAAM,oBAAoB;IACuB;IAAtD,YAAsD,MAAkB;QAAlB,WAAM,GAAN,MAAM,CAAY;IAAG,CAAC;IAE5E;;;;;;;OAOG;IACH,eAAe,CAAC,MAAc,EAAE,MAAc;QAC5C,OAAO,iBAAiB,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACxD,CAAC;CACF,CAAA;AAdY,oDAAoB;+BAApB,oBAAoB;IADhC,IAAA,mBAAU,GAAE;IAEE,WAAA,IAAA,eAAM,EAAC,uBAAe,CAAC,CAAA;;GADzB,oBAAoB,CAchC"}

package/dist/nodes/node-route.decorator.d.ts

@@ -0,0 +1,31 @@
+import { type NodeRouteOptions } from './node-route.options';
+/**
+ * Marks an app controller (or handler) as a node-plane route. Its path must be
+ * under `NODE_ROUTE_PREFIX` (`/api/nodes`) and must not overlap
+ * `RESERVED_NODE_SUBPATHS` (checked at bootstrap by `NodeRouteModule` and by
+ * the `nodes` conformance suite). The controller's module imports
+ * `NodeRouteModule`, which provides the guard.
+ *
+ * The decorator applies `@Auth({ permissions })` too, so a controller needs no
+ * separate `@Auth()`.
+ *
+ * @param options - see {@link NodeRouteOptions}.
+ * @returns a class and method decorator.
+ *
+ * @example
+ * ```ts
+ * @Controller('nodes/:id/reports')
+ * @NodeRoute({ credentials: ['nod'] })
+ * export class ReportsController {
+ *   @Get('latest')
+ *   latest(@CurrentNode() node: WorkerNode) {
+ *     return this.reports.latestFor(node);
+ *   }
+ * }
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export declare function NodeRoute(options?: NodeRouteOptions): ClassDecorator & MethodDecorator;
+//# sourceMappingURL=node-route.decorator.d.ts.map

package/dist/nodes/node-route.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-route.decorator.d.ts","sourceRoot":"","sources":["../../src/nodes/node-route.decorator.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAgD,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAG3G;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,cAAc,GAAG,eAAe,CAO1F"}

package/dist/nodes/node-route.decorator.js

@@ -0,0 +1,54 @@
+"use strict";
+// =============================================================================
+// @NodeRoute(): an app route on the node plane
+// =============================================================================
+//
+// WHAT IT IS. `JwtAuthGuard` is the outer fence: a `nod_` credential reaches
+// `/api/nodes` and what is under it, nothing else. `@NodeRoute()` is the inner
+// one an app controller mounted there opts into. It composes `@Auth()` (the
+// platform node plane's permission, by default) with `NodeRouteGuard`, which
+// narrows the admitted credential kinds and PROVES the caller owns the node
+// named in the path before the handler runs, so no handler can forget to.
+//
+// It only narrows. It never widens what `JwtAuthGuard` admits, and the prefix
+// allowlist stays authoritative.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeRoute = NodeRoute;
+const common_1 = require("@nestjs/common");
+const index_1 = require("../identity/index");
+const node_route_options_1 = require("./node-route.options");
+const node_route_guard_1 = require("./node-route.guard");
+/**
+ * Marks an app controller (or handler) as a node-plane route. Its path must be
+ * under `NODE_ROUTE_PREFIX` (`/api/nodes`) and must not overlap
+ * `RESERVED_NODE_SUBPATHS` (checked at bootstrap by `NodeRouteModule` and by
+ * the `nodes` conformance suite). The controller's module imports
+ * `NodeRouteModule`, which provides the guard.
+ *
+ * The decorator applies `@Auth({ permissions })` too, so a controller needs no
+ * separate `@Auth()`.
+ *
+ * @param options - see {@link NodeRouteOptions}.
+ * @returns a class and method decorator.
+ *
+ * @example
+ * ```ts
+ * @Controller('nodes/:id/reports')
+ * @NodeRoute({ credentials: ['nod'] })
+ * export class ReportsController {
+ *   @Get('latest')
+ *   latest(@CurrentNode() node: WorkerNode) {
+ *     return this.reports.latestFor(node);
+ *   }
+ * }
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+function NodeRoute(options = {}) {
+    const resolved = (0, node_route_options_1.resolveNodeRouteOptions)(options);
+    return (0, common_1.applyDecorators)((0, common_1.SetMetadata)(node_route_options_1.NODE_ROUTE_METADATA, resolved), (0, index_1.Auth)({ permissions: [...resolved.permissions] }), (0, common_1.UseGuards)(node_route_guard_1.NodeRouteGuard));
+}
+//# sourceMappingURL=node-route.decorator.js.map

package/dist/nodes/node-route.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-route.decorator.js","sourceRoot":"","sources":["../../src/nodes/node-route.decorator.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,+CAA+C;AAC/C,gFAAgF;AAChF,EAAE;AACF,6EAA6E;AAC7E,+EAA+E;AAC/E,4EAA4E;AAC5E,6EAA6E;AAC7E,4EAA4E;AAC5E,0EAA0E;AAC1E,EAAE;AACF,8EAA8E;AAC9E,iCAAiC;AACjC,gFAAgF;;AAoChF,8BAOC;AAzCD,2CAAyE;AAEzE,6CAAyC;AACzC,6DAA2G;AAC3G,yDAAoD;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,SAAgB,SAAS,CAAC,UAA4B,EAAE;IACtD,MAAM,QAAQ,GAAG,IAAA,4CAAuB,EAAC,OAAO,CAAC,CAAC;IAClD,OAAO,IAAA,wBAAe,EACpB,IAAA,oBAAW,EAAC,wCAAmB,EAAE,QAAQ,CAAC,EAC1C,IAAA,YAAI,EAAC,EAAE,WAAW,EAAE,CAAC,GAAG,QAAQ,CAAC,WAAW,CAAU,EAAE,CAAC,EACzD,IAAA,kBAAS,EAAC,iCAAc,CAAC,CACU,CAAC;AACxC,CAAC"}

package/dist/nodes/node-route.guard.d.ts

@@ -0,0 +1,22 @@
+import { CanActivate, ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { NodeOwnershipService } from './node-ownership';
+/**
+ * Applied by `@NodeRoute()`, after `JwtAuthGuard`: refuses a credential kind
+ * the route did not admit (403), then, when the route names a node, loads it
+ * and proves the caller owns it (404 missing, 403 not yours; the packaged
+ * control plane's own semantics) and hands it to `@CurrentNode()`.
+ *
+ * @stability experimental
+ */
+export declare class NodeRouteGuard implements CanActivate {
+    private readonly reflector;
+    private readonly ownership;
+    constructor(reflector: Reflector, ownership: NodeOwnershipService);
+    /**
+     * @param context - the execution context.
+     * @returns `true` to admit; throws 400, 403 or 404 otherwise.
+     */
+    canActivate(context: ExecutionContext): Promise<boolean>;
+}
+//# sourceMappingURL=node-route.guard.d.ts.map

package/dist/nodes/node-route.guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-route.guard.d.ts","sourceRoot":"","sources":["../../src/nodes/node-route.guard.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,WAAW,EACX,gBAAgB,EAGjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAKzC,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAcxD;;;;;;;GAOG;AACH,qBACa,cAAe,YAAW,WAAW;IAE9C,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS;gBADT,SAAS,EAAE,SAAS,EACpB,SAAS,EAAE,oBAAoB;IAGlD;;;OAGG;IACG,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;CA8B/D"}

package/dist/nodes/node-route.guard.js

@@ -0,0 +1,74 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeRouteGuard = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const current_node_decorator_1 = require("./current-node.decorator");
+const node_route_options_1 = require("./node-route.options");
+const node_ownership_1 = require("./node-ownership");
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const KIND = { node: 'nod', pat: 'pat', jwt: 'jwt' };
+/**
+ * Applied by `@NodeRoute()`, after `JwtAuthGuard`: refuses a credential kind
+ * the route did not admit (403), then, when the route names a node, loads it
+ * and proves the caller owns it (404 missing, 403 not yours; the packaged
+ * control plane's own semantics) and hands it to `@CurrentNode()`.
+ *
+ * @stability experimental
+ */
+let NodeRouteGuard = class NodeRouteGuard {
+    reflector;
+    ownership;
+    constructor(reflector, ownership) {
+        this.reflector = reflector;
+        this.ownership = ownership;
+    }
+    /**
+     * @param context - the execution context.
+     * @returns `true` to admit; throws 400, 403 or 404 otherwise.
+     */
+    async canActivate(context) {
+        const options = this.reflector.getAllAndOverride(node_route_options_1.NODE_ROUTE_METADATA, [
+            context.getHandler(),
+            context.getClass(),
+        ]);
+        // Unreachable through the decorator; fail closed rather than admit.
+        if (!options)
+            throw new common_1.ForbiddenException('Route is not a declared node route.');
+        const request = context.switchToHttp().getRequest();
+        const credential = request.authCredential ? KIND[request.authCredential.kind] : undefined;
+        if (!credential || !options.credentials.includes(credential)) {
+            throw new common_1.ForbiddenException({
+                message: 'This credential kind is not accepted on this route.',
+                details: { accepted: [...options.credentials] },
+            });
+        }
+        if (options.nodeParam === false)
+            return true;
+        const userId = (request.requestUser ?? request.user)?.id;
+        if (!userId)
+            throw new common_1.ForbiddenException('No user in request');
+        const nodeId = request.params?.[options.nodeParam];
+        if (!nodeId || !UUID.test(nodeId)) {
+            throw new common_1.BadRequestException({ message: `Route parameter "${options.nodeParam}" must be a node id (uuid).` });
+        }
+        request[current_node_decorator_1.NODE_ROUTE_REQUEST_KEY] = await this.ownership.assertOwnership(userId, nodeId);
+        return true;
+    }
+};
+exports.NodeRouteGuard = NodeRouteGuard;
+exports.NodeRouteGuard = NodeRouteGuard = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [core_1.Reflector,
+        node_ownership_1.NodeOwnershipService])
+], NodeRouteGuard);
+//# sourceMappingURL=node-route.guard.js.map

package/dist/nodes/node-route.guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-route.guard.js","sourceRoot":"","sources":["../../src/nodes/node-route.guard.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAMwB;AACxB,uCAAyC;AAGzC,qEAAkE;AAClE,6DAAoH;AACpH,qDAAwD;AAExD,MAAM,IAAI,GAAG,iEAAiE,CAAC;AAU/E,MAAM,IAAI,GAA4D,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;AAE9G;;;;;;;GAOG;AAEI,IAAM,cAAc,GAApB,MAAM,cAAc;IAEN;IACA;IAFnB,YACmB,SAAoB,EACpB,SAA+B;QAD/B,cAAS,GAAT,SAAS,CAAW;QACpB,cAAS,GAAT,SAAS,CAAsB;IAC/C,CAAC;IAEJ;;;OAGG;IACH,KAAK,CAAC,WAAW,CAAC,OAAyB;QACzC,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,iBAAiB,CAAuC,wCAAmB,EAAE;YAC1G,OAAO,CAAC,UAAU,EAAE;YACpB,OAAO,CAAC,QAAQ,EAAE;SACnB,CAAC,CAAC;QACH,oEAAoE;QACpE,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,2BAAkB,CAAC,qCAAqC,CAAC,CAAC;QAElF,MAAM,OAAO,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,UAAU,EAAoB,CAAC;QACtE,MAAM,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC1F,IAAI,CAAC,UAAU,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;YAC7D,MAAM,IAAI,2BAAkB,CAAC;gBAC3B,OAAO,EAAE,qDAAqD;gBAC9D,OAAO,EAAE,EAAE,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,EAAE;aAChD,CAAC,CAAC;QACL,CAAC;QAED,IAAI,OAAO,CAAC,SAAS,KAAK,KAAK;YAAE,OAAO,IAAI,CAAC;QAE7C,MAAM,MAAM,GAAG,CAAC,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;QACzD,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,2BAAkB,CAAC,oBAAoB,CAAC,CAAC;QAEhE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACnD,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,4BAAmB,CAAC,EAAE,OAAO,EAAE,oBAAoB,OAAO,CAAC,SAAS,6BAA6B,EAAE,CAAC,CAAC;QACjH,CAAC;QAED,OAAO,CAAC,+CAAsB,CAAC,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACvF,OAAO,IAAI,CAAC;IACd,CAAC;CACF,CAAA;AAxCY,wCAAc;yBAAd,cAAc;IAD1B,IAAA,mBAAU,GAAE;qCAGmB,gBAAS;QACT,qCAAoB;GAHvC,cAAc,CAwC1B"}

package/dist/nodes/node-route.module.d.ts

@@ -0,0 +1,21 @@
+import type { Type } from '@nestjs/common';
+/**
+ * The problems with the `@NodeRoute()` controllers given, one message each.
+ *
+ * @param controllers - controller classes.
+ * @returns the violations; empty when every node route is placed correctly.
+ *
+ * @stability experimental
+ */
+export declare function findNodeRoutePlacementProblems(controllers: ReadonlyArray<Type<unknown>>): string[];
+/**
+ * Provides and exports `NodeRouteGuard` and `NodeOwnershipService`, and runs the
+ * placement check at bootstrap. Import it where a `@NodeRoute()` controller is
+ * declared.
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export declare class NodeRouteModule {
+}
+//# sourceMappingURL=node-route.module.d.ts.map

package/dist/nodes/node-route.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-route.module.d.ts","sourceRoot":"","sources":["../../src/nodes/node-route.module.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAAC,WAAW,EAAE,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,MAAM,EAAE,CAkBlG;AAkBD;;;;;;;GAOG;AACH,qBAKa,eAAe;CAAG"}

package/dist/nodes/node-route.module.js

@@ -0,0 +1,99 @@
+"use strict";
+// =============================================================================
+// NodeRouteModule: what a feature module imports to use @NodeRoute()
+// =============================================================================
+//
+// `NodesModule` does not export `NodesService` (a feature module that could
+// inject it could claim and settle jobs). This module is the narrow door: it
+// provides `NodeRouteGuard` (the guard `@NodeRoute()` applies is instantiated
+// in the module of the controller that uses it) and `NodeOwnershipService`
+// (the ownership rule alone), and it fails the application at bootstrap when a
+// `@NodeRoute()` controller sits outside `/api/nodes` or overlaps a reserved
+// sub-path. Import it in each module that declares a node route controller.
+// =============================================================================
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeRouteModule = void 0;
+exports.findNodeRoutePlacementProblems = findNodeRoutePlacementProblems;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const index_1 = require("../identity/index");
+const node_route_options_1 = require("./node-route.options");
+const node_route_paths_1 = require("./node-route.paths");
+const node_ownership_1 = require("./node-ownership");
+const node_route_guard_1 = require("./node-route.guard");
+/**
+ * The problems with the `@NodeRoute()` controllers given, one message each.
+ *
+ * @param controllers - controller classes.
+ * @returns the violations; empty when every node route is placed correctly.
+ *
+ * @stability experimental
+ */
+function findNodeRoutePlacementProblems(controllers) {
+    const problems = [];
+    for (const controller of controllers) {
+        const classDeclared = Reflect.getMetadata(node_route_options_1.NODE_ROUTE_METADATA, controller) !== undefined;
+        for (const route of (0, node_route_paths_1.controllerRoutes)(controller)) {
+            const handler = controller.prototype[route.handler];
+            if (!classDeclared && Reflect.getMetadata(node_route_options_1.NODE_ROUTE_METADATA, handler) === undefined)
+                continue;
+            if (route.nodeSegments === null) {
+                problems.push(`${route.id} is a @NodeRoute() but its path "/${route.path}" is not under ${index_1.NODE_ROUTE_PREFIX}.`);
+                continue;
+            }
+            const reserved = (0, node_route_paths_1.reservedNodeSubpathOverlap)(route.nodeSegments);
+            if (reserved !== null) {
+                problems.push(`${route.id} (${index_1.NODE_ROUTE_PREFIX}/${route.nodeSegments.join('/')}) overlaps the platform-reserved sub-path "${reserved}".`);
+            }
+        }
+    }
+    return problems;
+}
+let NodeRoutePlacementCheck = class NodeRoutePlacementCheck {
+    discovery;
+    constructor(discovery) {
+        this.discovery = discovery;
+    }
+    onApplicationBootstrap() {
+        const controllers = this.discovery
+            .getControllers()
+            .map((wrapper) => wrapper.metatype)
+            .filter((type) => typeof type === 'function');
+        const problems = findNodeRoutePlacementProblems(controllers);
+        if (problems.length > 0) {
+            throw new Error(`Invalid @NodeRoute() placement:\n- ${problems.join('\n- ')}`);
+        }
+    }
+};
+NodeRoutePlacementCheck = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [core_1.DiscoveryService])
+], NodeRoutePlacementCheck);
+/**
+ * Provides and exports `NodeRouteGuard` and `NodeOwnershipService`, and runs the
+ * placement check at bootstrap. Import it where a `@NodeRoute()` controller is
+ * declared.
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+let NodeRouteModule = class NodeRouteModule {
+};
+exports.NodeRouteModule = NodeRouteModule;
+exports.NodeRouteModule = NodeRouteModule = __decorate([
+    (0, common_1.Module)({
+        imports: [core_1.DiscoveryModule],
+        providers: [node_ownership_1.NodeOwnershipService, node_route_guard_1.NodeRouteGuard, NodeRoutePlacementCheck],
+        exports: [node_ownership_1.NodeOwnershipService, node_route_guard_1.NodeRouteGuard],
+    })
+], NodeRouteModule);
+//# sourceMappingURL=node-route.module.js.map

package/dist/nodes/node-route.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-route.module.js","sourceRoot":"","sources":["../../src/nodes/node-route.module.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,qEAAqE;AACrE,gFAAgF;AAChF,EAAE;AACF,4EAA4E;AAC5E,6EAA6E;AAC7E,8EAA8E;AAC9E,2EAA2E;AAC3E,+EAA+E;AAC/E,6EAA6E;AAC7E,4EAA4E;AAC5E,gFAAgF;;;;;;;;;;;;AAoBhF,wEAkBC;AApCD,2CAA4E;AAC5E,uCAAiE;AAEjE,6CAAsD;AACtD,6DAA2D;AAC3D,yDAAkF;AAClF,qDAAwD;AACxD,yDAAoD;AAGpD;;;;;;;GAOG;AACH,SAAgB,8BAA8B,CAAC,WAAyC;IACtF,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACrC,MAAM,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC,wCAAmB,EAAE,UAAU,CAAC,KAAK,SAAS,CAAC;QACzF,KAAK,MAAM,KAAK,IAAI,IAAA,mCAAgB,EAAC,UAAU,CAAC,EAAE,CAAC;YACjD,MAAM,OAAO,GAAI,UAAU,CAAC,SAAqC,CAAC,KAAK,CAAC,OAAO,CAAW,CAAC;YAC3F,IAAI,CAAC,aAAa,IAAI,OAAO,CAAC,WAAW,CAAC,wCAAmB,EAAE,OAAO,CAAC,KAAK,SAAS;gBAAE,SAAS;YAChG,IAAI,KAAK,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;gBAChC,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,EAAE,qCAAqC,KAAK,CAAC,IAAI,kBAAkB,yBAAiB,GAAG,CAAC,CAAC;gBAChH,SAAS;YACX,CAAC;YACD,MAAM,QAAQ,GAAG,IAAA,6CAA0B,EAAC,KAAK,CAAC,YAAY,CAAC,CAAC;YAChE,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;gBACtB,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,EAAE,KAAK,yBAAiB,IAAI,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,8CAA8C,QAAQ,IAAI,CAAC,CAAC;YAC7I,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,IACM,uBAAuB,GAD7B,MACM,uBAAuB;IACE;IAA7B,YAA6B,SAA2B;QAA3B,cAAS,GAAT,SAAS,CAAkB;IAAG,CAAC;IAE5D,sBAAsB;QACpB,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS;aAC/B,cAAc,EAAE;aAChB,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,QAAgC,CAAC;aAC1D,MAAM,CAAC,CAAC,IAAI,EAAyB,EAAE,CAAC,OAAO,IAAI,KAAK,UAAU,CAAC,CAAC;QACvE,MAAM,QAAQ,GAAG,8BAA8B,CAAC,WAAW,CAAC,CAAC;QAC7D,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,sCAAsC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACjF,CAAC;IACH,CAAC;CACF,CAAA;AAbK,uBAAuB;IAD5B,IAAA,mBAAU,GAAE;qCAE6B,uBAAgB;GADpD,uBAAuB,CAa5B;AAED;;;;;;;GAOG;AAMI,IAAM,eAAe,GAArB,MAAM,eAAe;CAAG,CAAA;AAAlB,0CAAe;0BAAf,eAAe;IAL3B,IAAA,eAAM,EAAC;QACN,OAAO,EAAE,CAAC,sBAAe,CAAC;QAC1B,SAAS,EAAE,CAAC,qCAAoB,EAAE,iCAAc,EAAE,uBAAuB,CAAC;QAC1E,OAAO,EAAE,CAAC,qCAAoB,EAAE,iCAAc,CAAC;KAChD,CAAC;GACW,eAAe,CAAG"}

package/dist/nodes/node-route.options.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The credential kinds a node route can admit: `nod` (a worker-node
+ * credential), `pat` (a personal access token) and `jwt` (a session token).
+ *
+ * @stability stable
+ */
+export type NodeRouteCredential = 'nod' | 'pat' | 'jwt';
+/**
+ * Options of {@link NodeRoute}.
+ *
+ * @stability stable
+ */
+export interface NodeRouteOptions {
+    /**
+     * Credential kinds admitted. Default `['nod', 'pat', 'jwt']`, as on the
+     * platform's own node routes. `['nod']` makes the route node-only: a human's
+     * PAT or session is refused with 403.
+     */
+    credentials?: ReadonlyArray<NodeRouteCredential>;
+    /**
+     * The route parameter holding the node id; node ownership is enforced before
+     * the handler runs. Default `'id'`. `false` for a route that names no node
+     * (it then has no `CurrentNode()`).
+     */
+    nodeParam?: string | false;
+    /** Permissions required, as `@Auth({ permissions })`. Default `['nodes:write']`, the platform node plane's. */
+    permissions?: string[];
+}
+/**
+ * The options of a node route with the defaults applied.
+ *
+ * @stability experimental
+ */
+export interface ResolvedNodeRouteOptions {
+    /** The admitted credential kinds. */
+    readonly credentials: ReadonlyArray<NodeRouteCredential>;
+    /** The route parameter holding the node id, or `false`. */
+    readonly nodeParam: string | false;
+    /** The permissions required. */
+    readonly permissions: readonly string[];
+}
+/**
+ * Metadata key under which {@link NodeRoute} records its resolved options.
+ *
+ * @stability experimental
+ */
+export declare const NODE_ROUTE_METADATA = "platform:node-route";
+/** The default admitted credential kinds. */
+export declare const DEFAULT_NODE_ROUTE_CREDENTIALS: ReadonlyArray<NodeRouteCredential>;
+/**
+ * Resolves the options a route declared against the defaults.
+ *
+ * @param options - what was passed to {@link NodeRoute}.
+ * @returns the effective options.
+ *
+ * @stability experimental
+ */
+export declare function resolveNodeRouteOptions(options?: NodeRouteOptions): ResolvedNodeRouteOptions;
+//# sourceMappingURL=node-route.options.d.ts.map

package/dist/nodes/node-route.options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-route.options.d.ts","sourceRoot":"","sources":["../../src/nodes/node-route.options.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAExD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,WAAW,CAAC,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;IACjD;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAC3B,+GAA+G;IAC/G,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,qCAAqC;IACrC,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;IACzD,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK,CAAC;IACnC,gCAAgC;IAChC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,wBAAwB,CAAC;AAEzD,6CAA6C;AAC7C,eAAO,MAAM,8BAA8B,EAAE,aAAa,CAAC,mBAAmB,CAAwC,CAAC;AAEvH;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,gBAAqB,GAAG,wBAAwB,CAMhG"}

package/dist/nodes/node-route.options.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_NODE_ROUTE_CREDENTIALS = exports.NODE_ROUTE_METADATA = void 0;
+exports.resolveNodeRouteOptions = resolveNodeRouteOptions;
+const nodes_permissions_1 = require("./nodes.permissions");
+/**
+ * Metadata key under which {@link NodeRoute} records its resolved options.
+ *
+ * @stability experimental
+ */
+exports.NODE_ROUTE_METADATA = 'platform:node-route';
+/** The default admitted credential kinds. */
+exports.DEFAULT_NODE_ROUTE_CREDENTIALS = Object.freeze(['nod', 'pat', 'jwt']);
+/**
+ * Resolves the options a route declared against the defaults.
+ *
+ * @param options - what was passed to {@link NodeRoute}.
+ * @returns the effective options.
+ *
+ * @stability experimental
+ */
+function resolveNodeRouteOptions(options = {}) {
+    return {
+        credentials: options.credentials && options.credentials.length > 0 ? [...options.credentials] : exports.DEFAULT_NODE_ROUTE_CREDENTIALS,
+        nodeParam: options.nodeParam === undefined ? 'id' : options.nodeParam,
+        permissions: options.permissions ?? [nodes_permissions_1.NODES_PERMISSIONS.NODES_WRITE.id],
+    };
+}
+//# sourceMappingURL=node-route.options.js.map

package/dist/nodes/node-route.options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-route.options.js","sourceRoot":"","sources":["../../src/nodes/node-route.options.ts"],"names":[],"mappings":";;;AAgEA,0DAMC;AAtED,2DAAwD;AA8CxD;;;;GAIG;AACU,QAAA,mBAAmB,GAAG,qBAAqB,CAAC;AAEzD,6CAA6C;AAChC,QAAA,8BAA8B,GAAuC,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;AAEvH;;;;;;;GAOG;AACH,SAAgB,uBAAuB,CAAC,UAA4B,EAAE;IACpE,OAAO;QACL,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,sCAA8B;QAC9H,SAAS,EAAE,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS;QACrE,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,CAAC,qCAAiB,CAAC,WAAW,CAAC,EAAE,CAAC;KACvE,CAAC;AACJ,CAAC"}

package/dist/nodes/node-route.paths.d.ts

@@ -0,0 +1,47 @@
+import type { Type } from '@nestjs/common';
+/**
+ * The sub-paths of `/api/nodes` the platform owns, relative to the collection,
+ * with `:param` for a path parameter. `''` is the collection itself; a trailing
+ * `/*` reserves everything beneath. A `@NodeRoute()` route that overlaps one
+ * (a parameter overlaps a literal, the HTTP method is ignored) fails at
+ * bootstrap and in the `nodes` conformance suite. Mount an app feature on a
+ * sub-path NOT listed here, for example `nodes/:id/<feature>/...`.
+ *
+ * @stability stable
+ */
+export declare const RESERVED_NODE_SUBPATHS: readonly string[];
+/**
+ * One route of a controller, as the node-route checks see it.
+ *
+ * @stability experimental
+ */
+export interface NodeControllerRoute {
+    /** `Controller#handler`. */
+    readonly id: string;
+    /** The handler's method name. */
+    readonly handler: string;
+    /** The full path without the global prefix, for example `nodes/:id/backup/changes`. */
+    readonly path: string;
+    /** The segments of `path` after the `nodes` collection, for example `[':id', 'backup', 'changes']`; `null` when the route is not under `/api/nodes`. */
+    readonly nodeSegments: readonly string[] | null;
+}
+/**
+ * Every route of `controller` with its full path. A leading `api` segment (the
+ * global prefix) is dropped, so `api/nodes/x` and `nodes/x` read the same.
+ *
+ * @param controller - a controller class.
+ * @returns one entry per handler per declared path.
+ *
+ * @stability experimental
+ */
+export declare function controllerRoutes(controller: Type<unknown>): NodeControllerRoute[];
+/**
+ * The reserved sub-path a route overlaps, or `null`.
+ *
+ * @param nodeSegments - the route's segments after `nodes`.
+ * @returns the entry of {@link RESERVED_NODE_SUBPATHS} it collides with.
+ *
+ * @stability stable
+ */
+export declare function reservedNodeSubpathOverlap(nodeSegments: readonly string[]): string | null;
+//# sourceMappingURL=node-route.paths.d.ts.map

package/dist/nodes/node-route.paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-route.paths.d.ts","sourceRoot":"","sources":["../../src/nodes/node-route.paths.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAK3C;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAYlD,CAAC;AAEH;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uFAAuF;IACvF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wJAAwJ;IACxJ,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;CACjD;AAeD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,mBAAmB,EAAE,CAyBjF;AAmBD;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAUzF"}