@ultimat3/storage 29.3.2 → 30.0.0

package/src/errors-promote.ts

@@ -2,6 +2,7 @@
 // still in quarantine, a key that is not a pending upload, and one an earlier call already moved.
 // Their codes are registered with the rest of the package's in `errors.ts`.
 
+import { renderFixLiteral } from '@ultimat3/core';
 import { StorageError } from './errors';
 
 /**
@@ -42,3 +43,16 @@ export const alreadyPromoted = (key: string, attachedKey: string, orgId: string)
     fix: `await disk.stat('${attachedKey}') answers the moved object: answer the row that references that key if one exists, write it with that key if none does, and never delete the key on a failure of your own`,
     meta: { key, attachedKey, orgId },
   });
+
+/**
+ * The object is no longer the revision that was judged. A presigned PUT stays valid until it
+ * expires, so an uploader can overwrite between the sniff and the copy, and what would land on the
+ * row's key is bytes nothing looked at.
+ */
+export const objectChanged = (key: string, expected: string, actual: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_OBJECT_CHANGED',
+    cause: `"${key}" changed while it was being promoted: it was judged at ${expected} and is now ${actual}`,
+    fix: `promoteAttachment({ disk, key: ${renderFixLiteral(key, "'<pending key>'")}, orgId, target, policy }) once the upload has finished: it reads the object again`,
+    meta: { key, expected, actual },
+  });

package/src/errors-range.ts

@@ -0,0 +1,47 @@
+// The two refusals of a ranged `get(key, { range })`: a first byte past the end (HTTP's 416) and a
+// window over the disk's get ceiling. Their codes are registered with the rest of the package's in
+// `errors.ts`; each `fix:` is the call to make next, with the numbers this object allows.
+
+import { renderFixLiteral } from '@ultimat3/core';
+import { StorageError } from './errors';
+
+const keyArg = (key: string): string => renderFixLiteral(key, "'<key>'");
+
+/**
+ * A first byte at or past the end. The last byte is CLAMPED (`range.ts`), so only the first can
+ * miss; an empty object has no first byte at all, so its fix is the plain read.
+ */
+export const rangeUnsatisfiable = (
+  disk: string,
+  key: string,
+  range: readonly [number, number],
+  size: number,
+): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_RANGE_UNSATISFIABLE',
+    cause: `get() asked "${key}" for bytes ${range[0]}-${range[1]}, and the object on the ${disk} disk is ${size}B — its first byte is past the end`,
+    fix:
+      size === 0
+        ? `await disk.get(${keyArg(key)})   # the object is empty: no range has a first byte`
+        : `await disk.get(${keyArg(key)}, { range: [0, ${size - 1}] })   # the whole ${size}B object; any first byte below ${size}`,
+    meta: { disk, key, first: range[0], last: range[1], size },
+  });
+
+/**
+ * A window over `maxGetBytes` — the ceiling bounds the RANGE, so the repair is a smaller window
+ * from the same first byte, or a higher ceiling on the disk.
+ */
+export const rangeTooLarge = (
+  disk: string,
+  key: string,
+  range: readonly [number, number],
+  maxBytes: number,
+): StorageError => {
+  const bytes = range[1] - range[0] + 1;
+  return new StorageError({
+    code: 'X_STORAGE_TOO_LARGE',
+    cause: `the range asked of "${key}" is ${bytes}B against the ${disk} disk's get ceiling of ${maxBytes}B, and get() buffers the range`,
+    fix: `await disk.get(${keyArg(key)}, { range: [${range[0]}, ${range[0] + maxBytes - 1}] })   # one window within the ceiling; or raise maxGetBytes to ${bytes} on the disk`,
+    meta: { disk, key, bytes, maxBytes, first: range[0], last: range[1] },
+  });
+};

package/src/errors-sniff.ts

