@marinoscar/platform-api 0.1.0-next.3 → 0.1.0-next.5

package/dist/nodes/node-credential.service.js

@@ -0,0 +1,406 @@
+"use strict";
+// =============================================================================
+// NodeCredentialService — the `nod_` bearer credential (issue #267, epic #254)
+// =============================================================================
+//
+// A worker node has to authenticate to the API before it can register,
+// heartbeat, claim a job or report a result (#268). This service mints and
+// validates the credential it does that with.
+//
+// It is modelled DELIBERATELY CLOSELY on `pat/pat.service.ts` — same
+// `randomBytes(32).toString('hex')` entropy, same sha256-at-rest, same short
+// display prefix, same show-the-raw-value-exactly-once contract, same
+// fire-and-forget `lastUsedAt` stamp. Where the two differ, the difference is
+// load-bearing and is written out at the point it appears. Reading the two
+// side by side should make every divergence obvious; anything that looks the
+// same IS the same, on purpose.
+//
+// -----------------------------------------------------------------------------
+// WHY THIS EXISTS AT ALL, RATHER THAN REUSING A PAT
+// -----------------------------------------------------------------------------
+//
+// The tempting answer is "a node is just another automated client, give it a
+// PAT". That answer is wrong, and it is wrong in a way that only shows up
+// after a leak.
+//
+// A PAT carries its owner's FULL AUTHORITY. `JwtAuthGuard` resolves a `pat_`
+// token to the owning `AuthenticatedUser` and hands it to `RolesGuard` and
+// `PermissionsGuard` exactly as the JWT strategy would, and
+// `test/auth/pat-universality.integration.spec.ts` exists specifically to
+// prove that this holds on EVERY authenticated route with no narrower scope —
+// that universality is a documented promise of this API, not an accident.
+//
+// Now consider where a node credential physically lives: a config file on a
+// spare box, a container image someone else's cluster pulls, a `.env` on a
+// machine nobody has patched since it was set up, read by a long-lived
+// process that nobody is watching. If the credential sitting there is a PAT
+// and its owner is an admin — and the owner IS an admin, because
+// `nodes:write` is admin-only in `prisma/seed-data.ts` — then whoever reads
+// that file owns the deployment: `PATCH /api/users/:id` to grant themselves
+// a role, `PUT /api/system-settings`, the lot.
+//
+// So a node credential is a SEPARATE TOKEN FAMILY with its own prefix, and
+// the guard confines that prefix to `/api/nodes/*` by route allowlist. The
+// blast radius of a leaked worker token becomes "can pretend to be a worker",
+// which is bad but bounded and observable, instead of "is an administrator".
+// The allowlist lives in the guard rather than in this service; see
+// `auth/guards/jwt-auth.guard.ts` and docs/specs/worker-nodes.md for why.
+//
+// -----------------------------------------------------------------------------
+// WHAT THIS SERVICE IS NOT RESPONSIBLE FOR
+// -----------------------------------------------------------------------------
+//
+// It does not know which routes a `nod_` token may reach. `validateToken`
+// answers exactly one question — "is this string a live credential, and whose
+// is it" — and returns an `AuthenticatedUser` or `null`. It has more than one
+// caller by design (the guard today; #268's node control plane may well want
+// to resolve a credential without an HTTP request in front of it), and a
+// route allowlist buried in here would be an authorization decision made by a
+// component that cannot see the route. Rejected alternative, recorded in
+// docs/specs/worker-nodes.md.
+// =============================================================================
+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); }
+};
+var NodeCredentialService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeCredentialService = exports.CREDENTIAL_OWNER_SELECT = exports.NODE_TOKEN_PREFIX = void 0;
+const common_1 = require("@nestjs/common");
+const index_1 = require("../core/index");
+const node_crypto_1 = require("node:crypto");
+const index_2 = require("../identity/index");
+/**
+ * The token family marker.
+ *
+ * It is a CONSTANT and not a literal typed four times because three separate
+ * components have to agree on it or the security model quietly stops working:
+ * this service (which mints it), `JwtAuthGuard` (which routes on it), and
+ * `MaintenanceGuard.OPAQUE_BEARER_PREFIXES` (which refuses to treat it as an
+ * admin bypass). A typo in any one of them is not a crash — it is a token
+ * that falls through to a different branch and is handled by the wrong rules.
+  *
+  * @stability experimental
+ */
+exports.NODE_TOKEN_PREFIX = 'nod_';
+/** Hex characters of the random part kept in `tokenPrefix` for display. */
+const DISPLAY_PREFIX_HEX_CHARS = 4;
+/** One day in milliseconds — the unit `expiresInDays` is expressed in. */
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+/**
+ * The owner columns {@link NodeCredentialService.listAllCredentials} joins.
+ *
+ * Hoisted out of the inline `select` (and exported) for the same reason
+ * `nodes-admin.service.ts`'s `OWNER_SELECT` is: it lets
+ * `test/nodes/worker-node-model-fields.spec.ts` assert its keys are real
+ * `User` scalar columns, which is the check issue #340 (a `name` column that
+ * does not exist) would have failed instantly.
+  *
+  * @stability experimental
+ */
+exports.CREDENTIAL_OWNER_SELECT = {
+    select: { id: true, email: true, displayName: true },
+};
+/**
+ * Mints, lists, validates and revokes the `nod_` node credentials (hashed at rest).
+ *
+ * @stability experimental
+ */
+let NodeCredentialService = NodeCredentialService_1 = class NodeCredentialService {
+    prisma;
+    logger = new common_1.Logger(NodeCredentialService_1.name);
+    constructor(prisma) {
+        this.prisma = prisma;
+    }
+    /**
+     * Hashes a raw token the one way this service ever hashes one.
+     *
+     * A single private helper rather than an inlined `createHash(...)` at each
+     * of the two sites (mint, validate) because those two MUST agree exactly:
+     * if minting and validating ever computed a different digest — a different
+     * algorithm, a different encoding, a stray `.trim()` on one side — every
+     * credential would mint successfully and then fail to authenticate, and the
+     * symptom ("the node can't log in") points nowhere near the cause. One
+     * function means the two cannot drift.
+     *
+     * sha256 with no salt and no key stretching, matching `PatService`. That is
+     * correct HERE and would not be for a password: the preimage is 32 bytes of
+     * `randomBytes` entropy, so there is no dictionary to run and no work
+     * factor that would meaningfully slow an attacker who cannot guess 256 bits
+     * in the first place. What the hash buys is that a database dump does not
+     * hand over working credentials — and it buys that at a cost small enough
+     * to run on the authentication path of every worker request.
+     */
+    hash(rawToken) {
+        return (0, node_crypto_1.createHash)('sha256').update(rawToken).digest('hex');
+    }
+    /**
+     * Mints a credential and returns the raw token — THE ONLY TIME IT EXISTS
+     * OUTSIDE THE CALLER'S PROCESS.
+     *
+     * The row stores `hash()`'s output and a short display prefix; the
+     * plaintext is never written anywhere, never logged (note that the log line
+     * below names the credential and its owner and NOT the token), and cannot
+     * be recovered. An operator who loses it revokes and mints again — which is
+     * the same amount of work as a "show it to me again" endpoint would be, but
+     * without a second, permanently-reachable path to a live credential.
+     */
+    async createCredential(userId, dto) {
+        // 32 bytes = 256 bits of entropy, hex-encoded to 64 characters. Identical
+        // to `PatService.createToken` on purpose: this is the number that makes
+        // guessing a token irrelevant as an attack, and there is no reason for
+        // the two token families to have different strength.
+        const hexPart = (0, node_crypto_1.randomBytes)(32).toString('hex');
+        const rawToken = `${exports.NODE_TOKEN_PREFIX}${hexPart}`;
+        const tokenHash = this.hash(rawToken);
+        // e.g. `nod_1a2b` — enough to tell two credentials apart in a list, far
+        // too little to narrow a search of the remaining 240 bits.
+        const tokenPrefix = `${exports.NODE_TOKEN_PREFIX}${hexPart.slice(0, DISPLAY_PREFIX_HEX_CHARS)}`;
+        // `undefined` → `null` in the row → "never expires". See the block
+        // comment above `NodeCredential.expiresAt` in `prisma/schema.prisma`, and
+        // `dto/create-node-credential.dto.ts`, for why this is a supported
+        // outcome rather than a missing value. Computed from the SERVER's clock,
+        // which is the clock `validateToken` later compares against.
+        const expiresAt = dto.expiresInDays === undefined
+            ? null
+            : new Date(Date.now() + dto.expiresInDays * MS_PER_DAY);
+        const credential = await this.prisma.nodeCredential.create({
+            data: {
+                userId,
+                name: dto.name,
+                tokenHash,
+                tokenPrefix,
+                expiresAt,
+            },
+        });
+        this.logger.log(`Created node credential "${credential.name}" (${credential.id}) for user ${userId}` +
+            `${expiresAt ? `, expiring ${expiresAt.toISOString()}` : ', no expiry'}`);
+        return {
+            token: rawToken,
+            id: credential.id,
+            name: credential.name,
+            tokenPrefix: credential.tokenPrefix,
+            expiresAt: credential.expiresAt ? credential.expiresAt.toISOString() : null,
+            createdAt: credential.createdAt.toISOString(),
+        };
+    }
+    /**
+     * Lists the caller's own credentials, masked.
+     *
+     * The `select` is an ALLOWLIST, not an omission of `tokenHash` from a
+     * `where`-only query, and that distinction is the whole point: with an
+     * explicit `select`, a column added to this model in a future migration is
+     * absent from this response until somebody deliberately adds it here. With
+     * a bare `findMany` it would be included the moment the migration lands,
+     * silently, in a response an operator may well paste into a bug report. See
+     * `NodeCredentialListItemDto` for why `tokenHash` in particular must not
+     * appear.
+     */
+    async listCredentials(userId) {
+        return this.prisma.nodeCredential.findMany({
+            where: { userId },
+            orderBy: { createdAt: 'desc' },
+            select: {
+                id: true,
+                name: true,
+                tokenPrefix: true,
+                expiresAt: true,
+                lastUsedAt: true,
+                createdAt: true,
+                revokedAt: true,
+            },
+        });
+    }
+    /**
+     * Revokes one credential, ownership-checked.
+     *
+     * OWNERSHIP IS PART OF THE LOOKUP (`findFirst({ where: { id, userId } })`),
+     * not a check after a `findUnique`. Written the other way round, the
+     * "belongs to someone else" case and the "does not exist" case would take
+     * different branches — and a caller who can tell those two apart can
+     * enumerate other users' credential IDs by watching which 403s become 404s.
+     * Folding the owner into the query makes both cases indistinguishable from
+     * outside, because they are literally the same code path.
+     *
+     * Revoking an already-revoked credential is a 404 rather than a silent
+     * success, matching `PatService.revokeToken`: an operator who is racing
+     * another admin — or a script running twice — should be told the state
+     * changed under them, not handed a 204 that implies they did something.
+     * Either way the credential ends up revoked, and `revokedAt` keeps the
+     * FIRST revocation's timestamp, which is the one that actually cut the node
+     * off.
+     */
+    async revokeCredential(userId, credentialId) {
+        return this.revokeMatching({ id: credentialId, userId }, `user ${userId}`);
+    }
+    /**
+     * Lists EVERY credential in the deployment with its owner, masked (#270).
+     *
+     * The admin half of `listCredentials` above, and it exists because a
+     * `NodeCredential` has no mandatory expiry (see the model's own comment):
+     * the only thing that ever cuts a worker token off is somebody revoking it,
+     * and somebody can only revoke what they can see. An administrator who can
+     * see their own credentials and not the fleet's has no way to answer "which
+     * long-lived tokens can reach this API", which is the question the whole
+     * `nod_` design leans on being answerable.
+     *
+     * The `select` is an ALLOWLIST for exactly the reason `listCredentials`
+     * gives — a column added by a future migration must not appear here until
+     * somebody adds it deliberately — and `tokenHash` is absent from it. That
+     * matters MORE on this surface than on the owner-scoped one: this response
+     * carries every credential in the deployment at once, so a hash leaked here
+     * is an offline verification oracle for the entire fleet.
+     *
+     * Not paginated. This is bounded by how many worker machines an operator
+     * runs, which is a number they chose and can see; a page cursor over a list
+     * an admin is scanning for anomalies would hide the anomaly on page two.
+     */
+    async listAllCredentials() {
+        return (await this.prisma.nodeCredential.findMany({
+            orderBy: { createdAt: 'desc' },
+            select: {
+                id: true,
+                name: true,
+                tokenPrefix: true,
+                expiresAt: true,
+                lastUsedAt: true,
+                createdAt: true,
+                revokedAt: true,
+                user: exports.CREDENTIAL_OWNER_SELECT,
+            },
+        }));
+    }
+    /**
+     * Revokes ANY credential, whoever owns it (#270).
+     *
+     * The ownership half of the `where` is dropped, and nothing else changes —
+     * both paths go through `revokeMatching` so revocation stays ONE piece of
+     * code with one definition of "already revoked" and one place that stamps
+     * `revokedAt`. A second hand-written revoke for admins is how the two
+     * acquire different semantics for the second call.
+     *
+     * The enumeration argument that shapes the owner-scoped path does NOT apply
+     * here: an administrator is allowed to know which credential ids exist, so
+     * "not found" being distinguishable from "someone else's" costs nothing.
+     * The 404 shape is kept anyway, because the caller cannot tell them apart
+     * either way and one message is easier to test than two.
+     */
+    async revokeAnyCredential(credentialId) {
+        return this.revokeMatching({ id: credentialId }, 'an administrator');
+    }
+    /**
+     * The one revocation, with the caller's scope folded into the lookup.
+     *
+     * OWNERSHIP IS PART OF THE `where` rather than a check after a `findUnique`
+     * — see `revokeCredential`'s doc comment for the enumeration oracle that
+     * prevents. `actor` is only ever a log string; it is never a second place
+     * authorization is decided.
+     */
+    async revokeMatching(where, actor) {
+        const credential = await this.prisma.nodeCredential.findFirst({ where });
+        if (!credential) {
+            throw new common_1.NotFoundException('Node credential not found');
+        }
+        if (credential.revokedAt !== null) {
+            throw new common_1.NotFoundException('Node credential already revoked');
+        }
+        await this.prisma.nodeCredential.update({
+            where: { id: credential.id },
+            data: { revokedAt: new Date() },
+        });
+        this.logger.log(`Revoked node credential "${credential.name}" (${credential.id}) for ${actor}`);
+    }
+    /**
+     * Resolves a raw `nod_…` token to its owning user, or `null`.
+     *
+     * `null` FOR EVERY FAILURE, WITH NO DETAIL. Unknown hash, revoked,
+     * expired, inactive owner — all four return the same thing, and the caller
+     * (`JwtAuthGuard`) turns all four into the same 401 with the same message.
+     * Distinguishing them would tell an attacker holding a stolen token whether
+     * it was ever real, which is exactly the fact they are trying to establish.
+     *
+     * THE ORDER OF THE FOUR CHECKS IS NOT SIGNIFICANT TO SECURITY — they all
+     * produce the same answer — but it IS significant that all four exist, so
+     * each is written as its own statement with its own reason rather than
+     * being collapsed into one clever `where` clause. A compound `where` that
+     * returns `null` cannot be debugged, and cannot be unit-tested one
+     * condition at a time.
+     */
+    async validateToken(rawToken) {
+        const tokenHash = this.hash(rawToken);
+        // Looked up BY HASH, never by prefix or id. `tokenHash` is `@unique`, so
+        // this is a single index probe regardless of how many credentials exist —
+        // which matters because this runs on every authenticated worker request.
+        const credential = (await this.prisma.nodeCredential.findUnique({
+            where: { tokenHash },
+            include: {
+                // System roles and memberships with their org roles (PP-6.3, #723):
+                // the graph every credential path loads (auth/principal.factory.ts).
+                user: { include: index_2.PRINCIPAL_USER_INCLUDE },
+            },
+        }));
+        // Unknown token. Also covers a token from a deleted user: the row went
+        // with the account (`onDelete: Cascade`), so there is nothing to find.
+        if (!credential) {
+            return null;
+        }
+        // Revoked. This is the PRIMARY control for a node credential — see the
+        // `expiresAt` block comment in `prisma/schema.prisma` — and it is
+        // deliberately checked against the row on every request rather than
+        // cached anywhere, so revocation takes effect on the node's very next
+        // call and not at the end of some TTL.
+        if (credential.revokedAt !== null) {
+            return null;
+        }
+        // Expired — but ONLY when an expiry was set. `expiresAt === null` means
+        // "never expires" and MUST NOT be treated as "expired at the epoch"; that
+        // inversion is the single most damaging bug this method could contain,
+        // because it would take an entire fleet offline at once while every row
+        // still looked perfectly healthy in the database. Comparison is `<=` so a
+        // credential is dead at its stated instant, not one millisecond after.
+        if (credential.expiresAt !== null && credential.expiresAt <= new Date()) {
+            return null;
+        }
+        // A deactivated human must not keep authenticating through a machine they
+        // set up. Checked here — and not left to a downstream guard — for the
+        // same reason `PatService` checks it: this method is the point at which a
+        // string becomes an identity, and an identity that should not exist must
+        // not be minted in the first place.
+        if (!credential.user.isActive) {
+            return null;
+        }
+        // FIRE AND FORGET, AND THAT IS THE POINT. `lastUsedAt` is operator
+        // telemetry ("is this node still alive, is this credential safe to
+        // revoke"), not an authorization input, so it must never be able to fail
+        // an authentication that has already succeeded, and must never add its
+        // write latency to the worker's request. The `.catch(() => {})` is
+        // load-bearing: without it a rejected promise here becomes an
+        // unhandled rejection that can take the process down, on the one code
+        // path that runs for every single worker request.
+        this.prisma.nodeCredential
+            .update({ where: { id: credential.id }, data: { lastUsedAt: new Date() } })
+            .catch(() => { });
+        // System-scoped (ADR 0001, #724): a node credential acts in no
+        // organization, so only its owner's SYSTEM grants count (`activeOrgId`
+        // null), and the principal records `tokenKind: 'node'`.
+        return (0, index_2.stampCredential)(credential.user, {
+            activeOrgId: null,
+            tokenKind: 'node',
+        });
+    }
+};
+exports.NodeCredentialService = NodeCredentialService;
+exports.NodeCredentialService = NodeCredentialService = NodeCredentialService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(index_1.PLATFORM_PRISMA)),
+    __metadata("design:paramtypes", [Object])
+], NodeCredentialService);
+//# sourceMappingURL=node-credential.service.js.map

