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

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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"}