@bevel-software/platform-core-backend 0.23.0 → 0.24.0

package/dist/modules/workspace/agent-upload.routes.js

@@ -0,0 +1,210 @@
+import express from 'express';
+import { validateFilename } from '@bevel-software/platform-shared';
+import { logger } from '../../shared/logging.js';
+import { UploadTokenError, overLimit } from './agent-upload.store.js';
+const log = logger('agent-uploads');
+/** The route's own prefix, under `/api`. One spelling, shared with the raw-body test below. */
+export const AGENT_UPLOAD_ROUTE = '/agent/uploads/:token';
+/**
+ * The same endpoint with the token in the `x-upload-token` HEADER instead of
+ * the path — the address `uploadUrl` is, without its last segment.
+ *
+ * Two spellings because a token in a URL is a credential in a place that keeps
+ * copies: an access log, a proxy log, a shell history, a `ps` listing of the
+ * `curl` that sent it. The path form is what `request_file_upload` answers,
+ * because one address an agent can paste into any client is the thing that
+ * makes this route usable at all; the header form is for a caller that would
+ * rather its credential not be written down on the way. Both reach the same
+ * handler and are judged identically — same token, same single use.
+ */
+export const AGENT_UPLOAD_HEADER_ROUTE = '/agent/uploads';
+/**
+ * Whether `path` is the agent upload route, and so must reach its handler with
+ * the body still a STREAM.
+ *
+ * The app installs a global `express.json()`. It only claims a JSON
+ * content-type, but `curl --data-binary @file.zip -H 'content-type:
+ * application/json'` is a request an agent can and will make — and once the
+ * parser has drained the stream there are no bytes left to store, so the
+ * upload would answer "0 bytes received" for a file that was sent in full.
+ * Exempting the path is the same move `/api/sync` makes for its HMAC body, and
+ * for the same reason: whoever needs the exact bytes has to see them first.
+ *
+ * Case-insensitive, because Express routing is: `/api/Agent/uploads/x` reaches
+ * this router, and a check that said no would let the parser eat that body.
+ */
+export function isAgentUploadRawBodyPath(path) {
+    // Trailing slashes trimmed first, so the header form's bare address matches
+    // in every spelling Express routes to it (`/api/agent/uploads` and
+    // `/api/agent/uploads/` are one route): missing one of them would hand that
+    // request to the JSON parser, and the bytes it drains are gone.
+    const lower = path.toLowerCase().replace(/\/+$/, '');
+    return lower === '/api/agent/uploads' || lower.startsWith('/api/agent/uploads/');
+}
+/**
+ * `POST /api/agent/uploads/:token` — the one endpoint on this server
+ * authenticated by a single-use token and nothing else.
+ *
+ * It exists because MCP tool arguments are JSON, so every byte an agent sends
+ * through a tool passes through the model first. A 37 KB page gets truncated
+ * mid-response; a file of regex backslashes fails to parse as a JSON string; a
+ * PNG cannot be sent at all. Here the agent asks for a token, sends the file
+ * with any HTTP client it has, and then names the token in
+ * `apply_file_upload`. The bytes never enter a prompt.
+ *
+ * What the route itself may do is deliberately almost nothing: it stores bytes
+ * against a token, in a directory beside the workspaces root, and answers what
+ * it received. It resolves no workspace, writes nothing into one, and commits
+ * nothing — every access, platform-file and branch rule is applied later, by
+ * the apply tool, against the branch the caller then names. A token that is
+ * unknown, spent, expired or someone else's gets one 404 that says which of
+ * those it was: none of them.
+ */
+export function createAgentUploadRoutes(deps) {
+    const router = express.Router();
+    const { uploads } = deps;
+    const handle = async (req, res) => {
+        const token = tokenOf(req);
+        try {
+            // THE TOKEN FIRST, before anything about the request is read, parsed,
+            // judged or quoted back. This route is authenticated by the token and
+            // nothing else, which cuts two ways. Without the check up here, anyone
+            // could make the process buffer the deployment's whole upload limit per
+            // request against tokens they invented, as many at a time as they liked;
+            // and a caller holding no token could learn which of its OTHER guesses
+            // were well formed — "that is not a usable file name" is an answer only
+            // somebody entitled to send a file should get. One refusal, nothing else.
+            // `receive` below asks again, under the same record, because that is
+            // where the token is actually spent.
+            uploads.assertOpen(token);
+            const filename = fileNameOf(req);
+            if (filename === null) {
+                res.status(400).json({
+                    error: 'Name the file you are sending: add `?filename=<name>` to the upload URL (or send it as the ' +
+                        '`x-upload-filename` header). A single file lands under that name, and a name ending in `.zip` is ' +
+                        'read as an archive.',
+                });
+                return;
+            }
+            const invalid = validateFilename(filename);
+            if (invalid !== null || filename.includes('/')) {
+                res.status(400).json({
+                    error: `"${filename}" is not a usable file name: ${invalid ?? 'a name cannot contain "/"'}. Send one plain file name.`,
+                });
+                return;
+            }
+            // Then the declared length, so a caller sending something far too large
+            // is told the limit before it spends the bandwidth. The real total is
+            // counted by the store as the bytes arrive — `content-length` is the
+            // sender's claim, not a fact.
+            const declared = Number.parseInt(req.headers['content-length'] ?? '', 10);
+            if (Number.isFinite(declared) && declared > uploads.maxBytes) {
+                res.status(413).json({ error: overLimit(declared, uploads.maxBytes) });
+                return;
+            }
+            // The request itself, as a stream: the store writes the bytes to disk as
+            // they arrive and never holds the body. It refuses an empty body, one
+            // past the limit and an unreadable archive with its own status.
+            res.json(await uploads.receive(token, filename, req));
+        }
+        catch (err) {
+            if (err instanceof UploadTokenError) {
+                res.status(err.status).json({ error: err.message });
+                return;
+            }
+            // The detail stays in the log. An unexpected failure here is a
+            // filesystem error, and its message quotes the absolute path of the
+            // store's root — a place the caller is told nothing else about.
+            log.error('upload failed:', { err });
+            res.status(500).json({ error: 'Upload failed' });
+        }
+    };
+    // Both spellings of the one endpoint: the token in the path, or in the
+    // `x-upload-token` header on the bare address.
+    router.post(AGENT_UPLOAD_ROUTE, handle);
+    router.post(AGENT_UPLOAD_HEADER_ROUTE, handle);
+    return router;
+}
+/**
+ * The token the sender presented: the `:token` path segment, or the
+ * `x-upload-token` header when the bytes went to the bare address.
+ *
+ * The path wins when both are present — it is the address the sender actually
+ * POSTed to, and a header left over from an earlier upload must not quietly
+ * redirect these bytes onto a different token.
+ *
+ * No token at all answers the empty string rather than its own refusal, so it
+ * goes through `assertOpen` like any other unusable token and gets the same
+ * single 404. A caller holding nothing is told nothing it did not already
+ * know — not even whether this endpoint wanted a header.
+ */
+function tokenOf(req) {
+    const inPath = req.params.token;
+    if (typeof inPath === 'string' && inPath.trim() !== '')
+        return inPath.trim();
+    const header = req.headers['x-upload-token'];
+    if (typeof header === 'string' && header.trim() !== '')
+        return header.trim();
+    return '';
+}
+/**
+ * The name the sender gave the file: the `filename` query parameter, the
+ * `x-upload-filename` header, or a `content-disposition`'s own `filename=`.
+ * Three spellings because three kinds of client are expected to use this —
+ * `curl` with a query string, a scripted `fetch` with a header, and a client
+ * that sends the disposition it would send to any upload endpoint.
+ */
+function fileNameOf(req) {
+    const query = req.query.filename;
+    if (typeof query === 'string' && query.trim() !== '')
+        return query.trim();
+    const header = req.headers['x-upload-filename'];
+    if (typeof header === 'string' && header.trim() !== '')
+        return header.trim();
+    const disposition = req.headers['content-disposition'];
+    if (typeof disposition === 'string')
+        return dispositionFilename(disposition);
+    return null;
+}
+/**
+ * The `filename` a `content-disposition` names, or null when it names none.
+ *
+ * A QUOTED value is read to its closing quote, not to the first semicolon: a
+ * semicolon separates the header's parameters only OUTSIDE the quotes, and
+ * `filename="report;final.md"` is one perfectly ordinary name that a
+ * semicolon-first reading landed as `report`. An unquoted value ends at the
+ * next parameter, as it must.
+ *
+ * Percent-decoded only in the extended `filename*=UTF-8''…` form, which is the
+ * only one where the encoding is part of the grammar. A plain `filename=` value
+ * is the name itself, so `50%20off.md` stays `50%20off.md` rather than losing
+ * its `%20` to a decode nobody asked for.
+ *
+ * The parameter name is matched at a boundary — the start of the header or a
+ * `;` — because `filename` is a suffix of other perfectly legal parameter
+ * names: without it, `inline; xfilename=wrong.md` read `wrong.md` as the name
+ * the sender gave, from a parameter that says nothing of the kind.
+ */
+export function dispositionFilename(disposition) {
+    const match = /(?:^|;)\s*filename(\*?)\s*=\s*(?:"([^"]*)"|([^;]*))/i.exec(disposition);
+    if (!match)
+        return null;
+    const extended = match[1] === '*';
+    const raw = (match[2] ?? match[3] ?? '').trim();
+    if (!extended)
+        return raw === '' ? null : raw;
+    // `UTF-8''name`, or any other charset and language the sender declares.
+    const encoded = raw.replace(/^[^']*'[^']*'/, '');
+    try {
+        const decoded = decodeURIComponent(encoded).trim();
+        if (decoded !== '')
+            return decoded;
+    }
+    catch {
+        const kept = encoded.trim();
+        if (kept !== '')
+            return kept;
+    }
+    return null;
+}
+//# sourceMappingURL=agent-upload.routes.js.map

package/dist/modules/workspace/agent-upload.routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-upload.routes.js","sourceRoot":"","sources":["../../../src/modules/workspace/agent-upload.routes.ts"],"names":[],"mappings":"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"}

package/dist/modules/workspace/agent-upload.store.d.ts

@@ -0,0 +1,284 @@
+/** How long an issued token, and the bytes sent against it, stay usable. */
+export declare const UPLOAD_TOKEN_TTL_MS: number;
+/**
+ * THE one refusal for every way a token can fail to be usable: it was never
+ * issued, it has already been applied, it has expired, or it belongs to
+ * somebody else. One sentence for all four, deliberately — an answer that
+ * distinguished "no such token" from "not yours" would let anyone holding a
+ * guess learn which guesses exist, and the token is the whole credential this
+ * route has.
+ */
+export declare const UPLOAD_TOKEN_REFUSAL: string;
+/**
+ * How many tokens one user may hold open at once.
+ *
+ * A token is permission to put the deployment's whole upload limit on its
+ * disk for a TTL, and to hold a connection open while it arrives. Without a
+ * bound, one caller asks for a hundred and sends against all of them
+ * together. Ten is far more than the route's own use needs — one token carries
+ * a zip of any number of files — and a token is given back the moment it is
+ * applied or expires.
+ */
+export declare const MAX_OPEN_UPLOADS_PER_USER = 10;
+/** The refusal an over-limit upload gets, naming the limit that applied. */
+export declare function overLimit(bytes: number, maxBytes: number): string;
+/** A refusal with the HTTP status the upload route and the apply tool both answer. */
+export declare class UploadTokenError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/** What `request_file_upload` answers: where to send the bytes, and the terms. */
+export interface IssuedUpload {
+    /** The absolute URL the bytes are POSTed to. Carries the token in its path. */
+    uploadUrl: string;
+    /**
+     * The token itself — what `apply_file_upload` takes, and the credential the
+     * upload route is authenticated by.
+     *
+     * Named separately from `uploadUrl` for two reasons: the apply needs it on
+     * its own, and the route takes it either way round. The bytes can go to
+     * `uploadUrl`, which carries the token in its last path segment, or to that
+     * address WITHOUT that segment with the token in the `x-upload-token`
+     * header — the spelling for a caller that would rather its credential not
+     * land in an access log or a shell history on the way.
+     */
+    token: string;
+    /** ISO-8601 instant after which the token and any bytes sent with it are gone. */
+    expiresAt: string;
+    /** Seconds from now until `expiresAt`, so a caller need not parse the date. */
+    expiresInSeconds: number;
+    /** The largest upload this deployment accepts, in bytes. */
+    maxBytes: number;
+}
+/** What the upload route answers, and what `apply_file_upload` reads back. */
+export interface ReceivedUpload {
+    /** The name the sender gave the file. For a single file, the name it lands under. */
+    filename: string;
+    bytes: number;
+    /** `zip` when the name ends in `.zip` and the bytes parse as an archive. */
+    kind: 'file' | 'zip';
+    /** Present for a zip: how many members the archive holds. */
+    entries?: number;
+}
+/** A received upload, with the bytes on disk, as `apply_file_upload` claims it. */
+export interface ClaimedUpload extends ReceivedUpload {
+    /** Absolute path of the stored bytes — OUTSIDE every workspace. */
+    absolutePath: string;
+}
+export interface AgentUploadStoreOptions {
+    /** Directory the bytes are written to. A sibling of `workspacesRoot`, never inside one. */
+    root: string;
+    /** Absolute base URL of this deployment's API, e.g. `https://core.example.com`. */
+    publicBaseUrl: string;
+    /** Token prefix, so a leaked credential can be recognised by shape. */
+    tokenPrefix?: string;
+    ttlMs?: number;
+    maxBytes?: number;
+    /** How many tokens one user may hold open at once. Defaults to {@link MAX_OPEN_UPLOADS_PER_USER}. */
+    maxOpenPerUser?: number;
+    /**
+     * How the staging root is listed. Test seam — defaults to `fs.readdir`.
+     *
+     * The ONE thing about the sweep a suite needs to control. Whether a token
+     * issued and uploaded while the sweep is running survives depends on the
+     * order of two steps inside {@link AgentUploadStore.sweepNow} — the listing
+     * and the live-id set — and the gap between them is a filesystem round-trip
+     * no test can otherwise sit inside. Given a listing it can hold open, a test
+     * can put a whole upload in that gap and assert the bytes are still there.
+     */
+    listRoot?: (root: string) => Promise<string[]>;
+}
+/**
+ * The upload tokens an agent lands files with, and the bytes sent against
+ * them.
+ *
+ * An agent that wants to put 27 files on a branch has no way to do it through
+ * a tool argument: the content would have to pass through the model, which
+ * truncates, mangles escape characters and cannot carry a PNG at all. So the
+ * bytes take a route of their own — this store issues a one-time token, the
+ * upload route attaches bytes to it, and `apply_file_upload` lands them.
+ *
+ * Three properties the whole design rests on, because the upload route is the
+ * one endpoint on this server that authenticates by a token alone:
+ *
+ *  - **Unguessable.** 32 random bytes, base64url. Nothing about the token is
+ *    derived from the user, the time or a counter.
+ *  - **Never stored in the clear.** Records are keyed by the token's SHA-256,
+ *    so the store's own memory (and anything that dumps it) holds no usable
+ *    credential.
+ *  - **Bound and single-use.** A record carries the id of the user it was
+ *    issued to and is consumed by the apply that lands it; a second apply, an
+ *    apply by anyone else, and an apply after the expiry all meet
+ *    {@link UPLOAD_TOKEN_REFUSAL}.
+ *
+ * And the bytes land in `root` — a directory beside the workspaces root, not
+ * inside one. No file tool can reach it: every workspace path is resolved
+ * against a branch's checkout, so there is no spelling of a tool argument that
+ * names a file in here. An upload nobody applies is deleted when its token
+ * expires (see {@link startSweeping}), so an abandoned drop costs disk for at
+ * most one TTL.
+ */
+export declare class AgentUploadStore {
+    private readonly records;
+    private readonly root;
+    private readonly publicBaseUrl;
+    private readonly tokenPrefix;
+    private readonly ttlMs;
+    private readonly listRoot;
+    readonly maxBytes: number;
+    private readonly maxOpenPerUser;
+    private sweepTimer;
+    /** The sweep in flight, so a shutdown can wait for it — see {@link drainSweep}. */
+    private sweeping;
+    /** Set by {@link stopSweeping}: no further sweep deletes anything. */
+    private stopped;
+    constructor(options: AgentUploadStoreOptions);
+    /** The URL a token's bytes are sent to. The one spelling of this route's address. */
+    uploadUrlFor(token: string): string;
+    /**
+     * Mint a token for `user` and answer the terms it is good for. Nothing is
+     * written to disk yet — a token nobody uploads against costs one map entry
+     * until the sweep drops it.
+     */
+    issue(user: {
+        id: string;
+    }): IssuedUpload;
+    /**
+     * Store the bytes of `body` against `token` and say what was received. One
+     * file per token: a second upload against the same token is refused, so a
+     * token cannot be used to keep replacing bytes an apply is about to land.
+     *
+     * WRITTEN AS THEY ARRIVE, never gathered first. The body is up to the
+     * deployment's whole upload limit, and this is the one route a caller can
+     * send to without a session: held in memory, a handful of uploads at once
+     * cost the process several times that limit each (the chunks, the buffer
+     * they were joined into, the archive read over it). Streamed, an upload in
+     * flight costs one chunk.
+     *
+     * A name ending in `.zip` is read as an archive HERE, once the bytes are on
+     * disk, so the answer can carry the entry count and so a corrupt archive is
+     * refused while the caller is still holding the file — rather than at apply
+     * time, when its token would already be spent.
+     */
+    receive(token: string, filename: string, body: AsyncIterable<Buffer | string>): Promise<ReceivedUpload>;
+    /**
+     * Refuse `token` if it cannot accept bytes — unknown, expired, somebody
+     * else's doing, or already holding a file — and answer its record if it can.
+     *
+     * Exists as its own step so the upload route can ask BEFORE it reads the
+     * body. The route is the one endpoint here authenticated by a token alone,
+     * and buffering up to the deployment's whole upload limit for an invented
+     * token would let a handful of concurrent requests spend the process's
+     * memory on bytes that were never going to be stored.
+     */
+    assertOpen(token: string): void;
+    /** {@link assertOpen}, with the record it found — the store's own view of it. */
+    private openRecord;
+    /**
+     * Hold `token` for an apply by `userId`, and answer where its bytes are.
+     *
+     * A CLAIM rather than a consume, because an apply can be refused whole —
+     * the destination is on a protected branch the caller may not write, the
+     * archive turned out unreadable — and a token spent on a refusal would make
+     * the agent send the same 40 MB again to try a different destination. The
+     * claim is what keeps it single-use meanwhile: a second apply arriving while
+     * the first runs finds the token in use and is refused. The caller
+     * {@link consume}s it once an answer exists, or {@link release}s it on a
+     * refusal that landed nothing.
+     */
+    claim(token: string, userId: string): ClaimedUpload;
+    /** Give a claimed token back, unused — the apply refused without landing anything. */
+    release(token: string): void;
+    /** Spend the token and delete its bytes. Idempotent. */
+    consume(token: string): Promise<void>;
+    /**
+     * Delete every record whose token has expired, with the bytes it was
+     * holding — then delete any file in the root that no LIVE record claims and
+     * that has outlived every token that could name it.
+     *
+     * The second half is what makes the first one true. A process killed between
+     * the write and the apply leaves a file no map will ever mention again, and
+     * sweeping by what the records DON'T name is the honest reading of the
+     * promise: an upload nobody applied does not stay. By AGE rather than at
+     * once, because a file this map does not name may be another process's (see
+     * the loop below).
+     *
+     * ONE record is kept past its expiry: one an apply has CLAIMED. Those bytes
+     * are being read right now, and a sweep that deleted them would make the
+     * commit land short of what the answer promised. The pin lasts
+     * {@link CLAIM_GRACE_MS}, after which a claim nobody consumed or released
+     * belongs to a dead process and is reclaimed.
+     */
+    sweepNow(): Promise<void>;
+    /**
+     * Whether the stored file `name` is older than any token that could still be
+     * naming it, in this process or another. A file that cannot be examined is
+     * left for the next sweep rather than judged.
+     */
+    private outlivedEveryToken;
+    /**
+     * Whether an expired record is held open by work that is still running:
+     * an UPLOAD still writing its bytes, or an APPLY still reading them.
+     *
+     * Both windows can outlast a TTL — a large upload over a slow link, an apply
+     * that clones a branch before it reads — and in both the record's own file is
+     * being written or read right now. A sweep that deleted either would leave a
+     * file no map mentions (the upload writes after the delete) or an apply
+     * reading a path that has gone. The apply's pin has a grace, because a claim
+     * can be abandoned by a process that dies; the upload's needs none, because
+     * `receive` always ends — it clears `attaching` on failure and sets
+     * `received` on success, and one whose TTL passed meanwhile deletes the
+     * record itself rather than leaving it pinned.
+     */
+    private pinned;
+    /**
+     * Sweep now, and keep sweeping. Started by the first {@link issue} rather
+     * than at boot, so a deployment nobody uploads to runs no timer; idempotent,
+     * and the timer is `unref`'d because nothing here is worth keeping a process
+     * alive for — the records are in memory and go with it.
+     *
+     * The first sweep runs IMMEDIATELY, not one interval later, because the
+     * records are in memory: a process that restarted holds no record of what
+     * the previous one stored, and what that one left behind long enough ago
+     * has no reason to wait a further interval.
+     */
+    startSweeping(intervalMs?: number): void;
+    /**
+     * Stop sweeping, for good: the timer is cleared AND a sweep already running
+     * abandons the rest of its work.
+     *
+     * Both halves matter when a graph is stopped — a tenant evicted, the process
+     * shutting down. The root is this tenant's, and a reactivation builds a new
+     * store over the same directory with an empty record map: a sweep left
+     * running from the old store would find the new store's files named by no
+     * record of ITS own and delete them, under an apply that is about to read
+     * them. {@link drainSweep} is how a caller waits for the abandonment to
+     * actually have happened.
+     */
+    stopSweeping(): void;
+    /** Wait for the sweep in flight, if any. Pairs with {@link stopSweeping} on shutdown. */
+    drainSweep(): Promise<void>;
+    /** One sweep, with its failure logged and its promise kept for {@link drainSweep}. */
+    private sweep;
+    /** The live record for `token`, or the one refusal. Expiry is judged here. */
+    private find;
+    /** Best-effort delete of one stored upload. Never throws. */
+    private remove;
+}
+/**
+ * Refuse a boot whose upload root is not OUTSIDE every workspace.
+ *
+ * The whole safety of this route rests on where the bytes land: they are a
+ * buffer somebody sent, judged by nothing until `apply_file_upload` judges each
+ * path against a branch. A root configured inside `workspacesRoot` would put
+ * that unjudged buffer where the file tools read — `read_file`, `grep`, the
+ * download route — bypassing the access and platform-file rules the apply
+ * exists to apply. The invariant is documented on `AGENT_UPLOADS_ROOT`; this is
+ * it checked, at boot, naming the variable, rather than trusted.
+ *
+ * Both directions and both spellings: equal paths, either containing the
+ * other, and the real paths, so a root that is a LINK into the workspaces tree
+ * is refused too.
+ */
+export declare function assertUploadsRootOutsideWorkspaces(uploadsRoot: string, workspacesRoot: string): Promise<void>;
+//# sourceMappingURL=agent-upload.store.d.ts.map

package/dist/modules/workspace/agent-upload.store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-upload.store.d.ts","sourceRoot":"","sources":["../../../src/modules/workspace/agent-upload.store.ts"],"names":[],"mappings":"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"}