package/dist/nodes/node-credential.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-credential.service.js","sourceRoot":"","sources":["../../src/nodes/node-credential.service.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,+EAA+E;AAC/E,gFAAgF;AAChF,EAAE;AACF,uEAAuE;AACvE,2EAA2E;AAC3E,8CAA8C;AAC9C,EAAE;AACF,qEAAqE;AACrE,6EAA6E;AAC7E,sEAAsE;AACtE,8EAA8E;AAC9E,2EAA2E;AAC3E,6EAA6E;AAC7E,gCAAgC;AAChC,EAAE;AACF,gFAAgF;AAChF,oDAAoD;AACpD,gFAAgF;AAChF,EAAE;AACF,6EAA6E;AAC7E,0EAA0E;AAC1E,gBAAgB;AAChB,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,4DAA4D;AAC5D,0EAA0E;AAC1E,8EAA8E;AAC9E,0EAA0E;AAC1E,EAAE;AACF,4EAA4E;AAC5E,2EAA2E;AAC3E,uEAAuE;AACvE,4EAA4E;AAC5E,iEAAiE;AACjE,4EAA4E;AAC5E,4EAA4E;AAC5E,+CAA+C;AAC/C,EAAE;AACF,2EAA2E;AAC3E,2EAA2E;AAC3E,8EAA8E;AAC9E,6EAA6E;AAC7E,oEAAoE;AACpE,0EAA0E;AAC1E,EAAE;AACF,gFAAgF;AAChF,2CAA2C;AAC3C,gFAAgF;AAChF,EAAE;AACF,0EAA0E;AAC1E,8EAA8E;AAC9E,8EAA8E;AAC9E,6EAA6E;AAC7E,yEAAyE;AACzE,8EAA8E;AAC9E,yEAAyE;AACzE,8BAA8B;AAC9B,gFAAgF;;;;;;;;;;;;;;;;AAEhF,2CAA+E;AAE/E,yCAAgD;AAChD,6CAAsD;AACtD,6CAI2B;AAG3B;;;;;;;;;;;GAWG;AACU,QAAA,iBAAiB,GAAG,MAAM,CAAC;AAExC,2EAA2E;AAC3E,MAAM,wBAAwB,GAAG,CAAC,CAAC;AAEnC,0EAA0E;AAC1E,MAAM,UAAU,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAqDvC;;;;;;;;;;GAUG;AACU,QAAA,uBAAuB,GAGhC;IACF,MAAM,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE;CACrD,CAAC;AAsBF;;;;GAIG;AAEI,IAAM,qBAAqB,6BAA3B,MAAM,qBAAqB;IAGsB;IAFrC,MAAM,GAAG,IAAI,eAAM,CAAC,uBAAqB,CAAC,IAAI,CAAC,CAAC;IAEjE,YAAsD,MAAkB;QAAlB,WAAM,GAAN,MAAM,CAAY;IAAG,CAAC;IAE5E;;;;;;;;;;;;;;;;;;OAkBG;IACK,IAAI,CAAC,QAAgB;QAC3B,OAAO,IAAA,wBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7D,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,gBAAgB,CACpB,MAAc,EACd,GAA4B;QAE5B,0EAA0E;QAC1E,wEAAwE;QACxE,uEAAuE;QACvE,qDAAqD;QACrD,MAAM,OAAO,GAAG,IAAA,yBAAW,EAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAChD,MAAM,QAAQ,GAAG,GAAG,yBAAiB,GAAG,OAAO,EAAE,CAAC;QAElD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAEtC,wEAAwE;QACxE,2DAA2D;QAC3D,MAAM,WAAW,GAAG,GAAG,yBAAiB,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,wBAAwB,CAAC,EAAE,CAAC;QAExF,mEAAmE;QACnE,0EAA0E;QAC1E,mEAAmE;QACnE,yEAAyE;QACzE,6DAA6D;QAC7D,MAAM,SAAS,GACb,GAAG,CAAC,aAAa,KAAK,SAAS;YAC7B,CAAC,CAAC,IAAI;YACN,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC,aAAa,GAAG,UAAU,CAAC,CAAC;QAE5D,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC;YACzD,IAAI,EAAE;gBACJ,MAAM;gBACN,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,SAAS;gBACT,WAAW;gBACX,SAAS;aACV;SACF,CAAC,CAAC;QAEH,IAAI,CAAC,MAAM,CAAC,GAAG,CACb,4BAA4B,UAAU,CAAC,IAAI,MAAM,UAAU,CAAC,EAAE,cAAc,MAAM,EAAE;YAClF,GAAG,SAAS,CAAC,CAAC,CAAC,cAAc,SAAS,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,EAAE,CAC3E,CAAC;QAEF,OAAO;YACL,KAAK,EAAE,QAAQ;YACf,EAAE,EAAE,UAAU,CAAC,EAAE;YACjB,IAAI,EAAE,UAAU,CAAC,IAAI;YACrB,WAAW,EAAE,UAAU,CAAC,WAAW;YACnC,SAAS,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI;YAC3E,SAAS,EAAE,UAAU,CAAC,SAAS,CAAC,WAAW,EAAE;SAC9C,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,eAAe,CAAC,MAAc;QAClC,OAAO,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC;YACzC,KAAK,EAAE,EAAE,MAAM,EAAE;YACjB,OAAO,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE;YAC9B,MAAM,EAAE;gBACN,EAAE,EAAE,IAAI;gBACR,IAAI,EAAE,IAAI;gBACV,WAAW,EAAE,IAAI;gBACjB,SAAS,EAAE,IAAI;gBACf,UAAU,EAAE,IAAI;gBAChB,SAAS,EAAE,IAAI;gBACf,SAAS,EAAE,IAAI;aAChB;SACF,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,CAAC,gBAAgB,CAAC,MAAc,EAAE,YAAoB;QACzD,OAAO,IAAI,CAAC,cAAc,CAAC,EAAE,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,EAAE,QAAQ,MAAM,EAAE,CAAC,CAAC;IAC7E,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,CAAC,kBAAkB;QACtB,OAAO,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC;YAChD,OAAO,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE;YAC9B,MAAM,EAAE;gBACN,EAAE,EAAE,IAAI;gBACR,IAAI,EAAE,IAAI;gBACV,WAAW,EAAE,IAAI;gBACjB,SAAS,EAAE,IAAI;gBACf,UAAU,EAAE,IAAI;gBAChB,SAAS,EAAE,IAAI;gBACf,SAAS,EAAE,IAAI;gBACf,IAAI,EAAE,+BAAuB;aAC9B;SACF,CAAC,CAAwC,CAAC;IAC7C,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,mBAAmB,CAAC,YAAoB;QAC5C,OAAO,IAAI,CAAC,cAAc,CAAC,EAAE,EAAE,EAAE,YAAY,EAAE,EAAE,kBAAkB,CAAC,CAAC;IACvE,CAAC;IAED;;;;;;;OAOG;IACK,KAAK,CAAC,cAAc,CAC1B,KAAgB,EAChB,KAAa;QAEb,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QAEzE,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,IAAI,0BAAiB,CAAC,2BAA2B,CAAC,CAAC;QAC3D,CAAC;QAED,IAAI,UAAU,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;YAClC,MAAM,IAAI,0BAAiB,CAAC,iCAAiC,CAAC,CAAC;QACjE,CAAC;QAED,MAAM,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC;YACtC,KAAK,EAAE,EAAE,EAAE,EAAE,UAAU,CAAC,EAAE,EAAE;YAC5B,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,EAAE;SAChC,CAAC,CAAC;QAEH,IAAI,CAAC,MAAM,CAAC,GAAG,CACb,4BAA4B,UAAU,CAAC,IAAI,MAAM,UAAU,CAAC,EAAE,SAAS,KAAK,EAAE,CAC/E,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,aAAa,CAAC,QAAgB;QAClC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAEtC,yEAAyE;QACzE,0EAA0E;QAC1E,yEAAyE;QACzE,MAAM,UAAU,GAAG,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,UAAU,CAAC;YAC9D,KAAK,EAAE,EAAE,SAAS,EAAE;YACpB,OAAO,EAAE;gBACP,oEAAoE;gBACpE,qEAAqE;gBACrE,IAAI,EAAE,EAAE,OAAO,EAAE,8BAAsB,EAAE;aAC1C;SACF,CAAC,CAA8D,CAAC;QAEjE,uEAAuE;QACvE,uEAAuE;QACvE,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,uEAAuE;QACvE,kEAAkE;QAClE,oEAAoE;QACpE,sEAAsE;QACtE,uCAAuC;QACvC,IAAI,UAAU,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;YAClC,OAAO,IAAI,CAAC;QACd,CAAC;QAED,wEAAwE;QACxE,0EAA0E;QAC1E,uEAAuE;QACvE,wEAAwE;QACxE,0EAA0E;QAC1E,uEAAuE;QACvE,IAAI,UAAU,CAAC,SAAS,KAAK,IAAI,IAAI,UAAU,CAAC,SAAS,IAAI,IAAI,IAAI,EAAE,EAAE,CAAC;YACxE,OAAO,IAAI,CAAC;QACd,CAAC;QAED,0EAA0E;QAC1E,sEAAsE;QACtE,0EAA0E;QAC1E,yEAAyE;QACzE,oCAAoC;QACpC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC9B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,mEAAmE;QACnE,mEAAmE;QACnE,yEAAyE;QACzE,uEAAuE;QACvE,mEAAmE;QACnE,8DAA8D;QAC9D,sEAAsE;QACtE,kDAAkD;QAClD,IAAI,CAAC,MAAM,CAAC,cAAc;aACvB,MAAM,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,UAAU,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,UAAU,EAAE,IAAI,IAAI,EAAE,EAAE,EAAE,CAAC;aAC1E,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAEnB,+DAA+D;QAC/D,uEAAuE;QACvE,wDAAwD;QACxD,OAAO,IAAA,uBAAe,EAAC,UAAU,CAAC,IAAyB,EAAE;YAC3D,WAAW,EAAE,IAAI;YACjB,SAAS,EAAE,MAAM;SAClB,CAAC,CAAC;IACL,CAAC;CACF,CAAA;AA5TY,sDAAqB;gCAArB,qBAAqB;IADjC,IAAA,mBAAU,GAAE;IAIE,WAAA,IAAA,eAAM,EAAC,uBAAe,CAAC,CAAA;;GAHzB,qBAAqB,CA4TjC"}