@@ -0,0 +1,35 @@
+// The two refusals only a bounded sniff can reach: markup that could sit past what was read. Their
+// code is `X_STORAGE_TYPE_REJECTED`, registered with the rest of the package's in `errors.ts`; they
+// are their own constructors because the sniff saw nothing to name, so `contentTypeMismatch`'s
+// "re-upload with the sniffed type" would be advice about a type nobody found.
+
+import { renderFixLiteral } from '@ultimat3/core';
+import { StorageError } from './errors';
+
+/**
+ * A body opening with more whitespace than `limit` bytes. Past a window nothing is seen, so padding
+ * is how markup would hide from a head read, and no real file opens this way.
+ */
+export const leadingWhitespacePastLimit = (
+  key: string,
+  declared: string,
+  limit: number,
+): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_TYPE_REJECTED',
+    cause: `"${key}" declares ${declared} and opens with more than ${limit} bytes of whitespace, so its type cannot be read`,
+    fix: `validateUpload({ key: ${renderFixLiteral(key, "'a/file.txt'")}, declaredContentType: ${renderFixLiteral(declared, "'text/plain'")}, bytes: new TextEncoder().encode(text.trimStart()) }, policy) — where text is the file with its leading whitespace removed`,
+    meta: { key, declared, limit },
+  });
+
+/**
+ * An XML document too long for a head window to screen: XML runs a script anywhere in the tree, so
+ * no prefix can clear it. The server-side path reads all of it, which is the way through.
+ */
+export const xmlBodyPastWindow = (key: string, declared: string, window: number): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_TYPE_REJECTED',
+    cause: `"${key}" declares ${declared} and is over the ${window} bytes promotion reads, and an XML document can run a script anywhere in it`,
+    fix: `validateUpload({ key: ${renderFixLiteral(key, "'a/data.xml'")}, declaredContentType: ${renderFixLiteral(declared, "'application/xml'")}, bytes }, policy) — upload it through the server, which reads the whole body, then disk.put(key, bytes, { contentType })`,
+    meta: { key, declared, window },
+  });

package/src/errors-stream.ts

@@ -0,0 +1,62 @@
+// The refusals of the streaming calls and of a size a grant was not told. Registered with the rest
+// of the package's codes in `errors.ts`; each `fix:` names the call that goes next, because these
+// calls have their own option where `put()`'s refusal names the disk's ceiling.
+
+import { describeValue, renderFixLiteral, renderThrowable } from '@ultimat3/core';
+import { StorageError } from './errors';
+
+const keyArg = (key: string): string => renderFixLiteral(key, "'<key>'");
+
+/** A `putStream` body past the call's own `maxBytes`. Counted, so `bytes` is how far it had got. */
+export const streamTooLarge = (
+  disk: string,
+  key: string,
+  bytes: number,
+  maxBytes: number,
+): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_TOO_LARGE',
+    cause: `the stream for "${key}" passed its maxBytes of ${maxBytes}B at ${bytes}B on the ${disk} disk, so the write was abandoned and nothing was stored`,
+    fix: `await disk.putStream(${keyArg(key)}, stream, { maxBytes: ${bytes * 2} })   # a higher maxBytes on the call, if a body this large is meant`,
+    meta: { disk, key, bytes, maxBytes },
+  });
+
+/** `rangeUnsatisfiable` for a call that holds no size: the next step is learning it. */
+export const streamRangeUnsatisfiable = (
+  disk: string,
+  key: string,
+  range: readonly [number, number],
+  size: number,
+): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_RANGE_UNSATISFIABLE',
+    cause: `streamRange() asked "${key}" for bytes ${range[0]}-${range[1]}, and the object on the ${disk} disk is ${size}B, so its first byte is past the end`,
+    fix: `const { size } = await disk.stat(${keyArg(key)})   # the object's size now; any first byte below it is a window`,
+    meta: { disk, key, first: range[0], last: range[1], size },
+  });
+
+/**
+ * A grant with nothing to bind. A presign has one way to hold a size, the exact `Content-Length`
+ * inside the signature, so "any size up to the policy" is a URL that bounds nothing.
+ */
+export const uploadSizeUndeclared = (key: string, size: unknown): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_UPLOAD_SIZE_UNDECLARED',
+    cause: `the upload for "${key}" declared its size as ${describeValue(size)}, not a whole byte count of at least 1, so the URL could not bind one`,
+    fix: 'grantUpload({ disk, orgId, request: { filename, contentType, size: file.size } })',
+    meta: { key },
+  });
+
+/**
+ * A write sent whose answer was lost, and nothing could settle what it did. Never `putFailed`: that
+ * says the key is as it was, and the object may be the one sent. `X_DB_COMMIT_UNKNOWN`'s idea.
+ */
+export const writeOutcomeUnknown = (disk: string, key: string, lost: unknown): StorageError => {
+  const reason = renderThrowable(lost);
+  return new StorageError({
+    code: 'X_STORAGE_WRITE_OUTCOME_UNKNOWN',
+    cause: `the write of "${key}" on the ${disk} disk was sent and its answer lost (${reason}), and neither a stat nor an abort could say whether it landed`,
+    fix: `await disk.stat(${keyArg(key)})   # the size and etag now at the key; the same as what was sent means it landed`,
+    meta: { disk, key, reason },
+  });
+};

