@ultimat3/storage 29.4.0 → 30.0.0

package/src/index.ts

@@ -3,8 +3,11 @@
 
 export type { AcceptSignedUploadInput, SignedRequestInput } from './accept';
 export { acceptSignedUpload, readSignedObject, signedUploadConstraints } from './accept';
+export type { AcceptSignedPartInput } from './accept-part';
+export { acceptSignedPart } from './accept-part';
 export type {
   AttachmentTarget,
+  DeleteVariantsInput,
   PromoteAttachmentInput,
   ReleaseQuarantineInput,
   SweepFailure,
@@ -14,6 +17,7 @@ export type {
 export {
   attachmentKey,
   attachmentPrefix,
+  deleteVariants,
   isPendingKey,
   isQuarantinedKey,
   PENDING_SEGMENT,
@@ -28,8 +32,11 @@ export {
   uploadExtension,
   uploadName,
 } from './attachment';
+export type { PumpLimit } from './byte-pump';
+export { pumpBounded } from './byte-pump';
 export type {
   ByteLimit,
+  CopyOptions,
   ListOptions,
   PutOptions,
   ServerSideEncryption,
@@ -50,6 +57,7 @@ export {
   etagOf,
   resolveListLimit,
   sha256Base64,
+  signedByteBound,
   toBytes,
 } from './driver';
 export type { LocalDriverOptions } from './driver-local';
@@ -96,10 +104,33 @@ export {
   uploadFailed,
   xmlBodyUnreadable,
 } from './errors';
+export { multipartUnsupported, partsInvalid, uploadUnknown } from './errors-multipart';
 export { alreadyPromoted, quarantined } from './errors-promote';
 export { rangeTooLarge, rangeUnsatisfiable } from './errors-range';
+export type {
+  AbortResult,
+  AbortStaleUploadsInput,
+  ExpireObjectsInput,
+  ExpireResult,
+  ObjectPurgeTargetInput,
+} from './expire';
+export { abortStaleUploads, expireObjects, objectPurgeTarget } from './expire';
 export type { GrantUploadInput, UploadGrant, UploadRequest } from './grant';
 export { grantUpload } from './grant';
+export type {
+  CompleteUploadInput,
+  GrantMultipartInput,
+  MultipartGrant,
+  SignPartInput,
+  UploadSessionInput,
+} from './grant-multipart';
+export {
+  abortUpload,
+  completeUpload,
+  grantMultipart,
+  listParts,
+  signPart,
+} from './grant-multipart';
 export type {
   ImageFit,
   ImageSize,
@@ -120,8 +151,21 @@ export {
   srcsetDescriptors,
   transformImage,
   VARIANT_FORMATS,
+  variantFormatOf,
   variantKey,
+  variantRevision,
+  variantSourceOf,
 } from './image';
+export type { WarmFailure, WarmVariantsInput, WarmVariantsResult } from './image-warm';
+export { warmVariants } from './image-warm';
+export type {
+  CompletedPart,
+  MultipartCapability,
+  MultipartSession,
+  SignPartOptions,
+  UploadedPart,
+} from './multipart';
+export { MAX_PART_BYTES, MAX_PARTS, MIN_PART_BYTES, matchParts, partBytesFor } from './multipart';
 export type {
   LockedAction,
   ObjectLock,
@@ -130,7 +174,6 @@ export type {
   RetentionMode,
 } from './object-lock';
 export { isLocked, ObjectLockedError, RETENTION_MODES } from './object-lock';
-
 export {
   assertSafeKey,
   isSafeKey,
@@ -145,13 +188,16 @@ export {
   orgPrefix,
   scopedKey,
 } from './path';
+export type { PutStreamOptions } from './put-stream';
+export { assertPutStream, streamLimit } from './put-stream';
 /**
  * `get(key, { range })`. A third-party driver screens and clamps through these two, or it is a
  * fourth answer to what a range means.
  */
 export type { ByteRange, GetOptions } from './range';
-export { assertGetOptions, servedRange } from './range';
+export { assertGetOptions, assertStreamRange, servedRange, streamedRange } from './range';
 export type {
+  SignedPart,
   SignedUrlConstraints,
   SignedUrlFailure,
   SignedUrlInput,
@@ -178,15 +224,31 @@ export {
 } from './signing-secret';
 export type { Storage, StorageConfig } from './storage';
 export { definedStorage, defineStorage, disk, resetStorage, storage } from './storage';
-export type { UploadCandidate, UploadPolicy, UploadPolicyInit, ValidatedUpload } from './upload';
+export type {
+  StorageSubjectRef,
+  StorageSubjectTarget,
+  StorageSubjectTargetOptions,
+} from './subject-target';
+export { STORAGE_SUBJECT_COLUMNS, storageSubjectTarget } from './subject-target';
+export type {
+  StoredHeadCandidate,
+  UploadCandidate,
+  UploadPolicy,
+  UploadPolicyInit,
+  ValidatedHead,
+  ValidatedUpload,
+} from './upload';
 export {
   contentTypeMatches,
   DEFAULT_MAX_UPLOAD_BYTES,
   DOCUMENT_CONTENT_TYPES,
   IMAGE_CONTENT_TYPES,
+  MAX_LEADING_WHITESPACE,
   normalizeContentType,
+  SNIFF_WINDOW_BYTES,
   sniffContentType,
   uploadPolicy,
+  validateStoredHead,
   validateUpload,
 } from './upload';
 export type {
@@ -203,3 +265,13 @@ export {
   uploadFile,
   xhrSignedPut,
 } from './upload-client';
+export type {
+  MultipartUploadClient,
+  MultipartUploadInput,
+  UploadSessionRef,
+} from './upload-client-multipart';
+export {
+  DEFAULT_PART_THRESHOLD_BYTES,
+  PART_CONCURRENCY,
+  uploadInParts,
+} from './upload-client-multipart';

package/src/multipart-staged.ts

@@ -0,0 +1,127 @@
+// Single responsibility: an upload in parts on a disk that signs its own URLs (`local`, `memory`):
+// the session rules over a `PartStore` the disk supplies. Same contract as s3's, so dev and tests
+// behave as production: a part URL is signed, a part lands only in an open session, a Complete
+// assembles exactly the parts named and drops the session, and an abort leaves nothing.
+
+import type { Clock } from '@ultimat3/core';
+import { etagOf, type StorageDriver, type StorageObject } from './driver';
+import { uploadUnknown } from './errors-multipart';
+import type { MultipartCapability, MultipartSession, UploadedPart } from './multipart';
+import { assertSafeKey } from './path';
+
+/** What a staged session records at `create`. `initiated` is ISO, so a file store can hold it. */
+export interface StagedSession {
+  readonly key: string;
+  readonly contentType: string;
+  readonly initiated: string;
+}
+
+/** Where a disk keeps open sessions and their parts: a directory, or a `Map`. */
+export interface PartStore {
+  open(uploadId: string, session: StagedSession): Promise<void>;
+  session(uploadId: string): Promise<StagedSession | undefined>;
+  writePart(uploadId: string, part: UploadedPart, bytes: Uint8Array): Promise<void>;
+  /** Ascending by part number. */
+  parts(uploadId: string): Promise<readonly UploadedPart[]>;
+  /** The named parts' bytes, end to end, read as the stream is pulled. */
+  read(uploadId: string, parts: readonly UploadedPart[]): ReadableStream<Uint8Array>;
+  drop(uploadId: string): Promise<void>;
+  sessions(): Promise<readonly (readonly [string, StagedSession])[]>;
+}
+
+export interface StagedMultipartOptions {
+  readonly store: PartStore;
+  readonly clock: Clock;
+  /** The disk the parts belong to: it signs their URLs and takes the Complete's stream. */
+  readonly driver: StorageDriver;
+}
+
+/**
+ * The disk with `multipart` attached IN PLACE, never spread: a spread reads `signedUrlBase` once,
+ * and `registerAs` re-points it after construction.
+ */
+export function withStagedMultipart<D extends StorageDriver>(
+  driver: D,
+  store: PartStore,
+  clock: Clock,
+): D {
+  return Object.assign(driver, { multipart: stagedMultipart({ store, clock, driver }) });
+}
+
+export function stagedMultipart(options: StagedMultipartOptions): MultipartCapability {
+  const { store } = options;
+  /** The session, held to the key it was opened for: an id is never a capability on its own. */
+  const openSession = async (key: string, uploadId: string): Promise<StagedSession> => {
+    const session = await store.session(uploadId);
+    if (session === undefined || session.key !== key) {
+      throw uploadUnknown(options.driver.name, key, uploadId);
+    }
+    return session;
+  };
+
+  return {
+    async create(key, { contentType }): Promise<string> {
+      const safe = assertSafeKey(key);
+      const uploadId = crypto.randomUUID();
+      await store.open(uploadId, {
+        key: safe,
+        contentType,
+        initiated: options.clock.now().toISOString(),
+      });
+      return uploadId;
+    },
+
+    signPart: (key, uploadId, partNumber, { contentLength, expiresInMs }) =>
+      options.driver.signedUrl(key, {
+        method: 'PUT',
+        contentLength,
+        maxBytes: contentLength,
+        expiresInMs,
+        part: { uploadId, partNumber },
+      }),
+
+    async listParts(key, uploadId): Promise<readonly UploadedPart[]> {
+      await openSession(assertSafeKey(key), uploadId);
+      return store.parts(uploadId);
+    },
+
+    async receivePart(key, uploadId, partNumber, bytes): Promise<UploadedPart> {
+      await openSession(assertSafeKey(key), uploadId);
+      const part = { partNumber, etag: etagOf(bytes), size: bytes.byteLength };
+      await store.writePart(uploadId, part, bytes);
+      return part;
+    },
+
+    async complete(key, uploadId, parts): Promise<StorageObject> {
+      const safe = assertSafeKey(key);
+      const session = await openSession(safe, uploadId);
+      const total = parts.reduce((sum, part) => sum + part.size, 0);
+      const object = await options.driver.putStream(safe, store.read(uploadId, parts), {
+        maxBytes: Math.max(total, 1),
+        contentType: session.contentType,
+      });
+      await store.drop(uploadId);
+      return object;
+    },
+
+    async abort(key, uploadId): Promise<void> {
+      const safe = assertSafeKey(key);
+      const session = await store.session(uploadId);
+      if (session?.key === safe) await store.drop(uploadId);
+    },
+
+    async listUploads(prefix): Promise<readonly MultipartSession[]> {
+      const open = await store.sessions();
+      return open
+        .filter(([, session]) => prefix === undefined || session.key.startsWith(prefix))
+        .map(([uploadId, session]) => {
+          const initiated = new Date(session.initiated);
+          return {
+            key: session.key,
+            uploadId,
+            ...(Number.isNaN(initiated.getTime()) ? {} : { initiated }),
+          };
+        });
+    },
+  };
+}

package/src/multipart.ts

@@ -0,0 +1,119 @@
+// Single responsibility: the part arithmetic of an S3 multipart upload: the protocol's two limits
+// and the part size that follows from a ceiling, plus the optional capability a disk declares for
+// an upload in parts. No wire and no disk, so any caller may ask.
+
+import type { StorageObject } from './driver';
+
+/** S3's floor on every part but the last. */
+export const MIN_PART_BYTES = 5 * 1024 * 1024;
+/** S3's count of parts in one upload. */
+export const MAX_PARTS = 10_000;
+
+/**
+ * How much is held before a part is sent. The smallest size whose 10,000 parts still cover
+ * `maxBytes`, since what is held is what this process pays for the stream.
+ */
+export const partBytesFor = (maxBytes: number): number =>
+  Math.max(MIN_PART_BYTES, Math.ceil(maxBytes / MAX_PARTS));
+
+/** S3's ceiling on one part, and so on one part URL's signed length. */
+export const MAX_PART_BYTES = 5 * 1024 * 1024 * 1024;
+
+/** One part a disk holds for an open upload: what `listParts` answers, and what a resume reads. */
+export interface UploadedPart {
+  readonly partNumber: number;
+  /** The disk's own etag of the part. S3's is quoted MD5; the local disks' is `etagOf`. */
+  readonly etag: string;
+  readonly size: number;
+}
+
+/** A part the caller asks `completeUpload` to assemble. The etag, when given, must be the stored one. */
+export interface CompletedPart {
+  readonly partNumber: number;
+  readonly etag?: string | undefined;
+}
+
+/** One upload opened and neither completed nor aborted: what `abortStaleUploads` weighs. */
+export interface MultipartSession {
+  readonly key: string;
+  readonly uploadId: string;
+  /** ABSENT when the disk did not say, as `StorageListEntry.lastModified` is — never epoch 0. */
+  readonly initiated?: Date | undefined;
+}
+
+export interface SignPartOptions {
+  /** The part's exact size, signed: the disk stores it at no other length. */
+  readonly contentLength: number;
+  readonly expiresInMs: number;
+}
+
+/**
+ * An upload in parts, on one disk. Optional on `StorageDriver`, so a third-party driver still
+ * compiles; `grantMultipart` refuses a disk without it (`X_STORAGE_MULTIPART_UNSUPPORTED`). Every
+ * method takes a key already held to the tenant by the caller in `grant-multipart.ts`.
+ */
+export interface MultipartCapability {
+  /** Opens a session and answers its id. The object's content type travels here: a part has none. */
+  create(key: string, options: { readonly contentType: string }): Promise<string>;
+  /** A URL a browser PUTs one part to. Signs nothing about whether the upload is still open. */
+  signPart(
+    key: string,
+    uploadId: string,
+    partNumber: number,
+    options: SignPartOptions,
+  ): Promise<string>;
+  /** Ascending by part number. `X_STORAGE_UPLOAD_UNKNOWN` for a session that is not open. */
+  listParts(key: string, uploadId: string): Promise<readonly UploadedPart[]>;
+  /** Assembles `parts`, already checked against `listParts`; the object exists once it returns. */
+  complete(key: string, uploadId: string, parts: readonly UploadedPart[]): Promise<StorageObject>;
+  /** Drops the session and every part. An unknown session is already in the asked-for state. */
+  abort(key: string, uploadId: string): Promise<void>;
+  /** Every open session under `prefix`, so a sweep can reclaim what nobody finished. */
+  listUploads(prefix?: string): Promise<readonly MultipartSession[]>;
+  /**
+   * Stores one part's bytes — only on a disk that signs its own part URLs (`local`, `memory`),
+   * called by the `/_storage` PUT once the URL verified. On s3 the bytes go to the bucket.
+   */
+  receivePart?(
+    key: string,
+    uploadId: string,
+    partNumber: number,
+    bytes: Uint8Array,
+  ): Promise<UploadedPart>;
+}
+
+/**
+ * The parts asked for, held to the parts stored: each asked part is stored, in ascending order,
+ * under the stored etag when one is named, and none but the last is under S3's part floor.
+ * Answers the stored parts in the asked order, which is what `complete` assembles; `problem` names
+ * the first reason it cannot.
+ */
+export function matchParts(
+  asked: readonly CompletedPart[],
+  stored: readonly UploadedPart[],
+): { readonly parts: readonly UploadedPart[] } | { readonly problem: string } {
+  if (asked.length === 0) return { problem: 'no parts were named' };
+  const byNumber = new Map(stored.map((part) => [part.partNumber, part]));
+  const parts: UploadedPart[] = [];
+  let previous = 0;
+  for (const { partNumber, etag } of asked) {
+    if (!Number.isSafeInteger(partNumber) || partNumber <= previous) {
+      return { problem: `part ${String(partNumber)} is not in ascending order after ${previous}` };
+    }
+    const held = byNumber.get(partNumber);
+    if (held === undefined) return { problem: `part ${partNumber} never arrived` };
+    if (etag !== undefined && etag !== held.etag) {
+      return { problem: `part ${partNumber}'s etag is not the one the disk stored` };
+    }
+    parts.push(held);
+    previous = partNumber;
+  }
+  // S3's EntityTooSmall, asked on every disk so the local ones cannot complete what s3 refuses.
+  const short = parts.slice(0, -1).find((part) => part.size < MIN_PART_BYTES);
+  if (short !== undefined) {
+    return {
+      problem: `part ${short.partNumber} is ${short.size}B, under the ${MIN_PART_BYTES}B every part but the last must reach`,
+    };
+  }
+  return { parts };
+}

package/src/put-stream.ts

@@ -0,0 +1,52 @@
+// Single responsibility: what `putStream` may be handed, and the limit it pumps under. The pump itself
+// is `byte-pump.ts`, which `put()` reads through too.
+
+import { assert, describeValue, finiteCount } from '@ultimat3/core';
+import type { PumpLimit } from './byte-pump';
+import { assertPutOptions } from './driver';
+import { streamTooLarge } from './errors-stream';
+
+export interface PutStreamOptions {
+  /**
+   * Required: a stream's length is the sender's until it is counted. Past it the write is abandoned
+   * (`X_STORAGE_TOO_LARGE`) and the key is as it was. Replaces the disk's `maxPutBytes`, which bounds
+   * what `put()` buffers, and nothing here is buffered past one s3 part.
+   */
+  readonly maxBytes: number;
+  readonly contentType?: string | undefined;
+  readonly cacheControl?: string | undefined;
+  readonly metadata?: Readonly<Record<string, string>> | undefined;
+}
+
+/** `put()` options that need the bytes before the object exists. The type omits them too. */
+const NEEDS_THE_BYTES = ['checksum', 'retention', 'legalHold', 'serverSideEncryption'] as const;
+
+/** Everything judged before a chunk is read. Answers the screened `maxBytes`. */
+export function assertPutStream(
+  driver: string,
+  body: ReadableStream<Uint8Array>,
+  options: PutStreamOptions,
+): number {
+  assert(
+    body instanceof ReadableStream,
+    `putStream() on the ${driver} disk was given a body that is not a ReadableStream (${describeValue(body)})`,
+    'await disk.putStream(key, request.body, { maxBytes })   # a Uint8Array or a Blob goes through disk.put(key, bytes)',
+  );
+  const asked = (options ?? {}) as unknown as Readonly<Record<string, unknown>>;
+  for (const name of NEEDS_THE_BYTES) {
+    assert(
+      asked[name] === undefined,
+      `putStream() on the ${driver} disk was given ${name}, which needs the whole body before the object exists`,
+      `await disk.put(key, bytes, { ${name} })   # buffered, so bounded by the disk's maxPutBytes`,
+    );
+  }
+  assertPutOptions(driver, options);
+  return finiteCount(`putStream() on the ${driver} disk`, 'maxBytes', options?.maxBytes, 1);
+}
+
+/** The limit `putStream` pumps under: its own `maxBytes`, and the refusal that names it. */
+export const streamLimit = (driver: string, key: string, maxBytes: number): PumpLimit => ({
+  driver,
+  maxBytes,
+  refuse: (total) => streamTooLarge(driver, key, total, maxBytes),
+});

package/src/range.ts

@@ -5,6 +5,7 @@
 
 import { assert } from '@ultimat3/core';
 import { rangeTooLarge, rangeUnsatisfiable } from './errors-range';
+import { streamRangeUnsatisfiable } from './errors-stream';
 
 /**
  * The first and the last byte, BOTH INCLUSIVE — HTTP's `Range: bytes=first-last` and S3's, so a
@@ -39,19 +40,49 @@ const isOffset = (value: unknown): value is number =>
 export function assertGetOptions(driver: string, options: GetOptions | undefined): void {
   const range = options?.range;
   if (range === undefined) return;
+  assertRange(driver, 'get()', 'get(key, { range: ', ' })', range);
+}
+
+/** The same screen for `streamRange`, naming the call that was made. */
+export function assertStreamRange(driver: string, range: ByteRange): void {
+  assertRange(driver, 'streamRange()', 'streamRange(key, ', ')', range);
+}
+
+function assertRange(
+  driver: string,
+  call: string,
+  open: string,
+  close: string,
+  range: ByteRange,
+): void {
   const [first, last] = Array.isArray(range) ? range : [];
   assert(
     Array.isArray(range) && range.length === 2 && isOffset(first) && isOffset(last),
-    `get() on the ${driver} disk was given a range that is not two whole, non-negative byte offsets`,
-    'get(key, { range: [first, last] }) — inclusive offsets: [0, 99] reads the first 100 bytes',
+    `${call} on the ${driver} disk was given a range that is not two whole, non-negative byte offsets`,
+    `${open}[first, last]${close} — inclusive offsets: [0, 99] reads the first 100 bytes`,
   );
   assert(
     first <= last,
-    `get() on the ${driver} disk was given the range [${first}, ${last}], whose first byte is past its last`,
-    `get(key, { range: [${last}, ${first}] }) — first before last, both inclusive`,
+    `${call} on the ${driver} disk was given the range [${first}, ${last}], whose first byte is past its last`,
+    `${open}[${last}, ${first}]${close} — first before last, both inclusive`,
   );
 }
 
+/**
+ * The window `streamRange` serves: clamped as `servedRange` clamps. No ceiling, because nothing is
+ * buffered: the bytes asked for are the bytes pulled, and they flow at the reader's pace.
+ */
+export function streamedRange(
+  disk: string,
+  key: string,
+  range: ByteRange,
+  size: number,
+): ByteRange {
+  const [first, wanted] = range;
+  if (first >= size) throw streamRangeUnsatisfiable(disk, key, range, size);
+  return [first, Math.min(wanted, size - 1)];
+}
+
 /**
  * The range a disk SERVES for an object of `size` bytes — clamped, refused, or over the ceiling.
  * Called with the object's own measured size, before a byte is read, by every driver.

package/src/signed-url.ts

@@ -4,7 +4,7 @@
 // a 2GB executable. Verification never throws and never short-circuits on expiry before the
 // signature, so a forged URL can never learn "the signature was fine, just late".
 
-import { type Clock, finiteCount, systemClock, timingSafeEqual } from '@ultimat3/core';
+import { assert, type Clock, finiteCount, systemClock, timingSafeEqual } from '@ultimat3/core';
 import type { SignedUrlMethod } from './driver';
 import { assertSafeKey, isSafeKey } from './path';
 
@@ -31,8 +31,20 @@ export const SIGNED_URL_PARAMS = {
   maxBytes: 'x-max',
   contentType: 'x-ct',
   signature: 'x-sig',
+  uploadId: 'x-upload',
+  partNumber: 'x-part',
 } as const;
 
+/** The session and part a part URL writes into — inside the signature, so neither can be edited. */
+export interface SignedPart {
+  readonly uploadId: string;
+  readonly partNumber: number;
+}
+
+/** `MAX_PARTS` restated as the parse's bound: `multipart.ts` imports this module's types. */
+const MAX_SIGNED_PART = 10_000;
+const SIGNED_UPLOAD_ID = /^[A-Za-z0-9._~-]{1,128}$/;
+
 export interface SignedUrlConstraints {
   readonly key: string;
   readonly method: SignedUrlMethod;
@@ -40,6 +52,8 @@ export interface SignedUrlConstraints {
   readonly expiresAt: number;
   readonly maxBytes: number | undefined;
   readonly contentType: string | undefined;
+  /** Present on a part URL only: a single PUT and a part are two capabilities, never one. */
+  readonly part?: SignedPart | undefined;
 }
 
 export interface SignedUrlInput {
@@ -50,6 +64,8 @@ export interface SignedUrlInput {
   readonly expiresInMs?: number | undefined;
   readonly maxBytes?: number | undefined;
   readonly contentType?: string | undefined;
+  /** Mint a part URL of an open upload (`MultipartCapability.signPart` on the local disks). */
+  readonly part?: SignedPart | undefined;
   readonly baseUrl?: string | undefined;
   readonly clock?: Clock | undefined;
 }
@@ -92,14 +108,19 @@ export function signedUrlBasePath(baseUrl: string): string {
  * origin is deliberately outside it: the verifying route is handed a path.
  */
 export function canonicalRequest(constraints: SignedUrlConstraints, basePath: string): string {
+  const part = constraints.part;
+  // A part signs under its own version line, so no single-PUT string can ever read as a part's:
+  // the two domains share no canonical form, and a single URL's bytes are what they always were.
+  const tail = part === undefined ? [] : [part.uploadId, String(part.partNumber)];
   return [
-    SIGNED_URL_VERSION,
+    part === undefined ? SIGNED_URL_VERSION : `${SIGNED_URL_VERSION}-part`,
     basePath,
     constraints.method,
     constraints.key,
     String(constraints.expiresAt),
     constraints.maxBytes === undefined ? '' : String(constraints.maxBytes),
     constraints.contentType ?? '',
+    ...tail,
   ].join('\n');
 }
 
@@ -163,6 +184,7 @@ export async function buildSignedUrl(input: SignedUrlInput): Promise<string> {
     // one while `acceptSignedUpload`'s `unconstrained` refusal (which tests `undefined`) stayed
     // silent. One spelling for "no content type", here and at the parse below.
     contentType: input.contentType === '' ? undefined : input.contentType,
+    ...(input.part === undefined ? {} : { part: assertSignedPart(input.part) }),
   };
   const params = new URLSearchParams();
   params.set(SIGNED_URL_PARAMS.method, constraints.method);
@@ -173,6 +195,10 @@ export async function buildSignedUrl(input: SignedUrlInput): Promise<string> {
   if (constraints.contentType !== undefined) {
     params.set(SIGNED_URL_PARAMS.contentType, constraints.contentType);
   }
+  if (constraints.part !== undefined) {
+    params.set(SIGNED_URL_PARAMS.uploadId, constraints.part.uploadId);
+    params.set(SIGNED_URL_PARAMS.partNumber, String(constraints.part.partNumber));
+  }
   const base = trimBase(input.baseUrl ?? DEFAULT_SIGNED_URL_BASE);
   params.set(
     SIGNED_URL_PARAMS.signature,
@@ -232,15 +258,46 @@ function parseConstraints(url: URL, base: string): SignedUrlConstraints | Signed
   // An EMPTY `x-ct` is malformed, never "no content type": absent and empty share one canonical
   // string, so accepting it let `&x-ct=` be appended to a URL signed with none and still verify.
   if (rawContentType === '') return 'malformed';
+  const part = parsePart(url);
+  if (part === 'malformed') return part;
   return {
     key,
     method,
     expiresAt,
     maxBytes,
     contentType: rawContentType ?? undefined,
+    ...(part === undefined ? {} : { part }),
   };
 }
 
+const isSignedPart = (part: SignedPart): boolean =>
+  SIGNED_UPLOAD_ID.test(part.uploadId) &&
+  Number.isSafeInteger(part.partNumber) &&
+  part.partNumber >= 1 &&
+  part.partNumber <= MAX_SIGNED_PART;
+
+/** The mint's screen: a part this module could not parse back is a URL dead on arrival. */
+function assertSignedPart(part: SignedPart): SignedPart {
+  assert(
+    isSignedPart(part),
+    `buildSignedUrl was handed a part that is not an upload id and a part number 1..${MAX_SIGNED_PART}`,
+    "buildSignedUrl({ secret, key, method: 'PUT', part: { uploadId: crypto.randomUUID(), partNumber: 1 } })",
+  );
+  return { uploadId: part.uploadId, partNumber: part.partNumber };
+}
+
+/** Both parameters or neither; one alone is a URL this module never minted. */
+function parsePart(url: URL): SignedPart | 'malformed' | undefined {
+  const uploadId = url.searchParams.get(SIGNED_URL_PARAMS.uploadId);
+  const rawNumber = url.searchParams.get(SIGNED_URL_PARAMS.partNumber);
+  if (uploadId === null && rawNumber === null) return undefined;
+  if (uploadId === null || rawNumber === null || !/^[1-9][0-9]{0,4}$/.test(rawNumber)) {
+    return 'malformed';
+  }
+  const part = { uploadId, partNumber: Number(rawNumber) };
+  return isSignedPart(part) ? part : 'malformed';
+}
+
 export async function verifySignedUrl(input: VerifySignedUrlInput): Promise<SignedUrlVerification> {
   let url: URL;
   try {