package/dist/nodes/node-data-plane.service.d.ts

@@ -0,0 +1,198 @@
+import { ConfigService } from '@nestjs/config';
+import { type JobsPrisma } from '../jobs/index';
+import { JobHandlerRegistry } from '../jobs/index';
+import { type NodeJobInputs, type NodeObjectStore } from './ports';
+import { NodeDownloadUrlDto, NodeDownloadUrlResponseDto, NodeUploadUrlDto, NodeUploadUrlResponseDto } from './dto/node-data-plane.dto';
+import { NodesService } from './nodes.service';
+/**
+ * The longest a node-facing signed URL may live, in seconds.
+ *
+ * FIFTEEN MINUTES, AND IT IS A CEILING RATHER THAN A SETTING. The
+ * application-wide `storage.signedUrlExpiry` defaults to an hour, which is the
+ * right answer for a URL handed to a logged-in person's browser and the wrong
+ * one for a URL handed to an unattended process on hardware this deployment
+ * may not own. A signed URL is a bearer capability: whoever holds the string
+ * has it, so the only thing bounding the damage of one that leaks — into a
+ * node's own debug log, a crash dump, a support ticket, a shell history — is
+ * how long it stays valid.
+ *
+ * Fifteen minutes is long enough for a large object over a slow link and short
+ * enough that a leaked URL is worthless by the time anyone finds it. A node
+ * that needs longer asks again, which costs one request and is available for
+ * as long as it holds the lease.
+ */
+export declare const NODE_SIGNED_URL_MAX_TTL_SECONDS = 900;
+/**
+ * The shortest a node-facing signed URL may live.
+ *
+ * Guards against a deployment that sets `SIGNED_URL_EXPIRY=0` (or something
+ * negative, or unparseable) and thereby hands its whole fleet URLs that expire
+ * before the node can use them — a fleet-wide outage produced by a config
+ * typo, whose symptom is every transfer failing with a provider-side
+ * "expired" error that names nothing about this setting.
+ */
+export declare const NODE_SIGNED_URL_MIN_TTL_SECONDS = 60;
+/**
+ * The prefix every node-written output lands under.
+ *
+ * One namespace, separate from `uploads/` where `ObjectsService` puts
+ * user-uploaded objects, so "what did the fleet write" is answerable with a
+ * single prefix listing and a lifecycle rule can be applied to node output
+ * without touching a single user upload.
+ */
+/**
+ * The key prefix every default node output lands under (`node-outputs/<jobId>/<uuid>`), without the trailing slash.
+ *
+ * @stability experimental
+ */
+export declare const NODE_OUTPUT_KEY_PREFIX = "node-outputs";
+/**
+ * Mints the short-lived signed URLs a node moves a held job's bytes through (`NODE_OBJECT_STORE`).
+ *
+ * @stability experimental
+ */
+export declare class NodeDataPlaneService {
+    private readonly prisma;
+    private readonly config;
+    private readonly nodes;
+    private readonly storage;
+    private readonly registry;
+    private readonly inputs;
+    private readonly logger;
+    constructor(prisma: JobsPrisma, config: ConfigService, nodes: NodesService, storage: NodeObjectStore, registry: JobHandlerRegistry, inputs: NodeJobInputs);
+    /**
+     * A short-lived signed GET for the input object of a job this node holds.
+     *
+     * THE ORDER IS THE CONTRACT, and it is the same discipline `submitResult`
+     * follows: prove the caller may speak for this job, THEN resolve what the
+     * job is about, THEN mint. Nothing is minted for a job whose lease has
+     * lapsed, and nothing is minted for a job whose input cannot be named.
+     *
+     * ⚠ THE URL IS NEVER LOGGED. Not at `debug`, not on the error path, not
+     * "temporarily". It is a bearer capability for the object, and a log line is
+     * the easiest place in a system for one to be copied to somewhere it
+     * outlives its expiry. The log below names the job and the object, which is
+     * everything an operator needs to trace a transfer and nothing that grants
+     * access to it. `S3StorageProvider.getSignedDownloadUrl` holds to the same
+     * rule from its side, and the HTTP interceptor records method, url and
+     * duration only — never a response body.
+     */
+    createDownloadUrl(userId: string, nodeId: string, jobId: string, dto: NodeDownloadUrlDto): Promise<NodeDownloadUrlResponseDto>;
+    /**
+     * A short-lived signed PUT to a key THIS SERVER CHOSE, for a job this node
+     * holds.
+     *
+     * The key derivation is the security-relevant line and it takes no input
+     * from the request. The DEFAULT is `node-outputs/<jobId>/<uuid>`: the job id
+     * is a UUID the router already validated, the suffix is a fresh
+     * `randomUUID()`. Two consequences worth stating, because both are
+     * load-bearing:
+     *
+     *   * A NODE CANNOT OVERWRITE ANYTHING. The random suffix means every mint
+     *     is a new key, so even the same node asking twice for the same job
+     *     cannot clobber its own earlier output — let alone somebody else's
+     *     upload. A signed PUT is an unconditional overwrite of its key, so
+     *     "the key is always new" is the whole of that guarantee.
+     *   * THE OUTPUT IS ATTRIBUTABLE. The job id is in the path, so an object
+     *     found in the bucket months later can be traced to the row that
+     *     produced it without a lookup table.
+     *
+     * ⚠ A TYPE MAY OVERRIDE WHERE ITS OUTPUT LANDS, AND THE SERVER STILL CHOOSES
+     * (#348). A handler implementing `deriveOutputKey` answers instead of the
+     * template above, because some artifacts have a REQUIRED location: a
+     * database backup's key is recorded on its `database_backup_runs` row and
+     * read back by the retention sweep, the download endpoint and the restore
+     * path, so an archive under `node-outputs/…` is one none of them can find.
+     * Without this, no such type could ever be node-eligible.
+     *
+     * What does NOT change is who decides. `deriveOutputKey` runs in this
+     * process, in the handler that owns the artifact, with the `Job` row as its
+     * only input; the node's influence remains exactly zero. It is also the
+     * handler's job to be IDEMPOTENT — a node that asks twice (a retry, a lost
+     * response) must get the same key back rather than a second artifact; see
+     * `JobHandler.deriveOutputKey`. Note the trade that buys: a handler that
+     * derives a STABLE key gives up the "every mint is a new key" guarantee
+     * above for its own type, deliberately, because a stable location is the
+     * whole point — the overwrite it can then perform is of its own artifact,
+     * for its own job, and of nothing else.
+     *
+     * A `key` in the request body is REFUSED, not ignored — see the DTO file's
+     * header for why the node's author being told beats the node's author
+     * guessing. That refusal is unchanged by the above and happens BEFORE any
+     * derivation runs.
+     *
+     * NO `storage_objects` ROW IS CREATED HERE. Minting a write target is not
+     * the same as recording an object: the node may never use the URL, may
+     * crash mid-transfer, or may have its lease expire and its result refused,
+     * and a row written now would outlive all three as a `pending` object with
+     * nothing behind it. Recording the output is the HANDLER's business, in
+     * `persistNodeResult`, after the bytes are known to exist — which is why the
+     * chosen key is returned to the node rather than kept: the node reports it
+     * back in its result, and the handler writes it down.
+     */
+    createUploadTarget(userId: string, nodeId: string, jobId: string, dto: NodeUploadUrlDto): Promise<NodeUploadUrlResponseDto>;
+    /**
+     * The job's input object, or a clean 422 naming exactly what is missing.
+     *
+     * THIS IS THE `ENOENT … open ''` FIX, EXPRESSED OVER HTTP.
+     * `NodeJobInputs.resolve` refuses to produce an empty path and throws
+     * one of three named reasons instead (`NodeJobInputError`); this
+     * method's only job is to turn that into a status code a node can act on.
+     *
+     * WHY 422 AND NOT 400, 404 OR 500 — the status is the instruction, exactly
+     * as it is for the 409 in #268:
+     *
+     *   * `400` would say "your request was malformed". It was not: the node
+     *     sent the right thing about the right job. A node written to fix and
+     *     resend a 4xx would resend forever.
+     *   * `404` would say "no such job", which is false and sends the operator
+     *     hunting for a job that is right there in the admin list.
+     *   * `500` would say "this server is broken, try again". It is not, and a
+     *     retry cannot help: all three reasons are permanent (a subject that was
+     *     never set does not appear later; a deleted row does not come back).
+     *   * `422` says "your request was understood and cannot be processed",
+     *     which is the truth. The node's correct response is to report the job
+     *     FAILED through `POST …/failure`, letting the attempt budget and the
+     *     admin job list surface it the way every other permanent failure
+     *     surfaces — with `details.reason` naming which of the three it was.
+     */
+    private resolveInput;
+    /**
+     * Refuses any field the node is not permitted to choose — today, anything
+     * beyond `contentType` and `claimToken`.
+     *
+     * The `key` case is the one that matters and the message says so by name.
+     * Everything else is caught by the same net rather than by a growing list of
+     * individual checks: a field this endpoint does not understand is a field
+     * the node believes has an effect and which is having none, and that belief
+     * is the bug. Naming the offending keys turns "my output went somewhere
+     * else" into "the server told me on the first run".
+     *
+     * ⚠ THIS ALLOWLIST IS THE AUTHORITY, NOT THE ZOD SCHEMA, which is why
+     * `claimToken` had to be added in two places when #364 threaded it through
+     * this route. `nodeUploadUrlSchema` is a `z.looseObject` precisely so
+     * unknown keys survive the parse and can be refused BY NAME here; a field
+     * described there but missing from this set is therefore not permissive, it
+     * is a 400 on every request that sends it. `claimToken` belongs in the set
+     * for the same reason `contentType` does: it is a thing a node may say. The
+     * difference — that it asks for nothing and can only get the caller refused
+     * — is argued in `claim-token.field.ts`, not re-argued here.
+     */
+    private rejectCallerSuppliedFields;
+    /**
+     * How long a node-facing signed URL lives, clamped into
+     * `[NODE_SIGNED_URL_MIN_TTL_SECONDS, NODE_SIGNED_URL_MAX_TTL_SECONDS]`.
+     *
+     * READS THE APPLICATION SETTING AND THEN OVERRIDES IT DOWNWARD, which is
+     * deliberate rather than lazy. An operator who shortens
+     * `SIGNED_URL_EXPIRY` for the interactive API means it for the fleet too, so
+     * the setting is honoured when it is stricter; an operator who lengthens it
+     * to an hour for browser downloads did not mean "hand hour-long bucket
+     * capabilities to unattended machines", so the ceiling wins. There is no
+     * separate node-only environment variable, because a second knob is a second
+     * thing to get wrong and its only correct values are already inside this
+     * range.
+     */
+    private resolveTtlSeconds;
+}
+//# sourceMappingURL=node-data-plane.service.d.ts.map