package/src/errors.ts

@@ -32,6 +32,13 @@ export const STORAGE_OWNED_ERROR_CODES = [
   'X_STORAGE_OBJECT_LOCKED',
   'X_STORAGE_KEY_UNSHARED',
   'X_STORAGE_ALREADY_PROMOTED',
+  'X_STORAGE_RANGE_UNSATISFIABLE',
+  'X_STORAGE_OBJECT_CHANGED',
+  'X_STORAGE_UPLOAD_SIZE_UNDECLARED',
+  'X_STORAGE_WRITE_OUTCOME_UNKNOWN',
+  'X_STORAGE_MULTIPART_UNSUPPORTED',
+  'X_STORAGE_UPLOAD_UNKNOWN',
+  'X_STORAGE_PARTS_INVALID',
 ] as const;
 
 /**
@@ -74,6 +81,14 @@ export const STORAGE_ERROR_TITLES: Readonly<Record<StorageOwnedErrorCode, string
   X_STORAGE_OBJECT_LOCKED: 'the object is under retention or a legal hold',
   X_STORAGE_KEY_UNSHARED: 'object key is outside every tenant and every shared prefix',
   X_STORAGE_ALREADY_PROMOTED: 'the upload was already promoted onto its row',
+  X_STORAGE_RANGE_UNSATISFIABLE: 'the requested byte range starts past the end of the object',
+  X_STORAGE_OBJECT_CHANGED: 'the object changed while it was being promoted',
+  X_STORAGE_UPLOAD_SIZE_UNDECLARED: 'an upload grant was asked for without the size of the file',
+  X_STORAGE_WRITE_OUTCOME_UNKNOWN:
+    'a write was sent and its answer lost, and the disk could not say whether it landed',
+  X_STORAGE_MULTIPART_UNSUPPORTED: 'this disk cannot take an upload in parts',
+  X_STORAGE_UPLOAD_UNKNOWN: 'no open multipart upload has that id',
+  X_STORAGE_PARTS_INVALID: 'the parts named do not match the parts stored',
 };
 
 // One unconditional call, so a second package claiming one of storage's codes throws
@@ -193,7 +208,7 @@ export const getTooLarge = (
     code: 'X_STORAGE_TOO_LARGE',
     cause: `"${key}" is ${bytes}B against the ${disk} disk's get ceiling of ${maxBytes}B, and get() buffers the whole object`,
     fix:
-      `read it with disk.stream(key) instead of get(), or raise the ceiling: ` +
+      `await disk.stream(${renderFixLiteral(key, "'<key>'")})   # unbuffered; or a window with get(key, { range }), or raise the ceiling: ` +
       (disk === 's3'
         ? `s3Driver({ bucket, maxGetBytes: ${bytes} })`
         : disk === 'memory'

package/src/expire.ts

@@ -0,0 +1,169 @@
+// Single responsibility: objects and upload sessions past a window the APP names, swept on any
+// disk. Bucket lifecycle rules stay the operator's (axiom 7); a local disk has none, and abandoned
+// parts bill silently forever without one, so a sweep that works the same on every disk is
+// mechanism. No timer here: `objectPurgeTarget` hands the sweep to the app's one `purge()` job.
+
+import {
+  assert,
+  type Clock,
+  finiteCount,
+  logger,
+  renderThrowable,
+  systemClock,
+} from '@ultimat3/core';
+import type { SweepFailure, SweepResult } from './attachment';
+import type { StorageDriver, StorageListEntry } from './driver';
+import type { MultipartSession } from './multipart';
+
+export interface ExpireObjectsInput {
+  readonly disk: StorageDriver;
+  /** Required and non-empty: a sweep of the whole disk is never a default. */
+  readonly prefix: string;
+  /** Age past which an object goes. Required: the window is the app's. */
+  readonly olderThanMs: number;
+  /** `true` spares an object the app still accounts for. */
+  readonly keep?: ((object: StorageListEntry) => boolean | Promise<boolean>) | undefined;
+  readonly clock?: Clock | undefined;
+}
+
+/** `SweepResult`'s two lists, plus what was spared: undated, inside the window, or kept. */
+export interface ExpireResult extends SweepResult {
+  readonly spared: readonly string[];
+}
+
+const screenPrefix = (caller: string, prefix: string): string => {
+  assert(
+    typeof prefix === 'string' && prefix !== '',
+    `${caller} was handed an empty prefix, which is the whole disk`,
+    `${caller}({ disk, prefix: 'exports/', olderThanMs })   # name the prefix the window applies to`,
+  );
+  return prefix;
+};
+
+const cutoffOf = (caller: string, olderThanMs: number, clock: Clock | undefined): number =>
+  // Screened first: `now - NaN` is NaN, and every age comparison against it reads "old enough".
+  (clock ?? systemClock).now().getTime() - finiteCount(caller, 'olderThanMs', olderThanMs, 0);
+
+/**
+ * Delete every object under `prefix` older than the window. An object with no reported age is
+ * spared, as `sweepOrphans` spares it; a refusal — a locked object included — is recorded in
+ * `failed` and the sweep goes on, never forced and never reported as deleted.
+ */
+export async function expireObjects(input: ExpireObjectsInput): Promise<ExpireResult> {
+  const prefix = screenPrefix('expireObjects', input.prefix);
+  const cutoff = cutoffOf('expireObjects', input.olderThanMs, input.clock);
+  const deleted: string[] = [];
+  const failed: SweepFailure[] = [];
+  const spared: string[] = [];
+  let cursor: string | null = null;
+  do {
+    const page = await input.disk.list({ prefix, cursor });
+    for (const object of page.rows) {
+      const modified = object.lastModified?.getTime();
+      if (modified === undefined || modified > cutoff || (await input.keep?.(object)) === true) {
+        spared.push(object.key);
+        continue;
+      }
+      try {
+        await input.disk.delete(object.key);
+        deleted.push(object.key);
+      } catch (error) {
+        failed.push({ key: object.key, reason: renderThrowable(error) });
+      }
+    }
+    cursor = page.nextCursor;
+  } while (cursor !== null);
+  return { deleted, failed, spared };
+}
+
+export interface AbortStaleUploadsInput {
+  readonly disk: StorageDriver;
+  /** Age past which an open session is abandoned. */
+  readonly olderThanMs: number;
+  /** Absent is every session on the disk: an open session under no prefix bills all the same. */
+  readonly prefix?: string | undefined;
+  /** Only sessions whose key this answers `true` for: a per-tenant kind no prefix spells. */
+  readonly match?: ((key: string) => boolean) | undefined;
+  readonly clock?: Clock | undefined;
+}
+
+export interface AbortResult {
+  readonly aborted: readonly MultipartSession[];
+  readonly failed: readonly SweepFailure[];
+  /** Undated or inside the window: possibly a phone still on the train. */
+  readonly spared: readonly MultipartSession[];
+}
+
+/** Abort every upload session opened before the window and never completed. */
+export async function abortStaleUploads(input: AbortStaleUploadsInput): Promise<AbortResult> {
+  const cutoff = cutoffOf('abortStaleUploads', input.olderThanMs, input.clock);
+  const multipart = input.disk.multipart;
+  if (multipart === undefined) return { aborted: [], failed: [], spared: [] };
+  const aborted: MultipartSession[] = [];
+  const failed: SweepFailure[] = [];
+  const spared: MultipartSession[] = [];
+  for (const session of await multipart.listUploads(input.prefix)) {
+    if (input.match !== undefined && !input.match(session.key)) continue;
+    const initiated = session.initiated?.getTime();
+    if (initiated === undefined || initiated > cutoff) {
+      spared.push(session);
+      continue;
+    }
+    try {
+      await multipart.abort(session.key, session.uploadId);
+      aborted.push(session);
+    } catch (error) {
+      failed.push({ key: session.key, reason: renderThrowable(error) });
+    }
+  }
+  return { aborted, failed, spared };
+}
+
+export interface ObjectPurgeTargetInput {
+  /** The step's name in the purge job, unique within it. */
+  readonly name: string;
+  readonly disk: StorageDriver;
+  readonly prefix: string;
+  /**
+   * Only keys this answers `true` for, under `prefix`: `org/<id>/imports/` is one kind of file
+   * under every tenant, and no prefix names it without also naming every avatar beside it.
+   */
+  readonly match?: ((key: string) => boolean) | undefined;
+  readonly olderThanMs: number;
+}
+
+/**
+ * Structurally `@ultimat3/jobs`' `PurgeTarget`, so this package imports nothing upward and the
+ * app's one `purge({ targets })` carries it. One pass expires the objects and aborts the sessions
+ * under the prefix, on the JOB's clock. A refusal is logged and counted out, never retried into a
+ * dead letter: a locked object stays locked on every attempt.
+ */
+export function objectPurgeTarget(input: ObjectPurgeTargetInput): {
+  readonly name: string;
+  purgeExpired(nowMs: number): Promise<number>;
+} {
+  const prefix = screenPrefix('objectPurgeTarget', input.prefix);
+  finiteCount('objectPurgeTarget', 'olderThanMs', input.olderThanMs, 0);
+  return {
+    name: input.name,
+    async purgeExpired(nowMs: number): Promise<number> {
+      const clock: Clock = { now: () => new Date(nowMs), monotonic: () => nowMs };
+      const window = { disk: input.disk, prefix, olderThanMs: input.olderThanMs, clock };
+      const match = input.match;
+      // Outside `match` is spared, never deleted: `keep` is `expireObjects`' own way of saying so.
+      const objects = await expireObjects(
+        match === undefined ? window : { ...window, keep: (object) => !match(object.key) },
+      );
+      const uploads = await abortStaleUploads({ ...window, match });
+      const failed = [...objects.failed, ...uploads.failed];
+      if (failed.length > 0) {
+        logger.warn('storage.expire.refused', {
+          target: input.name,
+          refused: failed.length,
+          first: failed[0]?.reason,
+        });
+      }
+      return objects.deleted.length + uploads.aborted.length;
+    },
+  };
+}