package/dist/nodes/node-data-plane.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-data-plane.service.d.ts","sourceRoot":"","sources":["../../src/nodes/node-data-plane.service.ts"],"names":[],"mappings":"AA8FA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAI1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,eAAe,EACrB,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,kBAAkB,EAClB,0BAA0B,EAC1B,gBAAgB,EAChB,wBAAwB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,+BAA+B,MAAM,CAAC;AAEnD;;;;;;;;GAQG;AACH,eAAO,MAAM,+BAA+B,KAAK,CAAC;AAElD;;;;;;;GAOG;AAQH;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,iBAAiB,CAAC;AAuBrD;;;;GAIG;AACH,qBACa,oBAAoB;IAIJ,OAAO,CAAC,QAAQ,CAAC,MAAM;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAKtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAKxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAEzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAjBzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyC;gBAGpB,MAAM,EAAE,UAAU,EAC3C,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,YAAY,EAKnB,OAAO,EAAE,eAAe,EAKxB,QAAQ,EAAE,kBAAkB,EAE5B,MAAM,EAAE,aAAa;IAOxC;;;;;;;;;;;;;;;;OAgBG;IACG,iBAAiB,CACrB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,kBAAkB,GACtB,OAAO,CAAC,0BAA0B,CAAC;IAqCtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmDG;IACG,kBAAkB,CACtB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,wBAAwB,CAAC;IAqEpC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;YACW,YAAY;IA+B1B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,0BAA0B;IAuBlC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,iBAAiB;CAe1B"}