package/src/grant-multipart.ts

@@ -0,0 +1,196 @@
+// Single responsibility: the server half of an upload in parts — open a session under
+// `grantUpload`'s policy gate, sign a part, list what landed, complete, abort. Each is a function the
+// app wraps in its own `action()`, and each is held to the ACTOR's tenant, so an upload id read off a
+// request reaches nothing outside the caller's org.
+
+import { assert } from '@ultimat3/core';
+import type { StorageDriver, StorageObject } from './driver';
+import { orgMismatch, tooLarge } from './errors';
+import { multipartUnsupported, partsInvalid } from './errors-multipart';
+import { decideGrant, type GrantUploadInput } from './grant';
+import {
+  type CompletedPart,
+  MAX_PART_BYTES,
+  MAX_PARTS,
+  MIN_PART_BYTES,
+  type MultipartCapability,
+  matchParts,
+  partBytesFor,
+  type UploadedPart,
+} from './multipart';
+import { isWithinOrg } from './path';
+import { DEFAULT_SIGNED_URL_TTL_MS } from './signed-url';
+import type { UploadPolicy } from './upload';
+
+export interface GrantMultipartInput extends GrantUploadInput {
+  /** A part size the app prefers; raised to what 10,000 parts need, never below S3's 5 MiB. */
+  readonly partBytes?: number | undefined;
+}
+
+export interface MultipartGrant {
+  readonly key: string;
+  readonly uploadId: string;
+  /** Every part but the last is exactly this long. */
+  readonly partBytes: number;
+  /** How many parts the declared size takes at `partBytes`. */
+  readonly maxParts: number;
+  /** Normalised: the type the object is created under. */
+  readonly contentType: string;
+  /** The declared size, already held to the policy. The client's claim: `policy` is the bound. */
+  readonly size: number;
+  /** Epoch ms: the part URLs' window from now. Each `signPart` opens a fresh one. */
+  readonly expiresAt: number;
+}
+
+/** What names one open session. `orgId` is the actor's, resolved server-side. */
+export interface UploadSessionInput {
+  readonly disk: StorageDriver;
+  readonly orgId: string;
+  readonly key: string;
+  readonly uploadId: string;
+}
+
+export interface SignPartInput extends UploadSessionInput {
+  readonly partNumber: number;
+  /** This part's exact size: `partBytes`, or less for the last part. Signed. */
+  readonly size: number;
+  /** The policy the grant was made under: a part no object under its `maxBytes` holds is refused. */
+  readonly policy: UploadPolicy;
+  readonly expiresInMs?: number | undefined;
+}
+
+export interface CompleteUploadInput extends UploadSessionInput {
+  /** Ascending. Etags are optional: the disk's own, read by `listParts` here, are what is sent. */
+  readonly parts: readonly CompletedPart[];
+  /** The policy the grant was made under: a completed object past its `maxBytes` is refused. */
+  readonly policy: UploadPolicy;
+}
+
+const capabilityOf = (disk: StorageDriver, key: string): MultipartCapability => {
+  if (disk.multipart === undefined) throw multipartUnsupported(disk.name, key);
+  return disk.multipart;
+};
+
+/** The key a session was opened for, held to the actor's org exactly as `accept.ts` holds a URL. */
+const sessionOf = (input: UploadSessionInput): MultipartCapability => {
+  // Every session a grant opens is under `org/<id>/`, so a key outside the actor's org is refused
+  // whether or not another tenant owns it: no shared prefix takes parts.
+  if (!isWithinOrg(input.key, input.orgId)) {
+    throw orgMismatch(input.key, input.orgId);
+  }
+  return capabilityOf(input.disk, input.key);
+};
+
+/**
+ * The type says required; an untyped caller upgrading from the call without one does not read
+ * types, and with no policy nothing bounds what the session stores — `promoteAttachment`'s guard.
+ */
+const assertPolicy = (caller: string, policy: UploadPolicy | undefined, fix: string): number => {
+  assert(
+    typeof policy?.maxBytes === 'number',
+    `${caller} was called with no policy, so nothing bounds the size of the upload in parts`,
+    fix,
+  );
+  return policy.maxBytes;
+};
+
+/**
+ * The smallest object part `partNumber` at `size` bytes can belong to. Every part before it is at
+ * least S3's floor and at least as long as it (each but the last is exactly `partBytes`), so an
+ * honest grant's part never implies more than its declared size, and so never more than the policy.
+ */
+const impliedBytes = (partNumber: number, size: number): number =>
+  Math.max((partNumber - 1) * MIN_PART_BYTES + size, partNumber * size);
+
+/** The part size: the app's preference, raised to what the size and the protocol require. */
+const partSizeFor = (size: number, preferred: number | undefined): number => {
+  const floor = partBytesFor(size);
+  if (preferred === undefined) return floor;
+  assert(
+    Number.isSafeInteger(preferred) && preferred >= MIN_PART_BYTES && preferred <= MAX_PART_BYTES,
+    `grantMultipart was handed partBytes ${String(preferred)}, outside S3's ${MIN_PART_BYTES}..${MAX_PART_BYTES} bytes`,
+    `grantMultipart({ disk, orgId, request, partBytes: ${MIN_PART_BYTES} })   # or omit it`,
+  );
+  return Math.max(floor, preferred);
+};
+
+/** Refuses as `grantUpload` refuses, then opens the session the parts go into. */
+export async function grantMultipart(input: GrantMultipartInput): Promise<MultipartGrant> {
+  const granted = decideGrant('grantMultipart', input);
+  const multipart = capabilityOf(input.disk, granted.key);
+  const partBytes = partSizeFor(granted.size, input.partBytes);
+  const uploadId = await multipart.create(granted.key, { contentType: granted.contentType });
+  return {
+    key: granted.key,
+    uploadId,
+    partBytes,
+    maxParts: Math.ceil(granted.size / partBytes),
+    contentType: granted.contentType,
+    size: granted.size,
+    expiresAt: granted.now + granted.expiresInMs,
+  };
+}
+
+/**
+ * One part's URL, its length inside the signature. A part past what an object under the policy
+ * holds is `X_STORAGE_TOO_LARGE`, so a session's parts cannot outgrow the policy before the
+ * `completeUpload` that would refuse them: unassembled parts bill too.
+ */
+export async function signPart(input: SignPartInput): Promise<string> {
+  const maxBytes = assertPolicy(
+    'signPart',
+    input.policy,
+    'signPart({ disk, orgId, key, uploadId, partNumber, size, policy: uploadPolicy({ maxBytes }) }) — the policy the grant was made under',
+  );
+  const multipart = sessionOf(input);
+  const { partNumber, size } = input;
+  assert(
+    Number.isSafeInteger(partNumber) && partNumber >= 1 && partNumber <= MAX_PARTS,
+    `signPart was handed partNumber ${String(partNumber)}, outside 1..${MAX_PARTS}`,
+    'signPart({ disk, orgId, key, uploadId, partNumber: 1, size })',
+  );
+  assert(
+    Number.isSafeInteger(size) && size >= 1 && size <= MAX_PART_BYTES,
+    `signPart was handed size ${String(size)}, not a part of 1..${MAX_PART_BYTES} bytes`,
+    'signPart({ disk, orgId, key, uploadId, partNumber, size: grant.partBytes })',
+  );
+  const implied = impliedBytes(partNumber, size);
+  if (implied > maxBytes) throw tooLarge(input.key, implied, maxBytes);
+  return multipart.signPart(input.key, input.uploadId, partNumber, {
+    contentLength: size,
+    expiresInMs: input.expiresInMs === undefined ? DEFAULT_SIGNED_URL_TTL_MS : input.expiresInMs,
+  });
+}
+
+/** What landed, ascending — the resume: a client sends only the parts not here. */
+export function listParts(input: UploadSessionInput): Promise<readonly UploadedPart[]> {
+  return sessionOf(input).listParts(input.key, input.uploadId);
+}
+
+/**
+ * The parts named, checked against what the disk holds, then assembled. The etags sent are the
+ * disk's own, so the browser never needs a bucket's CORS to expose `ETag`. A total past the policy
+ * aborts the session: those bytes were never going to be promoted.
+ */
+export async function completeUpload(input: CompleteUploadInput): Promise<StorageObject> {
+  const maxBytes = assertPolicy(
+    'completeUpload',
+    input.policy,
+    'completeUpload({ disk, orgId, key, uploadId, parts, policy: uploadPolicy({ maxBytes }) }) — the policy the grant was made under',
+  );
+  const multipart = sessionOf(input);
+  const stored = await multipart.listParts(input.key, input.uploadId);
+  const matched = matchParts(input.parts, stored);
+  if ('problem' in matched) throw partsInvalid(input.key, input.uploadId, matched.problem);
+  const total = matched.parts.reduce((sum, part) => sum + part.size, 0);
+  if (total > maxBytes) {
+    await multipart.abort(input.key, input.uploadId);
+    throw tooLarge(input.key, total, maxBytes);
+  }
+  return multipart.complete(input.key, input.uploadId, matched.parts);
+}
+
+/** Drops the session and every part. An id already gone is the state asked for. */
+export function abortUpload(input: UploadSessionInput): Promise<void> {
+  return sessionOf(input).abort(input.key, input.uploadId);
+}